Ibm Base Professional 6.0.1 User Guide PDF

i
IBM SPSS Data Collection Base

Professional 6.0.1 User’s Guide
Note: Before using this information and the product it supports, read the general information
under Notices on p. 1589.
This edition applies to IBM SPSS Data Collection Base Professional 6.0.1 and to all subsequent
releases and modifications until otherwise indicated in new editions.
Adobe product screenshot(s) reprinted with permission from Adobe Systems Incorporated.
Microsoft product screenshot(s) reprinted with permission from Microsoft Corporation.
Licensed Materials - Property of IBM
Licensed Materials - Property of IBM © Copyright IBM Corporation 2000, 2011
Licensed Materials - Property of IBM © Copyright IBM Corporation 2000, 2011
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
Preface
Welcome to the IBM® SPSS® Data Collection Base Professional 6.0.1 User’s Guide. This guide
provides information on using the IBM® SPSS® Data Collection Base Professional application.
For information about installing the product, see the IBM SPSS Data Collection Desktop 6.0.1
Installation Guide.
Adobe Portable Document Format (.pdf) versions of the guides are available on the IBM SPSS
Data Collection Desktop 6.0.1 DVD-ROM. Viewing and printing the documents requires Adobe
Reader. If necessary, you can download it at no cost from www.adobe.com. Use the Adobe Reader
online Help for answers to your questions regarding viewing and navigating the documents.
Notice: IBM® SPSS® Data Collection offers many powerful functions and features for use in
the business of our customers. IBM is not responsible for determining the requirements of laws
applicable to any licensee’s business, including those relating to Data Collection Program, nor that
IBM’s provision of (or any licensee’s receipt of) the Program meets the requirements of such laws.
All licensees shall comply with all laws applicable to use and access of the Program, whether such
use or access is standalone or in conjunction with any third party product or service.
About IBM Business Analytics

IBM Business Analytics software delivers complete, consistent and accurate information that
decision-makers trust to improve business performance. A comprehensive portfolio of business
intelligence, predictive analytics, financial performance and strategy management, and analytic
applications provides clear, immediate and actionable insights into current performance and the
ability to predict future outcomes. Combined with rich industry solutions, proven practices and
professional services, organizations of every size can drive the highest productivity, confidently
automate decisions and deliver better results.
As part of this portfolio, IBM SPSS Predictive Analytics software helps organizations predict
future events and proactively act upon that insight to drive better business outcomes. Commercial,
government and academic customers worldwide rely on IBM SPSS technology as a competitive
advantage in attracting, retaining and growing customers, while reducing fraud and mitigating
risk. By incorporating IBM SPSS software into their daily operations, organizations become
predictive enterprises – able to direct and automate decisions to meet business goals and achieve
measurable competitive advantage. For further information or to reach a representative visit
http://www.ibm.com/spss.
Technical support
Technical support is available to maintenance customers. Customers may contact Technical
Support for assistance in using IBM Corp. products or for installation help for one of the
supported hardware environments. To reach Technical Support, see the IBM Corp. web site
at http://www.ibm.com/support. Be prepared to identify yourself, your organization, and your
support agreement when requesting assistance.
Licensed Materials - Property of IBM © iii

Copyright IBM Corporation 2000, 2011
Contents
1 Base Professional 1
Welcome to IBM SPSS Data Collection Base Professional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
What’s new in IBM SPSS Data Collection Base Professional 6.0.1. . . . . . . . . . . . . . . . . . . . . . . . . 2
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Creating Your First mrScriptBasic Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Using IBM SPSS Data Collection Base Professional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Which File Types Can I Work With? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 12
The IBM SPSS Data Collection Base Professional Window . . . . . . . . . . . . . . ... ... ... . . . 13
Working with Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 21
Working with Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 25
Using the Workspace Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 27
Using the Metadata Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 28
Using the Connection String Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 31
Using Context-Sensitive Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 42
Using ScriptAssist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 43
Finding and Replacing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 44
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . . 46
IBM SPSS Data Collection Base Professional in Other Languages . . . . . . . . . ... ... ... . . . 53
Using IBM SPSS Data Collection Base Professional to develop interviews. . . ... ... ... . . . 54
The IBM SPSS Data Collection Base Professional menu . . . . . . . . . . . . . . . . ... ... ... . . . 91
IBM SPSS Data Collection Base Professional toolbars. . . . . . . . . . . . . . . . . . ... ... ... . . . 93
IBM SPSS Data Collection Base Professional keyboard shortcuts . . . . . . . . . ... ... ... . . . 99
IBM SPSS Data Collection Base Professional options . . . . . . . . . . . . . . . . . . ... ... ... . . 101
Local Deployment Wizard overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . 199
Activation Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . 203
Notes for IBM SPSS Quantum Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... . . 111
The Big Picture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Activating questionnaires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Activation templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
IBM SPSS Data Collection Activation Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Activation History tab . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... ... .. 196
Filters tab . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... ... .. 197
Settings tab . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... ... .. 198
Local Deployment Wizard overview . . ... ... ... ... ... ... ... ... ... ... ... ... ... ... .. 199
Usage options . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... .. 199
Validation options . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... .. 200
Routing options - data entry . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... .. 200
Routing options - live interviewing . . . ... ... ... ... ... ... ... ... ... ... ... ... ... .. 201
Display options . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... .. 201
Deployment options . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... .. 201
iv
Expiry date and time options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Summary options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Activation Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Data Management Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Data Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 206
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 208
Understanding the Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 231
Data Management Script (DMS) File . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 241
DMS Runner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 289
WinDMSRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 300
Transferring Data Using a DMS File . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 310
Working with IBM SPSS Data Collection Interviewer Server Data ... ... ... ... ... ... .. 356
Merging Case Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 373
Data Cleaning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 388
Working with the Weight Component . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 406
Creating New Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 433
Analyzing a Tracking Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 442
Table Scripting in a Data Management Script . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 451
Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 466
Data Management Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 482
Interview Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... .. 503
What’s New in Interview Scripting 6.0.1 . . ... ... ... ... ... ... ... ... ... ... ... ... . . 504
Getting Started . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . . 504
Writing Interview Scripts . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . . 522
Testing Interview Scripts . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . . 984
Activating Interview Scripts. . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . . 987
Sample Management. . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . . 992
Quota Control . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1076
Interview Scripting Reference . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1086
Table Scripting . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1140
Getting Started . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1142
Table Specification Syntax. . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1192
Cell Contents . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1247
Hierarchical Data . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1271
Statistical Tests . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1310
Table Presentation. . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1396
Annotations . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1432
Working with Profile Tables . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1443
Working with Metadata . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1453
Working with Change Tracker . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1469
Working with the Variables Interface . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1475
Exporting Tables . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1477
Working with Axis Expressions . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1536
Sample Table Scripts . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... . 1541
v
Limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... . 1555
Table Object Model Reference. . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... . 1556
Metadata Services Object Model Reference . ... ... ... ... ... ... ... ... ... ... ... . 1560
QsfTom component object model reference . . ... ... ... ... ... ... ... ... ... ... ... . 1560
Accessibility Guide . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... . 1560
Keyboard Navigation . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1561
Accessibility for the Visually Impaired . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1561
Accessibility for Blind Users . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1561
Special Considerations . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1561
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... . 1562
IBM SPSS Data Collection Base Professional FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565
Data Management Troubleshooting and FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565
Appendix
A Notices 1589
Index 1592
vi
Chapter
1
Base Professional
Welcome to IBM SPSS Data Collection Base Professional
IBM® SPSS® Data Collection Base Professional is a complete set of tools that supports the
building of automated market research processes. Base Professional includes an integrated
development environment (IDE) that enables you to create, edit, run, and debug IBM® SPSS®
Data Collection scripts. In addition, Base Professional comes with the internal components that
enable you to create scripts that perform various data management tasks.
Two additional options are available for Base Professional:

The Tables Option includes components that enable you to create batch tables using a script.
The Interview Option includes components that enable you to develop and test interviews, and
activate them in IBM® SPSS® Data Collection Interviewer Server.
The documentation for Base Professional includes getting started topics, step-by-step instructions,
conceptual overviews, numerous examples, information about the samples and command prompt
tools, and extensive reference material. The following table provides a summary of the major
sections in the Base Professional documentation.
What’s new in IBM SPSS Data Collection Base Provides a summary of the main changes in this
Professional 6.0.1 section.
Getting Started A brief introduction to writing scripts in Base
Professional.
Using IBM SPSS Data Collection Base Professional How to use the Base Professional integrated
development environment (IDE).
Notes for IBM SPSS Quantum Users A section designed to help Quantum users get
started with Base Professional.
Data Management Scripting Detailed documentation on using Base Professional
to perform data management-related tasks. This
section includes a Getting Started section, details
of the DMS file, information on cleaning and
transferring data, setting up weighting schemes, and
creating new variables. Detailed reference to the
Data Management Object Model (DMOM) and the
Weight component object model in also provided.
Interview Scripting Describes how to use the Base Professional
Interview Option to create interviews that can be
activated in version 3.0 (or later) of Interviewer
Server.
Table Scripting Documentation on using the Base Professional
Tables Option to create batch tables using a script.
Troubleshooting FAQs and error messages.
Licensed Materials - Property of IBM © Copyright 1

IBM Corporation 2000, 2011
2
Chapter 1
What’s new in IBM SPSS Data Collection Base Professional 6.0.1

What’s new in IBM® SPSS® Data Collection Base Professional 6.0.1 is summarized under the
following headings:
IBM® SPSS® Data Collection Base Professional Installation
Base Professional IDE
IBM® SPSS® Data Collection Question Repository
Data Management
Interview Scripting
Table Scripting
Table Scripting Samples
Installation
x64 64-bit support. x64 64-bit editions are now provided for the IBM® SPSS® Data Collection
applications (note that IBM® SPSS® Data Collection Author Server Edition and IBM® SPSS®
Data Collection Survey Reporter Server Edition are only provided as x86 32-bit). Refer to the
appropriate Data Collection installation guide for more information.
Fix pack and hotfix information. You can now view information regarding which fix packs and
hotfixes are installed via the application’s Help menu.
Help > About Base Professional... > Details...
IDE
Data Management
Integration with IBM SPSS Collaboration and Deployment Services Repository.IBM® SPSS®
Data Collection 6.0.1 provides support for storing and retrieving .mrz, and .dmz packages (zip
archives) to a IBM® SPSS® Collaboration and Deployment Services Repository. A package
is an executable element of Data Collection.
A .dmz package contains a primary .dms file, a configuration file for the primary .dms file, and any
other internal includes files.
An .mrz package contains a primary .mrs file, a configuration file for the primary .mrs file, and any
other internal includes files.
IBM® SPSS® Collaboration and Deployment Services is used as a job scheduling and
configuration platform. User-configured script items are exposed to IBM SPSS Collaboration and
Deployment Services, but IBM SPSS Collaboration and Deployment Services will not execute
any part of a Data Collection script. User-configured items include parameters and store locations,
access permissions, and output file properties.
3
Base Professional
Base Professional supports the following integration with the IBM SPSS Collaboration and
Deployment Services Repository:
Script Packager component. The component provides support for generating deployable
.mrz, .dmz, and mtz packages (zip archives) for the purpose of integration with IBM SPSS
Collaboration and Deployment Services Repository. For more information, see the topic
Script Packager Component Object Model on p. 501.
IBM SPSS Collaboration and Deployment Services comment block. The IBM SPSS Collaboration
and Deployment Services comment block defines parameters for .mrs and .dms scripts. The
new CaDSCommentBlock.dms sample provides an IBM SPSS Collaboration and Deployment
Services comment block example in .dms format. For more information, see the topic Sample
DMS Files on p. 467.
DMS Runner. DMS Runner provides support for the /loc:<location> option. The option allows
you to specify which location is used when working with a .dmz package (zip archive). For
more information, see the topic DMS Runner on p. 289.
mrScript Command Line Runner. The mrScript Command Line Runner provides support for the
/loc:<location> option. The option allows you to specify which location is used when working
with an .mrz package. A package is an executable element of Data Collection; each package
contains a main script that is utilized for execution entry and a set of scripts that are included
in the main script. Packages supports script integration with the IBM SPSS Collaboration and
Deployment Services Repository.
Data Collection Execution Server. Provide the web services to process the zip archive packages
and associated configuration files. The server executes and returns the output variables and
output files via a web service response. The server also supports IBM SPSS Collaboration and
Deployment Services job step cancellation.
Data Collection IBM SPSS Collaboration and Deployment Services example.
The Data Collection IBM SPSS Collaboration and Deployment Services
example provides an IBM SPSS Data Collection integration scenario with
IBM SPSS Collaboration and Deployment Services. The example is stored
in the [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data
Management\Collaboration Deployment Services directory. Refer to The Data Collection
Collaboration and Deployment Services example for more information.
Refer to the Introduction to IBM SPSS Collaboration and Deployment Services Repository
integration section in the IBM® SPSS® Data Collection Developer Library for more information.
Project expiry setting in Local Deployment Wizard. The Local Deployment Wizard now provides an
expiry date and time step that allows you define the project’s expiration date and time (UTC time).
Defining a project expiration date and time allows interviewers to easily identify expired projects.
For more information, see the topic Local Deployment Wizard overview on p. 199.
Interview Scripting
Support for reserved names and keywords in metadata. Data Collection now provides full support
for SQL and mrScript reserved names and keywords in metadata variables. In previous releases,
the use of reserved SQL keywords could cause issues when using the IBM® SPSS® Data
4
Chapter 1
Collection Data Model to query data for processes such as DMOM; the use of reserved mrScript
keywords could cause syntax errors when referenced within a routing script.
Refer to and for more information.
Auto Answer feature enhancements. The Auto Answer feature has been updated to support more
robust auto answer playback capabilities including adding, editing, changing, and removing
data sources connections, defining the number of cases, and so on. For more information, see
the topic Auto Answer dialog box on p. 66.
Census.mdd hierarchical data example. The new Census.mdd hierarchical

data example is included in the Data Collection Developer Library at
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Frequently Asked
Questions\Loops and Grids. The example demonstrates the use of hierarchical data when working
with loops and grids. Refer to For more information, see the topic Hierarchical Data on p. 1391.
for more information.
MaxRecordsInBatch property. This new CATI parameter defines the maximum number of records
to pass to the sample management script. The maximum value defaults to 25 when the property is
not defined. For more information, see the topic Scripts in the CATI Folder on p. 1054.
Support for Web browser capability detection. A new property collection that
contains the respondent’s browser capabilities has been implemented. Refer to
IInterview.Info.BrowserCapabilities for more information.
Table Scripting
QsfTom component object model. The QsfTom component converts Quanvert saved table specs
(as many as possible) to a set of TOM table specs in an MTD file. For more information, see the
topic QsfTom component object model reference on p. 1560.
Table Scripting Samples
Getting Started
This section introduces some of the features of the IBM® SPSS® Data Collection Base
Professional IDE that make it easy to write scripts. This topic contains step-by-step instructions
that walk you through creating a simple mrScriptBasic file.
Creating Your First mrScriptBasic Script

This topic is designed to introduce you to some of the features in the IBM® SPSS® Data
Collection Base Professional IDE for writing mrScriptBasic code, and is in the form of
step-by-step instructions that walk you through creating a simple mrScriptBasic file. This topic
is not designed to teach you about the mrScriptBasic language itself, and you do not need to
be an expert in mrScriptBasic to follow the steps. For tips on learning mrScriptBasic, see 6.
Mastering mrScriptBasic.
5
Base Professional
E First let’s create a new mrScriptBasic file. From the File menu, choose:
New > File
This opens the New File dialog box.
E From the list of available file types, select mrScriptBasic File, and then click Open.
E In the main Edit pane, type the following:
Dim MDM
Set MDM =
We will now use the to create an instance of an MDM Document object. We will insert the
function using the Functions pane, which lists all of the functions in the .
E Click the Functions tab to bring the Functions pane to the front, and then expand the Misc folder.
E Right-click the CreateObject function, and from the shortcut menu, choose Add Function.
This inserts the name of the function into the script.
E Now type the opening parenthesis: (
This displays the function’s syntax, which shows us that there is one parameter (the class) and
that the function returns an object.
E Type the parameter and the closing parenthesis: "MDM.Document")

6
Chapter 1
Notice that Base Professional automatically highlights the parentheses so that you can see the
opening and closing pair, and colors the text to help you distinguish the different elements of your
script. For example, different colors are used for keywords, variables, and literals.
E On the next line type MDM. (including the dot).
This activates the ScriptAssist autosuggest feature, which means that a drop-down list appears
showing the object’s properties and methods.
E From the list, double-click the Open method.
This inserts the method into your script.

E Now type the opening parenthesis: (
This displays the method’s parameters. (This is called the autosignature.) The parameter that you
are on is shown in bold — we will use this parameter to specify the .mdd file to be opened.
Optional parameters are shown in square brackets.
E Type the name and location of the Short Drinks sample .mdd file. Because this is a text argument,
we must enclose it in quotation marks:
MDM.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Mdd\short_drinks.mdd")
E Now, click the Types tab to bring the Types pane to the front.
The Types pane is similar to the Visual Basic object browser. It shows the properties and methods
of all of the default objects. When you use the CreateObject function to create an instance of a
IBM® SPSS® Data Collection Data Model or IBM® SPSS® Data Collection object, the Types
7
Base Professional
pane also lists the objects in the associated type library. We created an MDM object from the
MDM type library, which is called MDMLib.
E Select MDMLib from the first drop-down list in the top left corner of the pane.
This restricts the list to the objects in the MDM type library.
There are tools on the Types pane toolbar that you can use to search and sort the list of objects
and the list of an object’s members. When you select an object on the left side of the pane, its
members are shown on the right. When you click on a property or method, the lower part of the
pane shows its syntax and other useful information (such as whether it is a read-only or read-write
property) and when you click on a constant, its value is shown. The Types pane has a shortcut
menu, like the Functions pane: right-clicking a member (such as a property or method) opens a
shortcut menu, which enables you to insert the property or method into the code.
To demonstrate working with a common Microsoft object, next we will create a Microsoft
Scripting FileSystemObject and use it to create a text file.
E Enter the following:
Dim FSO, MyTextFile
Set FSO = CreateObject("Scripting.FileSystemObject")

MyTextFile = FSO.
Even though the FileSystemObject is not an SPSS object, this activates the ScriptAssist feature
and opens a drop-down list of the object’s properties and methods. The ScriptAssist feature is
available for all suitable COM object models that are created using the CreateObject function.
Note that when the ScriptAssist feature is available for an object, the object’s type library will also
be included in the Types pane. However, the type library does not show in the Types pane until
you reference the object and type the dot (.) that activates the ScriptAssist feature.
8
Chapter 1
E From the list, select the CreateTextFile method and then type the opening parenthesis: (
Again, this makes Base Professional display details of the method’s parameters.
E Enter a name, and optionally the location, for the new text file, and then use the Dim statement
to define a variable called MyVariableInstance. For example:
MyTextFile = FSO.CreateTextFile("MyVariables.txt")
Dim MyVariableInstance
We will now create a macro that we can use to insert some common code into our script.
E From the Tools menu, choose Macros:
This opens the AutoExpansion Macros dialog box.

9
Base Professional
E Click on the mrScriptBasic tab.
E In the Macro Name text box, enter a name for our new macro. For example, FE.
E In the Macro Text text box, type the following:
For Each {0} In {1}
Next
The items in braces ({0} and {1}) define parameters. When we subsequently use the macro, Base
Professional will replace these with the first and second arguments that we supply.
E Click the Add Macro toolbar button (this is the leftmost button on the toolbar).
This adds the macro to the list of mrScriptBasic macros.

E Close the AutoExpansion Macros dialog box.
Now we will use the macro in our script.

E Back in the main Edit pane, type the following (where FE refers to the name you gave the macro.
Make sure you use exactly the same combination of upper and lower case letters that you used
when you defined its name.)
FE(MyVariableInstance,MDM.Variables)
E Now type Ctrl+M.
Base Professional inserts the macro and replaces the first parameter ({0}) with
“MyVariableInstance” and the second parameter ({1}) with “MDM.Variables”. (This is a
simplistic example to demonstrate using the macro feature. In practice you would normally use
macros to insert more complex code.)
10
Chapter 1
E Use the ScriptAssist feature to insert code into the loop to write the full name of the variable
instance to the text file and to add code after the loop to close the text file.
For Each MyVariableInstance In MDM.Variables

MyTextFile.WriteLine(MyVariableInstance.FullName)
Next
MyTextFile.Close()
E Now let’s run the code. You do this by pressing Ctrl+F5, selecting the Start Without Debugging tool,
or choosing Start Without Debugging from the Debugging menu.
If you are using the Save Before Execution option, Base Professional will prompt you for a name
for the script file. If necessary, enter a name (for example, MyFirstScript.mrs). Shortly afterwards
you should then see a message telling you that the script has completed successfully. If not,
you may have made an error in the script and you will need to debug it. For more information,
see the topic Debugging on p. 46.
E If your script ran successfully, open the text file in Base Professional.
11
Base Professional
Using IBM SPSS Data Collection Base Professional

This section provides a brief introduction to working in the IBM® SPSS® Data Collection Base
Professional integrated development environment (IDE). The following table summarizes the
topics in this section.
Which File Types Can I Work With? Explains which types of files you can work with in
the Base Professional IDE.
The IBM SPSS Data Collection Base Professional Introduces the Base Professional window, and
Window describes how you can customize the window layout
to suit your needs.
Working with Templates Explains how to base a new file on a template and
how to create new templates and edit existing ones.
Working with Macros Explains how to use, create, and edit macros.
Using the Workspace Feature Information about the workspace feature, which
is particularly useful when you are working on a
number of linked files.
Using the Metadata Viewer Introduces you to the Metadata Viewer, which
enables you to browse the objects in a Metadata
Document (.mdd) file. This is useful when you need
to look up names of variables and categories for use
in a filter or table.
Using the Connection String Builder Introduces you to the Connection String Builder,
which makes it easy to insert a connection string
into a script.
Using Context-Sensitive Help Describes how to access specific help for any
element of your script.
Using ScriptAssist Describes the ScriptAssist feature in Base
Professional, which can help you to write scripts
without having to remember the names of an
object’s properties and methods.
Finding and Replacing Text Describes some of the advanced options for finding
and replacing text in your scripts, including how to
use regular expressions to find patterns of text.
Debugging Introduces you to the features of the Base
Professional IDE that help you debug mrScriptBasic
files.
IBM SPSS Data Collection Base Professional in Describes how to display Base Professional in a
Other Languages language other than English.
Using IBM SPSS Data Collection Base Professional Describes the features of Base Professional that can
to develop interviews help you to develop, test, and deploy interviews.
Working with Advanced Editing Options Describes the Base Professional advanced editing
options.
IBM SPSS Data Collection Base Professional A handy list of all of the tools on the Base
toolbars Professional toolbars and their keyboard shortcuts.
IBM SPSS Data Collection Base Professional A handy list of the keyboard shortcuts you can use
keyboard shortcuts in Base Professional.
IBM SPSS Data Collection Base Professional Explains the options that you can use to customize
options the Base Professional IDE.
12
Chapter 1
Which File Types Can I Work With?

IBM® SPSS® Data Collection Base Professional has been designed for working with IBM®
SPSS® Data Collection script files of the following types:
Data Management Script (.dms) files. These scripts are used for performing data management
tasks, such as cleaning and transferring data, creating derived variables for use during
analysis, and setting up weighting schemes. A data management script has two or more
different sections, which have different coding rules and use different technologies. For
example, the InputDataSource section uses property definition and SQL syntax, whereas
the Metadata section is written in mrScriptMetadata, and the Event sections are written in
mrScriptBasic. A data management script is particularly useful when you want to clean and
transfer data and create derived variables, because it handles the connections to the input and
output data sources, the merging of the metadata, and gives you scriptable access to the case
data (in the OnNextCase Event section). You can run your data management scripts from
the Base Professional IDE or by using the DMS Runner command prompt utility. For more
information, see the topic Data Management Scripting on p. 204.
mrScriptBasic (.mrs) files. mrScriptBasic is a programming language that enables scriptable
access to Data Collection components. You would typically use a standalone mrScriptBasic
script to perform tasks that do not involve transforming data, such as creating reports, topline
tables and charts. Sometimes you might develop a mrScriptBasic script for use as an Include
file in one of the Event sections of a data management script. You can run and debug your
mrScriptBasic scripts from the Base Professional IDE or by using the .
Interview Script (.mdd) files. These scripts are used to create interviews that can be activated
in version 3.0 (or later) of IBM® SPSS® Data Collection Interviewer Server. Interview
scripts have a Metadata section, and one or more Routing sections. The Metadata section
is used to define the questions that will be asked during the interview and is written in
mrScriptMetadata. A Routing section is written in mrScriptBasic and defines which of the
questions will be asked during an interview, and in what order they will be asked. You can
have individual routing sections for different interview environments, for example, “Web”
and “Paper”. For more information, see the topic Interview Scripting on p. 503.
In addition to Data Collection scripts, you can also use Base Professional to create and edit
the following types of files:
Text (.txt) files
HTML files
XML files
Rich text format (.rtf) files
You can also open other types of text files, such as log files.
If you have IBM SPSS Data Collection Survey Reporter Professional, you can use Base
Professional to create an .mtd file that can be opened in IBM® SPSS® Data Collection Survey
Tabulation. However, you do not create or edit .mtd files directly. Instead you create them using a
script. For more information, see the topic Creating a Simple Table of Age by Gender on p. 1144.
13
Base Professional
The IBM SPSS Data Collection Base Professional Window

The IBM® SPSS® Data Collection Base Professional window has a number of different panes and
toolbars. You can use standard Windows techniques to rearrange the various panes and toolbars.
For example, you can use the title bar at the top of each pane to drag them into different positions.
When a pane is “floating”, you can double-click its title bar to return it to the position in which it
was last docked. For more information, see the topic Changing the Layout of the Window on p. 16.
The picture below briefly describes the layout of the Base Professional window.
If you open an interview script (.mdd) file, the layout includes some additional features which
are described in the picture below.
14
Chapter 1
Figure 1-1
The individual panes are described in more detail in the table below.
Tab Pane Description
Edit This is the main part of the
desktop, where you edit your files.
If you open an interview script
(.mdd) file, the Edit pane is
separated into a Metadata section
and one or more Routing sections.
By default, the individual sections
can be selected by clicking
on the tabs at the bottom of
the Edit pane. However, you
can change the way that the
metadata and routing sections
are displayed—see Viewing and
navigating an interview script for
more information. By default,
Base Professional also opens a
metadata viewer automatically
whenever you open an interview
script.
15
Base Professional

Breakpoints Lists the breakpoints that have
been set in a script. When you are
debugging, you use breakpoints
to indicate points in your code
at which you want to suspend
the running of the script—for
example, so that you can then step
through the following lines.
Output Displays status and other
information when you run a data
management script (.dms file).
Expressions Use this pane to evaluate an
expression or inspect the value
of a object property when you
are debugging a script. You
can also use this pane to change
the value of a variable.For
more information, see the topic
Examining the Values of Variables
on p. 49.
Find Use to search for text.
Replace Use to search for text and replace

with a different text.
Browser Use this pane to interact with
the interview when you run an
interview script (.mdd) file.
Workspace Lists the files in the current
workspace. The workspace
feature is particularly useful when
you are working on a number of
linked files—for example, a data
management script (.dms file)
that has a number of associated
Include files. You can add new
and existing files to the workspace
by right-clicking in the Workspace
pane and choosing Add New Item
to Workspace and Add Existing Item
to Workspace, respectively. For
Using the Workspace Feature on
p. 27.
Metadata Use to browse the questions,
variables, and categories in a
metadata document (.mdd) file.
This is useful when you need to
refer to individual variables and
categories in your script. For
Using the Metadata Viewer on p.
28.
16
Chapter 1

Types Similar to the Visual Basic
Object Browser, this shows the
properties and methods of all of
the default objects and details
of the associated enumerated
constants. Similar information
is shown whenever possible for
objects created in the script.
When you click on an object, its
properties and methods are listed.
To insert a property or method
into your code, right-click it, and
from the shortcut menu, choose
Add member.
Functions Lists all of the functions in
the IBM SPSS Data Collection
Function Library, showing brief
details of their parameters.
To insert a function into your
code, right-click it, and from
the shortcut menu, choose Add
Function. For detailed information
about the functions, see .
Locals Shows the values of the
variables in your script when
you are debugging it. For
on p. 49.
Auto Answer Shows a list of the questions that
have been answered when you
run an interview script (.mdd) file
in Auto Answer mode.
Repository Shows all currently defined
Question Repositories. You can
navigate for topics and survey
assets, and add asset metadata
and routing information to the
working .mdd file.
Help Shows context-sensitive
help topics. To access
context-sensitive help, select an
element of your script and press
F1, For more information, see
the topic Using Context-Sensitive
Help on p. 42.
Changing the Layout of the Window
The IBM® SPSS® Data Collection Base Professional window has a number of different panes.
The panes can be docked at any of the four edges of the main window or they can be floating
above the main window.
17
Base Professional
You can use standard Windows techniques to rearrange the various panes. For example:
You can use the title bar at the top of a pane or a group of panes to drag it into a different
position.
When a pane or group of panes is floating, you can double-click the title bar to return it
to the position in which it was last docked.
When a pane or group of panes is docked, you can double-click the title bar to return it to the
position in which it was last floating.
If you want to dock a floating pane or group of panes, click the title bar and drag it to the edge
of the window where you want it to be docked. When you move the mouse pointer over
a docking zone, Base Professional displays a gray outline that indicates the new docked
position. Note that it is the mouse pointer that is the trigger for this behavior and not the
edge of the pane you are dragging.
To move one pane out of a group of panes, click the pane’s tab and drag it into the desired
position.
To a move a floating pane into a group of panes, drag the floating pane’s title bar to the title
bar of the group.
You can dock a pane below another pane or a group of panes. This is just like docking at an
edge of the main window, except that you drag the pane you want to dock to the bottom of the
other pane. When you move the mouse pointer over the docking zone at the bottom of the
other pane, Base Professional displays the gray outline indicating the new docked position.
Restoring the Default Layout
You can restore the layout that existed when Base Professional was first installed on your
computer by deleting the three .bin files from the C:\Documents and Settings\<your Windows
user name>\Application Data\IBM\SPSS\DataCollection\6\Base Professional folder. Do not
delete any other files.
Creating Layouts for Different Tasks
When you run or debug a script, or run an interview script (.mdd) file using Auto Answer, IBM®
SPSS® Data Collection Base Professional automatically restores the window layout you were
using when you last performed the same task. When the script has finished executing, Base
Professional restores your original window layout. You can use this feature of Base Professional
to create individual window layouts for these different tasks.
For example, if you press Ctrl+F5 to run a data management script (.dms file), you might then
want to click on the Output pane tab and increase the size of the Output pane so that you could
follow the progress of the script more easily. When the script finishes running, Base Professional
will automatically decrease the size of the Output pane to the size it was before you ran the script
(and if the Output Pane was not visible to start with, it will be moved back behind another pane). If
you now run the data management script again by pressing Ctrl+F5, you will find that the Output
pane automatically appears and increases to the size that you set it to when you first ran the script.
18
Chapter 1
In a similar way, if you are working on an interview script you might want to reveal the Browser
pane and increase its size while you are debugging the script. When you are editing the script, you
might want to increase the size of the Edit pane and have the Find pane showing. The benefit
of this feature is that you only need to make those layout changes once, and not every time you
start and stop debugging.
Although this feature of Base Professional can be a little confusing at first, you might find it
useful once you have become more familiar with how it works. The important thing to remember
is to press Ctrl+F5, F5 or F6 first, and only then arrange the window layout to how you want it
to appear. In addition, wait for a script to finish executing before arranging your window layout
for editing tasks.
Viewing Large or Multiple Files
By default, the Edit pane displays a single view of one file, referred to as the current file. If you
wish, you can arrange the Edit pane so that you can view two different parts of the current file
simultaneously, or view multiple files simultaneously. You can also “bookmark” lines in your
file so that you can return to them easily without having to scroll through the file or use the
find command.
Viewing Different Parts of a File Simultaneously
When you are working on a large file, it is often useful to be able to browse and edit different parts
of the file at the same time, for example, if you want to copy text to another part of the file. You can
do this by choosing Split from the Window menu. This will split the Edit pane into two sections
that provide two separate views of the current file. Each section can then scroll independently.
The following picture shows an example of using this feature.

19
Base Professional
Figure 1-2
To change the relative sizes of the two sections, drag the split bar to the desired position. To return
to a single Edit pane, choose Remove Split from the Window menu.
Viewing Multiple Files Simultaneously
By default, IBM® SPSS® Data Collection Base Professional arranges multiple files in the Edit
pane as a single tab group. This means that only one file can be viewed at a time, but that you
can switch to any other file by clicking on its tab. If you want to view more than one file at the
same time, you can do so by creating additional tab groups. Each tab group will then appear
in its own section of the Edit pane.
To create an additional tab group, right-click on the tab of the file that you would like to be able to
view alongside the current file. From the shortcut menu, choose either New Horizontal Tab Group
or New Vertical Tab Group, depending on whether you want the files arranged horizontally or
vertically in the Edit pane.
The following picture shows an example of creating a new horizontal tab group.
20
Chapter 1
Figure 1-3
If you have more than two files open, you can move a file between groups by right-clicking on the
file’s tab, and from the shortcut menu, choosing Move to Next Tab Group or Move to Previous Tab
Group. You can also create more tab groups by choosing the relevant option from the shortcut
menu.
To change the relative sizes of tab groups, drag the split bar to the desired position. To return to a
single tab group, use the Move to Next Tab Group or Move to Previous Tab Group choices in the
shortcut menu to move all the files into a single group.
Using Bookmarks
You can use bookmarks to mark one or more lines in your file so that you can quickly find those
lines again. The following table lists the keyboard shortcuts that you can use to create and use
bookmarks.
Description Keyboard Shortcut
Insert a bookmark on the line where the cursor is Ctrl+Shift+B
positioned. If the line where the cursor is positioned
already has a bookmark, remove the bookmark.
Move to the next bookmark in the current file. Ctrl+Shift+N
Move to the previous bookmark in the current file. Ctrl+Shift+P
Remove all bookmarks from the current file. Ctrl+Shift+A
21
Base Professional
You can also create and use bookmarks using the bookmark toolbar buttons. For more information,
see the topic IBM SPSS Data Collection Base Professional toolbars on p. 93.
You can also use Base Professional’s Find feature to insert a bookmark on every line that contains
a text string. To do this, open the Find pane, enter a search string and click Mark All. A bookmark
is inserted on every line that contains the string. Note that if a line already contained a bookmark,
the bookmark will be removed.
Working with Advanced Editing Options
IBM® SPSS® Data Collection Base Professional provides a number of advanced editing features
that are available from the Edit menu:
Edit > Advanced
Advanced Option Description

Increase Line Indent Increases the indentation for the selected lines.
Decrease Line Indent Decreases the indentation for the selected lines.
Comment Selection Effectively comments-out script by adding an apostrophe character to
the beginning of each selected line.
Uncomment selection Removes the comment apostrophe characters from each selected line.
Tabify Selection Converts selected spaces into tabs. The number of spaces-to-tabs is
defined in the Tab Indent option in the IBM SPSS Data Collection Base
Professional options dialog.
Untabify Selection Converts selected tabs into spaces. The number of spaces-to-tabs is
defined in the Tab Indent option in the IBM SPSS Data Collection Base
Professional options dialog.
Working with Templates

IBM® SPSS® Data Collection Base Professional comes with a number of templates that you can
base new scripts on. The templates are organized into a number of folders. It is easy to amend the
templates and add new templates and template folders.
E To create a new script based on a template:
1. From the File menu, choose:

New > From Template
This opens the New File From Template dialog box. The left side of the dialog box lists the
available template folders.
2. On the left side of the dialog box, select the required folder. The right side of the dialog box now
displays the templates that are contained in the selected folder.
3. Select the template you want to use.
4. Click Open.
E To create a new template:
1. Create the file on which you want to base your template in the normal way.
22
Chapter 1
2. From the File menu, choose Save As.
3. Browse to the Templates folder in the folder where Base Professional was installed. In
the default installation, this is [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base
Professional\Templates.
4. Browse to the required template folder within the main Templates folder or click the Create
New Folder tool to create a new template folder.
5. In the File name box, type a name for the new template, and then click Save.
E To edit an existing template:
1. From the File menu, choose:

Open > File
2. Browse to the Templates folder in the folder where Base Professional was installed. In
the default installation, this is [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base
Professional\Templates.
3. Browse to the required template folder within the main Templates folder.
4. Select the template you want to edit and then click Open.
5. Edit and save the file in the normal way.
Project Templates
You can create a project template to preserve all of the files and settings for a specific IBM®
SPSS® Data Collection project that can be used again in the future. Project templates can include
survey files (.mdd), quota, sample, and layout templates. A project template can also include the
activation file, which stores all of the project activation settings, configured for deployment
to an interviewing player.
Project templates help you work more efficiently by minimizing repetition while leveraging
projects that have already been optimized and proven. You may currently have a project that is
utilized numerous times (for example, as a tracker), and have taken the time to tune the document
and modify the numerous activation settings that will be applied when the project is deployed to
a server (and/or locally). The project may also have consistent quota totals. A project template
would enable you to perform basic construction and configuration of a project once; the project
template would then be available for redeployment as needed.
When a project template is configured, and selected to be used for a new project in IBM® SPSS®
Data Collection Author or IBM® SPSS® Data Collection Base Professional, the .mdd file that is
stored within the template populates the authoring tool you are working in. Once the Activation
dialog is opened, the template’s activation settings are displayed, and Quota and Participants
information (within the Activation interface) are updated based on the template’s stored quota
and sample files. When activated, all of the files and settings are carried over to the server or
cluster to which the project is deployed.
23
Base Professional
Project templates can also be updated. A survey may require additional questions or categories,
different call times may be required to satisfy field constraints, an so on. You can save these
changes back to the original template, or create a new template if you have typical variations.
Creating and Saving Project Templates
IBM® SPSS® Data Collection Base Professional comes with a number of templates that you can
base new questionnaires on. The templates (stored as .ptz files) are organized into a number of
folders. It is easy to amend the templates and add new templates and template folders.
Creating a new questionnaire from a template
E From the menu, choose:

File > New > Project...
or press Alt+F, N, P.
This opens the Select Project Template dialog box. The left side of the dialog box lists the
available template folders.
E On the left side of the dialog box, select the required folder. The right side of the dialog box now
displays the templates that are contained in the selected folder.
E Select the template you want to use.
E Click Select.
Saving a questionnaire as a project template

File > Save As
or press Alt+F, A.
E Use the Save As dialog box to browse to the folder where you want to save the questionnaire as a
template.
Important: When the source .mdd file specifies a TemplateLocation, all files that exist in the
specified template location will be included in the template .ptz file. For example, if the source
.mdd file specifies your desktop as the TemplateLocation, all files on your desktop will be
packaged into the resulting project template .ptz file. As such, you must ensure that you select
an appropriate TemplateLocation.
E Select the file extension .ptz.
E Enter a name for the file and choose Save.
Note: Remember that depending on the folder location to which you saved the template, you may
need to copy or move the saved file to another location to be able to select it in Base Professional.
24
Chapter 1
Editing an existing project template

File > Open > File...
or press Alt+O, F.
E In the Open dialog box select the file extension .ptz and browse to the folder where your templates
are held.
E Select the template you want to edit and then click Open.
E Edit and save the file in the normal way.
Configure Project Templates dialog
Use the Configure Project Templates... dialog box to set defaults for the use of previously created
templates in IBM® SPSS® Data Collection Base Professional.
Fields on the Configure Project Templates dialog
Use local location: When your templates are stored locally, select this option and enter the details
of the template locations.
Project template folder: This is the location where all your project templates will be stored.
By default, the templates will be stored in C:\Documents and Settings\All Users\Application
Data\IBM\SPSS\DataCollection\6\Project Templates. If required, you can change the location to
point to your own files. To point to a different location for the templates, click Browse and then
use the Browse for Folder dialog box to select the required folder.
Important: When the source .mdd file specifies a TemplateLocation, all files that exist in the
specified template location will be included in the template .ptz file. For example, if the source
.mdd file specifies your desktop as the TemplateLocation, all files on your desktop will be
packaged into the resulting project template .ptz file. As such, you must ensure that you select
an appropriate TemplateLocation.
Default project template:For more information, see the topic Select Project Template dialog on
p. 25.
Use Question Repository: If your project templates are stored in IBM® SPSS® Data Collection
Question Repository, select this option and enter the details of the template locations.
Repository: Select the repository in which the templates are stored and connect to it.
Project template root topic: Select the root topic from the repository to identify the project
templates’ location. To point to a different root topic, click Browse and then use the Browse for
Folder dialog box to select the required topic.
25
Base Professional
Default Project template:For more information, see the topic Select Project Template dialog on
p. 25.
Working with unzipped project templates
To simplify the testing of project templates during development, unzipped templates will also be
supported. To deploy an unzipped template, you can simply copy or save the project files to the
correct project template location (local or server). In order to correctly recognize an unzipped
template, and to correctly distinguish it from a template folder and non-template files, the template
files must be correctly structured. More specifically, the following file structures for unzipped
templates will be supported:
MyProject
[MyProject.mdd]
Layout.htm
MyProject.mqd
MiscFiles
MyProjectSample.csv
MySMScript.mrs
OtherFileCopiedByUser.xyz
The unzipped project files must reside in a folder that matches the project name. This ensures that
project folder can be distinguished from a normal template folder. Any folder that contains files,
but does not contain template archives (.zip files) or Project_files, will be considered an unzipped
template. In this case, all files in the project folder are considered part of the template.
Select Project Template dialog
The Select Project Template dialog enables you to select the template to use when creating
a new project.
Template location: Displays the locations from which you can select templates. For example, this
may be on your machine, or from a server, but not both at the same time. Select the required
location to display the available templates in the Templates area.
Templates: The templates that you can use from the selected location are displayed. Click on the
one you want and click Select to open the new project.
Working with Macros

IBM® SPSS® Data Collection Base Professional comes with a number of macros to help you
build your scripts. There are three types of macros—, mrScriptBasic, Data Management Script,
and mrScriptMetadata. It is easy to add new macros and edit existing macros. For step-by-step
instructions on creating a macro and inserting it into your script, see Creating Your First
mrScriptBasic Script.
E To view, edit and add macros

26
Chapter 1
1. Open the AutoExpansion Macros dialog box by choosing Macros from the Tools menu.
2. Then select the type of macro that you want to work with by clicking on one of the three tabs
called mrScriptBasic, mrDataManagementScript or mrMetadataScript.
The following table lists the tools on the toolbar in the AutoExpansion Macros dialog box.
Tool Description
Adds the macro to the list.
Delete the selected macro.

Edit the selected macro. This copies the macro’s
code into the code text box, so that you can edit it.
Updates the select macro with the code defined in
the code text box.
E To insert a macro into your script:
1. In the main Edit window, place the cursor at the position in which you want to insert the macro.
2. Type the name of the macro followed by Ctrl+M. If the macro has parameters, enter the arguments
after the macro name, enclosed in parentheses and separated by commas.
For example, to insert the INP data management macro without specifying any arguments, type
INP, then without leaving a space, press Ctrl+M. To insert the FN1mrScriptBasic macro using i
and j as the arguments, type FN1(i,j), then without leaving a space press Ctrl+M.
Note that macro names are case-sensitive and you must not insert a space character between
the arguments.
E To create a new macro:
1. Open the AutoExpansion Macros dialog box, by choosing Macros from the Tools menu.
27
Base Professional
2. Click on the relevant tab for the type of your macro, either mrScriptBasic, mrDataManagementScript
or mrMetadataScript.
3. In the Macro Name text box, enter a name for the new macro.
4. In the Macro Text text box, type the code that you want the macro to insert. You can define
parameters by inserting numbers in braces. The parameters must be numbered in ascending order,
starting with 0 (for example, {0} and {1}). When you subsequently use the macro, you can
supply arguments to replace the parameters.
5. Click the Add Macro toolbar button.
E To edit an existing macro:
1. Open the AutoExpansion Macros dialog box, by choosing Macros from the Tools menu.
2. Click on the relevant tab for the type of macro, either mrScriptBasic, mrDataManagementScript
or mrMetadataScript.
3. Select the macro you want to edit in the list of macros.
4. Click the Edit Macro toolbar button. This displays the macro’s name and code in the text boxes at
the top of the dialog box.
5. Make the required changes.
6. Click the Update Macro toolbar button.
Using the Workspace Feature

A workspace is a container for the scripts and files that you are developing. Using a workspace
is particularly useful when you are working on a number of linked files—for example, a data
management script (.dms file) that has a number of associated Include files. However, using this
feature is optional. Although IBM® SPSS® Data Collection Base Professional automatically
creates an empty workspace when you open Base Professional, you can simply ignore this if
you don’t want to use the workspace feature.
When using this feature, you can begin by creating a workspace and adding files to it or by
creating files and then adding them to a workspace. The Workspace pane displays the files in
the workspace and makes it easy to switch between the files (you simply double-click a file to
open it in the Edit pane). You can add new and existing files to the workspace by right-clicking
the workspace folder in the Workspace pane and choosing Add New Item to Workspace and Add
Existing Item to Workspace, respectively. You can also add the current file to the workspace by
choosing Add Current Item to Workspace from the File menu, and you can remove a file from the
workspace by right-clicking it in the Workspace pane, and choosing Exclude from workspace.
When you save a workspace, it is saved as a file with an .sws filename extension. You can
subsequently open the workspace by double-clicking this file in Windows Explorer. Whenever
possible, the workspace stores the locations of the files relatively (provided they have a common
root folder). This makes it easy to share files with colleagues. For example, if you zip up a folder
containing a workspace and its associated files and send them to a colleague, the file locations
28
Chapter 1
specified in the workspace file should be valid, even if he or she unpacks the files into a different
folder.
To Create and Use a Workspace

To illustrate how the workspace feature works, we will make a workspace for the
IncludeExample.dms sample. This sample uses two include files—Include1.dms and Include2.dms.
1. Start a new workspace. You do this by choosing New > Workspace from the File menu or pressing
Ctrl+W.
2. Display the Workspace pane by clicking on the Workspace tab or pressing Alt+0 twice.
3. Now add the IncludeExample.dms file to the workspace. You can do this by right-clicking in the
Workspace pane and from the shortcut menu, choosing Add Existing Item to Workspace or by
choosing Add Existing Item to Workspace from the main File menu. Then in the Open dialog box,
browse to the location where the data management script samples are installed (typically this is
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS) and
select the IncludeExample.dms sample file.
4. Now we will use different techniques to add the include files to the workspace.
First choose Open from the main File menu and in the Open dialog box, browse
to the location where the data management script sample include files are installed
(typically this is [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data
Management\DMS\Include), select the Include1.dms and Include2.dms samples, and click OK.
This opens the two files in Base Professional.
5. View the Include1.dms sample in the Edit window, by clicking the Include1.dms tab to bring it to
the front.
6. From the main File menu, choose Add Current Item to Workspace.
7. Finally, save the workspace. You can do this by choosing Save Workspace from the main File
menu, or right-clicking in the Workspace pane and choosing Save. In the Save Workspace
As dialog box, give the workspace a name, such as IncludeExample, and then click OK. The
workspace file will be saved with a .sws extension, for example, IncludeExample.sws.
For more information about using Include files with data management scripts, see Using Include
Files in the DMS file.
Using the Metadata Viewer

When you are working in IBM® SPSS® Data Collection Base Professional, you can use the
Metadata pane to view the objects in a Metadata Document (.mdd) file. This is useful when you
need to look up names of variables and categories for use in a filter or table.
If you have installed Base Professional with the Interview option, each interview script will
open with its own individual metadata viewer attached to the side of the script. See Using the
interview metadata viewer for more information, which also contains advice on using the viewer
to help you write interview scripts.
29
Base Professional
You display the Metadata pane by choosing Metadata from the View menu or pressing Alt+7
twice. You can open any Metadata Document (.mdd) file. You do this by selecting the Open
Metadata Document toolbar button and then selecting the file in the Open Metadata dialog box.
If the .mdd file contains multiple versions, the latest version is opened initially. However, you
can change the version by right-clicking in the Metadata pane, choosing Change Version from the
shortcut menu, and then selecting the required version from the drop-drown list. Note that the file
is always opened in read-only mode and so any changes you make will not be saved.
When you are using the Metadata pane, the Properties pane displays the properties of the object
selected in the Metadata pane. For example, when you select a variable or element in the Metadata
pane, you can view its Label property in the Properties pane. Initially the labels are displayed in
the default language, but you can change the language by right-clicking in the Metadata pane,
choosing Change Language from the shortcut menu, and then selecting the required language
from the drop-drown list.
The following table lists the buttons on the toolbar in the Metadata pane.
Button Description
Create a new Metadata Document (.mdd) file.
Open a Metadata Document (.mdd) file.
Save the metadata to a Metadata Document (.mdd)

file.
Show or hide the Properties Pane.
View Allows you to show or hide the various types of

objects that the metadata viewer can display.
E To view the full names of the variables you can use in a filter in a DMS file:
1. If you are using an MDSC to read the input metadata, you will need to create an .mdd file before
you can open it in the Metadata pane. You can do this in MDM Explorer. For more information,
see the topic Creating an .mdd File From Proprietary Metadata on p. 314.
2. Open the .mdd file in the Metadata pane.
3. Double-click the Document’s Variables folder. This lists all the variables you can use in a filter in
a DMS file, showing for each one, its full name and an icon that indicates its type. The full names
are the names you need to use in the select query in your DMS file.
30
Chapter 1
When you select a variable in the Metadata pane, its properties are displayed in the Properties
pane. If you scroll through the properties, you will see the variable’s FullName property. It is easy
to copy the full name into your script. You do this by selecting the full name text, right-clicking
and choosing Copy from the shortcut menu. If you then move the cursor back into the main Edit
window, you can paste the full name into the script.
E To view category full names for use in a filter in a DMS file:
1. Select the required variable from the list in the Document’s Variable’s folder.
2. Double-click the variables’s Categories folder. This lists all the categories for that variable. You
can copy a category’s full name into your script, in the same way that you can copy a variable’s
full name.
31
Base Professional
For information about using the Metadata Viewer to look up variables names for use when
scripting tables, see:
Using the Flat (VDATA) View
Using the Hierarchical (HDATA) View
Using the Connection String Builder
The Connection String Builder makes it easy to insert a connection string into a script. You
typically use the Connection String Builder to specify the ConnectionString parameter in the
InputDataSource and OutputDataSource sections of a DMS file. The ConnectionString parameter
specifies the name, type, and location of the input and output data. If you are new to data
management scripting, see 3. Transferring Different Types of Data in the Getting Started section
for step-by-step instructions on using the Connection String Builder.
The Connection String Builder uses the Data Link Properties dialog box to build the connection
string. This dialog box has four tabs:
1. Provider. This is automatically set up to use the IBM SPSS Data Collection OLE DB Provider,
but you can select a different provider when necessary.
2. Connection. This is where you define the name, type, and location of the data.
32
Chapter 1
3. Advanced. This is where you define additional connection properties, such as the validation
options.
4. All. This lists all of the connection properties that you can set in a connection string.
E To use the Connection String Builder:
1. In the main Edit window, place the cursor at the position in which you want to insert the
connection string.
2. From the Tools menu, choose Connection String Builder.
3. Use the features of the Data Link Properties dialog box to specify the details of the data to which
you want to connect.
4. Click OK.
Data Link Properties dialog box
The Data Link Properties dialog box has the following tabs:
Provider - provides options for selecting the appropriate OLE DB provider for the type of
data you want to access.
Connection - provides access to the Metadata Properties and Metadata Versions dialog boxes
Advanced - provides options for defining additional connection options.
All - provides options for editing the initialization properties that are available for the chosen
Provider.
Data Link Properties: Provider
You use the Provider tab in the Data Link Properties dialog box to select the provider you want
to use.
33
Base Professional
Selecting the appropriate OLE DB Provider

To connect to the IBM® SPSS® Data Collection Data Model, select IBM® SPSS® Data
Collection DM-n OLE DB Provider (where n is the version number) from the list of OLE DB
Providers.
To connect to another provider, select the appropriate entry from the list of OLE DB Providers
(for example to select a Microsoft SQL Server provider, select Microsoft OLE DB Provider for
SQL Server from the list).
Refer to the appropriate database provider documentation for information on configuring

connection strings.
Data Link Properties: Connection
You use the Connection tab in the Data Link Properties dialog box to define the name, location,
and type of the data to which you want to connect. When you select IBM® SPSS® Data
Collection DM-n OLE DB Provider (where n is the version number) on the Provider tab, an Data
Collection-specific Connection tab is displayed.
34
Chapter 1
Metadata Type. Defines the type of metadata. The drop-down list shows the types of metadata for
which you have a metadata source component (MDSC). The default options are:
None. Choose this option if you want to connect to case data only.
Data Collection Metadata Document. MR Metadata Document. Selects metadata that is in
the standard IBM® SPSS® Data Collection Data Model format, which is a questionnaire
definition (.mdd) file.
ADO Database. Selects metadata that is in an ActiveX Data Objects (ADO) data source.
Data Collection Log File. Selects metadata in a standard Data Collection log file.
Data Collection Participation Database. Selects metadata that is in a IBM® SPSS® Data
Collection Interviewer Server Administration project’s Sample and HistoryTable tables.
Data Collection Scripting File. Selects metadata that is in a mrScriptMetadata file.
In2data Database. Selects metadata that is in an In2data database (.i2d) file.
Quancept Definitions File (QDI). Selects metadata in a IBM® SPSS® Quancept™ .qdi file
using the QDI/DRS DSC.
Quancept Script File. Writes the metadata in an MDM document to a Quancept script (.qqc) file.
Quantum Specification. Writes the metadata in an MDM document to a IBM® SPSS®
Quantum™ specification.
Quanvert Database. Selects metadata that is in a IBM® SPSS® Quanvert™ database.
Routing Script File. Writes the routing section of an MDM document to a script that defines the
routing required for interviewing.
35
Base Professional
SPSS Statistics File (SAV). Selects metadata that is in an IBM® SPSS® Statistics .sav file.
Surveycraft File. Selects metadata that is in a IBM® SPSS® Surveycraft™ Validated
Questionnaire (.vq) file.
Metadata Location. The name and location of the metadata. The way you specify this depends on
the type of metadata that you selected in the previous drop-down list:
Data Collection Metadata Document. The name and location of the .mdd file.
ADO Database. The name and location of a .adoinfo file, which is an XML file that specifies the
connection string for the target data source and the name of the target table in that data source.
Data Collection Log File. The name and location of the log file. Typically log files have a
.tmp filename extension. However, some log files may have another filename extension. If
necessary, you can rename the file so that it has a .tmp filename extension.
Data Collection Participation Database. The name and location of a Participants Report
Document (.prd) file, which is an XML file that specifies the connection string and the names
of the table and columns to be used.
Data Collection Scripting File. The name and location of the mrScriptMetadata file. Typically
these files have an .mdd or .dms filename extension.
In2data Database. The name and location of the .i2d file.
Quancept Definitions File (QDI). The name and location of the .qdi file.
Quancept Script File. The name and location of the .qqc file.
Quantum Specification. The location of the Quantum specification files.
Quanvert Database. The name and location of the qvinfo or .pkd file.
Routing Script File. The name and location of the routing script file.
SPSS Statistics File (SAV). The name and location of the .sav file.
Surveycraft File. The name and location of the .vq file.
Click Browse to select the file in the Open dialog box.

Open Metadata Read/Write. By default, the metadata is opened in read-only mode. Select this
option if you want to be able to write to it. When you open some types of data (for example, a
Quanvert database) the metadata is always opened in read-only mode.
Properties. Edit MDM Properties. Click this button to open the MetadataMDM Properties dialog
box, in which you can specify the versions, language, context, and label type to use. For more
information, see the topic Data Link Properties: Metadata Properties on p. 73.
Case Data Type. Defines the type of case data. The drop-down list shows all of the types of case
data for which you have a case data source component (CDSC). The default options are:
ADO Database. Reads case data from an ActiveX Data Objects (ADO) data source.
Delimited Text File (Excel). Writes case data in tab-delimited format to a .csv file.
Data Collection Database (MS SQL Server). Reads and writes case data in a Data Collection
relational database in SQL Server. This option can be used to read data collected using IBM®
SPSS® Data Collection Interviewer Server.
Data Collection Log File. Selects the Log DSC, which enables you to read Data Collection
log files.
36
Chapter 1
Data Collection XML Data File. Reads and writes case data in an XML file. Typically, you use
this option when you want to transfer case data to another location.
In2data Database. Reads case data from an In2data Database (.i2d ) file.
Quancept Data File (DRS). Reads case data in a Quancept.drs, .drz, or .dru file using the
QDI/DRS DSC.
Quantum Data File (DAT). Selects the Quantum DSC, which reads and writes case data in a
Quantum-format ASCII file.
Quanvert Database. Selects the Quanvert DSC, which reads data in a Quanvert database.
SPSS Statistics File (SAV). Reads and writes case data in an SPSS Statistics .sav file.
Surveycraft File. Reads case data from a Surveycraft data file.
Tip: If you have specified a Metadata Type and a Metadata Location, and the default data source
in your metadata refers to the case data that you want to connect to, you don’t need to specify
a Case Data Type or a Case Data Location.
Case Data Location. The name and location of the case data. The way you specify this depends on
the type of case data that you selected in the previous drop-down list:
ADO Database. The OLE DB connection string for the ADO data source. To build this string,
click Browse, which opens a second Data Link Properties dialog box in which you can choose
the options for your data source. For example, to connect to a Microsoft Access database or a
Microsoft Excel file, select Microsoft OLE DB Provider for ODBC Drivers in the Provider tab and
click the Build button in the Connection tab to build a connection string that uses the Machine
Data Source called “MS Access Database” or “Excel Files” as appropriate. If your data source
is a Microsoft SQL Server database that is not a Data Collection relational database, select
Microsoft OLE DB Provider for SQL Server in the Provider tab and enter the server name and
database name in the Connection tab. Then click OK to close the second Data Link Properties
dialog box and return to the Connection tab of the first Data Link Properties dialog box.
Delimited Text File (Excel). The name and location of the .csv file.
Data Collection Database (MS SQL Server). This must be an OLE DB connection string.
Data Collection XML Data File. The name and location of the .xml file.
Quancept Data File (DRS). The name and location of the .drs, .drz, or .dru file.
Quantum Data File (DAT). The name and location of the .dat file. If a .dau file is created, it will
have the same name, but with the file name extension of .dau.
Surveycraft File. The name and location of the Surveycraft Validated Questionnaire (.vq) file.
The Surveycraft .qdt file, which contains the actual case data, must be in the same folder
as the .vq file.
Click Browse if you want to browse to the location of the case data in a dialog box.
37
Base Professional
Case Data Project. This text box should be blank, unless you are connecting to one of the
following case data types:
ADO Database. If you are connecting to a Microsoft SQL Server database (that is not a Data
Collection relational database) or a Microsoft Access database, enter the name of the database
table that you want to use. If you are connecting to a Microsoft Excel file, enter the name of
the worksheet that you want to use, for example, Sheet1. Depending on the version of Excel
installed, you may have to add a dollar sign ($) after the worksheet name for the connection to
be successful, for example, Sheet1$.
Data Collection Database (MS SQL Server). Enter the name of the project that you want to use.
Test Connection. Click this button to test the connection and verify whether you have entered all
information correctly.
Data Link Properties: Metadata Properties
You use the Metadata Properties dialog box to define the version, language, context, and label type
that you want to use when you connect to a questionnaire definition (.mdd) file (also known as
IBM® SPSS® Data Collection Metadata Document file). You open this dialog box by clicking
the Properties button in the Metadata section on the Connection tab in the Data Link Properties
dialog box.
Version. Select the version or versions that you want to use. Questionnaire definition (.mdd) files
typically contain , which record any changes to the content of the questionnaire. Typically, when
the questionnaire changes (for example, a question or category is added or deleted) a new version
is created and when the changes are complete, the version is locked. The drop-down list box
displays all of the available versions plus three additional options:
All versions. Select this option if you want to use a combination (superset) of all of the
available versions. (This is sometimes called a superversion). When there is a conflict
between the versions, the most recent versions generally take precedence over the older
versions. For example, if a category label differs in any of the versions, the text in the latest
version will be used. However the order of questions and categories is always taken from the
most recent version and there is special handling of changes to loop definition ranges and the
minimum and maximum values of variables, similar to that described for the IBM® SPSS®
Data Collection Metadata Model Version Utility in . Use the Multiple Versions option if
you want to change the order of precedence.
38
Chapter 1
Multiple versions. Select this option if you want to use a combination (superset) of two or
more specific versions. For more information, see the topic Data Link Properties: Metadata
Versions on p. 74.
Latest version. Select this option if you want to use the most recent version.
Using a combination of some or all of the versions is useful when, for example, you want to export
case data for more than one version and there have been changes to the variable and category
definitions that mean that case data collected with one version is not valid in another version.
Selecting all of the versions for which you want to export the case data, means that generally
you can export the case data collected with the different versions at the same time without
encountering validity errors due to the differences between the versions. However, depending on
the version changes, some validity errors may still be encountered.
Language. Languages. Select the language you want to use. You can change the language only if
there is more than one language defined.
Context. Contexts. Select the user context you want to use. The user context controls which texts
are displayed. For example, select Question to display question texts, or Analysis to display shorter
texts suitable for displaying when analyzing the data.
LabelType. LabelTypes. Select the label type you want to use. You should generally select the
Label option.
Data Link Properties: Metadata Versions
You use the Metadata Versions dialog box when you want to select two or more versions of the
questionnaire definition (.mdd) file. You open this dialog box by selecting Multiple Versions in the
Version drop-down list box in the Metadata Properties dialog box.
39
Base Professional
Versions. The Metadata Versions dialog box lists all of the versions that are available. Click Select
All to select all of the versions. Click Clear All to deselect all of the versions and then select the
versions you want individually. For each version, the following information is shown:
Name. Version. The version name. Version names are made up of a combination of the major
version and minor version numbers in the form Major#:Minor#, where Major# is the number
of the major version and Minor# is the number of the minor version. Changes in the major
version number indicate that the structure of the case data has changed (for example, variables
or categories have been added or deleted) whereas changes in the minor version number
indicate that the changes affect the metadata only (for example, a question text has been
changed). Version names are created automatically when a version is locked. A version that
has not been locked is always called LATEST.
Created by. The ID of the user who created the version.
Created Date. This shows the date and time at which the version was locked.
Description. When present, this is a text that gives information about the version.
The order in which you select the versions controls the order of precedence that will generally be
used when there is a conflict between the versions. For example, if a category label differs in the
versions you select, the text in the version with the higher precedence will be used. However the
order of questions and categories is always taken from the most recent version and there is special
handling of changes to loop definition ranges and the minimum and maximum values of variables,
similar to that described for the IBM® SPSS® Data Collection Metadata Model Version Utility in
If you want the most recent version to take precedence, start selecting the versions at the top
and work down the list. If you want the oldest version to take precedence, start at the bottom
and work up the list.
Note that you can select multiple versions by pressing Ctrl or Shift while you click.
Tip. You can select individual or multiple versions by pressing Ctrl or Shift while you click,
provided the mouse is in the Description or Date/Time Locked column. You can then click in the
Version column to select or deselect the check boxes for all of the versions that you have selected.
You may find this useful when you are working in a file that has many versions.
Selected Versions. Displays an expression that represents the selection you have chosen. You can
optionally select the versions you want to use by typing an expression directly into this text box.
The order of precedence is taken from the order in which versions are specified, with the rightmost
versions taking precedence over the leftmost.
Syntax Description
.. Specifies all versions
v1, v2, v3, v4 Specifies individual versions
v1..v2 Specifies an inclusive range of versions
^v1..v2 Excludes a range of versions
Specifies the most recent version.
40
Chapter 1
You can specify a combination of individual versions, and ranges to include or exclude. For
example, the following specifies version 3:2 and all versions from 4:5 to 7:3 with the exception
of versions 7 through 7:2:
3:2, 4:5..7:3, ^7..7:2
Data Link Properties: Advanced
You use the Advanced tab in the Data Link Properties dialog box to define additional connection
options. When you select IBM® SPSS® Data Collection DM-n OLE DB Provider (where n is the
version number) on the Provider tab, an Data Collection-specific Advanced tab is displayed.
Metadata Source when Location is Different. If existing Data Source has a different location. The
Data Model uses the DataSource object to store details about case data that is associated with an
MDM Document (.mdd file). This option specifies what should happen if there is no DataSource
object in the MDM Document with the same case data type whose location matches the case
data location specified on the Connection tab:
Use the Data Source (except for location). This is the default behavior. Select this option if
you want to use the first DataSource object of the same type that is encountered and do not
want to store the new case data location in it.
Use the Data Source and store the new location. Select this option if you want to use the first
DataSource object of the same type that is encountered and store the new case data location
in it.
41
Base Professional
Create a new Data Source. Select this option if you want to create a new DataSource object.
This is useful when you do not want to use the same variable names when exporting to SPSS
.sav as used previously.
Raise an Error. Select this option if you want the connection to fail.
For more information, see the IBM® SPSS® Data Collection Developer Library.
Categorical variables. Specifies whether to display the categories of categorical variables as

numeric values or names.
Preserve source column definitions. Select this option if you want the native objects in the
underlying database to be exposed directly as Data Model variables without any interpretation.
For example, if you select this option, a multiple dichotomy set in a .sav file would be represented
as several long or text variables instead of one categorical variable.
Reading categorical data. Specifies whether to display the categories of categorical variables as
Writing data. Specifies whether the CDSC deletes the output data, if it exists, before writing
new data. The options are as follows:
Append to existing data. This is the default behavior. Select this option if you want to append
to the existing data if it exists.
Replace existing data. Select this option if you want to delete the existing data and schema.
This will allow data to be created with a different schema.
Replace existing data but preserve schema. Select this option if you want to delete the existing
data, but preserve the existing schema if possible. Note that for some CDSCs, such as SPSS
SAV and Delimited Text, the schema will not be preserved because deleting the data results
in the loss of the schema.
Validation. Perform data validation. Select if you want case data to be validated before it is written.
Deselect if you do not want any validity checks to be performed on case data before it is written.
Allow Dirty. Allow dirty data. Select if you have chosen data validation, and you want to run in
dirty mode. This means that data is accepted even if it has some inconsistencies. Deselect this
option to run in clean mode, which means that data is rejected if it contains any inconsistencies
(for example, if more than one response has been selected in answer to a single response question).
The validation that is performed varies according to the CDSC that is selected.
User name. If required, enter your User ID.
Password. If required, enter your password.
Data Link Properties: All
You can use the All tab in the Data Link Properties dialog box to edit all of the initialization
properties that are available for the Provider. However, generally you define the values for the
properties on the Connection and Advanced tabs.
42
Chapter 1
The All tab lists all of the initialization properties and you can edit the values by selecting
a property and clicking Edit Value.
For detailed information about the connection properties, see Connection Properties in the IBM®
SPSS® Data Collection Data Model section of the DDL.
Using Context-Sensitive Help
If you have the IBM® SPSS® Data Collection Developer Library (DDL) installed on your
computer, you can access specific help for any element of your IBM® SPSS® Data Collection
Base Professional script. To do this, position the cursor in the element in the Base Professional
Edit pane (or select the element by double clicking on it) and press the F1 key. The most relevant
help topic in the DDL will then appear.
Specific help topics are included for all mrScriptBasic and mrScriptMetadata keywords, data
management script keywords, Data Model functions, preprocessor directives, and IBM® SPSS®
Data Collection object models. If a variable in your script references a Data Collection object,
placing the cursor in the variable name and pressing F1 will open the help topic for the object
type. If Base Professional cannot find a specific topic, for example, because a variable does not
reference an object, the overview topic for the type of script that you are editing will appear
instead. If the displayed help topic does not provide you with the information you need, you can
use the help system’s Contents, Index, and Search features.
To copy text from a help topic to the Windows clipboard, select the text, right click on it, and
choose Copy from the shortcut menu.
43
Base Professional
Using ScriptAssist
ScriptAssist is an automatic feature of IBM® SPSS® Data Collection Base Professional that can
help you to write scripts more quickly. Whenever you type a dot (.) after the name of a variable,
ScriptAssist displays a list of the members (properties and methods) or global functions that are
valid for that variable. Using the mouse or keyboard, you can select one of the entries in the
suggestion list, and it will be pasted into your script. This feature makes it easy to include objects
in your scripts without having to remember the names of all the valid properties and methods.
When the ScriptAssist suggestion list appears, you can select an item from the list by
double-clicking on the item, or by highlighting the item using the arrow keys and typing a dot (.).
If your variable is a question in the routing section of an interview script, the suggestion list might
show category names or sub questions, depending on the definition of the question.
Items in the Suggestion List
The following table list the different types of items that can appear in a suggestion list. The items
that actually appear will depend on the type of script and the variable name that has just been typed.
Icon Description
Property of an object.
Default property of an object.
Method of an object, or Function in the .
Enumerated type.
Question, or Built-in variable.
Category in a categorical question.
You can specify which items you would like to see in the suggestion list, or even stop the
suggestion list from appearing. For more information, see “ScriptAssist Options” in IBM SPSS
Data Collection Base Professional options.
Activating ScriptAssist Manually
You can use the following keyboard shortcuts to force the ScriptAssist suggestion list to appear.
The contents of the suggestion list will depend on the type of script, and the position of the
cursor when the keyboard shortcut is pressed.
Keyboard Shortcut Description Where to use
Ctrl+Space Display a global list of all Anywhere in a mrScriptBasic
IBM® SPSS® Data Collection script (.mrs) file, in the routing
functions, built-in variables, and section of an interview script
enumerators in Data Collection (.mdd) file, or in an event section
Type libraries. If pressed in the of a data management script
routing section of an interview (.dms) file.
script, the list will include all
44
Chapter 1
questions defined in the metadata

section.
Ctrl+Q Display a list of all the questions In the routing section of an
defined in the metadata section. interview script.
If the cursor was positioned after
the name of a question, Ctrl+Q
will display a list of all the sub
questions for that question.
Ctrl+R Display a list of all the categories In the routing section of an
for a question. interview script, with the cursor
positioned after the name of a
categorical question.
Finding and Replacing Text
You use IBM® SPSS® Data Collection Base Professional’s Find and Replace panes to find and
replace text in your scripts. You can open these panes from the Base Professional Edit menu or by
pressing Ctrl+F to open the Find pane and Ctrl+H to open the Replace pane.
Several advanced options exist to help you find exactly what you are looking for and these are
described below. You can also use regular expressions to search for patterns of text.
Searching Multiple Scripts
To search for a text string in all your open scripts, open the Find pane, enter a search string, and
select All open documents before clicking Find Next.
Listing all Occurrences of a Text String
To display a list of the lines in your script that contain the text you are looking for, open the Find
pane, enter your search string and click Find All. The Find Results pane opens and displays a list of
the lines that contain one, or more than one, occurrence of the string. Double clicking on any line
(or selecting the line and clicking Goto Current) displays the corresponding line in the Edit pane
and highlights the first occurrence of the string. To display each line in turn, click Goto Next.
If you select All open documents before clicking Find All, the search results will include all
your open scripts. The “File” and “Location” columns in the Find Results pane show you in
which script the string was found.
Bookmarking all Occurrences of a Text String
To add a bookmark to every line that contains the text you are looking for, enter a search string,
and click Mark All. A bookmark is inserted on every line that contains the string. Note that if a
line already contained a bookmark, the bookmark will be removed. To add bookmarks to all your
open scripts, select All open documents before clicking Mark All.
For more information about bookmarks, see “Using Bookmarks” in Viewing Large or Multiple
Files.
45
Base Professional
Using Regular Expressions to Find Text
You can use regular expressions to search for text in your script. Regular expressions are a flexible
and powerful notation for finding patterns of text. To use regular expressions, open either the Find
pane or the Replace pane and select the Use check box. When you next click Find Next, your
search string will be evaluated as a regular expression.
When a regular expression contains characters, it usually means that the text being searched
must match those characters. However, regular expressions use a number of characters that have a
special meaning. The following table provides a summary of the most common special characters
used in regular expressions. The special characters are shown in bold and are case sensitive—for
example, \U is not the same as \u.
Regular Expression Description
. Any character (including newline).
[abcn-z] Any of the characters a, b, c, n, o, p, ..., z.
[âbcn-z] Any characters except a, b, c, n, o, p, ..., z.
\w Any alphanumeric character (including accents) or
underscore (_).
\l Any lower-case character (including accents).
\u Any upper-case character (including accents).
\d Any numeric character.
\s A whitespace character.
^xxx xxx at the beginning of a line.
xxx\r$ xxx at the end of a line. In IBM® SPSS® Data
Collection Base Professional, you must use \r$ to
find text at the end of a line instead of the more
typical $.
xxx|yyy Either xxx or yyy.
(xxx) Grouping (subexpression).
x* Zero or more occurrences of x.
x+ One or more occurrences of x.
x? Zero or one occurrences of x.
(xxx){m} Exactly m occurrences of xxx.
(xxx){m,n} At least m and at most n occurrences of xxx.
\ The escape character that you use to match
characters that have a special meaning in regular
expressions, such as the following characters , . ? {
} [ ] ( ) $ ^ *. For example, to match the { character,
you would specify \{.
Examples
Example Matches
abcd The character sequence abcd anywhere in a line.
âbcd The character sequence abcd at the beginning of
a line.
^\s*abcd The character sequence abcd at the beginning of a
line after zero or more spaces.
46
Chapter 1
Example Matches
abcd\r$ The character sequence abcd at the end of a line.
\.txt\r$ The character sequence .txt at the end of a line.
[Â-Z]+ Any character that is not an uppercase English letter.
[0-9]+\r$ Any digits in the range 0-9 that appear at the end
of a line.
^\$ A dollar sign at the beginning of a line.
\[\] The [ character and the ] character.
For a more detailed description of the regular expression syntax, see

http://www.boost.org/libs/regex/doc/syntax.html
Debugging
IBM® SPSS® Data Collection Base Professional has a number of features to help you identify
and correct bugs (errors) in your mrScriptBasic code. You can debug mrScriptBasic script
(.mrs) files, the routing sections of interview script (.mdd) files, and the Event sections of data
management script (.dms) files. Other sections in a .dms file are not suitable for debugging because
they are properties sections and do not contain mrScriptBasic code.
Bugs fall into two main categories:
Syntax errors. These are improperly formed statements that don’t conform to the rules of the
scripting language. Syntax errors include spelling and typographical errors, and are generally
caught when parsing the script before executing it. For more information, see the topic Syntax
Errors on p. 46.
Semantic errors. These occur when your script’s syntax is correct, but the semantics or meaning
are not what you intended. Semantic errors might not be caught during the parsing stage, but will
cause the script to execute improperly. Semantic errors might cause the script to crash, hang, or
produce an unintended result when executed.
When your script is not producing the results that you expect, it usually means that you have made
a semantic error. This type of error is less easy to track down than a simple syntax error. However,
Base Professional provides a number of features to help you:
Stepping Through the Code
Setting Breakpoints
Showing Line Numbers
Syntax Errors
IBM® SPSS® Data Collection Base Professional can detect some syntax errors when parsing
the script before executing it. Examples of these errors are mispelling a keyword or the name of
a variable.
47
Base Professional
The following code includes two syntax errors—a spelling error on line 3 (the final “n” has been
omitted from the name of the Position variable) and the “Then” keyword has been omitted from
the If statement on line 5.
Dim Position
Positio = Find("ABDCDEFGHIJKLM", "H")
If Position > 5
Position = Position + 3
End If
If you attempt to run this code, Base Professional will detect and underline the errors during the
initial parsing stage and will stop before executing the code, displaying a message describing the
problem below the error. If the error is due to a specific word then that word will be underlined,
otherwise the entire line will be underlined.
When you press Esc, to close the error message, the underlining remains, making it easy to
subsequently identify the exact position of the errors.
Note that you cannot edit your script while you are in debugging mode—you need to stop the
debugging session first. Do this by pressing Ctrl+F5 or choosing Stop from the Debug menu. If
there has been an error, debugging will stop automatically, putting you instantly in edit mode.
Some syntax errors cannot be detected until the code is actually executed. An example of this
type of error is spelling a function name incorrectly. For example, suppose we correct the above
example and then deliberately mispell the Find function as “Fnd”.
Dim Position
Position = Fnd("ABDCDEFGHIJKLM", "H")
If Position > 5 Then

Position = Position + 3
End If
48
Chapter 1
When we attempt to run the code, Base Professional finds that there is no function called “Fnd”,
so it underlines it and displays an execute error message similar to the parser error message we
saw before. However, the text of the message indicates that it is an execute error.
Because Base Professional pinpoints the exact position of any syntax errors, identifying and
correcting the problems is usually fairly straight forward. Identifying and correcting semantic
errors of your script is generally more challenging.
Stepping Through the Code
Stepping through code means executing the code one line at a time. Stepping allows you to see
the exact sequence of execution and the value of the various variables at each step. This can be
invaluable when your script is not giving the results that you expect.
When stepping through a script reaches an Include file, the Include file is opened so that it can
be stepped through as well.
E To step through the code one line at a time, press F10 or choose Single Step from the Debug menu.
IBM® SPSS® Data Collection Base Professional then executes the current line of code and
moves to the next line, which it highlights.
E To execute the next line of code, press F10 again or choose Single Step from the Debug menu.
Note that if you are stepping through an OnNextCase Event section in a DMS file, you will step
through each case, which could be a lengthy process if there are many cases.
Setting Breakpoints
When you do not want to step through an entire script line by line, you can set breakpoints at the
points in the code at which you want the execution to stop, so that you can step through the
following lines. This is particularly useful when you have a rough idea where the problem lies.
E There are several ways to set a breakpoint. Move the cursor to the line on which you want to
set the breakpoint, and then:
Choose Toggle Breakpoints from the Debug menu.
-or-
Press Ctrl+B or F9.
-or-
Click the Edit pane to the left of the line number.
49
Base Professional
IBM® SPSS® Data Collection Base Professional then highlights the line in red and adds the
breakpoint to the list in the Breakpoints pane.
E To run the code up to the next breakpoint, press F5 or choose Start or Continue from the Debug
menu.
Base Professional executes the code up to the breakpoint and then it stops, so that you can examine
the values of any variables and object properties and step through the following lines.
E To clear a breakpoint, move the cursor to the breakpoint, and then:

Choose Toggle Breakpoints from the Debug menu.
-or-
Press Ctrl+B or F9.
-or-
Click the Edit pane to the left of the line number.
E To clear all breakpoints, press Ctrl+Shift+F9 or choose Clear All Breakpoints from the Debug menu.
When you are debugging a script and its execution is halted (for example, at a breakpoint or when
you are stepping through the code line by line), you can move your mouse over any variable to get
IBM® SPSS® Data Collection Base Professional to display its current value.
50
Chapter 1
Checking the Syntax of Functions
If you have used any of the functions in the , you can move your mouse over them to get Base
Professional to display the correct syntax. This is particularly useful when functions have several
parameters and you want to check that you have specified them in the correct order, for example.
Using the Locals Pane to Examine Values
When you are debugging a script, Base Professional displays in the Locals pane the current
value of all of the variables in the current scope.
In addition, Base Professional shows in the Locals pane the current value of the properties of
the objects in the current scope. You can expand and inspect objects by clicking the plus icon
next to the object, but note that an object can only be expanded while the script is halted during
debugging, not when the script has completed.
51
Base Professional
You can also use the Locals pane to check the value of the Err object’s properties. This is
particularly useful when you are using error handling to stop the script failing and an error occurs.
52
Chapter 1
Using the Expressions Pane
You can use the Expressions pane to evaluate an expression or to inspect the value of an object’s
properties. There are two ways of doing this:
Type the expression in the text box and click Evaluate.
Type a question mark, then type the expression and press Enter. For example, type ?a and
press Enter to display the value of the a variable.
You can also re-evaluate an expression that you previously evaluated by selecting the text of the
expression in the text box and clicking Evaluate.
For example, here is the Expressions pane after using the Sqrt function to evaluate the square
root of the a variable:
Note that sometimes you might need to resize the pane in order to be able to see the output. Here
is the Expressions pane after evaluating the value of an MDM property:
You can also use the Expression pane to change the value of a variable. For example, if you type
a = 15 into the text box and press Enter (or alternatively, click Execute), Base Professional will
set the value of the a variable to 15.
The Expression pane can also be used to declare variables, which you can then use to store the
current value of another variable when you are debugging a script. For example, type dim temp
in the text box and press Enter to declare a variable called temp. Then assign the value of a to
temp by typing temp = a and pressing Enter. To restore the original value of a at any point, type
a = temp and press Enter.
Showing Line Numbers
IBM® SPSS® Data Collection Base Professional can optionally show line numbers on the left
side of the Edit pane. This is particularly useful when you use mrScript Command Line Runner to
run your mrScriptBasic files, because it reports the line number in the error messages.
53
Base Professional
E To show line numbers, choose Options from the Tools menu.
E Click on Show Line Numbers, and then select True from the drop-down list.
E Click OK.
IBM SPSS Data Collection Base Professional in Other Languages

You can display the application in a language other than English. You can change the language at
any time by following the appropriate instructions below for your computer’s operating system.
Close the application before making these changes. You can change the language back to English
at any time or even switch back and forward between various languages.
To Display the application in a Different Language
On a Windows XP Professional or Windows Server computer:
1. Refer to the Microsoft article Set up Windows XP for multiple languages

(http://www.microsoft.com/windowsxp/using/setup/winxp/yourlanguage.mspx).
2. Delete all files (for example, Default_DockingLayout.xml and Options.xml) from the following
folders:
For IBM® SPSS® Data Collection Author: C:\Documents and Settings\<Windows user
name>\Application Data\SPSSInc\IBM\SPSS\DataCollection\6\Author\
For IBM® SPSS® Data Collection Survey Reporter: C:\Documents and Settings\<Windows
user name>\Application DataSPSSInc\IBM\SPSS\DataCollection\6\Survey Reporter\
3. Modify the appropriate application configuration file to include the desired culture value. For
example, add the following to change the language to French:
<appSettings>
<add key="Culture" value="fr-FR" />
</appSettings>
Language Culture Value

Chinese ZH-cn
English en-US, or blank
French fr-FR
German de-DE
Italian it-IT
Japanese ja-JP
Spanish es-ES
For Author: [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\\Author\Author.exe.config

For Survey Reporter: [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\\Survey
Reporter\Reporter.exe.config
For IBM® SPSS® Data Collection Base Professional:
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base Professional\mrstudio.exe.config
54
Chapter 1
On a Windows Vista Ultimate Edition computer:
1. In the Windows Control Panel, open Regional and Language Options.
2. Click the Keyboard and Languages tab. In Display languages, click Install/uninstall languages…
3. Click How can I install additional languages? for information on installing additional languages (for
example Japanese or Simplified Chinese) in Windows Vista.
4. Follow the instructions for installing other display languages.
5. Follow the above steps 2 and 3 in On a Windows XP Professional or Windows Server

computer.
Using IBM SPSS Data Collection Base Professional to develop interviews

This section describes the features of the IBM® SPSS® Data Collection Base Professional
integrated development environment (IDE) that can help you with the development and testing of
interviews that will be activated in version 6.0.1 of IBM® SPSS® Data Collection Interviewer
Server. Note that many of the features described are only accessible after you have installed the
Base Professional Interview Option.
The IBM® SPSS® Data Collection Developer Library also includes a detailed description of
the syntax that is used for interview scripting, and a tutorial that demonstrates how to write an
interview script. For more information, see the topic Interview Scripting on p. 503.
Which file type should I use?
You create interview scripts as .mdd files. This is the standard file type used by IBM® SPSS®
Data Collection products to store metadata (that is, the questions, other variables, and routing
information for a survey). In different contexts, a .mdd file might also be known as a metadata
document file or a questionnaire definition file.
Creating an interview script (.mdd) file
E From the File menu, choose:

New > File
This opens the New File dialog box.
E From the list of available file types, select Metadata File, and click Open.
Importing metadata from other file types
You can create an interview script (.mdd) file by importing metadata from any proprietary data
format for which a read-enabled Metadata Source Component (MDSC) is available (refer to
the Available DSCs topic in the IBM® SPSS® Data Collection Developer Library for more
information.). For example, you can import metadata from a .sav file. To import metadata from a
proprietary data format, choose Import Metadata from the IBM® SPSS® Data Collection Base
Professional File menu.
55
Base Professional
You can also export the metadata in a .mdd file to any proprietary data format for which a
write-enabled MDSC is available. To export metadata, choose Export Metadata from the Base
Professional File menu.
Working with IVS files
A .ivs file contains only the script portion of an interview script (.mdd) file. Unlike a .mdd file, a
.ivs file contains only plain text and can therefore be opened and edited in a text editor such as
Notepad. You might want to create .ivs files so that you can store them in a version management
system and easily see the differences between versions of your scripts. To create a .ivs file, open
the .mdd file in Base Professional and choose Export Metadata from the File menu. Note that
you can also use the IBM® SPSS® Data Collection Metadata Model - Compare accessory to
compare .mdd files. Refer to the MDM Compare topic in the Data Collection Developer Library
You can also import a .ivs file into Base Professional and save it as a .mdd file. To do this,
choose Import Metadata from the Base Professional File menu. However, a .ivs file is not a
replacement for a .mdd file as it contains only a subset of the information stored in a .mdd file. For
example, .ivs files do not store translations or custom properties. For that reason, do not import
a .ivs file and save it with the same name as the .mdd file that you originally exported it from,
because you will lose any additional information that was stored in the .mdd file.
If you attempt to save a .mdd file that contains syntax errors in the metadata section, Base
Professional instead saves the script portion of your interview script as a .tmp.ivs file, as these
types of errors cannot be saved in an .mdd file. The .tmp.ivs file is saved in the same location as
your .mdd file. You can recover your latest changes by importing the .tmp.ivs file into Base
Professional, but remember that the .tmp.ivs file might not contain all the information stored
in your original .mdd file.
How a metadata script is displayed in IBM SPSS Data Collection Base Professional
When you close and reopen an interview script you might find that the script in the metadata
section does not look the same as when you closed it. This is because the IBM® SPSS® Data
Collection Data Model component used to display mrScriptMetadata (which is the language used
in the metadata section) determines how the syntax of the language is displayed. This is designed
to make mrScriptMetadata easier to read, for example, by defining a single question over several
lines rather than on one long line. Other changes that you might notice are:
Defined lists (also known as shared lists) are moved to the top of the script so that they appear
before any questions that use them.
Page fields are moved to the bottom of the script so that they appear after any questions
that they reference.
A label is added to any question or category that does not have one. The value of the label
is made the same as the question or category name. This makes it easier for you to enter
your own label texts at a later date.
You can continue to amend your metadata script, or write any new interview scripts, in any
style you prefer, as the instructions that determine how the syntax is displayed are only applied
when the interview script is opened.
56
Chapter 1
Working with multiple contexts
Contexts (or “user contexts”) define different uses for metadata. When you create an interview
script (.mdd) file in IBM® SPSS® Data Collection Base Professional, Question and Analysis
contexts are added to the metadata. The Question context is intended to store texts and custom
properties that are to be used in the data collection phase of a survey, and the Analysis context is
designed for texts and properties that are to be used when analyzing the collected case data. For
example, a question text in the Question context might say “What is your name?”, whereas the
text for the same question in the Analysis context might just say “Participant’s name”.
When you create an interview script file, Base Professional makes the Question context the
default (or “base”) context. Therefore, when you add question and category labels to the metadata
section of a new interview script, you are actually defining these texts in the Question context.
To define labels and custom properties in other contexts, select Contexts from the Base
Professional View menu, and select the context or contexts that you want to view. For each
context that you choose, Base Professional adds an “area-code” definition (which defines a
combination of language, context, and label type) near the top of the interview script’s metadata
section, like that in the following example:
ANALYSIS lcl(en-US, Analysis, Label);
The name of the area-code, known as the “area name”, is also added to the label of every
question and category in the metadata section, as highlighted in the following example:
name "What is your name?" ANALYSIS: - text;
To set the label text in the alternative context, simply replace the dash with the text, for example:
name "What is your name?" ANALYSIS: "Participant's name" text;
To set a custom property in the alternative context, replace the dash with syntax like that in the
following example, which sets the Max property in the SAV context:
name "What is your name?" SAV: [ Max = 30 ] text;
If you want to set both a label text and a custom property in an alternative context, or you want
to set label texts and custom properties in multiple alternative contexts, make sure that you add the
area name before every label text or custom property. For example:
name "What is your name?"
ANALYSIS: "Participant's name"
SAV: "Name"
SAV: [ Max = 30 ]
text;
To remove an existing text or custom property from an alternative context, replace the text
string (including the quotation marks) or property setting (including the brackets) with a dash, but
do not delete the area name or the colon that comes after it. To hide a context, select Contexts from
the Base Professional View menu, and cancel the selection for that context.
Note: The Contexts menu option can be used only to view or hide contexts that are already present
in the interview script file. To add or remove contexts, see Working with multiple languages.
57
Base Professional
Working with multiple languages
Interview script (.mdd) files can store texts in different languages. For example, your interview
script might contain Spanish and Japanese translations of the question text “What is your name?”.
In IBM® SPSS® Data Collection Base Professional, you can use the MDM Label Manager
to add languages to an interview script file. You can also use MDM Label Manager to remove
languages. To start MDM Label Manager, open a .mdd file in Base Professional and then choose
Manage Languages and Labels from the Base Professional Tools menu. For more information
about MDM Label Manager, see the Configuring Languages topic in the IBM® SPSS® Data
Collection Developer Library.
Once you have added a language to your interview script, you can use the Data Collection
Translation Utility (ms-its:mrTranslate.chm::/mrtranslate_overview.htm)Data Collection
Translation Utility to translate the question texts.
Note: You can also use the MDM Label Manager to add contexts to an interview script file, or
remove contexts. For more information about contexts, see Working with multiple contexts.
Adding a routing context
By default, each new interview script is created with a single routing context called Web, which is
intended to be used for an Internet or intranet-based survey. If your interview will be used for
more than one type of survey, you can create additional routing contexts by choosing Add Routing
Context from the Tools menu. Make sure that you specify a name for your routing context in the
Add Routing Context dialog box, as routing contexts cannot be renamed.
For example, you might want your interview to also be used for a phone-based survey or
a paper-based survey. If so, you should add routing contexts called CATI and Paper to your
interview script.
If you don’t want your script to include the Web routing context, delete that routing context
before you add any code to its routing section and create a new routing context with the name
that you want.
Deleting a routing context
When you delete a routing context, any code in the routing section will be lost, so copy the code
elsewhere if you want to keep it. Then follow these steps:
E In the Edit pane, click on the tab of the routing context that you want to delete.
E From the Tools menu, choose Remove Routing Context.
Amending the Paper routing context
If you used other IBM® SPSS® Data Collection authoring tools to create your interview script,
the script might already contain a read-only routing context called Paper. Although you cannot
change this routing context, you can copy its code into a new routing context and amend the code
there. If you do this, you will need to change the activation options when you activate your
interview script so that the interview will use your new routing context. For more information, see
the topic Activating an interview on p. 87.
58
Chapter 1
Viewing and navigating an interview script
By default, IBM® SPSS® Data Collection Base Professional displays an interview script (.mdd)
file’s metadata and routing sections as separate tabs in the Edit pane. However, if you want to
view the metadata section and one of the routing sections at the same time (that is, as two halves
of the Edit pane), you can do so by changing the value of Base Professional’s View Metadata
and Routing option. Note that you will still need to use the tabs at the bottom of the Edit pane
to select different routing contexts.
If you use Base Professional’s find and replace features, they will apply to the section (metadata
or routing) that has focus.
Navigating an interview script
The following aids to navigation are available when you open an interview script in Base
Professional:
To: Do:
Switch between the metadata and routing sections Press Ctrl+PageUp or Ctrl+PageDown.
using the keyboard.
Find a question in the metadata section. Right-click on the question in the Fields folder of
the attached metadata viewer and on the shortcut
menu choose Goto Question. Note that this also
highlights the same question in the routing section.
Alternatively, with the routing section visible,
right-click on the name of the question in the
routing section and on the shortcut menu choose
Goto Definition.
Find a question in the routing section. Right-click on the question in the Fields folder of
the attached metadata viewer and on the shortcut
menu choose Goto Question. Note that this also
highlights the same question in the metadata section.
Using the interview metadata viewer
By default, each interview script opens in IBM® SPSS® Data Collection Base Professional with a
Metadata Model (MDM) metadata viewer attached on the right-hand edge of the Edit pane. The
metadata viewer can be useful when you are writing and debugging your interview script. For
example, you can use the Copy as Ask shortcut menu option to generate mrScriptBasic code to ask
some or all of the questions defined in the metadata section of your script. You can then paste
this code into the routing section of the script.
The metadata viewer displays the metadata only for the interview script that it is attached to
and cannot be used to display any other metadata document. If you need to view another metadata
document, you can either use Base Professional’s independent metadata viewer (in the Base
Professional Metadata pane), or open the other metadata document from the File menu.
Apart from adding a data source and changing the current data source, the metadata viewers
in Base Professional cannot be used to make permanent changes to the metadata. If you need to
make permanent changes, use MDM Explorer. Refer to the MDM Explorer topic in the IBM®
SPSS® Data Collection Developer Library for more information.
59
Base Professional
If you do not want a metadata viewer to open automatically whenever you open an interview
script, change the setting of Base Professional’s Initially Show Metadata View option. If an open
interview script does not have a metadata viewer attached, you can open one by right-clicking in
the Edit pane and from the shortcut menu choosing Show Metadata.
Toolbar buttons
The following table lists the toolbar buttons in the metadata viewer.
Button Description
Show or hide the Properties Pane.
View Allows you to show or hide the various types of

objects that the metadata viewer can display.
Shortcut menu options
The following table describes all the shortcut menu options that are available when you right-click
in a metadata viewer. Note that these options are also available in the independent metadata
viewer in Base Professional’s Metadata pane.
Shortcut Menu Option Description
Change Language If your metadata document contains multiple
languages, you can choose another language.
Change Version If your metadata document contains multiple
versions, you can choose another version.
Goto Question If you are viewing the metadata section of
your interview script, you can quickly locate
the mrScriptMetadata code for any question.
Right-click on the question name in the Fields
folder, and choose this option. This option is useful
when working on large scripts.
Copy Node Copies to the Windows clipboard all the object and
folder names under a folder (node). For example,
if you right-click on the Fields folder and choose
this option, the clipboard will contain a list of all
the question names.
Copy as Select Statement Copies to the Windows clipboard the template
code for a mrScriptBasicSelect Case statement.
The object or folder name that you right-clicked
will become the expression that the Select Case
statement will test. If you choose this option for the
Categories folder of a categorical question, each
category name becomes a separate Case clause. You
can then paste the code into the routing section of
your interview script.
Copy as Ask Copies to the Windows clipboard the mrScriptBasic
code to ask a question. If you selected more than
one question, the code includes individual Ask
statements for all the questions that you selected.
You can then paste the code into the routing section
of your interview script. This menu option is only
available for questions in the Fields folder.
60
Chapter 1
Copy as Show Copies to the Windows clipboard the mrScriptBasic

code to ask a question which cannot be answered.
If you selected more than one question, the code
includes individual Show statements for all the
questions that you selected. You can then paste
the code into the routing section of your interview
script. This menu option is only available for
questions in the Fields folder.
Copy as Script Copies to the Windows clipboard the
mrScriptMetadata definition of a question.
If you selected more than one question, the code
includes definitions for all the questions that you
selected. This option is useful for creating a similar
question in the metadata section of your interview
script or copying one or more questions to another
script. This menu option is only available for
questions in the Fields folder.
Add Datasource Opens the Data Link Properties dialog box, which
you can use to add a data source to the interview
script. The data source added automatically
becomes the current (default) data source for the
interview script. Data sources are used to store
case data when you run your script. For more
information about creating case data and how to use
the Data Link Properties dialog box, see Creating
case data.
Change Datasource If your interview script has more than one data
source, you can choose another data source to be
the current (default) data source. Data sources are
used to store case data when you run your script.
For more information, see the topic Creating case
data on p. 78.
Testing an interview
You can test your interview script in three different ways:

Using the Debug option. The script will pause when it reaches the first question in the current
routing context. When you answer the first question, the script will then pause at the next
question, and so on. Use this option to test the appearance of the interview, and to interact
with the interview in a web browser. See below for details of how to use this option.
Using the Single Step option. The script will pause on the first line of code in the current routing
context, and you can then continue to single step through the rest of the code. This option is
useful if your routing section contains mrScriptBasic statements such as If and Select and you
want to be able to follow the flow of your code. See below for details of how to use this option.
Using the Auto Answer option. IBM® SPSS® Data Collection Base Professional will run the
script and automatically generate random answers to the questions in the current routing
context. For more information on using this option, see Running an interview automatically.
61
Base Professional
Selecting a Web browser
By default, Base Professional will display the interview questions in the Browser pane. To display
the interview in an external web browser, change the setting of Base Professional’s Use Built-in
Browser option.
At present, the only external browser that is supported by Base Professional is Microsoft
Internet Explorer. Future versions of Base Professional might include support for other browsers.
Testing your interview using the Debug option
1. In the Edit pane, click on the tab of the routing context that you want to run. You can skip this step
if your interview script has only one routing context.
2. From the Debug menu, choose Start. Alternatively, press F5.

Note: You can also run an interview by choosing Start Without Debugging from the Base
Professional Debug menu or pressing Ctrl+F5. The difference between the two methods is that the
“Start” (F5) option will stop execution if it encounters a breakpoint in the current routing context.
3. To reveal the Browser pane, click on the Browser pane tab or press Alt+9 twice. If you have
chosen to use an external browser, a browser window will open automatically.
4. As each question appears, you can choose to answer the question and click the Next button on the
browser page, or press F5 to let Auto Answer generate a random answer to the question. If you are
using an external browser, you must switch back to Base Professional before pressing F5.
5. To stop the interview at any time, click the Stop button on the browser page or press Shift+F5. If
you are using an external browser, be aware that closing the browser window while an interview is
running does not stop the interview.
Testing your interview using the Single Step option
1. In the Edit pane, click on the tab of the routing context that you want to step through. You can
skip this step if your interview script has only one routing context.
2. From the Debug menu, choose Single Step. Alternatively, press F10.
3. As the script pauses on each line of code, press F10 to execute that line and continue to the
next line.
4. To stop the script at any time, press Shift+F5.

You might find it useful to have the Locals pane visible while you are stepping through your code
so that you can see the current values of all the variables in your routing context.
Running an interview automatically
You can use the Auto Answer feature of IBM® SPSS® Data Collection Base Professional to
generate random answers to the questions in the current routing context.
62
Chapter 1
The Auto Answer dialog box provides options that control the automatic generation of
answers when you test questionnaires. For more information, see the topic Auto Answer
dialog box on p. 66.
After running an interview using Auto Answer, details of the questions and answers are listed
in the Answer Log pane. You can save these details to a data source. For more information,
see the topic Saving auto answer data to a data source on p. 67.
How Auto Answer works
Base Professional will choose a valid answer for each question based on the definition of the
question in the metadata section of your interview script. For example, if you have specified a
valid range of 10 to 20 for a numeric question, Base Professional will randomly choose a number
from within that range. If no valid range has been specified, Base Professional will choose any
valid value for the type of question.
Text questions are treated slightly differently. Base Professional will create an answer
consisting of part or all of a standard phrase, which is repeated as many times as required to fill the
answer. If the length of the text question is specified (or implied) as a range, the length of the
answer will be any value within that range. If a fixed length has been specified, the length of the
answer will be that value.
If a non-categorical question includes factors, one of the factor values will be chosen at random.
If any type of question includes special responses such as Don’t Know and Not Answered, Base
Professional may choose one of those responses as an answer.
Note that in the following situations, Base Professional might generate an invalid answer:
When a question contains a validation expression, because expressions are ignored.
When a question contains a range expression that consists of two or more ranges, for example
10..20, 40..50. Only the lowest and highest values in the expression are observed, so that in this
example Base Professional will generate any answer between 10 and 50.
In these situations, you might want to specify hints to reduce the range of answers that Base
Professional can choose from. See “Using Hints” below for more information.
Because Base Professional is unable to generate a year value that begins with a 0, it will never
choose an answer earlier than 01-Jan-1000, even if the specified or implied range for a date
question includes earlier dates. In addition, if the range expression for a date question specifies a
maximum date earlier than 01-Jan-1000, an invalid answer will be generated.
Running Auto Answer
Each time that you run Auto Answer, you can specify the following options:
The number of times that the interview will be run in succession.
The maximum number of attempts that Base Professional can have at generating a valid answer
to a question. If that limit is exceeded, Auto Answer stops and displays an error message.
Whether Base Professional should refer to hints in the metadata document (.mdd) file when
answering a question.
63
Base Professional
You can follow the progress of Auto Answer using the Auto Answer pane. Initially, this
displays a list of all of the questions defined in the metadata section of your interview script. As
Auto Answer progresses, questions that have been answered are highlighted in blue, and a number
alongside each question shows the number of times that it has been answered.
The answers that Base Professional has generated are displayed in the Output pane. If you
have enabled the option to create case data from the interview, you will also be able to see the
answers in the case data once Auto Answer has finished running. For more information, see the
topic Creating case data on p. 78.
1. In the Edit pane, click on the tab of the routing context that you want to run Auto Answer for. You
can skip this step if your interview script has only one routing context.
2. From the Debug menu, choose Start With Auto Answer. Alternatively, press F6.
This displays the Auto Answer dialog box.
Note: You can also run Auto Answer by choosing Auto Answer Data Generation from the Base
Professional Tools menu. The difference between the two methods is that the “Start With Auto
Answer” (F6) option will stop execution if it encounters a breakpoint in the current routing context.
3. Change any of the options in the dialog box to the settings that you want, and click Start.
4. To reveal the Auto Answer pane, click on the Auto Answer pane tab or press Alt+8 twice. To
reveal the Output pane, click on the Output pane tab or press Alt+6 twice.
5. To stop Auto Answer at any time, press Shift+F5.
Toolbar Buttons
The following table lists the toolbar buttons in the Auto Answer pane.
Button Description
Use this button to see the progress of individual
questions.
Use this button to see the overall progress of the
interview.
Do not show questions within loops.
Show questions within loops.
Using auto answer playback
When auto answer playback is enabled, questions values can be provided via a data source.
Use the Auto Answer dialog box to set options that control automatic generation of answers
when you test questionnaires.
64
Chapter 1
Response creation
Create responses from a data source. When selected, auto answer playback is enabled during
interviewing, and the auto answer questions are generated from a specified data source (the
question values are set according to what is found in the data source). This setting is not selected
by default. Random values are generated for questions that do not exist in the specified data
source. When this setting is enabled, valid Data source connection values are required.
Data source connection. Use this field to specify the data source connection string used in auto
answer playback (when the Create responses from a data source option is selected). Clicking the
Edit button displays the Data Link Properties dialog that prompts you to input the appropriate
data source information. Refer to For more information, see the topic Data Link Properties dialog
box on p. 68. for information on working with the Data Link Properties dialog.
Select table. Indicate whether HDATA or VDATA will be used for querying the data source.
Select columns. Select which data source columns will be used in the auto answer playback.
Specify where clause. Use this field to provide a valid select clause for querying the data
source.
Create responses using hints from .mdd. Select this option if you want IBM® SPSS® Data
Collection Author to refer to hints in the Advanced Properties tab when answering a question.
When the Create responses from a data source setting is enabled, the data source’s question values
take priority over random values.
Number of cases
Create the same number of interviews as specified in the source above. Select this option when you
want to create the same number of interviews as the record count in the specified data source.
When selected, the total number of interviews created by ALL threads is equal to the source’s
record count. The option is only available when the Create responses from a data source option
is selected.
Interviews to create. Enter the number of times you want the application to run the interview
and fill in random answers for each question.
Maximum attempts to answer a question. Enter the maximum number of attempts that the
application can have at generating a valid answer to a question. If that limit is exceeded, Auto
Answer stops and displays an error message.
Using hints
You can use hints to reduce the range of values that Base Professional can choose from when
generating an answer in Auto Answer.
To be able to use hints, you must be comfortable using MDM Explorer to create and amend
custom properties in your .mdd file. Note that you cannot use the metadata viewers in Base
Professional to update custom properties. Make sure that you close your interview script in
Base Professional before using MDM Explorer.
65
Base Professional
You can create hints for either Field or VariableInstance objects. Always use the Field object
unless you are creating different hints for each question in a loop. All custom properties used to
specify hints must be created in the AutoAnswer context, so check that this context exists in your
.mdd file and create it if necessary before trying to create hints.
The following table describes the custom properties that you can create.
Custom Property Name Description
AllowedCategories For categorical questions, this string property
defines a subset of categories from which Base
Professional can choose an answer. For example, if
a question’s category names are the seven days of
the week, you could set the value of this property
to monday,tuesday,saturday to specify that Base
Professional can choose the answer only from those
three categories.
When specifying the value of this property, do not
enclose the value within braces. When specifying
more than one category name, separate the category
names using commas. If the question includes
factors, specify the category names as described
above and not the factor values.
Max For numeric and date questions, this property
defines the maximum value that can be used as an
answer. For text questions, this property defines
the maximum length of the answer. For categorical
questions, this property defines the maximum
number of categories that Base Professional should
choose.
For numeric and date questions, set the data type of
this property to match the question type (either long,
double, or date). For text and categorical questions,
set the data type to long.
Min For numeric and date questions, this property
defines the minimum value that can be used as an
answer. For text questions, this property defines
the minimum length of the answer. For categorical
questions, this property defines the minimum
number of categories that Base Professional should
choose.
set the data type to long.
Value The actual value that Base Professional should
use for the answer. You can use this hint for any
type of question. If the hint is for a categorical
question, specify the category name or names
using the same method as that described above for
AllowedCategories.
set the data type to string.
Notes
66
Chapter 1
Decimal values for the Min, Max, and Value custom properties must always be specified using
a dot (.) for the separator, and dates must always be specified in the yyyy/mm/dd format.
To ensure that Auto Answer does not select any categorical responses, set the Max value to
zero (0).
For non-categorical questions, you can specify a special response such as Don’t Know as the
answer. To do this, create the Value custom property on the question and set the value of the
property to Codes. Then create a Value custom property on the Codes object for the question, and
set the value of the property to the name of the code that defines the special response.
When you run Auto Answer, you can confirm that a hint has been used by looking at the
answers in the Output pane. Note that if you specify an invalid hint for the type of question, such
as a text value for a numeric question, Base Professional will write a warning message to the
Output pane and ignore the hint. However, if the Value property specifies an invalid category or
code for a question, Auto Answer stops and an error message is displayed.
Auto Answer dialog box
Use the Auto Answer dialog box to set options that control automatic generation of answers
when you test questionnaires.
Response creation
Create responses from a data source. When selected, auto answer playback is enabled during
interviewing, and the auto answer questions are generated from a specified data source (the
question values are set according to what is found in the data source). This setting is not selected
by default. Random values are generated for questions that do not exist in the specified data
source. When this setting is enabled, valid Data source connection values are required.
Data source connection. Use this field to specify the data source connection string used in auto
answer playback (when the Create responses from a data source option is selected). Clicking the
Edit button displays the Data Link Properties dialog that prompts you to input the appropriate
data source information. Refer to For more information, see the topic Data Link Properties dialog
box on p. 68. for information on working with the Data Link Properties dialog.
Select table. Indicate whether HDATA or VDATA will be used for querying the data source.
Select columns. Select which data source columns will be used in the auto answer playback.
Specify where clause. Use this field to provide a valid select clause for querying the data
source.
Create responses using hints from .mdd. Select this option if you want IBM® SPSS® Data
Collection Author to refer to hints in the Advanced Properties tab when answering a question.
When the Create responses from a data source setting is enabled, the data source’s question values
take priority over random values.
67
Base Professional
Number of cases
Create the same number of interviews as specified in the source above. Select this option when you
want to create the same number of interviews as the record count in the specified data source.
When selected, the total number of interviews created by ALL threads is equal to the source’s
record count. The option is only available when the Create responses from a data source option
is selected.
Interviews to create. Enter the number of times you want the application to run the interview
and fill in random answers for each question.
Maximum attempts to answer a question. Enter the maximum number of attempts that the
application can have at generating a valid answer to a question. If that limit is exceeded, Auto
Answer stops and displays an error message.
Saving auto answer data to a data source
After running an interview using Auto Answer, details of the questions and answers are listed in
the Answer Log pane. You can save these details to a data source.
Adding a data source definition
The Configure Data Source dialog provides options for adding, editing, and removing data sources.
E From the menu, choose

Tools > Configure Data Sources
or press Alt+T, F.
The Configure Data Source dialog is displayed.
E Click Add… or press Alt+A. The Data Link Properties dialog displays.
E Enter the required information on each tab of the Data Link Properties dialog and click OK when
finished. For more information, see the topic Data Link Properties dialog box on p. 68.
E Click OK to exit the Configure Data Source dialog.
Selecting a different data source definition
E Select the appropriate data source from the Configure Data Source dialog’s Data Source list, then
click Set As Current or press Alt+S. The selected data source is set as the current data source.
Editing a data source definition
click Edit... or press Alt+E. The Data Link Properties dialog displays.
68
Chapter 1
Removing a data source definition
click Remove or press Alt+R. The selected data source is removed.
Saving the auto answer details to a data source
To save the results to a data source when you run Auto Answer, you must first perform the
following step after setting up your data source:

Tools > Write Data to Database
or press Alt+T, W.
Data Link Properties dialog box
The Data Link Properties dialog box has the following tabs:
Provider - provides options for selecting the appropriate OLE DB provider for the type of
data you want to access.
Connection - provides access to the Metadata Properties and Metadata Versions dialog boxes
Advanced - provides options for defining additional connection options.
All - provides options for editing the initialization properties that are available for the chosen
Provider.
Data Link Properties: Provider
You use the Provider tab in the Data Link Properties dialog box to select the provider you want
to use.
69
Base Professional
Selecting the appropriate OLE DB Provider

To connect to the IBM® SPSS® Data Collection Data Model, select IBM® SPSS® Data
Collection DM-n OLE DB Provider (where n is the version number) from the list of OLE DB
Providers.
To connect to another provider, select the appropriate entry from the list of OLE DB Providers
(for example to select a Microsoft SQL Server provider, select Microsoft OLE DB Provider for
SQL Server from the list).
Refer to the appropriate database provider documentation for information on configuring

connection strings.
Data Link Properties: Connection
You use the Connection tab in the Data Link Properties dialog box to define the name, location,
and type of the data to which you want to connect. When you select IBM® SPSS® Data
Collection DM-n OLE DB Provider (where n is the version number) on the Provider tab, an Data
Collection-specific Connection tab is displayed.
70
Chapter 1
Metadata Type. Defines the type of metadata. The drop-down list shows the types of metadata for
which you have a metadata source component (MDSC). The default options are:
None. Choose this option if you want to connect to case data only.
Data Collection Metadata Document. MR Metadata Document. Selects metadata that is in
the standard IBM® SPSS® Data Collection Data Model format, which is a questionnaire
definition (.mdd) file.
ADO Database. Selects metadata that is in an ActiveX Data Objects (ADO) data source.
Data Collection Log File. Selects metadata in a standard Data Collection log file.
Data Collection Participation Database. Selects metadata that is in a IBM® SPSS® Data
Collection Interviewer Server Administration project’s Sample and HistoryTable tables.
Data Collection Scripting File. Selects metadata that is in a mrScriptMetadata file.
In2data Database. Selects metadata that is in an In2data database (.i2d) file.
Quancept Definitions File (QDI). Selects metadata in a IBM® SPSS® Quancept™ .qdi file
using the QDI/DRS DSC.
Quancept Script File. Writes the metadata in an MDM document to a Quancept script (.qqc) file.
Quantum Specification. Writes the metadata in an MDM document to a IBM® SPSS®
Quantum™ specification.
Quanvert Database. Selects metadata that is in a IBM® SPSS® Quanvert™ database.
Routing Script File. Writes the routing section of an MDM document to a script that defines the
routing required for interviewing.
71
Base Professional
SPSS Statistics File (SAV). Selects metadata that is in an IBM® SPSS® Statistics .sav file.
Surveycraft File. Selects metadata that is in a IBM® SPSS® Surveycraft™ Validated
Questionnaire (.vq) file.
Metadata Location. The name and location of the metadata. The way you specify this depends on
the type of metadata that you selected in the previous drop-down list:
Data Collection Metadata Document. The name and location of the .mdd file.
ADO Database. The name and location of a .adoinfo file, which is an XML file that specifies the
connection string for the target data source and the name of the target table in that data source.
Data Collection Participation Database. The name and location of a Participants Report
Document (.prd) file, which is an XML file that specifies the connection string and the names
of the table and columns to be used.
Data Collection Scripting File. The name and location of the mrScriptMetadata file. Typically
these files have an .mdd or .dms filename extension.
Quancept Definitions File (QDI). The name and location of the .qdi file.
Quancept Script File. The name and location of the .qqc file.
Quantum Specification. The location of the Quantum specification files.
Routing Script File. The name and location of the routing script file.
Surveycraft File. The name and location of the .vq file.
Click Browse to select the file in the Open dialog box.

Open Metadata Read/Write. By default, the metadata is opened in read-only mode. Select this
option if you want to be able to write to it. When you open some types of data (for example, a
Quanvert database) the metadata is always opened in read-only mode.
Properties. Edit MDM Properties. Click this button to open the MetadataMDM Properties dialog
box, in which you can specify the versions, language, context, and label type to use. For more
information, see the topic Data Link Properties: Metadata Properties on p. 73.
Case Data Type. Defines the type of case data. The drop-down list shows all of the types of case
data for which you have a case data source component (CDSC). The default options are:
ADO Database. Reads case data from an ActiveX Data Objects (ADO) data source.
Delimited Text File (Excel). Writes case data in tab-delimited format to a .csv file.
Data Collection Database (MS SQL Server). Reads and writes case data in a Data Collection
relational database in SQL Server. This option can be used to read data collected using IBM®
SPSS® Data Collection Interviewer Server.
Data Collection Log File. Selects the Log DSC, which enables you to read Data Collection
log files.
72
Chapter 1
Data Collection XML Data File. Reads and writes case data in an XML file. Typically, you use
this option when you want to transfer case data to another location.
In2data Database. Reads case data from an In2data Database (.i2d ) file.
Quancept Data File (DRS). Reads case data in a Quancept.drs, .drz, or .dru file using the
QDI/DRS DSC.
Quantum Data File (DAT). Selects the Quantum DSC, which reads and writes case data in a
Quantum-format ASCII file.
Quanvert Database. Selects the Quanvert DSC, which reads data in a Quanvert database.
SPSS Statistics File (SAV). Reads and writes case data in an SPSS Statistics .sav file.
Surveycraft File. Reads case data from a Surveycraft data file.
Tip: If you have specified a Metadata Type and a Metadata Location, and the default data source
in your metadata refers to the case data that you want to connect to, you don’t need to specify
a Case Data Type or a Case Data Location.
Case Data Location. The name and location of the case data. The way you specify this depends on
the type of case data that you selected in the previous drop-down list:
ADO Database. The OLE DB connection string for the ADO data source. To build this string,
click Browse, which opens a second Data Link Properties dialog box in which you can choose
the options for your data source. For example, to connect to a Microsoft Access database or a
Microsoft Excel file, select Microsoft OLE DB Provider for ODBC Drivers in the Provider tab and
click the Build button in the Connection tab to build a connection string that uses the Machine
Data Source called “MS Access Database” or “Excel Files” as appropriate. If your data source
is a Microsoft SQL Server database that is not a Data Collection relational database, select
Microsoft OLE DB Provider for SQL Server in the Provider tab and enter the server name and
database name in the Connection tab. Then click OK to close the second Data Link Properties
dialog box and return to the Connection tab of the first Data Link Properties dialog box.
Delimited Text File (Excel). The name and location of the .csv file.
Data Collection Database (MS SQL Server). This must be an OLE DB connection string.
Data Collection XML Data File. The name and location of the .xml file.
Quancept Data File (DRS). The name and location of the .drs, .drz, or .dru file.
Quantum Data File (DAT). The name and location of the .dat file. If a .dau file is created, it will
have the same name, but with the file name extension of .dau.
Surveycraft File. The name and location of the Surveycraft Validated Questionnaire (.vq) file.
The Surveycraft .qdt file, which contains the actual case data, must be in the same folder
as the .vq file.
Click Browse if you want to browse to the location of the case data in a dialog box.
73
Base Professional
Case Data Project. This text box should be blank, unless you are connecting to one of the
following case data types:
ADO Database. If you are connecting to a Microsoft SQL Server database (that is not a Data
Collection relational database) or a Microsoft Access database, enter the name of the database
table that you want to use. If you are connecting to a Microsoft Excel file, enter the name of
the worksheet that you want to use, for example, Sheet1. Depending on the version of Excel
installed, you may have to add a dollar sign ($) after the worksheet name for the connection to
be successful, for example, Sheet1$.
Data Collection Database (MS SQL Server). Enter the name of the project that you want to use.
Test Connection. Click this button to test the connection and verify whether you have entered all
information correctly.
Data Link Properties: Metadata Properties
You use the Metadata Properties dialog box to define the version, language, context, and label type
that you want to use when you connect to a questionnaire definition (.mdd) file (also known as
IBM® SPSS® Data Collection Metadata Document file). You open this dialog box by clicking
the Properties button in the Metadata section on the Connection tab in the Data Link Properties
dialog box.
Version. Select the version or versions that you want to use. Questionnaire definition (.mdd) files
typically contain , which record any changes to the content of the questionnaire. Typically, when
the questionnaire changes (for example, a question or category is added or deleted) a new version
is created and when the changes are complete, the version is locked. The drop-down list box
displays all of the available versions plus three additional options:
All versions. Select this option if you want to use a combination (superset) of all of the
available versions. (This is sometimes called a superversion). When there is a conflict
between the versions, the most recent versions generally take precedence over the older
versions. For example, if a category label differs in any of the versions, the text in the latest
version will be used. However the order of questions and categories is always taken from the
most recent version and there is special handling of changes to loop definition ranges and the
minimum and maximum values of variables, similar to that described for the IBM® SPSS®
Data Collection Metadata Model Version Utility in . Use the Multiple Versions option if
you want to change the order of precedence.
74
Chapter 1
Multiple versions. Select this option if you want to use a combination (superset) of two or
more specific versions. For more information, see the topic Data Link Properties: Metadata
Versions on p. 74.
Latest version. Select this option if you want to use the most recent version.
Using a combination of some or all of the versions is useful when, for example, you want to export
case data for more than one version and there have been changes to the variable and category
definitions that mean that case data collected with one version is not valid in another version.
Selecting all of the versions for which you want to export the case data, means that generally
you can export the case data collected with the different versions at the same time without
encountering validity errors due to the differences between the versions. However, depending on
the version changes, some validity errors may still be encountered.
Language. Languages. Select the language you want to use. You can change the language only if
there is more than one language defined.
Context. Contexts. Select the user context you want to use. The user context controls which texts
are displayed. For example, select Question to display question texts, or Analysis to display shorter
texts suitable for displaying when analyzing the data.
LabelType. LabelTypes. Select the label type you want to use. You should generally select the
Label option.
Data Link Properties: Metadata Versions
You use the Metadata Versions dialog box when you want to select two or more versions of the
questionnaire definition (.mdd) file. You open this dialog box by selecting Multiple Versions in the
Version drop-down list box in the Metadata Properties dialog box.
75
Base Professional
Versions. The Metadata Versions dialog box lists all of the versions that are available. Click Select
All to select all of the versions. Click Clear All to deselect all of the versions and then select the
versions you want individually. For each version, the following information is shown:
Name. Version. The version name. Version names are made up of a combination of the major
version and minor version numbers in the form Major#:Minor#, where Major# is the number
of the major version and Minor# is the number of the minor version. Changes in the major
version number indicate that the structure of the case data has changed (for example, variables
or categories have been added or deleted) whereas changes in the minor version number
indicate that the changes affect the metadata only (for example, a question text has been
changed). Version names are created automatically when a version is locked. A version that
has not been locked is always called LATEST.
Created by. The ID of the user who created the version.
Created Date. This shows the date and time at which the version was locked.
Description. When present, this is a text that gives information about the version.
The order in which you select the versions controls the order of precedence that will generally be
used when there is a conflict between the versions. For example, if a category label differs in the
versions you select, the text in the version with the higher precedence will be used. However the
order of questions and categories is always taken from the most recent version and there is special
handling of changes to loop definition ranges and the minimum and maximum values of variables,
similar to that described for the IBM® SPSS® Data Collection Metadata Model Version Utility in
If you want the most recent version to take precedence, start selecting the versions at the top
and work down the list. If you want the oldest version to take precedence, start at the bottom
and work up the list.
Note that you can select multiple versions by pressing Ctrl or Shift while you click.
Tip. You can select individual or multiple versions by pressing Ctrl or Shift while you click,
provided the mouse is in the Description or Date/Time Locked column. You can then click in the
Version column to select or deselect the check boxes for all of the versions that you have selected.
You may find this useful when you are working in a file that has many versions.
Selected Versions. Displays an expression that represents the selection you have chosen. You can
optionally select the versions you want to use by typing an expression directly into this text box.
The order of precedence is taken from the order in which versions are specified, with the rightmost
versions taking precedence over the leftmost.
Syntax Description
.. Specifies all versions
v1, v2, v3, v4 Specifies individual versions
v1..v2 Specifies an inclusive range of versions
^v1..v2 Excludes a range of versions
Specifies the most recent version.
76
Chapter 1
You can specify a combination of individual versions, and ranges to include or exclude. For
example, the following specifies version 3:2 and all versions from 4:5 to 7:3 with the exception
of versions 7 through 7:2:
3:2, 4:5..7:3, ^7..7:2
Data Link Properties: Advanced
You use the Advanced tab in the Data Link Properties dialog box to define additional connection
options. When you select IBM® SPSS® Data Collection DM-n OLE DB Provider (where n is the
version number) on the Provider tab, an Data Collection-specific Advanced tab is displayed.
Metadata Source when Location is Different. If existing Data Source has a different location. The
Data Model uses the DataSource object to store details about case data that is associated with an
MDM Document (.mdd file). This option specifies what should happen if there is no DataSource
object in the MDM Document with the same case data type whose location matches the case
data location specified on the Connection tab:
Use the Data Source (except for location). This is the default behavior. Select this option if
you want to use the first DataSource object of the same type that is encountered and do not
want to store the new case data location in it.
Use the Data Source and store the new location. Select this option if you want to use the first
DataSource object of the same type that is encountered and store the new case data location
in it.
77
Base Professional
Create a new Data Source. Select this option if you want to create a new DataSource object.
This is useful when you do not want to use the same variable names when exporting to SPSS
.sav as used previously.
Raise an Error. Select this option if you want the connection to fail.
For more information, see the IBM® SPSS® Data Collection Developer Library.
Categorical variables. Specifies whether to display the categories of categorical variables as

Preserve source column definitions. Select this option if you want the native objects in the
underlying database to be exposed directly as Data Model variables without any interpretation.
For example, if you select this option, a multiple dichotomy set in a .sav file would be represented
as several long or text variables instead of one categorical variable.
Reading categorical data. Specifies whether to display the categories of categorical variables as
Writing data. Specifies whether the CDSC deletes the output data, if it exists, before writing
new data. The options are as follows:
Append to existing data. This is the default behavior. Select this option if you want to append
to the existing data if it exists.
Replace existing data. Select this option if you want to delete the existing data and schema.
This will allow data to be created with a different schema.
Replace existing data but preserve schema. Select this option if you want to delete the existing
data, but preserve the existing schema if possible. Note that for some CDSCs, such as SPSS
SAV and Delimited Text, the schema will not be preserved because deleting the data results
in the loss of the schema.
Validation. Perform data validation. Select if you want case data to be validated before it is written.
Deselect if you do not want any validity checks to be performed on case data before it is written.
Allow Dirty. Allow dirty data. Select if you have chosen data validation, and you want to run in
dirty mode. This means that data is accepted even if it has some inconsistencies. Deselect this
option to run in clean mode, which means that data is rejected if it contains any inconsistencies
(for example, if more than one response has been selected in answer to a single response question).
The validation that is performed varies according to the CDSC that is selected.
User name. If required, enter your User ID.
Password. If required, enter your password.
Data Link Properties: All
You can use the All tab in the Data Link Properties dialog box to edit all of the initialization
properties that are available for the Provider. However, generally you define the values for the
properties on the Connection and Advanced tabs.
78
Chapter 1
The All tab lists all of the initialization properties and you can edit the values by selecting
a property and clicking Edit Value.
For detailed information about the connection properties, see Connection Properties in the IBM®
SPSS® Data Collection Data Model section of the DDL.
Creating case data
When you run or debug an interview, or run the interview using Auto Answer, you can choose
to write the answers, also known as the Case Data, to an output format supported by the IBM®
SPSS® Data Collection Data Model. At present, the formats you can write to are IBM SPSS
Data Collection Data File, IBM® SPSS® Statistics SAV file, IBM® SPSS® Data Collection
RDB database, and Data Collection XML file.
You define a target location for your case data by adding a data source to your interview script
(.mdd) file. Your script can contain more than one data source, so that you can easily change from
using a IBM SPSS Data Collection Data File to an RDB database, for example.
Note: You can choose to mark your case data as Live or Test data. In the routing section of your
interview script, you can use the IsTest property of the IInterviewInfo object to make your code
execution conditional on whether you have marked the data as live or test data.
Creating case data
E Open the Tools menu, and make sure that Write To Database is selected.
79
Base Professional
E If you have not already configured at least one data source, the Configure Data Sources dialog
displays, allowing to add new or edit existing data sources. If you have already defined a data
source, skip the next six steps.
E Click Add... to define a new data source.
The Data Link Properties dialog will appear, as shown below.
E In the Case Data Type drop-down list, select IBM SPSS Data Collection Data File, SPSS Statistics
File (SAV), Data Collection Database (MS SQL Server), or Data Collection XML Data File.
E Click on the Browse button to the right of the Case Data Location edit box.
E If you selected “IBM SPSS Data Collection Data File”, “SPSS Statistics File (SAV)” or “Data
Collection XML Data File” as your case data source, an Open File dialog appears. Enter the name
and location of a new or existing .ddf, .sav, or .xml file, as appropriate, and click Open.
E If you selected “Data Collection Database (MS SQL Server)” as your case data source, enter
the server name, database name, and any other information that is required for your server
environment. Click OK.
E In the Data Link Properties dialog, click OK.
E From the Tools menu, choose Options, and change the Collect Live Data option to True or False as
required.
E Start your interview using F5 (debug), F10 (single step), or F6 (Auto Answer).
The information about your case data source will be saved in your interview script (.mdd) file, and
you will not be prompted for that information again.
80
Chapter 1
The interview will now run and collect the case data in the data source that you specified.
Configuring data sources
After running an interview using Auto Answer, details of the questions and answers are listed in
the Answer Log pane. You can save these details to a data source.
Note: When working with questionnaire files that are opened from an IBM® SPSS® Data
Collection Interviewer Server, auto answer always generates a <project name>.ddf file in the
User_Data directory (located in the user project directory). A data source definition is not
provided.
Adding a data source definition
You might want to add another case data source to your interview script if, for example, you have
been using a IBM SPSS Data Collection Data File to develop your script and you now want to
change to using an RDB database. You might also need to use this option if your script was
created outside of IBM® SPSS® Data Collection Base Professional and the default data source is
not a IBM SPSS Data Collection Data File, an SPSS Statistics SAV file, a Data Collection XML
file, or an RDB database.
The Configure Data Source dialog provides options for adding, editing, and removing data sources.

Tools > Auto Answer > Configure Data Source
This opens the Data Link Properties dialog.
E In the Case Data Type drop-down list, select IBM SPSS Data Collection Data File, SPSS Statistics
File (SAV), Data Collection Database (MS SQL Server), or Data Collection XML Data File. Note that
your interview script can contain only one data source of each case data type, so select only a case
data type that your script does not already have.
E Click on the Browse button to the right of the Case Data Location edit box.
E If you selected IBM SPSS Data Collection Data File, SPSS Statistics File (SAV), or Data Collection
XML Data File as your case data source, an Open File dialog appears. Enter the name and location
of a new or existing .ddf, .sav, or .xml file, as appropriate, and click Open.
E If you selected Data Collection Database (MS SQL Server) as your case data source, enter the server
name, database name, and any other information that is required for your server environment.
Click OK.
E In the Data Link Properties dialog, click OK.

81
Base Professional
Selecting a different data source definition
click Set As Current or press Alt+S. The selected data source is set as the current data source.
Editing a data source definition
click Edit... or press Alt+E. The Data Link Properties dialog displays.
Removing a data source definition
click Remove or press Alt+R. The selected data source is removed.
Accessing sample management data
If your interview will use Sample Management when activated in IBM® SPSS® Data Collection
Interviewer Server, and the routing section of your interview script (.mdd) file accesses sample
data, you can test your interview script in IBM® SPSS® Data Collection Base Professional
before activating it.
In Base Professional, Sample Management data is stored in a Sample User XML (.xsu) file,
which contains a single sample record with one or more fields. The records and fields are defined
using XML syntax. Each field has a name, a type and a value. Note that you cannot have more
than one sample record in a .xsu file.
The following sample record is from a file called DefaultSample.xsu, which by default can be
found in the [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base Professional\Interview
folder. The sample record contains three fields called ID, UserName and Password.
<SampleRecord ID="ID1">
<SampleFields>
<SampleField>
<name>ID</name>
<type>8</type>
<value>ID1</value>
</SampleField>
<SampleField>
<name>UserName</name>
<type>8</type>
<value>Name1</value>
</SampleField>
82
Chapter 1
<SampleField>
<name>Password</name>
<type>8</type>
<value>Password1</value>
</SampleField>
</SampleFields>
</SampleRecord>
When you create your own sample fields, you must give each field a type. A list of the valid
values for the <type> element is shown in the following table. Make sure that the types in your
Sample User XML file match the equivalent SQL field types for the sample table (sometimes
known as the participants table) that your interview will use after activation.
Value of <type> Equivalent SQL Field Type
2 Smallint
3 Int
7 Datetime
8 Char, Text, Ntext, or Nvarchar
11 Bit
For an example of the code you need to write to access the data in the sample record, see
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Sample Management -
Dimensions script\Basic\Basic.mdd, which is intended to be used with DefaultSample.xsu. The
relevant parts of the script are shown below. When the script is run, the browser should display
the message “Welcome to the Drinks Survey Name1”, as Name1 is the value of the UserName
field in DefaultSample.xsu.
Metadata(en-US, Question, label)
...
Welcome "Welcome to the Drinks survey {UserName}." info;
...
End Metadata
Routing(Web)
' Get the UserName from the sample record

Welcome.Label.Inserts["UserName"].Text = IOM.SampleRecord.Item["UserName"]
Welcome.Show()
...
End Routing
Using sample management
1. Create a .xsu file and add a sample record. You can use DefaultSample.xsu as a template for your
own sample record.
83
Base Professional
2. From the Tools menu, choose Options and change the Sample Management Record option to the
name and location of your .xsu file.
3. Run your interview script. The script should now be able to access the sample data in your .xsu file.
Sample scripts
For an example of using Sample Management in Base Professional, open

[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\CATI\MultiMode1\MultiMode1.mdd.
The script demonstrates how code execution can be made conditional on the content of the sample
data, and is intended to be used with either CATIMode.xsu or WebMode.xsu, which are both
located in the same folder as the script. The file MultiMode1ReadMe.htm, which is also in the
same folder as the script, contains more information about using the script.
Further examples of using Sample Management can be found in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Sample Management -
IBM® SPSS® Data Collection script folder.
Testing quotas
If your interview will use quota control, you can use IBM® SPSS® Data Collection Base
Professional to test your quota categories and targets before you activate your interview in IBM®
SPSS® Data Collection Interviewer Server. Note that Base Professional can only test a quota that
is based on the answers to questions in your interview script (.mdd) file. Quotas based on sample
management data are ignored by Base Professional.
Overview
You define quotas by creating a quota definition (.mqd) file. If you have already created a quota
definition file for your Interviewer Server project, you might want to use that file for testing in
Base Professional. Alternatively, you can create a new file from within Base Professional.
The quota targets and counts are stored in a quota database. If you have already activated your
interview and you selected the activation option to use quotas, a suitable quota database might
already exist on your Interviewer Server cluster. Alternatively, Base Professional can create a
quota database for you using any edition of Microsoft SQL Server 2005, including the free SQL
Server 2005 Express Edition (http://www.microsoft.com/sql/editions/express/default.mspx) and
Microsoft SQL Server Desktop Engine (MSDE).
To test a quota, you specify the quota database name and location in the Base Professional
options, and then select Debug Quotas from the Base Professional Tools menu. This synchronizes
the categories and targets in the quota definition file with the quota database. When you now test
your interview, Base Professional increments the counts in the quota database. To check the quota
counts, you must stop your interview script and run an mrScriptBasic file to produce a report.
The rest of this topic describes the following procedures in more detail:
Creating or updating a Quota Definition file
Testing a quota
Checking the quota counts
Resetting the quota counts
84
Chapter 1
Changing the quota targets

Accessing a quota from an interview script
Creating or updating a Quota Definition file
E In Base Professional, create or open an interview script (.mdd) file.
E From the Base Professional menu, choose:

Tools > Quota
This opens the IBM® SPSS® Data Collection Quota Setup Window.
E In the Quota Setup Window, define the quota categories and targets that you want to use for your
interview. If the quota definition file already existed, you can amend the existing categories
and targets.
For more information about using the Quota Setup Window and defining quotas, see Quota Setup
(UserGuide.chm::/Intug-features.htm)search for the topic “Quota Setup” in the Interviewer Server
User’s Guide. Note that when testing a quota, Base Professional ignores any quotas that are
based on sample management data.
E In the Quota Setup Window, save the quota definition (.mqd) file with the same name (except for
the extension) and to the same location as your interview script (.mdd) file.
Testing a quota

Tools > Options
This opens the Base Professional Options dialog box.
E Change the “Debug Quotas: Data Source Name” option to the name of the SQL Server instance
that contains an existing quota database that you want to use. Alternatively, specify the name of
the SQL Server instance in which you want Base Professional to create a new quota database.
If the SQL Server instance is the default instance on the computer in which SQL Server is
installed, set the value of “Debug Quotas: Data Source Name” to the name of the computer.
If the SQL Server instance is a named instance, the format of the “Debug Quotas: Data
Source Name” option must be <computer_name>\<instance_name>, for example,
MyComputer\MyNamedInstance01.
Note: If you have installed SQL Server 2005 Express Edition to use for testing quotas, be aware
that the default installation of SQL Server 2005 Express Edition creates a named instance called
SQLExpress rather than a default instance.
E Change the “Debug Quotas: Database Name” option to the name of the existing or new quota
database.
E Click OK to close the Base Professional Options dialog box.
E In Base Professional, open your interview script (.mdd) file if it is not already open.
85
Base Professional

Tools > Debug Quotas
If the quota database does not already exist, Base Professional creates it. There might be a delay
while this happens. The Debug Quotas menu option should now be selected.
When you next test your interview script, Base Professional will maintain completed and pending
counts in the quota database. If the database already existed, Base Professional will increment
the existing counts.
Checking the quota counts
E If your interview script is running in Base Professional, complete or stop the interview.
E In Base Professional, open the mrScriptBasic script called

DebugQuotaReport.mrs, which by default is installed in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\General\mrScriptBasic folder.
E Edit the mrScriptBasic script to change the values of the following parameters:
Parameter Name Value

PROJECT_NAME The name of your interview script file, without the
.mdd extension.
DEBUGQUOTA_DATASOURCE The value you assigned to “Debug Quotas: Data
Source Name” in Base Professional Options. See
“To Test a Quota” above for more information about
this option.
DEBUGQUOTA_DATABASE The value you assigned to “Debug Quotas: Database
Name” in Base Professional Options. See “To Test
a Quota” above for more information about this
option.
E Run the mrScriptBasic script.
After a brief pause, an Excel worksheet opens. For each quota category, the worksheet shows the
count of completed and pending interviews and the target value.
Resetting the quota counts
E Make sure that the Base Professional options refer to the quota database that you want to reset.
See “To Test a Quota” above for more information about these options.
E In Base Professional, open your interview script (.mdd) file if it is not already open, and select
Debug Quotas from the Tools menu.
86
Chapter 1

Tools > Reset Debug Quota Counters
After a brief pause, a message confirms that all the counts in the quota database have been set to
zero.
Changing the quota targets
E Make sure that the Base Professional options refer to the quota database whose targets you want to
change. See “To Test a Quota” above for more information about these options.
E If the Debug Quotas menu option (in the Tools menu) is already selected, clear the selection.
E Follow the steps in “To Create or Update a Quota Definition File” above to open the quota
definition (.mqd) file.
E Amend the targets as required, then save and close the quota definition file.

Tools > Debug Quotas
After a brief pause, the new targets are written to the quota database.
Accessing a quota from an interview script
You access the quota from the routing section of your interview script (.mdd) file by using the
Quota Object Model. For example, the following mrScriptBasic code adds the current respondent
to the relevant pending count in the quota group called “Gender”:
Dim quota_pend_result
Gender.Ask()
' Make sure that the IBM SPSS Data Collection Base Professional Debug Quotas menu option has been selected
If Not IsNullObject(QuotaEngine) Then
' Increment the pending count

quota_pend_result = QuotaEngine.QuotaGroups["Gender"].Pend()
End If
The IBM® SPSS® Data Collection Developer Library contains several example interview script
(.mdd) files that demonstrate the use of quotas. By default, these files are installed in folder
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Quotas.
Comparing interview scripts
You can use IBM® SPSS® Data Collection Base Professional to do the following:
Compare different metadata versions of your interview script (.mdd) file.
Compare your interview script file with another interview script file.
87
Base Professional
A IBM® SPSS® Data Collection Data Model accessory called IBM® SPSS® Data Collection
Metadata Model - Compare is used to carry out the comparison. To start Metadata Model
- Compare, open a .mdd file in Base Professional and then choose Compare from the Base
Professional Tools menu. When the Metadata Model - Compare window opens, the “Original
file” settings will automatically have been set to refer to your .mdd file. For more information
about setting up and using Metadata Model - Compare, see the MDM Compare topic in the IBM®
SPSS® Data Collection Developer Library.
A metadata version is added to your interview script file each time that you activate it. You can
also add metadata versions manually to your interview script file by using MDM Explorer. It is
not possible to add metadata versions manually in Base Professional.
Validating an interview template file
If you have created templates to control the appearance of your interview, you can use the
HTML Tidy utility in IBM® SPSS® Data Collection Base Professional to ensure that the HTML
statements in your interview templates are valid.
To work successfully, interview template files must contain XHTML, which is sometimes
referred to as “well formed” HTML and has strict rules governing the syntax of HTML statements.
However, you can write your interview templates in standard HTML and then use HTML Tidy to
convert them to XHTML.
Using HTML Tidy
1. Open your interview template file in Base Professional.
2. From the Tools menu, choose HTML Tidy.
3. Select Current File.
4. Click OK.
Activating an interview
When you have finished developing and testing your interview, you can activate it so that it can
be used for interviewing in version 6.0.1 of IBM® SPSS® Data Collection Interviewer Server.
Activating an interview
E From the Tools menu, choose Activate.
This opens the activate Login dialog.
E Complete the fields in the Login dialog as follows, depending on whether you are connected to
the same local network as the Interviewer Server cluster and have access to the FMRoot shared
folder on the primary DPM server:
If you are connected to the local network. In “Destination Server or IBM® SPSS® Data
Collection Interviewer Server Administration URL”, enter the name of the primary DPM
server in the target Interviewer Server cluster, or select the name from the drop down list if you
88
Chapter 1
have activated to this server before. Then select Login using my Windows account or Login As
IBM® SPSS® Data Collection User1, and if required enter the user name and password to use.
If you are not connected to the local network. In “Destination Server or Interviewer
Server Administration URL”, enter the URL that you use to login to Interviewer
Server Administration on the target Interviewer Server cluster, for example,
http://primary_dpm_server_name/SPSSMR/DimensionNet/default.aspx. Alternatively, if you
have activated to this URL before, you can select it from the drop down list. Then select Login
As Data Collection User and enter the user name and password to use.
E Click Login.
If the login was successful, the activation dialog will start and prompt you for further information.
For more information on completing the dialog, see Using the Activation Option in IBM SPSS
Data Collection Base Professional.
Note: The Login dialog might not appear if IBM® SPSS® Data Collection Base Professional’s
Show Login Dialog option has been set to False.
Activating an interview from the Start Menu
You can also activate an interview from the Windows Start menu without having to start Base
Professional. This option might be useful for organizations in which activation is performed by
someone other than the scriptwriters. To activate from the Start menu, choose the following
options :
Programs > Data Collection > IBM® SPSS® Data Collection Base Professional 6.0.1 > Activate
This opens the activate Login dialog. To complete the activation dialog, follow the instructions in
“To Activate an Interview” above.
For information about customizing the Activate shortcut in the Windows Start menu, see
Activating Projects from the Command Line.
1 If you select Login As Data Collection User, the user name that you enter will automatically
have access to the interview (project) in Interviewer Server Administration.
Displaying different languages
When using IBM® SPSS® Data Collection Base Professional to develop interviews, you can
display different languages in the following ways:
Change the language that is used in window titles, menu names, ToolTips, and other elements
of the Base Professional graphical user interface (GUI). For more information, see the topic
IBM SPSS Data Collection Base Professional in Other Languages on p. 53.
Change the browser pages that appear when you run an interview in Base Professional. By
default, these two pages contain the English text “No interviews are currently running” and
“Executing routing logic”. However, you can create individual browser pages for any number
of different languages. The pages whose language matches the system locale setting in your
computer’s operating system will then appear when you run an interview.
89
Base Professional
Creating browser pages for different languages
1. In the Interview folder, which by default can be found in the

[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base Professional folder, create a sub
folder whose name is the four letter language code for the required language. Typically,
you will want to create a folder that matches the system locale for your computer’s
operating system. For example, for French-Canada, you would create a folder called
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base Professional\Interview\fr-CA.
2. Copy the following five files from [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base

Professional\Interview to the sub folder that you created in the previous step:
BrowserDefault.htm
InterviewDefault.htm
RedArrow.gif
Routing.gif
SPSSBoxesTop.gif
3. In Windows Explorer, navigate to your new sub folder, right-click BrowserDefault.htm,

choose Properties from the shortcut menu, and clear the Read-only checkbox. Do the same for
InterviewDefault.htm.
4. You can now edit the BrowserDefault.htm and InterviewDefault.htm files in your new sub folder
to change the text to the language you require. To edit these files, you can use either a text editor
such as Notepad or an HTML editor. Alternatively, you can replace these files with your own
HTML files that have the same file names.
5. After you have saved the two files, quit and restart Base Professional.
When you now run an interview, Base Professional will use the browser pages in the sub folder
whose name matches the system locale setting. To change back to the English browser pages,
rename the sub folder that you created so that its name no longer matches the system locale
setting and restart Base Professional.
Setting the default language for interviews
When you create an interview script (.mdd) file, the current language of the metadata is set, by
default, to the system locale setting in your computer’s operating system. If you do not have a
language pack installed, you can specify the default language for new interview scripts by creating
a configuration (.exe.config) file for IBM® SPSS® Data Collection Base Professional.
Note: Do not follow the instructions below if you have a language pack installed. It is not possible
to set a default language for new interview scripts that is different from the language installed
by a language pack.
90
Chapter 1
Setting the default language for new interview scripts
1. If you have changed any of the default options in Base Professional, make a note of your changes.
To do this, choose Options from the Tools menu and make a note of the names and values of all
options whose values are displayed in bold text.
2. Quit Base Professional.
3. Delete the files DockingLayout.bin, DockingModes.bin, mrStudioOptions.xml, and

ToolbarLayout.bin from the C:\Documents and Settings\<your Windows user name>\Application
Data\IBM\SPSS\DataCollection\6\Base Professional folder.
4. In the Base Professional installation folder, which by default is

[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Base Professional, use Notepad or a similar
text editor to create a file called mrStudio.exe.config.
5. Insert the following XML elements into mrStudio.exe.config, replacing en-us with the for the
language that you want to set as the default:
<configuration>
<appSettings>
<add key="Culture" value="en-us" />
</appSettings>
</configuration>
6. Save mrStudio.exe.config and start Base Professional.
7. Using your notes from the first step, amend any of the default options in Base Professional.
When you now create an interview script in Base Professional, the current language of the
metadata is set to the language that you specified in the mrStudio.exe.config file.
Setting the default language back to your system locale setting
1. If you have changed any of the default options in Base Professional, make a note of your changes.
To do this, choose Options from the Tools menu and make a note of the names and values of all
options whose values are displayed in bold text.
2. Quit Base Professional.
3. Delete the files DockingLayout.bin, DockingModes.bin, mrStudioOptions.xml, and

ToolbarLayout.bin from the C:\Documents and Settings\<your Windows user name>\Application
Data\IBM\SPSS\DataCollection\6\Base Professional folder.
4. Delete the mrStudio.exe.config file that you previously created.
5. Start Base Professional.
6. Using your notes from the first step, amend any of the default options in Base Professional.
91
Base Professional
The IBM SPSS Data Collection Base Professional menu
The IBM® SPSS® Data Collection Base Professional menu contains the following options:
Menu Submenu Submenu Keyboard Shortcut
File New File Ctrl+N
Project Alt+F, N, P
From Template Alt+F, N, T
Workspace Ctrl+W
Open File Ctrl+O
Workspace Alt+F, O, W
Save Ctrl+S
Save As Alt+F, A
Close Ctrl+F
Close All Alt+F, L
Save All Ctrl+Shift, S
Add Current Item to Alt+F, D
Workspace
Add New Item to Alt+F, T
Workspace
Add Existing Item to Alt+F, G
Workspace
Save Workspace Alt+F, W
Save Workspace As Alt+F, K
Import Metadata Alt+F, I
Export Metadata Alt+F, M
Store to Repository Alt+F, P, S
Retrieve from Alt+F, P, R
Repository
Print Ctrl+P
Print Preview Alt+F, V
Page Setup Alt+F, U
Recent Files Alt+F, F
Recent Workspaces Alt+F, R
Exit Alt+F, X
Edit Undo Ctrl+Z
Redo Ctrl+Y
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Delete Delete
Find Ctrl+F
Find Next F3
Replace Ctrl+H
Go To Ctrl+G
Select All Ctrl+A
Advanced Increase Line Indent Ctrl+Shift+I
92
Chapter 1

Decrease Line Indent Ctrl+Shift+D
Comment Selection Ctrl+Shift+C
Uncomment Selection Ctrl+Shift+U
Tabify Selection Alt+E, V, T
Untabify Selection Alt+E, V, U
Folding Expand All Foldings Alt+E, O, E
Collapse All Foldings Alt+E, O, C
ScriptAssist Show Members Alt+E, S, M
Expand Macro Ctrl+M
Parameter Info Ctrl+Shift+O
Bookmarks Toggle Bookmark Ctrl+Shift+B
Next Bookmark Ctrl+Shift+N
Previous Bookmark Ctrl+Shift+P
Clear All Bookmarks Ctrl+Shift+A
View Workspace Alt+0
Types Alt+1
Functions Alt+2
Breakpoints Alt+3
Locals Alt+4
Expressions Alt+5
Output Alt+6
Metadata Explorer Alt+7
Auto Answer Start Auto Answer Alt+T, U
Write Data to Data Alt+T, W
Source
Configure Data Source Alt+T, F
Browser Alt+9
Repository Alt+F1
Show All Alt+V, S
Hide All Alt+V, H
Pin All Alt+V, P
Unpin All Alt+V, U
Toolbars File Alt+V, T, F
Edit Alt+V, T, E
View Alt+V, T, V
Debug Alt+V, T, D
Formatting Alt+V, T, F
Workspace Alt+V, T, W
Interview Options Alt+V, T, I
Contexts Analysis Alt+V, C
CARDCOL
Debug Start F5
Restart Ctrl+Shift+F5
Start With Auto Answer F6
Start Without Debugging Ctrl+F5
93
Base Professional

Show Next Statement Alt+D, H
Single Step F10
Toggle Breakpoint Ctrl+B
Clear All Breakpoints Ctrl+Shift+F9
Tools Macros Alt+T, M
Connection String Alt+T, C
Builder
Add Routing Context Alt+T, R
Remove Routing Alt+T, M
Context
Label Manager Alt+T, L
Metadata Model Alt+T, P
Compare
HTML Tidy Alt+T, H
Write to Database Alt+T, W
Debug Quotas Alt+T, Q
Reset Debug Quotas Alt+T, D
Counter
Auto Answer Data Alt+T, U
Generation
Quota Alt+T, Q
Deploy Locally Alt+T, Y
Activate Alt+T, A
Activation Console Alt+T, V
Store to Question Alt+T, S
Repository
Configure Question Alt+T, C
Repository Connections
Configure Project Alt+T, T
Templates
Options Alt+T, O
Window Split Alt+W, S
Next Window Alt+T, N
Previous Window Alt+T, P
Help Contents F1
About Base Professional Alt+H, A
IBM SPSS Data Collection Base Professional toolbars

By default, the seven toolbars in IBM® SPSS® Data Collection Base Professional are docked at
the top and right hand edges of the window. All the toolbars can be moved individually, so that if
you wish, you can dock them on any of the four edges of the window, or they can remain “floating”.
To move a toolbar, click on its grab handle and drag the toolbar to its new position. If you double
click on the title bar of a “floating” toolbar, the toolbar will return to its last docked position.
94
Chapter 1
To show or hide buttons on a docked toolbar, click on the drop-down arrow at the end of the
toolbar, click Add or Remove Buttons, and in the shortcut menu, click the name of the toolbar you
want to change. You can then show or hide each toolbar button by selecting or clearing the
relevant checkbox. You can also do the same on a floating toolbar by clicking on the title bar with
the right mouse button. It is not currently possible to add new buttons to a toolbar, although this
may be a feature of a future version of Base Professional.
The seven toolbars are described in detail below.
File Toolbar
Button Description Keyboard Shortcut

Create a new file. Ctrl+N
Open an existing file. Ctrl+O
Save the current file. Ctrl+S
Save all of the files that are open. Alt+F, N, A
Print the current file. Ctrl+P
Display the current file in the Alt+F, V

Print Preview dialog box.
Open the Page Setup dialog box. Alt+F, U
Edit toolbar

Cut the selection and copy it to Ctrl+X
the Windows clipboard. Note that
this applies to the Edit window
only. If you want to cut text
from one of the other panes (for
example, the Properties pane),
select the text and right-click.
Then choose the Cut command on
the shortcut menu.
Copy the selection to the Windows Ctrl+C
clipboard. Note that this applies
to the Edit window only. If you
want to copy text from one of
the other panes (for example, the
Properties pane), select the text
and right-click. Then choose the
Copy command on the shortcut
menu.
95
Base Professional

Paste the contents of the Windows Ctrl+V
clipboard at the current cursor
position.
Undo the last change you made to Ctrl+Z
the current file.
Redo the last change that you Ctrl+Y
canceled using Undo.
Show the Find pane. Ctrl+F
Show the Replace pane. Ctrl+H
Advanced Edit toolbar

Decrease the indentation of the Ctrl+Shift+D
selected lines by the number of
character spaces specified by the
TabIndent option.
Increase the indentation of the Ctrl+Shift+I
selected lines by the number
of character spaces specified
by the TabIndent option. For
IBM SPSS Data Collection Base
Professional options on p. 101.
Insert a comment symbol (‘) at Ctrl+Shift+C
the start of all of the selected
lines, so that they are considered
comments. This is useful when
you want to remove some code,
but may want to reinstate it later.
Uncomment the selected lines by Ctrl+Shift+U
removing the comment symbols.
Open the AutoExpansion Macros Alt+T, M
dialog box.
Open the Base Professional Alt+T, O
Options dialog box.
Bookmarks Open the Bookmarks menu,
which contains the four buttons
shown below. You use bookmarks
to quickly navigate through the
code.
If the line where the cursor Ctrl+Shift+B
is currently positioned has a
bookmark, remove the bookmark,
and if not, insert a bookmark on
the line.
Move to the next bookmark in the Ctrl+Shift+N
current file.
96
Chapter 1

Move back to the previous Ctrl+Shift+P
bookmark in the current file.
Remove all bookmarks from the Ctrl+Shift+A
current file.
Debugging toolbar

Run the current script in F5
debugging mode. If a script has
stopped at a breakpoint, you
can click this button to continue
execution.
When running an interview script
(.mdd) file, you can use this
button to display the next question
without answering the current
question (that is, the Auto Answer
feature will answer the current
question for you).
Run the current interview script F6
(.mdd) file in Auto Answer
mode. If an interview script
has stopped at a breakpoint, you
can click this button to continue
execution in Auto Answer mode.
For more information, see the
topic Running an interview
automatically on p. 61.
Run the current script in normal Ctrl+F5
(non-debugging) mode. Any
breakpoints in the script will be
ignored.
Stop the debugging session. If Shift+F5
you are running an interview
script (.mdd) file, or a data
management script (.dms) file,
you can also use this button at any
time to stop the run. There may
be a delay before the run stops.
This button is hidden when no
scripts are running.
Restart the debugging session Ctrl+Shift+F5
from the beginning of the script.
Step through the script one line of F10
code at a time.
In a debugging session, scroll Alt+D, H
the script in the Edit pane so that
the next statement to be executed
can be seen. The statement is
highlighted in yellow.
97
Base Professional

Breakpoints Open the Breakpoints menu,
which contains the two buttons
shown below.
If the line where the cursor Ctrl+B or F9
is currently positioned has
a breakpoint, remove the
breakpoint, and if not, insert a
breakpoint on the line. Lines on
which a breakpoint has been set
are highlighted in red.
Remove all breakpoints from the Ctrl+Shift+F9
current script.
Workspace toolbar

Create a new workspace. If Ctrl+W
you have updated the current
workspace, you will be prompted
to save it.
Open an existing workspace. If Alt+F, O, W
you have updated the current
workspace, you will be prompted
to save it.
Add the current file to the Alt+F, D
workspace.
The New File dialog box appears. Alt+F, T
When you confirm the details of
the new file, it will be opened and
added to the workspace.
The Open file dialog box appears. Alt+F, G
When you confirm the name of
the existing file, it will be opened
and added to the workspace.
Save the workspace. Alt+F, W
Interview Options toolbar

Add a routing context to the Alt+T, R
current interview script (.mdd)
file. For more information, see
the topic Adding a routing context
on p. 57.
98
Chapter 1

Remove the current routing Alt+T, M
context from the current interview
script (.mdd) file. For more
information, see the topic Adding
a routing context on p. 57.
Launch MDM Label Manager.
topic Working with multiple
languages on p. 57.
Launch IBM® SPSS® Data
Collection Metadata Model -
Compare. For more information,
see the topic Comparing interview
scripts on p. 86.
Run HTML Tidy. You can use Alt+T, H
HTML Tidy to make sure that
your interview template files
contain only “well formed”
HTML, otherwise known as
XHTML. For more information,
see the topic Validating an
interview template file on p. 87.
Open the IBM® SPSS® Data Alt+T, Q
Collection Quota Setup Window.
topic Testing quotas on p. 83.
Open the Local Deployment Alt+T, D
Wizard. For more information,
see the topic Local Deployment
Wizard overview on p. 199.
Activate the current interview Alt+T, A
script (.mdd) file. For more
information, see the topic
Activating an interview on p. 87.
Opens the IBM® SPSS® Data Alt+T, V
Collection Activation Console.
View toolbar

Show or hide the Workspace pane. Alt+0
Show or hide the Types pane. Alt+1
Show or hide the Functions pane. Alt+2
Show or hide the Breakpoints Alt+3

pane.
Show or hide the Locals pane. Alt+4
Show or hide the Expressions Alt+5
pane.
99
Base Professional

Show or hide the Output pane. Alt+6
Show or hide the Metadata pane. Alt+7
Show or hide the Auto Answer Alt+8

pane.
Show or hide the Browser pane. Alt+9
Show or hide the Repository pane.
Show the Find pane. Ctrl+F
Show the Replace pane. Ctrl+H
IBM SPSS Data Collection Base Professional keyboard shortcuts
Help
To: Press:
Open the IBM® SPSS® Data Collection Developer F1
Library.
General
To: Press:
Create a new file. Ctrl+N
Create a new workspace. Ctrl+W
Open an existing file. Ctrl+O
Save the current file. Ctrl+S
Close the current file. Ctrl+F4
Print the current file. Ctrl+P
Editing
To: Press:
Cut the selection in the Edit pane and copy it to Ctrl+X
the Windows clipboard. Note that this applies to
the Edit window only. If you want to cut text from
one of the other panes (for example, the Properties
pane), select the text and right-click. Then choose
the Cut command on the shortcut menu.
Copy the selection in the Edit pane to the Windows Ctrl+C
clipboard. Note that this applies to the Edit window
only. If you want to copy text from one of the other
panes (for example, the Properties pane), select
the text and right-click. Then choose the Copy
command on the shortcut menu.
Paste the contents of the Windows clipboard at the Ctrl+V
current cursor position.
100
Chapter 1
Undo the last change you made to the current file. Ctrl+Z
Redo the last change that you canceled using Undo. Ctrl+Y
Show the Find pane to find text in the document, Ctrl+F
or in all open documents.
Find the next instance of the text entered in the Find F3
pane.
Show the Replace pane to replace text with other Ctrl+H
text in the document, or in all open documents.
Open the Go To Line dialog box to jump to a line Ctrl+G
number in the document.
Select all text in the document. Ctrl+A
Increase the indent of a line. Ctrl+Shift+I
Decrease the indent of a line. Ctrl+Shift+D
Insert comment marks around a line. Place the cursor on the appropriate line and press
Ctrl+Shift+C
Remove comment marks around a line. Place the cursor on the appropriate line and press
Ctrl+Shift+U
Insert a bookmark or remove an existing bookmark. Place the cursor on the appropriate line and press
Ctrl+Shift+B
Move to the next bookmark in the current file. Ctrl+Shift+N
Move back to the previous bookmark in the current Ctrl+Shift+P
file.
Remove all bookmarks from the current file. Ctrl+Shift+A
Navigation
To: Press:
Switch between the Metadata section and the Ctrl+PageUp/PageDown
Routing section in an interview script (.mdd) file.
Switch to the file in the Edit pane that was Ctrl+Tab (You can use Ctrl+Tab to alternate
previously the current file. between two files. Also note that pressing Ctrl+Tab
and then releasing Tab displays a dialog box in
which you can use the Tab and arrow keys to select
any open file or pane.)
Switch to the previous file in the Edit pane. Ctrl+Shift+Tab
Viewing
Note: To move to a pane that is not hidden, press the keyboard shortcut twice.
To: Press:
Show or hide the Workspace pane. Alt+0
Show or hide the Types pane. Alt+1
Show or hide the Functions pane. Alt+2
Show or hide the Breakpoints pane. Alt+3
Show or hide the Locals pane. Alt+4
Show or hide the Expressions pane. Alt+5
Show or hide the Output pane. Alt+6
Show or hide the Metadata pane. Alt+7
101
Base Professional
Show or hide the Auto Answer pane. Alt+8

Show or hide the Browser pane. Alt+9
Macros
To: Press:
Insert a macro. Type the macro name and any arguments followed
by Ctrl+M
ScriptAssist
To: Press:
Open the autosuggest drop-down list. Ctrl+Space
Close the autosuggest drop-down list Esc
Navigate the autosuggest drop-down list. Down arrow, Up arrow, Page up, Page down, or
type the first letter to jump to items that start with
that letter.
Insert into the script the item that is selected in the Space or dot (.) or left parenthesis ( ( ) or Tab or
autosuggest drop-down list. Enter.
Display a list of all the questions defined in the Ctrl+Q
metadata section of an interview script (.mdd) file.
Display a list of all the sub questions for a question Type the question name (or select using Ctrl+Q),
in an interview script (.mdd) file. type a dot (.) followed by Ctrl+Q
Display the category list for a categorical question Type the question name (or select using Ctrl+Q),
in an interview script (.mdd) file. type a dot (.) followed by Ctrl+R
Debugging
To: Press:
Start running a script in debugging mode. F5
Start running an interview script (.mdd) file in Auto F6
Answer mode.
Start running a script without debugging. Ctrl+F5
Stop the script that is running. Shift+F5
Restart a script in debugging mode after its Ctrl+Shift+F5
execution has been stopped.
Step through the script one line of code at a time. F10
Insert or remove a breakpoint on the current line. Ctrl+B or F9
Remove all breakpoints from the current script. Ctrl+Shift+F9
Close the error message box. Esc
IBM SPSS Data Collection Base Professional options

You can use the IBM® SPSS® Data Collection Base Professional Options dialog box to define
options that control the appearance and behavior of Base Professional. You can open the dialog
box by choosing Options from the Tools menu. If you click on an option, a description of the
option appears at the bottom of the dialog box.
102
Chapter 1
How you change an option depends on the type of option. For numeric options, you simply click
on the option and enter the new numeric value. For options that have a limited number of valid
values, click on the drop-down list to select the value you require. For options that require a file or
folder name, you can either type in the name directly or click on the small button at the rightmost
end of the option to select a file or folder from a list.
The options are described in detail below.
Appearance options
Option Description
Docking Appearance For panes, controls the look of the title bar and the
caption buttons.
Tab Appearance For open files in the Edit pane, controls the look
of the tab.
Toolbar Appearance Controls the look of the toolbars.
Application options
Option Description
Number of Recent Files Controls the number of files that are shown in the
list of recent files on the File menu.
Number of Recent Workspaces Controls the number of workspaces that are shown
in the list of recent files on the File menu.
Debugging options
Option Description
Save Before Execution Controls whether files are automatically saved when
you run or debug them.
103
Base Professional
Interview options
Option Description
Activate Server or URL Specifies the target IBM® SPSS® Data Collection
Interviewer Server cluster to use when you choose
Activate from the Base Professional Tools menu.
The value of this option depends on whether you are
connected to the same local network as the cluster
and have access to the FMRoot shared folder on the
primary DPM server. If you are connected to the
same local network, enter the name of the primary
DPM server. If you are not connected to the same
local network, enter the URL that you use to login
to IBM® SPSS® Data Collection Interviewer
Server Administration on that cluster, for example,
http://primary_dpm_server_name/SPSSMR/Dimen-
sionNet/default.aspx.
If you typically activate to only one cluster, and
are connected to the same local network as that
cluster, you can stop the activate Login dialog from
appearing by entering the name of the primary DPM
server in this option and then setting the “Show
Login Dialog” option below to False. For more
information, see the topic Activating an interview
on p. 87.
Base Folder for Cache The location for interview cache files. Typically,
you should not need to change this option.
Collect Live Data Controls whether answers (case data) collected
during the running of an interview should be marked
as Live or Test. For more information, see the topic
Creating case data on p. 78.
Compare Tool The name and location of the third-party file
compare tool that will be used when you choose
Compare from the Base Professional Tools menu.
For more information, see the topic Comparing
interview scripts on p. 86.
Debug Quotas: Data Source Name The SQL Server instance to be used for storing
quota databases. For more information, see the
Debug Quotas: Database Name The database name you want to use for your quota
database. For more information, see the topic
Testing quotas on p. 83.
Debug Quotas: Display Enabling Message Determines whether Base Professional displays a
warning message when you choose Debug Quotas
from the Base Professional Tools menu. The
message says that creating the quota database might
take a long time. For more information, see the
Default Browser Page The HTML page that will appear in the Browser
pane when no interview is running. If you create
your own page, change this value to the name and
location of your .htm file.
Default Interview Page The HTML page that will appear in the Browser
pane when an interview is running. If you create
your own page, change this value to the name and
location of your .htm file.
104
Chapter 1
Option Description
Error Messages Location The metadata document (.mdd) file that contains the
text for interview error messages. If you create your
own error message texts, change this value to the
name and location of your .mdd file.
Global Template Folder The default location for interview template files.
HTML Doctype The HTML document type declaration to be used
for interview pages. Typically, you should not need
to change this option.
HTMLOptions: NoAutoJump Auto jump is disabled for CATI Player questions.
HTMLOptions: NoExpiryMetaTags Excludes the expiry meta tags in the HTML output.
HTMLOptions: UsePredefinedKeycodes Uses predefined keycodes for CATI Player
questions.
HTMLOptions: UseTablesLayout Uses table layout for single row/column categorical
lists.
HTMLOptions: WebTVSupport Provides WebTV support.
HTTP Ports The HTTP ports to use when running interviews.
Typically, you should not need to change this option.
Initially Show Metadata View Determines whether Base Professional opens a
metadata viewer automatically whenever you open
an interview script (.mdd) file.
Routing Selection Mode Determines whether the standard HTML player
or the CATI HTML player will be used to present
the interview. The CATI HTML player allows the
interview to be completed using the keyboard only.
If you select FromRoutingContext, routing contexts
called CATI will automatically use the CATI HTML
player and all other routing contexts will use the
standard HTML player.
Sample Management Record The name of the Sample User XML (.xsu) file,
which contains a Sample Management record
that can be used to test an interview. For more
information, see the topic Accessing sample
management data on p. 81.
Shared Content Folder The location for Shared Content files. This option
supports the <mrSharedRef> tag.
Show Login Dialog Determines whether the Login dialog appears when
you choose Activate from the Base Professional
Tools menu. Note that if you set Show Login Dialog
to False, but enter a URL in the “Activate Server
or URL” option above (or do not enter any value
for “Activate Server or URL”), the Login dialog
will still appear. For more information, see the topic
Activating an interview on p. 87.
Use Built-in Browser Determines whether a running interview will appear
in the Browser pane or in a standalone Internet
Explorer browser. For more information, see the
topic Testing an interview on p. 60.
Use Hints During Auto Answer Controls whether the Use hints from .mdd checkbox
in the Auto Answer dialog box is selected by
default. Note that using hints can degrade the
performance of the interview script. For more
information, see the topic Running an interview
automatically on p. 61.
105
Base Professional
Option Description
Use In-Memory Cache Controls whether caching will take place in memory
or on disk. Typically, you should not need to change
this option.
View Metadata and Routing Controls how Base Professional displays the
metadata and routing sections of an interview script
(.mdd) file. The two sections can be displayed on
separate tabs in the Edit pane, or can appear as two
halves (top and bottom, or left and right) of the Edit
pane. For more information, see the topic Viewing
and navigating an interview script on p. 58.
ScriptAssist options
Option Description
Show Auto Signature This option controls whether Base Professional
displays the syntax of a function or method when
you type the opening parenthesis.
Show Auto Suggest This option controls whether Base Professional
displays a list of the valid global functions,
properties and methods for a variable when you
type a dot after the variable’s name.
Show Enums Controls whether the ScriptAssist suggestion list
will include enumerators from IBM® SPSS® Data
Collection Type libraries.
Show Function List Controls whether the ScriptAssist suggestion list
will include functions from the IBM SPSS Data
Collection Function Library.
Show Hidden Members Controls whether the ScriptAssist suggestion list
will include hidden items.
Show ToolTips When you move your mouse pointer in the Edit
window over a function or object property or
method, Base Professional can display a ToolTip
showing the correct syntax. You can use this option
to turn this feature on and off.
Text Display options
These options control different aspects of the Edit pane.

Option Description
Convert Tabs to Spaces Controls whether tabs are automatically converted
to spaces. The number of spaces is determined by
the setting of the Tab Indent option.
Default Font The default font that is used in the Edit pane. You
can change this by clicking the ... button on the right
side. This opens the standard Windows Font dialog
box, in which you can select the font name, size,
and other options. Alternatively, you can expand
the DefaultFont options by clicking the + on the left
side. You can then change the suboptions in the
normal way. Note: Italics are not recommended for
the Base Professional default font. Italics may be
difficult to read in the Edit pane.
106
Chapter 1
Option Description
Enable Folding This option enables you to expand and collapse
sections of indented code (such as loops and
subroutines).
Show End Of Line Markers Controls whether end of line markers are shown.
Show Horizontal Ruler Controls whether a horizontal ruler is shown at the
top of the Edit pane.
Show Icon Bar This option displays a bar on the left side of the
Edit pane on which icons indicate the presence of
bookmarks and breakpoints.
Show Invalid Lines This option indicates the presence of empty lines at
the end of a script.
Show Line Numbers Controls whether line numbers are shown.
Show Matching Braces Controls whether a pair of matching left and right
braces ( “[” and “]” ) are highlighted as you type
in the second brace.
Show Spaces Controls whether space characters are shown as
a blue dot.
Show Tabs Controls whether tab characters are shown
Show Vertical Ruler Controls whether a vertical ruler is shown on the
left side of the Edit pane.
Tab Indent Controls the number of spaces between tab stops.
Local Deployment Wizard overview

The Local Deployment Wizard allows you to deploy a survey to one or more IBM® SPSS®
Data Collection Interviewer installations without requiring an IBM® SPSS® Data Collection
Interviewer Server. The wizard provides a simpler alternative to the Activate dialog that is
commonly used to deploy surveys to Interviewer.
The wizard contains the following steps:

Usage options – allows you to select how the project will be used.
Validation options – provides data entry validation options.
Routing options - data entry – provides data entry routing options.
Routing options - live interviewing – provides live interviewing routing options.
Display options – allows you to select which fields are visible in the case data, and select
which field is used to uniquely identify each case.
Deployment options – provides options for deploying the survey to a deployment package or
directly to the local Interviewer installation.
Expiry date and time options – provides options for defining the project expiration data and
time.
Summary options – provides a summary of all selected options prior to starting project
deployment.
Note: If a project was previously activated, the wizard provides the previous activation options. If
a survey was not previously activated, the wizard provides default values.
107
Base Professional
Usage options
The usage options step allows you to select how the project will be used. Options include:
Data entry (default setting) – select this option when the project will be used for entering
response data from paper surveys.
Live interviewing – select this option when the project will be used to conduct face-to-face
interviewing.
Include subdirectories – select this option if you have subdirectories that include additional
files, such as templates and images.
E After selecting the appropriate usage option, click Next to continue to Validation options (when
Data entry is selected) or Routing options - live interviewing (when Live interviewing is selected).
Validation options
The validation options step allows you to select the data entry validation method. This step is only
available when you select Data entry in the Usage options step.
Options include:
Full validation – when selected, all responses require validation.
Partial validation – when selected, only a subset of responses require validation. Partial
validation is not available for surveys that contain only one routing.
Require two-user validation – when selected, operators are not allowed to validate their own
entries. A second operator is required to validate initial entries.
E After selecting the appropriate validation options, click Next to continue to Routing options -
data entry.
Routing options - data entry
The data entry routing options step allows you specify the routing used for data entry. This step is
only available when you select Data entry in the Usage options step.
E Select the appropriate routing context for each data entry option:
Initial data entry – the drop-down menu provides all available routings.
Full validation – the drop-down menu provides all available routings. This option is only
available when you select Full validation in the Validation options step.
Partial validation – the drop-down menu provides all available routings. This option is only
available when you select Partial validation in the Validation options step.
Note: Partial validation is not available for surveys that contain only one routing.
108
Chapter 1
Notes
You will receive an error when the same routing is selected for Partial validation and Initial
data entry or Full validation.
The Initial data entry and Full validation (if applicable) routing options are automatically selected
when the survey contains only one routing context.
E After selecting the appropriate routing options, click Next to continue to Display options.
Routing options - live interviewing
The live interviewing routing options step allows you specify the routing used for live interviewing.
This step is only available when you select Live interviewing in the Usage options step.
E Select the appropriate routing options for each project task:

Routing – the drop-down menu provides all available routings.
Renderer – the drop-down menu provides all available renderers. The selected renderer
controls which display renderer is used for live interviewing. The default value is Web.
Notes
The Routing option is automatically selected when the survey has only one routing context.
Display options
The display options step allows you to select which fields are visible in the case data, and select
Identify unique surveys with this variable – select an appropriate variable that will be used to
uniquely identify each survey. The drop-down menu provides all user variables that can be
used as unique IDs. Boolean and categorical variables are excluded from this list.
Display fields – select the appropriate display fields. Selected fields are included in the IBM®
SPSS® Data Collection Interviewer Case List. The fields are displayed in the order in which
they appear in the Display fields list. Use Move Up and Move Down to reorder the list.
Notes
Respondent.ID and DataCollection.Status are selected by default.
DataCollection.Status is a required field and cannot be deselected.
E After selecting the appropriate display options, click Next to continue to Deployment options.
Deployment options
The deployment options step allows you to select whether to deploy the survey to a deployment
package or directly to the local IBM® SPSS® Data Collection Interviewer installation.
109
Base Professional
Options include:
Create a deployment package for this project (default setting) – when selected, the project is
saved as a deployment package, allowing it to be loaded into other Interviewer installations.
Enter a save location in the provided field, or click ... to browse for an appropriate save
location. The deployment package is saved to the location you specify.
Deploy this project to local Interviewer – when selected, the project is deployed to the local
Interviewer installation. This option requires an Interviewer installation on the local machine.
Data file type – allows you to select the deployment package save file format. The drop-down
menu provides the following save file options:
– Data Collection Data File (.ddf)
– Statistics File (.sav)
E After selecting the appropriate deployment options, click Next to continue to Expiry date and
time options.
Expiry date and time options
The expiry date and time step allows you to define the project’s expiration date and time (UTC
time). Defining a project expiration date and time allows interviewers to easily identify expired
projects.
Options include:
Date: The project expiration date. You can manually enter a date, in the format mm/dd/yyyy, or
you can click the down arrow to display a calendar and select a date.
Time: The project expiration time. This indicates the exact time of day, for the selected date,
that the project will expire. Enter an appropriate time in the 24-hour format hh:mm (for
example 17:00 for 5:00 PM).
E After selecting the appropriate deployment options, click Next to continue to Summary options.
Summary options
The Summary Options step provides a summary of the options selected in each wizard step.
E After reviewing the selected options, click Finish to exit the Deployment Wizard.
If you selected Create a deployment package for this project in the Deployment options step,
the deployment package is saved to the specified location.
If you selected Deploy this project to local Interviewer, the project is deployed to the local IBM®
SPSS® Data Collection Interviewer installation.
Note: If you want to change any of the selected options, click Previous until the appropriate wizard
step displays. After changing the appropriate option(s), click Next until the Summary Options step
displays. Review the selected options, and click Finish.
110
Chapter 1
Activation Settings
Using the File Management component
Most users who activate projects using either an IBM® SPSS® Data Collection Interviewer
Server Administration activity such as Launch or a desktop program such asIBM® SPSS®
Data Collection Base Professional have access to the shared FMRoot folder. Users whose
computers are not connected to the network cannot access FMRoot and therefore need to use the
File Management component for activation instead. When you install Base Professional, the
installation procedure asks whether the user has access to FMRoot and configures the user’s
machine accordingly. You can change this manually at any time simply by changing the value of
a registry key.
The registry key is called UseFileManagerWebService and it is located in
HKEY_LOCAL_MACHINE\SOFTWARE\SPSS\COMMON\FileManager. Its default value is
0 meaning that activation will use FMRoot. To use the File Management component instead of
FMRoot, change the value of this key to 1.
Users who do not have access to FMRoot and whose files are copied using the File Management
component may notice that activation run slightly slower than for users with access to FMRoot.
Option to select .sam sample management scripts
The activation procedure does not normally allow users to select sample management scripts
written in VBScript (.sam files). If your company has an overriding requirement to use .sam sample
management scripts with IBM® SPSS® Data Collection projects, you may reinstate the option to
select .sam files by setting the ShowVBScriptProvider key to 1 in the registry. This key is of type
DWORD and is located in \HKEY_LOCAL_MACHINE\Software\SPSS\mrInterview\3\Activate.
If the key is not defined or has a value of zero, .sam files cannot be selected.
Specifying which files are copied during local deployment
The IVFilesToBeCopied registry entry controls which files and file extensions are copied during
local deployment. By default, IVFilesToBeCopied includes the following files and extensions that
are automatically copied during local deployment:
.mdd
.sif
.htm
.html
.xml
.mqd
.gif
.jpg
.jpeg
.png
.mov
111
Base Professional
.bmp
.avi
catifields_*.mdd
.css
.js
catiCallOutcomes_*.mdd
projectinfo.xml
You can define additional files and/or file extensions by updating the
IVFilesToBeCopied user registry entry. The IVFilesToBeCopied registry entry is
located at: HKEY_CURRENT_USER\Software\SPSS\mrInterview\3\Activate.
The IVFilesToBeCopied rules are as follows:

E When the localdeployconfig.xml file is available, the file’s IVFilesToBeCopied value is used.
E When the localdeployconfig.xml file is not available, the

IVFilesToBeCopied value is retrieved from the user registry
(HKEY_CURRENT_USER\Software\SPSS\mrInterview\3\Activate\IVFilesToBeCopied)
and written to the local config.xml file.
E When the IVFilesToBeCopied user registry key is not found,
IVFilesToBeCopied is read from the local machine key
(\HKEY_LOCAL_MACHINE\Software\SPSS\mrInterview\3\Activate\IVFilesToBeCopied),
copied to the current user registry key
(HKEY_CURRENT_USER\Software\SPSS\mrInterview\3\Activate\IVFilesToBeCopied), and
then written to the local config.xml file.
Note: Registry key changes will not take effect until you manually remove any existing references
to IVFilesToBeCopied in the local config xml file. For example:
<?xml version="1.0" encoding="utf-8" ?>
<properties>
<IVFilesToBeCopied> <![CDATA[mdd;*.htm;*.html;*.xml;mqd;*.gif;*.jpg;*.jpeg;*.png;*.mov;*.bmp;*.avi;catifields_*.mdd;*.css;*.js;catiCa
</properties>
The default local activation directory is C:\Documents and Settings\<your Windows user
name>\Application Data\IBM\SPSS\DataCollection\Activate.
Notes for IBM SPSS Quantum Users

This section has been designed to help IBM® SPSS® Quantum™ users get started with IBM®
SPSS® Data Collection Base Professional. Quantum is a sophisticated tabulation package that
enables you to manage and tabulate your survey data. For example, routine tasks that you can
perform in Quantum include:
Checking and validating survey data
Cleaning and manipulating survey data
112
Chapter 1
Creating sophisticated schemes for weighting survey data

Producing market research tables
Performing statistical calculations
Exporting data to a variety of formats for further analysis
Generating IBM® SPSS® Quanvert™ databases
With the exception of generating a Quanvert database, you can also perform all of these tasks
using Base Professional. Although Quantum has been developed over many years and has a
number of detailed features that not yet available in Base Professional, already Base Professional
has a number of advantages. For example:
Unlike Quantum, you are not restricted to any one specific data format—Base Professional
can work with data in any format for which a suitable Data Source Component (DSC) is
available. In addition, Base Professional can import data directly from any data format for
which you have a suitable OLE DB provider (this means that you can easily import data from
Access and Excel if you have Microsoft Office installed).
Similarly, exporting data is easy and flexible. You can export data to any format for which a
suitable Data Source Component (DSC) is available or for which you have a suitable OLE
DB provider (this means that you can easily export data to Access and Excel provided you
have Microsoft Office installed).
You can set up rule-based cleaning routines based on the variable definitions.
Base Professional makes working with multiple languages easy and, unlike Quantum,
supports languages that use double-byte character sets (DBCS), such as many of the East
Asian languages, including Japanese.
Publishing tables is easy and flexible. The Base Professional Tables Option comes with a
number of components that make it easy to publish tables in HTML and Excel. In addition,
further export components are planned for future releases and it is possible to create your own
export component.
When you run or debug an interview, or run the interview using Auto Answer, you can choose
to write the answers, also known as the Case Data, to an output format supported by the
IBM® SPSS® Data CollectionIBM® SPSS® Data Collection Data Model. At present, the
formats you can write to are Data Collection Data File, IBM® SPSS® Statistics SAV file,
Data Collection RDB database, and Data Collection XML file. For more information , see
Creating case data.
Learning Base Professional takes time and effort, just like learning Quantum did. However, Base
Professional has lots of features to help you. For example, it has a number of templates and
macros that simplify setting up routine jobs. In addition, the IBM® SPSS® Data Collection
Developer Library comes with numerous samples, most of which are designed to run “right
out of the box” against the sample data. You can use these samples as a basis for your own
jobs. In addition, because Base Professional uses industry-standard technology, the skills you
develop using Base Professional will be more easy to utilize in other scripting and technology
environments than some of your Quantum skills.
113
Base Professional
The Big Picture

You can perform many of the same tasks in IBM® SPSS® Data Collection Base Professional
that you can in IBM® SPSS® Quantum™. However, the way you do them is different in Base
Professional. This topic is designed to help you understand in general terms the Base Professional
approach.
First let’s categorize the Quantum tasks, by looking at the contents of the four volumes of the
Quantum 5.7 User’s Guide:
1. Data Editing. This covers listing, validating, checking, and cleaning data, and setting up new
variables.
2. Basic Tables. This covers the basics of creating tables.
3. Advanced Tables. This covers more advanced table features, such as setting up weighting for
your tables, dealing with hierarchical data, adding statistical tests, and customizing the output.
4. Administrative Functions. This covers converting and transferring data, as well as setting up a
IBM® SPSS® Quanvert™ database.
The Base Professional documentation is divided into three main sections. The first section is an
introduction to using Base Professional and the other two sections reflect the two main areas
of functionality:
Using Base Professional. This provides a general introduction to Base Professional and working in
its integrated development environment (IDE). For more information, see the topic Using IBM
SPSS Data Collection Base Professional on p. 11.
Data Management Scripting. This covers functions that generally correspond to those covered in
Volumes 1 and 4 of the Quantum User’s Guide, but with the addition of setting up weighting. For
more information, see the topic Data Management Scripting on p. 204.
Table Scripting. This covers functions that generally correspond to those covered in Volumes 2 and
3 of the Quantum User’s Guide, with the exception of setting up weighting. For more information,
see the topic Table Scripting on p. 1140.
Activating questionnaires
To release a questionnaire online, you need to activate it. The Activation process uploads the
questionnaire file to an IBM® SPSS® Data Collection Interviewer Server and creates an IBM®
SPSS® Data Collection Interviewer Server Administration project for it. It also creates a set of
web pages for the questionnaire and provides a URL link to the web site containing the pages.
Respondents can then access the web site and take the questionnaire by following the link.
Once you activate an interview, either in test mode or in live mode, any further changes that you
make to the questionnaire file are saved in a separate version of the file. Interviewer Server
updates the file and saves the changes with a new version number. The content of the file before
the changes is always retained in an earlier version. This includes adding or deleting questions,
114
Chapter 1
and changing question types. It is therefore recommended that you test your interview using the
Interview Preview option before activating the questionnaire, so that additions or deletions that
you make in the course of designing your questionnaire are not permanently saved in the file.
You can activate the questionnaire either as a test or live interview. A test interview works in the
same way as creating a live interview, except that any data collected is flagged as test data.
Activation user role implications

You cannot activate questionnaires (the Activate option is disabled) unless you are assigned to
the Can activate in test mode activity role feature.
You cannot activate questionnaires in Go live mode (the Go live option is disabled) unless you
are assigned to the Can activate in active mode activity role feature.
You cannot access advanced activation features (the More option is disabled) unless you are
assigned to the Can view advanced activation settings activity role feature.
You cannot modify advanced activation settings (the More option is enabled, but each setting
is read-only and the Load local file... option is disabled) unless you are assigned to the Can edit
advanced activation settings activity role feature.
Refer to the Assigning users or roles to activity features topic in the IBM SPSS Data Collection
Interviewer Server Administration User’s Guide for more information on user roles.
Activation permissions
Project does not exist in the Distributed Property Management (DPM) server: If the login user
is assigned the canCreateProject activity feature, the user can activate the project (otherwise
the user cannot activate the project).
Project exists in the Distributed Property Management (DPM) server: If the login user is the
owner of the project, the user can activate the project. Otherwise, the following rules apply:
– If the project is not assigned to the login user, that user cannot activate the project.
– If the project is assigned to login user, a check is made to determine if the project is
currently locked by login user. If yes, the user can activate the project, otherwise a check is
made to determine if the user is assigned the canUnlockProject activity feature. If assigned
the canUnlockProject activity feature, the user can activate the project (otherwise the user
cannot activate the project).
Refer to the Assigning users or roles to activity features topic in the IBM SPSS Data Collection
Interviewer Server Administration User’s Guide for more information on user roles.
The Activate button is disabled when unable to activate a project. Activation information is
located in the IBM® SPSS® Data Collection Desktop log file.
Activating a questionnaire
E If you have not done so, save the questionnaire file.
E Select the routing that you want to activate.

115
Base Professional

Tools > Activate
or press Alt+T, A.
E In the Data Collection Login dialog box, enter (or select from the drop-down list) the following:
Destination Server or Interviewer Server URL: Enter the name or URL of the
server where Interviewer Server Administration is located (for example,
http://server_name/SPSSMR/DimensionNet/default.aspx). Use this to connect to a server
using an internet or intranet link.
User name: Enter a valid Windows or Interviewer Server user name.
Password: Enter a valid password for the defined user name.
Authentication: Select Interviewer Server Authentication or Windows Authentication (if
Interviewer Server Administration is configured for Active Directory).
Login using my Windows Account: When selected, the User name, Password, and Authentication
fields are disabled and your current Windows login credentials are used.
E Click Login. If the login credentials are valid, you are presented with the Activate - Current Project
dialog.
Figure 1-4
Activate dialog
E You can activate projects using either Basic or Advanced mode.

Basic mode: Provides options for activating a project in either Test or Live mode, and allows
you to select an activation template from which to pull activation settings.
Advanced mode: Provides options for configuring various activation and project settings. For
more information, see the topic Activate Current Project - Project settings on p. 121.
E Select Test mode, Go live, or Inactive from the Basic settings section.
Note: Inactive only displays when the Status after activation option is set to Inactive. For more
information, see the topic Activate Current Project - Project settings on p. 121.
116
Chapter 1
E Select Apply activation settings from activation template if you want to use activation settings from an
existing template. When this option is selected, the Activation Template displays on right-hand side
of the dialog, allowing to select an existing activation template. Select an appropriate template and
click Accept to use the selected template’s settings (click Preview to view the selected template’s
settings). For more information, see the topic Activation templates on p. 117.
Note: Refer to Activate Current Project - Project settings if you want to configure additional
activation settings.
E Click Activate to activate the questionnaire to the Interviewer Server. The Activate dialog closes
and a message indicating that the activation request was sent to the server displays.
You can monitor the activation status via the Activation Console. The console provides options
for viewing pending and completed activations, and creating activation history filters. For more
information, see the topic IBM SPSS Data Collection Activation Console on p. 195.
Notes
E In order for the activation process to function properly, the server software version must be the
same (or higher) as the client software version.
E When activating a new project from a desktop application (IBM® SPSS® Data Collection Author,
IBM® SPSS® Data Collection Base Professional), a warning message will display during
activation when there is an existing ActivateDocument.xml file with unmatched information in
the project’s local folder:
The latest activation settings in the project folder are for a different project. Do you want to update the activation settings based on the curre
[Yes] [No]
If you select Yes, all unmatched information will be replaced with the current project information.
If you select No, the unmatched information will be preserved.
E When you activate a questionnaire in Author or Base Professional, the .mdd file is copied into the
FileName_files folder beneath the questionnaire file. The activation process uploads all the files
from this folder into the Interviewer Server Administration project.
E If you attempt to reactivate a project before receiving the successful activation message from the
IBM® SPSS® Data Collection Activation Console, you may not retrieve the most up-to-date
information from the server.
The .NET Framework’s default encoding reads the registry’s ANSI codepage when encoding. As
a result you may encounter errors when activating questionnaires that include characters such
as umlauts (for example, when the project name contains the character Ä). You can resolve this
issue by updating the server’s ANSI codepage:
1. Access the registry on the server (Start > Run >regedit).
2. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP
3. For servers running a German operating system, enter a value of 850; for Chinese, enter a value of
936; for Japanese, enter a value of 932.
117
Base Professional
Refer to Encoding Class (http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx) on

the Microsoft MSDN site for more information.
Activation templates
You can set up activation options for use in specific circumstances, and save the options as
activation templates that you can later select when activating other projects.
Creating an activation template
E If you have not done so, save the questionnaire file.
E Select the routing that you want to activate.

Tools > Activate
or press Alt+T, A.
E In the IBM® SPSS® Data Collection Login dialog box, enter (or select from the drop-down list)
the following:
Destination Server or IBM® SPSS® Data Collection Interviewer Server URL: Enter the name or
URL of the server where IBM® SPSS® Data Collection Interviewer Server Administration is
located (for example, http://server_name/SPSSMR/DimensionNet/default.aspx). Use this to
connect to a server using an internet or intranet link.
User name: Enter a valid Windows or Interviewer Server user name.
Password: Enter a valid password for the defined user name.
Authentication: Select Interviewer Server Authentication or Windows Authentication (if
Interviewer Server Administration is configured for Active Directory).
Login using my Windows Account: When selected, the User name, Password, and Authentication
fields are disabled and your current Windows login credentials are used.
E Click Login. If the login credentials are valid, you are presented with the Activate - Current Project
dialog.
E By default, the Activate - Current Project dialog displays in the Basic settings mode. In order
to create a activation template, you will need to switch the dialog to Advanced mode. This is
accomplished by clicking More >>.
118
Chapter 1
Figure 1-5
Activate - Current Project dialog
Advanced mode provides options for configuring various activation and project settings. For more
information, see the topic Activate Current Project - Project settings on p. 121.
E After configuring the appropriate activation settings, you can choose to save the activation
template to the local file system or to the Interviewer Server.
119
Base Professional
Note: You can use the Page Up and Page Down keys to navigate through the Activate advanced
mode options on the left.
Saving activation templates to the local file system
E From the Activate - Current Project dialog, select the following:

File > Save as File...
The Save As dialog displays, allowing you to save the activation template to the local file system.
Select a file system location and provide an appropriate template file name.
E Click Save to save the activation template to the local file system.
Saving activation templates to the IBM SPSS Data Collection Interviewer Server

File > Save as Template...
The Save Template dialog displays, allowing you to save the activation template to the Interviewer
Server.
Figure 1-6
Save Template dialog
Activation templates: Lists existing activation templates on the Interviewer Server.
Template name: Enter an appropriate template name in the field, ensuring the name is not the same
as an existing activation template name (unless you want to overwrite an existing template).
E Click Save to save the activation template to the Interviewer Server.
Loading activation templates from the local file system

File > Load Local File...
The Open dialog displays, allowing you to select the appropriate activation template from the
local file system.
120
Chapter 1
E Navigate to the appropriate file system directory, select the desired activation template, and click
Open to load the template’s settings into the Activate - Current Project dialog.
The loaded activation settings will be used for each project activation during the active session, or
until you load settings from another activation template.
Notes
The following properties will not overwrite the current property values after an activation template
is loaded from the server or local file system:
Project ID
Project name
Project database
Project description
Use reporting database
Reporting database location
Login information (user name, ticket, server name, web service URL) and queued activation
information, which is stored in the activation XML, will not overwrite current settings after a
document is loaded from the server or local file system.
121
Base Professional
Activate Current Project - Project settings
The Project settings is where you enter general information that details where and how the
project is to be activated:
Figure 1-7
Project details dialog
122
Chapter 1
The Project settings dialog provides details about the current project. You should not need to
change these fields. You can choose a different project here, but it is easier to close the dialog
and select a different project, as this will automatically update the other fields with the correct
project information.
Project details
ID: The ID is automatically generated from the name of your .mdd file. When the project is
activated in IBM® SPSS® Data Collection Interviewer Server Administration, this is used as the
unique identifier for the project. The drop-down list displays the IDs of any projects that have
previously been activated. To change the settings for a project that does not relate to the file you
currently have open, select the project name from the drop-down list.
Name: The name is automatically generated from the name of your .mdd file. When the project
is activated in Interviewer Server Administration, this is used as the project name. You can
change the name if required.
Description: Enter a description for the project.
Status after activation: The status that you want the project to have once it has been activated.
Choose one of the following:
Active. The project is available for live interviewing.
Inactive. The project cannot be used for test or live interviewing.
Test. The project is available for testing, and any data collected will be flagged as test data.
Project database: The name of the case data database. The default is to store each project’s data
in a separate database with the same name as the project. However, if your site is configured to
allow it, several projects can write case data to the same database.
You may also have authority to create a new database for the project (with a name of your
choice). If so, the drop-down list will contain the Create New Custom Database option. Select
this option and then enter a name for this database in the Custom box that appears next to the
Project Database field.
Activation notes: Background information about the project that you want to save in the project
database for reference by other users. You can leave this box blank.
Source files: The location of the source files for this project (that is, the name of the folder
containing the .mdd file). Select Include sub-folders if the project’s folder contains localization
sub-folders that must be copied to the Shared and Master project folders along with the main
project files.
Interview server project folder: Identifies the Interviewer Server Administration folder into which
the project will be activated. You can select one of the following options:
Select an existing Interviewer Server Administration folder (if any currently exist).
123
Base Professional
Select the default <Top Level> setting. When selected, this option has no affect on where the
project will be activated.
Select the <Create new folder> option and then enter an appropriate folder name. Upon
activation, the specified folder name will be created on the interview server, and the project
will be activated into this folder.
Latest Version Label: The version label to assign to the version of the questionnaire that will be
created during activation.
Project Expiry (UTC Time). Provides options for specifying a project expiration time.
Options
The following options enable and disable specific project settings. When enabled, any user defined
settings are applied to the project during activation. When disabled, any user defined settings are
not applied to the project during activation.
Use disconnected interviewing: When selected, the Disconnected node displays under the Activate
tree. The Disconnected node provides options for deploying a survey to one of more IBM®
SPSS® Data Collection Interviewer installations without requiring an IBM® SPSS® Data
Collection Interviewer Server. For more information, see the topic Activate Current Project
- Disconnected settings on p. 126.
Use participants to specify who to interview: When selected, the Participants node displays under
the Activate tree. The Participants node provides options for specifying the project’s sample
management parameters. This option is only available if you have permission to work with
participants and the project has already been activated with sample management data. For more
information, see the topic Activate Current Project - Participants settings on p. 131.
Use telephone interviewing: When selected, the Telephone node displays under the Activate
tree. The Telephone node provides options specific to projects used for telephone interviewing
(autodialer settings, calling rules, and so on). This option is only available if you have permission
to work with phone surveys and the project has already been activated with CATI sample data.
For more information, see the topic Activate Current Project - Telephone settings on p. 152.
Use quota control: When selected, the Quota node displays under the Activate tree. The Quota node
provides options that allow you to create a new, or using an existing, quota database for the project.
This option is only available if you have permission to work with quota and the server has a quota
database. For more information, see the topic Activate Current Project - Quota settings on p. 186.
124
Chapter 1
Project - Interview
The Interview settings allows you specify the default questionnaire language, define which version
of the questionnaire should be used for interviews run in test and active mode, and decide whether
to restart stopped interviews using the latest version of the questionnaire. This is particularly useful
when you need to make changes to a questionnaire that is already being used for live interviewing.
Figure 1-8
Interview settings
Default Questionnaire Language. The default (base) language for the questionnaire.
With multilingual questionnaires, the language in which you write the questionnaire automatically
becomes the default language for that script. If the questionnaire does not specify the language
in which it is to run, and the information cannot be obtained from the participant record, the
interview will run in this language. Once you start translating a script, other languages are added
to the questionnaire definition file and you may want to select one of those languages as the
default language for the questionnaire.
The language list contains only languages that are present in the questionnaire definition file. If
the computer’s default language does not appear in the questionnaire definition file, the language
list defaults to US English.
Test version. Choose Latest Version to use the latest activated version of the questionnaire for test
interviews. Choose Current Version to use the version of the questionnaire that is being used
now, before activation generates a new version.
125
Base Professional
Active version. Choose Latest Version to use the latest activated version of the questionnaire for
live interviews. Choose Current Version to use the version of the questionnaire that is being used
now, before activation generates a new version.
Restart interviews using new version. Deselect this box if you want to restart interviews using
the version of the questionnaire with which the interviews were originally started, rather than
the latest version.
Default Routing Context. If you have more than one routing context defined, select the one you
want to use as the default. The activation process activates all routing contexts it finds, but only
sets one as the default.
Project - Roles
The Roles settings allow you view the roles to which you currently belong and provide project
access to the listed roles. If you are a member of the DPMAdmin role, or you are assigned the
Can assign project feature, all roles are displayed in the roles list. Otherwise, only the roles
to which you belong are displayed.
Note: The DPMAdmin role never displays.

Figure 1-9
Project Roles settings
126
Chapter 1
After activation, the selected roles are provided access to the project.
Activate Current Project - Disconnected settings
The Disconnected settings provide options for deploying a survey to one or more IBM® SPSS®
Data Collection Interviewer installations, without the need for an IBM® SPSS® Data Collection
Interviewer Server. The settings are applied when the questionnaire is opened in Interviewer.
Refer to the Interviewer User’s Guide for more information.
Note: The Disconnected node displays under the Activate tree when the Use disconnected
interviewing option is selected from the Project settings dialog.
Figure 1-10
Disconnected settings
You can configure settings for:

Routing
Display Fields
Data Entry
Deployment
127
Base Professional
Disconnected - Routing
The Routing settings allow you to select each routing’s activity and the player that will be used in
IBM® SPSS® Data Collection Interviewer.
Figure 1-11
Routing settings
Routing. Allows you to select from the available questionnaire routings
Activity. Allows you to select an activity for the selected routing. Activities include:
Local Interview – when selected, the associated routing is flagged for live interviewing, and
Web and Phone are the only options available in the Player column.
Initial Data Entry – when selected, the associated routing is flagged as an initial data entry
project, which means that Interviewer cases are keyed in Initial Entry mode. When this
option is selected, IBM® SPSS® Data Collection Data Entry is the only option available in
the Player column.
Full Validation – when selected, the associated routing is flagged as a full validation project,
which means that all question responses require full validation. When this option is selected,
Data Entry is the only option available in the Player column.
128
Chapter 1
Player. This column allows you to select which Interviewer player will be used for the associated
routing. The available options are dependant on what was selected in the Activity column. Options
include:
Data Entry – when selected, cases will be entered via the Data Entry Player when the
questionnaire is opened in Interviewer.
Web – when selected, cases will be entered in live interviewing mode when the questionnaire
is opened in Interviewer.
Phone – when selected, cases will be entered in live interviewing mode when the questionnaire
is opened in Interviewer.
Disconnected - Display Fields
The Display Fields settings allow you to select which fields will be visible when the questionnaire
is opened in IBM® SPSS® Data Collection Interviewer, and identify the field that will be used to
uniquely identify each case. Use the Move Up and Move Down buttons to change the field order.
Figure 1-12
Display Fields settings
129
Base Professional
Disconnected - Data Entry
The Data Entry settings allow you to configure data entry verification related options. The settings
are applied when the questionnaire is opened in IBM® SPSS® Data Collection Interviewer.
Figure 1-13
IBM SPSS Data Collection Data Entry settings
Identify unique surveys with this variable: Allows you to select which field will be used to uniquely
identify the questionnaire. The RespondentID field is the default.
Require two user verification: When selected, two user verification is required when validating
question responses. This means that the user who validates question responses must be different
than the user who performs initial data entry.
Disconnected - Deployment
The Deployment settings provides options for deploying the questionnaire to a deployment
package, or directly to the local IBM® SPSS® Data Collection Interviewer installation.
130
Chapter 1
Figure 1-14
Deployment settings
Data file
File type: Allows you to select the file format for the activated or locally deployed questionnaire.
Options include:
Data Collection Data File (.ddf)
Statistics File (.sav)
Upon activation
Use a deployment package for disconnected machines: When selected, this option allows you
to create a deployment package for use with Interviewer. Deployment packages are typically
employed for Interviewer machines that are not connected to an IBM® SPSS® Data Collection
Interviewer Server. Click Browse... to select a location to save the deployment package.
Add to Interviewer on this machine: When selected, the questionnaire is automatically added to the
Interviewer project list on the current machine. This option is only available when Interviewer
is installed on the same machine.
131
Base Professional
Activate Current Project - Participants settings
The Participants settings provide options for specifying the project’s sample management
parameters.
Note: The Participants node displays under the Activate tree when the Use participants to specify
who to interview option is selected from the Project settings dialog.
Figure 1-15
Participants settings

Upload
Database
Fields
Script
E-mail
Participants - Upload
The Upload settings allow you to specify the name and location of the file that contains the
participant records.
132
Chapter 1
Figure 1-16
Upload settings
Use existing participants. When selected, the project uses sample management and participant
records that have already been uploaded.
Upload participants. When selected, the project uses sample management and you are provided the
option of uploading the participant records. Click Browse... to select a participant file location.
Note: You can only upload participant records if your IBM® SPSS® Data Collection Interviewer
Server Administration user profile is assigned the Can upload participants activity feature in
Interviewer Server Administration. Refer to the topic Assigning Users or Roles to Activity
Features in the Interviewer Server Administration User’s Guide for more information.
With phone interviewing support. When selected, the project allows outbound telephone
interviewing.
133
Base Professional
The table names the fields that are (or will be) present in the sample table and displays how
they will be used.
Setting Description
Available Fields to make available to the sample management
script. Cancel any that are not used by the sample
management script (you cannot cancel required
fields).
Fields whose contents are used only by the interview
script become available during interviews and need
not be selected here.
Authentication Fields to use for authenticating inbound callers
taking Web interviews. Choose the fields you want
to use and cancel any you do not.
If you need to be able to select specific participant
records, you should select the Id field because this
is a key to the database and is guaranteed to contain
a unique value for each record.
If you authenticate on a field that may contain
non-unique values, the sample management system
will select the first record whose value in that
column matches the values specified in the sample
management script.
Field Field names. You cannot modify these settings.
Default Default values to be inserted into empty fields.
Fields with no default values will have a null value.
You may specify your own defaults as long as the
values are consistent with the fields’ data types and
lengths.
Type The type of data in the field. You cannot change the
data type of required fields.
Length The number of characters that can be held in a text
field. You cannot change the length of required
fields.
Refer to Uploading participant records for information about the field parameters you can change.
Participants - Database
The Database settings allow you to specify the server to which the participant records will be
uploaded and the database and table in which the records will be stored.
134
Chapter 1
Figure 1-17
Database settings
Server name: The name of the server on which the participant database is located. The
drop-down list contains only those servers that are present in your current domain. If you want
to use a server in another domain, you must manually enter the domain name (for example,
<domain_name>\<server_name>).
Database name: The name of the participant database. The drop-down list displays the names of
databases that you have permission to use and that exist on the chosen server. If you are uploading
participant records, and you have permission to create databases, the New button is visible and
allows you to create a new database. Enter the database name when prompted.
Table name: The name of the table that contains the participant records for this project. The
drop-down list displays the names of tables in the chosen database. If you are uploading
participant records you can click New to create a new table. Enter the table name when prompted.
Participants - Fields
The Fields settings allow you to specify which fields will be present in the sample table and
provides various field configuration options.
135
Base Professional
Figure 1-18
Fields settings
With phone interviewing support. When selected, the project allows outbound telephone
interviewing.
The fields table names the fields that are (or will be) present in the sample table and displays
how they will be used.
Setting Description
fields).
136
Chapter 1
Setting Description
management script.
lengths.
fields.
Refer to Uploading participant records for information about the field parameters you can change.
Participants - Script
The Script settings displays the sample management script that the project will use for managing
participant records. In the selection box, choose the name of the script you want to download.
The standard choices are Basic (for Web interviewing) and Multimode (for Web and telephone
interviewing).
137
Base Professional
Figure 1-19
Script settings
Depending on your user permissions, and the sample management system configuration, you may
also be able to click Browse... to load a file other than those in the drop-down list.
Participants - E-mail
The E-mail settings provide options for setting up e-mail for participants in the sample file. For
example, at the start of a project you might send a message to everyone inviting them to participate
in the survey. Later, you might setup a second job that sends reminders to those respondents
who have not yet taken the survey.
138
Chapter 1
Figure 1-20
E-mail settings
E-mail provides the following options:

Respondent selection. You can send e-mail to all respondents in a queue or set of queues.
Alternatively, send to a fixed number of respondents chosen either from the start of the queue
or at random.
Customized and personalized message texts. If you want to include information from a
respondent’s sample record, or the value of a project property, insert a placeholder in the
message text and the appropriate values will be substituted for the placeholders when the
messages are sent. This allows you to address respondents by name, and to include the URL
for starting the interview as part of the message.
Test messages. Check how the message will appear to respondents by sending a test message.
Project status. You can specify that the job should only be run if the project has a particular
status.
139
Base Professional
Activity recording. You can record which respondents received which e-mail by updating a
field in the sample record with a note of the time and date at which the e-mail was sent.
No repeat e-mail. If you rerun an e-mail job, a message is normally to everyone who is
selected to receive it. You may choose not to target people who received this message during
a previous run.
Delayed sending of e-mails. There is no direct link between setting up an e-mail job and
running it. All job specifications are saved and are run only when selected from a list of
e-mail jobs for the current project.
Maintenance facilities. Job specifications can be edited and deleted as required.
Dealing with e-mail problems. You can specify the e-mail address of a user who is to be
contacted if there are problems. This user is also the person who receives test e-mails.
Note: E-mail does not support SMTP servers that are set up to require authentication.
E-mail jobs
The e-mail jobs table allows you to define the following parameters:
Setting Description
Name Enter a name for the e-mail job.
From Enter the e-mail address that will display as the sender.
Reply Address Enter your name (or e-mail address) or the name (or e-mail address) of the
person on whose behalf you are sending the message. Whatever you type here
will appear as the sender’s name in the recipient’s message box.
Priority Select the e-mail priority from the drop-down list. You can choose either a
High, Medium, or Low priority.
Project Status Select the status that the project must have in order for the e-mail to be sent.
You can select more than one status.
E-mail text tab
The E-mail text tab allows you to configure the following settings:
Subject: Enter a subject for the e-mail message.
Send as: Select either HTML or Plain text. HTML provides formatting options (bold text, italics,
and so on), while Plain text does not.
Body: Displays suggested message text, complete with substitution markers for inserting
respondent or project specific information. You can accept this text as it is, modify it, or replace
it with different text.
Preview... Click to preview how the e-mail will display.
Substitutions... If you want to insert the value of a Sample Management field or project property
into the message text, click in the text at the point you want to make the insertion, then click
Substitutions... and select the field or property you want to insert from the dialog box that is
140
Chapter 1
displayed. The property name appears in the message text enclosed in curly brackets and will be
replaced by the appropriate value when the e-mail message is sent.
E-mail address field from sample: Select the Sample Management field that contains recipient
e-mail addresses.
Write date and time that e-mail was sent to sample: When selected, the date and time when the
message was sent, as part of each recipient’s sample record, is recorded.
Sample field in write to write: Select the name of the sample field from the drop-down list.
Note: Use the above two options if you want to prevent the same message from being sent to
respondents more than once.
If a respondent is sent the same message more than once, the date and time field information is
overwritten each time a new message is sent.
Send e-mails to this address when test e-mails are sent or when there are problems: Enter an e-mail
address that will be sent messages when test e-mails are sent or when problems are encountered.
Participants tab
Choose queues: Select the queues from which recipients can be selected.
Note: The list only shows queues that contained sample records at the time the mrDPMServer3
service was started. This may mean that the list may contain out-of-date information, for example,
because records have been moved into a queue that was previously empty or because a queue
that contained records is now empty. You may need to ask your IBM® SPSS® Data Collection
Interviewer Server administrator to stop and restart the mrDPMServer3 service in order to view an
up-to-date queue list.
To restrict your selections even further do the following:
Choose a field to filter participants: Select a field to be used for filtering participants. The list shows
all fields in the sample table except Queue.
Choose filter value(s): Select the values that the field must contain in order for respondents to be
selected. The list shows all values present in the selected field.
Send e-mail to:

All participants meeting the criteria specified above: When selected, e-mail is sent to all
participants that meet the previously specified criteria.
A maximum number of participants: When selected, e-mail is only sent to the number of
participants you specify.
First x: When selected, e-mail is sent to select respondents from the top of the list (of those
matching the selection criteria).
Randomly selected: When selected, e-mail is sent to random respondents (of those matching
the selection criteria).
141
Base Professional
This e-mail can be sent to the same participant more than once: When selected, e-mail is allowed to
be sent to the same participant more than once. This option is only available if you enabled the
Write date and time that e-mail was sent to sample field on the E-mail text tab.
Uploading participant records
This topic explains how to upload participant records using the Activate dialog box.
Note: You can only upload participant records if your IBM® SPSS® Data Collection Interviewer
Server Administration user profile is assigned the Can upload participants activity feature in
Interviewer Server Administration. Refer to the topic Assigning Users or Roles to Activity
Features in the Interviewer Server Administration User’s Guide for more information.
Using this method to load records is generally the same as loading records using the Participants
activity in Interviewer Server Administration, but there are some restrictions that apply to the
participants text file. Whereas the Participants activity accepts any field names in the participants
text file, and provides facilities for mapping fields in the file to the field names that the sample
management system requires in the database, the Activate component does not. This means that
all fields that are present in the text file, and that are required sample management fields, must
have the correct names in the text file. For example, the record Id must be stored in a field called
Id. If the field name is RecNum, you must change this in the header line of the text file before
you upload records.
The names of the required fields for Web interviews are as follows:
Column Data type Null Primary key Default Notes
and length permitted value
Active Long Yes No 0 Set to 1 while
the sample
management
functions are
running; that
is, while the
record is in
the ACTIVE
queue.
Id Text(64) No Yes The sample
record
ID which
uniquely
identifies
each sample
record.
Queue Text(255) Yes No FRESH Names the
queue in
which the
record is
currently
held.
142
Chapter 1

Serial Long Yes No 0 The unique
serial number
that IBM®
SPSS® Data
Collection
Interviewer
Server
assigns
to each
respondent’s
case data.
Generally,
this serial
number is not
the same as
the sample
record ID.
When a
respondent
restarts an
interview,
Interviewer
Server uses
the serial
number to
retrieve the
respondent’s
case data
record and
to display
the responses
(stored in
the case
data record)
that the
respondent
has already
given.
Test Long Yes No Null Set to 1 if the
record is test
data, or 0 if
it is real data
(also known
as live data).
This column
is used by
the Phone
activity to
restrict the
type of data
that appears
in phone
reports. If the
value is Null,
the Phone
activity will
treat the
record as if
143
Base Professional

it is both real
and test data.
The required fields for telephone interviews are:

Column Data type Null Primary Default Notes
and length permitted key value
Active Long Yes No 0 Set to 1 while the sample
management functions are
running; that is, while the
record is in the ACTIVE
queue..
ActivityStartTime
DateTime Yes No Null The StartTime of latest
record in the history table
for a specific sample.
Date
AppointmentTime Yes No The time in UTC at which
the respondent asked to be
called.
Long
AppointmentTryCount Yes No 0 The number of calls made
to this record after an
appointment was set.
When sample records are
uploaded into the sample
table, a non-null default
value should be specified
otherwise errors will occur
during the upload.
Audit Text(2000) Yes No Records changes made
but see Notes to other fields (except
for more Comments) in the record.
information This field was new in
Interviewer Server 4.0.
In earlier versions, these
changes were stored in the
Comments field.
If you reuse a pre-v4.0
sample table that contains
a Comments field of
SQL type ntext, the
Audit field is created as
nvarchar(2000) instead.
This is due to an issue in
the Microsoft OLE DB
consumer templates that
prevents a table containing
two ntext columns.
CallOutcome Text(64) Yes No The call outcome (return)
code for the previous call
to this record.
144
Chapter 1

Long
CallRecordingsCount Yes No 0 for The number of call
telephone recordings for this record.
projects, Records loaded with this
otherwise field empty have this field
Null set to Null in the sample
table.
Comments Text(2000) Yes No Additional information
but see Notes about the participant.
for more Interviewers may update
information. this field when they call
the participant.
In pre-v4.0 sample tables,
the Comments field is
created as ntext(16). If
you reuse a pre-v4.0
a Comments field of
type ntext, its data type
remains unchanged and
the Audit field is created
as nvarchar(2000) instead.
two ntext columns.
The standard multimode
sample management
scripts display records
with comments before
dialing so that the
interviewer can read
the comments before
talking to the participant.
ConnectCount Long Yes No 0 The number of times
that the number has been
connected. This field is
updated when a sample is
dialed and connected.
DayPart Text(128) Yes No Null Records the call count for
each specific day part.
For example, assume there
are two day parts named
aa, ab. The value for
this field will be aa1|ab2
(or aa1). This means the
sample was used to call
one time in aa time range
and two times in ab time
range. If the sample has
not yet been used, the
value of this field is null.
145
Base Professional

ExpirationTimeDateTime Yes No 2099–12–31Defines the participant
23:59:000 record expiration date
and time. For example, a
project may dictate that
participant records can
only be called within a
specific date range.
Expired records are not
available for dialing
(except for retrieving
appointments).
Id Text(64) No Yes The sample record ID that
uniquely identifies each
sample record.
InternalDialerFlags
Text(64) Yes No NULL Used in conjunction with
a 3rd party dialer. In
full predictive mode, this
field should accompany
all numbers dialed
commands. It is set to
an initial value by the
CATI system for the first
dialer (for a different
dialer, the initial value can
be different).
IBM® SPSS® Data
Collection Dialer will
return a new value for
Internal Dialer Flag for
the number. After dialing,
this field will be updated
with the new value,
and this value will be
permanently set with the
sample record and passed
through for all subsequent
dialing attempts.
InterviewModeText(64) Yes No How the record may be
used: set to Web for an
inbound self-completion
interview or Web CATI
for outbound telephone
interviewing. In projects
that allow a mix of
inbound and outbound
calling, the sample
management script should
check the value of this
field and select records
for telephone interviewing
accordingly.
The value in this field
can be changed in the
questionnaire script, or by
editing the record directly
in SQL. You might
want to do this towards
146
Chapter 1

the end of a survey if
there are a number of
timed out or stopped
Web interviews and you
want your interviewers
to contact those people
to try to complete the
interviews.
Long
NoAnswerCount Yes No 0 How many times this
sample has been called
and received NoAnswer.
This field is updated
when a sample is dialed
and returned with a call
outcome of NoAnswer
PhoneNumber Text(64) Yes No Must contain a phone
number if the record is
to be used for telephone
interviewing.
If the project uses
an autodialer, phone
numbers that start with
a + sign will have that
character replaced by the
InternationalAccessCode
defined in DPM. + signs
preceded by white space
or other characters are not
replaced.
If the project allows
inbound calling, you can
add a question to the script
that asks respondents to
enter contact numbers,
and then update the
sample records with this
information.
PreviousInterviewerID
Text(64) Yes No The name of the
interviewer who made
the previous call to
this participant. This
allows appointments
to be returned to the
previous interviewer if the
current time is before the
AppointmentMarginAfter
interval has passed.
Appointments that are not
kept within this period
may be passed to any
interviewer.
When interviews are
reviewed, this field is
updated with the name of
the reviewer.
147
Base Professional

PreviousQueue Text(64) Yes No The name of the queue
in which the record was
previously held. When
records are displayed
for interviewers, the
record’s current queue
is always shown as
ACTIVE because the
record has been selected
for interviewing.
Displaying the value of
PreviousQueue can be
useful to interviewers
as it may provide
additional information
about the record’s calling
history. For example, if
PreviousQueue is FRESH,
the interviewer knows
the record has not been
called before, whereas
if PreviousQueue is
APPOINTMENT, he/she
knows that the respondent
has already been contacted
and has asked to be called
back to be interviewed.
Queue Text(64) Yes No FRESH Names the queue in which
the record is currently
held.
When replicate identifiers
are defined in the queue
field for specific records,
those records can
then be used to create
sample/participant record
subsets.
RecallTime Date Yes No The time in UTC that
was set as the callback
time for appointments that
are set automatically by
the sample management
script.
Long
RequiresManualDial Yes No Indicates that the record
must be manually dialed.
The sample management
script will set AutoDial=0
for these records.
The feature will not work
if RequiresManualDial
is not defined in the
participants table
148
Chapter 1

ReturnTime Date Yes No The time at which the
record was returned to
sample management. This
allows you to specify the
amount of time that must
elapse between repeat
calls to records whose
interviews timed out or
were stopped.
Serial Long Yes No 0 The unique serial
number that Interviewer
Server assigns to each
respondent’s case data.
Generally, this serial
number is not the same
as the sample record
ID. When a respondent
restarts an interview,
Interviewer Server uses
the serial number to
retrieve the respondent’s
case data record and to
display the responses
(stored in the case data
record) that the respondent
has already given.
Screener Text(64) Yes No Null Identifies which
respondents are the
suitable candidates for the
current survey. Screener
questions are designed to
filter respondents. If a
respondent answers do not
meet the Screener criteria,
the respondent is not
allowed to continue the
survey, and the Screener
field is recorded as Failed.
If respondent answers
they are allowed to
continue the survey, and
the Screener field is
recorded as Passed.
This field can be set using
the following IOM script
in routing (it is the data
source for the Incidence
report).
Passed Screener:
IOM.SampleRecord.Item["Screener"].Value = "Passed"
Failed Screener:
IOM.SampleRecord.Item["Screener"].Value = "Failed"
IOM.Terminate(Signals.sigFailedScreener, True)
149
Base Professional

In order to accurately
calculate the project
incidence, the Screener
field is added to the
sample table. The field
is updated during the
survey with three values
– Null, Passed, and
Failed. The sum of
Passed is the incidence
numerator; the sum of
Passed and Failed is the
incidence denominator.
The incidence report is
generated using TOM
based on the data source,
sample table, and sample
history table.
SortId Text(64) Yes No Null A random value that
can be used for sorting
records prior to selection.
(Appointments and recalls
are not affected by this
property as they are
always sorted in ascending
date/time order.) The
Participants activity can
initialize this field with
a random value when
uploading records. If
records are uploaded in
batches, each record in the
sample table receives a
new random number, not
just those being uploaded
in the current batch. See
“Naming the Database
Server, Sample Database,
and Sample Table” in the
Interviewer Server User’s
Guide for details.
Test Long Yes No Null Set to 1 if the record is
test data, or 0 if it is real
data (also known as live
data). This column is used
by the Phone activity to
restrict the type of data
that appears in phone
reports. If the value is
Null, the Phone activity
will treat the record as if it
is both real and test data.
150
Chapter 1

TimeZone Long Yes No The respondent’s
timezone. This is
used in the setting
of appointments to
ensure that any time
differences between
the respondent’s and
interviewer’s locations are
taken into account when
the record is presented
for recalling. For more
Time Zone Management
on p. 1032.
TrunkGroup Long or Yes No NULL If sample records are used
Text(64) in telephone interviewing
projects, you can use
the TrunkGroup field to
specify which trunk group
of the dialer will be used
for dialing the sample
record. If you want the
dialer to automatically
select the trunk group,
the field should be set to
NULL or empty.
TryCount Long Yes No 0 The number of calls
made to this record.
during the upload.
UserId Text(64) Yes No NULL The UserId of latest record
in the history table for a
specific sample.
The data types shown above are those that the IBM® SPSS® Data Collection Data Model uses.
When the table is created in the sample database, the Activate component converts these data
types into the corresponding data types in the database application you are using. (For further
details about the mapping process, open the IBM® SPSS® Data Collection Developer Library
documentation and use the Search facility to locate the topic entitled “Data Type Mapping for
Columns in Sample Tables”.) You can check the column data types by opening the table in your
database application and can change the data types if they are not exactly what you want. Refer to
your database application’s documentation for information on changing data types.
Your participants text file does not need to contain information for all the required columns, as
many of the columns are used only internally by the sample management system and will only
contain information once a participant has been called. As a minimum, you must supply a value in
your text file for the Id column. For telephone interviewing projects, you should provide a value
for the PhoneNumber column, and if you have participants in more than one time zone you might
want to provide a value for the TimeZone column.
151
Base Professional
Once you have told Activate which text file to use, it scans the file and decides how it will load
the data into the sample table. It does this by comparing the field names in the participants text
file with the columns names that need to exist in the sample table. If there are additional fields in
the text file, new columns will be created in the sample table to hold this data. The fields table
displays a summary of what it will do and lets you change it if this is necessary. Typically, you
might change the fields that are used for authenticating inbound callers.
The columns in this display are as follows.
Setting Description
fields).
management script.
lengths.
fields.
Uploading participant records
E Select Upload (located under the Participants node).
E Select Upload participants and click Browse....
This opens the Specify Participants dialog box.

152
Chapter 1
Figure 1-21
Specify Participants dialog box
E In Delimiter, select the character that separates the fields in each record. The default is a comma. If
you pick a different character, this becomes the default the next time you activate a project.
E Click Browse... and select the .txt or .csv file you want to upload.
E The upload process automatically randomizes records as it loads them. Click Re-randomize all
participant records during import if you want to cancel the randomization process.
E Click OK to close the dialog box.
Activate checks the participants text file and displays the fields in the fields table.
E Make whatever changes are appropriate in this table.
E Use the Fields and Script settings to select the sample database and table you want to use, and the
sample management script that will control access to the participant records.
Activate Current Project - Telephone settings
The Telephone settings provides options specific to projects used for telephone interviewing
(autodialer settings, calling rules, and so on).
Note: The Telephone node displays under the Activate tree when the Use telephone interviewing
option is selected from the Project settings dialog.
153
Base Professional
Figure 1-22
Telephone settings

Interviewing
Calling Rules
Dialing
Note: The Dialing options are only available when a dialer is installed on the server.
Telephone - Interviewing settings
The Interviewing settings allow you to configure options for a telephone interviewing project.
154
Chapter 1
Figure 1-23
Interviewing settings

Display Fields
Call Outcomes
Introduction
Interviewer
Review
Interviewing - Display Fields
The Display Fields settings allow you to specify which sample management fields are required
in the participant records, which fields should be displayed on the interview screen, and which
of the displayed fields interviewers can edit.
When an autodialer connects a telephone interviewer to a participant (or, for projects that do not
use an autodialer, when the interviewer requests a number to call) the interviewing program
displays a page showing information about the participant and a list of possible call outcomes.
Some items of information are always displayed whereas other items are displayed only if selected
by the supervisor. The supervisor can change the selection of optional fields during the course
of the project. Supervisors can also specify for each displayed field whether or not interviewers
can change the field’s contents. For example, if the Comments field is displayed you might
want interviewers to be able to update this field with information that might be useful to other
interviewers who are about to speak to this participant.
155
Base Professional
Figure 1-24
Display Fields settings
Setting Description
Label Shows the field name that will be displayed on the
interviewing screen.
Required Shows which fields must be present in each
participant record. You cannot change the settings
in this column for any of the standard fields that
must be present in all telephone databases, but you
can change the settings for other fields.
156
Chapter 1
Setting Description
Show Determines which fields will be displayed on the
interviewing screen. Of the standard fields, the ID,
Queue, Name, Phone Number, Comments, and
Previous Queue fields are always displayed, so you
cannot clear the Show check box for these fields.
The settings in this column also define the fields
that interviewers can search when searching for a
specific contact. To allow interviewers to search for
specific contacts, you must select the Show Specific
Contact option on the Interviewing - Interviewer
dialog .
Can Edit During Survey Determines which of the displayed fields
interviewers can edit. For the standard fields, you
can only change the settings for Return Time,
Interview Mode, and Call Outcome.
Can Tabulate Specifies which fields should be available to the
Phone activity. The only standard field whose
setting you can change is Try Count. If your sample
data includes a Segment field and you want to run
the reports in the Phone activity that can display
data about segments, make sure that you select
Can Tabulate for your Segment field. For more
information about segments, search the Phone
activity online help for the topic “About Segments”.
Interviewing - Call Outcome
The Call Outcome settings allow you to set the call outcome options.
Interviewers working on a telephone interviewing project are provided with a list of call outcome
codes from which they must select the outcome of each call that they make. IBM® SPSS® Data
Collection Interviewer Server comes with a default list of call outcome codes that cover most
requirements, so you should never need to build a call outcome list from scratch.
Note: For projects that use an autodialer, Interviewer Server automatically maps the status codes
returned by the autodialer to one of the call outcomes.
157
Base Professional
Figure 1-25
Call Outcome settings
Setting Description
Code The call outcome code number.
Name The call outcome name.
Text The call outcome description. This is the text that the interviewer sees.
Show During Interview Specify which codes must be available while interviews are in
progress; for example, an Abandoned Interview code can be selected
if a participant starts an interview but then refuses to complete it.
Show Appointment Page Specify which codes should prompt the interviewer to arrange a
callback appointment with the participant. When interviewers select
one of these outcomes they will prompted to enter a callback date
and time.
Cancel Code Specify which code should be used for canceled calls. Canceled
calls occur when an interviewer is presented with a number to call
manually, but clicks Cancel Contact rather than making the call. This
returns the participant record to the Sample Management system with
the appropriate code so that the record can be returned to the queue
from which it was selected.
Always Hidden Select which codes are always hidden from interviewers. Typically,
these are call outcomes that are chosen automatically by Interviewer
Server.
158
Chapter 1
Interviewing - Introduction
The Introduction settings allow you to define the introductory script that interviewers should
read to each participant.
When an autodialer connects a telephone interviewer to a participant (or, for projects that do not
use an autodialer, when the interviewer requests a number to call), interviewers are provided
with an introductory text that they can read to the participant to explain the reason for the call.
IBM® SPSS® Data Collection Interviewer Server comes with a default text that is suitable for all
surveys, but you can define your own text that is more specific to the current project.
Figure 1-26
Introduction settings
Introduction to survey: Displays the default introductory text. You can manually replace the default
text that Interviewer Server provides with your organization’s default text.
Substitution fields: Lists fields available for insertion into the introductory text. The available
fields typically reference to a sample field or the interviewer’s name.
Show valid substitution fields: When selected, only valid substitution fields display in the
Substitution fields list.
Inserting a field into the introductory text
E Click in the introductory text at the point you want to make the insertion.
E Select a field from the Substitution fields list.

159
Base Professional
E Click Insert.
The field name appears in the introductory text enclosed in curly brackets and will be replaced by
the appropriate value when the introductory message displays for the interviewers.
Interviewing - Interviewer
The Interviewer settings allow you to specify interviewer dialing parameters.

Figure 1-27
Interviewer settings
Dialing option: Select whether an autodialer is used to dial phone numbers, whether interviewers
must dial numbers manually, or whether interviewers can use modems to dial numbers.
IBM SPSS Dialer (Extension) – Power dial for the interviewer screen. In extension dialing, the
autodialer dials participants only when interviewers click the Start Dialing button in the
Phone Participants activity. This mode can result in longer wait times for interviewers, but
is unlikely to result in silent calls.
IBM SPSS Dialer (Group) – Dial for the interview in a group (with optional predictive dialing). In
group/predictive dialing, the autodialer dials participants before interviewers are available to
answer the connected calls. That is, the software predicts when interviewers will click the
Start Dialing button. This mode can deliver the highest interviewer productivity, but might
result in silent calls.
Modem – Show Dial Contact button on the Interviewer screen. Allow interviewers to use modems
to dial phone numbers. The Dial Contact button on the main screen of the Phone Participants
activity will then be usable. When interviewers click that button, the phone number displayed
160
Chapter 1
in the main screen will be dialed automatically by the modem. Note that the modem option
will work only for phone numbers that are formatted as follows:
+Country/RegionCode (Area/CityCode) SubscriberNumber
For example, 44 12 3456 7890 for a subscriber in the United Kingdom. In addition, a separate
software installation is required on each telephone interviewer station that will use the
modem option. For more information, search the IBM® SPSS® Data Collection Interviewer
Server Installation Instructions for the topic “Things You Must Do on Local Machines”. If
a station has access to more than one modem, you can specify which one to use—for more
information, use the search function in the IBM® SPSS® Data Collection Developer Library
documentation to search for the text “Settings for the Phone Participants Activity” and in the
search results open the topic with that title.
If you select the option to use modems, the project cannot use an autodialer. Interviewers will
still be able to dial numbers manually if they have access to a telephone keypad. The modem
option works only on Microsoft Windows computers.
Manual – Interviewer dials numbers manually. Interviewers must manually dial the phone
number displayed on the main screen of the Phone Participants activity.
Note: If you select the option to dial phone numbers manually, the project cannot use an autodialer
or modems.
Interviewer to select qualifications: When selected, interviewers will be prompted to select their
qualifications at the start of each session.
Interviewer qualifications control which sample records are allocated to each interviewer and are a
good way of making the best use of your interviewers’ skills. There are two ways of assigning
qualifications to interviewers, which can be used together or separately. Administrators can set
an interviewer’s qualifications when they create IBM® SPSS® Data Collection Interviewer
Server Administration accounts, or interviewers may select their own qualifications at the start of
each interviewing session or during a session.
Depending on how your company uses qualifications, it may be appropriate for administrators to
set some qualifications and for interviewers to be allowed to select others. For example, language
or refusal-conversion qualifications could be set by administrators, while location qualifications
that specify which region an interviewer should call could be set and changed by interviewers
themselves.
Select the qualifications that interviewers may select themselves. Selecting the option but no
qualifications is the same as not selecting the option at all.
Note: Take care when choosing which qualifications interviewers may select, as it is possible
to allow interviewers to select qualifications they do not have. For example, suppose the
administrator has created Sam’s account with a French language qualification. If you allow
interviewers to set the language qualification, Sam will be presented with the full list of languages
and will be able to choose any combination of languages from that list.
161
Base Professional
Show Specific Contact button on the Interviewer screen: When selected, interviewers can retrieve
specific participants from the sample database and the Specific Contact button on the main screen
of the Phone Participants activity is enabled. When interviewers click the button, they are
presented with a dialog box from which they can select whether to retrieve their last contact or
search for a contact. If they choose to search for a contact, they can select the field to search and
specify the value to search for. The choice of fields to search is determined by the settings in the
Show column in Interviewing - Display Fields.
Automatically select next contact: When selected, the interviewing program will automatically
select an interviewer’s next contact; when not selected, interviewers must click a button to
request their next contact.
Interviewers working on projects with this option set will see a check box labeled “Auto contact
selection” just above the list of call outcomes, so it is still possible for some interviewers to work
in fully manual mode if you wish.
Some projects may use a combination of automated and modem or manual dialing. You can still
select the “automatically select next contact” option for these projects, but interviewers who are
using the dialer will need to cancel the “Auto contact selection” check box on the interviewing
screen otherwise they will not be able to stop the dialer making calls when they reach the end of
their shift or need to take a break.
Enable monitoring/recording: When selected, supervisors can monitor and record interviewers
while they are in progress.
Interviewer must get approval for monitoring/recording: When selected, interviewers must obtain
consent for monitoring and recording from each participant.
Depending on your local laws or your organization’s policy, you can configure monitoring for
three different scenarios:
Scenario To Specify This
Monitoring and recording are not allowed for this Clear the Enable monitoring/recording check box.
project
Monitoring and recording are always allowed for Select the Enable monitoring/recording check box
this project and clear the The interviewer must get approval for
monitoring/recording check box.
Monitoring and recording are allowed only if the Select the Enable monitoring/recording and The
participant gives his or her consent interviewer must get approval for monitoring/recording
check boxes.
If you have selected The interviewer must get approval for monitoring/recording, Yes and No options
will appear on the main screen of the Phone Participants activity whenever interviewers retrieve a
contact. As part of their introductory script, interviewers must ask each participant if they give
their consent for monitoring and recording, and record the participant’s answer by selecting either
Yes or No. The three options underneath The interviewer must get approval for monitoring/recording
determine the default settings of the Yes and No options as described below:
Option Description
Interviewer must manually select an option The interviewer must always select either Yes or No.
162
Chapter 1
Option Description
Default setting is ‘monitoring/recording prohibited’ The No option is selected by default. The
interviewer can change the selection.
Default setting is ‘monitoring/recording allowed’ The Yes option is selected by default. The
interviewer can change the selection.
Allow Interviewer to start an interview without a dialer connection to a respondent: When selected,
interviewers are allowed to start interviews without a dialer connection to a respondent.
Interviewing - Review
The Review settings allow you to specify whether interviewers can review the participant’s
responses after the interview has completed.
Figure 1-28
Review settings
Review interview options: The drop-down list provides the following options:
Option Description
No Review The interviewer cannot review interviews.
Review Interview The interviewer can review the whole interview.
Review Open-ends The interviewer can review open-ended (text) responses only.
If you have selected either Review Interview or Review Open-ends, you can then choose between
the following two settings.
163
Base Professional
Show the review button on the Interviewer screen: When selected, the interviewer must click the
Review Completed Interview button in the Phone Participants activity in order to start the review.
Interviewer must review: When selected, the review starts automatically when the interview
finishes.
Telephone - Calling Rules settings
The Calling Rules settings allow you to define specific calling rules for a telephone interviewing
project.
Figure 1-29
Calling Rules settings

Parameters
Ordering
Call Times
Appointments
Overrides
Calling Rules - Parameters
The Parameters settings allow you to specify the amount of time to wait before re-dialing numbers
that are busy, unanswered, or answered by an answering machine.
164
Chapter 1
You set these parameters at the start of the project, and can change them throughout the
interviewing period to match the current requirements of the survey. For example, if it is the last
day of the survey and you are running low on new participants, you might want to increase the
maximum number of times that numbers may be called. You might also wish to reduce the elapse
times for automatically set appointments so that numbers with callbacks become available for
recall more quickly.
Figure 1-30
Calling Rules settings
Time parameters: The table allows you to define the amount of time to wait before attempting to
re-dial samples that meet a specific criteria (no answer, busy, and so on). Enter appropriate values
(in minutes) for each call category.
Give preference to the interviewer who arranged the appointment: When selected, the interviewer
who arranged the appointment is given preference over other available interviewers (as it applies
to scheduling when samples can be retried). If the project uses group/predictive autodialing,
165
Base Professional
the interviewer will not be connected automatically to the participant who has an appointment.
Instead, the participant’s details are displayed on the interviewer’s screen, and the interviewer
must then click the Start Dialing button to dial the participant’s phone number.
Before an appointment, by the arranger only: The number of minutes before a scheduled
appointment that the interviewer, who arranged the appointment, may attempt to retry the
sample.
After an appointment, by any interviewer: The number of minutes after a scheduled appointment
that any available interviewer may attempt to retry the sample.
No preference for appointments: When selected, any available interviewer is allowed to retry the
sample, regardless of who arranged the appointment. This is the default setting.
Before an appointment, by any interviewer: The number of minutes before a scheduled
appointment that any available interviewer may attempt to retry the sample.
Before a recall: The number of minutes before the recall time that a number with an automatic
appointment can be called. The default is ten minutes.
Time zones: The time zones in which participants are located. The values that you enter in this
field must be the indexes of the time zones in the list of time zones stored in the registry. If more
than one time zone is specified, the numbers must be separated by semicolons. If this property is
blank, IBM® SPSS® Data Collection Interviewer Server will ignore time zone and calling times
when selecting records for interviewers to call.
Time Zone Name Displayed As Index Value
Greenwich Standard Time (GMT) Casablanca, Monrovia 90
GMT Standard Time (GMT) Greenwich Mean Time 85
: Dublin, Edinburgh, Lisbon,
London
Morocco Standard Time (GMT) Casablanca -2147483571
W. Europe Standard Time (GMT+01:00) Amsterdam, 110
Berlin, Bern, Rome, Stockholm,
Vienna
Central Europe Standard Time (GMT+01:00) Belgrade, 95
Bratislava, Budapest, Ljubljana,
Prague
Romance Standard Time (GMT+01:00) Brussels, 105
Copenhagen, Madrid, Paris
Central European Standard Time (GMT+01:00) Sarajevo, Skopje, 100
Warsaw, Zagreb
W. Central Africa Standard Time (GMT+01:00) West Central 113
Africa
GTB Standard Time (GMT+02:00) Athens, Istanbul, 130
Minsk
E. Europe Standard Time (GMT+02:00) Bucharest 115
Egypt Standard Time (GMT+02:00) Cairo 120
South Africa Standard Time (GMT+02:00) Harare, Pretoria 140
FLE Standard Time (GMT+02:00) Helsinki, Kyiv, 125
Riga, Sofia, Tallinn, Vilnius
Israel Standard Time (GMT+02:00) Jerusalem 135
166
Chapter 1

Jordan Standard Time (GMT+02:00) Amman -2147483582
Middle East Standard Time (GMT+02:00) Beirut -2147483583
Namibia Standard Time (GMT+02:00) Windhoek -2147483578
Arabic Standard Time (GMT+03:00) Baghdad 158
Arab Standard Time (GMT+03:00) Kuwait, Riyadh 150
Russian Standard Time (GMT+03:00) Moscow, St. 145
Petersburg, Volgograd
E. Africa Standard Time (GMT+03:00) Nairobi 155
Georgian Standard Time (GMT+03:00) Tbilisi -2147483577
Iran Standard Time (GMT+03:30) Tehran 160
Arabian Standard Time (GMT+04:00) Abu Dhabi, 165
Muscat
Caucasus Standard Time (GMT+04:00) Baku, Tbilisi, 170
Yerevan
Azerbaijan Standard Time (GMT+04:00) Baku -2147483584
Mauritius Standard Time (GMT+04:00) Port Louis -2147483569
Armenian Standard Time (GMT+04:00) Yerevan -2147483574
Afghanistan Standard Time (GMT+04:30) Kabul 175
Ekaterinburg Standard Time (GMT+05:00) Ekaterinburg 180
West Asia Standard Time (GMT+05:00) Islamabad, 185
Karachi, Tashkent
Pakistan Standard Time GMT+05:00) Islamabad, Karachi -2147483570
India Standard Time (GMT+05:30) Chennai, Kolkata, 190
Mumbai, New Delhi
Nepal Standard Time (GMT+05:45) Kathmandu 193
N. Central Asia Standard Time (GMT+06:00) Almaty, 201
Novosibirsk
Central Asia Standard Time (GMT+06:00) Astana, Dhaka 195
Sri Lanka Standard Time (GMT+06:00) Sri 200
Jayawardenepura
Myanmar Standard Time (GMT+06:30) Rangoon 203
SE Asia Standard Time (GMT+07:00) Bangkok, Hanoi, 205
Jakarta
North Asia Standard Time (GMT+07:00) Krasnoyarsk 207
China Standard Time (GMT+08:00) Beijing, 210
Chongqing, Hong Kong, Urumqi
North Asia East Standard Time (GMT+08:00) Irkutsk, Ulaan 227
Bataar
Singapore Standard Time (GMT+08:00) Kuala Lumpur, 215
Singapore
W. Australia Standard Time (GMT+08:00) Perth 225
Taipei Standard Time (GMT+08:00) Taipei 220
Tokyo Standard Time (GMT+09:00) Osaka, Sapporo, 235
Tokyo
Korea Standard Time (GMT+09:00) Seoul 230
Yakutsk Standard Time (GMT+09:00) Yakutsk 240
Cen. Australia Standard Time (GMT+09:30) Adelaide 250
167
Base Professional

AUS Central Standard Time (GMT+09:30) Darwin 245
E. Australia Standard Time (GMT+10:00) Brisbane 260
AUS Eastern Standard Time (GMT+10:00) Canberra, 255
Melbourne, Sydney
West Pacific Standard Time (GMT+10:00) Guam, Port 275
Moresby
Tasmania Standard Time (GMT+10:00) Hobart 265
Vladivostok Standard Time (GMT+10:00) Vladivostok 270
Central Pacific Standard Time (GMT+11:00) Magadan, 280
Solomon Is., New Caledonia
New Zealand Standard Time (GMT+12:00) Auckland, 290
Wellington
Fiji Standard Time (GMT+12:00) Fiji, Kamchatka, 285
Marshall Is.
Tonga Standard Time (GMT+13:00) Nuku’alofa 300
Azores Standard Time (GMT-01:00) Azores 80
Cape Verde Standard Time (GMT-01:00) Cape Verde Is. 83
Mid-Atlantic Standard Time (GMT-02:00) Mid-Atlantic 75
Argentina Standard Time (GMT-03:00) Buenos Aires -2147483572
E. South America Standard Time (GMT-03:00) Brasilia 65
SA Eastern Standard Time (GMT-03:00) Buenos Aires, 70
Georgetown
Greenland Standard Time (GMT-03:00) Greenland 73
Montevideo Standard Time (GMT-03:00) Montevideo -2147483575
Newfoundland Standard Time (GMT-03:30) Newfoundland 60
Atlantic Standard Time (GMT-04:00) Atlantic Time 50
(Canada)
Central Brazilian Standard Time (GMT-04:00) Manaus -2147483576
SA Western Standard Time (GMT-04:00) Caracas, La Paz 55
Pacific SA Standard Time (GMT-04:00) Santiago 56
Venezuela Standard Time (GMT-04:30) Caracas -2147483573
SA Pacific Standard Time (GMT-05:00) Bogota, Lima, 45
Quito
Eastern Standard Time (GMT-05:00) Eastern Time (US 35
and Canada)
US Eastern Standard Time (GMT-05:00) Indiana (East) 40
Central America Standard Time (GMT-06:00) Central America 33
Central Standard Time (GMT-06:00) Central Time (US, 20
Canada)
Central Standard Time (Mexico) (GMT-06:00) Guadalajara, -2147483581
Mexico City, Monterrey
Mexico Standard Time (GMT-06:00) Guadalajara, 30
Mexico City, Monterrey - Old
Canada Central Standard Time (GMT-06:00) Saskatchewan 25
US Mountain Standard Time (GMT-07:00) Arizona 15
Mexico Standard Time 2 (GMT-07:00) Chihuahua, La Paz, 13
Mazatlan - Old
168
Chapter 1

Mountain Standard Time (GMT-07:00) Mountain Time 10
(US, Canada)
Mountain Standard Time (GMT-07:00) Chihuahua, La Paz, -2147483580
(Mexico) Mazatlan
Pacific Standard Time (GMT-08:00) Pacific Time (US, 4
Canada), Tijuana
Pacific Standard Time (Mexico) (GMT-08:00) Tijuana, Baja -2147483579
California
Alaskan Standard Time (GMT-09:00) Alaska 3
Hawaiian Standard Time (GMT-10:00) Hawaii 2
Samoa Standard Time (GMT-11:00) Midway Island, 1
Samoa
Dateline Standard Time (GMT-12:00) International Date 0
Line West
Filter interviewers based on their qualifications: When selected, calls are assigned to interviewers
based on interviewer qualifications. For example, if the participant’s native language is Spanish,
then assign the call to a Spanish speaking interviewer.
Calling Rules - Ordering
The Ordering settings allow you to specify the order in which records are retrieved from each
individual queue. For example, you may want to first dial records with a higher number of
attempts when scanning the Recall queue.
169
Base Professional
Figure 1-31
Ordering settings
Ordering records: The table defines the ordering of records, by field, in each queue. Select the
field order from the Field drop-down menus.
Prioritize recalls over fresh. Allows you to specify the frequency in which recalls to busy and
other unanswered calls take priority over calls to new numbers. Specify a percentage to check
the RECALL queue before the FRESH queue. For example, specifying a value of 25% would
result in the RECALL queue being checked before the FRESH queue for one-in-four calls. The
default value is 90%.
Order records within each queue: The table displays the current field order for each queue and
allows you to define which sample fields will be used for ordering the queue records.
Setting Description
Queue The queue name. The names are not modifiable.
170
Chapter 1
Setting Description
Direction The drop-down list provides all sample fields available to its relative queue. Select
an appropriate field from the list.
Sort By The order in which the selected sample field will be sorted. The drop-down list
provides options for Ascending and Descending.
Notes
When queue ordering and field/weight ordering are both specified, queue ordering is used to
resolve parallel ordering.
Records with values for which no order or weight are specified are retrieved last from the
Appointment queue (records are not retrieved from any of the other queues).
Calling Rules - Call Times
The Call Times settings allow you to specify the project’s valid participant call times and day
parts. Day parts allow you to ensure that records are called at specific times of the day in order to
increase the chance of success in reaching participants.
Note: If you have an existing project that uses pre-version 5.6 sample management scripts, you
can setup day parts but they will not be recognized. The use of day parts requires version 5.6 or
higher sample management scripts.
171
Base Professional
Figure 1-32
Call Times settings
Weekday: Allows you to specify valid weekday participant call times:

Start (hh:mm). The earliest time at which participants may be called on weekdays. Enter
an appropriate start time.
End (hh:mm). The latest time at which participants may be called on weekdays. Enter an
appropriate end time.
Weekend: Allows you to specify valid weekend participant call times:

Start (hh:mm). The earliest time at which participants may be called on weekends. Enter
an appropriate start time.
End (hh:mm). The latest time at which participants may be called on weekends. Enter an
appropriate start time.
By default, a weekend runs from 00:01 on Saturday to midnight on Sunday. The Sample
Management script will handle situations where the project has participants in time zones with
different definitions of weekdays and weekends.
Single day part: When selected, the time parameters defined in the Valid participant call times
section are used.
172
Chapter 1
Maximum tries. The maximum number of times that a record may be called. The default is 3. If
an Appointment is made, then an additional “Maximum Tries” tries can be made to connect
the appointment.
Using day parts. When selected, you can utilize an existing day parts template that defines valid
participant call times.
Day parts: The table lists all day parts that are currently defined for the project and allows you
to add new day parts.
Setting Description
Day Part The day part name. Enter an appropriate name.
Tries The maximum number of times that a record may be called. Enter an appropriate
value.
Start Time The earliest time at which participants may be called. Enter the earliest call time.
End Time The latest time at which participants may be called. Enter the latest call time.
Value Enter the appropriate days of the week to contact participants.
Clear Daypart(s). Click to clear any currently defined day part settings in the Day Parts table.
Load Template... Click to load an existing day parts template. Templates are stored in the
Distributed Property Management (DPM). See the “Distributed Property Management (DPM)”
topic in the IBM® SPSS® Data Collection Developer Library for more information.
Save As... Click to save the current settings, listed in the Day Parts table, as a template in DPM. The
Save As... dialog displays, allowing you to specify a template name. Enter an appropriate template
name and click Save. Otherwise click Cancel to return to the Call Times dialog without saving.
Calling Rules - Appointments
The Appointments settings allow you to specify a project expiry date and create appointment
schedules.
An appointment schedule can be used to specify the interviewer shifts and holidays, ensuring that
appointments can be made when interviewers are working. There can be multiple appointment
schedules for a distributed site.
Appointment schedules may differ between projects and are therefore project specific. For
example, interviewers may be scheduled to call business projects during the day and consumer
projects in the evening.
173
Base Professional
Figure 1-33
Appointments settings
Project Expiry (UTC Time). Provides options for specifying a project expiration time.
Appointment Schedule. Provides options for clearing the existing sub-schedules, loading schedule
templates, and saving schedule templates.
174
Chapter 1
Selected template: Displays the name of the currently loaded appointment schedule template.
When a template is not loaded, not using template displays.
Sub-schedules: Lists available sub-schedules.
Creating a new sub-schedule
E Enter an appropriate name in the Sub-schedule field.
Removing an existing sub-schedule
E Right-click the cell to the left of the appropriate sub-schedule name and select Remove.
Regular shifts in sub-schedule: The table lists all shifts currently defined for the selected
sub-schedule.
Creating new shifts for a sub-schedule
E Select a sub-schedule from the Sub-schedule list. If no sub-schedules exist, you must either create
a new sub-schedule or load an appointment schedule template.
E Enter the appropriate shift information in the table.
Setting Description
Days Select the appropriate days of the week to contact participants.
Start Time The earliest time at which participants may be called. Enter the earliest call time.
End Time The latest time at which participants may be called. Enter the latest call time.
Date overrides: The table lists all date override shifts currently defined for the selected
sub-schedule. Date overrides allow you to specify specific dates and/or times where appointments
are not allowed, as well as define specific dates and times that will override the shifts defined
in the Regular Shifts table.
Creating new date overrides for a sub-schedule
E Select a sub-schedule from the Sub-schedule list. If no sub-schedules exist, you must either create
a new sub-schedule or load an appointment schedule template.
E Enter the appropriate date override information in the table.
Setting Description
Type The drop-down menu provides the following options:
No appointment. Select this option when you want to define specific dates and
times where no appointments are allowed
Date override. Select this option when you want to define specific dates and
times that override the shifts defined in the Regular Shifts table.
Date The drop-down menu allows you to select specific no appointment or date override
dates. Select the appropriate date(s).
175
Base Professional
Setting Description
Start Time When No appointment is selected, the starting time at which participants may not be
called. Enter the starting time. When Date override is selected, the earliest time at
which participants may be called. Enter the earliest call time.
End Time When No appointment is selected, the end time at which participants may not be
called. Enter the end time. When Date override is selected, the latest time at which
participants may be called. Enter the latest call time.
Clear Schedule. Click to clear any currently defined sub-schedules.
Load Template... Click to load an existing appointment schedule template. Templates are stored
in the Distributed Property Management (DPM). See the “Distributed Property Management
(DPM)” topic in the IBM® SPSS® Data Collection Developer Library for more information.
Save As. Click to save the current schedule settings as a template in DPM. The Save As... dialog
displays, allowing you to specify a schedule template name. Enter an appropriate schedule
template name and click Save. Otherwise click Cancel to return to the Appointments dialog
without saving.
Calling Rules - Overrides
The Overrides settings allow you to specify the parameters that control dialing for a subset of
records. All records, except those in the specified subset, continue to follow the base dialing rules.
Parameters that can be overridden are:

The maximum number of attempts for a record.
The call back delay for numbers that are not answered, busy, answered by an answering
machine, or started on the web.
In addition, you can specify that a subset of records be identified as having a high priority. High
priority records are generally called before other records. This feature could be used, for example,
if you discover that the completion percentage for a particular subset of records (region for
example) is particularly low. You could indicate that the subset has priority until the completion
percentage reaches the average, at which point you could disable the override.
176
Chapter 1
Figure 1-34
Overrides settings
Prioritize. Select this option when you want the specify that the Selection criteria value be identified
as having priority over other records. High priority records are generally called before other
records
Selection criteria. Identifies the subset of records upon which the override parameters are based.
Enter an appropriate criteria.
Time parameters: The table allows you to specify an override value (in minutes) for specific
delay types:
Delay Type Description
No answer delay The callback delay (in minutes) for numbers that are not answered.
Enter an appropriate value in the corresponding Override (minutes)
cell.
Busy delay The callback delay (in minutes) for numbers that are busy. Enter an
appropriate value in the corresponding Override (minutes) cell.
Answering machine delay The callback delay (in minutes) for numbers that are answered by an
answering machine. Enter an appropriate value in the corresponding
Override (minutes) cell.
Web callback delay The callback delay (in minutes) for surveys that are started on the
Web. Enter an appropriate value in the corresponding Override
(minutes) cell.
Maximum tries (for any day parts). Specifies the maximum number of callback attempts for each
participant. Enter an appropriate value.
177
Base Professional
Telephone - Dialing settings
The Dialing settings allow you to configure autodialer related parameters.

Figure 1-35
Dialing settings

Autodialer
Predictive
Answering Machine Detection
Dialing - Autodialer
The Autodialer settings allow you to define settings that relate to the use of an autodialer. The
autodialer settings are only valid when IBM SPSS Dialer (Extension) – Power dial for the interviewer
screen or IBM SPSS Dialer (Group) – Dial for the interview in a group (with optional predictive dialing)
is selected as a Dialing option in the Interviewer settings.
178
Chapter 1
Figure 1-36
Autodialer settings
Send caller identification: When selected, the caller’s telephone number is transmitted when
the autodialer makes a call.
Phone number to send (leave blank to use dialer’s settings): Enter a valid phone number. The phone
number must contain only the digits 0 to 9, * and # (optionally preceded by a plus (+) to present
the international access code). In addition, the phone number can contain the visual separators
SPACE, (, ), . and -. Visual separators are not allowed before the first digit.
Error if login position is not in configuration: When selected, the Phone Participants activity will not
open on a station with an unrecognized position and an error message will be displayed instead.
When not selected, stations with unrecognized positions can be used to conduct interviews (the
Phone Participants activity will still open), and manual dialing must be used on those stations.
Ring time: Enter the minimum length of time (in seconds) that an unanswered phone call must ring
before the autodialer terminates the call. Make sure that you set a value that allows participants
plenty of time to pick up the phone. In addition, local laws might specify the minimum value that
you must use. The default value is 15 seconds.
Name of silent call announcement file (leave blank to use dialer’s settings): Enter the name of a
wave-sound (.wav) file that contains a message that will be played to the participant when a silent
call occurs (for example, SilentCall.wav). Silent calls can occur when an autodialer generates
more calls than there are interviewers available to handle the calls. The .wav file must be located
in the autodialer’s “audio” folder, the location of which is defined in the autodialer’s dialer.ini file.
179
Base Professional
You can also specify a .wav file that is located in a sub folder of the audio folder by including a
relative path (for example, Projects\MyProject\SilentCall.wav).
Time to try connecting to interviewer: Enter the numbers of minutes that interviewers must wait
to be connected to a participant before the autodialer cancels the connection attempt, allowing
interviewers to leave their stations if they need to. The default value is 10 minutes.
Percentage of calls to record: Enter the percentage of calls that the autodialer will record. Both
individual questions and entire calls are recorded, and the recordings are saved as sound files in
the autodialer’s file system. To record calls, enter a whole number from 0 to 100. To record no
calls or all calls, enter 0 or 100 respectively. The default value is 0.
If you enter any other value, that percentage of calls will be selected at random for recording, with
the following exceptions:
All subsequent calls to a participant whose previous call was recorded will also be recorded.
This includes calls to keep an appointment or calls to complete an interview that was
interrupted by a disconnection.
Calls to participants retrieved by the Specific Contact button are recorded only if that
participant was called previously and that previous call was recorded.
Note that when you change this setting, there might be a delay of up to a minute before the
new value takes effect.
For more information, use the search function in the IBM® SPSS® Data Collection Developer
Library documentation to search for the text “Recording Calls and Interviews” and in the search
results open the topic with that title.
Dialing - Predictive
The Predictive settings allow you to configure the predictive autodialing parameters. When using
predictive dialing, the autodialer dials participants before interviewers are available to answer the
connected calls. That is, the software predicts when interviewers will become available. This
mode can deliver the highest interviewer productivity, but may result in silent calls.
The predictive settings are only valid when the Dialer (Group/Predictive) – Show Start Dialing button
on the Interviewer screen option is selected as the Dialing option in the Interviewer settings.
180
Chapter 1
Figure 1-37
Predictive settings
Initial dialing aggressiveness: The initial “aggressiveness” of the autodialing system when it
calculates the number of predictive calls to make. A higher aggressiveness setting can lead to less
wait time for interviewers, but might result in more silent calls. Enter a whole number between
0 and 100. The default value is 0.
To stop the autodialing system from dialing predictively, set Initial dialing aggressiveness to 0. In
this mode, the autodialer dials participants only when interviewers click the Start Dialing button in
the Phone Participants activity, which is unlikely to result in silent calls.
Maximum percentage of silent calls: The maximum percentage of silent calls that are allowed to
occur in the 24 hour period (since midnight). If the actual rate of silent calls approaches this value,
the autodialing system reduces the current rate of predictive calls to ensure that the maximum
percentage of silent calls is not exceeded. Enter a decimal value between 0 and 100. The default
value is 0.
Target percentage of silent calls: The target percentage of silent calls that should occur at any time.
The autodialing system attempts to keep the actual rate of silent calls at this value by continually
adjusting the current rate of predictive calls. Enter a decimal value between 0 and 100. The value
must be less than the value of Maximum percentage of silent calls. The default value is 0.
181
Base Professional
Dialing - Answering Machine Detection
The Answering Machine Detection settings allow you to configure parameters relating to
answering machine detection.
IBM® SPSS® Data Collection Dialer supports a simple answering machine detection (AMD)
that can be useful when dialing residential numbers. It is based on the observation that human
greetings are usually short, whereas answering machine messages are long. When an auto-dialed
participant record is dialed, and Dialer detects that an answering machine picked up the call, the
call is automatically ended with the Answering Machine call outcome when the IBM® SPSS®
Data Collection Interviewer Server is properly configured to support the feature. Answering
machine detection is currently configured through the DPM Explorer tool.
Figure 1-38
Answering Machine Detection settings
Mode: The answering machine detection mode. Possible values include: Disabled, Filtering, and
Calibration.
Parameters: The table lists the current answering machine detection parameters. All of the
optional parameters (off, max, on, db, and so on) are encapsulated in this property. For example,
max:4.5,on:11 (using commas as the delimiter).
182
Chapter 1
Announcement file: The name of the sound file to play for an answering machine, including the
pathname (relative to AudioDir on the Dialer). You are not required to provide a value for this
setting.
False Positives
False positives are humans that were misinterpreted as answering machines, in which case the
dialer hangs up the call, or plays the amfile. The main causes of false positives are:
The human speaks a long greeting (> max). This typically happens when reaching a business
number. If an amfile file is specified, the respondent will hear it.
The human has loud background noise (permanently above the db threshold). This typically
occurs with car phones. The playback of amfile starts when the AMD algorithm has waited
for end-of-greeting for off seconds. However, this timer needs to be longer than the longest
AM greeting (~30 seconds), so it is unlikely that the respondent will wait long enough
to hear amfile.
Humans can also be misinterpreted as “No audio”. This occurs when:

There is no audio connection (for example, because the battery in the respondent’s phone is
running low). After on seconds without start-of-voice, the dialer hangs up (call outcome:
No audio).
The human picks up the phone but does not start speaking immediately (for example, the
respondent is busy, or due to a disability). After on seconds, the dialer hangs up.
The greeting was spoken very softly (below the db threshold). Usually the respondent speaks
up louder, but if the voice is not raised the dialer hangs up after on seconds. The dialer plays
the amfile to “No audio” numbers unless the setting is disabled by option cp:-S (hangup
immediately if silence).
Qualification Timers
Spoken words contains short gaps in the audio due to articulation. The dialer ignores gaps that are
shorter than a qualification timer qoff; that is, the end-of-voice is asserted when qoff expires.
The dialer utilizes two qualification timers:

qoff, for humans, determines when a call is connected to an interviewer. The settings should
be short (<0.8 seconds); otherwise the respondent might become impatient and hang up.
However, a qoff that is too short causes many false negatives because the timer fails to bridge
well-articulated greetings.
qam, for answering machines, determines when amfile is played. It should be long (>2
seconds), otherwise the playback might start before the answering machine is ready to
record it.
Calibration Mode
Calibration mode is a means to determine the optimum AMD parameters. In calibration mode,
all calls are connected to interviewers (just as when AMD is disabled). The AMD measures
the duration of the respondent’s initial greeting. During this phase, the interviewer can hear
183
Base Professional
the respondent, but cannot talk. When the AMD measurement is finished (end-of-voice), the
interviewer hears a short beep (WBeep) and audio is connected in both directions.
In cases of long initial silence (longer than coff seconds) or persistent voice (longer than con
seconds), the AMD measurement is aborted and audio is connected in both directions. This makes
it possible to try out different values of db and qoff without losing the contacts.
The greet time measured by AMD is sent to the application and recorded in call.log. To determine
the reliability of a given max setting for the AMD call dispositions, make a frequency distribution
of the call outcomes according to the following table:
Interviewer’s Disposition AMD ReportedgreetValue
greet = 0 greet ≤ max greet > max

Human (proceed, False positive? [1] Correct (human) False positive
appointment, refusal,
and so on)
Answering machine Semi-correct (AM) [2] False negative Correct (AM)
[1]greet=0 can be an artifact from using a too small coff value, such that the AMD measurement
was abandoned before the greeting started.
[2]greet=0 starts playback of amfile, but possibly too early, before the answering machine is
ready to record it.
Summary of AMD Modes and Parameters
Syntax: mode , param1 : value , param2 : value2...
Example: amd = 1,qoff:0.40,log:1

Mode Meaning Description
0 Disabled No AMD analysis (but the Call Progress parameter cp is used).
1 Filtering Only “live” calls are through-connected to an interviewer; otherwise the
amfile is played.
2 Calibration Calls are connected in listen-only mode during AMD analysis; the result
is reported in greet.
Name Default Unit Description Action if exceeded Applies to

off 6.0 seconds Max silence at start of Hangup Filtering
call QSAMP_NO_AUDIO
coff 4.5 seconds Max silence at start of Connect two-way Calibration
call audio
max 1.15 seconds Max greeting from Hangup Filtering
human [1] QSAMP_ANSMC
on 60.0 seconds Max greeting from AM Play amfile to AM Filtering
con 3.0 seconds Max greeting measured Connect two-way Calibration
audio
184
Chapter 1
Name Default Unit Description Action if exceeded Applies to

qoff 0.35 seconds Qualification timer for Connect Both
end of voice [2] QSAMP_CON-
NECTED
qam 2.9 seconds Qualification timer for Play amfile Filtering
starting playback
db -34.0 dBm Silence threshold (range Start max timer Both
-46 to -34 dBm) [3]
log 0 0 or 1 If =1, report greet Both
and silence times
(milliseconds) in
call.log[4]
cp Override dialer.ini All
call progress analysis
completion criteria
CpComplete[5]
[1]max recommended range from 0.9 seconds (aggressive, many false positives) to 2.1 seconds
(conservative, many false negatives).
[2]qoff recommended range from 0.3 seconds (many false negatives) to 1.1 (detects most AM, but
connects humans very slowly to an interviewer).
[3]db should be high (insensitive) to avoid detecting people in noisy environments as answering
machines (false positives).
[4]log times are measured on the dialer PC and can differ slightly from the greet times measured
by the DSP.
[4]log times are measured on the dialer PC and can differ slightly from the greet times measured
by the DSP.
[5]cp should normally not be applied for AMD; the only relevant parameter is cp:-S. If persistent
silence is detected, hangup call without playing amfile.
AMD Parameter for Call Progress Analysis
The cp parameter specifies the actions to take when detecting call progress tones, overriding the
default call progress analysis completion criteria CpComplete in the dialer.ini file. Application
areas:
Calling countries with non-standard ringback or “number unobtainable” tones.
Calling networks that announce tariff information at the start of the call.
Calling subscribers with personalized ringback tones (music or announcements).
In order to achieve special effects, such as recording of in-band announcements.
The table below lists the different call progress events. Each event is identified by a letter;
pre-CONNECT events in lower case, post-CONNECT in upper case. Each letter or group of
letters is preceded by an action identifier (see the legend below the table). The post-CONNECT
events are only detected in AMD filtering or calibration mode (amd=1 or amd=2).
Syntax: cp:actionID event... [ actionID event... ] ...
Default: cp:-b-c-d-f!r:t:v-B-C+D-F-T
185
Base Professional
Example: cp:=vea Ignore pre-CONNECT voice events (for instance, personalized ringback tones).
Example: cp:*t*v Record recfile when detecting tritone or start-of-voice (until stopped by noansw
timeout).
Example: cp:+v Connect to extension when detecting start-of-voice.

Def ault Call Outcome if Action is ‘-’ or ‘:’
Call Progress Event pre post
con nect Dialer Interviewer Phone IBM® SPSS®
Quancept™
d Dial tone (steady tone for -d +D QSAMP_BADNUMBER QSAMP_BUSY d_badsyn
>3 s)
r Ringback pulse (duration !r =R QSAMP_RINGING n/a [6] d_error [7]
1.5 - 3 s)
q End of ringback (no pulse =q =Q QSAMP_NOANSW coNoAnswer d_na
for >8 s)
b Busy tone (cadence or -b -B QSAMP_BUSY coBusy d_busy
“precise” tone [8])
c Congested / reorder tone -c -C QSAMP_FASTBUSY coFastBusy d_sitout
(cadence)
t Tritone (Special :t -T QSAMP_TRITONE coTriTone d_sitout
Information Tone)
f Fax/modem tone -f -F QSAMP_MODEM coFaxModem d_modem
v Start of voice (diffuse :v =V QSAMP_ANNOUNCEMT coAnnouncement d_sitout
energy above db dBm)
e End of voice (for qoff =e =E QSAMP_ANNOUNCEMT coAnnouncement d_sitout
seconds)
a Voice for more than max =a =A QSAMP_ANNOUNCEMT coAnnouncement d_sitout
seconds
s Silence; no voice for off n/a =S QSAMP_ANNOUNCEMT coNoAudio d_error [7]
seconds [9]
w Call waiting, ignore voice =w =W QSAMP_BUSY coBusy d_busy
events [10]
Action identifiers:
- Hangup immediately. ! Start noansw timer.
: Hangup if no CONNECT is received within ^ Stop CP analysis (ends AMD, connecting the
two seconds. extension).
+ Connect to extension even if no CONNECT = No action (can be used to override default
was received. actions).
* Start recording (for use with recfile option
beg:3).
[6] Call outcome QSAMP_RINGING does not map to a supported CallOutcome in Interviewer
Phone 5.6.
[7] Call outcomes can be mapped to other tipcode values in section [qsamp map] in the qts-sms.ini
file.
[8] “Precise” tone meaning the 480 + 620 Hz busy tone of the North American Precise Audible
Tones Plan.
186
Chapter 1
[9] Condition S (silence) is only generated in AMD filtering or calibration mode (amd=1 or amd=2).
[10] Condition W (waiting) is generated by signaling events with the action announcemt in
causes.cfg.
Activate Current Project - Quota settings
The Quota settings provide options for specifying the project’s Quota Control parameters.
Note: The Quota node displays under the Activate tree when the Use quota control option is selected
from the Project settings dialog.
Figure 1-39
Quota settings
Create new quota database: Select this option if you are activating the project for the first time, or
if you are reactivating but this is the first time that you have had quota information available. The
exception is when your new project shares quotas with another project. In this case, if the shared
quota database already exists, select the quota database from the list instead.
When a project uses quota control and you activate it for the first time, the activation process
creates a new quota database for the project using the information in the project’s quota definition
(.mqd) file.
The quota database is a set of tables whose names start with QUOTA and which the activation
process creates inside the project database. They contain definitions of the quota groups and their
targets and, once interviewing starts, counts of completed, pending, and rolled back interviews for
each group. The quota definition (.mqd) file is the file that the IBM® SPSS® Data Collection
187
Base Professional
Quota Setup program creates when you save the quota definitions and targets. The activation
process uses the file to determine the structure and content of the quota database it is to create.
The .mqd file is not used during interviewing.
Use existing quota database: If the project has been previously activated with quota, or it shares an
existing quota database with another project, select this option and then select the appropriate
quota database from the drop-down list.
Do not update the quota definitions on the server: When selected, quota definitions on the server
will not be updated.
Publish new quota definitions, but do not update existing quotas: When selected, any new definitions
are updated to the server, but existing definitions on the server remain unchanged.
Update quota with changes made in the project’s mqd file Once a quota database exists, this check
box is always available for selection but is unchecked. If you have made changes to the .mqd file,
select this check box if you want these changes to be implemented in the quota database.
Note: If you have changed quotas using the Quotas activity in IBM® SPSS® Data Collection
Interviewer Server Administration these changes will have been written to the quota database but
will not appear in the project’s .mqd file. If you choose to activate using the .mqd file, the changes
you made with the Quotas activity will be lost. If you want to keep these changes, you will need to
make them in the .mqd file using Quota Setup before reactivating.
IBM SPSS Data Collection Quota Setup
To set up a quota control file for the project, use the Quota Setup program. This is available
from the Start menu by choosing:
All Programs > IBM Corp. > IBM® SPSS® Data Collection 6.0.1 > Accessories > Quota
Follow the instructions in the Quota Setup program’s online help (see the Defining Table Quotas
and Defining Expression Quotas topics). However, when you save a quota definition (.mqd) file
you must save it in a subfolder beneath the questionnaire (.mdd) file (not in the same folder
as the questionnaire file).
Activate Current Project - Advanced settings
The Advanced settings allow you to configure parameters that provide a more detailed level of
control over the activation process.
188
Chapter 1
Figure 1-40
Dialing settings

Page Templates
Files
Tasks
Others
Advanced - Page Templates
The Page Templates settings provides options for defining custom templates in place of some or
all of the default templates.
189
Base Professional
Figure 1-41
Page Templates settings
Use Custom Interview Templates. Select this check box if you want to use your own templates
for any of the listed events.
Custom templates: The table lists the default templates and allows you to define a custom template
or URL for each default template.
Setting Description
Name The default template name. Refer to the ‘Default templates’ section below for
more information.
Type Indicates whether the custom template information is generated from a template
file, or a URL. The drop-down list provides the options None, Template, and URL.
None - when selected, the default template is used.
Template - when selected, a custom template file is used, and the template
name must be specified in the associated Filename/URL cell.
URL - when selected, a custom template URL is used, and the template URL
must be specified in the associated Filename/URL cell.
Filename / URL Identifies the custom template filename or URL. Custom template files must be
present in the project’s source directory, in [INSTALL_FOLDER]\IBM\SPSS\Dat-
aCollection\6\Interviewer Server\Projects, or in a shared location on your
web server. In all cases, you specify the file using a simple filename
(not a path name). When the project is activated, templates that exist in
the project’s source directory will be copied to the project’s directory in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Interviewer Server\Projects.
When interviews take place, the interviewing program will look for the templates
first in the project-specific directory and then in the main Projects directory.
190
Chapter 1
Default templates
Note: You can specify all pages except Authenticate and Authenticate Retry as templates or URLs.
For these two pages we strongly recommend using only templates, as URLs can result in an
interview having two connection IDs.
Template Name Description
Interview stopped The page to display when the participant stops an interview or the interview is
stopped by a statement in the interview script. There is no default template but
IBM® SPSS® Data Collection Interviewer Server displays ‘End of interview.
Thank you for your participation.’
Interview completed The page to display at the end of the interview (that is, when the participant
has answered all relevant questions in the questionnaire). There is no default
page, but Interviewer Server displays ‘End of interview. Thank you for your
participation’.
Note that if the interview ends with a display statement, this text is displayed
as the last page of the interview instead.
Interview rejected The page to display when a participant fails authentication and no retry prompt
is required, for example, when the participant fails quota control. The default
is a template named rejected.htm that displays the message ‘Thank you for
your interest in participating in this survey.’
Authenticate The page to display when an inbound project uses Sample Management, and
you need to verify that the person taking the interview is a member of the
participant group. The default is a template named authenticate.htm that
displays the message ‘Please enter your authentication information’.
Authenticate failed The page to display when authentication fails. The default is a template named
authfailed.htm that displays the message ‘Your authentication information
is incorrect’.
Authenticate retry The page to display when authentication of a prospective participant against
the participant database fails, and you want the participant to reenter the
authentication details. The default page is a template named authretry.htm that
displays the message ‘The authentication information you have entered is
incorrect. Please try again’.
Project inactive The page to display when the participant attempts to start an interview for an
inactive project. The default is a template named projinactive.htm that displays
the message ‘Please come back later’.
Quota full The page to display when the participant belongs in a quota cell whose target
has already been met. There is no default page.
Click Reset if you want to return to the default settings.
Disabling button double-clicks in the default templates
Survey respondents are often presented the option of logging in to complete surveys. After a
respondent enters a user ID and clicks OK, it can sometimes takes a few seconds for the server
to authenticate the user credentials. If a respondent clicks OK a second time, the server may
generate a message similar to the following:
Thank you for your interest in participating in this survey.

A survey is active for your ID. Please continue the original survey or return in 10 minutes to restart.
191
Base Professional
You can avoid this by adding the following script to the header tags for all default templates:
<script language="javascript" defer="true">

function addEvent(target, eventName, handlerName)
{
if (target.addEventListener) // W3C
{
target.addEventListener(eventName, handlerName, false);
return true;
}
else if (target.attachEvent) // IE
{
return target.attachEvent("on" + eventName, handlerName);
}
else
{
target["on" + eventName] = handlerName;
}
}
var ctrlNext;
ctrlNext = document.getElementsByName("_NNext")[0];
function NextClicked()
{
if(ctrlNext != null)
{
setTimeout('ctrlNext.disabled = true;', 1);
}
}
addEvent(ctrlNext, 'click', NextClicked);

</script>
The script prevents additional clicks from registering with the server.
Advanced - Files
The Files settings provides options for excluding specific folders when activating a project.
Excluding specific folders effectively limits the number of files that are uploaded during the
activation process.
192
Chapter 1
Figure 1-42
Files settings
Source files. This non-modifiable field displays the source files location specified in the Project
Settings.
Include sub-folders. When selected, the sub-folders selected in the Sub-folders to include section are
copied to the Shared and Master project folders along with the main project files.
Sub-folders to include: Displays all sub-folders in the current Source files location. Select which
sub-folders will be activated with the project.
Note: This option is only available when the Include sub-folders option is selected.
193
Base Professional
Data Collection files to include. Displays all file types that can be copied when a IBM® SPSS®
Data Collection project is activated. File types not listed will not be activated with the project.
Select which file types will be activated with the project.
Note: You can add files to a project through activation, but you cannot remove files. Deselecting
sub-folders, or Data Collection files to include, will not remove any folders/files from the server.
Advanced - Tasks
The Tasks settings allow you to specify which tasks the activation process will perform. Once
a project has been activated for the first time, this is an ideal way of reducing the time required
for subsequent activations when only certain parts of the activation process need to be run. For
example, if the project does not use Sample Management or Quota Control you can skip these
tasks.
Figure 1-43
Tasks settings
Activate tasks: Specify which tasks the activation process should perform. Tasks are displayed in
a hierarchical structure that can be expanded by clicking the + symbols at the start of each line.
Select the check boxes of the tasks you want the activation process to perform.
194
Chapter 1
Activate project. Run the complete activation process. This is the default and only option
the first time you activate a project (even if that project does not use Sample Management
or Quota Control).
Update project. Run all aspects of the Update Project part of the activation process.
Update project database. Update the information held for this project in the project database.
Update project files. Update the project files (project_name.xxx) for this project.
Update FMRoot. Copy files from FMRoot\Shared into FMRoot\Master.
Update interview server files. Copy files from FMRoot\Master to the Projects folder on all
IBM® SPSS® Data Collection Interviewer Servers.
Update master MDM document. Update the master base language for this project to be the one
specified in Questionnaire Base Language on the Project Settings tab.
Update project in DPM. Update the basic project information held for this project in DPM. If
you are activating the project just to change its status, selecting this task and no others makes
the change in the shortest possible time.
Update sample management. Run all aspects of the Sample Management part of the activation
process.
Update sample management in DPM. Update the Sample Management information held for
this project in DPM.
Update sample management database. Update the CATI Sample Management information held
for this project in DPM.
Update quota. Run all aspects of the Quota Control part of the activation process.
Update quota database. Update the project’s quota database with information about the
project’s Quota Control requirements.
Update quota in DPM. Update the Quota Control information held for this project in DPM.
Update phone interviewing. Run all aspects of the ‘Update Telephone’ part of the activation
process.
Update e-mail jobs. Update the project’s e-mail setup information.
Advanced - Others
The Others settings provides options for defining a destination cluster, reporting setting, and
dialog settings.
195
Base Professional
Figure 1-44
Others settings
Destination cluster: The cluster on which to activate the project. If you are activating a project that
has already been activated — for example, if you have changed and recompiled the questionnaire
— you must activate it on the same cluster that you previously used.
Use a reporting database: When selected, you can identify a reporting database.
Reporting database connection: When Use a reporting database option is selected, this field
displays the connection string to a reporting database. You can manually enter a connection
string or click Edit... to launch the Data Link Properties dialog and construct a connection
string.
Suppress interview template warnings: Select this option if you do not want the activation process
to display warnings if the project’s template files do not contain well-formed HTML.
IBM SPSS Data Collection Activation Console

The IBM® SPSS® Data Collection Activation Console allows you to monitor questionnaire
activation status. The console provides options for viewing pending and completed activations,
and creating activation history filters. The console is composed of the following tabs:
Activation History tab – allows you to view the status of both pending and completed
activations.
Filters tab – provides options for filtering questionnaire activation history.
Settings tab – provides options for configuring the Activation Console.
196
Chapter 1
When the Activation Console is launched, an icon displays in the Windows taskbar. Whenever a
questionnaire is submitted for activation, or completes activation, the icon provides relevant status
notification messages. The notification messages include the survey URL link for each completed
activation. For more information, see the topic Settings tab on p. 198.
Activation History tab

The Activation History tab allows you to view the status of both pending and completed
activations.
Note: In general, you are limited to viewing only your activations.
Pending Activations
The following information is provided:

ProjectIcon – Provides a visual cue for the activation status.
Icon Description
Indicates that project files are currently uploading to the server.
Indicates that the project is pending activation.
Indicates that project activation is currently in progress.
Project – The project name as it appears in IBM® SPSS® Data Collection Interviewer Server
Administration.
Status – The project activation status (pending, processing, success, or failed).
Server – The name of the server to which the questionnaire is being activated.
User – The name of the user who initiated the activation.
Submitted – The time at which the questionnaire was submitted for activation. This is the time
as reported by the IBM® SPSS® Data Collection Interviewer Server.
Select all. Click to select all projects in the Pending Activations list.
Cancel selected. Click to cancel activation for all selected projects.
Completed activations
The following information is provided:

ProjectIcon – Provides a visual cue for the activation status.
Icon Description
Indicates that project activation was successful. You can select the appropriate table row
and click View Message... to view all activation messages.
Indicates that project activation failed. You can select the appropriate table row and click
View Message... to view related activation error information.
197
Base Professional
Project – The project name as it appears in Interviewer Server Administration.

Status – The project activation status (pending, processing, success, or failed).
Server – The name of the server to which the questionnaire is being activated.
User – The name of the user who initiated the activation.
ProcessingServer – The server that performs the activation. In a cluster environment, the server
to which an activation is submitted is not necessarily the server that performs the activation.
StartTime – The time at which the questionnaire was submitted for activation. This is the
time as reported by the Interviewer Server.
EndTime – The time at which the questionnaire completed activation. This is the time as
reported by the Interviewer Server.
Link – The URL for the activated, live questionnaire.
Test Link – The URL for the activated, test questionnaire.
ProjectId – The activated questionnaire project’s unique ID. The ID is generated by the
Interviewer Server.
Refresh. Click to refresh the activation status.
View Messages. Select a completed activation and click to view any messages generated during
activation.
Removing pending activations
E Select the appropriate project(s) from the Pending Activation section. Alternatively you can select
all project by clicking Select all.
E Click Cancel selected or right-click and select Cancel.
Note: You cannot remove activations initiated by other users. You can only remove your own
activations.
Filters tab
The Filters tab provides options for defining how activations are displayed on the Activation
History tab.
Activation type. Displays the status for the current activation. When applicable, the drop-down list
allows you to select which activation types display on the Activation History tab. Options include:
All
Activate – the activation history for activations submitted via the IBM® SPSS® Data
Collection Activation Console.
Launch – the activation history for activations submitted via the IBM® SPSS® Data Collection
Interviewer Server’s Launch activity.
Promote – the activation history for activations submitted via the Interviewer Server’s
Promote Project activity.
198
Chapter 1
Activation history. The drop-down list allows you to select which activations display in the
Activation History tab. Options include:
All
Successful activation
Failed activation
Activation status. The check boxes allows you to select the activation status to display in the
Activation History tab. Options include:
Active
Inactive
Test
Project. Allows you to define specific projects to display in the Activation History tab.
E Click Find to locate questionnaire projects on the Interviewer Server.
E Use the Add>> and <<Remove buttons to select which projects will display in the Activation
History tab.
User. Allows you to define projects, activated by specific users, to display in the Activation
History tab.
E Click Find to locate users on the Interviewer Server.
E Use the Add>> and <<Remove buttons to select which users’ projects will display in the Activation
History tab.
Activation date between. Allows you to select an activation date range. Only activations that
occurred between the specified date will display in the Activation History tab.
E Click Apply to save your settings.
Settings tab
The Setting tab provides IBM® SPSS® Data Collection Activation Console configuration settings.
Activation status run option. The drop-down menu provides options for determining how the
activation console will handle submitted activations:
Start Activation Status when activation queued. The Activation Console begins immediately
after activations are added to the queue. This is the default setting.
Start Activation Console when my computer starts. The Activation Console automatically
begins when the computer is started.
Start Activation Console manually. The Activation Console is manually started.
Default date range. Controls the date range that displays for the Activation date between fields on
the Filters tab.
Activation message range.

199
Base Professional
Show activation notification. When selected, the Activation Console taskbar icon provides
activation notification messages.
Activation auto refresh on/off. When selected, the Activation History tab automatically refreshes
based on the Activation auto refresh interval setting.
Play audible notification. When selected, the Activation Console taskbar icon provides audible
notifications whenever activation messages are generated. The Play this sound file field allows you
to specify a sound file. Click the Browse (...) button to select a sound file.
E Click Save changes to save your settings.
Local Deployment Wizard overview

The Local Deployment Wizard allows you to deploy a survey to one or more IBM® SPSS®
Data Collection Interviewer installations without requiring an IBM® SPSS® Data Collection
Interviewer Server. The wizard provides a simpler alternative to the Activate dialog that is
commonly used to deploy surveys to Interviewer.
The wizard contains the following steps:

Usage options – allows you to select how the project will be used.
Validation options – provides data entry validation options.
Routing options - data entry – provides data entry routing options.
Routing options - live interviewing – provides live interviewing routing options.
Display options – allows you to select which fields are visible in the case data, and select
Deployment options – provides options for deploying the survey to a deployment package or
directly to the local Interviewer installation.
Expiry date and time options – provides options for defining the project expiration data and
time.
Summary options – provides a summary of all selected options prior to starting project
deployment.
Note: If a project was previously activated, the wizard provides the previous activation options. If
a survey was not previously activated, the wizard provides default values.
Usage options
The usage options step allows you to select how the project will be used. Options include:
Data entry (default setting) – select this option when the project will be used for entering
response data from paper surveys.
200
Chapter 1
Live interviewing – select this option when the project will be used to conduct face-to-face
interviewing.
Include subdirectories – select this option if you have subdirectories that include additional
files, such as templates and images.
E After selecting the appropriate usage option, click Next to continue to Validation options (when
Data entry is selected) or Routing options - live interviewing (when Live interviewing is selected).
Validation options
The validation options step allows you to select the data entry validation method. This step is only
available when you select Data entry in the Usage options step.
Options include:
Full validation – when selected, all responses require validation.
Partial validation – when selected, only a subset of responses require validation. Partial
validation is not available for surveys that contain only one routing.
Require two-user validation – when selected, operators are not allowed to validate their own
entries. A second operator is required to validate initial entries.
E After selecting the appropriate validation options, click Next to continue to Routing options -
data entry.
Routing options - data entry
The data entry routing options step allows you specify the routing used for data entry. This step is
only available when you select Data entry in the Usage options step.
E Select the appropriate routing context for each data entry option:
Initial data entry – the drop-down menu provides all available routings.
Full validation – the drop-down menu provides all available routings. This option is only
available when you select Full validation in the Validation options step.
Partial validation – the drop-down menu provides all available routings. This option is only
available when you select Partial validation in the Validation options step.
Note: Partial validation is not available for surveys that contain only one routing.
Notes
You will receive an error when the same routing is selected for Partial validation and Initial
data entry or Full validation.
The Initial data entry and Full validation (if applicable) routing options are automatically selected
when the survey contains only one routing context.
201
Base Professional
Routing options - live interviewing
The live interviewing routing options step allows you specify the routing used for live interviewing.
This step is only available when you select Live interviewing in the Usage options step.
E Select the appropriate routing options for each project task:

Routing – the drop-down menu provides all available routings.
Renderer – the drop-down menu provides all available renderers. The selected renderer
controls which display renderer is used for live interviewing. The default value is Web.
Notes
The Routing option is automatically selected when the survey has only one routing context.
Display options
The display options step allows you to select which fields are visible in the case data, and select
Identify unique surveys with this variable – select an appropriate variable that will be used to
uniquely identify each survey. The drop-down menu provides all user variables that can be
used as unique IDs. Boolean and categorical variables are excluded from this list.
Display fields – select the appropriate display fields. Selected fields are included in the IBM®
SPSS® Data Collection Interviewer Case List. The fields are displayed in the order in which
they appear in the Display fields list. Use Move Up and Move Down to reorder the list.
Notes
Respondent.ID and DataCollection.Status are selected by default.
DataCollection.Status is a required field and cannot be deselected.
E After selecting the appropriate display options, click Next to continue to Deployment options.
Deployment options
The deployment options step allows you to select whether to deploy the survey to a deployment
package or directly to the local IBM® SPSS® Data Collection Interviewer installation.
Options include:
Create a deployment package for this project (default setting) – when selected, the project is
saved as a deployment package, allowing it to be loaded into other Interviewer installations.
Enter a save location in the provided field, or click ... to browse for an appropriate save
location. The deployment package is saved to the location you specify.
202
Chapter 1
Deploy this project to local Interviewer – when selected, the project is deployed to the local
Interviewer installation. This option requires an Interviewer installation on the local machine.
Data file type – allows you to select the deployment package save file format. The drop-down
menu provides the following save file options:
– Data Collection Data File (.ddf)
– Statistics File (.sav)
E After selecting the appropriate deployment options, click Next to continue to Expiry date and
time options.
Expiry date and time options

The expiry date and time step allows you to define the project’s expiration date and time (UTC
time). Defining a project expiration date and time allows interviewers to easily identify expired
projects.
Options include:
E After selecting the appropriate deployment options, click Next to continue to Summary options.
Summary options
The Summary Options step provides a summary of the options selected in each wizard step.
E After reviewing the selected options, click Finish to exit the Deployment Wizard.
If you selected Create a deployment package for this project in the Deployment options step,
the deployment package is saved to the specified location.
If you selected Deploy this project to local Interviewer, the project is deployed to the local IBM®
SPSS® Data Collection Interviewer installation.
Note: If you want to change any of the selected options, click Previous until the appropriate wizard
step displays. After changing the appropriate option(s), click Next until the Summary Options step
displays. Review the selected options, and click Finish.
203
Base Professional
Activation Settings
Using the File Management component
Most users who activate projects using either an IBM® SPSS® Data Collection Interviewer
Server Administration activity such as Launch or a desktop program such asIBM® SPSS®
Data Collection Base Professional have access to the shared FMRoot folder. Users whose
computers are not connected to the network cannot access FMRoot and therefore need to use the
File Management component for activation instead. When you install Base Professional, the
installation procedure asks whether the user has access to FMRoot and configures the user’s
machine accordingly. You can change this manually at any time simply by changing the value of
a registry key.
The registry key is called UseFileManagerWebService and it is located in
HKEY_LOCAL_MACHINE\SOFTWARE\SPSS\COMMON\FileManager. Its default value is
0 meaning that activation will use FMRoot. To use the File Management component instead of
FMRoot, change the value of this key to 1.
Users who do not have access to FMRoot and whose files are copied using the File Management
component may notice that activation run slightly slower than for users with access to FMRoot.
Option to select .sam sample management scripts
The activation procedure does not normally allow users to select sample management scripts
written in VBScript (.sam files). If your company has an overriding requirement to use .sam sample
management scripts with IBM® SPSS® Data Collection projects, you may reinstate the option to
select .sam files by setting the ShowVBScriptProvider key to 1 in the registry. This key is of type
DWORD and is located in \HKEY_LOCAL_MACHINE\Software\SPSS\mrInterview\3\Activate.
If the key is not defined or has a value of zero, .sam files cannot be selected.
Specifying which files are copied during local deployment
The IVFilesToBeCopied registry entry controls which files and file extensions are copied during
local deployment. By default, IVFilesToBeCopied includes the following files and extensions that
are automatically copied during local deployment:
.mdd
.sif
.htm
.html
.xml
.mqd
.gif
.jpg
.jpeg
.png
.mov
204
Chapter 1
.bmp
.avi
catifields_*.mdd
.css
.js
catiCallOutcomes_*.mdd
projectinfo.xml
You can define additional files and/or file extensions by updating the
IVFilesToBeCopied user registry entry. The IVFilesToBeCopied registry entry is
located at: HKEY_CURRENT_USER\Software\SPSS\mrInterview\3\Activate.
The IVFilesToBeCopied rules are as follows:

E When the localdeployconfig.xml file is available, the file’s IVFilesToBeCopied value is used.
E When the localdeployconfig.xml file is not available, the

IVFilesToBeCopied value is retrieved from the user registry
(HKEY_CURRENT_USER\Software\SPSS\mrInterview\3\Activate\IVFilesToBeCopied)
and written to the local config.xml file.
E When the IVFilesToBeCopied user registry key is not found,
IVFilesToBeCopied is read from the local machine key
(\HKEY_LOCAL_MACHINE\Software\SPSS\mrInterview\3\Activate\IVFilesToBeCopied),
copied to the current user registry key
(HKEY_CURRENT_USER\Software\SPSS\mrInterview\3\Activate\IVFilesToBeCopied), and
then written to the local config.xml file.
Note: Registry key changes will not take effect until you manually remove any existing references
to IVFilesToBeCopied in the local config xml file. For example:
<?xml version="1.0" encoding="utf-8" ?>
<properties>
<IVFilesToBeCopied> <![CDATA[mdd;*.htm;*.html;*.xml;mqd;*.gif;*.jpg;*.jpeg;*.png;*.mov;*.bmp;*.avi;catifields_*.mdd;*.css;*.js;catiCa
</properties>
The default local activation directory is C:\Documents and Settings\<your Windows user
name>\Application Data\IBM\SPSS\DataCollection\Activate.
Data Management Scripting

This section provides documentation for the using IBM® SPSS® Data Collection Base
Professional to perform various data management-related tasks. The following table provides a
summary of the documentation in this section.
What’s new in IBM SPSS Data Collection Base Notes about what has changed in this section
Professional 6.0.1
Data Management Overview A brief introduction to data management scripting.
205
Base Professional
Getting Started A step-by-step guide to help you get started with

data management scripting.
Understanding the Process Flow A number of diagrams that illustrate the process
flow when a DataManagementScript (DMS) file
is run.
Data Management Script (DMS) File Includes a detailed reference to the
DataManagementScript (DMS) file, an
overview of filtering data, and several examples.
DMS Runner Explains how to use the DMS Runner command
prompt utility to run your DMS files.
Transferring Data Using a DMS File An introduction to transferring data to and from
various formats.
Working with IBM SPSS Data Collection Provides information about using a DMS file to
Interviewer Server Data export IBM® SPSS® Data Collection Interviewer
Server data to other formats.
Merging Case Data Explains how to use a DMS file to combine the
case data from two or more data sources into a
single data source.
Data Cleaning An introduction to cleaning data and several
examples that illustrate using the DMS file to clean
data.
Working with the Weight Component Provides detailed information about the different
methods of calculating weighting, and includes
the formulae used by the Weight component and
several detailed examples.
Creating New Variables An introduction to creating different types of
variables.
Analyzing a Tracking Study Describes how you can use data management
scripting and other IBM® SPSS® Data Collection
and SPSS technologies to analyze the response data
from your tracking studies.
Table Scripting in a Data Management Script Covers the aspects of table scripting that are
specific to DMS files and provides some examples
of scripting tables in a DMS file.
Data Management Functions Provides information for Data Management
(DMOM) functions.
Data Management Troubleshooting and FAQs Tips and answers to some common problems and
queries.
WinDMSRun Provides information about WinDMSRun, which
is a sample Windows application that comes with
the IBM® SPSS® Data Collection Developer
Library. You can use WinDMSRun to set up and
run your DMS files. WinDMSRun also has a
handy feature that enables you to view the input
and output data. The Visual Basic .NET source
code of WinDMSRun is provided as a reference
for programmers.
Samples Includes details of the numerous sample DMS and
related files that come with the Data Collection
Developer Library.
Data Management Reference This provides detailed reference information about
the Data Management (DMOM) and Weight
component object models.
206
Chapter 1
Data Management Overview
IBM® SPSS® Data Collection Base Professional includes a number of components that facilitate
various data management tasks, including:
Transferring data. You can transfer data from one format or location to another. For example, when
you collect data using IBM® SPSS® Data Collection Interviewer Server, it is stored in a relational
MR database and you can use a DataManagementScript (DMS) file to transfer the data to an SPSS
.sav file so that you can analyze it using SPSS.
Merging data. You can use a DataManagementScript (DMS) file to combine the case data from
two or more data sources into a single data source. For example, if the case data for your survey
has been collected in separate data sources, you may want to merge the data before cleaning
and analyzing it.
Filtering data. You can use filters to restrict the transfer to certain variables or respondents. For
example, you might want to create filters to restrict the transfer to specific variables that record
demographic details and to include respondent data only if the interview was completed in the last
24 hours.
Cleaning data. This involves correcting errors and anomalies in the case data. For example,
checking whether more than one response has been selected for each single response question, and
if so, marking the case as requiring review or taking some action to correct the problem such as
randomly selecting one of the responses and removing the others. When cleaning data, it is usual,
but not necessary, to store the “clean” data separately so that the original data remains intact.
Setting up weighting. This involves creating special weighting variables that can be used to weight
data during analysis; for example, so that it more accurately reflects the target population.
Creating new variables. You can define filter variables and other derived variables, which can then
make analysis easier. For example, if a questionnaire asked respondents to enter their exact age as
a numeric value, you may want to create a derived categorical variable that groups respondents
into standard age groups.
Scripting tables. If you have IBM SPSS Data Collection Survey Reporter Professional, you can
create batch tables using a script.
Data Management Infrastructure
You define your data management tasks using a DataManagementScript (DMS) file. The
DMS file is a text file with a .dms filename extension. It is easy to read and edit a DMS file
that defines simple data management tasks, such as copying data from one location to another,
even if you have little or no programming experience. If you are an advanced user and have
some programming or scripting expertise, the DMS file makes it possible to define complex and
advanced data management tasks.
207
Base Professional
The DMS file does not use a new language, instead it acts as a container for a number of
industry-standard languages:
Property definitions. The DMS file uses a simple INI file-like syntax to initialize property
settings.
SQL syntax. Used in the DMS file for queries and other operations that are implemented by the
OLE DB provider. The SQL syntax that you can use depends upon which OLE DB provider
you are using. For example, when you are using the IBM SPSS Data Collection OLE DB
Provider you can use any SQL syntax that is supported by the IBM® SPSS® Data Collection
Data Model, provided that it is also supported by the DSC through which you are accessing
the data. Refer to the SQL Syntax topic in the IBM® SPSS® Data Collection Developer
Library for more information.
mrScriptMetadata. Used in the DMS file to define new variables in the metadata.
mrScriptMetadata is a proprietary SPSS syntax that provides a fast and easy way of creating
metadata using a script.
mrScriptBasic. Used in the DMS file for defining procedural code for cleaning data, setting
up weighting, etc. mrScriptBasic is based on Visual Basic and Visual Basic Scripting
Edition (VBScript), and if you know these languages, you will find mrScriptBasic easy to
learn. However, unlike Visual Basic and VBScript, mrScriptBasic provides native support
for market research data types and expression evaluation.
In addition, IBM® SPSS® Data Collection Base Professional includes the following:
Base Professional IDE. Integral to Base Professional is an integrated development environment
(IDE) that enables you to create, edit, run, and debug IBM® SPSS® Data Collection scripts.
For more information, see the topic Using IBM SPSS Data Collection Base Professional
on p. 11.
DMS Runner. A command line tool for running a DMS file. For more information, see the topic
DMS Runner on p. 289.
Data Management Object Model (DMOM). A set of component objects that are designed
specifically to facilitate data transformations. These objects are generally called from
mrScriptBasic in the DMS file. For more information, see the topic DMOM Scripting
Reference on p. 501.
Weight component. A set of component objects for creating rim, factor, and target weighting.
Like the DMOM objects, the weight objects are generally called from mrScriptBasic in the
DMS file. For more information, see the topic Working with the Weight Component on p. 406.
Table Object Model (TOM). A set of component objects for creating market research tables.
TOM is available only if you have purchased the Base Professional Tables Option. For more
information, see the topic Table Scripting on p. 1140.
Samples. The Data Collection Developer Library comes with numerous sample DMS files
that you can use as templates. For more information, see the topic Using the Sample DMS
Files on p. 466.
208
Chapter 1
Getting Started
Getting started with data management scripting can be challenging because it uses technologies
(like SQL syntax, mrScriptBasic, and mrScriptMetadata) which you may not have used before.
In addition, data management scripting is powerful and can accomplish many different data
management tasks and procedures. This makes it hard to know where to start. However, you don’t
have to master all of the technologies to start using data management scripting and you can
build up your knowledge step by step.
This section is designed to help you get started with data management scripting. It walks you
through some simple tasks and gives you some ideas on how to build up your knowledge. This
section is designed to be used in conjunction with the other documentation and it contains many
links to other topics and sections. The links are there for your convenience. However, you can
ignore them if you find them distracting.
You may often find it helpful to read the next and previous topics in the table of contents, although
you may want to come back and do that later. If you follow a link and decide you want to return
to where you were, just click the Back button on the toolbar.
The topics in this section are:

1. Running Your First Transfer
2. Setting up a Filter
3. Transferring Different Types of Data
4. Using an Update Query
5. Running Your First Cleaning Script
6. Mastering mrScriptBasic
7. Learning about Weighting
8. Mastering mrScriptMetadata
9. Getting To Know the Samples
10. Where Do I Go From Here?
1. Running Your First Transfer
At the heart of data management scripting is the DataManagementScript (DMS) file. This is a
text file with a .dms filename extension that defines a data transformation job. At its simplest, a
DMS file can define a simple transfer from one data format or location to another. The IBM®
SPSS® Data Collection Developer Library comes with several sample DMS files, including
MyFirstTransfer.dms, which is similar to the simple example described in Simple Example of a
DMS File. You can use this file to transfer to an IBM® SPSS® Statistics .sav file the first 100
records in the Museum sample IBM SPSS Data Collection Data File that comes with the Data
The sample file is called MyFirstTransfer.dms and by default it is installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS folder.
209
Base Professional
E Let’s open the file in IBM® SPSS® Data Collection Base Professional now:
Before you run the file, check that it is set up correctly for your computer:
The connection string in the InputDataSource section (highlighted in red) defines the name,
location, and type of the data you want to transfer. If the sample files have not been installed
into the default location, you will need to edit the Location and Initial Catalog connection
properties accordingly.
The connection string in the OutputDataSource section (highlighted in blue) defines the
name, location, and type of the target data. Check that the location exists on your computer
and if not, edit the Location connection property accordingly. (If a .sav file exists with the
same name in the specified location, move the existing .sav file to a different folder before
you run the transfer.)
The Path parameter in the Logging section defines the location for the log file. Check that this
location exists on your computer, and if not edit the parameter accordingly.
E Now let’s run the file. To do this, choose Start Without Debugging from the Debug menu.
E Now click the Output tab (this is typically in the lower part of the Base Professional window), to
bring the Output pane to the front.
210
Chapter 1
Provided that the sample files are present and in the specified locations, and there is not already
a .sav file of the same name and in the same location as that specified in the OutputDataSource
section, this is what you should see in the Output pane:
“The transformation completed successfully” message means that the transfer has been successful.
If you now go to the target location folder in Windows Explorer, you should see three new files:
MyFirstTransfer.sav. This is an SPSS Statistics .sav file that should contain the first 100 records
from the Museum sample IBM SPSS Data Collection Data File. If you open this file in SPSS
Statistics, you will notice that the variable names are different. This is because the long
names that can be used in the IBM® SPSS® Data Collection Data Model are not valid in
SPSS Statistics and some of the variables (such as multiple response variables) are handled
differently in SPSS Statistics. The DMS file uses the Data Model data source components
(DSCs) to read and write the data for the transfer. SPSS Statistics SAV DSC is used to write
the data to the .sav file. For more information, see the topic Transferring Data to IBM SPSS
Statistics on p. 342.
MyFirstTransfer.sav.ini. This file contains a setting that defines the language to be used when
reading the .sav file that has just been created, for example, if the .sav file is used as the input
data source in another data management script. Refer to the Language Handling by the SPSS
Statistics SAV DSC topic in the Data Collection Developer Library for more information.
MyFirstTransfer.sav.xml. This file contains additional information for use by SPSS WebApp.
Refer to the SPSS WebApp XML File topic in the Data Collection Developer Library for
more information.
MyFirstTransfer.mdd. This is a Metadata Document (.mdd) file for the transfer. If you want to
use the .sav file in IBM® SPSS® Data Collection Survey Tabulation, performance will be
better if you access the .sav file using this file.
In the next topic, 2. Setting up a Filter, you will learn how to set up a filter to restrict the variables
that are included in the transfer.
211
Base Professional
2. Setting up a Filter
In the simple DMS file we looked at in 1. Running Your First Transfer, the following line is
included in the InputDataSource section:
SelectQuery = "SELECT * FROM vdata WHERE Respondent.Serial < 101"
This is called the select query and it is where you specify the filter for the transfer. A filter is
a way of defining a subset of the data to be transferred. The filter can restrict the variables that
are included in the transfer, or the case data records, or both. In this query, the line WHERE
Respondent.Serial < 101 specifies that case data records should be included in the transfer only
if their serial number is less than 101. Respondent.Serial is a special variable (called a system
variable) that is present in most IBM® SPSS® Data Collection data and which stores the
respondent’s serial number.
Now let’s change the filter to restrict the transfer to a few specific variables and different case
data records. Doing this will change the MyFirstTransfer.dms sample file, so you may want
to make a backup copy of it first.
E If its not already open, open MyFirstTransfer.dms in IBM® SPSS® Data Collection Base
Professional and change the line shown above to:
SelectQuery = "SELECT age, gender, education, remember FROM VDATA _
WHERE gender = {female}"
This filter will restrict the transfer to the four named variables (age, gender, education, and
remember) and case data records for female respondents only.
If we use this filter for the transfer, the structure of the data will not match the structure of the
data we transferred before. If we try to export it to the same .sav file, we will get an error. So
before you run the transfer, you need to move or delete the files created by the previous export, or
specify a different name for the output files. We will change the name of the output files. To do
this, change the OutputDataSource section as follows (the changes are highlighted):
OutputDataSource(myOutputDataSource)
ConnectionString = "Provider=mrOleDB.Provider.2; _
Data Source=mrSavDsc; _
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTransfer2.sav"
MetaDataOutputName = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTransfer2.mdd"
End OutputDataSource
E Now save the file with a new name, for example MyFirstTransfer2.dms.
E Now press Ctrl+F5 to run the transfer without debugging, and click the Output tab, so that you can
see the Output pane.
E If you have IBM® SPSS® Statistics, use it to open the .sav file after the transfer has finished.
You will see that this time only the variables in the select query have been transferred. However,
a number of numeric variables have been created for the remember variable, because it is a
multiple response variable. If you have the SPSS Statistics Tables add-on module, you will see
that a multiple response set called $remembe has also been created for this variable. Refer to the
212
Chapter 1
Variable Definitions When Writing to a .sav File topic in the IBM® SPSS® Data Collection
Developer Library for more information.
E If you are new to writing SQL queries, refer to the Basic SQL Queries, Running the Example
Queries in DM Query, and DM Query topics in the Data Collection Developer Library.
Note that you can copy queries in DM Query and paste them straight into your DMS files. Paste
the query after the equal sign like this:
SelectQuery = "<Paste the query here>"
For more information, see the topic Filtering Data in a DMS File on p. 243.
In the next topic, 3. Transferring Different Types of Data, you will learn how to transfer other
types of data.
3. Transferring Different Types of Data
Generally DMS files use the IBM® SPSS® Data Collection Data Model and its data source
components (DSCs), to read and write data in different formats. DMS files can also transfer data
using OLE DB providers that are not part of the Data Model. However, this topic provides an
introduction to transferring different types of data using the Data Model and its DSCs.
For an introduction to the Data Model, see the Data Model topic in the IBM® SPSS® Data
For an introduction to DSCs and information about the DSCs that are supplied with the Data
Model, see the Available DSCs topic in the Data Collection Developer Library.
You can use a DMS file to transfer data from any format for which you have a suitable
read-enabled DSC to any format for which have a suitable write-enabled DSC.
In this topic you will learn how to set up a DMS file to transfer the Museum sample IBM® SPSS®
Quanvert™ database to a IBM SPSS Data Collection Data File (.ddf). This transfer utilizes the
Quanvert DSC to read the Quanvert database and the IBM SPSS Data Collection Data File CDSC
to write the IBM SPSS Data Collection Data File.
213
Base Professional
Let’s look at MyFirstTransfer2.dms file in IBM® SPSS® Data Collection Base Professional again.
Note that this topic assumes that you have created the MyFirstTransfer2.dms file as described in
the 2. Setting up a Filter. If you haven’t already done that, create the file now, so it looks like this:
The InputDataSource section (highlighted in red) is where you define the details that relate to the
data you want to transfer.
The OutputDataSource section (highlighted in blue) is where you define the details that relate to
the target data.
It is the ConnectionString parameter in each of these sections that defines the name and location
of the data and the DSC and other options that you want to use. You can type in the connection
string by hand, but you must be careful to spell all of the connection properties and file and path
names correctly. Refer to the Connection Properties topic in the Data Collection Developer
However, there is an easier way of setting up the connection string, and that is to use the Base
Professional Connection String Builder. Let’s do that now for the InputDataSource section:
E In the InputDataSource section, delete the value of the connection string (shown below):
Data Source=mrDataFileDsc; _
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.ddf; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.mdd"
Your connection string should now look like this:
ConnectionString = ""
E Keeping the cursor between the quotation marks, choose Connection String Builder from the Tools
menu.
This opens the Connection Tab in the Data Link Properties dialog box, with the Provider tab
already set up to use the IBM SPSS Data Collection OLE DB Provider.
214
Chapter 1
E From the Metadata Type drop-down list, select Quanvert Database.
E Enter the Metadata Location of the Museum sample Quanvert database. You can either type the
name and location of the Quanvertqvinfo file into the text box or click Browse and select the file
in the Open dialog box. By default the Museum sample Quanvert database is installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum folder.
E From the Case Data Type drop-down list, select Quanvert Database.
E Enter the Case Data Location of the Museum sample Quanvert database exactly as you entered it
in the Metadata Location text box.
E Click OK.
This inserts the connection string at the cursor position. Now your InputDataSource section
should look like this:
InputDataSource("My input data source")

Data Source=mrQvDsc; _
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\qvinfo; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\qvinfo; _
MR Init MDSC=mrQvDsc"
SelectQuery = "SELECT age, gender, education, remember FROM VDATA _
End InputDataSource
215
Base Professional
To make the connection string easier to read, we have added line continuation characters
so that we can place each property on a separate line, like the original connection string in
MyFirstTransfer.dms. For more information, see the topic Breaking Up Long Lines in the DMS
file on p. 247. However, if you prefer you can leave the connection string on one very long line.
You may notice that some of the connection properties were not present in the original connection
string that you deleted. This is because you do not need to specify connection properties whose
default values are being used.
Now let’s set up the connection string for the OutputDataSource section for the export to the
IBM SPSS Data Collection Data File:
E Delete the connection string in the OutputDataSource section.
E Without moving the cursor, choose Connection String Builder from the Tools menu.
Again, this opens the Connection Tab in the Data Link Properties dialog box, with the Provider
tab already set up to use the IBM SPSS Data Collection OLE DB Provider.
E From the Metadata Type drop-down list, select (none).
E From the Case Data Type drop-down list, select IBM SPSS Data Collection Data File (read-write).
E Enter the Case Data Location for the new IBM SPSS Data Collection Data File. You can either
type the name and location of the file into the text box or click Browse and browse to the location
in the Open dialog box.
E Select the Advanced tab.

216
Chapter 1
E Select Allow dirty data. This specifies that we want the case data to be validated, but we want to
accept data even if it contains some errors and anomalies.
E Click OK.
This inserts the connection string at the cursor position.
E Now edit the MetadataOutputName parameter in the OutputDataSource section, to give the output
metadata file a different name (such as MyFirstTransfer3.mdd) so that when we run the file, the
new metadata won’t overwrite the metadata that was created for the .sav file in the previous topic.
E Save the file with a new name, such as MyFirstTransfer3.dms.
E Now run MyFirstTransfer3.dms.
You can use similar techniques to set up connection strings for different types of transfer. For
more information, see the topic Transferring Data Using a DMS File on p. 310.
4. Using an Update Query
You can optionally use an update query in the InputDataSource section and the OutputDataSource
section to add, delete, or update case data records. Note that you can use an update query only
if the CDSC that is being used can write case data and supports this type of operation (that is,
the Can Add and Can Update properties are both True for the CDSC—for more information, see
Supported Features of the CDSCs in the IBM® SPSS® Data Collection Developer Library).
217
Base Professional
In 2. Setting up a Filter, we learned how to write SQL query statements to filter the data. Update
queries use a different type of SQL statement, called data manipulation statements. The
following data manipulation statements are supported by the IBM® SPSS® Data Collection
Data Model:
INSERT. Use to add new case data records.
UPDATE. Use to change existing case data records.
DELETE. Use to delete case data records.
E Follow the links above to find out more about these SQL statements and use DM Query and the
Museum sample IBM SPSS Data Collection Data File (.ddf) to try out the examples.
E Now create the following DMS file, which contains two update queries:
InputDataSource(myInputDataSource, "My input data source")

SelectQuery = "SELECT * FROM VDATA _
WHERE Respondent.Serial < 101"
UpdateQuery = "DELETE FROM vdata _
WHERE DataCollection.Status = {Test}"
End InputDataSource
OutputDataSource(myOutputDataSource, "My output data source")

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\UpdateQuery.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\UpdateQuery.mdd"
UpdateQuery = "UPDATE vdata _
SET DataCollection.FinishTime = Now()"
The update query in the InputDataSource section uses an SQL DELETE statement to delete the test
data. A WHERE clause is used to filter the case data records on the DataCollection.Status system
variable. Note that you should use update queries in the InputDataSource section of your DMS
files with extreme care, because the update query will modify the input data source irreversibly.
The update query in the OutputDataSource section uses an SQL UPDATE statement and the
function to set the value of the DataCollection.FinishTime system variable to the current time.
E Now try running this example.
5. Running Your First Cleaning Script
Data cleaning is the process by which you correct errors and anomalies in the case data. Typically
you clean the data using mrScriptBasic code in the OnNextCase Event section. mrScriptBasic
is based on Visual Basic Scripting Edition (VBScript), which is in turn based on Visual Basic,
and if you are familiar with either of these languages, you will find mrScriptBasic easy to pick
up. This topic does not go into detail about mrScriptBasic, but rather walks you through a simple
218
Chapter 1
cleaning script and shows you how to examine the results. The script is designed as a taster
rather than as a “real life” example.
We will look at and run the MyFirstCleaningScript.dms file, which is similar to the Cleaning.dms
file described in 1. More Than One Response To a Single Response Question in the Data Cleaning
section. However, it has been modified to deliberately introduce a number of errors into a copy
of the Museum XML sample data, which are then “cleaned” in the OnNextCase Event section.
Without these modifications, the cleaning script would not change the data because the Museum
sample data is generally clean.
E Let’s start by opening the MyFirstCleaningScript.dms in IBM® SPSS®

Data Collection Base Professional. By default, the file is installed into the
Notice that the InputDataSource section contains the following update query:
UpdateQuery = "UPDATE vdata SET interest = {Birds, Fossils}, _

expect = expect + {12, 13, 14}, _
when_decid = when_decid + {129, 130, 131, 132, 133}, _
age = age + {1, 2, 3} _
This updates the first 10 case data records in the input data source with additional responses to
four questions (interest, expect, when_decid, and age). This will make the answers to these
questions incorrect because they are all single response questions and so should have only one
response each. More than one response to a single response question is typical of the type of
error that data cleaning attempts to correct.
Now let’s look at the OnNextCase Event section in MyFirstCleaningScript.dms to see how these
four questions are cleaned.
219
Base Professional
Base Professional has an option to show the line numbers on the left side. If this option isn’t
selected, you may want to switch it on. For more information, see the topic IBM SPSS Data
Collection Base Professional options on p. 101.
When an error is encountered in the code when it is validated or run, Base Professional displays a
message that includes the line number. For example, the message for an error that occurs in the
OnNextCase Event section on line 41 would look something like this:
Event(OnNextCase,"Clean the data")mrScriptEngine parse error:
Parser Error(41): ...
Using the option to display the line numbers makes it easy to locate the line on which the error
occurred. For more information, see the topic Debugging on p. 46.
MyFirstCleaningScript.dms shows several different ways of cleaning single response data that
contains more than one response. However, the function is always used to test whether more than
one response has been selected for the question. The AnswerCount function is part of the , all of
whose functions are automatically available to mrScriptBasic.
Lines 43-45 test whether the interest question has more than one response and if so, replaces
them with the Not answered response.
Lines 47-49 replace any multiple responses to the expect question with a predefined default.
Lines 51-53 test whether there are multiple responses to the when_decid question, and if so uses
the function to select one of the responses at random and remove the rest.
220
Chapter 1
Lines 55-59 handles multiple responses to the age question by setting the DataCleaning.Status
system variable to Needs review and adding a message to a text string and the DataCleaning.Note
system variable. Note that line 41 has already set up the text string to contain the respondent’s
serial number (Respondent.Serial system variable) and line 68 writes the text to a report file.
Lines 63-65 illustrate another way of handling a single response question that has more than
one response, and that is to delete the record from the output data source. This is done for the
gender question and to illustrate this, the response to this question is made multiple response for
one case data record (for which Respondent.Serial has a value of 11) in the OnNextCase Event
section in lines 61-62.
E Now let’s run the DMS file.
E Now we will use DM Query to examine the clean data. For instructions on setting up DM Query
to do this, see the How to Run the Example Queries in DM Query Using the Museum Sample
topic in the IBM® SPSS® Data Collection Developer Library. However, remember to select the
output data source files (MyFirstCleaningScript.mdd and MyFirstCleaningScript.xml) rather than
the installed Museum sample files.
E Enter the following query into the text box in DM Query:
SELECT Respondent.Serial, interest, expect, when_decid,

age, gender, DataCleaning.Note, DataCleaning.Status
FROM vdata
Here are the results for the first 15 case data records:
First let’s study the first ten rows. These represent the case data records for which the update query
inserted additional responses for the interest, expect, when_decid, and age questions. As expected,
the multiple responses in the interest and expect columns have been replaced with Not_answered
and general_knowledge_and_education respectively. The multiple responses in the when_decid
column have been replaced by one response selected randomly. The responses in the age column
are unchanged, but we can see that the text has been written to the DataCleaning.Note variable
and the DataCleaning.Status variable is set to needsreview. Also, notice that, as expected, there is
221
Base Professional
no Respondent.Serial with a value of 11, because this is the record for which the gender variable
was given two responses and so the case was deleted from the output.
If you open the MyFirstCleaningScript.txt report file, you will see that the Age needs checking
text has been written for the first ten respondents. You can open the text file in Base Professional
or in a text editor, such as Notepad.
E To find out more about data cleaning, read the Data Cleaning section, which includes a general
introduction to data cleaning, an overview of using a DMS file to clean data, and examples of how
to handle many common data cleaning requirements.
The next topic, 6. Mastering mrScriptBasic, gives ideas about how to go about learning
mrScriptBasic.
6. Mastering mrScriptBasic
In the previous topic, 5. Running Your First Cleaning Script, we looked at a simple example of
using mrScriptBasic to clean the case data. You use mrScriptBasic to write procedural code in
the Event sections of your DMS file. There are a number of possible Event sections, each one
being processed at a different time during the execution of the DMS file. Therefore each one is
suitable for different types of tasks. For more information, see the topic Event Section on p. 273.
However, the Event sections are not compulsory and there are many data management tasks that
you can achieve without using an Event section.
mrScriptBasic is based on Visual Basic Scripting Edition (VBScript), which is in turn based on
Visual Basic. However, the syntax of mrScriptBasic has a number of differences from VBScript
and Visual Basic. If you plan to write only very simple mrScriptBasic code, you may be able to
meet your needs by simply modifying the sample DMS files that are provided with the IBM®
SPSS® Data Collection Developer Library. However, if you plan to write more complicated
procedures, you will probably find you make faster progress if you spend some time learning
mrScriptBasic outside of a DMS file. This topic provides some suggestions on how to do that.
E If you are new to scripting or programing with objects, start by working through , in the
mrScriptBasic section.
E Then read the other introductory topics in the . These give you an introduction to mrScriptBasic,
and describe the main syntax differences between mrScriptBasic and VBScript and Visual Basic.
222
Chapter 1
E Now follow the steps in Creating Your First mrScriptBasic Script. This topic introduces you to the
features in IBM® SPSS® Data Collection Base Professional that help you write mrScriptBasic
scripts and explain how to run an mrScriptBasic file in Base Professional.
E Now run the examples described in . The examples are installed with the Data Collection
Developer Library as sample mrScriptBasic files. Refer to the Sample mrScriptBasic Files topic in
the Data Collection Developer Library for more information.
E Take the time to read the topics on each of the examples because they draw attention to many
things that you need to look out for when you start writing mrScriptBasic code.
E Now read Debugging to learn about the features in Base Professional that you can use to help
you debug your mrScriptBasic files.
E Now try creating some mrScriptBasic files of your own and running them. For example, you could
try and recreate in mrScriptBasic some of the Visual Basic examples shown in MDM Tutorial
topic in the Data Collection Developer Library.
E While you are doing this, refer to and make full use of the debugging features.
E Before you start writing mrScriptBasic code in the Event sections of your DMS files, take the
time to study the following topics:
Using Objects in the Event Sections. Describes which objects are automatically registered
with the mrScriptBasic engine in the various Event sections.
Event Section. Describes the various Event sections and provides links to topics on each one.
These topics contain a number of examples.
Data Cleaning Examples. Provides a number of examples of using mrScriptBasic in the
OnNextCase Event section to clean data.
Note: The IBM® SPSS® Data Collection Data Model comes with the , which provides an
alternative way of running mrScriptBasic files. It also provides a number of debugging features.
7. Learning about Weighting
Weighting is another term for sample balancing. You use weighting when you want the figures
in your table to reflect your target population more accurately than the actual figures do. For
example, suppose your target population consists of 57% women and 43% men, but you
interviewed 50% women and 50% men for your survey. By applying weighting, you can make the
women’s figures count for more than the men’s figures, so that they more accurately reflect the
gender distribution in the target population.
IBM® SPSS® Data Collection Base Professional includes the IBM® SPSS® Data Collection
Weight component, which enables you to set up weighting in your data. In this topic we will look
at and run the Weighting.dms file. This sets up weighting based on equal numbers of male and
female respondents.
E Let’s start by opening the Weighting.dms file in Base Professional. By default, the file is installed
into the [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS
folder.
223
Base Professional
Notice that this DMS file contains a Metadata Section:
Metadata (enu, Analysis, Label, Input)

Weight "Weighting based on gender balance"
Double usagetype("Weight");
End Metadata
This creates in the output data source a numeric variable, called Weight, to hold the weighting
information that we will set up using the Weight component in the OnJobEnd Event Section
section.
Here is the OnJobEnd Event section code that calls the Weight component and sets up weighting
in the Weight variable that we defined in the Metadata section:
Event(OnJobEnd, "Weight the data")

Dim WgtEng, Wgt, fso, ReptFile
Set WgtEng = dmgrJob.WeightEngine
' Create an html file to contain the weighting report...
Set fso = CreateObject("Scripting.FileSystemObject")

Set ReptFile = _
fso.CreateTextFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\WeightingReport.htm", _
True)
' Create an instance of the Weight object with the following parameters:
' "Weight" is the variable of type Double that was created in the
' metadata section.
' "gender" is the variable that stores the characteristics on
' which we wish to base the weighting.
' wtMethod.wtTargets defines the weighting method as target weighting.
Set Wgt = WgtEng.CreateWeight("Weight", "gender", wtMethod.wtTargets)
' Define a two cell weighting matrix with a target of 301 for
' each value of the gender variable...
Wgt.CellRows.Targets = "301; 301"
' Call the WeightEngine.Prepare method and then write the

' weighting report to the html file...
WgtEng.Prepare(Wgt)
ReptFile.Write(Wgt.Report)
' Call the WeightEngine.Execute method, which will insert the

' calculated weight values in the Weight variable. Then
' write the weighting report to the html file...
WgtEng.Execute(Wgt)
224
Chapter 1
ReptFile.Close()
' Setting WgtEng to Null ensures that the connection to the

' output data source is closed and that any pending data
' updates are flushed...
set WgtEng = Null

End Event
E Now run the Weighting.dms file.
E If you have the Base Professional Tables Option, you can use the DMSWeightedTables.mrs table
scripting sample mrScriptBasic file to create two tables of Age by Gender, the first unweighted
and the second weighted using the Weight variable we have just set up. (If you don’t have the
Base Professional Tables Option, you can use DM Query instead as described below.) To run the
DMSWeightedTables.mrs sample:
1. Open the DMSWeightedTables.mrs file in Base Professional. (The table scripting sample files are
typically installed into the [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables
folder.)
2. Press Ctrl+F5 OR choose Start Without Debugging from the Debug menu.
Here is the unweighted table:
Here is the weighted table:

225
Base Professional
E Notice that in the unweighted table there are 339 male and 263 female respondents in the Base
row, whereas in the table weighted using the Weight variable there are equal numbers of male and
female respondents in the Base row.
E If you do not have the Base Professional Tables Option, create equivalent tables in DM Query.
Refer to the How to Run the Example Queries in DM Query Using the Museum Sample topic in
the IBM® SPSS® Data Collection Developer Library for more information.. However, remember
to select the output data source files (Weighting.mdd and Weighting.ddf) rather than the installed
Museum sample files.
E To create the unweighted table, enter the following into the text box:
SELECT groupby.col[0] AS Age,

SUM(gender = {male}) AS Male,
SUM(gender = {female}) AS Female
FROM vdata
GROUP BY age ON age.DefinedCategories()
WITH (BaseSummaryRow)
Here are the results:
E To create the weighted table in DM Query, enter the following into the text box:
SELECT groupby.col[0] AS Age,

SUM((gender = {male}) * Weight) AS Male,
SUM((gender = {female}) * Weight) AS Female
FROM vdata
GROUP BY age ON age.DefinedCategories()
WITH (BaseSummaryRow)
226
Chapter 1
Here are the results:
The difference in decimal precision is because the Base Professional Tables Option post-processes
the results. Refer to the Advanced SQL Queries topic in the Data Collection Developer Library
Note that you could include code in the OnAfterJobEnd Event section in your DMS file to set up
the tables. For more information, see the topic OnAfterJobEnd Event Section on p. 285.
The Weight component automatically creates a weighting report. The OnJobEnd Event section
contains the following line:
This writes the report to an HTML file called Weighting.htm.
E Let’s open the weighting report file now. To do this, in Windows

Explorer go to the location of the weighting report file (typically this is
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output) and double-click
WeightingReport.htm.
This opens the file in your default browser:

227
Base Professional
For more information, see the topic Weighting Report on p. 412.
E To find out more about weighting, read the Working with the Weight Component section, which
includes a general introduction to weighting, details of the various weighting methods and their
formulae, and examples of using each of the weighting methods. Note that most of the examples
are in the form of mrScriptBasic (.mrs) files. The final topic in the Working with the Weight
Component section, Setting Up Weighting in a DMS File, explains the changes you need to make
to the examples to incorporate them into a DMS file.
The next topic, 8. Mastering mrScriptMetadata, gives ideas about how to go about learning
mrScriptMetadata.
8. Mastering mrScriptMetadata
In 7. Learning about Weighting, we used a line of mrScriptMetadata to create a numeric variable

in the output data source to hold the weighting information. The mrScriptMetadata was in the
Metadata section , which is an optional section in a DMS file for creating new questions and
variables. Typically, you would use this to create filters and other derived variables for use during
analysis. However, the DMS file does not limit you in the type of metadata you can create. You
define the metadata using mrScriptMetadata, which has been designed as a fast and easy way
of creating metadata using a script.
If you are planning to use the Metadata section to create anything other than the simplest variables,
you may find it helpful to spend some time familiarizing yourself with mrScriptMetadata outside
of a DMS file. This topic provides some suggestions for how to do that.
E Start by reading the topics in the . These give you an introduction to mrScriptMetadata and
describe how you can open an mrScriptMetadata file in IBM® SPSS® Data Collection Metadata
Model Explorer.
E Refer to the mrScript MDSC topic in the IBM® SPSS® Data Collection Developer Library.
mrScript MDSC can convert an mrScriptMetadata file into an MDM Document and an MDM
Document into an mrScriptMetadata file.
E The Data Collection Developer Library comes with some sample mrScriptMetadata files. Follow
the instructions in the second topic in the User’s Guide to open these files in MDM Explorer.
E Now try creating some mrScriptMetadata files of your own and opening them in MDM Explorer.
For example, you could try to recreate some of the questions in some of the sample .mdd files.
Refer to the Sample Data topic in the Data Collection Developer Library for more information.
E You can also open the sample .mdd files in MDM Explorer to see an mrScriptMetadata
representation of the various metadata objects.
E While you are doing this, refer to the .
E Before you start writing mrScriptMetadata code in your DMS files, take the time to study the
topics in the Creating New Variables section.
228
Chapter 1
9. Getting To Know the Samples
The IBM® SPSS® Data Collection Developer Library comes with a number of sample DMS files
that have been set up to demonstrate many common data management tasks. Most of these sample
files have been designed to run straight “out of the box” on the sample data that also comes with
the Data Collection Developer Library. However, if you did a custom installation, you may need
to modify the file locations specified in the samples before you run them. Some of the samples
require other software to be installed as well as IBM® SPSS® Data Collection Base Professional.
For example, some of the samples require one or more of the Microsoft Office applications, such
as Word, Access, or Excel. Below you will find links to topics that list the samples. These topics
provide a brief explanation of each sample and explain any special requirements.
The sample DMS files are divided into five groups:

Sample DMS Files. These demonstrate many basic features like transferring data to and
from various data formats, cleaning data, setting up weighting, creating new variables, using
the IBM® SPSS® Data Collection Metadata Model to Quantum component to set up card,
column, and punch definitions, etc.
Sample DMS Files For Exporting IBM SPSS Data Collection Interviewer Server Data.
These samples have been designed to demonstrate exporting IBM® SPSS® Data Collection
Interviewer Server data that has been collected using multiple questionnaire versions. All of
these samples use the Short Drinks sample database, but they can be adapted easily to run with
any multiversion project. You need access to an SQL Server installation and appropriate user
access rights to run these samples. You also need to restore the Short Drinks sample. Refer to
The Short Drinks Sample topic in the Data Collection Developer Library for more information.
Sample DMS Files That Integrate with Microsoft Office. These demonstrate some advanced
features, such as transferring data from an Access database, setting up tables and charts in
Excel and topline tables in Word.
Table Scripting Sample Data Management Scripts. These provide some examples of scripting
tables in a DMS file. To run these samples, you need to have Base Professional Tables Option
installed. Some of the samples have additional requirements.
Sample DMS Include Files. These are Include files that can be reused in other DMS files.
You can use the sample DMS files as a starting point when you develop your own DMS files.
However, it is recommended that you work on a copy of the samples rather than the samples
themselves. An easy way of doing this is to copy the entire folder to another location on your
computer and then work on the copies in the new location. This means you will avoid losing your
work when you uninstall or upgrade to a new version of the Data Collection Developer Library
and it will be easy to refer back to the original samples when necessary.
This topic includes some suggestions for how to make the most of the sample files. However,
some of the sample files use the Include file and text substitution features. So before you begin to
look at the samples, read the topics that explain these features:
Using Include Files in the DMS file
Using Text Substitution in the DMS file
229
Base Professional
Now, start by studying the lists of sample files and make your own list of which ones seem most
relevant to your work. For each of the samples on your list, do the following:
E Open the sample in Base Professional. Look at each section and try to work out what it means.
Refer to the relevant parts of the documentation. (Note that the topics that list the samples include
handy links to relevant documentation.)
E If the sample uses one or more Include files and/or text substitutions, use the /a: and /norun options
in DMS Runner to save the expanded file. For example, if you change the path in the command
prompt to the folder where the sample DMS files are installed, you could use the following to
save the expanded MDM2QuantumExtra.dms sample to a file called MyExpanded.dms, without
running it:
DMSRun MDM2QuantumExtra.dms /a:MyExpanded.dms /norun
E Now open the expanded file in Base Professional and study it. The expanded file shows the file as
Base Professional and DMS Runner “see” it after all of the text substitutions and Include files
have been implemented. The line numbers shown in error messages always refer to the line
numbers in the expanded file. Note that any comments that appeared between the sections in the
original will not appear in the expanded file.
E Now use Base Professional or DMS Runner to run the sample on the sample data.
E Use the tools at your disposal to study the output of the transformation. How you do this depends
on the type of output. For example, examine report, log, and error files in a text editor. For output
data types that can be read by the IBM® SPSS® Data Collection Data Model, you could open the
relevant output files in IBM® SPSS® Data Collection Paper or IBM® SPSS® Data Collection
Survey Tabulation if you have them. Alternatively you could use DM Query to look at the case
data and MDM Explorer to look at the metadata.
E Now try modifying a copy of the sample to run on your own data. However, make sure that you
do not use any of the features (such as update queries in the InputDataSource section or the
UseInputAsOutput feature) that will actually change the input data until you are sure that is
what you want to do.
The Data Collection Developer Library also comes with the executable file and Visual Basic .NET
source code for WinDMSRun, which is a simple Windows tool that you can use to set up and run
simple DMS files. If you are a programmer who wants to develop applications that use the Data
Management Object Model (DMOM), you may want to use the source code as a reference. For
more information, see the topic WinDMSRun as Programmer’s Reference on p. 309.
10. Where Do I Go From Here?
If you have followed the steps in this Getting Started guide, you should now have an idea of what
you can achieve using a DMS file. You may also be aware of how much there is still to learn.
You may want to sit down now and read through the Data Management Scripting section of the
IBM® SPSS® Data Collection Developer Library. However, this approach may not suit everyone,
and you may prefer to wait until you have a specific problem you want to solve. However, if you
230
Chapter 1
do decide to ait before reading much more, it is still a good idea to browse through the contents of
the Data Management Scripting section, so that you have an idea of the material that it covers.
Notice that the Data Management Reference section provides detailed documentation of all of
the properties and methods of all of the Data Management Object Model (DMOM) and Weight
Component objects. However, you are not restricted to using these objects in your Event section
code. You can use any objects that are registered on your computer, including the objects that are
part of the various IBM® SPSS® Data Collection Data Model components.
You may therefore want to spend some time familiarizing yourself with the structure of the Data
Collection Developer Library, particularly:
. This provides detailed documentation of mrScriptBasic, mrScriptMetadata, and the IBM
SPSS Data Collection Function Library.
Data Model Reference topic in the Data Collection Developer Library. This provides detailed
documentation of the main object models that are part of the Data Model, including the MDM
and IBM® SPSS® Data Collection Metadata Model to Quantum Component object model
documentation, which you may want to use in your Event section code.
It will almost certainly be in your interest to spend some time learning how to make the most of
the Data Collection Developer Library. Read the Getting the Most Out of the DDL section and
practice using the Index and Search features. When you find a topic that is useful, click the
Contents tab to see which section it is in. This will help you understand how it fits into the bigger
picture and to find related topics.
For example, suppose you want to write advanced Event section code using the Metadata Model
to Quantum component and you want to know whether the component has a method for writing
the data map to a .csv file. If you just type “MDM2Quantum” into the search field, the search will
return many topics. You could narrow the search by typing “MDM2Quantum AND csv”.
The search will now return fewer topics because it will return only those that contain both
“MDM2Quantum” and “csv”. If you look through the topics that are returned, you will see one on
the MDM2Quantum.WriteToCommaSeparatedFile method. This topic describes a method of the
Metadata Model to Quantum component that writes the data map to a .csv file.
If you click the topic in the list and then click the Contents tab, you will then see that the topic is
located in the Methods section of the Metadata Model to Quantum object documentation, which is
in the Data Model Reference section. You will notice that there are topics on each of the Metadata
Model to Quantum object’s other methods and properties in the same section.
You could also have reached the Metadata Model to Quantum Component documentation using
the index. For example, by entering “Metadata Model to Quantum component” into the index
keyword text box and then selecting the Metadata Model to Quantum Component, Overview
subentry. Using the index is sometimes quicker than using the search. However, the search is
useful when the index does not lead you to what you are looking for.
If you prefer to use printed documentation, you can easily print individual topics or all of the
topics in a section.
231
Base Professional
Understanding the Process Flow

This section provides a number of diagrams that illustrate various aspects of DMS file processing:
DMS File Flow. Provides a simplified representation of the processing that is performed
when you run a standard DMS file.
DMS File Flow When You Use the UseInputAsOutput Option. Provides a simplified
representation of the processing that is performed when you run a DMS file that uses the
UseInputAsOutput option.
DMS File Flow In a Case Data Only Transformation. Provides a simplified representation of
the processing that is performed when you run a DMS file that operates on case data only,
either because you have not specified an input metadata source or because you are using a
provider that is not part of the IBM® SPSS® Data Collection Data Model to read the data.
DMS File Flow When Operating on Metadata Only. Provides a simplified representation of
the processing that is performed when you run a DMS file that operates on metadata only.
Example Timeline. A timeline that represents the processing of a hypothetical DMS file.
DMS File Flow
The following diagram provides a simplified representation of the processing that is performed
when you run a standard DMS file. The diagram is intended to show the sequence in which the
various parts of the file are executed. However, some parts of the file are optional. For example,
the input and output data source update queries are optional as are the GlobalSQLVariables
section and the OnBeforeJobStart, OnAfterMetaDataTransformation, OnJobStart, OnNextCase,
OnBadCase, OnJobEnd, and OnAfterJobEnd Event sections.
The numbers from 1 (at top of diagram) to 13 (at bottom) indicate the sequence in which the
processing takes place. Scroll down below the diagram for notes on each numbered step.
For a diagram that illustrates the processing of a hypothetical job in the form of a timeline, see
Example Timeline.
232
Chapter 1
1. The OnBeforeJobStart Event Section is processed first. This is typically used to set up card
and column allocations in the input data source’s metadata in a job that exports case data to a
IBM® SPSS® Quantum™ .dat file.
233
Base Professional
2. The GlobalSQLVariables Section can optionally be used to exchange information between the
output and input data source. This is useful when you are transferrring case data in batches and
want to transfer only records that have been collected since the last batch was transferred.
3. The Update Query defined in the InputDataSource Section can be used to add, update, or delete
case data in the input data source and is typically used to remove unwanted test data. However,
note that this should be used with caution because the input data source is updated irreversibly.
4. The metadata specified in the connection string in the InputDataSource section is merged with
the metadata defined in the Metadata section, if there is one. The merged metadata is then made
available to the input data source so that any new variables (from the Metadata section) that have
been included in the Select Query statement will be returned by the query.
5. The merged metadata is then filtered according to the filter defined in the Select Query in the
InputDataSource section and written to the output metadata file defined in the OutputDataSource
section.
6. The OnAfterMetaDataTransformation Event Section is run after the metadata merge is complete
and is typically used to set up card, column, and punch definitions in the new variables created in
the Metadata section.
7. The output case data source is created (if it does not already exist) and synchronized with
the output metadata.
8. The OnJobStart Event Section is run before the processing of the individual cases and is typically
used to set up global variables that are required in the OnNextCase and OnBadCase sections.
9. The OnNextCase Event section is processed for each case included in the transfer and is
typically used to clean the case data.
10. The OnBadCase Event section is processed for each case that has failed validation and will not
be transferred to the output data source, and is typically used to create a report of bad cases.
11. The OnJobEnd Event section is run after the processing of the last case has been completed
and is typically used to close report files and set up weighting using the Weight component.
12. The Update Query defined in the OutputDataSource section can be used to add, update, or
delete case data in the output data source.
13. The OnAfterJobEnd Event section is processed after all other processing has finished. This is
typically used to set up tables or to e-mail a report or notification.
234
Chapter 1
DMS File Flow When You Use the UseInputAsOutput Option
when you run a DMS file using the UseInputAsOutput option. Note that this option should be
used with caution because the input data source is updated irreversibly.
You can specify the UseInputAsOutput option in one of the InputDataSource sections, in
which case you do not need an OutputDataSource section in your DMS script. If you are
using the IBM® SPSS® Data Collection Data Model to read the case data, you can specify
the UseInputAsOutput option only if the CDSC for that data source supports the updating
of existing records. You must also set the MR Init MDM Access connection property to 1 in
the InputDataSource section to open the data source for read/write access or when operating
in validation mode.
The diagram is intended to show the sequence in which the various parts of the file are executed.
However, some parts of the file are optional. For example, the update query is optional as are
the OnBeforeJobStart, OnAfterMetaDataTransformation, OnJobStart, OnNextCase, OnBadCase,
OnJobEnd, and OnAfterJobEnd Event sections.
235
Base Professional
1. The OnBeforeJobStart Event Section is processed first.
case data in the input data source and is typically used to remove unwanted test data.
3. The metadata specified in the Metadata section is merged with the metadata specified in the
connection string in the InputDataSource section. The merged metadata is then made available
to the input data source so that any new variables (from the Metadata section) that have been
included in the Select Query statement will be returned by the query.
4. The OnAfterMetaDataTransformation Event Section is run after the metadata merge is complete.
236
Chapter 1
5. The OnJobStart Event Section is run before the processing of the individual cases and is typically
used to set up global variables that are required in the OnNextCase and OnBadCase sections.
6. The OnNextCase Event section is processed for each case included in the transfer and is
typically used to clean the case data.
7. The OnBadCase Event section is processed for each case that has failed validation and will not
be transferred to the output data source, and is typically used to create a report of bad cases.
8. The OnJobEnd Event section is run after the processing of the last case has been completed and
is typically used to close report files and set up weighting using the Weight component.
9. The OnAfterJobEnd Event section is processed after all other processing has finished. This is
typically used to set up tables.
DMS File Flow In a Case Data Only Transformation
when you run a case data-only transformation, either because you have not specified an input
metadata source or because you are using an OLE DB provider that is not part of the IBM®
SPSS® Data Collection Data Model to read the data.
The diagram is intended to show the sequence in which the various parts of the file are executed.
However, some parts of the file are optional. For example, the update queries are optional as are
the OnBeforeJobStart and OnAfterJobEnd Event Event sections. Note that you cannot use an
OnAfterMetaDataTransformation, OnJobStart, OnNextCase, OnBadCase, or OnJobEnd Event
section in a case data-only transformation.
237
Base Professional
2. The GlobalSQLVariables Section can optionally be used to exchange information between the
output and input data source. This is useful when you are transferrring case data in batches and
want to transfer only records that have been collected since the last batch was transferred.
case data in the input data source.
4. The case data is filtered according to the select query specified in the InputDataSource section.
5. The output data source is created based upon the variables specified in the select query in the
InputDataSource section.
238
Chapter 1
6. The case data specified in the select query is transferred to the output data source.
7. The update query specified in the OutputDataSource Section can be used to add, update, or
delete case data in the output data source.
8. The OnAfterJobEnd Event section is processed after all other processing has finished. This
can be used to set up tables.
DMS File Flow When Operating on Metadata Only
when you run a DMS file that operates on metadata only. The diagram is intended to show the
sequence in which the various parts of the file are executed. However, some parts of the file
are optional.
239
Base Professional
2. The metadata is filtered according to the select query specified in the InputDataSource Section.
3. The metadata specified in the Metadata section (if any) is merged with the filtered metadata to
give the output metadata.
4. The OnAfterMetaDataTransformation Event Section is processed after the merge is complete.
5. The OnAfterJobEnd Event section is processed after all other processing has finished. This can
be used to export a IBM® SPSS® Quancept™ script.
240
Chapter 1
Example Timeline
The following diagram is a timeline that represents the processing of a hypothetical DMS file,
which is described below.
InputDataSource section. This includes:

ConnectionString. Defines a connection to a relational MR database that stores dirty data
collected using IBM® SPSS® Data Collection Interviewer Server and IBM® SPSS® Data
Collection Paper - Scan Add-on.
UpdateQuery. Deletes all test data from the database.
SelectQuery. Selects a subset of variables that are suitable for analysis and all completed
non-test cases.
Metadata section. This defines a numeric variable to be used to hold weighting defined using the
Weight component in the OnJobEnd Event section, and a number of filter and banner variables
that will be required during analysis.
OutputDataSource section. This includes:

ConnectionString. Defines a connection to the data source that will receive the clean case data.
This could be a new or existing, file or database.
MetaDataOutputName. Defines the name and path of the new .mdd file that will define the
structure of the output data source.
OnBeforeJobStart Event section. This defines card and column specifications in the input data
source for use when transferring case data to a IBM® SPSS® Quantum™ .dat file.
OnJobStart Event section. Sets up various global variables that are required in the OnNextCase and
OnBadCase Event sections, including a text file for reporting purposes.
OnNextCase Event section. This section contains cleaning code that will be applied to each case
that is included in the transfer.
OnBadCase Event section. This section contains reporting code that will be executed for each case
that has failed validation and will not be transferred to the output data source.
241
Base Professional
OnJobEnd Event section. Closes the report file and uses the Weight component to set up weighting
in the numeric variable defined in the Metadata Section.
Data Management Script (DMS) File
The Data Management Script (DMS) file is a text file with a .dms filename extension, which defines
a data transformation job. The DMS file provides a scalable solution to your data management
tasks. For example, at its simplest, a DMS file can define a simple transfer from one data format or
location to another. A more complex example would be a DMS file that includes complex cleaning
algorithms, that sets up several different types of weighting and a number of filter and banner
variables for use during analysis, and transfers a subset of the case data to three different formats.
You can create a DMS file using IBM® SPSS® Data Collection Base Professional or a standard
text editor, such as Notepad. When using a text editor, if the file contains non-Western European
characters, make sure that you save it using the Unicode or UTF-8 text format option and not
the ANSI option.
This section defines the syntax of the DMS file and provides some examples. The conventions
used for defining the syntax are similar to those used in the IBM® SPSS® Data Collection
Scripting section.
This section includes:

Simple Example of a DMS File
Filtering Data in a DMS File
Breaking Up Long Lines in the DMS file
Comments in the DMS file
Sections in the DMS file
Tips
If you are new to DMS files, try working through the Getting Started Guide, if you haven’t
already done so. For more information, see the topic Getting Started on p. 208.
The IBM® SPSS® Data Collection Developer Library comes with WinDMSRun, a sample
Windows application for generating, validating, and running a simple DMS file. For more
information, see the topic WinDMSRun on p. 300.
The Data Collection Developer Library comes with numerous sample DMS files, which you
can use as templates. For more information, see the topic Using the Sample DMS Files
on p. 466.
242
Chapter 1
The Data Management Troubleshooting and FAQs section provides tips and answers to some
common problems and queries.
The Understanding the Process Flow section provides some diagramatic representations of
the order of processing the various sections in the DMS file in different situations (such
as a typical standard transformation, using the UseInputAsOutput option, a case data-only
transformation, and when operating on metadata only).
Simple Example of a DMS File
This topic provides an example of a very simple DMS file, which transfers all of the case data
stored in a IBM SPSS Data Collection Data File to a IBM® SPSS® Statistics (.sav) file. This
example demonstrates the minimum contents of a DMS file, which must contain the following
sections:
InputDataSource Section. Defines the location and format of the data that you want to transfer.
(This example contains only one input data source. However, you can define more than one
InputDataSource section in a DMS file when you want to merge data.)
OutputDataSource Section. Defines the location and format to which you want to transfer the
data. (This example contains only one output data source. However, you can define more than
one OutputDataSource section in a DMS file. When you do this, the data will be transferred to
each of the specified output data sources.)
InputDataSource(myInputDataSource)
End InputDataSource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Simple.sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Simple.mdd"
It is recommended that you also include a Logging Section in your DMS file. This means that
details of any problems will be written to a log file, which is useful when trying to track down the
cause of any problems that occur.
Logging(myLog)
Path = "c:\temp"
Group = "DMGR"
Alias = "Tester"
FileSize = 500
End Logging
243
Base Professional
Note: This example is provided as a sample DMS file (called Simple.dms) that is installed with the
IBM® SPSS® Data Collection Developer Library. For more information, see the topic Sample
DMS Files on p. 467. For step-by-step instructions on running a DMS file, see 1. Running
Your First Transfer.
Filtering Data in a DMS File
Filters enable you to perform a data transformation on a subset of the data in a data source. For
example, when you transfer data you may often want to transfer some, but not all, of the data.
This topic describes some typical scenarios.
Metadata Filter
When you export data to a particular format for analysis (such as IBM® SPSS® Statistics .sav or
IBM® SPSS® Quantum™ .dat), you may want to exclude from the export all of the variables that
will not be useful to the analysis that you are planning. You may also want to aggregate existing
variables to a new variable (helpful when performing analysis). You can achieve this by defining a
metadata filter that defines the variables to include, or aggregate, in the export.
In the DMS file, you define a metadata filter by specifying in the select query defined for the input
data source the variables that you want to include or aggregate.
Note: Since version 5.6, the Data Management Object Model (DMOM) will check for duplicate
select variables in query strings. As a result, the following example would result in the error
Duplicate select variable: Age when transformation starts:
SelectQuery = "SELECT Person.(Age, Age, Name) FROM HDATA"
1. Filtering metadata via a VDATA query
The following InputDataSource section defines a metadata filter that specifies seven variables that
will be included in the data transformation:
ConnectionString = ...
SelectQuery = "SELECT age, gender, education, _
interest, rating, remember, signs FROM VDATA"
End InputDataSource
2. Filtering metadata from one level via an HDATA query
The following InputDataSource section defines a metadata filter that specifies three variables,
from the Person level, that will be included in the data transformation:
SelectQuery = " SELECT Name, Age, Trip FROM HDATA.Person"
End InputDataSource
244
Chapter 1
3. Filtering metadata from different levels via an HDATA query
The following InputDataSource section defines a metadata filter that specifies one variable from
the parent level, one variable from current level, and one variable from the children level, that
will be included in the data transformation:
SelectQuery = "SELECT ^.address, Name, _
Trip.(Country) FROM HDATA.Person”
End InputDataSource
4. Creating new variables using an expression or aggregation
The following InputDataSource section defines a metadata filter that specifies one aggregation and
one expression that will create new variables in the data transformation:
SelectQuery = "SELECT sum(visits+visits12) as 'total visits', _
name+address as person FROM HDATA"
End InputDataSource
5. Selecting a grid slice via a VDATA or HDATA query
The following InputDataSource section defines a metadata filter that specifies two grid slices
in the data transformation:
SelectQuery = "SELECT Person[3].tvdays[channel_1].column as NewGridSlice1, _
Person[1].Age, Person[3].tvdays[channel_1].column FROM HDATA"
End InputDataSource
The first grid slice will be changed to a normal field after transformation (it has been renamed).
The second grid slice will remain at its HDATA level structure after transformation (it has not
been renamed).
6. Renaming with a metadata filter
Using metadata filtering, you can rename a variable, expression, aggregation, or gird slice.
SelectQuery = "SELECT ^.Pets, _
^.address as HomeAddress, _
Name as ‘Person Name', _
Age+Weight as ‘PersonWeight', _
SUM(Age+Gender) FROM HDATA.Person"
End InputDataSource
245
Base Professional
The resulting output metadata is:

Household_Pets (Auto renamed)
HomeAddress;
Person_Name (Auto renamed)
PersonWeight
SUM_Age_Gender_ (Auto renamed)
The system will automatically rename if any of the following conditions are met:
The user specified a new name, but it does not meet variable naming conventions (contains
blank spaces, symbols, and so on). For example, Name as ‘Person Name' would be
automatically renamed because of the space between Person and Name.
The Select query contains a down-leved variable, but the user did not explicitly rename
the variable. For example, ^.Pets would be automatically renamed to <filename>_Pets
(Household_Pets) because it was down-leved one layer from the top level.
As another example, ^.^.Age would be automatically renamed to <filename>_<parent level
name>_age (household_person_age) because it was down-leveled two layers from the top
level and the person level.
The Select query contains an expression or aggregation, but does not explicitly rename the
expression\aggregation. For example, SUM(Age+Gender) would be automatically renamed to
SUM_Age_Gender_ based on metadata creation naming conventions.
Tips:
1. You can use the IBM® SPSS® Data Collection Base Professional Metadata Viewer to view the
names of the variables. For more information, see the topic Using the Metadata Viewer on p. 28.
2. When you have a large number of variables to specify or they have long names, you may find
it easier to set up the metadata filter in WinDMSRun. For more information, see the topic
WinDMSRun Window: Variable Selection on p. 305.
Case Data Filter
In a large study, you may want to export the case data for each region separately, so that it can be
analyzed separately. You can achieve this by defining a case data filter that selects the cases for
which the region variable has a specified value.
In the DMS file, you define a case data filter of this type using a WHERE clause in the select
query defined for the input data source. For example, this InputDataSource section defines a
case data filter (shown in red) that selects cases for which the South category is selected for
the region variable:
SelectQuery = "SELECT * FROM vdata WHERE region = {South}"
End InputDataSource
246
Chapter 1
For more information on defining case data filters using the WHERE clause, see the Basic SQL
Queries topic in the IBM® SPSS® Data Collection Developer Library.
Tips:
1. You can use the Base Professional Metadata Viewer to view the variable and category names. For
more information, see the topic Using the Metadata Viewer on p. 28.
2. If you are working with IBM® SPSS® Data Collection Interviewer Server data and want to filter
out test, active, and timed out records, or select records based on the date they were collected, you
may find it easier to set up the case data filter in WinDMSRun. For more information, see the
topic WinDMSRun Window: Case Selection on p. 305.
When cleaning data in an ongoing study, you may want to set up a case data filter to include only
cases that have not been cleaned before. One way of doing this is to use a global SQL variable.
For more information, see the topic GlobalSQLVariables Section on p. 266. In your cleaning
script, you may also want to specify that some cases are to be excluded; for example, because they
contain questionable responses. In the DMS file, you can define this type of case data filter using
the dmgrJob.DropCurrentCase method in the OnNextCase Event section. Here is an example:
Event(OnNextCase)
If age < 0 Then dmgrJob.DropCurrentCase()
.
.
.
End Event
You can also use an update query in the OutputDataSource section to remove case data records
from the output data source. For example, the following snippet shows how you could use
update queries in two OutputDataSource sections to split the case data between two output data
sources—one of which stores the clean data and the other the dirty data.
OutputDataSource(Clean, "My clean data")
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\CleanData.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\CleanData.mdd"
UpdateQuery="DELETE FROM vdata _
WHERE DataCleaning.Status = {NeedsReview}"
OutputDataSource(Dirty, "My dirty data")

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\DirtyData.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\DirtyData.mdd"
UpdateQuery="DELETE FROM vdata _
WHERE NOT DataCleaning.Status.ContainsAny({NeedsReview})"
Note: This example is included in the SplitIntoDirtyAndClean.dms sample. For more information,
see the topic Sample DMS Files on p. 467.
247
Base Professional
Breaking Up Long Lines in the DMS file
A long statement can be broken into multiple lines using the line-continuation characters (a space
followed by an underscore). Doing this can make your code easier to read, both online and when
printed. Here is an example of a connection string in the InputDataSource section that has been
broken into several lines using the line-continuation characters ( _):
End InputDataSource
There are some restrictions on where you can break lines. For example, you cannot break a line
in the middle of a connection property. However, you can break a connection string, provided
the individual properties are intact. In addition you cannot use a line continuation character
in #include or #define statements.
Comments in the DMS file
You can include comments in your DMS file to make it easier to read. You can place comments
anywhere between sections. You can also include comments within sections provided that they
conform to the syntax for that section. For example, comments in the Event sections must
conform to the rules for mrScriptBasic comments and comments in the Metadata Section must
conform to the rules for mrScriptMetadata comments. Comments in all other sections must
start on the first character of a line.
Single-line comments start with the single quotation mark character ('). For example:
' Standard Logging section to activate logging.
You can also define block comments that span more than one line using the block comment start
characters ('!) and end characters (!'). For example:
'! Standard Logging section to activate logging
and define location of log file.!'
Warning. When you use a DMS file in WinDMSRun, any comments that appear between the
sections will be removed when you change between the Normal and Script tabs or when you save
and reopen a file. For more information, see the topic WinDMSRun on p. 300.
You can include in your DMS file a block of code that is defined in another file. This is useful, for
example, when you want to use the same cleaning or weighting routines or set up standard filter
and banner variables in several projects. Instead of repeating the code in each DMS file, you can
simply define the code you want to reuse in one or more separate files and then use the Include
statement to include them in your main DMS files.
248
Chapter 1
The syntax is:

#include "Filename"
Part Description
Filename The name and location of the file to include.
Typically this is a text file with a .dms filename
extension.
Remarks
There is no restriction on where you can put an Include statement in your DMS file. However,
the Include statement is replaced by the code in the Include file when you run the DMS file,
so you must make sure that you place the Include statement in an appropriate position. For
example, if the Include file contains an entire section, place the Include statement before,
after, or between the other sections in the file. Similarly, if the Include file contains only part
of a section, make sure that you place the Include statement in an appropriate place in the
section to which the code applies.
You can replace text in an Include file with your own text by inserting a #define statement in
your DMS file before the #include statement. In this way, you can reuse the same Include files
in projects that have different variable names. The main example below shows you how to do
this. For more information on using the #define statement, see Using Text Substitution in
the DMS file.
You can also have Include statements in the Include files themselves. However, be careful not
to create a circular construction, because there is no warning when this happens.
You must not use line-continuation characters in an #include statement.
mrScriptBasic and mrScriptMetadata error messages give the approximate line number where
the error occurred. Using an Include file may result in misleading line numbers in these error
messages because the line numbers are calculated using the expanded file. However, you can
use the DMS Runner /a: option to save the expanded DMS file.
You are not restricted to using files with a .dms filename extension as Include files. For
example, you could use an mrScriptBasic (.mrs) file as an Include file. (To ensure that your
DMS file can be debugged, only include .dms or .mrs files.) The MSOutlookSendReport.mrs
file is included as an example Include file to demonstrate this. For more information, see the
topic Sample DMS Files That Integrate with Microsoft Office on p. 475.
When you specify the path to an include file, it must always be specified relative to the folder
in which the file that contains the #include statement is located.
Your DMS file and all include files must be saved using the same text encoding, either all
ANSI or all Unicode.
Example
Here is a DMS file that contains two Include statements. Two #define statements have been
inserted before the second #include statement to replace text in that Include file:
249
Base Professional
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.ddf; _

Initial Catalog=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.mdd"
#Include ".\Include\Include1.dms"
End InputDataSource
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\IncludeExample.ddf"
MetaDataOutputName = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\IncludeExample.mdd"
#define srvar museums
#define textvar address
#Include ".\Include\Include2.dms"
Here is the contents of include1.dms:
'==========================================================
'Licensed Materials - Property of IBM
'
'IBM SPSS Products: Data Collection
'
'(C) Copyright IBM Corp. 2001, 2011
'
'US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP
'Schedule Contract with IBM Corp.
'==========================================================
SelectQuery = "SELECT Respondent.Serial, _

age, address, gender, museums, dinosaurs, _
rating[{dinosaurs}].column, _
rating_ent[{dinosaurs}].column, _
DataCleaning.Note, DataCleaning.Status _
FROM VDATA WHERE Respondent.Serial < 101"
Here is the contents of include2.dms:
Event(OnNextCase, Clean the data)

If srvar.Response.AnswerCount() > 2 Then
DataCleaning.Note = DataCleaning.Note + srvar.QuestionName + " needs checking."
DataCleaning.Status = {NeedsReview}
End If
Dim TextLength
TextLength = Len(textvar.Trim())
If TextLength > 90 Then
textvar = Left(TextLength, 90)
End If
End Event
250
Chapter 1
Here is the contents of the expanded file created using the /a: option of DMS Runner. Notice how
the “srvar” and “textvar” text in include2.dms have been replaced by “museums” and “address”
respectively:
InputDatasource(myInputDataSource)
ConnectionString = _
"Provider=mrOleDB.Provider.2; _
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.ddf; _
Initial Catalog=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.mdd"
SelectQuery = "SELECT Respondent.Serial, age, address, gender, museums, dinosaurs,
rating[{dinosaurs}].column, rating_ent[{dinosaurs}].column, DataCleaning.Note,
DataCleaning.Status FROM VDATA WHERE Respondent.Serial < 101"
End InputDatasource
OutputDatasource(myOutputDataSource)
ConnectionString = _
"Provider=mrOleDB.Provider.2; _
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\IncludeExample.ddf"
MetaDataOutputName = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\IncludeExample.mdd"
End OutputDatasource
Event(OnNextCase, "Clean the data")

If museums.Response.AnswerCount() > 2 Then
DataCleaning.Note = DataCleaning.Note + museums.QuestionName + " needs checking."
End If
Dim TextLength
TextLength = Len(address.Trim())
If TextLength > 90 Then
address = Left(TextLength, 90)
End If
End Event
Note: The three files in this example are provided as sample DMS files (called
IncludeExample.dms, Include1.dms, and Include2.dms) that are installed with the IBM® SPSS®
Data Collection Developer Library. For more information, see the topic Sample DMS Files
on p. 467.
You can use text substitution to replace text in a DMS file with your own text when you run
the file. This is useful, for example, when you want to reuse DMS files in projects that have
different data sources. Instead of manually changing the data source section, you can define a text
substitution statement that will automatically insert the correct values when the DMS file is run.
251
Base Professional
The syntax is:
#define Search Replace
Part Description
Search Text that is to be replaced by Replace.
Replace The text to replace Search.
Remarks
You can include more than one #define statement in a DMS file. You must insert the
statement before the appearance of the text that you want to replace and you must not use a
line-continuation character in the #define statement. Note that the search is case sensitive.
You can replace text in an Include file by inserting a #define statement in your DMS file
before the #include statement. For an example of replacing text in an Include file in this
way, see Using Include Files in the DMS file.
To restrict the range of a text substitution, insert an #undef statement in your DMS file at the
point where you want the text substitution to stop. The following example shows how to
restrict the range of a text substitution to the contents of an Include file:
#define textvar address

#include ".\Include\Include2.dms"
#undef textvar
When debugging DMS files that use text substitution, you may find it useful to use the DMS
Runner /a: option to save the DMS file after the text substitution has been implemented.
Example 1
This example is based on the simple example described in Simple Example of a DMS File.
However, a #define statement has been inserted at the beginning to change the names of the
output files.
#define simple "TextSubstitution"

End InputDataSource

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\" + simple + ".sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\" + simple + ".mdd"
252
Chapter 1
Example 2
This example uses the MSExcelToDDF.dms sample file included with the DDL.
#define ADOInfoFile "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelToDDF.adoinfo"
' The output Data Collection Data and MDD files...
#define OutputDDFFile "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelToDDF.ddf"

#define OutputMDDFile "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelToDDF.mdd"
InputDataSource(Input)
Data Source=mrADODsc; _
MR Init MDSC=mrADODsc; _
Initial Catalog=" + ADOInfoFile
SelectQuery = "SELECT * FROM vdata"
End InputDatasource
OutputDataSource(Output)
Location=" + OutputDDFFile
MetaDataOutputName = OutputMDDFile
Sections in the DMS file
The DMS file consists of a number of sections, which can appear in any order and are defined
as follows:
section_name (parameter, parameter, ... )

...
END section_name
Part Description
section_name This must be a recognized section name as shown
below.
parameter Parameter of type Text. The parameters vary
depending on the section type. For most section
types there are two parameters—the first defines
a name and the second is an optional parameter
that enables you to define a description. However,
the Metadata section takes four parameters that
define the default language, user context, label
type, and the data source to which the section
applies, respectively. Note that for the Event
section the first parameter defines when the section
is to be executed. For more information, see the
documentation on each section.
253
Base Professional
The recognized section names are:

Job. Optional section that defines the job name and job description. The Job section is
designed for supporting the job’s global parameters. Currently, TempDirectory is the only
identified parameter.
InputDataSource. Required section that defines an input data source for the data
transformation. There must be one (and only one) InputDataSource section in your DMS file.
OutputDataSource. Required section that defines an output data source for the data
transformation. There must be at least one OutputDataSource section in your DMS file.
GlobalSQLVariables. This is an optional section that defines global SQL variables, which
enable you to exchange information between data sources.
Metadata. Optional section that is used to define new questions and variables in the metadata
using mrScriptMetadata.
Logging. Optional section that defines the parameters for the Logging component.
Event. Optional sections that define procedural code, written in mrScriptBasic, for cleaning
the case data, setting up weighting, etc.
Job Section
The Job section defines the job name and description. The Job section is designed for supporting
the job’s global parameters. Currently, TempDirectory is the only identified parameter. This
section is optional. The syntax is:
Job(name [, "description"])
[TempDirectory = "<Temp Directory>"]
End Job
name and description should be of type Text.
TempDirectory is used to set a temporary directory in which to store temporary files generated
during Job transformation. Ensure this directory is assigned the appropriate read and write
access permissions.
Examples
The following example defines a job with a name of MUS03 and a description of Copy the
Museum database to IBM® SPSS® Statistics SAV:
Job(MUS03, "Copy the Museum database to IBM SPSS Statistics SAV")
TempDirectory = "C:\Temp"
End Job
InputDataSource Section
The InputDataSource section defines the input data source for the data transformation. The
InputDataSource section is required, which means that there must always be at least one
InputDataSource section in a DMS file. If you add more than one InputDataSource section to a
254
Chapter 1
DMS file, the case data for the input data sources will be combined into a single data source. For
more information, see the topic Using a DMS Script to Merge Data on p. 378.
The syntax for the InputDataSource section is:
InputDataSource(name [", description"])

ConnectionString = "<connection_string>"
[SelectQuery = "<select_query>"]
[UpdateQuery = "<update_query>"]
[UseInputAsOutput = True | False"]
[JoinKey = "<variable_name>"]
[JoinType = "Full" | "Inner" | "Left"]
[JoinKeySorted = True | False"]
End InputDataSource
name and description define a name and description for the InputDataSource and should be of
type Text. You use the name you define here in the Metadata section to identify the data source to
which the Metadata section applies.
ConnectionString
This specifies the OLE DB connection properties, which define the OLE DB provider to be used
and all of the details about the physical data source, such as its name and location. Note that each
OLE DB provider has different requirements for the connection string. For specific information
about non-Data Model OLE DB providers, see the documention that comes with the OLE DB
provider. For general information, see Reading Data Using Other OLE DB Providers.
If you want to use the IBM® SPSS® Data Collection Data Model, specify the IBM SPSS Data
Collection OLE DB Provider by setting the Provider connection property to mrOleDB.Provider.n
(where n is the version number). The IBM SPSS Data Collection OLE DB Provider has a number
of custom connection properties that define the CDSC that is to be used to read the case data (this
must be a read-enabled CDSC), the Metadata Document (.mdd) file or other metadata source and
MDSC to be used, etc. Refer to the Connection Properties topic in the IBM® SPSS® Data
Collection Developer Library for more information.
You can specify file locations using a relative path (relative to the folder in which the DMS file
is located when you run it). Generally, you do not need to specify a connection property for
which the default value is being used.
When you are using a non-Data Model OLE DB Provider to write the case data, provided you
have specified an input metadata source, you can set the MR Init Category Names connection
property to 1 so that the category names are exported instead of the numeric values. However, you
will get an error if you use this setting when writing data using the IBM SPSS Data Collection
OLE DB Provider. This means that you cannot use this option when you have more than one
OutputDataSource section in your DMS file and one or more of them uses the IBM SPSS Data
Collection OLE DB Provider to write the data.
255
Base Professional
Each DSC that you can use to read data behaves differently and has different requirements. For
specific information about reading data using the read-enabled DSCs that come with the Data
Model, see:
Transferring Data From a Relational MR Database (RDB)
Transferring Data From a IBM SPSS Data Collection Data File
Transferring Data From IBM SPSS Statistics
Transferring Data From IBM SPSS Quantum
Transferring Data From IBM SPSS Quanvert
Transferring Data From QDI/DRS
Transferring Data From Log Files
Transferring Data From Triple-S
Transferring Data From Microsoft Office
Transferring Data From XML
When using the Data Model, if the metadata associated with the input data source is in a Metadata
Document (.mdd) file, specify the name and location of the .mdd file in the Initial Catalog
connection property. Note that the .mdd file itself must be writable. For example:

End InputDataSource
If the .mdd file has more than one version, the most recent version will be used by default.
However, you can select an earlier version by using the MR Init MDM Version connection
property. For more information, see the topic Selecting a Specific Version on p. 361. You can
also select multiple versions. This is useful when you want to export data collected using more
than one version of the questionnaire. For more information, see the topic Selecting Multiple
Versions on p. 362.
If the metadata is not in the form of a Metadata Document (.mdd) file, you specify the metadata
source and the MDSC to be used in the Initial Catalog and MR Init MDSC connection properties.
Note that the MDSC must be read-enabled. This example specifies the IBM® SPSS® Quanvert™
Museum sample database and the Quanvert DSC:
InputDataSource("My input data source")

Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\qvinfo; _
End InputDataSource
256
Chapter 1
For some types of data you do not need to specify a metadata source, although generally
you will want to do so, because without an input metadata source, you cannot use the
OnAfterMetaDataTransformation, OnJobStart, OnNextCase, OnBadCase, and OnJobEnd event
sections. Moreover, if you are transferring data to a target data source that already exists, the
transfer will succeed only if the structure of the output data exactly matches the existing target
data. It’s possible to transfer data without specifying a metadata source only when using Relational
MR Database CDSC, IBM® SPSS® Data Collection Data File CDSC, SPSS Statistics SAV DSC,
or XML CDSC to write the data (although transferring to a .sav file without a metadata source
has a number of limitations. For more information, see the topic Transferring Data to IBM SPSS
Statistics on p. 342.) See below for an example.
If you are using the Data Model and want to operate on the metadata only, specify the case data in
the normal way in the InputDataSource section. Then in the OutputDataSource section, set the
Data Source connection property to CDSC. This specifies the Null DSC, which means that no case
data will be written. Note that you should not specify the Null DSC in the InputDataSource section.
Tip: An easy way to create the connection string is to use the IBM® SPSS® Data Collection Base
Professional Connection String Builder. For more information, see the topic 3. Transferring
Different Types of Data on p. 212.
SelectQuery
An SQL query that defines a case data filter, a metadata filter, or both a case data and a metadata
filter. For more information, see the topic Filtering Data in a DMS File on p. 243.
If you do not specify a query, it will default to the following query:
SELECT * FROM vdata
If you are using the IBM SPSS Data Collection OLE DB Provider (which is part of the Data
Model), this query means that all of the data that can be flattened will be included. However, this
query will give you an error if you are using another OLE DB provider. So you must always
specify a query when you are using a non-Data Model OLE DB provider.
Case data will be transferred for the specified variables only. However, if you select a helper
variable or a variable that is part of a metadata block (Class object), the parent object will be
included in the output metadata. If you specify in the select query one or more variable instances
that relate to a variable inside a grid or a loop, all of the related variable instances will be included
in the output, but case data will be transferred only for the variable instances specified in the
select query.
When you are using the IBM SPSS Data Collection OLE DB Provider and do not specify a query
or you use a SELECT * FROM vdata query, any variables defined in the Metadata section are
included in the transformation automatically. However, if you specify the variables individually
in the query, you also need to specify in the select query any variables that are defined in the
Metadata section. Otherwise the variables defined in the Metadata section will be excluded from
the output metadata and the transformation.
257
Base Professional
The query can be any SQL query that is supported by the OLE DB provider you are using. For
information about the SQL queries that are supported by the IBM SPSS Data Collection OLE DB
Provider, see the Basic SQL Queries topic in the Data Collection Developer Library.
UpdateQuery
An SQL statement to be executed on the data source before any processing takes place. For more
information, see the topic 4. Using an Update Query on p. 216.
Any Data Manipulation SQL syntax that is supported by the OLE DB provider can be used. When
you are using the IBM SPSS Data Collection OLE DB Provider you can use an INSERT, UPDATE,
or DELETE statement, provided the syntax is also supported by the CDSC that is being used to
read the case data. See the SQL Syntax and Supported Features of the CDSCs topics in the Data
Collection Developer Library for more information.
Warning: Use this feature with care because the update query will permanently alter the input
data source. It is recommended that you take a backup of the input data source before running a
DMS file that includes this feature.
UseInputAsOutput, JoinKey, JoinType, and JoinKeySorted
These parameters are used only when running a case data merge. For more information, see the
topic Using a DMS Script to Merge Data on p. 378.
Examples
1. Using a VDATA select query to filter case data and metadata
The following example specifies the Museum sample Data Collection Data File, which consists of
case data in the museum.ddf file and a Metadata Document (.mdd) file called museum.mdd.
The query specifies a metadata filter consisting of three named variables (age, gender, museums)
and a case data filter that selects female respondents only.
SelectQuery = "SELECT age, gender, museums FROM vdata _
End InputDataSource
2. Using an HDATA select query to filter metadata in the same level
The following query specifies a metadata filter consisting of three named variables (age, gender,
name) at the person level.
258
Chapter 1
Location=C:\Program Files\SPSSInc\PASWDataCollection5.6\DDL\Data\Data Collection File\Household.ddf; _

Initial Catalog=C:\Program Files\SPSSInc\PASWDataCollection5.6\DDL\Data\Data Collection File\Household.mdd"
SelectQuery = "SELECT age, gender, name FROM hdata.person"
End InputDataSource
3. Using an HDATA select query to filter metadata in different levels
The following query specifies a metadata filter consisting of three named variables (address, age,
country) at different levels via the Up-lev and Down-lev operators (based on the person level).
SelectQuery = "SELECT ^.address, age, trip.(country) FROM hdata.person"
End InputDataSource
Note: ^.address is automatically renamed to <FileName>_address (in this example, it is renamed

to Household_address).
4. Using a select query to rename metadata
The following query specifies a metadata filter consisting of one renamed variable (age) at the
person level.
SelectQuery = "SELECT age as “person_age” FROM hdata.person"
End InputDataSource
5. Using an update query to delete test data
The following example includes an update query that is used to delete test data from the input
data source. Note that you should always be extremely careful when using an update query in the
InputDataSource section because it alters the input data source permanently.
UpdateQuery = "DELETE FROM vdata _
WHERE DataCollection.Status.ContainsAny({Test})"
End InputDataSource
6. Operating on metadata only

259
Base Professional
The following example shows how to operate on the metadata only. In the InputDataSource
section you specify the case data in the normal way and in the OutputDataSource section, the
Data Source connection property is set to CDSC, which is the Null DSC and which enables you
to operate on the metadata without case data.
'==========================================================
'
'
'
'==========================================================
End InputDataSource
Data Source=CDSC"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MetadataOnly.mdd"
Metadata (ENU, Question, Label, Input)

Entering "Respondents interviewed entering the museum" boolean
expression ("interview = {entering}");
Leaving "Respondents interviewed leaving the museum" boolean
expression ("interview = {leaving}");
End Metadata
Note: This example is provided as a sample DMS file (called MetadataOnly.dms) that is installed
with the Data Collection Developer Library. For more information, see the topic Sample DMS
Files on p. 467.
7. Operating on case data only
The following example shows how to operate on the case data without specifying a metadata
source. This is possible only when using Relational MR Database CDSC and SPSS Statistics
SAV DSC to write the case data. However, note that transferring to a .sav file without using a
metadata source has a number of limitations. For more information, see the topic Transferring
Data to IBM SPSS Statistics on p. 342.
260
Chapter 1
This example transfers case data from a .sav file to another .sav file without using a metadata
source:
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.sav"
SelectQuery = "SELECT id, bdate, educ, salary, salbegin, jobtime, prevexp FROM VDATA"
End InputDatasource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\CaseDataOnly.sav"
Note: This example is provided as a sample DMS file (called CaseDataOnly.dms) that is installed
Files on p. 467.
8. Using Other OLE DB Providers
The following example uses the Microsoft OLE DB Provider for ODBC Drivers to read data in
an Access database:
Location=""Provider=MSDASQL.1; _
Persist Security Info=False; _
Extended Properties='DSN=MS Access Database; _
DBQ=C:\Inetpub\iissamples\sdk\asp\database\Authors.mdb; _
DriverId=281; _
FIL=MS Access; _
MaxBufferSize=2048; _
PageTimeout=5; _
UID=admin'""; _
MR Init Project=Authors"
End InputDatasource
The example uses the Data Collection ADO DSC in the Data Model to read the Access database
as an ADO data source. Although not demonstrated here, it is also possible to specify an input
metadata source when using the ADO DSC, which allows you to create an output metadata
document (.mdd) file. For more information, see the topic Transferring Data From Microsoft
Office on p. 328.
Note: To run this sample, you must have the Microsoft OLE DB Provider for ODBC Drivers,
the ODBC data source called MS Access Database, and the Authors sample Access database,
which all come with Microsoft Office. In the Data Collection Developer Library, there are similar
example scripts called MSAccessToQuantum.dms and MSAccessToSav.dms.
261
Base Professional
OutputDataSource Section
The OutputDataSource section defines an output data source for the data transformation. There
must be at least one OutputDataSource section in a DMS file and you can optionally specify more
than one. If you specify more than one OutputDataSource section in a DMS file, the case data will
be written to each output data source specified. This is useful, if, for example, you want to export
the case data to two or more different formats or locations at the same time. The syntax is:
OutputDataSource(name [, "description"])
[ConnectionString = "<connection_string> | UseInputAsOutput = True|False"]
[MetaDataOutputName = "<metadata_location>"]
[UpdateQuery = "<update_query>"]
[TableOutputName = "<table_output_name>"]
[VariableOrder = "SELECTORDER"]
name and description should be of type Text.
ConnectionString
This specifies the OLE DB connection properties, which define the OLE DB provider to be used
and all of the details about the physical data source, such as its name and location. Note that each
OLE DB provider has different requirements for the connection string. For specific information
about non-Data Model OLE DB providers, see the documentation that comes with the provider.
For general information, see Writing Data Using Other OLE DB Providers.
If you want to use the IBM® SPSS® Data Collection Data Model, specify the IBM SPSS Data
of custom connection properties that define the CDSC that is to be used to write the case data (this
must be a write-enabled CDSC), the data validation settings, etc. Note that the Initial Catalog
connection property should not be given a value—if specified, it should be set to an empty string
(“”). Refer to the Connection Properties topic in the IBM® SPSS® Data Collection Developer
If you specify a physical data source that does not already exist, generally it will be created when
the DMS file is executed, provided the specified folder exists. However, when exporting to a
relational MR database, you must create the actual database before you run the DMS file. For
more information, see the topic Transferring Data to a Relational MR Database (RDB) on p. 337.
What happens when you specify a physical data source that does exist, depends on a number
of factors.
If you are doing a case-data only transformation or are not using the Data Model to read
the data, the transfer will succeed only if the structure of the output data exactly matches
the existing data.
262
Chapter 1
If you are using the Data Model to read the data and have specified an input metadata source,
what happens depends on whether the output of the data transformation matches the structure
of the data in the output data source, whether the cases already exist in the target data source,
and on the format of the data (and hence the CDSC being used).
For some data types (such as relational MR database) the transfer will fail if the output data
contains any cases that already exist.
For information about what happens when you are using a non-Data Model OLE DB provider
to write the data, see TableOutputName below.
If the metadata to be written will not be in the form of a Metadata Document (.mdd) file, you can
specify the metadata file to be written and the MDSC to be used in the Initial Catalog and MR Init
MDSC connection properties. Note that the MDSC must be write-enabled. At present, the only
DSC that can be used in this way to write a metadata file other than a .mdd file is the Triple-S DSC.
Each DSC that you can use to write data behaves differently and has different requirements. For
specific information about writing data using some of the write-enabled DSCs that come with
the Data Model, see:
Transferring Data to a Relational MR Database (RDB)
Transferring Data to a IBM SPSS Data Collection Data File
Transferring Data to IBM SPSS Statistics
Transferring Data to IBM SPSS Quantum
Transferring Data to Triple-S
Transferring Data to SAS
Transferring Data to a Delimited Text File
Transferring Data to XML
If you are using the Data Model and want to operate on the metadata only, specify the Data Source
connection property as CDSC. This is a special CDSC, called the Null DSC, which enables you to
connect to the IBM SPSS Data Collection OLE DB Provider without any case data.
MetaDataOutputName
This defines the name and location of the Metadata Document (.mdd) file to which the exported
metadata is to be written. If you do not specify this parameter, the output metadata is not saved.
The output metadata determines the structure of the output case data. For example, if the output
case data source does not exist, it will be created based on the output metadata. If the output case
data source does exist and the data format is one that can be updated, the output case data is
synchronized with the output metadata.
263
Base Professional
The output metadata is created in the following way:

If the DMS file contains a Metadata section that relates to the input data source, the metadata
defined in the Metadata section is merged with the input data source metadata. The input data
source metadata is used as the master version for the merge.
The merged metadata is then filtered according to the metadata filter defined in the select query
in the InputDataSource section. If the select query includes a helper variable or a variable that
is part of a metadata block (Class object), the parent object will also be included in the output
metadata. If the select query includes one or more variable instances that relate to a variable
inside a grid or a loop, all of the related variable instances will be included in the output.
The output metadata will not contain any versions, even if the input metadata source contains
versions. By default, the output metadata will be based on the most recent version of the
input metadata source. However, if the input metadata source has multiple versions, and you
specify one or more specific versions to use for the transfer (using the MR Init MDM Version
connection property in the InputDataSource section), the output metadata will be based on the
specified version or combination of versions.
The resulting metadata is written or merged to the specified location.
When you are transferring data to a .sav file, it is recommended that you save the output metadata
file, whenever possible. If you subsequently want to read the .sav file using the Data Model, it is
usually preferable to do so using the .mdd file, because this gives you access to the original Data
Model variable names. In addition, if you subsequently want to export additional records to the
.sav file, it will be possible only if you run the export using this file as the input metadata source.
For more information, see the topic Transferring Data to IBM SPSS Statistics on p. 342.
Note: Starting with version 5.6, the input metadata will be merged to any existing output metadata
(with the existing output acting as the master). A merge is used, instead of simply overwriting the
existing metadata, to ensure that the category map for the existing output is used. For example, if
data is collected using two separate clusters, the category maps may be different on each cluster.
Similar to a vertical merge, when appending data to a combined data set, the category map for
the output dataset needs to be used. Prior to version 5.6, the output metadata was overwritten,
invalidating any existing data.
Case data-only transformation. No output metadata is created if you do not specify a metadata
source in the InputDataSource section (for example, because you are using a non-Data Model
OLE DB provider to read the data or you are doing a case data-only transformation), and the
output case data structure is based on the attributes and names in the input case data. If you specify
the MetaDataOutputName parameter in this situation, it will be silently ignoredt.
UpdateQuery
An SQL statement to be executed on the data source after the processing of the procedural code
defined in all of the Event sections with the exception of the OnAfterJobEnd Event section. For
more information, see the topic 4. Using an Update Query on p. 216.
Any Data Manipulation SQL syntax that is supported by the OLE DB provider can be used. When
you are using the IBM SPSS Data Collection OLE DB Provider you can use an INSERT, UPDATE,
or DELETE statement, provided the syntax is also supported by the CDSC that is being used to
264
Chapter 1
write the case data. Refer to the Supported SQL Syntax and Supported Features of the CDSCs
topics in the Data Collection Developer Library for more information.
UseInputAsOutput
Set to True if your DMS file has a single input data source and you want the data to be written
to that data source. This means that the input data source will be overwritten with the results of
the data transformation. The default is False. If you are using the Data Model to read the input
data, the CDSC must be write-enabled and support changing the data in existing records (Can
Update is True for the CDSC).
If you want the data to be written to the input data source when you are running a case
data merge, and therefore your DMS file contains multiple input data sources, you must
specify the UseInputAsOutput option in the relevant InputDataSource Section and not in the
OutputDataSource section.
When using the UseInputAsOutput option, you must set the MR Init MDM Access connection
property to 1 in the InputDataSource section.
When you use the UseInputAsOutput option, the version history in the input metadata will be
preserved only if, by default, you are using the most recent version. A new unlocked version will
be created if the most recent version is locked. However, if you specify one or more versions
using the MR Init MDM Version connection property in the InputDataSource section, the input
metadata will be overwritten with the specified version or combination of versions and the version
history will be deleted.
Warning: The UseInputAsOutput option should be used with caution because it changes the input
metadata and case data irreversibly. It is not suitable for use with data that is in the process of
the being collected by a live IBM® SPSS® Data Collection Interviewer Server project. It is
recommended that you take a backup of your data before using this option.
TableOutputName
Used only when writing the case data using a non-Data Model OLE DB provider, this specifies the
name of the table to which the data is to be written.
The table will be created if it does not exist already. You can append data to an existing table
only if the provider you are using supports this operation and the structure of the data you are
transferring is identical to (or a subset of) the data in the existing table. For example, if the
existing table contains the variables age, gender, and income, exports that contain the variables
age and gender, or age, gender, and income should succeed, provided the variables are of the
same type and the provider you are using supports this type of operation. However, an export of
variables age, gender, income, and occupation would always fail.
VariableOrder
Variables are output in the order in which they appear in the Select Query statement in the
InputDataSource section. In Dimensions versions 3.0 through 5.5 , variables were output
in the order in which they appeared in the input metadata source, unless the output data set
265
Base Professional
specified in OutputDataSource already existed. You can delete the output data set in the event
OnBeforeJobStart section, or use property MR Init Overwrite, to ensure that variables are output
in the same order as the Select Query statement in the InputDataSource section.
Starting with version 5.6, SELECTORDER is supported exclusively.
Examples
1. Transferring data to IBM® SPSS® Statistics
The following example specifies that the data is to be written to a .sav file.
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Simple.sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Simple.mdd"
2. Using an update query to set the DataCollection.FinishTime
The following example specifies that the case data is to be written to a IBM SPSS Data
Collection Data File (.ddf) and shows an update query. This uses the function to set the
DataCollection.FinishTime variable to the current date and time.
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\UpdateQuery.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\UpdateQuery.mdd"
UpdateQuery = "UPDATE vdata _
SET DataCollection.FinishTime = Now()"
3. Using the UseInputAsOutput option
The following example shows using the UseInputAsOutput option. Note that the MR Init MDM
Access connection property has been set to 1 in the InputDataSource section.
InputDataSource(Input, "The input data source")

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum-copy.ddf; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum-copy.mdd; _
MR Init MDM Access=1"
SelectQuery = "SELECT DataCollection.FinishTime FROM vdata"
End InputDataSource
OutputDataSource(Output, "The output data source")

UseInputAsOutput = "True"
266
Chapter 1
4. Using the Null DSC and operating on metadata and case data only
For an example of using the Null DSC and operating on metadata only, see the third example
in the InputDataSource section. For an example of operating on case data only, see the fourth
example in the same topic.
5. Writing the data to Excel
This example shows exporting a subset of the Museum sample data set to Excel using a non-Data
Model OLE DB provider. Notice that the MR Init Category Names connection property has been
set to 1 in the InputDataSource section so that the category names are transferred to Excel rather
than the category values. This generally makes the data easier to interpret. For more information,
see the topic Writing Data Using Other OLE DB Providers on p. 352.
InputDataSource(Input, "The input data source")

Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.mdd; _
MR Init Category Names=1"
SelectQuery = "SELECT interest, age, gender, expect, when_decid _
FROM VDATA WHERE gender = {female}"
End InputDataSource
OutputDatasource(MSExcel)
ConnectionString = "Provider=MSDASQL.1; _
Data Source=Excel Files; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelTransferToFromDDF.xls"
TableOutputName = "Sheet1"
Note: This example is provided as a sample DMS file, called MSExcelTransferToFromDDF.dms,

that is installed with the Data Collection Developer Library. For more information, see the topic
Sample DMS Files That Integrate with Microsoft Office on p. 475.
GlobalSQLVariables Section
The GlobalSQLVariables section is an optional section that you can use to define global SQL
variables, which provide a means of exchanging data between different data sources. The syntax is:
GlobalSQLVariables(name [, "description"])
ConnectionString = "<connection_string>"
SelectQuery = "<select_query>"
End GlobalSQLVariables
name and description define a name and description for the section and should be of type Text.
ConnectionString
267
Base Professional
A connection string that defines the OLE DB connection properties, which define the OLE DB
provider to be used to access the case data and all of the details about the physical data source,
such as its name and location.
If you are using the IBM® SPSS® Data Collection Data Model, specify the IBM SPSS Data
of custom connection properties that define the CDSC that is to be used to access the case data, the
Metadata Document (.mdd) file or other metadata source and MDSC to be used, etc. Refer to the
Connection Properties topic in the IBM® SPSS® Data Collection Developer Library for more
information. Note that the CDSC you are using must be read-enabled. This means that you cannot
use a GlobalSQLVariables section with a IBM® SPSS® Quantum™ data source.
SelectQuery
An SQL query that defines the global variable(s). You define a global variable in the query using
the AS clause and by prefixing the column name with the at sign (@). The query can specify a
simple column or an expression based on one or more columns, using the SQL syntax supported
by the OLE DB provider you are using. See the Basic SQL Queries topic in the Data Collection
Developer Library for information on the SQL queries supported by the Data Model.
Example
The following example shows using a global SQL variable in a DMS file that is being used
to clean batches of case data and write it to a different data source, which is being used to
store the clean data. The example shows only the GlobalSQLVariables, InputDataSource, and
OutputDataSource sections of the DMS file:
GlobalSQLVariables section. This specifies a connection string for the output (clean) database
and a query that defines a global SQL variable called @LastTransferred, which stores the
maximum value of the DataCollection.FinishTime variable. This is a system variable that
stores the date and time that an interview is stopped or completed. This means that the global
variable stores the date and time of the most recent (“newest”) respondent record in the output
data source. Refer to the System Variables topic in the Data Collection Developer Library
InputDataSource section. This specifies a connection string for the input (live) data source and
a query that selects respondent records that have the Completed status and whose finish time
is after that of the newest record in the output database.
OutputDataSource section. This specifies a connection string for the output (clean) database.
268
Chapter 1
'==========================================================
'
'
'
'==========================================================
GlobalSQLVariables(myGlobals, "My globals section")

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\GlobalSQLVariable.ddf; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\GlobalSQLVariable.mdd"
SelectQuery = "SELECT MAX(DataCollection.FinishTime) As @LastTransferred FROM VDATA"
End GlobalSQLVariables
SelectQuery = "SELECT * FROM VDATA WHERE (DataCollection.FinishTime > '@LastTransferred') _
AND (DataCollection.Status = {Completed})"
End InputDataSource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\GlobalSQLVariable.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\GlobalSQLVariable.mdd"
Note: This example is provided as a sample DMS file (called GlobalSQLVariable.dms)

that is installed with the Data Collection Developer Library. You need to run the
GlobalSQLVariableSetUp.dms sample first to set up the output data source and transfer the first
records. For more information, see the topic Sample DMS Files on p. 467. Note that you can use
the RunGlobalSQLVariableExample.bat sample batch file to run the two files in sequence.
Metadata Section
The Metadata section is an optional section that can be used to define new variables in the
metadata that is used for the transformation. The code in the Metadata section must be valid
mrScriptMetadata.
269
Base Professional
When the DMS file is executed, the metadata defined in the Metadata section is merged with
the metadata in the specified data source. You can define only one Metadata section for a data
source and the metadata defined in the data source is always used as the master version in the
merge operation.
If you have not specified a metadata source in the InputDataSource section (for example, because
you are not using the IBM® SPSS® Data Collection Data Model OLE DB Provider to read the
data or are doing a case data-only transformation) and you define a Metadata section for that data
source, the Metadata section will be silently ignored.
The syntax is:

Metadata [(language [, context [, labeltype] [, datasource]])]
field_name "field description" <type_info>;
...
END Metadata
Parameter Description
language Defines the current language for the metadata. Must
be a recognized language code.
context Defines the current user context for the metadata.
User contexts define different usages for the
metadata, so that different texts and custom
properties can be used depending on how the
metadata is being used. For example, the Question
user context is typically used to define the default
texts to be used when interviewing and the Analysis
user context is typically used to define shorter texts
for use when analyzing the response data.
labeltype Defines the current label type. Label types enable
different types of labels to be created for different
types of information. For example, the default label
type of Label is used for question and category texts
and variable descriptions, and the Instruction label
type is used for interviewer instructions.
datasource Identifies the input data source to which the
Metadata section relates. You specify the
data source using the name defined for the
InputDataSource section.
For details of recognized language codes, user contexts and label types, see and .
You define metadata in mrScriptMetadata by adding field entries to the Metadata section. Each
field entry corresponds to a question, loop, block, information item, or derived variable. See in the
mrScriptMetadata section for information about defining fields.
A quick way of creating new variables based on other variables is to use one or more expressions.
Variables that are defined in the metadata using expressions are known as “dynamically derived
variables” because the Data Model calculates the case data for these variables “on the fly”.
However, these variables are not understood by products that do not use the Data Model to read
their data, such as IBM® SPSS® Statistics, IBM® SPSS® Quantum™, Excel, and Access.
Therefore, dynamically derived variables are automatically converted into “standard” variables.
270
Chapter 1
This means that the output data source contains case data for these variables (so that you can
use them in SPSS Statistics, Quantum, Excel, etc.) and the expressions are removed from the
variables in the output metadata.
However, there is one exception: when you are using the UseInputAsOutput option, dynamically
derived variables are not converted to standard variables. This has the advantage that the
dynamically derived variables will automatically include any additional case data records that are
added to the data source and it is not a disadvantage because you cannot use the UseInputAsOutput
option to set up metadata in SPSS Statistics and Quantum data.
Examples
The following metadata section has a default language of English (United States), a default user
context of Question, a default label type of Label, and applies to the data source that was defined
in the InputDataSource section called Input. It defines two derived Boolean variables for use as
filter variables when analyzing the data.
Entering "Respondents interviewed entering the museum" boolean
expression ("interview = {entering}");
Leaving "Respondents interviewed leaving the museum" boolean
expression ("interview = {leaving}");
End Metadata
All texts and custom properties will be created in the default language, user context, and label
type, unless you specify otherwise when you define them.
The following metadata section has a default language of English (United States), a default user
context of Question, a default label type of Label, and applies to the data source that was defined
in the InputDataSource section called Input. It defines a derived categorical variable named
GenderAge within loop called Person for use as filter variables when analyzing the data.
Person "Person" loop [1 .. 6] fields -
(
GenderAge "Gender/Age Classification" categorical[1]
{
Boys
expression("Gender = {Male} And Age < 18"),
YoungMen "Young men"
expression("Gender = {Male} And Age >= 18 And Age < 35"),
MiddleMen "Middle-aged men"
expression("Gender = {Male} And Age >= 35 And Age < 65"),
OldMen "Older men"
expression("Gender = {Male} And Age >= 65"),
Girls
expression("Gender = {Female} And Age < 18"),
YoungWomen "Young women"
expression("Gender = {Female} And Age >= 18 And Age < 35"),
MiddleWomen "Middle-aged women"
expression("Gender = {Female} And Age >= 35 And Age < 65"),
271
Base Professional
OldWomen "Older women"

expression("Gender = {Female} And Age >= 65")
};
)
End Metadata
Note: Any variables added in the metadata section need to also appear in the input select statement.
Logging Section
The Logging section defines the parameters for the Logging component and specifies that you
want logging to be performed when the DMS file is executed. This section is optional. However,
if you do not specify a Logging section, no logging will be performed. A DMS file should not
contain more than one Logging section. The syntax is:
Logging(name [, "description"])
Group = "Group"
Path = "Path"
Alias = "Alias"
[FileSize = FileSize
End Logging
name and description define a name and description for the section and should be of type Text.
The following table describes the parameters that you can set within the section.
Logging parameter Description
Group Defines the application group that writes the log
and controls the first three characters of the log
filenames.
Path Defines the location of the log file. You can specify
a full path or a relative path (relative to the location
of the DMS file), such as “MyLogs”. However, the
“..” notation (such as ..\..\MyLogs) is not valid. The
log file will be created in this folder with a .tmp
filename extension.
Alias Defines a name to be used in the logging file. This
means you can identify the logs that originated in
this DMS file when multiple clients are using the
same log file.
FileSize Defines the maximum size of the log file. If you
do not specify this parameter, the maximum size
defaults to 100 KB.
It is generally a good idea to have a Logging section in all your DMS files, as any records that
fail validation will then be written to the log file. For more information, see the topic Validation
Options When Transferring Data on p. 336.
The log filenames are constructed from the first three characters defined in the Group parameter
with the addition of two or more characters to make the name unique and a .tmp filename extension.
272
Chapter 1
Example
The following example shows a DMS file that contains a Logging section that sets the logging
group to “DMGR”, the folder for the log file, an alias name of “Tester”, and a maximum file
size of 500KB.
The example also shows using the log file to record data cleaning information. In the OnNextCase
Event section a string is set up and the Log.LogScript_2 method is called to write the string
to the log file.
'==========================================================
'
'
'
'==========================================================
Logging(myLog)
Group = "DMGR"
Path = "c:\temp"
Alias = "Tester"
FileSize = 500
End Logging
SelectQuery = "SELECT Respondent.Serial, visits, before FROM VDATA WHERE Respondent.Serial < 101"
End InputDataSource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Logging.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Logging.mdd"

Dim strDetails
strDetails = CText(Respondent.Serial)
If visits is not Null then

If visits = 0 Then
before = {No}
strDetails = strDetails + " Before = No"
Else
273
Base Professional
before = {Yes}
strDetails = strDetails + " Before = Yes"
End If
Else
before = {No}
End If
dmgrJob.Log.LogScript_2(strDetails)
End Event
Note: This example is provided as a sample DMS file (called Logging.dms) that is installed
with the IBM® SPSS® Data Collection Developer Library. For more information, see the topic
Sample DMS Files on p. 467.
You can use Log DSC to read and query log files. Here is the log file viewed in DM Query
using Log DSC.
Event Section
The Event section defines procedural code for cleaning case data, setting up weighting, setting up
case data for derived variables, creating batch tables, etc. The Event section is optional and there
can be more than one Event section in a DMS file. The code must be written in mrScriptBasic.
The syntax is:
Event(name [, "description"])
...
End Event
name and description must be of type Text and name must be a recognized Event section name,
which defines when the processing will take place. The recognized names are:
OnBeforeJobStart. Used to define procedural code that is to be executed before any of the
data sources are opened. For example, code that uses the IBM® SPSS® Data Collection
Metadata Model to Quantum component to set up card, column, and punch specifications for
use when exporting case data to a IBM® SPSS® Quantum™-format .dat file, or code that
creates an .mdd file from proprietary metadata.
274
Chapter 1
OnAfterMetaDataTransformation1. Used to define procedural code that is to be executed

after any metadata defined in a Metadata section has been merged with the input metadata.
Typically this is used to set up card, column, and punch definitions for variables defined in
the Metadata section.
OnJobStart1. Used to define procedural code that is to be executed after all of the data sources
have been opened and before the processing of the first case begins. For example, code to
set up global variables that are used in the OnNextCase, OnBadCase, and OnJobEnd Event
sections.
OnNextCase1. Used to define procedural code that is to be applied to each case. For example,
code to clean the case data.
OnBadCase1. Used to define procedural code that is to be executed for each record that will
not be transferred because it has failed the validation. Typically used to create a report of
bad cases.
OnJobEnd1. Used to define procedural code that is to be executed after all of the processing
of the individual cases has been completed and before the data sources are closed. For
example, code that closes report files, or uses the Weight component to set up weighting
in the output data source.
OnAfterJobEnd. Used to define procedural code that is to be executed after the data source
connections are closed. For example, code to create tables, launch a report file, or export a
IBM® SPSS® Quancept™ script.
1 These sections require a metadata source to be specified in the InputDataSource section.
Each Event section can contain any number of functions and subroutines and can access any of
the registered objects. The objects that are registered vary according to the section. Objects in
other object models can be accessed using the function. For more information, see the topic
Using Objects in the Event Sections on p. 274.
Tip: If you are new to objects, see .
Using Objects in the Event Sections
Tip: If you are new to working with objects, see .
Note: If you explicitly call the MDM Document.Open method to open an MDM document, you
need to call the Document.Close method to release the document. For more information, see the
topic OnAfterMetaDataTransformation Event Section on p. 279.
Objects in the OnJobStart, OnNextCase, OnBadCase, and OnJobEnd Event sections
In the OnJobStart, OnNextCase, OnBadCase, and OnJobEnd event sections, the Data Management
Object Model (DMOM) registers a number of objects with the mrScriptBasic engine. This means
that the registered objects are automatically available in the script as intrinsic variables. However,
DMOM requires an input metadata source to do this. This means that you cannot use these Event
sections during a case data-only transfer or when are using a non-IBM® SPSS® Data Collection
Data Model OLE DB provider to read the data.
275
Base Professional
The registered objects are:
Job. The Job object is of type IDataManagerJob and is available as an intrinsic variable called
dmgrJob.
Note that although the Job object gives you access to the input and output metadata through the
TransformedInputMetaData and TransformedOutputMetaData properties, these properties are
designed to enable you to set up card, column, and punch definitions and other custom properties
in the OnAfterMetaDataTransformation Event section. It is important that you do not make
any changes to the structure of the input or output metadata in the OnJobStart, OnNextCase,
OnBadCase, OnJobEnd, or OnAfterMetaDataTransformation Event sections. For example, you
should not add or delete variables or categories or change a variable’s data type.
If you have IBM SPSS Data Collection Survey Reporter Professional, the Job.TableDocuments
property returns a collection of TableDocument objects, one for each output data source
that is written using a CDSC that is also read-enabled. A TableDocument object is not
available for non-Data Model format output data sources or IBM® SPSS® Quantum™-format
output data sources (because the Quantum CDSC is not read-enabled). Note that although
you can define your tables in the OnJobStart, OnNextCase, OnBadCase, OnJobEnd, and
OnAfterMetadataTransformation Event sections, you cannot populate or export your tables in
these sections. (Attempting to do so may lead to an error.) You should populate and export the
tables in the OnAfterJobEnd Event section. For more information, see the topic Table Scripting in
a Data Management Script on p. 451.
GlobalVariables. The GlobalVariables object is of type IDataManagerGlobalVariables and is

available in the script as an intrinsic variable called dmgrGlobal. This collection enables you
to share objects between the OnAfterMetaDataTransformation, OnJobStart, OnNextCase,
OnBadCase, and OnJobEnd Event sections. For example, you can add an object to this collection
in the OnJobStart Event section and access the object in the OnNextCase, OnBadCase, and
OnJobEnd Event sections.
Global SQL variables. If you define any global SQL variables in the GlobalSQLVariables section,
each global SQL variable is available with the name defined for it in the GlobalSQLVariables
section.
Questions. The Questions object is available in the script as an intrinsic variable called
dmgrQuestions. The Questions collection contains a Question object for each variable included in
the SelectQuery statement in the InputDataSource section. In addition, each of these variables is
available as a Question object with the name specified in the SelectQuery statement. For example,
if the SelectQuery statement contains the following SELECT statement, the mrScriptBasic will
automatically contain Question objects called Respondent.Serial, age, and gender.
SELECT Respondent.Serial, age, gender FROM vdata
Log. The Log object is available as an intrinsic variable called dmgrLog. Note that if your DMS
file does not have a Logging section, no logging will be performed.
276
Chapter 1
WeightEngines. The WeightEngines object is available as an intrinsic variable called

dmgrWeightEngines and returns a collection of WeightEngine objects, one for each output data
source. Note that the WeightEngine objects are automatically initialized and so you do not need to
call the WeightEngine.Initialize method. In fact calling this method is likely to lead to an error.
Objects in other object models can be accessed using the function.
Objects in the OnAfterMetaDataTransformation Event section
In the OnAfterMetaDataTransformation Event sections, the Data Management Object Model

(DMOM) registers the Job object with the mrScriptBasic engine and it is available as an intrinsic
variable called dmgrJob. You can access all of the properties on the Job object in this Event
section except for the Questions collection, which is not available.
The Job object gives you access to the input and output metadata through the
TransformedInputMetaData and TransformedOutputMetaData properties. These properties are
designed to enable you to set up card, column, and punch definitions and other custom properties
in the input and output metadata. It is important that you do not make any changes to the structure
of the input or output metadata in this section. For example, you should not add or delete variables
or categories or change a variable’s data type.
The OnAfterMetaDataTransformation Event section requires an input metadata source. This

means that you cannot use this Event section in a case data-only transfer or when are using a
non-Data Model OLE DB provider to read the data.
Objects in the OnAfterJobEnd Event sections
Provided you have specified an input metadata source, the Job object is available as an intrinsic
variable called dmgrJob in the OnAfterJobEnd Event section. You can access all of the
properties on the Job object in this Event section except for the Questions collection, which is
not available. If you have the IBM® SPSS® Data Collection Base Professional Tables Option,
the Job.TableDocuments property returns a collection of TableDocument objects, one for each
suitable output data source. For more information, see the topic Table Scripting in a Data
Management Script on p. 451.
If you have not specified an input metadata source, you can use an OnAfterJobEnd Event section,
but the Job object is not available.
Objects in other object models can be accessed using the function.
Objects in the OnBeforeJobStart Event sections
The Job object, and the other objects listed above to which it gives access, are not available
in the OnBeforeJobStart and Event section. You need to use the function to access any object
in this section.
277
Base Professional
OnBeforeJobStart Event Section
The OnBeforeJobStart Event section defines procedural code that is to be executed before any
of the data sources are opened. For example, code that uses the IBM® SPSS® Data Collection
Metadata Model to Quantum component to set up card, column, and punch specifications for
use when exporting case data to a IBM® SPSS® Quantum™ .dat file, or that sets up custom
properties to customize an export to a .sav file. For more information, see the topic Transferring
In this section you do not have access to any variables you are creating in the Metadata section.
However, you can access the new variables in the OnAfterMetaDataTransformation Event
section, and if necessary you can set up card, column, and punch definitions and other custom
properties for them there.
When exporting proprietary data, you can set up an .mdd file in the OnBeforeJobStart Event
section and then specify the .mdd file as the input metadata source in the InputDataSource section.
For more information, see the topic Creating an .mdd File From Proprietary Metadata on p. 314.
The Job object, and the other objects to which it gives access, are not available in the
OnBeforeJobStart Event sections. You need to use the function to access any object in this section.
Example
The following example shows a DMS file that contains an OnBeforeJobStart Event section that
uses the to set up card, column, and punch definitions in the input metadata so that the case data
can be exported to a Quantum .dat file using . It also uses the new MDSC capability of Quantum
DSC to create a basic Quantum specification based on the card, column, and punch definitions.
'==========================================================
'
'
'
'==========================================================
#define COPY_OF_MUSEUM_MDD "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum.mdd"
Event(OnBeforeJobStart, "Set up the card and column definitions")

Dim M2Q, MDM, MyDataSource, fso, f
' Create a copy of museum.mdd so that

' we do not update the original file...
fso.CopyFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.mdd", _
COPY_OF_MUSEUM_MDD, True)
278
Chapter 1
' Make sure that the read-only attribute is not set

Set f = fso.GetFile(COPY_OF_MUSEUM_MDD)
If f.Attributes.BitAnd(1) Then
f.Attributes = f.Attributes - 1
End If
' Create the MDM object and open the Museum .mdd file in read-write mode
Set MDM = CreateObject("MDM.Document")
MDM.Open(COPY_OF_MUSEUM_MDD)
' Check whether a Quantum DSC DataSource object already exists

On Error Resume Next
Set MyDataSource = MDM.DataSources.Find("mrpunchdsc")
If MyDataSource Is Null Then
' Create a Quantum DSC DataSource object if one doesn't already exist
Set MyDataSource = MDM.DataSources.AddNew("mrPunchDsc", "mrPunchDsc", "MDM2Quantum.dat")
End If
Set MDM.DataSources.Current = MyDataSource
Err.Clear()
' Disable error handling...
On Error Goto 0
' Create the MDM2Quantum object

Set M2Q = CreateObject("MDM2QuantumLib.MDM2Quantum")
' Set the MDM Document into the MDM2Quantum object

Set M2Q.MDMDocument = MDM
' Set the MDM2Quantum properties to use the standard Quantum

' setting of multiple cards with 80 columns. Delete these lines
' if you want to use one card of unlimited length
M2Q.SerialFullName = "Respondent.Serial"
M2Q.SerialColCount = 5
M2Q.CardNumColCount = 2
M2Q.CardNumColStart = 6
M2Q.CardSize = 80
' Run the allocation

M2Q.AllocateCardColPunch(True)
' Write the data map to a .csv file using the

' Now function to create a unique filename
M2Q.WriteToCommaSeparatedFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MDM2Quantum." + CText(CDouble(Now()
' Save the Museum .mdd file

MDM.Save()
' Use the DSC Registration component to find Quantum DSC

Dim DMComp, dscQuantum
Set DMComp = CreateObject("MRDSCReg.Components")
Set dscQuantum = DMComp.Item["mrPunchDsc"]
279
Base Professional
' Write out the specs

dscQuantum.Metadata.Save(MDM, "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Museum\Museum", Null)
MDM.Close()
End Event
Initial Catalog=" + COPY_OF_MUSEUM_MDD
End InputDataSource
#define Target "MDM2Quantum"

#Include "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS\Include\QuantumOutput.dms"
Note: This example is provided as a sample DMS file (called MDM2Quantum.dms) that is
installed with the IBM® SPSS® Data Collection Developer Library. For more information,
OnAfterMetaDataTransformation Event Section
The OnAfterMetaDataTransformation Event section defines procedural code that is to be executed

after the metadata defined in the Metadata section has been merged with the input metadata.
Typically, you would use this section in a DMS file that creates variables in the Metadata section
to set up card, column, and punch specifications or other custom properties for the new variables
before exporting case data to a IBM® SPSS® Quantum™ .dat file or a IBM® SPSS® Statistics
.sav file.
The Job object, and all of the other objects to which it gives access (with the exception of the
Questions collection) are available in the OnAfterMetaDataTransformation Event section. For
more information, see the topic Using Objects in the Event Sections on p. 274.
Note that the OnAfterMetaDataTransformation Event section is not available when you have not
specified an input metadata source.
Example
The following example uses the IBM® SPSS® Data Collection Metadata Model to Quantum
component to set up card, column, and punch definitions in the output metadata after the
metadata defined in the Metadata section has been merged with the metadata specified in
the InputDataSource section. It also uses the new MDSC capability of to create a Quantum
specification based on the card, column, and punch definitions.
The Job.TransformedOutputMetadata property is used to get the name and location of the output
metadata. If you have not specified an output metadata file name, this will be a temporary
metadata file that is created during the transformation and then deleted.
280
Chapter 1
It is important that you do not make any changes to the structure of the input or output metadata
in this section. For example, you should not add or delete variables or categories or change a
variable’s data type.
Event(OnAfterMetaDataTransformation, "Allocate card columns and create Quantum spec")
Dim M2Q, MDM

MDM.Open(dmgrJob.TransformedOutputMetaData[0])
' Create the MDM2Quantum object

Set M2Q = CreateObject("MDM2QuantumLib.MDM2Quantum")
' Set the MDM Document into the MDM2Quantum object

Set M2Q.MDMDocument = MDM
' Set the MDM2Quantum properties to use the standard Quantum

' setting of multiple cards with 80 columns. Delete these lines
' if you want to use one card of unlimited length
M2Q.SerialFullName = "Respondent.Serial"
M2Q.SerialColCount = 5
M2Q.CardNumColCount = 2
M2Q.CardNumColStart = 6
M2Q.CardSize = 80
' Run the allocation

M2Q.AllocateCardColPunch(True)
MDM.Save()
' Use the DSC Registration component to find Quantum DSC

Dim DMComp, dscQuantum
Set DMComp = CreateObject("MRDSCReg.Components")
Set dscQuantum = DMComp.Item["mrPunchDsc"]
' Write out the specs

dscQuantum.Metadata.Save(MDM, "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\OnAfterMetadataTransformation\MySpe
MDM.Close()
End Event
Notice that this example does not check for a DataSource object or set it as the current DataSource
object for the Document. This is because the DataSource object is automatically set up in the
output metadata and made the default DataSource. Also notice that this example does not call the
MDM2Quantum.ClearCardColPunch method. This means that it will preserve any card, column,
and punch definitions that have already been defined in the input metadata.
This example sets up the card, column, and punch definitions in the output metadata
only. If you want to set up the card, column, and punch defninitions in the input metadata
in the OnAfterMetadataTransformation Event section as well, you would need to use
281
Base Professional
Job.TransformedInputMetadata property to get the name and location of the input metadata
and repeat the relevant code.
Notice that the MDM Document.Close method has been called to release the MDM Document. If
we did not do this, we would get an error, typically containing the text “The process cannot access
the file because it is being used by another process”.
Note: This example is included in a sample DMS file (called

OnAfterMetaDataTransformation.dms) and as a separate Include file (called CardColsExtra.dms)
that are installed with the IBM® SPSS® Data Collection Developer Library. For more
information, see the topic Sample DMS Files on p. 467.
OnJobStart Event Section
Used to define procedural code that is to be executed after all of the data sources have been opened
and before the processing of the first case begins. For example, code to set up global variables that
are used in the OnNextCase, OnBadCase, and OnJobEnd Event sections.
Note that the OnJobStart Event section is not available when you have not specified an input
metadata source. If you attempt to include an OnJobStart Event section in a case data-only
transformation or when using a non-Data Model OLE DB provider, you will typically get an
“Object reference not set to an instance of an object” error.
For information about accessing objects in this section, see Using Objects in the Event Sections.
Example
This example shows setting up:

A report file. The function is used to create a FileSystemObject, which is a standard Microsoft
object for working with folders and files. The FileSystemObject.CreateTextFile method is then
called to create a text file object, which is added to the job’s global variables collection so that
it can be accessed in the OnNextCase and OnJobEnd Event sections.
A default response for a question. The Response.Default property is used to set up a default
response for a question called expect. This means that the Validation.Validate method can be
used to assign the default value to the question in the OnNextCase Event section.
Event(OnJobStart, "Do the set up")

Dim fso, txtfile
Set txtfile = fso.CreateTextFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Cleaning.txt", True, True)
dmgrGlobal.Add("mytextfile")
Set dmgrGlobal.mytextfile = txtfile
expect.Response.Default = {general_knowledge_and_education}
End Event
For more data cleaning examples, see Data Cleaning Examples.

282
Chapter 1
OnNextCase Event Section
Used to define procedural code that is to be applied to each case. For example, code to clean the
case data or set up case data for persisted derived variables.
An error occurs if you attempt to assign a value of the wrong type to a question, for example,
attempting to assign a string value to a numeric question.
Note that the OnNextCase Event section is not available when you have not specified an input
metadata source. If you attempt to include an OnNextCase Event section in a case data-only
“Object reference not set to an instance of an object” error. For information about accessing
objects in this section, see Using Objects in the Event Sections.
Unbounded loops are available in the OnNextCase event with an HDATA view (available to
read/write the response value and add/remove iterations).
Examples
Data Cleaning Example
This example tests the response to the visits numeric question. This question asks how many
times the respondent has visited the museum previously and is only asked if he or she selected
Yes in response to the before question, which asks whether he or she has visited the museum
before. If the visits question holds a NULL value or is zero, the response to the before question is
automatically set to No, and otherwise the response to the before question is set to Yes. A string is
set up to hold the respondent’s serial number and the response to the before question after cleaning
and this string is then written to the log file. The DMS file would need to have a Logging section.

Dim strDetails

If visits = 0 Then
before = {No}
Else
before = {Yes}
strDetails = strDetails + " Before = Yes"
End If
Else
before = {No}
End If
dmgrJob.Log.LogScript_2(strDetails)
End Event
283
Base Professional
For more data cleaning examples, see Data Cleaning Examples. For examples of setting up data
for new variables in the OnNextCase Event section, see Creating New Variables.
Unbounded Loop Question Example
This example uses the Household data set to read, modify, add iterations, and delete iterations in
the person loop.
Event(OnNextCase, "Manipulate unbounded question")

Dim Quest, Level1Quest, Level2Quest, Level3Quest
'Numberic Loop for Person, and Unbound loop for Trip
'read and modify

for each Quest in person
For each Level2Quest in Quest.trip
For each Level3Quest in Level2Quest
'set country value with 'canada'
if Level3Quest.QuestionName = "country" then
Level3Quest = "canada"
end if
Next
Next
Next
'add new record

if person[2].age = null then
'add person's iteration 2
person[2].age = 35
person[2].numtrips = 0
person[2].name = "new added person"
'add trip's iteration one in person iteration 2
person[2].trip[1].country = "canada"
person[2].trip[1].daysaway = 1
person[2].trip[1].trip = 1
end if
'delete existing record

for each Quest in person
For each Level1Quest in Quest.trip
if Level1Quest.QuestionName = 2 then
'remove all value in current record will remove current record
For each Level2Quest in Level1Quest
Level2Quest = null
Next
end if
Next
Next
End Event
284
Chapter 1
OnBadCase Event Section
Used to define procedural code that is to be executed for each “bad” case, that is, a record that will
not be transferred to the output data source because it has failed the validation. You typically use
the OnBadCase event section to create a report of bad cases, for example, by writing the details of
the invalid record to a text file. You could then email the text file in the OnJobEnd event section.
Note that you cannot use the OnBadCase event to correct the error or errors that caused the record
to fail validation. If you want to clean your records during the transfer, use the OnNextCase event
section. Also note that if your data management script includes a Logging Section, full details of
each bad record will be automatically written to the log.
Depending on the options set for the data transfer, the OnBadCase event might not be executed for
some or all records that contain errors. For more information, see the topic Validation Options
When Transferring Data on p. 336.
The OnBadCase Event section is available only when you have specified an input metadata
source. If you attempt to include an OnBadCase Event section in a case data-only transformation
or when using a non-IBM® SPSS® Data Collection Data Model OLE DB provider, you will
typically get an “Object reference not set to an instance of an object” error.
Example
This example writes a message to a text file for each bad case. The message includes the value of
the record’s Respondent.Serial variable.
The example also increments a count of bad cases, which will be written to the text file in the
OnJobEnd event. The count of bad cases is stored in a global variable called BadCaseTotal.
Event (OnBadCase, "Output details of the bad case")

' For each bad case, write a message to the text
' file and the console...
Dim txtmsg
txtmsg = "Bad case - Record not transferred for respondent: " + _
CText(Respondent.Serial)
dmgrGlobal.MyTextFile.WriteLine(txtmsg)
Debug.Log(txtmsg)
' Increment the count of bad cases...

dmgrGlobal.BadCaseTotal = dmgrGlobal.BadCaseTotal + 1
End Event
This example is part of a sample DMS file called OnBadCase.dms, which is installed with the
285
Base Professional
OnJobEnd Event Section
Used to define procedural code that is to be executed after all of the processing of the individual
cases has been completed and before the data sources are closed. For example, code that closes
report files, or uses the Weight component to set up weighting in the output data source. For more
information, see the topic Setting Up Weighting in a DMS File on p. 431.
Note that the OnJobEnd Event section is not available when you have not specified an input
metadata source. If you attempt to include an OnJobEnd Event section in a case data-only
“Object reference not set to an instance of an object” error.
Example
This example closes a text file that was created and added to the GlobalVariables collection in the
OnJobStart Event Section
Event(OnJobEnd, "Close the text file")
dmgrGlobal.mytextfile.Close()
End Event
OnAfterJobEnd Event Section
Used to define procedural code that is to be executed after the data source connections are closed.
For example, code to create tables or call the function to open a report file.
Provided you have specified an input metadata source, the Job object is available in the
OnAfterJobEnd Event section as an intrinsic variable called dmgrJob. You can use the Job object
to access all of the other objects to which it gives access (with the exception of the Questions
collection). For more information, see the topic Using Objects in the Event Sections on p. 274.
You can use the function to access other objects in this section.
If you have IBM SPSS Data Collection Survey Reporter Professional and want to script tables
in a DMS file, you typically include the code in the OnAfterJobEnd Event section. For more
information, see the topic Table Scripting in a Data Management Script on p. 451.
Examples
1. Creating tables in Excel
This example uses ADO to access the case data in the output data source and advanced SQL
queries to set up some tables in Excel. Note each table is created on a separate worksheet.
'==========================================================
'
286
Chapter 1
'
'
'==========================================================
Event(OnAfterJobEnd, "Create tables")

Dim ConnectionString, sqlQuery, adoConnection, adoRS, i
Dim xlApp, xlWorkbook, xlWorksheet
ConnectionString = "Provider=mrOleDB.Provider.2; Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelTa
Set adoConnection = CreateObject("ADODB.Connection")

adoConnection.Open(ConnectionString)
Set xlApp = CreateObject("Excel.Application")

xlApp.Visible = true
Set xlWorkbook = xlApp.Workbooks.Add()
' Table of age by gender
Set xlWorksheet = xlWorkbook.Worksheets[1]

sqlQuery = "SELECT groupby.col[0] AS Age, SUM(gender = {male}) AS Male, SUM(gender = {female}) AS Female FROM vdata GROUP BY ag
Set adoRS = adoConnection.Execute(sqlQuery)
DisplayTable(adoRS, xlWorksheet)
' Table of interest by gender
If xlWorkbook.Worksheets.Count > 1 Then

Else
Set xlWorksheet = xlWorkbook.Worksheets.Add(, xlWorkbook.Worksheets[1])
End If
sqlQuery = "SELECT groupby.col[0] AS Interest, SUM(gender = {male}) AS Male, SUM(gender = {female}) AS Female FROM vdata WHERE in
' Visits summary data
If xlWorkbook.Worksheets.Count > 2 Then

Else
Set xlWorksheet = xlWorkbook.Worksheets.Add(, xlWorkbook.Worksheets[2])
End If
sqlQuery = "SELECT SUM(visits) AS TotalVisits, AVG(visits) AS AverageVisits, MIN(visits) AS MinimumVisits, MAX(visits) AS MaximumVisit
xlWorkBook.SaveAs("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelTables.xls")
adoConnection.Close()
287
Base Professional
Sub DisplayTable(RecordSet, WorkSheet)

Dim xlStartRow, xlStartColumn, xlCol, xlRow, i
xlStartRow = 1
xlStartColumn = 1
xlCol = xlStartColumn
xlRow = xlStartRow
Dim xlCell
For i = 0 to (RecordSet.Fields.Count - 1)
Set xlCell = WorkSheet.Cells[xlRow][xlCol]
xlCell.FormulaR1C1 = RecordSet.Fields[i].Name
xlCol = xlCol + 1
Next
If Not RecordSet.EOF Then

xlRow = xlStartRow + 1
Do Until RecordSet.EOF
xlCol = xlStartColumn
For i = 0 to (RecordSet.Fields.Count - 1)
WorkSheet.Cells[xlRow][xlCol].FormulaR1C1 = RecordSet[RecordSet.Fields[i].Name]
xlCol = xlCol + 1
Next
xlRow = xlRow + 1
RecordSet.MoveNext()
Loop
End If
End Sub
End Event
Note: This example is provided as a sample DMS file (called MSExcelTables.dms) that is installed
with the IBM® SPSS® Data Collection Developer Library. For similar examples that create
charts in Excel and top line tables in Word, see the MSExcelCharts.dms and MSWordToplines.dms
sample Include files. For more information, see the topic Sample DMS Files That Integrate with
Microsoft Office on p. 475.
288
Chapter 1
Here is the table on the first Excel worksheet:
2. Opening a report file
This example calls the function to open the report file set up in the cleaning example described in
2. A Complete Example. (This example is provided as a sample DMS file called Cleaning.dms.
For more information, see the topic Sample DMS Files on p. 467.)
If you add the following code to the sample, the report file will open at the end of the job.
Event(OnAfterJobEnd, "Open report file")
ShellExecute("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\Cleaning.txt")
End Event
Alias
In a Logging Section, specifies the name to be used in the log file.
ConnectionString
In an InputDataSource Section, an OutputDataSource Section, or a GlobalSQLVariables Section,

specifies the OLE DB connection properties.
FileSize
In a Logging Section, specifies the maximum size of the log file.
Group
In a Logging Section, specifies the application group that writes the log and defines the first
three characters of the log filename.
JoinKey
In an InputDataSource Section, specifies the variable used to join the data source to other input
data sources when running a case data merge.
JoinKeySorted
289
Base Professional
In an InputDataSource Section, specifies whether to sort the data source when running a case
data merge.
JoinType
In an InputDataSource Section, specifies the type of join to perform when running a case data
merge.
MetaDataOutputName
In an OutputDataSource Section, specifies the name and location of the Metadata Document
(.mdd) file to which the exported metadata is written.
Path
In a Logging Section, specifies the location of the log file.
SelectQuery
In an InputDataSource Section or a GlobalSQLVariables Section, specifies the SQL query to

execute.
TableOutputName
In an OutputDataSource Section, specifies the name of the database table when writing the case
data to a non-IBM® SPSS® Data Collection Data Model OLE DB provider.
UpdateQuery
1. In an InputDataSource Section, specifies an SQL query to execute on the data source before
any processing takes place.
2. In an OutputDataSource Section, specifies an SQL query to execute on the data source after
all other processing has completed.
UseInputAsOutput
1. In an InputDataSource Section, specifies that the output case data should be written to this input
data source when running a case data merge.
2. In an OutputDataSource Section, specifies that the output case data should be written to the
input data source.
DMS Runner
DMS Runner is a command prompt utility that is installed with IBM® SPSS® Data Collection
Base Professional. DMS Runner enables you to run a DataManagementScript (DMS) file.
Typically DMS files have a .dms filename extension.
290
Chapter 1
You can create your DMS files using Base Professional or a standard text editor, such as Notepad.
When using a text editor, make sure that you save your DMS files using the Unicode or UTF-8
text format option and not the ANSI option if the files contain non-Western European characters.
By default, DMS Runner validates the DMS file, which involves checking that the correct syntax
has been used. For example, DMS Runner checks the connection strings and SQL syntax defined
in the InputDataSource and OutputDataSource sections, the mrScriptMetadata defined in the
Metadata Section, and the mrScriptBasic syntax in the Event sections. Note that this pre-execution
validation checks the mrScriptBasic syntax only and not that the names of any questions referred
to in the mrScriptBasic code are correct or that those questions are included in the transformation,
for example. However, these things are automatically checked when the file is executed. Use
the /novalidate option if you want to run a DMS file without first validating it. However, it is
recommended that you use the validate option.
When encountering an mrScriptBasic or mrScriptMetadata error either during the validation

process or during the execution of the file, DMS Runner will display a message that includes the
approximate line number at which the error was encountered. This represents the line number
within the expanded file (that is, after any #Include and #Define statements have been expanded
and comments and invalid code between sections have been removed). You can use the /a option
to save the expanded file.
What happens when the DMS Runner encounters a record that cannot be written to the output data
source depends on whether you are using the option to validate the data. (You choose this option
by setting the MR Init Validation connection property to True in the OutputDataSource section.
See Validation Options When Transferring Data for more information.)
When validation is selected, by default DMS Runner displays an “Error writing record:
<Record number>” message on the screen and continues with the run. If the DMS file has a
Logging sectionLogging section, DMS Runner also writes the record and the message to the
log file. At the end of the run, DMS Runner displays the total number of “bad” records that
were encountered. (A “bad” record is a record that fails the validation.) However, you can
make the run stop if DMS Runner encounters a record that fails the validation. You do this
using the /break option when you run the file.
If validation is not selected, DMS Runner stops if it cannot write a record for any reason.
If you have more than one OutputDataSource section and validation is selected in one (or
more) and not in another one (or more), DMS Runner will stop exporting records to the data
sources for which validation is not being used when it encounters a record that cannot be
written, however, it will continue exporting data to the data source(s) for which validation is
selected, unless you select the /break option when you run the file.
DMS Runner automatically sets the current folder to be the location of the DMS file. This means
that in your DMS files, you can refer to file locations using a relative path (relative to the location
of the DMS file), or no path if the files are located in the same folder as the DMS file.
If necessary, you can stop DMS Runner by pressing Ctrl-C. However, when you do this, any
output that has been generated is likely to be corrupt or unusable.
291
Base Professional
Syntax
DMSRun filename.extension [<options>]
filename.extension specifies the location, name, and filename extension of the DMS file that you
want to run. If the file location or filename contains spaces, enclose filename.extension in double
quotation marks (“ “). If you change to the folder in which your DMS file is located, you do not
need to specify the location of the DMS file.
The options are described in the following table.

Option Description
/s Run in silent mode. This means that progress
statements will not be displayed.
/novalidate Do not validate the DMS file.
/norun Do not run the DMS file. This option is useful when
you want to validate a file without running it.
/break Makes DMS Runner stop the run if it encounters a
record that fails validation.
/x If the run fails when you are using this option,
DMS Runner saves the application state to an
XML file. This has a filename of the form
myFile_exception_yyyymmdd_hhmmss.xml, where
yyyy represents the year, mm the month, etc. If you
need to contact IBM® SPSS® Data Collection
Technical Support because of the failure of a DMS
file, you may be asked to run the file again using
this option and send the XML file to the support
consultant.
/a:filename Expand any include files and save the expanded
DMS file to the name and location specified in
filename. This is useful when you are using the
include feature and need to debug your code,
because the line numbers shown in mrScriptBasic
and mrScriptMetadata error messages refer to the
line numbers in the expanded file. Similarly, if you
are using the text replacement feature, the expanded
file enables you to see how the texts were replaced.
/dA Defines the specified variable A in the expanded
DMS file. Note that you can use this option more
than once.
/d"A B" Replaces all occurrences of A in the expanded DMS
file with B. Occurrences of A that occur within string
literals are not replaced, however. The search is case
sensitive. Note that you can use this option more
than once to specify multiple texts to be replaced.
/d"A \”B\”" Replaces all occurrences of the specified text A in
the expanded DMS file with a specified replacement
text B within quotation marks. Occurrences
of A that occur within string literals are not
replaced, however. This format is required when
double-quotes are needed in the definition, in
order to get a text string value. The search is case
sensitive. Note that you can use this option more
than once.
292
Chapter 1
Option Description
/d"A(x y) f(x, y)"y Defines the specified variable A in the expanded
DMS file as a function of arguments x and y, with
a value of f(x, y). Note that you can use this option
more than once.
/loc:<location> Optional. The package extraction destination. If
a location is not specified, the default location
(C:\Documents and Settings\<User Name>\Temp)
is used to extract the .dmz package and execute
script.
/p:priority Set the process priority to the specified value. This
controls how fast the process runs. The Idle and
BelowNormal values are useful for jobs you want
to run overnight, for example, with the minimum
impact on other processes that are running. Possible
values are shown in the table below. Note that using
the AboveNormal, High, and RealTime priorities
can adversely affect the performance of other
processes. The default is Normal.
/? Display the syntax and options.
The following table shows the possible values for the priority parameter.
Value Description
Low This is the lowest possible priority value.
BelowNormal Specifies a priority that is one step below the normal.
Normal Specifies the normal priority. This is the default
value.
AboveNormal Specifies a priority that is one step above the normal.
High Specifies a high priority.
RealTime Specifies the highest priority.
Examples
The following example runs the Simple.dms sample file using the default options (validation,
normal priority, and not silent.) This example assumes that you have already changed to the
folder where Simple.dms is located:
DMSRun Simple.dms
The following example runs the same file without validating it:
DMSRun Simple.dms /novalidate
The following example runs the DMSRunExample.dms sample file after replacing all occurrences
of the text Target with the text string “MyOutputTestFile”, and also after replacing the text
LogSize with the text 350:
DMSRun DMSRunExample.dms /d"Target \"MyOutputTestFile\"" /d"LogSize 350"

293
Base Professional
If you do not change to the folder where Simple.dms or DMSRunExample.dms is located, you
would need to specify the location of the file. For example:
DMSRun "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS\Simple.dms"
The following example runs a .dmz package using the default location:
DMSRun "test.dmz"
The following example runs a .dmz package using a specified location:
DMSRun "test.dmz" /loc:"c:\test"
Tip: You can use the At command or the Windows Scheduled Task wizard to schedule the
execution of your DMS files, for example, during the night or at regular intervals. For more
information, see the topic Scheduling the Running of DMS Files on p. 294.
Requirements
Base Professional 2.0 or later
To Run a DMS File
E From the Windows Start menu, choose:

Programs > IBM® SPSS® Data Collection > IBM® SPSS® Data Collection Base Professional 6.0.1
> Tools > DMSRun Prompt
E Type DMSRun followed by the location and name of the file you want to run and the options
that you require.
Tips:
If you change to the folder in which your DMS file is located, you do not need to specify the
location of the DMS file.
An easy way to run a DMS file in Windows Explorer is to drag the DMS file
to the folder in which DMSRun.exe is installed and simply drop the file on
DMSRun.exe. By default DMSRun.exe is installed into C:\Program Files\Common
Files\IBM\SPSS\DataCollection\6\\DMOM\6.0.1.0.0.
If necessary, you can stop DMS Runner by pressing Ctrl-C. However, note that when you do
this, any output that has been generated is likely to be corrupt or unusable.
You can use the At command or the Windows Scheduled Task wizard to schedule the
execution of your DMS files, for example, during the night or at regular intervals. For more
information, see the topic Scheduling the Running of DMS Files on p. 294.
Requirements
IBM® SPSS® Data Collection Base Professional 2.0 or later

294
Chapter 1
Scheduling the Running of DMS Files
Sometimes you may want to run your DMS files unattended (for example, at night) or schedule a
batch export to be run at regular intervals. You can achieve this using the At command or the
Windows Scheduled Task wizard.
You can use the Scheduled Tasks window to view and modify the tasks that you have scheduled.
The Task Scheduler records in a log file details of the tasks that run and any errors that are
encountered. The log file is useful when you want to check on the success of tasks that run in the
background or overnight, for example, and when investigating tasks that fail to run successfully.
Here is the Scheduled Tasks window showing two scheduled tasks that have been set up to run
DMS files. The first task was defined using the Task Scheduler wizard and the second using
the At command:
To open the Scheduled Tasks window:

Settings > Control Panel
E In the Control Panel, choose Scheduled Tasks.
This opens the Scheduled Tasks window.
To schedule the running of a DMS file:
There are two ways to schedule the running of a DMS file:

Using the At command
Using the Scheduled Task wizard
To amend a scheduled task:
E Double-click the task in the Scheduled Tasks window.
This opens the tasks dialog box.

To: Do this:
Temporarily stop a task from running. On the Task tab, deselect Enabled (scheduled task
runs at specified time).
Change the dates, times, and intervals at which the On the Schedule tab, select the options you require.
task is to be run. Optionally click Advanced for further options.
295
Base Professional
To: Do this:
Automatically delete a task if it is not scheduled to On the Settings tab, select Delete the task if it is not
be run again. scheduled to run again.
Stop a task being automatically deleted if it is not On the Settings tab, deselect Delete the task if it is
scheduled to be run again. not scheduled to run again.
To manually delete a scheduled task:
E In the Scheduled Tasks window, select the task you want to delete.
E Press Delete.
To view the scheduled tasks log:
E From the menus in the Scheduled Tasks window, choose:

Advanced > View Log
Using the At Command to Schedule a DMS File
The At command schedules commands to run at one or more specified times. The At command
provides a number of scheduling options. This topic provides detailed instructions for scheduling
a DMS file to be run once later today and to be run once every day of the week. However, you are
not limited to these options. Refer to the Microsoft documentation for full details. (Type Help
At at the command prompt for information on the command.)
To open the command prompt:

Programs > Accessories > Command Prompt
To schedule a DMS file to be run later today:
E At the command prompt, type At followed by:

The time you want the file to be run. This should be expressed in the form hh:mm, where hh is
the hour in 24 hour notation and mm is the minute.
The full location and name of the DMSRun program. By default this is C:\Program
Files\Common Files\IBM\SPSS\DataCollection\6\\DMOM\6.0.1.0.0\DMSRun.exe. You must
enclose the name and location in quotation marks (“ “) if the location contains spaces.
The full name and location of the DMS file you want to run. You must enclose this in quotation
marks if there are any spaces. Note that the default sample file locations may exceed the
number of characters that are allowed. If necessary, copy the files to a new shorter location.
E Press Enter.
For example, to run C:\Samples\DMS Files\Cleaning.dms at 4.30pm, enter:
At 16:30 "C:\Program Files\Common Files\IBM\SPSS\DataCollection\6\\DMOM\6.0.1.0.0\DMSRun.exe" "C:\Samples\DMS Files\Cleaning.dms

296
Chapter 1
To schedule a DMS file to be run every day:
E At the command prompt, type At followed by:

The time you want the file to be run.
/every: followed by the days you want to run the file. For example: /every:m,t,w,th,f,s,su
specifies every day of every week; /every:m,w,f specifies every Monday, Wednesday, and
Friday; /every:1,11,21 specifies the 1st, 11th, and 21st day of every month.
The full location and name of the DMSRun program.
The full name and location of the DMS file you want to run.
E Press Enter.
For example, to run C:\Samples\DMS Files\Cleaning.dms at 10.30pm every day, enter:
At 22;30 /every:m,t,w,th,f,s,su "C:\Program Files\Common Files\IBM\SPSS\DataCollection\6\\DMOM\6.0.1.0.0\DMSRun.exe" "C:\Samples\DM
Tips
By default, when the file is run, the processing will take place in the background. If you want
to see the DMS file being run, use the /interactive option. You specify this immediately
after the time. For example:
At 15:41 /interactive "C:\Program Files\Common

Files\IBM\SPSS\DataCollection\6\\DMOM\6.0.1.0.0\DMSRun.exe" "C:\Samples\DMS Files\cleaning.dms"
You can get help on the At command by typing Help At at the command prompt and pressing
Enter.
You must include the filename extensions for both DMSRun and your DMS file.
Enclose the filename and location in quotation marks (“ “) if there are any spaces.
Note that the default sample file locations may exceed the number of characters that are
allowed. If necessary, copy the files to a new shorter location.
You can use a batch file to run multiple DMS files and schedule it for running later. Remember
to specify the location and filename extensions. The CategoricalsOnly.bat sample batch file
that comes with the IBM® SPSS® Data Collection Developer Library provides an example
of a batch file that has been set up so that it can run as a scheduled task. For example, to
schedule it to be run at 1.30pm, you could enter:
At 13:30 "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\Batch\CategoricalsOnly.bat"
When you use the At command to set up tasks that are to be run once only, by default the
option to automatically delete them after running is selected. If you want to retain the task,
you can deselect this option in the Scheduled Tasks window before the task is run.
Using the Scheduled Task Wizard to Schedule a DMS File
You can schedule a DMS file to be run later or at regular intervals using the Scheduled Task
wizard. This topic provides step-by-step instructions. For further information, refer to the
Windows documentation.
297
Base Professional

Settings > Control Panel
E In the Control Panel, choose Scheduled Tasks.
E Double-click Add Scheduled Task.
This opens the Scheduled Task wizard.
E Click Next.
This opens a list of some of the programs installed on your computer.
E Click Browse and browse to the folder in which DMS Runner is installed. Typically this is
C:\Program Files\Common Files\IBM\SPSS\DataCollection\6\\DMOM\6.0.1.0.0.
E Select DMSRun.exe and click Open.
E Optionally enter a name for the task and then select when you want the task to be run.
E Click Next.
E Select the required time and start date, and when you want the task to be run.
298
Chapter 1
E Click Next.
E Enter your user name and password.
E Click Next.
E Select Open advanced properties for this task when I click Finish.
E Click Finish.
299
Base Professional
E In the Run text box, enter the name of the DMS file you want to run. Make sure you place the
name of your DMS file after the DMSRun.exe filename and location. Enclose the name in
quotation marks (“ “) if it contains spaces.
E Enter the location of the DMS file in the Start In text box. Enclose the location in quotation
marks if it contains spaces.
E Select Enabled (scheduled task runs at specified time).
E Select the Schedule tab.

300
Chapter 1
E Select the options you require. You can optionally click Advanced for additional options.
E Click OK.
You should now be able to see your new task in the Scheduled Tasks window.
WinDMSRun
WinDMSRun is a simple Windows application that comes with the IBM® SPSS® Data Collection
Developer Library. The Visual Basic .NET source code is provided as a reference for developers
who are creating applications using the Data Management Object Model (DMOM). For more
information, see the topic WinDMSRun as Programmer’s Reference on p. 309.
301
Base Professional
You can use WinDMSRun to create, modify, validate, and run DataManagementScript (DMS)
files. WinDMSRun is particularly useful when you are learning about DMS files because you can
use the Windows interface to specify the details of the input and output data sources and the filters
to use and WinDMSRun automatically generates the DMS file code for you.
When you first open WinDMSRun, it opens on the Normal tab. You open an existing DMS file
using the Open command on the File menu. You can start a new DMS file by using the New
command on the File menu, although you do not need to do this when you first start WinDMSRun,
because a new file is started automatically.
You can see the code in the DMS file at any time by clicking the Script tab. You can edit the code
on the Script tab and add new sections, such as Event and Metadata sections. However, working
on the Script tab is not the same as working in IBM® SPSS® Data Collection Base Professional
or a text editor, because each time you switch between the tabs or save and reopen your file,
WinDMSRun regenerates the code. For example, WinDMSRun expands any #Include and #Define
statements and removes comments between sections. In fact, switching between the two tabs is
like using the /a and /norun options in DMS Runner to save the expanded file without running it.
You may therefore want to take a backup of your DMS files before opening them in WinDMSRun.
You can save the file using the Save and Save As commands on the File menu and you can
validate it using the Validate Job command on the Tools menu.
You can view the input data selected for the transfer on the Input Data tab and, after you have run
(executed) the transfer, you can view the output data on the Output Data tab.
Note: New files are automatically based on a template, called Default.dms, which is stored in
the <%UserProfile%>\Application Data\SPSS MR\WinDMSRun folder. The location of the
<%UserProfile%> folder varies on different operating systems. For example, on Windows 2000,
it is typically C:\Documents and Settings\<UserName>, where <UserName> is your user name.
You can change the template file that is used using the Save As Default command on the File
menu, or by replacing the Default.dms file with another one of the same name.
Requirements
Starting WinDMSRun
E In Windows Explorer, browse to the folder where WinDMSRun was installed.
Typically this is the

[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Code\Tools\VB.NET\WinDMSRun
folder.
E Double-click WinDMSRun.exe.
Tip: You can have more than one occurrence of WinDMSRun open at a time.
302
Chapter 1
Requirements
WinDMSRun Window: Normal Tab
You use the Normal tab to set up the connection string and select query for the InputDataSource
section and the connection string for the OutputDataSource section of your DMS file.
1. Select input data. This opens the Data Link Properties dialog box, which you can use to build
the connection string for the input data source. Typically, the dialog box opens on the Connection
tab with the IBM SPSS Data Collection OLE DB Provider automatically selected on the Provider
tab. However, the exact behavior depends on the DMS file you are working on or, on your
default DMS file, if you are starting a new file. Both the MDSC and the CDSC you select must
be read-enabled. If you are using a Metadata Document (.mdd) file, it must be writable and you
need to select Open metadata read/write. If you want to select all versions or one or more specific
versions, click the Properties button. For more information, see the topic WinDMSRun Window:
Selecting Versions on p. 303. On the Advanced tab, make sure that Return data as category values
is selected. For more information, see the topic Reading Data on p. 311.
2. Select output data. This opens the Data Link Properties dialog box again, this time to build
the connection string for the output data source. Again, the dialog box typically opens on the
Connection tab with the IBM SPSS Data Collection OLE DB Provider automatically selected on
the Provider tab. Select None for the Metadata Type. The CDSC you select must be write-enabled.
On the Advanced tab, make sure that Return data as category values is selected and select the
validation options you require. For more information, see the topic Writing Data on p. 335.
303
Base Professional
3. Select output metadata. This opens the Save As dialog box, in which you can specify the name
and location of the output metadata file.
4. Select variables to transfer. This opens the Variable Selection dialog box, which lists all of the
variables defined in the MDM Document and which you use to define the metadata filter. Either
deselect Select all and then select the individual variables you want to transfer, or select Select
all to transfer all of the variables. For more information, see the topic WinDMSRun Window:
Variable Selection on p. 305.
5. Select filtering of data to transfer. This opens the Case Selection dialog box, which contains a
number of options and drop-down list boxes that you can use to define a case data filter. For more
information, see the topic WinDMSRun Window: Case Selection on p. 305.
6. Execute job. Run the job. However, this does not automatically validate the job before running
it. It is therefore recommended that you validate it first. You do this using the Validate Job
command on the Tools menu.
Requirements
WinDMSRun Window: Selecting Versions
E When you select the .mdd file for the input data source, click the Properties button.
This opens the Metadata Properties dialog box.

304
Chapter 1
The Version drop-down list box lists the individual versions that are available, plus options to
select all versions, the latest version, and multiple versions.
E Select the item from the list that you want to use, and click OK. For more information, see the
topic Data Link Properties: Metadata Properties on p. 73.
Selecting the Multiple Versions option opens the Metadata Versions dialog box. This lists all
of the versions that are available.
E Select the version or versions that you want to use, and then click OK. For more information, see
the topic Data Link Properties: Metadata Versions on p. 74.
Requirements

305
Base Professional
WinDMSRun Window: Variable Selection
You use the Variable Selection dialog box to set up a metadata filter for your DMS file. The
metadata filter specifies the variables to be included in the select query for the InputDataSource
section of your DMS file. For more information, see the topic Filtering Data in a DMS File
on p. 243.
If you want to include all of the variables in the transfer, select Select all. This is equivalent to
specifying “SELECT * FROM vdata” in your select query.
If you want to restrict the transfer to specific variables, deselect Select all and then select the
individual variables you want to transfer.
Requirements
WinDMSRun Window: Case Selection
You use the Case Selection dialog box to set up a case data filter for your DMS file. The case data
filter specifies the WHERE clause in the select query for the InputDataSource section of your
DMS file. For more information, see the topic Filtering Data in a DMS File on p. 243.
The Case Selection dialog box is designed for use with data collected using IBM® SPSS® Data
Collection Interviewer Server and makes it easy to filter out test, active, and timed out records,
and to select records based on the date they were collected, etc.
306
Chapter 1
Requirements
WinDMSRun Window: Script Tab
The Script tab in the WinDMSRun window displays the contents of the DMS file that you have
defined on the Normal tab. You can save the file using the Save and Save As commands on the
File menu and you can validate it using the Validate Job command on the Tools menu.
You can also edit the code on the Script tab and add new sections, such as Event and Metadata
sections. However, working on the Script tab is not the same as working in IBM® SPSS® Data
Collection Base Professional or a text editor, because each time you switch between the tabs
or save and reopen your file, WinDMSRun regenerates the code. For example, WinDMSRun
expands any #Include and #Define statements and removes comments between sections. In fact,
switching between the two tabs is like using the /a and /norun options in DMS Runner to save
the expanded file without running it.
307
Base Professional
Requirements
WinDMSRun Window: Input Data Tab
The Input Data tab in the WinDMSRun window displays the data that you have selected for the
transfer. To see the data, you need to click Refresh on the lower part of the tab.
308
Chapter 1
You can sort the rows in the grid on any of the columns by clicking the heading of the column by
which you want to sort. When you change the sort order, a small arrow appears in the column
heading to indicate that this is the active column, and to show whether the sort order is ascending
or descending. Click the heading again to swap between ascending and descending order.
You can copy rows in the grid and paste them into other applications, such as Excel. You do this
by selecting the rows you want to copy on the left side and pressing Ctrl+C.
Note: WinDMSRun cannot display the case data on the Input Data tab when the DMS file
contains a GlobalSQLVariables section.
Requirements
WinDMSRun Window: Output Data Tab
The Output Data tab in the WinDMSRun window displays the transferred data. Like the Input
Data tab, you need to click Refresh on the lower part of the tab to see the data. However, you
will get an error if you do this before running the transfer. You can run the transfer by choosing
Execute from the Tools menu.
309
Base Professional
You can sort the rows in the grid on any of the columns by clicking the heading of the column by
which you want to sort. When you change the sort order, a small arrow appears in the column
heading to indicate that this is the active column, and to show whether the sort order is ascending
or descending. Click the heading again to swap between ascending and descending order.
You can copy rows in the grid and paste them into other applications, such as Excel. You do this
by selecting the rows you want to copy on the left side and pressing Ctrl+C.
Requirements
WinDMSRun as Programmer’s Reference
The IBM® SPSS® Data Collection Developer Library comes with the Visual Basic .NET source
code for WinDMSRun, which is a simple Windows tool that you can use to set up and run
DataManagementScript (DMS) files. The source code is provided as a reference for developers
who are creating applications using the Data Management Object Model (DMOM).
To compile the source code you need to have both IBM® SPSS® Data Collection Base
Professional 2.1 or later and Visual Basic .NET installed. To run the executable file, you need to
have Base Professional 2.1 or later installed.
By default the executable file and the source code are installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Code\Tools\VB.NET folder.
310
Chapter 1
Warning
You can use the source files as a starting point when you develop your own applications, etc.
However, it is always advisable to work on a copy of the files rather than working on the sample
files directly. This means you will avoid losing your work when you uninstall or upgrade to a new
version of the Data Collection Developer Library.
Requirements
Transferring Data Using a DMS File

You can use a DMS file to transfer case data from one format or location to another. Generally a
DMS file uses the IBM® SPSS® Data Collection Data Model and its data source components
(DSCs), to read and write data in different formats. For an introduction to DSCs and information
about the DSCs that are supplied with the Data Model, see .
You can transfer case data from any format for which you have a suitable read-enabled CDSC and
you can write to any data format for which you have a suitable write-enabled CDSC. For example:
You can use the Relational MR Database DSC to read IBM® SPSS® Data Collection
Interviewer Server data that is stored in a relational MR database, and you can use SPSS
Statistics SAV DSC to write the data to a .sav file for analysis in IBM® SPSS® Statistics, or
you can use IBM® SPSS® Quantum™ DSC to write the data to a .dat file for analysis in
Quantum.
When you need to send data to another location, you can use the IBM SPSS Data Collection
Data File CDSC to write the data to a IBM SPSS Data Collection Data File, which you can
then send to another site, for example, by e-mail. The recipient can then use a DMS file or
to transfer the data to the required format.
However, DMS files can also transfer data using OLE DB providers that are not part of the
Data Model. For example, you can transfer data stored in an Microsoft Access database using
the Microsoft Jet OLE DB Provider.
Input data source. You define the location and format of the data you want to transfer in the
InputDataSource section of the DataManagementScript (DMS) file. If you want to transfer a
subset of the data only, you also define the filters in this section. For more information, see
the topic Reading Data on p. 311.
Output data source. You define the location and format of the data to which you want to write the
transferred data in the OutputDataSource section of the DMS file. You also set the validation
options that you require in this section. For more information, see the topic Writing Data on p. 335.
In the InputDataSource and OutputDataSource sections, you can specify file locations using
absolute or relative paths. If you specify a relative path, it will be treated as being relative to the
folder in which the DMS file is located when you run it.
311
Base Professional
Transferring Hierarchical Data
In IBM® SPSS® Data Collection Base Professional, when you transfer data using the IBM SPSS
Data Collection OLE DB Provider, the flattened (VDATA) view of the data is always used. This
means that you can use a DMS file to export hierarchical data only if it can be represented in a
flattened form. This is true for all hierarchical data collected using Interviewer Server, IBM®
SPSS® Data Collection Paper and IBM® SPSS® Data Collection Paper - Scan Add-on. However,
you cannot use a DMS file to transfer hierarchical data that was collected using other tools if it
cannot be flattened—for example, because it was collected using an unbounded loop. The lower
levels in a IBM® SPSS® Quanvert™ Levels are an example of this type of hierarchical data,
and you therefore cannot export data from the lower levels of a Quanvert levels project using a
DMS file.
Reading Data
You define the location and format of the data you want to transfer in the InputDataSource section
of the DataManagementScript (DMS) file. If you want to transfer a subset of the data only, you
also define the filters in this section. For more information, see the topic Filtering Data in a
DMS File on p. 243.
When you read the data using the IBM® SPSS® Data Collection Data Model, you generally need
a metadata source for the transfer. This can be a Metadata Document (.mdd) file or a proprietary
data format for which an MDSC is available. However, for some data types you do not need to
specify a metadata source, although it is usually preferable to do so. For more information, see the
topic Reading Metadata on p. 312.
Each DSC that you can use to read data behaves differently and has different requirements. This
section provides information on reading data using some of the read-enabled DSCs that come
with the Data Model.
For information about transferring data using an OLE DB provider that is not part of the Data
Model, see Reading Data Using Other OLE DB Providers.
312
Chapter 1
Reading Metadata
When you transfer data using a DMS file and the IBM® SPSS® Data Collection Data Model,
you generally need to specify an input metadata source. The metadata source can be a
Metadata Document (.mdd) file or a proprietary data format for which an MDSC is available.
However, for some data types you do not need to specify a metadata source, although it is
usually preferable to do so, because without an input metadata source, you cannot use the
OnAfterMetaDataTransformation, OnJobStart, OnNextCase, and OnJobEnd Event sections.
Moreover, if you are transferring data to a target data source that already exists without using an
input metadata source, the transfer will succeed only if the structure of the output data exactly
matches the existing target data.
You define the input metadata source in the connection string in the InputDataSource section. If
you are using the Connection String Builder or WinDMSRun sample application to set up the
connection string, you can select the metadata source and the MDSC (when relevant) on the
Connection tab in the Data Link Properties dialog box (provided the IBM SPSS Data Collection
OLE DB Provider is selected on the Provider tab). Alternatively, you can type the connection
string into your DMS file manually.
Using a .mdd File
You specify a Metadata Document (.mdd) file in the connection string in the InputDataSource
section as follows:
If you are setting up the connection string using the Data Link Properties dialog box, choose
the Connection tab and from the Metadata Type drop-down list, select IBM® SPSS® Data
Collection Metadata Document. Then enter the Metadata Location, either by typing the name
and location of the .mdd file into the text box, or by clicking Browse and selecting it in the
Open dialog box. Make sure you select Open metadata read/write.
If you are setting up the connection string manually, set the Initial Catalog connection
property to the name and location of the .mdd file:
InputDatasource(myInputDataSource, "My input data source")
Data Source=<Name of CDSC>; _
Initial Catalog=<Name and location of .mdd file>; _
Location=<Name and location of case data>"
End InputDatasource
If the .mdd file has more than one version, the most recent version will be used by default.
However, you can select an earlier version by using the MR Init MDM Version connection
property. For more information, see the topic Selecting a Specific Version on p. 361. You can
also select multiple versions to use for the export. For more information, see the topic Selecting
Multiple Versions on p. 362.
Note that the .mdd file itself must be writable. For example, you will get an error if the file is
read-only.
Name and Location of Case Data

313
Base Professional
When you are using an .mdd file, you do not need to specify the name and location of the case
data to be transferred if the following statements are both true:
The .mdd file already contains a DataSource object that is the same type as that specified
in the connection string.
That DataSource object refers to the case data that you want to transfer.
In addition, if the Datasource object is the default data source in the .mdd file, you do not need to
specify the name of the CDSC in the InputDataSource section.
For example, if you are transferring IBM® SPSS® Data Collection Interviewer Server data using
the .mdd file in the FMRoot\Shared folder on the File Management server, you generally do not
need to specify the name and location of the case data, or the name of the CDSC, because those
details will already be stored in the default DataSource object in the .mdd file.
Be careful when the DataSource object refers to case data that is stored in a file (such as a .sav
file), and the path stored in the DataSource object is a relative path. In that situation, the path will
be treated as if it relative to the location of the .mdd file. In contrast, in the InputDataSource
section, if you specify the name and location of the case data using a relative path, the path will be
treated as if it relative to the location of the DMS file being run.
Using a Proprietary Metadata Source
You specify a proprietary metadata source in the connection string in the InputDataSource section
as follows:
If you are setting up the connection string using the Data Link Properties dialog box, select the
Connection tab and from the Metadata Type drop-down list, select the type of metadata. (All
of the metadata types for which a read-enabled MDSC is available will be listed.) Then enter
the Metadata Location, either by typing the name and location of the file or database into the
text box, or by clicking Browse and selecting it in the Open dialog box.
If you are setting up the connection string manually, set the Initial Catalog connection
property to the name and location of the file or database and the MR Init MDSC connection
property to the name of the MDSC you are using to read the metadata:
Data Source=<Name of CDSC>; _
Location=<Name and location of case data>; _
Initial Catalog=<Name and location of metadata file or database>; _
MR Init MDSC=<Name of MDSC>"
End InputDatasource
When you read from a proprietary data source, it is sometimes useful to create a Metadata
Document (.mdd) file. For more information, see the topic Creating an .mdd File From Proprietary
Metadata on p. 314.
Transferring Without Using a Metadata Source
For some types of data you do not need to specify a metadata source, although generally you will
want to do so. It’s possible to transfer data without specifying a metadata source only when using
Relational MR Database CDSC, IBM SPSS Data Collection Data File CDSC, SPSS Statistics
314
Chapter 1
SAV DSC, or XML CDSC to write the case data (although transferring to a .sav file without a
metadata source has a number of limitations. For more information, see the topic Transferring
Data to IBM SPSS Statistics on p. 342.) See InputDataSource section for an example.
Tip: In the InputDataSource section, you can specify file locations using a relative path (that is,
relative to the folder in which the DMS file is located when you run it).
Creating an .mdd File From Proprietary Metadata
When you read from a proprietary data source, it is sometimes useful to create a Metadata
Document (.mdd) file; for example, when you want to set up system variables or custom properties
and other options in the metadata for use during the export. You can create the .mdd file in the
OnBeforeJobStart Event Section. Alternatively, you can create an .mdd file from the proprietary
metadata in before you run the export. (See step-by-step instructions later in this topic.)
Creating an .mdd file from proprietary metadata in the OnBeforeJobStart Event section
The following example uses the DSC Registration component to access the SPSS Statistics
SAV DSC, which is then used to create an MDM Document object from a .sav file. The MDM
Document object is saved as an .mdd file, which is then specified as the input metadata source in
the InputDataSource section.
Notice that the MDM.IncludeSystemVariables = True line “turns on” system variables in the
.mdd file. This is useful when you are transferring data to a relational database using the older
ODBC-based RDB DSC, because it requires the Respondent.Serial variable to be present.
Typically .sav files and IBM® SPSS® Quanvert™ databases do not have a variable called
Respondent.Serial. You do not need to assign case data to the variable when you are exporting
to an RDB database, because if it is blank, RDB DSC automatically generates a serial number
before writing the record. Note that the new OLE DB-based RDB DSC 2 does not require
Respondent.Serial to be present.
'==========================================================
'
'
'
'==========================================================
#define EMPLOYEEMDD "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Employee data.mdd"
Event(OnBeforeJobStart, "Create an .mdd file")

Dim MDM, DSC, DSCs
' Use ShellExecute function to call MS-DOS batch file to create the RDB database
ShellExecute("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\Batch\CreateRDBDatabase.bat")
315
Base Professional
' Create the Data source component Collection

Set DSCs = CreateObject("MRDSCReg.Components")
' Find the SPSS Statistics SAV DSC

Set DSC = DSCs["mrSavDsc"]
' Create an MDM Document from the .sav file

Set MDM = DSC.Metadata.Open("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.sav")
MDM.IncludeSystemVariables = True
' Save the MDM document out to an .mdd file that we will use in the file transfer.
MDM.Save(EMPLOYEEMDD)
MDM.Close()
End Event
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.sav; _
Initial Catalog=" + EMPLOYEEMDD
End InputDatasource
#define Target "SavToRdb"

#Include ".\Include\RdbOutput.dms"
Note that when you run the DMS file using the validate option, you will get two validation
errors. For example:
Error opening input data source: myInputDataSource
Failed to close the InputDataSource: myInputDataSource
This is because the validation takes place before the input metadata has been created. You can
safely ignore these errors.
Note: This example is provided as a sample DMS file (called SavToRDB.dms) that is installed
To create an .mdd file from proprietary metadata in MDM Explorer:
E Open MDM Explorer.
E From the File menu in MDM Explorer, choose Open MDSC.
This opens the Open Metadata Source Component dialog box.
E In the Files of Type list box, select the type of metadata you want to open.
E Browse to the folder in which the proprietary metadata is located.

316
Chapter 1
E Double-click the file you want to open.
There is a short delay while the file is loaded.

E From the File menu, choose Save As.
E In the Save Metadata Document As dialog box, enter a File Name for the .mdd file and click Save.
You can transfer data from a relational MR database using .
Case data that is stored in a relational MR database is typically used with metadata in an .mdd
file. When the case data is collected using IBM® SPSS® Data Collection software, the .mdd file
will typically contain versions, which record any changes to the content of the questionnaire.
Typically, when the metadata changes (for example, when variables or categories are added or
deleted) a new version is created and when the changes are complete, the version is locked. For
more information, see the topic Understanding Versions on p. 360.
For information about exporting IBM® SPSS® Data Collection Interviewer Server data, see
Working with IBM SPSS Data Collection Interviewer Server Data. For a list of sample DMS files
that have been designed specifically for use with Interviewer Server data, see Sample DMS Files
For Exporting IBM SPSS Data Collection Interviewer Server Data.
How do I specify using RDB DSC?
In the connection string in the InputDataSource section, specify mrRdbDsc2 for the Data Source
property and specify the OLE DB connection string for the Location property. You also need to
specify the MR Init Project connection property and make sure that the Initial Catalog property is
specified before the Location property:
Data Source=mrRdbDsc2; _
Initial Catalog=<Name and location of .mdd file>; _
Location=<OLE DB connection string>; _
MR Init Project=<Name of project>"
End InputDatasource
Tip: You do not need to specify the Location and MR Init Project connection properties if the
details are the same as those defined in the default DataSource object in the .mdd file. For
example, if you are transferring Interviewer Server data using the .mdd file in the FMRoot\Shared
folder, these details will generally be stored in the default DataSource in the .mdd file.
Using Text Substitution in the OLE DB Connection String
If you are using text substitution to replace text in the OLE DB connection string with your own
text strings, you must enclose the value of the Location property in single quotes (‘) for the
substitution to work correctly. There is an example of this in the sample include file RDBInput.dms:
InputDatasource(myInputDataSource, "RDBInput.dms")
317
Base Professional
Initial Catalog=" + MyMddFile + "; _
Location='Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=" + MyDatabase + ";Data Source
MR Init Project=" + MyProject
End InputDatasource
RDBInput.dms is used by the sample file RDBToQuantum.dms, which includes the following code:
#define MyDatabase "SavToRdb"

#define MyServer "Localhost"
#Include ".\Include\RDBInput.dms"
By enclosing the value of the Location property in single quotes, the values of MyDatabase and
MyServer will be correctly inserted into the OLE DB connection string.
Examples
1. Using the Favor Speed option
This example uses RDB DSC 2 to transfer data from the relational MR database for the Short
Drinks sample:

Location="Provider=SQLOLEDB.1; _
Integrated Security=SSPI; _
Initial Catalog=short_drinks; _
Data Source=LocalHost"; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Mdd\short_drinks.mdd; _
MR Init Project=short_drinks; _
MR Init MDM Version={..}"
End InputDatasource
OutputDataSource(Output, "My output data source")

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToSav.sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToSav.mdd"
Note: A similar example is included as a sample DMS file called RDBToSav.dms, which is
2. Using the Favor Memory option

318
Chapter 1
There is a known problem (mrBug00015444) that can affect DMS files that use RDB DSC 2 to
read the input data and have an update query in the InputDataSource section. This problem can
cause the update query to fail. You can avoid this problem by using the Favor Memory option,
as shown in this example:
InputDatasource(mrInterviewData)
MR Init Project=short_drinks; _
MR Init Custom=FavorMemory"
UpdateQuery = "UPDATE VDATA SET Respondent.Origin.Other = 'xxx' _
End InputDatasource
You can transfer data from a IBM SPSS Data Collection Data File (.ddf or .dzf) using the .
Case data that is stored in a IBM SPSS Data Collection Data File is typically used with metadata
in an .mdd file. When the case data is collected using IBM® SPSS® Data Collection software,
the .mdd file will typically contain versions, which record any changes to the content of the
questionnaire. Typically, when the metadata changes (for example, when variables or categories
are added or deleted) a new version is created and when the changes are complete, the version is
locked. For more information, see the topic Understanding Versions on p. 360.
How do I specify reading from a IBM SPSS Data Collection Data File?
In the connection string in the InputDataSource section, specify mrDataFileDsc for the Data
Source property. Specify the name and location of the .ddf or .dzf file for the Location connection
property and the name and location of the .mdd file for the Initial Catalog connection property:
Location=<Name and location of .ddf or .dzf file>; _
Initial Catalog=<Name and location of .mdd file>"
End InputDatasource
Example
This example InputDataSource section is taken from the MergeVertical.dms sample DMS
file, which is installed with the IBM® SPSS® Data Collection Developer Library. For more
InputDatasource(myMasterDataSource)
ConnectionString = " _
319
Base Professional
Provider = mrOleDB.Provider.2; _
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalMaster.ddf; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalMaster.mdd"
End InputDatasource
You can transfer data from a .sav file using SPSS Statistics SAV DSC. For information about how
SPSS Statistics SAV DSC interprets the information in the .sav file, see the SPSS Statistics SAV
DSC documentation in the section.
When you are reading a .sav file that you have previously created using the IBM® SPSS® Data
Collection Data Model, it is preferable to read it using the .mdd file that was used when creating it
whenever possible (that is the output metadata file if you created the .sav file using a DMS file.)
This means that the variable names will match those in the .mdd file. If you connect specifying the
SPSS Statistics SAV DSC as the MDSC, the variable names will be closer to those in the .sav file,
but the names will be changed, if necessary, to make them valid in the MDM.
IBM® SPSS® Data Collection Base Professional provides only limited support for Japanese
characters when working with .sav files. In particular, Japanese characters that appear in .sav file
variable names are sometimes not handled correctly when you read the metadata using the SPSS
Statistics SAV DSC. This can result in incorrect variable names in the output. If the .sav file was
created by a previous export, you can get around this problem by using the .mdd file used for that
export (the output metadata file if the export was done using a DMS file) as the input metadata
source for the transfer.
How do I specify reading from a .sav file?
1. Using SPSS Statistics SAV DSC to read the metadata
In the connection string in the InputDataSource section, specify mrSavDsc for both the Data
Source and the MR Init MDSC connection properties. Specify the name and location of the .sav file
for both the Location and Initial Catalog connection properties:
Location=<Name and location of .sav file>; _
Initial Catalog=<Name and location of .sav file>; _
MR Init MDSC=mrSavDsc"
End InputDatasource
2. Using a .mdd file
In the connection string in the InputDataSource section, specify mrSavDsc for the Data Source
connection property and leave the MR Init MDSC connection property blank. Specify the name and
location of the .sav file for the Location connection property and specify the name and location of
the .mdd file for the Initial Catalog connection property:
320
Chapter 1
Location=<Name and location of .sav file>; _
End InputDatasource
Examples
1. Using SPSS Statistics SAV DSC to read the metadata
This example uses SPSS Statistics SAV DSC to read both the case data and the metadata in
the Employee data sample . sav file.

Location=" + InputSav + "; _
Initial Catalog=" + InputSav + "; _
MR Init MDSC=mrSavDsc"
End InputDatasource
Note: The SavInput.dms Include file that is installed with the IBM® SPSS® Data Collection
Developer Library contains this example. For more information, see the topic Sample DMS
Include Files on p. 479.
This example uses SPSS Statistics SAV DSC to read the case data in the Employee data sample
.sav file, but uses the metadata in an .mdd file. If an .mdd file is not available, you could create the
.mdd file in the OnBeforeJobStart Event section. For more information, see the topic Creating an
.mdd File From Proprietary Metadata on p. 314.

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.sav; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Employee data.mdd"
End InputDatasource
Note: This example is similar to that in the SavToRDB.dms sample DMS file, which is installed
with the Data Collection Developer Library.For more information, see the topic Sample DMS
Files on p. 467.
You can transfer data from any IBM® SPSS® Quantum™-format ASCII file by using the
Quantum DSC. The Quantum format stores the responses to each question in fixed positions on
lines of text. The positions are determined by card and column definitions that are stored in a
separate questionnaire definition (.mdd) file. Typically, a suitable questionnaire definition file will
not exist beforehand, so you will need to create one before you can start to read your Quantum data.
321
Base Professional
How do I specify reading from a IBM SPSS Quantum file?
In the connection string in the InputDataSource section, specify mrPunchDsc for the Data Source
connection property, and specify the name and location of the Quantum file for the Location
connection property. Then specify the name and location of the questionnaire definition (.mdd)
file for the Initial Catalog connection property:

Data Source=mrPunchDsc; _
Location=<Name and location of Quantum file>; _
End InputDatasource
Example
This example uses the Quantum DSC to read the first 100 records in the “Ski Demo” Quantum
sample file provided with the IBM® SPSS® Data Collection Developer Library (DDL):
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quantum\skidemo.dat; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quantum\skidemo.mdd"
SelectQuery = "SELECT * FROM vdata WHERE serial <= 100"
End InputDatasource
Note: This example is taken from the QuantumToDDF.dms sample file, which is installed with
the Data Collection Developer Library. For more information, see the topic Sample DMS Files
on p. 467.
You can transfer data from a IBM® SPSS® Quanvert™ database using Quanvert DSC.
Packed databases. In IBM® SPSS® Data Collection Base Professional 2.1, you can transfer
data from both packed and unpacked databases. You can tell the difference between a packed
and unpacked Quanvert database because a packed one consists of one or more files with a .pkd
filename extension whereas an unpacked database consists of many files including a header file
called qvinfo. For more information about working with packed databases, see .
Quanvert levels projects. These are hierarchical data sets and only the top level can be represented
in the flat VDATA virtual table. This means that if you attempt to use a DMS file to transfer a
Quanvert levels project to another format or location, only the top level will be transferred and no
error message will be issued. If necessary, you can include code in the OnBeforeJobStart Event
322
Chapter 1
section to check whether it is a levels project. By raising an error and not trapping it, you can
stop the job. For example:
Event(OnBeforeJobStart, "Create the .mdd file")

Dim MDM, DSC, DSCs, MDMField

' Find the Quanvert DSC

Set DSC = DSCs["mrQvDsc"]
' Create an MDM Document from the Quanvert database

Set MDM = DSC.Metadata.Open("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Household\qvinfo")
For Each MDMField In MDM.Fields

If MDMField.ObjectTypeValue = ObjectTypesConstants.mtArray Then
If MDMField.Type = ArrayTypeConstants.mlLevel Then
On Error Goto 0
Err.Raise(1, , "This is a Quanvert Levels Project - Job stopped")
End If
End If
Next
'Save the MDM Document

MDM.Save("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Household.mdd")
MDM.Close()
End Event
See for more information.
Quanvert multiprojects. The Quanvert multiproject feature enables you to analyze together the data
in separate but related Quanvert projects. Quanvert multiprojects are made up of two or more
projects (generally called subprojects but sometimes referred to as waves). When you create
a multiproject in Quanvert, you specify the projects you want to include in the multiproject,
the master subproject, and the folder in which the multiproject is to be created. Quanvert then
creates the multiproject in the specified folder without changing the subprojects in any way. You
can export a Quanvert multiproject using a DMS file. You simply specify the qvinfo file in the
folder in which the multiproject was created in the normal way. However, for large multiprojects,
you can improve the performance of the export by creating an MDM document (.mdd) file first
and using that file for the transfer.
Special Quanvert information. Quanvert categorical variables (which are called axes) usually
contain special elements, which define summary and statistics rows and intermediate values for
use during tabulation. creates two columns in the virtual table for categorical variables that
contain these special elements. The first (called varname, where varname is the axis name) stores
the responses to the categories and the second (called varname.ex) stores the data for the special
elements. Quanvert DSC creates the varname.ex variables as helper fields in the metadata and sets
up a number of custom properties to store Quanvert-specific information.
323
Base Professional
Some applications, such as IBM® SPSS® Data Collection Survey Tabulation, can make
use of the special elements and recombine the variables when reading a Quanvert database.
However, the Quanvert-specific information is generally not relevant in other data formats, such
as IBM® SPSS® Statistics. The QuanvertToSav.dms sample provides an example of deleting
the varname.ex variables.
Large Quanvert projects. Quanvert DSC cannot read data for more than 2039 variables at once
(509 variables in IBM® SPSS® Data Collection Data Model 2.6). (For this calculation, you
need to count the number of Quanvert variables, not the number of variables that are created in
the Data Model. Each variable that is displayed in the Available Variables frame in Quanvert
generally counts as one variable. However, some categorical and grid variables have numeric data
associated with them and each of these variables counts as two variables.) This limit is most likely
to be reached if you attempt to export all of the variables in a large Quanvert project, for example
using a “SELECT * FROM vdata” select query in the InputDataSource section. However, the
export should succeed if you change the SELECT statement to include fewer than 2040 Quanvert
variables (510 in Data Model 2.6).
Using a select query. There is a known problem (mrBug00013907) that affects exports that use
Quanvert MDSC to read the metadata. This problem means that if you specify in the select query
a subset of the variables in the database, all of the variables will be included in the output data
source. However, case data is transferred for the specified variables only. However, this does not
happen if you use an .mdd file as the input metadata for the export. You can create an .mdd file in
the OnBeforeJobStart Event section and specify the new .mdd file as the metadata source in the
InputDataSource section. There is an example of doing this later in this topic.
How do I specify reading from a IBM SPSS Quanvert database?
1. Using Quanvert DSC to read the metadata
In the connection string in the InputDataSource section, specify mrQvDsc for both the Data Source
and the MR Init MDSC connection properties. Specify the name and location of the qvinfo or .pkd
file for both the Location and Initial Catalog connection properties:
ConnectionString = "rovider=mrOleDB.Provider.2; _
Location=<Name and location of qvinfo or .pkd file>; _
Initial Catalog=<Name and location of qvinfo or .pkd file>; _
End InputDatasource
In the connection string in the InputDataSource section, specify mrQvDsc for the Data Source
location of the qvinfo or .pkd file for the Location connection property and specify the name and
location of the .mdd file for the Initial Catalog connection property:
Location=<Name and location of qvinfo or .pkd file>; _
Initial Catalog=<Name and location of mdd file>"
324
Chapter 1
End InputDatasource
Example
The following example does the following:

Uses the DSC Registration component to access the Quanvert DSC, which is then used to
create an MDM Document object from a Quanvert database.
Saves the MDM Document object as an .mdd file, which is then specified as the input metadata
source in the InputDataSource section.
Uses SPSS Statistics SAV DSC to transfer the case data to a .sav file.
Event(OnBeforeJobStart, "Create the .mdd file")

Dim MDM, DSC, DSCs

' Find the Quanvert DSC

Set DSC = DSCs["mrQvDsc"]
' Create an MDM Document from the Quanvert database

Set MDM = DSC.Metadata.Open("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\qvinfo")
' Save the MDM document out to an .mdd file which we will use in the file transfer.
MDM.Save("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Museum.mdd")
MDM.Close()
End Event

Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Museum.mdd"
End InputDatasource

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\QuanvertToSav.sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\QuanvertToSav.mdd"
Note: A similar example is provided as a sample DMS file called QuanvertToSav.dms, which is
installed with the IBM® SPSS® Data Collection Developer Library. For an example that transfers
data from a packed database, see the QuanvertPkdToDDF.dms sample. For more information,
325
Base Professional
You can transfer data from the standard IBM® SPSS® Quancept™ QDI/DRS format using
QDI/DRS DSC. For information about how QDI/DRS DSC interprets and presents the
information, see the documentation in the section.
Note that (unlike IBM® SPSS® Quanvert™ DSC and SPSS Statistics SAV DSC) QDI/DRS DSC
automatically sets up system variables including Respondent.Serial.
How do I specify reading from QDI/DRS?
1. Using QDI/DRS DSC to read the metadata
In the connection string in the InputDataSource section, specify mrQdiDrsDsc for both the Data
Source and the MR Init MDSC connection properties. Specify the name and location of the .drs
file for the Location connection property and the name and location of the .qdi file for the Initial
Catalog connection property:
Data Source=mrQdiDrsDsc; _
Location=<Name and location of .drs file>; _
Initial Catalog=<Name and location of .qdi file>; _
MR Init MDSC=mrQdiDrsDsc"
End InputDatasource
In the connection string in the InputDataSource section, specify mrQdiDrsDsc for the Data Source
location of the .drs file for the Location connection property and the name and location of the .mdd
file for the Initial Catalog connection property:
Location=<Name and location of .drs file>; _
End InputDatasource
Example
This example transfers the Museum sample .qdi and .drs files to a IBM® SPSS® Data Collection
Data (.ddf) file.
'==========================================================
'
'
'
326
Chapter 1
'==========================================================
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\qdidrs\museum.drs; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\qdidrs\museum.qdi; _
MR Init MDSC=mrQdiDrsDsc"
End InputDatasource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\QdiDrsToDDF.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\QdiDrsToDDF.mdd"
Note: This example is provided as a sample DMS file (called QdiDrsToDDF.dms) that is installed
You can transfer data from a IBM® SPSS® Data Collection log file using Log DSC.
How do I specify reading from a IBM SPSS Data Collection log file?
In the connection string in the InputDataSource section, specify mrLogDsc for the Data Source
and MR Init MDSC connection properties. Specify the name and location of the log file for the
Location and Initial Catalog connection properties. In IBM® SPSS® Data Collection Data Model
2.7 and later, you can specify the location of a folder to incude all of the log files in that folder:
Data Source=mrLogDsc; _
Location=<Name and location of the log file or log file folder>; _
Initial Catalog=<Name and location of log file>; _
MR Init MDSC=mrLogDsc"
End InputDatasource
Example
This example transfers the MDG335.tmp log file to a IBM SPSS Data Collection Data File (.ddf),
using the DDFOutput.dms Include file.
Data Source=mrLogDsc; _
Location=C:\Temp\DMG33Z.tmp; _
Initial Catalog=C:\Temp\DMG33Z.tmp; _
MR Init MDSC=mrLogDsc"
End InputDataSource
327
Base Professional
#define TargetDDF "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\LogToDDF.ddf"

#define TargetMdd "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\LogToDDF.mdd"
#Include "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS\Include\DDFOutput.dms"
The IBM® SPSS® Data Collection Developer Library comes with a sample Include file (called
LogInput.dms) that you can use to define a transfer from a Data Collection log file.
You can transfer data from Triple-S files by using the Triple-S DSC. The Triple-S files must
meet version 1.2 or version 2.0 of the Triple-S standard. Version 2.0 of the standard supports
case data files that contain either fixed-format fields or comma-separated values, while version
1.2 of the standard supports only fixed-format fields. However, the Triple-S DSC cannot transfer
hierarchical data (which was introduced in the version 2.0 standard).
You typically read a Triple-S case data file by using a Triple-S metadata file. You can also use a
metadata document (.mdd) file to read a Triple-S case data file, although you would normally do
this only if you created the Triple-S case data file using a data management script and you also
output a .mdd file at the same time.
How do I specify reading from Triple-S files?
1. Using the Triple-S DSC to read the metadata
In the connection string in the InputDataSource section, specify mrTripleSDsc for both the Data
Source and the MR Init MDSC connection properties. Specify the name and location of the Triple-S
case data file, which will normally have a .asc, .dat, or .csv extension, for the Location connection
property. Then specify the name and location of the Triple-S metadata file, which will normally
have a .sss or .xml extension, for the Initial Catalog connection property:
Data Source=mrTripleSDsc; _
Location=<Name and location of .asc, .dat, or .csv file>; _
Initial Catalog=<Name and location of .sss or .xml file>; _
MR Init MDSC=mrTripleSDsc"
End InputDatasource
In the connection string in the InputDataSource section, specify mrTripleSDsc for the Data Source
location of the Triple-S case data file for the Location connection property, and specify the name
and location of the .mdd file for the Initial Catalog connection property:
Location=<Name and location of .asc, .dat, or .csv file>; _
328
Chapter 1

End InputDatasource
Example
This example uses the Triple-S DSC to read the first 100 records in the “Ski Demo” Triple-S
sample metadata and case data files provided with the IBM® SPSS® Data Collection Developer
Library (DDL):
InputDataSource(Input, "Input case and metadata")

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Triple-S\skidemo.asc; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Triple-S\skidemo_asc.xml; _
MR Init MDSC=mrTripleSDsc"
SelectQuery = "SELECT * FROM vdata WHERE serial <= 100"
End InputDataSource
Note: This example is taken from the TripleSToDDF.dms sample DMS file, which is installed
Files on p. 467.
You can transfer data from Microsoft Access tables, Microsoft Excel worksheets, and Microsoft
SQL Server tables using the ADO DSC, which itself uses non-IBM® SPSS® Data Collection
Data Model OLE DB providers to read data sources. Using the ADO DSC to read a data source is
always preferable to using a non-Data Model OLE DB provider directly because the ADO DSC
presents the data using the standard VDATA virtual table. Therefore, you do not need to specify a
select query in the InputDataSource section as it will default to SELECT * FROM vdata. In addition,
using the ADO DSC allows you to use an input metadata source, which means that you can then
create an output metadata document (.mdd) file when you run the transfer. If you are exporting to
a IBM® SPSS® Quantum™ file, using an input metadata source means that you will be able to
allocate the card, column, and punch definitions in the OnAfterMetaDataTransformation event.
Not all non-Data Model providers can be used with the ADO DSC, but here are some that can be
used:
Microsoft OLE DB Provider for ODBC Drivers. Can read Access tables and Excel worksheets.
Microsoft Jet 4.0 OLE DB Provider. Can also read Access tables and Excel worksheets.
However, this provider always returns variables in alphabetical order, which may not be
what you require.
Microsoft OLE DB Provider for SQL Server. Can read SQL Server tables. However, do not use
this provider to read a IBM® SPSS® Data Collection relational MR database (instead, see
Transferring Data From a Relational MR Database (RDB)).
For information about using providers that are not supported by the ADO DSC, see Reading
Data Using Other OLE DB Providers.
329
Base Professional
Providing a Metadata Source
You can optionally use a .adoinfo file as the metadata source for your transfer. An .adoinfo file
does not contain actual metadata, instead it contains an ADO connection string that identifies the
data source and the name of the table to be read. Having a metadata source is recommended as it
will allow you to create a metadata document (.mdd) file in the OutputDataSource section of your
data management script and also allow you to define new variables in the Metadata section. In
addition, if you are exporting to a Quantum file, having a metadata source means that you will be
able to allocate the card, column, and punch definitions during the export.
It is not possible to use a metadata document (.mdd) file as a metadata source when using the
ADO DSC.
How do I specify reading from an MS Office file?
1. Using ADO DSC to read the metadata
In the connection string in the InputDataSource Section, specify mrADODsc for both the Data
Source and the MR Init MDSC connection properties and specify the name and location of the
.adoinfo file for the Initial Catalog connection property:
Initial Catalog=<Name and location of .adoinfo file>; _
MR Init MDSC=mrADODsc"
End InputDatasource
2. Reading case data only
In the connection string in the InputDataSource Section, specify mrADODsc for the Data Source
connection property, specify the ADO connection string for the Location connection property,
and specify the name of the table to be read (or if Excel, the worksheet name) for the MR Init
Project connection property:
Location=<ADO connection string>; _
MR Init Project=<table name>"
End InputDatasource
The value of the ADO connection string depends on both the provider being used and the type of
data source. In this situation, you may find it easier to use the Connection String Builder in IBM®
SPSS® Data Collection Base Professional to generate the value for ConnectionString. For more
information, see the topic Using the Connection String Builder on p. 31.
Reading an Excel Worksheet
The data on the worksheet needs to be suitable. By default, the first row in the worksheet defines
the variable names and the provider will examine the cell contents of the next few rows to
determine the appropriate data type for each variable. The provider will change the variable names
330
Chapter 1
if they contain characters that are not supported. For example, a column called Respondent.Serial
will become Respondent#Serial in the output, and a column called When Decided will become
whenDecided.
Data Types and Sizes
The provider will assign a maximum length of 255 characters to any worksheet column that it
identifies as a text variable. Any column that contains only numbers, whether integer or decimal,
will be deemed to be a 64-bit floating point number with at least 15 digits of precision. However,
if you have defined a metadata source, you can change the types and sizes of variables during
the transfer by adding code to the OnAfterMetaDataTransformation Event Section of your data
management script. For example:
Event(OnAfterMetaDataTransformation, "Change types and sizes of columns")
Dim MDM

MDM.Open(dmgrJob.TransformedOutputMetaData[0])
' Change decimal column "MyFirstColumn" to an integer

' with a valid range between 0 and 99...
MDM.Variables["MyFirstColumn"].DataType = DataTypeConstants.mtLong
MDM.Variables["MyFirstColumn"].Variable.RangeExpression = "[0..99]"
' Restrict the valid range of decimal column "MySecondColumn"...
MDM.Variables["MySecondColumn"].Variable.RangeExpression = "[-999.999..999.999]"
' Restrict the size of text column "MyThirdColumn" to

' between 0 and 25 characters...
MDM.Variables["MyThirdColumn"].Variable.RangeExpression = "[0..25]"
MDM.Save()
MDM.Close()
End Event
Worksheet Names
Depending on the version of Excel installed on your computer, you may have to add a dollar
sign ($) after the worksheet name to be able read the worksheet successfully. The worksheet
name is specified in the .adoinfo file or, if the transfer is case data only, by the MR Init Project
connection string property. For example, to read the worksheet called Sheet1, you may have to
specify Sheet1$. You may also be able to specify a range of cells in the worksheet. For example,
specifying the worksheet name as Sheet1$A1:C11 will read the range A1:C11. If you specify a
range, make sure that the first row contains the variable names.
331
Base Professional
Examples
1. Microsoft Access
This example transfers to a SAV file all of the data in the Authors sample Access database. The
example uses the Data Collection ADO DSC and the Microsoft OLE DB Provider for ODBC
Drivers to read the Access database. This example does not use an input metadata source so it is
not possible to create an output metadata document (.mdd) file. Note that the name of the Access
table to be read has been specified using the MR Init Project custom connection property.
Location=""Provider=MSDASQL.1; _
Extended Properties='DSN=MS Access Database; _
DBQ=C:\Inetpub\iissamples\sdk\asp\database\Authors.mdb; _
DriverId=281; _
FIL=MS Access; _
MaxBufferSize=2048; _
PageTimeout=5; _
UID=admin'""; _
MR Init Project=Authors"
End InputDatasource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSAccessToSav.sav"
The IBM® SPSS® Data Collection Developer Library includes two sample data
management script files that transfer data from Access databases. The files are called are
MSAccessToQuantum.dms and MSAccessToSav.dms (which is similar to the above example). For
more information, see the topic Sample DMS Files That Integrate with Microsoft Office on p. 475.
2. Microsoft Excel
The following example shows how to set up the InputDataSource section to read data on the first
worksheet in an Excel file. The example uses the Data Collection ADO DSC and the Microsoft
OLE DB Provider for ODBC Drivers to read the Excel file. A .adoinfo file is used as an input
metadata source as this allows the output metadata document (.mdd) to be created. When using a
.adoinfo file, the names of the Excel file and the worksheet are specified in that file. Note that you
must set the MR Init MDSC custom connection property to specify that the Data Collection ADO
metadata source component (MDSC) should be used to read the metadata.
#define ADOInfoFile "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelToDDF.adoinfo"
' The output Data Collection Data and MDD files...
#define OutputDDFFile "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelToDDF.ddf"

332
Chapter 1
#define OutputMDDFile "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelToDDF.mdd"
MR Init MDSC=mrADODsc; _
Initial Catalog=" + ADOInfoFile
SelectQuery = "SELECT * FROM vdata"
End InputDatasource
Location=" + OutputDDFFile
MetaDataOutputName = OutputMDDFile
Here are the contents of the .adoinfo file:
<ADODSC>
<ConnectionString>
DSN=Excel Files;
DBQ=C:\samples\MyMuseumData.xls;
DriverId=790;
MaxBufferSize=2048;
PageTimeout=5
</ConnectionString>
<Table>
Sheet1
</Table>
</ADODSC>
Depending on the version of Excel installed on your computer, you may have to specify the
worksheet (“table”) name as Sheet1$.
This example is provided as a sample data management script file called MSExcelToDDF.dms,
which is installed with the Data Collection Developer Library. A similar sample script that
transfers Excel data to Quantum is MSExcelToQuantum.dms. For more information, see the topic
Sample DMS Files That Integrate with Microsoft Office on p. 475.
You can transfer data from an XML file using XML CDSC, provided the data is stored using the
IBM® SPSS® Data Collection schema. See for more information.
Warning: The XML DSC is supplied by Data Collection for the purpose of demonstrating
and testing the transfer of small volumes of data. Do not use the XML DSC in production
processes—use the IBM SPSS Data Collection Data File CDSC instead. The XML DSC might be
withdrawn in a future release of Data Collection.
333
Base Professional
Case data that is stored in an XML file is typically used with metadata in an .mdd file. When the
case data is collected using Data Collection software, the .mdd file will typically contain versions,
which record any changes to the content of the questionnaire. Typically, when the metadata
changes (for example, when variables or categories are added or deleted) a new version is created
and when the changes are complete, the version is locked. For more information, see the topic
Understanding Versions on p. 360.
How do I specify reading from an XML file?
In the connection string in the InputDataSource section, specify mrXmlDsc for the Data Source
property. Specify the name and location of the XML file for the Location connection property and
the name and location of the .mdd file for the Initial Catalog connection property:
Data Source=mrXmlDsc; _
Location=<Name and location of the XML file>; _
End InputDatasource
Example
The sample data management script called MyFirstCleaningScript.dms, which is supplied with the
IBM® SPSS® Data Collection Developer Library, reads data from an XML file.
Reading Data Using Other OLE DB Providers
You are not restricted to using the IBM® SPSS® Data Collection Data Model to read the
data—you can read data using any suitable OLE DB provider that is installed on your system.
Using a non-Data Model OLE DB provider to read the data is similar to doing a case data-only
transfer using the Data Model to read the data. However, non-Data Model providers do not
provide built-in support for market research data types, such as single response and multiple
response categorical data. Note also that the Data Model can read Microsoft Access tables,
Microsoft Excel worksheets, and Microsoft SQL Server tables—see Transferring Data From
Microsoft Office for more information.
If you specify a Metadata section or an output metadata name when you are using a non-Data
Model provider, they will be ignored without giving an error. However, you will get an
error (typically “Object reference not set to an instance of an object”) if you include an
OnAfterMetaDataTransformation, OnJobStart, OnNextCase, or OnJobEnd Event section in your
DMS file. These Event sections are available only when using the Data Model to read the case
data with an input metadata source.
You will get an error if you do not specify a select query in the InputDataSource section when
you are not using the Data Model provider. This is because when not specified, the select query
defaults to SELECT * FROM vdata and this fails because typically the data source will not contain a
table called vdata. So make sure you specify a suitable select query. Each provider has its own
rules about the SQL syntax and connection properties it supports. For further information, refer to
documentation about the provider you are using.
334
Chapter 1
Column names that are not valid Data Model identifier names will cause an error (typically
“Error : Failed to create target table: Output - Unknown table ‘VDATA’”) if they are not given
special handling. For example, Tree Type is not a valid Data Model identifier name because it
contains a space character. This means you will get an error if you use a “SELECT * FROM <
Table Name>” select query. However, the transfer will run successfully if you redefine the column
name using the AS keyword in your select query. For example:
SelectQuery = "SELECT [Tree ID] As TreeID, [Tree Type] As TreeType FROM Trees"
Note that you cannot use the AS keyword when you are transferring the data to a .sav file. For
more information, see the topic FAQs About How To Set Up Specific Jobs on p. 1569.
Alternatively, you could rename the column in your data source. See for more information.
The Provider tab in the Data Link dialog box lists all of the OLE DB providers that are installed.
(You can open the Data Link dialog box in WinDMSRun or using a data link (.udl) file. See
for more information.)
335
Base Professional
Each provider has different requirements for the connection string. If you select a provider on
the Provider tab in the Data Link dialog box, and then click Next, the Connection tab shows the
main connection properties for that provider. For example, here is the Connection tab when the
Microsoft Jet 4.0 OLE DB Provider is selected:
Writing Data
You define the location and format of the data to which you want to write the transferred data
in the OutputDataSource section of the DMS file. You also set the validation options that you
require in this section. For more information, see the topic Validation Options When Transferring
Data on p. 336.
Each CDSC that you can use to write case data behaves differently and has different requirements.
This section provides information on transferring data using some of the write-enabled CDSCs
that come with the IBM® SPSS® Data Collection Data Model.
336
Chapter 1
For information about writing data using an OLE DB provider that is not part of the Data Model,
see Writing Data Using Other OLE DB Providers.
Validation Options When Transferring Data
There are a number of validation options that you can set when you use the IBM® SPSS® Data
Collection Data Model to write the output case data. The actual validation that takes place varies
according to the CDSC that is being used to write the case data. However, you set the options in
the same way. This topic explains the validation options and how to set them.
You define the validation options in the connection string in the OutputDataSource section. If
you are using the Connection String Builder or the WinDMSRun sample application to set up
the connection string, you can select the validation options on the Advanced tab in the Data
Link Properties dialog box.
If you do not specify otherwise, validation in clean mode is automatically selected. When
validation is selected (whether in clean or dirty mode) and a record fails the validation, by default,
both IBM® SPSS® Data Collection Base Professional and DMS Runner display an error message
showing the record number and continue with the run. If the DMS file has a Logging section,
the bad record is written to the log file. At the end of the run, the total number of “bad” records
that were encountered is shown. (A “bad” record is a record that fails the validation.) However,
you can make DMS Runner stop when it encounters a record that fails the validation. You do
this using the DMS Runner /break option when you run the file.
No validation. When you select this option, the CDSC performs no validation of the data at all.
However, some problems can cause errors and prevent the export from succeeding. You select
this option as follows:
If you are setting up the connection string using the Data Link Properties dialog box, on the
Advanced tab deselect Perform data validation.
If you are setting up the connection string manually, set the MR Init Validation connection
property to False:
... MR Init Validation=False; ...
Validation in clean mode. The CDSC validates the case data and rejects incorrect and inconsistent
data. You select this option as follows:
Advanced tab select Perform data validation and deselect Allow dirty.
If you are setting up the connection string manually, set the MR Init Allow Dirty property to
False and the and the MR Init Validation property to True:
... MR Init Allow Dirty=False; _

MR Init Validation=True; ...
337
Base Professional
Validation in dirty mode. The CDSC performs validation checks but accepts some incorrect and
inconsistent data, generally issuing a warning when it does so. You select this option as follows:
Advanced tab select Perform data validation and Allow dirty.
If you are setting up the connection string manually, set the MR Init Allow Dirty and MR
Init Validation properties to True:
... MR Init Allow Dirty=True; _
MR Init Validation=True; ...
This topic provides some notes on using a DMS file to transfer case data to a relational MR
database. The DMS file uses the to write the data to the databas.
Case data that is stored in a relational MR database is typically used with metadata in an .mdd
file. When the case data is collected using IBM® SPSS® Data Collection software, the .mdd file
will typically contain versions, which record any changes to the content of the questionnaire.
Typically, when the metadata changes (for example, when variables or categories are added or
deleted) a new version is created and when the changes are complete, the version is locked. For
more information, see the topic Understanding Versions on p. 360.
For information about exporting IBM® SPSS® Data Collection Interviewer Server data, see
Working with IBM SPSS Data Collection Interviewer Server Data. For a list of sample DMS files
that have been designed specifically for use with Interviewer Server data, see Sample DMS Files
For Exporting IBM SPSS Data Collection Interviewer Server Data.
Writing to a new database. Before you can transfer case data to a new database, you need to create
the SQL Server database. See the instructions later in this topic.
Writing to an existing database. Relational MR database CDSC can write new data to an existing
database. However, except when you are using the UseInputAsOutput option, existing records
are not updated and you will get an error if you attempt to write records that already exist in
the database—that is, records for which the serial number (stored in the Respondent.Serial
system variable) is already in use in the database. However, if necessary you can manipulate
the serial number in the OnNextCase Event section—for example, by adding 1000 to its value.
Alternatively, you could clear the Respondent.Serial variable, because if it is blank, Relational
MR Database CDSC will automatically generate new serial numbers when writing the records.
If the structure of the data has changed, the CDSC will update the structure in the existing
database whenever possible. However, this is not possible if the data type of any of the variables
has changed. For example, you will get an error (typically “Type Mismatch” or “Invalid Index”)
if you attempt to export a categorical variable called age to a database that already contains a
numeric variable called age.
Setting up weighting. Relational MR Database CDSC can update existing records and so you can
use the Weight component to set up weighting in the database. For an example of doing this, see
Setting Up Weighting in a DMS File.
338
Chapter 1
How do I specify an export using RDB DSC 2?
In the connection string in the OutputDataSource section, specify mrRdbDsc2 for the Data Source
property and specify the OLE DB connection string for the Location property. See for more
information. You also need to specify the MR Init Project connection property and make sure that
the Initial Catalog property is set to an empty string and is specified before the Location property:
OutputDatasource(myOutputDataSource, "My output data source")
Initial Catalog="" _
Location=<OLE DB connection string>; _
MR Init Project=<Name of project>"
MetaDataOutputName = "<Name of and location of output .mdd file>"
Using Text Substitution in the OLE DB Connection String
If you are using text substitution to replace text in the OLE DB connection string with your
own text strings, you must enclose the value of the Location property in single quotes (‘)
for the substitution to work correctly. There is an example of this in the sample include file
RDBOutput.dms:
OutputDataSource(RDBOutput)
Initial Catalog=''; _
Location='Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=" + Target + ";Data Source=Loca
MR Init Project=" + Target
MetaDataOutputName = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\" + Target + ".mdd"
RDBOutput.dms is used by the sample file SavToRDB.dms, which includes the following code:
#define Target "SavToRdb"
#Include ".\Include\RdbOutput.dms"
By enclosing the value of the Location property in single quotes, the value of Target will be
correctly inserted into the OLE DB connection string.
How do I create a new SQL Server database?
Note that to be able to create a new SQL Server database, you need Microsoft SQL Server 7 or
later Client Tools to be installed. There are several ways of creating a new database depending on
the version of the SQL Server client tools that you are using:
1. For SQL Server 7 or 2000: Using SQL Server Enterprise Manager
E Open SQL Server Enterprise Manager.
E Use the + symbol to expand Microsoft SQL Servers, SQL Server Group, and the server on which you
want to create the database.
E Select Databases.
339
Base Professional
E From the Action menu, choose New Database.
E Enter a Name for the database.
E Click OK.
2. For SQL Server 7 or 2000: Using the isql command prompt utility
For example, the following creates a database called NewMuseum:

isql -E -d Master -Q "Create Database NewMuseum" -S LocalHost
Provided you have the appropriate rights, you can also use the command to delete a database:
isql -E -d Master -Q "Drop Database NewMuseum" -S LocalHost
For further information about the utility, refer to the SQL Server documentation or use the
folllowing:
isql -?
One advantage of using the command line utility is that you can specify the command in a batch
file and then use the function to call the batch file in the OnBeforeJobStarts Event section. See
the SavToRDB.dms sample file for an example. For more information, see the topic Sample
3. For SQL Server 2005: Using SQL Server Management Studio
E Open SQL Server Management Studio.
E In the Object Explorer pane, use the + symbol to expand the server on which you want to create
the database.
E Right click the Databases node and on the shortcut menu choose New Database. The New
Database dialog box opens.
E Enter a Database Name and click OK. The database is created.
4. For SQL Server 2005: Using the sqlcmd command prompt utility
In SQL Server 2005, isql has been replaced by sqlcmd. However, for most purposes, both utilities
share the same command line parameters. Therefore, the command to create a database using
sqlcmd is almost the same as when using isql:
sqlcmd -E -d Master -Q "Create Database NewMuseum" -S LocalHost
To list all the sqlcmd parameters, use the following command:

sqlcmd -?
Example
1. Using the default Favor Speed option

340
Chapter 1
This example shows a DMS file that transfers case data from a IBM SPSS Data Collection Data
File (.ddf) to a relational MR database, using RDB DSC 2 and its default Favor Speed option.
Before you run this example, you need to create the NewMuseum database and, if necessary,
change the connection string in the OutputDataSource section to reflect the name of the server
you are using.
'==========================================================
'
'
'
'==========================================================
SelectQuery = "SELECT * FROM VDATA WHERE Respondent.Serial < 101"
End InputDataSource
Location='Provider=SQLOLEDB.1; _
Initial Catalog=NewMuseum; _
Data Source=LocalHost'; _
MR Init Project=NewMuseum"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\NewMuseum.mdd"
Note: This example is provided as a sample DMS file (called DDFToRDB.dms) that is installed
with the IBM® SPSS® Data Collection Developer Library. For an example that uses the function
to call an MS-DOS batch file to create the database, see the SavToRDB.dms sample. For more
2. Using the Favor Memory option
There is a known problem (mrBug00015444) that can affect DMS files that use RDB DSC 2 to
write the data. This problem can cause the transfer to fail. You can avoid this problem by using
the Favor Memory option, as shown in this example:
341
Base Professional
Initial Catalog=""; _
Initial Catalog=TargetData; _
MR Init Project=TargetData; _
MR Init Custom=FavorMemory"
MetaDataOutputName = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\TargetData.mdd"
See for more information about this problem.
Troubleshooting checklist
Did the SQL Server database exist before running the transfer?
Does the Data Source property in the string specify the server you are using correctly?
Have you specified the Initial Catalog connection property as an empty string and put it in front of the
Location connection property?
Did you specify the project name (MR Init Project connection property) correctly?
Do the serial numbers in the data you are tranferring conflict with serial numbers that already exist
in the target database?
Has there been a change in the data type of any of the variables you are transferring? (This applies only if
you are transferring to an existing RDB database.)
Requirements
Microsoft SQL Server 7, 2000, or 2005 Client Tools
This topic provides some notes on using a DMS file to transfer case data to a IBM SPSS Data
Collection Data File (.ddf or .dzf). The DMS file uses the to write the data to the IBM SPSS
Data Collection Data File.
Writing to a new file. If the IBM SPSS Data Collection Data File you specify in the
OutputDataSource section does not exist, the IBM SPSS Data Collection Data File CDSC will
create a new file.
Writing to an existing file. The IBM SPSS Data Collection Data File CDSC can write data to
an existing IBM SPSS Data Collection Data File. If the structure of the data has changed,
the IBM SPSS Data Collection Data File CDSC will update the structure in the existing file
whenever possible. You can update data that was transferred previously only if you include the
UseInputAsOutput option in the OutputDataSource section. Otherwise, the DMS file merely
appends the new case data records to the end of the IBM SPSS Data Collection Data File. You
should therefore be careful not to create duplicate records in the IBM SPSS Data Collection Data
File by exporting the same case data more than once.
342
Chapter 1
Setting up weighting. The IBM SPSS Data Collection Data File CDSC can update existing records
and so you can use the Weight component to set up weighting in the IBM SPSS Data Collection
Data File. For an example of doing this, see Setting Up Weighting in a DMS File.
How do I specify an export to a IBM SPSS Data Collection Data File?
In the connection string in the OutputDataSource section, specify mrDataFileDsc for the Data
Source property and the name and location of the IBM SPSS Data Collection Data File for the
Location property. For example:
OutputDataSource(Output,"The output data source")
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\AnalysisData.ddf;
MetaDataOutputName = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\AnalysisData.mdd"
How do I specify an export to a compressed file?
Follow the instructions above, but specify the .dzf file extension instead of .ddf. For example:
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\AnalysisData.dzf;
MetaDataOutputName = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\AnalysisData.mdd"
Note: The IBM® SPSS® Data Collection Developer Library comes with a number of sample
DMS files that transfer data to a IBM SPSS Data Collection Data File. For more information,
This topic provides some notes on using a DMS file to transfer case data to a .sav file. The DMS
file uses the SPSS Statistics SAV DSC to write the data to the .sav file.
Writing to a new .sav file. If the .sav file you specify in the OutputDataSource section does not
exist, SPSS Statistics SAV DSC will create a new .sav file.
Writing to an existing .sav file. A DMS file can be used to write data to an existing .sav file if it is
empty. If it is not empty, the export will succeed only if all of the following are true:
You have exported to that file previously.
You are using the same .mdd file for the export as was used previously. If the first export was
done using a DMS file, you need to use the output metadata file from that export as the input
metadata source for the second and subsequent transfers.
There has been no change in the structure of the data since the previous export. This means
that the select query in the InputDataSource section in the second and subsequent transfers
must specify the same variables that were specified for the first transfer.
343
Base Professional
However, SPSS Statistics SAV DSC cannot update the data that was transferred previously, and
merely appends the new case data records to the end of the file. You should therefore be careful
not to create duplicate records in the .sav file by exporting the same case data to it more than once.
If you are using a DMS file to write to an existing .sav file that was created using a version of the
IBM® SPSS® Data Collection Data Model from versions 3.0 to 5.5, you may find that the transfer
fails because the variables are not being output in the same order as before. In versions 3.0 through
5.5, the order of the variables in the output data source was determined by the variable order in
the SelectQuery statement in the DMS file’s InputDataSource section. To resolve this problem,
reorder the Select Query’s variable order in the DMS file’s InputDataSource Section, or transfer
the old .sav file to a new .sav file using the new Select Query (this will allow you to append data).
The SPSS WebApp file. In addition to the .sav file, SPSS Statistics SAV DSC automatically creates
an XML file that provides additional information for use with SPSS WebApp. This XML file
has the same name as the .sav file, but with the addition of an .xml filename extension. If a file
of that name already exists in the same location, SPSS Statistics SAV DSC will overwrite it
without issuing a warning.
Customizing the output files. You can customize both the XML file and the variables in the .sav
file by setting custom properties in the metadata that is specified in the InputDataSource section.
Typically, you would do this in the OnBeforeJobStart Event section. See and for more information.
Variable names. Generally SPSS Statistics SAV DSC cannot use the same names for the variables
in the .sav file as in the metadata because the variable-naming rules are different. SPSS
Statistics SAV DSC automatically creates names that conform to the IBM® SPSS® Statistics
variable-naming rules. These SPSS Statistics-specific names are called aliases and are stored
in the output metadata. This means that if you want to use the same names for a subsequent
export, you need to use the output metadata file from the previous export as the input metadata
source for the new transfer.
You can optionally customize the aliases. Just as with the custom properties, you would typically
do this in the OnBeforeJobStart Event section. See for more information.
Note: You can set up custom properties and customize the aliases, only if you are using a Metadata
Document (.mdd) file in the InputDataSource section.
Output metadata. It is recommended that you save the output metadata file, whenever possible. If
you subsequently want to read the .sav file using the Data Model, it is usually preferable to do
so using the .mdd file, because this gives you access to the original Data Model variable names.
In addition, if you subsequently want to export additional records to the same .sav file, it will
be possible only if you run the export using the output metadata from the previous export as
the input metadata source.
Transferring case data without a metadata source. Transferring data to a .sav file without specifying
a metadata source in the InputDataSource section is generally possible only when you are reading
the data using a non-Data Model OLE DB provider. When there is no metadata source, SPSS
Statistics SAV DSC is not able to create and store the alias names and merely uses the first eight
characters of the names from the input file. This means you will get an error if the first eight
344
Chapter 1
characters of any of the variable names contain characters that are not allowed in SPSS Statistics
variable names or if there are any duplicates. Problems will also arise when using SPSS Statistics
SAV DSC in Data Model 2.9 or earlier if any text variables store texts that are longer than 255
characters because of the limit in SPSS Statistics 12 and earlier. When you are using the Data
Model to read the data to be transferred, you should always specify an input metadata source.
Exporting dirty data. When you run the export in clean mode, SPSS Statistics SAV DSC issues
errors when it encounters incorrect and inconsistent data and this can make the export of those
records fail. If you want to export the data as it is and clean it in SPSS Statistics, select dirty
mode or switch off validation altogether. For more information, see the topic Validation Options
When Transferring Data on p. 336.
Setting up weighting. Because SPSS Statistics SAV DSC can update the records in the .sav file,
you can use the Weight component to set up weighting in the .sav file. The DDL includes a data
management script called SavWeighting.dms, which demonstrates how to add weights to a .sav
file. For more information, see the topic Sample DMS Files on p. 467.
Working with Japanese characters. DMS files provides only limited support for Japanese
characters when working with .sav files. In particular, if the names of any of the variables that
you are exporting contain Japanese characters, the Japanese characters may be incorrect in the
.sav file. If necessary, you will need to correct the variable names manually in the Japanese
language version of SPSS Statistics.
How do I specify an export to IBM SPSS Statistics?
In the connection string in the OutputDataSource section, specify mrSavDsc for the Data Source
property and the name and location of the .sav file for the Location property. For example:
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\museum.sav
MetaDataOutputName = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\museum.mdd"
Example
This example shows a DMS file that contains an OnBeforeJobStart Event section that sets
up custom properties in the input metadata to customize both the .sav file and the WebApp
.xml file. The custom properties are written to the Document.Properties collection because,
although SPSS Statistics SAV DSC reads the custom properties from the DataSourceProperties
collections, these are inherited from the Properties collection. If you want custom properties to
be available for the current MDM DataSource only, you should write the custom properties to
the DataSourceProperties collections. However, this would require first checking whether the
DataSource object exists, and if it doesn’t creating a new one. For an example of doing this for
IBM® SPSS® Quantum™ DSC, see OnBeforeJobStart Event Section. You would also need
to do this if you want to customize the aliases because the VariableInstance.AliasName and
VariableInstance.SubAliases properties are also specific to a specified DataSource object.
345
Base Professional
See the section for more information about setting custom properties in general and the custom
properties used by SPSS Statistics SAV DSC.
'==========================================================
'
'
'
'==========================================================
#define COPY_OF_MUSEUM_MDD "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum.mdd"
Event(OnBeforeJobStart, "Set up the custom properties")

Dim MDM, fso, f
' Create a copy of museum.mdd so that

' we do not update the original file...
COPY_OF_MUSEUM_MDD, True)
' Make sure that the read-only attribute is not set

Set f = fso.GetFile(COPY_OF_MUSEUM_MDD)
End If

MDM.Open(COPY_OF_MUSEUM_MDD)
MDM.Contexts.Add("SAV")
MDM.Contexts.Current = "SAV"
MDM.Properties.Item["DichotomyLabelYes"] = "Oui"
MDM.Properties.Item["DichotomyLabelNo"] = "Non"
MDM.Contexts.Add("WebApp")
MDM.Contexts.Current = "WebApp"
MDM.Properties.Item["SecurityGroups"] = "World;LocalUser;WanUser"
MDM.Save()
MDM.Close()
End Event
346
Chapter 1
Initial Catalog=" + COPY_OF_MUSEUM_MDD

SelectQuery = "SELECT serial, age, gender, before, biology, distance, _
education, entrance, expect, visits, adults, museums, plan, similar, _
certificat, location, who_with, resident, when_decid, _
why_decid, plan_time, know_way, find_way _
FROM VDATA WHERE serial < 101"
End InputDataSource
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\SavCustomization.sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\SavCustomization.mdd"
Note: This example is provided as a sample DMS file (called SavCustomization.dms) that is
This topic provides some notes on using a DMS file to transfer case data to a IBM® SPSS®
Quantum™-format .dat file. The DMS file uses the to write the data to the .dat file. The Quantum
format stores the responses to each question in fixed positions on lines of text. The positions are
controlled by card and column definitions that are stored in the metadata.
Note: Quantum Specification files are not saved when transferring data to Quantum with DMOM.
Card, column, and punch definitions. In order to be able to export the case data, Quantum DSC
requires valid card, column, and punch definitions to exist in the metadata. You can set up these
definitions using the before the export or using the in the OnBeforeJobStart Event Section or
OnAfterMetaDataTransformation Event Section Event sections.
Serial number variable. Quantum DSC can optionally write open-ended responses to a .dau file.
However, this is possible only if the data contains a suitable serial number variable. By default,
the IBM® SPSS® Data Collection Metadata Model to Quantum component and Quantum
DSC look for a serial number variable called Respondent.Serial. However, you can specify
that a different variable should be used as the serial number variable. You do this using the
MDM2Quantum.SerialFullName property and the corresponding SerialFullName . IBM® SPSS®
Data Collection data generally contains the Respondent.Serial variable. However, proprietary
data does not usually have this variable. For an example of setting up Respondent.Serial when
exporting to Quantum from a .sav file, see the SavToQuantum.dms sample DMS file.
Writing to a new .dat file. If the .dat file you specify in the OutputDataSource section does not
exist, Quantum DSC will create a new .dat file.
Writing to an existing .dat file. Quantum DSC can write data to an existing .dat file but does not
check that the data being exported matches the data already present in the file. Quantum DSC
cannot update the data that was transferred previously, and merely appends the new case data
347
Base Professional
records to the end of the file. You should therefore be careful to make sure that subsequent exports
to the same .dat file use the same data map and not to create duplicate records in the .dat file by
exporting the same case data to it more than once.
If you are using a DMS file to write to an existing .dat file that was created using a version of
the IBM® SPSS® Data Collection Data Model earlier than 3.0, and you allocate the card and
column information in the OnAfterMetadataTransformation event section, you may find that the
card and column allocations are no longer the same as before.
Exporting dirty data. When you run the export in clean mode, Quantum DSC issues errors when it
encounters incorrect and inconsistent data and this can make the export of the dirty records fail.
If you want to export the data as it is and clean it in Quantum, select dirty mode or switch off
validation altogether. For more information, see the topic Validation Options When Transferring
Data on p. 336.
Creating the Quantum specification. You can include code in the DMS file to create a basic
Quantum specification based on the card, column, and punch definitions. For more information,
see the topic Creating the IBM SPSS Quantum Specification on p. 368.
Setting up weighting. Because Quantum DSC can update the records in the .dat file, you can use
the Weight component to set up weighting in the .dat file. The DDL includes a data management
script called QuantumWeighting.dms, which demonstrates how to add weights to a .dat file. For
more information, see the topic Sample DMS Files on p. 467.
Note: When IBM® SPSS® Data Collection Base Professional validates a DMS file that exports
data to Quantum, it tests the connection to the Quantum .dat file. This always returns two
warnings because the validation is performed before the output metadata has been created and
without a metadata source Quantum DSC cannot function. This is because Quantum DSC relies
on the card, column, and punch definitions in the metadata. You can safely ignore these warnings.
How do I specify an export to IBM SPSS Quantum?
In the connection string in the OutputDataSource section, specify mrPunchDsc for the Data Source
property and the name and location of the .dat file for the Location property. For example:
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MDM2Quantum.dat
MetaDataOutputName = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MDM2Quantum.mdd"
Example
For an example of a DMS file that sets up the card, column, and punch definitions and then exports
to a Quantum-format .dat file, see OnBeforeJobStart Event Section. Also see the CardCols.dms
and CardColsPlus.dms sample Include files. For more information, see the topic Sample DMS
Include Files on p. 479.
348
Chapter 1
You can transfer data to Triple-S files by using the Triple-S DSC. The Triple-S DSC can output
files that meet version 1.2 or version 2.0 of the Triple-S standard. Version 2.0 of the standard
supports case data files that contain either fixed-format fields or comma-separated values, while
version 1.2 of the standard supports only fixed-format fields. However, the Triple-S DSC cannot
output hierarchical data (which was introduced in the version 2.0 standard).
Writing to new files. If the Triple-S metadata and case data files you specify in the
OutputDataSource section do not exist, the Triple-S DSC will create new files.
Writing to existing files. The Triple-S DSC will append data to an existing file that has the same
name as the Triple-S case data file to be written, but does not attempt to check whether the format
and structure of the existing data and the new data are the same.
Warning: The Triple-S DSC always overwrites an existing file that has the same name as the
Triple-S metadata file to be written.
Specifying the format of the Triple-S case data. By default, the Triple-S DSC outputs fixed-format
fields. To specify that you want comma-separated values, you must include the MR Init Custom
connection property in the connection string for the OutputDataSource, as described in “How do I
specify an export to Triple-S files?” below.
Output metadata. Typically, you will want to write the metadata to a Triple-S metadata file, so
that the case data and metadata can be read together by a third-party application that supports
Triple-S. However, you can also (or instead) output a metadata document (.mdd) file, which
you might want to do if you plan to read the Triple-S case data using another IBM® SPSS®
Data Collection product. In general though, it is better to use a IBM SPSS Data Collection Data
File to store “offline” interview data.
How do I specify an export to Triple-S files?
In the connection string in the OutputDataSource section, specify mrTripleSDsc for the Data
Source and the MR Init MDSC connection properties. Specify the name and location of the Triple-S
case data file, which will normally have a .asc, .dat, or .csv extension, for the Location connection
property. Then specify the name and location of the Triple-S metadata file, which will normally
have a .sss or .xml extension, for the Initial Catalog connection property.
Finally, if you want the case data to consist of comma-separated values instead of fixed-format
fields, you must include the MR Init Custom connection property as shown below:
Data Source = mrTripleSDsc; _
Location = <Name and location of .asc, .dat, or .csv file>; _
Initial Catalog = <Name and location of .sss or .xml file>; _
MR Init MDSC = mrTripleSDsc; _
MR Init Custom = 'SssFormat = csv'"
349
Base Professional
To export fixed-format fields, simply omit the MR Init Custom property or set the value of
SssFormat to “fixed” instead of “csv”.
If you do not require a Triple-S metadata file, simply omit the Initial Catalog and MR Init
MDSC connection properties. To create a metadata document (.mdd) file instead, add a
MetaDataOutputName statement to the OutputDataSource section. For example:

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MyTripleSData.asc"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MyTripleSData_asc.mdd"
Example
This example has two OutputDataSource sections, which create two Triple-S case data files
containing fixed-format fields and comma-separated values:
OutputDataSource(myOutputDataSource1, "Output metadata and fixed-format case data")
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToTripleS.asc; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToTripleS_asc.xml; _
MR Init Custom = 'SssFormat = fixed'"
' Output the Triple-S metadata file

' and comma-separated case data file
OutputDataSource(myOutputDataSource2, "Output metadata and comma-separated case data")
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToTripleS.csv; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToTripleS_csv.xml; _
MR Init Custom = 'SssFormat = csv'"
Note: This example is taken from the RDBToTripleS.dms sample file, which is installed with the
You can transfer data to a SAS data file in the SAS version 7 for Windows, standard-extension
format. These types of files have a .sas7bdat extension. The SAS DSC also writes a SAS program
(.sas) file immediately after writing the SAS data file.
Writing to a new file. If the SAS data file you specify in the OutputDataSource section does
not exist, the SAS DSC will create a new file.
350
Chapter 1
Writing to an existing file. The SAS DSC cannot append data to an existing SAS data (.sas7bdat)
file. The transfer will fail if a file exists with the same name and location as the SAS data file to
be written.
Warning: The SAS DSC always overwrites an existing SAS program (.sas) file that has the same
name as the SAS program file to be written.
How do I specify an export to a SAS file?
In the connection string in the OutputDataSource section, specify mrSasDsc for the Data Source
connection property. Then specify the name and location of the SAS data file, which will normally
have a .sas7bdat extension, for the Location connection property, as shown below.

Data Source = mrSasDsc; _
Location = <Name and location of .sas7bdat file>"
Note that the SAS DSC will write the SAS program (.sas) file to the same location as the SAS
data (.sas7bdat) file.
Example
This example OutputDataSource section is taken from the RDBToSAS.dms sample file, which
is installed with the IBM® SPSS® Data Collection Developer Library. For more information,
ConnectionString="Provider=mrOleDB.Provider.2; _
Data Source=mrSasDsc; _
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\RDBToSAS.sas7bdat"
You can transfer case data to a text file that contains tab-delimited, variable length records. The
text file typically has a .csv extension and can be imported in to Microsoft Excel.
Writing to a new file. If the delimited text file you specify in the OutputDataSource section does
not exist, the Delimited Text DSC will create a new file.
Writing to an existing file. The Delimited Text DSC will append data to an existing file that has
the same name as the delimited text file to be written, but does not attempt to check whether the
structure of the existing data and the new data are the same.
351
Base Professional
How do I specify an export to a delimited text file?
In the connection string in the OutputDataSource section, specify mrCsvDsc for the Data Source
connection property. Then specify the name and location of the delimited text file, which will
normally have a .csv extension, for the Location connection property, as shown below.
Data Source = mrCsvDsc; _
Location = <Name and location of .csv file>"
Example
This example OutputDataSource section creates a delimited text file and an output metadata
document (.mdd) file:
Data Source=mrCsvDsc; _
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MyDelimTextFile.csv"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MyDelimTextFile.mdd"
A similar example is provided as a sample file called CreateCSVAndCategoryMap.dms, which

This topic provides some notes on using a DMS file to transfer case data to an XML file. The
DMS file uses the to write the data to the XML file.
Warning: The XML DSC is supplied by IBM® SPSS® Data Collection for the purpose of
demonstrating and testing the transfer of small volumes of data. Do not use the XML DSC in
production processes—use the IBM SPSS Data Collection Data File CDSC instead. The XML
DSC might be withdrawn in a future release of Data Collection.
Writing to a new file. If the XML file you specify in the OutputDataSource section does not exist,
XML CDSC will create a new file.
Writing to an existing file. XML CDSC can write data to an existing XML file. If the structure of
the data has changed, XML CDSC will update the structure in the existing file whenever possible.
However, XML CDSC cannot update the data structure if the data type of any of the variables has
changed. For example, you will get an error (typically “Invalid index”) if you attempt to export a
categorical variable called age to a file that contains a numeric variable called age. The DMS
file does not update data that was transferred previously, and merely appends the new case data
records to the end of the file. You should therefore be careful not to create duplicate records in the
XML file by exporting the same case data to it more than once.
352
Chapter 1
Setting up weighting. XML CDSC can update existing records and so you can use the Weight
component to set up weighting in the XML file. For an example of doing this, see Setting Up
Weighting in a DMS File.
How do I specify an export to an XML file?
In the connection string in the OutputDataSource section, specify mrXmlDsc for the Data Source
property and the name and location of the XML file for the Location property. For example:
Data Source=mrXmlDsc; _
Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\CleanData.xml; _
MetaDataOutputName = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\CleanData.mdd"
Writing Data Using Other OLE DB Providers
You are not restricted to using the IBM® SPSS® Data Collection Data Model to write the
data—you can write data using any suitable OLE DB provider that is installed on your system.
Using a non-Data Model OLE DB provider to write the case data differs from using the Data
Model to write the case data in several ways:
Metadata. No output metadata is created, because it is not relevant to non-Data Model data formats.
Categorical data. Non-Data Model providers do not provide built-in support for categorical data
and all categorical values are converted into text. By default the category values are exported
as the unique numeric values that are known as MDM mapped values. This means the single
response data in the output data source is in the form {34} where 34 is the MDM mapped
value of the category that was chosen and multiple response data is in the form {34, 38, 42}.
However, provided you are using an input metadata source, by setting the MR Init Category
Names connection property to 1, the category names are exported instead. This means that single
response and multiple response data is in the form {female} and {dinosaurs, fossils, evolution},
respectively and this is generally easier to interpret.
Variable names. Some Data Model variable names contain characters that are not supported by
some OLE DB providers. For example, the names that the Data Model generates for variables
that are part of grids and loops typically contain periods (.) and brackets ([ ]), which are not
supported by some OLE DB providers. IBM® SPSS® Data Collection Base Professional
therefore replaces periods with the underscore character (_) and brackets with parentheses (( )),
which are generally supported. For example, Respondent.Serial becomes Respondent_Serial and
CHILDHHZ[{YEARS_0_5}].Questi1 becomes CHILDHHZ({YEARS_0_5})_Questi1. However,
these characters are supported by Microsoft SQL Server and so the names are unchanged when
you export to Microsoft SQL Server using the Microsoft OLE DB Provider for SQL Server.
Column order. When you look at the exported data, you may find that the columns are in an
unexpected order. This is because the sorting of the columns is controlled by the OLE DB provider
you are using and the sorting rules vary from provider to provider.
353
Base Professional
TableOutputName. In the OutputDataSource Section, you must specify the name of the table to
which you want to write the data. The table will be created if it does not exist already. You can
append data to an existing table only if the provider you are using supports this operation and the
structure of the data you are transferring is identical to (or a subset of) the data in the existing
table. For example, if the existing table contains the variables age, gender, and income, exports
that contain the variables age and gender, or age, gender, and income should succeed, provided
the variables are of the same type and the provider you are using supports this type of operation.
However, an export of variables age, gender, income, and occupation would fail.
The Provider tab in the Data Link dialog box lists all of the OLE DB providers that are installed.
(You can open the Data Link dialog box in WinDMSRun or using a data link (.udl) file. See
for more information.)
354
Chapter 1
Each provider has different requirements for the connection string. If you select a provider on
the Provider tab in the Data Link dialog box, and then click Next, the Connection tab shows the
main connection properties for that provider. For example, here is the Connection tab when the
Microsoft OLE DB Provider for SQL Server is selected:
For further information, refer to documentation about the provider.
Examples
1. Exporting Data To Access
The following example uses the Microsoft Jet 4.0 OLE DB Provider to transfer a subset of the
Short Drinks sample to an Access database. Before you run this sample, you need to create
a database called DMSTransfers.mdb and make sure that it does not already contain a table
called short_drinks.
'==========================================================
'
'
'
'==========================================================
355
Base Professional
MR Init Category Names=1; _
MR Init Project=short_drinks"
SelectQuery = "SELECT Respondent.Serial, gender, age, income, occup, hhsize FROM vdata WHERE DataCollection.MetadataVersionNum
End InputDatasource
OutputDatasource(MSAccess)
ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; _
Data Source=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\DMSTransfers.mdb; _
Persist Security Info=False"
TableOutputName = "short_drinks"
Notice that the MR Init Category Names connection property has been set to 1 in the
InputDataSource section. This means that the category names will be exported rather than the
numeric cateogry values. Note that you must not use this setting if the DMS file contains another
OutputDataSource section that writes data using the IBM SPSS Data Collection OLE DB Provider.
2. Exporting Data To Excel
The following example shows an OutputDataSource that uses the Microsoft OLE DB Provider for
ODBC Drivers to transfer data to an Excel file. This OutputDataSource section assumes that an
empty Excel file called MSExcelTransferToFromRDB.xls already exists in the output folder.
OutputDatasource(MSExcel)
ConnectionString = "Provider=MSDASQL.1; _
Data Source=Excel Files; _
Initial Catalog=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelTransferToFromRDB.xls"
TableOutputName = "Sheet1"
You can create the empty Excel file using the following code in the OnBeforeJobStarts Event
section.
Event(OnBeforeJobStart, "Do some file and folder management")

Dim MyExcelApp, MyExcelBook, MyExcelSheet
'Set up my Excel document
Set MyExcelApp = CreateObject("Excel.Application")
Set MyExcelBook = MyExcelApp.WorkBooks.Add()
MyExcelBook.SaveAs("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MSExcelTransferToFromRDB.xls")
myExcelApp.Quit()
End Event
3. Exporting Data To Microsoft SQL Server

356
Chapter 1
The following example shows an OutputDataSource that uses the Microsoft OLE DB Provider
for SQL Server to transfer data to an SQL Server database. Note that this transfers the data to a
single table that matches the Data Model’s VDATA virtual table and does not use the schema and
format used by . If you want to transfer the data to SQL Server using the RDB CDSC’s schema,
you should use RDB CDSC for the transfer, as described in Transferring Data to a Relational
MR Database (RDB).
Base Professional automatically converts dates into a format that is supported by SQL Server.
The format is YYYY-MM-DD or YY-MM-DD where YYYY and YY is the four-digit or two-digit
year number (depending on the number of digits stored in the data), MM is the month number,
and DD is the day number.
To run this sample, you need access to an SQL Server installation that contains a database called
DMSTransfers.
OutputDatasource(MSSQL)
ConnectionString = "Provider=SQLOLEDB.1; _
Initial Catalog=DMSTransfers; _
Data Source=LocalHost"
TableOutputName = "short_drinks"
Note: These examples are provided as sample DMS files (called

MSAccessTransferToFromRDB.dms, MSExcelTransferToFromRDB.dms, and
MSSQLTransferToFromRDB.dms) that are installed with the IBM® SPSS® Data Collection
Developer Library. For more information, see the topic Sample DMS Files That Integrate
with Microsoft Office on p. 475.
Working with IBM SPSS Data Collection Interviewer Server Data
When you conduct surveys using IBM® SPSS® Data Collection Interviewer Server, the response
data is stored in a relational MR (RDB) database as it is collected and the questionnaire definition
is stored in a Metadata Document (.mdd) file. When you use a DMS file to export the response
data to other formats, you generally use the .mdd file as the input metadata source for the transfer.
However, the questionnaire definition (.mdd) file for a project exists in several locations as follows:
The FMRoot\Shared folder on the File Management server
The FMRoot\Master folder on the File Management server
The Projects folder on each interview tier machine.
Generally, you should use the .mdd file that is in the FMRoot\Shared folder as the input metadata
source when you use a DMS file to transfer your Interviewer Server case data. However, this is not
reflected in the examples in this section. This is because the examples use the Short Drinks sample
that comes with the IBM® SPSS® Data Collection Developer Library and which is installed by
default into the standard location within the Program Files folder.
357
Base Professional
This section provides information about how to export Interviewer Server data to other formats. In
this section, the .mdd file to be used as the input metadata source is assumed to be the .mdd file
that is in the FMRoot\Shared folder, except when specified otherwise.
Much of the material in this section is also applicable to data collected using IBM® SPSS®
Data Collection Paper - Scan Add-on and stored in a relational MR database. However,
Paper - Scan Add-on does not set the DataCollection.Status, DataCollection.StartTime, or
DataCollection.FinishTime system variables.
Note: The Data Collection Developer Library comes with a number of sample DMS files that
have been designed to demonstrate exporting Interviewer Server data. All of the samples use
the Short Drinks sample database, but they can be adapted easily to run with any multiversion
project. For more information, see the topic Sample DMS Files For Exporting IBM SPSS Data
Collection Interviewer Server Data on p. 473.
Filtering on the Interview Status
When data is collected using IBM® SPSS® Data Collection Interviewer Server, the
DataCollection.Status stores information about the status of the interview. DataCollection.Status
is a multiple response variable that has the following categories:
Category Name Description
Completed The respondent completed the interview.
Active The interview is in progress.
TimedOut The interview timed out, for example, because the
respondent lost his or her connection or went to
another page.
ScriptStopped The interview was stopped by the script.
RespondentStopped The interview was stopped by the respondent.
Shutdown The interview was stopped because the interview
system shut down.
Signal The interview was terminated by the signal
keyword.
Test The data was collected when the questionnaire was
being tested.
You can use this variable to filter the case data records according to the interview status. You
do this by setting up a WHERE clause in the select query in the InputDataSource section. For
example, if you want to restrict the export to data that comes from completed “real” (that is, not
test) interviews, you could use the following:
SelectQuery = "SELECT * FROM vdata _

WHERE (ContainsAny(DataCollection.Status, {completed})) _
AND NOT (DataCollection.Status >= {test})"
358
Chapter 1
Because it is common to analyze only completed “real” interview data, this filter is included in
most of the DMS sample files that are designed for use with mrIntervew. However, you can easily
adapt the filter. For example, if you want to include timed out interviews as well as completed
ones, you would change the WHERE clause to:
WHERE (ContainsAny(DataCollection.Status, {completed, timedout})) _
If you want to include all of the data regardless of its interview status, you would remove the
WHERE clause or replace it, as required.
Filtering on the Interview Finish Time
When data is collected using IBM® SPSS® Data Collection Interviewer Server, the
DataCollection.StartTime and DataCollection.FinishTime store the date and time that the
interview started and finished. You can use these variables to filter the case data records according
to the time the interview started or finished. For example, the following WHERE clause selects
interviews that finished in the last 24 hours. (Note that it uses the function to subtract 24 hours
from the date and time returned by the function.)
WHERE (DataCollection.FinishTime > DateAdd(Now(), 'h', -24))"
However, the DataCollection.StartTime and DataCollection.FinishTime system variables store the

times in coordinated universal time (UTC). (UTC was formerly referred to as Greenwich Mean
Time or GMT.) Whereas the Now function returns the current date and time on the server.
Data Model 2.8.1 does not have a function for returning a date and time in UTC. However, this
is planned for a future version of the Data Model. Until this function is available, there are two
options for handling the time comparison. One method is to adjust the interval subtracted from the
current time in the select query to take account of the time difference between your timezone and
UTC. For example, New York is 5 or 6 hours behind UTC time, depending on whether daylight
saving time is in force. So if you are running the DMS file in New York, you would subtract 19
hours (18 hours when daylight saving time is in force) from the current time to select interviews
that were completed in the previous 24 hours:
WHERE (DataCollection.FinishTime > DateAdd(Now(), 'h', -19))"
Alternatively, you could use code similar to the following in the OnNextCase Event section. This
code uses the WScript.Shell object to get the timezone information from the registry and uses it
to convert the output of the Now function to UTC. (See Microsoft Knowledge Base Article -
Q208305 for more information.) Case data records whose finish time does not meet the criteria
are filtered out of the export using the Job.DropCurrentCase method.
Event(OnJobStart)
Dim WshShell, Bias, UTC
Set WshShell = CreateObject("WScript.Shell")

359
Base Professional
Bias = WshShell.RegRead("HKLM\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\ActiveTimeBias")
UTC = CDate(CDouble(Now()) + (CDouble(Bias) / 1440))
UTC = UTC.DateAdd("h", -24)
dmgrGlobal.Add("Last24hrs", UTC)
End Event
Event(OnNextCase)
If DataCollection.FinishTime < dmgrGlobal.Last24hrs Then
dmgrJob.DropCurrentCase()
End If
End Event
Generally using a WHERE clause to select case data records is faster than using mrScriptBasic
code in the OnNextCase Event section.
Note: The code in this example is included in the mrInterviewSelectOnFinishTime.dms sample

DMS file that comes with the IBM® SPSS® Data Collection Developer Library. For more
information, see the topic Sample DMS Files For Exporting IBM SPSS Data Collection
Interviewer Server Data on p. 473.
Restricting the Variables Included in the Export
Sometimes you may want to export a subset of the variables in your project. For example, you
may want to export certain key variables only. The Filtering Data in a DMS File topic describes
how you can easily set up a metadata filter in your DMS files to restrict the variables included in
the export. However, sometimes you may want to restrict an export to variables of one type, such
as categorical or text variables. The IBM® SPSS® Data Collection Developer Library comes
with two sample .mrs files that are useful when you want to do this. These samples could easily be
amended to select variables of different types.
Both samples create a SELECT statement containing Respondent.Serial and all of the variables
of the specified type. You can easily copy the SELECT statement in the text file and paste it
into your DMS file. It is also easy to delete the names of any variables of the specified type
that you do not want to include. Alternatively, you can use the text file as an Include file.
The mrInterviewCategoricalsOnlyToDDF.dms sample provides an example of doing this. For
more information, see the topic Sample DMS Files For Exporting IBM SPSS Data Collection
Interviewer Server Data on p. 473. In addition, the CategoricalsOnly.bat sample batch file
provides an example of running the two files. For more information, see the topic Sample Batch
Files on p. 481.
ListCategoricalVars.mrs. This writes the full name of each categorical variable instance to a text file
in a form that can be copied and pasted straight into the select query in a DataManagementScript
(DMS) file.
ListOpenEndedVars.mrs. This writes the full name of each text variable instance to a text file in
a form that can be copied and pasted straight into the select query in a DataManagementScript
(DMS) file.
360
Chapter 1
Understanding Versions
As an IBM® SPSS® Data Collection Interviewer Server survey progresses, changes are
sometimes made to the questionnaire definition. For example, questions and categories may be
added and deleted. Typically a new version is created in the .mdd file each time a change is made
to the questionnaire definition and each version corresponds to a variation of the questionnaire
definition used for some of the interviews. When the responses are stored in the RDB database,
the name of the version of the questionnaire definition used for the interview is also stored (in the
DataCollection.MetadataVersionNumber ).
When you export the data using a DMS file, unless you specify a particular version or versions,
the most recent version of the questionnaire is automatically used and only the variables that are in
that version will be available for exporting. You can optionally select a previous version of the
metadata to use for the export. You can also select multiple versions to use for the export. If you do
this, only the variables that are in the selected version or versions will be available for that export.
However, it is important to understand that the version or versions of the metadata used for the
export do not affect which case data records are included in the export (although you can set up a
filter to restrict the export to data collected using one or more specific versions).
Suppose you are using a single version for the export. When categories have been deleted in that
version and you are exporting case data collected using a version in which those categories were
present, you may get validation errors if any of the responses contain the deleted category, because
the metadata for those categories does not exist in the version of the metadata being used.
To illustrate this, let’s look at what happens when we run an export from the Short Drinks sample.
But first we need to understand the versions in the Short Drinks sample. The following table gives
details of the important differences in each of the six versions in the Short Drinks sample .mdd file.
Version Name Description
1 This version was created when the Interviewer
Server project was activated in test mode and was
used for collecting test data. 5 cases were collected
using this version.
Server project was first activated in live mode. 45
cases were collected using this version. There were
no significant changes in this version.
3 In this version a new category (Fulltime parent)
was added to the sclass question. 24 cases were
collected using this version.
4 In this version the 7 or more people category was
deleted from the hhsize question and the text on the
6 people category was changed to 6 or more people.
20 cases were collected using this version.
5 In this version the text of the Fruit drinks category
in the numdrksz question was changed to Fruit and
vegetable drinks and the sclass categorical question
was deleted and replaced with an open-ended
question called occup. 27 cases were collected
using this version.
6 System variables were added to support 5.6 features.
361
Base Professional
When we run an export from the Short Drinks sample without specifying the version to use,
version 6 is automatically used because it is the most recent version and only the variables that are
in that version will be exported. This means that the sclass variable that was deleted in version
5 will not be exported. However, if the export includes case data records that were collected
using version 3 or earlier, we would expect to get a validation error on any records for which
the category deleted in version 4 was selected. (However, the behavior will depend on the
validation options you have chosen. For more information, see the topic Validation Options
When Transferring Data on p. 336.)
The occup variable that was added in version 5 will have a NULL value in case data records
that were collected using any of the earlier versions, because this variable did not exist in those
versions. A NULL value in the case data generally means that the question that corresponds to
the variable was not asked.
If you run the export again, but this time you select version 3 of the metadata and include all of the
case data records, we would expect the export to run without any validation errors because version
3 contains all of the categories. This time the export will include the sclass variable deleted in
version 5 but will exclude the occup variable that replaced it. This would mean that the sclass
variable would have a NULL value for all respondents who took the survey using version 5.
Selecting a Specific Version
When you transfer IBM® SPSS® Data Collection Interviewer Server data using a DMS file, by
default the most recent version of the metadata is used and the export includes case data for all
versions. However, you can select a specific version of the metadata to be used and it is easy to set
up a filter to restrict the transfer to records that were collected using one or more specified versions.
Version names are made up of a combination of the major version and minor version numbers in
the form Major#:Minor#, where Major# is the number of the major version and Minor# is the
number of the minor version. Changes in the major version number indicate that the structure
of the case data has changed (for example, variables or categories have been added or deleted)
whereas changes in the minor version number indicate that the changes affect the metadata only
(for example, a question text has been changed). This means that it is generally safe to export data
collected using a major version and all of its associated minor versions simultaneously.
Note: Version names are created automatically when a version is locked. A version that has not
been locked is always called LATEST.
Specifying a metadata version to use. You specify the version of the metadata to be used in
the transfer using the MR Init MDM Version connection property in the connection string in
the InputDataSource section. If you are using the Data Link Properties dialog box to set up
the connection string (for example, because you are using the Connection String Builder or
WinDMSRun) click the Properties button in the Metadata section on the Connection tab. This
opens the Metadata Properties dialog box, in which you can select the version you want to use
from the Version drop-down list box.
362
Chapter 1
Note that when you select a specific version for the transfer, the output metadata will be based on
that version only and will not contain the previous versions. When you do not specify a version to
use, the most recent version of the metadata is automatically used and the output metadata will
contain all of the versions that exist in the input metadata.
Filtering on a specific version. When you want to restrict a transfer to case data records
that were collected using a specific version of the metadata, you filter using the
DataCollection.MetadataVersionNumber . You can include the case data for a major version and
all of its minor versions by using the LIKE keyword and the % wildcard character.
Example
This example selects version 2 of the metadata and case data collected with this version and all
of its minor versions. (Note that the Short Drinks sample doesn’t actually contain any minor
versions.)
MR Init MDM Version=2; _
WHERE (DataCollection.MetadataVersionNumber ='2' _
OR DataCollection.MetadataVersionNumber LIKE '2:%') _
AND (ContainsAny(DataCollection.Status, {completed})) _
End InputDatasource
Note: This example is included in the mrInterviewOneVersionToSav.dms sample that comes with
the IBM® SPSS® Data Collection Developer Library. For more information, see the topic Sample
DMS Files For Exporting IBM SPSS Data Collection Interviewer Server Data on p. 473.
Selecting Multiple Versions
You can select multiple versions of the metadata to be used and as we saw in Selecting a Specific
Version, it is easy to set up a filter to restrict the transfer to records that were collected using
the corresponding versions.
Specifying multiple metadata versions. You specify multiple versions of the metadata to be used in
the transfer by using a version expression for the MR Init MDM Version connection property in the
connection string in the InputDataSource section. The version expression also determines the order
of priority to be used when, for example, texts in one version conflict with those in another verison.
363
Base Professional
If you are using the Data Link Properties dialog box to set up the connection string (for example,
because you are using the Connection String Builder or WinDMSRun) click the Properties button
in the Metadata section on the Connection tab. This opens the Metadata Properties dialog box, in
which you can select the version or versions you want to use from the Version drop-down list box.
For more information, see the topic WinDMSRun Window: Selecting Versions on p. 303.
Note that when you select multiple versions for the transfer, the output metadata will be based on
the combined versions only and will not contain the individual versions.
If you want to restrict the transfer to case data records that were collected using one or more
specific versions of the metadata, filter using the DataCollection.MetadataVersionNumber . You
can include the case data for a major version and all of its minor versions by using the LIKE
keyword and the % wildcard character.
Examples
1. Selecting all versions
This example selects all versions of the metadata and does not filter the case data.
MR Init MDM Version={..}; _
WHERE (ContainsAny(DataCollection.Status, {completed})) _
End InputDatasource
Note: This example is included in the mrInterviewAllVersionsToSav.dms sample that comes with
the IBM® SPSS® Data Collection Developer Library. For more information, see the topic Sample
DMS Files For Exporting IBM SPSS Data Collection Interviewer Server Data on p. 473.
2. Selecting two specific versions
This example selects two specific versions of the metadata and case data collected with the same
versions and any related minor versions. (Note that the Short Drinks sample doesn’t actually
contain any minor versions.)
364
Chapter 1
MR Init MDM Version={2,5}; _
SelectQuery = "SELECT Respondent.Serial, age, gender, sclass, occup FROM vdata _
WHERE (DataCollection.MetadataVersionNumber ='2' _
OR DataCollection.MetadataVersionNumber LIKE '2:%' _
OR DataCollection.MetadataVersionNumber ='5' _
OR DataCollection.MetadataVersionNumber LIKE '5:%') _
AND ContainsAny(DataCollection.Status, {completed}) _
End InputDatasource
Note: This example is included in the mrInterviewMultipleVersionsToSav.dms sample that comes

Files For Exporting IBM SPSS Data Collection Interviewer Server Data on p. 473.
Listing and Comparing Versions
The IBM® SPSS® Data Collection Developer Library comes with some useful mrScriptBasic
samples for use when working with multiversion projects:
ListVersions.mrs. This iterates through the versions in a named MDM Document, writing the
name of each version to a text file.
CompareVersions.mrs. This can be used to do a limited comparison of two or more versions of

the metadata. The comparison is designed to detect whether the version changes mean that cases
collected using one or more versions can be safely exported using another (typically later) version.
At the top of the sample you specify the metadata file to be used and two or more of its major
versions to be the “case data” versions and one version to be the “metadata” version. Categories
and variables that appear in the designated “case data” versions but that are not in the designated
“metadata” version are listed on the screen.
Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Quantum
Exporting IBM® SPSS® Data Collection Interviewer Server data to IBM® SPSS® Quantum™
is not different from other exports to Quantum, in that in order for the export to succeed, valid
card, column, and punch definitions must be available in the output metadata. However, there
are a number of considerations that you need to take into account when you export an active
Interviewer Server project’s data to Quantum.
There are two alternative ways of setting up card, column, and punch definitions:
Using the Metadata Model to Quantum accessory. Use IBM® SPSS® Data Collection Metadata
Model to Quantum on the .mdd file in the FMRoot\Shared folder. Generally, you should set up
the card, column, and punch definitions for the variables in each version before it is activated.
Typically you would then run your export on the .mdd file in the FMRoot\Shared folder. If
365
Base Professional
you use this method, you should ensure that your DMS files do not clear the definitions that
have already been set up. Note that some of the sample DMS files do this, so if you want to
use these samples, you need to amend them before you run them.
Using the Metadata Model to Quantum component in your DMS file. The advantage of setting
up your card, column, and punch definitions in your DMS file is that you can set up the
definitions and run the export in one step and setting up the definitions is largely invisible.
Most of the samples assume that you are using this method.
Whichever method you use, there are a number of considerations when you export data from a
multiversion project. This is particularly true if you want to store the data for all versions in the
same .dat file, because you need to ensure that the layout of the data created by all versions
is compatible.
You can export data for all versions of a multiversion project after all of the data has been collected,
by selecting all versions of the metadata. For more information, see the topic Exporting IBM SPSS
Data Collection Interviewer Server Data to IBM SPSS Quantum Using All Versions on p. 365.
However, in a large or ongoing project, you may want to export data in batches, for example on a
daily basis. The IBM® SPSS® Data Collection Developer Library comes with some samples that
you can use to do this. For more information, see the topic Exporting Batches of IBM SPSS Data
Collection Interviewer Server Data to IBM SPSS Quantum on p. 367.
For information on creating the Quantum specification, see Creating the IBM SPSS Quantum
Specification.
Note: If you export the same records to the same .dat file two or more times, the new records are
appended to the end of the file and the existing records are not updated. You should therefore
be careful not to create duplicate records in the .dat file by exporting the same case data to it
more than once.
Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Quantum Using All
Versions
It is easy to export data for all versions at the end of your project. You simply
select all of the versions of the metadata and export all of the data in one run. The
mrInterviewAllVersionsToQuantum.dms sample has been designed to cater for this scenario and
does the following:
1. Opens all versions of the .mdd file.
2. Calls the MDM2Quantum.ClearCardColPunch method to clear any existing card, column, and
punch definitions. You should remove this line if you want to retain any card, column, and punch
definitions that you have already set up, for example, using the IBM® SPSS® Data Collection
Metadata Model to Quantum accessory.
366
Chapter 1
3. Sets the Metadata Model to Quantum properties to use the standard IBM® SPSS® Quantum™
setting of multiple cards with 80 columns. You should remove these lines if you want to use a
single card of unlimited length or have already set up your card, column, and punch definitions,
for example, using the Metadata Model to Quantum accessory.
4. Sets the MDM2Quantum.SpareColumns property to 2. This means that two extra columns will
be allocated to each categorical variable to allow for the addition of extra categories. This is not
necessary if you are using this DMS file to export the data after all data collection has finished.
However, it is useful if you are running the export part way through the collection process and
want to allow space for categories being added in later versions.
5. Note that there are a number of other properties of the object that correspond to preferences
you can set in the Metadata Model to Quantum accessory (such as, ExplodeMultiPunch,
CodesOnSeparateCard, OtherCodesOnSeparateCard, and AllocateSystemVariables). If you want
to use any of these properties, you should set them before the call to the AllocateCardColPunch
method.
6. Calls the MDM2Quantum.AllocateCardColPunch method with the MoveToEnd parameter set

to True. This allocates card, column, and punch definitions to all of the variables in the document.
7. Uses the FileSystemObject to create a new folder for the output, if it does not already exist.
This is a useful technique to help make sure that the Quantum specification files do not overwrite
those from a different data set. Although most of the specification filenames are based on the name
supplied in the script, the names of the include files created for numeric grids are based on the
axis names. This means that these files may be overwritten if there are any numeric grids with
the same name in the two data sets.
8. Writes out a basic Quantum specification based on the card, column, and punch definitions.
9. Exports all non-test data that has the Completed status to a Quantum .dat file.
Notes
Note that this sample does not save the output metadata. Saving the output metadata can take
a considerable amount of time in a large project and it is not generally necessary when using
this sample because the card, column, and punch definitions are set up in the input .mdd file
in the OnBeforeJobStart Event section. However, if you want to save the output metadata,
simply add the MetaDataOutputName parameter to the OutputDataSource Section.
This sample is designed to be run once, typically at the end of a project. If you want to use this
sample to export data part way through a project and you want to export data to the same .dat
file later in the project, this sample would be suitable for the first export, but not for subseqent
ones. However, you could amend the OnBeforeJobStart Event section to remove the line
that clears the existing card, column, and punch definitions and set the Metadata Model to
Quantum properties (points 2 through 5 in the list above) before running it again.
The mrInterviewAllVersionsToQuantum.dms sample DMS file is installed with the IBM®
SPSS® Data Collection Developer Library. For more information, see the topic Sample DMS
Files For Exporting IBM SPSS Data Collection Interviewer Server Data on p. 473.
367
Base Professional
Exporting Batches of IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Quantum
In an ongoing project, you may want to export data in batches. For example, at the end of
each day you may want to export all of the data collected since the end of the previous day,
and you may want to export the batches of data to the same .dat file. The IBM® SPSS®
Data Collection Developer Library comes with two sample DMS files that are designed to
enable you to do this. The samples are called mrInterviewFirstBatchToQuantum.dms and
mrInterviewNextBatchToQuantum.dms and are designed for use in a multiversion project. These
files open all versions of the metadata, which means that they can handle most version changes.
However, there are some version changes that will require special handling, but this is described
below.
The sample mrInterviewFirstBatchToQuantum.dms transfers the current IBM® SPSS® Data

Collection Interviewer Server data to a new IBM® SPSS® Quantum™ .dat file. The second
sample (mrInterviewNextBatchToQuantum.dms) uses the read capability of the Quantum
data source component (DSC) to find the existing case on the Quantum .dat file that has
the latest interview finish date and time (by reference to the value of the system variable
DataCollection.FinishTime). Only those cases that have a later interview finish time than this are
then exported from Interviewer Server to the .dat file.
Only the first file (mrInterviewFirstBatchToQuantum.dms) includes code to create a Quantum

specification, on the assumption that you will probably want to start editing your Quantum
specification right after running the first transfer. When there is a change in the data map in
subsequent exports, you will need to change the specification manually. However, you can use the
.csv file created by the subsequent transfers to get information on the changes to the data map
that you need to manually incorporate into the specification. For more information, see the topic
Creating the IBM SPSS Quantum Specification on p. 368.
Note that neither of these samples saves the output metadata. Saving the output metadata can
take a considerable amount of time in a large project and is generally not necessary when using
these samples because the card, column, and punch definitions are set up in the input .mdd
file. However, if you want to save the output metadata, simply add the MetaDataOutputName
parameter to the OutputDataSource Section.
mrInterviewFirstBatchToQuantum.dms. You use this sample when you export the first batch to
Quantum. It does the following:
In the OnBeforeJobStart Event section it opens all versions of the input metadata, clears
existing card, column, and punch definitions, sets up new ones, and writes the Quantum
specification. The code used is similar to the card column-related code described in Exporting
IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Quantum Using All
Versions.
Exports all non-test data that has the Completed status to a Quantum .dat file.
368
Chapter 1
mrInterviewNextBatchToQuantum.dms. You use this sample to export the second and subsequent
batches to Quantum. It does the following:
In the OnBeforeJobStart Event section, it opens all versions of the input metadata and allocates
card, column, and punch definitions to any variables and categories that do not have them
already, and writes the card, column, and punch definitions to a .csv file.
Exports to a Quantum .dat file all non-test data that has the Completed status and an interview
finish time that is later than the latest case already on the .dat file.
Note that this sample will fail if you run it before running the
mrInterviewFirstBatchToQuantum.dms file. In addition, this sample will not transfer any
records if you run it immediately after running mrInterviewFirstBatchToQuantum.dms without
collecting any additional data in between.
Exporting batches when there have been version changes
Both of the samples described in this topic use all versions of the metadata. This means that the
samples can handle most changes to the data layout. The main potential problem area is likely to
be if you add large numbers of categories to an existing variable. If you add more categories to
a variable than can be accommodated in the spare columns that are available, the variable will
be moved to the last card so that additional columns can be allocated. If this happens it would
mean that in earlier records in the .dat file the variable would be stored using different columns
and you would need to handle this appropriately in Quantum. Note that this is likely to happen
when you add categories to a multiple response variable and are using the explode multipunch
option because each category is assigned a separate column.
Note: The mrInterviewFirstBatchToQuantum.dms and mrInterviewNextBatchToQuantum.dms

sample DMS files are installed with the Data Collection Developer Library. For more information,
see the topic Sample DMS Files For Exporting IBM SPSS Data Collection Interviewer Server
Data on p. 473.
Creating the IBM SPSS Quantum Specification
You can use the MDSC capability of the IBM® SPSS® Quantum™ DSC to create a Quantum
specification based on the card, column, and punch definitions in the metadata. Typically you
would include the code in the Event section in which you set up the card, column, and punch
definitions.
For an example of creating the Quantum specification in the OnBeforeJobStart Event section,
see OnBeforeJobStart Event Section.
For an example of creating the Quantum specification in the OnAfterMetadataTransformation
Event section, see OnAfterMetaDataTransformation Event Section.
For information about the Quantum specification, see .
For an example of using the Use Short Names option, see .
369
Base Professional
Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Statistics
Exporting IBM® SPSS® Data Collection Interviewer Server data to an IBM® SPSS® Statistics
.sav file is not fundamentally different from other exports to a .sav file. However, there are a
number of things you need to aware of when working with data collected using multiple versions.
Multiple exports to the same .sav file. There are a number of restrictions on running multiple
exports to the same .sav file:
The structure of the input metadata in the second and subsequent exports must exactly
match the structure of the input metadata used for the first export. Even a small change in
the input metadata, like the addition of a single category, may make the next export fail. In
practical terms this generally means that you must export the data collected with each major
version to a different .sav file or you must use the same set of versions for the export. The
IBM® SPSS® Data Collection Developer Library comes with sample .mrs files for listing
and comparing the versions in an .mdd file. For more information, see the topic Listing
and Comparing Versions on p. 364.
When exporting batches of data to the same .sav file, you need to use the output metadata
from the first export as the input metadata for the second and subsequent exports.
If you specify a subset of the variables to transfer, you must specify exactly the same set of
variables for all of the transfers to the same .sav file.
If you export the same records to the same .sav file two or more times, the new records are
appended to the end of the file and the existing records are not updated. You should therefore
be careful not to create duplicate records in the .sav file by exporting the same case data
to it more than once.
Using the same alias names as a previous export. When there is a version change and you start
exporting to a new .sav file, you may want as far as possible to use the same alias names in the
new .sav file variables as used in the previous one. Doing this requires a special type of merge
of the newest version in the project’s .mdd file with the metadata used for the previous version’s
exports. See the mrInterviewNextBatchNewVersionToSav.dms sample for an example of doing
this. For more information, see the topic Sample DMS Files For Exporting IBM SPSS Data
Collection Interviewer Server Data on p. 473.
Exporting all data at the end of a project. In a multiversion project, you can export data for all
versions after all of the data has been collected using all of the versions. For more information, see
the topic Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Statistics
Using All Versions on p. 370.
Exporting batches of data. In a large or ongoing project, you may want to export data in batches,
for example on a daily basis. The Data Collection Developer Library comes with some samples
that you can use to do this. For more information, see the topic Exporting Batches of IBM SPSS
Data Collection Interviewer Server Data to IBM SPSS Statistics on p. 370.
370
Chapter 1
Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Statistics Using All
Versions
If you want to export data for all versions to IBM® SPSS® Statistics at the end of your project,
you can simply select all versions of the metadata and export all of the data in one run. The
mrInterviewAllVersionsToSav.dms sample has been designed to cater for this scenario.
mrInterviewAllVersionsToSav.dms. This sample does the following:

In the OnBeforeJobStart Event section, it writes out the highest version number for future
reference.
Selects all versions of the metadata for the export.
Exports all non-test data that has the Completed status to SPSS Statistics .sav file.
Saves the output metadata.
This sample is designed to be run once, typically at the end of a project. However, you could use
this sample to export data part way through a project and then use it again after collecting more
data if there have been no version changes. You would need to change the InputDataSource
section to use the output metadata from the previous export and remove the metadata version
selection from the InputDataSource section. If there have been version changes, you would need
to start a new .sav file. If you want to reuse the same alias names wherever possible use the
mrInterviewMoreVersionsToSav.dms sample for the second export.
mrInterviewMoreVersionsToSav.dms. This sample is designed to be run after

mrInterviewAllVersionsToSav.dms and after additional versions have been created in the metadata.
mrInterviewMoreVersionsToSav.dms creates a new .mdd file for the export by merging in all
versions of the project’s metadata into the output metadata from mrInterviewAllVersionsToSav.dms.
This means that wherever possible the alias names are reused. The sample does not filter the case
data according to whether it has already been transferred. However, you could easily modify it to
do so using a similar method to that used in the batch export samples.
This sample also writes the highest version number used to a text file for future reference.
If you use this sample more than once, you need to amend it before running it the second and
subsequent times to use the output .mdd file from the previous run.
Note: The mrInterviewAllVersionsToSav.dms and mrInterviewMoreVersionsToSav.dms sample

DMS files are installed with the IBM® SPSS® Data Collection Developer Library. For
Exporting Batches of IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Statistics
In an ongoing project, you may want to export data in batches. For example, at the end of each
day you may want to export all of the data collected since the end of the previous day. The
IBM® SPSS® Data Collection Developer Library comes with three sample DMS files that are
designed to enable you to do this. The samples are called mrInterviewFirstBatchToSav.dms,
mrInterviewNextBatchToSav.dms, and mrInterviewNextBatchNewVersionToSav.dms and are
371
Base Professional
designed for use in a multiversion project. There are some version changes that will require
special handling, but this is described below.
The sample mrInterviewFirstBatchToSav.dms transfers the current IBM® SPSS® Data

Collection Interviewer Server data to a new IBM® SPSS® Statistics .sav file. The two samples
mrInterviewNextBatchToSav.dms and mrInterviewNextBatchNewVersionToSav.dms use the read
capability of the SPSS Statistics SAV data source component (DSC) to find the existing case on
the SPSS Statistics .sav file that has the latest interview finish date and time (by reference to the
value of the system variable DataCollection.FinishTime). Only those cases that have a later
interview finish time than this are then exported from Interviewer Server to the .sav file.
mrInterviewFirstBatchToSav.dms. Use this sample to export the first batch to SPSS Statistics. It
does the following:
Exports all non-test data that has the Completed status to a new SPSS Statistics .sav file.
Saves the output metadata.
mrInterviewNextBatchToSav.dms. Use this sample to export the second and subsequent batches
to SPSS Statistics when there has been no change to the metadata since the last batch export. It
does the following:
Uses the output metadata created by running the mrInterviewFirstBatchToSav.dms file as
the input metadata for the export.
Exports to a new SPSS Statistics .sav file all non-test data that has the Completed status and an
interview finish time that is later than the latest case already on the .sav file.
This sample does not save the output metadata. This sample is designed to be run when there
has been no change in the metadata since the previous batch export. Therefore there is no
need to save the output metadata.
Note that this sample will fail if you run it before running the mrInterviewFirstBatchToSav.dms
file. In addition, this sample will not transfer any records if you run it immediately after running
mrInterviewFirstBatchToSav.dms without collecting any additional data in between.
mrInterviewNextBatchNewVersionToSav.dms. Use this sample to export the first batch after there
has been a major version change. It does the following:
In the OnBeforeJobStart Event section, it extracts the most recent version of the project’s .mdd
file and merges it with the output metadata file used for the previous exports so that the alias
names used for the previous exports will be reused wherever possible.
Exports to a new SPSS Statistics .sav file all non-test data that has the Completed status and an
interview finish time that is later than the latest case already on the .sav file.
Saves a new output metadata file.
Note that additional versions are created in the output metadata file with the result that the versions
in the output metadata file will not match the versions in the project’s main .mdd file. Therefore
the version names stored in the case data in the DataCollection.MetadataVersionNumber variable
will not correspond to the versions of the same name in the output metadata file. However, this
should not present a problem when using the output metadata file for subsequent exports.
372
Chapter 1
Note that you should use this sample once each time you export the data using a new version. You
should then use the mrInterviewNextBatchToSav.dms file for subsequent exports using that version
until the version changes again. However, before running the mrInterviewNextBatchToSav.dmsfile,
you will need to amend the name of the input .sav and .mdd files to reflect the name of those
created by mrInterviewNextBatchNewVersionToSav.dms.
Note that if you have amended the samples to include only a subset of variables
and the version changes do not affect these variables, you would not need to run the
mrInterviewNextBatchNewVersionToSav.dms file nor make the adjustments described below.
When a batch includes data collected using two major versions. You would need to adjust the
process as follows:
E Take a backup copy of mrInterviewNextBatchToSav.dms.
E Change the InputDataSource section in mrInterviewNextBatchToSav.dms so that it selects the

earlier version of the metadata and change the WHERE clause to additionally restrict the transfer
to data that was collected using the earlier version. For example:
Initial Catalog=" + InputMDDFile + "; _
MR Init MDM Version=7; _
WHERE (DataCollection.FinishTime > '@LastFinishTime') _
AND (ContainsAny(DataCollection.Status, {completed})) _
AND (DataCollection.MetadataVersionNumber = '7') _
End InputDatasource
E Run the modified version of mrInterviewNextBatchToSav.dms.
E Run mrInterviewNextBatchNewVersionToSav.dms to transfer records from the later version.
E Restore the backed up copy of mrInterviewNextBatchToSav.dms.
Note: The mrInterviewFirstBatchToSav.dms, mrInterviewNextBatchToSav.dms and

mrInterviewNextBatchNewVersionToSav.dms sample DMS files are installed with the Data
Collection Developer Library. For more information, see the topic Sample DMS Files For
Exporting IBM SPSS Data Collection Interviewer Server Data on p. 473.
373
Base Professional
Exporting IBM SPSS Data Collection Interviewer Server Data to RDB and IBM SPSS Data
Collection Data File
In a large or ongoing project you may want to store completed data separately from the live
database. For example, you may want to store the data separately while you are cleaning it and
setting up weighting, etc. The relational MR (RDB) database and IBM SPSS Data Collection
Data File formats are particularly suitable for this purpose because they support updating the
data. For example, you can transfer the data to the new database or IBM SPSS Data Collection
Data File (.ddf) and then use the UseInputAsOutput option when you subsequently clean the
data and set up weighting.
Exporting IBM® SPSS® Data Collection Interviewer Server data to another RDB database
or to a IBM SPSS Data Collection Data File is more straightforward than exporting to IBM®
SPSS® Quantum™ and IBM® SPSS® Statistics because there are no card, column or alias name
issues to consider. In addition, the RDB and IBM SPSS Data Collection Data File formats can
handle changes in the structure of the data, provided there are no changes to the data types of any
variables. However, you need to be aware of the version issues described in Understanding
Versions.
If you want to export batches of Interviewer Server data to RDB or a IBM SPSS Data Collection
Data File, there is no need to use a separate XML file to store the date and time of the last
interview in the batch. Provided you include the DataCollection.FinishTime variable in the export,
you can use that as a global SQL variable, as shown in the examples in the GlobalSQLVariables
Section topic.
Merging Case Data

Merging is the process by which the case data from two or more data sources are combined into a
single data source. Merging is typically used after the case data has been collected and before
the analysis stage of the survey takes place. The following situations are examples of when
you might want to carry out a merge:
Your organization has carried out a survey from several different offices, and each office has
collected the case data in separate data sources.
Your organization has carried out a panel survey and collected the case data for each wave
in separate data sources.
You have been asked to combine supplementary data with your case data.
You have extracted all of the open-ended responses from your case data for coding, and you
now wish to combine the coded responses with your original case data.
The Different Types of Merge
You can use Data Management Scripting to run two different types of case data merge:
In a vertical merge, the cases from the second and subsequent data sources are added after the
cases from the first data source. You would typically use a vertical merge to combine case
data sources that have mostly the same variables but contain data for different respondents.
374
Chapter 1
In a horizontal merge, the variables from all of the case data sources are combined into a
single case. You would typically use a horizontal merge to combine case data sources that
have different variables but contain data for mostly the same respondents.
In This Section
This section includes topics that describe how the two different types of merge work and how
you can run a merge using a data management (DMS) script.
How a Vertical Merge Works
How a Horizontal Merge Works
How Merge Deals with Metadata Conflicts
Using a DMS Script to Merge Data
Running a Vertical Merge
Running a Horizontal Merge
Examples of Merging Case Data, which includes examples of merging Japanese (multibyte)
data sources.
How a Vertical Merge Works
In a vertical merge, the case data in each input data source is written in its entirety to the output
data. The case data for the first data source is written first, followed by the case data for the
second and any subsequent input data sources.
375
Base Professional
The following diagram shows a vertical merge of two simple input data sources. Note that the first
data source is known as the master data source:
The first thing to note is that the merge has resulted in the merging of the input metadata
documents. Therefore, the output metadata and the output case data contain all of the variable
names from both input metadata documents. Nulls have been inserted into the output case data
for those variables that did not exist in the input data source.
The second thing to note that the output case data contains duplicate values for the system
variable, Respondent.Serial. This may cause a problem when using output data sources, such as
the Relational MR Database DSC, that do not allow duplicate serial numbers. Ways in which you
can avoid this problem are described later in Running a Vertical Merge.
How a Horizontal Merge Works
A horizontal merge combines the variables from cases in two or more input data sources into a
single case, which is then written to the output data. Cases are combined (or “joined”) only when
they have the same value in their key fields. You define the key field for each input data source in
the data management (DMS) script that will be used to run the merge.
The default type of horizontal merge, known as a “full” horizontal merge, will also write to the
output data any cases that have not been joined. This ensures that all cases on all input data
sources are written to the output data. Data management scripting also supports other types of
horizontal merge, but these are typically used less often as they may result in some cases not
being written to the output data. The different types of horizontal merge are described later in
Running a Horizontal Merge.
376
Chapter 1
The following diagram shows a full horizontal merge of two simple input data sources that are
being joined using the system variable, Respondent.Serial. Note that the first data source is
known as the master data source:
The above example illustrates several features of a horizontal merge:

The merge has resulted in the merging of the input metadata documents. Therefore, the
output metadata and the output case data contain all of the variable names from both input
metadata documents.
Because cases exist for respondents 1, 2, and 4 on both input data sources, the data for each of
those respondents have been combined in the output data.
When case data are combined from data sources that have identical variable names, the data
from the source that is higher in the order of the data sources takes precedence. This applies
even when the value of the data taking precedence is a null or an empty categorical value. In
the above example, Question3 exists on both input data sources. So for respondents 1, 2, and
4, the value of Question3 from the master data source is written to the output data.
As a result of the previous rule, case data for Question3 in the second input data source
has been dropped—in other words, that data has not been written to the output data for
respondents 1, 2, and 4. For this reason, horizontal merges are typically used to merge only
data sources that contain different variable names.
Note that the cases for respondents 3 and 5 have also been written to the output data. This is a
feature of a full horizontal merge—other types of horizontal merges would have dropped one or
both of those cases. For those two cases, nulls have been inserted in the output case data for those
variables that did not exist in the input data source.
377
Base Professional
How Merge Deals with Metadata Conflicts
When a merge is run, conflicts can occur when two or more input data sources contain a variable
with the same name but a different data type, or a different set of categories, or some other
difference in the metadata for the variable. This topic explains how merge deals with those types
of conflicts.
The following diagram shows a vertical merge of two simple input data sources with identical
variable names. However, note that there are differences in the category lists for Question1, and
that the data type for Question2 is also different.
When variables have the same name but different data types, the data type defined in the source
that is higher in the order of the data sources takes precedence. In the output case data, the variable
will then be set to null for all cases from subsequent input data sources that have a different data
type. Therefore, in the above example, Question2 has been set to null for all cases from the second
input data source. Note that conflicts of this type are not reported when a data management (DMS)
script is run in IBM® SPSS® Data Collection Base Professional.
Because the output metadata is the result of merging all input metadata documents, the output
metadata for a categorical variable will include all of the categories from input data sources
that have a categorical variable of the same name. Therefore, in the above example, the output
metadata for Question2 includes all of the categories from both input data sources.
378
Chapter 1
Variables with Different Range Expressions
If two or more variables have the same name and data type but different ranges, the range in the
output metadata will, if possible, consist of the lowest and highest values across all of the input
ranges. For example, if the input ranges are [1 .. 1] and [3 .. 4], the output range will be [1 .. 4].
Note that 2 is now a valid range value although it wasn’t valid in either of the input data sources.
Using a DMS Script to Merge Data
To merge data using a data management (DMS) script, you need to specify the files that you want
to merge and the type of merge that you want to run.
Specifying the Files That You Want to Merge
To specify the case data files that you want to merge, add an InputDataSource Section to your
DMS script for each case data file. Therefore, if you want to merge three case data files, you will
need to add three InputDataSource sections. You will also need to add an OutputDataSource
Section to your DMS script to specify the data source that your merged data will be output to.
Before writing the InputDataSource sections, note the following:

The first InputDataSource section defines the master data source, the second InputDataSource
section defines the second data source, and so on.
The master data source must use the IBM SPSS Data Collection OLE DB Provider and must
include a metadata source. This can be either a metadata document (.mdd) file or a proprietary
metadata file for which a read-enabled MDSC is available.
All input data sources will be opened with the value of the MR Init Category Names
connection property automatically set to 1. This means that category names will be read from
the input data sources instead of category values. This is done because the same category
value could have been assigned to a different category name in each data source.
By default, the most recent versions of the input metadata sources will be merged. However, if
an input metadata source contains multiple versions, you can specify a version or combination
of versions to be input to the merge by setting the MR Init MDM Version connection property
in the relevant InputDataSource section.
You can specify the UseInputAsOutput option in one of the InputDataSource sections, in
which case you do not need an OutputDataSource section in your DMS script. If you are
using the IBM® SPSS® Data Collection Data Model to read the case data, you can specify
the UseInputAsOutput option only if the CDSC for that data source supports the updating
of existing records. You must also set the MR Init MDM Access connection property to 1 in
the InputDataSource section to open the data source for read/write access or when operating
in validation mode.
When you use the UseInputAsOutput option, the version history in the input metadata will
be preserved only if, by default, you are using the most recent version. A new unlocked
version will be created if the most recent version is locked. However, if you specify one or
more versions using the MR Init MDM Version connection property in the InputDataSource
section, the version history will be deleted.
379
Base Professional
Note: You can use a select query that returns no records (for example, ‘select * from vdata where
false') to avoid processing case data for the UseInputAsOutput data source. This is useful when
merging new case data to an existing dataset.
Warning: The UseInputAsOutput option should always be used with caution because it will
change the metadata and case data irreversibly for that data source. It is not suitable for
use with data that is in the process of the being collected by a live IBM® SPSS® Data
Collection Interviewer Server project. It is recommended that you take a backup of your data
before using this option.
Before writing the OutputDataSource section, note the following:

The output metadata will not contain any versions, even if one or more input metadata
sources contains versions.
You cannot write case data to any of the Microsoft Office file formats when running a merge.
Future versions of IBM® SPSS® Data Collection Base Professional may support those
file formats.
Specifying the Type of Merge that you want to Run
To specify that you want to run a horizontal merge, add a JoinKey parameter to every
InputDataSource section in your DMS script. For more information, see the topic Running a
Horizontal Merge on p. 381.
If you do not have any JoinKey parameters in your InputDataSource sections, a vertical merge
will take place by default. For more information, see the topic Running a Vertical Merge on p. 379.
Running a Vertical Merge
If you do not have any JoinKey parameters in your InputDataSource sections, a vertical merge
will take place when you run your data management (DMS) script.
The DMS script does not automatically renumber Respondent.Serial when writing cases to the
output data. Therefore, all cases from all input data sources will retain their original values of
Respondent.Serial, which may result in duplicate values. This may cause a problem when using
output data sources, such as the Relational MR Database DSC, that do not allow duplicate serial
numbers. In addition, once the merge is complete, it may be difficult to identify which cases
originated from which data source.
You can avoid these problems by using either of the following approaches:
Create a new value for Respondent.Serial as each case is written to the output data. Typically,
you would start with a value of one and increase the value by one for each case.
Allocate values for Respondent.Serial in unique ranges depending on the input data source.
For example, the cases from your master data source might be allocated values from 1 to
1,000; the cases from your second input data source might be allocated values from 1,001
to 2,000; and so on.
380
Chapter 1
Regardless of which approach you use, you might also want to add new variables to the output
metadata, so that for each case you can store the original value of Respondent.Serial and other
information about the input data source.
These approaches are described in more detail below.
Creating New Values for Respondent.Serial
The following example makes use of both the Metadata section and the OnNextCase event section
of a DMS script.
Two new variables are defined in the Metadata section to store the original value of
Respondent.Serial and the name of the office that collected the input data.
In the OnNextCase event section, the original value of Respondent.Serial is assigned to the first
new variable, and the OutputCaseNumber property of the dmgrJob object is used to create a new
a value for Respondent.Serial. The CurrentInputDataSource property of the dmgrJob object is
then used to identify the input data source, and the relevant office name is stored in the second
new variable.
Metadata (ENU, Question, Label, myMasterDataSource)
OriginalRespondentSerial long;
OriginatingOffice text [10];
End Metadata
Event (OnNextCase, "Create new Respondent.Serial")
OriginalRespondentSerial = Respondent.Serial
Respondent.Serial = dmgrJob.OutputCaseNumber
Select Case (dmgrJob.CurrentInputDataSource)

Case 0 ' Master data source
OriginatingOffice = "Paris"
Case 1 ' Second input data source
OriginatingOffice = "London"
Case 2 ' Third input data source
OriginatingOffice = "Berlin"
End Select
End Event
Of course, you could store other information about the input data source if you wanted to, such as
the name of the input file.
381
Base Professional
Allocating Respondent.Serial in Ranges
The following example makes use of the OnNextCase event section of a DMS script. The
CurrentInputDataSource property of the dmgrJob object is used to identify the input data source.
An offset value is then added to the original value of Respondent.Serial to create a number within
a unique range for each input data source.
Event (OnNextCase, "Reallocate Respondent.Serial")
Dim myOffset

myOffset = 0
myOffset = 10000
myOffset = 20000
End Select
Respondent.Serial = Respondent.Serial + myOffset
End Event
A more succinct version of the same example is shown below.
Event (OnNextCase, "Reallocate Respondent.Serial")
Respondent.Serial = _
Respondent.Serial + _
(dmgrJob.CurrentInputDataSource * 10000)
End Event
For these above example to work successfully, none of the cases in the input data sources should
have a value of Respondent.Serial greater than 9999. If your input data files contain cases that
have higher values than this, you must specify larger offset values.
Running a Horizontal Merge
To specify that you want to run a horizontal merge, do the following:

Add a JoinKey parameter to every InputDataSource section in your data management (DMS)
script. The JoinKey parameter defines the variable that will be used to join the data source
to the other input data sources. Typically, Respondent.Serial will be used, but you can
specify other variables or even specify different variables for different input data sources.
However, the variable that is specified must always contain a unique value for each case
in the data source.
Add a JoinType parameter to the InputDataSource section for the master data source.
382
Chapter 1
The valid values for JoinType are described in the following table:
Value of JoinType Description
Full All cases on all input data sources are written to the
output data. Cases with identical JoinKey values
are combined before writing. This is the default
behavior if JoinType is not specified.
Inner Only cases with identical JoinKey values on all
input data sources are written to the output data.
The cases will be combined before writing.
Left Only cases with JoinKey values that exist in the
master data source are written to the output data.
Cases with identical JoinKey values are combined
before writing.
Typically, you will use a full join for most of your horizontal merges, as it is the only type of join
that ensures that all cases in all input data sources will be written to the output data.
Improving the Performance of a Horizontal Merge
By default, a horizontal merge sorts each input data source by the variable defined in its JoinKey
parameter before joining the data sources. If you a merging one or more large data sources that are
already sorted in the correct order, you can improve the performance of the merge by specifying
that a data source does not need to be sorted. To do this, add a JoinKeySorted parameter to every
InputDataSource section that does not need to be sorted and set the value of the parameter to True.
In the follow example, the inclusion of JoinKeySorted = True implies that the data source is
already sorted in SerialNumber order and specifies that it must not be sorted:
JoinKey = "SerialNumber"
JoinKeySorted = True
Example
The following example contains two InputDataSource sections that define a IBM SPSS Data
Collection Data File and a IBM® SPSS® Statistics SAV file that will be horizontally merged.
The two data sources will be joined using the Respondent.Serial system variable on the IBM SPSS
Data Collection Data File and the SerialNo variable on the SPSS Statistics SAV file. A full join
will be carried out, meaning that all of the cases on both data sources will be written to the output
data. The JoinKeySorted parameter is included for the second data source to define that the SPSS
Statistics SAV file is already sorted in SerialNo order and must not be sorted.
Data Source = mrDataFileDsc; _
Location = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeMaster.ddf; _
Initial Catalog = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeMaster.mdd;"
JoinKey = "Respondent.Serial"
383
Base Professional
JoinType = "Full"
End InputDatasource
InputDatasource(mySecondInputDataSource)
Data Source = mrSavDsc; _
Location = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Sav\MergeSecond.sav; _
Initial Catalog = [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Sav\MergeSecond.mdd;"
JoinKey = "SerialNo"
JoinKeySorted = True
End InputDatasource
Note that because a full join will run by default, JoinType = "Full" can be omitted.
Examples of Merging Case Data
Example of a Vertical Merge
This example is provided as a sample data management script file called MergeVertical.dms, which
is installed with the IBM® SPSS® Data Collection Developer Library. For more information, see
the topic Samples on p. 466.
Note that there are three InputDataSource sections, which do not contain any JoinKey parameters.
(If they did, a horizontal merge would run instead of a vertical merge.) When the script is run, the
three input IBM SPSS Data Collection Data Files will be merged into a single IBM SPSS Data
Collection Data File called MergeVerticalOutput.ddf.
'==========================================================
'
'
'
'==========================================================
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalMaster.ddf; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalMaster.mdd"
End InputDatasource
384
Chapter 1
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalSecond.ddf; _

Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalSecond.mdd"
End InputDatasource
InputDatasource(myThirdInputDataSource)
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalThird.ddf; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeVerticalThird.mdd"
End InputDatasource
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MergeVerticalOutput.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MergeVerticalOutput.mdd"
Metadata (ENU, Question, Label, myMasterDataSource)
OriginalRespondentSerial long;
OriginalFile text [30];
End Metadata
Event (OnNextCase, "Create new Respondent.Serial")
OriginalRespondentSerial = Respondent.Serial
Respondent.Serial = dmgrJob.OutputCaseNumber

OriginalFile = "MergeVerticalMaster.ddf"
OriginalFile = "MergeVerticalSecond.ddf"
OriginalFile = "MergeVerticalThird.ddf"
End Select
End Event
Each case in the output file will include two new variables, which have been defined in the
metadata section. In the OnNextCase event section, the original value of Respondent.Serial is
stored in the first new variable and Respondent.Serial is renumbered, starting from one for the
first case. In the Select Case statement, the name of the original input file is stored in the second
new variable.
385
Base Professional
The case data contained in the three input files is based on the Short Drinks sample data, which
is installed with the Data Collection Developer Library. MergeVerticalMaster.ddf contains the
case data collected using version 3 of short_drinks.mdd, MergeVerticalSecond.ddf contains the
case data collected using version 4, and MergeVerticalThird.ddf contains the case data collected
using version 5.
Example of a Horizontal Merge
This example is provided as a sample data management script file called MergeHorizontal.dms,
which is installed with the IBM® SPSS® Data Collection Developer Library. For more
information, see the topic Samples on p. 466.
The two InputDataSource sections both contain JoinKey parameters that specify that the data
sources will be joined using the Respondent.Serial system variable. The JoinType parameter in
the first InputDataSource section specifies that a full join is required. When the script is run, the
two input IBM SPSS Data Collection Data Files will be merged into a single IBM SPSS Data
Collection Data File called MergeHorizontalOutput.ddf.
'==========================================================
'
'
'
'==========================================================
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeHorizontalMaster.ddf; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeHorizontalMaster.mdd"
JoinType = "Full"
End InputDatasource
Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeHorizontalSecond.ddf; _
Initial Catalog = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\MergeHorizontalSecond.mdd"
End InputDatasource
386
Chapter 1

Location = C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MergeHorizontalOutput.ddf;"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\MergeHorizontalOutput.mdd"
The two input files are based on the Short Drinks sample data, which is installed with the Data
Collection Developer Library, and contain case data collected using version 5 of short_drinks.mdd.
However, the values of Respondent.Serial in both files have been renumbered starting from 1.
MergeHorizontalMaster.ddf contains case data for all variables except age and income and is
missing respondents 12 and 19. MergeHorizontalSecond.ddf contains case data for the age and
income variables but is missing respondents 2, 23 and 26.
If you run the above script and look at the output data, you will see that a case exists for all
respondents. However, respondents 12 and 19 will contain data for only age and income, and
respondents 2, 23 and 26 will be missing data for age and income.
If you change the value of JoinType to “Left” and rerun this script, you will see that respondents
12 and 19 are now missing from the output data because they did not exist in the master data
source. If you then change the value of JoinType to “Inner” and rerun this script, you will see that
respondents 2, 12, 19, 23 and 26 are now missing from the output data because they were not
present in both input data sources.
Merging Japanese (Multibyte) Data Sources
The IBM® SPSS® Data Collection Developer Library (DDL) contains two sample
data management scripts that demonstrate the merging of data sources that contain
Japanese-language surveys and Japanese-language case data. The data management scripts are
JapaneseMergeHorizontal.dms and JapaneseMergeVertical.dms and by default are located in
folder [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS.
The input data sources are, by default, located in folder

[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Japanese Data. The question
and category names in these data sources are in Japanese as are all label texts and all
responses to text questions. The surveys are based on that for the museum sample data set
that is supplied with the DDL.
By running these examples, you can see that both metadata and case data are merged successfully
even when question and category names are defined in a multibyte language such as Japanese.
Note: If you do not see Japanese characters in the text below, you may need to install files for
East Asian languages on your computer. You can normally do this from Regional and Language
Options (or Regional Options) in Control Panel.
387
Base Professional
Vertical Merge Example
The script JapaneseMergeVertical.dms performs a vertical merge of two data sources that contain
data for different respondents, such as when different offices have carried out the same survey.
The metadata for the two data sources is similar, but not identical. The differences in the metadata
are described in the following table.
Question Name Differences
Age (年齢種別) In the second data source, this question has an
additional category, which is a NA (no answer)
special response.
Certificate (生物学の資格種別) This question exists only in the master data source.
Country (国) This question exists only in the second data source.
Expect (期待) In the master data source, this question has an
additional category, which is named Reacquaint (知
識の再整理).
Museums (博物館種別) In the second data source, this question has
additional categories, which are named Transport (
交通手段) and ModernArt (近代美術).
The data management script includes both a Metadata section and an OnNextCase section, which
are used to ensure that the output data does not contain duplicate values of the system variable
Respondent.Serial. For a description of the technique used, see Running a Vertical Merge.
When you run JapaneseMergeVertical.dms you should find that the output metadata document
contains all questions and categories from both input data sources. For question Certificate (生
物学の資格種別), the output case data will contain nulls for those cases originating from the
second input data source. For question Country (国), the output case data will contain nulls for
those cases originating from the master input data source.
Horizontal Merge Example
The script JapaneseMergeHorizontal.dms performs a horizontal merge of two data sources that
contain data for mostly the same respondents. A full join is performed, that is, all cases are written
to the output data regardless of whether a matching case was found on the other input data source.
The metadata for the two data sources is different, that is, the master data source contains
questions that were asked as the respondents entered the museum and the second data source
contains questions that were asked as the respondents left the museum.
The cases are joined using the value of the system variable Respondent.Serial. The differences
in the number of respondents are as follows:
Respondents 2, 8, and 18, exist only on the master data source.
Respondents 4 and 19 exist only on the second data source.
Respondent 13 does not exist on either data source.
388
Chapter 1
When you run JapaneseMergeHorizontal.dms you should find that the output metadata document
contains all the questions from both input data sources. For those respondents that did not
participate in both questionnaires, the output case data will contain nulls for those questions
that were not asked.
Data Cleaning
Data cleaning is the process by which errors and anomalies are removed from the case data so that
it can be analyzed efficiently. A number of factors affect the types of errors and anomalies that are
likely to occur in the case data, for example:
Interviewing medium. In a paper questionnaire there is nothing to stop a respondent selecting
more than one response in a single response question or entering his or her age as 500 years,
for example, regardless of the quality of the instructions. You are therefore likely to find
more errors and anomalies in paper survey data than in electronic survey data because you
can design an electronic questionnaire so that it will not accept more than one response to a
single response question or an age that is greater than a specified maximum. However, even
data collected using the best-designed electronic questionnaire may contain some errors and
anomalies due to respondent confusion, fatigue, or perversity. Indeed sometimes you may
want to design the questionnaire in such a way that contradictory information can be entered
to alert you to respondents who may be less than candid.
Interviewer or self-completion. Using an interviewer to conduct a survey and record the
responses may reduce the number of errors and anomalies, but it is unlikely to totally
eliminate any errors that the interviewing medium allows, due to human error.
Mode of data entry. Errors can be introduced when data is entered into the system. For example,
operators may make typographical and other mistakes when using a manual data entry
system. Other errors are likely to be introduced when paper questionnaires are scanned—for
example, when the paper has been torn, marked, or crumpled, or when the scanning software
misinterprets hand-written responses. Sometimes data is cleaned as part of the data entry
process. For example, during manual data entry or the verification of scanned data, operators
will look for and correct invalid responses according to predefined rules. This has the
advantage that each response can be easily viewed in the context of the whole questionnaire
and the respondent’s other responses. However it has the disadvantage that variations in the
ways operators interpret and apply the rules invariably lead to inconsistencies. Moreover it
means that there is no electronic record of the original responses to refer to when a suspicion
arises that errors or other distortions have actually been introduced during cleaning.
Questionnaire design. Sometimes errors and anomalies are introduced due to errors in the
design of the questions and the routing logic. Generally most of these errors should be
discovered and corrected during testing before the first respondent is interviewed. However,
in a complex survey, some potential problems may be inadvertently overlooked.
The aim when cleaning data is to attempt to interpret what the respondent was trying to express
without distorting the data. There are a number of different approaches and conventions for
cleaning data, each of which has its merits. For example, suppose a respondent selected both Very
good and Fair in response to a single response question that has the following list of possible
responses (categories):
Excellent
389
Base Professional
Very good
Good
Fair
Poor
Don’t know
Here are some of the possible solutions:

Delete both responses and replace them with Don’t know.
Delete both responses and replace them with Good, which is halfway between the two chosen
responses.
Select one of the responses randomly and delete the other one.
Use an alternating algorithm so that the first time this scenario is encountered, you select
the response that is higher in the scale and delete the lower one and the next time, you do
the reverse.
Mark the case as requiring review, and record the question name in the data cleaning note
system variable.
List the problem in a report and record the action taken.
List the problem in a report and take no other action.
Delete the case.
IBM® SPSS® Data Collection Base Professional can handle all of these approaches and has the
advantage that it can implement the chosen solution consistently.
Other common errors that may need correcting are:

Text and numeric responses that are outside the specified ranges. For example, a 20-character
response in an 8-character postal code field, an age in years that is greater than the specified
maximum age.
A single-choice special category (such as Don’t know, Refused to answer, etc.) that has been
selected in combination with a regular category in response to a multiple response question.
Responses that violate the routing logic. For example, in the Museum survey there is a
question that asks Do you have any qualifications in biology? Only if the respondent answers
Yes to this question should he or she answer the next question, What are your qualifications in
biology? Otherwise, clearly the response to at least one of the two questions is incorrect.
Cleaning Data Using a DMS File
The DMS file provides a powerful scripting solution to cleaning data:

You can clean the data using SQL syntax, mrScriptBasic, or a combination of both SQL
syntax and mrScriptBasic. However, unless you are an expert in SQL syntax, mrScriptBasic
is generally easier to read and understand.
390
Chapter 1
By default, the clean data is written to a different data source, thus keeping the original “dirty”
data intact. An advantage of keeping the original data is that it is available for comparison if
subsequently there are any queries about the validity of the changes made to the data during
the cleaning process. However, the original data can be overwritten if required.
You can clean the data and export it to more than one data format (such as IBM® SPSS®
Statistics .sav file and IBM® SPSS® Quantum™ .dat file) in one operation.
You can use the same cleaning algorithms on data that has been collected and entered using a
combination of methods; such as a combination of IBM® SPSS® Data Collection Interviewer
Server, IBM® SPSS® Data Collection Paper - Scan Add-on, and manual data entry of IBM®
SPSS® Data Collection Paper questionnaires.
You can first write a report on the errors and use this to design the cleaning algorithms,
which you then run.
You can clean the data in stages. For example, at the end of each day or week of a long-term
project.
You can use the three data cleaning system variables (DataCleaning.Status,
DataCleaning.ReviewStatus, and DataCleaning.Note) to mark a case as requiring review
and write notes about the problems found.
You can remove variables that are not required for analysis. You do this by setting up a
metadata filter. For more information, see the topic Filtering Data in a DMS File on p. 243.
Data Cleaning Examples
This section provides some mrScriptBasic examples that illustrate some possible solutions to
various common data cleaning scenarios.
1. More Than One Response To a Single Response Question
2. A Complete Example
3. More on Cleaning Single Response Data
4. Cleaning Other Question Types
5. Routing-Based Cleaning
6. Advanced Cleaning Example
Most of the examples in this section are based on the Museum example data set.
1. More Than One Response To a Single Response Question
In the Data Cleaning overview topic, we saw there are many possible solutions to cleaning
data that contains multiple responses to single response questions. This topic provides some
mrScriptBasic code for implementing some of these solutions.
Except where specified otherwise, you implement the mrScriptBasic code in the OnNextCase
Event section of the DMS file. All of the variables that were included in the Select Query in
the InputDataSource section are automatically available as Data Management Object Model
(DMOM) Question objects in the OnNextCase section and you can access the responses using the
Question.Response property.
391
Base Professional
To see the code as it would appear in a DMS file, see 2. A Complete Example.
Delete all responses and replace them with Not Answered
This example uses the function to return the number of responses the respondent chose when
answering the question. If the result is more than 1, the response is then set to the Not answered
category.
If interest.Response.AnswerCount() > 1 Then
interest.Response = {Not_answered}
End If
You do not need to specify the Question.Response property explicitly because it is the default
property for simple questions. This means you can simplify the code like this:
If interest.AnswerCount() > 1 Then
interest = {Not_answered}
End If
Delete the respondent record
This example also uses the AnswerCount function, but this time if there is more than one response,
the DropCurrentCase method is called so that the case is not transferred to the output data source.
If gender.AnswerCount() > 1 Then dmgrJob.DropCurrentCase()
Note that DropCurrentCase does not delete the case from the input data source—it merely drops
the case from the transformation.
Select one response randomly
This example use the function to select one response randomly:

If time_spent.AnswerCount() > 1 Then
time_spent = time_spent.Response.ran(1)
End If
Mark the case as requiring review
This example adds a text to the DataCleaning.Note and sets the DataCleaning.Status system
variable to Needs review.
If age.AnswerCount() > 1 Then
DataCleaning.Note = DataCleaning.Note + " Age needs checking."
End If
Write the details to a report
This example shows writing a report of the problem to a text file. The example shows the
OnJobStart, OnNextCase, and OnJobEnd Event sections of the DMS file only.
392
Chapter 1
The OnJobStart Event uses the function to create a FileSystemObject, which is a standard
Microsoft object for working with folders and files. The FileSystemObject.CreateTextFile method
is then called to create a text file object, which is then added to the global variables collection.
The OnNextCase Event section sets up a string and calls the WriteLine method on the text file
object to write it to the text file. Notice that the function has been used to convert the numeric
serial number to text.
The OnJobEnd Event section closes the text file.

Dim fso, txtfile
Set txtfile = fso.CreateTextFile("Cleaning.txt", True, True)
End Event
Event(OnNextCase, "Check the data")

Dim strDetails

strDetails = strDetails + " Age needs checking."
End If
dmgrGlobal.mytextfile.WriteLine(strDetails)
End Event

End Event
You could use a similar technique to write questionable responses to the text file or to write
the information to a .csv file, which is easy to open in Excel. For an mrScriptBasic example
of creating a .csv file, see . Alternatively, you could write the report to the log file. For more
information, see the topic Logging Section on p. 271. In addition the MSWordReport.dms sample
files shows how to create a report in Word. For more information, see the topic Sample DMS Files
That Integrate with Microsoft Office on p. 475.
Replace the responses with a predefined default
You can use the Response.Default property to set up a default response for a question. You can
then use the Validation.Validate method to assign the default value to questions for which the
respondent has selected more than one response.
Event(OnJobStart, "Set up the default")
393
Base Professional
End Event

If expect.AnswerCount() > 1 Then
expect.Validation.Validate(ValidateActions.vaAssignDefault)
End If
End Event
Note that the Validate method checks the maximum value set for the variable. This means that this
code only replaces the respondent’s selected responses with the default if he or she has chosen
more responses than the maximum number allowed. The code works in this example because
expect is a single response variable, which by definition means that its maximum value is set to 1.
However, it is possible to change the maximum value in the script. For an example of doing this,
see the second example in 3. More on Cleaning Single Response Data.
Also, notice that when you use a constant that is defined in a type library that is registered in the
script, you need to include the name of the type definition. For example, if this example had
excluded the “ValidateActions” name and specified only “vaAssignDefault” as the parameter to
the Validate method, mrScriptBasic would give an “Unidentified variable” error.
Requirements
2. A Complete Example
This topic shows the code from 1. More Than One Response To a Single Response Question
as it would appear in a DMS file.
Notice that the InputDataSource section contains a select query, which specifies a number of
variables by name. Each of these variables is available as a Question object in the OnNextCase
Event section.
'==========================================================
'
'
'
'==========================================================
SelectQuery = "SELECT Respondent.Serial, DataCleaning.Note, _
394
Chapter 1
DataCleaning.Status, interest, age, gender, expect, time_spent _

FROM VDATA _
End InputDataSource

Dim fso, txtfile
Set txtfile = fso.CreateTextFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Cleaning.txt", True, True)
End Event

Dim strDetails
If interest.AnswerCount() > 1 Then

interest = {Not_answered}
End If
If gender.AnswerCount() > 1 Then dmgrJob.DropCurrentCase()
If time_spent.AnswerCount() > 1 Then

time_spent = time_spent.Response.ran(1)
End If

strDetails = strDetails + " Age needs checking."
End If
If expect.AnswerCount() > 1 Then

expect.Validation.Validate(ValidateActions.vaAssignDefault)
End If
End Event

End Event

Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Cleaning.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Cleaning.mdd"
395
Base Professional
Note: This example is provided as a sample DMS file (called Cleaning.dms) that is installed
Requirements
3. More on Cleaning Single Response Data
In 1. More Than One Response To a Single Response Question, we saw examples of various ways
of dealing with case data that contains multiple responses to single response questions. The
examples showed cleaning the data for each question individually by name. However, in “real
life” you will often want to apply the same cleaning rules to many of the questions in a survey.
This topic provides examples of two ways of doing this. These examples are followed by an
example of alternately selecting the highest and lowest response when more than one response has
been chosen as the answer to a rating question.
Using a loop
The following example uses a loop to iterate through all of the single response questions included
in the job, testing whether they have more than one response, and if they do, writing the details to
a report file and setting the DataCleaning.Status system variable to Needs review. (This example
assumes that the report file is set up in the OnJobStart Event section and closed in the OnJobEnd
Event section as shown in the previous example.)
Dim myQuestion, strDetails, strError
On Error Goto ErrorHandler
For Each myQuestion in dmgrJob.Questions

If myQuestion.QuestionType = QuestionTypes.qtSimple Then
If myQuestion.Response.DataType = mr.Categorical Then
If myQuestion.Validation.MaxValue = 1 Then
If myQuestion.AnswerCount() > 1 Then
strDetails = strDetails + myQuestion.QuestionFullName + " needs checking "
End If
End If
End If
End If
Next
Exit ' Success
ErrorHandler:
396
Chapter 1
strError = CText(Err.LineNumber) + ": " + Err.Description

dmgrLog.LogScript_2(strError)
Debug.Log("ERROR: " + strError)
End Event
Logging(myLog)
Group = "DMGR"
Path = "c:\temp"
Alias = "Tester"
FileSize = 500
End Logging
The first line within the For Each loop tests the Question.QuestionType property to check that the
question is a simple question and not a complex question like a loop or a compound. When using
a For Each with the Questions object, you must always include a test for complex questions or
you risk getting an error. For more information, see the topic 6. Advanced Cleaning Example
on p. 402.
The next line tests the Response.DataType property to check that the response is Categorical. See
Data Management Object Model (DMOM) for more information.
Notice that this example includes error handling that writes the line number and description of any
error to the log file. For more information, see the topic Logging Section on p. 271.
Note: This example is provided as a sample DMS file (called Cleaning2.dms) that is installed
Using object collection iteration and a subroutine
The Museum example data set contains a number of categorical grid questions. For example,
the rating grid asks respondents to say how interested they were in the various galleries in the
museum. The following table shows the possible responses.
Category label Category name
Not at all interested Not_at_all_interested_1
Not particularly interested Not_particularly_interested_2
No opinion No_opinion_3
Slightly interested Slightly_interested_4
Very interested Very_interested_5
The grid has a multiple response categorical question (called column) that is asked once for each
gallery. Each gallery is a category in the controlling category list. The grid can be considered a
loop that is iterated once for each category in the controlling category list.
This example uses the mrScriptBasic feature to set the default response for the column question to
No opinion and validate all of the iterations of the grid.
397
Base Professional
The Validate method checks the maximum value set for each iteration of the grid and replaces
the selected responses with the default response only if the number of responses is greater than
the maximum value. However, the question is a multiple response question with a maximum
value of 5, so the maximum value is changed by setting the Validation.MaxValue property to 1.
Note that this changes the maximum value in the script only and does not change the maximum
value in the input or output metadata.
rating[..].Column.Response.Default = {No_opinion_3}
rating[..].Column.Validation.MaxValue=1
End Event

On Error Goto ErrorHandler
Dim strError
rating[..].Column.AssignDefaultValidation()
Sub AssignDefaultValidation(Iteration)
If Iteration.AnswerCount() > 1 Then
Iteration.Validation.Validate(ValidateActions.vaAssignDefault)
End If
End Sub
Exit ' Success
ErrorHandler:
strError = CText(Err.LineNumber) + ": " + Err.Description
dmgrLog.LogScript_2(strError)
End Event
Notice that this example also contains a procedure and that, unlike in Visual Basic, the Question
object global variable needs to be passed as a parameter to the subroutine. This is because in
mrScriptBasic variables (including global variables) that are available to the main script block are
not visible to functions and subroutines accessed by that script block.
This example assumes that the grid is available as a Question object called rating. This is true if
SELECT * FROM vdata is used (for example, because the InputDataSource section does not include
a select query). However, if a select query is included, it would need to include two or more of
the variable instances that belong to the grid. (You cannot specify the grid itself in the select
query, only the variable instances that relate to the grid. In this grid there is one variable instance
for each iteration of the grid.) For example:
SelectQuery = SELECT rating[{Fossils}].Column, rating[{Birds}].Column FROM vdata
Note: This example and the next one are included in the Cleaning3.dms sample DMS file that
is installed with the Data Collection Developer Library. For more information, see the topic
Selecting the highest and lowest response alternately

398
Chapter 1
When two or more responses have been selected in answer to a rating question, you may
sometimes want to use an alternating algorithm so that the first time this scenario is encountered,
you select the response that is higher in the scale and delete any lower ones and the next time,
you do the reverse. The next example shows an example of doing this for one of the iterations of
the rating_ent categorical grid, which has similar responses to the rating grid described above.
The example uses the and functions to sort the responses into ascending and descending order
and select the first response in the list. A global variable is used to keep track of which one was
used last time.
Dim Switch
Switch = 1
dmgrGlobal.Add("Switch")
Set dmgrGlobal.Switch = Switch
End Event

If rating_ent[{Fossils}].Column.AnswerCount() > 1 Then
If dmgrGlobal.Switch = True Then
rating_ent[{Fossils}].Column = rating_ent[{Fossils}].Column.SortAsc(1)
dmgrGlobal.Switch = False
Else
rating_ent[{Fossils}].Column = rating_ent[{Fossils}].Column.SortDesc(1)
dmgrGlobal.Switch = True
End If
End If
End Event
Requirements
4. Cleaning Other Question Types
Special category selected with regular categories in response to a multiple response question
The special Don’t Know, No Answer, and Refuse to Answer categories are generally defined as
exclusive or single-choice even when they are part of a multiple response question. This example
shows using the > to test whether the No Answer category has been selected in combination with
any other response in answer to the Remember multiple response question. If it has been, the
function is then used to remove the No Answer category from the list of responses.
If Remember > {Not_answered} Then
Remember = Difference(Remember, {Not_answered})
End If
You can test whether categories have been defined as exclusive using the Attributes property of the
DMOM Category object. For example, the following code uses For Each...Next to loop through
the categories in the question, testing whether any of them are defined as exclusive. If a category
is exclusive and it has been chosen with any other responses, the code uses the Difference function
399
Base Professional
to remove the exclusive category from the list of responses. The code uses the function to test
whether the caExclusive attribute has been set.
Dim myCategory
If Remember.AnswerCount() > 1 Then
For Each myCategory in Remember.Categories
If BitAnd(myCategory.Attributes, CategoryAttributes.caExclusive) And Remember >= myCategory Then
Remember = Difference(Remember, myCategory.Value)
End If
Next
End If
Alternatively, you can use the individual response values to look up the corresponding category in
the Categories collection. For example:
Dim Value, i
If Remember.AnswerCount() > 1 Then
For i = LBound(Remember.Response.Value) to UBound(Remember.Response.Value)
Value = CCategorical(Remember.Response.Value[i])
If BitAnd(Remember.Categories[Value].Attributes, CategoryAttributes.caExclusive) Then
Remember = Difference(Remember, Value)
End If
Next
End If
Notice that this example uses the and functions to loop through the responses, because the
Response.Value property does not support the For Each loop.
When using the response to access the category in the Categories collection, you will get an
error (typically “Object required when accessing Attributes”) if the response in the case data
does not correspond to a category in the Categories collection or the case data contains a Null
value. The first problem typically occurs when you are working with case data that was collected
with multiple versions and the category that corresponds to the response in the case data has
been deleted from the version being used for the transformation. You can avoid this problem by
selecting all versions of the metadata for the export and using IS NOT NULL to filter out the
Null values. See the CreateDRS.dms file for an example. For more information, see the topic
Open-ended response is too long
This example uses the function to strip leading and trailing spaces from an open-ended response
and then uses the function to return the number of characters that remain. If greater than 90, the
response is set to the 90 leftmost characters that are returned by the function.
Dim AddressLength
AddressLength = Len(address.Trim())
If AddressLength > 90 Then
address = Left(AddressLength, 90)
End If
Accessing the open-ended responses to an Other Specify category

400
Chapter 1
You can access the responses to an Other Specify category using the Response.Other property.
This returns a collection of Response objects. The following example shows writing the Other
Specify text to a text file.
If MyQuestion.Response.Other.Count >= 1 Then
For Each OtherResponse in MyQuestion.Response.Other
strResponse = CText(SerialNumber) + ": " + CText(OtherResponse.Value)
dmgrJob.GlobalVariables.mytextfile.WriteLine(strResponse)
Next
End If
This example is included in the GetOtherSpecifyText.dms sample. For more information, see the
topic Sample DMS Files on p. 467.
Accessing special responses to non-categorical questions
Non-categorical questions (that is, numeric, text, date, and boolean questions) can include Don’t
Know, No Answer, and Refuse to Answer special responses. In a non-categorical question, special
responses are defined as categories in the question’s codes list and are marked as exclusive,
meaning that they cannot be combined with any other answer.
You can access the responses to a question’s codes list using the Response.Coded property. The
following example shows how to test if the response to question Q1’s codes list is a category
named REF, meaning Refuse to answer:
If Q1.Response.Coded = {REF} Then
Debug.Log("Respondent: " + CText(Respondent.Serial) + _
" - Response to question Q1 is 'Refuse to answer'")
End If
Requirements
Base Professional 3.5 or later for using the Response.Coded property
5. Routing-Based Cleaning
Paper questionnaires often contain routing in the form of Go To instructions. For example, in the
Museum example, the education question asks whether the respondent is currently enrolled in
full-time education. If the response is Yes, he or she is asked to go to the school question, which
asks for details about the type of school or college he or she attends.
The IBM® SPSS® Data Collection Developer Library comes with a paper questionnaire
(Museum.doc) that shows the routing used to collect the data. The paper questionnaire
is in the form of a Word document and was created from the Museum.mdd file using
IBM® SPSS® Data Collection Paper. However, you do not need to have Paper
installed to open the document. By default, the questionnaire is installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File folder.
401
Base Professional
This example uses a Select Case statement to test the response given to the education question. If
the response is No or Not answered and a regular response was selected for the school question,
the education question response is set to Yes. Similarly, the response to the education question is
set to No if no regular response was selected for the school question.

Select Case education
Case {No}
If Not (school = {Not_answered}) Then
If school.AnswerCount() > 0 Then
education = {Yes}
End If
End If
Case {Yes}
If school = {Not_answered} _
OR school.AnswerCount() < 1 Then
education = {No}
End If
Case {Not_answered}
If Not (school = {Not_answered}) Then
If school.AnswerCount() > 0 Then
education = {Yes}
End If
End If
Case Else
End Select
End Event
402
Chapter 1
Here is another example, an mrScriptBasic snippet, that tests the response to the visits numeric
question. This question asks how many times the respondent has visited the museum previously
and is only asked if he or she selected Yes in response to the before question, which asks whether
he or she has visited the museum before. If the response to the visits question is within the valid
range (1-99), the response to the before question is automatically set to Yes.
If (visits > 0) And (visits < 100) Then
before = {Yes}
Else
visits = 0
before = {No}
End If
End If
End Event
Requirements
6. Advanced Cleaning Example
This example provides an example of using advanced mrScriptBasic features to create a general
cleaning script for all of the questions in a survey. It builds on the first example shown in 3. More
on Cleaning Single Response Data, but handles questions of all types.
The most important code in this example is in the CleanQuestion Sub procedure, which determines
the question type and then takes the appropriate action. Notice that this subroutine starts with the
following line:
If (Q.QuestionType <> QuestionTypes.qtSimple) Then
This tests whether the question is a complex question like a block or a grid, and if it is, performs
another For Each loop on the Questions object that corresponds to the questions nested within the
block or grid. It is important that you always include a test of this type when you are using a For
Each construction with the Questions collection or you risk getting an error.
Notice that all of the subroutines take the dmgrJob object as the first argument. This is useful
because the dmgrJob object gives you access to many other objects that you need, such as the
GlobalVariables collection. Also, notice that this example provides an example of calling the
Err.Raise method.
'==========================================================
'
'
'
403
Base Professional
'==========================================================
' ==============================================================================
Event(OnJobStart)
Dim fso, out
Set out = fso.CreateTextFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\AdvancedCleaning.txt", True, True)
dmgrGlobal.Add("Rep")
Set dmgrGlobal.Rep = out
dmgrGlobal.Rep.WriteLine("Advanced cleaning script started successfully")
End Event
' ==============================================================================
Event(OnNextCase)
CleanAllQuestions(dmgrJob, Respondent.Serial)
'—
———
———
———
———
———
———
———
——–
Sub CleanAllQuestions(dmgrJob, RSerial)

Dim Question
For Each Question in dmgrJob.Questions
Select Case Question.QuestionFullName
Case "Respondent", "DataCollection", "DataCleaning"
' Ignore system variables
Case Else
CleanQuestion(dmgrJob, Question, RSerial)
End Select
Next
End Sub
'—
———
———
———
———
———
———
———
——–
Sub CleanQuestion(dmgrJob, Q, RSerial)

If (Q.QuestionType <> QuestionTypes.qtSimple) Then
' The Question is a complex question (collection)
Dim Question
For Each Question in Q
CleanQuestion(dmgrJob, Question, RSerial)
Next
Else
' For a simple question, figure out the type and call the relevant procedure.
Select Case Q.Response.DataType
Case mr.None
' No response
CheckNone(dmgrJob, Q, RSerial)
Case mr.Double, mr.Long
' Numeric response
404
Chapter 1
CheckNumeric(dmgrJob, Q, RSerial)
Case mr.Text
' Text response
CheckText(dmgrJob, Q, RSerial)
Case mr.Categorical
' Categorical response
CheckCategorical(dmgrJob, Q, RSerial)
Case mr.Date
' Date response
CheckDate(dmgrJob, Q, RSerial)
Case mr.Boolean
' Boolean response
Case Else
Err.Raise(1, , "Unexpected response type encountered (type=" _
+ CText(Q.Response.DataType) + ")")
End Select
End If
End Sub
'—
———
———
———
———
———
———
———
——–
' Check 'unanswered' responses
Sub CheckNone(dmgrJob, Q, RSerial)

'! Insert checks for unanswered variables here ...
For example, you could add the following lines:
If Q.Validation.MinValue > 0 Or Q.Validation.MaxValue < 0 Then

MarkInError(dmgrJob, Q, "should not be blank", RSerial)
End If
However, these lines do not take into account that in some surveys
some respondents are routed around some of the questions. This is
true in the Museum survey, and so these lines are not used in this
example. !'
End Sub
'—
———
———
———
———
———
———
———
——–
' Check numeric responses
Sub CheckNumeric(dmgrJob, Q, RSerial)

' Insert checks for numeric variables here ...
If Q.Response.Value IS NOT NULL Then
If Q.Response.Value < Q.Validation.MinValue Or _
Q.Response.Value > Q.Validation.MaxValue Then
MarkInError(dmgrJob, Q, "is <" + CText(Q.Validation.MinValue) + _
" or >" + CText(Q.Validation.MaxValue), RSerial)
End If
Else
CheckNone(dmgrJob, Q, RSerial)
405
Base Professional
End If
End Sub
'—
———
———
———
———
———
———
———
——–
' Check text responses
Sub CheckText(dmgrJob, Q, RSerial)

' Insert checks for text variables here ...
End Sub
'—
———
———
———
———
———
———
———
——–
' Check categorical responses
Sub CheckCategorical(dmgrJob, Q, RSerial)

Dim C
' Insert checks for categorical variables here ...
' Multiple responses given

If Q.AnswerCount() > 1 Then
For Each C in Q.Categories
If BitAnd(C.Attributes, CategoryAttributes.caExclusive) And Q >= C Then
MarkInError(dmgrJob, Q, "- response """ + C.FullName + """ is not exclusive", RSerial)
End If
Next
End If
If Q.AnswerCount() > Q.Validation.MaxValue Then
MarkInError(dmgrJob, Q, "has >" + CText(Q.Validation.MaxValue) + " responses", RSerial)
End If
End Sub
'—
———
———
———
———
———
———
———
——–
Sub CheckDate(dmgrJob, Q, RSerial)

' Insert checks for date variables here ...
End Sub
'—
———
———
———
———
———
———
———
——–
' Mark the current case in error
Sub MarkInError(dmgrJob, Q, msg, RSerial)

Dim txt
txt = CText(RSerial) + ": " _
+ msg + " (" + Q.QuestionFullName + ")"
dmgrJob.GlobalVariables.Rep.WriteLine(txt)
End Sub
End Event
' ==============================================================================
406
Chapter 1
End InputDataSource
' ==============================================================================
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\AdvancedCleaning.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\AdvancedCleaning.mdd"
' ==============================================================================
Note: This example is provided as a sample DMS file (called AdvancedCleaning.dms) that is
Requirements
Working with the Weight Component

You can use the IBM® SPSS® Data Collection Weight component to define weighting, which
you can then use to weight your data. Weighting is sometimes referred to as sample balancing.
Typically, you use it when you want your data to reflect the proportions of various groups in your
target population more accurately than your data actually does.
The Weight component is designed to work with the IBM® SPSS® Data Collection Data Model
and requires that the CDSC that you are using is write-enabled (Can Add is True for the CDSC),
supports the flat (VDATA) view of the data, and changing the data in existing records (Can Update
is True for the CDSC). Note that in IBM® SPSS® Data Collection Base Professional, the Weight
component always uses the flattened (VDATA) view of the data.
Sometimes weighting is used to treat the respondents as representatives of the total population of
which they are a sample. For example, the data you collect in a survey reflects the attitudes of the
people interviewed. However, sometimes you may want to weight the data to reflect the attitudes
of the total population instead, as if you had interviewed everyone rather than just a sample of the
population. This, of course, assumes that the people interviewed are a truly representative sample.
Suppose you interview 380 respondents from a population of 10,000 internet users, and discover
that 57 members of this sample go fishing regularly. However, you know from national statistics
that out of 380 people, normally 60 would go fishing. So you want to create crosstabulations that
407
Base Professional
show the total number of internet users who go fishing as 60 instead of 57. Moving from 57 to 60
is the fine art of weighting. In this case, each internet user has an individual weight (sometimes
referred to as the weighting factor) of 60/57.
Weighting can also be used to correct bias that builds up during a survey. For example, when
conducting interviews by telephone you may find that 60% of the respondents are women. Using
weighting you could adjust the results so that they more accurately reflect the more even balance
of men and women in the target population.
The basic idea behind weighting is that the data for each respondent is multiplied by that
individual’s weight. For example, consider a simple table of age by gender. When the table is
unweighted, the count in each cell is incremented by 1 for each respondent that satisfies the
conditions of the cell. When the table is weighted, the count in each cell is incremented by 1
multiplied by the individual’s weight.
The Weight component provides three methods of calculating the weighting:
Factor weighting. Use this method when the weighting factors are already known for the
respondents in each population group on which you are basing your weighting—for example,
because they have been calculated using another software package.
Target weighting. Use this method when you know the number or proportion of respondents in
each of the population groups on which you are basing your weighting.
Rim weighting. Use this method when:

You want to weight according to various characteristics, but you do not know the relationship
of the various combinations of those characteristics.
You want to weight using target weighting but there are no respondents who fulfill the
requirements of one or more of the cells of the target weighting matrix.
For all three methods, you specify the weighting parameters using one or more single response
categorical variables. (Note that you cannot use multiple response categorical variables to specify
the weighting parameters.) Generally, you use categorical variables that record demographic
information, such as gender, marital status, age, or region. However, the Weight component does
not restrict you in the selection of the variables to be used. It is up to you to ensure that the
variables that you choose are suitable. If necessary, you can create one or more derived variables
to use to specify the weighting parameters.
Note: The examples in this section are designed to illustrate how to use the Weight component
only. They are not meant to be an accurate representation of how you should use weighting in
a survey.
408
Chapter 1
Factor Weighting
You use factor weighting when you already know the weighting factor for the respondents in each
population group on which you are basing your weighting. For example, you would use factor
weighting when you are basing the weighting on gender and the weights have already been
calculated as:
Gender Weight
Male 0.8
Female 1.2
Similarly, you would use factor weighting when you are basing the weighting on characteristics
recorded using two or more variables and the weight for each combination of categories has
already been calculated. When using more than one variable, it is generally easiest to visualize
this using a table. For example:
Male Female
Under 25 1.05 0.95
25-44 years 1.20 1.10
45 and over 0.90 0.97
When you represent the weighting requirements in a table in this way, it is known as a weighting
matrix.
When three variables are used, the third variable would form layers. Each layer is effectively a
separate two-dimensional table filtered on a category of the variable that forms the layers. For
example, suppose you want to use three variables—gender and age as in the previous example
and the variable status, which has two categories Single and Has live-in partner. The first layer
would define the weights for the respondents in the Single category and the second layer would
define the weights for the respondents in the Has live-in partner category:
Layer 1: Single Male Female
Under 25 0.95 0.75
25-44 years 1.01 1.05
45 and over 0.98 0.97
Layer 2: Has live-in partner Male Female

Under 25 1.25 1.05
25-44 years 0.99 0.96
45 and over 1.02 0.97
Tip. When you want to define factor and target weighting using three variables, you may
sometimes find it easier to create a derived variable that combines the characteristics of two of the
variables and use it in a two-dimensional weighting matrix rather than using a three-dimensional
weighting matrix.
Male Female
Under 25 and single 0.95 0.75
409
Base Professional
Male Female
Under 25 and has live-in partner 1.25 1.05
25-44 years and single 1.01 1.05
25-44 years and has live-in partner 0.99 0.96
45 and over and single 0.98 0.97
45 and over and has live-in partner 1.02 0.97
Target Weighting
You use target weighting (sometimes referred to as cell target weighting) when you know
the number or proportion of respondents in each of the population groups on which you are
basing your weighting. Just as with factor weighting, it is easiest to visualize this using a table
or weighting matrix. (For more information, see Factor Weighting). You use target weighting
when you know the total number or proportion of respondents that you want to appear in each
cell of the table.
For example, suppose you interviewed 600 respondents, and you want to weight the results so
that the gender and age groups carry equal weight. You could do this using target weights by
specifying the number of respondents in each cell. By default, the numbers specified for each cell
are taken to be the total weighted value for that cell. However, if you use the option to weight to a
total value or to the unweighted count of cases, the values are interpreted as proportions.
Male Female
Under 25 100 100
25-44 years 100 100
45 and over 100 100
Rim Weighting
You use rim weighting (sometimes referred to as rim target weighting) when:
You want to weight according to various characteristics, but you do not know the relationship
of the various combinations of those characteristics. For example, when you want to weight
by age, gender, and income and you know the targets for each age, gender, and income group,
but you do not know the targets for some or all of the combinations, such as men under 25
who earn more than 25,000, women between 25 and 44 who earn 10,000-20,000, etc.
You want to weight using target weighting but there are no respondents who fulfill the
requirements of one or more of the cells of the target weighting table. This is more likely
to happen when you base the weight on several variables and so have a multidimensional
weighting table that has a large number of cells.
Rim weighting is designed to attempt to weight all of the characteristics at the same time. The
accuracy of the weighting will depend on how well your sample matches the target population. If
the sample is a good match, then it is likely that the Weight component will generate acceptable
weights. If the sample is not a good match it is possible that the weights will be acceptable for
some of the subgroups but not for others, which will, of course, mean that the weighting will be
unacceptable overall.
410
Chapter 1
As the rim weighting process runs, it tries to distort each variable as little as possible while still
trying to attain all of the desired proportions among the characteristics. The Weight component
produces a root mean square figure, which tells you how much distortion has been introduced, and
therefore how reliable your sample is. The larger the figure, the greater the distortion and therefore
the less accurate your sample is. The root mean square figure is recorded in the weighting report.
Another powerful feature of rim weighting is that it automatically rescales all of the target values
to the same base. For instance, suppose you have a sample of 5,000 respondents and you define
rim weighting parameters as follows:
A weighted total of 10,000
Weighting targets for age in percentages
Weighting targets for gender that add up to 758
Weighting targets for occupation that add up to 1134
The Weight component calculates the weights for these characteristics, using the figures given,
and then adjusts them to the required total. If you do not define a total, the weights are adjusted
to the sum of the targets given for the first variable specified.
As you can see from this simple example, rim weighting can be used when you have weights
coming from different sources, and when those weights are expressed in different ways.
General Weighting Options
This topic describes various options that you can apply when you are using any of the three
weighting methods. The rim weighting method has a number of additional options. For further
information, see Rim Weighting Options.
Weighting to a Specified Total
By default the Weight component calculates the weights for each respondent as follows:
If target weighting is selected, the weighted total equals the sum of the targets defined in
the weighting matrix.
If factor weighting is selected, the weighted total equals the sum of the counts multiplied by
the factors in all of the cells in the weighting matrix.
If rim weighting is selected, the weighted total equals the sum of the targets given for the
first variable specified.
However, you can change this behavior as follows:

If you want the weighted total to equal the unweighted total, set the Weight.TotalType property
to 2.
If you want to define the weighted total, set the Weight.TotalType property to 3 and specify the
weighted total in the Weight.WeightedTotal property.
Preweights
411
Base Professional
You can optionally specify a numeric variable to use as a preweight. The Weight component
then applies the weighting defined in this variable to the data before performing the
weighting calculations. You specify the name of the preweight variable to use in the
Weight.PreweightVariable property.
Preweights are often used in studies that deal with opinions and in which, for example, an adult
male respondent is counted as the total number of male adults in his household. The theory behind
this is that generally all of the adult males in a household have similar opinions. Another use is in
CATI political polls where a respondent is preweighted by the number of calls it took to reach
him or her. The supposition behind this is that the more calls it takes to reach a respondent, the
more people there are like him or her, who are equally hard to reach. The respondent is therefore
preweighted in order to represent the many similar respondents who are never interviewed.
Postweights
Postweights are the opposite of preweights. Postweights are applied after all of the other weighting
has been applied. Postweights therefore have no effect on the way in which the weighting targets
are reached. You specify the name of the numeric variable to use for postweighting in the
Weight.PostweightVariable property.
Postweights are generally used to make a final adjustment to a specific item. For example, when a
survey is conducted in London and Inverness and 200 respondents are interviewed in each city.
Target weighting is calculated to balance each group according to gender and age so that the
samples match the patterns of the total populations in those cities. After this is done, you might
apply a postweight to adjust the totals for each city into their correct relative proportions, where
London has a much larger population than Inverness.
Minimum and Maximum Weights
You can optionally define the minimum and maximum weights that you want to be applied
using the Weight.MinWeight and Weight.MaxWeight properties. When you use either or both of
these options, you can optionally specify the maximum number of iterations that the Weight
component is to make when attempting to fit the minimum and/or maximum weights to the data.
You do this using the Weight.MinMaxIterations property. (Note this property is unrelated to the
Weight.RimIterations property, which applies to rim weighting only.)
Excluding Cases
You can exclude respondents from a weighting calculation by defining a filter. For an example
of doing this, see More on Target Weighting.
Rim Weighting Options
Rim weighting calculates weights using a form of regression analysis. This requires a limit that
defines how close the weighting procedure must get to the targets you define in order for the
weights to be acceptable, and the number of times the weight calculations may be repeated in the
attempt to reach the targets. Each time the weight calculations are performed is called an iteration.
412
Chapter 1
At the end of each iteration, the Weight component compares the root mean square with the
product of the weighted total and the given limit. The iterations continue until the root mean
square is within the limit, in which case weighting is considered successful, or until the maximum
number of iterations has been reached. If, after the maximum number of iterations, the root mean
square is still outside the limit, the Weight component reports the failure in the weighting report.
However, the weights that have been calculated are still written to the case data variable.
The default limit is 0.005 and the default number of iterations is 12. However, you can change
these parameters using the Weight.RimLimit and Weight.RimIterations properties. For example,
you may want to reduce the limit and increase the number of iterations on a large sample to
increase the accuracy of the weights.
You can also request that the weighting report gives details of the weights calculated at the end
of each iteration instead of merely at the end of the final iteration. You do this by setting the
Weight.RimReportInDetail property to True.
The weighting report highlights rim weights that are outside of a specified range. By default,
the range is defined as 0.6-1.4. However, you can specify a different range using the
Weight.RimFlagBelow and Weight.RimFlagAbove properties.
Weighting Report
The Weight component generates a report in HTML format that can easily be written to a text
file. The main report is generated by the WeightEngine.Execute method. However, additional
information (such as information about cases that do not belong in the weighting matrix) is added
by the WeightEngine.Prepare method. You should therefore write the report to the text file twice,
once after the call to WeightEngine.Prepare and once after the call to WeightEngine.Execute as
shown in the Weighting.dms sample file. For more information, see the topic Setting Up Weighting
in a DMS File on p. 431.
Here is an example of the report for a simple target weighting run based on equal targets of
male and female respondents.
413
Base Professional
For each cell in the weighting matrix, the report shows:

Given. The target or factor that was defined
Counts. The number of cases that fulfill the requirements of the cell
Weights. The weight calculated for the cases in the cell.
In the example report above, the weighting was based on one variable that has only two categories
and so the weighting matrix has only two cells. Here is another example of the report for a
weighting matrix of gender by age and equal targets of respondents in each cell.
414
Chapter 1
Note that in this example, the weighting matrix has been specified in the order gender then age
and the report gives the figures for the Male category of the gender variable first and then for
the Female category of the gender variable.
If the variables had been specified in the reverse order (age then gender) as in the example in
More on Target Weighting, the table of figures would be rotated.
In addition to this information for each cell in the weighting matrix, the Weight component also
reports the following information about the weighting overall:
The lowest and highest weights
The ratio of the highest weight to the lowest weight
The effective base, which is calculated by dividing the squared sum of weights for all of the
respondents in the weighting matrix table by the sum of the squared weights
The unweighted total
Rim Weighting
For rim weighting, the weighting report shows the target value for each category of each variable
on which the weighting is based. In addition it includes additional information that is not relevant
to target and factor weighting.
For each category of each variable the report shows the following:
Input frequency. The number of cases for which the category is selected.
Input percent. The percentage of cases for which the category is selected.
Projected frequency. The number of cases that are required in the category. This is based on
the target given for the category.
Projected percentage. The percentage of cases that are required in the category. This is based
on the target given for the category.
This is followed by the following information:

Convergence/failure. The iteration on which convergence occurred or on which the weighting
was deemed a failure.
Root mean square (RMS). Rim weighting calculates the weights for each cell in the weighting
matrix using a form of regression analysis. The aim is to distort each variable as little as
possible while trying to attain all of the desired proportions among the various characteristics.
The root mean square figure tells you how much distortion has been introduced, and therefore
how reliable your sample is. The larger the figure, the greater the distortion and therefore the
less accurate your sample. For details of the formula, see Rim Weighting Formulae.
Limit. This is the limit below which the root mean square must not fall. It is calculated as the
product of the weighted total and the limit defined in the Weight.RimLimit property (0.005
by default).
By default the following information is given for each category of each variable in the
final iteration. However, you can request this information for each iteration by using the
Weight.RimReportInDetail property.
415
Base Professional
Rim weights. The rim weight calculated for the cases in the category. Weights that are outside
of the required range are highlighted. The range is defined in the Weight.RimFlagBelow and
Weight.RimFlagAbove properties, which are set to 0.6 and 1.4 by default.
Output frequency. The number of cases in the category after the weighting is applied.
Output percent. The percentage of cases in the category after the weighting is applied.
Finally the following information is given:

Rim weighting efficiency. This figure gives an indication of how well balanced the sample is. If
the data for many cases needs to be weighted heavily up or down, the efficiency percentage
is low. The greater the percentage, the more well balanced the sample. For details of the
formula, see Rim Weighting Formulae.
Maximum respondent rim weight.
Minimum respondent rim weight.
Rim Weighting Formulae
Root Mean Square
The formula is given for a rim weighting matrix consisting of two variables (dimensions), but the
same principle applies when there are more dimensions.
Notation Represents
The target number in category i in the first
dimension.
The sum of the observed numbers in category i in

the first dimension.
The target number in category j in the second

dimension.
The sum of the observed numbers in category j in

the second dimension.
The number of categories in the first dimension.
The number of categories in the second dimension.
The formula for the weight adjustment is

416
Chapter 1
Where
Represents the weight adjustment calculated in the
previous iteration for the cell at the intersection of
category i in the first dimension and category j in
the second dimension. In the first iteration, it is
substituted with
Represents the sum of the weight adjustments
calculated in the previous iteration for category j
in the second dimension. In the first iteration, the
expression is substituted with 1.
The calculation for the root mean square is
Where
calculated in the previous iteration for category i in
the first dimension.
calculated in the current iteration for category j in
the second dimension.
At the end of each iteration, the Weight component compares the root mean square with the
product of the weighted total and the given limit. (The limit defaults to 0.005, but it can be set to
another proportion.) The iterations continue until all of the weights are within the limit or the
maximum number of iterations has been reached.
Rim Weighting Efficiency
The rim weighting efficiency figure gives an indication of how well balanced the sample is.
Let
Be the preweight for case j
Be the rim weight for case j
Then the rim weighting efficiency is

417
Base Professional
If the data for many respondents needs to be weighted heavily up or down, the efficiency
percentage will be low. The greater the percentage the more well balanced the sample.
Further Information
For further information on rim weighting see the Rim Weighting Theoretical Basis Paper entitled
“ON A LEAST SQUARES ADJUSTMENT OF A SAMPLED FREQUENCY TABLE WHEN
THE EXPECTED MARGINAL TOTALS ARE KNOWN”, by W. Edwards Deming and Frederick
F. Stephan, in Volume 11, 1940 of the Annals of Mathematical Statistics.
Weight Component Examples
This section provides some mrScriptBasic examples that illustrate using the IBM® SPSS® Data
Collection Weight component. The examples are designed to illustrate how to use the Weight
component only. They are not meant to be an accurate representation of how you should use
weighting in a survey.
The examples use copies of the Data Collection Data File version of the Museum
sample that is installed with the IBM® SPSS® Data Collection Developer Library. The
Museum sample metadata file is called museum.mdd and by default it is installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File folder. If
the sample files are stored in a different location on your computer, you will need to edit the
Weight1a.mrs script accordingly before running it. To avoid updating the original Museum
sample files, Weight1a.mrs makes copies of the original files, and the remaining scripts then
add weights to the copies.
The topics in this section are illustrated using tables created using IBM SPSS Data Collection
Survey Reporter Professional to show the data when it has been weighted using the weighting that
we create in the examples. However, IBM SPSS Data Collection Survey Reporter Professional is
not a requirement for using the Weight component. If you do not have IBM SPSS Data Collection
Survey Reporter Professional installed, you can easily create equivalent tables using SQL queries
in DM Query. For further information, see 7. Learning about Weighting and .
Here is a table of age by gender run on the unweighted Museum data, to which you may want
to refer for comparison purposes.
418
Chapter 1
Each of the mrScriptBasic examples shown in this section is available as a sample .mrs file that
is installed with the Data Collection Developer Library. The samples are called Weight1a.mrs,
Weight1b.mrs, Weight2.mrs, Weight3.mrs, Weight4.mrs, and Weight5.mrs.
Running the mrScriptBasic examples
You can run the mrScriptBasic (.mrs) examples in IBM® SPSS® Data Collection Base
Professional or using the mrScript Command Line Runner.
Before you run the examples, check that any filenames, and file and folder locations that are
referred to in the examples are correct for your system, and if necessary edit the examples
accordingly.
E To run the mrScriptBasic samples in Base Professional:
1. Open Base Professional.
2. Open the .mrs file you want to run. (The sample mrScriptBasic files are typically installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\General\mrScriptBasic folder.)
3. Press F5 OR choose Start from the Debug menu OR select the Start tool on the Debugging toolbar.
If the examples are not successful, check the value of the the ErrorText variable in the Locals pane.
For more information on editing, running, and debugging mrScriptBasic files in Base Professional,
see Using IBM SPSS Data Collection Base Professional.
E To run the mrScriptBasic samples using the mrScript Command Line Runner:
1. Open a Command Prompt. For example, on Windows 2000, choose Programs from the Windows
Start menu, and then choose Accessories, followed by Command Prompt.
2. Change to the folder in which the sample files are located. This is typically the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\General\mrScriptBasic folder.
3. Type mrScriptCL followed by the name of the file you want to run and the options you require. It
is recommended that you use the /v option. For example, to run the Weight1a.mrs sample, enter:
mrScriptCl Weight1a.mrs /v
419
Base Professional
Using the /v option means that the mrScript Command Line Runner displays the variables used
in the script and their values when the script exits. This means you can check the value of the
ErrorText variable if there are any errors.
Requirements
Editing the Default DataSource Information in the Museum.mdd File
Some example scripts assume that the default DataSource in the museum.mdd file is set up to use
the IBM® SPSS® Data Collection Data File CDSC and the museum.ddf case data file. If either of
these are not true, you will need to edit museum.mdd.
E Open the .mdd file in IBM® SPSS® Data Collection Metadata Model Explorer.
E On the left side, click on the DataSources folder.
E On the right side, double-click Default.
This opens the Edit MDM Property dialog box.

E Select mrDataFileDsc and click OK.
E On the left side, open the DataSources folder and then click on the DefaultDataSource folder.
E On the right side, double-click DBLocation.

E If necessary, edit the text so that it says museum.ddf. (However, if museum.ddf is located in a
different folder from museum.mdd, include the full path to museum.ddf.)
E Click OK.
E Save the file.

420
Chapter 1
Requirements
Creating a New Variable To Hold the Weighting Information
The Weight component does not create a new variable to hold the weighting information. It needs
a suitable numeric variable (of type Double) to already exist in both the metadata and the case data.
This topic shows you how to create the new variable, first in the MDM Document and then in
the case data. You can easily incorporate similar code in the script that you use to set up the
weighting. However, example scripts for creating the variables in the metadata and the case data
are shown here separately for clarity.
Creating the new variable in the MDM Document
The following mrScriptBasic example creates a variable called Weight in a copy of the
museum.mdd file.
'==========================================================
'
'
'
'==========================================================
' The output metadata document (.mdd) file

#define OUTPUTMDM "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum_weight.mdd"
' The output case data (.ddf) file

#define OUTPUTDDF "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum_weight.ddf"
' Note: After running this script, run Weight1b.mrs to add

' the Weight variable to the case data file (museum_weight.ddf).
' Copy the museum.mdd and museum.ddf sample files so that

' the weight examples will not update the original files...
Dim fso, f
OUTPUTMDM, True)
fso.CopyFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Data\Data Collection File\museum.ddf", _
OUTPUTDDF, True)
' Make sure that the read-only attributes are not set
Set f = fso.GetFile(OUTPUTMDM)
421
Base Professional
End If
Set f = fso.GetFile(OUTPUTDDF)
End If
Dim MDM2, WgtVar, MyDataSource
' Create the MDM object

Set MDM2 = CreateObject("MDM.Document")
' Open the Museum.mdd file in read-write mode

MDM2.Open(OUTPUTMDM)
' Create the new variable

Set WgtVar = MDM2.CreateVariable("Weight", "Weighting variable")
' Specify the DataType

WgtVar.DataType = mr.Double
' Specify the usage type as VariableUsageConstants.vtWeight, so

' that it is recognized as a weight variable in Survey Tabulation, etc.
WgtVar.UsageType = BitOr(WgtVar.UsageType, _
MDMLib.VariableUsageConstants.vtWeight)
' Add the new variable to the Fields collection

MDM2.Fields.Add(WgtVar)
' Add a new data source object to the MDM document

' to refer to museum_weight.ddf
MDM2.DataSources.Remove(0)
MDM2.DataSources.AddNew("mrDataFileDsc", "mrDataFileDsc", "museum_weight.ddf", 0)
' Save the metadata file

MDM2.Save()
MDM2.Close()
This example is included with the IBM® SPSS® Data Collection Developer Library as a sample
script called Weight1a.mrs.
Note that the function is used to set the variable’s usage type to vtWeight. This means that the
variable will be recognized as a weighting variable in IBM® SPSS® Data Collection Survey
Tabulation and InterviewReporter. BitOr is used instead of just setting WgtVar.UsageType =
MDMLib.VariableUsageConstants.vtWeight. The reason is to preserve any existing flags that are
set in WgtVar.UsageType.
Also note that the script copies the Museum sample case data file (museum.ddf) to another file
called museum_weight.ddf, which will be used by the weight example scripts in the following
topics. This ensures that the original museum.ddf file is not updated.
422
Chapter 1
Creating the new variable in the case data
The following mrScriptBasic example displays the Data Link Properties dialog box, and
then runs the xp_syncdb extended stored procedure to synchronize the case data with the
metadata. If you run this script after running Weight1a.mrs, and select the appropriate metadata
(museum_weight.mdd) and case data (museum_weight.ddf) in the Data Link Properties dialog box,
the corresponding variable is created in the case data.
Dim Wizard, ConnectionString
' Use the Data Link Properties dialog box to get the connection string
Set Wizard = CreateObject("mrOleDB.DataLinkHelper")
ConnectionString = Wizard.DisplayWizard()
If Len(ConnectionString) > 0 Then

' Create a connection and open a recordset against VDATA
Dim adoConnection
Set adoConnection = CreateObject("ADODB.Connection")
adoConnection.Open(ConnectionString)
adoConnection.Execute("exec xp_syncdb")
End if
A similar example is included with the Data Collection Developer Library as a sample script
called Weight1b.mrs.
Note: Running the xp_syncdb extended stored procedure on an existing data set requires that the
CDSC that you are using is write-enabled and supports changing the layout of the data in existing
records (Can Update and DDL Column are True for the CDSC).
Requirements
Simple Target Weighting Example
This simple mrScriptBasic example sets up target weighting in a variable called Weight that
already exists in both the metadata and the case data. You will get an error if you attempt to run
the example when this variable does not exist. (For an example that creates this variable, see
Creating a New Variable To Hold the Weighting Information.) The weighting is based on equal
numbers of male and female respondents. Here is the weighting matrix:
Gender Target
Male 301
Female 301
Here is the mrScriptBasic code:

'==========================================================
'
423
Base Professional

'
'
'==========================================================
' This script weights the files created by Weight1a.mrs

' and Weight1b.mrs
Dim MDM2, WgtEng, Wgt, fso, ReptFile

' Open the .mdd file created by Weight1a.mrs

MDM2.Open("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\museum_weight.mdd")
' Create an instance of the Weight Engine object

Set WgtEng = CreateObject("mrWeight.WeightEngine")
' Initialize the Weight Engine

WgtEng.Initialize (MDM2)
' "Weight" is a variable of type Double that already exists in both
' the metadata and the case data
' "gender" is the variable that stores the characteristics on which
' we wish to base the weighting
'2 defines the weighting method as target weighting
Set Wgt = WgtEng.CreateWeight("Weight", "gender", 2)
' Create a text file for the weighting report

Set ReptFile = fso.CreateTextFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Weight2.htm", True)
' Define the targets for the 2 cells of the weighting matrix
' Call the WeightEngine.Prepare method
WgtEng.Prepare(Wgt)
' Write the weighting report to the text file
' Call the WeightEngine.Execute method
WgtEng.Execute(Wgt)
ReptFile.Close()
' Close the database connection and flush pending data updates
Set WgtEng = Null
MDM2.Close()
424
Chapter 1
script called Weight2.mrs.
Here is a table of age by gender run on the Museum example data weighted using the Weight
variable:
Notice that whereas in the unweighted table, shown in Weight Component Examples, there were
339 male and 263 female respondents in the Base row, now there are equal numbers of male and
female respondents in the Base row.
The Wgt.CellRows.Targets = "301; 301" line in the example script defines targets of 301 respondents
for each of the two cells of the weighting matrix. The weighted total is the sum of the targets (301
+ 301 = 602) because this is the default behavior and we have not specified a different option in
the Weight.TotalType property.
If you want the weighted total to be 1000, with an even distribution between the male and female
respondents, you could simply change the Wgt.CellRows.Targets = "301; 301" line to:
If you want the targets to represent proportions, you must specify the weighted total. One way of
doing this is to specify that the weighted total should equal the unweighted total. This is useful
when you want to specify your targets as proportions of the unweighted total but you do not
know what the unweighted total is, perhaps because the data is still being collected. You do this
by setting the Weight.TotalType property to 2. For example, replace the Wgt.CellRows.Targets =
"301; 301" line with the following:

Wgt.TotalType = 2
If you now run a table of age by gender on the weighted data, the results will be the same as in
the table shown above. If, however, you want your weighted total to be 5000, replace these lines
with the following:

Wgt.TotalType = 3
Wgt.WeightedTotal = 5000
425
Base Professional
In the next topic you will learn how to specify target weights using more than one variable in the
weighting matrix and how to specify targets using the names of the categories.
Requirements
More on Target Weighting
This mrScriptBasic example shows how to set up target weighting in a variable, Weight, that must
already exist. You will get an error if you attempt to run the example when this variable does
not exist. (For an example that creates this variable, see Creating a New Variable To Hold the
Weighting Information.) The weighting is based on two variables, age and gender, and is based on
equal proportions of respondents in each cell of the weighting matrix:
Male Female
11-16 years 5 5
17-20 years 5 5
21-24 years 5 5
25-34 years 5 5
35-44 years 5 5
45-54 years 5 5
55-64 years 5 5
65+ years 5 5
Notice that there are 16 cells in the weighting matrix. Here is the mrScriptBasic code to set up
the weighting:
'==========================================================
'
'
'
'==========================================================

' and Weight1b.mrs
Dim MDM2, WgtEng, Wgt, fso, ReptFile, Vars[2]


426
Chapter 1

WgtEng.Initialize(MDM2)
Vars[0] = "age"
Vars[1] = "gender"
Set Wgt = WgtEng.CreateWeight("Weight", Vars, 2)

Wgt.CellRows.Targets = "16 * 5"
Wgt.TotalType = 3
Wgt.WeightedTotal = 5000
WgtEng.Prepare(Wgt)
WgtEng.Execute(Wgt)
ReptFile.Close()
Set WgtEng = Null
MDM2.Close()
Notice that the variables that define the weighting matrix have been specified using an array
variable and that the weighting targets have been specified as "16 * 5". This uses the asterisk (*)
as a convenient shorthand to indicate that all of the 16 cells in the weighting matrix have an
identical target of 5.
Here is a table of age by gender run on the Museum example data weighted using the weight
variable:
427
Base Professional
Now, suppose we want to specify different proportions for each cell in the table:
Male Female
11-16 years 1 2
17-20 years 2 4
21-24 years 3 6
25-34 years 4 8
35-44 years 5 10
45-54 years 6 12
55-64 years 7 14
65+ years 8 16
To specify this, we need to replace the Wgt.CellRows.Targets = "16 * 5" line with the following:
Wgt.CellRows[0].Targets = "1; 2"

Each CellRow object in the CellRows collection corresponds to one row in our weighting matrix.
The order in which you specify the variables that are being used to define the weighting in the
CreateWeight method, defines how the weighting matrix table is oriented. In this example,
age was specified first and gender second, and so there are eight CellRow objects, each one
corresponding to a category of the age variable. If we had specified gender first and age second,
there would be two CellRow objects—one for the Male category and one for the Female category
of the gender variable.
Here is a table of age by gender run on the weighted data.

428
Chapter 1
Sometimes you may want to set the same target for most, but not all, of the cells in the weighting
matrix. You can do this by first specifying the same target for all of the cells in the weighting
matrix and then specifying the targets for any individual cells that differ. For example:

When you are setting up weighting in a DMS file, you can specify the cells in the matrix using the
names of the categories. For example, we could specify the same weighting using the category
names as follows:
Wgt.CellRows[{e2534_years}].Cells[{Male}].Target = "4"
Wgt.CellRows[{e2534_years}].Cells[{Female}].Target = "8"
Wgt.CellRows[{e5564_years}].Cells[{Male}].Target = "5"
Wgt.CellRows[{e5564_years}].Cells[{Female}].Target = "6"
You can also use this method when you run a standalone .mrs script in using the /m: option to
specify the .mdd file. This means that the MDM Document is automatically created as an intrinsic
variable (called MDM) in the script, so you would need to remove the line that creates the MDM
object: Set MDM = CreateObject("MDM.Document").
If the main example, in which there is only one variable in the weighting matrix, in the previous
topic was in a DMS file, we would specify it like this:
Wgt.CellRows[0].Cells[{Male}].Target = "301"
Wgt.CellRows[0].Cells[{Female}].Target = "301"
You can use a filter to exclude cases from the weighting process. When you do this, the value in the
variable that is being used to record the weights (Weight in these examples) will be unchanged for
any cases that do not pass the filter. You create the filter using the Weight.FilterExpression property.
You can use any expression that is supported by the IBM® SPSS® Data Collection Data Model.
For example, the following two lines are equivalent and would exclude from the weighting
calculation any cases in the 11-16 years category of the age variable.
Wgt.FilterExpression = "Not age.ContainsAll({e1116_years})"
Wgt.FilterExpression = "Not (age >= {e1116_years})"
The first line uses the function, which is part of the IBM SPSS Data Collection Function Library
that comes with the Data Model. The second line uses the equivalent . See and for more
information.
Requirements

429
Base Professional
Factor Weighting Example
Defining factor weighting is similar to defining target weighting, except that you specify the actual
weighting factors instead of the target figures. For example, suppose you want to create weighting
that is based on an equal balance between male and female respondents and you have already
calculated the weighting factors that need to be applied as:
Gender Weight
Male 0.8879
Female 1.1445
To define this weighting, you need to change only two lines in the example script in Simple Target
Weighting Example. First, you would need to change the third parameter of the CreateWeight
method to specify that we want factor weighting:
Set Wgt = WgtEng.CreateWeight("weight", "gender", 1)
Second, you need to specify the factors instead of the targets:

Wgt.CellRows.Factors = "0.8879; 1.1445"
An example of factor weighting is included with the IBM® SPSS® Data Collection Developer
Library as a sample script called Weight4.mrs.
Requirements
Rim Weighting Example
In the target weighting examples in the previous topics, we have known the targets for each cell
in the weighting matrix. You use rim weighting when you do not have this information. For
example, when you want to base your weighting on the following information:
A 50:50 balance of male and female respondents (gender variable).
A 75:25 balance of respondents who live in this country and those who do not live in this
country (resident variable)
Targets for the various age groups as shown in the following table (age variable).
Age group Target
11-16 years 50
17-20 years 100
21-24 years 100
25-34 years 200
35-44 years 100
45-54 years 50
55-64 years 30
65+ years 15
430
Chapter 1
Here is the mrScriptBasic code to set up the weighting in a variable, Weight, that must already
exist. You will get an error if you attempt to run the example when this variable does not exist.
(For an example that creates this variable, see Creating a New Variable To Hold the Weighting
Information.)
'==========================================================
'
'
'
'==========================================================

' and Weight1b.mrs
Dim MDM2, WgtEng, Wgt, fso, ReptFile



WgtEng.Initialize(MDM2)
Set Wgt = WgtEng.CreateWeight("Weight", "gender, age, resident", 3)

Wgt.Rims["gender"].Targets = "50; 50"

Wgt.Rims["age"].Targets = "50; 100; 100; 200; 100; 50; 30; 15"
Wgt.Rims["resident"].RimElements[0].Target = "75"
Wgt.TotalType = 2
WgtEng.Prepare(Wgt)
WgtEng.Execute(Wgt)
ReptFile.Close()
Set WgtEng = Null
431
Base Professional
MDM2.Close()
In the line Set Wgt = WgtEng.CreateWeight("Weight", "gender, age, resident", 3), 3 defines the
weighting method as rim weighting.
The line Wgt.TotalType = 2 specifies that the weighted total should be based on the unweighted
total. If we had not included this line, the weighted total would have been set to 100, which is the
sum of the targets defined for the first variable specified (gender).
Here is a table of resident by gender run on the Museum example data weighted using the
weight variable:
There are a number of options that are specific to rim weighting. For example, by default, the
weighting report shows the weights that are calculated by the final iteration of the rim weighting
algorithm. However, you can make it report the weights that are calculated by each iteration
by including the following line in your script:
Wgt.RimReportInDetail = True
Requirements
Setting Up Weighting in a DMS File
This topic shows a DMS file that sets up the Weight variable and the target weighting shown in
Simple Target Weighting Example. Notice that the Weight metadata and case data variable is
defined in the Metadata Section using one line of mrScriptMetadata code. You do not need to
explicitly define the case data variable because IBM® SPSS® Data Collection Base Professional
automatically synchronizes the output case data with the output metadata.
Note that you must not call the Initialize method when you set up the weighting in a DMS file
because Base Professional automatically initializes the weight engine with the output metadata.
You will get an error if you call the Initialize method in a DMS file.
432
Chapter 1
Note that to close the database connection and flush any pending data updates at the end of the
Event section, you must set Wgt to null. This can either be done explicitly by saying WgtEng =
null, or implicitly by making it go out of scope. Also, there is a known issue that Wgt.Report must
be accessed in some way once Wgt has been created with CreateWeight(); otherwise the database
connection is still not closed even is you have correctly set WgtEng = null.
' In the Metadata section, create a numeric variable called "Weight"

' to hold the weighting information...

Weight "Weighting based on gender balance"
Double usagetype("Weight");
End Metadata
' In the OnJobEnd event, use the Weight component to set up weighting
' and write a weighting report...
Event(OnJobEnd, "Weight the data")

Dim WgtEng, Wgt, fso, ReptFile
' Create an html file to contain the weighting report...

Set ReptFile = _
fso.CreateTextFile("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\WeightingReport.htm", _
True)
' "Weight" is the variable of type Double that was created in the
' metadata section.
' "gender" is the variable that stores the characteristics on
' which we wish to base the weighting.
' wtMethod.wtTargets defines the weighting method as target weighting.
' Define a two cell weighting matrix with a target of 301 for
' each value of the gender variable...
' Call the WeightEngine.Prepare method and then write the

' weighting report to the html file...
WgtEng.Prepare(Wgt)
' Call the WeightEngine.Execute method, which will insert the

' calculated weight values in the Weight variable. Then
' write the weighting report to the html file...
433
Base Professional
WgtEng.Execute(Wgt)
ReptFile.Close()
' Setting WgtEng to Null ensures that the connection to the

' output data source is closed and that any pending data
' updates are flushed...
set WgtEng = Null

End Event
' The input data source is the museum.ddf sample

' data set...
End InputDataSource
' The output data source...
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Weighting.ddf"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\Weighting.mdd"
Note: This example is provided as a sample DMS file (called Weighting.dms) that is installed
Requirements
Creating New Variables

It is easy to define new variables in a DMS file. For example, you can create categorical variables
from numeric variables, Boolean variables for use as filters, banner variables to use during
crosstabulations, etc.
This section provides some examples of creating different types of variables.

1. Creating a Categorical Variable From a Numeric Variable
2. Creating a Numeric Variable to Store the Total Number of Questions Answered
3. Creating Filter Variables
434
Chapter 1
4. Creating “Total Awareness” Variables

5. Creating Banner Variables
6. Creating Nets
7. Adding Categories to Existing Variables
Note that the examples in this section are included in the NewVariables.dms sample DMS file that
Requirements
1. Creating a Categorical Variable From a Numeric Variable
When you analyze numeric data, you will sometimes want to group the numeric values into
categories. For example, you may want to analyze age data in age groups even when respondents
are asked to enter their age as a numeric value. It is easy to create a categorical variable from a
numeric variable in a DMS file. This process is sometimes called banding and each category
created from the numeric variable is called a band.
This topic shows two ways of doing this: using an expression in the metadata and setting up the
case data in the OnNextCase Event section.
Note: When using IBM® SPSS® Data Collection Survey Tabulation 2 and IBM SPSS Data
Collection Survey Reporter Professional to analyze your data, you can tabulate your numeric
variables without creating derived categorical variables based on them. To do this, you simply
define an axis expression to be used. If you want to save an axis expression in the metadata, you
can define it in the Metadata section of your DMS files. For more information, see the topic
Creating Axis Expressions and Exporting to IBM SPSS Statistics on p. 456.
Using an expression in the metadata
Variables that are defined in the metadata using an expression are known as dynamically derived
variables and do not actually exist in the case data. After they have been defined in the metadata,
they can be queried through the Case IBM® SPSS® Data Collection Data Model just like any
other variable, but the return values are calculated “on the fly”. Generally the term “derived
variable” is used to mean a dynamically derived variable.
However, with one exception, IBM® SPSS® Data Collection Base Professional always converts
dynamically derived variables defined in the Metadata section of a DMS file into standard
variables that exist in both the case data and the metadata. Because these variables are based on
other variables, they are sometimes called persisted derived variables. Base Professional does
this conversion because dynamically derived variables are not understood by other products,
such as SPSS, IBM® SPSS® Quantum™, and Excel. Because Base Professional automatically
persists the dynamically derived variable, the output data source contains case data for these
435
Base Professional
variables (so that you can use them in any suitable product) and the expressions are removed from
the variables in the output metadata.
The exception is that when you are using the UseInputAsOutput option, Base Professional does
not convert the dynamically derived variables to standard variables. This has the advantage
that the dynamically derived variables will automatically include any additional case data
records that are added to the data source and is not a disadvantage because you cannot use the
UseInputAsOutput option to set up metadata in SPSS and Quantum data.
Here is the Metadata Section in a DMS file that creates a dynamically derived categorical variable
from the visits numeric variable in the Museum sample data set. Notice that each category has
the expression keyword and an expression that specifies which values of the visits variable
correspond to the category.
Metadata(ENU, Question, Label, "myInputDataSource")

TotalVisits1 "Number of previous visits derived variable" categorical [1..1]
{Band1 "None" expression("visits = 0"),
Band2 "1-5 visits" expression("visits > 0 and visits < 6"),
Band3 "6-10 visits" expression("visits > 5 and visits <= 10"),
Band7 "More than 70" expression("visits > 70")
};
End Metadata
Setting up the case data in the OnNextCase Event section
Another way of setting up a derived variable is to set up the metadata in the Metadata Section
and the case data in the OnNextCase Event Section . However, note that setting up the case data
in the OnNextCase Event section is generally slower than using expressions in the Metadata
section, because the OnNextCase Event section code is executed separately for each individual
case data record.
Here is the Metadata Section. Notice that this time the categories do not have the expression
keyword because we will set up the case data in the OnNextCase Event Section.
Metadata(ENU, Question, Label, myInputDataSource)

TotalVisits2 "Number of previous visits persisted derived variable"
categorical [1..1]
{Band1 "None",
Band2 "1-5 visits",
Band3 "6-10 visits",
Band7 "More than 70"
};
End Metadata
436
Chapter 1
Here is the mrScriptBasic code for the OnNextCase Event Section. This code uses a statement to
test the value of the response in the visits variable. This avoids the use of multiple statements.
The code assigns the categorical variable a value according to the value of the response in the
visits variable.
Event(OnNextCase, "Set up the case data")

Select Case visits
Case NULL
TotalVisits2 = NULL
Case 0
TotalVisits2 = {Band1}
Case 1 To 5
Case 6 To 10
Case 11 To 20
Case 21 To 40
Case 41 To 70
Case > 70
End Select
End Event
Note that you can use multiple expressions or ranges in each Case clause. For example, the
following tests for nonconsecutive values:
Case 1 To 3, > 8
Note that the examples in this topic are included in the NewVariables.dms sample DMS file that
Requirements
2. Creating a Numeric Variable to Store the Total Number of Questions Answered
Like the second example in 1. Creating a Categorical Variable From a Numeric Variable, the case
data for the variable in this example is set up in the OnNextCase Event section. However, this
time it is a numeric (Long) variable that stores the number of questions that have been answered.
Here is the Metadata Section, which creates the numeric variable in the output metadata:

QuestionsAnswered "Number of questions answered" long;
End Metadata
437
Base Professional
Here is the mrScriptBasic code for the OnNextCase Event Section. This code uses a loop and
a procedure to count the number of questions that have been answered (or more precisely, the
number of variables that store responses).
Dim Question
For Each Question in dmgrQuestions

QuestionsAnswered = QuestionsAnswered + GetQuestionAnsweredCount(Question)
Next
Function GetQuestionAnsweredCount(Question)
If Question.Count > 0 Then
Dim Counter
For Counter = 0 to Question.Count - 1
GetQuestionAnsweredCount = GetQuestionAnsweredCount + GetQuestionAnsweredCount(Question[Counter])
Next
Else
If Question IS NOT NULL Then
GetQuestionAnsweredCount = 1
Else
GetQuestionAnsweredCount = 0
End If
End If
End Function
End Event
Requirements
3. Creating Filter Variables
You use filters during analysis to select a subset of the case data. For example, if you want to
create a table that includes only female respondents, you would filter on the Female category of
the Gender variable. You can use the DMS file to set up filters as Boolean variables, which can
then be reused as filters. This is particularly useful when the same filters will be required again
and again and when the analysis requires the use of filters that are based on complex expressions.
Typically, you set up Boolean variables for use as filters as dynamically derived variables. You do
this in the Metadata Section using the expression keyword. For example, the following Metadata
section creates a Boolean variable that could be used to select female respondents between the
ages of 11 and 34:
YoungWomen1 "Young women filter - dynamically derived" boolean
438
Chapter 1
expression ("Gender = {Female} And Age * {E1116_years, E1720_years, E2124_years, E2534_years}");

End Metadata
You can also create the Boolean variable without the expression keyword in the Metadata Section
and set up the case data in the OnNextCase Event Section. However, note that setting up the
case data in the OnNextCase Event section is generally slower than using an expression in the
Metadata section, because the OnNextCase Event section code is executed separately for each
individual case data record.
YoungWomen2 "Young women filter - persisted derived" boolean;
End Metadata

If gender = {Female} Then
If Age * {E1116_years, E1720_years, E2124_years, E2534_years} Then
YoungWomen2 = True
Else
YoungWomen2 = False
End If
Else
YoungWomen2 = False
End If
End Event
Working with Null values
When evaluating a dynamically derived Boolean variable whose expression is based on a

comparison operator, the IBM® SPSS® Data Collection Data Model assigns a value of False to
any cases for which the expression does not evaluate to True. This happens even when the value
being compared in the case data is Null, because the Data Model uses the SQL-92 ANSI standard
when a comparison operator is used with a Null value. See for more information.
A Null value in the case data typically means that the respondent was not asked the question. This
is unlikely to be an issue in the YoungWomen1 example, because generally all respondents are
asked the demographic questions on which the expression is based.
However, sometimes you may want to base a Boolean variable on a question that some
respondents were not asked. For example, in the Museum survey, the remember question was
asked only if the respondent was interviewed as he or she left the museum. Suppose we want to
base a Boolean variable on this variable to select respondents who remember seeing the Fossils
gallery. If we simply define the expression as remember >= {fossils}, the Boolean variable will
have a False value for all respondents regardless of whether they were asked the question or not.
This could lead to misleading results if, for example, we were to use the Boolean variable to
calculate the percentage of people who remembered the Fossils gallery.
You can avoid this problem, set the value of the Boolean variable to Null for cases for which the
remember variable has a Null value. For example:
RememberFossils "People who remember seeing fossils" boolean
439
Base Professional
expression ("IIf(remember IS NULL, NULL, remember >= {Fossils})");

End Metadata
Requirements
4. Creating “Total Awareness” Variables
Market research surveys frequently ask respondents to:

Name their favorite brand of a product (such as washing powder).
Name any other brands of the product they can remember.
Look at a list of brands of the product and say which ones they have heard of or used before.
Typically the category lists for each of these questions are identical. The first of these questions is
typically a single response question, the second question (known as a spontaneous awareness
question) and the third question (known as a prompted awareness question) are typically
multiple response questions.
It often useful to create a “total awareness” variable that combines the responses to the three
questions for use during analysis.
The Museum survey does not contain questions of exactly this type. However, it has a single
response question called Interest, which asks respondents to say which gallery they found most
interesting and a multiple response question called Remember, which asks respondents to select
all of the galleries they remember viewing. Both questions have identical category lists and we
will use them in the following example to illustrate how to set up a total awareness variable.
The example shows setting up a total awareness type of categorical variable in the Metadata
Section. The variable is created as a derived categorical variable using a single expression
that uses the function in the IBM SPSS Data Collection Function Library to combine the two
categorical variables. Notice that no categories are specified. This means that the categories will
be generated automatically based on the categories in the variables in the expression. In addition,
the Union function will generate categories even if the value of Remember or Interest is NULL
(which means that the question was not asked).

TotalAwareness "Most interesting gallery and all galleries remembered"
categorical [..]
expression ("Union (remember, interest)");
End Metadata
440
Chapter 1
Note that the category lists in the variables you are combining do not have to be identical. You
can create a derived variable that is the combination of two or more categorical variables that
have different or overlapping category lists.
The example in this topic is included in the NewVariables.dms sample DMS file that is installed
Requirements
5. Creating Banner Variables
During analysis, you may sometimes want to create a number of crosstabulations using the same
variables on the top of the table. This is sometimes called the banner or breakdown and is
typically a combination of demographic variables. You can use the DMS file to create a derived
variable to use as the banner in your analysis. For example, the following creates a dynamically
derived variable called AgeGender from the Gender and Age variables for use as a banner
during analysis.

AgeGender "Age and gender banner variable"
categorical
expression ("gender + age");
End Metadata
Like the total awareness example in the previous topic, the derived variable is defined using a
single expression that uses the union (+) operator to combine the two categorical variables. Notice
that no categories are specified. This means that the categories will be generated automatically
based on the categories in the variables in the expression.
Note that this example is included in the NewVariables.dms sample DMS file that is installed
Requirements
6. Creating Nets
Sometimes you may want to create net elements in a multiple response variable to show the
number of respondents who chose one or more categories in a group of categories. In a single
response variable a net is the same as a subtotal, which shows the number of responses.
441
Base Professional
You can create a net element anywhere in a categorical variable, however, they are generally
placed immediately before or after the categories to which they refer. The following example
creates a derived categorical variable based on the Remember multiple response variable.

RememberWithNets "Galleries remembered with nets"
categorical
{ExtinctLife "Extinct life forms and evolution"
expression ("remember * {Dinosaurs, Fossils, Evolution, Origin_of_species}"),
Dinosaurs "Dinosaurs"
expression ("remember * {Dinosaurs}"),
Fossils "Fossils"
expression ("remember * {Fossils}"),
Evolution "Evolution"
expression ("remember * {Evolution}"),
Origin_of_species "Origin of species"
expression ("remember * {Origin_of_species}"),
CurrentLife "Current life forms"
expression ("remember * {Fish_and_reptiles, Whales, Birds, Insects, Mammals, Botany, Human_biology}"),
Fish_and_reptiles "Fish and reptiles"
expression ("remember * {Fish_and_reptiles}"),
Whales "Whales"
expression ("remember * {Whales}"),
Birds "Birds"
expression ("remember * {Birds}"),
Insects "Insects"
expression ("remember * {Insects}"),
Mammals "Mammals"
expression ("remember * {Mammals}"),
Botany "Botany"
expression ("remember * {Botany}"),
Human_biology "Human biology"
expression ("remember * {Human_biology}"),
Theory "Theoretically themed exhibits"
expression ("remember * {Conservation, Ecology, Wildlife_in_danger}"),
Conservation "Conservation"
expression ("remember * {Conservation}"),
Ecology "Ecology"
expression ("remember * {Ecology}"),
Wildlife_in_danger "Wildlife in danger"
expression ("remember * {Wildlife_in_danger}")};
End Metadata
The next topic, 7. Adding Categories to Existing Variables, shows you how to add categories to
existing variables. You could use a similar technique to add nets to an existing variable.
442
Chapter 1
Requirements
7. Adding Categories to Existing Variables
Sometimes you may want to add categories to variables that already exist in the metadata. For
example, the Museum sample data set has a variable called Museums that records which other
museums and galleries the respondent has visited. The following example shows how you could
add new categories to this variable.
When you run the DMS file, IBM® SPSS® Data Collection Base Professional merges the new
categories defined in the Metadata with the categories in the existing variable. If the definitions
conflict, the definition in the existing metadata is taken as the master. Note that in the merged
metadata, the categories defined in the Metadata section will always appear after the existing
categories.

museums "Museums and galleries visited or plans to visit"
categorical
{Museum_of_space "Exploration of Space Museum",
Modern_Art "Gallery of Modern Art"};
End Metadata
When you use this technique for adding categories to existing variables, make sure that you spell
the name of the variable correctly and that you do not change the variable’s type. If you spell the
name differently in the Metadata section, Base Professional will create a new variable. However,
you will get an error if you specify an existing variable’s name but with a different type keyword.
For example, you will get an error if the existing variable is defined as a numeric variable and you
specify a categorical variable of the same name in the Metadata Section.
Requirements
Analyzing a Tracking Study

A tracking study is a survey that is used to monitor change over time. This type of survey is
typically carried out as a series of “waves”, where each wave consists of one or more collections
of response data. This section describes how you can use data management scripting and other
IBM® SPSS® Data Collection and IBM Corp. technologies to analyze the response data from
your tracking studies. The data management scripts described are included with the IBM® SPSS®
Data Collection Developer Library so that you can run them yourself.
443
Base Professional
Analyzing the response data from a tracking study often includes coding open-ended responses
into categories and adding weights to the data. Reports are typically run against copies of the
live data and might include reports for the wave that is currently in progress and reports for
all completed waves.
The Analysis Process
The process described in this section uses the following products and technologies:
Responses are collected using IBM® SPSS® Data Collection Interviewer Server.
IBM® SPSS® Text Analytics for Surveys is used to code open-ended responses.
Data management scripting is used to transfer data, merge data, and weight the data using the
Data Collection Weight component.
IBM® SPSS® Data Collection Survey Tabulation is used to run reports.
However, you should be able to adapt the process to suit your own needs. For example, you
might want to use a manual-coding tool instead of SPSS Text Analytics for Surveys, or your
survey might not require any coding.
The process uses three main data sources:

The live data, which is stored in an Interviewer Server database.
The Wave database, which is created by a data management script and contains coded and
weighted responses for the current wave of the survey.
The Report database, which is created and updated by data management scripts and contains
coded and weighted responses for all complete waves.
444
Chapter 1
The following diagram shows the data flow for the process:
445
Base Professional
When Coding is not Required
Some tracking studies do not include open-ended responses or do not require them to be coded.
This section also describes an alternative process that only adds weights to the data. The following
diagram shows the data flow for this process:
Processing a Wave that Requires Coding
Each wave that requires coding is processed as follows:

IBM® SPSS® Text Analytics for Surveys or another coding tool is used to code open-ended
responses into categories and export the coded data to IBM® SPSS® Statistics (.sav) file.
A data management script is used to merge the coded data with the original (live) IBM®
SPSS® Data Collection Interviewer Server data and create a separate database for reporting
purposes. The data management script will also add weights to the merged data. The new
database is called the Wave database, as it contains data for the current wave only.
There is an additional step if more than one coder is working on your survey: all coded data must
be brought together into a single file (by running another data management script) before it is
merged with the original Interviewer Server data.
Depending on your reporting requirements, you can perform the process once at the end of each
wave or, if your waves consist of more than one data collection, you can perform the process
at the end of each data collection.
Note: By default, the scripts referred to in the steps below are installed in folder
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS.
446
Chapter 1
To Process a Wave
If you intend to use an alternative coding tool to SPSS Text Analytics for Surveys, see Using
Other Coding Tools for more information about creating the required .sav file, and then start
from step 4 once you have created your file.
1. Start SPSS Text Analytics for Surveys and import your Interviewer Server data.
2. When the SPSS Text Analytics for Surveys “Select Variables” dialog box opens, select
Respondent.Serial as the Unique ID.
3. Select the open-ended texts that you want to code and create categories for them1. Then export the
coded data to a .sav file. For more information about these tasks, see the SPSS Text Analytics
for Surveys documentation.
4. If your coded data has been exported to more than one .sav file (because more
than one coder is working on your survey), edit the data management script called
TrackingStudy-MergeSAVFiles.dms so that it contains one InputDataSource section for each .sav
file. Then run the script to merge the files into a single .sav file.
5. Edit the #define statements in script TrackingStudy-Settings.mrs, as follows:

#define statement Description
MyWaveNumber The number of the current wave. You must set this
to 1 for the first wave.
UsingSameLiveDatabase If the current wave has been collected in the same
Interviewer Server database (that is, the same
Interviewer Server project) as the previous wave,
set this to True. Otherwise, set this to False. Note
that this setting is ignored for the first wave.
INTDB The name of the Interviewer Server database that
contains the live data.
INTDBMDD The metadata document (.mdd) file associated with
the Interviewer Server database.
INTDBSRVR The database server hosting the Interviewer Server
database.
SAVFILE The name of the .sav file exported by SPSS Text
Analytics for Surveys or another coding tool,
excluding the “.sav” extension. If you ran the script
TrackingStudy-MergeSAVFiles.dms in step 4, enter
the name of the .sav file output by that script.
WAVDB The name of the Wave database.
WAVDBMDD The metadata document (.mdd) file that will be
associated with the Wave database.
WAVDBSRVR The database server that will host the Wave
database.
RPTDB The name of the Report database.
RPTDBMDD The metadata document (.mdd) file that will be
associated with the Report database.
447
Base Professional

RPTDBSRVR The database server that will host the Report
database.
ISQLPATH The location of isql.exe (the SQL Server command
prompt utility) on your system. If your are using
the SQL Server 2005 client tools, the location of
sqlcmd.exe on your system.
6. Run the mrScriptBasic script called TrackingStudy-CreateMDD.mrs, which will create a metadata
document (.mdd) file that will be used in the next step.
7. Edit the data management script called TrackingStudy-CreateWaveDB.dms and amend both the
Metadata section and the OnJobEnd event section to set up weighting as required. Then run the
script, which will drop the Wave database if it already exists and then merge the coded data in the
.sav file with your original (live) Interviewer Server data and output the merged data to a new
Wave database. (The script also adds a categorical variable called Wave to each record on the
Wave database; this is intended to be of use later when the data is copied to the Report database.)
The Wave database now contains the coded and weighted data for the current wave, which might
be complete or still in the data collection phase if the wave consists of more than one data
collection. You can tabulate the data using IBM® SPSS® Data Collection Survey Tabulation.
1 Note that if you select a text question that also includes special-response categories such as
“Don’t Know” and “Refuse to Answer”, the process of merging the coded data with the original
text variable will mean that the case data for those special responses will be missing from the
Wave and Report databases.
Processing a Wave that Doesn’t Require Coding
For each wave that doesn’t require coding, a data management script is used to transfer the original
(live) IBM® SPSS® Data Collection Interviewer Server data to a new database for reporting
purposes. The data management script will also add weights to the data. The new database is
called the Wave database, as it contains data for the current wave only.
Depending on your reporting requirements, you can perform the process once at the end of
each wave or, if your waves consist of more than one data collection, you can perform the process
at the end of each data collection.
Note: By default, the scripts referred to in the steps below are installed in folder
To Process a Wave
1. Edit the #define statements in script TrackingStudy-Settings.mrs, as follows:

MyWaveNumber The number of the current wave. You must set this
to 1 for the first wave.
448
Chapter 1

UsingSameLiveDatabase If the current wave has been collected in the same
Interviewer Server database (that is, the same
Interviewer Server project) as the previous wave,
set this to True. Otherwise, set this to False. Note
that this setting is ignored for the first wave.
INTDB The name of the Interviewer Server database that
contains the live data.
INTDBMDD The metadata document (.mdd) file associated with
the Interviewer Server database.
INTDBSRVR The database server hosting the Interviewer Server
database.
SAVFILE This statement can be ignored.
WAVDB The name of the Wave database.
WAVDBMDD The metadata document (.mdd) file that will be
associated with the Wave database.
WAVDBSRVR The database server that will host the Wave
database.
RPTDB The name of the Report database.
RPTDBMDD The metadata document (.mdd) file that will be
associated with the Report database.
RPTDBSRVR The database server that will host the Report
database.
ISQLPATH The location of isql.exe (the SQL Server command
prompt utility) on your system. If your are using
the SQL Server 2005 client tools, the location of
sqlcmd.exe on your system.
2. Edit the data management script called TrackingStudy-CreateWaveDB-WeightsOnly.dms and

amend both the Metadata section and the OnJobEnd event section to set up weighting as required.
Then run the script, which will drop the Wave database if it already exists and then transfer your
original (live) Interviewer Server data to a new Wave database. (The script also adds a categorical
variable called Wave to each record on the Wave database; this is intended to be of use later
when the data is copied to the Report database.)
The Wave database now contains the weighted data for the current wave, which might be complete
or still in the data collection phase if the wave consists of more than one data collection. You can
tabulate the data using IBM® SPSS® Data Collection Survey Tabulation.
Completing a Wave
When the data collection is complete for the current wave of your tracking study and your Wave
database contains all the responses for the current wave, you must transfer the data on the Wave
database to the Report database. This frees the Wave database to be used for the next wave.
449
Base Professional
The procedure to do this is different for the first wave as compared with subsequent waves,
because the Report database will not exist at the end of the first wave and therefore has to be
created:
At the end of the first wave, run the data management script called
TrackingStudy-CreateReportDB.dms. This will create the Report database,
transfer the data from the Wave database to the Report database and then create a new
metadata version in the Metadata Document (.mdd) file associated with the Report database.
The version description will be set to “Wave 1”.
At the end of the second or later wave, run the data management script called
TrackingStudy-UpdateReportDB.dms. This will add the data on the Wave database to the
Report database and then create a new metadata version in the Metadata Document (.mdd) file
associated with the Report database. The version description will be set to “Wave n”, where n
is the wave number. Because this script changes the existing Report database irreversibly,
take a backup of the Report database before running the script.
The Report database now contains the coded (if coding was performed) and weighted data for
all the completed waves of your tracking study. You can tabulate the data using IBM® SPSS®
Data Collection Survey Tabulation. In addition, each record includes a categorical variable called
Wave, which you can use to identify the wave in which the response was collected.
Note: By default, the .dms scripts referred to above are installed in folder
Completing the Study
When all waves of your tracking study are complete and your Report database contains the
responses for all waves, you might want to weight the data for the whole survey. To do this,
edit the data management script called TrackingStudy-WeightAllWaves.dms and amend both the
Metadata section and the OnJobEnd event section to set up weighting as required. Then run the
script to add the weights.
Because this script changes the existing Report database irreversibly, take a backup of the Report
database before running the script.
Note: By default, the .dms script referred to above is installed in folder
Using Other Coding Tools
If you normally use a coding tool other than IBM® SPSS® Text Analytics for Surveys, you can
still make use of the IBM® SPSS® Data Collection scripts provided for this analysis process,
provided that your coding tool is able to save your coded data to a .sav file. To avoid having to
make significant changes to the scripts, the format of your .sav file must match the format of the
.sav file created by SPSS Text Analytics for Surveys, which is as follows:
Each coded question must be saved as a multiple dichotomy set, which contains one numeric
variable for each category that you defined for that question. Each numeric variable must have
two value labels only: “Yes” which corresponds to a value of 1, and “No” which corresponds
450
Chapter 1
to a value of 0. For every record in the case data, each numeric variable must be set to 1 to
specify that the category is selected or 0 to specify that the category is not selected.
The name of the multiple dichotomy set must be the same as the original variable in the
IBM® SPSS® Data Collection Interviewer Server survey. For example, the name might be
FavoriteMovie for a text question, or CoffeeBrands.Other for an “other specify” open-ended
response to a categorical question.
The respondent’s serial number must be saved to a numeric variable called Respondent.Serial,
which should not have any value labels. The value must match the value in the Interviewer
Server data.
Any other variables in the .sav file will be ignored, provided that their names do not match the
names of variables in the Interviewer Server data.
To use the .sav file that you have created, follow the steps in Processing a Wave that Requires
Coding.
Sample Scripts Used
The following scripts are used in the analysis process:

TrackingStudy-CreateMDD.mrs. Creates a metadata document (.mdd) file that is used as the
metadata source for the IBM® SPSS® Statistics (.sav) file that was exported by IBM® SPSS®
Text Analytics for Surveys or another coding tool.
TrackingStudy-CreateReportDB.dms. Creates the Report database and transfers the data from the
Wave database to the Report database. Run this script after the first wave only. For subsequent
waves, use TrackingStudy-UpdateReportDB.dms.
TrackingStudy-CreateWaveDB.dms. Merges the coded data from SPSS Text Analytics for Surveys
or another coding tool with the original (live) IBM® SPSS® Data Collection Interviewer Server
data and outputs the data to the Wave database. Also adds weights to the data.
TrackingStudy-CreateWaveDB-WeightsOnly.dms. Transfers the original (live) Interviewer
Server data to the Wave database and adds weights to the data. Run this script instead of
TrackingStudy-CreateWaveDB.dms if your tracking study doesn’t require any coding of
open-ended responses.
TrackingStudy-MergeSAVFiles.dms. Merges several SPSS Statistics (.sav) files into a single .sav
file. This script is required if there is more than one coder working on the survey and each coder
has exported a separate .sav file from SPSS Text Analytics for Surveys or another coding tool.
TrackingStudy-Settings.mrs. Contains settings, such as the current wave number, that are used
by the other scripts in the process.
TrackingStudy-UpdateReportDB.dms. Adds the data on the Wave database to the Report database.
TrackingStudy-WeightAllWaves.dms. Weights the data for the whole survey. Run when the data
collection phase of the survey has finished.
Note: By default, these scripts are installed in folder
451
Base Professional
Table Scripting in a Data Management Script

If you have IBM SPSS Data Collection Survey Reporter Professional, you can use data
management script (.dms) files to create tables. This section covers the aspects of table scripting
that are specific to data management scripts and provides some examples of data management
scripts that create tables. For full documentation on creating tables using the IBM® SPSS® Data
Collection Base Professional Tables Option, including a tutorial and detailed reference material on
the Table Object Model, see the main Table Scripting section.
This section assumes a basic understanding of table scripting, such as can be obtained by working
through the Table Scripting Tutorial. For more information, see the topic Getting Started on p.
1142.
The examples in this section are available as sample data management script files that come with
the IBM® SPSS® Data Collection Developer Library. For more information, see the topic Table
Scripting Sample Data Management Scripts on p. 478.
Creating Tables Using a Data Management Script
When you create tables using a data management script, you generally use the OnAfterJobEnd
Event section, where the dmgrJob.TableDocuments property gives you access to a collection of
Table Document objects, one for each suitable output data source.
Here is a simple example that exports the Museum sample data set to an RDB database. It includes
an OnAfterJobEnd Event section that sets up a simple crosstabulation (Age by Gender), a grid table
for the Rating grid question, and a frequency table for the Education question. It then populates the
tables, saves them as an .mtd file, and exports them (along with a chart for each table) to HTML:
Dim TableDoc
Set TableDoc = dmgrJob.TableDocuments["RDBOutput"]
With TableDoc.Tables
' Create a table of Age by Gender
.AddNew("AgeByGender", "age * gender", "Age by Gender")
' Create a grid table for the Rating grid question

.AddNewGrid("RatingGrid", "rating", , "Rating Grid Table")
' Create a frequency table for the Education question

.AddNew("Education", "education", "Frequencies in full-time education")
' Add cumulative column percentages to the cell contents for the
' Educuation table
.Education.CellItems.AddNew(CellItemType.itCumColPercent)
End With
' Save the tables document

TableDoc.Save("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\TablesFirstScript.mtd")
452
Chapter 1
' Populate the tables

TableDoc.Populate()
' Export the tables

With TableDoc.Exports["mrHtmlExport"]
.Properties["Interactive"] = True
.Properties["LaunchApplication"] = True
.Properties["DisplayOption"] = "Table and Chart"
.Properties["LayoutStyle"] = "Frame Table of Contents"
.Properties["PresentationStyle"] = "Black and White"
.Export("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\TablesFirstScript.htm")
End With
End Event
End InputDataSource
OutputDataSource(RDBOutput)
Location='Provider=SQLOLEDB.1; _
Initial Catalog=TablesFirstScript; _
Data Source=localhost'; _
MR Init Project=TablesFirstScript"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\TablesFirstScript.mdd"
In the OnAfterJobEnd Event section, there are two lines that show the main difference between
creating tables in a data management script (.dms) file and in a standalone mrScriptBasic (.mrs)
file:
Set TableDoc = dmgrJob.TableDocuments["RDBOutput"]
The above line shows how in the OnAfterJobEnd Event section in a data management script you
can use the dmrgJob.TableDocuments property to get access to a table document object for each
output data source that was written using a read-enabled CDSC. This means that you cannot write
scripts to create tables on a non-IBM® SPSS® Data Collection Data Model format output data
source or a IBM® SPSS® Quantum™-format output data source (because the QuantumQuantum
CDSC is write-only).
.Education.CellItems.AddNew(CellItemType.itCumColPercent)
453
Base Professional
The above line uses an enumeration constant to add a new item of cell contents to the Education
table. This is to draw attention to the fact that in a data management script, you can use the
enumeration constants built into the Table Object Model, whereas in a standalone .mrs file, you
must use the equivalent numeric value. For more information, see the topic Creating a Frequency
Table and Defining Cell Contents on p. 1149.
The example shown above is available as a sample file called TablesFirstScript.dms. To run this
sample, you need to have IBM SPSS Data Collection Survey Reporter Professional and access to
an SQL Server installation and appropriate user access rights. Before running the sample, you
need to set up an SQL Server database called TablesFirstScript. If you run this script more than
once, you must delete the records in the database created by the previous run, otherwise the serial
numbers will be duplicated and errors will result. Note that when exporting charts, the HTML
Tables Export component requires Microsoft Office Web Components (OWC) version 10 or
later, which is available from the Microsoft Download Center. If necessary, you can change the
sample to export tables only, by changing the DisplayOption export property to “Table Only”. For
example:
.Properties["DisplayOption"] = "Table Only"
Here is the HTML output:

454
Chapter 1
As mentioned above, you usually create tables in the OnAfterJobEnd Event section. However,
you can also access the Table Document in the same way in the OnJobStart, OnNextCase, and
OnJobEnd Event sections. If you decide to do this, make sure that you do not populate or export
the tables in these sections, because that may lead to an error. Instead, save the tables in an .mtd
file (as shown in the sample above) and then open the .mtd file in the OnAfterJobEnd Event
section, where you can then populate and export the tables. For an example of opening an .mtd file
in a script, see Opening an Existing Table Document in the Table Scripting Tutorial.
For information on sample data management scripts with table scripting sections, see Table
Scripting Sample Data Management Scripts.
Exporting to RDB and Creating Multiple Weighted Tables
In a data management script file, you can use the Weight component to set up weighting, which
you can then use to weight your tables. The TablesWeightingAllFieldsHdata.dms sample provides
an example of doing this. It includes a Metadata section that creates a weighting variable called
Weight and an OnJobEnd Event section that uses the Weight component to define target weighting
similar to that described in More on Target Weighting.
The OnAfterJobEnd Event section then creates multiple tables that are all weighted using the
newly-created Weight variable. This is achieved by defining the weighting variable as the default
weight for the tables like this:
' Set the default weight, so that all new tables are weighted by default
TableDoc.Default.Weight = "Weight"
For an example of setting the weighting on individual tables, see Weighting Tables.
The sample also demonstrates setting up a reusable axis and then creating a table for each suitable
variable in the data set with the reusable axis forming the banner. Here is the script:
' Create an axis that we can reuse
Dim Axis
Set Axis = TableDoc.Axes.AddNew("MyBanner")
Axis.Specification = "Before{.., ^Not_answered}"
' Create tables for all suitable variables

MakeHdataTables(TableDoc, TableDoc.DataSet.MDMDocument.Fields)
Sub MakeHdataTables(TableDoc, Fields)

Dim Field
' Loop through all fields and create tables for all the
' Categorical and Grid variables and any other simple
' variables that have an axis specification stored in the
' metadata
For Each Field In Fields
Select Case Field.ObjectTypeValue
Case ObjectTypesConstants.mtVariable ' Simple variable
If Field.DataType = mr.Categorical Then
455
Base Professional
' It's a categorical variable - create a table

TableDoc.Tables.AddNew("Table" + CText(TableDoc.Tables.Count + 1), _
Field.FullName + " * axis(MyBanner)", Field.Label)
ElseIf Field.AxisExpression.IsEmpty() = False Then
' It's not a categorical variable but it has an axis expression,
' so we can create a table
Field.FullName + " * axis(MyBanner)", Field.Label)
End If
Case ObjectTypesConstants.mtGrid
' It's a grid, so use the AddNewGrid method to create
' a grid table
TableDoc.Tables.AddNewGrid("Table" + CText(TableDoc.Tables.Count + 1), _
Field.FullName, , "Grid: " + Field.Name)
Case ObjectTypesConstants.mtClass, _
ObjectTypesConstants.mtCompound, _
ObjectTypesConstants.mtArray
' Another form of container, process the contents
MakeHdataTables(TableDoc, Field.Fields)
End Select
Next
End Sub
Notice that the MakeHdataTables Sub procedure uses a For Each loop to iterate through all of
the objects in the Fields collection that is passed as a parameter. In the first iteration, this is the
Fields collection of the metadata document and subsequently it is the Fields collection of any
nested Array, Compound, or Class objects. The For Each loop tests each object to determine
the appropriate action:
If the object is a simple categorical variable, it is crosstabulated against the reusable banner.
If the object is a simple variable of any other type and has an axis expression, the variable is
crosstabulated against the reusable banner. For an example of setting up an axis expression in
a data management script file, see Creating Axis Expressions and Exporting to IBM SPSS
Statistics.
If the object is a grid variable, a grid table is created.
If the object is one of the other types of container object, the MakeHdataTables Sub procedure
is called again to process the variables nested inside the container.
To run this sample, you need to have the IBM® SPSS® Data Collection Base Professional Tables
Option and access to an SQL Server installation and appropriate user access rights. Before running
the sample, you need to set up an SQL Server database called TablesWeightingAllFieldsHdata.
If you run this script more than once, you must delete the records in the database created by the
previous run, otherwise the serial numbers will be duplicated and errors will result.
You can modify the TablesWeightingAllFieldsHdata.dms sample to write to any other output data
format, provided that the CDSC you are using is write-enabled (Can Add is True for the CDSC)
and supports a hierarchical HDATA view of the data.
For information on sample data management scripts with table scripting sections, see Table
Scripting Sample Data Management Scripts.
456
Chapter 1
Creating Axis Expressions and Exporting to IBM SPSS Statistics
In IBM® SPSS® Data Collection Survey Tabulation and the IBM® SPSS® Data Collection
Base Professional Tables Option, you can use numeric, text, and date variables in your tables by
defining an axis specification that bands or codes the values into categories. You can define the
axis specification for a variable at the time you create the table. Elements added in this way
are not saved in the metadata. For further information, see Working with Numeric Variables in
the Table Scripting section.
Alternatively, you can save the axis specification in the metadata, and it is used by default when
you subsequently create a table for the variable in Survey Tabulation or using a table script. Axis
specifications that are saved in the metadata are sometimes called axis expressions. You can use
data management scripts to set up axis specifications for variables for use in Survey Tabulation
and Base Professional Tables Option.
Here is a Metadata section that defines axis expressions for a number of variables that already
exist in the input data source. Note that in this example the axis expressions are presented on
multiple lines for clarity. In practice you must specify the axis specification without line breaks.
' Autocode a text variable

address text
axis("{London 'London' expression('address.find(""london"") <> -1'),
Liverpool 'Liverpool' expression('address.find(""liverpool"") <> -1'),
Aberdeen 'Aberdeen' expression('address.find(""aberdeen"") <> -1'),
Leeds 'Leeds' expression('address.find(""leeds"") <> -1'),
Edinburgh 'Edinburgh' expression('address.find(""edinburgh"") <> -1'),
OtherCities 'Other cities' expression('address.find(""london"") = -1
And address.find(""liverpool"") = -1
And address.find(""aberdeen"") = -1
And address.find(""Leeds"") = -1
And address.find(""Edinburgh"") = -1
And Not address.IsEmpty()'),
NotAnswered 'Not answered' expression('address.IsEmpty()')}");
' Band a numeric variable

visits long
axis ("{visits1 '1 to 10' expression('visits > 0 And visits < 11'),
visits2 'More than 10' expression('visits > 10'),
mean 'Mean' mean(visits)}");
' Summarize a numeric variable

adults long
axis ("{min 'Minimum' min(adults),
max 'Maximum' max(adults),
mean 'Mean' mean(adults),
StdDev 'Standard deviation' StdDev(adults)}");

human long
axis ("{NotAtAll 'Not at all interested' expression('human = 1'),
NotParticularly 'Not particularly interested' expression('human = 2'),
NotOpinion 'No opinion' expression('human = 3'),
Slightly 'Slightly interested' expression('human = 4'),
Very 'Very interested' expression('human = 5'),
'Mean' mean(human)}");
End Metadata
When defining axis expressions in the Metadata section, do not include the variable name,
just specify the element list syntax. For more information on defining axis expressions in
mrScriptMetadata, including information on when to use single quotation marks and when to use
457
Base Professional
two double quotation marks, see . For information about the element list syntax, see Element
List Syntax.
You can create tables for these variables in your table script, just like you can for categorical
variables. For example, the TablesDefineAxes.dms sample exports the data to a .sav file and
includes a Metadata section similar to the one shown above and the following OnAfterJobEnd
Event section. This has a CreateTables Sub procedure, which creates tables for the text and
numeric variables for which axis expressions are defined in the Metadata section.

Dim TableDoc
Set TableDoc = dmgrJob.TableDocuments["SavOutput"]
' Create tables for simple variables

CreateTables(TableDoc, TableDoc.DataSet.MDMDocument.Fields)
Sub CreateTables(TableDoc, Fields)

Dim Field
' Create tables for the simple categoricals

' and any other simple variables that have an axis expression
Case ObjectTypesConstants.mtVariable
If Field.DataType = mr.Categorical Then
' It's a categorical variable - add a new table
Field.FullName + " * gender", Field.Label)
ElseIf Field.AxisExpression.IsEmpty() = False Then
Field.FullName + " * gender", Field.Label)
End If
Case ObjectTypesConstants.mtClass, ObjectTypesConstants.mtCompound
If Field.IsSystem = False Then ' Exclude system variables
CreateTables(TableDoc, Field.Fields)
End If
End Select
Next
End Sub

TableDoc.Populate()
' Export the tables

With TableDoc.Exports["mrHtmlExport"]
.Export("C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\TablesDefineAxes.htm")
End With
458
Chapter 1
End Event
Because IBM® SPSS® Statistics has different variable naming rules from the IBM® SPSS® Data
Collection Data Model, the variable names used in the .sav file are often different from those in
the input data source. In addition, sometimes several variables are created in the .sav file for a
single variable in the input data source. When you export data to SPSS Statistics, it is always
best to save the output metadata in a .mdd file and always use this when creating tables. Here
is the OutputDataSource section from the TablesDefineAxes.dms sample, showing that a .mdd
file has been specified in the MetaDataOutputName parameter:
OutputDataSource(SavOutput)
Location=C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\TablesDefineAxes.sav"
MetaDataOutputName = "C:\Program Files\IBM\SPSS\DataCollection\6\DDL\Output\TablesDefineAxes.mdd"
When you access the .sav file using the .mdd file, you can use the familiar input data source
variable names in your script rather than the .sav file variable names. In addition, you can
ignore any differences in variable structure, because the Data Model automatically recombines
variables that have been split into multiple variables in the .sav file. For example, when you run
the TablesDefineAxes.dms sample in Data Model 2.9 or earlier, five variables (called address1
through address5) are created in the .sav file from the address text variable in the input data. This
is because the address variable can contain up to 1024 characters, but .sav file text variables have
a limit of 255 characters in SPSS Statistics 12 and earlier. However, provided you use the .mdd
file when creating your tables, you can access these five variables as if they were one variable
called address.
Here is the table created for the address variable by the script:
The axis specification for the address variable is defined by the axis expression defined in the
Metadata section.
459
Base Professional
Note: The examples in this topic are available in a sample file (called TablesDefineAxes.dms) that
comes with the IBM® SPSS® Data Collection Developer Library. For more information, see the
topic Table Scripting Sample Data Management Scripts on p. 478.
Creating Axis Expressions in the OnBeforeJobStart Event Section
In Creating Axis Expressions and Exporting to IBM SPSS Statistics, we saw an example of setting
up axis expressions in the Metadata section of a data management script. However, sometimes
you may want to use a standard axis expression for a number of variables. For example, you may
want to use the same expression to summarize a number of numeric variables. This is usually
easier using mrScriptBasic rather than mrScriptMetadata. For examples of using this technique in
a standalone .mrs file, see Creating Axis Expressions in Your Script in the Table Scripting section.
If you want to use this technique in a data management script, you would typically do it in the
OnBeforeJobStart Event section. For example, the TablesDefineAxesExportToRDB.dms sample
includes an OnBeforeJobStart Event section that creates axis expressions for all numeric variables
that do not already have one.
Event(OnBeforeJobStart, "Autosummarize the numeric variables")
Dim MDM

' Open all versions of the Short Drinks sample
MDM.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Mdd\short_drinks.mdd", "{..}")
' Set up axis expressions for all numeric variables

' that don't already have one
CreateAxisExpressions(MDM.Fields)
Sub CreateAxisExpressions(Fields)
Dim Field
' Loop through all fields and create an axis expression for
' all of the numeric variables that don't already have one
Case ObjectTypesConstants.mtVariable ' Simple variable
If Field.DataType = mr.Long Or Field.DataType = mr.Double Then
' It's a numeric
If Field.AxisExpression.IsEmpty() Then
' It hasn't already got an axis expression, so create one
Field.AxisExpression = "{min 'Minimum' min(" + Field.FullName + _
"), max 'Maximum' max(" + Field.FullName + _
"), mean 'Mean' mean(" + Field.FullName + _
"), StdDev 'Standard deviation' StdDev(" + Field.FullName + _
"), StdErr 'Standard error' StdErr(" + Field.FullName + ")}"
End If
End If
Case ObjectTypesConstants.mtClass, ObjectTypesConstants.mtCompound, _
ObjectTypesConstants.mtGrid, ObjectTypesConstants.mtArray
460
Chapter 1
' It's a container, process the contents

CreateAxisExpressions(Field.Fields)
End Select
Next
End Sub
MDM.Save("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\short_drinks_with_axis.mdd")
MDM.Close()
End Event
The highlighted lines show a section from the OnBeforeJobStart event section that loops through
all numeric variables to check for the presence of an axis expression. If none exists, the script
creates an axis expression consisting of a minimum, maximum, mean, standard deviation, and
standard error element for each variable. The script also contains a Metadata section that creates
an axis expression for a specific categorical element (see Creating Special Elements in Metadata
Using a Data Management Script for further details) and an OnAfterJobEnd event section that
creates the tables.
To run this sample, you need to have the IBM® SPSS® Data Collection Base Professional Tables
Option and access to an SQL Server installation and appropriate user access rights. Before running
the sample, you need to set up an SQL Server database called TablesDefineAxesExportToRDB.
If you run this script more than once, you must delete the records in the database created by the
previous run, otherwise the serial numbers will be duplicated and errors will result.
Note: The example in this topic is available in a sample file (called

TablesDefineAxesExportToRDB.dms) that comes with the IBM® SPSS® Data
Collection Developer Library. For more information, see the topic Table Scripting Sample Data
Management Scripts on p. 478.
Creating Special Elements in Metadata Using a Data Management Script
Special elements are used by IBM SPSS Data Collection Survey Reporter Professional or IBM®
SPSS® Data Collection Survey Tabulation to assist in the analysis of data (for example, mean,
standard deviation, totals, and subtotals) or to provide additional information (for example, text
elements). For more information, see the topic Special Elements on p. 1204.
In Survey Tabulation and the IBM® SPSS® Data Collection Base Professional Tables Option,
you can add special elements to your tables by defining an axis specification. You can define the
axis specification for a variable at the time you create the table. Elements added in this way are
not saved in the metadata.
Another way to add special elements to a table is to include them in the metadata so that they
are permanently attached to a variable. This can be useful if you know in advance the types of
special elements that will be required for analysis on a particular variable. You can add special
elements to the metadata using a data management script, either by setting up an axis expression
on an existing variable, or by creating a derived variable that includes the special element.
461
Base Professional
Adding a Special Element to the Metadata Using an Axis Expression
The TablesDefineAxesExportToRDB.dms sample (introduced in the topic Creating Axis

Expressions in the OnBeforeJobStart Event Section) also includes a Metadata section that creates
an axis expression including a mean element to a variable in a grid.
' Add an axis expression including a mean to a variable inside a grid.

' This enables you to show an average in the grid table.
childhhz "Number of children in each age group"

loop
{YEARS_0_5 "0-5 years",
YEARS_6_10 "6-10 years",
YEARS_11_15 "11-15 years"}
fields
(questi1 "Number of children in household" categorical [1]
{CHILDH_0 "None" factor(0),
CHILDH_1 "1" factor(1),
CHILDH_5 "5 or more" factor(5)}
axis("{.., Mean 'Average' mean()}");) grid expand;
End Metadata
This example uses the factors attached to each category to calculate the mean.
You can also create a mean calculated using a numeric variable, by specifying the variable as a
parameter. For example, the TablesDefineAxes.dms sample (introduced in the topic Creating Axis
Expressions and Exporting to IBM SPSS Statistics) includes a Metadata section that creates an
axis expression including a mean for the Human numeric variable in the Museum sample data set:
human long
axis ("{NotAtAll 'Not at all interested' expression('human = 1'),
NotParticularly 'Not particularly interested' expression('human = 2'),
NotOpinion 'No opinion' expression('human = 3'),
Slightly 'Slightly interested' expression('human = 4'),
Very 'Very interested' expression('human = 5'),
'Mean' mean(human)}");
Adding a Special Element to the Metadata Using a Derived Variable
When you add a special element to a table using an axis expression, the Table Object Model
automatically takes care of creating any associated helper elements that are required by special
elements you have created. These are elements that do not appear on the resulting table but are
required during the calculation of the special element’s value.
462
Chapter 1
In some circumstances, however, you may prefer to add both the special elements and their helper
elements to the metadata. You can do this by using a derived variable. This eliminates the need to
use an axis expression, and can increase the speed of population of tables.
This example creates derived variables based on variables in the Short Drinks sample data set. It
defines special elements calculated using factors and others calculated using numeric variables,
and shows how to define helper elements.
The first derived variable, hhsize2, has a number of categories based on those in the hhsize
categorical variable, with the addition of a factor attached to each category. The variable also
includes a mean element. The mean is calculated using the factors attached to the categories,
so no helper elements are required:
hhsize2 "Derived variable based on the Household size variable with categories and a mean based on factors"
categorical [1]
{Hsize_1 "1 Person" expression ("hhsize * {HH_1}") factor(1),
Hsize_2 "2 People" expression ("hhsize * {HH_2}") factor(2),
Hsize_7 "7 or More People" expression ("hhsize * {HH_7}") factor(7),
NotAnswered "Not Answered" expression ("hhsize * {NA}"),
Mean "Average Household size" [CalculationType="Mean", HasNoData=True, ExcludedFromSummaries=True] elementtype(AnalysisMea
};
For a list of the properties to use when adding special elements to the metadata using a derived
variable, see the topic. This topic also defines the helper elements required and their properties.
The second derived variable, Income2, is a categorical variable based on the Income numeric
variable. It includes a number of bands based on the values in the original variable, and it also
includes a mean element and the relevant helper elements (SumX and SumN) required to calculate
the mean using the values from the numeric Income variable:
income2 "derived variable showing bands, mean, and standard deviation"

categorical [1]
{income_1 "Lower income" expression("income > 0 and income <= 30000"),
income_2 "Middle income" expression("income > 30000 and income <= 60000"),
income_3 "High income" expression("income > 60000"),
SumXSquared [CalculationType="SumXSquared", Hidden=True, ExcludedFromSummaries=True, DataElement=""] elementType(AnalysisS
SumX [CalculationType="SumX", Hidden=True, ExcludedFromSummaries=True, DataElement=""] elementType(AnalysisSummaryData) mu
SumN [CalculationType="SumN", Hidden=True, ExcludedFromSummaries=True,DataElement=""] elementType(AnalysisSummaryData),
Mean "Average income" [CalculationType="Mean", HasNoData=True, ExcludedFromSummaries=True] elementtype(AnalysisMean),
Stddev "Standard deviation" [CalculationType="Stddev", HasNoData=True, ExcludedFromSummaries=True] elementtype(AnalysisStddev)
};
Notice that this example also includes a Standard deviation element. This requires an additional
helper element, SumXSquared, but it does not require separate SumX or SumN elements, as these
are shared with the mean element.
463
Base Professional
This example is available as a sample file called TablesDefineSpecialElements.dms. To run this

sample, you need to have IBM SPSS Data Collection Survey Reporter Professional and access to
an SQL Server installation and appropriate user access rights. Before running the sample, you
need to set up an SQL Server database called TablesDefineSpecialElements. If you run this script
more than once, you must delete the records in the database created by the previous run, otherwise
the serial numbers will be duplicated and errors will result.
The examples in this topic are provided in the TablesDefineAxesExportToRDB.dms,

TablesDefineAxes.dms, and TablesDefineSpecialElements.dms sample files that come with the
IBM® SPSS® Data Collection Developer Library. For more information, see the topic Table
Creating Built-in Base Elements
Base elements typically show the total number of cases in an axis and are used in the calculation
of percentages and statistical tests. The Table Object Model automatically adds a base element
(sometimes called an autobase) to every axis that does not already have a base element. The axis
would already have a base element if one was specified in the axis specification or if the variable
on which it is based contains a built-in base element. A built-in base is a base that is defined as
an element in the variable on which the axis is based (rather than in the axis specification). For
more information, see the topic The Base Element on p. 1230.
Typically, you create a built-in base element when you want the base element to be filtered—for
example, because you want to exclude from the base cases that are in a “Not answered” or “Don’t
know” category. This topic explains how to create a built-in base element (both filtered and
unfiltered) in a derived variable and provides examples that show how a built-in base element
differs from an autobase.
The autobase shows the total number of cases in all of the categories in the variable on which
the axis is based. For example, the following script creates two one-dimensional tables from the
Signs variable in the Museum sample data set. The first table includes all of the categories in the
variable and the second includes the Yes and No categories only.
.AddNew("Table1", "Signs", _
"All categories of the Signs variable")
.AddNew("Table2", "Signs{Yes, No}", _
"Two categories of the Signs variable")
End With
Here are the two tables, shown side by side:

464
Chapter 1
Notice that the two Base rows (formed from the autobases) show the same value, because the
autobase shows the total number of cases in the variable on which the axis is based, regardless of
which categories are actually shown on the table. This is because the base is used to calculate
percentages, and it is normal to want to base percentages on the number of respondents who were
asked the question (which typically corresponds to the number of cases in the variable), rather
than on the number of people who selected the categories that are shown on the table.
However, sometimes you may want to base the percentages on the cases in the categories shown
on the table only. You can achieve this by filtering the table to exclude the cases that are in the
categories that are not shown on the table, as shown in The Base Element topic. Alternatively,
you can create a derived variable that has only the required categories and use this in the table
instead of the original variable. The autobase will then show the number of cases in the categories
included in the derived variable.
We can create the derived variable in the Metadata section of a data management script like this:
' Create a derived variable based on two categories of
' the Signs variable
Signs2 "Thinks signs could be improved"

categorical
{
Yes expression("signs * {Yes}"),
No expression("signs * {No}")
};
Now let’s create a one-dimensional table for this derived variable. For example:
TableDoc.Tables.AddNew("Table3", "Signs2", _
"Derived variable based on two categories of Signs")
Here is the table:
The Base row in this table is again an autobase because the derived variable does not have a built-in
base element. Notice that the base in this table shows the total number of cases in the Yes and No
categories and does not include the cases in the Don’t know category. This is because the axis is
based on the derived variable and the derived variable does not have the Don’t know category.
Now let’s create the derived variable again, but this time with a built-in base element. For example:
' Create a derived variable based on two categories of the Signs variable
' and include a built-in base element.
Signs3 "Thinks signs could be improved with built-in base"

categorical
{Base "Base" elementtype(AnalysisBase)
465
Base Professional
expression("@ > {}"),

Yes "Yes",
No "No"
}expression("signs * {Yes, No}");
Notice that an expression is used to define the categories that are to contribute to the base. In this
example, the expression for the base specifies the Yes and No categories of the Signs variable.
Here is a one-dimensional table created from this derived variable:
Notice that the base in this table is exactly the same as the autobase created for the previous
table. This is what we would expect because the expression that defines the base specifies the
same categories as are included in the variable. This is an unfiltered built-in base and it is the
same as the autobase.
Now suppose you want to include the Don’t know category in the table but exclude it from the
base. You can achieve this by creating a derived variable that includes the Don’t know category
and a built-in base, but excluding the Don’t know category from the base element’s expression.
This is sometimes called a filtered base. For example:
' Create a derived variable based on three categories of the Signs variable
' and include a built-in base element that is filtered to exclude the Don't
' know category.
Signs4 "Thinks signs could be improved with built-in filtered base"

categorical
{Base "Base" elementtype(AnalysisBase)
expression("@ * {Yes, No}"),
Yes "Yes",
No "No",
Dont_know "Don't know"
}expression("signs");
Here is the table:
Notice that now although the Don’t know category is shown on the table, the Base row does not
include the cases in the Don’t know category.
For more information, see the topic The Base Element on p. 1230.
466
Chapter 1
Note: The examples in this topic are available in a sample file (called TablesFilteredBase.dms)
that comes with the IBM® SPSS® Data Collection Developer Library. For more information, see
the topic Table Scripting Sample Data Management Scripts on p. 478.
Samples
The data management samples that come with the IBM® SPSS® Data Collection Developer
Library include:
WinDMSRun sample application
Sample DMS Files
Sample batch files
Warning: You can use the samples as a starting point when you develop your own DMS files,
applications, etc. However, it is always advisable to work on a copy of the files rather than
working on the sample files directly. This avoids the risk of losing your work when you uninstall
or upgrade to a new version of the Data Collection Developer Library.
Requirements
IBM® SPSS® Data Collection Base Professional 6.0.1
Some scripts require the use of a Microsoft SQL Server database
Some scripts require the use of Microsoft Office
Using the Sample DMS Files
The IBM® SPSS® Data Collection Developer Library comes with a

number of sample DMS files. By default, these are installed into the
A number of DMS files are also installed for use as Include files. These are installed into the
Include subfolder.
Notes on using the samples

The samples reference various sample data files. If the sample data files are stored in a
different location on your computer, you will need to edit the sample DMS files accordingly
before running them.
You need IBM® SPSS® Data Collection Base Professional 6.0.1 installed to run these
samples. Some of the samples have additional requirements. For example, the samples that
read or write data in a relational MR database require access to a Microsoft SQL Server 2005
or 2008 installation and appropriate user access rights; the samples whose names start with
“MS” require one or more of the Microsoft Office applications to be installed; the table
scripting samples require the IBM® SPSS® Data Collection Base Professional Tables Option.
For further information, see the notes about each sample in the following topics.
The samples are set up to store the output files in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output folder. This folder is
generally created by the Data Collection Developer Library installation. However, if this
467
Base Professional
folder does not exist on your system, because, for example, you chose a custom installation,
you will need to create the folder or edit the sample DMS files to specify a different
folder that does exist.
Some of the samples are set up to create the log file in the C:\temp folder. If this folder does
not exist on your system, you will need to create it or edit the sample DMS files to specify
a different folder that does exist.
To help you quickly identify the output files created by each sample DMS file, the output files
generally have the name of the sample DMS file. For example, Weighting.dms creates output
files called Weighting.mdd, Weighting.ddf, and Weighting.htm.
You may get an error if you try to run some of the samples more than once without first
deleting or moving the output from the previous run. For example, transfers to a relational
MR database may fail if you attempt to transfer a record with the same serial number (stored
in Respondent.Serial) twice.
Warning: You can use the samples as a starting point when you develop your own DMS files.
Tip: Some of the samples use Include files, sometimes with several text substitutions. You may
find it easier to understand these samples if you look at the expanded file. You can save the
expanded file without running it using the /a: and /norun options in DMS Runner.
Requirements
Base Professional 6.0.1
Some scripts require the use of Microsoft Office
Sample DMS Files
AdvancedCleaning.dms. This shows using advanced mrScriptBasic features to iterate through all of
the questions in a survey performing different cleaning routines according to the question type.
For more information, see the topic 6. Advanced Cleaning Example on p. 402..
CaDSCommentBlock.dms. Provides a IBM® SPSS® Collaboration and Deployment Services

comment block for .dms files. The sample defines one input parameter, one output variable,
and two output files.
CaseDataOnly.dms. This transfers data from the Employee Data sample IBM® SPSS® Statistics
.sav file to another .sav file without specifying a metadata source. For more information, see the
fourth example in InputDataSource Section.
Cleaning.dms. This shows a number of ways of cleaning single response questions in answer to
which respondents have selected more than one response. For more information, see 1. More
Than One Response To a Single Response Question in the Data Cleaning section.
468
Chapter 1
Cleaning2.dms. This shows using a loop to to iterate through all of the single response questions
included in the job, testing whether they have more than one response, and if they do, writing the
details to a report file and setting the DataCleaning.Status system variable. For more information,
see the first example in 3. More on Cleaning Single Response Data.
Cleaning3.dms. This shows how to select the highest and lowest response alternately and use the
mrScriptBasic object collection iteration feature to validate all of the iterations of a grid question.
For more information, see the second and third example shown in 3. More on Cleaning Single
Response Data.
CreateCSVAndCategoryMap.dms. This script transfers case data to tab-delimited .csv file, which can
be opened in Microsoft Excel. To help understand the data in the .csv file, the script also creates a
text file that contains a list of the category values used and the equivalent category labels.
CreateDRS.dms. This writes the case data to a text file in the standard IBM® SPSS® Quancept™
.drs format. This sample demonstrates a recursive subroutine call, accessing category attributes,
dealing with multiple response values, retrieving category labels, and a replace string function.
Note that this sample does not export Other Specify texts.
DDFToRDB.dms. This transfers the Museum sample IBM SPSS Data Collection Data File to a
relational MR database. Before you run this example, you need to create a database called
NewMuseum and, if necessary, change the connection string in the OutputDataSource section to
reflect the name of the server you are using. For more information, see the topic Transferring Data
to a Relational MR Database (RDB) on p. 337.
DDFToSavHdataTransfer.dms. This script demonstrates how DMOM will transfer case data from a
Hierarchical dataset to a flattened dataset when the input data source query does not contain any
Levels variables (grid/loop).
DDFToSavHdataTransferExpressionAggregation.dms. This script demonstrates DMOM support for

expressions and aggregations in an input data source query.
DMSRunExample.dms. This script demonstrates the use of text substitution in a DMS file when
running the file using the DMS Runner command prompt utility. Like the sample file Simple.dms,
this script transfers the Museum sample IBM SPSS Data Collection Data File to a new SPSS
Statistics .sav file. When you run the script, you must use the DMS Runner /d option to replace
the text “Target” with the chosen name for your output data source, and to replace the text
“LogSize” with the maximum size of the log file in KB. For example:
DMSRun DMSRunExample.dms /d"Target \"MyOutputDatasource\"" /d"LogSize 250"
For more information, see the topic DMS Runner on p. 289.
GetOtherSpecifyText.dms. This provides an example of accessing the open-ended responses to an

Other Specify category in the OnNextCase Event section. For more information, see the topic
4. Cleaning Other Question Types on p. 398.
469
Base Professional
GlobalSQLVariable.dms. This shows how to use a global SQL variable in a DMS file that is
being used to clean or transfer batches of case data and write it to a different data source. For
more information, see the topic GlobalSQLVariables Section on p. 266. You need to run the
GlobalSQLVariableSetUp.dms file before you run this sample to set up the output data source
and transfer the first records. Note that you can use the RunGlobalSQLVariableExample.bat
sample batch file to run the two files in sequence.
GlobalSQLVariableSetUp.dms. This sets up the output data source for use by the
GlobalSQLVariable.dms sample. Note that you can use the RunGlobalSQLVariableExample.bat
sample batch file to run the two files in sequence.
IncludeExample.dms. This shows using the Include1.dms and Include2.dms Include files. For more
information, see Using Include Files in the DMS file.
JapaneseMergeHorizontal.dms. This sample demonstrates a horizontal merge of two Japanese

(multibyte) data sources. For more information, see the topic Merging Japanese (Multibyte)
Data Sources on p. 386.
JapaneseMergeVertical.dms. This sample demonstrates a vertical merge of two Japanese

(multibyte) data sources. For more information, see the topic Merging Japanese (Multibyte)
Data Sources on p. 386.
Logging.dms. This shows a Logging section and using the log file to record data cleaning
information. For more information, see Logging Section.
MDM2Quantum.dms. This sample uses the IBM® SPSS® Data Collection Metadata Model
to Quantum Component to set up card, column, and punch definitions in the input Metadata
Document (.mdd) file before exporting the case data from the Museum sample IBM SPSS Data
Collection Data File to a IBM® SPSS® Quantum™-format .dat file. This sample also includes
code to create the Quantum specification as shown in OnBeforeJobStart Event Section. The
OutputDataSource section in this sample is in an include file called QuantumOutput.dms.
MDM2QuantumExtra.dms. This sample uses the CardColsExtra.dms Include file to set up

card, column, and punch definitions for a variable created in the Metadata section, and the
QuantumOutput.dms Include file to define the OutputDataSource section. For more information,
see the topic OnAfterMetaDataTransformation Event Section on p. 279.
MergeHorizontal.dms. This sample shows how to combine the case data from two or more data
sources into a single data source. In a horizontal merge, the variables from all the data sources
are combined into a single case. For more information, see the topic Example of a Horizontal
Merge on p. 385.
MergeVertical.dms. This sample shows how to combine the case data from two or more data
sources into a single data source. In a vertical merge, the cases from the second and subsequent
data sources are output after the cases from the first data source. For more information, see the
topic Example of a Vertical Merge on p. 383.
470
Chapter 1
MetadataOnly.dms. This shows using the Null DSC to operate on metadata only and a simple
Metadata section that sets up two simple Boolean variables. For more information, see the third
example in InputDataSource Section.
Interviewer Server-prefixed sample DMS files. These samples are designed for use with data
collected using IBM® SPSS® Data Collection Interviewer Server and are listed separately. For
MS-prefixed sample DMS files. These samples integrate with Microsoft Office applications and
are listed separately. For more information, see the topic Sample DMS Files That Integrate with
MyFirstCleaningScript.dms. This is the sample used in 5. Running Your First Cleaning Script in the
Getting Started section. This sample includes an update query in the InputDataSource section that
deliberately introduces a number of errors into a copy of the Museum XML sample data. These
errors are then “cleaned” in the OnNextCase Event section. Without these modifications, the
cleaning script would not change the data because the Museum sample data is generally clean.
MyFirstTransfer.dms. This is the sample used in 1. Running Your First Transfer in the Getting
Started section.
NewVariables.dms. This shows a number of examples of creating new variables in a DMS files, as
described in the Creating New Variables section. This sample also demonstrates using the log file
in your OnNextCase Event section error handling.
OnAfterMetaDataTransformation.dms. This shows how to set up card, column, and punch definitions
for variables created in the Metadata section and to create the Quantum specification. For more
information, see the topic OnAfterMetaDataTransformation Event Section on p. 279.
OnBadCase.dms. This script shows how to use the OnBadCase event section to write the details of
each invalid record to a text file. The script also writes a total count of bad cases to the text file.
For more information, see the topic OnBadCase Event Section on p. 284.
QdiDrsToDDF.dms. This transfers the Museum sample .qdi and .drs files to a IBM SPSS Data
Collection Data File (.ddf). For more information, see the topic Transferring Data From QDI/DRS
on p. 325.
QuantumToDDF.dms. This script transfers data from the “Ski Demo” Quantum sample data supplied
with the IBM® SPSS® Data Collection Developer Library to a IBM SPSS Data Collection Data
File (.ddf). For more information, see the topic Transferring Data From IBM SPSS Quantum
on p. 320.
QuantumWeighting.dms. Uses the Weight Component to add a weight to a Quantum output file. The
script is similar to the Weighting.dms sample, but includes an OnAfterMetaDataTransformation
event to set up card, column, and punch definitions for all variables. In addition, the variable that
is used to store the weight information has a slightly different definition. See Working with the
Weight Component for more information about weighting.
471
Base Professional
QuanvertPkdToDDF.dms. Provides an example of using a DMS file to export data from a IBM®
SPSS® Quanvert™ packed database to a IBM SPSS Data Collection Data File (.ddf).
QuanvertToDDFHdataTransfer.dms. This script transfers data from the Data Collection sample
metadata and case data files, supplied with the Data Collection Developer Library, to a IBM SPSS
Data Collection Data File (.ddf) where grid questions are directly transferred.
QuanvertToDDFHdataTransferLevel.dms. This script demonstrates DMOM support for selecting

variables from different Levels by up-lev or down-lev.
QuanvertToDDFHdataTransferUnboundloop.dms. This script transfers data from the Data Collection

sample metadata and case data files, supplied with the Data Collection Developer Library, to a
IBM SPSS Data Collection Data File (.ddf) where unbound loop questions are directly transferred.
QuanvertToSav.dms. Creates a Metadata Document (.mdd) file from a Quanvert database, cleans up
some of the Quanvert-specific information, and then transfers data from the Quanvert database to
a .sav file. This sample illustrates using text substitution using the #define syntax and utilizes the
QuanvertInput.dms Include file. For more information, see the topic Transferring Data From IBM
SPSS Quanvert on p. 321.
RDBToQuantum.dms. This transfers the data in the SavToRdb relational MR database (which is the
output of the SavToRDB.dms sample) to a Quantum-format ASCII file. It uses the CardCols.dms
Include file to set up card, column, and punch definitions in the input .mdd file and create the
Quantum specification and the RDBInput.dms and QuantumOutput.dms Include files to define
the InputDataSource and OutputDataSource sections respectively. Before you run this sample,
make sure the connection string in the InputDataSource section reflects the name of the server
you are using.
RDBToSAS.dms. This script transfers a subset of the data in the NewMuseum relational MR
database (which is the output of the DDFToRDB.dms sample) to a SAS data file. The script
also creates a SAS program file, which specifies the user-defined formats for some of the SAS
variables and can be used by SAS products to read the data file. For more information, see the
topic Transferring Data to SAS on p. 349.
RDBToSav.dms. This script transfers a subset of the data in the NewMuseum relational MR database
(which is the output of the DDFToRDB.dms sample) to a .sav file. The OutputDataSource section
is specified using the SavOutput.dms include file. Before you run this sample, make sure the
connection string in the InputDataSource section reflects the name of the server you are using.
RDBToTripleS.dms. This script transfers the data in the NewMuseum relational MR database (which
is the output of the DDFToRDB.dms sample) to Triple-S metadata and case data files. The
script creates two Triple-S case data files, one that contains fixed-format fields and another that
contains comma-separated values. For more information, see the topic Transferring Data to
Triple-S on p. 348.
472
Chapter 1
SavCustomization.dms. This contains an OnBeforeJobStart Event section that sets up custom

properties in the input metadata before exporting the data to a new SPSS Statistics .sav file. The
custom properties customize both the .sav file and the .xml file created by the SPSS Statistics SAV
DSC. For more information, see Transferring Data to IBM SPSS Statistics.
SavToQuantum.dms. Uses the SavMddInput.dms, CardColsPlus.dms, and QuantumOutput.dms

Include files to create an .mdd file from a .sav file, set up the serial number system variable
(Respondent.Serial) and card, column, and punch definitions, and export the case data to Quantum.
SavToRDB.dms. Creates a Metadata Document (.mdd) file from the .sav file in the OnBeforeJobStart
Event section, uses the function to call the CreateRDBDatabase.bat sample batch file. This calls
the isql Microsoft SQL Server command line utility to create a database called SavToRDB. The
script then transfers data from the .sav file to the database. Before you run this sample, check that
the parameters for the isql command are correct for your installation. If you are using the SQL
Server 2005 client tools, you must change CreateRDBDatabase.bat to call sqlcmd instead of isql.
If necessary, change the connection string in the OutputDataSource section of SavToRDB.dms
to reflect the name of the server you are using. The OutputDataSource section in this sample is
in an include file called RDBOutput.dms. Note that you need Microsoft SQL Server 7, 2000, or
2005 Client Tools to run this sample.
SavToDDF.dms. Transfers data from a SPSS Statistics .sav file to a IBM SPSS Data Collection Data
File (.ddf) using the SPSS Statistics SAV DSC to read the case data and the metadata. Uses the
SavInput.dms and DDFOutput.dms Include files. For more information, see the topic Transferring
Data From IBM SPSS Statistics on p. 319.
SavWeighting.dms. Uses the Weight Component to add a weight to SPSS Statistics SAV output
files. The script is similar to the Weighting.dms sample. See Working with the Weight Component
for more information about weighting.
Simple.dms. This transfers the Museum sample IBM SPSS Data Collection Data File to a new
SPSS Statistics .sav file, as shown in Simple Example of a DMS File.
SplitIntoDirtyAndClean.dms. This transfers the Short Drinks sample data to two IBM SPSS Data
Collection Data Files (.ddf), one of which stores the clean data and the other the dirty data. This
is achieved using update queries in the two OutputDataSource sections to delete the clean data
from the dirty data source and the dirty data from the clean data source. For more information,
see the topic Filtering Data in a DMS File on p. 243. This sample assumes that the Short Drinks
sample database has been restored to LocalHost.
STAfSMerge.dms. This script merges coded data that was produced using IBM® SPSS® Text
Analytics for Surveys with the original Interviewer Server data to produce a new Interviewer
Server database. Before running this script, you must first edit the #define statements in
STAfSMerge.txt and then run STAfSMerge.mrs. Those two files are installed in the same folder
as STAfSMerge.dms.
SurveycraftToSav.dms. Transfers data from the IBM® SPSS® Surveycraft™ Household sample
data set to a new SPSS Statistics .sav file. The Surveycraft MDSC is used to read metadata
from the Surveycraft .vq file.
473
Base Professional
Tables-prefixed sample DMS files. These samples provide examples of scripting tables in a DMS
file using IBM SPSS Data Collection Survey Reporter Professional and are listed separately. For
more information, see the topic Table Scripting Sample Data Management Scripts on p. 478.
TrackingStudy-prefixed sample DMS files. These samples are used to analyze the response data
from a tracking study. For more information, see the topic Analyzing a Tracking Study on p. 442.
TripleSToDDF.dms. This script transfers data from the “Ski Demo” Triple-S sample metadata and
case data files supplied with the Data Collection Developer Library to a IBM SPSS Data Collection
Data File (.ddf). For more information, see the topic Transferring Data From Triple-S on p. 327.
UseInputAsOutput.dms. Demonstrates using the “use input as output” feature to update the input
data source rather than creating an output data source. For more information, see the topic
OutputDataSource Section on p. 261.
UtilizeOuterDirectives.dms. This script demonstrates passing directives to the Data Management

Script (DMS) via the IJob.Load function’s second parameter. The script cannot be run
independently.
Weighting.dms. This uses the Weight Component to set up weighting based on equal numbers of
male and female respondents, as shown in Setting Up Weighting in a DMS File in the Working
with the Weight Component section.
WeightingFactors.dms. This uses the Weight Component to set up weighting based on known
weighting factors based on age groups and gender. A derived categorical variable is set up in
the Metadata Section for the age groups on which the factors are based. A variable usage type
of Weight is specified to identify the weight variable to applications like IBM® SPSS® Data
Collection Survey Tabulation.
WeightingTargets.dms. This is similar to the WeightingFactors.dms sample, except that it uses

weighting targets rather than factors.
Requirements
Sample DMS Files For Exporting IBM SPSS Data Collection Interviewer Server Data
The samples listed in this topic have been designed to demonstrate exporting IBM® SPSS® Data
Collection Interviewer Server data that has been collected using multiple versions. All of the
samples use the Short Drinks sample database, but they can be adapted easily to run with any
multiversion project. You need access to an SQL Server installation and appropriate user access
rights to run all of these samples.
Before you can run these samples, you need to restore the Short Drinks sample. See for more
information. You may also need to change the Data Source property in the OLE DB connection
string to reflect the name of the server you are using. See for more information.
474
Chapter 1
mrInterviewAllVersionsToQuantum.dms. This sample shows you how to select all versions of

the metadata for an export to IBM® SPSS® Quantum™. For more information, see the topic
Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Quantum Using All
Versions on p. 365.
mrInterviewAllVersionsToSav.dms. This sample is designed for exporting data for all versions at
the end of your project. This uses all of the versions of the .mdd file and exports data collected
with all of the versions to a new IBM® SPSS® Statistics .sav file. For more information, see the
topic Exporting IBM SPSS Data Collection Interviewer Server Data to IBM SPSS Statistics
Using All Versions on p. 370.
mrInterviewCategoricalsOnlyToDDF.dms. This uses the output of the ListCategoricalVars.mrs

sample as an include file to export Respondent.Serial and all of the categorical variables in the
Short Drinks sample database. For more information, see the topic Restricting the Variables
Included in the Export on p. 359. You can use the CategoricalsOnly.bat sample batch file to run
the two files. For more information, see the topic Sample Batch Files on p. 481.
mrInterviewFirstBatchToQuantum.dms. This sample is designed for use when you want to export
Interviewer Server data to Quantum in batches. You use this sample to export the first batch
because it allocates new card, column, and punch definitions and creates a Quantum .dat file
that can then be updated by mrInterviewNextBatchToQuantum.dms. This sample also exports a
Quantum specification. For more information, see the topic Exporting Batches of IBM SPSS Data
Collection Interviewer Server Data to IBM SPSS Quantum on p. 367.
mrInterviewFirstBatchToSav.dms. This sample is designed for use when you want to export
Interviewer Server data to SPSS Statistics in batches. You use this sample to export the
first batch because it creates a new SPSS Statistics .sav file that can then be updated by
mrInterviewNextBatchToSav.dms or mrInterviewNextBatchNewVersionToSav.dms. For more
information, see the topic Exporting Batches of IBM SPSS Data Collection Interviewer Server
mrInterviewMoreVersionsToSav.dms. This sample is designed to be run after

mrInterviewAllVersionsToSav.dms. It merges all versions of the project’s metadata into the output
metadata from mrInterviewAllVersionsToSav.dms. This means that wherever possible the alias
names are reused. This sample does not filter the case data according to whether it has already
been transferred. However, you could easily modify it to do so using a similar method to that
used in the batch export samples. For more information, see the topic Exporting IBM SPSS Data
Collection Interviewer Server Data to IBM SPSS Statistics Using All Versions on p. 370.
mrInterviewMultipleVersionsToSav.dms. This sample shows you how to select two versions of the
metadata for an export and export only case data collected using those versions and their minor
versions. For more information, see the topic Selecting Multiple Versions on p. 362.
mrInterviewNextBatchNewVersionToSav.dms. This sample is designed for use when you want to

export Interviewer Server data to SPSS Statistics in batches and there is a new major version of the
metadata. Each new version must export to a new .sav file. You would use this sample for the first
export using the new version before using mrInterviewNextBatchToSav.dms to export the second
and subsequent batches collected with that version. mrInterviewNextBatchNewVersionToSav.dms
475
Base Professional
extracts the most recent version of the Interviewer Server project’s .mdd file into a new metadata
file so that the alias names used for the previous exports will be reused wherever possible. For
more information, see the topic Exporting Batches of IBM SPSS Data Collection Interviewer
Server Data to IBM SPSS Statistics on p. 370.
mrInterviewNextBatchToQuantum.dms. This sample is designed for use when you want to export
Interviewer Server data to Quantum in batches. You would use this sample to export the second
and subsequent batches. It queries the .dat file created by mrInterviewFirstBatchToQuantum.dms
(and updated by previous runs of mrInterviewNextBatchToQuantum.dms) to find the record with
the latest value of DataCollection.FinishTime. It then transfers from the Interviewer Server data
all records that have a later value than that record. Generally you can export each batch to the
same .dat file. However, there are certain version changes that require special handling. For more
information, see the topic Exporting Batches of IBM SPSS Data Collection Interviewer Server
Data to IBM SPSS Quantum on p. 367.
mrInterviewNextBatchToSav.dms. This sample is designed for use when you want to export
Interviewer Server data to SPSS Statistics in batches. You would use this sample to export the
second and subsequent batches. It queries the .sav file created by mrInterviewFirstBatchToSav.dms
(and updated by previous runs of mrInterviewNextBatchToQuantum.dms) to find the record with
the latest value of DataCollection.FinishTime. It then transfers from the Interviewer Server
data all records that have a later value than that record. Note that if you have previously run
mrInterviewNextBatchNewVersionToSav.dms, you must change the names of the input .sav and
.mdd files in this sample to match those output by mrInterviewNextBatchNewVersionToSav.dms.
For more information, see the topic Exporting Batches of IBM SPSS Data Collection Interviewer
Server Data to IBM SPSS Statistics on p. 370.
mrInterviewOneVersionToSav.dms. This sample shows you how to select a single metadata version
for an export and export only case data collected using that version and its minor versions. For
more information, see the topic Selecting a Specific Version on p. 361.>
mrInterviewSelectOnFinishTime.dms. This sample shows how to use the WScript.Shell object to get
the timezone information from the registry and use it to convert the output of the Now function to
UTC. For more information, see the topic Filtering on the Interview Finish Time on p. 358.
Requirements
Use of a Microsoft SQL Server database
Sample DMS Files That Integrate with Microsoft Office
To run these samples, you need to have Microsoft Office installed on your computer.
MSAccessToQuantum.dms. This uses the IBM® SPSS® Data Collection ADO DSC and the
Microsoft OLE DB Provider for ODBC Drivers to read data in the Authors sample Access database
and transfer it to a .dat file using the Data CollectionIBM® SPSS® Quantum™ DSC. The script
also demonstrates creating and populating two new variables on the Quantum file, one to store a
serial number and the other to contain persisted derived data. To run this sample, you need to have
476
Chapter 1
the Microsoft OLE DB Provider for ODBC Drivers and the ODBC data source called MS Access
Database. For more information, see the topic Transferring Data From Microsoft Office on p. 328.
MSAccessToSav.dms. This uses the Data Collection ADO DSC and the Microsoft OLE DB
Provider for ODBC Drivers to read data in the Northwind sample Access database and transfer it to
a .sav file using the Data CollectionSPSS Statistics SAV DSC. To run this sample, you need to have
the Microsoft OLE DB Provider for ODBC Drivers and the ODBC data source called MS Access
Database. For more information, see the topic Transferring Data From Microsoft Office on p. 328.
MSAccessTransferToFromRDB.dms. This transfers a subset of the Short Drinks sample RDB

database to an Access database. It provides an example of using the Microsoft Jet 4.0 OLE DB
Provider to write the data. Before you can run this sample, you need to create an Access database
called DMSTransfers. For more information, see the topic Writing Data Using Other OLE DB
Providers on p. 352.
MSExcelCharts.dms. This is an Include file that uses ADO to access the case data in the
output data source and advanced SQL queries and Office automation to set up some charts
in Excel. This Include file is designed to be used with text substitution as shown in the
MSExcelChartsFromQuancept.dms sample. You need Excel to run this sample.
MSExcelChartsFromQuancept.dms. This exports data from the Museum sample IBM® SPSS®
Quancept™ (Museum.qdi and Museum.drs) data and then uses the MSExcelCharts.dms Include
file to create charts in Excel. This sample also uses the QdiDrsInput.dms and DDFOutput.dms
Include files to define the input and output data sources. You need Excel to run this sample.
MSExcelDataViewer.dms. This provides an example of selecting a subset of the variables in the

Museum sample IBM SPSS Data Collection Data File (.ddf), creating two new variables and
setting up case data for them in the OnNextCase Event section, and then displaying the data in
Excel. This sample provides an example of using the Question.Categories collection to return
the category that corresponds to a response to a categorical question and using it to display the
category name and label. You need Excel to run this sample.
MSExcelTables.dms. This uses ADO to access the case data in the output data source and advanced
SQL queries to set up some tables that are displayed in Excel. For more information, see the
second example shown in OnAfterJobEnd Event Section. You need Excel to run this sample.
MSExcelToQuantum.dms. This uses the Data Collection ADO DSC and the Microsoft OLE DB
Provider for ODBC Drivers to transfer data from an Excel file to a .dat file using the Data
CollectionQuantum DSC. To run this sample, you need to have the Microsoft OLE DB Provider
for ODBC Drivers and the ODBC data source called Excel Files. For more information, see the
topic Transferring Data From Microsoft Office on p. 328.
MSExcelToDDF.dms. This provides an example of using the Data Collection ADO DSC and the
Microsoft OLE DB Provider for ODBC Drivers to transfer data from an Excel file to a IBM SPSS
Data Collection Data File (.ddf). Before you run this sample, you need to edit the sample to insert
the name and location of a suitable Excel file. To run this sample, you need to have the Microsoft
OLE DB Provider for ODBC Drivers and the ODBC data source called Excel Files. For more
information, see the topic Transferring Data From Microsoft Office on p. 328.
477
Base Professional
MSExcelTransferToFromDDF.dms. This transfers a subset of the Museum sample IBM SPSS Data
Collection Data File to Excel. It provides an example of using the Microsoft OLE DB Provider for
ODBC Drivers to write data to Excel. This sample includes code in the OnBeforeJobStarts Event
section to create the empty Excel file in the output folder. For more information, see the topic
Writing Data Using Other OLE DB Providers on p. 352. You need Excel to run this sample.
MSExcelTransferToFromRDB.dms. This transfers a subset of the Short Drinks sample RDB database
to Excel. It provides an example of using the Microsoft OLE DB Provider for ODBC Drivers to
write data to Excel. This sample includes code in the OnBeforeJobStarts Event section to create
the empty Excel file in the output folder. For more information, see the topic Writing Data Using
Other OLE DB Providers on p. 352. You need Excel to run this sample.
MSOutlookSendReport.mrs. This is an .mrs file that automatically generates and sends an e-mail
with an attachment. This file requires access to a Microsoft Exchange server and is designed to
be used as an Include file with text substitution being used to insert the name of the Exchange
server, the sender’s and recipient’s e-mail addresses, and the name and location of the report file
to send. Comments in the MSWordReport.dms sample show you how to do this. See FAQs on
the Differences Between DMS and .mrs Files for information about the differences between
DMS and .mrs files.
MSPowerPointCharts.dms. This is an Include file that uses ADO to access the case data in the
output data source and advanced SQL queries and Office automation to set up some charts in
PowerPoint. This Include file is designed to be used with text substitution as shown in the
MSPowerPointChartsFromQuanvert.dms sample. You need PowerPoint to run this sample.
MSPowerPointChartsFromQuanvert.dms. This exports data from the Museum sample IBM®

SPSS® Quanvert™ database data and then uses the MSPowerPointCharts.dms Include file to
create charts in PowerPoint. This sample also uses the DDFOutput.dms Include files to define the
output data source. You need PowerPoint to run this sample.
MSSQLTransferToFromRDB.dms. This transfers a subset of the Short Drinks sample RDB database
to an MS SQL Server database. It provides an example of using the Microsoft OLE DB Provider
for SQL Server. Before you can run this sample, you need access to an SQL Server installation
that contains a database called DMSTransfers. For more information, see the topic Writing Data
Using Other OLE DB Providers on p. 352.
MSWordMuseumToplines.dms. This exports data from the Museum sample IBM SPSS Data
Collection Data File and then uses the MSWordToplines.dms Include file to create top line tables in
Word and save them as Word .doc and HTML files. You need Word to run this sample.
MSWordReport.dms. This writes a cleaning report to a Microsoft Word document. This sample uses
the DDFOutput.dms Include file to define the output data source, a IBM SPSS Data Collection
Data File (.ddf). This file includes a “commented out” OnAfterJobEnd Event section, that uses the
MSOutlookSendReport.mrs sample Include file to send the report as an e-mail attachment. If you
have access to a Microsoft Exchange Server, you can implement this by “uncommenting” the
relevant lines and entering your e-mail details. You need Word to run this sample.
478
Chapter 1
MSWordToplines.dms. This is an Include file that uses ADO to access the case data in the
output data source and advanced SQL queries and Office automation to set up some top line
tables in Word. This Include file is designed to be used with text substitution as shown in the
MSWordMuseumToplines.dms sample. You need Word to run this sample.
Requirements
Microsoft Office
Table Scripting Sample Data Management Scripts
To run these samples, you need to have IBM® SPSS® Data Collection Base Professional Tables
Option installed. Some of the samples have additional requirements. For further information, see
the notes about each sample below.
TablesDefineAxes.dms. This sample exports the Museum sample IBM SPSS Data Collection Data
File to a new IBM® SPSS® Statistics .sav file and includes a Metadata section that sets up an axis
expression for some of the numeric and text variables and an OnAfterJobEnd Event section that
sets up tables for these and other variables in the output data source. For more information, see the
topic Creating Axis Expressions and Exporting to IBM SPSS Statistics on p. 456.
TablesDefineAxesExportToRDB.dms. This sample sets up some axis expressions in the Short Drinks
sample metadata as follows: first, in the OnBeforeJobStart Event section, an axis expression that
includes only summary special elements is set up for all numeric variables that don’t already have
one. Secondly, in the Metadata section, an axis expression is set up for a specific categorical
variable. The variable is inside a grid variable and the axis expression sets up factors for the
categories and inserts a mean element that is subsequently used to show an average in a grid table.
The sample then exports the Short Drinks sample data to a new RDB database and includes an
OnAfterJobEnd Event section that sets up batch tables. To run this sample, you need access to an
SQL Server installation and appropriate user access rights. Before running the sample, you need
to create an SQL Server database called TablesDefineAxesExportToRDB. For information on the
axis expression for numeric variables, see Creating Axis Expressions in the OnBeforeJobStart
Event Section. For information on the axis expression for the categorical variable, see Creating
Special Elements in Metadata Using a Data Management Script.
TablesDefineSpecialElements.dms*. This sample creates derived variables including special

elements and their associated helper elements. To run this sample, you need access to an SQL
Server installation and appropriate user access rights. Before running the sample, you need to
create an SQL Server database called TablesDefineSpecialElements. For more information, see
the topic Creating Special Elements in Metadata Using a Data Management Script on p. 460.
TablesFilteredBase.dms. This sample exports the Museum sample IBM SPSS Data Collection Data
File to another IBM SPSS Data Collection Data File and has a Metadata section that demonstrates
creating built-in base elements. For more information, see the topic Creating Built-in Base
Elements on p. 463.
479
Base Professional
TablesFirstScript.dms. This sample exports the Museum sample IBM SPSS Data Collection Data
File to an RDB database and includes an OnAfterJobEnd Event section that scripts three tables,
and then populates and exports them (along with a chart for each table) to HTML. To run this
sample, you need to have access to an SQL Server installation and appropriate user access rights.
Before running the sample, you need to create an SQL Server database called TablesFirstScript.
In addition, to create charts, the HTML Export component requires Microsoft Office Web
Components (OWC) version 10 or later, which is available from the Microsoft Download Center.
For more information, see the topic Creating Tables Using a Data Management Script on p. 451.
TablesLoopThroughPaperRouting.dms. This sample exports the Museum sample IBM SPSS

Data Collection Data File to another IBM SPSS Data Collection Data File and includes an
OnAfterJobEnd Event section that loops through the IBM® SPSS® Data Collection Paper routing
items and creates a top-line table for all of the suitable simple questions in the routing that have a
short name defined. After populating the tables, the tables are exported to HTML as charts. You
need to have Microsoft Office 2007 or later installed to be able to export the charts.
TablesWeightingAllFieldsHdata.dms. This sample exports the Museum sample IBM SPSS Data
Collection Data File to an RDB database, creates a weighting variable, uses the Weight component
to set up weighting and creates a weighted table for each of the suitable variables in the output data
source. To run this sample, you need to have access to an SQL Server installation and appropriate
user access rights. Before running the sample, you need to create an SQL Server database called
TablesWeightingAllFieldsHdata. For more information, see the topic Exporting to RDB and
Creating Multiple Weighted Tables on p. 454.
Note: This sample is designed to demonstrate how to set up and use weighting in your tables. It is
not designed to show you how you should actually use weighting when analyzing survey results.
Requirements
IBM® SPSS® Data Collection Base Professional 6.0.1 Tables Option
Sample DMS Include Files
CardCols.dms. This is an OnBeforeJobStarts Event section that uses the IBM® SPSS® Data
Collection Metadata Model to Quantum component to set up card, column, and punch definitions.
This Include file is designed to be used with text substitution as shown in RDBToQuantum.dms.
CardColsExtra.dms. This is an OnAfterMetaDataTransformation Event section that uses the

Metadata Model to Quantum component to set up card, column, and punch definitions in the
output metadata. This can be used to set up card, column, and punch definitions for variables
created in the Metadata section. This Include file is designed to be used in a DMS file that contains
a Logging section as shown in MDM2QuantumExtra.dms.
CardColsPlus.dms. This is an OnBeforeJobStarts Event section that creates an .mdd file from a
proprietary metadata source, sets up system variables and uses the Metadata Model to Quantum
component to set up card, column, and punch definitions. It also contains an OnJobStart Event
section that initializes a counter that is used in the OnNextCase Event section to set up case data
480
Chapter 1
for Respondent.Serial. This Include file is designed to be used with text substitution as shown in
SavToQuantum.dms.
DDFInput.dms. An InputDataSource section that uses IBM SPSS Data Collection Data File CDSC
to read the case data in a .ddf file and the metadata in a .mdd file. This Include file is designed to
be used with text substitution as shown in MSExcelTables.dms.
DDFOutput.dms. An OutputDataSource section that uses the IBM SPSS Data Collection Data File
CDSC to write to a IBM SPSS Data Collection Data File (.ddf). This Include file is designed to be
used with text substitution as shown in MSExcelTables.dms.
Include1.dms. This is an Include file that is referenced by the IncludeExample.dms sample file.
Include2.dms. This is an Include file that is referenced by the IncludeExample.dms sample file.
LoggingSection.dms. A standard Logging section that can be included in any DMS file. For more
information, see the topic Logging Section on p. 271.
LogInput.dms. An InputDataSource section that uses Log DSC to read a IBM® SPSS® Data
Collection log file. This Include file is designed to be used with text substitution.
MS-prefixed sample Include files. These samples integrate with Microsoft Office applications and
are listed separately. For more information, see the topic Sample DMS Files That Integrate with
QdiDrsInput.dms. A connection string that uses QDI/DRS DSC to read IBM® SPSS® Quancept™
data for use in an InputDataSource section. This Include file is designed to be used with text
substitution.
QuantumOutput.dms. An OutputDataSource section that uses IBM® SPSS® Quantum™ DSC to

write case data to a Quantum-format ASCII file. This Include file is designed to be used with text
substitution as shown in MDM2Quantum.dms.
QuantumOutput2.dms. An OutputDataSource section that uses Quantum DSC to write case data
to a Quantum-format ASCII file but does not save the output metadata file. This Include file
is designed to be used with text substitution.
QuanvertInput.dms. An InputDataSource section that uses IBM® SPSS® Quanvert™ DSC to read
the case data and metadata in an .mdd file. This Include file is designed to be used with text
substitution as shown in QuanvertToSav.dms.
RDBInput.dms. An InputDataSource section that uses RDB DSC 2 to read a relational MR database.
This Include file is designed to be used with text substitution as shown in RDBToQuantum.dms.
RDBOutput.dms. An OutputDataSource section that uses RDB DSC 2 to write to a relational

MR database. This Include file is designed to be used with text substitution as shown in
SavToRDB.dms.
481
Base Professional
SavInput.dms. An InputDataSource section that uses SPSS Statistics SAV DSC to read case
data and metadata. This Include file is designed to be used with text substitution as shown in
SavToDDF.dms.
SavMddInput.dms. An InputDataSource section that includes a select query, an .mdd file and uses
SPSS Statistics SAV DSC to read case data. This Include file is designed to be used with text
substitution as shown in SavToQuantum.dms.
SavOutput.dms. An OutputDataSource section that uses SPSS Statistics SAV DSC to write to a
.sav file. This Include file is designed to be used with text substitution.
Requirements
Sample Batch Files
The IBM® SPSS® Data Collection Developer Library comes with a number
of sample MS-DOS batch files that have been set up to perform various data
management-related tasks. By default, the batch files are installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\Batch folder.
Some of the batch files reference various sample files. If the sample files are stored in a different
location on your computer, you will need to edit the sample batch files accordingly before running
them. You will also need to check that the requirements of each sample DMS file is met, that the
data files they reference exist in the specified locations, etc.
Warning: You can use the samples as a starting point when you develop your own batch files.
files directly. This avoids the risk of losing your work when you uninstall or upgrade to a new
List of sample batch files
CategoricalsOnly.bat. This batch file runs the following:

The ListCategoricalVars.mrs sample mrScriptBasic file, which creates a text file that sets
up the first part of the select query with the names of all the categorical variables in the
Short Drinks sample .mdd file. For more information, see the topic Restricting the Variables
Included in the Export on p. 359.
The IBM® SPSS® Data Collection Interviewer ServerCategoricalsOnlyToDDF.dms sample
DMS file, which uses the output of the ListCategoricalVars.mrs sample as an include file to
export all of the categorical variables in the Short Drinks sample database. To run this sample,
you need access to an SQL Server installation and appropriate user access rights. You also
need to restore the Short Drinks sample.
This file has been designed so that it can be run as a scheduled task. For more information, see the
topic Using the At Command to Schedule a DMS File on p. 295.
482
Chapter 1
CreateRDBDatabase.bat. This batch file uses the Microsoft SQL Server isql command line utility
to create a database called SavToRDB. Note that the SavToRDB.dms sample DMS file uses the
function to call this batch file to set up the database prior to the transfer. You need Microsoft SQL
Server 7, 2000, or 2005 Client Tools to run this sample. Before you run this sample, you need to
ensure that the parameters specified for the isql utility are correct for your installation. If you are
using SQL Server 2005, you must change CreateRDBDatabase.bat to call sqlcmd instead of isql.
Refer to the SQL Server documentation for further information.
RunGlobalSQLVariableExample.bat. This batch file changes to the folder where the DMS sample
files are installed and then runs the the UseInputAsOutput.dms, GlobalSQLVariableSetup.dms, and
GlobalSQLVariable.dms sample files. The batch file ends with a pause statement, which stops the
command prompt from closing automatically, so that you can check for error messages.
RunTwoDMSFiles.bat. This batch file changes to the folder where the DMS sample files are
installed and then runs the Simple.dms and MDM2Quantum.dms sample files. The batch file ends
with a pause statement, which stops the command prompt from closing automatically, so that
you can check for error messages.
Requirements
Some files require the use of a Microsoft SQL Server database
Data Management Reference

This section includes:
DMS File System Interaction. A diagram that illustrates how the different objects interact when a
valid DMS file is executed.
Data Management Functions. Provides information on the various Data Management functions.
DMOM Scripting Reference. Detailed technical reference to the Data Management objects that
are exposed in the DataManagementScript (DMS) file.
Levels Export Component Object Model. Detailed technical reference for the Levels Export
component that is used to export hierarchical data to flattened data.
Script Packager Component Object Model. Detailed technical reference for the Script Packager
component objects.
Tabulation Services Component Object Model Reference Detailed technical reference for the
Tabulation Services component objects.
Weight Component Object Model. Detailed technical reference to the Weight component objects.
DMOM Programmer’s Reference. A complete reference to the Data Management Object Model
(DMOM) for programmers who are creating applications using the DMOM.
483
Base Professional
DMS File System Interaction
The following diagram illustrates how the different objects interact when a valid DMS file is
executed.
Data Management Functions
This following table list available Data Management functions.

Function Description
CombineIterations Combines the response value for nested grid
questions iterations.
CopyGrid Transfers data from SourceGrid to DestinationGrid.
CreateGridSummary Creates a summary result for a grid.
FlattenGrid Converts grid sub-questions into flattened questions.
FlipGrid Retrieves flipped data from SourceGrid.
RemoveCategory Removes the deprecated OldCategory from
MDMObject.
ReplaceCategory Replaces oldCategory with newCategory for a
loop/categorical questions.
SubtractQuestion Subtracts the values for one or more questions.
SumQuestions Sums the value for more than one categorical
question.
484
Chapter 1
CombineIterations
Combines the response value for nested grid question iterations (used for OnNextCase events).
CombineIterations(CombineQuestion, CombineIterationName, CombineList)
Parameter Type Remarks

CombineQuestion object Grid question
CombineIterationName string The iteration category that stores
the combination results.
CombineList Categorical The iteration category items that
determine the result.
Return value Boolean True if the function is successful.
Remarks
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
485
Base Professional
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 }
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.
CopyGrid(SourceGrid, DestinationGrid, IterationFilter)

SourceGrid Object Grid question
DestinationGrid Object Grid question
IterationFilter Categorical Categorical for iteration filter
(return) Boolean True if copy is successful
Remarks
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 may 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 -
486
Chapter 1
};
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 the above value for Loop1, the value for LoopForCopy will be as follows:
LevelID Q2 Q1
{A} I am testing { Dislike }
{B} I am {Like}
487
Base Professional
Performance note
CopyGrid can transfer data between grids for many scenarios. The grid may 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
CreateGridSummary
Creates a summary result for a grid (used for OnNextCase events).

CreateGridSummary (Grid, SummaryVarible, SummaryCategories, QuestionNameForSummary)

Grid None The summarized grid question.
SummaryVariable None The categorical question for
saving summary results.
SummaryCategories None The category list for calculating
summary results.
QuestionNameForSummary Text The name of sub-question in the
summarized grid.
Remarks
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.

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",
488
Chapter 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}
FlattenGrid
Converts categorical loop sub-questions (both grid and non-grid) into flattened questions that can
be used in the DMOM eventOnBeforeJobStart/OnAfterMetaDataTransformation.
FlattenGrid(FlattenQuestionFullName, FilterIteration, MDMObject)

FlattenQuestionFullName string FullName for the question being
flattened
FilterIteration string String for the iteration filter
MDMObject object MDM object related to the .mdd
file that contains GridObjectName
(return) string True if the function is successful.
489
Base Professional
Remarks
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:

{
A "A",
B "B",
C "C",
D "D"
} fields -
(
{
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
490
Chapter 1
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 -
(
{
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");
expression("ComplexLoop[{A}].Grid1[{_2}].rating");
expression("ComplexLoop[{A}].Grid1[{_3}].rating");
ComplexLoop_B_1_rating categorical
expression("ComplexLoop[{B}].Grid1[{_1}].rating");
491
Base Professional
FlipGrid
Retrieves flipped data from SourceGrid. SourceGrid contains the originally collected data;
DestinationGrid (used for OnNextCase events) stores the flipped data.
FlipGrid(SourceGrid, DestinationGrid, QuestionNameForFlip,IterationFilter)

SourceGrid Object Grid question
DestinationGrid Object Grid question
QuestionNameForFlip Text The categorical question name for
being flipped (optional).
IterationFilter None Categorical for iteration filter.
The default is NULL.
(return) Boolean True if the flip is successful.
Remarks

When DestinationGrid is a categorical loop with only one nested categorical question,
and SourceGrid is a categorical loop, which may 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 may be some iteration categories for DestinationGrid that do not exist in the question
categories for sub-questions in SourceGrid, or there may 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).
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",
492
Chapter 1
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})

493
Base Professional
The value for MyFlipLoop is as follows:

LevelID Type
{ Like } {B}
{ Dislike } {A}
RemoveCategory
Removes the deprecated OldCategory from MDMObject (often used in the OnJobEnd event).
RemoveCategory(MDMObject, QuestionName, OldCategory)

MDMObject object The name for the MDM document
that contains QuestionName.
QuestionName string The name of the question object
from which oldCategory will be
removed.
OldCategory string The category item being moved
from QuestionName.
(return) Boolean Returns True if moving
oldCategory is successful,
otherwise returns False.
Remarks
The category OldCategory may exist in defined categories for categorical questions, iteration
categorical, or defined question categories for loop questions.

The QuestionName question type is categorical, loop numeric, or loop categorical.
Example
RemoveCategory(mdmObject, "cat", "snake")
The following table illustrates changes after running the above example:
Before Removing After Removing
cat - categorical [1..] cat - categorical [1..]
{ {
Dog -, Dog -,
Goldfish -, Goldfish -,
Panda -, Panda -,
Giraffe -, Giraffe -,
snake -, DonKnow -
DonKnow -
}; };
RemoveCategory(mdmObject, "MyLoopCatQuestion", "snake")

494
Chapter 1
MyLoopCatQuestion - loop MyLoopCatQuestion - loop
{ {
A "A", A "A",
B "B", B "B",
C "C", C "C",
D "D" D "D"
} fields - } fields -
( (
rating "rating" rating "rating"
categorical [1..1] categorical [1..1]
{ {
Dog "Dog", Dog "Dog",
Goldfish "Goldfish", Goldfish "Goldfish",
snake "snake", Panda "Panda",
Panda "Panda", Giraffe "Giraffe"
Giraffe "Giraffe" };
};
) expand grid;
) expand grid;
RemoveCategory(mdmObject, "MyLoopLogicQuestion", "snake")
MyLoopLogicQuestion - loop MyLoopLogicQuestion - loop
{ {
Dog "Dog", Dog "Dog",
Goldfish "Goldfish", Goldfish "Goldfish",
Panda "Panda", Panda "Panda",
Giraffe "Giraffe", Giraffe "Giraffe"
snake "snake"
} fields - } fields -
( (
YesOrNo categorical [1..1] YesOrNo categorical [1..1]
{ {
Yes "Yes", Yes "Yes",
No "No" No "No"
}; };
) expand grid; ) expand grid;
ReplaceCategory
Replaces oldCategory with newCategory for a loop/categorical questions (used for OnNextCase
events).
ReplaceCategory(Question, oldCategory, newCategory)

Question object Category question or loop
question.
oldCategory string Category item that will be
replaced with newCategory.
495
Base Professional

newCategory string The new category value that
replaces oldCategory.
(return) Boolean True when oldCategory
successfully replaces
newCategory, otherwise False
Remarks
For each question, the oldCategory can be an iteration category, a question category for a loop
question, or a category for categorical question.

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"
};
{
A "A",
B "B",
C "C",
D "D"
} fields -
(
{
Dog "Dog",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
Serpent " Serpent "
};
496
Chapter 1
) expand grid;
MyLoopLogicQuestion - loop
{
Dog "Dog",
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.
SubtractQuestion
Subtracts the values for one or more questions (used for OnNextCase events).
497
Base Professional
SubtractQuestion(ResultCat, CatVar1, CatVar2,...)

CatVar1 object Categorical question
CatVar2 object Categorical question
ResultCat object Categorical question.
ResultCat.Response.value =
catVar1.Response.Value -
catVar2.Response.Value-…-
catVarN.Response.Value
(return) Categorical ResultCat.Response.Value
Remarks
The value for question being subtracted from the first question (CatVar1) can be zero. In this case,
the ResultCat value is same as the CatVar1 value.

Questions can contain special responses, such as DK / NA/ REF, but the questions will be
adjusted to the related special response for CatVar1.
Example
SubtractQuestion(Result4, Spont, Prompt1, Prompt2, Prompt3)
The definitions for Result4, Spont, Prompt1, Prompt2, and Prompt3 are as follows:
Spont categorical [1..]
{
Dog -,
Goldfish -,
Panda -,
Giraffe -,
snake -,
SpontDK - DK,
SpontREF - REF,
SpontNA - NA
};
Prompt1 categorical [1..]

{
Dog -,
Goldfish -,
Panda -,
Giraffe -,
snake -,
Prompt1DK - DK,
Prompt1REF - REF,
Prompt1NA - NA
};
498
Chapter 1

{
Dog -,
Goldfish -,
Panda -,
Giraffe -,
snake -,
Prompt2DK - DK,
Prompt2REF - REF,
Prompt2NA - NA
};

{
Dog -,
Goldfish -,
Panda -,
Giraffe -,
snake -,
Prompt3DK - DK,
Prompt3REF - REF,
Prompt3NA - NA
};
Result4 "What animal you like? (Do not read the list)" categorical [1..]
{
Dog "Dog",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
SpontDK "SpontDK" DK,
SpontREF "SpontREF" REF,
SpontNA "SpontNA" NA
};
The related values are as follows:

Question Case 1 Case2
Spont { SpontRef } {SpontDK}
Prompt1 {snake,Griaffe,Goldfish } {Prompt1DK}
Prompt2 { dog,goldfish,giraffe } {Prompt2NA}
Prompt3 {giraffe,dog} { Prompt3NA }
Result4 { SpontRef } {}
SumQuestions
Sums the value for more than one categorical question (used for OnNextCase events).
499
Base Professional
SumQuestions(TotalCat, CatVar1, CatVar2, CarVar3,,,)

CatVar1 object Categorical question. The number
of questions varies, but there
should be at least two questions.
CatVar2 object Categorical question. The number
of questions varies, but there
should be at least two questions.
TotalCat object Categorical question. Total-
Cat.response.value=catVar1.re-
sponse.value + catvar2.re-
sponse.value
(return) Categorical TotalCat.Response.Value
Remarks
The question TotalCat will sum the response.value of questions CatVar1, CatVar2, to CatVarN. If
there is only one question, TotalCat will have the same value as CatVar1.

All questions must be categorical.
Questions can contain special responses, such as DK / NA/ REF, but the questions will be
adjusted to the related special response for CatVar1.
Example
SumQuestions(TotalSum4, Spont, Prompt1, Prompt2, Prompt3)
The definitions for TotalSum4, Spont, Prompt1, Prompt2, and Prompt3 are as follows:
TotalSum4 "What animal you like? (Do not read the list)"
categorical [1..]
{
Dog "Dog",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
};
Spont "What animal you like? (Do not read the list)" categorical [1..]
{
Dog "Dog",
Panda "Panda",
500
Chapter 1
Giraffe "Giraffe",
snake "snake",
};
Prompt1 "What animal you like? (read the list)" categorical [1..]
{
Dog "Dog",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
Prompt1DK "SpontDK" DK,
Prompt1REF "SpontREF" REF,
Prompt1NA "SpontNA" NA
};
{
Dog "Dog",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
};
{
Dog "Dog",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
};
The related values are as follows:

Question Case 1 Case 2
Spont { spontDK} {Giraffe}
Prompt1 {Prompt1DK } {Prompt1NA}
Prompt2 { Giraffe } {Prompt2DK}
Prompt3 {Prompt3NA} {Giraffe}
TotalSum4 { Giraffe,SpontNA ,spontDK} {Giraffe,SpontNA,SpontDK}
501
Base Professional
DMOM Scripting Reference
The Data Management Object Model (DMOM) is a set of component objects that are
designed specifically to facilitate data transformations. These objects are generally called from
mrScriptBasic in the Event sections in the DataManagementScript (DMS) File. This section
provides documentation of all of the DMOM objects that are exposed as objects in the DMS file.
In order to make the interview and data cleaning scripting as consistent as possible, the core of
the IBM® SPSS® Data Collection Data Management and Interview object models (DMOM and
IOM, respectively) have been shared. This means that the skills that you develop in scripting
DMS files can also be used for interview scripting. This documentation covers the objects that
are shared in the two object models and includes some properties and methods (such as the
Question.Style property and Question.Ask method) that are designed for use in interview scripting
and not for use in data management. This is noted in the documentation when it is relevant.
Levels Export Component Object Model
The Levels Export component, part of IBM® SPSS® Data Collection Base Professional, can be
used to transfer hierarchical data to flattened data. All levels (unbounded loop) are exported into
different files. Typically, you will use Levels Export when you want change your data format from
hierarchical data to flattened data.
The Levels Export object model describes how the methods and properties are used for exporting
levels data.
Script Packager Component Object Model
The Script Packager component can be used to generate deployable .mrz, .dmz, and mtz packages
(zip archives) for the purpose of integration with IBM® SPSS® Collaboration and Deployment
Services Repository.
The Script Packager object model describes how the methods and properties are used for
generating deployable packages.
Tabulation Services Component Object Model Reference
The Tabulation Services component is used for creating a derived variable based on a given axis
expression. You can modify a variable by setting the axis expression in IBM® SPSS® Data
Collection Survey Reporter, but this does not affect the source variable. If the source variable
is a numeric variable, it will still be still a numeric variable after applying an axis expression.
You may occasionally want to create a categorical variable that is based on the axis expression
modification. You can then use that derived variable to create tables.
The Tabulation Services component is designed for this purpose. The following sample
demonstrates how to use the component.
Sample Script File:TabulationServices.mrs

502
Chapter 1
This example script is based on the Museum sample data set. See Running the Sample Table
Scripts for information on running the example scripts.
The script creates a derived variable based on the axis expression that bands the visits values into
two categories. It also includes a special mean element.
Set TabulationServ = CreateObject("TabulationServices.AxisExpressionServices")

TabulationServ.CreateAxisVariable(TableDoc.DataSet.MDMDocument.Fields["visits"], _
"{visits1 '1 to 10' expression('visits > 0 And visits < 11'), _
visits2 'More than 10' expression('visits > 10'), _
mean 'Mean' mean(visits)}",_
"NewVisits", 0)
' Create the tables
.AddNew("Table1", "NewVisits * gender", "Number of visits by Gender")
End With

TableDoc.Populate()
' Export the tables

With TableDoc.Exports.mrExcelExport
.Properties["HideApplication"] = False
.Properties["UseExcelStyles"] = True
.Export(EXPORT_FILE)
End With
The resulting table after exportation to Excel:

Figure 1-45
503
Base Professional
Weight Component Object Model
The Weight component, part of IBM® SPSS® Data Collection Base Professional, can be used
to define weighting, which you can then use to weight your data. Typically, you use weighting
when you want your data to reflect the proportions of various groups in your target population
more accurately than your data actually does.
DMOM Programmer’s Reference
This section provides a complete reference to the Data Management Object Model (DMOM) for
programmers who are creating applications using the DMOM.
This section provides Visual Studio 7-style documentation and shows the syntax that is used in
Visual Basic .NET and Visual C#. Although the description of the objects, properties, and methods
are relevant to programming in Visual Studio 6, the syntax is slightly different. However, if you
are using Visual Basic 6, you can use the Visual Basic object browser to find out the correct syntax.
Notes
The clean up of the ADO connections, etc. on the Job object is not performed until the object is
destroyed or the Load method is called. This means that after the Job object has been used to run a
transformation, it cannot be used again until it is destroyed or you load a new DMS file.
When programming with DMOM, you must use a single-threaded apartment (STA). For example:
[STAThread]
static int Main(string[] args)
Known problem
Unfortunately some of the topics in this section contain broken links to the MS .NET Framework
SDK v1.1 help, and when you click on them you will see a “This page cannot be displayed” page.
For many of the links, there is an associated topic in the DMOM Scripting Reference section,
but you will need to navigate to it manually.
Interview Scripting
This section provides documentation for using IBM® SPSS® Data Collection Base Professional
to create interview scripts. The following table provides a summary of the documentation in
this section.
What’s New in Interview Scripting 6.0.1 Summarizes changes and additions to this section
between versions
Getting Started A step-by-step guide that walks you through
creating your first interview script.
Writing Interview Scripts In-depth information on the structure and syntax
of interview scripts, as well as how to use styles
and templates to control the presentation of your
interviews.
504
Chapter 1
Testing Interview Scripts Testing and debugging your interview scripts.

Activating Interview Scripts How to make interview scripts available for
interviewing.
Sample Management Describes the facilities that the Sample Management
system provides for managing and accessing
participant (respondent) records.
Quota Control Describes how to implement quota control.
Samples Details of the sample MDD and other
interview-related files that come with the IBM®
What’s New in Interview Scripting 6.0.1

Support for <mrSharedRef> tag. The <mrSharedRef> tag provides support for accessing shared
content. For more information, see the topic Referring to External Files on p. 851.
Refer to the topic Sample mrScriptBasic Files in the IBM® SPSS® Data Collection Developer
Library for information on working with sample scripts.
Getting Started
The topics in this section form an online tutorial that explains how to create a simple interview
script in IBM® SPSS® Data Collection Base Professional using the Interview Scripting Language.
Getting Started walks you through the basic tasks, and gives you some ideas on how to build up
your knowledge. It is designed to be used in conjunction with the rest of the IBM® SPSS® Data
Collection Developer Library, and it contains many links to related topics and sections.
How Long Will It Take?
It should take you between an hour and an hour and a half to work through the whole tutorial.
However, different people work at different speeds and, depending on your existing experience,
you may find that you need more or less time. There is no requirement to complete the tutorial
in one sitting, and you can stop and restart whenever you wish, although it is best to stop at the
end of a topic if you can.
Navigation
You may often find it helpful to read the next and previous topics in the table of contents, although
you may want to come back and do that later. If you follow a link and decide you want to return
to where you were, just click the Back button on the toolbar.
Conventions
This section contains many script samples that you can copy into Base Professional. Some
samples are shown with surrounding information to make the context clear; in this case, the part
of the script that should be copied is highlighted in red, and this is noted in the instructions. If a
script sample is to be copied in its entirety, no highlighting is used.
505
Base Professional
Base Professional does not support breaking question texts over multiple lines, although it does
support breaking lines in other places. Question texts that are shown broken over multiple lines
are broken for ease of reading only and must be typed as one long line, and this is noted in the
instructions.
Contents
The topics in this section are:

1. Creating Your First IBM SPSS Data Collection Interviewer Server Script
2. Writing an Information Item
3. Writing a Text Question
4. Writing an Integer Question
5. Writing a Decimal Question
6. Writing Single Choice and Multiple Choice Questions
7. Writing a Date/Time Question
8. Writing a Yes/No Question
9. Writing and Using a Shared List
10. Writing Repeated Questions
11. Changing the Order of Responses in a List
12. Displaying Multiple Questions on One Page
13. Asking Questions
14. Changing the Order in which Questions are Asked
15. Changing the Look of Your Interview
16. Activating Your Script
Creating Your First IBM SPSS Data Collection Interviewer Server Script
E Open IBM® SPSS® Data Collection Base Professional.

File > New > File
E Click Metadata File. Then, enter MyFirstInterview as the file name and click Open.
This creates your file in Base Professional. The Edit pane shows the metadata section of the file,
which is where you define the questions and responses that make up the questionnaire. The
metadata section contains a line similar to the one shown here:
Metadata(en-us, Question, label)
End Metadata
506
Chapter 1
The language portion of the line (shown here as en–us) will vary according to the regional
settings for your computer. For example, if your regional settings are set for the UK you will
see en–GB instead.
E Click the Web tab at the bottom of the Edit pane to view the Web Routing section of the file.
Figure 1-46
The Routing tab icon
The Web Routing section is where you define the order in which questions are asked and the
circumstances in which they should be asked (see Asking Questions). A script can have different
Routing sections for different contexts, such as Web, CATI and Paper. The default context is
Web, so you see a Web Routing tab.
The Routing section contains the following script:

Routing(Web)
End Routing
E Click the Save button or type Ctrl+S to save your file in a location of your choice. If you forget to
do this, Base Professional will prompt you to save the file the first time that you test the script.
Requirements
Base Professional with Interview Scripting.
Writing an Information Item
An information item displays text on the screen. You use it for texts that are not related to
questions, such as page titles or instructions to respondents or interviewers.
In this tutorial, we’ll use an information item to define a title for the questionnaire. When you run
the interview, the information item looks like this:
Figure 1-47
Tutorial page for an information item
E Click the Metadata tab to go to the metadata section.

Figure 1-48
The metadata icon
E Enter a name for the information item. For this example, enter the name SurveyTitle:
507
Base Professional
SurveyTitle
End Metadata
E Enter the text that will be displayed during the interview. The text must be enclosed in double
quotation marks:
SurveyTitle "Tea Survey"
End Metadata
E Specify that this is an information item by adding the info keyword, and end the statement with a
semicolon:
SurveyTitle "Tea Survey" info;
End Metadata
Note: You do not have to indent your text as shown, but it makes the script clearer, and when you
close and then reopen the script in IBM® SPSS® Data Collection Base Professional, the script
will be indented as shown.
E If the Browser tab is not selected at the foot of the screen, select it now.
E Press F5 to run your script. You should see the survey title and two navigation buttons displayed
on the Browser tab. (You may need to reselect the Browser tab if it is overlaid by another tab.)
E Click the Stop button to stop the script.
You can press F5 to run your script at any time, to test that it is working as desired.
Requirements
Writing a Text Question
A text question requires a text response. Text questions are sometimes called verbatims or open
ends.
508
Chapter 1
In this example, we’ll write a text question that looks like this when you run the interview:
Figure 1-49
Tutorial page for a text question
E Enter a name for the question. It is a good idea to choose question names that reflect the question
text. This question asks for the respondent’s email address so type Email as the question name:
Email
End Metadata
E Now type a space followed by the question text enclosed in double quotation marks:

Email "Please enter your email address."
E Add the text keyword to specify that this is a text question.

Email "Please enter your email address." text
End Metadata
E To ensure a reasonable response, let’s say that the response must contain between ten and 50
characters. Type the allowed response range in square brackets as shown below. End the question
with a semicolon:
Email "Please enter your email address." text [10..50];
End Metadata
E Press F5 to run your script. When this question is displayed, you can either answer it by typing
some text and then clicking Next, or you can press F5 to continue without entering an answer.
Remember that you can press F5 whenever you like to test your script. You might like to do this at
the end of each topic even if this is not specifically mentioned in the task list.
Note: If you cannot enter text for a new topic, your script may still be running from the previous
topic. Click the Stop button to stop it.
509
Base Professional
Requirements
IBM® SPSS® Data Collection Base Professional with Interview Scripting.
Writing an Integer Question
An integer question requires a whole number response; that is, a number without decimals. The
Interview Scripting Language calls this a long question.
In this example, we’ll write a question that looks like this when you run the interview:
Figure 1-50
Tutorial page for an integer question
E Enter the question name followed by a space and then the question text enclosed in double
quotation marks:
Email "Please enter your email address?" text [10..50];
HowMany "How many cups of tea do you drink in an average week?"
End Metadata
E Add the long keyword to specify that this question requires a whole number as its response. (The
example shows this keyword on a separate line, but this is for printing purposes only. You can
type the keyword on the same line as the question text.)
long
End Metadata
E For the purposes of this example, let’s assume that some respondents will not drink tea at all, and
that no respondent can drink more than 99 cups of tea in a week. Type the allowed response range
enclosed in square brackets. End the question with a semicolon.
long [0..99];
End Metadata
Requirements

510
Chapter 1
Writing a Decimal Question
A decimal question requires a response that contains a decimal point and at least one decimal
place. The Interview Scripting Language calls these double questions.
In this example, we will write a question that looks like this when you run the interview:
Figure 1-51
Tutorial page for a decimal question
E Enter a name for the question followed by the question text in double quotation marks:

Email "What is your email address?" text [10..50];
HowMany "How many cups of tea do you drink in an average week?" long [0..99];
HowMuch "How much do you usually pay when you buy a cup of tea?"
End Metadata
E Add the double keyword to specify that this is a double question, and follow this with the range
of acceptable response values (0 to 9) enclosed in square brackets. End the question with a
semicolon. (The example shows this text on a separate line, but this is for printing purposes only.
You can type everything on the same line.)

Name "What is your name?" text [2..40];
HowMany "How many cups of tea do you drink in an average week?" long [0..99];
HowMuch "How much do you usually pay when buy a cup of tea?"
double [0..9];
End Metadata
E If you use F5 to run your interview you will find that you can enter numbers with up to two decimal
places. Facilities are available for setting the number of decimal places to use when writing out
data. For more information, see the topic Questions with Decimal Responses on p. 549.
Requirements
Writing Single Choice and Multiple Choice Questions
Single choice and multiple choice questions offer a list of choices from which respondents may
choose one, or sometimes more, responses. The general name for these types of questions
is categorical.
511
Base Professional
In this example, we will write two categorical questions. The multiple choice question looks
like this when asked:
Figure 1-52
Tutorial page for a multiple-response categorical question
E Enter a name and a text for the categorical question, followed by the categorical keyword to
specify that this is a categorical question:
HowDrink "How do you take tea?" categorical
E Specify how many responses are allowed. In this example, one or more responses are allowed
because you might drink tea in a number of ways. This is known as a multiple-response
categorical question. The number of responses allowed for this question is defined as at least one,
with no maximum, and must be in square brackets:
HowDrink How do you take tea?" categorical [1..]
E Enter the responses for the question. The responses in the list must be separated by commas, and
the whole list must be enclosed in braces. End the question with a semicolon:
HowDrink "How do you take tea?" categorical [1..]
{
Black,
WithMilk,
WithLemon
};
E Response names cannot contain spaces, punctuation, or other symbols, but in this example some
of the responses such as With Milk should be displayed with spaces. For these responses, enter the
text you want to display, enclosed in double quotation marks, after the response name:
{
Black,
WithMilk "With milk",
WithLemon "With lemon"
};
E Add an other response so that respondents can enter some other way of taking tea that has not
been included in the list of choices. Just like the rest of the responses in the list, the other response
has a name, OtherTakeTea, and an optional label, “Some other way”. The addition of the other
keyword is what specifies that it is a special response. An other response has a text box so that the
respondent can enter text.
{
Black,
WithMilk "With milk",
512
Chapter 1
WithLemon "With lemon",

OtherTakeTea "Some other way" other
};
E The second categorical question allows only one answer to be chosen and is known generically as
a single-response categorical question. It looks like this when asked:
Figure 1-53
Tutorial page for a single-response categorical question
E Define the question as follows. Notice that the response range is defined as [1..1], meaning that
only one response may be chosen. You can abbreviate this to [1] but when you close and reopen
the file you will see that it has changed to [1..1].
BagOrLoose "Do you mostly use tea bags or loose tea?" categorical [1..1]
{
TeaBags "Tea bags",
LooseTea "Loose tea"
};
E Press F5 to run your script.
Requirements
Writing a Date/Time Question
Questions that require a date, a time, or a date and time as the response are known as date
questions.
In this example, we will write a date question that look like this when you run the interview:
Figure 1-54
Tutorial page for a date/time question
E Enter the question name, the question text, and the date keyword. End the statement with a
semicolon:
TeaTime "At what time are you most likely to have a cup
of tea?" date;
513
Base Professional
E When you run the interview you may enter times in 12-hour or 24-hour format; for example,
2:30pm or 14:30.
Requirements
Writing a Yes/No Question
Questions that allow only a yes or no (true or false) response are known as boolean questions.
In this example, we will write a boolean question that looks like this when asked:
Figure 1-55
E Enter the question name, question text, and the boolean keyword followed by a semicolon.
GetNewsletter "Click the checkbox if you would like to receive

our online newsletter" boolean;
Because the question does not have a yes/no response list, only one check box is displayed. This
corresponds to a Yes (or true) answer. Anyone who does not click the box is assumed to have
given a No (false) answer.
Requirements
Writing and Using a Shared List
Some interview scripts may contain a number of categorical questions that use the same response
list. Rather than retyping the response list for each question or copying it from one question to
another, you can define the response list as a shared list and then use it with each question that
needs those responses.
In this example, we are going to have two categorical questions that ask respondents to choose
one or more teas from a list of tea types. The first question is a multiple choice question where
respondents are asked which types of tea they drink; the second is a single choice question that
asks which is their favorite tea.
You can define shared lists anywhere in the interview script, but when you close and reopen the
file you will see that the lists have been moved to the top of the metadata section.
514
Chapter 1
E Enter a name for the shared list and follow it with the define keyword:
TeaList define
E Enter the response list exactly as you would for a categorical question. Categories that contain
spaces or other non-alphanumeric characters must have a display text as well as a name. End
the list with a semicolon:
TeaList define
{
Assam,
Darjeeling,
LapsangSouchong "Lapsang Souchong",
Gunpower,
Ceylon,
China,
Oolong,
EnglishBreakfast "English Breakfast",
Black,
Rooibos,
Puerh,
EarlGrey "Earl Grey",
Green,
OrangePekoe "Orange Pekoe",
FruitHerbal "Fruit/Herbal"
};
E Now write a multiple-response categorical question that uses the shared list. Enter the question
name, question label, type, and number of allowed responses for the TeaDrink question as follows:
TeaDrink "Which of the following teas do you drink?" categorical [1..]
E Instead of writing the list of responses, specify that the question uses the TeaList shared list:

{
use TeaList
};
E Now write a single-response categorical question that asks which is the respondent’s favorite tea.
The only difference between this and the previous question is the specification for the allowed
number of responses:
FavoriteTea "And which is your favorite type of tea?" categorical [1..1]

{
use TeaList
};
E Add an Other response for respondents whose favorite tea does not appear in the shared list:

{
use TeaList,
OtherTea "Other Tea" other
};
Requirements

515
Base Professional
Writing Repeated Questions
When one or more questions are to be asked more than once, you define them inside a loop.
Depending on the number and type of questions inside the loop, you will either see one page of
questions for each repetition, or you will see a tabular display for all repetitions together, which
is called a grid.
In this example, the loop contains one categorical question and will be displayed as follows
when you run an interview:
Figure 1-56
Tutorial page for a repeated question
E Enter the loop question. This loop will ask the WhereProduced categorical question for each tea
in the TeaList shared list. Each question will have the response list of countries that is defined
within the loop.
WhereProducedLoop "Which country or countries produces ...?" loop
{
use TeaList
} fields
(
WhereProduced categorical [1..]
{
China,
India,
Japan,
Kenya,
SouthAfrica "South Africa",
SriLanka "Sri Lanka"
};
) expand;
Note: The expand keyword at the end of the definition tells the interviewing program to write the
data in a flat rather than hierarchical format.
516
Chapter 1
The structure of this definition is more complex than that of the other definitions you’ve typed
so far. In particular, notice the different bracketing mechanisms: braces for shared lists and
response lists, and ordinary parentheses for the fields definition as a whole.
Requirements
Changing the Order of Responses in a List
You may want to change the order in which the responses to your questions are delivered.
Rotating, randomizing or reversing the order can help counteract respondents’ tendency to choose
the first recognized and available option. Alphabetic sorting in either ascending or descending
order can help respondents quickly find a particular response in a long response list.
E Navigate to the TeaDrink multiple-response categorical question:

{
use TeaList
};
E We want to randomize the list of responses, so that each time the question is asked, the responses
will be displayed in a different order. This helps avoid bias in the responses. Enter the ran
keyword to specify that the list of responses should be randomized:

{
use TeaList
} ran;
E Now navigate to the FavoriteTea question and add the keywords sublist asc to sort just the list of
teas in ascending alphabetical order whenever this question is displayed. The OtherTea response
will always be the last response displayed.

{
use TeaList sublist asc,
OtherTea "Other Tea" other
};
Notice that although both questions use the same shared list, we have not added the ordering
keywords to the shared list’s definition. Instead, we have added the ordering keywords to the
questions that use the list. This is because we want to be able to choose the ordering sequence for
each question. If you always want to apply the same ordering sequence whenever a shared list is
used, then you can place the ordering keyword inside the list definition.
Requirements

517
Base Professional
Displaying Multiple Questions on One Page
The interviewing program normally presents each question on a separate page. You can have
several questions appear on the same page by using a page statement.
E Enter the following questions:
Age "How old are you?" long [18..99];
Gender "Are you...?" categorical [1..1]
{
Male,
Female
};
MaritalStatus "Are you .... ?" categorical [1..1]
{
Single,
MarriedOrCohabiting "Married/Living with partner",
Divorced,
Separated,
Widowed
};
Income "What is your annual household income?" categorical [1..1]
{
Under20K "Under 20,000",
I20To30K "20,000 to 29,999",
I30To40K "30,000 to 39,999",
I40To50K "40,000 to 49,999",
Over50K "50,000 or more"
};
E Now add a page statement that displays all four questions on the same page:
Demographics page(Age, Gender, MaritalStatus, Income);
E If you press F5 to run your script now, you will see the questions displayed on separate pages. This
is because you need to write a statement in the Routing section of the script that tells IBM® SPSS®
Data Collection Base Professional or the interviewing program to display the Demographics page
rather than the individual demographic questions. You’ll do this in the next section.
Requirements
Asking Questions
The Routing section determines the order in which questions are asked, the way the interview
pages will look, and the validation of the answers that the respondent gives.
A Routing section is not required. If there is no Routing section, the questions are delivered in the
order in which they appear in the metadata section as they have been so far when you’ve used F5.
E We will start by inserting the simplest form of routing, where all of the questions defined in the
metadata section are delivered in the order in which they appear in the metadata, so click the
Web (Routing) tab.
E If the Metadata View pane is not visible to the right of the Routing pane, right-click in the Routing
pane and select Show Metadata from the pop-up menu.
E In the Metadata View pane, right-click the Fields folder and choose Copy as Ask.
518
Chapter 1
Figure 1-57
Metadata Pane with pop-up menu
E Paste into the Routing section. This will insert routing so that all of the questions defined in the
metadata section are delivered in the order in which they appear in the metadata.
Routing(Web)
SurveyTitle.Ask()
Email.Ask()
HowMany.Ask()
HowMuch.Ask()
HowDrink.Ask()
BagOrLoose.Ask()
TeaTime.Ask()
GetNewsletter.Ask()
TeaDrink.Ask()
FavoriteTea.Ask()
WhereProducedLoop.Ask()
Age.Ask()
Gender.Ask()
MaritalStatus.Ask()
Income.Ask()
End Routing
E The metadata section defines a page called Demographics that presents the Age, Gender,
MaritalStatus and Income questions all on one page. We want to display this page rather than
the separate pages for these questions, so replace the lines for these questions with a single line
containing the text Demographics.Ask().
E Press F5 to run your script. Answer the questions or just keep pressing F5 to continue to the end of
the survey. To stop running the interview before it is complete, click the Stop button.
519
Base Professional
Requirements
Changing the Order in which Questions are Asked
As you ran the interview, you probably noticed that the order in which you defined the questions is
not the best order in which to ask them. For example, it might be better to ask for the respondent’s
email address only if the respondent wants to receive the online newsletter. You do not have to
alter the order of questions in the metadata section in order to do this. Just change the order in
which the questions are asked by the Routing section.
E In the Routing section, cut and paste the lines for the GetNewsletter and Email questions so that
they appear as the last questions in the interview and in the following order:
GetNewsletter.Ask()
Email.Ask()
End Routing
E We only want email addresses for respondents who want to receive the online newsletter, so
we need to apply a filter to the Email question. Make the following highlighted additions to
the Routing section:
If GetNewsletter.Response.Value = True Then
Email.Ask()
End If
E Press F5 to run an interview. When you reach the GetNewsletter question, click the check box and
then click Next. The Email question will be displayed. When you finish the first interview, click
F5 again to run another interview and this time when you reach GetNewsletter, click Next without
clicking the check box. The Email question will not be asked.
Requirements
Changing the Look of Your Interview
Applying a Template
Templates can quickly change the look of your whole survey. You can apply templates to the
layout of whole pages and the layout of individual questions.
E In the Routing section, enter the following highlighted text at the top of your script to add the
Blue Card template.
Routing(Web)
IOM.LayoutTemplate = "Card_Blue.htm"
E Press F5 to run the script to see how the template modified the appearance of the interview in
the browser pane.
520
Chapter 1
The Blue Card template is included in the default DDL installation, in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Templates folder.
Since this is defined in IBM® SPSS® Data Collection Base Professional as the Global Templates
Folder, Base Professional knows to look for the template there.
Applying a Style
Styles offer detailed control of the appearance of every aspect of your survey.
E Enter the following highlighted text at the top of the Routing section to make the survey title
dark blue, 36 point size, and bold.
Routing(Web)
SurveyTitle.Label.Style.Color = "darkblue"
SurveyTitle.Label.Style.Font.Size = 36
SurveyTitle.Label.Style.Font.Effects = FontEffects.feBold
E Press F5 to run your script. Open the browser pane and see how the script looks.
Figure 1-58
Title page with bold, dark blue, 36-point text
E Click the Stop button to stop the script at any time.
Requirements
Base Professional with Interview Scripting
Activating Your Script
Activating your script makes it available for test and live interviewing with IBM® SPSS® Data
Collection Interviewer Server.
521
Base Professional
E From the menu select

> Tools > Activate
This opens the Activate dialog box in which you define the requirements for the project. (The
Activate command tries to log you in to the activation process using a trusted user account
before it displays the dialog box. If this fails, you will see a login dialog box. Enter your IBM®
SPSS® Data Collection Interviewer Server Administration user name and password, and click
OK to continue.)
E The default settings are sufficient for your first interview script, so click Activate.
E On the Confirm Activate dialog box, click Yes.
E You’ll see a progress indicator displayed while the project is being activated, followed by a
message box confirming that activation is complete. Click OK to close the message box.
E To run an interview using Interviewer Server, open your browser and enter the following URL,
where server_name is the name of your interviewing server. If you have Interviewer Server
installed on your local machine you can use localhost as the server name if you wish.
http://server_name/mrIWeb/mrIWeb.dll?I.Project=MYFIRSTINTERVIEW&i.test=1
E The questions will be displayed in your browser as they were in IBM® SPSS® Data Collection
Base Professional, but this time you will have to answer each question as it is displayed.
If you are unable to activate your script, it may be because the name of the project management
server has not been set in Base Professional. The project management server is the machine that
stores information about each project, such as the location of the project’s files, the project’s
status, and other parameters that control how the project will work. Follow the steps below to
specify the name of the project management server.
E From the menu select

> Tools > Options
E On the Options dialog box, type the name of the server in the input box to the right of the Project
Management Server label. If you have Base Professional and Interviewer Server installed on your
local machine you can enter localhost as the server name, otherwise check with your Interviewer
Server administrator what name you should type here.
522
Chapter 1
Figure 1-59
IBM SPSS Data Collection Base Professional Options dialog box
E Click OK.
Requirements
Base Professional with IBM SPSS Data Collection Interviewer Server 6.0.1.
Writing Interview Scripts

This section gives detailed information on all of the facets of creating an interview script.
The goal of this section is to give you an understanding of why and how you may create an
interview script using the Interview Scripting Language. It is not a reference section, and so
it contains many links to the relevant reference topics elsewhere in the IBM® SPSS® Data
What is an Interview Script?
You write interview scripts in the mrScriptBasic language, which is based on Visual Basic, and
mrScriptMetadata. mrScriptBasic and mrScriptMetadata were developed so that market research
data types and expression evaluation can be supported natively in the script, something that is
not possible in Visual Basic or Java.
523
Base Professional
Unlike scripts written with some other interview scripting tools, interview scripts written in
mrScriptBasic and mrScriptMetadata make a distinction between metadata (the questions and
responses) and routing (the logic that controls when and how questions are asked, how questions
and responses are presented, and who sees which questions). This distinction makes it easier
to reuse both metadata and routing either for new questionnaires or for different modes of
interviewing on the same questionnaire.
Interview scripts have an .mdd file extension. You can edit them using any text editor, but IBM®
SPSS® Data Collection Base Professional offers a full-featured development environment for
interview scripting.
An interview script has two or three sections depending on the requirements of the interview.
These are the Metadata, Routing, and Events sections.
The Metadata Section
This section is written in and defines the question texts, the question types, and the response
texts. It also defines information texts such as instructions for respondents or interviewers, as
well as any other text — project or page titles, for example — that may need to be translated.
All interview scripts must have this section.
When you create a new interview script in Base Professional, the default Metadata section
looks like this:
End Metadata
en-us is the language, Question is a the context, and label is a the label type. It is not
mandatory to specify the language, context, or label type, as defaults will be used if they are
not provided. See , and for more information.
A very simple Metadata section with one categorical question looks like this:
LikesBest "Which tea do you like best?" categorical [1..1]
{
Assam,
Darjeeling,
China,
Ceylon,
Other
};
End Metadata
You can define questions in any order in the Metadata section because it is the Routing section that
determines the order in which they will be presented. However, if you leave the Routing section
empty, questions will be presented in the order they appear in the Metadata section.
When writing metadata statements, you can use almost any layout that you like. However, if
you close and reopen an .mdd file in Base Professional, you will notice that Base Professional
reformats (or rehydrates) the script so that it similar to the one shown above. Each component of
the question’s definition is placed on a separate line, and indentation is used to show the hierarchy
of the definition. In addition, shared list definitions are moved to the top of the script and page
statements are moved to the bottom.
524
Chapter 1
The Routing Section
This section is written in mrScriptBasic and defines the order and circumstances in which
questions should be asked. It also defines the presentation characteristics for questions and
other display items.
A very simple Routing section that specifies a template to use and asks two questions in sequence
looks like this:
Routing(Web)
TeaDrink.Ask()
LikesBest.Ask()
End Routing
In this example, Web is the routing context. The routing context determines how the script will
behave in a particular situation and, in this instance, it determines how self-completion, browser
based interviews will work. Other contexts that you might have include Paper, for printed
questionnaires (or those created using the Build activity in IBM® SPSS® Data Collection
Interviewer Server Administration), and CATI for outbound CATI interviewing. You do not have
to specify the routing context because the default is undefined, meaning that the routing logic will
be the default for all routing contexts.
Most interview scripts have a Routing section, but it may be omitted if questions are to be asked
in the order they appear in the Metadata section and all questions apply equally to all respondents.
When writing routing statements you must type each statement on a separate line. Statements
must not be split across lines.
Anatomy of Routing
A diagrammatic example of a Routing section looks like this:

Figure 1-60
Diagram of a Routing section
The Routing section contains these types of statements:

mrScriptBasic
Figure 1-61
Diagram of a Routing section with mrScriptBasic statements highlighted
and
525
Base Professional
Figure 1-62
Diagram of a Routing section with expression evaluation and function library statements highlighted
Interview Object Model (IOM)

Figure 1-63
Diagram of a Routing section with Interview Object Model objects highlighted
Events
Events define actions that are to be carried out at specific points such as at the start or end of the
interview. You define them in the Routing section using a Sub statement:
Sub OnBeforeQuestionAsk(Question, IOM)

' Do something here
End Sub
For more information, see the topic Events on p. 918.
Viewing the Routing and Metadata
If you view an interview script in a text editor, you will see the Metadata and the Routing sections
one after the other. For example:
Routing(Web)
Age.Ask()
Gender.Ask()
End Routing
Metadata (en-us, Question, label)
Age "How old are you?" long [18..99]
Gender "Are you ...?" categorical [1..1]
{
Male "Male",
Female "Female"
}
End Metadata
In Base Professional, the Routing and the Metadata are shown on two separate tabs.
526
Chapter 1
Figure 1-64
IBM SPSS Data Collection Base Professional window with the Metadata and Routing tabs highlighted.
Scriptwriting Rules and Recommendations
Rules
Do not waste time laying out statements in the metadata section in a particular way if you are
using IBM® SPSS® Data Collection Base Professional. The mrScriptMetadata DSC that
reads the .mdd file reformats the metadata section each time it opens a file.
Note: Due to screen and printing constraints, the example scripts and script snippets in the
interview scripting documentation do not always use this layout. Instead, scripts have been
laid out to fit on a printed page and to minimize scrolling when viewed on-screen.
Statements in the routing section may be split across lines as long as each line except the last
ends with an underscore symbol.
Include the expand keyword in all grid and loop definitions. The RDB DSC does not yet
support hierarchical data so the data must be flattened.
Recommendations
In the metadata section

Make questions and information items names reflect the purpose or content of the question or
item.
Avoid names that are the same as or very similar to interview scripting keywords.
Give questions and other items mixed case names.
527
Base Professional
Define unique response names for the special Other, No Answer, Don’t Know, and Refuse to
Answer responses rather than using a dash (–). Using a dash generates a response whose name
matches the special keyword, and this is unlikely to be unique within the script as a whole.
Do not include special responses such as other or na, or response ordering keywords such
as rot or ran in shared lists unless you want these responses and settings to apply every
time the list is used.
In multiple-language projects, use info statements in the metadata section of the script for all
non-question text that requires translation. Any text that exists in the routing section cannot
be translated and will always be displayed in the questionnaire’s base language. This is
particularly important for error messages.
When setting Initial text that should be replaced, put the text in brackets; for example, “<Type
your answer here>”.
If style, validation, and response constants apply to all routing contexts, set them in the
metadata section. For example, default values for questions typically apply to all routing
contexts, so should be set in the metadata section. Conversely, some styles may only apply to
a specific routing context, so should be set in that context in the routing section.
In scripts that copy information between the interview and the sample record, use similar
names for questions and sample fields that are related. For example, if the Age sample field
contains the participant’s age you might call the question in the script QAge. Alternatively,
you might decide to give all sample fields names that start with “Sample”, so the Age question
in the script could refer to the SampleAge field in the sample record. If your script has sample
quotas, you may want to use identical names for questions and sample fields. For more
information, see the topic Sample Quotas when you have No Access to the Sample Database
on p. 1083.
In the routing section

Use indentation and blank lines to make the structure of the section easy to follow. (When
working in Base Professional, you may indent using tabs but select the option that converts
tabs to spaces to ensure a smooth transition to other tools.)
Give temporary (Dim’d) variables lower-case names and place these declarations at the top of
the routing section.
Give constants upper-case names.
Use comments to explain complex code blocks.
Use the curly brace notation when referring to categorical values rather than enclosing values
in double quotation marks; for example: Q1.Categories[{Other}].
Use category names rather than indexes when referring to categorical values as this makes
scripts easier to read. For example, in a loop called Color in which red is the fourth item in the
loop control list, use If (Color[{Red}].Likes.Response = {No}) rather than If
(Color[3].Likes.Response = {No}) to test whether the respondent likes red.
Use If...Then with End If rather than using the single-line syntax.
Start all label names (used for Gotos) in column 1.
528
Chapter 1
Start Sub and Function declarations and Ends in column 1, but indent their contents.
It is easy to create infinite loops when using Goto, so consider replacing Goto with an If
statement with the appropriate condition. For example, rather than:
If Q1 = {Yes} Then Goto Q3X

Q2.Ask()
Goto Q4X
Q3X:
Q3.Ask()
Q4X:
Q4.Ask()
use:
If Q1 <> {Yes} Then

Q2.Ask()
Else
Q3.Ask()
End If
Q4.Ask()
Always type object references in full. Object references can often be abbreviated by assuming
that default properties will be used wherever a property name is not defined. However, this is
bad programming practice and should be avoided, especially when writing interview scripts
that other people may work on. For example, use Q1.Response.Categories[{Other}]
instead of Q1.Response.Other since the latter can be used only if the category is named
Other. The exceptions are Item and Value so, for example, use Q1.Response rather than
Q1.Response.Value.
Put JavaScript in separate .js files and use an <mrRef> tag to include them in the template file.
When writing a loop where the number of repetitions is controlled by the response to a
numeric question, define the number of repetitions in full rather than using the abbreviated
[..variable_name] notation. Loops defined using this notation use a lower boundary of 0
which means that the loop will be repeated one more time than you will normally require. In
addition, always ensure that you define a start value that is greater than 0 otherwise the same
problem will arise. For example, if you write:
PersonLoop.QuestionFilter = NumPeople
PersonLoop.Ask()
and PersonLoop is defined in the metadata section as either:
PersonLoop loop [..8] fields

(
...
)
or:
PersonLoop loop [0..8] fields

(
...
)
the loop will be repeated for 0 to NumPeople times, which is one more time than required.
529
Base Professional
Efficient Scripting
Try to define default styles in a template or cascading stylesheet rather than using the
DefaultStyles object.
When a series of routing statements applies to the same object, for example, you are defining a
number of styles for the same question, use a With statement to define the portion of code
that is common to all statements rather than typing each statement in full. For example:
With Sports.Label.Style.Font
.Family = "'Palatino Linotype', 'Times New Roman'"
.Size = 16
.Effects = FontEffects.feBold + FontEffects.feItalic
End With
rather than:
Sports.Label.Style.Font.Family = "'Palatino Linotype', 'Times New Roman'"
Sports.Label.Style.Font.Size = 16
Sports.Label.Style.Font.Effects = FontEffects.feBold + FontEffects.feItalic
Use a single For Each statement rather than [..] when setting more than one property in a
collection, as each instance of [..] is equivalent to a For Each statement. For example:
Dim ThisCat
For Each ThisCat in Sports.Categories
With Category.Style
.ImagePosition = ImagePositions.ipImageOnly
.ElementAlign = ElementAlignments.eaRight
Width = 100
End With
Next
is more efficient than:

Sports.Categories[..].Style.ImagePosition = ImagePositions.ipImageOnly
Sports.Categories[..].Style.ElementAlign = ElementAlignments.eaRight
Sports.Categories[..].Style.Width = 100
Templates
Templates should meet XHTML standards; in particular, all tags should be written in lower
case and each opening tag should have a closing tag.
Default templates should use a cascading style sheet.
Default templates should use relative fonts.
Define layout characteristics as styles in the metadata section rather than in the routing section
or in templates if you want them to carry forward into other products such as IBM® SPSS®
Data Collection Survey Tabulation or IBM SPSS Data Collection Survey Reporter.
Samples
The IBM® SPSS® Data Collection Developer Library contains many sample interview
scripts that you can use as the basis for your own scripts, or that you can run to learn
more about how a particular feature works. These scripts are normally installed into
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview.
New scripts are being added to this folder all the time, so each time you install a new version of
Data Collection Developer Library you will see new files. To find out more about the scripts, read
the InterviewScripts_ReadMe.htm file in the Interview folder.
530
Chapter 1
Comments
Comments are important for making your interview script understandable to other people, and
documenting the intentions of the code. To write a comment in either the Metadata or the Routing
section, type:
' Comment text
A Non-Programmer’s Guide to the Interview Object Model
The Interview Object Model (IOM) defines the components of an interview script, the
characteristics of those components, and the way that those components relate to one another.
It is related to the Routing section of the interview script and to the mrScriptBasic language in
which the Routing section is written.
As the title explains, this topic is designed to provide an overview of the Interview Object Model
in terms that are easy for scriptwriters and other non-programmers to understand. It is not the
intention of this topic to teach or explain object oriented programming, except in so far as such
explanations are necessary to describe the Interview Object Model. Even then, explanations
have been kept as simple as possible and are at all times related specifically to the structure and
behavior of the Interview Object Model. You should not assume that concepts described here
apply directly or in part to any other form of object oriented programming.
What is IOM?
The Interview Object Model (IOM) defines the components of an interview script, the
characteristics of those components, and the way that those components relate to one another.
It is related to the Routing section of the interview script and to the mrScriptBasic language in
which the Routing section is written.
You may find it useful to have a copy of the Interview Object Model diagram to hand as you read
this section so that you can refer to it as you go. The text that follows contains links to topics
in the IOM documentation which you can follow if you wish. These links are provided simply
as a means for you to learn how the IOM components fit together, and there is no requirement
for you to read the topics, although you may do so if you wish. Note, however, that the Object
Model documentation is targeted at programmers and assumes some knowledge of object oriented
programming concepts.
Objects
Objects are the components of the interview script so, for example, questions are known as
Question objects, and categorical responses are known as Category objects.
Objects are made up of different items and sometimes the same type of item will be present in
more than one object. For example, a question consists of a question name, a question text,
a question type (categorical or text, for example), and an appropriate response definition. A
categorical response consists of a response name and a response text. Even though question and
response texts will differ in the interview, they are the same type of item so they become an object
531
Base Professional
in their own right in IOM. IOM calls text items Label objects. It defines what a Label object is,
and gives each Question and Category object its own Label object.
IOM defines many objects, the most important of which are:

IOM The whole interview script.
Question Questions. Each question has its own Question
object.
Category Categorical responses. Each categorical response
has its own Category object.
Label Text strings such as questions, categorical responses,
and texts on navigation buttons.
Style The visible appearance of an item.
Navigation Navigation items such as the Next button.
Response Answers given to a question.
Take a moment to look at the Interview Object Model diagram and you’ll see a “map” of the
Object Model that has these objects as the top-level objects. You’ll also see how the Label and
Style objects are used within most of the other objects because most of the other objects have texts
and visible display characteristics. This hierarchy is important when it comes to writing code in
the Routing section and we’ll come back to it later.
Something else you’ll notice in the Object Model diagram is that some boxes are shaded whereas
others are not, and often the text of an unshaded box is the same as that of its related shaded
box, except that the text in the unshaded box is plural. For example, the IOM object contains a
Navigations item that contains a Navigation object.
In these cases, the unshaded box represents a collection of the corresponding shaded items; in
the example, Navigations is a collection item that contains one or more Navigation objects. If
we relate this to an interview, it means that an interview can use one or more navigation buttons.
Similarly, the Question object contains a Categories collection item that consists of Category
objects. In interviewing terms, this means that if the question allows a categorical response, the
question will contain a collection of Category objects each defining one categorical response.
Note: The Object Model diagram provides an overview of the more important objects in the
Object Model. There are many more objects in IOM, all of which are described in the IOM
documentation. You can access all of this documentation from the Object Model diagram by
clicking on an object in the diagram and then following the links on the individual documentation
pages.
Properties
All objects have properties. Each property defines a specific characteristic of the object.
Sometimes a property is actually another object or a collection item containing objects, but it can
also be a simple entity that defines one particular thing. For example, the Style object has a Color
property that defines the color of the object to which it belongs.
532
Chapter 1
If the Style object is attached to a Label object within a Question object, then the Color property
defines the color of the question text; if the Style object is attached to a Label object within a
Category object, then the Color property defines the color of that categorical response text. To see
other examples of simple properties, click any Style object in the Object Model diagram and then
click on any of the Read/Write Property links on the IStyle page.
Typical properties for collection items are Count, which returns the number of objects in the
collection, and Item, which returns the item in a given position in the collection (for example,
the first item).
Properties can be read-only or they may be readable and writable. You can query the values of
read-only properties in the routing script. You can set the values of read-write properties to control
the way an item looks or behaves in an interview. We’ll look at how to do this later in this section,
and you’ll find numerous examples in the rest of the Interview Scripting documentation.
Type Definitions
Type Definitions define constants (variables with fixed values) that you can use when you need to
assign a specific value to a property. For example, if you want to display a categorical response
text in italics, you can set the value of the font effect property for that category’s label to be the
name of the italic font effect Type Definition.
The values that a particular property can have are grouped within a single Type Definition, so
all the values related to font effects (italics, bold, underlined, and so on) are grouped under the
FontEffects Type Definition. Each value within a group has a unique name and value. You do
not need to worry about the values, all you need are the names. All names in a group start with
the same two-character code which is related in some way to the name of the Type Definition.
Using this standard, all font effect names start with the letters fe — fe.Italic, fe.Bold, fe.Underline,
and so on.
Operations
You can perform actions on objects. In object oriented programming, actions are referred to as
operations or methods. One action that you will always use is the Ask action for the Question
object because this is how you ask questions. Another action that you might use is the Terminate
action belonging to the IOM object: this terminates the interview immediately. There are other
operations belonging to these and other objects but you are unlikely to use them in Routing scripts
(they exist for use in other applications written in mrScriptBasic).
How do I Refer to Objects in Routing Scripts?
IOM has a hierarchical structure, so whenever you want to run an operation (method) or assign
a value to a property you must specify the exact location of that operation or property in the
hierarchy. The general syntax for these specifications is:
object1.object2.object3
533
Base Professional
where object1 is the top-level object in the hierarchy, object2 is an object within object1, and
object3 is a property or operation within object2. The reference can contain any number of
objects separated by dots.
The easiest way to understand how this works is to look at some examples of things most people
want to do in their scripts. You’ll find more detailed information for each of these examples in the
relevant sections of Writing Interview Scripts. As you read through this section you may find
it useful to have the Interview Object Model diagram available for reference. Follow the links
to the object documentation pages if you want to, but don’t worry if you don’t understand the
page content at the moment.
Asking Questions
Let’s start with the main point of an interview; that is, asking questions. This is a easy example
because the logic behind what you type is simple. However, we’ll look at it in the same way
that we will look at more complex examples.
E The task you want to perform is related to a question, so you know that you will be using the
Question object. This makes the Question object the top-level object for this statement.
E The next step is to consider what you want to do with this object. You want to ask a question,
so you need to use the Ask operation. This makes Ask() the second item in the statement. This
makes the statement Question.Ask(). However, this will not work because you have not said
which question you want to ask. To do this, replace the reference to the Question object with the
question name. If you want to ask the question whose name is prefer, the statement becomes:
prefer.Ask()
and this is what you type in the Routing section.
Setting Styles
Now suppose that you want to display the text of the prefer question in red. If you follow the
procedure, you start by asking what part of the interview you’re working on. It’s a question so
you use the Question object, and you already know that because you are defining something for a
specific question you use the question’s name instead of the word Question.
E The next thing to decide is what part of the question you are working with. It’s the question text,
and the object related to texts of all types is the Label object. This gives you:
prefer.Label
E The part of the text you want to control is its color, which is a visual attribute. Anything to do
with the way something looks on the screen is controlled by the Style object, so you extend the
specification to read:
prefer.Label.Style
E The Color property defines an item’s color, so the full specification for the item to be changed is:
prefer.Label.Style.Color
534
Chapter 1
E All that remains is to specify the color to be used. You want red text, so what you type in the
Routing section is:
prefer.Label.Style.Color = "red"
prefer.Ask()
Here is the statement that displays the categorical response texts for prefer in italics:
prefer.Categories[..].Label.Style.Font.Effects = FontEffects.feItalic
Let’s look at the left-hand side of the assignment first. Categories is a collection item and the [..]
that follows it means “all items in the collection”. Label.Style refers to the category text, and
Font.Effects refers to the way you want the text to be displayed (italics, bolding, underlining, and
so on are called font effects in IOM).
The right-hand side of the assignment specifies the italic font effect we want. The values that
represent the font effects are stored in the FontEffects Type Definition. Each effect has its own
name, but all effects start with the letters fe. Because the Type Definition has its own hierarchical
structure, you define the effect to be set using the same notation as for other hierarchical references.
Grids
The syntax for referring to the cells of a grid is quite long, but once you understand how it works
it’s quite easy to use. A grid consists of row headings, column headings (which may be repeated
in long grids), and grid cells. In most grids, the row headings come from the loop definition
itself, while the column headings come from the response list to the repeated question that is
inside the loop. You refer to these texts in the same way that you refer to ordinary questions
and their responses.
The cells inside the grid are formed by combining a row characteristic with a column
characteristic — for example, by combining gender and age — and in order to refer uniquely
to one cell you need to identify both the row and the column that form the cell. You do this
by starting statements with:
Gridname[..].Qname.Categories[..]
where:
Gridname is the name of the grid (loop) item. The [..] after the name means “all repetitions
of the loop”. If you want to refer to a particular repetition, replace .. with a number for a
number or a categorical text as appropriate. For example, TeaLoop[{Assam}] to refer to the
repetition for Assam tea.
Qname is the name of a question inside the loop.
Categories[..] refers to all the responses to Qname. To refer to a particular
response, replace .. with a number or categorical text as appropriate. For
example:Countries.Catagories[{China}] to refer to the “China” response.
Following these rules, you can refer to the cell formed by Assam and China by starting a
statement with the text:
TeaLoop[{Assam}].Countries.Categories[{China}]
535
Base Professional
For example, to give the cell a pink background you would type:
TeaLoop[{Assam}].Countries.Categories[{China}].Style.Cell.BgColor="pink"
Writing Scripts
These statements, and the last one in particular, look confusing when you’re new to interview
scripting, but you don’t have to remember all the object and property names, or the way that
they all link together, although you’ll find that this becomes easier the more Routing scripts you
write. If you write your scripts using IBM® SPSS® Data Collection Base Professional, you can
use the ScriptAssist feature to help you choose the right objects in the right order. Simply put,
ScriptAssist displays a pop-up list of valid choices whenever you type a dot in an object reference.
Just scroll down the list and select the item you want to insert at this point. In the most recent
example, all you would have to type on the left-hand side of the = sign is the question name, the
[..], and the dots between the objects. All the rest you could select from pop-up lists. For more
information, see the topic Using ScriptAssist on p. 43.
Here are some diagrams that show which objects refer to which elements of an interview page.
The first one shows a simple categorical question and the objects associated with the texts, boxes,
and buttons on the page:
Figure 1-65
Categorical question showing object names for question text, check box, response text, other response,
and navigation button text
536
Chapter 1
The next diagram shows the same question but with different styles applied:
Figure 1-66
Categorical question showing object names for styles
The IOM Object
The IOM refers to the interview as a whole, and its properties define characteristics that either
apply to the whole interview or act as defaults unless overridden at a lower level. The objects and
properties you are most likely to use are as follows:
Banners A collection of Label objects that can be used to
display titles at the top of interview pages.
DefaultStyles A list of Style objects, one for each of the standard
page elements so that default styles can be set for
the interview.
Errors A collection of Label objects, one for each of the
standard error messages. You can use this property
to replace the default messages with texts of your
own, or to define the appearance of the message
texts.
Language The default interviewing language for multilingual
scripts.
LayoutTemplate The page template to use. (Other Template
properties are available for specific items on a the
page.)
MustAnswer Whether respondents may leave questions
unanswered (that is, click Next without entering or
selecting a response).
Navigations A collection of Navigation objects.
NextPage The page object for the next page. This gives you
access to page level properties for the next page,
and is a good way to change a default setting for
one page only.
Questions A list of questions in the script.
537
Base Professional
The Question Object
The Question object defines the characteristics of a question. Each question object is named using
its question name. Questions inherit their characteristics from the IOM and NextPage objects,
but these can be overridden for individual questions. The Question properties you are most
likely to use are as follows:
Banners A collection of Label objects that can be used to
display non-question text above the question.
Categories A collection of categories; that is, the responses in a
categorical response list.
Errors A collection of Label objects, one for each of the
standard error messages. You can use this object to
replace the default messages with texts of your own,
or to define the appearance of the message texts.
Label The question text.
LayoutTemplate The page template to use for this question only.
(Other Template properties are available for specific
items on a the page.)
MustAnswer Whether respondents may leave this question
unanswered (that is, click Next without entering or
selecting a response).
Response The response chosen for this question. This property
is valid only with simple questions; it is not valid for
questions defined in loops, blocks or other similar
constructs.
Style The Style object for the current question. You can
use this to override any interview-level or page-level
settings, and to set the styles of questions in loops,
blocks and compound items.
The Category Object
The Category object represents one response (category) in a categorical response list. When using
this object, you must include the response’s name in the object name, as follows:
Category["ResponseName"]
The Category properties that you are most likely to use are as follows:
Index The response’s position in the response list.
Numbering starts at zero for the first item in the list.
Label The response’s text based on the active language,
routing context and label type.
Style The Style object for the response. This allows you
to override the default presentation styles just for
this response. For example:
Q4.Category["NoneOfThese"].Style.Color = "Dark Blue"
538
Chapter 1
The Label Object
The Label object controls the text for questions, banners, errors and navigation controls. Label
properties that you might use are:
Text The label’s text.
Style The Style object for the label. You can use this for
changing the text’s visual attributes.
The Style Object
The Style object defines the way questions, categories, labels and navigation controls will be
presented during the interview. Style properties that you might use include:
Align Horizontal alignment.
BgColor Background color.
Cell Cell properties in a grid.
Color The element’s color.
Columns The number of columns for a categorical response
list.
Control Properties for a control (for example, for a check
box).
Font Font characteristics such as family, effect, and size.
Height The vertical size of the element (for example, the
height of an input box).
Hidden Whether to hide the item.
Image Names an image file associated with the element.
ImagePosition The position of an image file relative to the text.
Orientation The direction in which to display responses in a
categorical list.
Rows The number of rows for a categorical response list.
Width The horizontal size of the element (for example, the
width of an input box).
VerticalAlign The vertical alignment of the item.
The Navigation Object
The Navigation object defines the characteristics of navigation elements on the screen. Navigation
properties you might use are:
Label The text for the navigation control based on the
active language, context, and label type.
Style The Style object for the label. Use this to define the
navigation’s presentation characteristics.
539
Base Professional
The Response Object
The Response object refers to the answers given to a particular question. You can also use it to
assign responses to questions, for example, when you want to assign a default response to a
question.
Default The default answer for the current question. This is
used if the respondent does not enter or select an
answer.
Initial The initial answer for the current question. This is
a useful way to pre-fill grids in which respondents
need to make a few selections only.
Other A collection of Other Response objects. You can use
this collection to extract answers that the respondent
entered for “Other”.
Questions and Responses
You define all the questions in the questionnaire in the metadata section of the interview
script. You can write the metadata for your interview in IBM® SPSS® Data Collection Base
Professional, or you can import metadata that has been created with another interview tool, such
as Build on the IBM® SPSS® Data Collection Interviewer Server Administration platform.
The interviewing program recognizes a number of different question and response types. The
interview scripting language uses the following keywords to identify these types:
boolean A question requiring a True or False value as the
response.
categorical A question requiring the respondent to select one or
more answers from a predefined list of responses.
date A question requiring a date and/or time as the
response.
double A question requiring a numeric response that can
contain decimals.
long A question requiring a whole number response.
text A question requiring a text response
This section also covers the following:

Non-alphanumeric characters in question and response texts.
Using HTML tags in question and response texts.
The Ask statement that you use in the routing section to ask the questions you have defined in
the metadata section.
Keywords for No Answer, Don’t Know, Refused to Answer, and Other Specify responses.
Allowing respondents not to answer questions
Questions with no columns in the case data file.
Defining default answers for questions.
Setting initial values for responses.
Working with .
540
Chapter 1
Questions with Categorical Responses
Categorical is the general term for a single-choice or multiple-choice response. When you
define a categorical question, you define the responses from which choices may be made, and
the number of choices that will be allowed.
This section introduces the following keywords that you can use in the metadata section when
defining categorical responses:
categorical Identifies a categorical question
exclusive A single-choice response in a multiple choice list
namespace Make ‘duplicate’ responses unique
This section explains how to:

Define questions with categorical response lists
Include single-choice responses in multiple-choice lists
Use subheadings in response lists
Use namespacing to differentiate between duplicate response names in a response list
Defining Categorical Response Lists
To define a question with a predefined set of possible responses, place the following statement in
the metadata section of the interview script:
Qname "Text" categorical [[NumChoices]]
{
ResponseName1 ["ResponseText1"],
...
ResponseNamen ["ResponseTextn"]
};
where:
Qname is the question name.
Text is the question text.
NumChoices is a single number or a range specifying the number of responses that may
be chosen from the list. If you omit this parameter, respondents may leave the question
unanswered.
ResponseName1 to ResponseNamen are the names of the responses from which the choices
may be made.
ResponseText1 to ResponseTextn are the response texts.
A categorical response list may contain any number of responses (approximately 4 billion is the
theoretical maximum). Respondents may select any number of responses and all the chosen
responses will be written to the case data, and will be correctly processed by IBM® SPSS® Data
Collection Survey Tabulation. However, the SPSS MR OLE DB provider (mrOleDB.2) is only
able to return the first 200 categories, so if you have an application that accesses the data using this
provider you may lose data if respondents have chosen more than 200 responses for a question.
541
Base Professional
Response Names and Response Texts
As the syntax statement shows, each response has a name and a response text. The response text
(referred to as the label in some documentation) is the full text of the response as you want it to
appear during the interview or on a printed questionnaire. It may contain any combination of
letters, numbers, punctuation, and other characters. Depending on the response’s name, you may
be able to omit the response text from the definition and display the response name instead.
The response name is a single word that is used by the interviewing program and other SPSS
applications for identifying the response. It must start with a letter. The rest of the name may
contain letters, numbers, or the underscore (_) character. If the response text is a single word that
satisfies the criteria for a response name, you can define just a response name and the interviewing
program and the printed questionnaire will display this as the response text.
Here is an example of a question with a single-choice response list. The question text has been
split across two lines for display purposes only. When you type question texts you should type
them all on one line with no line breaks:
LastEatOut "And the last time you ate out, what type of
restaurant did you go to?" categorical [1..1]
{
Indian,
Chinese,
Greek,
Italian,
English,
WestIndian "West Indian",
French,
Thai,
Japanese,
Spanish,
Turkish,
Other
};
There are several things to notice about this example:

The West Indian response has a response name and a response text because the text you want
to display consists of two words. None of the other responses contains spaces or any other
special characters so you need only specify the response name.
Each response is shown on a separate line. This is the standard way that IBM® SPSS® Data
Collection Base Professional displays interview scripts. You can type more than one response
on a line if you wish and, in some instances, the documentation shows response lists in this
format if this allows a complete example to displayed on one page. However, when you close
and reopen an interview script, response lists will always be shown as in this example.
This example contains a simple Other response that respondents who went to a different type
of restaurant can select. It is not a special Other Specify response that automatically prompts
the user to enter an associated text response. For details about Other Specify responses,
see Other Specify.
The [1..1] identifies this as a single-choice response list. This means that the responses will
be displayed with radio buttons during the interview and respondents will be able to select
only one answer from the list. If you omit this parameter respondents may leave the question
unanswered. You can abbreviate the number of responses required for single-choice response
lists to [1], but when you close and reopen the file, this will be converted to [1..1].
542
Chapter 1
Here is another example that illustrates a situation when you must always define response names
and response texts. Most of the response texts you want to display start with a number. Response
names cannot start with numbers so you must choose different names for each response:
ChildAge "How old are your children?" categorical [1..]
{
YUnder1 "Under 1 Year",
Y3_5 "3-5 Years",
Y6_12 "6-12 Years",
Y13_16 "13-16 Years",
Y17_18 "17-18 Years",
Y19_21 "19-21 Years",
YAdult "Over 21 Years"
};
Note: If you need to use a double quotation mark in a question or response text, you must type it
as " so that it is not interpreted as a quotation mark that encloses text.
How Many Responses can be Chosen?

When the respondent must choose a fixed number of responses, type that number enclosed in
square brackets. The interviewing program will not allow respondents to move to the next
question unless they have chosen the specified number of responses. For example:
KeyPoints "From the following list, what are the <b>two</b> main points
you consider when choosing a restaurant for a family celebration?"
categorical [2..2]
{
Price, Location,
ChildrenWelcome "Children are welcome",
ChildMenu "Children's menus",
FoodChoice "Wide choice of dishes",
Vegetarian "Vegetarian options available on the main menu",
SpecialDiet "Special diets catered for",
Ambience "General feeling and ambience",
NoSmoke "Non-smoking",
AllowsSmoking "Smoking allowed"
};
If you do not specify the number of responses required, the interviewing program allows
respondents to leave the question unanswered.
The usual method of setting up a multiple-choice response list is to specify the number of
responses as [1..], meaning that one or more responses may be chosen. For example:
FoodLiked "What types of food do you like?" categorical [1..]
{
Indian, Chinese, Greek, Italian,
English, WestIndian "West Indian",
French, Thai, Japanese, Spanish,
Turkish, Other
};
You can specify the maximum number of responses that can be chosen from a multiple choice
list by typing, for example:
UsuallyCook "When you cook for friends, which types of food do you
usually cook? You may make up to three choices." categorical [..3]
{
Indian, Chinese, Greek, Italian, English,
WestIndian "West Indian",
French, Thai, Japanese, Spanish, Turkish,
Other
};
543
Base Professional
Because there is no minimum number of responses defined, respondents may leave this question
unanswered. If you want respondents to answer the question you must specify a minimum number
of choices, so most questions of this type would specify a range such as [1..3].
Single-Choice Responses in a Multiple-Choice List
If you want to force respondents to answer all applicable questions in an interview, and you have
multiple-choice questions where they are asked to choose responses from a list, you may want
to include a response such as “None of these” that respondents can use when they are unable to
select any of the predefined responses. For example, if you ask respondents to choose the brand
that they normally use from a list of brands, and the normal brand is not one of those listed,
respondents may choose “None of these” to continue with the interview.
In order that respondents cannot select this response with any other responses in the list, you will
need to flag it as a single-choice response by using the exclusive keyword as follows:
Qname "Text" categorical [num_resps]
{
multiple-choice_responses,
single-choice_response exclusive
};
For example:
RestaurantType "When you go out for a meal, what types
of restaurant do you normally visit?" categorical [1..]
{
Indian, Chinese,
Oriental "Other Oriental",
Italian, French,
European "Other European",
RestaurantTypeNone "None of these" exclusive
};
The interviewing program displays exclusive responses in a bold font as a signal that they may
not be chosen with other responses.
Exclusive responses can appear anywhere in a response list, and a response list can contain
more than one such response. This often happens when a response list contains the special
responses for No Answer, Don’t Know, or Refused (see Special Responses for details). Also, if
the response list is sorted in some way, it is common for exclusive responses to be flagged as fixed
so that they always appear at the same point (usually the end) in the list (see Responses with
Fixed Positions in the Response List for details).
Note: An alternative to a “None of these” response is an Other Specify response. This allows
the respondent to type a text response that can be coded later on. For more information, see
the topic Other Specify on p. 562.
Subheadings in Response Lists
Subheadings are a means of grouping similar or related responses in a list. For example, if the
response list contains a number of statements about a product, you might group the responses
according to whether they are favorable or unfavorable comments. If there are many responses or
the response texts are long, this immediately helps respondents find the general type of comment
they want to make. Similarly, in a list of cars, you might use the different makes of car such
544
Chapter 1
as Ford or Volkswagen as subheadings and then list the various models under the appropriate
subheadings. As before, this makes it easy for respondents to find specific answers in the list (it’s
also easier for you or anyone else who needs to add responses to the list).
The general syntax for defining subheadings is:
Qname "Text" categorical [[NumChoices]]
{
Subhead_name1 ["Subhead_text1"]
{
Responses
},
...
Subhead_namen ["Subhead_textn"]
{
Responses
}
};
where:
NumChoices in the number of responses that must be chosen. If you omit this parameter,
respondents may leave the question unanswered.
Subhead_name1 to Subhead_namen and Subhead_text1 to Subhead_Ttextn are the subheading
names and display texts (labels).
Responses are the responses from which the choices may be made, specified with names and
display texts if appropriate.
Notice in particular the comma that separates the subsections. Each subsection has a subheading
followed by a collection of responses enclosed in braces, and each subsection is separated from
the next by a comma.
In the following example, responses have been grouped under two subheadings:
OrganicFood "There is an increasing interest in organically produced
food. What are your thoughts about this?" categorical [1..]
{
AgainstOrganicFood "Thoughts against"
{
Expensive "It's too expensive",
NotGoodLandUse "It doesn't make the best use of the land",
NotProven "There's no proof it's better than other food",
LaborIntensive "It's too labor intensive",
OtherNegative "Other thoughts against" other
},
ForOrganicFood "Thoughts for"
{
GoodForYou "It's good for you",
BuyItMyself "I buy organic food whenever I can",
GoodForLand "It's better for land",
GoodforWildlife "It's better for wildlife",
OtherPositive "Other thoughts for" other
},
NoThoughts "I have no opinions about organic food" exclusive
};
545
Base Professional
When this question is displayed during an interview it looks like this:

Figure 1-67
Category list with subheadings
If you have responses with identical names in more than one subsection, you will need to use
namespacing to force the response names to be unique. For more information, see the topic
Responses with Duplicate Response Names on p. 545.
Responses with Duplicate Response Names
When you write a categorical response list, you give each response in the list a unique name
which you normally use as the response text as well. As long as the response names are unique
within the question, it does not matter to the interviewing program or the case data file whether
the response texts are unique or not. This is important only for respondents so that they can
differentiate one response from another.
You can create questions whose response lists have one or more responses in common. For
example, in a survey about eating out, you may want to use the same restaurant name or type of
food in more than one response list. Perhaps you will have a question that asks respondents which
types of restaurants they go to when they eat out, and another question that asks which types of
food they cook when they entertain friends at home. The response names in each list are identical
but, because they appear in different questions, the interviewing program is able to differentiate
between them by inserting the question name in front of each response name. So, if Indian food
appears in the response lists for the EatOut and EatIn questions, the interviewing program treats
the response names as EatOut.Indian and EatIn.Indian.
This process of inserting the question name at the start of a response name is called
namespacing, and the response name that it creates is called the Fullname.
546
Chapter 1
As long as the duplicate response names appear in different questions, you do not normally
need to bother about namespacing when working in the metadata section because it happens
automatically. The exception is when you have a single question with a response list that needs to
have responses with identical names. The example below illustrates a typical scenario.
FoodProgs "Which of these food programs have you watched during
the last three months?" categorical [1..]
{
TVSat "On a TV or Satellite Channel"
{
HellsKitchen "Hell's Kitchen",
GoodFoodLive "Good Food Live",
CookingForOne "Cooking for One"
},
VideoDVD "On Video or DVD"
{
},
Internet "On the internet"
{
},
None "None of these" exclusive
};
In this example, each subsection contains the same programs, so you want to use the same
response name for each one. If you are using IBM® SPSS® Data Collection Base Professional
and you save the interview script as it is shown here, it will be saved as an .ivs file but not as an
.mdd file because of the duplicate response names. What makes the programs unique is the fact
that they appear under different subheadings. So, you need to specify that the response names
should be namespaced using the subheading names. This will generate fullnames for the programs
such as TVSat.HellsKitchen, VideoDVD.HellsKitchen, Internet.HellsKitchen, and so on. To do this,
place the namespace keyword at the end of each subsection definition, as follows:
FoodProgs "Which of these food programs have you watched during
the last three months?" categorical [1..]
{
{
} namespace,
{
} namespace,
{
} namespace,
None "None of these" exclusive
};
547
Base Professional
Questions with Integer Responses
When a question requires a whole number (integer) as a response, define it in the Metadata section
of the interview script as:
Qname "Text" long [[Values]];
where:
Values are the numbers or range of numbers that will be accepted as valid responses. If you
omit this parameter, the interviewing program will accept any whole number in the range
−2,147,483,648 to +2,147,483,647.
Responses of this type are stored in the case data as 32-bit signed integers.
You can define the numbers that will be accepted as valid responses as single values, ranges of
values, or a combination of single values and ranges.
A Fixed Range of Values
When the answer may be any number within a fixed range, type:
long [Minimum..Maximum];
For example:
PartySize "The last time you ate out, how many were there
in your group?" long [1..20];
Open-ended Ranges
Sometimes it is convenient to define a range with a fixed minimum value but no maximum, or with
a fixed maximum value but no minimum. In these cases, the interviewing program substitutes the
system default for the unspecified value. You define open-ended ranges as follows:
long [Minimum..];
or:
long [..Maximum];
For example:
EatOutTimes "Roughly how many times have you eaten out this
year?" long [1..];
EatInTimes "And how many times this year have you cooked for
friends?" long [..99];
A List of Single Values or Ranges

long [Value1, Value2, ... Valuen];
where:
Value1 to Valuen are either single whole numbers or ranges of whole numbers.
548
Chapter 1
For example, respondents may answer the following question with any of the values 4, 7, 10,
11, 12, 13, or 14:
NumberOfDays "How many days would you like the documents for?"
long [4,7,10..14];
Exclusive Values
Sometimes the easiest way to define valid responses is to allow all numbers in a given range but
with some exceptions. These exceptions may be single values or ranges of values. To write this
type of specification, define the full range first and then follow it with the values or ranges you
wish to exclude, with each one preceded by a ^ symbol:
long [Range, Êxclude1, ... Êxcluden];
In the following example any number between 100 and 130 is valid except 109 to 115 inclusive
and 126:
DocCode "Please enter the numeric code for the documents
you would like to borrow."
long [100..130,^109..115,^126];
Stepped Values
Occasionally you may have a range in which the numbers increment be a common value other
than 1. Rather than listing all values separately, you can specify the lowest and highest values
in the range and an incremental value that will be used to determine which other values will be
considered part of the range. To specify this type of range, type:
long [Minimum..Maximum step Increment];
For example, a survey related to usage of national census returns may ask:
CensusOnline "Which year's census returns would you most like to
have available online?"
long [1841..1901 step 10];
This assumes that national censuses occurred every ten years between 1841 and 1901 inclusive.
Allowing a Thousands Separator Character
The interviewing program does not normally accept a thousands separator character in large
numbers. For example, in countries that use a comma as the thousands separator, the number
1,500 will be rejected even if it is within the range specified for the question. If you want the
interviewing program to accept thousands separators in numeric responses, place the following
statement in the routing section of the questionnaire before the question is asked:
Qname.Validation.Options["AllowThousandsSeparator"] = True
where Qname is the name of a question with a numeric response.

The character that the interviewing program accepts as the thousands separator depends on the
language or locale set for the interview. The language can be set in the script itself, otherwise it
defaults to the language set in the respondent’s browser. This can be overridden by setting the
interview’s locale in the script. The Locale property defines the language to be used for data
549
Base Professional
input and output and for validation. For example, if the interview language is set to French, the
interviewing program expects respondents to use a space as the thousands separator and a comma
as the decimal point. If the script sets the locale to English, the interviewing program will then
expect a comma for the thousands separator and a dot for the decimal point.
The Locale property normally mirrors the Language property so that when the language changes
so does the locale. However, if you specify the locale manually this breaks the link between the
two properties and any subsequent language changes do not affect the locale setting. For more
information, see the topic Using Locale to Control Decimal Number and Date Formats on p. 886.
Note: AllowThousandsSeparator is provided primarily to maintain backwards
compatibility with early versions of the interview scripting language, in which the default was to
require the use of thousands separator characters.
Number of Digits to Write
To specify the maximum number of digits that can be written, append the precision keyword
to the standard question definition:
Qname "Text" double [[Values]] precision(NumDigits);
where:
NumDigits is the maximum number of digits.
Questions with Decimal Responses
When a question requires a decimal number as a response, define it in the Metadata section
of the interview script as:
Qname "Text" double [[Values]];
where:
Values are the numbers or range of numbers that will be accepted as valid responses. If you
omit this parameter, the interviewing program will accept any negative value in the range
−1.79769313486232e308 to −4.94065645841247e−324 and any positive value in the range
4.94065645841247e−324 to 1.79769313486232e308.
You specify valid responses for decimal questions in the same way as for integer questions, so
single values, fixed and open-ended ranges, lists of single values and ranges, and exclusive values
are all acceptable. For more information, see the topic Questions with Integer Responses on p. 547.
Decimal responses are stored in the case data as double variables — that is, as 64-bit floating
point values with 15 digits of precision. You can control the data format by specifying:
the number of decimal places to store in the case data
the number of characters to store for the number as a whole
550
Chapter 1
Decimal responses are stored in the case data as double variables — that is, as 64-bit floating
point values with 15 digits of precision. You can control the data format by specifying:
the number of decimal places to store in the case data
the number of characters to store for the number as a whole
Decimal Point Character
The character you use for the decimal point when specifying values depends on your computer’s
locale/culture/language setting. For example, if your setting is en–UK you will use a dot (1.2, for
example); if your setting is en–DA you will use a comma (1,2). The character that respondents
must use depends on the language that the script sets for the interview or, if none is set, the
language set for the respondent’s browser.
You can make the decimal point character independent of the interview language by specifying
a language in the IOM.Locale property. The Locale property defines the language to use for data
input and output and response validation. Normally, it is the same as the IOM.Language property,
so if the language changes so does the locale. If you want all respondents to use the same character
for the decimal point, you may specify a language that uses that character as the interview
locale. For example, if you want all respondents to use a dot for the decimal point you may set
IOM.Locale to English (en–us, for example). This overrides the language setting, so respondents
may see questions and responses in French but they will still have to enter prices and similar
values in the English format. (See also “Allowing a Thousands Separator Character” below.)
Note: Specifying the locale manually breaks the link between the two properties so any
subsequent language changes do not affect the locale setting.
Number of Digits to Write
To specify the maximum number of digits that can be written, append the precision keyword
to the standard question definition:
Qname "Text" double [[Values]] precision(NumDigits);
where:
NumDigits is the maximum number of digits.
In the following example, the weight will always be written as four digits.
Weight "What is your weight in kilograms?"
double [47.5..160] precision(4);
Number of Decimal Places

To specify the maximum number of decimal places that can be entered, append the scale keyword
to the standard specification:
Qname "Text" double [[Values]] scale(NumDigits);
where:
NumDp is the maximum number of decimal places.
551
Base Professional
In the following example, more than two decimal places cannot be entered for the price of the meal:
Cost "What was the total cost of the meal, including service?"
double scale(2);
Allowing a Thousands Separator Character
The interviewing program does not normally accept a thousands separator character in large
numbers. For example, in countries that use the comma as the thousands separator, the number
1,512.89 will be rejected even if it is within the range specified for the question. If you want the
interviewing program to accept thousands separators in numeric responses, place the following
statement in the routing section of the questionnaire before the question is asked:
Qname.Validation.Options["AllowThousandsSeparator"] = True
where Qname is the name of a question with a numeric response.

The character that the interviewing program accepts as the thousands separator depends on the
language or locale set for the interview. The language can be set in the script itself, otherwise it
defaults to the language set in the respondent’s browser. This can be overridden by setting the
interview’s locale in the script. The Locale property defines the language to be used for data
input and output and for validation. For example, if the interview language is set to French, the
interviewing program expects respondents to use a space as the thousands separator and a comma
as the decimal point. If the script sets the locale to English, the interviewing program will then
expect a comma for the thousands separator and a dot for the decimal point.
The Locale property normally mirrors the Language property so that when the language changes
so does the locale. However, if you specify the locale manually this breaks the link between the
two properties and any subsequent language changes do not affect the locale setting. For more
information, see the topic Using Locale to Control Decimal Number and Date Formats on p. 886.
Note: AllowThousandsSeparator is provided primarily to maintain backwards
compatibility with early versions of the interview scripting language, in which the default was to
require the use of thousands separator characters.
Questions with Text Responses
Questions that allow text responses are sometimes referred to as open ends or verbatims, and they
allow respondents to type any text in response to the current question. This text is saved in the
case data exactly as typed and is often manually coded once interviewing has finished so that the
information in the responses can be analyzed with the precoded data.
To define a question with a text response, type:
Qname "Qtext" text [[Length]];
where:
Qtext is the question text.
Length is the number of characters you will allow in the response text.
552
Chapter 1
Text questions are often used when you want to obtain respondents’ opinions on a particular
subject in their own words. Since you’ll want responses to be as detailed as possible, you will not
usually specify a length for the response text. In this case, the interviewing program will allow
respondents to enter up to 4000 characters, which is the maximum number of characters that can
be stored in a column in a relational MR database. (This limit is set in the MR IBM® SPSS® Data
Collection Data Model that IBM® SPSS® Data Collection Interviewer Server uses for storing
case data. You cannot alter it by changing the row limit in SQL.)
Note: Setting the length for the question to a maximum value of 40, or less, results in the text
question being rendered with a single line edit box. Setting the maximum value to 41, or higher,
results in the text question being rendered with a multiple line edit box.
If you use text questions to obtain information such as name and address, telephone, or
membership numbers, you may have some idea of how many characters you expect respondents
to type, or how many characters you wish to record. In these cases you can either enter the text
length as a fixed number (for example, when all membership numbers consist of eight characters),
or as a fixed or open-ended range. Here are some examples. In the first one, the respondent
must enter either seven or eight characters:
UserNumber "What is your user number?"

text [7..8];
The next example allows respondents to enter up to 50 characters for the first line of their address:
Address "What is the first line of your address?" text [..50];
Since the range does not specify a minimum number of characters, you would expect the
interviewing program to accept blank responses, so that respondents who do not wish to give their
names may just click Next to skip the question. This is not what happens.
Every question has a MustAnswer property that is normally set to True so that respondents
must answer the question with a response that satisfies the specification in the question. With text
questions, MustAnswer overrides the MinValue property that stores the minimum number of
characters required, so respondents must enter at least one character to continue. If you want to
allow respondents to skip the question you should set its MustAnswer property to False. For more
information, see the topic Allowing Respondents Not to Answer Questions on p. 563.
Specifying the Required Text Format
Texts such as telephone numbers, membership numbers, or national insurance numbers all have
fixed formats, so you can check the respondent’s answer and reject it if it does not match the
required format. This saves time and problems when you come to use or analyze the data because
you will not have to make arbitrary decisions about what to do with invalid data.
To have the interviewing program validate a respondent’s answer, you need to specify the
required text format as part of the question definition. You do this by appending the validation
keyword and a regular expression to the question definition:
Qname "Qtext" text [[Length]] validation ("Expression");

553
Base Professional
For example, suppose that membership numbers must consist of two letters, six digits, and
then a single letter (for example, AB123456Z). You could test that all texts match this pattern
by defining the question as:
CardNumber "What is your security card number?"
text [9..9] validation ("\u{2}\d{6}\u{1}");
In the example, the validation expression tells the interviewing program that membership numbers
must consist of two upper-case letters, six digits, and one upper-case letter, in that order.
The interviewing program uses the Validate function in the IBM® SPSS® Data Collection
Function Library to validate text responses. You’ll find full details about this function and the
facilities it provides for text validation in the “Regular expression syntax” subsection of , but here
are a couple more examples to give you an idea of what is possible.
JP 99 88 77 L is a typical British National Insurance number. To test that respondents enter
their National Insurance numbers in this format you would type:
NINumber "What is your National Insurance number?"
text [13]
validation ("\u{2}(\s{1}\d{2}){3}\s{1}\u{1}");
The regular expression specifies two upper-case letters, then three repetitions of a space followed
by two digits, then a space and an upper-case letter.
E3 9JP, TN8 5AB, S16 0XX, and WC1H 3ZZ are all valid formats for British postcodes (zip
codes). To accept text responses in any of these formats but no others you would type:
Postcode "And what is your postcode"
text [6..8]
validation ("\u{1,2}\d{1,2}\u?\s{1}\d{1}\u{2}");
This regular expression accepts one or two upper-case letters followed by one or two digits,
followed by zero or one upper-case letters. All texts must end with a space, one digit, and two
upper-case letters.
Questions with Yes/No Responses
When a question may have only a Yes or No (or, more correctly, a True or False) answer you may
define it so that the question variable is created with a boolean data type. To do this, type:
Qname "Text" boolean [{Value1, Value2}];
where:
Value1 and Value2 are the texts to display for the True/Yes and False/No responses. In general,
the first value is the True response and the second value is the False response, but this can
vary depending on the tool used to present the questionnaire.
If you omit the response texts, the interviewing program displays the question text followed by a
single check box. Respondents wishing to answer the question with a Yes or True response
should click the check box, others should just click Next to continue and the interviewing will
save a False value for the question.
554
Chapter 1
Figure 1-68
Boolean question with single check box
The question in this example was specified as follows:
Vegetarian "Tick below if you are vegetarian" boolean;
If you want to define responses for the question, you must define two responses and each must
consist of one word only. The responses are displayed with radio buttons so only one response
may be chosen. For example:
SpecialDiet "Do you follow a special diet (e.g., no wheat, no

dairy)?" boolean
{
Yes, No
};
Questions with Date/Time Responses
When a question requires a date, a time, or a date and time as a response, you define it as:
Qname "Text" date [[Range]];
where:
Range is an optional date/time range specifying which dates and times will be accepted as
responses. If you omit this parameter, any date and time between 0:00:00 on 1 January 100
and 23:59:59 on 31 December 9999 inclusive will be accepted.
The interviewing program displays the question text followed by an input box in which the
respondent may type an answer of up to 20 characters:
Figure 1-69
Date question
555
Base Professional
Formats for Dates and Times
The Interview Scripting Language is very flexible with regard to specifying dates and times. Dates
can be written using letters or numbers for the month and / or – as the separator. Years can be
entered using two or four digits. Here are some examples of the more common date formats:
dd–monthname–yyyy 31–December–2004
dd–mmm–yyyy 31–Dec–2004
mm/dd/yy 12/31/04
yyyy/mm/dd 2004/12/31
Note: If you use the numeric date format and you enter the date as dd/mm/yy (European notation),
the date is treated as if it were mm/dd/yy, so 01/04/05 is always 4 January 2005, never 1 April 2005.
Times may be specified in 12-hour format as hh:mmam or hh:mmpm, or in 24-hour format
as hh:mm.
Whichever methods you use for writing dates and times, your main objective should be to make
the specification unambiguous to anyone who reads the script. If you are unsure who else may
read or edit your script, it may be advisable to use letters rather than numbers for months.
When respondents answer a date question, the way in which they must enter dates is determined
by the locale/culture/language setting of the interview. If the interview language is set to en–US,
then respondents must enter dates in the US format (mm/dd/yy or equivalent). If the interview
language is set to en–UK, then respondents must enter dates in the British format (dd/mm/yy
or equivalent).
Date and Time Ranges

Questions may define just dates, just times, or dates and times. If you specify a date range only,
the interviewing program will accept any time on any date within that date range. If you specify a
time range only, the interviewing program will accept any date as long as the time is within the
given range. If you specify a time and a date, the interviewing program will only accept responses
where both the time and the date are within the given range. When you specify a date and time,
the date must come before the time and must be separated from it by a space.
You can specify date and time ranges in any of the following formats:
A range of values
date ["From".."To"];
For example:
Dob "Please enter your date of birth"
date ["1-Jan-1906".."31-Dec-2006"];
Any date in the given range is acceptable as a response.

Here is an example that uses a time specification:
TimeBooked "What time was your table booked for?"
date ["06:00pm".."11:00pm"];
Respondents may enter any time between 6 o’clock and 11 o’clock at night. These times may be
entered in 12-hour or 24-hour format.
556
Chapter 1
Here is an example with dates and times:

ConsultantTime "And when was your appointment with the
research consultant?"
date ["2-Jan-07 09:00am".."31-Jan-07 05:00pm"];
An open-ended range
date ["From"..];
or:
date [.."To"];
A start date with no end date has an implied end date of 31 December 9999; an end date with no
start date has an implied start date of 1 January 100. For example:
ExpiryDate "When does your driver's license expire?"
date ["31-Dec-2004".. ];
A list of single values or ranges
To specify a list of single dates and/or times or date/time ranges, type:

date ["Dt1", "Dt2"," ... "Dtn"];
where:
Dt1 to Dtn are single dates, single times, or date/time ranges.
For example:
TourTime "When would you like to take the special tour?"
date ["2-Jan-07 09:00am".."15-Jan-07 05:00pm",
"16-Jan-07 01:00pm".."31-Jan-07 07:00pm"];
Exclusive values
To exclude specific dates or times from a range, type:

date ["Range1"[, ..."Rangen"] Êxclude];
where:
Range1 to Rangen define the overall valid date/time range for the question.
Exclude is a date, time or date/time range within the overall range specification that is not
valid. To exclude more than one date, time, or range, enter each one separately, preceded
by a ^ symbol and separated by commas.
For example:
CollectDate "When would you like to collect the documents?"
date ["1-Dec-07".."31-Mar-08",^"25-Dec-07".."26-Dec-07",
^"28-Mar-06"];
Although you can specify a date and time range, you cannot force respondents to enter a date and
a time. If a respondent enters a date without a time, the interviewing program assumes that the
respondent means the current time and will accept the response as long as the current time falls
within the acceptable range for the question. Similarly with dates. If the respondent enters a time
557
Base Professional
but no date, the interviewing program assumes the current date and accepts the response as long as
the current date is within the valid range. All responses appear in the case data as a date and a time.
Special Characters in Question and Response Texts
You can use most characters on your keyboard in question and response texts and, generally, the
character that appears on your screen when you press the key is the character that the interviewing
program will display during the interview. There are, however, a few exceptions.
”. The double quotation mark introduces or terminates a question or response text. If you want to
display this symbol as part of a text, type ".
{. The open curly brace symbol introduces the name of a variable whose value is to be inserted at
that point in the text. To display { as part of the text, type %{. For more information, see the topic
Displaying Answers in Question and Banner Texts on p. 602.
Note: If { is followed by something other than a letter, the interviewing program and IBM®
SPSS® Data Collection Base Professional will display whatever you typed exactly as you typed
it. However, in IBM® SPSS® Data Collection Interviewer Server, the IVW log file will report a
syntax error at the character that follows the {. For example, {$MyText} generates an error in
the IVW file whereas %{$MyText} does not.
%n. This string inserts a line break in the text. You do not normally need to use this as pressing the
Return key usually produces the required result.
Using HTML Tags in Question and Response Texts
The interview scripting language supports a limited number of XHTML tags inside question and
response texts. These are as follows:
Tag Description
<b> ... </b> Bold text
<i> ... </i> Italic text
<u> ... </u> Underlined text
<br/> Line break
For example:
KeyPoints "From the following list, what are the <b>two</b> main points
you consider when choosing a restaurant for a family celebration?"
categorical [2..2]
{
Price, Location,
ChildrenWelcome "Children are welcome",
ChildMenu "Children's menus",
FoodChoice "Wide choice of dishes",
Vegetarian "Vegetarian options available on the main menu",
SpecialDiet "Special diets catered for",
Ambience "General feeling and ambience",
NoSmoke "Non-smoking",
AllowsSmoking "Smoking allowed"
};
558
Chapter 1
Asking Questions
You ask questions by placing statements in the routing section of the interview script. The
simplest way to ask a question is to type:
question_name.Ask()
For example:
RestaurantType.Ask()
EatOutTimes.Ask()
EatInTimes.Ask()
WhenLastEatOut.Ask()
LastEatOut.Ask()
If all questions apply to all respondents and you want to ask the questions in the order they
are defined in the metadata section, you can leave the routing section blank. If you want to ask
questions in a different order, or you want to apply filtering so that some questions are asked of
certain respondents only, then you must write an Ask statement for every question you want to ask.
Asking Certain Sets of Questions Only
If you want to ask a subset of questions, you may find SelectRange useful. This lets you ask all
questions between a starting and ending question — for example, all questions between Q1 and
Q5 inclusive — in the order they appear in the metadata section. To do this, place the following
statements in the routing section of the script:
Dim variable
For Each variable in IOM.Questions.SelectRange("Qstart..Qend")
variable.Ask()
Next
where:
variable is the name of a temporary variable. You may give the variable any name you like
but a name that reflects its purpose is useful.
Qstart is the first question you want to ask.
Qend is the last question you want to ask.
For example:
Dim Question
For Each Question in IOM.Questions.SelectRange("TimeBooked..OrganicFood")
Question.Ask()
Next
Question names are easiest to use when referring to questions, but you can use a numeric range if
you wish. However, be aware that the interviewing program numbers questions from 0 rather
than from 1, so the specification IOM.Questions.SelectRange(1..5) will ask the second
to sixth questions not the first five questions.
559
Base Professional
Special Responses
The interview scripting language provides special keywords for the responses No Answer,
Don’t Know, and Refused to Answer, which you will often want to allow as valid responses for
respondents who are unable or unwilling to answer questions in the normal way. The advantages
of using these keywords are as follows:
In categorical questions, they offer a simple and consistent alternative to defining your own
texts for these responses.
These responses are valid in specifications for text, numeric, and date questions where
categorical response texts are not allowed.
Responses defined using these keywords are saved to the case data in a standard way. If you
export the case data in a coded format such as IBM® SPSS® Quantum™ format, these
responses will be assigned the same codes regardless of which question they belong to or how
many responses there are in the list.
The Interview Scripting Language also provides a special keyword for an Other Specify response.
This response often appears in categorical response lists when you want to provide a response that
can be used when none of the predefined responses is suitable. The response is always presented
with a text box in which respondents can enter their own response to the question.
The keywords associated with these facilities are:
codes Introduces na, dk, and ref in numeric and text
response lists.
dk Don’t Know
na No Answer
other Other Specify
ref Refuse to Answer
You may use any combination of these responses in a response list, and may place them in any
order and in any position in the list. The usual method is to place them at the end of the list in
the order other, na, dk, ref.
When used with numeric, text, and date questions, all special responses are automatically
treated as exclusive responses, so any responses that contain a number, text, or date and have a
special response check box selected will be rejected. With categorical responses, only No Answer,
Don’t Know, and Refuse to Answer are automatically treated as exclusive, and they have an
implicit fix applied to them so that they retain their original positions in the list if the list is sorted.
No Answer
To define a No Answer response in a categorical response list, place the following line in the
question’s response list in the metadata section of the interview script:
ResponseName "ResponseText" na
560
Chapter 1
For example:
MaritalStatus "What is your marital status?" categorical [1..1]
{
Single,
Married "Married/Living with partner",
Divorced "Separated/Divorced",
Widowed,
MaritalStatusNA "Would rather not say" na
};
Respondents may choose any of the listed marital statuses or may choose Would rather not say.
To allow No Answer as a response to a numeric, text, or date question, define the question
as follows:
Qname "Text" Type [Size] codes (
{
ResponseName "ResponseText" na
}
);
For example:
OtherConsiderations "And is there anything else that is important
to you when choosing somewhere to eat?" text codes (
{
NoOtherConsiderations "Nothing else" na
}
);
When the interviewing program reaches this question, it displays a text input box with a No
answer check box below it. Respondents may answer the question by either typing text in the
input box or selecting the check box.
mrScriptMetadata accepts a dash or hyphen (–) as the response name for special responses,
and will generate a response whose name matches the special response keyword (“na” in this
instance). Although this is acceptable scriptwriting, we recommend that you choose unique names
for all categorical responses, including special responses.
If you need to test for No answer responses in the routing section of the script, use
Qname.Response.Coded as described in Checking for Special Responses to Non-Categorical
Questions.
Don’t Know
To define a Don’t know response, place the following line in the question’s response list in the
metadata section of the interview script:
ResponseName "ResponseText" dk
For example:
WhenLastEatOut "When was the last time you went out for a meal?"
categorical [1..1]
{
Yesterday,
ThisWeek "Another weekday during this week",
LastWeekend "Last weekend",
WeeksAgo "A couple of weeks ago",
MonthAgo "About a month ago",
MoreThanMonth "More than a month ago",
LastEatOutDK "Can't remember" dk
};
561
Base Professional
Respondents may choose one of the listed political parties or Can’t remember.
To allow Don’t know as a response to a numeric, text, or date question, define the question
as follows:
{
ResponseName "ResponseText" dk
}
);
For example:
TimeLeft "And roughly what time did you leave the restaurant?"
date ["07:00pm".."11:59pm"] codes (
{
TimeLeftDK "Can't remember" dk
}
);
When the interviewing program reaches this question, it displays an input box with a check box
labelled Can’t remember below it. Respondents may answer the question by either typing a time
in the input box or selecting the check box.
and will generate a response whose name matches the special response keyword (“dk” in this
If you need to test for Don’t know responses in the routing section of the script, use
Qname.Response.Coded as described in Checking for Special Responses to Non-Categorical
Questions.
Refuse to Answer
To define a Refuse to answer response, place the following line in the question’s response list in
ResponseName "ResponseText" ref
For example:
Purpose "What is the purpose of your research?" categorical [1..]
{
General "General interest",
Family "Family history",
Research "A research project",
Legal "Legal work",
Book "Writing a book",
OtherPurpose "Something else",
Refused "Prefer not to say" ref
};
To allow Refuse to answer as a response to a numeric, text, or date question, define the
question as follows:
{
ResponseName "ResponseText" ref
}
);
562
Chapter 1
For example:
HowLong "How many years have you lived at this address?"
long [1..50] codes (
{
Refused "Refuse to answer" ref
}
);
When the interviewing program reaches this question, it displays a numeric input box with a
Refuse to answer check box below it. Respondents may answer the question by either typing a
number between 18 and 99 in the input box or selecting the check box.
and will generate a response whose name matches the special response keyword (“ref” in this
If you need to test for refusals in the routing section of the script, use Qname.Response.Coded
as described in Checking for Special Responses to Non-Categorical Questions.
Other Specify
“Other” is a general purpose response that appears in many categorical response lists to collect
responses other than those specifically mentioned in the response list. Sometimes you will only
want to know that the respondent used some other product or traveled by some other form of
transport, whereas on other occasions you will want to know exactly what other product or mode
of transport was used. In the latter case, the easiest way to obtain this “other” information is to
include an Other Specify response in the response list. This displays a response labelled Other
with a text box in which the respondent may type what Other refers to.
To define an Other Specify response, place the following line in the response list. The usual
place is at the end of the list, but before any other special responses.
ResponseName "ResponseText" other [fix] [exclusive]
For example:
Reason "What was the reason that you ate out then?"
categorical [1..]
{
Anniversary "Wedding anniversary",
Birthday,
FamilyEvent "Some other family celebration",
TimeWithFriends "To spend time with friends",
Convenience "Convenience / It's just something I/we do",
OtherReason "Some other reason" other
};
Notice the response name that the example uses for Other Specify: from this name it is
immediately obvious which question the other response belongs to. Although this is not a
requirement and it may be quicker and easier simply to call all such responses Other, it is good
practice to use unique names for responses that are different, even if their response texts are the
same. This is particularly the case with response lists that contain subheadings.
In the following example, there is one Other Specify response in each subsection of the
response list. The two responses are different because one refers to positive impressions and the
other refers to negative impressions, so it makes sense to give them different response names.
563
Base Professional
OrganicFood "There is an increasing interest in organically produced

food. What are your thoughts about this?" categorical [1..]
{
AgainstOrganicFood "Thoughts against"
{
Expensive "It's too expensive",
NotGoodLandUse "It doesn't make the best use of the land",
NotProven "There's no proof it's better than other food",
LaborIntensive "It's too labor intensive",
OtherNegative "Other thoughts against" other
},
ForOrganicFood "Thoughts for"
{
GoodForYou "It's good for you",
BuyItMyself "I buy organic food whenever I can",
GoodForLand "It's better for land",
GoodforWildlife "It's better for wildlife",
OtherPositive "Other thoughts for" other
},
NoThoughts "I have no opinions about organic food" exclusive
};
mrScriptMetadata accepts a dash or hyphen (–) as the response name for special responses, and
will generate a response whose name matches the special response keyword (“other” in this
Selecting the Other Radio Button or Check Box
The interviewing program requires respondents to select the Other radio button or check box if
they enter text in the text box. It does not matter which order the respondents do this in as long as
they do both things. Many respondents simply type into the text box and forget to select the Other
option. If you are happy for them to do this, you can make this the default for the interview by
placing the following statement in the routing section of the script:
IOM.AutoSelectOther = True
This makes the interviewing program select the Other option automatically whenever a respondent
types into an Other text box.
Allowing Respondents Not to Answer Questions
Respondents must generally answer all questions that are displayed during the interview. If
they click Next without selecting or entering an answer an error message is displayed and the
interviewing program waits for the question to be answered. There are a number of situations
where this behavior is undesirable, typically:
You want to allow respondents not to answer certain questions. In this situation you want to
display the question but allow the respondent to click Next without choosing an answer.
A question’s response list has been filtered so that it is empty. In this case the interviewing
program recognizes that the question is now irrelevant and skips it automatically.
A question’s response list has been filtered so that it contains just the special No answer, Don’t
know, and Refused responses. In this situation you will not want to display the question but
will want to code it as unanswered.
564
Chapter 1
To allow a question to be unanswered for any reason, place the following statement in the routing
section somewhere before the question is asked:
Qname.MustAnswer = "False"
where Qname is the question’s name.
To allow all questions to be unanswered, type:
IOM.MustAnswer = "False"
This is worth considering if the script contains only a few questions that must be answered, as you
can reverse the setting just for the questions that must be answered.
Setting MustAnswer to False is sufficient to deal with questions or compound items with
empty response lists, and with block, compound, loop, or page items that have no sub-questions
(see Repeated questions and More Than One Question on a Page for information about these
item types) but it is not sufficient for the other scenarios. In these cases you will need either to
include the special na response in the response list or to define a default answer for the question.
Questions that do not have either of these settings will still require respondents to answer them
regardless of their MustAnswer flag.
If a response list contains an na response and the question has MustAnswer set to False, the
interviewing program does not display the na response, but will use it whenever the respondent
clicks Next without choosing an answer. This is the same as having MustAnswer set to True and
displaying the na response for the respondent to select.
The following example illustrates these two options. The questions are defined in the metadata
section as follows:
Siblings1 "Do you have brothers and sisters?" categorical [1..1]

{
Yes, No,
NoAnswer "" NA
};
Siblings2 "How many brothers and sisters do you have?"
long [0..10];
The routing statements are:
Siblings1.MustAnswer = "False"
Siblings1.Ask()
Siblings2.MustAnswer = "False"
Siblings2.Response.Default = 0
Siblings2.Ask()
Both questions allow the respondent to click Next without giving an answer. Siblings1 has
an na response which the interviewing program will not display but which it will set as the
response if none is given. Siblings2 has a default response value defined in the routing section,
so any respondent who click Next without entering a number at this question will have his/her
answer set to 0.
Note: The two options apply equally to all response types and are not restricted to the response
types shown in the example. You can set a default response for any type of question, and you can
use na, whether or not it is hidden, with any type of question.
565
Base Professional
MustAnswer and Boolean Responses
MustAnswer should only be used with boolean response lists that have a default answer specified
or that contain a codes section defining categorical responses such as No Answer. If you use
MustAnswer with a simple boolean response list, the interviewing program will always select
False if the respondent does not answer the question.
Questions with No Columns in the Case Data File
You can define questions that have no columns allocated for saving responses in the case data
file. The questions can still be asked in the normal way, and any answers given will be available
for use during the interview. However, because there are no columns for the question in the case
data file, the responses will be lost at the end of the interview.
You might want to do this when you want to verify information given earlier in the interview
or read in from the respondent’s sample record. The interview script may contain questions that
display the information to be verified and ask whether or not it is correct. If the information
is correct, the respondent answers Yes and there is nothing more to do. If the information is
incorrect, the respondent is prompted to correct it. Either way, you are unlikely to want to keep the
responses to the verification questions themselves.
To define questions that do not require the case data to be saved, place the nocasedata keyword
at the end of the question as shown in the following example.
FullName "What is your full name?" text nocasedata;
Setting Default Answers
If you allow respondents not to answer certain questions, you must either include the special na
(No answer) response in the list or define a default response. The interviewing program can then
assign one of these responses as the answer when the respondent does not choose one. You can
set a default answer in the metadata or the routing section. In the metadata section, append the
following to the question definition:
defaultanswer(Answer)
where Answer is a valid answer to the question.

In the routing section, type:
Qname.Response.Default = Answer
where:
Qname is the name of the question.
Answer is a valid answer to the question.
Categorical values must be enclosed in curly braces. If the question allows more than one
response and you want to specify several default answers, separate those answers with commas
and enclose the whole list in curly braces.
Here are a couple of examples.
566
Chapter 1
Gender "Are you ..." categorical [1..1]

{
Male, Female,
GenderNA "No Answer" na
} defaultanswer({Female});
Pets "How many pets do you have?" long [0..9] defaultanswer(0);
If you would rather set the default answers in the routing section you could type:
Gender.Response.Default = "{Female}"
Pets.Response.Default = 0
If the metadata and routing sections define different default answers for the same question, the
definition in the routing section overrides the metadata setting. If the metadata defines an na
response and a default answer, the default answer overrides na.
Whether you specify a default answer or define an na response is up to you and depends
on what you want the respondent to see in the interview. When MustAnswer is False and the
response list contains na, the interview scripting program does not display this response. If the
respondent does not answer the question, na is set as the response, but if the respondent goes
back to this question or it is displayed with .Show(), it appears to be unanswered. In contrast,
in categorical response lists, the default answer is always displayed the same as all the other
responses and, if the respondent goes back to the question or it is displayed with .Show(), that
response will be marked as the chosen response.
Notes: MustAnswer should always be set to False. Default answers are not typically presented
to the user. Refer to Setting Initial Values for information on presenting default values to the user.
Setting Initial Values
Initial values are a way of speeding up the interview by displaying questions with a certain answer
or set of answers preselected. If the respondent is happy with those answers, he/she can just
click Next to continue. Initial values are particularly useful with large numeric grids, where the
respondent may only have answers to fill in for certain cells. If you define initial values for
each cell, the respondent only has to change the cells that apply to him/her. For example, in a
grid that asks how many times the respondent did particular activities on each day of the week,
if you define the initial value for each cell as zero, it may reduce the number of cells that the
respondent has to fill in. In large grids this may affect the likelihood that the respondent will
continue with the interview.
Once the respondent clicks Next, any initial values that have not been changed become true
responses to the question and will be saved in the data as such.
You can define initial values in the metadata and routing sections of the script. In the metadata
section, append:
initialanswer(Value)
to the question’s definition or, for categorical responses, to the response definition. In the routing
section, type:
Qname.Response.Initial = Value
In both cases, Value is the answer you want to preset. Categorical responses must be enclosed in
curly braces. To set more than one categorical response, separate the responses with commas and
enclose the whole list in curly braces.
567
Base Professional
For grids, you need to define an initial value for each repetition and for each question in the
grid. The general syntax to use is:
GridName[..].Qname.Response.Initial = Value
where:
GridName is the name of the grid. The [..] notation means “for each repetition”.
Qname is the name of a question in the grid.
You will need one of these statements for each question in the grid. For more information, see the
topic Initial and default cell values on p. 628.
For example:
Children "How many children do you have?" long [0..9]
initialanswer(0);
Initial Values with Default Answers
Do not confuse default answers and initial values. Initial values are answers that are to be
displayed preselected. Default answers are answers that will be written to the case data if no other
response is chosen and the script allows the respondent not to answer the question.
If a question has an initial value only and no na response, the respondent must either accept
the initial value as his/her answer or must replace it with a different answer. Deleting the initial
value and clicking Next issues the “Missing answer” error and redisplays the question with the
initial value preselected. Even if MustAnswer is set to False, the respondent is still required to
answer the question. (See Allowing Respondents Not to Answer Questions for information
about MustAnswer.)
If a question has an initial value and a default answer or an na response, the question is
displayed with the initial answer preselected. If the respondent deletes the initial value and then
clicks Next without choosing another answer, the interviewing program will use the default
answer or na, as appropriate, as long as the script indicates that the question may be unanswered.
Sorting Categorical Response Lists
You can control the order in which the responses in a categorical list are presented to respondents,
either to make it easier for respondents to find items in a long list, or to counteract the tendency
to select responses from the top of the list. This section introduces the following keywords for
performing these functions in the metadata section of the interview script:
asc Sort in ascending alphabetical order
desc Sort in descending alphabetical order
fix Keep response in its current position
ran Sort in a random order
rev Reverse the order for each alternate interview
rot Sort in rotated order
This section also describes how to

568
Chapter 1
Sort responses in lists that contain subheadings.

Control the order of responses using statements in the routing section. (You would normally
do this only for advanced requirements such as a different order for each iteration of a
repeated question.)
Displaying Responses in Alphabetical Order
Note: Alphabetic sorting does not apply to responses that have a fixed position in the response list.
For more information, see the topic Responses with Fixed Positions in the Response List on p. 573.
To sort responses in alphabetical order, type the following statement in the metadata section:
Qname "Text" categorical [NumResps]
{
Responses
} asc;
for sorting in ascending order from A to Z, or:

{
Responses
} desc;
for sorting in descending order from Z to A. (asc and desc can be specified in full as ascending
and descending if you wish).
In the following example, the responses will be sorted in ascending alphabetical order so
“Changed your browser’s startup or home page” will come first and “Taken a seminar or class
about the Web or Internet” will come last:
WhatDone "For which of the following have you used the Internet?"
categorical [1..]
{
PlaceOrder "Ordered goods/services",
DirectPurchase "Made a purchase online for more than $100",
WebPage "Created a web page",
CustomizedPage "Customized a web page for yourself",
BrowserChange "Changed your browser's startup or home page",
CookieChange "Changed your cookie preferences",
Chatrooms "Participated in an online chat or discussion",
Radio "Listened to a radio broadcast online",
Seminar "Taken a seminar or class about the Web or Internet"
} asc;

To sort responses in alphabetical order using a statement in the routing section, type either:
Qname.Categories.Order = OrderConstants.oAscending
or:
Qname.Categories.Order = OrderConstants.oDescending
If you specify ordering for a question in both the metadata and the routing section, the routing
specification overrides the metadata specification.
569
Base Professional
For further information about defining order in the routing section, see Controlling Response
Order from the Routing Section
Displaying Responses in Rotation
When you display responses in rotation, each response takes a turn at being the first response in
the list. Once a response has reached the top of the list, it moves to the end of the list the next time
the list is displayed. Apart from this, the relative order of responses in the list remains unchanged.
To present responses in rotation, type:

{
Responses
} rot;
rot is an abbreviation of rotation which you can use if you prefer.

For example, if the question is defined as:
MainIssue "In your opinion, what is the single most critical
issue facing the Internet?" categorical [1..1]
{
FindingThings "Finding things/navigating around",
Speed "Speed/bandwidth",
Regulation "Government regulation",
EqualAccess "Equal access for all",
Pornography,
InternetCrime "Internet crime (e.g. hate crimes, stalking)",
Paying "Paying for online services or information",
Censorship,
Privacy
} rot;
The first time the question is asked, the last response in the list may be displayed first, followed by
all other responses in the list in the order in which they appear in that list:
Privacy
Finding things/navigating around
Speed/bandwidth
Government regulation
Equal access for all
Pornograph
Internet crime (e.g. hate crimes, stalking)
Paying for online services or information
Censorship
The second time the question is asked, responses will be presented in the same order except
that the last two response in the original list will be displayed first, with the other responses in
their original order:
Privacy
Censorship
other Responses as shown above
The third time, the response list will look like this:
Censorship
Privacy
Finding things/navigating around
570
Chapter 1
Speed/bandwidth
Government regulation
Equal access for all
Pornograph
Internet crime (e.g. hate crimes, stalking)
Once a rotation pattern has been set for a question in a particular interview it does not change,
regardless of how many times the question is asked. If the respondent snaps back to the question,
the responses will appear in the same order as when the respondent first saw the question. A new
rotation pattern is set for that question only when the next interview starts.
The rotation pattern is based on the number of responses in a response list, so if there are
several questions with rotated response lists and they all have the same number of responses, the
rotation sequence for all of those lists will be the same. The interviewing program does not
recalculate the rotation pattern for each question. If your script contains two response lists of four
responses and two response lists of five responses, the two response lists with four responses will
both use one rotation pattern while the two response lists containing five responses will both
use another rotation pattern.
The interviewing program generates the rotation patterns for a script when the first interview
runs, and the rotation patterns for subsequent interviews run on from there. For example, if
the rotation pattern for a question in the first interview is 4, 1, 2, 3, the rotation pattern for that
question in the second interview will be 1, 2, 3, 4, and in the third interview it will be 2, 3, 4, 1.
This applies whether or not the interviews run concurrently. Rotation patterns are based on what
is known as a seed value which, for rotation, is calculated as:
Number of characters in project name + interview serial number + 7

To rotate responses using a statement in the routing section, type:
Qname.Categories.Order = OrderConstants.oRotate
Rotation does not apply to responses that have a fixed position in the response list. For more
information, see the topic Responses with Fixed Positions in the Response List on p. 573.
Displaying Responses in Random Order
Note: Randomization behaves differently depending on whether you specify it in the metadata or
the routing section.
To display responses in a different random order each time the question is asked, type:
{
Responses
} ran;
571
Base Professional
ran is an abbreviation for the randomize keyword which you can use if you prefer.
For example:
OtherIssues "And are there any other issues that are of concern
to you?" categorical [0..]
{
FindingThings "Finding things/navigating around",
Speed "Speed/bandwidth",
Regulation "Government regulation",
EqualAccess "Equal access for all",
Pornography,
InternetCrime "Internet crime (e.g. hate crimes, stalking)",
Paying "Paying for online services or information",
Censorship,
Privacy
} ran;
When you specify randomization in the metadata section, the randomization pattern is based on
the number of responses in the response list, so if there are several questions with randomized
response lists and they all have the same number of responses, the randomization sequence for all
of those lists will be the same. The interviewing program does not recalculate the randomization
pattern for each question. If your script contains two response lists of four responses and two
response lists of five responses, the two response lists with four responses will both use one
randomization pattern while the two response lists containing five responses will both use another
randomization pattern.

To randomize responses using a statement in the routing section, type:
Qname.Categories.Order = OrderConstants.oRandomize
When you specify randomization in this way, the randomization patterns are recalculated for each
question using what is known as a seed value which is based on the system’s GetTickCount
function. If your script contains two response lists of four responses and two response lists of five
responses, each list will use a different randomization pattern. The exception is for questions in a
loop, where the same seed value and randomization pattern is used for each iteration.
If you want to use the same seed value for all randomized questions in an interview and, thus,
have the same randomization pattern for all questions with the same size response lists, you must
save it and then set it before each question is asked. To save the randomization seed, place the
following statements in the routing section:
Dim variable
variable = GetRandomSeed()
Then, before the .Ask statement for each question that will use that seed, type:
SetRandomSeed(variable)
For example, if the ISPNames and ISPUsed questions both use the same shared list, the following
routing statements will display both response lists in the same random order:
Dim seed
seed = GetRandomSeed()
ISPNames.Categories.Order = OrderConstants.oRandomize
ISPNames.Ask()
SetRandomSeed(seed)
ISPUsed.Categories.Order = OrderConstants.oRandomize
ISPUsed.Ask()
572
Chapter 1
General Information
Randomization does not apply to responses that have a fixed position in the response list. For
more information, see the topic Responses with Fixed Positions in the Response List on p. 573.
If the respondent snaps back to a question with a randomized list, the interviewing program
presents the list in the order in which it was originally displayed, regardless of how many times
the respondent views the question.
specification overrides the metadata specification. For further information about defining order in
the routing section, see Controlling Response Order from the Routing Section
Displaying Responses in Reverse Order
The rev (or reverse) keyword reverses the order of responses for each interview. In the first
interview, responses are displayed in the order they are defined in the response list. In the second
interview, the responses are displayed in reverse order, with the last response in the list appearing
at the top and the first response in the list appearing last. In the third interview, the response order
is reversed so that responses again appear in the order they are defined. And so it continues.

To define a question with this kind of response list, type:
{
Responses
} rev;
For example:
Register "Some Web sites ask you to register with the site by
providing personal information. When asked for such information,
how frequently do you falsify the information?"
categorical [1.1]
{
Never, Rarely, Occasionally, Sometimes, Mostly,
NeverRegistered "Have never registered with a site"
} rev;
In the first interview the responses are presented in the order they appear here; in the second
interview they are presented from the bottom up.

To sort responses in reverse order using a statement in the routing section, type:
Qname.Categories.Order = OrderConstants.oReverse
Reverse sorting does not apply to responses that have a fixed position in the response list. For
more information, see the topic Responses with Fixed Positions in the Response List on p. 573.
573
Base Professional
Responses with Fixed Positions in the Response List
If a response list contains responses such as “None of these” or any of the special responses NA,
DK, REF, and Other Specify, they normally appear at the end of the list after the predefined
responses, and you will probably want them to remain there even if the order of the predefined
responses changes. To do this, append the fix keyword to the response’s definition in the metadata
section, as follows:

{
Sorted_responses,
Fixed_response fix
} Order_keyword;
In the following example, the list of tea types is displayed in a random order but with None of
these always at the end of the list:
Groups "Which of these groups have you become more connected to

through the Internet? (Please check all that apply)"
categorical [1..]
{
Polical "People who share my political interests",
Hobbies "People who share my hobbies/recreational activities",
Religion "People who share my religion",
Profession "People in my profession",
Family "People in my family",
LifeSituations "People in similar life situations",
OtherGroups "Other groups" fix,
NoGroups "None" exclusive fix
} ran;
A response list may contain any number of fixed responses at any positions in the list. This means
that you can, for example, always display a certain response at the top of the list if this is what
you want. If the list contains a fixed response in the middle of the list, the other responses are
reordered around the fixed response as appropriate. So, if the fixed response is the third in the
list, it will remain there and other responses will be sorted around it according to the ordering
keyword you have used.
Sorting Response Lists Containing Subheadings
If a response list contains subheadings it is important that you place the ordering keyword in the
right place to achieve the results you require. You may find it helpful to think of the response
list as having a hierarchical structure in which the ordering keyword applies only to the level at
which it appears in the interview script. If the keyword appears on a subsection, it applies only to
the contents of that subsection, whereas if the keyword appears at the main response-list level it
applies to the subsections themselves and not to their contents.
Sorting Responses in a Subsection
Place the appropriate ordering keyword immediately after the closing brace for the subsection.
The responses within that section will be sorted, but responses in other sections will not be sorted,
and the subsections themselves will appear in the order in which they are defined. If you want
574
Chapter 1
to sort the contents of more than one subsection, you must give each section its own ordering
keyword. For example, if the question is defined as:
Perception1 "What things would you mention about the Internet
if you were describing it to a friend?" categorical [1..]
{
Favorable "Good things"
{
EasytoUse "Easy to use",
LotsOfInfo "Access to a lot of information",
PeopleLikeMe "Can chat to people with same interests",
BuyOnline "Good way to buy goods/services"
} ran,
Unfavorable "Bad things"
{
NotReliable "Not a secure way to make purchases",
BadExperience "I had a bad experience in the past",
NotPrivate "Need to guard personal information",
Difficult "It's difficult to find appropriate web sites"
} ran
};
the interviewing program will always display favorable comments before unfavorable ones, but
the comments themselves will be shown in a random order in each subsection:
Figure 1-70
Interview page showing sorted responses within subsections but unsorted sections
Notice that the responses in the two subsections are presented in the same random order. This is
because there are the same number of responses in each subsection. If one subsection had more
responses than the other, then the randomization sequence for the responses would be different.
You can specify the same sorting in the routing section using:
Perception1.Categories["Favorable"].Order=OrderConstants.oRandomize
Perception1.Categories["Unfavorable"].Order=OrderConstants.oRandomize
575
Base Professional
Sorting Subsections but not Responses in the Subsections
Place the ordering keyword at the end of the response section of the question as a whole. The
interviewing program will then present the subsections in a different order for each interview, but
all respondents will always see the responses in the subsections in the order they are defined in the
interviewing script. For example, if the question is defined as:
{
{
},
{
}
} rot;
the interviewing program will display favorable comments before unfavorable ones for one
interview and then display unfavorable comments before favorable ones for the next interview.
The comments themselves will always be shown in the order in which they are defined in the
question:
Figure 1-71
Interview page showing sorted subsections with unsorted contents
576
Chapter 1
{
{
},
{
}
} rot;
Sorting Subsections and the Responses in the Subsections
Place the appropriate ordering keywords at the ends of the subsections and also at the end of the
response list as a whole. For example, if the question is defined as:
{
{
} ran,
{
} ran
} rot;
the interviewing program will display favorable comments before unfavorable ones for one
interview and then display unfavorable comments before favorable ones for the next interview. In
addition, the responses within each section will be sorted in an identical random order.
577
Base Professional
Figure 1-72
Interview page showing sorted responses within sorted subsections
Perception3.Categories["Favorable"].Order=OrderConstants.oRandomize
Perception3.Categories["Unfavorable"].Order=OrderConstants.oRandomize
Perception3.Categories.Order=OrderConstants.oRotate
Controlling Response Order from the Routing Section
Specifying response order using statements in the routing section can sometimes give you more
flexibility than specifying the response order as part of the question definition in the metadata
section. In particular, it allows you to change the order based on answers to previous questions or
you can ask respondents to choose an order (for example, most expensive first).
The general syntax for defining ordering in the routing section is:
Qname.Categories.Order = OrderConstants.order
where order is one of oAscending, oDescending, oRotate, oRandomize, oReverse, or

oCustom.
For example, if the metadata section contains the following questions:
CurrentISP "Who is your current Internet Service Provider (ISP)?"
categorical [1..1]
{
use ISPList
};
SortISP "Now some questions about your ISP. How would you like
to sort your choices?" categorical [1..1]
{
Ascen "Alphabetically A-Z",
Descen "Alphabetically Z to A"
};
578
Chapter 1
you would place the following statements in the routing section to present the response list in the
order that the respondent requests:
SortISP.Ask()
If SortISP= {Ascen} Then
CurrentISP.Categories.Order = OrderConstants.oAscending
CurrentISP.Ask()
ElseIf SortISP = {Descen} Then
CurrentISP.Categories.Order = OrderConstants.oDescending
CurrentISP.Ask()
End If
Custom Ordering
Use oCustom order when you want to use a customized order that cannot be achieved using the
standard ordering keywords. A typical example might be ordering by size or price. In cases such
as these you need to list the responses in the routing section in the order they are to be displayed
and then use the oCustom setting to make the interviewing program pick up this order. Here’s an
example. In the metadata section you have:
CompareISP "The following list shows other ISPs in {Order} price
order." categorical [1..]
{
use ISPList
};
Ordering "Why not compare the cost of your ISP with others?
How would you like to sort the list?" categorical [1..1]
{
PriceAscen "By price, ascending",
PriceDescen "By price, descending"
};
In the routing section you have:

Ordering.Ask()
If Ordering = {PriceAscen} Then
CompareISP.Categories.Filter = _
{OnTheWeb,GetOnline,InternetAtHome,YourISP,OneStop,ThePhoneCompany}
CompareISP.Categories.Order = OrderConstants.oCustom
CompareISP.Label.Inserts["Order"].Text = "ascending"
CompareISP.Show()
ElseIf Ordering = {PriceDescen} Then
CompareISP.Categories.Filter = _
{ThePhoneCompany,OneStop,YourISP,InternetAtHome,GetOnline,OnTheWeb}
CompareISP.Categories.Order = OrderConstants.oCustom
CompareISP.Label.Inserts["Order"].Text = "descending"
CompareISP.Ask()
Note: When repeated questions are displayed as a grid, you must use the same order for the items
in the loop control list for all repetitions. If the questions are asked separately you may use a
different order for some repetitions if you wish.
Rotation and randomization with grids
If the order of responses in a row or column of a grid differs from the order of those responses in
the header row or column, the interviewing program does not display the grid. Instead, it displays
an error message and writes that message to the IVW* log file. This prevents data corruption that
would happen if the script was allowed to run as written.
A simple way to avoid this error is always to specify rotation or randomization for loops in
the metadata section of the script, as this ensures that all iterations of the loop will use the same
rotation or randomization pattern. If you have to specify rotation or randomization in the routing
579
Base Professional
section, you should always set the program’s state before requesting the reordering. For example,
always set the randomization seed before requesting randomization, as shown here:
For Each Question In MyLoop
SetRandomSeed(IOM.Info.RandomSeed)
Question.Order = OrderConstants.oRandomize
Next
Shared Lists
In many questionnaires you’ll have a set of questions that have identical or very similar response
lists. A typical example is a brand awareness study, where you have a list of key brands that you
want to ask about. You may have a question that asks respondents which brands they can name,
then another one that asks which brands they use, and one that asks which brands they’ve seen or
heard advertised in recent weeks. An even more general example is a ratings list that you want to
apply to a number of questions. In an employee satisfaction survey, you might present employees
with various statements about different aspects of their work and ask them to say how much they
agree or disagree with the statement using a five point scale.
When a response list is common to a number of questions, the most efficient way of setting
it up is to make it a shared list. Not only does it mean that you only have to type the full set of
responses once, it also makes it easier to manipulate the responses in the list at various points
in the questionnaire. For example, in the brand awareness study, you might want to remind
respondents of any brands that they did not mention spontaneously and ask whether they recognize
the names. Since each respondent will mention different brands spontaneously, you’ll want to
specifically mention different brands for each person.
Unlike other scripting languages, shared lists in interview scripts are not concerned with setting
up a coding frame for responses that are common to a number of lists. IBM® SPSS® Data
Collection data analysis is based more on response names and native values rather than response
codes, and as long as a response has the same name wherever it is defined, you will be able
to treat all occurrences of that response as if they were a single response. For example, if the
respondent chooses strawberry yogurt from the list of Alpine flavors and from the list of Dairy
Fresh flavors, you will usually be able to treat these choices as a simple reference to strawberry
yogurt for analysis purposes.
This section describes the following keywords for the metadata section of the interview script:
define Create a shared list
namespace Make ‘duplicate’ responses unique when using two
lists with some responses in common
use Include one list in another list, or use a shared list as
a question’s response list

Create a simple shared list
Combine two or more shared lists to form a larger list
Include subheadings in a list
Write a question whose responses come from one or more shared lists
Deal with identical response texts in two or more lists
580
Chapter 1
Change the order of responses in shared lists

Use special responses with shared lists
Create a question whose response list is based on answers chosen/not chosen from a shared list
Note: Try to avoid using the same name between shared lists and their contained responses.
For example, when a shared list contains a response named Drink, use a shared list name like
DrinkList to avoid any potential conflicts.
Creating Shared Lists
To create a shared list, place the following statement in the metadata section of the questionnaire:
Name define
{
ResponseName1 [ResponseText1],
...
ResponseNamen [ResponseTextn]
};
where:
Name is the name of the list. Try to make the list name reflect its contents as this will make the
rest of the questionnaire script easier to understand.
ResponseName1 to ResponseNamen are the response names. These must consist of a letter
followed by letters and numbers only. It is a good idea to make the response name the same as
the response text if you can so that you can omit the response text.
ResponseText1 to ResponseTextn are the response texts. If a response text does not contain
spaces, punctuation, or other non-alphanumeric characters you may omit it and the
interviewing program will use the response name as the response text.
Here is a shared list naming different brands of a product:
BrandList define
{
Alpine,
Finborough,
Alsace,
DairyFresh "Dairy Fresh"
};
The Dairy Fresh response has a name and a text because the response text contains spaces.
This example lists each response on a separate line and indented, but you may place several
responses on the same line if you prefer. Note, however, that when you close and reopen the file,
IBM® SPSS® Data Collection Base Professional will reapply its default layout which is to
place each response on a separate line.
You can define lists at any point in the questionnaire, but if you are using Base Professional
the lists will always be moved to the top of the metadata section when you close and reopen the
questionnaire. In the Metadata Explorer pane of Base Professional, response lists are shown
under Types.
If you define a shared list inside a block or a loop it will be visible within that block or loop
only. If a question outside the block of loop uses the shared list, the question will be displayed
without a response list. If you create a shared list inside a block or loop and give it the same name
581
Base Professional
as a shared list that already exists in the parent script, the shared list within the block or loop will
take precedence over the one in the parent script.
Using a Shared List as a Response List for a Question
To use a shared list as the response list for a question, place the following statement in the
metadata section of the questionnaire:
Name "Question text" categorical [NumResps]
{
use ListName
};
where:
NumResps defines the number of responses that may be chosen, as for a standard categorical
question.
ListName is the name of the list you want to use as the response list for the question.
For example:
BrandList define
{
Alpine,
Finborough,
Alsace,
};
IceCreamKnow "Which brands of ice cream can you name?"
categorical [1..]
{
use BrandList
};
IceCreamBuy "Which brand of ice cream do you usually buy?"
categorical [1..1]
{
use BrandList
};
Both questions use the same response list but the first one allows a multiple choice answer,
whereas the second one allows only one answer to be chosen.
You can build a question’s response list using more than one shared list, or by combining a
shared list with other categorical responses. To do this, enter one use statement for each shared
list and separate these statements with commas. The following example defines separate lists for
organic and nonorganic brands, but uses the two lists to generate the brand list for the unaided
awareness question.
582
Chapter 1
BrandList define
{
Alpine,
Finborough,
Alsace,
};
OrganicBrands define
{
HelenBradley "Helen Bradley's",
KentishFarm "Kentish Farm",
NaturesWay "Nature's Way Organic"
};
DessertKnow "Which brands of frozen desserts can you name?"
categorical [1..]
{
use BrandList,
use OrganicBrands
};
The page that the interviewing program displays is as follows:

Figure 1-73
Example output for a response list that uses two shared lists
This example works because the two lists contain responses with different names. If you try
to use two lists that contain one or more responses with identical names, you will need to use
namespacing to ensure that each of those responses is saved with its full name in the questionnaire
definition (.mdd) file. For more information, see the topic When the Same Response Appears
in More Than One List on p. 585.
The next example shows how to create a response list by combining a shared list with other
categorical responses.
DessertBuy "Which of the following brands do you usually buy?"
categorical [1..]
{
use BrandList,
use OrganicBrands,
None "None of these" exclusive fix
};
583
Base Professional
The interview page is as follows:

Figure 1-74
Example output for a shared list with a separate categorical response
Using One List in Another List
You can create a shared list by using the contents of other shared lists, in much the same way
that you use two or more shared lists to generate the complete response list for a question. In
the metadata section, type:
Name define
{
use ListName1,
...
use ListNamen
};
where:
Name is the name of the main list.
ListName1 to ListNamen are the names of the shared lists you want to include in the main list.
584
Chapter 1
For example:
AllBrands define
{
use BrandList,
use OrganicBrands
};
BrandList define
{
Alpine,
Finborough,
Alsace,
};
{
};
Unaided "When I mention the word yogurt, which brand names do
you think of?" categorical [1..]
{
use AllBrands
};
This produces the following interview page:

Figure 1-75
Example output for a shared list built from two lists
This example is a variation of the one that shows how to use two or more shared lists with a
question. Click here to see that example.
Another thing you might want to do in this example is display subheadings to make it clear
which are the organic brands and which are not. See Subheadings in Shared Lists for information
on how to set this up.
If you combine lists that have responses in common you must namespace the lists when you name
them in the main list to ensure that each response is given a unique name. For more information,
see the topic When the Same Response Appears in More Than One List on p. 585.
585
Base Professional
When the Same Response Appears in More Than One List
Sometimes the same response will appear in more than one list. For example, all brands of
yogurt may have raspberry and strawberry flavors. Depending on how you set up and use the
lists, you may need to use namespacing to ensure that these ‘duplicate’ responses are treated as
separate responses. This topic provides sufficient information about namespacing such that you
can understand when you must use it with shared lists. For more detailed information about
namespacing in general see Questions with Duplicate Response Names.
Let’s start by assuming that you have the following lists:
AlpineList define
{
Raspberry, Strawberry, BlackCherry "Black cherry"
};
DairyFreshList define
{
Strawberry, Apricot, Peach
};
Both lists contain a strawberry response. As long as you do not use the two lists with the same
question, there is no need to use namespacing because these responses will always be unique
within the response list for a single question. For example:
AlpLike "Which flavors of Alpine yogurt do you like?"

categorical [1..]
{
use AlpineList
};
DFLike "Which flavors of Dairy Fresh yogurt do you like?"
categorical [1..]
{
use DairyFreshList
};
Here you have one question for Alpine brand and another for Dairy Fresh brand so there is no
overlap between the responses within each question.
If you rewrite this example so that there is one question for all brands, the response list for that
question will contain two occurrences of strawberry. In order for this to be accepted you must
follow each list name in the question definition with the namespace keyword as shown below.
Like "Which flavors of yogurt do you like?" categorical [1..]

{
Alpine
{
use AlpineList namespace
},
{
use DairyFreshList namespace
}
};
This forces each response name to include the name of its parent list, so the names of the responses
become AlpineList.Raspberry, AlpineList.Strawberry, DairyFreshList.Strawberry, and so on.
586
Chapter 1
The interview page for this example is as follows:

Figure 1-76
Example output for using namespacing to combine shared lists with common responses
The same rule applies if you create a shared list that uses lists that have common responses. In this
case you place the namespace keyword inside the main list as follows:
OrganicFlavors define
{
use HelenBradleyList namespace,
use KentishList namespace
};
HelenBradleyList define
{
Raspberry, Pineapple, Apricot, Blackcurrant
};
KentishList define
{
Blackcurrant, Mango, Peach, Apricot
};
Prefer "Which of the following ice cream flavors do you
like best?" categorical [1..1]
{
use OrganicFlavors
};
Note: The interview page for this example is similar to the one shown earlier except that there are
no subheadings to show the respondent why there are two identical responses in the list.
Changing the Order of Responses in a Shared List
You can change the order in which the responses in a shared list are displayed by using one
of the ordering keywords:
rot. Rotate responses so that each interview starts at a different position in the response list
while keeping the responses in the same order overall.
ran. Display responses in a random order every time it is used, even if within the same
interview.
rev. Reverse the order of the responses in the list for alternate interviews. Responses in the
list are presented in reverse order for the first, third, fifth, and so on, interviews and in the
defined order for other interviews.
587
Base Professional
asc. Present responses in alphabetical order, A to Z.

desc. Present responses in reverse alphabetical order, Z to A.
If you want to use the same ordering method every time the list is used by a question, include the
ordering keyword as part of the list specification. If you want to apply different ordering methods
to the list at different questions, then place the ordering keyword in the question specification.
Here are two examples that illustrate the different approaches. In the first example the
YogurtBrand shared list is used twice, once with its responses presented in rotation and once with
the responses presented in the order they are defined. Because of this, the rot keyword is placed
on the question that requires the rotated list.
BrandList define
{
Alpine,
Finborough,
Alsace,
};
ChocBarKnow "Which of the following brands of frozen
chocolate bars have you heard of?" categorical [1..]
{
use BrandList
} rot;
ChocBarBuy "And which brands of frozen chocolate bars
do you usually buy?" categorical [1..]
{
use BrandList
};
In the next example, the responses in the Flavors list are always to be presented in a random order,
so ran is included as part of the list definition.
Flavors define
{
Strawberry, Raspberry, Mango, Apricot, Pineapple
} ran;
Likes "Which of the following flavors do you like for
frozen desserts?" categorical [1..]
{
use Flavors sublist
};
Dislikes "And are there any flavors that you do not like?"
categorical [1..]
{
use Flavors sublist
};
Note: The sublist keyword is currently required in order for randomization to work. If you
forget it, responses are always displayed in the order they appear in the list.
Subheadings with Shared Lists
Very long lists can be made more readable and easy to use if you break them up using subheadings.
The subheadings provide an overall structure to the list by grouping similar or related responses
together and, because the responses in a group are indented below their subheading, make it easier
to scan the list in search of particular responses.
588
Chapter 1
Figure 1-77
Example output for a shared list with subheadings
There are two ways of defining subheadings, depending on the way the lists are defined and
used in the script.
If you want to place subheadings inside a shared list, split the list into subsections using
curly braces and give each subsection a subheading. For more information, see the topic
Subheadings in a Shared List on p. 588.
If you are loading shared lists into a question and want to precede each list with a subheading,
place the sublist keyword on the use statement that loads the shared list. Then define
the subheading after the sublist keyword or as part of the list definition itself. For more
information, see the topic Subheadings using “sublist” on p. 590.
Subheadings in a Shared List
The rules for defining subheadings inside a shared list are similar to those for placing subheadings
in response lists. To add subheadings to a shared list, place the following statement in the metadata
section of the questionnaire:
name define
{
SubheadName1 ["Text1"]
{
response definitions
},
SubheadName2 ["Text2"]
{
response definitions
}
...
}
where:
SubheadName1 and SubheadName2 are the names of the subheadings.
Text1 and Text2 are the texts for the subheadings. If the texts are the same as the names and
do not contain spaces or other non-alphanumeric characters you may omit them and the
interviewing program will display the subheading names instead.
response definitions are either a list of response names and texts, or one or more use statements
naming shared lists to be included in this list.
589
Base Professional
For example:
Like "Which flavors of yogurt do you like?" categorical [1..]
{
Alpine
{
use AlpineList namespace
},
{
use DairyFreshList namespace
}
};
might produce the following list:

Figure 1-78
Example output for a shared list with subheadings
When you use subheadings in this way, the subheadings divide the list into separate functional
sections, so that the responses in each section can be referenced as a group using the subheading
name. For example, in the routing section, you can filter on one sublist by typing, say,
Responses.Alpine.Filter = {mango} to select mango flavored Alpine yogurt. However, subheadings
do not make the response names unique so you cannot have two responses with identical names in
the list. In the example shown here, Alpine and Dairy Fresh each produce different flavors of
yogurt. If you want to generate this sort of display and have the same responses appearing under
each subheading you must use namespacing as shown in When the Same Response Appears in
More Than One List
If you sort a shared list that contains subheadings, the subsections (Alpine and Dairy Fresh
in this example) are reordered but the responses inside each subsection remain in their original
places relative to the subheadings.
590
Chapter 1
Subheadings using “sublist”
If you have shared lists that you load into questions with use, you can use the sublist keyword
to mark lists whose responses are to be treated as a single group or sublist within the response
list as a whole:
Name "Question text" categorical [NumResps]
{
use ListName1 sublist ["Subheading1"],
...
use ListNamen sublist ["Subheadingn"]
};
where:
Name is the question name.
ListName1 to ListNamen are the names of the shared lists you want to include in the question’s
response list.
Subheading1 to Subheadingn are optional subheadings to be displayed above the shared lists.
For example:
BrandList define
{
Alpine,
Finborough,
Alsace,
};
{
};
TVAds "Which brands of yogurt have you see advertised
on TV?" categorical [1..]
{
use BrandList sublist "Non-organic brands",
use OrganicBrands sublist "Organic brands"
};
Figure 1-79
Sublist with subheading defined on the “use” statement
If you use a shared list as a sublist for a number of questions and you always want to use the
same subheading text, you can include the subheading text as part of the list’s definition and omit
it from the individual uses. The list’s definition becomes:
Name "SubheadingText" define
{
...
ResponseNamen [ResponseTextn]
};
591
Base Professional
You can rewrite the previous example as follows and still achieve the same page layout as in
the illustration.
NonOrgYogs "Non-organic brands" define
{
Alpine,
Finborough,
Alsace,
};
OrgYogs "Organic brands" define
{
};
PrintedAds "Which brands of yogurt have you seen
advertised in magazines or newspapers?" categorical [1..]
{
use NonOrgYogs sublist,
use OrgYogs sublist
};
If a shared list is defined with one subheading text and is then used as a sublist with a different
subheading, the subheading defined with sublist overrides the subheading defined in the
define statement. If a shared list is defined with an integral subheading and you want to use the
list without a subheading, just enter a null text (two consecutive double quotation marks) after the
sublist keyword for that list. For example:
RadioAds "Which brands of yogurt have you heard
advertised on the radio?" categorical [1..]
{
use NonOrgYogs sublist "",
use OrgYogs sublist ""
};
to display the lists of yogurt brands without their subheadings.
Response Indentation with Subheadings
When a shared list has subheadings, the interviewing program indents the responses below their
respective subheadings, making it clear that the subheadings are texts rather than selectable
responses. The interviewing program applies this indentation automatically until either it reaches
the end of the subsection (a closing curly brace or another sublist keyword) or it reads a response
that has a different indent specified. Indentation is one of a response’s many style properties, along
with size, color, and font effect. To reset a response back to the default indentation, type:
style(indent=0)
in the response line after the response text. You may want to do this with response lists that use a
combination of shared lists and special responses such as No answer or Don’t know. Here’s an
example:
FruitKnow "Which brands of fruit yogurt can you name?"
categorical [1..]
{
use OrganicBrands sublist "Organic brands",
OtherBrands "Other (specify)" style(indent=0) other,
NoBrands "None" style(indent=0) na
};
592
Chapter 1
Figure 1-80
Resetting the indent for responses not in a sublist
Sorting Responses with Subheadings
Subheadings affect the way that responses in a list are sorted or reordered. If you place an
ordering keyword at the end of the question definition, the interviewing program applies it to the
subsections only. The responses within a subsection (that is, under a subheading) remain in their
subsections in the order they were defined. For example, if the question is defined as:
PlainKnow "Which brands of natural yogurt can you name?"
categorical [1..]
{
use OrganicBrands sublist "Organic brands"
} rot;
the interviewing program will display nonorganic brands followed by organic brands for one
interview, and then organic followed by nonorganic for the next. The individual brand names will
simply move with their subheadings.
If you want to reorder the responses under a subheading, do one of the following:
Place the ordering keyword at the end of the use statement, after the sublist clause.
Place the ordering keyword after the curly brace that terminates the subsection in the define
statement.
593
Base Professional
Using Shared Lists with Special Responses
Although you will often want to use the special No Answer, Don’t Know, Refused, and Other
Specify responses with shared lists, it is not usual to include them in a shared list unless you want
those responses to be available to all questions that use that list. Instead, you will normally define
these responses separately within the questions that require them:
FlavorList define
{
Strawberry, Raspberry, Peach, Pineapple, Mango,
BlackCherry "Black cherry", Apricot
};
FlavorLike "Which flavors of yogurt do you like?" categorical [1..]
{
use FlavorList,
LikeOtherFlavor "Other (specify)" other fix,
LikeNoAnswer "No answer" na
} asc;
This example sorts the yogurt flavors alphabetically from A to Z and appends Other Specify and
No answer in that order to the end of the list. Because the question allows multiple choice, No
answer is flagged as a single choice answer.
Figure 1-81
Example output showing an alphabetically sorted list
Responses Based on Answers to Previous Questions
Shared lists are commonly used to simplify the manipulation of responses, for example, when you
want to base the response list for one question on the answers given or not given at a previous
question. A typical example is aided/unaided awareness questions where you start by asking
respondents to name items spontaneously, and then ask them specifically about any other items
that they did not mention.
Setting up this type of script means placing statements in both the metadata and the routing
sections of the questionnaire. You specify the shared lists and the questions in the metadata
section, but specify which responses are to be presented for each question in the routing section.
594
Chapter 1
The following example illustrates how to set up an aided and unaided awareness script, and also
how to merge the two sets of answers into a single variable for use later on in the questionnaire.
The metadata section contains the following text:

Spont "Which brands of fresh cream puddings do you know?"
categorical [1..]
{
use BrandList
};
BrandsUsed "And of those brands, which ones do you buy?"
categorical [1..]
{
use BrandList
};
AidedQ "Do you recognize any of the following brand names?"
categorical [1..]
{
use BrandList,
AidedNA "Do not recognize any of these names" na
} ran;
KnownQ "The brands that you named are as follows." categorical [1..]
{
use BrandList
};
The Known question is a dummy question that is used for display purposes only. Its purpose
is to define a variable that can be used for storing categorical information for use later in the
questionnaire. Data is placed in the variable by statements in the routing section, and the variable
will be available for analysis in IBM® SPSS® Data Collection Survey Tabulation in the same
way as ordinary question variables. You will see dummy questions of this type referred to as
derived variables in some documentation because the question generates a variable whose value
is derived from the values of other questions or variables.
The routing section contains the following statements:

Spont.Ask()
' Set response list for BrandsUsed to be those brands mentioned
' at Spont.
BrandsUsed.Categories.Filter = Spont
BrandsUsed.Ask()
' Set response list for AidedQ to be all brands not mentioned
' at Spont.
AidedQ.Categories.Filter = AidedQ.Categories - Spont
AidedQ.Ask()
' Merge unaided and aided mentions into a single variable
KnownQ = Spont + AidedQ
KnownQ.Show()
The key statements to notice in this example are the ones that create the aided awareness response
list and merge the answers to the unaided and aided awareness questions. The response list for the
Aided question is created by taking the full list of brands defined for the question in the metadata
section (Aided.Categories) and removing any that were mentioned at the Unaided question.
The brands that the respondent recognizes are added into the Known variable. Because the
metadata section specifies that the response list for this question comes from the Brands shared
list, a response of “Do not recognize any of these brands” at the aided awareness question is
ignored because it is not part of the shared list.
The last statement in the script snippet displays the KnownQ question and response list, but
with the responses that have been set into it marked. The respondent cannot make any changes on
this page. If he/she wishes to make changes, he/she must go back to the original question from
595
Base Professional
which that part of the answer came. For example, if the respondent forgot to say that he/she
recognizes the Alpine brand name, he/she must go back to AidedQ and change it there.
Displaying Information on a Page
Most questionnaires need to display text that is not part of a question or response list, such as
page headings or titles, and instructions to interviewers or respondents. The best way to do this
is to define the text in the metadata section of the questionnaire in the same way that you define
questions and responses, and then to use statements in the routing section to display the text.
This has two advantages:
The text can be translated using SPSS translation utilities, in the same way as question and
response texts.
You have complete control over how and when individual texts are displayed, so texts can be
reused if necessary.
Note: Non-question text is not available at the analysis stage of a project.
Another feature to do with displaying information is text substitution. This allows you to display
the answer to a previous question or, indeed, any variable text of your choice as part of a question
or response text. You’ll often use it for displaying a respondent’s Other specify answer as a
valid response in another response list.
This section introduces the following keywords for use in the metadata section:
info Define non-question text
{#variable} Display answers to previous questions in question
texts and banners.
{@variable} Display the current value of a loop in the texts of
questions inside the loop.
This section also introduces the following properties that you can set in the routing section to
help with displaying text on the page:
Banners for adding information texts to questions and pages during the interview.
Inserts for inserting text in substitution markers in question and response texts.
This section also explains how to change or translate the labels displayed on navigation buttons
and choose between question names and question texts in the Goto navigation box..
Defining Information Texts
To define any type of non-question text, type the following statement in the metadata section of
the interview script:
Name "Text" info;
where:
Name is the name of the information item.
Text is the text to be displayed.
596
Chapter 1
For example, you might define the interview page title as:
SurveyTitle "<b>Training Course Review Survey</b>" info;
or provide the following respondent information on the first page of the questionnaire:
RespInfo "Thank you for agreeing to take part in our survey.
When navigating through the questionnaire, please do not use
your Browser's Back and Forward buttons. Always use the Next
and Previous buttons displayed at the bottom of the
questionnaire page." info;
The info keyword is optional because any statement in the metadata section that does not contain a
scripting keyword is assumed to be an information item. Nevertheless, it is a good idea to include
the info keyword because it makes your intentions obvious to other users.
If you have a simple information text that you want to display by itself on a single page, place
the following statement in the routing section at the point you want the text displayed:
Name.Show()
where:
Name is the name of the info item.
This is ideal when you want to be sure that the respondent or interviewer reads the text before
continuing. For example, typing:
RespInfo.Show()
displays the text on a page with navigation buttons, in the same way as a question is displayed.
For anything other than this, such as displaying a page title at the top of each page, or displaying
explanatory text above a question, define the text using an info item and then use the Banner
property in the routing section to display the text.
Only text that is part of an information or question item can be translated. If the interview script
contains any other text that you want to be able to translate, define it in information items but do
not add .Show or .Banner statements to the routing section for the ones you do not want to display.
Banners
Banners are the usual way to display non-question text on the interview screen. The text is defined
in the metadata section of the interview script using an info item, and can consist of plain text
and variables whose current values are to be substituted in the text when it is displayed. In the
routing section, you add the banner text to the question or page to which it relates so that it can be
displayed by the Ask statement that presents the page or question.
You can add banners at two levels:
Question. At the lower level, question banners are added to a specific question. You can add the
same banner to more than one question if you wish.
Page. At the higher level, page banners are added to a specific page. You can add the same
banner to more than one page.
You can display more than one banner at each level.
597
Base Professional
Each banner belonging to a question or page has a name and a text, rather like a question in
the metadata section. When you add a banner, you define its name and specify the name of the
info item that contains the banner text. You can give every banner a unique name in the routing
section if you wish, but if you use templates and want to refer to banners in some more general
way, it is more likely that you will create one or maybe two banners per level, and simply update
their contents from different info items as and when required.
For example, if the interview script has three sections, you may want to display the section
name at the top of each page. Instead of defining three different banners and only displaying one
at a time, it is better to define a single banner and change its text as the respondent reaches the start
of each new section in the interview. This allows you to use the same template for all sections
rather than needing three templates with different banner names in them.
In the default template, all page banners are displayed at the top of the page before all of the
questions, and the question banners are displayed above the question they are associated with.
You can change where and how banners are displayed by defining your own template. For more
information, see the topic Templates on p. 825.
Adding Banners to Questions and Pages
To add a banner to a question, type the following statement in the routing section of the interview
script. (As you type each dot separator, IBM® SPSS® Data Collection Base Professional’s
ScriptAssist feature will display a pop-up list of valid options from which you can choose the next
keyword to use, so don’t worry if you find you can’t remember the syntax).
Qname.Banners.Add("BannerName", InfoName.Label)
where:
Qname is the name of the question to which the banner should be added.
BannerName is the banner’s name.
InfoName is the name of the information item containing the banner text.
To add a banner to a page, type the following statements in the routing section of the interview
script.
IOM.Banners.Add("BannerName", InfoName.Label)
where:
BannerName is the banner’s name.
InfoName is the name of the information item containing the banner text.
These statements do not display the banner text. This happens when you display the question or
page. Here is an example interview page with two page banners shown in red. (This is simply to
highlight the banners in the illustration. The page was generated using the default template which
displays the text in a different font face and size but not in a different color.
598
Chapter 1
Figure 1-82
Interview page with two page banners
The metadata section for this page is as follows:

Disclosure "We do not disclose your personal details to anyone
outside our company." info;
HowUseAnswers "The answers you give to the following questions
will be used for analysis purposes only." info;
FirstName "What is your first name?" text [1..20];
Job "What is your position in your company?" categorical [1..1]
{
IntScriptwriter" Interview scriptwriter",
SMScriptwriter "Sample management scriptwriter",
SysAdmin "System administrator",
PhoneSupervisor "Phone room supervisor",
ProjMan "Project manager",
Interviewer, Coder
};
Demographics page(FirstName, Job);
The routing statements that add the banner text to the demographics page and then display the
page are:
IOM.Banners.Add("DisclosureBanner",Disclosure.Label)
IOM.Banners.Add("HowUseAnswersBanner",HowUseAnswers.Label)
Demographics.Ask()
Because they have been added as page banners, DisclosureBanner and HowUseAnswersBanner
will be displayed at the top of every page until the end of the interview or until they are manually
removed (see Removing Banners from Questions and Pages for details).
Here is another example that shows a question banner, again highlighted in red. The first
banner is the page banner retained from the previous example.
599
Base Professional
Figure 1-83
Interview page with question banner
The metadata for this question and banner are:

EmailInfo "If you have more than one e-mail address, please enter
the one that you want us to use when contacting you." info;
Email "And what is your e-mail address?" text [5..99];
and the routing statements are:

Email.Banners.Add("EmailBanner",EmailInfo.Label)
Email.Ask()
If the metadata section uses a page statement to group several questions on the same page, and
you want to add a banner to just one of the questions on the page, the Add statement must name
the page and the question as shown below. For example, if the metadata section defines the
following questions:
Name "What is your full name?" text [5..50];
UserDetails page (Name, Email);
and the routing section contains the following statements:

UserDetails.Banners.AddNew("EmailBanner",EmailInfo.Label)
UserDetails.Ask()
600
Chapter 1
the respondent will see the following page:

Figure 1-84
Interview page with multiple questions but with only the second question having a question banner
Removing Banners from Questions and Pages
To remove a banner from a page, type:

IOM.Banners.Remove("Banner_name")
in the routing section, where:

Banner_name is the banner’s name.
To remove a banner from a question, type:
Qname.Banners.Remove("Banner_name")
where:
Qname is the question’s name. If the question is part of a page group, the name must be
consist of the page name and the question name.
Banner_name is the banner’s name.
601
Base Professional
For example, suppose the metadata section is defined as follows:

Disclosure "We do not disclose your personal details to anyone
outside our company." info;
HowUseAnswers "The answers you give to the following questions
will be used for analysis purposes only." info;
FirstName "What is your first name?" text [1..20];
{
Interviewer, Coder
};
Demographics page(FirstName, Job);
ContactAgain "Click the check box if you would be willing to take
part in a follow-up survey" boolean;
If the routing section contains the following statements:

IOM.Banners.Add("HowUseAnswersBanner",HowUseAnswers.Label)
Demographics.Ask()
IOM.Banners.Remove("DisclosureBanner")
IOM.Banners.Remove("HowUseAnswersBanner")
IOM.Navigations[NavigationTypes.nvStop].Label.Style.Hidden = True
ContactAgain.Ask()
If ContactAgain.Response.Value = True Then
Name.Ask()
Email.Banners.AddNew("EmailBanner",EmailInfo.Label)
Email.Ask()
IOM.Banners.Remove("DisclosureBanner")
Email.Banners.Remove("EmailBanner")
End If
the page for the ContactAgain question will contain no banners at all:
Figure 1-85
Interview page showing effect of removing banners
To see this page in the context of the full interview script, refer to the illustrations in Adding
Banners to Questions and Pages.
Text Substitution
Text Substitution is the insertion of variable text into a fixed text. For practical purposes, it
covers such things as displaying respondent-specific information in a question text or banner,
displaying answers to Other responses as part of a second response list, and inserting texts from a
categorical loop control list into the texts of the questions inside the loop. A very simple example
602
Chapter 1
of text substitution is asking for the person’s name and then displaying it as part of the text that
thanks respondents for taking part in the survey.
The topics that follow describe how to:
display answers in question and banner texts
display loop control values in repeated questions
display Other response texts as responses in other lists
programmatically insert text into a label so that it can be displayed during the interview
apply formatting to text substitutions
Displaying Answers in Question and Banner Texts
To display the answer to a question in the text of another question or in a banner, type:
{#QuestionName}
in the question or banner text at the point at which you want the substituted text to appear.
QuestionName is the name of the question whose answer you want to display. For example:
Thanks "Thank you, {#Name:u}, for taking part in our survey."
info;
The :u in the Thanks example is a formatting specification that forces the name to be displayed
with the first letter in upper case, regardless of how the respondent typed his or her name. For
more information, see the topic Formatting Substituted Values on p. 609.
Note: If the substitution does not work and you see the marker rather than the text it represents,
check that you typed # in front of the marker name and that the marker name is spelled correctly.
Most of the time you’ll be making substitutions using questions that are all at the same level in
the script, but if you have a script that has nested loops you may find that you need to substitute
a response to a question that is at a different level. For example, you may want to substitute a
response from a question at the top level of the script in a question that is at the lowest level of a
nested loop. The general procedure is the same for all substitutions, you just need to include some
extra characters to show what level the substituted value is coming from:
Use To
{#Qname} Insert the response to Qname, where Qname
is at the same level as the question containing
the substitution (for example, both at the root
level or both inside the same loop).
{#\.Qname} Insert the response to Qname, where Qname
is at the root (that is, document or top) level.
{#^.Qname} (or {#^.^.Qname} and so on.) Insert the response to Qname, where Qname
is at the parent level relative to the current
question (or an ancestor, depending on the
number of ^. operators included).
If the response you want to insert belongs to a question that is part or a block or loop, you can use
the full question name to refer to it. For example:
{#\.DrinksLoop[{Water}].HowOften}
603
Base Professional
to insert how frequently the respondent drinks water.
Displaying the Values of Temporary Variables in Question and Banner Texts
Temporary variables are those that you define in the routing section using the Dim keyword. To
display the value of a temporary variable in a question or banner text, type:
{#VariableName}
in the text at the point at which you want the substituted text to appear. VariableName is the
name of the variable whose answer you want to display.
check that you typed # in front of the marker name and that the marker name is spelled correctly.
Displaying Loop Control Values in Repeated Questions
Loops are a flexible yet efficient way of defining repeated questions. The number of repetitions
can be specified using a numeric range or a list of categorical texts, both of which are called the
loop control list. If you are displaying each repetition of the questions on a separate page, you
may want to display the current value of the loop control item in the question texts. For example,
if you’re asking the same set of questions for each person in the household you may want to refer
to the people as Person 1, Person 2, and so on. Similarly, if you’re asking questions about a list of
brands you may want to include the name of the current brand in the question text.
To display the current value of the loop control item in a question or banner text, type:
{@LoopName}
in the question text at the point at which you want the substituted text to appear. LoopName is the
name of the loop. For example, if the loop is defined in the metadata section as:
RateLoop loop {
Knowledge "Subject knowledge",
Presentation "Presentation skills",
Interest "Ability to hold my interest",
Friendly "Friendliness/approachability",
Problems "Ability to deal with problems"
} fields "How would you rate the trainer for ...<p/>" (
Rating "{@RateLoop}" categorical [1..1]
{
Excellent, VGood "Very Good", Good,
Poor, VPoor "Very Poor"
};
) expand;
604
Chapter 1
each question page will start with the general question text defined after fields, then a blank
line, and then the item to be rated:
Figure 1-86
Page from a loop showing substitution of the loop control value in the question text
check that you typed in @ in front of the marker name and that the marker name is spelled correctly.
When a loop is nested — that is, one loop inside another — and you want to substitute the value of
the inner loop control list in the question text, you need to use the full name of the inner loop that
shows its relationship to the outer loop. Type:
{@OuterLoopName.InnerLoopName}
where:
OuterLoopName is the name of the outer (parent) loop.
InnerLoopName is the name of the inner (child) loop.
Here’s what a nested loop might look like during an interview. Each question is displayed on a
separate page and shows the values of the inner loop (attribute to be rated) and the outer loop
(course section) in its text.
Figure 1-87
Text substitution in a nested loop
605
Base Professional
The metadata section that defines the loop and the text substitutions is:
CoursePart loop
{
Architecture "Overview of system architecture",
Installation "Server installation",
Performance "Performance monitoring",
Troubleshooting, Security,
Access "Implementing access plans"
} fields (
RateFor loop
{
Relevance "Relevant to my job",
Content "Information provided",
Materials "Training materials",
Exercises "Exercises"
} fields (
Rating "Please rate the <I>{@CoursePart}</I> section
of the course for <I>{@CoursePart.RateFor}</I>."
categorical [1..1]
{
Excellent, VGood "Very Good", Good, Poor,
VPoor "Very Poor"
};
) expand;
) expand;
CoursePart is the outer loop and defines the part of the course that are to be rated. Its current
value is substituted in the Rating question text using {@CoursePart}. RateFor is the inner loop
and defines the aspects to be rated for each course part. Its current value is substituted in the
Rating question using {@CoursePart.RateFor}. Notice the use of standard HTML tags to
display these texts in italics.
If you want to see this example working, copy it into your own script and add the following
code to the routing section (see “Each Question on a Separate Page” in Asking repeated questions
for an explanation):
Dim training_section, attribute, question
For Each training_section In CoursePart
For Each attribute In training_section
For Each question in attribute
question.Ask()
Next
Next
Next
Abbreviations and Shortcuts with @
The interviewing program numbers the levels in nested loops relative to one another, so that the
current loop is level 1, the next level out (the parent) is level 2, and the next level beyond that (the
grandparent) is level 3, and so on. Rather that typing the hierarchical loop names when you want
to substitute loop values in question texts, you can use these level numbers instead.
{@} or{@1} is an abbreviated way of substituting the value of the current loop in question
texts. In the example you could use either notation instead of {@CoursePart.RateFor}. You
could also use {@2} instead of {@CoursePart} to substitute the value of the parent loop.
The advantage of using the fuller syntax is that it is immediately clear what is being substituted
so it helps in debugging problems in the script. The disadvantage is that the code is not
immediately portable if you want to copy and paste just the inner section of a nested loop. You
will always need to edit the substitution marker before the code will work. Most examples in this
documentation use the fuller syntax for clarity whereas the sample scripts installed with the IBM®
SPSS® Data Collection Developer Library use the abbreviated version for portability.
606
Chapter 1
Variable Response Texts
If you have a set of questions that use a shared or otherwise similar response list, and you provide
an Other response for entering responses not in the list, you may want to include whatever the
respondent enters at Other in one of the later response lists. For example, if you have some
questions about how the household uses cheese and the respondent uses Other to say that the
household puts cheese in mousetraps, you may want to include mousetraps as a possible response
to the question about how cheese is used most frequently.
If you just use the standard {#QuestionName} method, the substitution marker is replaced by
the text “Other: respondent’s answer” which, although usable, doesn’t look very professional.
A better option is to use Label Inserts which allow you to insert a specific text into a named
substitution marker. To do this, start by naming the marker and placing it in the response text.
Type the response definition as:
ResponseName "{Marker}"
where:
ResponseName is the response’s name.
Marker is a word of your choice that represents the respondent’s Other answer text.
For example:
DNOtherUses "{DNOtherText:w}"
Then add a statement to the routing section that inserts the respondent’s Other answer in the
marker, as follows. The statement is quite long so it has been split across two lines, but you should
type it all on one line or use an underscore at the end of very line that is continued.
Name.Categories.CatName.Label.Inserts["Marker"].Text
= PrevQ.Response.Other["OtherName"]
where:
Name is the name of the question in whose response list the substitution will occur (that is,
the question you are about to ask).
CatName is the name of the response whose text will be created by substitution.
Marker is the name of the marker you have used in the metadata for this response.
PrevQ is the name of the question at which the original response was given.
OtherName is the name of the Other response in the previous question.
Here’s the code for the cheese usage example. The questions are defined in the metadata as
follows. The point at which the substitution is to happen is marked by {OtherText} on the
penultimate line.
607
Base Professional
DNDoc define
{
DNWhatsNew "What's New",
DNArch "Architecture",
DNAdmin "Administation and Maintenance",
DNCustom "Customization",
DNRef "Reference"
};
DNAllUses "Which sections of the DDL do you normally use for
help with Interviewer Server Administrator?" categorical [1..]
{
Use DNDoc,
DNOtherUses "Other" other
};
DNMostUsed "And of those uses, which one or ones do you use
most often?" categorical [1..]
{
Use DNDoc,
DNOtherUses "{DNOtherText:w}"
};
The routing statements that display these two questions and substitute the respondent’s answer in
the second response list are as follows.
DNAllUses.Ask()
DNMostUsed.Categories.DNOtherUses.Label.Inserts["DNOtherText"].Text = _
DNAllUses.Response.Other["DNOtherUses"]
DNMostUsed.Ask()
If the respondent chooses Other and enters “interview scripting” at DNAllUses, the fifth response
in the list for DNMostUsed will show “interview scripting” exactly as the respondent typed it.
If the respondent does not choose Other, this example will show an unlabeled radio button for
Other in DNMostUsed. You can this by filtering the response list for the second question so that it
contains only those responses chosen at the first question. If the metadata is:
mrIntDoc define
{
mrIntWhatsNew "What's New",
mrIntArch "Architecture",
mrIntAdmin "Administration and Maintenance",
mrIntCustom "Configuration and Customization",
mrIntPerf "Monitoring and Tuning System Performance",
mrIntRef "Reference"
};
mrIntAllUses "Which sections of the DDL do you normally use for
help with Interviewer Server?" categorical [1..]
{
Use mrIntDoc,
mrIntOtherUses "Other" other
};
mrIntMostUsed "And of those uses, which one or ones do you use
most often?" categorical [1..]
{
Use mrIntDoc,
mrIntOtherUses "{mrIntOtherText:w}"
};
and the respondent chooses Architecture and Other at mrIntAllUsed, the following code in the
routing section will display just these options in the response list for mrIntMostUsed:
mrIntAllUses.Ask()
mrIntMostUsed.Categories.Filter = DNAllUses
mrIntMostUsed.Categories.mrIntOtherUses.Label.Inserts["mrIntOtherText"].Text _
= mrIntAllUses.Response.Other["mrIntOtherUses"]
mrIntMostUsed.Ask()
See Filtering Categorical Response Lists for further information about this type of filtering.
608
Chapter 1
Programmatically Inserting Text into Labels
You can use named inserts to insert any text into a label which you can then display during the
interview or write to a file. The topic about variable response texts shows one example of using
named inserts to present a respondent’s Other answer in the response list for a later question, but
you can use named inserts in other situations too. For example, if you are writing an error handler
that logs an error report to a file, you can define the fixed text of the message as an info item in
the metadata section (which makes it available for translation) and use named inserts to mark the
points at which interview-specific information should be inserted when the message is written out.
When defining the fixed text in the metadata section, mark the place at which the variable
text goes by typing:
{Marker}
where Marker is a word of your choice. If you can, it’s a good idea to make the marker’s name
similar to the text that will be substituted in its place, but if you’re trying to write portable or
reusable code this may not always be possible. If you need to make more than one substitution,
choose a different marker for each one.
Next, add statements to the routing section that insert the appropriate values in the markers
you have defined.
Name.Label.Inserts["Marker"].Text = Value
where:
Name is the name of the item in which the marker is used.
Marker is the name of the marker whose value you are defining.
Value is the value you want the marker to have.
Going back to the error handler example, here is the error message text from the metadata section.
Note that it has been split over several lines for readability. If you want to use this example
yourself, make sure that the entire <a> tag is typed on a single line as line breaks will cause it
to be treated as plain text:
ErrorDisplay "A processing error has occurred. If you have a moment to

spare, please help us to resolve the error by clicking
<a href=""mailto:_helpdesk@spss.com?subject=Error in survey {ProjectName}
&body=Please enter any details about what happened here:%0A%0A
Technical details:%0ATime of error (UTC) = {TimeStamp}%0A
Project = {ProjectName}%0ARecord identifiers = {Serial}, {RespId}%0A
{ErrorDetails}"">here</a> to send an email description of the problem.
<br/><br/>Please return later to try again. Thank you for your help."
info;
The marker names are enclosed in curly braces and all of them represent information that will
be specific to each interview. The markers are defined in the error handler code in the routing
section. As you’ll see, some values such as the project name and the respondent ID come from
properties that are maintained by the interview scripting language whereas others such as the
time come from external functions.
609
Base Professional
ErrorHandler2:
Dim err_msg
' Write message to log file
err_msg = "Error executing script (line " + _
CText(Err.LineNumber) + "): " + Err.Description + " (" + _
CText(Hex(Err.Number)) + ")"
Debug.Log(err_msg, logLevels.LOGLEVEL_ERROR)
' Populate inserts for user message
ErrorDisplay.Label.Inserts["TimeStamp"].Text = Now("UTC")
ErrorDisplay.Label.Inserts["ProjectName"].Text = IOM.ProjectName
ErrorDisplay.Label.Inserts["Serial"].Text = CText(IOM.Info.Serial)
If (IOM.Info.RespondentID = "") Then
ErrorDisplay.Label.Inserts["RespId"].Text = "Unavailable"
Else
ErrorDisplay.Label.Inserts["RespId"].Text = IOM.Info.RespondentID
End If
ErrorDisplay.Label.Inserts["ErrorDetails"].Text = err_msg
' Display message
IOM.Texts.InterviewStopped = ErrorDisplay.Label
' Terminate interview and flag as failed due to script error
IOM.Terminate(Signals.sigError)
If an error occurs, the respondent sees an error page with an explanation and a click here link.
Clicking the link opens the respondent’s mail program with the template message displayed:
Figure 1-88
Email window with template error message
Formatting Substituted Values
When the interviewing program makes substitutions, it inserts the values exactly as they are
defined in the script or as the respondent typed them. When you display something that the
respondent typed, you can change the formatting so that, for example, a cost value is always
displayed with a currency symbol and two decimal places, or a text value is always displayed with
the first letter in upper case and the rest in lower case. You do this by following the name of the
question or substitution marker with a colon and a formatting code:
{#Qname:fmt} or {@Marker:fmt} or {InsertName:fmt}
(Remember that the # version is for ordinary questions and the @ version is for loops.) You
can use any formatting code that the IBM® SPSS® Data Collection function supports, but the
ones that you’ll find most useful are listed here.
610
Chapter 1
Decimal Numbers
If the substituted value is a decimal number (for example, the response to a question whose type is
double), you can specify the number of decimal places to be displayed. The character used for the
decimal point (dot or comma) is determined by the setting of the IOM.Language or IOM.Locale
property in the script or, if this is undefined, by the language of the respondent’s browser.
These properties also control the character displayed for the thousands separator: a comma is
used for languages such as English that normally use a comma, and a space is used for countries
such as France and Germany that normally use a dot. Note, however, that displaying examples of
numbers that use a thousands separator may be confusing for respondents when the interview
scripting language normally requires responses to be entered without this character. Refer to
“Allowing a Thousands Separator Character” in Questions with Decimal Responses for details.
Methods of formatting decimal values are shown below and are based on the response
Interest=15.8241 and Cost=50870.
Substitution marker Produces
{#Interest:f2.3} 15.825 or 15,825 depending on the browser setting.
Rounding is always away from zero.
{#Interest:f2.0} 15 for all respondents.
{#Cost:f2} 50870.00 or 50870,00 depending on the browser
setting. The number of decimal places shown
depends on the default for the locale. Decimal
values are padded with zeroes to reach the required
number of decimal places.
{#Cost:n} 50,870.00 for a respondent running a UK English
browser, or 50 870,00 for a respondent in, say,
France, where the decimal separator is a comma and
the thousands separator is a dot.
Currency
If the substituted value is a currency value you can use the c formatting code to have it displayed
with a currency symbol and a set number of decimal places. The currency symbol and format
are determined by the setting of the IOM.Language or IOM.Locale property in the script or, if
this is undefined, by the language of the respondent’s browser. See Using Locale to Control
Decimal Number and Date Formats for further information about the relationship between
language and locale.
If you want to control the number of decimal places displayed, follow c with the number of
decimal places required. If the respondent’s answer has fewer decimal places, the interviewing
program pads the answer with zeroes at the end to reach the specified length. If the answer has
more decimal places, the interviewing program rounds the answer to the nearest two places,
rounding away from zero in borderline cases. Examples based on responses of Cost=26 and
Interest=15.8245 are as follows:
{#Interest:c} £15.8245 for a respondent running a UK English
browser, $15.8245 for a respondent running a US
English browser, or 15,8245€ for a respondent in,
say, France, where the currency is euros and the
decimal separator is a comma.
611
Base Professional

{#Cost:c0} $26 or the equivalent for non US-English browsers.
{#Cost:c2} $26.00 or the equivalent for non US-English
browsers.
{#Interest:c2} $15.83 or the equivalent for non US-English
browsers (15,83€ for a French browser, for
example).
Dates and Times
If the substituted value is a date and/or time you can display just the date, just the time, or both
and can choose the format in which it is presented. As with currency, the underlying date format is
determined by the setting of the IOM.Language or IOM.Locale property in the script or, if this is
undefined, by the language of the respondent’s browser. Available formats are shown in the table
and are based on an answer of Birth=2:10pm 4 September 1956:
{#Birth:d} or {#Birth:D} A date in the format specified by the respondent’s
browser; for example, 04/09/1956 or 04 September
1956 in a UK English browser and 09/04/1956
or Tuesday, September 04, 1956 in a US English
browser. If the year is omitted the current year is
assumed.
{#Birth:t} or {#Birth:T} A time in the format specified by the respondent’s
browser; for example, 14:10:00 or 2:10PM. If
there is no time specified, midnight (00:00:00) is
assumed.
{#Birth:f} or {#Birth:F} A date and time in the format specified by the
respondent’s browser; for example, 04 September
1956 14:10:00 (or 2:10:00 PM) in a UK English
browser or Tuesday, September 04, 1956 2:10 PM
in a US English browser.
Text
If the substituted value is text that the respondent has typed, you have a range of formatting codes
available for determining the case in which the text should be displayed. In the examples that
follow, Flavor=Peach and Pineapple and OtherFlavor=apricot and mango.
Substitution marker Action Produces
{Flavor:l} (lowercase L) Lowercase first letter of text. peach and Pineapple
{Flavor:L} Lowercase the whole text. peach and pineapple
{OtherFlavor:u} Uppercase first letter of text. Apricot and mango
{OtherFlavor:U} Uppercase the whole text. APRICOT AND MANGO
{OtherFlavor:w} Title case the first word Apricot and mango
(upper case first letter and lower
case all others).
{Flavor:W} Title case all words. Peach And Pineapple
612
Chapter 1
Categorical Responses
When the interviewing program reads {#Qname} and Qname is the name of a categorical question,
it displays the labels of the answers chosen for that question exactly as they are defined in the
script. If you want to change the way in which the texts are displayed (for example, to display
them in lower case when they have been defined in mixed case), you need to use two formatting
codes, one that picks up the label text and the other that defines the format required. The two
codes must be separated by a semicolon. The code that picks up the response label is b, so the
general syntax for formatting categorical response texts is:
{#Qname:b;code}

{
Interviewer, Coder
};
the reference
{#Job:b;L}
will display the respondent’s answer all in lower case — interview scriptwriter or system
administrator, for example.
Response labels are treated as texts, so you can use any formatting character that is valid for
texts, as described earlier in this section. For example:
{#Job:b;U}
to display the respondent’s job title all in upper case.
Navigation Buttons
The interview scripting program normally displays Previous, Next, and Stop buttons on interview
pages. Previous is not displayed on the first page and Next is not displayed on the last page as they
are inappropriate in these contexts. You can also choose to display First and Last buttons to take
respondents directly to the first or last page of the interview, and a Goto button for selecting a
destination from a list of possible destinations. To do this, type:
IOM.Navigations.Add(NavigationTypes.Type)
in routing section, where Type is the type of navigation button you want to display, and is one of
nvPrev, nvNext, nvFirst, nvLast, nvStop, or nvGoto.
For example:
IOM.Navigations.Add(NavigationTypes.nvFirst)
IOM.Navigations.Add(NavigationTypes.nvLast)
IOM.Navigations.Add(NavigationTypes.nvGoto)
add the First, Last, and Goto navigation buttons to the set of navigation items for the interview so
that they are available for all pages from the current point onwards.
613
Base Professional
Temporarily hiding buttons
You can hide a button for certain pages and then reinstate it, and you can remove buttons from
the collection so that they are no longer available at all. To hide buttons temporarily, set the
button’s Hidden property to True:
IOM.Navigations[NavigationTypes.nvStop].Label.Style.Hidden = True
To reinstate the button, set Hidden to False. For more information, see the topic Styles for
Navigation Buttons on p. 775.
What to display in the Goto list
The selection list for Goto normally shows question names, but if you have used short or cryptic
question names you may prefer to display question texts instead. To do this, place either of the
following statements in the routing section of the script:
IOM.SavePoints.UseQuestionLabels = True
IOM.Navigations[NavigationTypes.nvGoto].Targets.UseQuestionLabels = True
Labels on Navigation Buttons
The interviewing program uses default texts for the navigation buttons that it displays on each
page. You can change these texts so that, for example, the Previous button is labelled Back or <<
instead. You can also translate these texts so that the button labels appear in the same language as
the rest of the questionnaire.
For All Projects

The default button names are defined in the StandardTexts.mdd file in C:\Program
Files\Common Files\IBM\SPSS\DataCollection\6\\IOM, and translations are available in a
number of languages. You can change these default texts using MDM Label Manager, or you
can use IBM® SPSS® Translation Utility to add translations in other languages if you wish. If
you want to change button labels for certain projects only, you may define the new names in the
metadata section of the script as described below.
Note: If you change StandardTexts.mdd in any way you must stop and restart IIS to have your
changes recognized. If you are running Windows 2003, you can stop and restart the IBM® SPSS®
Data Collection Interviewer Server application pool rather than restarting IIS if you prefer. This
has the advantage of not affecting any other applications that may be using IIS.
For All Pages in a Script
To define replacement labels for navigation buttons throughout a single project, place the
following statement in the metadata section of the interview script:
StandardTexts block fields
(
Navigations block fields
(
ButtonName1 "Text 1" info;
ButtonName2 "Text 2" info;
...
);
);
614
Chapter 1
where:
ButtonName is the name of the navigation button, and is one of: Next, Prev, First, Last,
GoTo, and Stop.
Text is the replacement text.
You can define any number of replacement texts just by listing them one after the other inside
the Navigations block. For example:

(
(
Next "Forward" info;
Prev "Back" info;
);
);
changes the labels for the Next and Previous buttons but leaves the labels of the others unchanged.
For Individual Questions
If you want to use different navigation labels for just one question in a script, you define them in
the metadata section as a helper text related to the question. Write the question’s definition as
normal and then insert the helperfields block at the end of the definition:
Qname "QText" Definition

helperfields
(
(
(
ButtonName "ButtonText" info;
);
);
);
where:
QText is the question text.
Definition is the remainder of the usual question definition, including the question type,
length, and so on.
ButtonName is the name of the navigation button, and is one of: Next, Prev, First, Last,
GoTo, and Stop.
ButtonText is the replacement text.
For Groups of Questions
If you want to make the same changes to a set of consecutive questions, you can use Inserts.
Inserts are normally used for text substitution in question and response texts but they work equally
well with navigation buttons. Start by adding a StandardTexts block to the metadata section
615
Base Professional
defining the buttons whose labels you want to change and specifying a unique insert name for
each one. For example:
StandardTexts "StandardTexts" block fields

(
Navigations "Navigations" block fields
(
Next "{Ins}" info;
);
);
Then, in the routing section, add statements at the appropriate points that define the values
of the insert labels:
IOM.Navigations[NavigationTypes.ButtonName].Label.Inserts["InsertName"]
= "ButtonText"
where:
ButtonName is the name of the navigation button, and is one of: nvNext, nvPrev, nvFirst,
nvLast, nvGoto, and nvStop.
InsertName is the name of the variable that represents the button’s text in the Navigations
block in the metadata section.
ButtonText is the replacement text.
For example:
IOM.Navigations[NavigationTypes.nvNext].Label.Inserts["Ins"] = ">>>"
This example defines a Next navigation button that has >>> as its label rather than the word Next.
Whenever you want to alter the button labels, just write another of these statements at the
appropriate point in the routing section.
Repeated questions
Repeated questions occur when you need to ask the same question or set of questions more
than once. Usually the question text varies slightly for each repetition so that, for instance, each
repetition refers to a different brand or product.
You can present repeated questions in two ways: as a grid or as a loop. With a grid, all the
repetitions are displayed in a table on a single page, with the questions forming one dimension of
the table (usually the columns) and the answers to the questions forming the other dimension. The
loop method displays each repetition on a separate page as if you had defined each repetition as a
separate question. Often the choice of presentation method will be entirely up to you, but you may
find that in some instances one method works better than the other.
This section introduces the following keywords for the metadata section of the interview script:
column Use the questions as the columns of the grid.
expand Save data in flat (non-hierarchical) format.
fields Introduce the questions to be repeated.
616
Chapter 1
grid Display the question as a grid when the question is

tabulated using an analysis product such as IBM®
SPSS® Data Collection Survey Tabulation, or when
the interview script is printed using IBM® SPSS®
Data Collection Paper. No effect in browser based
interviews.
loop Mark a set of repeated questions and define
the number of repetitions required (including
unbounded loops).
row Use the questions as the rows of the grid.
The topics in this section explain how loops and grids work and tell you how to:
Define categorical and numeric loops
Ask repeated questions either as a set of repetitions or as a grid
Add and remove iterations to create unbounded loops
Change the order of items that control the repetitions in categorical loops
Set initial and default cell values for grids
Set up a three-dimensional grid
Split large grids across multiple pages
Create categorical loops based on answers to a previous question
Create numeric loops based on answers to a previous question with no maximum value
Set up nested loops
Determine how data is written for repeated questions
Print repeated questions as grids using Paper
How loops and grids work
When you define a loop or a grid, you specify the number of times the questions in the loop or grid
are to be repeated by defining either a set of categorical values or a numeric range. These values
are called the loop control list. The loop may contain any number of questions of any type.
When the interviewing program encounters a loop with a list of categorical values, it repeats the
questions in the loop once for each categorical value. If the loop contains more than one question,
all questions are displayed one below the other on the same page, but you can force questions
onto separate pages if you wish. The first repetition uses the first categorical value in the loop
control list, the second repetition uses the second categorical value in the loop control list, and
so on. After the last question has been asked for the last categorical value in the control list, the
interviewing program continues with the next statement in the routing section.
If you substitute the current loop control value in the question text, you will have a set of unique
questions that could have been defined as completely separate questions. So, for example, a loop
that repeats a question asking how many journeys the respondent made, and that is repeated for
the categories train and car, has the same effect as writing one question that asks about train
journeys and another question that asks about car journeys. The advantage of using a loop is that it
makes analysis of the data across all questions in the loop easier. For example, if the data were
617
Base Professional
available you could calculate the total number of journeys made or the average journey length
as part of the analysis phase of the project.
Loops whose control list is numeric behave in much the same way, except that the questions are
repeated for every value within the specified range. This is the ideal way of repeating questions a
fixed number of times without the number of repetitions being related to anything in particular.
For example, in a product test you may have asked respondents to try a different product each
week over a period of four weeks. To find the order in which products were tested you might write
a loop that asks the question “Which product did you try first/next?” and repeat it four times.
Most loops can be presented as grids. For example, in a product test you might want to know the
order in which the products were tested (numeric), a rating (categorical), and what the respondent
liked about each product (text). If you choose to present these questions as a grid, the interviewing
program displays all three questions side by side as a table on a single page.
When a categorical question such as a rating question is displayed as a grid, the items to be rated
(defined as categories in the loop control list) form one dimension of the grid and the responses
to the question form the other dimension. Thus, a product rating grid may show the products as
the columns of the grid (these come from the loop control list) and the ratings as the rows of the
grid (these come from the question definition).
When a numeric or text question is displayed as a grid, each cell of the grid contains an input box
in which the respondent enters a numeric or text value as appropriate. As an example, suppose
you want to ask respondents how many times they took various forms of exercise during the
last week and the last month. You define one numeric question for each activity and place the
values “last week” and “last month” in the loop control list. The grid then provides one cell for
each combination of activity and time period.
Categorical loops
Write a categorical loop when you want to repeat a question or set of questions for a number of
categorical values; for example, when you want to know how frequently respondents read the
different sections of their newspaper, or when you want respondents to give their opinions on a
number of statements. To define this type of loop, place the following statement in the metadata
section of the interview script:
LoopName ["GridHeaderText"] loop
{
Categorical texts
} fields ["NonGridHeaderText"]
(
Questions
) expand;
where:
LoopName is the name of the loop.
GridHeaderText is an optional text that refers to all questions in the loop, and that is used
only when the loop is displayed as a grid. If there is only one question in the loop, this text
is displayed as the question text and the text defined in the question is ignored. If the loop
contains more than one question, this text is displayed above the grid as a whole and the texts
defined inside the questions are displayed in the grid itself. The interviewing program ignores
this text when questions are displayed as a series of repeated pages.
618
Chapter 1
Categorical texts are the texts for which the questions in the loop are to be repeated. You may
use a shared list here if you wish.
Questions are the questions you want to repeat, optionally with no question text defined.
NonGridHeaderText is an optional text that refers to all questions in the loop, and that is used
only when the loop is displayed as a series of repeated pages rather than as a grid. This text is
displayed at the top of the page, followed by the texts and response lists of the questions in the
loop. The interviewing program ignores this text when questions are displayed as a grid.
Here is the loop that asks respondents whether they have used the internet to obtain quotations for
various types of insurance.
InsuranceType "" define
{
Car, Health, Buildings, Contents, Travel
};
InsuranceType1 "Insurance Type" loop
{
use InsuranceType
} fields (
InternetQuote "Have you ever used the internet to obtain quotes
for {@InsuranceType1} insurance?" categorical [1..1]
{Yes, No};
) expand;
If you present the question as a loop, the InternetQuote question is repeated five times, once for
each section in the loop control list, and each time the current section name is substituted in the
question text. Notice how the example uses {@InsuranceType1} to represent the current value of
the loop control variable (InsuranceType1) in the question text. This type of specification is
particularly suited to CATI interviews where the interviewer reads the text of each question to
the respondent.
For self-completion Web interviews, you may prefer to use a grid layout. To achieve the best
effect, move the question text to the start of the loop and reword it as follows.
{
};
InsuranceType2 "Will you use the internet to compare prices
when your insurance for the following becomes due?" loop
{
use InsuranceType
} fields (
WillUseInternet "WillUseInternet" categorical [1..1]
{Yes, No};
) expand;
619
Base Professional
This produces the following grid:

Figure 1-89
Categorical grid with categories as the rows of the grid (the default)
This grid looks very drab and uninspiring. You can use styles and templates to create grids that are
visually more attractive and are much easier to use. See Styles for Grids and Default Styles for
Grids, and Grid Templates for details.
As you can see, the loop control texts form the rows and the response texts form the columns.
This is the default layout and is the equivalent of placing the row keyword after the closing
parenthesis at the end of the fields specification. To generate a grid that has the loop control texts
as the columns and the response texts as the rows, place the column keyword after the closing
parenthesis at the end of the fields specification. The specification for the previous example
would therefore become:

{
};
InsuranceType2 "Will you use the internet to compare prices
when your insurance for the following becomes due?" loop
{
use InsuranceType
} fields (
WillUseInternet "WillUseInternet" categorical [1..1]
{Yes, No};
) column expand;
and the output would be:

Figure 1-90
Categorical grid with categories as the columns of the grid
620
Chapter 1
When a loop contains more than one question, all questions for a repetition are displayed one
below the other on the same page. When the respondent clicks Next to continue, the interviewing
program displays a new page containing all the questions for the second iteration. See Asking
Repeated Questions for information on how to display each question on a separate page.
Numeric loops
Use a numeric loop when you want to repeat one or more questions a fixed number of times, and
the number of repetitions can be specified as a number or a range of numbers.
Note: Use unbounded loops when you want to allow the respondent or interviewer to keep adding
the required number of iterations. For more information, see the topic Unbounded loops on p. 624.
The metadata syntax for this type of loop is as follows:

LoopName loop [NumExpr] fields
(
Questions
) expand;
where:
NumExpr is a numeric expression that determines how many times the questions in the loop
should be asked.
Questions are the questions you want to ask.
Here is a very simple example that asks the respondent to choose three insurance companies.
Because the question is asked three times you will know the order in which the respondent chose
the companies:
InsuranceCompanies define
{
RedWhiteBlue "Red, White, Blue Insurance",
InsuranceToGo "Insurance To Go",
WhistleHope "Whistle and Hope",
BestDeals "Best Deals",
CloverBenCo "Clover Ben and Co"
};
InsuranceCompany "Insurance companies to try"
loop [1..3] fields
(
WhichCompany "Which company will you try {number}?" categorical [1..1]
{
use InsuranceCompanies,
OtherCompany "Another company" other
};
) expand;
The routing section contains the following code to set the value of the number insert to first,
second, or third according to the repetition.
Dim iteration, icomp
iteration= 0
For Each icomp in InsuranceCompany
iteration= iteration + 1
if iteration= 1 then
icomp.WhichCompany.Label.Inserts["number"].Text = "first"
elseif iteration= 2 then
icomp.WhichCompany.Label.Inserts["number"].Text = "second"
else
621
Base Professional
icomp.WhichCompany.Label.Inserts["number"].Text = "third"
end if
icomp.WhichCompany.Ask()
Next
There are many ways in which you can specify the number of repetitions required. For example,
you can repeat questions for all values in a range or only for selected values. You can set the
start and end values in the range as part of the loop specification, or you can specify just an end
value so that the start value varies according to the content of the current interview. The table
shows examples of all the variations you can use.
Repeat for Example Description
Single values [100, 200, 500] 100, 200 and 500 only. Real
numbers do not work in loop
control lists. If you want to use
real values use a categorical loop
instead.
A range of values [1..10] All whole numbers between 1 and
10 inclusive.
Several different ranges [24..30, 50..60] All whole numbers between 24
and 30 inclusive and between 50
and 60 inclusive.
Exclusive values [1..10, ^5..7] All whole numbers between 1
and 10 inclusive, except the
whole numbers between 5 and 7
inclusive. (In other words, 1, 2, 3,
4, 8, 9, 10.)
Stepped values [6..30 step 2] All whole numbers between 6
and 30 inclusive in steps of 2. (In
other words, 6, 8, 10, 12, 14, 16,
18, 20, 22, 24, 26, 28, 30.)
From undefined minimum to fixed [..10] Whole numbers less than 11,
maximum including negative numbers. The
start point is set independently for
each interview.
Has a fixed starting point and [1..] Whose number may be 1,2,3…and
an undefined endpoint (an so on.
unbounded loop).
Has an undefined starting point [..] Whose number may be 1,2,3…and
and an undefined endpoint (an so on.
unbounded loop).
Here is a numeric loop that asks respondents how much their car insurance was in each of three
different years and how they paid it. Notice how the example uses {@Year} to represent the current
value of the loop control variable (Year) in the question text.
YearLoop "" loop [2005, 2006, 2007] fields
(
CarInsuranceCost "Approximately how much did you pay for car
insurance in {@YearLoop}?" long [1 .. 9999];
CarHowPaid "And which payment method did you use in {@YearLoop}?"
categorical [1..1]
{
CreditCardSingle "Single payment on credit card",
CreditCardSeveral "Several payments on credit card",
ChequeSingle "Single cheque payment",
ChequePostDated "A number of post-dated cheques",
Cash,
622
Chapter 1
OtherPaymentMethod "Other (specify)" other

};
) expand;
If you present the questions as a loop, the two questions are displayed one after the other on
the same page for each repetition:
Figure 1-91
Loop with two questions displayed on same page
See Asking repeated questions for information on how to display each question on a separate page.
If you present the questions as a grid, the questions for each repetition will be displayed side by
side with a separate page for each repetition. As the illustration below shows, the layout for this
example is not particularly pleasing for the Other category, so you may prefer to use a different
layout for questions with this type of response.
Figure 1-92
Loop with two questions displayed as a grid
623
Base Professional
Note that you cannot use real (decimal) numbers in the loop control list. If you want to write a
loop based on real values, use a categorical loop and specify the values as texts. A typical example
of a repeated question based on a list of real values is one in which respondents are asked how
likely they would be to purchase a product at various prices.
Asking repeated questions
As a grid
To present a set of repeated questions as a grid, type:

LoopName.Ask()
in the routing section of the interview script as for an ordinary question. This is the default if
you do not specify a format.
The interviewing program displays the questions side by side in tabular form, using the values
in the loop control list as the rows of the grid and the repeated questions as the columns.
Note: If the set of repeated questions contains a compound item or is nested, the compound
and/or nested items are ignored.
As a set of repetition pages

To display each repetition on a separate page, type:
LoopName[..].Ask()
in the routing section. The [..] notation means “for each item in the loop control list” and is a
shorthand way of telling the interviewing program to step through each value in the loop control
list one at a time. The rest of the statement simply says to display the question.
Each question on a separate page

If a loop contains more than one question, the [..] notation displays all questions for a repetition
on the same page. If you want each question to be displayed on a separate page, place the
following statements in the routing section:
Dim variable_name
For Each variable_name In loopname
variable_name.question_name1.Ask()
...
variable_name.question_namen.Ask()
Next
where:
variable_name is a variable name of your choice. It is used to point to each question in
the loop in turn.
loopname is the name of the loop containing the repeated questions.
question_name1 to question_namen are the names of the questions in the loop.
For example:
Dim thisq
For Each thisq In YearLoop
thisq.CarInsuranceCost.Ask()
624
Chapter 1
thisq.CarHowPaid.Ask()
Next
Because each question is asked using a separate Ask statement, the interviewing program will
present them on separate pages.
Asking selected repetitions only

You do not have to repeat loop questions for all iterations of the loop. To ask the questions for a
particular repetition only, type:
LoopName[Repetition].Ask()

Repetition identifies the repetition for which the question is to be asked. In a numeric loop,
this is simply a numeric value from the range expression. In a categorical loop, this is a
category text enclosed in braces; for example BrandLoop[{Brand1}].Ask().
An alternative for categorical loops is:
LoopName.Category.Ask()
where:
Category is the category name; for example, BrandLoop.Brand1.Ask().
For further information about filtering loops see Filtering Loops.
Unbounded loops
You can script unbounded (also known as unexpanded) loops, where iterations can be added to a
loop continually during an interview and the maximum number of iterations is undefined. These
script loops iterate based on a previous numeric response with no maximum configured value.
The scripts used to build unbounded loops can be rendered in the IBM® SPSS® Data Collection
applications that support unbounded loops.
You can script an unbounded loop that enables the respondent, or interviewer, to continue adding
the required number of iterations. A selection can be made to end the loop when the number of
iterations is satisfied. When the loop is closed, an added iteration is essentially deleted. The
following example provides a simple unbounded loop:
Person "Person" loop [1..] fields -
(
Name "Name" text;
Age "Age" categorical [1..1]
{
Young "Young",
Old "Old"
};
);
625
Base Professional
In the above example, the unbounded loop does not include an expand keyword in the definition.
The unbounded loop can be called with the following script:
' Ask questions for each person in the household
HowManyPeople.Ask()
Dim Index
For Index = 1 To HowManyPeople
Person[Index].Ask()
Next
' An alternative to the above would be the following if the Person
' loop is setup to use HowManyPeople as its Iteration control.
HowManyPeople.Ask()
Person.QuestionFilter = HowManyPeople
Person.Ask()
' Add a new person

Person[LoopIterations.New].Ask()
Configuring unbounded loops
Before an unbounded loop can be asked, the iterations related to it should be specified as in the
following example:
person "Person" loop [..] fields -

(
trip "Trip" loop [..] fields -
(
DaysForStay "DaysForStay" long;
CountryName - text;
);
name "Name" text;
numberOfTrips "numberOfTrips" long;
);
You can specify the iterations via the property QuestionFilter (for example,
Person.QuestionFilter = 3).
You can specify the iterations via the method Add. For example:
Set SinglePerson = person[LoopIterations.New]
In this example, person.count will be increased by one.
The number of iterations should be specified before an unbounded loop is asked; if the loop
contains a nested unbounded loop, the number of iterations should also be specified before being
asked.
Adding iterations to an unbounded loop
The following example can be used to add unbounded loop iterations:
person[LoopIterations.New].Ask()
Set SinglePerson = person[LoopIterations.New]
SinglePerson.Ask()
626
Chapter 1
If the unbounded loop’s QuestionFilter is set (for example, to 3) before adding an iteration, the
newly added iteration will have a levelID of 4. If the unbounded loop’s QuestionFilter is not set,
the newly added iteration will have a levelID starting at 1.
The example .mdd file MeetingManagent-Enrollment.mdd demonstrates how to add unbounded

loop iterations. The file is installed with the IBM® SPSS® Data Collection Developer Library at:
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Documentation.
Removing iterations from a unbounded loop
The following example can be used to remove unbounded loop iterations:

Person.delete (1)
In the above example, the iteration with a LevelID=1 will be deleted.

Person.delete (“_1”)
In the above example, the iteration with an iteration name of “_1” will be deleted.
The example .mdd file MeetingManagent-EnrollmentPlus.mdd demonstrates how to remove

unbounded loop iterations. The file is installed with the Data Collection Developer Library at:
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Documentation.
Changing the order of loop control list items
You can vary the order in which the loop control items are selected using statements in either the
metadata or the routing section. Specifications in the metadata section apply to all interviews
whereas specifications in the routing section may be tailored according to the respondent or type
of interview (for example, do not randomize in test interviews).
You can control the order of items in the loop control list by placing any of the following keywords
at the end of the list, as you do with standard categorical questions:
asc. Select items in ascending order, for example, A to Z.
desc. Present items in descending order, for example, Z to A.
ran. Select items in a random order.
rev. Reverse the order of the items in the list for alternate interviews. Items are selected
in reverse order for the first, third, fifth, and so on, interviews and in the defined order for
other interviews.
rot. Rotate items so that each interview starts at a different position in the list while keeping
the items in the same order overall.
In the following example, the columns for insurance types will be presented in a random order for
each interview:
{
627
Base Professional

};
UsedBroker "For the following types of insurance, how often
do you use the services of a specialist broker?" loop
{
use InsuranceType
} ran fields (
InsuranceBroker "" categorical [1..1]
{
AllTime "All the time",
Mostly "More often than not",
Sometimes, Never
};
) expand;
In the routing section you specify the order for the items in the loop control list using
IQuestion.QuestionOrder. Type:
Loopname.QuestionOrder = OrderConstants.order
where order is one of:

Value Action
oAscending Sort items in ascending order. Normally used only
with categorical values.
oCustom Sort items as defined by the question’s
Category.Filter property. Use when you want a
customized order that cannot be achieved using the
standard ordering keywords.
oDescending Sort items in descending order. Normally used only
with categorical values.
oRandomize Sort items in a random order.
oReverse Reverse the order of items between respondents.
oRotate Rotate items in the loop control list.
For example, to sort the list of insurance types in the previous example in rotation you would type:
UsedBroker.QuestionOrder = OrderConstants.oRotate
If you want to select items in an order that is not covered by the standard options you can specify
the order using the question’s Category.Filter property and then apply it using the oCustom
setting. As an example, here’s a variation of the earlier script. The loop is defined as:
{
};
UsedBroker "For the following types of insurance, how often
do you use the services of a specialist broker?" loop
{
Sometimes, Never
} fields (
InsuranceBroker "" categorical [1..1]
{
use InsuranceType
};
) expand;
628
Chapter 1
but for some respondents we want to ask about insurance in the following order: buildings,
contents, travel, car, and health. There is no option that provides this automatically so we must
specify the order ourselves as follows:
UsedBroker[..].InsuranceBroker.Categories.Filter = _
{Buildings, Contents, Travel, Car, Health}
and then apply it for the appropriate respondents using:
UsedBroker[..].InsuranceBroker.Categories.Order = OrderConstants.oCustom
Points to remember when altering the order in the Routing section

If you specify ordering for a loop in both the metadata and the routing section, the routing
When a loop is displayed as a grid, the questions and categories must be the same for all
repetitions. You may change the order of the loop control items for the grid as long as you
use the same order for each iteration. In other words, do not use the oCustom setting to
specify different orders for different iterations.
If a loop is re-asked, the interviewing program uses the same ordering each time. The only
time this changes is if the script defines a different order property for the replay.
Loops can be nested — that is, a loop can contain other loops. When you define ordering for a
loop that contains other loops, the ordering applies only to the loop named on the ordering
statement; it does not apply to loops nested within that loop. If you want to reorder the
questions within a loop you must write a separate statement to do this. See Loops inside loops
for further information about nested loops.
If the order of responses in a row or column of a grid differs from the order of those responses
in the header row or column, the interviewing program does not display the grid. Instead, it
displays an error message and writes that message to the IVW* log file. This prevents data
corruption that would happen if the script was allowed to run as written .A simple way to
avoid this error is always to specify rotation or randomization for loops in the metadata
section of the script, as this ensures that all iterations of the loop will use the same rotation or
randomization pattern. If you have to specify rotation or randomization in the routing section,
you should always set the program’s state before requesting the reordering. For example,
always set the randomization seed before requesting randomization, as shown here:
For Each Question In MyLoop

SetRandomSeed(IOM.Info.RandomSeed)
Question.Order = OrderConstants.oRandomize
Next
Initial and default cell values
Grids are displayed with blank cells and respondents must usually enter or select a response in
every cell of the grid before they can continue to the next page. In large grids where only some
cells may be relevant, you can make the grid less of a chore to complete by setting a default
response such as 0 or “Not applicable” for all cells. Any cells that the respondent leaves blank will
be assigned the default value. This is particularly useful for repeated numeric and text questions
where respondents often do not need to enter values in all cells.
629
Base Professional
Respondents do not see these default values the first time the grid is displayed, but if the grid is
redisplayed for any reason (errors or snapbacks, for example) default values will be shown in all
cells that the respondent previously left blank.
Another option is to define an initial value for each cell so that the grid is displayed with this
value in each cell. Any cells that the respondent does not change are saved with the initial value
as the data for those cells.
You can set default and initial values in either the metadata or the routing section of the interview
script. If the same value applies to all cells in the grid, it is probably easiest to set the value in
the metadata section, as you would for non-repeated questions, so that it is immediately obvious
to anyone looking at the question’s definition. For example:
WhichYear "WhichYear" loop [2005, 2006, 2007]
fields (
HealthInsuranceCost "Approximately how much did you pay for health
insurance in {@WhichYear}?" long [1 .. 9999] initialanswer(0);
) expand;
To set a different default or initial value for each repetition, place the following statements in
the routing section:
LoopName[Repetition].Qname.Response.Type = Value
where:
Repetition is the repetition number for which the default or initial value is to be set.
Qname is the name of a question in the loop.
Type is Default for a default value or Initial for an initial value.
Value is the response for this question. The value must be a valid response to the question and
must match the question’s data type; that is an integer for a long question, a real number for a
double question, or a text enclosed in double quotes for a text question.
For example:
HowManyLoop[..].Brand.Response.Initial = 0
PriceLoop[1].Cost.Response.Initial = 0.0
NameLoop[5].Name.Response.Default = "No answer"
Three-dimensional grids
A three-dimensional grid is a categorical grid in which each cell contains a drop-down selection
list of possible responses. You may find this an efficient method of obtaining ratings for
subquestions based on two characteristics, where one of the characteristics is common to all
subquestions. For example, suppose you have survey that compares a number of insurance
companies. You want to obtain ratings for various aspects of each company’s web site. The value
in each cell of the grid has three characteristics: company name, aspect to be rated, and rating.
The rating is the component that is supplied by respondents, so that must be the value that is
entered into each cell of the grid during interviews. Once you take this out of the requirement,
you are left with a standard grid of company name by aspect. The question you want to repeat is
“How would you rate the web site for company X for Y?” so the company names become the
630
Chapter 1
loop control texts and the aspects to be rated become the response texts. When displayed, the
grid looks like this:
Figure 1-93
Example output for a three-dimensional grid
The general structure of a three-dimensional grid in the metadata section is as follows:

LoopName "Question text" loop
{
Repetition texts
} fields
(
Qname "" loop
{
Grid categories
} fields
(
SubQname categorical [1..1]
{
Responses
};
) expand;
) [column|row] expand;
where:
Question text is the question text.
Repetition texts are the texts to use for each repetition of the question. You can use a shared
list here is you wish.
Qname is the name of the question that forms the second dimension of the grid (either rows or
columns depending on the position of the repetition texts). You can use a shared list here if
you wish.
Grid categories are the category texts for the second dimension of the grid (either rows or
columns depending on the position of the sub-question texts).
SubQname is the name of the sub-question that the respondent answers in each cell of the grid.
Responses is a list of categorical responses from which respondents can choose an answer in
each cell of the grid. You can use a shared list here if you wish.
Here is the definition for the carrier by service by rating grid:
WebSite "How would you rate each company's web site for the following?"
loop
{
631
Base Professional
use InsuranceCompanies
} fields (
Aspect "" loop
{
Usability "Ease of use",
Information "Provision of information",
Visual "Visual layout/appearance",
Speed "Speed of loading"
} fields (
Rating "Rating" style(control(type="droplist"))
categorical [1..1]
{
NoSelect "Please select"
{
Excellent, VeryGood "Very Good",
Good, Fair, Poor
}
};
) expand;
) expand;
Notice how the drop-down list has been set up to prompt the respondent to select a category
in each cell. The response list has been defined with a subheading which would normally be
displayed with the responses listed below it. However, because only one response can be visible
in the cell at a time, the subheading acts as a prompt instead. The fact that the list should be
displayed as a drop-down list is defined in the routing section, which is as follows:
WebSite[..].Aspect[..].Rating.Style.Control = ControlTypes.ctDropList
WebSite.Ask()
WebSite[..].Aspect[..].Rating is a reference to every cell of the grid: WebSite[..] refers to each

carrier, Aspect[..] refers to each service, and Rating refers to the ratings, so this part of the
statement translates to “For every combination of carrier, service and rating”.
Style refers to the display characteristics of each cell, and Control is the keyword for the way
the cell is to be displayed. In this example, a drop-down list is required so the display control for
each cell is set to ControlTypes.ctDropList. Don’t worry about having to remember all these words.
The routing section has a ScriptAssist facility that displays selection lists of appropriate keywords
that change as you type (see Creating Your First mrScriptBasic Script for details.
The second line of routing instruction simply tells the interviewing program to display the
question.
Splitting large grids over several pages
Large grids can be difficult to display effectively on a single page without resorting to small fonts
and cramped row and column spacing. A better approach is to split the grid over a number of
pages. This immediately makes it easier for respondents to use and allows you to retain the styles
and page layout set in your standard templates.
Start by defining the grid in the metadata section in the usual way. Then place the following
statements in the routing section at the point you want to display the grid.
Dim start_pos_variable
Dim numrows_variable
start_pos_variable = 0
numrows_variable = rows_per_page
' QuestionFilter assignment is split across two lines for printing purposes only
While (start_pos_variable < loopname.Categories.Count)
loopname.QuestionFilter =
loopname.Categories.Mid(start_pos_variable, numrows_variable)
loopname.Ask()
632
Chapter 1
start_pos_variable = start_pos_variable + numrows_variable

loopname.QuestionFilter = NULL
End While
where:
start_pos_variable is a variable that is used to mark the start position in the loop control
list for the current page.
numrows_variable is a variable that stores the number of rows to display on each page.
rows_per_page is the number of rows to display on each page. You must specify this value in
the routing section (as in the example below) or ask a question whose value can be used as the
value for this parameter.
Here’s an example that will make understanding this general syntax much easier. The grid is
defined in the metadata section as follows:
LargeGrid "For which of the following insurance companies have
you seen or heard advertising during the three months?" loop
{
CloverBenCo "Clover Ben and Co",
Rothwood,
Woodhurst "Woodhurst Ltd",
TusonNoakes "Tuson, Noakes and Partners",
GoFaster "Go Faster",
BestDealsFaster "Best Deals Faster"
} fields (
SeeHearAds "SeeHearAds" categorical [0..]
{
Seen "Saw advertising",
Heard "Heard advertising"
};
) expand;
The routing statements that split this grid so that only five rows are displayed on each page is:
Dim startpos
Dim numrows
startpos = 0
numrows = 5
While (startpos < LargeGrid.Categories.Count)
LargeGrid.QuestionFilter = _
LargeGrid.Categories.Mid(startpos, numrows)
LargeGrid.Ask()
startpos = startpos + numrows
LargeGrid.QuestionFilter = NULL
End While
The While loop in this code is repeated all the time that the current start position in the
loop control list (startpos) is less than the total number of items in the loop control list
(LargeGrid.Categories.Count). It filters the loop control list by selecting five items starting at
the current start position, and then displays a grid containing the repeated questions and those
five items. When the respondent clicks Next, the new start position is calculated by adding five
(numrows) to its current setting.
The last statement inside the loop resets the filter to null so that all items in the loop control list
will be eligible for inclusion in the grid when the loop is repeated. The fact that the start position
has changed means that those items that have already appeared in the grid will be skipped, so
there will be no duplication of items. If you omit this statement the loop will be repeated once
633
Base Professional
only because, as far as the interviewing program is concerned, all items were used in the first
repetition: the fact that filtering excluded most of them is irrelevant.
Categorical loops based on answers to previous questions
Often you’ll want to ask a question for each response given to an earlier question; for example, in
a brand awareness test you may ask respondents to name brands they have seen advertised and
then, for each of those brands, ask what type of advertising was seen or heard and where.
The way to do this is to define the repeated question in the metadata section as if you were
going to ask the question for all brands, not just those mentioned by the respondent. Then, in
the routing section, you define a filter that restricts the brand list to those mentioned, and then
ask the question in the normal way.
Note: You can also create Numeric loops.
Here is the metadata section for some insurance advertising awareness questions:
InsuranceCompanies define
{
CloverBenCo "Clover Ben and Co"
};
Adverts "Which insurance Companies have you seen or heard
advertised during the last month?" categorical [1..]
{
};
Company "Company loop" loop
{
} fields (
AdvertType "What type of advertising did you see/hear for
{@Company}?" categorical [1..]
{
TV, Radio, Newspaper, Magazine, Billboard
};
WhereAdvert "Please specify exactly where you saw/heard the
advertising (e.g., which TV channel, which magazine)" text;
) expand;
The Company loop is set up to ask the questions for each item in InsuranceCompanies, but
you want to restrict this to only the companies mentioned at Adverts. You do this by defining a
filter in the routing section as follows:
Adverts.Ask()
Company.Categories.Filter = Adverts
Company[..].Ask()
The filter statement tells the interviewing program to filter the categories held in Company so that
they are the same as the answers given to Adverts. For more information, see the topic Filtering
Categorical Response Lists on p. 680.
634
Chapter 1
If the respondent saw advertising for Insurance To Go and Clover Ben and Co, the loop is repeated
twice with the page for the first iteration looking like this:
Figure 1-94
Example output for a loop based on response to a previous question
Loops inside loops
Loops can contain other loops. This is called nesting. When loops are nested, the interviewing
program generates a separate page for each repetition of the outer loop and then displays on that
page all the questions in the inner and outer loops in the order they are defined. If the inner loop
contains more than one question, those questions are displayed side by side across the page, with
categorical questions being displayed as grids unless the routing section specifies a non-grid layout.
As an example, suppose that the metadata section contains the following code. The indentation
helps show the hierarchy of the loop, and the keywords and punctuation that mark the start and
end of each loop have been highlighted to make this clearer.
Newspapers loop
{
Bugle "The Daily Bugle",
Herald "The Morning Herald",
Informer "The Informer"
} fields
(
RatePaper "On a scale of 1 (Excellent) to 5 (Very poor), how would you
rate {@Newspapers}?" long [1..5];
NewsSections "" loop
{
Property, Arts, Sports, Financial
} fields
(
ReadSection "How often do you read the following sections of this
newspaper?" categorical [1]
{
Always, Usually, Sometimes, Never
};
RateSection "Rating: 1=Excellent, 5=Very bad" long [1..5];
) expand;
635
Base Professional
Like "Is there anything that you particularly like about

{@Newspapers}?" text;
) expand;
The outer loop consists of the RatePaper and Like questions, while the inner loop consists of
ReadSection and RateSection. The routing section contains just Newspapers[..].Ask(), so the first
page that the respondent sees for the Newspapers loop is as follows:
Figure 1-95
Example output for a nested loop
Notice that ReadSection has been converted to a grid and that RateSection has been placed beside
it. If you would prefer to have some or all of the questions presented on separate pages, refer to
Asking repeated questions for instructions on how to achieve this.
Another thing to notice about the metadata section of this example is the blank text on the
NewsSections loop statement. This generates a blank line on the screen above the start of the
inner loop questions. Without it, the page would show the loop’s name at the point at which
the inner loop starts.
Note: Although there is theoretically no limit to the amount of nesting in a loop, the HTML player
supports only two levels of nesting when the innermost loop is displayed as a grid.
Controlling how case data is written
Case (respondent) data for questions in grids and loop can be stored in a flat format or in a
hierarchical format. By default, repeated questions are defined as levels, which means that the
case data is stored in a hierarchical format. If you want to store it in a flat format, place the
636
Chapter 1
expand keyword at the end of the loop specification in the metadata section of the interview
script, as follows:
{
Loop control list
} fields
(
Questions
) expand;
Printing and tabulating repeating questions as grids
If you want to print or tabulate repeated questions as grids rather than as separate questions, place
the grid keyword at the end of the loop specification in the metadata section of the interview
script, as follows:
{
Loop control list
} fields
(
Questions
) grid;
The effects are as follows:

Web or CATI interviews None. The method of presentation is determined by
instructions in the routing section.
IBM® SPSS® Data Collection Paper The question is printed as a table.
Survey Results activity You can create a complete table using just this
question.
IBM® SPSS® Data Collection Metadata Model to Each repetition is checked to ensure that it has the
Quantum same punch and offset allocations.
mrQtSpecDSC The IBM® SPSS® Quantum™ specification defines
a grid question rather than an ordinary question.
More Than One Question on a Page
The interviewing program normally displays each question on a separate page. The exceptions
are loops that contain more than one question, where the interviewing program starts a new page
for each repetition of the loop rather than for each question in the loop (see Asking repeated
questions for details.)
When questions are short and simple and are closely related, you may wish to present several
questions all on one page. The interviewing program displays the questions one below the other,
but you can change this by using a template that applies a layout of your choice to the page. For
example, with four questions you may decide to display the first two questions side by side with
the third and fourth questions side by side beneath them.
637
Base Professional
This section introduces the following keywords for the metadata section:
block Define a group of questions to be displayed on a
single page
compound Print categorical items that use the same category
list side by side
page List the names of questions to be displayed on the
same page.
The section explains how to:

Display a list of questions on the same page
Define a block of related questions that will be displayed on the same page.
Print categorical questions and categorical loops that use the same category list side by side
Display the same questions at the top of every page
Change the order in which questions in a block, compound, or page are asked
Note: Currently, page and block generate identical page layouts during interviews, but there are
plans for this to change in future versions. If you are writing an interview script that you may
want to use in the future, we recommend using page when the requirement is simply to display
multiple questions on a page, and block when the requirement is to keep the questions together for
sorting or analysis purposes.
Displaying a List of Questions on the Same Page
When you want to display a set of questions all on the same page, place the following statement in
PageName ["Text"] page(Qname1, ..., Qnamen);
where:
PageName is the page name. This is the equivalent of a question name and you use it in the
routing section when you want to display the page.
Text is a text to display at the top of the page.
Qname1 to Qnamen are the names of the questions you want to display on the page.
For example:
CommState "Over the last year, would you say that communication
in the company has" categorical [1..1]
{
Improved,
Same "Stayed the same",
Worse "Got worse"
};
CommStateWhy "Why do you think this is?" text;
Communication page (CommState, CommStateWhy);
To display the page during the interview, type:

PageName.Ask()
638
Chapter 1
in the routing section, where

PageName is the name of the page.
In this example, typing:
Communication.Ask()
displays the following page:

Figure 1-96
Example output for Page keyword using default template
The advantages of using page to display multiple questions on a page are as follows:
The questions can be defined anywhere in the metadata section.
Changing the order of questions on the page or replacing one question with another is simply a
case of editing the page statement.
Note that the page keyword controls the way questions are displayed; it does not affect the
way questions are held in a project’s metadata or the way the case data is stored. So, if you
ask a question once by displaying it on a page by itself and then again by displaying it using a
page statement, the second presentation is treated as a repeat of the question. The question is
displayed with the original responses shown, as is the case when a respondent snaps back to a
previous question. If the respondent changes the answers for the question, the new answers
overwrite the previous answers in the case data.
Similarly, if the same question appears on more than one page statement, but different
respondents see each page, only one set of metadata is stored for the question and only one
column is allocated to the question in the case data database. The fact that the question appears
with different questions for different respondents is irrelevant.
Note: IBM® SPSS® Data Collection Base Professional moves page statements to the end
of the metadata section when close and reopen the .mdd file. This does not affect the way the
script works.
639
Base Professional
Printing Categorical Items Side by Side
When a set of items uses the same set of categorical responses, you can display them side by side
across the page. This gives the appearance of a table or grid, because the common responses are
listed one below the other in the first column of the table, and the questions are displayed as the
other columns of the table. The illustration shows three simple categorical questions displayed
side by side using the default page layout template, but you can use it with categorical loops and
grids too.
Figure 1-97
Layout for a simple compound question
The general term for this type of question is compound question, and you are most likely to use it
if you will be using IBM® SPSS® Data Collection Paper to generate printed questionnaires from
the interview script. (Paper uses a similar layout to the one shown here, except that it displays the
question texts above the grid as a whole and labels the columns with the question names. This,
together with the styles and templates available with Paper, generates a pleasing layout on the
printed page.) For browser based interviews you will often find that you can achieve a similar
effect but with a better appearance if you use the page keyword, or you use a question template
designed specifically for displaying this type of question.
To define a compound question, type the following in the metadata section of the interview
script:
CompoundName ["Text"] compound Categories fields

(
Questions
);
where:
CompoundName is the name of the compound question.
Text is the overall text for the compound question.
640
Chapter 1
Categories are the categories for which the questions and loops are to be asked. You may
use a shared list here if you wish.
Questions are the questions and loops that you want to print side by side.
Simple Categorical Questions

Here is the metadata definition for the earlier illustration.
CommMethodList define
{
FocusGroups "Focus groups",
Newsletter "Internal newsletters",
Website "Company web site",
Email "E-mail",
MyManager "My manager",
DeptManager "Department head",
OtherCommMethod "Other"
};
CommMethods "How do you find out what is going on in the company?"
compound
{use CommMethodList} fields
(
MainMethod "Main method" categorical [1..1];
OtherMethods "Other methods" categorical [1..1];
PrefMethod "Preferred method" categorical [0..];
);
The interviewing program automatically namespaces the questions within a compound item. In
the example, the question names are CommMethods.MainMethod, CommMethods.OtherMethods,
and CommMethods.PrefMethod.
When placing questions side by side in a compound item, the interviewing program does not
leave extra space between the end of one question and the start of the next. As the earlier picture
shows, this creates a cluttered look when you use the script for web or telephone interviewing,
so you may want to increase the space between the two questions. You can do this by setting an
indent for the question text and response list for the second and subsequent questions. In the
example, you would place the following statements in the routing section immediately before
the .Ask statement:
CommMethods["OtherMethods"].Label.Style.Indent = 2
CommMethods["OtherMethods"].Categories[..].Style.Indent = 4
CommMethods["PrefMethod"].Label.Style.Indent = 2
CommMethods["PrefMethod"].Categories[..].Style.Indent = 4
641
Base Professional
This produces:
Figure 1-98
Extra horizontal space in a compound question
For more information, see the topic Indenting Response Lists on p. 763.
Loops and Grids
The examples so far have used simple categorical questions, but the compound item has been
designed for use with loops and grids too. Here’s an example that places two grids side by side.
The grids are defined in the metadata section as:
GridCompound "" compound
{use Agreement}
fields (
RatingGrid1 "How would you rate the company for the following?"
loop fields (
Company "" categorical [1..1]
{
Teamwork "Teamwork is encouraged" ,
WorkFair "Work is distributed fairly",
AllEqual "Teams work well together"
};
) expand;
RatingGrid2 "How would you rate your manager for the following?"
loop fields (
Manager "" categorical [1..1]
{
Leads "Leads by example" ,
Listens "Listens to my concerns",
Informs "Keeps me informed about<br/>management decisions"
};
) expand;
);
642
Chapter 1
and display as:

Figure 1-99
Two grids side by side
Question Blocks
Use a question block to define a set of related questions that you want to keep together as a group.
During interviews, all questions in the block are displayed on the same page in the order they
appear in the block. Demographic questions are typically defined as blocks.
To define a question block, place the following statements in the metadata section of the interview
script:
BlockName ["Text"] block fields
(
Questions
);
where:
BlockName is the name of the question block.
Text is the text to display at the top of the block.
Questions are questions defined in the usual way.
643
Base Professional
For example:
AboutYou "" block fields

(
WorkStatus "Do you work ...?" categorical [1]
{
Fulltime "Full time",
Parttime "Part time"
};
Dept "Which department do you work for?" categorical [..1]
{
CustomerService "Customer Services",
Facilities "Facilities",
Finance "Finance",
HumanResources "Human Resources",
IT "IT",
Sales "Sales/Marketing"
};
);
To display the question block, type:
BlockName.Ask()

BlockName is the name of the question block.
So, for example,
AboutYou.Ask()
IOM.GlobalQuestions.Add(ChangeTemplate)
ChangeTemplate.Style.Orientation = Orientations.orRow
ChangeTemplate.Style.Rows = 2
produces the following output:

Figure 1-100
Example output for a question block using default template
644
Chapter 1
Questions in a block are automatically namespaced, which means that their full names include the
name of the block. In the example, the questions are called AboutYou.Age, AboutYou.WorkStatus,
and AboutYou.Dept.
Displaying the Same Questions at the Top of Every Page
Questionnaire scripts can contain global questions that are displayed at the top of every page. In
most cases, these are not ordinary questions that the respondent answers as a matter of course.
Rather, they provide facilities for respondents to interact with the interviewing program in a
certain way at any point during the interview. Typical examples are:
To change the appearance of the page so that it is easier to use, for example, by choosing a
template that provides more contrast between the page background color and the color of the
text, or that uses a larger or smaller text size.
To enter general comments that cannot be entered anywhere else in the interview.
To use global questions, define the questions in the metadata section in the normal way and then,
in the routing section, type:
IOM.GlobalQuestions.Add(QName)
at the point at which you want to start adding the question called QName to each page.
You may sometimes need to write additional code to process the answers to the global
questions. In the case where respondents can choose a different template, you’ll need code that
checks whether the user has chosen a different template and, if so, sets that template to be the
layout template for the rest of the interview. You can place this code in an OnAfterQuestionAsk
event, as shown in the examples that follow.
To remove a global question, type:
IOM.GlobalQuestions.Remove(Position)
where Position is the question’s position in the current list of global questions. For example:
IOM.GlobalQuestions.Remove(0)
to remove the first question in the global question list.

To remove all global questions, type:
IOM.GlobalQuestions.Clear()
Choosing a Different Layout Template
This example shows how to use a global question to allow respondents to change the page layout
template during the course of the interview. The change is made in the OnAfterQuestionAsk
event so it will affect the next page of the interview, not the current one. The global question is
defined as:
ChangeTemplate "Change layout template" categorical [1..1]
{
NoChange "No change",
CardBlue "Blue card",
PeopleWorkingRed "Red image of people working",
RectangleGreen "Green rectangle",
BlueSlide "Blue slide"
} defaultanswer(NoChange);
645
Base Professional
Notice that the question has a “No Change” response that is set as the default, so respondents who
are satisfied with the current template can ignore the question.
The question is defined in the routing section as a global question and the response list is set up
to display in two rows across the page, thus reducing the amount of space it takes up.
IOM.GlobalQuestions.Add(ChangeTemplate)
ChangeTemplate.Style.Orientation = Orientations.orRow
ChangeTemplate.Style.Rows = 2
The response to the global question is checked and any template change is implemented using
an OnAfterQuestionAsk event:
Sub OnAfterQuestionAsk(Question, IOM)
If IOM.Questions["ChangeTemplate"].Response.Value = {CardBlue} Then
End If
If IOM.Questions["ChangeTemplate"].Response.Value = {PeopleWorkingRed} Then
IOM.LayoutTemplate = "People_Working_Red_Layout.htm"
End If
If IOM.Questions["ChangeTemplate"].Response.Value = {RectangleGreen} Then
IOM.LayoutTemplate = "Rectangle_Green.htm"
End If
If IOM.Questions["ChangeTemplate"].Response.Value = {BlueSlide} Then
IOM.LayoutTemplate = "Slide_Blue.htm"
End If
End Sub
Here’s an illustration showing the global question on a typical interview page:

Figure 1-101
Grid with global “Change template” question above it
646
Chapter 1
Gathering General Comments
This example shows how to gather general comments throughout the interview and then forward
them to the project manager at the end of the interview. The metadata section defines the
following questions:
YourComments "General comments" text [..50];

AllComments "" text;
SendComments "You entered some general comments during the interview. Please click
<a href='mailto:bhorton@spss.com?subject=General comments&body={#AllComments}'>here</a>
to review them and send them to the project manager.
<br/>Thank you for your help." info;
YourComments is the global question that respondents see. AllComments will contain a
concatenation of all comments so far, and SendComments is the message that respondents see
at the end of the interview.
The routing section is as follows:
YourComments.MustAnswer = False
IOM.GlobalQuestions.Add(YourComments)
Cares.Ask()
Respect.Ask()
Profits.Ask()
IOM.GlobalQuestions.Remove(0)
SendComments.Show()
IOM.Questions["AllComments"].Response.Value = _
IOM.Questions["AllComments"].Response.Value + _
IOM.Questions["YourComments"].Response.Value
End Sub
This displays pages for Cares, Respect, and Profits, each with YourComments at the top of the
page. The global question is removed before the last page (on which the respondent may review
the comments message) is displayed.
Changing the Order in which Questions are Asked
The interviewing program normally asks questions in a page, block, or compound item in the
order they are defined in the metadata section. You can choose a different order by using
IQuestion.QuestionOrder in the routing section. Type:
Qname.QuestionOrder = OrderConstants.order
where order is one of:

Value Action
oRandomize Display questions in a random order.
oReverse Reverse the display order between respondents; that
is, display Q1 to Qn for respondent 1 then Qn to Q1
for respondent 2, and so on.
oRotate Display questions in rotation so that each question
takes a turn at being first in the display.
647
Base Professional
For example, suppose you have a page that displays three questions about the cleanliness of trains
and stations, and you want to rotate the question order between respondents. Here’s how you’d
do it. In the metadata section, define the questions as normal:
Agreement define {
CompAgree "Agree completely",
PartAgree "Agree somewhat",
NeitherAgree "Neither agree nor disagree",
PartDisagree "Disagree somewhat",
CompDisagree "Disagree completely"
};
Intro "How much do you agree/disagree with the following statements?" info;
ValueMe "The company values my work." categorical[1..1]
{use Agreement};
Targets "I have clear targets/objectives." categorical[1..1]
{use Agreement};
Required "I understand what is required of me." categorical[1..1]
{use Agreement};
RatingPage page(ValueMe, Targets, Required);
Then, in the routing section, type:

RatingPage.Banners.Add("RatingPageBanner", Intro.Label)
RatingPage.QuestionOrder = OrderConstants.oRotate
RatingPage.Ask()
The first interview will display ValueMe, Targets, and Required; the second will display Targets,
Required, and ValueMe; the third will display Required, ValueMe, and Targets, and so on.
Nested Question Groups
Block questions can be nested — that is, a block can contain other blocks. When you define
ordering for a block that contains other blocks, the ordering applies only to the block named on
the ordering statement; it does not apply to blocks nested within that block. If you want to reorder
the questions within a block you must write a separate statement to do this.
Here’s an example. Suppose that you have two sets of questions to ask about train travel. You
want to ask the questions in each set in a random order, but you also want to present the two sets
in rotation. This is where you use block rather than page because it allows you to define the
two sets of questions as components of a parent question, and to specify the order in which
the questions and subquestions are presented.
648
Chapter 1
The questions are defined in the metadata section as follows:

Agreement define {
CompAgree "Agree completely",
PartAgree "Agree somewhat",
NeitherAgree "Neither agree nor disagree",
PartDisagree "Disagree somewhat",
CompDisagree "Disagree completely"
};
Intro "How much do you agree/disagree with the following statements?" info;
RatingBlock "How much do you agree/disagree with the following
statements?" block fields
(
Payment block fields
(
Salary "The company pays good salaries." categorical[1..1]
{use Agreement};
Holidays "I get enough holiday for my needs." categorical[1..1]
{use Agreement};
Benefits "The company provides good benefits." categorical[1..1]
{use Agreement};
);
Training block fields
(
EnoughTrg "I get enough training for my job." categorical[1..1]
{use Agreement};
RightTrg "I get the right training for my job." categorical[1..1]
{use Agreement};
);
);
This shows quite clearly that Payment and Training are both subsets of RatingBlock. You want to
present the questions within these blocks in a random order, and to rotate the blocks themselves,
so the routing instructions are:
RatingBlock.Payment.QuestionOrder = OrderConstants.oRandomize
RatingBlock.Training.QuestionOrder = OrderConstants.oRandomize
RatingBlock.QuestionOrder = OrderConstants.oRotate
RatingBlock.Ask()
This code displays all the questions on one page. If you want to display each question on a
separate page, use RatingBlock[..].Ask() instead.
Ordering when Questions are Re-asked
If questions are re-asked, the interviewing program uses the same ordering each time the questions
are asked. The only time this changes is if the script defines a different order property for the
replay.
Logical Expressions
One of the main things you’ll want to do in the Routing section is check how a respondent has
answered a question. You do this by writing an expression that compares the current response
against a given value or set of values and returns True or False depending on the results of the
comparison. A very simple example is an expression that tests whether the respondent is female.
If the question is called Gender, the expression:
Gender = {Female}
returns True if the answer to Gender to Female and False if it is anything else.
649
Base Professional
Another simple example is a test for age. If Age is a numeric question, the expression:
Age >= 60
returns True for anyone who is aged 60 or older.

The Interview Scripting Language provides a number of keywords and operators for testing
responses, some of which work with all question types and others of which are specific to a
particular type of question. You’ll find information about these operators and keywords in the
following topics, as well as links to other topics describing a variety of less commonly used
functions that you may also find useful.
Expressions need not be limited to using question names and fixed values. You can replace the
question name or the value, or both, with expressions. A simple example is one that subtracts
the respondent’s age from the statutory retirement age (assume it is 65 years old) and then tests
whether the respondent has more than ten years left to work:
(65 - age) > 10
The Interview Scripting Language recognizes the standard arithmetic operators +, −, * (multiply),
and / (divide). Normally you’ll use these operators with numeric questions and numeric values,
but they can also be used in more advanced expressions to manipulate and test categorical or
text questions.
Test numeric responses
Test categorical responses
Test for no answer, don’t know, or refused answers to non-categorical questions
Test text responses
Test date/time responses
Combine expressions
Reverse the meaning of an expression
Checking Numeric Responses
You can use the following operators for testing numeric responses:
= Equal to
<> Unequal to
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
For example:
Age >= 21
is True for anyone aged 21 years or older, while:

Duration > 60
650
Chapter 1
might be True for anyone whose journey to work takes more than 60 minutes.
Checking Categorical Responses
You can use any suitable operator or function in the IBM® SPSS® Data Collection Scripting
language for testing responses to categorical questions. However, the majority of tests can be
carried out using just the operators and functions listed in the following table. For information
about the full range of functions available for categorical responses, refer to and .
= Tests whether the response exactly matches a
specified answer
<> Tests whether the response does not exactly match
a specified answer
< Tests whether the response contains a subset of
specified answers but not all of them
<= Tests whether the response contains one or more
specified answers
> Tests whether the response contains all the specified
answers and at least one other answer
>= Tests whether the response contains all specified
answers, with or without additional answers
AnswerCount Returns the number of responses chosen
ContainsAll Tests whether the response contains all the specified
answers
ContainsAny Tests whether the response contains at least one of
the specified answers
ContainsSome Tests whether the response contains a given number
of the specified answers
The topics in this section explain how to:

Find the number of responses chosen for a question
Check whether the respondent chose all the answers in a given set
Check whether the respondent chose at least one answer from a given set
Check whether the respondent chose a specified number of answers from a given set
Number of Responses Chosen
Some questions may require the respondent to choose a certain number of responses from a list.
The AnswerCount function counts the number of responses chosen, and the following example
shows one way in which it can be used:
DaysVisit.Ask()
If DaysVisit.AnswerCount() < 2 Then
WhyNoMore.Ask()
End If
The DaysVisit question asks respondents which days of the week they visit the gym. Respondents
who choose less than two days are asked the WhyNoMore question to find out why they do not
go more frequently.
651
Base Professional
All the Specified Responses Chosen
There are two ways of testing whether all responses in a set were chosen, as in, did the respondent
choose product A and product B from the response list. You can use the =, >=, or > operators
or the ContainsAll function.
All Specified Responses and No Others

To test whether the respondent chose all the specified responses and no others, type either:
Qname = {Resp1, Resp2, ... Respn}
or:
Qname.ContainsAll({Resp1, Resp2, ... Respn}, true)
where:
Qname is the name of the question whose response you want to check.
Resp1 to Respn are the names of the responses you want to check for. If you are using
ContainsAll, you must name at least two responses.
(With ContainsAll, the true parameter is passed to the function when it is executed, and is the
setting to be applied to the internal boolean variable, exactly. If the variable is True, the function
tests for exactly the listed values and no others; if it is False, the function just tests for the
presence of all the listed values. )
In both cases, the expression is True if the respondent chooses all the specified answers at the
named question and no others. For example, if the question is defined as:
Tried "Which of the test products did you try?"
categorical [1..4]
{
ProductA "Product A",
ProductB "Product B",
ProductC "Product C",
ProductD "Product D"
};
the expressions:
Tried = {ProductA, ProductB}
Tried.ContainsAll({ProductA, ProductB}, true)
are True for all respondents who tried both products and no others. They are False for anyone
who did not try both the named products, and for people who tried products A and B with one
or both of products C or D.
All Specified Responses with or without Others

If you want to test whether the respondent chose all the specified responses with or without
others, type either:
Qname >= {Resp1, Resp2, ... Respn}
or:
Qname.ContainsAll({Resp1, Resp2, ... Respn})
652
Chapter 1
For example:
Tried >= {ProductA, ProductB}
Tried.ContainsAll({ProductA, ProductB})
Both expression are True for respondents choosing products A and B with or without products C
and D. The expressions are False for anyone who does not choose products A and B.
All Specified Responses and At Least One Other

The final possibility to is test whether the respondent chose all the specified responses with at
least one other response. To do this, type either:
Qname > {Resp1, Resp2, ... Respn}
For example:
Tried > {ProductA, ProductB}
This expression is True if the respondent chooses products A and B with at least one of products C
and D — that is, A, B, and C, or A, B, and D, or all four products.
At Least One of the Specified Responses Chosen
There are two ways of testing whether at least one response in a set was chosen, as in, did the
respondent choose at least one weekend day from the response list, or, does the respondent play
tennis, squash, badminton, and/or table tennis, but not all four sports. You can use the < or <=
operators or the ContainsAny function.
At Least One Specified Response and No Others

To test whether the respondent chose at least one of the specified responses and no others,
type either:
Qname <= {Resp1, Resp2, ... Respn}
or:
Qname.ContainsAny({Resp1, Resp2, ... Respn}, true)
where:
Resp1 to Respn are the names of the responses you want to check for.
(With ContainsAny, the true parameter is passed to the function when it is executed, and is the
setting to be applied to the internal boolean variable, exactly. If the variable is True, the function
tests for exactly the listed values and no others; if it is False, the function just tests for the
presence of all the listed values. )
In both cases, the expression is True if the respondent chooses any of the specified answers at
the named question and no others. For example, if the question is defined as:
DaysVisit "On which days do you normally visit the gym?"
categorical [1..7]
{
Monday, Tuesday, Wednesday, Thursday,
Friday, Saturday, Sunday
};
653
Base Professional
the expressions:
DaysVisit <= {Saturday, Sunday}
DaysVisit.ContainsAny({Saturday, Sunday}, true)
are True for all respondents who go to the gym at the weekend only; that is, on Saturday only, on
Sunday only, or on both Saturday and Sunday. The expressions are False for people who go to
the gym on any weekday even if they also go at the weekend.
At Least One Specified Response with or without Others

To test whether the respondent chose any of the specified responses with or without others, type:
Qname.ContainsAny({Resp1, Resp2, ... Respn})
For example, to check whether the respondent visits the gym at the weekend, regardless of any
visits during the week, you might type either of the following:
DaysVisit.ContainsAny({Saturday, Sunday})
This expression is True for respondents choosing Saturday, Sunday, or both, with or without a
weekday. The expression is False for anyone who does not got to the gym at the weekend.
Note: If a question has no answer because it was never asked, ContainsAny returns False. An na
response does not count as none, whether chosen specifically by the respondent or automatically
because MustAnswer is False.
Some But Not All Specified Responses with No Others

You can check whether some but not all of the specified responses are chosen, without any
other responses:
Qname < {Resp1, Resp2, ... Respn}
The expression:
DaysVisit < {Saturday, Sunday, Monday}
is True if the respondent goes to the gym on one or two of the specified days, but not on all
three, and also not on any other days of the week. In other words, it is True for people who go
on Saturday, Sunday, or Monday only, or who go on Saturday and Sunday, or on Saturday and
Monday, or on Sunday and Monday only. The expression is False for anyone who goes to the gym
on Saturday, Sunday, and Monday, or on any other day or days of the week.
Not Just All the Specified Responses
You can also specify a test that returns True if none, or some but not all, of the listed responses are
chosen, with or without other answers. In other words, you want to reject answers that contain the
listed responses and nothing else. To do this, type:
Qname<> {Resp1, Resp2, ... Respn}
For example:
DaysVisit <> {Saturday, Sunday}
654
Chapter 1
is False for anyone who goes to the gym on both Saturday and Sunday and not on any other day. It
is True for everyone else; that is, for people who go only during the week, and for people who go
on Friday and Saturday, and for people who go on Friday, Saturday, and Sunday.
A Given Number of Specified Responses Chosen
To test whether the respondent chose a given number of answers from a set of responses, as in, did
the respondent choose three track and field sports from a selection of sports, use the ContainsSome
function as follows:
ContainsSome({Resp1, Resp2, ... Respn}[, Minimum][, Maximum][, No_Others])
where:
Resp1 to Respn are the names of the responses you want to check for.
Minimum is the minimum number of responses that must be chosen from the set in order for
ContainsSome to be True. If you omit this parameter, the default is zero meaning that none
of the specified responses need be chosen.
Maximum is the maximum number of responses that must be chosen from the set in order for
ContainsSome to be True. If you omit this parameter, the default is the number of responses
specified in the expression.
No_Others is True if the response may contain only answers from the specified set, or False if
other answers may be chosen too. If you omit this parameter, the default is False.
If the Sports question is defined in the Metadata section as:
Sports "Which sports do you take part in?" categorical [1..]
{
Running, Cycling, Football, Javelin, Discus,
HighJump "High jump", LongJump "Long jump",
Swimming, Basketball, Tennis, Hockey, Rugby,
PoleVault "Pole vault", Netball, Gymnastics
};
and you want to test whether the respondent’s answer contains between three and five track and
field events, you would write the following expression:
Sports.ContainsSome({Running,Javelin,Discus, HighJump,LongJump,PoleVault}, 3, 5)
This expression ignores any other sports that may be present in the response to the Sports question,
and has the same effect as:
Sports.ContainsSome({Running,Javelin,Discus,HighJump,LongJump,PoleVault}, 3, 5, false)
If you want to take other sports into account and test whether the respondent mentioned only three,
four, or five track and field events and no other sports, you would write:
Sports.ContainsSome({Running,Javelin,Discus,HighJump,LongJump,PoleVault}, 3, 5, true)
You can leave the minimum and/or maximum number of required responses undefined, and the
interviewing program will use the function’s default settings instead. The default minimum
is one, so the expression:
Sports.ContainsSome({Running,Javelin,Discus,HighJump,LongJump,PoleVault}, , 5)
655
Base Professional
is True if the respondent’s answer contains between one and five of the specified sports. It is
False if all six sports or none are mentioned. The results of the expression are unaffected by
any other sports mentioned.
Similarly, if the expression is:
Sports.ContainsSome({Running,Javelin,Discus,HighJump,LongJump,PoleVault}, 3)
the result is True if the respondent mentions at least three of the specified sports, regardless of
any other sports mentioned.
Checking for Special Responses to Non-Categorical Questions
If a numeric or text response list contains a codes() section that allows the special responses
na, dk and ref you may want to check whether the respondent chose one of these responses
rather than entering a number or text. You use the same expressions for testing these special
responses as you do for testing standard categorical responses, except that the general format of
the test statement is:
Qname.Response.Coded CategoricalTest
where:
Qname is the name of the question.
CategoricalTest is any valid syntax for testing categorical responses.
For example, if Age is defined as:
Age "How old will you be next birthday?" long [18 .. 99]
codes (
{
AgeRef "Would rather not say" ref,
AgeDK "Don't know/Can't remember" dk
}
);
the expression:
Age.Response.Coded = {AgeDK}
tests whether the respondent chose Don’t know.

In this example only one of the coded responses can be chosen, but sometimes this is not the
case. When more than one coded response can be chosen, use an expression such as:
ThisQ.Response.Coded.ContainsAny({ThisOne,ThatOne})
Notice how ContainsAny is appended to the rest of the expression, as it would be for an
ordinary categorical question.
Checking Text Responses
With text questions you can test whether the response matches, or is like, a pattern. The
expression format is:
Qname Like "pattern"
656
Chapter 1
where:
pattern is the text with which the response is to be compared. An underscore in the text
matches any single character, and a percent sign matches any number of characters, including
zero.
For example, a telephone service provider may be about to install a special high-speed internet
access service on a local exchange, and may want to ask respondents whose numbers belong to
that exchange whether they would be interested in using the service. If the Metadata contains a
text question called TelephoneNumber, you could test for respondents in the 01342 area using
the expression:
TelephoneNumber like "01342%"
This expression returns True for all respondents who typed telephone numbers starting with 01342.
The = and <> operators are valid with text responses but are only useful for short responses
where you know what the responses are likely to be.
Checking Date/Time Responses
IBM® SPSS® Data Collection Interviewer Server stores date and time responses as a date and
time string. The way to test dates and times is to extract the date or time component that you want
to test as a numeric value and then write an arithmetic expression to test that value.
There are a number of functions that work with dates and times, but the ones you are most likely
to use are as follows:
Day The day in month (1 to 31)
Month The month in year (1 to 12)
Year The year
Hour The hour (0 to 23)
Minute The number of minutes (0 to 59)
Refer to for information about other date and time manipulation functions.
To test the value returned by these functions, use the following operators:
= Equal to
<> Unequal to
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
In the following examples, assume that the answer to the performance question is 22 December
2004 2:30pm.
657
Base Professional
Day in Month
To test the day part of a date, use the Day function which returns a value in the range 1 to 31. For
example:
Day(performance) < 20
returns False because the date is later than the 20th of the month.
Month in Year
To test the month part of a date, use the Month function which returns a value in the range 1
to 12. For example:
Month(performance) > 6
returns True because the performance date is later than month 6 (June).
Year
To test the year part of a date, use the Year function. For example:
Year(performance) = 2005
returns False because the performance date is during 2004.
Hour in Day
To test the hour part of a date, use the Hour function which returns a value in the range 0 to
23. If the time is entered in 12-hour format, times with a pm tag are converted to their 24-hour
equivalents. For example:
Hour(performance) >= 12
returns True because the performance time is in the afternoon.
Minute in Hour
To test the minute part of a date, use the Minute function which returns a value in the range 0
to 59. For example:
Minute(performance) <> 30
returns False because the performance time shows 30 minutes.

658
Chapter 1
Combining Expressions
You can combine two or more simple expressions to form a more complex expression that tests the
answers to two questions, or performs a more detailed test on the responses to a single question.
The operators that you use for combining expressions are as follows:
And Tests whether both expressions are True
Or Tests whether at least one expression is True
Xor Tests whether one expression or the other is True
Both Expressions True
When your test uses two expressions that must both be True, combine them using the And operator:
Expression1 And Expression2
For example:
Sports.ContainsAny({Swimming, Running}) And DaysVisit.ContainsAll({Saturday, Sunday})
This expression is True when Sport contains one or both of Swimming and Running, and Days
contains both Saturday and Sunday. In other words, it is True for respondents who go swimming,
running, or both on Saturdays and Sundays. It is False for people who swim and/or run but not on
both days, and for people who do neither sport.
At Least One Expression True
To test whether one expression or the other, or both expressions are True, use the Or operator:
Expression1 Or Expression2
This is a particularly useful operator for using with product or brand awareness studies where
you want to test whether a key brand or product was mentioned at one or more of a number of
questions. In the following example, the expression is True if the respondent mentioned Hot and
Spicy sauce at either the Spontaneous or Prompted awareness question:
Spontaneous >= {HotAndSpicy} Or Prompted >= {HotAndSpicy}
In this example it is impossible for respondents to mention the same response at both questions,
but this does not affect the validity of the test. Here is a variation that tests which products the
respondent has seen or heard advertised:
AdvertsSeen >= {HotAndSpicy} Or AdvertsHeard >= {HotAndSpicy}
The expression is True for anyone who saw advertising for Hot and Spicy sauce, for anyone who
heard advertising for Hot and Spicy sauce, and for anyone who saw and heard this advertising. It
is False only for people who did not see or hear advertising for the product.
659
Base Professional
Only One Expression True
The Xor operator combines expressions such that only one of the expressions must be True. If
both expressions are True then the expression as a whole is False:
Expression1 Xor Expression2
The following expression is True for anyone who has either children or pets but not both:
HasChildren = {Yes} Xor HasPets = {Yes}
Combining More Than Two Expressions
When an expression contains more than one operator, the expression is evaluated using the
following order of precedence:
1. Not
2. *, /, Mod
3. +, −, Like
4. =, <>, <, >, <=, >=
5. And, Or, Xor
If the expression contains two or more operators at the same level they are evaluated in the order
they appear in the expression. To impose your own evaluation order, or simply to make it visually
clearer how the expression will be evaluated, use parentheses to group the expressions that are to
be evaluated together. For example:
Gender = {Male} Or Age >= 21 And Age <= 24
By default, this expression is evaluated from left to right, so it behaves as if there were parentheses
around the first two expressions:
(Gender = {Male} Or Age >= 21) And Age <= 24
It is True for anyone aged 21 to 24 and for men who are younger than 24 years of age. In
comparison, the expression:
Gender = {Male} Or (Age >= 21 And Age <= 24)
is True for all men and for anyone who is between 21 and 24 years of age.
Here are some more examples, this time using three different questions:
Without any parentheses, the test:

unaid >= {BrandA} Or aided >= {BrandB} And advert >= {BrandB}
follows the standard rules for precedence; that is, from left to right. The expression as a whole
is True if the respondent:
mentions Brand A at the unaided awareness question and remembers seeing the advertisement
for Brand B, or
660
Chapter 1
is aware of Brand B when prompted and remembers seeing the advertisement for it, or
mentions Brand A at the unaided awareness question, is aware of Brand B when prompted,
and remembers seeing advertising for Brand B
Notice here that respondents must always remember the advertisement if the expression is to be
true.
If you want the And operator to be evaluated first, you must enclose the two expressions
on either side of it in parentheses:
unaid >= {BrandA} Or (aided >= {BrandB} And advert >= {BrandB})
Now the expression as a whole will be true if the respondent:

mentions Brand A unaided, or
is aware of Brand B when prompted and remembers seeing advertising for it, or
belongs in both the previous categories
This example removes the previous requirement for respondents who are aware of Brand A to
have seen Brand B advertised.
Reversing the Meaning of an Expression
The Not operator reverses the meaning of the expression that it precedes. When the expression
starts with a simple question name you should enclose the expression in parentheses to ensure that
the statement is evaluated correctly.
Not(expression)
For example:
Not (Gender = {Male})
means the same as:

Gender <> {Male}
and the expressions:

(Not Tried > {ProductA, ProductB})
Not Tried.ContainsAll({ProductA, ProductB}, false)
are both True if the answer to Tried does not contain Product A, Product B and at least one other
response.
In the second example, notice that the first expression is enclosed in parentheses so that it is
clear that the question name belongs with the product names. This is not necessary in the second
expression because the question name is followed by a function name.
If the expression contains a number of subexpressions linked with And, Or, or Xor, Not refers only
to the first subexpression. To reverse the meaning of more than one subexpression or a group of
subexpressions either place Not in front of each subexpression or group the subexpressions using
parentheses so that Not reverses the meaning of the parenthesized expression as a whole. Which
method you use will depend on the purpose of the test. Take, for example, the expression:
Region = {North} And Age <= 24
661
Base Professional
This is True for people who live in the north and are aged 24 or younger. There are four ways of
using Not in this expression: with Region, with Age, with Region and Age separately, and with
Region and Age grouped inside parentheses. Each possibility generates a different result, so it
is important that you are clear about which respondents you will be accepting and rejecting
before your project goes live.
Not (Region = {North}) And Age <= 24
In this expression only the test for region is reversed. The expression is True for anyone who does
not live in the north and who is younger than 25 years of age, and includes anyone who lives in
the south, east, or west as long as they are of the right age. The expression is False for everyone
who lives in the north regardless of their age, and for anyone aged 25 or older regardless of
where they live.
Region = {North} And Not (Age <= 24)
In this expression only the test for age is reversed. The expression is True for anyone who lives in
the north and who is not aged 24 or younger. It is False for anyone who lives in the south, east, or
west regardless of their age, and for all northerners aged 24 or younger.
Not (Region = {North}) And Not (Age <= 24)
In this expression both tests are reversed separately. The region subexpression is True for anyone
who does not live in the north; the age subexpression is True for anyone who is not aged 24 or
younger. The And operator indicates that both subexpressions must be True, so the expression as a
whole is True for people who do not live in the north and who are not under 25 years of age.
Not (Region = {North} And Age <= 24)
In this variation the two expressions are grouped and the meaning of the combined expression is
reversed. The expression in parentheses is True for people who live in the north and are aged 24
or younger. It is False for people of any age who live in the south, east, or west, as well as for
northerners aged 25 or older. Not switches this round so that the expression is False for people
who live in the north and are aged 24 or younger, and True for people of any age who live in the
south, east, or west, as well as for northerners aged 25 or older.
Here is a table that brings these results together for easy comparison:
Elsewhere aged Elsewhere aged
North aged <=24 North aged >24
<=24 >24
region And age True False False False
Not region And age False True False False
region And Not age False False True False
Not region And
False False False True
Not age
Not (region And
False True True True
age)
Similar rules apply when the operator is Or or Xor, and when the expression contains more than
two subexpressions.
662
Chapter 1
Conditional Actions
Conditional actions are those that may or may not happen during an interview, and are most often
concerned with determining which questions a respondent should answer. For example, you will
only want to ask respondents for opinions of products that they have tried, or will not want to
ask questions about children if the respondent has no children.
Conditional actions are based on the result of comparing a response or the result of a logical
expression against a given value or set of values. The expression states the conditions that must be
satisfied in order for an action to be carried out. If the respondent does not satisfy the requirements
of the expression, then the conditional actions are ignored.
There are two statements associated with conditional actions, both of which may appear in the
routing section of the interview script.
If...Then...Else Execute statements based on the value of a logical
expression
Select Case Execute statements based on the value of a variable
or question
This section explains how to specify conditional actions:

Based on responses to questions that have a single value
Based on the value of any logical expression
Select Case
Select Case is a quick and easy way of defining conditional actions when the conditions are
based on a question that can have only one value; that is a single-response categorical question, a
numeric question, or a boolean question. To use it, type:
Select Case Qname.Response.Value
Case Response1
Actions1
Case Response2
Actions2
...
[Case Else
ActionsN]
End Select
where:
Qname is the name of the question whose response controls the conditional actions.
Response1 and Response2 are responses to the question or, for numeric responses, expressions
such as <value that group responses to the question.
Actions1 and Actions2 are one or more statements to be executed if the question’s response
matches the response for the current Case statement.
ActionsN is one or more statements to be executed for respondents who fail all the previous
Case tests.
663
Base Professional
For example, suppose your interview script contains the following questions:
BestColor "Which color scheme do you think suited

the product best?" categorical [1..1]
{
BluePink "Blue and pink" ,
RedYellow "Red and yellow" ,
YellowGreen "Yellow and green" ,
None "None were suitable"
};
Red "Why do you think red and yellow is effective?" text [1..];
Blue "Why do you think blue and pink is effective?" text [1..];
Green "Why do you think yellow and green is effective?" text [1..];
Having asked the Color question, you want to know why the respondent chose a particular color
scheme. Because the question allows one response only, a Select Case statement makes this easy
(compare this example with the one that uses If and ElseIf in If...Then...Else):
BestColor.Ask()
Select Case BestColor.Response.Value
Case {RedYellow}
Red.Ask()
Case{BluePink}
Blue.Ask()
Case {YellowGreen}
Green.Ask()
End Select
The Select Case statement tells the interviewing program to check which color was chosen. The
Case statements define the possible responses and the actions that are to be taken for each one.
Once a respondent has satisfied a Case test and the actions for that test have been executed, all
other Case tests are ignored and the respondent continues with the next statement after End Select.
Respondents who do not satisfy any of the Case tests simply pass through this section of the
routing script with no actions being taken. In the example, this is what happens for respondents
who say that none of the color schemes was suitable.
Here is an example for a numeric question. Notice how the range 31 to 59 has been specified.
Age.Ask()
Select Case Age
Case < 30
Young.Ask()
Case 30 To 59
Middleaged.Ask()
Case Else
Old.Ask()
End Select
If...Then...Else
If...Then...Else is a very flexible way of defining conditional statements. It can be used with
expressions of any complexity, based on the answers to one or more questions. The simplest
form for an If statement is:
If Expression Then
Actions
End If
664
Chapter 1
where:
Expression is a logical expression whose result determines whether the rest of the If statement
will be executed.
Actions are one or more statements specifying actions to be carried out if Expression is True.
For example, suppose the metadata section defines the following questions:
AllColors "You had three packets of the test product each with
a different color scheme. Which color schemes do you think suited
the product?" categorical [1..]
{
None "None were suitable" exclusive
};
Red "Why do you think red and yellow is effective?" text [1..];
Blue "Why do you think blue and pink is effective?" text [1..];
Green "Why do you think yellow and green is effective?" text [1..];
All respondents should be asked the Color question, followed by the questions related to the
colors that they say are suitable for the product. So, for example, respondents who think that red
and yellow and yellow and green are suitable colors will see the Red and the Green questions,
whereas respondents who say that none of the colors is suitable will see no extra questions at all.
You specify this in the routing section as follows:
AllColors.Ask()
' Respondents mentioning red and yellow packaging with any others
If AllColors.ContainsAny({RedYellow}) Then
Red.Ask()
End If
' Respondents mentioning blue and pink packaging with any others
If AllColors >= {BluePink} Then
Blue.Ask()
End If
' Respondents mentioning yellow and green packaging with any other
If AllColors <= {YellowGreen} Then
Green.Ask()
End If
Note: You’ll notice that each expression uses a different syntax. This is simply to show different
ways of achieving the same end result. If you prefer always to use ContainsAny rather than >= or
<= (when appropriate) then you may do so.
If a respondent fails an If test of this type, he or she simply continues with the next statement
in the routing section. Sometimes, though, you’ll want to specify some other action for these
respondents. In these cases, you need to include an Else section with the If:
If Expression Then
Actions1
Else
Actions2
End If
In this form of the statement:

Expression is a logical expression whose result determines which part of the If statement
will be executed.
Actions1 are one or more statements specifying actions to be carried out if Expression is True.
Actions2 are one or more statements specifying actions to be carried out if Expression is False.
665
Base Professional
In the following example, anyone who mentions red and yellow packaging at the Color question
is asked why they think it is a good color for the product. Anyone who does not mention it is
asked why they did not choose it:
If AllColors.ContainsAny({RedYellow}) Then
WhyRYGood.Ask()
Else
WhyNotRY.Ask()
End If
Not all conditional actions are based on simple either–or tests; many will consist of a number of
tests each for different responses. In this situation, you extend the basic If...Then..Else statement to
include ElseIf clauses:
If Expression1 Then
Actions1
ElseIf Expression2 Then
Actions2
[ElseIf ...
...]
Else
ActionsN
End If
You may write as many Else...If clauses as you need. Each respondent passes through the
whole If...End If group of statements from top to bottom until one of the expressions returns
True. At this point the actions for that expression take place and then the respondent continues
with the statement immediately after End If. It is therefore important that the expressions are
mutually exclusive — that is to say, only one expression must be True for each respondent. If the
expressions are not mutually exclusive and a respondent can pass more than one test, the actions
for the first test will be always carried out, and the second test will never be reached.
Here is a variation of the first example that combines the three separate If statements into a
single group. The question has been changed from multiple choice to single choice to ensure that
each respondent satisfies one expression only. The Color question is now:
BestColor "Which color scheme do you think suited

the product best?" categorical [1..1]
{
None "None were suitable"
};
The If statement that asks the color-specific questions can be written as follows:
If BestColor={RedYellow} Then
Red.Ask()
ElseIf BestColor = {BluePink} Then
Blue.Ask()
ElseIf BestColor = {YellowGreen} Then
Green.Ask()
End If
Respondents who think that none of the color schemes is suitable fail all three tests and do not
see any additional questions.
Note: Test of this type can be specified with less typing if you use a Select Case statement.
666
Chapter 1
If clauses may contain other If clauses. This is called nesting. What this means in practise is that
you can accumulate characteristics on an incremental basis, each time reducing the number of
respondents eligible to answer the next question. In the following example, we want to ask
different questions depending on whether or not the respondent usually travels to work by train.
We also want to ask this group of respondents different questions according to their general
opinion of the train service. The questions are defined in the metadata section as follows. They are
listed in the order they are used in the routing section, but this is not a requirement.
Commuter "Are you a daily commuter?" categorical [1..1]
{
Yes, No
};
Transport "How do you usually complete the majority of your journey"
categorical [1..1]
{
Train, Bus, Car, OtherTransport "Other"
};
Ticket "What type of ticket do you buy?" categorical [1..1]
{
Single, Return, Daily "Daily Travelcard",
Weekly "Weekly Season", Monthly "Monthly Season",
Annual "Annual Season",
OtherTicket "Other" other
};
Service "What is your general opinion of the service offered for commuters?"
categorical [1..1]
{
Excellent, VeryGood "Very Good", Satisfactory,
Bad, Appalling
};
WhyBad "Why do you say that?" text [1..100];
Improve "Even though you are generally satisfied with the service offered for
commuters, is there anything about it that you think could be improved?" text [1..100];
EverUseTrain "Do you ever use the train to travel to work?" categorical [1..1]
{
Yes, No
};
The routing statements that implement the questionnaire logic are as follows. The comments
explain who sees each question, and the indentation highlights the relationship between the
various sections of the code.
Commuter.Ask()
If Commuter = {Yes} Then
Transport.Ask()
' Respondents who travel to work by train ....
If Commuter = {Yes} And Transport = {Train} Then
Ticket.Ask()
Service.Ask()
' ... and who think that the service is bad or appalling
If Service={Bad} Or Service={Appalling} Then
WhyBad.Ask()
' ... or who think that the service is generally good

Else
Improve.Ask()
End If
' Respondents who do not normally travel to work by train
Else
EverUseTrain.Ask()
End If
End If
To illustrate how this example works, suppose we have three people:

Person A commutes daily by train and thinks the service is bad. Person A is asked Ticket,
Service, and WhyBad.
667
Base Professional
Person B commutes daily by train and thinks the service is very good. Person B is asked
ticket, Service, and Improve.
Person C commutes but does not use the train. Person C is asked EverUseTrain.
When you write nested loops of this type, you will need to be very careful that you structure the If
and Else clauses correctly; otherwise, your script may not do exactly what you expect. Indenting
all the statements in each clause by the same amount helps you here. In particular, make sure that
each If has an End If. However, if you find that the logic is becoming difficult to follow, try
breaking the block into a number of separate, unnested blocks, and see whether that makes the
script easier to work with.
Repetitive Actions in the Routing Section
This section explains how to define repetitive actions in the routing section, and is primarily
concerned with actions other than asking repeated questions. Repeated questions are a special
type of repetition that is partially controlled by the way the questions are defined in the metadata
section, and although this section contains a short topic about repeated questions, the bulk of the
information is provided in Repeated questions.
This section covers the following topics and introduces the following keywords:
Do...Until Repeat statements until a condition becomes True
Do...While Repeat statements all the time a condition is True
For...Next Repeat statements a specified number of times
For Each...Next Repeat statements for each element in an array or
collection
While...End While Repeat statements all the time a condition is True
With Execute a series of statements on a single object
This section also explains how to repeat a statement or an assignment for each object in a
collection — for example, how to refer to the individual repetitions of a loop or grid questions, or
how to refer to all the answers given to an earlier question. The general term for this is object
collection iteration.
Repeating Questions
There are two ways of repeating questions. One method saves the data separately for each
repetition as if each repetition were a completely separate question, while the other simply
redisplays the same question and overwrites any existing data with whatever answer the
respondent gives for the current repetition. In order for your script to function as you intend and
to save all the data you expect to collect, you must be careful that you define and ask repeated
questions in the appropriate way.
More often than not, you will want to treat each repetition of a question as if it were a separate
question, and to save data for all repetitions. To do this, you must define the question as a loop or
grid in the metadata section. This generates separate columns in the case data for each repetition,
even if not all respondents answer all repetitions. For more information, see the topic Repeated
questions on p. 615.
668
Chapter 1
If you do not define a question as a loop or grid, only one column or set of columns is allocated
to the question in the case data. If you ask the question more than once, each repetition is treated
as a re-presentation of a previously asked question, so the question will be displayed with its
previous response shown, just as if the respondent had used the Previous button to return to the
question. If the respondent replaces the displayed answer with a new answer, the new answer
overwrites the existing answer in the case data.
This second approach is not wrong if you really want respondents to see their existing answers
and to be able to change them in this way. You might do this if you have some key questions that
you want to verify before closing the interview. It is also not wrong if, as shown in some of the
examples in other topics in this section, you are redisplaying the question because the respondent
has made some sort of error.
To display repeated (loop) questions on separate pages during interviews, you type:
LoopName[..].Ask
[..] is a special notation that means “iterate over all the objects in the named collection”. For more
information, see the topic Asking repeated questions on p. 623.
[..] can be used with any object in the Interview Object Model to repeat an action for every
element in that object. For more information, see the topic Object Collection Iteration on p. 668.
To present the same question more than once, either type:
Qname.Ask
at the points you want the question to appear (for example, if it appears in different sections of the
script and different groups of respondents answer different sections), or make it part of a repetitive
statement as shown, for example in Repeat While or Until a Condition is True.
Object Collection Iteration
To repeat an action such as an assignment for all elements in an object, include the notation:
Object[..]
at the appropriate place in the statement.

Here are some examples.
UsageLoop[..].TimesUsed.Response.Default = 0
This sets the default response for every repetition of the TimesUsed question in UsageLoop.
FavoritePicture.Categories[..].Style.Control.Type = ControlTypes.ctButton
This statement is related to a question (FavoritePicture) whose responses are images rather than
texts, and sets up the question so that the respondent clicks on an image to select it as the answer
to the question. The object reference is hierarchical, and refers to the control type for the style
of every category within the FavoritePicture question object.
You can restrict the items within an object that a statement refers to as follows:
Object[.. In Object2]
669
Base Professional
A typical example is when you want to ask questions in a loop only for responses mentioned at a
previous question. To ask respondents to rate each product that they tried, you could type:
ProductsTried.Ask()
RatingLoop.Categories.Filter = ProductsTried
RatingLoop[.. In ProductsTried].Ask()
For more information, see the topic Asking repeated questions on p. 623.
Repeat While or Until a Condition is True
The Do...Loop statement lets you repeat a number of statements either all the time that an expression
returns True or until an expression returns True. There are several ways you can write these loops.
While an Expression is True
To write a loop that is repeated all the time that an expression returns True, type either:
Do While Expression
Statements
Loop
or:
Do
Statements
Loop While Expression
In both cases:
Expression is a logical expression that controls whether the statements in the loop will be
repeated.
Statements are the statements to be executed.
You can nest Do loops to any number of levels.
The difference between the two loop formats is this. If you place the expression at the start of
the loop and it returns False, the statements inside the loop will never be executed. If you place
the expression at the end of the loop, the statements inside the loop will always be executed at
least once, because the expression is not tested until the end of the first pass through the loop.
Here is an example that illustrates how you can use Do...Loop to ask a question and repeat it if
the answer is not correct. The questions in the metadata section are:
HoursTV "How many hours, to the nearest quarter hour, did you spend
watching TV last week?" double [0 .. 168];
Programs "How much of that time was spent watching ..." loop
{
Films,
News "News programs",
Documentaries,
Sitcoms "Situation comedies",
Otherprogs "Other programs"
} fields
(
ProgTime "" double [0..168];
) expand grid;
NoMatch "The sum of the times you have just entered is {Total} but the
total time you gave earlier is {HoursTV}. Please check those figures."
info;
670
Chapter 1
The routing section needs to do three things:
1. Ask the question.
2. Check that the sum of program times matches the total time.
3. If the sum of times does not match the total time, issue an error message and repeat the question.
The loop that you write is as follows:
HoursTV.Ask()
Dim Total, Prog
Do
Total=0.0
Programs.Ask()
' Add up the individual program times
For Each Prog in Programs
Total = Total + Prog.Item["ProgTime"]
Next
' Compare sum of program times with original total time
If Total <> HoursTV Then
NoMatch.Label.Inserts["Total"] = Total
NoMatch.Label.Inserts["HoursTV"] = HoursTV
NoMatch.Show()
End If
Loop While (Total <> HoursTV)
Besides showing how to write a Do While loop, this example is also interesting because it includes
a For Each loop and an If block and shows how these statements can be combined to perform a
common scripting task for numeric questions.
Until an Expression becomes True
Repeating actions until an expression returns True is the opposite of Do While, but its syntax is
identical except for the replacement of While with Until. As with Do While, there are two variants:
Do Until Expression
Statements
Loop
or:
Do
Statements
[Exit Do]
More statements
Loop Until Expression
In both cases:
repeated.
If you want to execute the statements in the loop at least once, place the expression at the end of
the loop. Here is the earlier example rewritten to use Until. Notice that it identical apart from the
last line, where Until replaces While and the operator in the expression changes from <> to =.
671
Base Professional
HoursTV.Ask()
Dim Total1, Prog1
Do
Total1=0.0
Programs.Ask()
For Each Prog1 in Programs
Total1 = Total1 + Prog1.Item["ProgTime"]
Next
If Total1 <> HoursTV Then
NoMatch.Label.Inserts["Total"] = Total1
NoMatch.Show()
End If
Loop Until (Total1 = HoursTV)
You can also write both these examples using While or For...Next . See Repeat While a Condition
is True and A Set Number of Repetitions for details.
Jumping Out of a Do Loop

If you need to jump out of a loop before it has finished executing, insert anExit Do statement at
the point you want to leave the loop. When the interviewing program reaches this statement, it
skips out of the loop to the statement immediately after Loop.
Repeat While a Condition is True
The While...End While block is an alternative to Do...While for repeating a set of statements all the
time that an expression is True. To use it, type:
While Expression
Statements
End While
where:
repeated.
Here is an example that illustrates how you can use While to ask a question and repeat it if the
answer is not correct. The questions in the metadata section are:
{
Films,
Documentaries,
} fields
(
) expand grid;
info;
The routing section needs to do three things:

1. Ask the question.
672
Chapter 1
2. Check that the sum of program times matches the total time.
3. If the sum of times does not match the total time, issue an error message and repeat the question.
The loop that you write is as follows:
HoursTV.Ask()
Dim Total2, Prog2
Total2=0.0
While (Total2 <> HoursTV)
Programs.Ask()
Next
If Total2 <> HoursTV Then
NoMatch.Show()
End If
End While
You can also write this example using Do or For...Next. See Repeat While or Until a Condition is
True and A Set Number of Repetitions for details.
A Set Number of Repetitions
If you want to repeat a set of statements a fixed number of times you can place them inside a
For...Next loop:
Dim Variable
For Variable = Start To Finish
Statements
Next
where:
Variable is a temporary variable that counts the number of repetitions, and points to each
value in the range Start to Finish in turn.
Start and Finish define a range that determines the number of times the statements are to be
repeated.
Statements are the statements to be repeated.
A simple example of a For...Next loop is one that repeats a question a set number of times if the
respondent has not answered the question correctly. Here is an example. The questions in the
metadata section are:
{
Films,
Documentaries,
} fields
(
) expand grid;
info;
673
Base Professional
We want to check that the sum of the times entered at the Programs question equals the total time
entered at HoursTV. If the two values do not match, we want to ask the respondent to check his/her
answers and correct them where necessary. We will allow three attempts at getting a correct
answer, after which we will set the response to HoursTV to match the sum of the individual times.
HoursTV.Ask()
Dim Total3, Prog3, i
For i = 1 to 3
Total3=0.0
Programs.Ask()
Next
If Total3 = HoursTV Then
Exit For
End If
If Total3 <> HoursTV And i < 3 Then
NoMatch.Show()
Else
HoursTV = Total3
End If
Next
Notice how the script uses Exit For to skip out of the loop as soon as the sum of times matches the
total. This takes the respondent to the statement immediately after the Next line. If you wanted to
jump to some other location in the routing section, you could use a Goto statement here instead.
When the sum of times does not match the total and the questions have not been asked three
times, the script displays an explanatory message and returns to the top of the loop to display the
Programs question again. If these times are correct and it is the total that is wrong, the respondent
can use the Previous button to return to the HoursTV question and change the answer. Having
done this, the respondent then passes through the loop again so that the sum of times can be
compared against the new total.
If the respondent is unable to enter a valid set of responses after three attempts, the loop
overwrites the respondent’s answer to HoursTV with the sum of the times entered at Programs.
For variations on this scenario that use Do and While loops, refer to Repeat While or Until a
Condition is True and Repeat While a Condition is True
Jumping Out of a For Loop

If you need to jump out of a loop before it has finished executing, insert anExit For statement at
skips out of the loop to the statement immediately after Next. The example earlier in this section
shows how this works.
Repeat for Each Element of an Array or Collection
When you want to define actions that apply to all the elements in an array or to all the items in a
collection, you place them in a For Each loop:
Dim Variable
For Each Variable In Collection
Statements
Next
674
Chapter 1
where:
Variable is a temporary variable that will point to each element in the collection in turn.
Collection is the name of the element collection to which the statements in the loop should
be applied.
Statements are the statements to be applied to each element in the collection.
As an example, suppose you are working on a general community survey for a local district
council. The council is interested in gaining as much information as possible about as many
aspects of local life as possible, but does not want to put people off by having interviews take
too long. It has been agreed that the questionnaire will be broken down into sections on various
topics such as health, leisure, business, transport, and so on, and respondents will be invited to
answer questions in up to three sections of their choice (or you could write the script so that
three sections are chosen at random).
The metadata section of the interview script defines all the questions that can be asked. The
routing section groups them into sections and displays the questions in the sections that the
respondent has chosen. All respondents end the interview by answering some demographic
questions. Here is an outline of the routing section.
WhichSections.Ask()
Dim Chosen
For Each Chosen In WhichSections
Select Case Chosen
Case {Health}
...
Case {Leisure}
...
Case {Business}
...
Case ...
...
End Select
Next
DemographicsPage.Ask()
Jumping Out of a For Loop

If you need to jump out of a loop before it has finished executing, insert anExit For statement at
skips out of the loop to the statement immediately after Next. The example earlier in this section
shows how this works.
Executing a Series of Statements on a Single Question
If you have a series of statements that all apply to one question, you may find that using a
With...End With block helps you reduce the amount of repetition in the code and makes the code
easier to read. This is certainly the case when you are defining the appearance of a question by
setting style properties, where each property starts with the words Qname.Style. For example, if
675
Base Professional
you want to specify the font, color and effect for the Unaided awareness question, as well as the
orientation and number of rows for the response list, you can type:
HoursTV.Label.Style.Color = "Blue"
HoursTV.Style.Font.Effects = FontEffects.feBold + FontEffects.feItalic
HoursTV.Style.Font.Family = "Arial"
HoursTV.Style.Orientation = Orientations.orRow
HoursTV.Style.Rows = 3
HoursTV.Ask()
Defining these requirements using With...End With means that you type the repeated words once
only and the interviewing program automatically applies them to all the statements in the block.
The syntax for an With...End With block is:
With Qname
Statements
End With
where:
Qname is the question (or other interview scripting object) that the statements in the block
apply to.
Statements are the statements that are to executed for the named question or object.
So, to specify the requirements for the Unaided question, you could type:
With HoursTV
.Label.Style.Color = "Blue"
.Style.Font.Effects = FontEffects.feBold + FontEffects.feItalic
.Style.Font.Family = "Arial"
.Style.Orientation = Orientations.orRow
.Style.Rows = 3
.Ask()
End With
Even though this reduces the amount of repetition, there are still further improvements that can be
made. The With statement can name any object in the Interview Object Model, not just questions,
so another change you can make is to have the With statement refer to the Style object for the
Unaided question, and then move the Ask and Label.Style statements outside the block:
With HoursTV.Style
.Font.Effects = FontEffects.feBold + FontEffects.feItalic
.Font.Family = "Arial"
.Orientation = Orientations.orRow
.Rows = 3
End With
HoursTV.Label.Style.Color = "Blue"
HoursTV.Ask()
Other Flow Control Statements
Besides facilities for defining repetitive and conditional actions, the Interview Scripting Language
also has a number of other keywords that define the structure of the routing section and control the
order in which things happen during the interview. These keywords are as follows:
exit Terminate the interview immediately
goto Jump to a named location
676
Chapter 1
Jumping to a Named Location in the Routing Script
In long or complicated routing sections it can be helpful to organize the code into named
sections. Named sections can be a useful alternative to long If...Then...Else statements with
complex expressions, because you can simply place all the statements that apply to one group
of respondents in a named section and then jump direct to the sections that apply to the current
respondent. Although the effect on the interview is the same, you may find that using named
sections makes the script easier to follow because each section stands alone rather than being
part of a larger statement.
To name a section in the routing section, type the name on a line by itself and follow the
name with a colon:
SectionName:
On the next lines, type the statements that belong in that section (you may wish to indent these
statements to highlight the fact that they are part of a section. The section extends until the next
section name is reached, or until the end of the routing section. For example:
Terminate:
IOM.Banners.Remove("IntroBanner")
TerminateText.Show()
Exit
The GoTo keyword jumps to a named location in the routing section of an interview script.
You’ll often use it when you want to skip a question or set of questions that do not apply to the
current respondent.
To specify a jump (or skip), type:
GoTo location
where:
location is a location name in the script.
You can use GoTo as a statement by itself, in which case it applies to every interview that reaches
the GoTo statement, but you’re more likely to use it as part of an If statement when you want to
ask some questions of certain respondents only. Respondents who should not see the questions
will be sent past them with a GoTo statement. For example:
If (RailwayWorker = {Yes}) Then GoTo Terminate
sends people who are railway workers straight to the end of the script because they are not
eligible to be interviewed.
Normally, you’ll be jumping forwards in the script, but backward jumps are also permitted.
However, if you jump backwards in the script, make certain that you are not creating an infinite
loop, where you are continually repeating the same set of statements. The interviewing program
has a mechanism for dealing with infinite loops, but it is better to avoid creating them in the
first place.
677
Base Professional
Terminating the Interview
You can terminate an interview at any time by placing an Exit statement in the routing section of
the script. If the project uses Sample Management, this causes the sample record to be returned to
the Sample Management system for processing, as normally happens when an interview ends
because the end of the script has been reached.
Ending an interview with Exit can be somewhat abrupt if you do not display an explanation
of why the interview is being terminated. Here is an example that displays a brief closing
message before terminating the interview when respondents do not satisfy the screening criteria.
Respondents who pass the screening criteria continue with the main part of the interview. The
metadata section defining the screening questions is as follows:
Intro "Hello, I'm calling from The Train Company. I wonder if you
can spare some time to answer a few questions about train travel." info;
TerminateText "Thank you for your help, but your household does not meet
the requirements for this survey." info;
Callback "INTERVIEWER: Arrange an appointment to call back and speak to

this person." info;
RailwayWorker "Do you work on the railways?

Is anyone in your immediate family associated with this field?"
categorical [1..1]
{
Yes, No
} NoCaseData;
UsesTrain "Do you travel regularly by train / may I speak with someone
who regularly travels by train?" categorical [1..1]
{
RegularTraveler "Respondent travels regularly by train",
NoTrainTraveler "No one travels regularly by train",
TrainUserNA "Regular train traveler not available"
} NoCaseData;
LastTwoWeeks " Have you traveled by train during the last two weeks?"
categorical [1..1]
{
Yes, No
} NoCaseData;
JourneyReason "What was the main reason for your journey?"
categorical [1..1]
{Business, Pleasure};
Notice how the screening questions have been flagged with NoCaseData because the data is of
no use to the survey.
678
Chapter 1
The routing section that filters out unsuitable respondents is as follows:

IOM.Banners.Add("IntroBanner",Intro.Label)
RailwayWorker.Ask()
If (RailwayWorker = {Yes}) Then GoTo Terminate
UsesTrain.Ask()
If (UsesTrain = {TrainUserNA}) Then GoTo Callback
If (UsesTrain = {NoTrainTraveler}) Then GoTo Terminate
LastTwoWeeks.Ask()
If (LastTwoWeeks = {No}) Then GoTo Terminate
' Questions for train travellers

JourneyReason.Ask()
Exit
Callback:
Callback.Show()
Exit
Terminate:
TerminateText.Show()
Exit
This script deals with three types of respondent.

Those who work for the railway or who have close relatives that work for the railway are
ineligible for the survey so their interview is terminated straight away.
Having established that the household is suitable, the script then guides the interviewer to
finding a suitable respondent within the household. Although the script does not specifically
do this, the implication is that if the first respondent is not a regular train traveler, the
interviewer will automatically ask to speak to someone who is. Once all possibilities have
been exhausted, the interviewer enters an answer to UsesTrain.
If there is no one at all who travels by train, the interview is terminated. If there is a regular
train traveler but this person is not available, the interviewer is asked to make an appointment.
The interviewer does this by selecting the appropriate option from the call results menu.
There is no need for the script to terminate the interview because this happens automatically
when the interviewer makes the appointment.
If the respondent travels regularly by train but has not done so within the last two weeks, the
interview is also terminated. After this, only people who travel regularly by train and who
have done so in the two weeks are left to start the main part of the interview.
Filtering Questions and Response Lists
Filtering is a means of programmatically restricting the questions and responses presented to

respondents. It is an efficient alternative to using complicated If statements or writing multiple
variations of a question with different response combinations. With filtering you can:
ask a subset of questions from a block, compound, or page
omit responses from categorical response lists
use only responses chosen at a previous question
use responses not chosen at a previous question
use responses chosen from a combination of previous questions
679
Base Professional
flag responses that should never be filtered out

ask a subset of questions from a loop
repeat a categorical loop for certain categories only
reduce the number of times a numeric loop is repeated
ask random questions from a loop or make random selections from a loop control list
hide cells in a grid
cancel a filter
Note: Filtering affects the items that are passed to the interviewing program — usually for
presentation to respondents. It does not affect the items that are available for use in the script that
controls the interview. All items are available, just as they are in scripts with no filtering, and can
always be accessed in the script by name. In other words, if the script defines a response list as
containing responses A to , and an interview is filtered so that only A to C are displayed, responses
D to G can still be referenced by name and used in the script even though the respondent may
never see them.
Asking a Subset of Questions from a Block, Compound, or Page
Pages, blocks, and compounds are all convenient and efficient ways of defining groups of related
questions that need to be kept together in some way. The thing that they have in common is that
the interviewing program sees each block, compound, or page as a single entity and expects to
display all the questions in the group. This need not prevent you using these items if you do not
always want to ask all questions in the group, as filtering gives you complete control over which
questions are presented to each respondent.
For example, suppose you have a block of demographic questions about the respondent’s
family. It contains questions about children, but you already know from a previous question
that the respondent has no children. Rather than defining two versions of the block, or placing
the child-related questions outside the block, you can define the block in the normal way and
then specify in the routing section that the child-related questions should be suppressed if the
respondent does not have children.
You specify this sort of filtering in the routing section by typing:
Name.QuestionFilter = "SubQname1, ..., SubQnameN"
where:
Name is the name of the block, compound, or page.
SubQname1 to SubQnameN are the names of the subquestions you want to display.
680
Chapter 1
Here’s how to use it to set up the example. The block is defined in the metadata section as:
Demographics "Demographic Questions" block fields
(
{
Male,
Female,
NoAnswer "No answer" na
};
MaritalStatus "What is your marital status?" categorical [1..1]
{
Single,
Couple "Married/Living with partner",
Separated,
Divorced,
Widowed,
NoAnswer "No answer" na
};
NumberChildren "How many children are there in your household?"
long [0..9];
ChildAge "How old are those children?" categorical [1..]
{
Baby "Under 18 months",
Preschool "19 months to 5 years",
Child "5-12 years",
Teen "12-18 years",
Adult "18 years or older"
};
);
An earlier question called HasChildren (not shown here) tells you whether the respondent has
children. To suppress the questions in the block about children, you place the following statements
in the routing section:
If (HasChildren <> {Yes}) Then
Demographics.QuestionFilter = "Gender, Age, MaritalStatus"
End If
Demographics.Ask()
Filtering Categorical Response Lists
To filter categorical response lists type:

Name.Categories.Filter = Category_Spec

Name is the name of the question whose response list is being filtered.
Category_Spec names the categories to be displayed. This may be the name of a single
category or a comma-separated list of category names, both enclosed in curly braces.
Alternatively, you can specify a range of categories using the , with the category specification
enclosed in double quotation marks.
For example, suppose the metadata contains:
IceCream "Which brands of ice cream can you name?"
categorical [1..]
{
Alpine, Finborough, Alsace,
DairyFresh "Dairy Fresh",
CountryFayre "Country Fayre",
KentishFarm "Kentish Farm"
};
681
Base Professional
You can reduce the response list so that it contains only Alpine, Alsace, Dairy Fresh, and Kentish
Farm brands by placing the following statement in the routing section before you ask the question:
IceCream.Categories.Filter = {Alpine, Alsace, DairyFresh, KentishFarm}
If the categories to be used as filters are defined consecutively, you can save yourself work by
using the double-dot range operator. For example:
IceCream.Categories.Filter = "Alpine..CountryFayre"
to include all brands between Alpine and Country Fayre inclusive (that is, all except Kentish
Farm). An alternative way of writing this particular example is to use the Not (^) operator
as follows:
IceCream.Categories.Filter = "^KentishFarm"
Note: The example has been written to illustrate the use of filters. In a proper script you might find
it easier to create separate shared lists for hot and cold drinks and to use the appropriate list at each
question as this makes filtering unnecessary.
Using Category Numbers instead of Names
Although the usual method is to filter using response names, you can filter using category numbers
if you wish, as long as the responses are not being reordered in some way during the interview.
Note: Responses in a list are numbered according to their position in the list, with the first
response being zero. Therefore, responses A to E would be numbered A=0 to E=4. If you sort the
list in reverse order, E becomes response 0 and A becomes response 4.
To filter using category numbers, define a function called, say, AddFilterByIndex in the routing
section and then call the function with the question name and the category numbers to be included
in the response list for the named question. Define the function as follows:
Function AddFilterByIndex(Question, Indexes)
Dim Filter, Index
Filter = {}
For Each Index in Indexes
Filter = Filter + Question.Categories[Index].Value
Next
Question.Categories.Filter = Filter
End Function
To use the function, type:

AddFilterByIndex(Qname, {Categories})
where:
Qname is the name of the question you want to filter.
Categories is a comma-separated list of the response numbers you want to include in the
response list for Qname. The first response in the list is category 0.
For example:
AddFilterByIndex(IceCream, {0,3})
You might find this method useful if you need to exclude certain brands or products from a list
because they are not available in certain countries.
682
Chapter 1
SubLists
When a response list has sublists, you can base filters on the sublists or on the items within the
sublists. Here are some examples using the following metadata:
BrandList define
{
CountryFayre "Country Fayre"
};
OrganicBrandList define
{
NaturesWay "Nature's Way Organic",
SimpleOrganix "Simple Organix"
};
OrganicIceCream "Which brands are organic?" categorical [1..]
{
use BrandList sublist,
use OrganicBrandList sublist
} asc;
The filter:
OrganicIceCream.Categories.Filter = {Alsace, DairyFresh, NaturesWay}
returns just the named responses, so there will be only one organic brand in the response list
shown to respondents.
The filter:
OrganicIceCream.Categories.Filter = {Finborough, OrganicBrandList}
returns all the brands in the OrganicBrandList sublist plus the one named brand from the other
sublist. Respondents can therefore choose from Helen Bradley’s, Kentish Farm, Nature’s Way
Organic, Simple Organix, and Finborough.
If the filter is defined as:

OrganicIceCream.Categories.Filter = {Alsace, Alpine, KentishFarm}
then the reference:

OrganicIceCream.Categories.Filter = OrganicIceCream.Categories.OrganicBrandList
returns just Kentish Farm, while:

OrganicIceCream.Categories.Filter = OrganicIceCream.Categories.BrandList
returns Alsace and Alpine.
Common Filter Requirements for Categorical Lists
There are some types of categorical filter that most scriptwriters need to use at some time or
another. If you’re unsure how to specify these filters, click a link below for more details.
Response Lists of Answers Chosen at a Previous Question
Response Lists of Answers Not Chosen at a Previous Question

683
Base Professional
Response Lists that Combine Answers to Previous Questions
Response Lists of Answers Chosen at a Previous Question
You can create response lists that show only answers chosen at a previous question. This is
common in brand or product studies where you ask respondents which brands or products they
can name and then you want to ask which of those brands or products they use. If you restrict the
response list to only the brands or products known, you automatically ensure that there will be no
brands or products that are used but not known. This cuts down on the amount of data cleaning
work required before the survey results can be analyzed.
When you want to apply this sort of filtering, the first step is to define the two questions in
the metadata section with the same response list. A shared list is the easiest way to do this,
but you can type the full response lists separately if you prefer. Then, in the routing section,
before you ask the second question, filter its response list so that only the answers chosen at the
first question are displayed. Type:
Name.Categories.Filter = PrevQname
where:
Name is the name of the question whose response list is being set up.
PrevQname is the name of the question whose answers will appear in that response list. (This
is a shorthand way of writing PrevQname.Response.Value, which the interviewing program
converts to {answers to PrevQname}.)
Here’s an example. The metadata section is:
BrandList define
{
};
{
};
Unaided "Which brands of yogurt can you name?" categorical [1..]
{
use BrandList,
use OrganicBrandList,
OtherUnaided "Other" Other fix,
NoneUnaided "None" excl fix
} asc;
Buy "And of those brands, which ones do you buy?" categorical [1..]
{
use BrandList,
BuyNone "None of them" excl fix
} asc;
The routing section is:

Unaided.Ask()
Buy.Categories.Filter = Unaided.Response.Value
Buy.Ask()
684
Chapter 1
Response Lists of Answers Not Chosen at a Previous Question
You can create response lists that show answers that were not chosen at a previous question.
This is common in brand awareness studies where you have a pair of questions that are used
together to find out which brands the respondent can name. The first question is unprompted and
asks the respondent to say which brands he/she knows; the second question asks the respondent
specifically about any brands not named at the unprompted question.
When you want to apply this sort of filtering, the first step is to define the two questions in the
metadata section with the same response list. A shared list is the easiest way to do this but you can
type each response list out in full if you prefer. Then, in the routing section, before you ask the
second question, filter its response list so that only the responses that were not mentioned at the
first question are displayed. Type:
Name.Categories.Filter = Name.DefinedCategories() − PrevQname
where:
Name is the name of the question whose response list is being set up.
PrevQname is the name of the question whose answers will be excluded from the response
list for Name.
Here’s an example. The metadata section is:

BrandList define
{
};
{
};
Unaided "Which brands of yogurt can you name?" categorical [1..]
{
use BrandList,
OtherUnaided "Other" Other fix,
NoneUnaided "None" excl fix
} asc;
Aided "Which of the following names do you recognize as yogurt
producers?" categorical [0..]
{
use BrandList,
use OrganicBrandList
} asc;

Unaided.Ask()
Aided.Categories.Filter = Aided.DefinedCategories() - Unaided.Response.Value
Aided.Ask()
There are two points to notice in this example. First, Unaided has some additional responses
defined in its response list. These apply to that question only and do not carry through to the
filtering for Aided, because the response list for Aided is based solely on the BrandList and
OrganicBrandList shared list. Second, the response range for Aided is specified as [0..] to
685
Base Professional
cater for respondents who do not recognize any brands other than those that they have already
mentioned at the previous question.
Response Lists that Combine Answers to Previous Questions
You can generate response lists that contain answers that were chosen or not chosen at a number
of previous questions. You can also make more complex combinations such that the response
list contains answers chosen at questions A and B but not at question C. The basic approach
to defining the response list in the metadata section is the same as when you base a response
list on answers chosen or not chosen at a single question — that is, you define all the possible
responses that the question can have. In most cases this simply means using the same shared list
that is used by the questions whose answers you want to merge, but you can list the responses
in full at each question if you wish.
The following links take you to topics that explain how to set up the most common types of
response filtering; you can use these strategies to set up your own filters along similar lines.
Answers Chosen in Response to At Least One Question
Answers Chosen at Both (All) Questions
Answers Chosen at Only One Question
Answers Chosen in Response to At Least One Question
This topic shows how to create a response list that displays only answers that were chosen in
response to at least one of two earlier questions. The metadata section is as follows:
BrandList define
{
};
{
};
SawAdvert "Which of the following brands have you seen advertised
during the last four weeks?" categorical [1..]
{
use BrandList,
SawNone "Did not see any brands advertised" excl fix
} asc;
HeardAdvert "Which of the following brands have you heard advertised
{
use BrandList,
HeardNone "Did not hear any brands advertised" excl fix
} asc;
MostEffective "Of those advertisements, which brand do you think
had the most effective advertising overall?" categorical [1..1]
{
use BrandList,
} asc;
686
Chapter 1
You want the response list for MostEffective to contain only the brands that were mentioned at
SawAdvert or HeardAdvert or both, so place the following statements in the routing section:
SawAdvert.Ask()
HeardAdvert.Ask()
MostEffective.Categories.Filter = SawAdvert.Response.Value + HeardAdvert.Response.Value
MostEffective.Ask()
As you can see, the response list is built using the union (+) operator that nets the answers to the
two previous questions. You can net as many questions as you like to produce the response list
that you need. The Did not see/hear responses are ignored when the filter is built because they
are not part of the Brands shared list that is used by MostEffective. If the filter for MostEffective
produces an empty list, the question is not asked.
Answers Chosen at Both (All) Questions
This topic shows how to generate a response list that displays only responses chosen at both the
previous questions. The questions in the metadata section are:
BrandList define
{
};
{
};
{
use BrandList,
} asc;
{
use BrandList,
} asc;
CompareAds "For the brands for which you both saw and heard
advertising, which brand had better visual than audio
advertising?" categorical [1..]
{
use BrandList,
} asc;
The routing statements that produce a list of answers that were given at both SawAdvert and
HeardAdvert are as follows:
CompareAds.Categories.Filter = SawAdvert.Response.Value * HeardAdvert.Response.Value
CompareAds.Ask()
This script uses the intersection (*) operator to collect answers that were chosen at both questions.
Answers chosen at only one question or not chosen at all are ignored. If the filter for CompareAds
generates a blank list, the question is not asked.
687
Base Professional
Here’s a prompted and unprompted awareness example that results in a final rating question
about a brand selected at random from those that the respondent knows. The metadata section
defines all the questions that are used (they are not all asked):
BrandList define
{
};
{
};
FirstKnown "When you think of frozen desserts, which is the first
brand that comes to mind?" categorical [1..1]
{
use BrandList,
} asc;
OtherKnown "Which other brands can you think of?" categorical [0..]
{
use BrandList,
} asc;
Prompted "Which of the following brands do you recognize?" categorical [0..]
{
use BrandList,
} asc;
RateThis "Randomly selected brand for rating" categorical [1..1]
{
use BrandList,
} asc;
Rating "How would you rate {#RateThis} overall?" categorical [1..1]
{Excellent, VGood "Very Good", Good, Poor, VPoor "Very poor"};
The routing section is as follows. Notice the use of the temporary AllKnown variable that keeps
track of which brands have been mentioned.
Dim AllKnown
FirstKnown.Ask()
AllKnown = FirstKnown.Response.Value
' Use all except first known brand
OtherKnown.Categories.Filter = OtherKnown.DefinedCategories() - FirstKnown.Response.Value
OtherKnown.Ask()
AllKnown = AllKnown + OtherKnown.Response.Value
' Use all not known
Prompted.Categories.Filter = Prompted.DefinedCategories() - AllKnown
Prompted.Ask()
AllKnown = AllKnown + Prompted.Response.Value
' Select one answer at random from all brands known
' An alternative is Ran(AllKnown,1)
RateThis = AllKnown.Ran(1)
Rating.Ask()
688
Chapter 1
Answers Chosen at Only One Question
You can filter a response list so that it contains answers that were chosen at only one of a set of
questions. As an example, suppose that the metadata section defines the following questions:
BrandList define
{
};
{
};
{
use BrandList,
} asc;
{
use BrandList,
} asc;
OnlyOne "For the brands for which you either saw or heard advertising,
but not both, which brand had the best advertising?" categorical [1..1]
{
use BrandList,
} asc;
To create a response list that contains brands for which advertising was either seen or heard but
not both, the routing is as follows.
OnlyOne.Categories.Filter = SawAdvert.Response.Value / HeardAdvert.Response.Value
OnlyOne.Ask()
The script uses the difference (/) operator to collect answers that were given to one question but
not the other. If the filter for OnlyOne generates a blank list, the question is not asked.
Responses that Should Not be Filtered
You do not have to allow all responses in a list to be filtered. If a response list contains an Other
category, for example, you may not want that response to be affected by filtering that omits
responses not chosen. To mark a response as being unfiltered, add nofilter to its definition
as follows:
ResponseName ["ResponseText"] nofilter
Filtering completely ignores responses marked in this way, so the question that uses the filtered
list will always include the unfiltered responses in its response list regardless of whether or not the
response was chosen at a previous question.
The special na, dk, and ref responses have nofilter applied automatically. If you want
them to be filtered the same as ordinary responses, include canfilter in the response definition.
689
Base Professional
Here’s an example that illustrates this. The metadata defines three questions: the first will use
the full list of insurance products, the second will use only those products not mentioned at
HasInsurance, and the third will use only products mentioned at EnquiredThisYear. However, in
each case we want to offer respondents the chance of mentioning an unlisted product, saying don’t
know, or not answering so we flag those responses with nofilter.
InsProducts define
{
Life,
CriticalIllness "Critical illness",
Buildings,
Contents,
Mortgage "Mortgage protection",
Income "Income protection",
Travel,
OtherInsProducts "Other insurance products" other nofilter,
NoInsProducts "None" na,
DkInsProducts "Can't remember / Don't know" dk
};
HasInsurance "Which types of insurance do you currently have?"
categorical [1..]
{
use InsProducts
};
EnquiredThisYear "And are there any other types of insurance
that you have considered buying in the past year or that you
are considering buying now?" categorical [1..]
{
use InsProducts
};
GotQuote "And of those products that you considered or are
considering buying, for which ones did you request a
quotation?" categorical [1..]
{
use InsProducts
};
The routing is quite straightforward:
HasInsurance.Ask()
EnquiredThisYear.Categories.Filter = _
EnquiredThisYear.DefinedCategories() - HasInsurance.Response.Value
EnquiredThisYear.Ask()
GotQuote.Categories.Filter = EnquiredThisYear.Response.Value
GotQuote.Ask()
If the respondent has life, travel, and health (other) insurance, the response list for
EnquiredThisYear will include all the listed products except life and travel. It will also include
Other because it is ignored by the filter, as well as None and Don’t know which filtering always
ignores.
If the respondent has enquired about buildings, contents, and car (other) insurance, the response
list for GotQuote will contain those three items. It will also include None and Don’t know because
they are ignored by the filter.
Note: This example is adequate to illustrate how nofilter works. If you want to use
something similar in your own surveys, you will probably want to alter it so that it does not ask
GotQuote if the respondent did not make any insurance enquiries (you could place the question
in an If statement or set its MustAnswer property to False). You may also like to use text
substitution to display the text of any Other answers in the EnquiredThisYear and GotQuote
response lists. For more information, see the topic Variable Response Texts on p. 606.
690
Chapter 1
Filtering Loops
There are two types of filtering that you can do with loops:
Filter the questions so that only some of them are presented to the respondent.
Filter a categorical or numeric loop control list so that the questions within the loop are asked
for certain repetitions only.
You can perform both types of filtering on the same loop at the same time if necessary.
This section also covers the following topics:
Using randomization to filter loops.
Filtering the questions in a grid based on answers to a previous grid
Hiding cells in a grid, giving the appearance of selective filtering in the grid.
Filtering the Questions in a Loop (Ask Some Questions but Not Others)
To filter the questions in a loop so that only some are presented to the respondent, place the
following statement in the routing section:
LoopName[..].QuestionFilter = "Questions"
where:
Questions are the questions to be displayed. This can be either a comma-separated
list of questions names or, if the questions are consecutive, a range of names defined as
Qname1..QnameN.
For example:
FoodList define
{
Fruit, Vegetables, Salads, Fish, Meat, Bread,
Dairy "Dairy produce",
Pulses "Pulses/Nuts/Cereals",
PastaRice "Pasta/Rice"
};
TimesEaten "On the following days last week, how many times did you
eat ... ?" loop
{use FoodList}
fields
(
Monday long [0..10];
Tuesday long [0..10];
Wednesday long [0..10];
Thursday long [0..10];
Friday long [0..10];
Saturday long [0..10];
Sunday long [0..10];
) grid expand;
In this loop, the types of food are the answers (rows) and the days are the questions (columns). To
restrict the grid to displaying weekend days only, place the following statement in the routing
section:
TimesEaten[..].QuestionFilter = "Saturday, Sunday"
691
Base Professional
For a grid that displays weekdays only, type:

TimesEaten[..].QuestionFilter = "Monday..Friday"
In both examples, notice the use of [..] to show that the specification applies to all repetitions.
Without this, the interviewing program assumes that the statement refers to repetitions rather than
questions, and the interview will fail when it reads values that refer to questions. You can use this
fact to your advantage if you want to filter on repetitions rather than questions. For example:
TimesEaten.QuestionFilter = "Fruit, Salads"
produces a grid with rows for fruit and salads only and columns for all days of the week. Refer
to Filtering the Repetitions of Loops with Categorical Control Lists for more information on
this aspect of loop filtering.
Filtering by Repetition and Question

You can combine repetition and question filtering on a loop to ask a subset of questions for
certain repetitions only; for example, about the number of portions of fruit and salads eaten
at the weekend:
TimesEaten[..].QuestionFilter = "Saturday, Sunday"
TimesEaten.QuestionFilter = "Fruit, Salads"
TimesEaten.Ask()
Figure 1-102
Loop filtered by category and question
Asking Different Questions for Different Repetitions
If you present the loop as a series of repeated pages rather than as a grid, you can use filtering to
vary the questions for each repetition. For example, you could ask about hot drinks on weekdays
and cold drinks at weekends. You cannot use filtering to do this if you present the questions in a
grid. (There is an alternative method for grids which is discussed in Jagged Grids.)
There are several things you need to do in order to present different questions for different
repetitions, including some possible alterations or additions to the specification in the metadata
section. However, let’s look at the filtering first. The code to define a filter for a specific repetition
is:
LoopName.CategoryName.QuestionFilter = "Qnames"
where:
692
Chapter 1
CategoryName is the name of the repetition to be executed.

Qnames are the names of the questions to be asked for this repetition.
So the filters for the example are:
EatThisFood.Fruit.QuestionFilter = "Monday..Friday"
EatThisFood.Vegetables.QuestionFilter = "Monday..Friday"
EatThisFood.Salads.QuestionFilter = "Monday..Friday"
EatThisFood.Fish.QuestionFilter = "Saturday..Sunday"
EatThisFood.Meat.QuestionFilter = "Saturday..Sunday"
and you present the questions about each type of food on a separate page by typing:
EatThisFood[..].Ask()
When you ask questions in this way, it’s important to place the general question text, or an
explanation of what the questions are about, after the fields parameter in the loop definition,
otherwise the respondent will just see boxes labeled with the days of the week. For example:
EatThisFood loop
{use FoodList}
fields "How many times did you eat {@EatThisFood} on ...?"
(
) expand;
produces pages of the form:

Figure 1-103
Per category filtering with repetitions on separate pages
Compare this illustration and the script snippets with the grid illustration and script shown
earlier in this topic.
Filtering the Repetitions of Loops with Categorical Control Lists
Filtering the repetitions of a loop with a categorical control list is similar to filtering an ordinary
categorical response list. You define the loop so that its control list contains all possible categories,
and then add routing statements that specify for which categories the loop should be executed.
In the routing section, type:
Name.Categories.Filter = {Category_Spec}
693
Base Professional
where:
Name is the name of the loop.
Category_Spec names the categories to be displayed. This may be the name of a single
category or a comma-separated list of category names, both enclosed in curly braces.
Alternatively, you can specify a range of categories using the , with the category specification
enclosed in double quotation marks.
Here is an example based on a loop that is defined in the metadata section as follows:
FoodList define
{
};
TimesEaten "On the following days last week, how many times did you
eat ... ?" loop
{use FoodList}
fields
(
) grid expand;
We want to ask about pulses/nuts/cereals, pasta/rice and bread only. We do this by placing the
following statement in the routing section before we ask the loop:
TimesEaten.Categories.Filter = {Pulses, PastaRice, Bread}
TimesEaten.Ask()
If the categories to be used as filters are defined consecutively, you can save yourself work by
using the double-dot range operator. For example:
TimesEaten.Categories.Filter = "Fruit..Bread"
Another way of filtering loop repetitions is to use the QuestionFilter object with a simple
reference to the loop name:
TimesEaten.QuestionFilter = {Fruit, Salads}
This produces a grid with rows for fruit and salads only and columns for all days of the week.
Because there is no [..] qualifier specified for the loop name (TimesEaten), the interviewing
program assumes that the filter applies to the repetitions of the loop rather than the questions.
Filtering the Repetitions of Loops with Numeric Control Lists
You can filter the repetitions of loops with numeric loop control lists using the response to a
numeric question. For example, you can filter a loop so that it is repeated for every member of
the household rather than the maximum number of people you have allowed per household.
When you filter based on the answer to a numeric question, the interviewing program treats the
response as “1..response” because you normally want to ask on the first “n” repetitions. For
example, if the metadata is
694
Chapter 1
PeopleInHousehold "How many people are there in your household?"

long[1..9];
PersonLoop loop [1..9]
fields
(
PersonAge "How old is person {@PersonLoop}?" long [0..99];
PersonGender "Is this person ...?" categorical [1..1]
{Male, Female}
) expand;
the routing statements to repeat the loop for just the number of people in each household will be:
PeopleInHousehold.Ask()
PersonLoop.QuestionFilter = PeopleInHousehold
PersonLoop[..].Ask()
The [..] notation in the last statement causes each iteration of the loop to be presented as
a separate page rather than as a grid all on one page. If there are three people in the household,
the respondent will see three pages only even though the loop is defined to execute a maximum
of nine times. A typical page looks like this:
Figure 1-104
Filtering for a numeric grid with each iteration asked separately
If you would prefer to use a grid, define the loop as:

PersonLoop1 "For each person in the household ..." loop [1..9]
fields
(
PersonAge1 "Age" long [0..99];
PersonGender1 "Gender" categorical [1..1]
{Male, Female}
) grid expand;
and write the .Ask statement as:

PersonLoop1.QuestionFilter = PeopleInHousehold
PersonLoop1.Ask()
695
Base Professional
The page then becomes:

Figure 1-105
Filtering for a numeric loop displayed as a grid
Filtering a Grid using Answers from a Previous Grid

The metadata for the example is as follows:
FoodList define
{
};
FoodLoop "Which of the following do you eat as part of
your normal diet?" loop
{use FoodList}
fields (
NormalDiet "" categorical [1..1]
{
Yes, No
}
) expand;
LastWeekLoop "And roughly how many portions of these foods
do you eat each week?" loop
{use FoodList}
fields (
Portions "" long [1..100]
) expand;
The routing section contains the following code. Notice how the filtering for the second grid
has been placed in a function, making it reusable elsewhere in the survey.
FoodLoop.Ask()
LastWeekLoop.QuestionFilter = GridIterationsContainsAny(FoodLoop, {Yes})
LastWeekLoop.Ask()
Function GridIterationsContainsAny(Grid, Answers)

Dim Iteration
For Each Iteration In Grid
' Iteration[0] is the first categorical question in the grid
If Iteration[0].Response.ContainsAny(Answers) Then
GridIterationsContainsAny = GridIterationsContainsAny + CCategorical(Iteration.QuestionName)
End If
Next
End Function
The function requires two parameters: a grid question name and a list of answers. The example
function tests only the first categorical question in the grid, but could be extended to test other
questions too. It checks whether the response given to the question contains any of the answers
passed to it — in this example, whether the response contains Yes. If so, that category is added
696
Chapter 1
to the list of categories for the second grid. So, if a respondent regularly eats fruit, salads,
vegetables and bread, the second grid will ask the number of portions for fruit, salads, vegetables,
and bread only.
Random Filtering for Loops
You can enhance your basic filtering by asking questions at random. Typical examples are:
You want to execute the loop once only for a value selected at random from the loop’s
control list.
You want to ask questions about a random selection of answers given to a previous question.
There are various ways of meeting these requirements, and this topic shows two of the easiest
and most efficient methods. Both methods use a loop that defines the questions to be asked and
whose control list contains all items about which the questions may be asked. The differences are
where the randomization happens and the way in which the loop control list is filtered to restrict
the items about which the questions are asked.
Repeat a Loop Once for a Randomly Selected Value
With this method, the loop is defined with a randomized control list so that the routing section
does not have to bother about reordering the control list before selecting a value. The example
asks members of the product development group about one project that their group has worked on
(it assumes that all members of the team have worked on all projects). The project is chosen from
a randomized list of projects tackled during the year.
The same questions are asked for each project, so they are defined in a loop whose control
list contains the project descriptions:
Projects loop
{Project1, Project2, Project3, Project4} ran
fields
(
Position "What was your position in the {@Projects} project team?"
categorical [1..1]
{
Designer, Developer, Writer, QA, Manager
};
HowLong "How long (in months) did you work on this project?"
long [1..12];
Likes "What did you particularly enjoy about this project?"
text;
Dislikes "And was there anything you disliked about the project?"
text;
) expand;
The routing section needs to select one project from the list and ask just that iteration of the loop.
There are a number of ways you can do this, but the most efficient is as follows:
Projects[Projects.DefinedCategories().Ran(1)].Ask()
It tells the interviewing program to select at random one category from the Projects category
list and to ask the questions in the loop for just that category. All questions in the loop will be
displayed on the same page.
697
Base Professional
Using Random Answers from Those Chosen at a Previous Question
This method uses an ordinary, unrandomized loop control list. The items that will be used from
the list are chosen at random from the answers given to an earlier question. This example is
similar to the previous one except that it does not assume that everyone works on all projects.
Instead, it asks employees which projects they worked on and then asks for more details about one
project chosen at random from each employee’s answer. The metadata is as follows:
ProjectList define
{Project11, Project12, Project13, Project14};
YourProjects "Which projects did you work on last year?" categorical [1..]
{use ProjectList};
ProjectsLoop loop
{use ProjectList}
fields (
Position1 "What was your position in the {@ProjectsLoop} project team?"
categorical [1..1]
{
Designer, Developer, Writer, QA, Manager
};
HowLong1 "How long (in months) did you work on this project?"
long [1..12];
Likes1 "What did you particularly enjoy about this project?"
text;
Dislikes1 "And was there anything you disliked about the project?"
text;
) expand;
The routing statements to ask the questions in the loop about one project chosen at random from
those worked on are as follows:
YourProjects.Ask()
Projects.Categories.Filter = YourProjects.Response.Ran(1)
ProjectsLoop[..].Ask()
Another option, and one that does not use filtering at all, is to write:
YourProjects.Ask()
ProjectsLoop[YourProjects.Response.Ran(1)].Ask()
Refer to “Asking Selected Repetitions Only” in Asking repeated questions for further information
about this syntax.
Jagged Grids
Jagged grids are grids in which certain cells are unavailable. The illustration shows a typical
example where the Sunday cells are unavailable for weekday newspapers, and the weekday
cells are unavailable for Sunday publications.
698
Chapter 1
Figure 1-106
Jagged grid of newspapers by day of week
You cannot create this type of grid using filtering because every row and column in the grid needs
to be displayed. Instead, you can hide the unwanted cells using:
Name.Style.Hidden = True

Name is the question name
The basic structure of the illustrated grid (without the style parameters that define column widths
and cell background colors) is as follows. You can find the more complete example in the
“Scripts\Interview\Frequently Asked Questions\Loops and Grids” folder in the DDL installation
folder.
699
Base Professional
DailyNewspapersList define
{
Telegraph, Independent "The Independent",
Times "The Times", Express "The Express", Mail,
Sun "The Sun", DailyMirror "Daily Mirror"
};
WeekdayNewspapersList define
{
Guardian "The Guardian", Star "The Star",
FinancialTimes "The Financial Times"
};
SundayNewspapersList define
{
Observer "The Observer",
NewsoftheWorld "The News of the World"
};
DayList define
{
Sunday, Monday, Tuesday, Wednesday, Thursday,
Friday, Saturday
};
JaggedGrid "Please select the newspapers that you read on each day." loop
{
use SundayNewspapersList sublist,
use WeekdayNewspapersList sublist,
use DailyNewspapersList sublist
} fields
(
DayQ "" categorical [0..]
{DayList use \\.DayList sublist};
) expand grid;
Hiding cells is all done in the routing section, as shown below.

Dim sunday, weekday, newspaper
' Create some category lists to be used for comparison
sunday = JaggedGrid.DefinedListElements({SundayNewspapersList})
weekday = JaggedGrid.DefinedListElements({WeekdayNewspapersList})
' Hide newspapers as appropriate

For Each newspaper in JaggedGrid.DefinedCategories()
With JaggedGrid[CCategorical(newspaper)].DayQ.Categories.DayList
' If the newspaper is a Sunday newspaper, hide the Monday through
' Saturday categories
If sunday >= newspaper Then
.Monday.Style.Hidden = True
.Tuesday.Style.Hidden = True
.Wednesday.Style.Hidden = True
.Thursday.Style.Hidden = True
.Friday.Style.Hidden = True
.Saturday.Style.Hidden = True
End If
' If the newspaper is a weekday newspaper, hide the Sunday category

If weekday >= newspaper Then
.Sunday.Style.Hidden = True
End If
End With
Next
JaggedGrid.Ask()
The code that hides unavailable responses steps through each newspaper in the control list for the
JaggedGrid loop. The With...End With statement is simply a more efficient way of writing:
If sunday >= newspaper Then
JaggedGrid[CCategorical(newspaper)].DayQ.Categories.DayList.Monday.Style.Hidden=True
JaggedGrid[CCategorical(newspaper)].DayQ.Categories.DayList.Tuesday.Style.Hidden=True
...
End If
and hides the cell if the current newspaper is a Sunday one.

700
Chapter 1
The generates references such as:

JaggedGrid.Telegraph.DayQ.Categories.DayList.Monday.Style.Hidden=True
The way it works is this. In the For Each statement, DefinedCategories()

returns a categorical value containing the newspaper in the grid — that is,
{Telegraph, The Independent, The Times, ...}. The interviewing program sees this as a list
of category values such as {49, 50, 51, ...}, so the loop executes for each category value, so
newspapers is set to 49, 50, 51, and so on. Without CCategorical, the With statement would be
trying to execute statements such as:
JaggedGrid[49].DayQ.Categories.DayList
which attempt to index the 49th iteration of the loop. Using CCategorical converts the number
49 into a categorical {49} which the interviewing program understands as Telegraph.
Cancelling Filters
To cancel a question filter, type:

Name.QuestionFilter = Null
For category filters, type:

Name.Categories.Filter = Null
In all cases, Name is the name of a filtered question or loop.
Ending, Suspending, and Rolling Back Interviews
When a respondent starts an interview, the routing section of the interview script controls which
questions the respondent sees and in which order. When the respondent clicks Next after
answering the last question, the interviewing program terminates the interview and flags it as
completed. For more information, see the topic Standard End-of-Interview Procedure on p. 701.
Not every interview that starts becomes completed. The respondent may decide to abandon the
interview partway through and will just let the browser session time out. Alternatively, he/she
may click Stop if it is available. If a project uses quotas to balance the different types of people
that take part in the survey, some interviews may have to be terminated because the respondent
belongs in a group whose target has already been met. Occasionally, an interview may fail due
to a script error. All these things are things you need to consider when writing and testing your
script, even if the solution is simply to display a friendly message before closing the interview.
See Ending or Stopping Interviews and Dealing with Off-Path Data for details.
In some cases, partially completed interviews can be restarted. Generally, the interviewing
program deals with this automatically, but it may help to understand what happens behind the
scenes so that you can take this into account when testing the script. For more information, see the
topic Restarting Stopped Interviews on p. 704.
Respondents sometimes forget what answers they’ve given to earlier questions, or they
may want to change an earlier answer for some reason. In both cases, they can use one of the
navigation buttons to go back to any question that they have already answered. The interviewing
program rolls back the interview to that point and, depending on what changes, if any, are made,
701
Base Professional
may replay the interview to follow the original path through the interview or may take a different
path with new questions if this becomes necessary. If a different set of questions is asked, the old
data becomes “off path” and is not normally saved, but you can specify differently if you wish.
For more information, see the topic Save Points, Rollbacks and Replays on p. 705.
It’s not just respondents who can roll back interviews. You can do this from the script. A
typical example is where the answers to a set of numeric questions do not sum to 100%. By rolling
back the interview rather than just skipping back with GoTo, you ensure that the interview state
the second time the questions asked is exactly the same as when they were first asked, and that any
temporary variables that may have been set are automatically reset during the rollback.
Other topics covered in this section are as follows:
Reviewing Completed Interviews
Displaying a Summary of Answers at the End of the Interview
Calculating the Total Time Taken to Complete Interviews
“Review Interviews” (supervisors) and “reviewing interviews” (interviewers) in the IBM®
SPSS® Data Collection Interviewer Server User’s Guide
Standard End-of-Interview Procedure
When a respondent reaches the end of the interview script, the interviewing program displays
the message “End of interview. Thank you for your participation.” and flags the interview as
completed. The interview data is written to the case data file and the DataCollection.Status system
variable in the data is set to Complete (if the AutoUpdateIBM® SPSS® Data Collection Data
Model property is set to 1 in DPM (the default) then interview data is written out as each question
is answered). If the project uses sample management, the sample record is returned to the sample
management system for postprocessing.
The messages that respondents may see at the end of the interview are defined in
StandardTexts.mdd in C:\Program Files\Common Files\IBM\SPSS\DataCollection\6\\IOM. The
message for completed interviews is defined in EndOfInterview while the message for interviews
that are stopped for any reason are defined in InterviewStopped. You can change these messages
for a single project in the same way that you change the standard error messages (see Replacing
the Standard Message Texts for details), or for all projects by opening the file in MDM Explorer
and changing the value of the EndOfInterview or InterviewStopped variables. You can also
translate the variables’ values using IBM® SPSS® Translation Utility.
If you need even more control over the wording and want to vary it for different respondents,
you can specify the text in the routing section with:
IOM.Texts.EndOfInterview = "Message"
IOM.Texts.InterviewStopped = "Message"
For example:
IOM.Texts.EndOfInterview = _
"You have finished the interview early due to "+ tInfo.Format("b")
In this example, the reason for termination comes from an information item called tInfo in the
metadata section. The Format parameter says to use the text of the item rather than the numeric
value that is assigned internally to this text (see for further details about this function).
702
Chapter 1
Ending or Stopping Interviews
You can terminate an interview by placing the following statement in the routing section at the
point that you want the interview the end:
IOM.Terminate([Signals.Signal], [WriteData], [TerminateStatus.Status])
where:
Signal is a signal value to be passed to sample management indicating the reason for the
termination (see “Signals” later in this topic). If the project does not use sample management
you can omit this parameter and a default setting of zero will be used instead. If you omit
the signal and the project uses sample management, a signal of 1 (completed interview) or 2
(stopped interview) will be passed depending on the value of Status.
WriteData is True (the default) or False depending on whether or not you want to write out
any unwritten data for this interview. Currently only True is supported.
Status is the interview status code that shows how the interview was terminated (see
“Interview Termination Status” later in this topic).
Signals
Signals have no meaning to the interviewing program. Instead, they pass information about the
outcome of an interview back to the sample management system. The sample management script
will have been set up to recognize certain signal values and will define the actions to be carried out
on sample records returned from interviews with each signal value. For example, a sample record
for a completed interview may be transferred to a queue of records for completed interviews so
that it cannot be selected again on the current project, whereas a record for an interview that has
been stopped may be transferred to a stopped queue to await restart.
You can use whatever values you like as signals and can assign them whatever meanings suit
your company’s requirements. As long as the interview and sample management scripts use the
same values everything will work well. (Note, however, that in telephone interviewing projects,
you may need to update some of the reports if you change the meanings of some signals. The
interview scripting program has a set of predefined signals that are used by the standard sample
management scripts that come with the IBM® SPSS® Data Collection Developer Library. These
values are defined as constants in the Signals type definition:
Signal name Value Meaning
sigCompleted 1 A completed interview. The
respondent has answered all
applicable questions.
sigStopped 2 Interview stopped by the
respondent clicking Stop or by a
statement in the interview script.
sigError 4 Interview terminated due to an
error in the script. See Writing
Your Own Error Handler for an
example of how to use this signal.
703
Base Professional
Signal name Value Meaning

sigOverQuota 5 Interview terminated by quota
control. This happens when all
the quota cells that a respondent
belongs in are full.
sigEarlyComplete 6 An interview that should be
treated as a completed interview
even though the respondent may
not have answered all applicable
questions. You might decide
to flag interviews in this way if
respondents have completed at
least 80% of the survey.
Interview Termination Status
The interview status code defines the outcome of the interview from the perspective of the
interviewing program. Possible values are defined in the TerminateStatus type definition and
are as follows:
Status name Meaning
tsCompleted The interview completed.
tsScriptStopped The interview stopped for some reason before it
could be completed.
Note: Setting this status does not prevent the
respondent restarting the interview by using the
browser’s Back button to go back to a previous page
and choosing an answer that takes a different path
through the interview. To prevent this, either write
code in the sample management script to stop the
interview being restarted or use the tsCompleted
status.
DataCollection System Variables
The DataCollection system variables in the case data contain general information about each
interview. The ones that are directly related to ending interviews are as follows:
System variable Contents
DataCollection.Status The interview status. This contains a
categorical value showing the following:
• Was this a test or live interview?
• Terminate.Status value.
• For all statuses except Complete, whether
the interview was terminated with a signal
(see below).
For example {test,scriptstopped,signal} for
a test interview that failed due to a script
error, or {test,completed} for a completed
test interview.
DataCollection.EndQuestion The name of the last question answered.
DataCollection.TerminateSignal The numeric signal value (blank for
completed interviews).
704
Chapter 1
Note: Interviews terminated by an Exit statement in the routing section are treated as completed
interviews.
Examples
To terminate an interview and flag it as an early complete:
IOM.Terminate(Signals.sigEarlyComplete, True, TerminateStatus.tsCompleted)
To suspend an interview so that it can be continued later; for example, after the respondent has
tried the test product, watched the television program, or attended the course.
IOM.Terminate(Signals.sigStopped, True, TerminateStatus.tsScriptStopped)
Remember that stopped interviews can only be restarted using sample management. If the project
does not use sample management respondents will not be able to restart these interviews.
To terminate an interview and flag it as terminated by quota control:
IOM.Terminate(Signals.sigOverQuota, True, TerminateStatus.tsScriptStopped)
If a respondent belongs in cells whose quotas are full, it is better to catch this in the script, display
a suitable message, and then terminate the interview manually than to let the quota control system
close the interview abruptly. It is up to you which termination status you use. It may be that if
the quota checks are near the end of the script you decide to treat the interview as completed
(tsCompleted) rather than stopped (tsScriptStopped).
Restarting Stopped Interviews
A respondent may restart an interview for a number of reasons:

The respondent clicked Stop because he/she needed to take a break from the interview. These
interviews must be restarted using sample management.
The script contained a statement in the routing section that suspended the interview. These
interviews must be restarted using sample management.
The interview timed out due to inactivity. As long as the interview page is still open in the
browser, the respondent can click Next to restart the interview (the respondent may not even
be aware of the time-out).
You do not have to do anything in the script for restarted interviews. If the project uses sample
management, the sample management system locates the existing data for the interview and
makes it available to the interviewing program. The interviewing program silently replays the
existing data as if the respondent were taking the interview for the first time. When it reaches an
unanswered question, the replay stops and the interviewing program displays that question.
If the interview is restarted after a time-out, the interviewing program will still be aware of the
interview and will be able to reconnect to it at the question at which the interview timed out.
Refer to the “Restarting by clicking Next” and “Restarting from a URL” subsections of for a
more detailed and technical explanation of the restart process.
705
Base Professional
The following properties are set or incremented when interviews are restarted:
Property Description
IQuestionInfo.AskCount The number of times a question is asked.
This is incremented when a question is re-asked due
to validation errors or when a question is re-asked
after a restart using sample management. Note that
the interviewing program sees a restart as a new
interview connected to existing data, so increments
AskCount from 0 to 1 because this is the first time
the question is asked in the “new” interview.
IQuestionInfo.AnswerCount The number of times a question has been successfully
answered.
This is incremented when a question is re-asked
during a restart from sample management. The
interviewing program sees a restart as a new
AnswerCount from 0 to 1 because this is the first
time the question has been answered in the “new”
interview.
IQuestionInfo.OnPathAnswerCount The number of times a question has been successfully
answered when on the interview path.
This is incremented when a question is re-asked
during a restart from sample management. The
interviewing program sees a restart as a new
AnswerCount from 0 to 1 because this is the first
time the question has been answered in the “new”
interview.
If a question becomes off-path, this property is
decremented by 1.
IQuestionInfo.ErrorCount The number of times a question has been incorrectly
answered.
IInterview.Restart Set to True while the interview is being replayed
during a restart from sample management. It is False
during normal execution of the routing script.
Save Points, Rollbacks and Replays
Each time a respondent answers a question and clicks Next, the interviewing program appends the
state of the interview at that point (including the answer chosen) to a temporary storage file on the
disk as a save point — that is, a point at which data was saved. In scripting terms, the save point
for a question occurs immediately after the .Ask() statement for the previous question, so any
routing statements that exist between that .Ask() and the Ask() for the current question are not
part of the question’s save point and will need to be re-executed during the replay.
Each interview has its own temporary file, and these files are known collectively as the
value cache. If data is not being saved as each question is asked (that is, the project’s
AutoUpdateDataModel property is set to 0), then the data in these files is copied periodically into
the case data database by a program called the Transfer Service. This also happens if the database
server becomes unavailable during the interview. In this case, the data is still written to the value
cache and will be transferred by the transfer service once the database server is back online.
706
Chapter 1
When a respondent uses the Previous, First, or Goto navigation buttons to go back to an earlier
question, the interviewing program rolls back the interview to the save point for that question and
displays the question with its current answer. The respondent may either click Next, Last, or Goto
to leave the answer intact or may change the answer in some way. If the respondent continues
using a navigation button and does not change anything, the interviewing program steps through
the save points in the temporary file until it reaches the end of the file. It then displays the next
question and waits for the respondent to choose or enter an answer.
If the respondent changes an answer, the interviewing program writes a new save point for
this question and then continues as if this is a new interview. Any save points for later questions
become invalid even if the changed answer does not affect which questions are asked. If some
questions are no longer applicable, the data is flagged as being off-path and no longer contributes
to the interview.
Refer to the “Rollbacks” subsection of for a more detailed and technical explanation of the
rollback and replay process, and to Dealing with Off-Path Data for information about what can
be done with off-path data.
It is also possible to roll back interviews using statements in the script. You might do this if you
find inconsistencies in the respondent’s answers, such as a set of numeric answers that do not sum
to a given total. For more information, see the topic Scripted Rollbacks on p. 706.
Scripted Rollbacks
You can return to a particular save point from the interview script. Unlike routing with GoTo, this
resets the interview to the state it was when the question for that save point was asked. You might
want to do this if you have some statements that sum up various numeric answers throughout the
script and test whether the total matches a fixed value. If the total is wrong you can go back to the
questions that were summed to have the respondent reenter the answers. To go back to a particular
save point, type one of the following. For non-repeated questions:
IOM.SavePoints["Qname"].Go()
where Qname is the question whose save point you want to return to.
For repeated questions that are displayed as a grid:
IOM.SavePoints["LoopName"].Go()
For example:
IOM.SavePoints["RatingGrid"].Go()
When repeated questions are displayed one at a time as a loop, you can go back to the save point
for a specific repetition of the loop by typing:
IOM.SavePoints["LoopName[{Iteration}]"].Go()
707
Base Professional
where Iteration is the appropriate value from the loop control list. For example, if the loop is
defined as:
QualityLoop "" loop [1..3] fields

(
Quality "Thinking about the qualities that are important in a
sports coach, what do you think is the most/next most important
quality that person should have?" categorical [1..1]
{
Patience, Enthusiasm, Tact, Leadership,
LikesPeople "Gets on with most people",
Knowledge "Good knowledge of the sport and its rules",
Ability "Good at explaining things"
};
) expand;
you would type:
IOM.SavePoints["QualityLoop[3]"].Go()
to go back to the third repetition. If the loop is defined as:
NewsSection "NewsSection" loop

{
Editorial,
Rules "Rules Forum",
Health "Health and Nutrition",
Local "Local Round-up",
Coaching "Coaching Forum"
} fields (
FreqRead "How often do you read the {@NewsSection}
section of Your Sport magazine?" categorical [1..1]
{
Sometimes, Never
};
) expand;
you would type:
IOM.SavePoints["NewsSection[{Local}]"].Go()
to go back to the repetition for the Local Round-up section.
Save Points for Single Questions that are Asked Multiple Times
When a question is asked more than once in a script because there are multiple .Ask() statements
for it, you need to specify both the question name and the “on-path position” for the save point
you want to return to. To understand what the “on path position” is, consider the following script:
Q1.Ask()
...
Q1.Ask()
...
Q1.Ask()
Assuming that there is nothing in the script that skips any of the .Ask() statements, the
respondent answers Q1 three times. The save point for the first Q1.Ask() is just called Q1. The
save point for the second Q1.Ask() is Q1–1 because there is already one on-path save point for
708
Chapter 1
Q1. The save point for the third Q1.Ask() is Q1–2 because there are already two on-path save
points for Q1. So, the statements to go back to the three save points from the end of the script are:
' Back to first Q1.Ask()
IOM.SavePoints["Q1"].Go()
' Back to second Q1.Ask()
IOM.SavePoints["Q1-1"].Go()
' Back to third Q1.Ask()
IOM.SavePoints["Q1-2"].Go()
If there is routing in the script that prevents the second Q1.Ask() from being executed, there will
be only two save points: Q1 for the first Q1.Ask() and Q1–1 for the third Q1.Ask().
Comparison of Rollbacks to Save Points and Rollbacks using GoTo
This topic contains some scripts that illustrate how rolling back to save points works and compare
this approach with using GoTo. The metadata for both examples is as follows:
TotalCost "What was the total cost of the meal that you had
when you left the cinema?" long [1..500];
Food "How much of that was for food?" long [1..500];
HadDrinks "Did you have drinks with the meal?" categorical [1..1]
{Yes, No};
Drinks "How much did you spend on drinks?" long [1..500];
Service "And how much went on service/tips?" long [1..500];
NoMatch "The sum of the costs for food, drinks and service does not
match the total. Your answers were:<br/>
Total cost {#TotalCost}
Food cost {#Food}
Drinks cost {#Drinks}
Service cost {#Service}<br/>
Please try again." info;
Summary "These are your answers
Total cost {#TotalCost}
Food cost {#Food}
Drinks cost {#Drinks}
Service cost {#Service}" info;
Using save points

The routing for the version that uses save points is:
Dim sum
TotalCost.Ask()
Food.Ask()
sum = Food
HadDrinks.Ask()
If (HadDrinks="Yes") Then
Drinks.Ask()
sum = sum + Drinks
End If
Service.Ask()
sum = sum + Service
If (sum <> TotalCost) Then
NoMatch.Show()
IOM.SavePoints["TotalCost"].Go()
End If
Summary.show()
Assume that a respondent gives the following answers:

TotalCost 100
Food 70
HadDrinks Yes
709
Base Professional
Drinks 25
Service 10
The sum of the three values (105) exceeds the total cost so the respondent is asked to correct
his/her answers. The script goes back to the save point for TotalCost which, in this case, is at the
start of the script, and resets the answers to any questions and temporary variables between this
point and the previous position in the script to their initial unanswered state. This ensures that
any questions or variables that become off-path due to changed answers will have no value.
When the value of an off-path question is checked in script, its value will be empty. However, as
each question is asked again, the previous answer, or off-path response, will be displayed. If the
off-path response also needs to be cleared, the ClearOffPathResponse method can be used. For
more information, see the topic Dealing with Off-Path Data on p. 710.
Using GoTo
Now here’s the same routing section written using GoTo:
Dim sum
Dim times_asked
GoHere:
times_asked = times_asked+1
TotalCost.Ask()
Food.Ask()
sum = Food
HadDrinks.Ask()
If (HadDrinks="Yes") Then
Drinks.Ask()
sum = sum + Drinks
End If
Service.Ask()
sum = sum + Service
' This stops the script getting into an infinite loop
If (times_asked>2) Then
GoTo Summary
End If
If (sum <> TotalCost) Then
NoMatch.Show()
GoTo GoHere
End If
Summary:
Summary.show()
When a script uses GoTo to go back to a previous question, the interviewing program does not
reset any of the questions or temporary variables that exist between the GoTo and that question.
This means that any question that becomes off-path during the rerun still retains its data. If there
is filtering or routing based on this question later in the script, this can result in the wrong path
being taken from that point onwards. To see this, let’s use the same sets of answers that were
used for the save point illustration.
TotalCost 100
Food 70
HadDrinks Yes
Drinks 25
Service 10
710
Chapter 1
After answering the questions for the first time, the respondent reaches the statement that
compares the sum with the total cost. The two values do not match so the script displays an error
message and skips back to the GoHere label. This does not change any of the existing answers,
so as each question is reached, the respondent sees the previous answer displayed and can either
click Next to accept it or type in a new answer.
If the respondent gives the same set of second answers as in the first test, he/she will not see
the Drinks question. However, because it was not reset during the rollback, the original answer
will still exist even though it no longer contributes towards the total. When the summary is
displayed it will show the following values:
TotalCost 80
Food 70
HadDrinks No
Drinks 25
Service 10
Drinks is still 25 even though HadDrinks is now No. It is for this reason that you are advised
to use roll back interviews using save points rather than GoTo.
The default procedure for dealing with off-path data is to set it to null when the interview ends,
so the fact that Drinks contains data will not affect the validity of your case data. However, this
would not be the case if you changed the behavior so that off-path data was kept. For more
information, see the topic Dealing with Off-Path Data on p. 710.
Dealing with Off-Path Data
Off-path data consists of responses to questions that are no longer on the interview path. They
occur when a respondent backtracks and changes an answer to a question, and that change causes
different questions to be asked. The questions that were asked the first time but that are now no
longer relevant are called off-path questions.
Off-path data exists in two places: in the case data and in the value cache. Off path case data is
set to null when the interview completes. Off-path data in the value cache is cleared whenever
a respondent navigates backwards in an interview, except in projects where you have chosen to
keep all off-path data. In this case only, the off-path data remains in the case data and in the value
cache. You can change these settings so that, for example, all off-path case data is nulled and all
off-path value cache data is deleted as soon as a question becomes off-path.
Case Data
To specify what to do with off-path case data, type:
IOM.OffPathDataMode = OffPathDataModes.mode
near the start of the routing section of the script, where mode is one of the following:
dmClearOnComplete to set the case data for all off-path questions to null when the interview
completes. Off-path data is kept for stopped or timed out interviews. This is the default.
711
Base Professional
dmClearOnExit to set the case data for off-path questions to null when the interview ends for
any reason (that is, completes, stops, or times out). Normally, responses are written straight
to the case data database. With this option, off-path responses are left in the case data until
the interview ends. At this point, the interviewing program nulls all responses in the case
data that are not on-path at the point the interview ended.
dmClearOnNavigateBack to set the case data for off-path questions to null as soon as
the respondent clicks the Previous button or skips to another question using Goto or First,
or when an ISavePoint.Go() instruction is encountered in the routing section of the
interview script. With this option, the case data always reflects the questions that are on the
current interview path, so this option does not attempt to null off-path data on exit because it
assumes that the case data is up to date. If an interview is restarted from sample management,
and a different path through the interview is taken, any questions not re-asked after the
restart are not set to null.
dmKeep to keep all off-path data.
The following example sets the case data for all off-path questions to null as soon as the
respondent goes back to an earlier question. The metadata for the example is:
Film "Which film did you like best?" categorical [1..1]
{
FilmA "The first one",
FilmB "The second one"
};
FilmAQ1 "The first film starred Ben Brown. What others
of his films have you seen?" categorical [1..]
{
FilmBB1, FilmBB2, FilmBB3,
NoBB "No others" na
};
FilmAQ2 "What did you like best about the first film?"
text;
FilmBQ1 "This film starred Emma Filby. What others of her
films have you seen?" categorical [1..]
{
FilmEF1, FilmEF2, FilmEF3,
NoEF "No others" na
};
FilmBQ2 "What did you like best about the second film?"
text;
LastQ "Which film do you think will be the most successful
at the box office?" categorical [1..1]
{
FilmA1 "The first one",
FilmB2 "The second one"
};
FilmSummary page (Film, FilmAQ1, FilmAQ2, FilmBQ1, FilmBQ2, LastQ);
The routing section contains the following statements:

IOM.OffPathDataMode = OffPathDataModes.dmClearOnNavigateBack
Film.Ask()
If Film = {FilmA} Then
FilmAQ1.Ask()
FilmAQ2.Ask()
Else
FilmBQ1.Ask()
FilmBQ2.Ask()
End If
LastQ.Ask()
FilmSummary.Show()
712
Chapter 1
The respondent starts by saying that he/she preferred the first film and answers FilmAQ1 and
FilmAQ2. At LastQ the respondent starts clicking Previous to backtrack to Film. Each time the
respondent clicks Previous, the case data for the question he/she has just left is set to null. On
reaching Film, the respondent changes the answer to show that he/she preferred the second film
and then answers FilmBQ1, FilmBQ2, and LastQ. The case data for the new questions is written
and reflects the respondent’s final path through the script.
However, when the FilmSummary question is displayed, it shows the answers to all the
questions that the respondent answered, whether or not they are on the interview path. This is
because the interviewing program reads the answers to the questions on this page from the value
cache rather than from the case data. The case data is correct, but it could be confusing for the
respondent to see the answers to the off-path questions displayed. If you delete the data from the
value cache, as shown below, this will not happen.
If you choose generally not to retain off-path data, you can still keep off-path data for certain
questions by manually setting the responses to those questions to be on-path. Type:
Qname.Response.Value = Qname.Info.OffPathResponse
where Qname is the name of the question whose off-path data you want to keep.
Value Cache Data

You can remove off-path data from the value cache for single questions or for all off-path
questions. To clear the answer to a specific question, place the following statement in the routing
section of the script:
IOM.Questions["Qname"].ClearOffPathResponse()
To clear the answers to all off-path questions, use:

IOM.Questions[..].ClearOffPathResponse()
713
Base Professional
An easy way of deleting all off-path data from the value cache is to use interview scripting events
to check whether the current response to the question is the same as the previous response (if any)
and to discard all off-path data from the value cache if they are not. To illustrate how this works,
we’ll use the same metadata as before but with the following routing:
IOM.OffPathDataMode = OffPathDataModes.dmClearOnNavigateBack
Film.Ask()
If Film = {FilmA} Then
FilmAQ1.Ask()
FilmAQ2.Ask()
Else
FilmBQ1.Ask()
FilmBQ2.Ask()
End If
LastQ.Ask()
FilmSummary.Show()
' This event runs before a question is asked.
Dim Prop
Set Prop = IOM.Properties.FindItem("PrevResponse")
If (IsNullObject(Prop)) Then
Set Prop = IOM.Properties.CreateProperty()
Prop.Name = "PrevResponse"
Prop.Value = Null
IOM.Properties.Add(Prop)
End If
If (Question.QuestionDataType <> DataTypeConstants.mtNone) Then
Prop.Value = Question.Info.OffPathResponse
End If
End Sub
' This event runs after a question has been asked.

If (Question.QuestionName = "Film") Then
If (IOM.Properties["PrevResponse"] <> Question.Response.Value) Then
IOM.Questions[..].ClearOffPathResponse()
End If
End If
End Sub
This routing uses the OnBeforeQuestionAsk and OnAfterQuestionAsk events to define actions
that are to take place immediately before and after every question is asked. Follow the links for
more details about these statements.
In this script, OnBeforeQuestionAsk checks whether the current question has a
PrevResponse property. If it does not, the script creates one and sets it to null, otherwise it assigns
the question’s current response (if it has one) to the property. All this is in preparation for work
that will be carried out after the question has been asked.
OnAfterQuestionAsk checks whether the respondent has just answered the Film question. If
so, it compares the question’s previous response with its current response and, if they are not the
same, deletes the data from any questions that have now become off-path from the value cache.
Let’s follow our previous respondent through this routing script. When Film is displayed,
OnBeforeQuestionAsk creates a PrevResponse property for it and sets its value to null. The
respondent chooses “The first film” and clicks Next. The OnAfterQuestionAsk event compares
this answer with the null value in PrevResponse but does nothing else because the two do not
match. A similar thing happens for FilmAQ1 and FilmAQ2.
At LastQ, the respondent clicks Previous. Because this routing script uses the default behavior
for clearing data from the case data file, the case data is not nulled as the respondent backtracks
(this does not happen until the end of the interview). However, what happens to the value cache is
different. When the respondent moves from LastQ to FilmAQ2, OnBeforeQuestionAsk runs
714
Chapter 1
before FilmAQ2 is displayed and sets its PrevResponse property to the current answer to that
question. A similar thing happens for the other questions as the respondent backtracks to Film.
At the point at which Film is redisplayed, its PrevResponse value is “The first one”. The
respondent chooses “The second one” and OnAfterQuestionAsk runs. The current question is
Film, so the interviewing program compares the current response with the previous one. They are
not the same so the data held in the value cache for all related questions is deleted.
The respondents then answers FilmBQ1, FilmBQ2, and LastQ. When the Summary page is
displayed, only Film, FilmBQ1 and FilmBQ2 will have answers because these are the only values
present in the value cache. At this point, the case data still contains data for all the questions that
the respondent answered. Data for off-path questions is set to null when the respondents clicks
Next and the interview ends.
Reviewing Completed Interviews
Interviewers and supervisors can review completed interviews. Interviewers sometimes use this
facility as a means of entering text responses that they have written down during the course of
the interview. Supervisors use the review process as a means of quality control and can review
any interview that has been completed. The following points summarize the things you as a
scriptwriter may need to know about reviewing interviews.
You can use the IOM.Info.IsReview property to check whether the interview is being reviewed
after completion. This allows you to skip statements such as quota checks that are not
appropriate when reviewing interviews.
Review mode always keeps all off-path data. This ensures that all data gathered during
the original interview is available even if the reviewer changes an answer that results in a
different path through the script
When interviews are reviewed, they are replayed to the end but do not complete. Instead, the
last page is returned to the reviewer. Similarly, if the reviewer goes to the last page of the
interview, the last page of the interview is displayed but the interview does not complete and
the LastQuestionAsked property is not updated.
The Stop button stops the review process and saves any modifications to answers on the
current page. This differs from clicking Stop during the interview, where any selections or
input in the current page are discarded. Note that since the interview keeps off-path data and
LastQuestionAsked is not updated, the interview will still appear to have been completed.
A Reject button is displayed so that reviewers can reject interviews that are invalid for some
reason (perhaps the interviewer falsified some answers and the reviewer does not wish to
continue the review). This button is displayed as part of the interview page’s XML and is not
part of the standard set of navigation buttons available through IOM.Navigations.
If the TextQuestionsOnly interview property is True, only questions with text are presented for
review. Questions that have Other Specify categories are also presented if those categories
have answers. When an interview is started in this mode, the interviewing program displays
the last page asked that contains a text question. The “goto” list of available questions shows
only pages that contain text questions.
715
Base Professional
Displaying a Summary of Answers at the End of the Interview
An increasingly common requirement is to print out or display a summary of answers at the end
of the interview so that respondents can review them and make changes before the interview
terminates. There are several ways you can do this, ranging from the simple solution of using a
page statement to display all the questions that the respondent has answered through to more
complex solutions that present question names and responses in tabular form using a special
layout template.
The approach you use depends on the length of the survey and why you need the summary; for
example, is it to make it easy for respondents to check their answers, or is it because your company
needs to keep a printed record of each interview. This topic takes you through a relatively simple
example that lists all the questions in the script with the answers given to each one. You can either
copy it and use it as it is or copy it and use it as the basis for your own solution. Suggestions for
enhancements are given at the end of the topic.
The summary page that appears at the end of the interview looks like this:
Figure 1-107
Basic answer summary
Note: The questions are displayed in the order they are defined in the metadata section, not
the order in which they are asked.
The metadata code that defines this report is:
AnswerSummary "{MyAnswers}" info;
716
Chapter 1
The routing code that creates the summary’s content is as follows (long lines have been split and
marked with _ at the end of each continued line):
AnswerSummary.Label.Inserts["MyAnswers"].Text = BuildAnswerSummary(IOM)
AnswerSummary.Show()
Function BuildAnswerSummary(IOM)
Dim Question, Html
For Each Question In IOM.Questions
Html = Html + FormatQuestion(Question, IOM)
Next
BuildAnswerSummary = BoldItalic("ANSWER SUMMARY") + "<br/><br/>" + Html
End Function
Function FormatQuestion(Question, IOM)

Dim Html, Iteration, SubQuestion
Select Case Question.QuestionType
Case QuestionTypes.qtSimple
' A simple question. Show question text and response
If Question.Info.IsOnPath Then
Html = Html + Italicise(Question.Label.Text)
Html = Html + FormatResponse(Question)
End If
Case QuestionTypes.qtLoopCategorical, QuestionTypes.qtLoopNumeric
' Question is a loop. Format all the iterations of the loop
For Each Iteration In Question
Html = Html + FormatQuestion(Iteration, IOM)
Next
' If there are any responses to the questions of the
' loop then show the loop heading. Also show a break
' before loop responses (in order to group them)
If Html <> "" Then
Html = "<br/>" + Italicise(Question.Label.Text) + "<br/>" + Html
End If
Case QuestionTypes.qtBlock, QuestionTypes.qtCompound, _
QuestionTypes.qtPage
' Build up responses for all questions in the block/page/compound
For Each SubQuestion In Question
Html = Html + FormatQuestion(SubQuestion, IOM)
Next
End Select
FormatQuestion = Html
End Function
Function FormatResponse(Question)
' Format the response for a simple question
If (Question.QuestionDataType = DataTypeConstants.mtCategorical) Then
FormatResponse = ": " + Question.Response.Label + "<br/>"
ElseIf (Question.QuestionDataType <> DataTypeConstants.mtNone) Then
FormatResponse = ": " + CText(Question.Response.Value) + "<br/>"
End If
End Function
Function Italicise(qlabel)
Italicise = "<i>" + qlabel + "</i>"
End Function
Function BoldItalic(qlabel)
BoldItalic = "<b><i>" + qlabel + "</i></b>"
End Function
The script consists of a number of functions:

BuildAnswerSummary calls the FormatQuestion function for every question in the script
(IOM.Questions), even the ones that do not apply to the respondent, and then returns a
string containing a page title and a list of questions and answers.
717
Base Professional
FormatResponses is called by FormatQuestion to extract the answers to a question.

FormatQuestion tests the data type of each question and then extracts the name and answer
to each one. As it processes each question, the script checks whether the question is on the
interview path and, if so, appends the information onto a temporary variable called Html,
whose final value is written out by the AnswerSummary item. If the question is categorical,
the italicized question text is appended to Html and the FormatResponse function is called to
process the answer.
When the script encounters a loop, it processes each question in the loop in the same way that
it does for simple questions (the FormatQuestion function calls itself to do this). If any of
the questions in the loop has an answer, the function inserts the italicized loop question text
in front of the repeated questions.
When it encounters a block, compound, or page item, the function runs recursively to extract
answers to every subquestion in the block, compound, or page.
When all questions have been processed, the function returns a string containing a
list of question names and answers. This is displayed by the MyAnswers insert in the
AnswerSummary item.
Suggested Enhancements
Display an explanation of the summary at the top of the page, or on a previous page, so that
the respondent knows how to proceed. For example, if you are not going to allow answers to
be changed once the summary is displayed, you need to tell respondents this before they see
the page.
Hide unwanted navigation buttons. For example, you might want to display only Next for
accepting the answers, and Goto for skipping back and changing answers.
Display the summary in multiple columns using, for instance:
AnswerSummary.Style.Columns=2
Apply a layout or question template that improves the overall appearance of the page.
Display the summary as a table, with the questions in one column and the answers in the other.
Even without a template this will make the whole thing easier to read.
Use the OnAfterQuestionAsk event to append questions and answers to the summary as
each question is answered, rather than dealing with all questions in one go at the end of
the interview. This has the advantage of automatically excluding unasked questions from
the summary.
Here’s a variation of the previous example that implements some of these suggestions.
718
Chapter 1
IOM.Navigations.Remove(NavigationTypes.nvStop) 'Hide Stop Button

IOM.Navigations.Remove(NavigationTypes.nvPrev) 'Hide Previous Button
' Enclose all the answers that were formatted in a <table> tag
With AnswerSummary.Label.Inserts["MyAnswers"]
.Text = "<table border=""1"" width=""100%"">" + .Text + "</table>"
End With
AnswerSummary.Show()
Sub OnInterviewStart(IOM)
IOM.Questions["AnswerSummary"].Label.Inserts["MyAnswers"].Text = _
BoldItalic("ANSWER SUMMARY")
End Sub

With IOM.Questions["AnswerSummary"].Label.Inserts["MyAnswers"]
.Text = .Text + FormatQuestion(Question, IOM)
End With
End Sub
Function FormatQuestion(Question, IOM)

Dim Html, Iteration, SubQuestion
Select Case Question.QuestionType
Case QuestionTypes.qtSimple
' A simple question. Show question text and response
If Question.Info.IsOnPath Then
Html = Html + "<tr>"
Html = Html + "<td>" + Italicise(Question.Label.Text) + "</td>"
Html = Html + FormatResponse(Question)
Html = Html + "</tr>"
End If
Case QuestionTypes.qtLoopCategorical, QuestionTypes.qtLoopNumeric

' Question is a loop. Format all iterations of the loop
For Each Iteration In Question
Html = Html + FormatQuestion(Iteration, IOM)
Next
' If there are any responses to the questions of the

' loop then show the loop heading. Also show a break
' before loop responses (in order to group them)
If Html <> "" Then
Html = "<tr><td>" + Italicise(Question.Label.Text) + "</td></tr>" + Html
End If
Case QuestionTypes.qtBlock, QuestionTypes.qtCompound, QuestionTypes.qtPage

' Build up responses for all questions in the block/page/compound question.
For Each SubQuestion In Question
Html = Html + FormatQuestion(SubQuestion, IOM)
Next
End Select
FormatQuestion = Html
End Function
Function FormatResponse(Question)
' Format the response for a simple question
If (Question.QuestionDataType = DataTypeConstants.mtCategorical) Then
FormatResponse = "<td>" + Question.Response.Label + "</td>"
ElseIf (Question.QuestionDataType <> DataTypeConstants.mtNone) Then
FormatResponse = "<td>" + CText(Question.Response.Value) + "</td>"
End If
End Function
Function Italicise(qlabel)
Italicise = "<i>" + qlabel + "</i>"
End Function
Function BoldItalic(qlabel)
BoldItalic = "<b><i>" + qlabel + "</i></b>"
End Function
719
Base Professional
In this example, the task of extracting questions and answers has been moved into the
OnAfterQuestionAsk event. This means that the answer summary is built up as each question
is answered rather than at the end of the interview. The appearance of the summary has been
improved by writing it out as a table, and the Previous and Stop navigation buttons have been
hidden to prevent the respondent changing answers. Here’s the page that this script produces:
Figure 1-108
Answer summary shown as table
Calculating the Total Time Taken to Complete Interviews
This topic gives an example of how to calculate the total time taken to complete an interview,
excluding time between any stops and restarts of the interview.
The metadata section contains the following statements:
InterviewLength "Length of interview" long [0..];
SessionStartTime "Used to calculate time after a restart"
date nocasedata;
InterviewLength is used to write the interview duration into the case data, and SessionStartTime is
used in the calculation of time between stopping and restarting the interview.
The calculations are carried out in the routing section using the OnInterviewStart and
OnInterviewEnd events.
720
Chapter 1
Dim IntDuration
IOM.Questions["SessionStartTime"] = Now("UTC")
' Assign question object to temporary variable to simplify

' structure oflater statements that use this object
Set IntDuration = IOM.Questions["InterviewLength"]
' Store current duration in interview property for writing to

' log file
If IntDuration = NULL Then
IOM.Info.User1 = 0
Else
IOM.Info.User1 = IntDuration
End If
Debug.Log("Survey Started: Current duration recorded as " + _
CText(IOM.Info.User1) + " seconds")
End Sub
Sub OnInterviewEnd(IOM)
Dim StartTime, IntDuration, EndTime
' Assign question objects to temporary variables to simplify

' structure of later statements that use these objects
Set StartTime = IOM.Questions["SessionStartTime"]
Set IntDuration = IOM.Questions["InterviewLength"]
' Retrieve original start time and duration if interviewer/respondent
' backtracks to first question
If Not StartTime.Info.IsOnPath Then
StartTime = StartTime.Info.OffPathResponse
End If
If Not IntDuration.Info.IsOnPath Then
IntDuration = IntDuration.Info.OffPathResponse
End If
' Update the duration

EndTime = IIf(IOM.InterviewStatus = InterviewStatus.isTimedOut, _
IOM.Info.LastAskedTime, Now("UTC"))
IntDuration = IntDuration + DateDiff(StartTime, EndTime, "s")
Debug.Log("Survey Ended: Interview duration recorded as " + _
CText(IntDuration) + " seconds")
End Sub
Both events use the to assign an interview object to a temporary variable. This makes later
statements in the events shorter because they can refer to the object using the name of the temporary
variable rather than having to use the full object reference. For example, OnInterviewStart
sets the IntDuration variable to represent IOM.Questions[”InterviewLength”]. This means that
instead of writing:
If IOM.Questions["InterviewLength"] = NULL
you can use:

If IntDuration = NULL
The OnInterviewStart event performs the following tasks:

Writes the current time into the SessionStartTime item.
Copies the current interview duration (or zero if this is a new interview) into the User1
interview property.
Writes a message to the IVW log file reporting the current duration.
The OnInterviewEnd event performs the following tasks:
Updates the interview duration to include the time spent during the current session and writes
a note about this to the IVW log file.
721
Base Professional
The tests whether the interview has ended because it has timed out; that is, whether its
current status is TimedOut. If the interview has timed out, the event sets EndTime to be the
time at which the last question was asked. If the interview has not timed out (it may have
completed, or have been stopped by the Stop button or a statement in the script), EndTime
is set to the current time.
The interview’s duration is calculated by adding the last recorded duration value to the
difference between the start and end times of the current session. The duration is calculated
in seconds.
If the interviewer or respondent has backtracked to the start of the interview, the interviewing
program resets the interview start time and duration to null. OnInterviewEnd caters for
this by checking whether StartTime and IntDuration are off-path and, if so, retrieving their
original values for use in the calculations.
Here’s an example with times to clarify this behavior.
Respondent actions Script actions
Starts a new interview at 10:35am and answers OnInterviewStart sets User1 to 0 and writes a
questions for five minutes. message with this value to the log file.
Interrupted at Q10 and is unable to continue the OnInterviewEnd does the following:
interview before it times out. • Sets IntDuration and SessionStartTime to on-path
so that they will be saved in the value cache.
• Sets EndTime to the time at which Q10 was asked
(10.40am).
• Sets IntDuration to 300 seconds.
• Writes a message containing this value to the log
file.
Restarts the interview two hours later, at 12:40pm. OnInterviewStart sets User1 to the currently saved
interview duration (300 seconds) and writes a
message with this value to the log file.
Clicks Stop at Q25. It is now 1pm. OnInterviewEnd does the following:
• Sets IntDuration and SessionStartTime on-path
if necessary.
• Sets EndTime to the current time.
• Sets IntDuration to the original 300 seconds plus
the 1200 seconds for the current session.
• Writes a message to the log file showing the
current duration as 1500 seconds.
Restarts the interview at 2pm. OnInterviewStart sets User1 to the currently saved
interview duration (1500 seconds) and writes a
message with this value to the log file.
Completes the interview at 2:15pm. It is now three OnInterviewEnd does the following:
hours and 40 minutes since the interview was • Sets IntDuration and SessionStartTime on-path
started, but only 40 of those minutes (5 + 20 + 15) if necessary.
have been spent answering questions. • Sets EndTime to the current time.
• Sets IntDuration to the previously saved 1500
seconds plus the 900 seconds for the current session.
• Writes a message to the log file showing the
current duration as 2400 seconds (40 minutes).
722
Chapter 1
Dealing with Errors
When a respondent selects or enters an answer, the interviewing program compares that answer
against the requirements for the question. If the response is valid, the interviewing program
accepts it and proceeds with the next instruction in the routing section of the script. If the response
is invalid, the interviewing program displays an error message and waits for the respondent
to correct the error.
This type of error handling is called validation and it happens automatically as part of the Ask
statement for each question. Errors that occur while executing the routing script are called
script errors, and include things such as division by zero, out-of-range subscripts, or data type
mismatches. You should write an error handling routine in the routing section to deal with these
errors.
This section covers the following topics:
How .Ask() validation works
Standard error messages
Replacing the standard messages with messages of your choice
Preventing cross-site scripting in text responses

Using a custom validation function for validation not covered by the standard messages
Writing an error handling routing to process non-validation errors.
How Validation Works
The .Ask() method has built-in response validation and error processing that is largely invisible
to respondents. As far as respondents are concerned, if they enter or select invalid responses, the
interviewing program displays the question with an explanatory error message and waits for them
to correct the error. The following illustration shows the error that is displayed when a respondent
chooses an exclusive response and another response from a multiple choice list:
Figure 1-109
The CannotCombine error message is displayed above the question label of a categorical question.
723
Base Professional
This topic provides a more detailed description of what happens behind the scenes to help you
understand what changes you can make to the way validation works. The following diagram
summarizes the procedure:
Figure 1-110
Response validation procedure
The interviewing program has a standard set of error messages that it uses to report validation
errors such as out-of-range numeric responses, or a multiple choice selection that includes
an exclusive response with other responses. These messages are known as the standard error
messages, and they are available to all questions in a script. For more information, see the topic
Standard Error Messages on p. 724.
Each question has a collection item called Qname.Errors that holds the error message, if any,
to be displayed for that question. A question’s Errors collection is empty until the respondent
enters an incorrect answer. At this point, the interviewing program selects the appropriate error
message and inserts it in the Errors collection ready to display with the question. (The Errors
collection is always displayed with each question but because it is usually empty you are not aware
of it.) For example, if the Age question expects a value between 20 and 50 and the respondent
enters 59, the interviewing program copies the error message for an out-of-range numeric response
into Age.Errors and then redisplays the question with the error message in red above it.
724
Chapter 1
You can modify this procedure in the following ways:

By defining your own message texts to use instead of the standard message texts; for example,
if you would prefer to explain an error in a different way. For more information, see the topic
Replacing the Standard Message Texts on p. 725.
By defining your own validation tests, optionally with your own error messages; for example,
if the standard tests and/or error messages do not cover the type of validation you want to
perform.For more information, see the topic Using a Custom Validation Function on p. 729.
If you want to change the color or other visual characteristics of the error text, you may do so
using styles and templates. You can also use an <mrData> instruction in a template to specify the
position of the error message text on the page. For more information, see the topic Questions,
Responses, and Error Messages on p. 830.
Standard Error Messages
There are standard error messages that the interviewing program displays when a respondent
selects or enters an invalid answer to a question. They are as follows:
Name Default Text
CannotCombine Answer ‘{ANSWER}’ ({CATEGORY}) cannot be
combined with other answers.
InvalidText Answer ‘{ANSWER}’ is not valid.
MissingAnswer Missing answer(s).
NotDate Answer ‘{ANSWER}’ is not a valid date.
NotInRange Answer ‘{ANSWER}’ is not in range ‘{RANGE}’.
NotInteger Answer ‘{ANSWER}’ is not an integer value.
NotNumeric Answer ‘{ANSWER}’ is not numeric.
NotSingleAnswer Only one answer is allowed.
OtherNotSelected Answer ‘{ANSWER}’ ({CATEGORY}) has a
response but is not selected.
PlayerNavigationDisabled You have used the browser buttons, please use the
Next/Previous buttons below.
ThousandsSeparator The thousands separator character is not allowed.
TooFewAnswers There are too few answers, at least
‘{MINANSWERS}’ are required.
TooLittleText The answer does not have enough text, current length
is ‘{LENGTH}’,, minimum is ‘{MINLENGTH}’.
TooManyAnswers There are too many answers, only
‘{MAXANSWERS}’ are allowed.
TooManyDecimalPlaces The answer ‘{ANSWER}’ has too many decimal
places. The maximum is ‘{MAXLENGTH}’.
TooManyDigits The answer ‘{ANSWER}’ has too many digits. The
maximum is ‘{MAXLENGTH}’.
TooMuchText The answer has too much text, current length is
‘{LENGTH}’,, maximum is ‘{MAXLENGTH}’.
725
Base Professional
If an error occurs on a question that is nested within another question, such as a question in a loop,
the error is shown next to the nested question, as shown here:
Figure 1-111
Three-dimensional grid with messages for the repeated question only
The interviewing program also generates error messages at the question’s parent level but does
not normally display them. The parent question error specifies the name and number of the
subquestion that caused the error. This is repeated for all levels independent of how many levels
of nesting there are. See Error Messages for Questions in Loops and Blocks for additional
information about displaying error messages for these types of questions, and also some examples
of what the messages look like on the screen.
The standard error messages are defined in a number of languages in the StandardTexts.mdd
file in C:\Program Files\Common Files\IBM\SPSS\DataCollection\6\IOM. You can change these
default texts using MDM Label Manager, or you can use IBM® SPSS® Translation Utility to
add translations in other languages if you wish. If you want to change error messages for certain
projects only, refer to Replacing the Standard Message Texts.
Note: If you change StandardTexts.mdd in any way you must stop and restart IIS to have your
changes recognized. If you are running Windows 2003, you can stop and restart the IBM® SPSS®
Data Collection Interviewer Server application pool rather than restarting IIS if you prefer. This
has the advantage of not affecting any other applications that may be using IIS.
When the interviewing program needs to use a standard message text it looks for it in the
following places in the following order:
1. Helper fields defined in the metadata for the current question.
2. A StandardTexts block in the metadata section.
3. A default text in StandardTexts.mdd.
4. A default message stored internally in the interviewing program itself. These are always displayed
in English unless you are running a translated version of the interviewing program.
Replacing the Standard Message Texts
You can define your own error messages to replace the standard texts for all questions or for
individual questions. Defining message texts is very similar to defining questions and responses.
726
Chapter 1
For All Questions
To define replacement texts for the whole script, include the following in the metadata section:

(
Errors block fields
(
MessageName1 "Text 1" info;
MessageName2 "Text 2" info;
...
);
);
where:
MessageName is the name of the standard message you are replacing.
Text is the replacement message text.
You can define any number of replacement messages just by listing them one after the other
inside the Errors block.
Replacement message texts can contain substitution markers for things such as question names
or category texts, in the same way that markers are used in the standard texts. Substitution markers
are always enclosed in curly braces to differentiate them from the message text, and are as follows:
Marker Description
ANSWER The respondent’s answer.
RANGE The valid answer range for the question as defined
in the metadata section.
QUESTION The question name.
QUESTION_NUMBER The question number.
LENGTH The length of the response text.
MINLENGTH The minimum length for a text response.
MAXLENGTH The maximum length for a text response.
MINANSWERS The minimum number of answers that must be
chosen from a multiple choice list.
MAXANSWERS The maximum number of answers that may be
chosen from a multiple choice list.
CATEGORY The text of a single multiple choice response.
ERROR The error message associated with an internal error.
For example:

(
Errors "Errors" block fields
(
MissingAnswer "You have forgotten to answer the question."
info;
InvalidText "Your response is not in the right format."
info;
TooFewAnswers "You have not chosen enough answers. At least {MINANSWERS} are required."
info;
);
);
727
Base Professional
The substitution markers in the table apply to specific standard error messages only and
replacements that you define for those messages. A replacement text can include some or all
of the substitution markers that are used in the corresponding standard error message, but
should not contain substitution markers that are used in other error texts. For example, the
TooLittleText error is “The answer does not have enough text, current length is ‘{LENGTH}’,
minimum is ‘{MINLENGTH}’.” Your replacement text may use both markers or neither of
them. The replacement message “Incorrect text length. Must be between {MINLENGTH}
and {MAXLENGTH} characters.” will not work because {MAXLENGTH} is not valid with
TooLittleText. The interviewing program will treat the marker as ordinary text.
The same rule applies to other substitution markers (also known as inserts) that you might use
elsewhere in the questionnaire script. These markers are not valid in error messages and will
be treated as ordinary text.
For Individual Questions
If you want to use a different message for just one question in a script, you define it in the metadata
section as a helper text related to that question. Write the question’s definition as normal and then
insert the helperfields block at the end of the definition:
Qname "Text" Definition
helperfields
(
(
Errors block fields
(
MessageName "MessageText" info;
);
);
where:
Definition is the remainder of the usual question definition, including the question type,
length, and so on.
MessageName is the name of the standard message you are replacing.
MessageText is the replacement message text.
For example, the following message will be displayed only if the respondents enters an invalid
response at the MembershipNumber question:
MembershipNumber "Please enter your membership number."
text [9..9]
helperfields (
(
Errors "Errors" block fields
(
InvalidText "Invalid number. Membership number format is UUnnnnnnU;
for example, AA123456Z." info;
);
);
) validation("\u{2}\d{6}\u{1}");
Note: You can also use the StandardTexts block for defining your own texts for navigation buttons
and for the special response texts No answer, Don’t know, and Refused.
728
Chapter 1
Preventing Cross-Site Scripting in Text Responses
Cross-site scripting (XSS) is a means of running code from one machine on another machine. It is
sometimes used maliciously, either to obtain information from another machine or to change a
machine’s settings. In interviews, questions with text responses provide an easy entry point for
cross-site scripting because they generally accept anything that the respondent types.
One way of preventing cross-site scripting is to validate everything that the respondent types
and to reject anything that does not contain characters that you deem to be valid in the response.
The most common requirement is to reject responses that contain HTML tags because these could
be used for introducing executable code into the response.
The interview scripting language provides the AllowXHTML option for you to specify whether
or not HTML codes are acceptable in text. This option is False for all questions with text responses,
so you should not normally need to do anything to prevent cross-site scripting. If you want to
allow respondents to include HTML tags in their responses, set this option to True as follows:
Name.Validation.Options["AllowXHTML"] = True
where Name is the name of a question with a text response.

Note: If you set AllowXHTML to True you should write your own custom validation function to
check respondents’ answers.
To see how this works, suppose you have the following questions in your script.
FirstName "What is your first name?" text;

LastName "What is your last name?" text;... other questions
Thanks "Thank you, {YourName}, for helping with our survey." info;
and the routing section contains:
FirstName.Validation.Options["AllowXHTML"] = True
FirstName.Ask()
LastName.Validation.Options["AllowXHTML"] = False
LastName.Ask()...ask other questions ...
Thanks.Label.Inserts["YourName"] = FirstName.Response.Value
Thanks.Show()
Respondents will be able to enter anything as their first name, including HTML tags, whereas
last names containing HTML tags will be rejected. If the respondent has entered HTML tags
at FirstName, any scripting code inside those tags is executed when the Thanks message is
displayed. If the code is malicious your system is at risk.
Disallowing HTML tags in response texts does not extend cases where you set the response to a
text containing HTML characters in the routing section of the script. In the following example,
respondents may enter anything they like as their profession as long as it does not contain HTML
tags. However, anyone who does not answer the question will have their profession shown as
“Not given” in bold regardless of the value of AllowXHTML:
Profession.MustAnswer = False
Profession.Ask()
If Profession.Response.Value = Null Then
Profession.Response.Value = "<b>Not given</b>"
End If
ConfirmProf.Label.Inserts["Prof"] = Profession.Response.Value
ConfirmProf.Ask()
729
Base Professional
Using a Custom Validation Function
You’ll need a custom validation function whenever you want to perform validation that is not
covered by any of the standard error messages. For example, suppose you have a response list
with two subsections, and you want respondents to select answers from one section or the other
only. There is no standard message that you can display if a respondent selects responses from
both sections so you’ll need to create one of your own, and then write the necessary code to test
the answers chosen and apply the message if appropriate.
Defining the Error Message

You define the error message you want to use as an info item in the metadata section. This
is essential for multilingual projects because it makes the message text available for translation.
It’s good practise for single language projects too, although in these projects you can define the
message text in the routing section if you wish. Here is the metadata section for the example, with
the error message defined at the end:
SelectBrand "Which brands do you like? Please select from set A or B,

but not both."
categorical [1..]
{
BrandSetA "Brand set A"
{
Brand1 "Brand 1", Brand2 "Brand 2", Brand3 "Brand 3"
},
BrandSetB "Brand set B"
{
Brand4 "Brand 4", Brand5 "Brand 5", Brand6 "Brand 6"
},
' Indent=0 forces responses to line up with the subheadings
OtherBrands "Other" style(Indent = 0) other(OtherBrand "" text [1..40] ) fix,
NoAnswer "No answer" style(Indent = 0) na
};
' Define the error message
SelectBrandError "Select from Brand Set A OR Brand Set B." info;
Notice how the two sets of responses have been defined. These will appear as two subheadings
followed by three responses each. The responses in each set will be indented using the standards
built into the interviewing program.
Because there is no statement that marks the end of the second brand set, the interviewing
program will assume that all responses up to the end of the definition are part of that set. Since
this is not the case, the definitions for the Other and No answer responses have a style setting that
resets to indent back to 0 so that these responses line up with the subheadings rather than with
the responses in the second set. For more information, see the topic Indenting Response Lists
on p. 763.
Writing the Validation Function

You define validation functions in the routing section of the script and specify which one to
use for each question. Validation functions are defined like any other function and have the
following basic structure:
Function Fname(Question, IOM, Attempt)

Statements
End Function
730
Chapter 1
where:
Fname is the function’s name. You can give your validation functions any names you like but
it is a good idea to use names that explain what the function does.
Statements are mrScriptBasic statements.
You can define functions anywhere in the script, but the usual place is at the end.
To specify which validation function to use for a question, place the statement:
Qname.Validation.Function = Fname
in the routing section somewhere before the statement that asks the question.
The routing statements for the example script are as follows:
SelectBrand.Validation.Function = "ValidateBrands"
SelectBrand.Ask()
Function ValidateBrands(Question, IOM, Attempt)

' Check whether brands from more than one list have been selected
If (Question.Response.ContainsAny(Question.Categories[{BrandSetA}]) And _
Question.Response.ContainsAny(Question.Categories[{BrandSetB}])) _
Then
' Add error message to the errors collection
Question.Errors.AddNew("SelectBrandError", IOM.Questions.SelectBrandError.Label)
' Set return value to False as validation has failed
ValidateBrands = False
Else
ValidateBrands = True
End If
End Function
The script starts by naming the validation function to use. Then it asks the question and checks the
responses chosen. If the response passes the standard validation tests, the interviewing program
runs the validation function.
The If statement checks whether the respondent’s answer contains responses from both
sections. It does not matter what the responses are; just that some are from one set and some are
from the other set. If the test is True, the script adds the error message to the question’s Errors
collection. The name of the message is SelectBrandError and its text is the text defined for that
variable in the metadata section (stored in SelectBrandError.Label).
The function ends by setting a return value indicating whether or not validation was successful.
If the return value is True the interview continues with the next question; if not, it redisplays the
current question with the error message that was added to Question.Errors.
Variables in Error Messages

For simplicity, this example uses fixed text in the definition of the error message. You
can make the script more flexible by replacing the subheading texts in the error message with
variables and then including some extra statements in the routing section that replace the variables
with the subheading texts. This means that if you change the subheadings you do not have to
remember to update the error message text as well. In the example, the metadata definition for
the error message would become:
SelectBrandErr "Please select from {InsertBrandSetA} or {InsertBrandSetB}."

info;
731
Base Professional
and the following statements would be added to the validation function:

IOM.Questions.SelectBrandError.Label.Inserts["InsertBrandSetA"] = _
Question.Categories[{BrandSetA}].Label
IOM.Questions.SelectBrandError.Label.Inserts["InsertBrandSetB"] = _
Question.Categories[{BrandSetB}].Label
See Programmatically Inserting Text into Labels for further details about substitution using Inserts.
For a more complex example that shows how to add more than one new
message to the Errors collection and how to choose which of those messages
to display, look at the ranking question in the NewFeatures.mdd script in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Projects\NewFeatures.
Adding Extra Validation During Interviewing
You can make changes to your script while interviewing is in progress. New interviews will
always start using the latest version of the script whereas interviews that are currently in progress
will continue running on the older version. If an interview has timed out or has been stopped on the
older version of the script and is restarted on the newer version, the interviewing program silently
replays the interview until it reaches the point at which the interview timed out or was stopped.
However, if you have added extra validation statements that now make some of the original
answers invalid, the interviewing program will stop at the point at which the error now occurs and
will wait for the respondent to correct the answer. The interview then continues from that point.
General Rules for Validation Functions
This topic lists some general points regarding validation functions. All references to examples
refer to the example in Using a Custom Validation Function.
Referring to the Current Question
The name of the question on which the validation function is being run is passed to the function
in the Question parameter. Whenever you want to refer to the current question inside the
function, use Question rather than the question name itself. This allows you to write a general
purpose validation function that can be used by more than one question. In the example, you have
statements such as:
If (Question.Response.ContainsAny(Question.Categories[{BrandSetA}]) ...
which becomes:
If (SelectBrands.Response.ContainsAny(SelectBrands.Categories[{BrandSetA}]) ...
when the function is run on the SelectBrands question.
Referring to Other Questions
Functions called for one question do not normally have access to other questions. However, in the
case of the validation function, the names of all questions in the script are passed to the function in
the IOM parameter. If you want to refer to another question inside the function, type its name
732
Chapter 1
as IOM.Questions.Qname. The function in the example needs to refer to the SelectBrandError

information item to pick up the error message, which it does using:
IOM.Questions.SelectBrand
Return Values
The function must return a True or False value indicating whether or not validation was successful.
Number of Validation Attempts
You can control the number of attempts respondents may make at giving a valid answer. The
Attempts parameter has an initial value of 1 and is incremented every time the function returns
False. It is reset to 1 when the function returns True. You can write statements inside the function
that check the Attempts parameter and perhaps accept the most recent invalid response if the
number of attempts is greater than a given value.
For further information about the validation function, see IValidation.Function.
Checking for Unique Ranks in a Categorical Ranking Grid
Ranking grids are grids in which you ask respondents to rank or rate items in priority order. This
topic offers some validation functions that you can use for ensuring that every item in a grid is
ranked with a unique categorical rank.
The questions are defined as follows:
RankGrid "Please rank the following brands for Value for Money." loop
{
BrandA "Brand A", BrandB "Brand B", BrandC "Brand C", BrandD "Brand D"
} fields
(
Rank "Ranking" categorical [0..1]
{
r1 "1st",r2 "2nd", r3 "3rd", r4 "4th", r5 "5th"
};
) expand grid;
DuplicateRanks "Please check your answers - you have duplicate selections
for the following column(s)... {Dups}" info;
MissingRanks "Some brands have not been ranked." info;
733
Base Professional
This creates a grid with columns labeled 1st to 5th. Ratings are made by clicking in one column per
brand. Notice, however, that there are only four brands to be rated, so the 5th rating is superfluous.
The routing statements that display and validate the grid suppress this column and are as follows:
IOM.LayoutTemplate = "Card_Blue_TopAndBottomErrors.htm"
RankGrid[..].Rank.Categories.Filter = MatchColumnsToRows(RankGrid)
RankGrid[..].Rank.Categories[..].Label.Style.Width = "3em"
RankGrid.Ask()
Function MatchColumnsToRows(LoopQ)
' Match the number of ranks to the number of categories (Questions/Rows)
' of the grid
Dim i, Filt
LoopQ.Validation.Function = "UniqueRank"
For i = 0 to LoopQ.Categories.Count - 1
Filt = Filt + LoopQ[i].Item[0].Categories[i]
Next
MatchColumnsToRows = Filt
End Function
Function UniqueRank(LoopQ, IOM, Attempt)

'Check for duplicate values in columns
Dim GridCat ' A category to be ranked
Dim Rankings ' List of different rankings applied to a category;
' duplicates appear once only
Dim DupRankLabel ' Labels for columns containing duplicate rankings
Dim NumRankings ' Number of rankings checked
Dim DupRankings ' List of duplicate rankings for a category
Dim NumDups ' Number of duplicate rankings
Dim ThisDupRanking ' A ranking in the list of duplicate rankings
Dim ThisRanking ' A ranking in the list of possible rankings
' Clear errors collection
LoopQ.Errors.Clear()
' Check for duplicate rankings in a column

For Each GridCat in LoopQ.Categories
If Not LoopQ[GridCat].Item[0].Response.Value = Null Then
If Len(Intersection(Rankings, _
LoopQ[GridCat].Item[0].Response.Value)) > 0 Then
DupRankings = _
Union(DupRankings,LoopQ[GridCat].Item[0].Response)
End If
NumRankings = NumRankings + 1
End If
Rankings = Union(Rankings,LoopQ[GridCat].Item[0].Response.Value)
Next
' Build list of rankings that have been duplicated

If Len(DupRankings) >0 Then
For Each ThisRanking in LoopQ[0].Item[0].Categories
For Each ThisDupRanking in DupRankings
If ThisDupRanking = _
LoopQ[0].Item[0].Categories[ThisRanking].Value Then
DupRankLabel = DupRankLabel + _
LoopQ[0].Item[0].Categories[ThisRanking].Label + ", "
End If
Next
Next
End If
' Update error messages and set success/failure of validation

If Len(Rankings) < NumRankings Or _
NumRankings < LoopQ.Categories.Count Then
If Len(Rankings) < NumRankings Then
DupRankLabel = Left(DupRankLabel,Len(DupRankLabel)-2)
IOM.Questions["DuplicateRanks"].Label.Inserts["Dups"].Text = _
DupRankLabel
LoopQ.Errors.AddNew("DuplicateRanks", _
IOM.Questions.DuplicateRanks.Label)
End If
If NumRankings < LoopQ.Categories.Count Then
LoopQ.Errors.AddNew("MissingRanks", _
IOM.Questions.MissingRanks.Label)
End If
UniqueRank = False
Else
UniqueRank = True
End If
End Function
734
Chapter 1
We’ll discuss this code in more detail shortly. First, here’s what it does if the respondent submits
invalid or incomplete rankings. Notice also that the 5th ranking column is not displayed.
Figure 1-112
Ranking grid showing errors
Now we’ll look at the validation function is detail.

This example uses the Card_Blue_TopAndBottomErrors template that is installed with IBM®
SPSS® Data Collection Interviewer Server. If you use this code with your own templates you
should ensure that they show top errors for the grid otherwise the error messages will not be shown.
For more information, see the topic Error Messages for Questions in Loops and Blocks on p. 836.
In the MatchColumnsToRows function, the loop steps through each item in RankGrid’s loop
control list in turn. Items in the control list are numbered from zero so the For statement takes this
into account. For each item in the control list, the function selects the rank in the corresponding
position in the Ranking question and adds it to the filter. The function never reaches the fifth
ranking because there are only four brands to be ranked.
Note: This is a very useful function in scripts that use filtering because it means that you can
use the same ranking grid for all respondents, and the function will ensure that the number of
ranking columns matches the number of items the respondent is being asked to rank.
The UniqueRank function is more complex and performs the bulk of the validation work.
First, it clears the errors collection for the grid in case this is not the first time that the
respondent has submitted invalid rankings.
Then, the For loop checks for duplicate rankings in a column.
Each brand is checked to see whether it has the same ranking as a previous brand. The loop
uses the for this. The Intersection function compares lists of categorical items (in this case
Ranking, which is the list of unique ranks so far, with the ranking for the current brand) and
returns a list of items that are present in both lists. If this list is not empty the current ranking
is a duplicate of a previous one.
When a duplicate ranking is found, the list of duplicates in DupRanking is updated using the
. This function compares categorical lists and returns a list of items that are present in one
or more of the lists.
The loop ends by incrementing the number of ranks it has checked and updating the list
of ranks so far in Ranking.
Next, the function looks at the list of duplicate rankings.
735
Base Professional
If there are duplicates, the function builds a list of the relevant rank labels ready for insertion
in the error message. It builds the list by looping through the list of ranks and comparing each
duplicate rank (ThisDupRank) with the current rank in the list (ThisRanking). When a match
is found, the rank’s label is added to the list in DupRankList.
Finally, UniqueRank sets its return value according to whether the categories have been
ranked correctly.
There are two types of errors that can occur, either separately or together — duplicate ranks,
and unranked categories. For duplicate ranks, the function removes the trailing comma and
space from the list of duplicates, updates the DuplicateRanks error message with this list, and
adds the error message to the errors collection. For unranked categories, the function simply
adds the MissingRanks error to the errors collection. The return value for the function is
then set accordingly.
Validating Grids that Contain More Than One Question
Grids can contain more than one question. In some scripts, whether or not a question must be
answered depends on whether the other questions in the grid were answered. For example, in
a grid containing questions to do with newspaper readership, respondents who say they read a
particular newspaper must also answer the questions to do with frequency and rating, whereas if
they do not read a newspaper these questions must be unanswered. This topic shows a function
you can use for validating this type of grid.
The questions are defined in the metadata section as follows:
NewspaperList "" define
{
Telegraph, Independent, Times,
Express, Mail, Sun, Mirror
};
RatingList "" define
{
Good, Neutral, Poor,
NoRating "No Rating",
NotApplic "Not Applicable"
};
PaperReview "Please answer the following questions about
the papers you read regularly." loop
{use NewspaperList}
fields (
Frequency "How often do you read this paper?"
style(Control(Type = "DropList")) categorical [0..1]
{
Select "- Select -"
{
Daily "Daily",
OnceAWeek "Up to once a week",
OnceAMonth "Up to once a month",
Less "Less than once a month",
NoAnswer "Not Answered" NA
}
};
LastRead "When (date) did you last read this paper?"
style(Width = "10em") date
codes(
{
NoAnswer "No Answer" NA
}
);
Rating "Rating" categorical [0..1]
{use \\.RatingList} initialanswer({NotApplic});
) expand;
736
Chapter 1
They generate a grid that looks like this:

Figure 1-113
Grid containing more than one question
737
Base Professional
The routing section that displays the grid and implements the validation is:
IOM.LayoutTemplate = "Card_Blue_TopAndBottomErrors.htm"
PaperReview[..].LastRead.MustAnswer = False
PaperReview[..].Frequency.MustAnswer = False
PaperReview[..].Rating.MustAnswer = False
PaperReview.Validation.Function = "ValidateGrid"
PaperReview.Ask()
Function ValidateGrid(GridQuestion, IOM, Attempt)

Dim Cat, RowFrequencyError, RowLastReadError
Dim RowRatingError, GridFrequencyError, GridLastReadError
Dim GridRatingError, errString
' Clear any previously set error settings

GridQuestion.Errors.Clear()
errString = ""
GridFrequencyError = 0
GridLastReadError = 0
GridRatingError = 0
'Check rows for errors

For each Cat in GridQuestion.Categories
' Reset row error codes between each row
RowFrequencyError = 0
RowLastReadError = 0
RowRatingError = 0
' If Frequency is answered, must answer LastRead and Rating.

If Not GridQuestion[Cat].Frequency.Response.Value = Null Then
If GridQuestion[Cat].LastRead.Response.Coded.ContainsAll({NoAnswer},True) Then
RowLastReadError = 1
End If
If GridQuestion[Cat].Rating.Response.Value.ContainsAll({NotApplic},True) Then
RowRatingError = 1
End If
' If Frequency is blank, RowLastRead and RowRating should be too.

Else
If Not GridQuestion[Cat].LastRead.Response.Coded.ContainsAll({NoAnswer},True) Then
End If
If Not GridQuestion[Cat].Rating.Response.Value.ContainsAll({NotApplic},True) Then
End If
End If
'Set Grid error codes

If RowFrequencyError = 1 Then
GridFrequencyError = 1
End If
If RowLastReadError = 1 Then
GridLastReadError = 1
End If
If RowRatingError =1 Then
GridRatingError = 1
End If
Next
' Display errors

If GridFrequencyError = 1 or _
GridLastReadError = 1 or _
GridRatingError = 1 Then
ValidateGrid = False
If GridFrequencyError = 1 Then
errString = "LastRead and/or Rating answered but no answer for Frequency."
End If
If GridLastReadError = 1 or GridRatingError = 1 Then
If errString <> "" Then
errString = errString + mr.CrLf
End If
errString = errString + "LastRead and/or Rating is unanswered."
End If
GridQuestion.Errors.AddNew("GridQuestion", Ctext(errString))
Else
ValidateGrid = True
End If
End Function
738
Chapter 1
None of the questions in the grid requires an answer, so the questions’ MustAnswer properties are
set to False. Frequency and LastRead both have na (no answer) categories that will be selected
automatically if the respondent does not answer the question. (See Allowing Respondents Not
to Answer Questions for further details about the relationship between MustAnswer and na
categories.) Rating does not have a “no answer” category but, instead, has “Not Applicable” which
is set as the initial (and therefore default) answer and which respondents can select if they wish to
cancel a previously selected rating. Respondents wanting to cancel a selection from the Frequency
drop-down list can simply choose the “Select” category, and dates in LastRead can be deleted.
The ValidateGrid function checks two things for each newspaper (row) in the grid:
If Frequency has an answer, LastRead and Rating must both be answered. If this is not so, the
RowLastReadError and/or RowRatingError variables are set to 1 as appropriate.
If Frequency does not have an answer, LastRead and Rating must both be unanswered. If this
is not so ,the RowFrequencyError variable is set to 1.
The function loops through each row of the grid setting the values of the row error variables if
errors are found. These variables are reset between each row. At the end of each row, the variables
GridFrequencyError, GridLastDateError and GridRatingError are set to 1 if RowFrequencyError,
RowLastDateError or RowRatingError are 1 for the current row. The Grid variables are not reset
between rows to cater for cases where some rows contains errors while others do not.
When the whole grid has been checked, the function uses the grid error variables to display
error messages.
Handling Script Errors
Non-validation errors are errors that happen when the routing instructions tell the interviewing
program to perform an impossible task. They are sometimes called run-time errors and include
things such as:
Out-of-range subscripts — for example, referring to variable[6] when there are only five
cells in the variable.
Data type mismatches — for example, adding a numeric value to a text value.
Invalid text substitutions — for example, substituting text into an unknown banner or text
variable.
Division by zero.
These types of errors always cause the interview to end immediately. The respondent will usually
see an error message, but since it has been generated by the interviewing program itself it may
not be very helpful. Sometimes your own testing will catch these types of errors, but unless you
are careful to test every possible combination of responses in an interview you cannot be sure
that all interviews will be error free. The best way to cater for unexpected errors is to write an
error handling function. This will trap the errors before they have a chance to make the interview
fail, and allows you either to terminate the interview with a message of your choice or to ignore
the error and continue with the next question.
You can make your error handler as simple or complex as you like, depending on the project’s
requirements. You can even define two error handlers and use different ones depending on
how far through the script the respondent is. If the interviews are long, you may decide that if
respondents have reached a certain point in the interview you would rather ignore the error and
739
Base Professional
collect what data you can, whereas if the respondent has only just started an interview you will
allow it end immediately.
Use the links below to find out more about writing error handlers.
Script to Demonstrate Script Errors
A Suggested Error Handler for your Scripts
Writing Your Own Error Handler
Script to Demonstrate Script Errors
This topic is designed for people who are new to scriptwriting. It contains a simple script that you
can run to generate script errors and then change to see the difference between using and not using
an error handler. The script generates a type mismatch and an out-of-range subscript, and contains
an error handler that displays the error message. If you’re using IBM® SPSS® Data Collection
Base Professional to write and test scripts, the error message appears in the Output pane.
To see how this code works, copy it into a new script file and then comment out different
sections as suggested in the comments in the script. The metadata section is:
Q1 "This is Q1" long [1 .. 9];
Q2 "This is Q2" long [1 .. 9];

' Remove the comment from the next line to use the error handler
' On Error Goto ErrorHandler
Q1.Ask()
' Define some variables for use in the script

Dim txtvar[3] ' Generates txtvar[0] to txtvar[2]
Dim numvar
numvar = 0
' Type mismatch error if you use the next line instead of one below it
' txtvar[numvar] = "Some text" + numvar
txtvar[numvar] = "Some text" + ctext(numvar)
For numvar = 0 to ubound(txtvar)-1

' Subscript out of range with this logic because there is no txtvar[3]
' Remove the comment from the next three lines to see the error
'If numvar = 1 Then
' numvar = 3
'End If
Debug.Log("txtvar contains " + txtvar[numvar])
Next
Q2.Ask()
Exit
ErrorHandler:
Debug.Log("ERROR HANDLER: The error is " + err.Description)
' Remove the comment from the next statement to continue the interview
' after the error
' Resume Next
Here are some suggestions on how you can use this script to test various error scenarios.
If you run the script exactly as it is, you will see Q1. Answer the question and click Next. The
script will stop with the message “Subscript out of range accessing the array variable ‘txtvar’”. If
you are using Base Professional you’ll see that this message appears when the Debug statement in
the For...Next loop is executed.
740
Chapter 1
Now change the commenting in the section that will produce a type mismatch. When you run
the script you’ll see Q1 and then the interview will end with the message “Type mismatch error,
converting ‘Some text’ from text to Double”.
Now remove the comment marker from the On Error statement. When you run the script
this time, errors will be directed to the error handler so you’ll see Q1 and then the interview ends
with a message that says “ERROR HANDLER: The error is Type mismatch error, converting
‘Some text’ from text to Double”. If you were to change the error message to say “An internal
error means that the interview cannot continue. Thank you for your help.”, you have an error
handler that you can use in your scripts.
All the interviews so far have ended when the error occurred, so you’ve never reached Q2. If
you want interviews to continue after an error, you need to instruct the interviewing program to do
this. To see this for yourself, remove the comment marker from the Resume Next statement.
This tells the interviewing program to resume the interview with the statement after the one
that caused the error. When you run the script now, you’ll see Q1, the message box with the
error message, and then Q2.
A Suggested Error Handler for your Scripts
A simple error handler that is adequate for most interviews is as follows. All scripts created using
the Build activity have this code inserted automatically at the start of the routing section.
If Not IOM.Info.IsDebug Then On Error Goto __DefaultErrHandler

Goto __StartOfScript
__DefaultErrHandler:
Dim __err_msg, __error
__err_msg = "Script error at line " + CText(Err.LineNumber) + ", " + Err.Description
IOM.Log(__err_msg, LogLevels.LOGLEVEL_ERROR)
If IOM.Info.IsTest Then
IOM.Banners.AddNew("__ScriptErrMsg" + CText(__error), __err_msg)
__error = __error + 1
If __error > IOM.Info.MaxTestErrors Then
End If
End If
Resume Next
__StartOfScript:
The variable names in the example all start with two underscores but this is not a requirement.
The reason is that this is code is automatically generated in the Build activity, so there needs to be
some way of ensuring that the variable names do not clash with any that the scriptwriter may use
for question names in the script. If you write your own error handler you can use any names you
like as long as they do not clash with variable names in the rest of the script.
The first two lines of code are not part of the error handler. They prevent the error handler
being enabled if the script is being run in IBM® SPSS® Data Collection Base Professional, so
that any script errors will cause the interview to fail and display their messages on the screen. The
key part of this section is:
On Error Goto __DefaultErrHandler
which directs all errors to the error handler. If you write an error handler, you should include a
statement like this at or near the top of the routing section.
741
Base Professional
The error handler is defined under the DefaultErrHandler label. When an error occurs, the
error handler writes the error message and the line number at which it occurred, to the log file
(IVW*.tmp). The line number is the line at which the error affected the interview, which may
or may not be the line number that contains the invalid instruction. Sometimes, an error in one
statement does not have an effect until a little later in the script. However, the line numbers are
usually a reasonable guide to where to start looking.
If the interview is a test interview, the message is also displayed as a banner at the top of the
current page. After an error, the Resume Next line instructs the interview to continue.
Writing Your Own Error Handler
All scripts that use an error handler must contain a statement that instructs the interviewing
program to use the error handler when errors occur. Type:
On Error Goto Label
where:
Label is the label that marks the start of the error handling code.
The normal place for this statement is at the top of the routing script, but you can use it elsewhere
too if you want to handle errors differently at different parts of the interview.
The general structure for an error handler is:
Label:
Statements
[Resume Next]
where:
Label is a script label that marks the start of the error handling code.
Statements are any valid routing or mrScriptBasic statements that you want to execute
when a run-time error occurs. The most common statements are those that write information
to a log file, but you may also want to display an explanatory message for the respondent
or interviewer.
Resume Next is an optional statement that causes the interview to continue at the statement
immediately after the one at which the error occurred.
You can define more than one error handler as long as each one has a unique label. You can put
them anywhere in the routing section, although at the start or end of the section are the most
usual places.
If you put the error handling code at the start of the routing section, you’ll also need a statement
that skips over the code to the first instruction in the interview itself. The way to do this is to mark
the start of the interview with a label and jump to that. For example:
On Error Goto ErrHandler
Goto StartHere
ErrHandler:
Error handling statements
StartHere:
Statements for interviews
742
Chapter 1
Since the error handling section will either terminate the interview with an error message or end
with Resume Next to continue with the next question, there is no need to include a statement that
specifically marks the end of this section. However, if the error handler does not use Resume
Next, it is good practise to mark the end of the error handler with an Exit statement to ensure
that the interviewing program stops when it reaches the end of this code.
When the error handler is at the end of the routing section, you need to mark the end of the
main interviewing section so that the interviewing program stops when it reaches this statement.
The statement you use is Exit:
On Error Goto ErrHandler
Statements for interviews
Exit
ErrHandler:
Error handling statements
Here’s an example of an error handler that writes a message to the log file and also displays
a message for the respondent or interviewer. The text of the message that the respondent or
interviewer sees is defined in the metadata section of the script as follows (the message is spread
over a number lines for readability, but must be typed all on one line in the script):
ErrorDisplay "A processing error has occurred. If you have a moment to
spare, please help us to resolve the error by clicking
<a href=""mailto:_helpdesk@spss.com?subject=Error in survey {ProjectName}
&body=Please enter any details about what happened here:%0A%0A
Technical details:%0ATime of error (UTC) = {TimeStamp}%0A
Project = {ProjectName}%0ARecord identifiers = {Serial}, {RespId}%0A
{ErrorDetails}"">here</a> to send an email description of the problem.
<br/><br/>Please return later to try again. Thank you for your help."
info;
The texts in curly braces are the names of variables whose values are set in the routing section
(they are called Inserts), and the %0A strings generate new lines in the text when it is displayed
in the email window.
The error handler is as follows:
ErrorHandler2:
Dim err_msg
err_msg = "Error executing script (line " + _
CText(Err.LineNumber) + "): " + Err.Description + " (" + _
CText(Hex(Err.Number)) + ")"
' Populate inserts for user message
ErrorDisplay.Label.Inserts["TimeStamp"].Text = Now("UTC")
ErrorDisplay.Label.Inserts["ProjectName"].Text = IOM.ProjectName
ErrorDisplay.Label.Inserts["Serial"].Text = CText(IOM.Info.Serial)
Else
End If
ErrorDisplay.Label.Inserts["ErrorDetails"].Text = err_msg
' Display message
IOM.Texts.InterviewStopped = ErrorDisplay.Label
' Terminate interview and flag as failed due to script error
All the statements that mention the Inserts property are placing information about the
interview in variables that are part of the message that the respondent or interviewer sees. See
Programmatically Inserting Text into Labels for further information about Inserts.
743
Base Professional
IOM.Text.InterviewStopped is the standard text that is displayed when an interview stops

for any reason. Our script sets it to be the same as the message text that is written to the log file.
Page Layout Facilities
Page layout facilities control everything about the appearance of the questionnaire during an
interview, from the background color of each page to the position of question and response texts
on a page, and the fonts and font effects used for those texts. You can break page layout facilities
into three categories:
Styles. These define the characteristics of an individual item, such as the color of a question’s text
or the image to be displayed for a particular response. You define styles in the metadata or routing
sections of the script. For more information, see the topic Styles on p. 744.
Default Styles. These define the default characteristics for the different types of page elements
such as question texts, response texts, and navigation buttons. You define default styles in the
routing section of the script. For more information, see the topic Default Styles on p. 814.
Templates. Template files define the overall appearance of a page and tend to apply either to whole
questionnaires or to sections of a questionnaire. They control aspects such as the position of
question and response texts and error messages, and can use cascading stylesheets to determine
colors, fonts, and so on. IBM® SPSS® Data Collection Development Library comes with a
number of example templates that you can use or you can define your own templates from scratch.
For more information, see the topic Templates on p. 825.
When a questionnaire uses two or more of these layout facilities, the styles are applied in the
following order:
1. Template
• CSS Styles
• HTML CSS Styling as attributes within tags
2. Defaults
• DefaultStyles.Default
• DefaultStyles.Labels
• DefaultStyles.Navigation and DefaultStyles.Categories
• DefaultStyles.Questions
• DefaultStyles.Questions.Labels
• DefaultStyles.Questions.Categories
• DefaultStyles.Grids
3. Styles in the metadata section
4. Styles in the routing section
5. Grid styles
A style defined for an individual item in the routing section overrides the corresponding style in
the metadata section and also the default style or template setting for that item only. For example,
if the template specifies that all question texts should be red, you can display an individual
question text in green simply by setting this as part of the question’s definition in the metadata or
routing section.
744
Chapter 1
Note: If you are not familiar with the Interview Object Model or with object oriented
programming in general, you are strongly advised to read A Non-Programmer’s Guide to the
Interview Object Model before reading anything to do with setting styles in the routing section of
the interview script.
In addition, the behavior of many of the styles and default styles is based on the way that
similar facilities work in standard HTML browsers. If you want to work with styles at a detailed
level you may find it helpful to purchase a generic reference guide to HTML.
Styles
You can define styles for:

Text defined in the script — color, size and display effects for question texts, categorical
response texts, and information (banner) texts.
Categorical response lists — whether responses are displayed with check boxes, radio buttons,
or in some other format; whether to display responses in rows or columns and how many rows
or columns to use; and how to indent response lists.
Categorical responses in non-categorical response lists — the type of selection box to display
for categorical responses that are defined in the codes() portion of a numeric, text, or date
question. Typically these are the special no answer, don’t know, and refused responses.
Input boxes for numeric, text, and date responses — size, color and dimensions of the input
box; display methods for text boxes, including those for Other Specify responses.
Navigation buttons — size and color of the buttons; and size, color, and display effects for the
text on the buttons.
Grids — color, size, and display effects for row and column heading texts; border type, size
and color; row height; column width; and space between cell content and cell borders.
Setting styles also covers the following:
The use of images in text or in place of categorical response texts.
Playing audio files to respondents and recording responses to text questions.
The relative alignment and position of the question text and response portions of questions.
Note: In almost all cases you will find that you can specify styles in the metadata section or in
the routing section. If you specify the same characteristic for the same item in both sections, the
specification in the routing section overrides the one in the metadata section. So, if the metadata
section defines a question with red text and the routing section specifies it as green, respondents
will see green question text for that question.
The advantages of defining styles in the metadata section are that it is easy and they carry
forward into other products such as IBM® SPSS® Data Collection Survey Tabulation.
The advantage of specifying styles in the routing section is that you can specify the styles
dynamically based on a previous response. For example, you could display the text of an Other
Specify response in a different color according to whether or not the respondent has chosen Other
Specify at the previous question. You cannot do this in the metadata section. Another advantage is
that you can vary the styles between CATI and Web interviews, using simpler styles for CATI and
more visually interesting styles for Web interviews.
745
Base Professional
Question, Response, and Information Text

Question, response, and information text is the basis of any interview so it is important that it
is easy to read and understand. You will also want to make the interview page look interesting
so that respondents are encouraged to continue with the interview. This might be particularly
important in surveys aimed at children or teenagers, who may be less inclined to persevere with
a survey whose pages look dull and lifeless.
One way of making pages look interesting is to use color. Not only can this brighten an
otherwise dull looking page, it also enables you to emphasize key words or phrases, or to introduce
a company branding concept by using the same color scheme as on your company’s web site or
in printed literature. When choosing colors it is worthwhile bearing in mind that “less is more”.
Use color sparingly and choose colors that work well together. Also bear in mind that certain
colors or color combinations may not suit some people: pale blue text on a white background, for
instance, is not always easy to read.
Font changes are another way of highlighting different types of text or applying company
standards to your surveys. They also allow you to cater for the needs of your prospective audience,
perhaps increasing the text size for surveys aimed at older people or people with sight problems.
There are three sorts of changes you can make with regard to fonts:
Family. The font family or name (often called the typeface) — for example, Times or Arial.
Size. The character size.
Effects. The appearance — for example, bold or italic.
You can specify color and font changes in the metadata section or in the routing section. In the
metadata section you use labelstyle keywords to specify all the characteristics for text that is
defined in the script. You can set any number of color and font characteristics for a single text
in one labelstyle specification.
In the routing section anything to do with text defined in the script is controlled by the Label
object and anything to do with appearance is controlled by the Style object. Therefore, any
statements you write to do with the appearance of text defined in the script will include the notation
Label.Style. You will need to write a separate statement for each characteristic you want to set.
You can also specify color and font display characteristics for the answers to numeric, text, and
date questions, and to texts entered in Other boxes. However, although the properties and values
that you use for this are the same as for text, the interview scripting language treats these “texts” as
part of the response section of the question. Consequently, the keywords and objects that you use
in specifications are different. You define these characteristics in the metadata section using the
style keyword, and in the routing section using the Style object that is a child of the individual
question object (Age.Style, where Age is the question name, for example). See Colors for
Categorical Response Lists and Display Settings for Respondents’ Answers for more information.
746
Chapter 1
Colors
Question, categorical response, and information texts have two colors associated with them: the
color of the text itself and the background of the area that the text covers. The following example
shows blue question text on a yellow background:
Figure 1-114
Question with blue question text on a yellow background
In the Metadata Section
To define text colors in the metadata section, include the following element as part of the question,
response, or information text definition:
labelstyle([color = "TextColor"][, bgcolor = "TextBgColor"])
where:
TextColor is the color for the text.
TextBgColor is the color for the text background.
You can specify colors using names or RGB values entered in hexadecimal format. The previous
illustration was created by the statement:
Sports1 "Which of the following sports do you play?"
labelstyle(color = "blue", bgcolor = "yellow") categorical [1..]
{Tennis, Football, Cricket, Basketball, Hockey};
This is the same as writing:

labelstyle(color = "#0000FF", bgcolor = "#FFFF00") categorical [1..]
For a complete list of the color names that you can use and their equivalent RGB (hexadecimal)
values, refer to your HTML documentation.
You use the same syntax when you want to define colors for response texts, except that you
place the labelstyle element next to the response text that it refers to. For example:
Sports3 "Which of the following sports do you play?" categorical [1..]
{
Tennis labelstyle(color = "blue", bgcolor = "yellow"),
Football labelstyle(color = "red"),
Cricket labelstyle(color = "green"),
Basketball labelstyle(bgcolor = "pink"),
Hockey labelstyle(color = "blue")
};
747
Base Professional
produces the following page:

Figure 1-115
Question with response texts in different colors and with different backgrounds
Notice that the color and bgcolor parameters can be used independently to control just the text
or text background color. If a parameter is not defined, the default color is used. The system
defaults are black text on a white background but you can set different defaults using default
styles or templates.
The settings for one response do not carry over onto subsequent responses: if consecutive
responses use the same color scheme, you may do any of the following:
Enter a separate labelstyle keyword for each response.
Specify the colors for the response control as a whole using the style keyword after the question
text. For more information, see the topic Colors for Categorical Response Lists on p. 755.
Define colors in the routing section.
In the Routing Section
In the routing section, any statement to do with text defined in the script uses the Label object in
the Interview Object Model in some way. The sort of text that the Label object refers to depends
on the object to which it is attached (its parent object). Anything to do with the visual appearance
of an item on the page is controlled by the Style object, so any statement to do with the visual
appearance of questionnaire text will always include the notation Label.Style.
Question and information text
To define the color of a question or information text, type:
Qname.Label.Style.Color = "color"
To define the background color of a text, type:
Qname.Label.Style.BgColor = "color"
where:
Qname is the name of the question or information item.
color is the name or hexadecimal RGB value of the color you want to use.
748
Chapter 1
The statements to produce blue question text on a yellow background, as shown in the earlier
illustration, are:
Sports.Label.Style.Color = "blue"
Sports.Label.Style.BgColor = "yellow"
Categorical response texts
To define colors for categorical response texts, type:

Qname.Categories[{Name}].Label.Style.Color = "color"
Qname.Categories[{Name}].Label.Style.BgColor = "color"
where:
Name is the name of the response whose color you are defining. If you want to apply the same
setting to all categorical response texts in a list, you can replace the [{Name}] notation
with [..].
color is the name or hexadecimal value of the color you want to use.
Here are some examples. The first one displays blue response texts on a yellow background:
Sports.Categories[..].Label.Style.Color = "blue"
Sports.Categories[..].Label.Style.BgColor = "yellow"
Figure 1-116
Blue response texts on a yellow background
The next example replicates the earlier example in which each response text has a different color
and background color.
Sports.Categories[{Tennis}].Label.Style.Color = "blue"
Sports.Categories[{Tennis}].Label.Style.BgColor = "yellow"
Sports.Categories[{Football}].Label.Style.Color = "red"
Sports.Categories[{Cricket}].Label.Style.Color = "green"
Sports.Categories[{Basketball}].Label.Style.BgColor = "pink"
Sports.Categories[{Hockey}].Label.Style.Color = "blue"
Typeface
The typeface is the name of the font you want to use, such as Arial, Arial Black, Times, or
Palatino. The interview scripting language calls the typeface the font family.
749
Base Professional
There are many different font families available, but since the font must exist on the
respondent’s machine, it is probably best to stick to common fonts such as Arial or Times.
Alternatively, provide one of these as an alternative that can be used if the respondent’s machine
does not have the main font you have chosen. (If you are using Internet Explorer you can find out
the names of the fonts available with your browser by selecting Tools>Internet Options and then
clicking the Font button on the General tab.)
To specify the font family for an information, question, or categorical response text, include the
following element as part of the question or response definition:
labelstyle(font(family = "name1[,name2, ...namen]"))
where:
name1 to namen are font family names. Names containing spaces must be enclosed in single
quotation marks.
When you name more than one family, the interviewing program passes them to the respondent’s
browser in the order they appear in the scrip. The browser reads the names from left to right, and
stops when it finds a font that exists. So, for example, if you want to display the Sports question
text in either Palatino Linotype, Garamond, or Times New Roman, you would type:

labelstyle(font(family = "'Palatino Linotype', Garamond, 'Times New Roman'"))
categorical [1..]
If the browser supports Palatino Linotype, it will display this question as:
Figure 1-117
Question text in Palatino, response texts in Arial
To set the font family in the routing section of the script, type:
ObjectName.Label.Style.Font.Family = "name1[, name2, ... namen]"

750
Chapter 1
where:
ObjectName is the object name of a question, category (response), or information item.
name1 to namen are font family names. Names containing spaces must be enclosed in single
quotation marks.
To produce the previous illustration you could type:
Sports.Label.Style.Font.Family = _
"'Palatino Linotype', Garamond, 'Times New Roman'"
For categorical responses, this refers to the response control as a whole. An alternative that
refers just to the categorical response texts is:
Sports.Categories[..].Label.Style.Font.Family = _
"'Palatino Linotype', Garamond, 'Times New Roman'"
Size
Font sizes are defined in points, and there are 72 points to one inch. Depending on which font
family you use, text at, say, 10-point in one font may look larger or smaller than the same size
text in a different font.
To set the font size for an information, question, or categorical response text in the metadata
section, include the following element in the item’s definition:
labelstyle(font(size = number))
where:
number is the point size you want to use.
For example:
labelstyle(font(size = 16)) categorical [1..]
displays the question text in 16-point, as shown below:

Figure 1-118
Question text in 16-point type
751
Base Professional
Setting the font size in the routing section lets you change the size of question and categorical
response texts and other texts such as banners. Font size is a property of the Font object, so
you type:
ObjectName.Label.Style.Font.Size = number
where:
ObjectName is the name of a question, category (response), or information item.
For example:
to make the question text for the Sports question 16-point.
Effects
Font effects refer to the appearance of the text; that is, whether it is bold, italicized, underlined,
and so on.
To define font effects for an information, question, or categorical response text, include the
following in the item’s definition:
labelstyle(font(variable1 = value1 [, ... variablen = valuen]))
where:
variable1 to variablen are the names of boolean variables representing the effects.
value1 to valuen are True to switch the effect on or False to switch it off.
The boolean variables associated with setting font effects in the metadata section are:
IsBold Bold text.
IsItalic Italic text.
IsOverline Text with a line above it.
IsStrikethrough Text with a line through it.
IsSubscript Subscripted text.
IsSuperscript Superscripted text.
IsUnderline Underlined text.
752
Chapter 1
If the Sports question is defined as:

labelstyle (font(IsBold = True)) categorical [1..]
{
Tennis labelstyle(font(IsItalic = True)),
Football labelstyle(font(IsItalic = True)),
Cricket labelstyle(font(IsItalic = True)),
Basketball labelstyle(font(IsItalic = True)),
Hockey labelstyle(font(IsItalic = True))
};
the question text will be displayed in bold and the categorical response texts will be italic,
as shown below:
Figure 1-119
Bold question text and italic categorical response texts
You can define any number of effects for a single text by listing the variable and value pairs one
after the other, separated by commas, inside the font parentheses. The statement:

labelstyle(font(IsBold = True, IsItalic = True)) categorical [1..]
displays the question text in bold italics and the response texts in the default font.
There are other font settings you can make with labelstyle(font(...)), and you can combine
these with font effects. For example:

labelstyle(font(IsBold=True, Size=12, Family="Times")) categorical [1..]
displays the question text in a bold, 12-point, Times font. See Size and Typeface for details
about these parameters.
You define font effects in the routing section using the Font.Effects property of the Style object.
Question, Category (response), and Info (used for banner texts) objects have a Style object, so
the statement you would write is as follows:
ObjectName.Label.Style.Font.Effects = FontEffects.effect
753
Base Professional
where:
ObjectName is the name of a question, category (response), or information item.
effect is the effect that you want to apply to the named object, and is one of:
feBold Bold text.

feItalic Italic text.
feOverline Text with a line above it.
feStrikethrough Text with a line through it.
feSubscript Subscripted text.
feSuperscript Superscripted text.
feUnderline Underlined text.
For example:
Sports.Label.Style.Font.Effects = FontEffects.feBold
displays the question text of the Sports question in bold, and:

Sports.Categories[..].Label.Style.Font.Effects = FontEffects.feItalic
displays the categorical response texts in italic.

You can combine font effects to produce, say, bold, italic or subscripted, underlined text. The
easiest way to do this, is to list the font effects you want to apply, separated by plus signs; for
example:
for bold italic question text. If you have a default style that uses a combined font effect, you can
remove an effect, say, to use italic rather than bold italic text, by subtracting the font you do
not wish to use.
To turn off or override a default font effect, set Font.Effects to False, Null, or zero.
Combining Font Settings in the Metadata Section
If you are specifying styles in the metadata section, you can save yourself typing by combining
font family, size, and effect parameters in a single font instruction. For example:
labelstyle (font (Family = "'Palatino Linotype', 'Times New Roman'",
Size = 16, IsBold = True, IsItalic = True)) categorical [1..]
754
Chapter 1
produces:
Figure 1-120
Palatino, 16-point, bold, italic question text
The equivalent routing statements are:
Sports.Label.Style.Font.Family = "'Palatino Linotype', 'Times New Roman'"

which can also be written as:
With Sports.Label.Style.Font
.Family = "'Palatino Linotype', 'Times New Roman'"
.Size = 16
.Effects = FontEffects.feBold + FontEffects.feItalic
End With
Categorical Response Lists
There are a number of layout characteristics you can set for categorical response lists besides
changes to the individual response texts. You can specify any of the following:
Colors — the foreground (text) and background colors for the response block as a whole. For more
information, see the topic Colors for Categorical Response Lists on p. 755.
Display method — whether the responses appear as texts with radio buttons or check boxes, or
in some other format. For more information, see the topic Display Methods for Categorical
Response Lists on p. 756.
Orientation — whether the responses are displayed in columns down the page or in rows across the
page. For more information, see the topic Rows or Columns, and How Many? on p. 760.
Number of rows or columns. For more information, see the topic Rows or Columns, and How
Many? on p. 760.
Indentation — how far the response list is indented relative to the question text. For more
information, see the topic Indenting Response Lists on p. 763.
You can specify all these requirements in the metadata section using the style keyword, or in the
routing section using the question’s Style object.
755
Base Professional
Colors for Categorical Response Lists
You can specify the foreground and backgrounds color for a complete categorical response block.
The foreground color is applied to the response texts and the background color is applied to
the whole area covered by the response block.
Place the following element after the question text:

style([color = "TextColor"][, bgcolor = "BlockBgColor"])
where:
TextColor is the color for the response texts.
BlockBgColor is the background color for the response block.
For example:
style(color = "blue", bgcolor = "yellow") categorical [1..]
produces:
Figure 1-121
Blue response text on yellow response block background
Compare this with the examples that use labelstyle instead of style you’ll see that the yellow
background now applies to the whole of the response list not just to the text.
Note: You cannot change the color of check boxes or radio buttons.

Type:
Qname.Style.Color = "color"
Qname.Style.BgColor = "color"
The statements:
Sports.Style.Color = "blue"
Sports.Style.BgColor = "yellow"
produce the same output as shown above.

756
Chapter 1
Display Methods for Categorical Response Lists
Categorical responses are normally displayed one per line preceded by a check box (multiple
choice) or radio button (single choice), but you can display them as a drop-down list or list box.
Drop-down lists allow respondents to choose one answer only and are therefore ideal for single
choice lists. If a respondent selects a second answer, that selection replaces the previous selection.
List boxes allow any number of selections so are best for multiple choice lists. Respondents select
answers using standard Windows selection methods.
Note: Drop-down lists and list boxes do not support “other specify” responses (that is, a
response with the other keyword) because they cannot display the additional input box for the
other response. You can get around this problem by defining an ordinary Other response and then
defining an additional “Please specify” question that is asked only of people choosing Other.
With single-choice lists you also have the option of displaying the responses as buttons.
Respondents then click a button to choose a response and move to the next question. There is
no need to click Next.
The response part of a question is known generically as the Control, so the way the response
section or control is displayed is referred to as the Control Type. You define it using the control
keyword in the metadata section or the question’s Control.Type property in the routing section.
To display responses in a drop-down list or a list box, place the following after the question text:
style(control(type = "CType"))
where:
CType is either DropList or ListBox.
For example, if you type:
FavoriteSport1 "Which sport do you like best?"
style(control(type = "droplist")) categorical [1..1]
the question will be displayed as:

Figure 1-122
Initial display for a drop-down response list
757
Base Professional
When the respondent clicks the arrow button at the side of the box, the full response list is
displayed:
Figure 1-123
Expanded display for a drop-down response list
A similar question displayed as a list box — style(control(type = "listbox")) — is:

Figure 1-124
Categorical responses displayed in a list box
If you want buttons in a single-choice response list, type:

style(control(type = "button"))
after each response text that you want displayed in this way. For example:
FavoriteSport2 "Which sport do you like best?" categorical [1..1]
{
Tennis style(control(type = "button")),
Football style(control(type = "button")),
Cricket style(control(type = "button")),
Basketball style(control(type = "button")),
Hockey style(control(type = "button"))
};
758
Chapter 1
This produces:
Figure 1-125
Categorical responses displayed as buttons
As the illustration shows, the interviewing program makes each button just as wide as is necessary
to contain the response text. You can often improve the appearance of the page by making all
buttons the same width. To do this, include the width keyword to specify the width for each
button, and the interviewing program will display the response texts centrally on each button. For
example:
style(control(type = "button"), width="20em")
For further information about width see Input Box IBM SPSS Data Collection and Navigation
Buttons.
To specify a question’s control type in the routing section, type:

Qname.Style.Control.Type = ControlTypes.Type
where:
Type is a keyword defining the control type, and is either ctDropList or ctListBox.
The previous examples could be specified in the routing section as:
FavoriteSport.Style.Control.Type = ControlTypes.ctDropList
Sports.Style.Control.Type = ControlTypes.ctListBox
For buttons, type:

Qname.Categories[{RespName}].Style.Control.Type = ControlTypes.ctButton
where:
RespName is the name of a response in the list. Use [..] to refer to all responses.
For example:
FavoriteSport2.Categories[..].Style.Control.Type = ControlTypes.ctButton
759
Base Professional
For information about displaying images as buttons rather than using the response texts see
Images as Buttons (Clickable Images).
Instructions and subheadings in drop-down lists
If a drop-down list contains nested responses (that is, responses at different levels) the interviewing
program decides whether to treat the top-level responses as subheadings or as instructions.
If the list contains only one top-level text followed by one subgroup of responses, the top-level
text is treated as an instruction text. It is displayed in the same typeface as the rest of the list; it
appears as the default answer when the question is first displayed, and can be selected in the same
way as any other response in the list. For example, if the question is defined as:
{
FS3Instruct "--Select--"
{
Tennis, Football, Cricket, Basketball, Hockey
}
};
it is displayed with “−−Select−−” as the default answer, and respondents may select any response
from the list (the routing section should reject “−−Select−−” if it is chosen).
Figure 1-126
Drop-down list with instruction text
If the list contains two or more top-level texts each followed by a subgroup of responses,
the top-level texts are treated as subheadings. They are displayed in a different typeface to the
rest of the list (the default is bold italic). Subheadings cannot be selected, so the first response
in the first subgroup is presented as the default answer when the question is first displayed. For
example, if the question is defined as:
{
Land
{
Tennis, Football, Cricket, Basketball, Hockey
},
Water
{
Swimming, Diving, Scuba, Sailing,
Waterski "Water ski-ing"
}
};
it is displayed with Tennis as the default answer. Land and Water appear in the list in bold italics
but cannot be selected.
760
Chapter 1
Figure 1-127
Drop-down list with subheadings
Rows or Columns, and How Many?
The default is to display categorical responses one below the other in a single column down the
page. With long response lists you can save space, and save respondents having to scroll to reach
the navigation buttons, by displaying the response list in more than one column. Even with
short response lists you can save space by displaying the responses across the page rather than
down. You may even find that the way you display the responses affects which responses are
most likely to be chosen.
To specify the orientation of the response list, place the following after the question text:
style(orientation = Direction)
where:
Direction is either Column, Row, or Default (the default category orientation by the
Player).
When you choose row orientation and do not define the number of rows required, the interviewing
program displays all responses on a single line, and attempts to space the responses evenly within
the line width. If you reduce the size of the display window you will see that the responses’
positions alter so that they still fit within the window’s width. When it is no longer possible to
reduce the spacing between responses, a horizontal scroll bar is displayed.
To specify the number of rows or columns, place one of the following after the question text:
style(columns = Number)
style(rows = Number)
where:
Number is the number of rows or columns required.
For example:
style(orientation = column, columns = 2) categorical [1..]
761
Base Professional
displays the responses column-wise in two columns:

Figure 1-128
Two-column columnwise display
whereas:
style(orientation = row, rows = 2) categorical [1..]
displays the responses row-wise in two rows:

Figure 1-129
Two-row row-wise display
762
Chapter 1
To set the response list orientation in the routing section, type:

Qname.Style.Orientation = Orientations.Direction
where:
Direction is one of orColumn, orRow, or orDefault (the default orientation used by
the Player).
To set the number of rows or columns, use
Qname.Style.Rows = Number
Qname.Style.Columns = Number
If the question is defined as:

Sports "Which of the following sports do you play?" categorical [1..]
the statements:
Sports.Style.Orientation = Orientations.orRow
Sports.Style.Rows = 3
will display the response list across the page in three rows:
Figure 1-130
3-row row-wise display
If You Don’t Get What You Asked For
Sometimes it may seem that the interview scripting program is ignoring your instructions for the
number of rows or columns required. This is often because your specification does not work well
with the number of responses in the response list. When the interviewing program lays out a
response list in columns, it counts the number of responses to be displayed and then works out
how many rows it will need to display those responses in the requested number of columns. It
then fills those rows on a column-by-column basis. Depending on how many responses there are
in the list, this many mean that you get fewer columns than you requested.
For example, if the response list contains 26 responses and you ask for it to be displayed
columnwise in 25 columns, the interview scripting program calculates that it needs two rows to do
this. It then starts allocating responses to columns, filling one column before starting the next one.
This means that responses 1 and 2 go into columns 1, responses 3 and 4 go into column 2, and so
on until responses 25 and 26 go into column 13.
763
Base Professional
You cannot mix and match row and column orientation with row and column counts. For
example, you cannot set the orientation to columns and then specify the number of rows required.
The interviewing program will display the response list in one column; it will not display the
responses column-wise in the given number of rows. Therefore, you have two options for resolving
the problem. Either, you can calculate for yourself the number of rows that will be required and
then specify row orientation and the number of rows required to generate the number of columns
you want. In the example, you will need to specify two rows laid out in row orientation. This lays
out responses sequentially across the page, with responses 1 to 13 in row 1 and 14 to 26 in row 2.
Or, if you must have responses listed down the page, you can reduce the number of columns.
Indenting Response Lists
You can indent the response list by a fixed amount relative to the question text (the parent of the
response list). The following example uses an indent of 3; compare it with the default indent
of 1 used in the illustrations in other topics:
Figure 1-131
Categorical response list indented by 3
Exactly how far an indentation instruction indents depends on which Player you are using to
run interviews. The HTML Player uses the margin-left HTML style to calculate the amount
of indentation. See http://www.w3.org/TR/REC-CSS1 (http://www.w3.org/TR/REC-CSS1) for
details. As a general rule, an indent setting with no measurement unit (as in the example) is
assumed to be in ems, where 1em is the height of the element’s font.
To set the indent in the metadata section, place the following after the question text:
style (indent = distance)
To set the indent in the routing section, type:
Qname.Style.Indent = distance
where:
distance is a number optionally followed by a unit of measurement. Valid units are inches
(in), centimeters (cm), millimeters (mm), points (pt), ems (em), and pixels (px). The default is
ems. Measurements may be negative (in fact, an indent of −1 is required to line the response
list up with the start of the question text).
764
Chapter 1
Note: You cannot override the default indent simply by using a layout template that lines up the
response list with the question text (see Laying Out the Components of a Question for details).
The default indentation is applied on top of the template’s settings. Always set the indentation to 0
(or even −1) in the script if you do not want response lists indented.
Indentation is particularly useful when displaying two or more questions on the same line, as
you might do when replicating forms. The first question on the line is the parent of the next
question, so one way of inserting space between the two questions is to specify an indent as part of
the style for the second question. . If the questions are defined as:
Title1 "Title"
labelstyle(width="5em")
style(elementalign="right", control(type="droplist"))
categorical [1..1]
{Ms, Miss, Mrs, Mr};
FirstName1 "First Name"
style(elementalign="right")
text [0..40];
Initials1 "Middle Initials"
labelstyle(elementalign="right", indent=2, width="6em")
style(elementalign="right", width="5em")
text [0..40];
LastName1 "Last Name"
style(elementalign="right", width="13.5em")
text [0..40];
FullName1 "" page(Title1, LastName1, FirstName1, Initials1);
and you use a template that places more than one question on a line, the output might look
as follows:
Figure 1-132
Title & last name on one line with first name & middle initials on the next line
Without the indentation there would be no space between the LastName and Initials question
texts and the preceding input boxes.
Selection Boxes for Categorical Responses in Non-Categorical Lists
When a numeric, date, or text question has a codes() section that defines categorical responses
such as no answer or don’t know, the interviewing program displays those responses with check
boxes for selection. You can replace the check boxes with radio buttons if you wish. In the
metadata section, place the following after the categorical response texts you want to change:
style(control="Type")
where:
Type is either RadioButton or CheckButton as appropriate.
765
Base Professional
For example:
codes (
{
NoAnswer "No answer" style(control="RadioButton") na
}
);
displays a radio button for No Answer rather than the usual check box.
Note: While a radio button makes it clear that the response is a single-choice response, it has
the disadvantage that, once selected, it cannot be deselected. With a check box, respondents can
deselect a response by clicking on it. This is not possible with radio buttons.
Figure 1-133
Numeric response with radio button for No Answer
Input Boxes for Numeric, Text, Date, and Other Specify Responses
Questions with numeric, text, or date responses display an input box in which respondents may
type their answers. The standard input box for numeric and date questions is a single line of 20
characters (scrollable to 40 characters for dates). The input box for text questions shows six rows
of 34 characters each, although respondents may scroll to enter more text if necessary.
Other Specify responses defined with the keyword other also display input boxes. These boxes
display a single line 21 characters wide but scroll to the left so that longer texts can be entered.
You can change the following things about input boxes:
Background Color — Set the background color of the input box. For more information, see the
topic Box Color on p. 766.
Input color and font settings — Define the color, size, and typeface in which to display respondents’
input, and the font effects to be applied. For more information, see the topic Display Settings for
Respondents’ Answers on p. 768.
IBM® SPSS® Data Collection — This is most useful for text responses because it may encourage
respondents to type more detailed answers than they would do when presented with a smaller input
box. However, it is still useful for numeric and date questions if you are displaying answers in a
large font. For more information, see the topic Input Box IBM SPSS Data Collection on p. 771.
Note: Changing the dimensions of an input box does not allow respondents to enter more text
than is allowed by the length specification on the question definition. With numeric and date
questions, respondents can still only enter values that satisfy the question specification.
Display method — for text responses, whether the input box covers one or many lines. For more
information, see the topic Types of Text Input Boxes on p. 774.
766
Chapter 1
About Input Boxes for Other Specify Responses
Other Specify responses are different to all other responses in a response list because they have a
selection button and an input box. The selection button belongs to the Other response whereas the
input box belongs to a hidden, automatically generated question attached to the Other response. If
you do not want to change the way the automatic question behaves you can ignore the fact that it
exists at all, because the interviewing program will do everything that needs to be done.
If you want to change the behavior or characteristics of the automatic question you must enter
its full definition as part of the specification for the Other response. For example:
MoreTV "Which sport would you like to see more of on TV?" categorical [1..1]
{
Swimming, Diving, Polo, Curling, Windsurfing,
OtherSport "Other sport" other
(MoreTVOthQ "Please specify." style(...) text)
};
Here, MoreTvOthQ is the name that you want to assign to the automatic Other Specify question,
and text is the question’s type. You can specify any valid question type here, although text is the
usual choice because this imposes no restrictions on what respondents can type. Any question text
that you specify is appended to the main response text defined for the Other response.
The style parameter is optional and defines the appearance of the input box. If you prefer to
specify layout characteristics in the routing section, use the OtherQuestion object which is a child
of the Category object. Both methods are described in the following sections.
Box Color
Numeric, Text, and Date Questions
Input boxes are normally white. To display input boxes for numeric, text, or date questions in a
different color, do one of the following. Either place the element:
style(bgcolor = "color")
after the question text in the metadata section, or type:
Qname.Style.BgColor = "color"

color is the background color for the box, specified as a text or RGB value.
For example:
DOB1 "Please enter your date of birth." style(bgcolor = "pink") date;

767
Base Professional
Figure 1-134
Pink input box for numeric question
If the question did not define the background color, it could have been set in the routing section
with:
DOB.Style.BgColor = "pink"
Other Specify Responses
To set the background color for the Other Specify box in the metadata section, define the Other
response as follows:
OthRespName ["RespText"] other
(OthQname "OthQtext" style(bgcolor = "color") Qtype)
where:
OthRespName is the name of the Other response.
RespText is the text of the Other response.
OthQname is the name for the automatic Other Specify question.
OthQtext is the text for the automatic Other Specify question.
color is the background color entered as a text or RGB value.
Qtype is the data type for the automatic Other Specify question (usually text).
For example:
MoreTV1 "Which sport would you like to see more of on TV?" categorical [1..1]
{
(MoreTVOthQ "Please specify." style(bgcolor = "#C0FFFF") text)
};
768
Chapter 1
Figure 1-135
Pale green Other Specify input box
To define the box’s background color in the routing section, type:

Qname.Categories[{OtherName}].OtherQuestion.Style.BgColor = "color"
where:
color is the background color for the box, specified as a text or as an RGB value.
OtherName is the name of the Other Specify response.
To produce the pale green box shown in the previous illustration you would type:
MoreTV.Categories[{OtherSport}].OtherQuestion.Style.BgColor = "#C0FFFF"
Display Settings for Respondents’ Answers
You can set the color, background color, typeface, size, and font effects for the answers that
respondents type into input boxes. The syntax in both the metadata and routing sections is similar
to that used for specifying the same settings for question texts, except that you use the style
keyword and Style object instead of labelstyle and Label.Style.
To specify settings for respondents’ answers to numeric, text, and date questions, place the
following element after the question text:
style([color = "TextColor"][, bgcolor = "TextBgColor"]
[, font([family = "name"][, size = number][, effect=value])])
where:
TextColor is the color in which to display the answer.
TextBgColor is the background color for the respondent’s answer.
name is a font family name. Names containing spaces must be enclosed in single quotation
marks. You may specify lists of names by separating the names with commas. The
interviewing program will scan the list in order and will use the first fonts that it finds in
the respondent’s browser.
769
Base Professional

effect is the name of a boolean variable associated with a particular font effect and is one of:
IsBold Bold text.

IsItalic Italic text.
IsOverline Text with a line above it.
IsStrikethrough Text with a line through it.
IsSubscript Subscripted text.
IsSuperscript Superscripted text.
IsUnderline Underlined text.
value is True to switch the effect on or False to switch it off.
Here are some examples:
DOB2 "Please enter your date of birth." style(color = "red") date;
Figure 1-136
Date response in red
DOB3"Please enter your date of birth."

style(font(family = "'Arial Black'")) date;
Figure 1-137
Numeric response in Arial Black typeface
For Other Specify responses, place the element after the text for the additional question. For
example:
{
(MoreTVOthQ ". Please specify." style(color="green", font(IsItalic="True")) text)
};
to display whatever the respondent types in green italics. For more information, see the topic
About Input Boxes for Other Specify Responses on p. 766.
770
Chapter 1
If you want to use a different color for answers that the respondent enters for numeric, text,
and date questions, or if you want the specification to apply to a complete categorical response
block, type:
Qname.Style.property = value
where:
property is the name of the property you want to set and is one of Color, BgColor,
Font.Family, Font.Size, or Font.Effects as described above.
value is an appropriate value for the property as described above.
The statement:
DOB.Style.Color = "red"
displays the date of birth that the respondent enters in red as shown above, while:
DOB.Style.Font.Effects = FontEffects.feBold
displays it in bold.
To specify settings for Other Specify responses, type:
Qname.Categories[{OtherName}].OtherQuestion.Style.property = value
where:
OtherName is the name of the Other Specify response.
property is the name of the property you want to set and is one of Color, BgColor,
Font.Family, Font.Size, or Font.Effects as described above.
value is an appropriate value for the property as described above.
MoreTV "Which sport would you like to see more of on TV?" categorical [1..1]
{
};
MoreTV.Categories[{OtherSport}].OtherQuestion.Style.Color = "green"
771
Base Professional
the respondent’s Other Specify answer would be shown as follows:

Figure 1-138
Question with green other specify answer text
Similarly:
MoreTV.Categories[{OtherSport}].OtherQuestion.Style.Font.Effects = _
FontEffects.feBold+FontEffects.feItalic
shows the respondent’s Other Specify answer in a bold italic font:

Figure 1-139
Question with bold italic other specify answer text
Input Box IBM SPSS Data Collection
The standard input box for numeric and date questions is a single line of 20 characters (scrollable
to 40 characters for dates). The input box for text questions shows six rows of 34 characters each,
although respondents may scroll to enter more text if necessary. Boxes for Other Specify text
display a single line 21 characters wide but scroll to the left so that longer texts can be entered.
To specify the dimensions of the input box for a numeric, text, or date question in the metadata
section, place the following after the question text:
style([height="high"][, width="wide"]])
772
Chapter 1
where:
high is the height of the box.
wide is the width of the box.
You may specify dimensions in any suitable recognized unit of measurement you wish. Typical
examples are inches (in), millimeters (mm), centimeters (cm), points (pt), pixels (px), or ems
(em). The default is pixels.
An em is a printing term meaning a space the width of the letter “m” in the current font. It
is a convenient unit to use if you want to use different templates with the same questionnaire,
since it ensures that the dimensions of the input box are always relative to the font size. If one
template uses a larger font that the other, you will not need always to make the boxes big enough
to accommodate text in the larger font, or to change the box sizes when you change templates.
Compare the two question definitions and illustrations shown below. The specification for the
input box dimensions is the same; only the font size has changed.
The first definition is:
Name1 "What is your name?"

style(height = "1.5em", width = "20em", font(size = 10))
text [1..30];
Figure 1-140
1.5em x 20em box for 10-point text
The second definition is:
Name2 "What is your name?"

style(height = "1.5em", width = "20em", font(size = 14))
text [1..30];
Figure 1-141
1.5em x 20em box for 14-point text
To specify the dimensions of an Other Specify box in the metadata section, define the Other
response as follows:
OthRespName ["RespText"] other

(OthQname "OthQtext" style([height="high"][, width="wide"]])
773
Base Professional
where:
OthRespName is the name of the Other response.
RespText is the text of the Other response.
OthQname is the name for the automatic Other Specify question.
OthQtext is the text for the automatic Other Specify question.
Qtype is the data type for the automatic Other Specify question (usually text).
high is the height of the box.
wide is the width of the box.
You may specify dimensions in any suitable recognized unit of measurement you wish. Typical
examples are inches (in), millimeters (mm), centimeters (cm), points (pt), pixels (px), or ems
(em). The default is pixels.
For example:
{
(MoreTVOthQ ". Please specify." style(height = "1.5em", width = "15em") text)
};
To specify the dimensions of numeric, text, or date input boxes in the routing section, type:
Qname.Style.Width = "wide"
Qname.Style.Height = "high"
where:
wide and high are as previously documented.
For example:
Name.Style.Height = "1.5em"
Name.Style.Width = "20em"
To specify the dimensions of Other Specify input boxes in the routing section, type:
Qname.Categories[{OtherName}].OtherQuestion.Style.Width = "wide"
Qname.Categories[{OtherName}].OtherQuestion.Style.Height = "high"
where:
OtherName is the name of the Other response.
wide and high are as previously documented.
For example:
MoreTV.Categories[{OtherSport}].OtherQuestion.Style.Width = "15em"
MoreTV.Categories[{OtherSport}].OtherQuestion.Style.Height = "1.5em"
774
Chapter 1
This can also be written as:

With MoreTV.Categories[{OtherSport}].OtherQuestion.Style
.Width = "15em"
.Height = "1.5em"
End With
Types of Text Input Boxes
Text input boxes normally show six rows of 34 characters each, and respondents may scroll to
enter more text if necessary. You can replace this with a single-line box that scrolls to the right
as the respondent types. If the script prompts respondents for sensitive information such as a
password or account number, you can request a single-line box that displays dots instead of
the characters the respondent types.
The display method is referred to as the Control Type and is defined using the control
keyword in the metadata section or the question’s Control.Type property in the routing section.
To determine the type of text input box displayed, place the following after the question text:
style(control(type = "CType"))
where:
CType is one of Edit, SingleLineEdit, MultiLineEdit (the default), or Password.
An Edit box is a text input box whose dimensions vary automatically according to the expected
length of the text. If the expected length is 40 characters or fewer, a single-line box is displayed; if
the expected length is greater than 40 characters, an multiline edit box is displayed.
A Password input box is ideal for sensitive information. For example, if you type:
SecCode1 "Please enter your security code."
style(control(type="Password")) text [1..10];
the interviewing program draws a single-line input box and displays the respondent’s security
code as one dot for each character typed. The security code appears in the data file exactly as the
respondent typed it.
Figure 1-142
Password text box
To specify a question’s control type in the routing section, type:

Qname.Style.Control.Type = ControlTypes.Type
775
Base Professional
where:
Type is a keyword defining the control type, and is either ctEdit, ctSingleLineEdit,
ctMultiLineEdit, or ctPassword.
The previous example could be specified in the routing section as:
SecCode.Style.Control.Type = ControlTypes.ctPassword
Styles for Navigation Buttons
You can define styles for navigation buttons in the routing section of the script. You can change
any or all of the following characteristics:
Text color, typeface (font family), size, and effect
Button color
Button border style and color
Button dimensions
Whether a button is visible or hidden
All statements that specify styles for navigation buttons must have the following structure:
IOM.Navigations[NavigationTypes.Type].Style.property = value
where:
Type is the name of the button whose style you are defining. The names for the
standard navigation buttons are as follows: nvNext, nvPrev, nvStop, nvFirst, nvLast, and
nvGoto. If you want to apply the same setting to all navigation buttons, you can replace
[NavigationTypes.Type] with [..].
property is the name of the style property to be set. In some cases this will be a simple name
whereas in others it will be an object name and property name combination.
value is the setting for the property.
The property names (characteristics) that you can define for navigation buttons are as follows:
Property name Description Value
BgColor Button color A color name or hexadecimal
RGB value enclosed in
double quotation marks. See
http://www.w3schools.com/html/html_colornames.asp
(http://www.w3schools.com/html/html_colornames.asp)
for a list of the color names and
their equivalent RGB values.
Color Text color As for BgColor.
Height Button height A number followed by a unit of
measurement. Valid measurement
units include inches (in),
millimeters (mm), centimeters
(cm), points (pt), pixels (px), or
ems (em). The default is pixels.
Width Button width As for Height.
776
Chapter 1
Property name Description Value

Cell.BorderColor Button border color As for BgColor.
Cell.BorderStyle Button border style BorderStyles.bstyle, where
bstyle is one of bsDouble,
bsGroove, bsInset, bsNone,
bsOutset, bsRidge, or bsSolid.
See Cell Borders for examples of
these styles.
Cell.BorderWidth Button border width A number that is read as a
measurement in pixels.
Font.Family Text typeface One or more font names separated
by commas, with the whole list
enclosed in double quotation
marks. Names containing spaces
must be enclosed in single
quotation marks. The browser
uses the first listed font that it
finds.
Font.Size Text size A number that is the point size for
the text.
Font.Effects Text effects FontEffects.effect,
where effect is one of
the following: feBold,
feItalic, feOverline,
feStrikethrough, feSubscript,
feSuperscript, or
feUnderline. To apply
multiple effects, list the effects
separated by plus signs.
Hidden Whether to hide the button. True to hide the button or False
to display it.
Text on Navigation Buttons
The rules for setting styles for the text on navigation buttons are similar to those for setting
styles for categorical response texts, except that you use IOM.Navigations[..] instead of
Qname.Categories[..]. To display the text on all navigation buttons in Tahoma or Trebuchet
MS font, you would type:
IOM.Navigations[..].Label.Style.Font.Family = "Tahoma, 'Trebuchet MS'"
If you want to change the font family for the text on an individual navigation button, you must
name the button using the NavigationTypes type definition. The following example changes
the font family for the Next button only:
IOM.Navigations[NavigationTypes.nvNext].Label.Style.Font.Family = "Arial"
To change the point-size of the text on all navigation buttons, type:

IOM.Navigations[..].Label.Style.Font.Size = 16
Note: You may have to increase the size of the navigation buttons to accommodate the larger
text.
777
Base Professional
You can apply font effects to text on navigation buttons. To underline the text on the Stop button
you would type:
IOM.Navigations[NavigationTypes.nvStop].Label.Style.Font.Effects = _
FontEffects.feUnderline
For information on changing the labels displayed on navigation buttons refer to Navigation
Buttons in the Templates section.
Button Color, Size, and Borders

The following illustration shows a variety of style settings that affect the appearance of the
navigation buttons themselves as well as the text displayed on them:
Figure 1-143
Navigation buttons showing use of different colors, font settings, and dimensions
It was created by the following statements:

With IOM.Navigations[NavigationTypes.nvPrev].Style
.BgColor = "yellow"
.Color = "green"
.Font.Size = 14
.Width = "6em"
End With
With IOM.Navigations[NavigationTypes.nvNext].Style
.Font.Family = "'Palatino Linotype'"
.Font.Effects = FontEffects.feBold+FontEffects.feItalic
.Cell.BorderStyle = BorderStyles.bsSolid
End With
With IOM.Navigations[NavigationTypes.nvStop].Style
.BgColor = "white"
.Color = "red"
.Cell.BorderColor = "blue"
.Cell.BorderStyle = BorderStyles.bsDouble
.Cell.BorderWidth = 6
.Height = "3em"
.Width = "4em"
End With
Note: For navigation buttons, the following properties produce identical results:
Style.Color and Label.Style.ColorStyle.BgColor and Label.Style.BgColor
Style.Font.Family and Label.Style.Font.Family
Style.Font.Size and Label.Style.Font.Size
Style.Font.Effects and Label.Style.Font.Effects
778
Chapter 1
Grids
In style terms grids have five components: rows, row headings, columns, column headings, and
grid cells (that is, the box formed by the intersection of a row with a column). This section
explains how you can control the overall appearance of a grid. It describes how to:
specify cell background colors
set row height and column width
repeat the header row at various points in the grid
set the color, style, and width of cell borders
define the amount of space around the cell contents
wrap text within a cell
The interviewing program treats the texts that form the row and column headings the same as
categorical responses so you can set styles for those texts just as you do for categorical response
texts. For more information, see the topic Question, Response, and Information Text on p.
745. If you want to set styles for these texts in the routing section, you should also read A
Non-Programmer’s Guide to the Interview Object Model because it explains which objects in the
Object Model refer to which parts of a grid. The diagram from that section is repeated here for
easy reference:
Figure 1-144
Objects used in grids
779
Base Professional
All the examples for grids are based on the following question definition:
Tealist "" define
{
Assam, Darjeeling, Rooibos,
Lapsang "Lapsang Souchong",
Gunpowder, Oolong
};
TeaLoop "In which country or countries are the following
teas produced?" loop
{
use Tealist
} fields
(
Countries "Countries" categorical [1..]
{
China, India, Japan, Kenya,
SouthAfrica "South Africa",
SriLanka "Sri Lanka"
};
) expand;
which, with no styles, displays as follows:

Figure 1-145
Grid with no styles applied
Note: The illustrations and related code snippets in the subtopics have been designed to show
the effect of the keyword or keywords being discussed. In order for the illustrations to be clear
is has sometimes been necessary to apply additional settings such as color or cell size which
are not included in the sample code.
Precendence for Cells with More Than One Style Applied
You can define any number of different styles for grid cells and the interviewing program will
apply them all by adding one style to another. In this way, you can create cells with a pale blue
background and a double dark blue border, and that are 1cm high by 1.5cm wide, and that have
5 pixels’ padding between the borders and the cell contents.
Each cell in a grid has its own set of characteristics that are a combination of the characteristics
of an individual row and column. Sometimes the row and column specifications can conflict so
that, for example, you have a cell where the row color is set to blue and the column color is set to
green. The interview scripting language makes it easy to work out which characteristic the cell
will have because it always applies styles in the order they are defined. So, if the row color is set
last the cell will be blue; if the column color is set last the cell will be green. The same rules apply
780
Chapter 1
to all other characteristics, so it can sometimes be important to specify styles in a particular order
to achieve the results you require.
If a script also defines templates and default styles, any individual style settings override
the templates and default styles for the items concerned. If the same characteristic is specified
in both the metadata and routing sections but with different settings, the specification in the
routing section overrides the metadata definition.
Body Cell Background Color
With grids, the body cell background color is the color of the cells formed by the intersection of a
row response with a column response; it does not apply to the row and column headings nor to
the area of the page covered by the grid table as a whole. Row and column headings are label
texts and are treated the same as any other categorical response texts. For more information, see
the topic Question, Response, and Information Text on p. 745.
You can apply the same color to all body cells or to all the cells in a particular row or column,
and there are commands that make it easy to switch between two colors for alternate rows or
columns. You can also specify colors for individual cells if that is what you want:
Figure 1-146
Grid with different background color in every cell
To set the background color for a body cell within a grid, place the following statement in the
routing section of the script:
Gridname[GridCategory].Qname.Categories[Category].Style.Cell.BgColor = "color"
where:
Gridname is the name of the grid.
GridCategory is the name of a category for which Qname is repeated (that is, one of the
categories named at the start of the grid definition). If the setting applies to all categories,
use [..].
Qname is the name of the repeated question.
Category is the name of a response in Qname’s response list. Use [..] to refer to all
responses.
color is the name or RGB code of the color you want to use. For a complete list of the
color names that you can use and their equivalent RGB (hexadecimal) values, refer to your
HTML documentation.
781
Base Professional
The first row of the illustration was created by the following statements:
With TeaLoop[{Assam}].Countries
.Categories[{China}].Style.Cell.BgColor = "#404000"
.Categories[{India}].Style.Cell.BgColor = "#808000"
.Categories[{Japan}].Style.Cell.BgColor = "#C0C000"
.Categories[{Kenya}].Style.Cell.BgColor = "#FFFF00"
.Categories[{SouthAfrica}].Style.Cell.BgColor = "#FFFF40"
.Categories[{SriLanka}].Style.Cell.BgColor = "#FFFF80"
End With
To set the background color for the cells in the row text column, type:
Gridname.Categories[..].Label.Style.Cell.BgColor = "color"
To set the background color for the cells in the column heading row, type:
Gridname[..].Qname.Categories[..].Label.Style.Cell.BgColor = "color"
For example:
TeaLoop.Categories[..].Label.Style.Cell.BgColor = "#FFC0C0" 'pink
TeaLoop[..].Countries.Categories[..].Label.Style.Cell.BgColor = "#C0FFC0" 'green
Figure 1-147
Grid with pink row text cells and pale green column heading cells
Notice that both statements include the Cell object. This indicates that the color specification
refers to the whole grid cell rather than just to the background color of the text.
Tip: It is the categories of the grid (that is, the categories for which the question is repeated) that
determine how the row labels in a standard grid are presented. It is the responses to the repeated
question that determine how the column labels are presented.
Row Height and Column Width
An easy way to make a grid look less cramped and cluttered is to set your own row height and
column width. Normally, you’ll make all the rows the same height and all the columns the same
width, but the interview scripting language is sufficiently flexible that you can set different row
heights and column widths for each row and column if you wish.
The general syntax for setting row heights and column widths is:
Gridname[GridCategory].Qname.Categories[Category].Style.Cell.Height = "high"
Gridname[GridCategory].Qname.Categories[Category].Style.Cell.Width = "wide"
where:
782
Chapter 1
use [..].
responses.
high and wide are measurements in pixels (px), points (pt), ems (em), inches (in),
centimeters (cm), or millimeters (mm).
For example:
TeaLoop[..].Countries.Categories[..].Style.Cell.Height = "1cm"
TeaLoop[..].Countries.Categories[..].Style.Cell.Width = "1.5cm"
Figure 1-148
Grid with rows 1cm high and columns 1.5cm wide
If you do not allow text wrapping in a heading row or column, the interview program will ignore
any column width you have specified globally or for that column, and will make the column as
wide as is necessary to display the full row or column text all on one line. With row texts, the
row text column will then be as wide as the longest row text. For more information, see the topic
Wrapping Text in Cells on p. 789.
Repeating Header Cells
You can make large grids easier to use by repeating the header cells periodically throughout the
grid. To repeat the column heading row, type:
Gridname.Style.Cell.RepeatHeader = number
where:
Gridname is the name of the loop item.
number is the number of rows you want to display between each repetition of the column
headings. Use 0 to display the column headings at the top and bottom of the grid, or –2 to
display the headings centrally within the height of the grid (that is, with an even number of
783
Base Professional
rows above and below it). To repeat the headings and display them at the bottom of the grid,
use a negative number greater than –2 (for example –4 repeats the headings every four rows
and displays them at the bottom of the grid).
For example:
TeaLoop.Style.Cell.RepeatHeader = 3
Figure 1-149
Grid with header row repeated every three rows
To repeat the column of row headings, type:
Gridname.Style.Cell.RepeatSideHeader = number
where:
Gridname is the name of the loop item.
number is the number of columns you want to display between each repetition of the row
headings. Use 0 to display the row headings on the left and right of the grid, or –2 to display
the headings centrally within the width of the grid (that is, with an even number of columns to
the left and right of it). To repeat the headings and display them on the right of the grid, use a
negative number greater than –2 (for example –4 repeats the headings every four columns
and displays them on the right of the grid).
For example:
TeaLoop.Style.Cell.RepeatSideHeader = 3
Figure 1-150
Grid with header column repeated every three columns
784
Chapter 1
Cell Borders
Borders are the lines that appear around the cells of the grid. To display them, set the
Cell.BorderStyle property to the type of border you want:
Gridname[GridCategory].Qname.Categories[Category].Style.Cell.BorderStyle =
BorderStyles.Type
where:
use [..].
responses.
Type is the border type and is one of:
bsDouble A pair of wide and narrow lines all the way round
the cell.
bsGroove The border looks like a groove cut into the
page.
bsInset The border appears to be set or engraved into the
page.
bsNone No borders. This is the default.
bsOutset The border appears to stand out from the
page.
bsRidge The border looks like a picture frame around the
cell.
bsSolid
A single solid line.
To create a grid in which all body cells are surrounded by a double border you would type:
TeaLoop[..].Countries.Categories[..].Style.Cell.BorderStyle = _
BorderStyles.bsDouble
785
Base Professional
Figure 1-151
Grid with all cells enclosed in double borders
You can set different styles for the four borders of a cell by using the property names
BorderTopStyle, BorderBottomStyle, BorderLeftStyle, and BorderRightStyle
instead of BorderStyle. You might do this when you want a border around the outside of the
grid body cells and no borders between the cells inside the grid. For example:
TeaLoop[..].Countries.Categories[{China}].Style.Cell.BorderLeftStyle = _
BorderStyles.bsSolid
TeaLoop[..].Countries.Categories[{SriLanka}].Style.Cell.BorderRightStyle = _
TeaLoop[{Assam}].Countries.Categories[..].Style.Cell.BorderTopStyle = _
TeaLoop[{Oolong}].Countries.Categories[..].Style.Cell.BorderBottomStyle = _
produces:
Figure 1-152
Grid with outside border only
Notice how the statements for the top and bottom of the grid refer to tea types, while the statements
for the sides of the grid refer to countries. This is because, for the top and bottom of the grid, the
border belongs to all countries (columns) but to only one tea type (row). For the sides of the grid,
the border belongs to all tea types (rows) but only one country (column).
If you use the standard BorderStyle together with any of the more specific settings,
BorderStyle will be used as the default for borders that have no style specifically defined.
786
Chapter 1
Border Color
Having switched on borders, you may want to choose a color to replace the default grey. The
syntax for border color changes is:
Gridname[GridCategory].Qname.Categories[Category].Style.Cell.BorderColor =
"color"
where:
use [..].
responses.
color is the name or RGB value of the border color. For a complete list of the color names
that you can use and their equivalent RGB (hexadecimal) values, refer to your HTML
documentation.
Alternatively, replace BorderColor with one of BorderTopColor, BorderBottomColor,
BorderLeftColor, or BorderRightColor to set the color for a particular border only. If you
use a combination of BorderColor and any of the more specific settings, BorderColor will be
used as the default for borders that have no color specifically defined.
Here is the grid with green double borders. The statement that sets the color is:
TeaLoop[..].Countries.Categories[..].Style.Cell.BorderColor = "#81FF93"
Figure 1-153
Grid with green double border on all cells
787
Base Professional
And here is the same grid with alternating dark and bright green borders for columns:
Figure 1-154
Grid with alternating dark and bright green column borders
The statements that set the colors are:

TeaLoop[..].Countries.Categories[..].Style.Cell.BorderColor = "#05FB05"
TeaLoop[..].Countries.Categories[{China}].Style.Cell.BorderColor = _
"#226E22"
TeaLoop[..].Countries.Categories[{Japan}].Style.Cell.BorderColor = _
"#226E22"
TeaLoop[..].Countries.Categories[{SouthAfrica}].Style.Cell.BorderColor = _
"#226E22"
Notice how the interviewing program deals with borders that are common to two adjacent cells. It
draws the cells for the left-most column in full and then appends whatever borders are required
for the next column, applying the color for the next column only to the borders that it needs to
add. This is why all columns except the first one have only three borders in the specified color. A
similar rule applies to row borders treated in this way. Only the top row has all four borders in the
specified color; other rows have their borders added to what is already there.
Border Width
The final setting you can make for borders is width and, as with style and color, you can define
a global border width and then alter it for individual borders. To specify a border width for
the whole grid, type:
Gridname[GridCategory].Qname.Categories[Category].Style.Cell.BorderWidth =
width
where:
use [..].
responses.
width is the line width in pixels.
788
Chapter 1
To specify individual border widths, replace BorderWidth with one of BorderTopWidth,

BorderBottomWidth, BorderLeftWidth, or BorderRightWidth. If you use a combination
of BorderWidth and one or more of the more specific settings, BorderWidth will be used as
the default for borders that have no width specifically defined.
All the illustrations in this topic have been created using the default width:
TeaLoop[..].Countries.Categories[..].Style.Cell.BorderWidth = 4
If you choose a smaller width, some border styles may not display correctly simply because there
is not enough room for them. For instance, with a width of 1, the bsDouble setting displays a
single line only.
Space Around the Cell Content
With no formatting, the size of each cell is usually determined by the width of the column heading
and the height of the row text, and the cell content is centered within the cell. Since these texts
are generally larger than the check boxes or radio buttons the cells contain, there is usually space
around those boxes or buttons. If you have a three-dimensional grid, the cell width may be
increased to display a drop-down list and there will be less space around the cell contents.
To set the amount of space around cell contents, type:

Gridname[GridCategory].Qname.Categories[Category].Style.Cell.Padding = number
where:
use [..].
responses.
number is the number of pixels padding each cell is to have.
If you want to specify the padding in a particular direction only, use the same statement but
replace Padding with PaddingTop, PaddingBottom, PaddingLeft, or PaddingRight.
If you specify global and direction-specific padding the direction-specific setting overrides the
global setting, but the global setting still applies where no direction-specific setting exists.
789
Base Professional
Here is the grid with no padding defined, which means that the space around the check boxes
comes solely from the column and row texts:
Figure 1-155
Grid with no styles set
And here it is with ten pixels’ padding:

Figure 1-156
Grid with 10 pixels’ padding
Although padding increases the cell dimensions, it is better to set the row height and column width
using properties designed for that purpose. Set cell padding when you want to increase the amount
of space between the cell contents and the cell borders
Wrapping Text in Cells
When a row text or column heading is wider than the space available to display it, the interviewing
program automatically wraps the text onto a new line by splitting it at a convenient space character
in the text. If the text does not contain spaces then it cannot be wrapped, but you can get round
this by inserting <br/> tags in the text anywhere that you want to force a break.
You can set text wrapping for row and column texts independently. To allow or disallow
wrapping of row texts, type:
Gridname.Categories[..].Label.Style.Cell.Wrap = Value
790
Chapter 1
and for column texts, type:

Gridname[..].Qname.Categories[..].Label.Style.Cell.Wrap = Value
where:
Value is True to allow text wrapping (the default) or False to disallow it.
The general rules for text wrapping are these:
When text wrapping is on (the default)

Longer texts are allocated wider columns that shorter texts.
Text wraps at the ends of words only. Long words are never wrapped.
No column is set narrower than the length of the longest word it contains. If this makes the
grid wider than the width of the browser window, the browser extends the width of the grid
past the end of the window and displays a horizontal scroll bar.
If no column widths are specified, the browser tries to make each column wide enough to
contain the full column heading all on one line, while still ensuring that the overall width of
the grid does not exceed that of the browser window. If the text is too long for this, the column
widths are reduced and text wrapping occurs where necessary.
If column widths are specified, the browser tries to make the columns those widths but, due to
the constraints noted earlier, this may not always be possible. In these cases, the columns
may be wider or narrower than specified.
When text wrapping is off

The browser makes each column as wide as is necessary to display the column heading all on
one line, even if this makes the grid wider than the width of the browser window.
Here are some examples that illustrate these differences. The first example shows what happens
when text wrapping is on and no column widths are defined. The row text column is as wide as
the longest row text, and the other columns are each as wide as their column heading. Since the
grid fits easily into the browser window, no wrapping takes place. The grid was created by the
statement TeaLoop.Ask().
791
Base Professional
Figure 1-157
Grid with text wrapping on and no column widths defined
This next example shows the same grid with all the column widths for the repeated question set to
1.5cm. Notice that South Africa now wraps.
Figure 1-158
Grid with text wrapping on and column widths for repeated question set to 1.5cm
This grid was created by the statements:

TeaLoop.Categories[..].label.Style.Align = Alignments.alCenter
TeaLoop.Ask()
The next example has all columns, including the row text column, set to 1.5cm. Now Lapsang
Souchong wraps as well.
Figure 1-159
Grid with text wrapping on and all column widths set to 1.5cm
792
Chapter 1
The statements that created this grid were:

TeaLoop[..].Countries.Categories[..].Label.Style.Cell.Wrap = True
TeaLoop.Categories[..].Label.Style.Cell.Width = "1.5cm"
TeaLoop[..].Countries.Categories[..].Style.Cell.Width = "1.5cm"
TeaLoop.Ask()
The final example uses the same code as the previous one, but with the following change which
switches off text wrapping for the repeated question:
TeaLoop[..].Countries.Categories[..].Label.Style.Cell.Wrap = False
Figure 1-160
Grid with text wrapping off for repeated question columns
The row texts still wrap but the column headings do not. This means that the interviewing
program must sometimes override the 1.5cm column width so that all column headings can
be displayed in full.
Example Layouts
This topic shows you how to specify different types of grid layouts.
793
Base Professional
Nested Grid with Radio Buttons in Each Cell
The layout you want to generate is as follows:

Figure 1-161
Grid with radio buttons in cells
794
Chapter 1
The metadata that creates it is:

Treatments "Treatment Options for Back Pain" compound
{
AntiInflam "Anti-inflamatory medication",
PainRelief "Pain relief",
PhysioHydro "Physiotherapy/Hydrotherapy"
} fields
(
ConfLoopFeatures "" loop {} fields (
ConfLoop "" loop
{
ConfLevel "Level of confidence in treatment" labelstyle(Width = "200px")
} fields (
Confidence "Level of confidence in treatment"
style(Align="left",Cell(BorderStyle = "Solid", BorderWidth="1"))
categorical [1..1]
{
NotConfident "Not at all confident",
LittleConfident "A little confident",
SomeConfident "Somewhat confident",
Confident "Confident",
VeryConfident "Very confident"
};
) expand ;
)expand;
FreqLoopFeatures "" loop {} fields (
FreqLoop "" loop
{
FreqLevel "Frequency of recommendation" labelstyle(Width = "200px")
} fields (
Frequency "Frequency of recommendation"
style(Align="left",Cell(BorderStyle = "Solid", BorderWidth="1"))
categorical [1..1]
{
Never "Never", Seldom "Seldom", Occasionally "Occasionally",
Frequently "Frequently", Always "Always"
};
) expand;
)expand;
);
The important points about this script are as follows:

The page consists of two three-dimensional grids side by side. This signals a compound
item as the overall structure for the question. The thing that is common to both grids is the
rows, so these become the control items for the compound item — that is, the items about
which the questions are asked.
In a three-dimensional grid, the outer loop defines the repetition texts, while the inner loop
defines the grid categories. In this example, the repetition texts for the ConfLoopFeatures
and FreqLoopFeatures outer loop have already been defined as part of the compound item so
their loop control lists are blank.
The responses to the question inside each inner loop become the contents of each grid cell so
we define these questions in the normal way.
The repetition texts for the inner loops match the question texts of the questions in the loops.
The interviewing program uses the texts in the loop control lists as the column headings, but
since you may need individual question texts for each cell for analysis purposes, the script
defines the same text as part of the questions themselves.
The width of each grid is specified using labelstyle on the items in the inner loop control
lists. This ensures an even column width across both grids.
795
Base Professional
The boxes around the grid cells are specified using the style keyword in the questions.
The radio buttons in each cell are indented because this is what the default layout template
does. Add indent=-1 to each question’s style settings to omit the indent. This will also
reduce the overall width of the boxed grid cells so you may want to reduce the label widths
for the column headings by a corresponding amount.
Using Images
You can display images or pictures as part of an information (banner), question, or response
text. In categorical response lists you can use images instead of response texts and check boxes
or radio buttons, so that respondents simply click an image to select it. If the response list is a
single choice list, you can set the script up so that the next question is displayed as soon as the
respondent clicks on an image.
Images are part of an item’s style and can be defined in either the metadata or the routing
section in the same way as other style characteristics. You have complete control over how and
where they are displayed. When you display images with text, you can place the image to the right
or left of the text, or above or below it. When necessary, you can choose not to display an image
even if one is defined, and, as previously mentioned, you can display images instead of text. If
you do not specify the position of images relative to text, they will be displayed to the left of the
text as if they were the first word in the text.
To display an image as part of a question, information or response text, insert the following
after the text:
labelstyle(image = "filename" [, imageposition = "position"])
where:
filename is the name of the image file. For more information, see the topic Format and
Location of Image Files on p. 799.
position is the image’s display position relative to the text and is one of Left (the default),
Right, Top, Bottom, or ImageOnly.
For example, for a question:
SeenLogo1 "Have you seen this image in any advertising during
the last two weeks?"
labelstyle(image = "catsnax.gif", imageposition = "Bottom")
categorical [1..1]
{
Yes, No,
DK "Don't remember" dk
};
796
Chapter 1
Figure 1-162
Image below question text
The interviewing program does not insert blank space between the image and the text. If you
want more space you must deal with this yourself. In the example, you could create more space
between the text and the image by adding <br/> tags to the end of the question text.
Here is an example that shows how to display images instead of response texts:
Logo1 "What was the brand logo for the cat food that you saw
advertised?" categorical [1..1]
{
PinkLogo "" labelstyle(image = "logo_fuchsia.gif"),
BlueLogo "" labelstyle(image = "logo_blue.gif"),
GreenLogo "" labelstyle(image = "logo_green.gif"),
YellowLogo "" labelstyle(image = "logo_yellow.gif"),
LogoOther "Something else. Please describe." other,
NoLogo "Do not remember brand logo"
};
Figure 1-163
Response list with four images
797
Base Professional
Notice the following things about this example:

The responses have empty response texts so that only the images are displayed. (If you
have response texts and want to achieve the same effect, use ImagePosition="ImageOnly" to
suppress the texts.)
Image positions are not defined because only the images are displayed.
The response list provides radio buttons for selecting responses. Respondents cannot select
images by clicking on them. For more information, see the topic Images as Buttons (Clickable
Images) on p. 798.
In the routing section, the properties associated with images are Label.Style.Image for image
names and Label.Style.ImagePosition for image positions. For questions, type:
Qname.Label.Style.Image = "filename"
Qname.Label.Style.ImagePosition = ImagePositions.position
For responses, type:

Qname.Categories[{ResponseName}].Label.Style.Image = "filename"
Qname.Categories[{ResponseName}].Label.Style.ImagePosition = ImagePositions.position
In both cases:
ResponseName is the name of the response.
filename is the name of the image file. For more information, see the topic Format and
Location of Image Files on p. 799.
position is the display position of the image relative to the text and is one of ipLeft (the
default), ipRight, ipBottom, ipTop, ipImageOnly, or ipImageNone (do not display image
even if is defined).
For example:
SeenLogo.Label.Style.Image = "catsnax.gif"
SeenLogo.Label.Style.ImagePosition = ImagePositions.ipBottom
to place the logo below the question text, as in the first illustration, and:
Logo.Categories[{PinkLogo}].Label.Style.Image = "logo_fuchsia.gif"
Logo.Categories[{BlueLogo}].Label.Style.Image = "logo_blue.gif"
Logo.Categories[{GreenLogo}].Label.Style.Image = "logo_green.gif"
Logo.Categories[{YellowLogo}].Label.Style.Image = "logo_yellow.gif"
to display four images in the response list, as in the second illustration. A more efficient way of
writing this is:
With Logo.Categories
.PinkLogo.Label.Style.Image = "logo_fuchsia.gif"
.BlueLogo.Label.Style.Image = "logo_blue.gif"
.GreenLogo.Label.Style.Image = "logo_green.gif"
.YellowLogo.Label.Style.Image = "logo_yellow.gif"
End With
798
Chapter 1
If you do not see the images displayed when you test your script and you are sure that there are no
syntax errors, refer to the “Images are not displayed in the respondent’s browser” subsection of
for suggestions on how to proceed.
Images as Buttons (Clickable Images)
When a response list contains images, respondents are likely to try selecting responses by clicking
on the images rather than using the check boxes or radio buttons. Nothing happens if they do
this and respondents may think that the interview has stopped working. If the question has a
single-choice response list, you can improve usability by making the images behave like buttons.
In response lists with no special responses you can also hide the navigation buttons so that clicking
on an image takes the respondent straight to the next question.
To make the images clickable, define the images in the metadata or routing section. Then specify
that responses should be displayed as buttons. You can do this in the metadata section by placing:
style(control(type = "button"))
after each response text, or in the routing section using:
Qname.Style.Control.Type = ControlTypes.ctButton
For example:
BestLogo "Which logo looks best?" categorical [1..1]

{
PinkLogo "" style(image = "logo_fuchsia.gif", control(type = "button")),
BlueLogo "" style(image = "logo_blue.gif", control(type = "button")),
GreenLogo "" style(image = "logo_green.gif", control(type = "button")),
YellowLogo "" style(image = "logo_yellow.gif", control(type = "button"))
};
Figure 1-164
Question with four clickable images
Response texts are not immediately visible when you display images as clickable buttons, but
if you hover over the image the text appears momentarily in a pop-up box. If you want images
with text, make the text part of the image file.
799
Base Professional
Format and Location of Image Files
You can save images in any format whose MIME type is defined in IIS, so standard formats
such as gif, wmf, and jpeg are all acceptable.
When you set up a new project that uses images, the best place to put those images is in the
project folder. You can use a subfolder within the project folder, but in this case you will have to
include the subfolder name in the image filenames when you refer to them in the script. When you
activate the project, the images are copied with the other project files into the appropriate folders.
When you run the first interview on a project, the interviewing program copies all the project’s
images into a central repository known as the image cache, and subsequently looks for images in
that location. The default location for the image cache is FMRoot\Master\Projects in the IBM®
SPSS® Data Collection Interviewer Server installation folder. If you update images during the
course of a project and reactivate the project, the image cache is automatically updated with the
latest version of the file. If you do not want to reactivate, copy the updated files into image
cache folder manually.
If the image cache is unavailable (for example, the server on which FMRoot resides may be
down), the interviewing program looks for images for IBM® SPSS® Data Collection projects in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Interviewer Server\Server\mrIWeb\Images
on the machine on which Interviewer Server is installed, so this is an alternative location you can
use for images if you do not want to use the image cache.
If you want to refer to images in specific folders in the image cache you must enter the full URL
of the file. This may vary from site to site depending on how Interviewer Server was installed, but
a typical URL is http://ImageServerMachine/Images/MyImage.gif, whereImageServerMachine is
the name of your image server. Do not use the %image_cache%/filename notation that is used in
scripts created using the Build activity as this will not work outside Build.
Note: When you are testing a script, your browser will cache any images you use. If you
change an image and then retest your script, the interviewing program will use the browser’s
cached version of the image rather than the updated version, even if you manually copy the new
file into the image cache folder. The only way to access the new image in the image cache is to
close and reopen your browser. This does not apply to respondents taking live interviews because
they are very unlikely to take an interview more than once.
Alignment and Positioning
All response texts, input boxes, and images in a line sit along an invisible line known as the
baseline. This is why, when you insert an image in a line, the text appears at the same level as
the bottom of the image rather than being level with the top of the image or centrally positioned
within its height. Changing the vertical position of the image relative to the text, or of the text
relative to the image, can make the page easier to read as well as producing a generally more
pleasing visual appearance.
You can also change the horizontal alignment of items on the page. This is a common
requirement in scripts that present questions and response controls as forms, or in any situation
where you want to display a question’s text and response control side by side.
800
Chapter 1
The keywords associated with text alignment and positioning are as follows:
Align Horizontal alignment of an element within
its allotted space on the page; for example,
right-justifying a question text within a specified
area of the page.
ElementAlign Horizontal alignment of one element relative to
another; for example, placing two questions on the
same line rather than on separate lines. (In some
cases this can be controlled by the page template.)
VerticalAlign Vertical alignment, usually of a text with an image
or response box.
You can use these keywords in the metadata or routing section of the script. The illustration shows
the effects of the metadata versions of these keywords on a typical page:
Figure 1-165
Effect of metadata alignment keywords on a page
Note: Horizontal alignment that relates to a question test and response control on the same line
also requires a template that places the question text and response controls side by side. Specifying
one without the other does not produces the desired effect.
If you are producing a form that requires a lot of horizontal and vertical alignment of question
texts and response controls, you may find that a template that uses a table to control layout goes a
long way to simplifying the questionnaire specification. See “Using Tables to Simplify Alignment
Specifications” in the Forms topic for details.
Horizontal Alignment
When you display items on a page side by side — for instance, when you display the question
text and the response list or input box on the same line — you need to do two things. First,
create a template that generates this page layout (see Questions, Responses, and Error Messages
for details). Second, add keywords or statements to the script that specify the alignment and
position of the question text and response control.
801
Base Professional
Horizontal alignment covers two aspects of a page’s layout:

Alignment of text within its space on the page. A typical example is right-justifying the
question text within the space allocated to question texts in the template. You use the align
label style keyword for this.
Alignment of one element relative to another. A typical example is placing a question and
its response control on the same line, or placing two questions on the same line. You use
the elementalign style keyword for this.
You can use these keywords in either the metadata section or the routing section of the script. You
can also apply both types of alignment to the same question, if appropriate. For example, you
might place a question’s text and response box on the same line, and right-justify the question
text in the part of the page used for that text.
To specify the alignment of a question or information text within the space allotted to it in the
template, insert the following element after the text:
labelstyle(align = "Position")
where:
Position is one of Left, Center, Right, Justify (for evenly spaced controls), or
Default (the default alignment for the Player). If you do not specify alignment, the
interviewing program uses left alignment.
For example, if you use the default page layout template:
FirstName1 "First name"
labelstyle(align = "right", width = "5em")
text [0..25];
LastName1 "Last name"
text [0..30];
Age1 "Age"
long [18 .. 99];
Gender1 "Gender"
style(control(type = "droplist"))
labelstyle(Align = "Right", Width = "5em")
categorical [1..1]
{Male, Female};
Personal1 "" page(Firstname1, Lastname1, Age1, Gender1);
802
Chapter 1
right-aligns the four question texts within the space that the template allocates for questions texts:
Figure 1-166
Right-aligned question texts
Notice that each question text is right aligned in a field five ems wide. Specifying the field width
ensures that the texts line up correctly regardless of their length. If texts ,are longer than the field
width, they are wrapped onto as many lines as necessary and the bottom line of text is aligned
with the bottom of the response box.
To specify the alignment of the response control relative to the question text, place the
style(elementalign = "Position")
where:
Position is one of Right, Newline (below the question text), or Default (the default
alignment for the Player). If you do not specify alignment, the interviewing program uses
newline alignment.
Note: You can also use this notation when you want to set up forms with more than one question
and response control on a line. For more information, see the topic Forms on p. 806.
For example, when used with a template that displays question texts and responses side by side,
the following code:
FirstName2 "First name"
style(elementalign = "right") text [0..25];
LastName2 "Last name"
Age2 "Age"
style(elementalign = "right") long [18 .. 99];
Gender2 "Gender"
style(Control(Type = "DropList"))
style(elementalign = "right") categorical [1..1]
{Male, Female};
Personal2 "" page(Firstname2, Lastname2, Age2, Gender2);
803
Base Professional
produces:
Figure 1-167
Question text and response controls side by side with right-aligned question texts
Note: Without the template, this code would produce the same layout as the previous one. In this
instance, the following question sub-template was used to define the question’s layout:
<mrSubTemplate>
<mrData QuestionElement="Label"/><mrData QuestionElement="Controls"/>
</mrSubTemplate>
See Sub-Templates for further information about sub-templates, and Laying Out the Components
of a Question for more information about templates in general.
To specify the same layouts in the routing section, use the following statements:
Qname.Label.Style.Align = Alignments.alType
Qname.Style.ElementAlign = ElementAlignments.eaType
where:
alType is the alignment of the question or information text and is one of: alLeft,
alCenter, alRight, alJustify (for evenly spaced elements), or alDefault (the default
alignment for the Player). If nothing is specified, text is left-aligned in the space available.
eaType is the alignment of the response control relative to the question text (or of the next
question text relative to the previous response control) and is one of: eaRight, eaNewline
(below the question text), or eaDefault (the default alignment for the Player). If nothing is
specified, eaNewLine is assumed.
The statements that define the alignment shown in the most recent illustration are:
' Field width for question texts
FirstName.Label.Style.Width = "5em"
LastName.Label.Style.Width = "5em"
Age.Label.Style.Width = "5em"
Gender.Label.Style.Width = "5em"
' Right-align question texts
FirstName.Label.Style.Align = Alignments.alRight
LastName.Label.Style.Align = Alignments.alRight
Age.Label.Style.Align = Alignments.alRight
Gender.Label.Style.Align = Alignments.alRight
' Response controls to right of question texts
FirstName.Style.ElementAlign = ElementAlignments.eaRight
LastName.Style.ElementAlign = ElementAlignments.eaRight
Age.Style.ElementAlign = ElementAlignments.eaRight
Gender.Style.ElementAlign = ElementAlignments.eaRight
' Drop-down list for Gender
Gender.Style.Control.Type = ControlTypes.ctDropList
804
Chapter 1
As in the previous example, a question sub-template is required for placing the response controls
on the same line as the question texts.
Vertical Alignment
When you display questions and responses side by side the interviewing program lines up the
question text and the response control, or the question or banner text and the image, along the
base line. If one item in the pair is very much taller than the other this may not produce the
effect you want, and you may wish to vary the vertical alignment so that, for instance, the
smaller item is positioned centrally within the height of the larger one. A typical example is a
multiline text box such as:
Figure 1-168
Multiline text box next to short question text with bottom alignment
where you might prefer to align the top of the text box with the top of the Address prompt:
Figure 1-169
Multiline text box next to short question text, with top alignment
To specify the vertical alignment of the response control relative to the question text, place the
style(verticalalign = "Position")
805
Base Professional
where:
Position is one of the following:
Baseline Align with the baseline of the parent element.

Bottom Align with the bottom of the lowest element on the
current line.
Default Use the default vertical alignment for the Player.
Middle Align the vertical midpoint of this element with the
baseline of its parent plus half of the vertical height
of its parent.
Sub Make this element a subscript of the parent element.
Super Make this element a superscript of the parent
element.
TextBottom Align with the bottom of the text in the parent
element’s font.
TextTop Align with the top of the text in the parent element’s
font.
Top Align the top of this element with the top of the
tallest element on the current line.
The earlier illustration with the top of the input box aligned with the top of the Address question
text was created using the following code:
FirstName4 "First name" labelstyle(width = "5em")
LastName4 "Last name" labelstyle(width = "5em")
Address "Address" labelstyle(width = "5em")
style(elementalign = "right", verticalalign="top") text;
Personal3 "" page (FirstName4, LastName4, Address);
To specify the vertical alignment of the response control relative to the question text, place the
Qname.Style.VerticalAlign = VerticalAlignments.Position
where:
Position is one of the following:
vaBaseline Align with the baseline of the parent element.

vaBottom Align with the bottom of the lowest element on the
current line.
vaDefault Use the default vertical alignment for the Player.
vaMiddle Align the vertical midpoint of this element with the
baseline of its parent plus half of the vertical height
of its parent.
vaSub Make this element a subscript of the parent element.
vaSuper Make this element a superscript of the parent
element.
806
Chapter 1
vaTextBottom Align with the bottom of the text in the parent

element’s font.
vaTextTop Align with the top of the text in the parent element’s
font.
vaTop Align the top of this element with the top of the
tallest element on the current line.
For example:
Address2.Style.ElementAlign = ElementAlignments.eaRight
FirstName.Style.VerticalAlign = VerticalAlignments.vaMiddle
LastName.Style.VerticalAlign = VerticalAlignments.vaMiddle
Address2.Style.VerticalAlign = VerticalAlignments.vaMiddle
vertically aligns the middle of each input box with the middle of its question text.
Figure 1-170
Middle vertical alignment of question texts
The effect for the single-line input boxes is negligible in this example but it is obvious for Address.
Forms
You can use styles to lay out interview pages so that they replicate printed forms that you already
use in your organization. While some basic familiarity with templates is handy, much of the skill
in laying out forms lies in knowing how to use horizontal alignment to determine the relative
positions of items on a line. This topic gives some examples that you can use as the basis for
designing your own forms.
Displaying Two or More Questions on the Same Line
The output for this example is:

Figure 1-171
Title & last name on one line with first name & middle initials on the next line
807
Base Professional
It was created by defining the basic questions in the metadata section and placing the following
code in the routing section:
' Template for question text & response controls on same line.
IOM.Questions[..].QuestionTemplate = "styles2.htm"
' Field width for question texts
Title.Label.Style.Width = "5em"
FirstName.Label.Style.Width = "5em"
Initials.Label.Style.Width = "6em"
LastName.Label.Style.Width = "5em"
' Response controls to right of question texts

Title.Style.ElementAlign = ElementAlignments.eaRight
Initials.Style.ElementAlign = ElementAlignments.eaRight
' Put LastName/Initials on same line as previous element ...

Initials.Label.Style.ElementAlign = ElementAlignments.eaRight
LastName.Label.Style.ElementAlign = ElementAlignments.eaRight
' ... with this space between the two

Initials.Label.Style.Indent = 2
LastName.Label.Style.Indent = 2
' Width for LastName/Initials input boxes

LastName.Style.Width = "13.5em"
Initials.Style.Width = "5em"
' Drop-down selection list for Title

Title.Style.Control.Type = ControlTypes.ctDropList
FullName.Ask()
The comments in the code explain what each set of statements does. However, there are some
additional points to note.
Statements are grouped by function rather than by question name, so all the statements to do
with placing response controls next to question texts are together. You could reorganize the
statements so that the statements are grouped by question name, if you find this approach
more logical. As long as all requirements are covered it does not matter what order they are
defined in. The only rule is that the .Ask statement that displays the question comes last.
The widths of the input boxes for LastName and Initials have been specified to ensure that
the ends of the boxes line up. Working out the measurements is done by trial and error as
you test your script.
The maximum response lengths for FirstName, LastName, and Initials were set in the metadata
at 40, 40, and 5 respectively to ensure that the input boxes were displayed as single-line boxes.
Lengths greater than 40 characters result in input boxes showing six lines of 34 characters.
808
Chapter 1
The metadata equivalent of this routing code is as follows:

Title1 "Title"
categorical [1..1]
{Ms, Miss, Mrs, Mr};
FirstName1 "First Name"
style(elementalign="right")
text [0..40];
Initials1 "Middle Initials"
style(elementalign="right", width="5em")
text [0..40];
LastName1 "Last Name"
style(elementalign="right", width="13.5em")
text [0..40];
FullName1 "" page(Title1, LastName1, FirstName1, Initials1);
The question sub-template for this example is:

<mrSubTemplate>
<mrData QuestionElement="Label"/><mrData QuestionElement="Controls"/>
</mrSubTemplate>
Dealing with Dates
Forms often require users to enter or select dates or partial dates. Typical examples are dates of
birth or start and end dates for credit cards or club membership. Depending on how you want to
use the data, you can either display a simple input box and let respondents enter a value of their
choice, or you can present the question with separate boxes for each date part. The easiest way
to display separate boxes for each date part is to create a separate question with a drop-down
response list for each date part you want, and to display the questions and response controls side
by side in a single line. Here’s an example that prompts for the user’s date of birth:
Figure 1-172
Date of birth a 3 side-by-side drop-down lists
It was created using the following routing code:

' Template for question text & response controls on same line.
IOM.Questions[..].QuestionTemplate = "styles2.htm"
' Response box on same line as question text
Dayname.Style.ElementAlign = ElementAlignments.eaRight
Monthname.Style.ElementAlign = ElementAlignments.eaRight
Yearnumber.Style.ElementAlign = ElementAlignments.eaRight
' Question text on same line as previous response box
Monthname.Label.Style.ElementAlign = ElementAlignments.eaRight
Yearnumber.Label.Style.ElementAlign = ElementAlignments.eaRight
' Drop-down response lists
DayName.Style.Control.Type = ControlTypes.ctDropList
MonthName.Style.Control.Type = ControlTypes.ctDropList
YearNumber.Style.Control.Type = ControlTypes.ctDropList
Dob.ask()
The questions were defined as basic categorical questions, with MonthName and YearNumber
having null question texts since these were not required in the form.
809
Base Professional
Here’s the same specification defined entirely in the metadata section:

DayName1 "Date of Birth" labelstyle(elementalign="right")
categorical[1..1]
{
d1 "01",
d2 "02",
d3 "03"
};
MonthName1 "" labelstyle(elementalign="right")
categorical[1..1]
{
January, February, March, April, May, June, July,
August,September, October, November, December
};
YearNumber1 "" labelstyle(elementalign="right")
categorical[1..1]
{
y1956 "1956",
y1957 "1957",
y1958 "1958"
};
Dob1 "" page (DayName1, MonthName1, YearNumber1);
This example uses the question sub-template shown earlier in this topic.
Using Tables to Simplify Alignment Specifications
Some forms are very precisely laid out so that the overall effect of the form is grid-like; that is to
say, the question texts and response controls in each row line up with the corresponding elements
in the other rows. If this is the layout you want for your form, you may find that a template that
lays out the elements as a table goes a long way to simplifying your alignment specifications.
The DDL comes with an example project that illustrates this perfectly. You’ll find it in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Projects\Forms
folder. The questionnaire file contains two examples, and it is the second one that uses a tabular
layout. The form looks like this:
Figure 1-173
Pediatric admission form showing a tabular layout
As you can see, the question texts appear above the response boxes and all the boxes are lined
up under one another. The template for the form (TableForm.htm) defines a table of three rows
of four columns each. Questions 1 to 4 go in the first row, questions 5 to 8 go in the second
row, and questions 9 to 12 go in the third row.
810
Chapter 1
Unlike the question sub-template used in the previous examples, this template does not specify
the locations of the question texts and response controls, so you would expect each table cell to
contain one question displayed using the default layout; that is, a question text and a response
control on separate lines with a blank line in between. However, in the illustration, there are no
blank lines between question texts and response boxes. This is because each question contains the
specification style(ElementAlign="NewLine") which instructs the interviewing program
to insert a line break between the question text and the response control. The indentation of the
response boxes is the standard indentation used to separate the response box from the question
text, and is not specified in the script.
Playing Sound Files and Recording Responses
You can record whole interviews or just selected questions. You can play an audio file to the
respondent when the question is displayed, or you can assign different audio files to different
responses in a list. All these things are controlled by the Audio style object.
In IBM® SPSS® Data Collection 4.5 record and playback are available only in the CATI
(telephone interviewing) player. If you are testing scripts using IBM® SPSS® Data Collection
Base Professional you will need to write your routing in the CATI context if you want to see the
record and playback button bars displayed. If you use the Web context the questions will be
displayed without the button bars.
Recording Questions
You can record questions automatically as soon as the question is displayed, or manually by
having the interviewer click a button to start.
To determine how a question should be recorded, place the following between the question text
and the response type keyword:
labelstyle(Audio(Record = "mode", RecordControlPosition = "position"))
where:
mode specifies how recording is to take place and is one of:
rmNone No recording. This is the default.
rmAuto Start recording the first time the question is
displayed and stop recording when the interviewer
navigates away from the question. If the question
is asked more than once, recording must be done
manually by clicking the record button.
811
Base Professional
rmManual Recording is under interviewer control via the start

and stop recording buttons.
rmProhibited Marks questions that must never be recorded even
if the whole call or interview is being recorded.
You might use this for flagging questions whose
responses could be used to identify individual
respondents.
position specifies the position of the recording button bar relative to the question text if
manual recording is required. It may be one of Top, Bottom, Left, or Right. The default
is Left.
For example:
DescribeAd1 "How would you describe the advertisement to someone who

had not seen it? INTERVIEWER: PROBE FULLY."
labelstyle(Audio(Record = "Manual", RecordControlPosition = "Bottom"))
text;
During telephone interviews the interviewer would see the question displayed as:
Figure 1-174
Question with recording button bar
To determine how a question should be recorded, type:
Name.Label.Style.Audio.Record = RecordModes.mode
where:
mode is one of the recording modes listed in the previous table.
If you are using manual recording, you also need to specify the position of the recording button
bar relative to the question text. To do this, type:
Name.Label.Style.Audio.RecordControlPosition = ControlPositions.position
812
Chapter 1
where:
position is one of cpTop, cpBottom, cpLeft, or cpRight. The default is cpLeft.
For example, if the metadata contains:
DescribeAd "How would you describe the advertisement to someone who
had not seen it? INTERVIEWER: PROBE FULLY." text;
you would place the following statements in the routing section to display it with a recording
button bar below it, as shown in the earlier illustration:
DescribeAd.Label.Style.Audio.Record = RecordModes.rmManual
DescribeAd.Label.Style.Audio.RecordControlPosition = AudioControlPositions.cpLeft
DescribeAd.Ask()
If you want to record the answers to questions in a loop, where the questions are asked separately
rather than displayed as grid, define the recording mode separately for each question and iteration.
For example:
MyLoop[{Iter1}].Q1.Label.Style.Audio.Record = RecordModes.rmAuto
MyLoop[{Iter1}].Q1.Label.Style.Audio.RecordControlPosition = AudioControlPositions.cpTop
MyLoop[{Iter2}].Q2.Label.Style.Audio.Record = RecordModes.rmAuto
MyLoop[{Iter2}].Q2.Label.Style.Audio.RecordControlPosition = AudioControlPositions.cpTop
Where to Find Recordings

All recording files are stored on the dialer in an audio\dimensions\ProjectName folder, and all
filenames are converted to lower case to avoid potential problems on case sensitive filesystems.
Files are named q–SampleId–QuestionFullName.wav; for example, q–id152–whyliked.wav for the
whyliked question for sample record ID152 or q–id152–rating[{taste}].wav for the taste iteration
of the rating loop for sample record ID152.
Sound Files for Questions and Responses
Note: Data Collection 4.5 does not support the playing of sound files for the categories or
iterations of grids or compound questions statement.
There are two things to do when you want to associate a sound file with a question or response:
name the file and specify where you want the play buttons to be displayed relative to the question
or response text. You can name the file in the metadata or routing section but the position of the
button bar must be defined in the routing section.

To name the file in the metadata section, follow the question or response text with:
labelstyle(Audio(Name = "filename"[, PlayControlPosition = "position"]))
where:
filename is the name or pathname of the sound (.wav) file relative to the Audio folder
on the dialer, or a URL.
position specifies the position of the recording button bar relative to the question or
response text if manual recording is required. It may be one of Top, Bottom, Left, or
Right. The default is cpLeft.
813
Base Professional
For example:
HeardAd "Please listen to this advertisement and tell me whether you recollect
hearing it during the last week.
INTERVIEWER: YOU MAY PLAY THE RECORDING MORE THAN ONCE."
labelstyle(Audio(Name = "catfood\catsnax.wav", PlayControlPosition = "Bottom"))
categorical [1..1]
{
Yes "Yes, I remember hearing it",
No "No, I have not heard it during the last week",
DK "I can't remember whether I heard it last week" dk
};
or:
HeardEver "And which of these adverts have you ever heard?
INTERVIEWER: PLAY EACH RECORDING AND SELECT THOSE HEARD."
categorical [1..]
{
MouseMorsels "Mouse Morsels"
labelstyle(Audio(Name = "catfood\mouse_morsels.wav", PlayControlPosition = "Right")),
Snax4Catz
labelstyle(Audio(Name = "catfood\snax4cats.wav", PlayControlPosition = "Right")),
KittyTreats "Kitty Treats"
labelstyle(Audio(Name = "catfood\kitty_treats.wav", PlayControlPosition = "Right")),
FishyNibbles "Fishy Nibbles"
labelstyle(Audio(Name = "catfood\fishy_nibbles.wav", PlayControlPosition = "Right"))
};
To name a sound file in the routing section, type:

Name.Label.Style.Audio.Name = "filename"
for a question or
Name.Categories["RespName"].Label.Style.Audio.Name = "filename"
where:
RespName is the response name.
filename is the name or pathname of the sound (.wav) file relative to the Audio folder
on the dialer, or a URL.
The play button toolbar is normally displayed to the left of the question or response text. To
change this, type:
Name.Label.Style.Audio.PlayControlPosition = ControlPositions.position
for a question or:

Name.Categories["RespName"].Label.Style.Audio.PlayControlPosition
= ControlPositions.position
where:
RespName is the response name.
Position is the control’s position relative to the question or response text and is one of
cpTop, cpBottom, cpLeft, or cpRight. The default is cpLeft.
814
Chapter 1
As an example, here’s the HeardEver question displayed using the default position for the play
buttons.
Figure 1-175
Question with play button bar
File Format and Location
The dialer supports mono (single channel) .wav files in the following formats:
Sample rate Sample encoding Data rate Comments
11025 Hz 8 bits/sample, PCM 38 MiB/h Default file format
8000 Hz 16 bits/sample, PCM 55 MiB/h Better sound quality
11025 Hz 16 bits/sample, PCM 76 MiB/h Common file format
In this table, PCM stands for Pulse Code Modulation; 1 MiB is 1024×1024 bytes.
If you have stereo (two-channel) sound files you can convert them to mono format with a
program such as WavePad.
You must copy sound files into the dialer’s Audio folder manually. If you wish, you may
organize files by placing them in subfolders. The location of the Audio folder may vary between
dialers so consult your dialer documentation for advice.
Default Styles
Default styles are a convenient way of defining basic styles that apply to the interview script as a
whole. For example, if you want all or most texts to be blue you can define this as a default style
and the interviewing program will apply it to all pages in each interview. Similarly, if you want
to change the appearance of the navigation buttons you can do so defining their characteristics
as default styles.
Default styles override the corresponding styles in templates but can themselves be overwritten
by more specific settings in either the metadata or routing section of the interview script. All
default styles are child objects of the IOM.DefaultStyles object, and are as follows:
Default — default styles from which all other interview styles derive. For more information,
see the topic Default Styles for the Whole Script on p. 815.
Labels — default styles for question, information, and response texts.
815
Base Professional
Questions — default styles for questions.

Categories — default styles for categorical responses.
Grids — default styles for grid questions.
Navigation — default styles for navigation buttons.
A typical page uses the following default styles:
Figure 1-176
Interview page showing use of default styles
Styles cascade, so any style properties that are set in the DefaultStyles object are cascaded to child
style objects. The order of precedence of the DefaultStyles object is generally:
1. DefaultStyles.Default
2. DefaultStyles.Labels
3. DefaultStyles.Navigation and DefaultStyles.Categories
4. DefaultStyles.Questions
5. DefaultStyles.Questions.Labels
6. DefaultStyles.Questions.Categories, DefaultStyles.Grids
Like ordinary style objects, default style objects have a number of properties that you can set. For
labels, for example, you can set the font family, size, and effects, and the text color and background
color, and so on, by naming the appropriate properties of the DefaultStyles.Labels object.
Note: In terms of efficiency, it is better to defined default styles in a template of cascading
stylesheet than it is to define them using the DefaultStyles object. For more information,
see the topic Templates on p. 825.
Default Styles for the Whole Script
To specify default styles for the whole script, place the following statement in the routing section
of the script:
IOM.DefaultStyles.Default.property = value
816
Chapter 1
where:
property is the name of the property you want to specify.
value is the value of the property.
For example:
IOM.DefaultStyles.Default.Columns = 2
IOM.DefaultStyles.Default.Orientation = Orientations.orColumn
to display all categorical responses lists column-wise in two columns.

Refer to the topics that describe how to set styles in the script and toIStyle in the Interview
Object Model for a full list of properties that can be set in this way.
Default Styles for Text
To specify default styles for text, type:

IOM.DefaultStyles.Labels[LabelStyleTypes.type].property = value
where type is one of the following label types (note that the type names all start with lowercase
L, not the number 1 or the letter I):
lsBanner Banner texts (from Info items)
lsCategory Categorical response texts
lsError Error messages
lsNavigation Text on navigation buttons
lsQuestion Question texts
lsTitle Titles
For example:
With IOM.DefaultStyles
.Labels[LabelStyleTypes.lsQuestion].Font.Family = "'Comic Sans MS'"
.Labels[LabelStyleTypes.lsCategory].Color = "blue"
.Labels[LabelStyleTypes.lsNavigation].color = "red"
.Labels[LabelStyleTypes.lsError].Font.Effects = FontEffects.feItalic
.Labels[LabelStyleTypes.lsError].Color = "#FF00FF"
End With
817
Base Professional
produces:
Figure 1-177
Default styles for texts
Another way of defining styles for categorical response texts is by category type. This approach
allows you to use different styles for single and multiple choice responses and for exclusive
responses. For more information, see the topic Default Styles for Types of Categorical Response
on p. 820.
Default Styles for Question Types
You can set different default styles for different types of questions. These correspond to the
settings you can make for single questions using Question.Style, so typical examples would
be setting the number of rows or columns to be used for categorical response lists, or the
background color for numeric text input boxes.
To set default styles based on question types, type:
IOM.DefaultStyles.Questions[QuestionStyleTypes.type].property = value
where type is one of the following question types:

qsBlock Question blocks
qsBoolean Boolean questions
qsCategorical Categorical questions
qsCompound Compound questions
qsDate Date questions
qsDouble Double (real) questions
qsInfo Information items
qsLong Long (integer) questions
qsLoopCategorical Categorical loops
qsLoopNumeric Numeric loops
qsOther Automatic Other Specify questions
qsPage Multiple questions on one page
qsText Text questions
818
Chapter 1

For example:
With IOM.DefaultStyles.Questions[QuestionStyleTypes.qsCategorical]
.Style.BgColor = "#C0C0FF"
.Style.Color = "blue"
.Style.Columns = 2
End With
With IOM.DefaultStyles.Questions[QuestionStyleTypes.qsLong]
.Style.BgColor = "#FFFF80"
.Style.Font.Effects = FontEffects.feItalic + FontEffects.feBold
.Style.Color = "green"
End With
produces the following effects for categorical and integer questions:

Figure 1-178
Default styles for question types
You can achieve even more control by combining question type styles with text and category
styles:
With IOM.DefaultStyles.Questions[QuestionStyleTypes.qsCategorical]
.Style.Columns = 2
.Categories[CategoryStyleTypes.csSingle].Label.Color = "red"
.Categories[CategoryStyleTypes.csExclusive].Label.Color = "#FF00FF"
End With
IOM.DefaultStyles.Questions[QuestionStyleTypes.qsLong]_
.Labels[LabelStyleTypes.lsQuestion].Color = "blue"
displays all categorical questions in two columns, with single choice responses in red and
exclusive responses in magenta. Question texts for integer questions are displayed in blue.
819
Base Professional
Figure 1-179
Default styles for question types, texts, and categories
Notice that the exclusive style does not apply to the Don’t know response in the integer response
list because the magenta text was defined only for categorical questions.
Setting a Default Recording Mode for Text Questions
To set a default recording mode for text questions, type:
IOM.DefaultStyles.Questions[QuestionStyleTypes.qsText]._
Labels[LabelStyleTypes.lsQuestion].Audio.Record = _
RecordModes.value
where value is one of:

rmNone No recording.
rmAuto Start recording the first time the question is
displayed and stop when the interviewer navigates
away from the question. If a question is asked more
than once recordings must be made manually by
clicking the record button.
rmManual Recording is under interviewer control via the start
and stop recording buttons.
rmProhibited Marks questions that must never be recorded even
if the whole call or interview is being recorded.
You might use this for flagging questions whose
responses could be used to identify individual
respondents. (This mode is not implemented in
version 6.0.1.)
If a question is asked more than once due to snapbacks, the new recording overwrites the previous
one.
820
Chapter 1
Note: You can use the same notation for recording responses to non-text questions, but this is
generally the exception rather than the rule.
Default Styles for Types of Categorical Response
Responses in a categorical list can be single or multiple choice, they can come from a shared
list, or they can be flagged as exclusive. To define default styles for these types of categorical
response, type:
IOM.DefaultStyles.Categories[CategoryStyleTypes.type].property = value
where:
type is one of the following category types:
csExclusive Exclusive responses (single choice in a multiple

choice list)
csList Subheading belonging to a category list
csMulti Multiple choice responses
csSingle Single choice responses

For example:
.Categories[CategoryStyleTypes.csSingle].Label.Color = "#FF00FF"
.Categories[CategoryStyleTypes.csMulti].Label.Color = "blue"
.Categories[CategoryStyleTypes.csExclusive].Label.Font.Effects = _
FontEffects.feItalic
.Categories[CategoryStyleTypes.csExclusive].Label.Color = "red"
End With
creates:
Figure 1-180
Default styles for category types
821
Base Professional
Notes
E Although this example shows response texts in different colors this is not the usual way to
define styles for response texts. The more usual method is to use the DefaultStyles.Label object
especially if you want all response texts to have the same styles.
E Sometimes responses can be very long, which results in the responses not left-justifying properly
in relation to shorter responses. Use the following settings to left-justify the output:
UseTablesLayout=true):
IOM.DefaultStyles.Categories[..].Style.Indent = -2
IOM.DefaultStyles.Categories[..].Style.Cell.PaddingLeft = 25
Default Styles for Grids
To define default styles for grid components, type:

IOM.DefaultStyles.Grids[GridStyleTypes.type].property = value
where:
type is one of the following grid components:
gsAltCol Alternate columns
gsAltColHeader Alternate column headers
gsAltRow Alternate rows
gsAltRowHeader Alternate row headers
gsCell Grid cells
gsColHeader Column headers
gsRowHeader Row headers

For example:
.Grids[GridStyleTypes.gsCell].Cell.BgColor = "#C0C0FF" 'blue
.Grids[GridStyleTypes.gsColHeader].Cell.BgColor = "#40FFFF" 'cyan
.Grids[GridStyleTypes.gsRowHeader].Cell.BgColor = "#FF40FF" 'magenta
End With
822
Chapter 1
creates grids with different background colors for the row and column heading cells and the body
cells as shown in the following illustration:
Figure 1-181
Default styles for grid row and column heading cells and body cells
You can often make grids easier to follow if you use different colors for alternate rows or columns.
Here are a couple of examples. The first grid uses alternate colors for column and column
heading cells as well as a different typeface and font effect for the column headings. These things
encourage respondents to look at the grid as a set of columns, and to choose all the teas that are
grown in China before thinking about which teas are grown in India.
Figure 1-182
Grid showing default styles for alternate columns
The statements that set the styles for this example are:
.Grids[GridStyleTypes.gsColHeader].Font.Family = "'Comic Sans MS'"
.Grids[GridStyleTypes.gsColHeader].Font.Effects = FontEffects.feBold
.Grids[GridStyleTypes.gsColHeader].Cell.BgColor = "#C0C0FF" 'blue
.Grids[GridStyleTypes.gsAltCol].Cell.BgColor = "#C0FFC0" 'green
.Grids[GridStyleTypes.gsAltColHeader].Cell.BgColor = "#C0FFC0" 'green
End With
823
Base Professional
The next example switches the emphasis from countries (columns) to tea types (rows) so that
respondents are encouraged to think about each tea type in turn. The statements are the same as
those you have just seen except that they refer to rows:
.Grids[GridStyleTypes.gsRowHeader].Font.Family = "'Comic Sans MS'"
.Grids[GridStyleTypes.gsRowHeader].Font.Effects = FontEffects.feBold
.Grids[GridStyleTypes.gsRowHeader].Cell.BgColor = "#C0C0FF" 'blue
.Grids[GridStyleTypes.gsAltRow].Cell.BgColor = "#C0FFC0" 'green
.Grids[GridStyleTypes.gsAltRowHeader].Cell.BgColor = "#C0FFC0" 'green
End With
Figure 1-183
Grid showing default styles for alternate columns
If you define defaults for both alternate rows and alternate columns in a grid with row orientation,
the styles for alternate rows always override those for alternate columns regardless of the order in
which the styles are defined. The following statements illustrate this. From reading the code you
might expect the background colors to be set in the order they are defined, so that you would have
pink alternate columns interspersed with columns of alternately blue and green cells.
.Grids[GridStyleTypes.gsAltRow].Cell.BgColor = "#C0FFC0" 'green
.Grids[GridStyleTypes.gsAltCol].Cell.BgColor = "#FFC0C0" 'pink
End With
824
Chapter 1
However, because rows always override columns when the grid uses row orientation, you get
green alternate rows interspersed with rows of alternate blue and pink cells, as follows. This will
always be the case even if you put the statements in a different order:
Figure 1-184
Grid with default styles for alternate rows and alternate columns
If the grid uses column orientation (in this example, the teas would be the columns and the
countries would be the rows), then column specifications override row specifications, and you
would have all-pink columns for Darjeeling, Lapsang Souchong, and Oolong rather than the
all-green rows shown in the illustration.
Default Styles for Navigation Buttons
To specify default styles for navigation buttons, place the following statement in the routing
IOM.DefaultStyles.Navigation.property = value
where:
For example:
IOM.DefaultStyles.Navigation.Cell.BorderColor = "green"
to display buttons with green borders, or:
IOM.DefaultStyles.Navigation.Font.Effects = FontEffects.feBold
to make the label texts bold.

Refer to the topics that describe how to set styles in the script and to IStyle in the Interview
Object Model for a full list of properties that can be set in this way. See also Default Styles for
Text for information about setting default styles for the text displayed on navigation buttons.
825
Base Professional
Templates
Templates control the layout of the interview pages separate from the page content, which means
that you can use a standard layout for all your interview projects just by applying the same
template or templates to each project. You can use any number of templates in a project, switching
between them according to the layout required for a particular page.
The interviewing program also supports cascading style sheets. These allow you to define global
formatting characteristics that apply to all templates. For example, you can always have dark blue,
12-point question text regardless of how or where the question text is displayed by your templates.
What Can I Define in a Template?
Templates define some or all of the following:

Page title.
Position and appearance of texts and controls (responses lists, for example) on the page.
Position in which error messages are to be displayed and their appearance.
Position and appearance of banner (information) texts.
Position, orientation, and type of progress bars.
Insertion points for images and other external references.
Navigation buttons that are to be displayed and their positions on the page.
Any fixed text, such as the Webmaster’s e-mail address.
HTML page generation settings.
Where Do Applications Look for Templates?
Applications look for templates in two locations, first in the project folder and then in the global
templates folder.
Project templates — exist in the project directory and apply only to that project. You use
project-specific templates either for special projects that have a different overall layout or for
particular questions in the questionnaire that require a nonstandard layout. When you activate a
project, the activation process copies any project-specific templates that it finds in the project’s
source directory into the Shared and Master folders in FMRoot.
Global templates — held in the main Projects directory, which is usually
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Interviewer Server\Projects for IBM®
SPSS® Data Collection Interviewer Server. If you are building and testing scripts using IBM®
SPSS® Data Collection Base Professional, you can set the location of the global templates folder
for Base Professional using Tools>Options. (Note that this does not affect Interviewer Server.)
Global templates can be used by any project and will include any templates that your company
creates to implement its current standards for interview page design and layout.
826
Chapter 1
Types of Templates
There are four types of templates:

Layout Templates. Each interviewing template file defines one page layout. However, this does
not necessarily mean that you have to create a completely new template file if you want to vary
just one aspect of the layout for a particular part of an interview or for a different project. If the
basic page layout is the same, you may find that creating one or more sub-templates for the
aspects that vary is the way to go.
Sub-Templates. A sub-template is a template file that defines the layout of one component of the
page. You can create sub-templates for questions (question and response texts), errors, banners,
navigation bars, and grids. The main page layout template contains a basic tag indicating where
the various components belong and the sub-templates define the exact layout for each component.
You specify which sub-templates are to be used by naming them in the routing section of the
interview script or in the main layout template.
During interviews, the sub-template is inserted in the page only if required: if an item is
not used on a page then the sub-template for that item is not inserted. One example of when
sub-templates are handy is errors. If you would like an animated image to appear next to any
errors, you cannot use the main template because the image will appear whether an error is present
or not. However, if you create an Error sub-template that contains the image, then if there are no
errors, the sub-template will not be inserted and the image will not appear.
You can create sub-templates for individual questions, so that just the appearance of those
questions differs from the rest of the interview. For example, if you have a question that asks for a
cost or price, you can define a template that displays a currency symbol in front of the input box
and then apply the template to that question only. In this way you achieve the effect you want
without having to alter the basic template for other questions.
Localized Templates. With localized templates, you can set the language of an interview based on
the respondent’s browser language, and the language can be changed in the interview script. The
interviewing program passes the language to the HTML Player, which searches for the appropriate
template in the language folder and then in the project folder.
For example, if the language is passed as “en–us”, the HTML Player looks for the localized
template in the following folders:
Project folder\en–us
Project folder\en
Project folder
Global templates folder\en–us
Global templates folder\en
Global templates folder
Grid Templates. An alternative to defining styles in the metadata or routing section. For more
information, see the topic Grid Templates on p. 856.
827
Base Professional
The Default Template
If you do not assign a template to your script, the interviewing program generates pages with
the following layout:
Figure 1-185
Page with no template applied
If the script uses banners (information texts), these are displayed above the question text in the
order in which they are added in the routing section. If a respondent selects or enters invalid
responses, an error message is displayed in red underneath the question text. For further details
about the default templates supplied with IBM® SPSS® Data Collection Developer Library and
IBM® SPSS® Data Collection Interviewer Server, see Default Templates.
Naming Templates in the Script
Each interview script should have at least one template associated with it, and some scripts may
require more than one template. If a script has no templates associated with it, the interviewing
program will use its default layout.
The way a question or text is displayed during the interview is determined by the layout
template in force at that time. You can switch layout templates as many times as you want, but will
normally do so to accommodate question types that cannot be displayed using the standard layout.
To name a template you want to use, do one of the following. In the metadata section, type:
templates(type="filename.htm"[, ... typen="filenamen.htm"])
after a question’s or page’s text parameter, or, in the routing section, type:
Item.TypeTemplate="filename.htm"
where:
Item is IOM if the template applies to the whole script or the name of a question or page
if it applies to a specific question or page.
Type is the template’s type and is either Layout for the main template or one of Question,
Error, Banner, NavBar, or Grid for a sub-template.
filename is the name of the template file.
828
Chapter 1
If you are using sub-templates that are not named in the main template, you will need to name
each sub-template separately. For more information, see the topic Sub-Templates on p. 847.
For example, placing:
templates(Question = "quest.htm", NavBar = "navigate.htm")
after question texts in the metadata section is the same as placing:
IOM.QuestionTemplate="quest.htm"
IOM.NavBarTemplate="navigate.htm"
in the routing section.
If you do not see the interview pages laid out as you expect when you test your script, and you are
sure that there are no syntax errors in your script, refer to the “Templates are not being displayed
by the interview” subsection of for suggestions on how to proceed.
Writing Templates
Templates are text files that contain template XML tags, optionally with other standard HTML
tags, and that have a .htm extension. Template XML tags are easy to recognize because they all
start with “mr”. They’re documented in detail in this section and you can find a quick reference
guide for them in the Template XML Schema.
You can create a very basic template using programs such as Notepad or Wordpad. Simply enter
the template XML tags that define the items that you want to appear on the interview page and
save the file with a .htm extension.
Note: If the template contains non-English characters such as characters with umlauts, you must
save the template in UTF-8 or Unicode format otherwise these characters will be displayed as ?.
For example, a template that produces the same page layout as the default is:
<html>
<head></head>
<body>
<mrBannerText/>
<br/>
<mrData/>
<br/>
<mrNavBar/>
</body>
</html>
<mrBannerText/> defines the position of information texts, <mrData/> defines the position of
the question and its response list, and <mrNavBar/> defines the position of the navigation buttons.
Because this does not produce very interesting pages, you will probably want to include
standard HTML formatting tags to insert font, point size, and color changes and to define the exact
position of the components on the page. You can do this either by typing the tags into a standard
829
Base Professional
text file, or by using a program such as FrontPage that converts your formatting requests into
HTML code. For example:
<html>
<head></head>
<body>
<center>
<b>
<font color="blue" size="4" face="Arial"><mrPageTitle/></font>
</b>
</center>
...
</body>
</html>
This displays the page title in large, bold, blue text in the center of the first line on the page.
Debugging Template Errors
Templates must be written in well-formed XML and must be XHTML compliant. Put simply,
this means that every tag must have an opening and a closing tag so, for example, you must
always write <br/> rather than just <br> to create a line break. If the XML in your template is
not well formed, you will see an error in the IVW*.tmp log file and the default template will be
used. You will also see messages in this log file if the template contains other errors such as
missing attributes on template tags.
An easy way to check whether a template is well formed and XHTML compliant is to make a
copy of the file with a .xml extension and then load that file into your browser. If the templates
loads correctly you will know that the template’s structure is not an issue.
If you have IBM® SPSS® Data Collection Base Professional installed, you can use the HTML
Tidy utility to ensure that your templates are valid. For more information, see the topic Validating
an interview template file on p. 87.
Example Templates
If you have access to IBM® SPSS® Data Collection Developer

Library, you will find a number of example templates in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Templates.
IBM® SPSS® Data Collection Interviewer Server also comes with a number of example
templates that are designed for using with the Build activity in IBM® SPSS® Data Collection
Interviewer Server Administration. It is not a good idea to edit these templates as your
changes may prevent them working with Build. However, you can make copies of them that
you can use as the basis for your own templates. These example templates are installed in
FMRoot\Shared\Templates\DataCollection.
Tips for Writing Templates

Tags can be general:
<mrData>All questions here</mrData>
or they can contain an index:

<mrData Index="1">First question here</mrData>
<mrData Index="2">Second question here</mrData>
830
Chapter 1
Questions or other items are inserted at the appropriate index. If an appropriate index does
not exist, the item is inserted at the general, unindexed tag. You should include a general
<mrData> tag as well as indexed <mrData> tags, to ensure that all items are inserted.
All mr tags and their parameters should be written using capitalization that matches that
shown in this documentation. While most tags will produce output regardless of case, you
may find that the effects are not those you expected if you do not use the documented format.
If special formatting is needed for specific items such as extra line breaks in some questions, it
is recommended that you use a sub-template.
Add placeholder text within your tags to support WYSIWYG formatting.
When writing pathnames in templates, always use a forward slash (/) rather than a backslash
(\) to separate the components of the path.
Using Forms
If you are an experienced HTML user, you can use additional <form>...</form> tags in your
layout template. This would allow you, for example, to display a button that participants could
click to switch to a different web-based application
When the interview player generates an interview page, it adds a form element to the page.
The positions in which it inserts the <form> tags varies according to the content of the template,
as follows:
If the template does not contain an <mrPage> tag, the Player inserts the <form> element
just inside the <body> element.
If the template contains an <mrPage> tag within the <body> tag, the Player attaches the
<form> tag to the <mrPage> parent, and all the child tags of the <mrPage> parent element
are inserted within the <form> tag
This information may be of use when deciding where on the page to place your own <form> tags.
Questions, Responses, and Error Messages
In terms of templates, a question consists of a banner, a question text (label), a response control,
and an error message, which you can display anywhere and in any order on the page. The easiest
way to display questions on a page is to place the following statement in the template at the point
you want the question text to start:
<mrData/>
This displays the question text with the response control indented below it. If the respondent
answers the question incorrectly, an error message is displayed above the question text.
The interviewing program inserts line breaks between the error message, the question text, and
the response control.
If there is more than one question to display on the page, the questions and their respective
response controls are displayed one after the other down the page.
If you want more control over the way the questions are displayed you will need to use the
fuller form of the tag as shown below. You’ll find more detailed descriptions and examples of
using the individual attributes in the topics that follow. Note that while those topics generally
831
Base Professional
deal with the attributes in isolation, you can include any combination of the listed attributes in a
single instance of the tag if required.
<mrData [Index='number'] [QuestionElement='Qpart' [ShowErrors='Errtype']]
[AutoComplete='TrueFalse']> [Text] </mrData>
where:
number is a number that identifies individual questions on a page that needs to display
more than one question.
Qpart specifies which part of the question to display at the current location and is one of:
Banner Question banners
Controls Response list or input box
Error Error message
Label Question text
Parameter Information for a custom control. For more
information, see the topic Custom Controls on p.
853.
Errtype specifies which error messages to display for questions in loops and blocks and
is one of:
All All errors
BottomMost Bottom level errors only
TopAndBottomMost Top and bottom level errors
TopMost Top level errors only
For more information, see the topic Error Messages for Questions in Loops and Blocks on p.
836.
TrueFalse determines whether auto-completion is enabled for the question. This feature
applies only to the Internet Explorer browser and is disabled by default.
Text is any text of your choice. The interviewing program ignores this text, but it is useful if
you want to test your template by opening the .htm file in your browser or with a program
such as FrontPage. In this case the text will be displayed in the position and with the attributes
defined in the file.
Laying Out the Components of a Question
Each question has four components: an optional banner defined in a separate information item, a
text, a response list or input box, and, when appropriate, an error message. You can specify the
positions of these components on the page by typing:
<mrData QuestionElement='Qpart']> [Text] </mrData>
832
Chapter 1
where:
Qpart specifies which part of the question to display at the current location and is one of:
Banner Question banners
Controls Response list or input box
Error Error message
Label Question text
Parameter Information for a custom control. For more
information, see the topic Custom Controls on p.
853.
For example, if you want to display error messages between the response control and the
navigation bar you would place the following statements in the template file:
<mrData QuestionElement='Label'/>
<mrData QuestionElement='Controls'/>
<mrData QuestionElement='Error'/>
<mrNavBar>
If the respondent clicks Next without choosing an answer, the page that this template generates is:
Figure 1-186
Page showing repositioning of Error element
There are two things in this page layout that are not a result of the instructions in the template:
The response list is indented, while the template shows it in line with the start of the question
and error texts. This is because the system default is to indent response controls. If you want
the response control lined up with the left of the page, set the indentation to zero (or even to a
negative value if necessary) by placing a statement such as:
IOM.DefaultStyles.Questions[..].Style.Indent=-1
833
Base Professional
in the routing section of the script. For more information, see the topic Indenting Response
Lists on p. 763.
The error message is in bold red type when nothing is specified in the template. This is the
system default. If you want to change this you should do so in the interview script. For
example, for purple, italic error messages you would type:
With IOM.DefaultStyles.Labels[LabelStyleTypes.lsError]
.Color = "#800080"
.Font.Effects = FontEffects.feItalic
End With
Displaying Response Controls Side by Side with Question Text
In some types of surveys you may want an interview page that looks like a form, with abbreviated
question texts followed on the same line by selection or input boxes. If you just write a
template that has the Label and Controls elements on the same line separated by spaces, the
interviewing program will allocate as much space as it needs to each question text and will then
append the response list or input box to the end of the line. Nothing will line up and the page
may be hard to use.
One solution is to use a table; an alternative is to use interview scripting alignment features
and to set a maximum width for the question texts in the script so that long texts are forced
to wrap across lines.
Here is a simple form created using the following tags in the body of the template:
<table>
<tr>
<td><mrData Index="1" QuestionElement="Label"/></td>
<td><mrData Index="1" QuestionElement="Controls"/></td>
</tr>
Repeat definition for indexes 2 to 5
<tr>
<td><mrData Index="6" QuestionElement="Label"/></td>
<td><mrData Index="6" QuestionElement="Controls"/></td>
</tr>
</table>
Figure 1-187
Question texts and response boxes side by side
834
Chapter 1
Additional points to notice about this example are:

The categorical response list has been displayed as a drop-down list to maintain the form-like
appearance of the page.
The page displays six questions and the template defines positions for each question
individually. This ensures that the question texts line up with their respective response
controls. If you use a single <mrData> tag for all questions and do not specify any alignment
parameters in the script, you may find that the question texts and response boxes do not line
up because the boxes take up more vertical space than the texts. For further information about
templates for displaying more than one question on a page see More Than One Question
on a Page.
Automatic Completion of Data Entry Fields
The AutoComplete feature in Internet Explorer remembers texts and other values that you enter in
web pages and then offers selected items as possible input for fields on other web pages. As you
type information into a field, Internet Explorer compares the characters you type with the stored
values and displays any entries that match. If the list contains the information you have started
typing, you can select it from the list. If not, simply continue typing as normal.
This feature is turned off in the interviewing program, but you can switch it on and off as you
want by placing the following statement in the page template:
<mrData AutoComplete='value'/>
where
value is either True or False.
For further information about AutoComplete, see your Internet Explorer online help.
When your script places more than one question on a page you have the choice of positioning
some or all of the questions one by one, or of automatically placing them one after the other
at a given starting point on the page. The default template uses the second method so that the
questions follow one another down the page. To position the questions individually, use the
QuestionName or Index attribute to refer to each question by name or according to its position
in the set of questions for the page:
<mrData QuestionName='qname' [attributes]> [Text] </mrData>
<mrData Index='number' [attributes]> [Text] </mrData>
where:
qname is the question’s name.
number is a number that identifies individual questions on the page. Questions are numbered
sequentially from 1 in the order they are named on the page statement.
835
Base Professional
attributes are any other attributes that can be used with <mrData> (typically,
QuestionElement).
For example, if the metadata section contains the statement:
demog "" page (gender, age, mstat, region);
and you want the page to look like this:

Figure 1-188
Page with two rows of two questions each
you would place the following statements in the template. Either:
<table>
<tr>
<td><mrData QuestionName="gender"/></td>
<td><mrData QuestionName="age"/></td>
</tr>
<tr>
<td><mrData QuestionName="mstat"/></td>
<td><mrData QuestionName="region"/></td>
</tr>
</table>
or:
<table>
<tr>
<td><mrData Index="1"/></td>
</tr>
<tr>
</tr>
</table>
836
Chapter 1
In this example, the additional spacing between the columns has been achieved by setting the
width of the question tag for the gender question in the interview script. For more information,
see the topic Horizontal Alignment on p. 800.
Points to bear in mind when using this facility are as follows:
QuestionName and Index are interchangeable. In some respects, question names are better
than indexes because it is immediately obvious which questions you are referring to. Also, if
you insert extra questions, the index numbers will change and the template may no longer
refer to the questions you expected. References to question names are not affected in this way.
However, using question names ties the template to one set of questions. If you want to use
the same layout for all pages with four questions, it is better to use index numbers.
Question names take priority over indexes, so if QuestionName and Index appear on the
same <mrData> tag, Index is ignored.
If two <mrData> tags reference the same question in different ways, the question will be
inserted at both locations.
The templates shown earlier have the same number of question names and indexes as there are
questions to display, but it is good practice always to include a tag with no attributes at the end
of the definition to catch any questions that are not represented by a named or indexed tag. This
means that the template will still work even if the page statement names more questions than
there are question names or index numbers. The layout will not be perfect, but you will generally
pick this up while testing the script. If you do not define an empty tag, any extra questions will not
be displayed, and you are less likely to notice this during testing. For example if the template
contains:
<mrData QuestionName="age"/>
<mrData QuestionName="mstat"/>
<mrData Index="1"/>
<mrData Index="3"/>
<mrData/>
the rendered page will show age, mstat, gender, mstat, and region in that order.
Error Messages for Questions in Loops and Blocks
When a respondent answers a question in a loop or a block incorrectly, there is usually more than
one message that can be displayed. The default is to display messages related to the question itself,
as shown in the following illustration, but you can display other messages as well if you wish:
Figure 1-189
Three-dimensional grid with messages for the repeated question only
837
Base Professional
The interviewing program generates one message related to the question itself and then a further
message for each level of nesting, so the number of messages you can display depends on how
deeply the question is nested. For example, if you have a loop that contains an inner loop, and the
respondent incorrectly answers a question in the inner loop, there will be one message for the
question and one for each of the loops, making three messages in all. You can use the ShowErrors
attribute of the <mrData> tag to specify which messages you want to display:
<mrData QuestionElement='Error' ShowErrors='Errtype']> [Text] </mrData>
where:
Errtype is one of:
All All messages.

BottomMost Messages for the question level only (the default).
TopAndBottomMost Messages for the question and outermost levels only.
TopMost Messages for the outermost level only.
If you add the tag:
<mrData QuestionElement="Error" ShowErrors="All"/>
to the template and rerun the previous example, you will see an additional error message for
the loop as a whole:
Figure 1-190
Three-dimensional grid with all messages displayed
Banners (Information Texts)

To display banner (information) text , place the following statement in the template at the point
you want the text to appear on the page.
<mrBannerText [Index="number"] [Name="name"]> [Text] </mrBannerText>
where:
number is the number of the banner to be inserted.
838
Chapter 1
name is the name of the banner to be inserted.

For example, suppose that the metadata section defines an information item called bantxt which
contains the words “PERSONAL DETAILS”. If the routing section contains the statements:
IOM.Banners.Add("ban01", bantxt.Label)
IOM.Banners["ban01"].Style.Font.Effects = FontEffects.feBold
IOM.Banners["ban01"].Style.Font.Size = 12
and the template contains:
<mrBannerText Name = "ban01"/>

<p/>
<mrData QuestionElement = "Label"/><mrData QuestionElement = "Controls"/>
the page for personal details will be displayed as follows:

Figure 1-191
12-point, bold banner text displayed above questions with side-by-side text and responses
The name and number parameters are both optional with <mrBannerText>. You can combine
statements that use name with statements that use number, and with statements that use neither.
This gives you ultimate flexibility in the way your template can control any number of banner
texts on a page. For instance, suppose your banner template is:
<mrBannerText Index=1/>
<mrBannerText/>
<mrBannerText Name="ban03"/>
The first banner defined for the page replaces <mrBannerText Index=1/>. The banner named
ban03 replaces <mrBannerText Name="ban03"/>. Any other banners will be inserted in
the middle.
The interviewing program ignores <mrBannertText> tags if the current page does not have a
banner. This means that there is no need to create special templates for pages that have banner text
unless you want the rest of the page to look different from your standard page.
839
Base Professional
Page Titles
To display the interview title (defined in the IOM.Title property in the routing section), place the
following statement in the template at the point you want to see the text:
<mrPageTitle> [Text] </mrPageTitle>
where:
For example, if the routing section contains:
IOM.Title="Employee Satisfaction Survey"
IOM.DefaultStyles.Questions[QuestionStyleTypes.qsCategorical].Style.Columns = 2
and the page layout template includes the following tags:

<font color="red" size="3"><center><b>
<mrPageTitle/>
</b></center></font>
<br/><br/>
<mrData/>
<br/>
<mrNavBar/>
pages will look similar to the one shown here:

Figure 1-192
Page showing centered, red page title
If you do not specify a page title, the interviewing program will display the name of the current
question instead.
Navigation Buttons
The standard navigation bar has Next, Previous, and Stop buttons and is always displayed at the
foot of the page after the last response line or other text. The interviewing program hides the
Previous button on the first question. To display this navigation bar, place the following tag at the
point you want the navigation bar displayed:
<mrNavBar> [Text] </mrNavBar>
840
Chapter 1
where:
If you would like more control over the navigation buttons, you can use the <mrNavButton> tag
to specify which buttons you want to display and where, and the labels to use for each button.
To display an individual navigation button, optionally with a label of your choice, place the
following statement in the layout template:
<mrNavButton Name='name' [Text='label'] Enabled='filename' Disabled='filename'>
[Text] </mrNavButton>
where
name is the button’s internal name and is one of Next, Prev, Stop, First, Last, or Goto.
label is the text to display on the button. The default is to display the button’s internal name.
filename is the name of the image file to display when the button is available (enabled)
or unavailable (disabled) for use. Enabling or disabling a button in this way overrides the
specification for the image in the interviewing program itself.
If you are happy with the size and shape of the standard navigation buttons but would rather have
different words displayed on them, just define the text you want to use when you display the
button. There is no need to create new images for the buttons. For example:
<mrNavButton Name="Prev" Text="Back"/>
to display the standard Previous button but labelled Back instead of Previous.
If you want to make more radical changes you can design your own navigation buttons. The
following illustration shows a page with three customized navigation buttons, where the first
one is disabled.
Figure 1-193
Page with Back button disabled
841
Base Professional
To generate a similar effect in your interviews place the following statements in your template:
<mrNavButton Name="Prev" Enabled="onprev.gif" Disabled="offprev.gif"/>
<mrNavButton Name="Next" Enabled="onnext.gif" Disabled="offnext.gif"/>
<mrNavButton Name="Stop" Enabled="onstop.gif" Disabled="offstop.gif"/>
An alternative to displaying a disabled image for navigation buttons that are unavailable is to
remove the button from the Navigations collection. For example:
IOM.Navigations.Remove(NavigationTypes.nvNext)
Because the button has been removed from the collection, any buttons that come after it will be
moved up so that there are no spaces in the navigation bar when it is displayed.
If you are familiar with HTML code, you can take more control over the navigation bar by using a
<form>...</form> section to display the navigation bar at the side of the page. If used, the
Form section must come within the Body section of the code.
Automatic Focus on the Next Button
When entering numeric or text responses, it’s often an automatic reaction to press the Enter key to
move to the next question. Unfortunately, because of the way that some browsers work on some
machines, this takes you back to the previous question instead. This is typically a problem with
Internet Explorer on Windows PCs, where pressing Enter instructs the browser to search for the
first navigation button on the page, which is usually the Previous button. You can get around this
problem in most cases by changing the way navigation buttons are specified in your templates,
but note that this may not resolve the problem for all browsers.
The following code is provided “as-is” and you may use it if you wish, but there is no guarantee
that, if it works now, it will continue to work for all browsers or that it will work if the way in
which browsers interpret HTML pages changes.
In your templates, replace the tags that display the navigation buttons with the following code.
This code reflects the tags in the default layout template so you may need to amend it slightly if
you use different tags in your templates.
<table id="Table1" cellspacing="1" cellpadding="1" width="300" border="0">
<tr>
<td></td>
<td valign="bottom" rowspan="2">
<mrNavButton Name="Next" Text="Forward" />
</td>
</tr>
<tr>
<td valign="bottom">
<mrNavButton Name="Prev" Text="Previous" />
</td>
</tr>
</table>
842
Chapter 1
Progress Bars
If you want to give respondents an idea of their progress through the interview you can include an
<mrProgressBar> tag in your template. The default progress bar is a single, thin blue line that
appears when the second and subsequent pages are displayed:
Figure 1-194
Page with default progress bar
This is not particularly satisfactory because there is no indication of where the bar will end,
so the respondent cannot calculate his/her relative position in the bar (in fact, it extends the
full width of the browser window). Additionally, the respondent may not realize straight away
that this is a progress bar.
You can resolve these issues to some degree by placing <mrProgressBar> inside a <div> tag and
then adding standard HTML code to alter the appearance of the progress bar. For example:
<div style="height:15px;width:250px;border-width:1px;border-style:solid;">
<mrProgressBar/>
</div>
Figure 1-195
Progress bar with border and shorter length
You can improve things further by using some of the attributes that <mrProgressBar> supports:
<mrProgressBar>
[ShowBar='TrueFalse'] [ShowCounts='type']
[Color='color'] [Image='filename']
[Orientation='orientation']
[Text]
</mrProgressBar>
where:
TrueFalse is True to display the progress bar or False to suppress it.
type determines how progress is to be reported, and is either AsValues to display counts or
AsPercentage to display a percentage. A third option is to use False which switches off the
text so that only the bar is displayed.
color is the color of the progress bar.
filename is the name of the file containing the image you want to use for the progress bar.
843
Base Professional
orientation is the orientation for the progress bar and is either Horizontal (the default)
or Vertical.
Here are a couple of examples that illustrate these attributes in action. The template for the
first example contains:
<div style="height:15px; width:250px;">
<mrProgressBar Color="red" ShowCounts="AsPercentage"/>
</div>
which displays a red progress bar followed by the percentage of questions answered so far. For
information about how counts are calculated and for suggestions on how you can change this
behavior by writing code in the routing section, refer to How to Calculate Progress:
Figure 1-196
Read progress bar with percentage complete
The template for the second example defines a customized image for the progress bar and displays
it vertically on the left of the screen. It uses a table to ensure that the progress bar is always
a fixed distance from the question.
<table>
<tr>
<td width="25">
<div style="height:100px;">
<mrProgressBar ShowCounts="AsPercentage"
Orientation="Vertical" Image="progbar1.gif"/>
</div>
</td>
<td>
<mrData/>
</td>
</tr>
</table>
844
Chapter 1
Figure 1-197
Vertical red arrow progress bar on left of page
When you use images such as the arrow shown here, you will notice that the image is either
squashed or stretched to fill the required amount of space. You can avoid the image distortion
that sometimes happens with this by using a solid block instead.
Note: When a script displays more than one question on a page, the progress bar treats each
page as one question regardless of the number of questions displayed. So, if the script contains
two pages with four and six questions respectively, the progress bar shown when questions 5
to 10 are displayed will always report 50%.
How to Calculate Progress
The calculations for counts and percentages are very simple and are based on the total number of
pages defined in the metadata section. (If each page displays a single question this is the same
as saying that the counts and percentages are based on the number of questions in the script.)
AsValues reports the position of the current page in the question list and the total number of pages
in the form answered/total; AsPercentage reports the same information as a percentage. So, if
there are ten questions in the metadata section with each one displayed on a separate page, and the
respondent has answered the first five questions, progress is always 5/10 or 50% respectively.
If you want to report progress more accurately by ignoring pages that do not apply to the
current respondent, you will need to calculate progress manually in the routing section of the
script. There are various ways of doing this, but there are some interview properties you need to
know about first. These are:
IOM.Info.EstimatedPages. The number of pages you expect respondents to see. This defaults to
the number of pages in the interview metadata, which is the same as the value returned by the
IOM.Questions.Count property (it assumes that each question is displayed on a separate page).
IOM.Info.EstimatedProgress. The number of pages answered so far as stored in the
IOM.Info.PagesAnswered property. (All pages are counted once only regardless of the
number of times they are displayed, for example, due to snapbacks.)
Setting the Number of Pages To Answer
If the script contains routing so that respondents do not answer all questions (pages) in the
script, you may be able to estimate the maximum number of pages that respondents or groups
of respondents will answer. If you set this value into IOM.Info.EstimatedPages, the progress
845
Base Professional
calculations will be made using this value rather than the total number of pages in the script. For
example:
IOM.LayoutTemplate = "WithOutBar.htm"
Q1.Ask()
IOM.LayoutTemplate = "WithBar.htm"
If Q1 = {Response1} Then
IOM.Info.EstimatedPages = 3
Q2.Ask()
Q3.Ask()
Else
IOM.Info.EstimatedPages = 4
Q4.Ask()
Q5.Ask()
Q6.Ask()
End If
The example uses two templates, one without a progress bar, which is used before we know how
many questions the respondent is likely to answer, and the other with a progress bar, which is used
for the rest of the script. The answer to Q1 determines which questions are asked, so it is at this
point that we set the estimated number of pages that the progress calculations will use. The page
that a respondent answering Q6 will see is as follows:
Figure 1-198
Progress bar using EstimatedPages
Setting the Estimated Progress Value Manually
If it is not practical to specify the number of pages respondents will answer, you can specify the
number of pages that have been answered after each question (you may have to estimate this if
not everyone answers all questions). When you specify values for IOM.Info.EstimatedProgress,
progress is calculated by comparing this value against the total number of pages in the script. It
does not matter how many pages a respondent actually answers to reach a given question, progress
at that point will be identical for all respondents because it is based on two fixed values. Here is
a routing script that illustrates this:
Q1.Ask()
IOM.Info.EstimatedProgress = 1
Q2.Ask()
Q3.Ask()
End If
End If
Q4.Ask()
Q5.Ask()
End If
846
Chapter 1
There are five questions in the script, each displayed on a separate page, so when progress is
reported at Q4 it will always be 3/5 or 60% even if some respondents have only answered Q1 so far.
In long scripts it will be tedious to set progress in this way, but you can cut down on the amount
of work involved by using the OnAfterQuestionAsk event.
Events are named points in the timeline of an interview, which allow you to specify things that
are to happen at those points (see Events for more details). The OnAfterQuestionAsk event defines
what is to happen after a question has been asked. If you insert a generic statement in this event
that increments the value of the EstimatedProgress property, you avoid having to write a separate
statement after each page. The only time you will need to specify the value of this property
manually is when a respondent is routed around a page that is not applicable. Here is a simple
routing script that illustrates the general procedure:
Q1.Ask()
Q2.Ask()
Q3.Ask()
Else
IOM.Info.EstimatedProgress = IOM.Info.EstimatedProgress + 1
End If
Else
End If
Q4.Ask()
Q5.Ask()
Else
End If

End Sub
If we follow two respondents through this script until Q4 is displayed we can see how progress
is calculated for each one. There are five questions in the script. The first respondent chooses
Response1 at Q1. When the respondent clicks Next, the OnAfterQuestionAsk event runs and
increments EstimatedProgress by 1. The respondent chooses Response1 at Q2 and then again at
Q3, and each time the OnAfterQuestionask event increments EstimatedProgress so that, when Q4
is displayed, progress is shown as 3/5 or 60%.
The second respondent chooses Response2 at Q1, and then something other than Response1 at Q2.
When the respondent clicks Next on both these questions the OnAfterQuestionAsk event runs and
increments EstimatedProgress by 1. This respondent is not eligible to answer Q3 but still needs to
have EstimatedProgress set correctly by the time Q4 is reached. This is achieved by manually
incrementing the property by 1 for each question that is skipped; this happens in the Else clause
of the section that tests the answer to Q2. The property has been incremented automatically or
manually for each question answered or skipped, so progress for respondent 2 is shown as 3/5 or
60% at Q4, the same as for respondent 1 who answered all questions.
Note: Once you set a value for EstimatedProgress in the script, the interviewing program will
always use this value for the property. It does not use this as the starting value and then increment
it automatically for each question subsequently asked.
847
Base Professional
Sub-Templates
Sub-templates define the layout of one component of the interview page, and you can create
them for questions (question and responses), errors, banners, navigation buttons, and grids. You
will normally use them when you want to vary the way that page components are displayed
within a single project or between projects, while always using the same overall page layout. For
example, if you use the standard DefaultLayout.htm template that comes with IBM® SPSS® Data
Collection Interviewer Server, a question that is defined as:
TeamSports "Which team sports do you play?" categorical [1..6]
{
Netball, Basketball, Football, Rugby, Cricket, Baseball,
OtherTeamSport "Other" other,
None na
};
will appear as:

Figure 1-199
Question using default layout template
848
Chapter 1
If you use the same layout template with a question template that displays the question text and
response controls in columns across the page, your page will be:
Figure 1-200
Question using question sub-template
When you use sub-templates, the interviewing program reads the layout template and replaces
any mr tags that have no controls specified (for example, <mrData/>) with the contents of the
appropriate sub-template. So, an <mrData/> tag is replaced with the contents of the question
sub-template, while an <mrNavBar/> tag is replaced with the contents of the navigation
sub-template, and so on. mr tags that have attributes specified are not replaced.
Creating a Sub-Template
A sub-template is an .htm file in which the contents are all part of an <mrSubTemplate>
tag. Inside this tag you can use any HTML tags that you like, including the special mr tags, to
define the layout and appearance of this component. The question sub-template file used in the
previous example is:
<mrSubTemplate>
<table>
<tr>
<td><mrData QuestionElement="Label"/></td>
<td><mrData QuestionElement="Controls"/></td>
</tr>
<table>
</mrSubTemplate>
Naming the Sub-Templates to be Used

There are two ways of naming the sub-templates you want to use: in the interview script or in
the layout template. To name sub-templates in the script, place statements of the following form
in the routing section of the script:
Item.TypeTemplate="filename.htm"
If the sub-template applies to an individual question only, you can name it with the templates
keyword as part of the question’s definition in the metadata section of the script. For further details
of both these methods, refer to Naming Templates in the Script.
849
Base Professional
So, to use the side by side sub-template for questions, as in the earlier example, you might type:
IOM.LayoutTemplate = "DefaultLayout.htm"
TeamSports.QuestionTemplate = "qrsidebyside.htm"
To name sub-templates in the layout template, use an <mrPage> tag:

<mrPage [QuestionTemplate='pathname'] [BannerTemplate='pathname']
[ErrorTemplate='pathname'] [NavBarTemplate='Npathname']
[GridTemplate='Gpathname']> [Text]
</mrPage>
where:
pathname is the relative pathname of the question, banner, or error sub-template to use when
replacing <mrData> tags in the layout template that do not specify a question, banner, or
error element as appropriate.
Npathname is the relative pathname of the navigation sub-template to use when replacing
<mrNavBar> tags in the layout template.
Gpathname is the relative pathname of the grid sub-template to use for formatting questions
in categorical and numeric grids.
For example:
<mrPage QuestionTemplate = "qrsidebyside.htm"/>
Examples
You’ve already seen an example of how a question sub-template alters the appearance of the
question and response block. Here are examples of using error and navigation sub-templates
to affect the appearance of the error message and navigation bar sections of the page. Both
sub-templates are used with the default layout template in its installed form.
850
Chapter 1
The following illustration shows how to display an image as part of the error message:
Figure 1-201
Question using error sub-template
The error template that defines this is:

<mrSubTemplate>
<table>
<tr>
<td><mrRef RefType="img" src="error.gif"/></td>
<td><mrErrorText/></td>
</tr>
</table>
</mrSubTemplate>
The following illustration shows how to use images in place of navigation buttons:
Figure 1-202
Question using navigation sub-template
851
Base Professional
The navigation template that defines this is:

<mrSubTemplate>
<mrNavButton Name="first" Enabled="first.gif"/>
<mrRef RefType="img" src="Spacer.gif"/>
<mrNavButton Name="prev" Enabled="prev.gif"/>
<mrNavButton Name="next" Enabled="next.gif"/>
<mrNavButton Name="last" Enabled="last.gif"/>
</mrSubTemplate>
Note: The First and Last buttons will not be displayed unless you request them by placing the
following (or similar) statements in the routing section of the script:
IOM.Navigations.Add(NavigationTypes.nvFirst)
IOM.Navigations.Add(NavigationTypes.nvLast)
The following illustration shows a repeated question in which errors for all levels have been
displayed:
Figure 1-203
Question using sub-template to control which errors are displayed
The question sub-template that created it is:

<mrSubTemplate>
<mrData QuestionElement="Error" ShowErrors="All"/>
<mrData QuestionElement="Label"/>
<mrData QuestionElement="Controls"/>
</mrSubTemplate>
Referring to External Files
External files are image files, stylesheets, or files containing Javascript that you want to use in
the current template. When you write and test a script using IBM® SPSS® Data Collection
Base Professional, you may have these files in a different location to where they will be for live
interviews. This means that you have to remember to change the references to the files in the
template before you activate. A better approach is to name these files in the template using an
<mrRef> or <mrSharedRef> tag. The <mrRef> and <mrSharedRef> tags are similar except
that the <mrRef> tag is typically used to reference project specific files while the <mrSharedRef>
tag is used to reference files that may be shared across projects (like Javascript frameworks used
to support custom controls or large media files). Tag usage examples are shown below.
852
Chapter 1
When a template contains an <mrRef> tag and you test your script in Base Professional, the
interviewing program looks for external files in folders relative to the location of the template.
When you activate the project, the <mrRef> locations are prefixed with the image cache URL
or, if you are manually copying the files to the web server, with the relative path to the images
folder. The interviewing program for live interviews will find the external files without you
needing to make any changes to the template.
<mrRef> tag
The syntax of the <mrRef> tag is as follows:
<mrRef RefType="type" attribute="value" ...> [Text] </mrRef>
where:
type is the tag name that you would normally use to reference a file of the current type; for
example, a for hyperlinks, img for images, link for stylesheets, and script for Javascript
files.
attribute is an attribute that you would normally specify on the type tag, as follows:
Tag Attributes Required

<a> src, alt
<img> src, alt. id is also beneficial. Other attributes may
be included as necessary.
<link> rel, type, href
<script> type, src
value is the value for that attribute.

There are two general points to remember when using <mrRef>:
The following keywords are case sensitive and must be specified exactly as shown here
otherwise the interviewing program will not recognize it and your template will not work:
mrRefTag, RefType, href, src.
Not all the HTML tags support the empty tag format: <script>, for instance, does not support
the <script/> notation and will not display anything if a tag of this form is read. To avoid this
problem, always place some text between the opening and closing<mrRef> tags. If you’re
referencing a Javascript program, you might like to type a short description of what the
program does.
You may define any number of attributes and values simply by listing them one after the other,
separated by spaces. When the interviewing program reads the <mrRef> tag, it builds an ordinary
HTML tag using the information given with <mrRef>. For example, if the <mrRef> tag is:
<mrRef RefType="img" src="logo.jpg" alt="SPSS logo" border="0">Dummy text</mrRef>
the instructions will be passed to your browser will be:

<img src="logo.jpg" alt="SPSS logo" border="0"/>
Similarly:
<mrRef RefType="link" rel="stylesheet" type="text/css" href="Standard2.css">Dummy text</mrRef>
853
Base Professional
becomes:
<link href="Standard2.css" rel="stylesheet" type="text/css"></link>
<mrSharedRef> tag
The <mrSharedRef> tag provides similar functions as the <mrRef> tag, but locations used in
<mrSharedRef> are based on a global location, as defined below:
Web/CATI Survey and IBM® SPSS® Data Collection Author Server Edition
[FMRoot]\Shared\Content
IBM® SPSS® Data Collection Interviewer, IBM® SPSS® Data Collection Author, and
Base Professional
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\\SharedContent
Desktop products, such as Interviewer, Author, and Base Professional, will use the above location
as a prefix when referencing files specified in <mrSharedRef>. For example,
<mrSharedRef RefPosition="head" RefType="script" type="text/javascript" src="/Dojo//dojo/dojo.js" djCo
will be rendered in Base Professional as:

<script type="text/javascript" src="C:\Documents and Settings\All Users\Application Data\IBM\SPSS\Data
For server products, such as IBM® SPSS® Data Collection Interviewer Server and Author Server
Edition, the same tag might be rendered and loaded from the shared content area using the
ImageCache. For example:
<script type="text/javascript" src="Images/Dojo/dojo/dojo.js" djConfig="parseOnLoad: true">Dojo script
In addition, when referring to Javascript frameworks like Dojo, you can update the examples to
use hard-coded links from a content delivery network. For example:
< script type="text/javascript"
src=" http://ajax.googleapis.com/ajax/libs/dojo/1.5/dojo/dojo.xd.js"
djConfig="parseOnLoad: true">
Custom Controls
Custom controls are controls that you define and then place on the page using a sub-template.
The IBM® SPSS® Data Collection Developer Library contains examples of slider and calendar
custom controls that you can use as they come or customize to suit your company’s requirements.
The general procedure for writing and using a custom control is as follows.
Write the control in HTML and Javascript and save it in a file in the project folder. The control
logic should be implemented in a separate .js file.
Create any images that are required by the template and save them in the project folder.
854
Chapter 1
Create a question sub-template and add the extra tags that name the .js file and place the
control on the page. For more information, see the topic Sub-Templates for Custom Controls
on p. 854.
Define the questions in the metadata section of the script and use the templates parameter
to name the sub-template to be used. For more information, see the topic Using a Custom
Control on p. 855.
Sub-Templates for Custom Controls
A sub-template for a custom control contains all the things that an ordinary sub-template contains,
plus the following items that are specific to the custom control:
1. An <mrRef> tag that names the Javascript file containing the specification for the custom control:
<mrRef
RefType="script" RefPosition="head" type="text/javascript" src="filename">Text</mrRef>
where:
RefPosition="head" says to place the reference to this file in the <head> section of the
HTML document that the Player creates for the page. This allows you to use the same custom
control more than once on a page without having to repeat the reference for each use.
filename is the name of the Javascript file that contains the code for the control.
Text is any text of your choice. A brief description of what the control does is useful.
Place this statement at the start of the template file, after the <mrSubTemplate> tag.
2. A <script> section that places the custom control in the page’s HTML document using <mrData
QuestionElement="Parameter"> tags to reference the question:
<mrData QuestionElement="Parameter" Type="PType"/>
where PType is the type of information you want to set or request, and is one of:
FullQuestionName The full question name including the _Q prefix used
in the HTML document to identify questions.
ImageLocation The image location that is inserted before image
tags, mrRef tags, and so on.
A backslash is output as \\ which makes it easier to
use ImageLocation as a string. Ampersand is output
as &
Label The question text without any style formatting.
(Normally, the question text is output in a <span>,
preceded by a <div> tag.) Using the Label
parameter type returns just the question text. If the
text contains HTML tags, these will be passed as
they are defined provided that they are well formed.
Max The maximum value defined on the validation node.
Min The minimum value defined on the validation node.
QuestionName The question name.
855
Base Professional
All parameters are inserted as text so they must be well formed XML. This means that any
reserved characters will be escaped. This happens mostly in the ImageLocation parameter. The
image cache will typically contain a simple & character which will output as &amp. If the location
is to be used in a script, you will need to convert all occurrences of &amp to &.
Placing the Control using the Question Input ID
You can obtain a question’s input using the FullQuestionName setting as follows:
var QuestionInput = document.getElementById("<mrData QuestionElement="Parameter" Type="FullQuestionNam
You must do this in order to set the question’s response.
Placing the Control using a Tag with a Known ID
If you know the ID of the control, you can access the control using its ID. In the following
example, the custom control consists of a slide bar image that has the ID “RailImg”. It is
displayed on the page by the <mrRef> tag. When we need to refer to the image in the <script>
section, we use this ID. The image is located using getElementById and is renamed using the
FullQuestionName parameter in order to ensure a unique identifier.
<mrRef RefType="img" id="RailImg" src="SliderRail.jpg" style="width: 500px; height: 50px"/>
<script type="text/javascript">
var Rail<mrData QuestionElement="Parameter" Type="FullQuestionName"/> =
document.getElementById("RailImg")
Rail<mrData QuestionElement="Parameter" Type="FullQuestionName"/>.id =
"Slider<mrData QuestionElement="Parameter" Type="FullQuestionName"/>RailImg"
...
</script>
For more detailed examples of how to write custom controls, refer to the Calendar.htm and
Slider.htm files in the subfolders of Scripts\Interview\HTML Controls in the IBM® SPSS®
Data Collection Developer Library. You can see these custom controls in action by running the
NewFeatures script in the Scripts\Interview\Projects\NewFeatures folder in the Data Collection
Developer Library.
Using a Custom Control
To use a custom control, define the question in the usual way and then add the templates
parameter to name the sub-template that contains the control. For example:
AttendDate "When did you visit the exhibition?" templates(Question="calendar.htm") date;
Clickable Response Texts
To allow respondents to select categorical responses by clicking on the response texts rather
than on a radio button or check box, add an <mrPage> tag to the template that sets the
IncludeElementIDs attribute to True, as follows:
<mrPage IncludeElementIDs='True'>[Text]</mrPage>
This adds element IDs to the rendered HTML, and may be required if you are including JavaScript.
However, note that this makes the generated HTML larger so that pages load more slowly.
856
Chapter 1
If your template contains other <mrPage> tags you may place this attribute on any of those
tags rather than writing a new tag.
Adding CSS Class Names to the Rendered HTML
To add CSS class names to the rendered HTML, use an <mrPage> tag with the
IncludeCSSNames attribute set to True, as follows:
<mrPage IncludeCSSNames='True'>[Text]</mrPage>
If your template contains other <mrPage> tags you may place this attribute on any of those
tags rather than writing a new tag.
Grid Templates
Grid template files are XML files that determine how a grid will appear on the interview page,
and are an alternative to defining styles for grid questions in the metadata or routing sections of
the script. The statements or tags that you can use in your grid templates are defined in an XML
schema file called mrigf.xsd. If you install the IBM® SPSS® Data Collection Developer Library,
you will find it in the Scripts\Interview\Templates in the folder in which you installed the DDL.
If you have an XML authoring tool such as XML Spy that supports schemas, you can validate
your grid template against the schema to ensure that the XML code you have written is valid. If
you do not have an XML authoring tool, you can work with any text editor of your choice, but you
will be responsible for ensuring that the code you write is correct. If you want to validate your grid
templates, you can download a free XML schema validator from http://www.w3.org/XML/Schema.
The interviewing program comes with a number of predefined grid templates. You may find
that you can use these templates as they are or with a little alteration, in which case you will not
need to build your own templates.
XML tags look and behave the same as HTML tags. In fact, if you are familiar with XML or
HTML you may recognize many of the tags. All tags in a grid template are case sensitive and
must be entered exactly as shown in this chapter. Mistyping tags in any way causes the grid to
be displayed in the default format. If you have a schema validator, it will flag any statements
where the case of a tag is incorrect as errors.
You can create any number of grid templates, related either to individual questions or to groups of
similar questions. You can call the grid template files anything you like as long as they have a
.xml extension.
Should I Use a Grid Template?
Support for grid templates is primarily aimed at companies who have been using IBM® SPSS®
Data Collection Interviewer Server prior to version 3.0. It allows them to continue to use their
existing templates rather than having to update their scripts to use the new methods provided by
the Interview Object Model. The notes in this section provide some guidance on which grid
template facilities are supported in interview scripting for Interviewer Server 3.0 and later, and
will be useful not only for scriptwriters moving from earlier versions but also to newer users who
might wish to consider using grid templates for some of their projects.
857
Base Professional
Grid templates are not applied to grids that are part of compound questions.
Grid templates work only if the loop contains simple questions all at one level. They do
not work with nested loops.
You cannot set styles for the top left cell of the grid (this applies to the Interview Object
Model too).
The altBodyRow styles are applied only if Orientation is Row; altBodyCol styles are
applied only if Orientation is Column.
The colWidths style for defining column widths is not supported.
Styles set using the Interview Object Model have precedence over styles defined in a grid
template.
The grid template style information is applied to the Player XML before the page is rendered.
The following table shows the relationship between grid template styles and grid styles in the
Interview Object Model.
Grid Template Style Interview Object Model Style
Cell Styles
align Align
height Cell.Height
nowrap Cell.Wrap. Note that the logic is inverted. For more
information, see the topic Wrapping Text in Cells
on p. 789.
valign VerticalAlign
width Cell.Width
bgColor Cell.BgColor
font, fontFace Font.Family
font, fontPoint Font.Size. Grid templates use 1-7 for the font size,
whereas the Interview Object Model uses units.
font, fontEffects FontEffects.IsEffect. Not all the font effects can be
supported.
font, fontColor Color
font, fontStyle Font.IsStyle. The Interview Object Model uses
IsBold and IsItalic for bold and italic settings
Table Styles
align Align
borderSize Cell.BorderWidth
cellPadding No corresponding option. You can set the padding
for every cell, although this is not very efficient.
cellSpacing No corresponding option.
width Width
Header Style
repeat Cell.RepeatHeader. Only header rows can be
repeated.
858
Chapter 1
Starting a Grid Template
A grid template definition is enclosed in the following tags:

<gridFormat> ... </gridFormat>
If you are using an XML authoring tool and want to be able to validate your template against
the grid schema, you will need to include information about the schema on the opening
<gridFormat> marker. You can copy this information from one of the example templates.
All grid templates must have a name. You define this on the line immediately below the
<gridFormat> marker, by typing:
<name>text</name>
where
text is the name or description of the template.
If you want to display a caption centrally below the grid, rather like a table or figure number
in a book, type:
<comment>text</comment>
Levels in a Grid Template
A grid template can contain formatting information at the following levels (shown in ascending
order of precedence:
grid level
all cells
alternate rows
alternate columns
heading row (column headings)
heading column (row headings)
If the same tag appears at two or more levels in the template, the tag at the lower level overrides
the same tag at the higher level for that particular aspect of the grid only. This allows you to define
global characteristics for all cells in the grid and then to override certain of those characteristics
for, say, the row headings. For example, you can have centered, bold, red text in all cells except
the row headings which are left-aligned but still have bold, red text.
The grid and all-cells levels refer to the grid as a whole, and you’ll normally define global
specifications as relating to all cells rather than the grid itself. There are, however, some tags such
as <name> and <colWidths> that cannot be defined at the all cells level and must be defined at
the grid level. There are also some tags that mean different things when used at these levels. For
example, <width> at grid level defines the width of the whole grid whereas at all-cells level it
defines the widths of the individual columns.
To enter tags at the grid level, type them inside the <gridFormat> markers. To define global
characteristics for all cells in the grid, place the appropriate tags within the following markers:
<allCells>...</allCells>
859
Base Professional
For example, to give all cells a pale green background, you can type:
<gridFormat>
<allCells>
<bgColor>
<colorFormat>numeric</colorFormat>
<color>#8FBC8F</color>
</bgColor>
</allCells>
</gridFormat>
In this particular instance, this has the same effect as typing:

<gridFormat>
<bgColor>
</bgColor>
</gridFormat>
The indentation makes the hierarchy of the example easy to follow, but it is not a requirement.
To define the characteristics of the heading row and heading column, enclose the appropriate
tags in the following markers:
<headRow>...</headRow>
<headCol>...</headCol>
For more information, see the topic Row and Column Headings on p. 868.
To specify formatting for alternate rows and columns of the grid, place the necessary tags
within the following markers:
<altBodyRow>...</altBodyRow>
<altBodyCol>...</altBodyCol>
For more information, see the topic Different Formats for Alternate Rows or Columns on p. 870.
Background Color
To define the background color for a grid or part of a grid, place the following statements at
the appropriate place in the grid specification:
<bgColor>
<colorFormat>type</colorFormat>
<color>color_ref</color>
</bgColor>
where
type defines how the color will be specified, and is either string if the color will be entered
as a text, or numeric if the color will be entered as a hexadecimal value.
color_ref is the name or hexadecimal value of the color to be used.
For example, a grid specification that contains only the following formatting statements produces
a standard grid on a pale yellow background:
<bgColor>
<color>#FFFFCC</color>
</bgColor>
860
Chapter 1
You can change the background color of certain cells in the grid by placing <bgColor> within
the tags that define those cells. For example, you can use different colors for alternating rows
or columns, or for the heading row or column. The following specification creates a grid with
green column heading cells and pale yellow cells elsewhere:
<allCells>
<bgColor>
</bgColor>
</allCells>
<headRow>
<headerCell>
<bgColor>
<color>#32CD32</color>
</bgColor>
</headerCell>
</headRow>
The grid displays as follows:
Wrapping Text Within a Column
When the interviewing program displays a grid, it tries to fit the whole grid within the current
width of the browser page. If there are texts that are longer than the column width, the
interviewing program wraps them over two or more lines so that they fit. You can switch line
wrapping off so that all columns are as wide as is necessary to display the full text all on one line,
and the respondent may need to scroll to see the full grid. To do this, type:
<nowrap>value</nowrap>
where
value is true to switch off line wrapping or false to switch it on.
You can use <nowrap> in any cell-format section of the grid specification, so you could have the
column heading texts wrapped and the row heading texts not wrapped.
861
Base Professional
Text Characteristics
Text characteristics for grids consist of:

alignment
bold, italic, or bold italic style
typeface and size
color
special effects such as underlining or small capitals
Text Alignment
To define the horizontal position of text (or other cell contents) within a grid cell, type:
<align>position</align>
where
position is left, right, center, justify, or char. (char aligns the cell contents
on a given character. The default is the user’s decimal point character.) The default is left
alignment.
To define the vertical position of text within a grid cell, type:
<valign>position</valign>
where
position is top, center, bottom, or baseline. (baseline aligns the cell contents so
that the first line of text in all cells is aligned on a baseline that is common to all first-line texts
in the row.) The default is central alignment.
You will find further information on these parameters in your HTML guides.
You can set different alignments for different parts of the grid. The example centers all cell
content vertically within the row height and horizontally within the column width. The exception
is the row heading column which is left-aligned.
<allCells>
<align>center</align>
<valign>center</valign>
</allCells>
<headCol>
<headerCell>
<align>left</align>
</headerCell>
</headCol>
862
Chapter 1
You can set the horizontal alignment of the grid within the width of the browser page by placing
the following tags at the top level of the grid:
<tableDef>
</tableDef>
This is not the same as:

<allCells>
</allCells>
which causes the texts in all cells to be centered.
Bold and Italic Text
You can display bold or italic text using the following tag:
<font>
<fontStyle>style</fontStyle>
</font>
where
style is either bold, italic, or bold italic. The name of the standard text style is
regular.
Typeface and Text Size
To set the typeface to be used for grid text, type:

<font>
<fontFace>name</fontFace>
</font>
where
name is the name of the typeface.
You can specify the size of text by typing:
<font>
863
Base Professional
<fontPoint>number</fontPoint>
</font>
where
number is a number in the range 1 (small) to 7 (large). The default size is 3.
In the following example, text is displayed in the Tahoma font and, because the grid has many
columns, a smaller text size has been used to fit all the columns on the screen in one go:
The statements that define the font characteristics are as follows:

<allCells>
<font>
<fontFace>Tahoma</fontFace>
<fontPoint>2</fontPoint>
</font>
</allCells>
<headRow>
<headerCell>
<font>
<fontStyle>bold</fontStyle>
</font>
</headerCell>
</headRow>
Text Color
You can set a default color for all text in the grid and also set a different color for text in specific
rows or columns. To define the default color, place the following statements inside a gridFormat
or allCells section:
<textColor>
864
Chapter 1
</textColor>
If you use <textColor> at both the grid level and the all-cells level, the setting at the all-cells
level overrides the setting at the grid level. To override the default setting for a row or column,
place the following statements inside a headRow, headCol, altBodyRow or altBodyCol
section:
<font>
<fontColor>
</fontColor>
</font>
In both cases the variable parameters are as follows:

type defines how the color will be specified, and is either string if the color will be entered
as a text, or numeric if the color will be entered as a hexadecimal value.
color_ref is the name or hexadecimal value of the color to be used.
For example, specifying either:
<allCells>
<textColor>
<colorFormat>string</colorFormat>
<color>green</color>
</textColor>
</allCells>
<headRow>
<headerCell>
<font>
<fontColor>
<color>blue</color>
</fontColor>
</font>
</headerCell>
</headRow>
or:
<gridFormat>
<textColor>
<color>green</color>
</textColor>
<headRow>
<headerCell>
<font>
<fontColor>
<color>blue</color>
</fontColor>
</font>
</headerCell>
</headRow>
<gridFormat>
865
Base Professional
produces the following effect:
Note:<textColor> and <fontColor> are identical when used at the all-cells level.
Special Text Effects
If you want to emphasize a text you can apply special effects such as underlining. These effects
work in addition to any styles such as italics, so by combining the two you can place increased
emphasis on particular words or phrases in the text. To apply effects, type:
<font>
<fontEffects>effect1</fontEffects>
<fontEffects>effect2</fontEffects>
</font>
where
effect1 and effect2 are each one of the following:
underline strikethrough overline blink

superscript subscript smallcaps allcaps
capitalize hidden strong emphasis
sample definition citation variable
code keyboard abbreviation acronym
big small quotation typewriter
Refer to your HTML documentation for further details on these effects.

866
Chapter 1
Row, Column, and Cell Characteristics
You can define the following settings for the rows, columns, or individual cells of the grid:
row height
column width
row and column headings
cell formatting using text styles, colors, and so on
repeated headings
formatting for alternate rows and columns
This section also explains the precedence between row, column, and cell specifications at different
levels.
Row Height
The interviewing program normally makes each row as tall as it needs to be to hold the row text.
You can set your own row heights by placing the following tag inside any of the cell-formatting
sections:
<height>value</height>
where
value is the row height in pixels.
Column Widths
The interviewing program normally makes each column as wide as the contents of the widest
cell in that column (usually the column heading) and separates each column with one pixel of
space. You can specify your own column widths in various ways depending on whether all the
columns are the same width.
If all columns are the same width, place the following tags in the <allCells> section of
the grid template:
<width>
<widthFormat>type</widthFormat>
<value>number</value>
</width>
where
type defines how to interpret the value parameter, and is either absolute if value is the
width of the column in pixels, or percent if value is the column width as a percentage of
the total grid width.
number is the width of the column in the given format.
You can override this specification for the column of row headings, for example, by placing these
statements inside the <headCol> definition as shown below:
<headCol>
<headerCell>
<width>
867
Base Professional
<widthFormat>percent</widthFormat>
<value>15</value>
</width>
</headerCell>
</headCol>
Note: When column widths are specified in different sections of the template, the interviewing
program chooses the width for a particular column based on a fixed order of precedence among
the sections. For more information, see the topic Precedence Between Specifications at Different
Levels on p. 872.
If you want to vary the column widths across the grid, place the following statements in the
top level of the grid specification:
<colWidths>
<width>
</width>
</colWidths>
Repeat the <width> block for each column in the grid.

Note:<colWidths> overrides any column widths specified elsewhere in the template.
Here is an example that uses <colWidths> to set specific widths for each cell in the table.
The column width specification is:
<colWidths>
<width>
<widthFormat>absolute</widthFormat>
<value>100</value>
</width>
<width>
<value>40</value>
</width>
<width>
<value>60</value>
</width>
<width>
<value>80</value>
</width>
<width>
<value>100</value>
</width>
<width>
<value>120</value>
</width>
<width>
<value>140</value>
</width>
<width>
<value>40</value>
</width>
<width>
<value>50</value>
</width>
</widthFormat>
868
Chapter 1
This produces the following table:
Row and Column Headings
Specifications for row and column headings are enclosed in the following tags:
<headRow>...</headRow>
<headCol>...</headCol>
Specifications for row and column headings have two parts: cell formatting and row or column
repetition. Cell formatting describes the characteristics of the row or column headings and covers
such things as the cell color, the text style, and the column width. Row or column repetition
specifies how frequently the heading row or column should be repeated in the grid.
Cell Formatting
To define cell requirements, place the appropriate statements inside the following tag:
<headerCell>...</headerCell>
For example:
<headCol>
<headerCell>
<font>
<fontStyle>italic</fontStyle>
869
Base Professional
<fontFace>Tahoma</fontFace>
</font>
<align>right</align>
</headerCell>
</headCol>
Repeating the Row or Column Headings
With large grids, the respondent may need to scroll to see the full grid. When this is likely, you
can make the grid easier to follow by repeating the heading row or column so that the row
or column headings are still visible after scrolling. To do this, place the following tag inside
the headCol or headRow section:
<repeat>number</repeat>
where
number is the number of rows or columns after which the heading row or column is to be
repeated. 0 displays the heading row at the top and bottom of the grid, or the heading column
on the left and right of the grid.
For example:
<headCol>
<headerCell>
<font>
</font>
<align>right</align>
</headerCell>
<repeat>0</repeat>
</headCol>
870
Chapter 1
displays the heading column on the left and right of the grid as follows:
The following specification creates a grid with mauve cells for the row and column headers. The
texts in the heading row (that is, the column headings) are bold and are centered within the column
widths; the texts in the heading column (that is, the row headings) are italic:
<headRow>
<bgColor>
<color>#C0D9D9</color>
</bgColor>
<fontStyle>bold</fontStyle>
</headRow>
<headCol>
<bgColor>
</bgColor>
</headCol>
Different Formats for Alternate Rows or Columns
Large grids can be made easier to read if you use different formatting on alternate rows or columns
of the grid. You specify the changes for alternate rows and columns of the grid by placing the
necessary tags within the following markers:
<altBodyRow> ... </altBodyRow>

<altBodyCol> ... </altBodyCol>
871
Base Professional
When the interviewing program builds the grid, it uses the characteristics you have defined for the
grid as a whole, and then reads the alternate specifications and updates just those aspects of the
grid before displaying it. For example, if the template contains the statements:
<allCells>
<bgColor>
</bgColor>
</allCells>
<altBodyRow>
<bgColor>
<color>#CD7F32</color>
</bgColor>
</altBodyRow>
the rows of the grid will be alternately pale yellow and bright green, as shown below:
Note: If the template contains only <altBodyRow> or only <altBodyCol>, the settings in that
section are applied to both rowgrids and colgrids. If the template contains both specifications,
the interviewing program uses the settings in the specification that matches the grid’s type and
ignores settings in the other alternate specification. Therefore, a row grid is formatted using the
<altBodyRow> specification and the <altBodyCol> specification is ignored.
872
Chapter 1
Precedence Between Specifications at Different Levels
When a grid template contains specifications at more than one level, the interviewing program
uses the following rules to determine which specifications take precedence over others:
In the top left cell of the grid, colWidths takes overall precedence, followed by headCol,
headRow, allCells and textColor in that order.
For all other cells in the left-hand column, colWidths takes overall precedence, followed
by headCol, altBodyRow (for odd-numbered rows only), allCells and textColor in
that order.
For all other cells in the top row, colWidths takes overall precedence, followed by headRow,
altBodyCol (for odd-numbered columns only), allCells and textColor in that order.
For all other cells (the body of the grid), colWidths takes overall precedence, followed by
altBodyRow (odd-numbered rows in a row grid or where altBodyCol is not defined),
altBodyCol (odd-numbered columns in a column grid or where altBodyRow is not
defined), allCells and textColor in that order.
Here is an example that uses color to illustrate these rules. The grid template is:
<allCells>
<bgColor>
</bgColor>
</allCells>
<headRow>
<headerCell>
<bgColor>
</bgColor>
</headerCell>
</headRow>
<headCol>
<headerCell>
<bgColor>
<color>#93DB70</color>
</bgColor>
</headerCell>
</headCol>
<altBodyRow>
<bgColor>
<color>#FF6EC7</color>
</bgColor>
</altBodyRow>
<altBodyCol>
<bgColor>
<color>#70DBDB</color>
</bgColor>
</altBodyCol>
873
Base Professional
With this template, row grids look like this:
If you follow the rules, you will see that the cells are assigned colors as follows:
The top left cell takes its green color from headCol.
The remaining cells in the left-hand column take their color from headCol too.
The pale blue cells in the top row come from headRow.
The pink and pale yellow cells form the body of the table and are controlled by altBodyRow
and altBodyCol, but because this is a row grid only altBodyRow applies. Odd-numbered
body rows take their pink color from altBodyRow, while the even-numbered rows take
their pale yellow from allCells.
874
Chapter 1
Column grids are formatted as follows:
The cell colors are assigned as follows:

The top left cell takes its green color from headCol.
The remaining cells in the left-hand column take their color from headCol too.
The pale blue cells in the top row come from headRow.
The turquoise and pale yellow cells form the body of the table and are controlled by
altBodyRow and altBodyCol, but because this is a column grid only altBodyCol applies.
Odd-numbered body columns take their turquoise color from altBodyCol, while the
even-numbered columns take their pale yellow from allCells.
Overall Characteristics of the Grid Table
The interviewing program converts the formatting instructions in the grid template into standard
HTML code which it then uses to lay out the grid on the interview page. You can specify the
following characteristics that will affect the overall appearance of the grid:
The width of the table relative to the page width.
The horizontal alignment of the table on the page.
The width of the table border, if any.
The amount of spacing between the columns of the grid.
The amount of spacing between the contents of a cell and the borders of the cell.
If you want to define any of these characteristics, start by creating a tableDef section in which
to place the necessary statements:
<tableDef> ... </tableDef>

875
Base Professional
Grid Width
To set the width of the grid relative to the page width, type:
<width>
</width>
where
type defines how to interpret the value parameter, and is either absolute if value is the
width of the column in pixels, or percent if value is the column width as a percentage of
the total grid width. The default is percent.
number is the width of the table in the given format. The default is 100.
If the respondent resizes the browser window, the grid’s overall width and the column widths
increase or decrease proportionally.
If you are using a table to lay out the whole page, so that the grid becomes just another cell of a
larger table, the width that you set for the grid affects that part of the table only. The sections of
the table that contain the question text and navigation buttons remains at the default width or the
width specified for those parts of the table.
Grid Alignment
To define the horizontal position of the grid on the page, type:

<align>position</align>
where
position is left, right, or center. The default is left alignment.
Borders
The interviewing program does not display borders around grids or around the cells in a grid. To
draw a border around the grid and each cell in the grid, type:
<borderSize>number</borderSize>
where
number is the width in pixels of the border. A value of 0 suppresses the border.
The interviewing program does not set the border color so the browser’s default applies.
Note: Drawing a border around a grid forces borders around the cells of that grid. You cannot
have a grid that has a border but whose cells have no borders.
Space Between Rows and Columns
The interviewing program uses the standard HTML rules for table layout when displaying grids.
Depending on the number of columns in the grid, the width of the columns and the amount of
column heading text to be displayed in each column, this may or may not result in a layout that is
attractive and easy to follow. If you find that the column headings seem to be running into one
876
Chapter 1
another, so that it is not clear where one column heading ends and the other begins, you can
increase the amount of space between the columns. Not only will this make the columns easier to
see, but it will also reduce the column widths slightly which may improve usability.
The same problem can apply to rows. If the grid is small, you may prefer to increase the space
between the rows so that the grid fills more of the page.
To set the amount of horizontal and vertical space between each cell, type:
<cellSpacing>number</cellSpacing>
where
number is the number of pixels of space to leave between the rows and columns of the grid.
If the grid has different colors defined for the grid background and the cell background, and
<cellSpacing> is greater than 0, the spaces between the cells will be shown in the grid
background color.
Note: Cell spacing applies to all aspects of each cell of the table. You cannot increase the
horizontal or vertical spacing in isolation, nor can you specify different spacing for rows and
columns.
Space Around Cell Texts
If you do not want to alter the space between rows and columns, another way of improving
readability is to increase the amount of space between the cell margins and the text. By increasing
the amount of white space here, you may force the column or row text to be spread over more
lines so that it no longer runs into the text for the next row or column.
To increase the space around cell texts, type:
<cellPadding>number</cellPadding>
where
number is either the number of pixels or the percentage of space to leave above, below and on
each side of the text. Numbers without percentage signs are assumed to be pixels.
Examples
This section contains some illustrations of how you can change the appearance of a grid simply by
changing the overall characteristics of the grid table. The grid specification is as follows:
<gridFormat>
<name>Table Characteristics</name>
<tableDef>
<width>
<widthFormat>percent</widthFormat>
<value>80</value>
</width>
<borderSize>1</borderSize>
<cellSpacing>3</cellSpacing>
</tableDef>
<bgColor>
</bgColor>
</gridFormat>
877
Base Professional
The grid is 80% of the width of the browser window, and will reduce or increase in size
proportionally as the respondent resizes the browser window. The grid has a green background
and there is a border one pixel wide around the whole grid and around each cell, and three pixels
of space between each row and column.
The <cellPadding> tag increases the amount of blank space around the contents of each cell. If
the specification contains the line:
<cellPadding>3</cellPadding>
the grid becomes:

878
Chapter 1
Using a different background for the cells of the grid makes the cells look more boxlike. If the
following statements are added to the example specification:
<tableDef>
<borderSize>2</borderSize>
</tableDef>
<allCells>
<bgColor>
<color>#FF6EC7</color>
</bgColor>
</allCells>
the grid has pink cells on a pale green background:
<meta> and <!doctype> Tags in Templates
HTML authoring tools such as FrontPage often insert <meta> tags in HTML templates to override
HTTP information that should generally be set by the IIS server. The interviewing program takes
care of setting the correct HTTP information, so there is a risk that these <meta> tags could
confuse some browsers. The interviewing program therefore removes all <meta> tags that it
finds in templates, and then inserts its own <meta> tags. These show the template’s name and
879
Base Professional
the version of the interviewing program component that edited it, and instruct a proxy server or
firewall to obtain the most recent version of a survey from the Web server.
The interviewing program will not load templates that contain <!doctype> tags.
Cascading Style Sheets
Cascading style sheets (CSS) are a standard feature of HTML that allow you to define global
formatting parameters that can be applied to any number of templates. It is therefore possible, for
example, to have a set of completely different page layouts that all have green, 12-point Arial
question texts, and to change them all to blue, 14-point Times New Roman question texts simply
by changing the specification for the question text in the CSS.
The benefit of using cascading style sheets is that it allows you to simplify the
content of your templates by placing tags that are common to all templates in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Interviewer Server\Projects, rather than
repeating them in every template. This, in turn, makes it very easy to keep the templates up to
date if you need to change the color, font or point size of the text. Note that you will probably
need to copy the .css files to the appropriate locations on your web servers if they are to be picked
up during interviews.
Note: The notes in this section refer mainly to the IBM® SPSS® Data Collection Interviewer
Server-specific keywords that you can use in cascading style sheets. Other keywords may appear
in the examples, but these are described only so far as is necessary for you to be able to understand
the examples. For complete documentation on the general use of cascading style sheets, refer to
your HTML manuals.
Format and Location of a Cascading Stylesheet
A CSS is a text file containing lines that define the appearance of different components of the
questionnaire. Each line starts with a tag that is followed by a number of formatting instructions
enclosed in braces (curly brackets). For example:
.mrQuestionText { font-family:Tahoma; color:blue }
Here, the tag is .mrQuestionText, which tells us that the instruction refers to question texts.
The instructions inside the braces define the appearance of the question text — it will be blue
and the font will be Tahoma.
You can type these instructions in whatever format you like. For example, you could type the
.mrQuestionText definition as:
.mrQuestionText {
font-family:Tahoma;
color:blue
}
if you find this easier to follow.

You may call your CSS anything you like, although it is best to give it a .css extension so
that it is easily recognizable.
If you are testing your CSS and need to change it, you must close and reopen your browser
for the changes to be recognized.
880
Chapter 1
Tags for Questionnaire Items

Use the following tags to define the appearance of question texts, banner texts, and error
messages:
.mrQuestionText Question text
.mrQuestionTable Question <table> tag
.mrGridQuestionText Grid question header text
.mrGridCategoryText Grid category header text
.mrBannerText Banner texts
.mrErrorText Error messages
.mrSingle Single response buttons
.mrMultiple Multiple response buttons
.mrSingleText Single choice response text
.mrMultipleText Multiple choice response text
.mrEdit Answer boxes for numeric and text responses
.mrDropdown Drop-down list boxes
.mrListBox List boxes
.mrNext Next navigation button
.mrPrev Previous navigation button
.mrFirst First navigation button
.mrLast Last navigation button
.mrStop Stop navigation button
.mrGoto Goto navigation button
.mrGotoDropdown Drop-down goto navigation button
For example:
body {background-color:#D9DAFF}
.mrBannerText {font-family:Tahoma; font-size:12pt;
font-style:italic; color:#800080}
.mrQuestionText {font-family:Tahoma; font-size:12pt; color:#000080}
.mrSingleText {font-family:Times; font-size:12pt; color:#008080}
.mrMultipleText {font-family:Times; font-size:12pt; color:#008080}
.mrErrorText {font-family:Tahoma; font-size:10pt; color:red}
881
Base Professional
produces the following output (the bold text for Do not drink tea is the result of the exclusive flag
on that response in the questionnaire script, rather than a setting in the .css file):
Figure 1-204
Page showing effects of .css definitions
The following tags apply only to interviews run using the CATI keyboard player:
.mrQuestionName Question name displayed before the question
.mrQuestion Unselected questions when multiple questions are
displayed on a page
.mrQuestionSelected The selected question when multiple questions are
displayed on a page.
.mrQuestionInput Input boxes for unselected questions
.mrQuestionInputSelected Input box for the selected question
.mrCategory Unselected categorical responses
.mrCategorySelected Selected categorical responses
.mrCategoryInput Unselected category input codes (this is the style
set for the number shown inside the brackets, for
example, [1] Red)
.mrCategoryInputSelected Selected category input codes
Lining Up Wrapped Response Texts
When a categorical response text is too long to display on a single line, the interviewing program
wraps it onto as many lines as necessary. This wrapping is very simple and does not take into
account the radio button or check box at the start of the first line, so the continuation lines start
underneath these buttons. You can force the interviewing program to line up continuation texts
with the start of the text on the first line by editing the .css file for the project.
882
Chapter 1
To line up continuation texts in response lists, add mrSingle, mrSingleText, mrMultiple, and
mrMultipleText sections to your style sheet (or edit the existing one), as follows:
.mrSingle
{
float: left;
clear:left;
display:inline-block;
}
.mrSingleText
{
display: table;
*display: inline-block;
}
.mrMultiple
{
float: left;
clear:left;
display:inline-block;
}
.mrMultipleText
{
display: table;
*display: inline-block;
}
Note: If your project does not have a style sheet, you can create one by copying the
default one (for example, [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\Interviewer
Server\Server\mrIWeb\CATI\CATIPlayer.css for telephone interviews) into your project’s source
folder and editing it as necessary. Then add an <mrRef> tag to the project’s layout template
naming the .css file as described in Naming the Stylesheet in the Template.
Naming the Stylesheet in the Template
To name the stylesheet that you want to use, place the following statement in the <head> section
of the template:
<mrRef RefType="link" rel="stylesheet" type="text/css"
href="filename" title="style"/>
where
filename is the name of the .css file.
Editing the Page’s Form Definition
When an interview is running, the interviewing program builds the pages that the browser displays
by merging the question and response texts for the current question into the page template for
the current page and combining them with other HTML code that is generated by the interview
process itself.
If you want to customize these pages more than is possible using page templates, you can do
so by writing Java script to define your requirements and editing the HTML page to include this
code. Customizations of this type generally require you to refer to the form by name. The name
of the interview page is mrFORM.
883
Base Professional
Multiple-Language Scripts
This chapter looks at things to do with scripts for interviews that will be conducted in more than
one language. It covers the following topics:
How to write and test multiple-language projects.
Rules for multiple-language projects.
Setting the interview language.
Setting the interview locale to deal with differences in decimal numbers and dates.
Displaying examples of valid input formats for dates and decimal numbers.
Making non-question texts translatable.
How to Write and Test Multiple-Language Scripts
The general procedure for writing a multiple-language script is as follows:
1. Write the script in the base language for the project. In most cases this will be your native
language, but in some cases it will be another language with which you are familiar.
You may need to write a question that asks what language the respondent speaks, but if the project
uses sample management, you can often obtain this information from the sample records. You
will not be able to test the script in these languages until it has been translated, but at least the
statements will be there ready for when the translations exist.
Remember that any text that needs to be translated must appear in the metadata section of the
script. In addition, if you are defining analysis elements in the script, only texts that appear in the
main part of the response list can be translated. Texts in axis blocks are not translatable.
2. Test the script to ensure that it works as intended. Remember to check grammar and spelling at
this point too, as errors may lead to incorrect or misleading translations later on. Also check that
the question texts are unambiguous and that you have responses or other statements to cater
for all eventualities.
If the questionnaire contains contexts (for example, for Web and telephone interviewing),
remember to conduct interviews using every context.
3. Translate the texts in the metadata section using IBM® SPSS® Translation Utility. If the
questionnaire contains contexts, make sure that context-specific texts are translated. Refer to the
SPSS Translation Utility User’s Guide for details. Also, read for advice on adding and translating
contexts.
Check that StandardTexts.mdd contains error messages in the languages you will be using for
interviewing. If not, you will need to update the file with the appropriate translations. For more
information, see the topic Standard Error Messages on p. 724.
884
Chapter 1
If your templates contain text that is displayed during interviews, create language-specific versions
of those templates and place them in the appropriate template folders. For more information,
see the topic Types of Templates on p. 826.
4. Activate the project and set the default questionnaire language to the language to use if the
respondent’s language is not available. Refer to Activating Questionnaires for more information
on configuring questionnaires for activation. Similar links are available for the corresponding
functionality in the Launch activity.The IBM® SPSS® Data Collection Interviewer Server User’s
Guide contains similar information for the corresponding functionality in the Launch activity.
See “Project Information” in the Launch chapter of the Guide.)
Rules for Multiple-Language Projects
The following rules apply to projects that provide for interviewing in different languages.
Write the script all in one language; do not include foreign-language text in the script. All
translations must be entered separately using IBM® SPSS® Translation Utility. An exception
is a question that asks what language the respondent wants to be interviewed in. Here, you
may wish to write the language names in the appropriate language. For more information, see
the topic Setting the Interview Language on p. 885.
To ensure that the participant is interviewed in his or her preferred language, set the interview
language either using a direct question or by reading the language from the sample record. If
the interview script does not set the language, the interviewing program looks for translations
in the respondent’s browser language. For more information, see the topic Setting the
Interview Language on p. 885.
If you are using the multimode1.mrs sample management script, note that it expects each
participant to have one language only. If you have participants who are willing to be
interviewed in a number of languages (that is, their language sample field contains a list of
languages), you will need to update the sample management script to deal with this.
Telephone interviewing projects

You do not have to write anything in the interview script to check that the interviewer can
speak the respondent’s language. The sample management script does this.
Interviewers must have interviewer qualifications set that define the languages
they can speak. See Interviewer Qualifications for general information about
qualifications. See also (ms-its:DimNet.chm::/Dimug-mu_userprops_creategroup.htm) and
(ms-its:DimNet.chm::/Dimug-mu_userprops_addprops.htm) for instructions on setting up
interviewer qualifications, and (ms-its:UserGuide.chm::/Intug-cs_defineparameters.htm) for
information on how to make projects use qualifications.See “Creating User Property Groups”
and “Adding Properties to User Groups” in the IBM® SPSS® Data Collection Interviewer
Server Administration User’s Guide for instructions on setting up interviewer qualifications,
and “Defining Sample Management Parameters” in theIBM® SPSS® Data Collection
Interviewer Server User’s Guide for information on how to make projects use qualifications.
Sample records for participants must have a field that stores the language in which the
participant wishes to be interviewed. The name of the language field in the sample record
must match the name of the language interviewer qualification. Most companies use the
885
Base Professional
word Language as this is the name used by the multimode1.mrs sample management script
supplied with Interviewer Server.
multimode1.mrs compares interviewer language qualifications against the participant’s
language using the “=“ operator. It is therefore advisable that the interviewer language
qualifications and the participant language requirements are specified in the same case.
Case is important in case sensitive databases but not otherwise; however, is good practice
to maintain consistency between the two settings as this reduces the likelihood of the script
failing due to inconsistencies in case.
Setting the Interview Language
The interview language controls not only the language in which questions, answers, and other
texts are displayed but also the format in which decimal and date responses must be entered.
When a respondent starts an interview and the interviewing program has no information about
the respondent’s language, it tries to find a suitable language for the interview. First, it checks
whether the questionnaire file contain texts in the respondent’s browser language and, if so, uses
that language. (If the respondent has a list of languages set in his or her browser, only the first
language is checked.) If the questionnaire does not contain texts in the respondent’s browser
language, the interviewing program uses the texts in the questionnaire’s base language (the default
language set when the project was activated).
For example, suppose the questionnaire is defined in English (the base language) and Spanish.
Participants whose browsers are set up to work in Spanish will automatically see Spanish texts and
must enter decimal numbers with a comma as the decimal point. Everyone else will see English
texts and must enter decimal numbers with a dot as the decimal point.
A better approach is to set the interview language in the script, either by asking a direct question
or by extracting the respondent’s language from the sample record.
To set the language based on a direct question, define the list of available languages in the
metadata section:
InterviewLanguage "In which language would you like to be interviewed?"
Notice that each language has its standard three-character code as its name as this is required
for setting the language in the routing section.
Note: In general you can set languages using their three-character code, as here, or their RFC
1766 format (en–gb or fr–fr, for instance). The interviewing program converts three-character
references to RFC 1766 format.
In the routing section, set the chosen language as the interview language with:
IOM.Language = Qname.Categories[Qname].Name
where Qname is the name of the language question. For example:

InterviewLanguage.Ask()
' Set the interview language
IOM.Language = InterviewLanguage.Categories[InterviewLanguage].Name
' Force comma for decimal places and yyyy-mm-dd dates
IOM.Locale = 1045 ' Polish locale
If the respondent’s preferred language is defined in the sample record, you can import it from there.
For example, if the preferred language is stored in the Language sample field, you would type:
IOM.Language = IOM.SampleRecord["Language"]
886
Chapter 1
For more information, see the topic Using Sample Data in Interviews on p. 890.
Note: The interview scripting language accepts setting the interview language to any language
that you like. However, the interviewing program requires the questionnaire (.mdd) file to contain
that language even if there are no translations for it yet. If the script instructs the interviewing
program to use a language that does not exist in the questionnaire file, the interviewing program
writes a warning to the IVW*.tmp log file and then continues the interview using the default
language that was set during activation. The warning says “Language ‘xxx’ is not available,
using ‘yyy’ instead”.
Using Locale to Control Decimal Number and Date Formats
There are a number of standards for writing decimal numbers and dates. English-speaking
countries, for instance, tend to use a dot as the decimal point whereas European countries use a
comma. For dates, Western European countries write day, month, year, whereas the American
standard is month, day, year, and the universal standard is year, month, day. This can cause
confusion in interviews. Interviewers or respondents may see error messages if they use the wrong
character as the decimal point, or they may misinterpret dates that are written using numbers only
(for example, is 1/2/2007 1 February or 2 January?).
The interview locale controls these aspects of an interview. It is closely related to the interview
language and defaults to being the same as the interview language. When a new interview starts,
the initial language and locale are set to match the respondent’s browser language or, if the script
does not support that language, the questionnaire’s default language that was set during activation.
Therefore, if the interview language is French, respondents must use a comma as the decimal point
and should enter dates as dd/mm/yyyy; if the interview language is US-English, respondents must
use a dot as the decimal point and should enter dates as mm/dd/yyyy. See Setting the Interview
Language for more detailed information about how the interview language is set.
You can change the interview locale so that it differs from the interview language. You might
do this if you want to enforce a particular method of entering or displaying numbers or dates
regardless of the interview language. This would certainly make things easier for multilingual
interviewers working on projects in areas with differing conventions for dates and decimal
numbers. To set or change the locale, type:
IOM.Locale = code
where code is the locale ID in either hex or decimal format.

Refer to http://www.microsoft.com/globaldev/reference/lcid-all.mspx
(http://www.microsoft.com/globaldev/reference/lcid-all.mspx) for a list of locale IDs.
As an example, suppose you have a Web project that covers a range of countries in the
European Union. The questionnaire’s default language is English and it has been translated into
various other languages. All countries in the survey, except Britain, use a comma as the decimal
point, and date formats vary between dd/mm/yyyy in the West and yyyy/mm/dd in the East (the
separator character varies between countries). For consistency, the project manager has decided
that all decimal numbers must be entered using a comma as the decimal point, and dates must be
displayed as yyyy–mm–dd.
Respondents may choose the interview language so the script starts with the following question:
InterviewLanguage "In which language would you like to be interviewed?"
887
Base Professional
The routing for the script is as follows:

InterviewLanguage.Ask()
' Set the interview language
IOM.Language = InterviewLanguage.Categories[InterviewLanguage].Name
' Force comma for decimal places and yyyy-mm-dd dates
IOM.Locale = 1045 ' Polish locale
InterviewLanguage is displayed on the respondent’s screen in the browser’s language, or in

English if there are no translations for that language. The script then sets the interview language
and locale based on the respondent’s answer. At this point a French interview would require
decimals such as 123,45 and would display dates in the form 25/12/2007, an English interview
would require decimals such as 123.45 and would display dates in the form 25/12/2007.
Poland is one of the countries whose locale settings match the requirements for the survey, so
the script sets this as the locale for all interviews. From this point onwards, all respondents must
use a comma for the decimal point and should enter dates in the format 2007–12–25.
Note: Setting the locale breaks the link between language and locale. If you change the language
after setting the locale, the locale will no longer change automatically to match the language.
Showing Example Input Formats
There are various ways of entering numbers and dates in interviews, all of which depend to some
extent on the interview’s language or locale. One of the most common problems relates to the
decimal point: is it a comma or is it a dot? If the interview language is one that requires a comma
as the decimal point, then any decimal responses that are entered with a dot will be rejected.
Similarly, if the language is one that requires a dot as the decimal point, numbers that contain a
comma will be rejected. The error message that the user sees depends on the browser language,
the script language and locale, and the character entered as the decimal point, but it will usually
state either that the response is not numeric or that the thousands separator is not allowed.
You can help respondents and interviewers avoid these problems by displaying an example of
the required response format as part of the question. There are several ways of doing this.
Numbers with .Ask()

To mark the point at which the example response should be displayed, place an insert marker
inside the question text (see Programmatically Inserting Text into Labels for further information
about inserts):
{Example[:Fmt]}
where
Example is the name of the insert marker.
Fmt is an optional formatting string specifying how the value should be formatted. For more
information, see the topic Formatting Substituted Values on p. 609.
For example:
WeeklyFood "How much do you spend on food in an average week? (e.g., {spend:f})"
Then, type the Ask() statement as follows:

Name.Ask(Value)
888
Chapter 1
where:
Value is a number.
When the question is displayed during interviews, the insert marker in the question text is replaced
with this value, formatted according to the given format string and the interview language. Here
are some examples produced by:
WeeklyFood.Ask(1234,5)
Insert Produces
{spend:f} 1234.50 (English) or 1234,50 (Continental
European)
{spend:f3} 1234.500 (English) or 1234,500 (Continental
European)
{spend:n} 1,234.50 (English), 1 234,50 (French), or 1.234,50
(German)
{spend} 1234.5
Note: There is no requirement for the value to be within the valid response range for the question,
although it is helpful to respondents if it is.
Dates with .Ask()
To mark the point at which the example date should be displayed, place an insert marker of
the following form inside the question text:
{Example[:Fmt]}
where Example and Fmt are as described previously. Then, in the routing section, type:
Name.Ask(CDate("yyyy-mm-dd"))
where:
yyyy, mm, and dd are the date components.
When the question is displayed during interviews, the example date is displayed in the format
required by the interview language. For example, if the question is
Expiry "When does your privilege card expire? (e.g., {exdate})" date;

Expiry.Ask(CDate("2007-12-31"))
the date will be displayed as follows:

Language Date displayed as
British English, Western European languages, and 31/12/2007
equivalents
889
Base Professional
Language Date displayed as

US English and equivalents 12/31/2007
Eastern European languages and equivalents 2007–12–31 (the separator character will vary
between countries)
Numbers or Dates with Format()

The other way of specifying example values for both numbers and dates is to use the standard
syntax for defining insert values together with the function
Name.Label.Inserts["Example"].Text = Format(Value, "Fmt", , IOM.Locale)
where:
Example is the name of the insert marker in the question’s metadata.
Value is a number enclosed in double quotation marks or a CDate expression defining the
value for Example.
Fmt is a formatting code the specifies how Value should be displayed.
For example, the previous examples could be written as:
WeeklyFood.Label.Inserts["spend"].Text = Format("12345","f2", ,IOM.Locale)
Expiry.Label.Inserts["exdate"].Text = Format(CDate("2007-12-31"),"d", ,IOM.Locale)
Non-Question Texts
All text that appears in the metadata section of the questionnaire — that is, questions, responses,
shared lists, and information texts — can be translated. Text that appears in the routing section
— error texts and insert values, for instance — cannot be translated and is always displayed as
it has been entered in the routing statements.
If you need to used fixed texts in the routing section and you want them to be translated, move
the texts into info items in the metadata section and then refer to them in the routing section
using ItemName.Label.Text. The code samples in Adding Banners to Questions and Pages
and Using a Custom Validation Function illustrate how to do this. Compare these examples with
the routing code for the error handler in Programmatically Inserting Text into Labels. Although
this example is generally translatable, the word “Unavailable” is hard-coded into the routing
code and cannot be translated:
Else
End If
To make this example fully translatable, you could place “Unavailable” in an info item of that
name and change the routing to refer to that item:
ErrorDisplay.Label.Inserts["RespId"].Text = Unavailable.Label.Text
Else
End If
890
Chapter 1
Templates can sometimes contain text that needs translating. You can create different language
versions of a template and, provided that you put them in the correct locations, the interviewing
program will pick up the template that matches the interview language. See Types of Templates
and for details.
Working with Sample Records
Sample (or participant) records store information about prospective participants in the survey.
The records can be used for inbound (Web) or outbound (telephone) interviews. The records are
stored in SQL databases and are loaded using the Participants activity in IBM® SPSS® Data
Collection Interviewer Server Administration.
Each record consists of a number of fields (columns in SQL) that each contain different
information. For Web (inbound) interviews you may have fields called Id, Name and Password
that store the participants’ unique IDs, login names and passwords for logging in to the survey.
For outbound telephone interviews you may have fields called Id and PhoneNumber, as well as
various other fields that the telephone interviewing activity requires for managing calls.
Sometimes, your sample records will contain other information about the participants. For
example, if you are running an employee survey for your company, you may have fields for the
participants’ names and job titles. You may also have information about how long they have
worked for the company. You can copy this information into the interview script and use it to
personalize greetings, or as a means of determining which questions each person is asked, or to
populate questions with data automatically so that you don’t have to ask for things that you
already know. For more information, see the topic Using Sample Data in Interviews on p. 890.
You can also copy interview data into sample records. You can write data into new fields or
you can update existing fields with new information. For example, if someone has married or
remarried, you can update that person’s name if this has changed; or, if you started with telephone
numbers only, you can ask for participants’ names during the interview and write them back into
the sample records for future use. For more information, see the topic Updating Sample Records
with Interview Data on p. 892.
Using Sample Data in Interviews
In ongoing or panel studies you have the chance to build up profiles of your respondents. If this
profiling information is held in the sample (participant) records you can use it in the interview,
either as a basis for routing or as predefined answers to certain questions in the script. For
example, in a car survey that asks different sets of questions depending on the type of car owned,
if the sample records contain information about the respondent’s car, you can use this information
directly in the routing rather than writing an intermediate question that asks what type of car the
respondent owns. Similarly, you can save time by automatically populating standard demographic
questions for use in analyses by reading the answers directly from the sample records.
To access any data in the sample record, place statements of the following form in the routing
Question = IOM.SampleRecord.Item["FieldName"]
891
Base Professional
where:
Question is a reference to the question or other item that is to store the sample data. The
exact syntax for this parameter varies according to how you will be using the sample data.
See below for examples.
Note: It’s a good idea to use similar names for the question and its related field in the sample
record. as this helps to ensure that you load the sample data into the right questions. If your
script has sample quotas, you may want to use identical names for questions and sample fields.
For more information, see the topic Sample Quotas when you have No Access to the Sample
Database on p. 1083.
FieldName is the name of the sample field that stores the information you want to use.
For example, suppose the SampleName field in the sample record contains the respondent’s
name, and you want to display it as part of a personalized introductory text. First, define the
welcome message in the metadata section using a named insert to mark the point at which the
respondent’s name will appear:
Welcome "Hello, {Name}. Welcome to our annual readership survey." info;
Then, in the routing section, copy the respondent’s name into the insert and display the message:
Welcome.Label.Inserts["Name"].Text = IOM.SampleRecord.Item["SampleName"]
Welcome.Show()
If you want to go a step further and use the sample data as the answers to questions, make sure
that you have an appropriate question in which to place the data. For example, if the SampleAge
field in the sample record contains the respondent’s age, you’ll need a numeric question in the
script to receive this information. The question is defined as:
The statements in the routing section are:

Age.Response.Value = IOM.SampleRecord.Item["SampleAge"]
This code snippet will work as long as the age in every sample record is within the 18 to 99 range,
and there are no blank ages. The interviewing program checks that the value it is importing from
the sample field is valid for the question that will store it and, if not, terminates the interview
abruptly with an internal program message because it does not know what to do. If you suspect
that there could be invalid ages in the sample data, you will need to write your script to deal
with this. There are various ways of doing this.
One way is to load the data into a temporary variable for checking before assigning it to a
question. Here’s an example:
Age.MustAnswer=False
Dim checkage
checkage = IOM.SampleRecord.Item["SampleAge"]
If checkage=Null Or checkage < 18 Or checkage > 99 Then
Age.Response.Value = Null
Else
Age.Response.Value = checkage
End If
In this example, the MustAnswer property has been set to False to allow Age to be set to null if
SampleAge is blank or invalid.
892
Chapter 1
Another option is simply to ignore the error, so that anything other than a number in the range
18 to 99 yields a null value in Age.

Age.Response.Value = IOM.SampleRecord.Item["SampleAge"]
On Error GoTo 0
In this code snippet, the first line switches on error handling and tells the interviewing program to
continue with the next statement in the script whenever it encounters an error. The second line
reads in the sample value. If SampleAge is a number in the range 18 to 99 it is assigned as the
response to Age, otherwise Age remains blank and the error message is suppressed. The third line
switches off error handling.
This method is the simplest because you do not have to hard-code the validation values in
the routing script, so changing the range in the question definition requires no further changes
to the routing script. Also, there is no need to set MustAnswer to False to cater for blank or
invalid values.
Updating Sample Records with Interview Data
If you have a panel of respondents that you survey regularly, you can build up a profile of each
respondent and save the key points as part of the respondent’s sample record. You can check
periodically that the profile is still valid and update it if necessary.
Note: If the data is completely new, you will need to add a new field to the sample file. You
may be able to do this yourself; if not, ask your IBM® SPSS® Data Collection administrator
to do it for you.
To write interview data into the sample record, type:
IOM.SampleRecord.Item["FieldName"] = Value
in the routing section of the script, where:

FieldName is the name of the sample field you want to write to. It’s a good idea to use
similar names for the question and its related field in the sample record. as this helps to ensure
that you copy the correct data into each sample field. If your script has sample quotas, you
may want to use identical names for questions and sample fields. For more information, see
the topic Sample Quotas when you have No Access to the Sample Database on p. 1083.
Value is the information you want to place in the sample field. This can be a fixed value
such as a number or a text, or the name of a question or variable that stores the information.
Sample tables do not support categorical values as such. If you want to save categorical data
in your sample records you will have to convert it into a numeric or text form first. For more
information, see the topic Converting Data to the Required Format on p. 893.
For example:
IOM.SampleRecord.Item["SampleAge"] = Age.Response.Value
to write the answer to the Age question into the SampleAge sample field. If SampleAge already
contains data it will be overwritten.
893
Base Professional
Here’s a longer example that shows how you can load existing sample data into the interview,
check that it is still correct, and then update any out-of-date sample fields with new data. The
metadata section defines the questions related to the sample fields:
Mstat "Please confirm your marital status" categorical [1..1]
{
Single, Married, Divorced, Widowed,
Partner "Living with partner"
};
Empstat "Please confirm your employment status" categorical [1..1]
{
Employed "Working for an employer",
SelfEmployed "Self-employed",
Homemaker, Retired,
Student "In full-time education",
Unemployed "Unemployed but able to work",
Unable "Unable to work (e.g., disability)"
};
Children "How many children do you have?" long [0..9];
The routing script that loads the sample data into these questions and writes the new answers back
into the sample records is as follows:
Empstat.Response.Value = IOM.SampleRecord.Item["SampleEmpstat"]
Children.Response.Value = IOM.SampleRecord.Item["SampleChildren"]
Empstat.Ask()
Children.Ask()
IOM.SampleRecord.Item["SampleEmpstat"] = Empstat.Response.Value.Format("a")
IOM.SampleRecord.Item["SampleChildren"] = Children.Response.Value
The sample data is loaded into the questions, so the questions are displayed with these answers
already selected or filled in. If the current answer is correct, respondents can click Next to move to
the next question; if not, they can select or enter a new answer. The answers to the questions are
written back into the sample fields. If the fields already contain values, this data is overwritten by
the current answers to the questions, even if the new value is the same as the old one. In this way
you can be sure that all the information in the sample records is up to date.
Converting Data to the Required Format
Data isn’t always in the right format for the situation in which you want to use it: the sample field
may have gender coded numerically, for example, while you want to read it into a categorical
question, or you may have categorical data that you have to write back into a numeric field. If you
have only a few conversions of this type, you can specify them separately for each question or
field, but an alternative is to write a function that you can call generically whenever you need to
perform a certain type of conversion.
Converting Numeric Sample Data into Categorical Script Data
Let’s take the numeric to categorical conversion for gender as an example. If you have a number
of similar fields, it makes sense to write a numeric to categorical conversion function that you can
use for any question. The Gender and Mstat questions are defined in the script as:
Gender "Gender" categorical [1..1]
{Male, Female};
{
};
894
Chapter 1
However, the “answers” to these questions are stored in the sample records in two numeric fields.
Gender is stored as 1 or 2 in SampleGender and marital status is a value in the range 1 to 5 in
SampleMstat. For simplicity, assume that there are no missing or incorrect values: everyone’s
gender and marital status is known and correctly coded. You therefore need a function that can
convert numeric values and assign them as the answers to categorical questions. The following
function does this:
Sub NumSamp2CatQ(Question, FieldValue)
FieldValue = CLong(FieldValue)
If FieldValue >= 1 And FieldValue <= Question.Categories.Count Then
Question.Response.Value = Question.Categories.Item[FieldValue-1].Value
End If
End Sub
The function is passed a question name and the value in the corresponding sample field. It
converts the value to an integer and checks that it is within the number of responses in the
question’s response list. If it is, the function uses that value as an index into the response list and
selects the name (category value) of the response in that position in the list. (Responses are
numbered from zero, so the function subtracts 1 from the field value to ensure that it matches
up values and responses correctly.)
To call this function, place the following statement in the routing section of your script:
NumSamp2CatQ(Qname, IOM.SampleRecord.Item["Fieldname"].Value)
In the example, you’d type:

NumSamp2CatQ(Gender, IOM.SampleRecord.Item["SampleGender"].Value)
NumSamp2CatQ(Mstat, IOM.SampleRecord.Item["SampleMstat"].Value)
If the respondent is a divorced woman, the incoming values would be SampleGender=2 and
SampleMstat=3, and these would be matched with responses at position 1 (female) and position 2
(divorced) in Gender and Mstat respectively.
Converting Categorical Script Data into Numeric Sample Data
Now suppose that you want to do the same thing but the other way round; that is, to write
categorical values into an integer field. The Region question is defined as:
Region "In which part of the country do you live?" categorical [1..1]
{North, South, East, West};
SampleRegion is an integer (data type smallint) field in the sample record, so you need to find
the position of the respondent’s chosen answer in the response list and copy that into the sample
field. Type:
IOM.SampleRecord.Item["FieldName"].Value = Qname.DefinedCategories().Find(Qname)
in the routing section of the script.

In this statement, DefinedCategories() is a function in the IBM® SPSS® Data Collection
Function Library that scans the full response list as it is defined in the metadata section, and
Find() is a function that searches for a value in a list. By concatenating the two functions after
the name of the question whose value you want, you instruct the interviewing program to scan the
full list of responses for a question and locate the answer that has been chosen from the list.
895
Base Professional
Since most sample fields start numbering from 1, it’s a good idea to add 1 to all categorical
values when you convert them, so in this example you would write:
IOM.SampleRecord.Item["SampleRegion"].Value = Region.DefinedCategories().Find(Region) + 1
Converting Text Sample Data into Categorical Script Data
If a sample field contains a single word you may be able use that word as the answer to a
categorical question. For example, if the respondent’s marital status appears in the sample record
as Single and the question about marital status contains a response with that name, you can use a
simple assignment statement in the routing section of the script to copy the sample data into the
script. If the question is defined as:
{
};
you can set the answer to the question automatically with:

Empstat.Response.Value = IOM.SampleRecord.Item["SampleEmpstat"]
If the sample field contains more than one word and those words are separated by the same
character or string of characters, you can use those values as the answers to a question with a
multiple choice response list. However, you will need to write some code that preprocesses the
string to remove the separators and then assigns each value to the question
Converting Categorical Script Data into Text Sample Data
You can write categorical data into sample records by using the function to pick up the category
names of the responses you want to copy. Type, for example:
IOM.SampleRecord.Item["SampleEmpstat"] = Empstat.Response.Value.Format("a")
If the question allows more than one answer to be chosen, the answers are written into the sample
field as a comma-separated list. Note that all response names are written in lower case regardless
of how they appear in the questionnaire script.
Quota Control Scripting
Quota control is a way of controlling the number of completed interviews in various categories of
your choice. Usually, the quotas are based on respondents, so you might have quotas based on age
or gender, or on the number of people who live in households of various sizes, but they can be
based on other counts such as brands purchased. In this case, a respondent may buy several brands
in which case one respondent will affect several quotas. Refer to Quota Control for an explanation
of how the quota control system works and description of the way quotas can be set and controlled
for different types of questions and answers.
The topics in this section explain how to write a script that interfaces with the quota control
system. They describe how to:
Pend quota cells for interviews that are in progress
896
Chapter 1
Terminate interviews when targets have been met

Increment the count of completed interviews
Check for empty or unfilled cells (this procedure applies to any type of check on individual
quota cells)
Specify cell priorities for multiple choice response lists (for example, always use quota cell A
before quota cell B if both responses are chosen) or when you want to pend quotas for the
cells that are currently the least full
You can also find out about:
Reviewing quota-controlled interviews
Restarting and snapping back in quota controlled interviews
Quota targets are defined in a .mqd file whose contents are written into a set of quota tables when a
project is activated with the “With Quota” option selected. Refer to the following for additional
information related to quota control:
Quota Setup (ms-its:UserGuide.chm::/Intug-features.htm) for information about setting up quota
targets.
Quota (ms-its:UserGuide.chm::/Intug-act_quota.htm) for information about activating projects
that use quota control.
Quotas (ms-its:UserGuide.chm::/Intug-rq_about.htm) for information about monitoring and
changing quotas when a project is running.
The “Quota Setup” chapter in the IBM® SPSS® Data Collection Interviewer Server User’s Guide
for information about setting up quota targets.
The “Quota” topic in the Launch chapter of the Interviewer Server User’s Guide for information
about activating projects that use quota control.
The “Quotas” chapter in the Interviewer Server User’s Guide for information about monitoring
and changing quotas when a project is running.
Testing quotas for information about testing quotas in IBM® SPSS® Data Collection Base
Professional.
Pending Quota Cells
When an interview belongs in a particular quota cell, you should increment the count of interviews
pending (that is, in progress) for that cell. This signals to the quota control system that there is
an interview running that may contribute to meeting the target for that cell. If you have quotas
set up for multiple choice response lists, the quota control system normally pends all cells that
correspond to the answers chosen from the list, but you can specify that only certain cells are
pended if you prefer (see Prioritizing Quota Cells for Multiple Choice Answers for details).
To increment pending counts, type the following statement in the routing section of the script at
the point you want to update the counts:
Result = QuotaEngine.QuotaGroups["QuotaName"].Pend()
897
Base Professional
where:
Result is the name of a variable whose value will indicate the outcome of the pend request.
The variable may be a question variable that you define in the metadata section of the script,
or a temporary variable defined in the routing section.
QuotaName is the name of the quota whose pending counts are to be incremented. Often the
quota name will be the same as the name of the question to which the quota belongs.
The outcome of a pend request is returned as one or more of the following flags:
qrWasPended The quota was pended.
qrOverTarget The count of completed interviews exceeds the
target.
qrBelowTarget The count of completed interviews is below the
target.
qrPendingOverTarget The sum of pended and completed interviews
exceeds the target.
For example:
RegionPendResult = QuotaEngine.QuotaGroups["Region"].Pend()
checks the Region quota and pends the count for the cell that corresponds to the region in
which the respondent lives. If the action of pending the quota cell is successful, the value of
RegionPendResult will include the qrWasPended flag. If it is not (the target may have been met
already), RegionPendResult will not include this flag.
The next step is to test the result of your request and specify what you want to happen next.
If the quota was pended, you’ll usually want to ask some more questions. If the quota could
not be pended, you may want to terminate the interview or skip to a different section of the
questionnaire. To test the result of a pend request, type:
If (IsSet(Result, QuotaResultConstants.qrWasPended)) Then

... Actions
End If
For example:
Dim RegionPendResult
If (IsSet(RegionPendResult, QuotaResultConstants.qrWasPended)) Then
Age.Ask()
Gender.Ask()
Else
Full.Show()
End If
An alternative to writing two separate statements to pend the quota and test the result is to write:
If (IsSet(QuotaEngine.QuotaGroups["QuotaName"].Pend(),
QuotaResultConstants.qrWasPended)) Then
898
Chapter 1
Incrementing Quota Counts for Completed Interviews
You do not have to write code to do this as it happens automatically. When an interview with
pended quota cells completes, the interviewing program automatically decrements each pended
cell for that interview by 1 and increments the corresponding completed cells. When testing
interview scripts you can monitor this behavior in a number of ways:
Using the Quotas (ms-its::UserGuide.chm::/Intug-rq_check.htm) activity in IBM® SPSS®
Data Collection Interviewer Server Administration.
By running the DebugQuotaReport.mrs script in IBM® SPSS® Data Collection Base
Professional. For more information, see the topic Testing quotas on p. 83.
By checking the counts in the project’s QUOTA_QuotaCount table.
Terminating Interviews when Targets have been Met
The quota control system normally increments the count of interviews that are in progress for each
cell as long as the sum of completed plus pended interviews does not exceed the cell target. When
the target is very close to being met and there are several interviews running, that would, if they
all completed, cause the target to be exceeded, only some of those interviews will be allowed to
run to completion. Which interviews those are depends entirely on which ones reach the quota
check first; it has nothing to do with which interview started first. If you want all interviews that
start to be allowed to complete, you will need to switch on the Allow OverQuota flag. You can do
this when you define quotas (see Table Quotas (UserGuide.chm::/Intug-definetablequotas.htm)) or
at any time during the course of the project (seeChecking Quota Targets, Behavior Flags, and/or
Cell Priorities (UserGuide.chm::/Intug-rq_change.htm)).
The most common reason for pending counts not being incremented is because the targets have
already been met when the interview starts, but this can also happen due to some other failure with
either the questionnaire script or the quota database. To ensure that interviews run smoothly you
are advised always to write code to cater for these situations whenever you pend quota cells. The
most common action is to terminate the interview immediately, flagging it as terminated due to
quota control. Here’s some general code that you can use as a basis for your own scripts:
If Not (IsSet(Result, QuotaResultConstants.qrWasPended)) Then
IOM.Texts.InterviewStopped = InfoName.Label
IOM.Terminate(Signals.sigOverQuota)
End If
In this code:
Result is the name of a variable whose value stores the result of the pend request. For more
information, see the topic Pending Quota Cells on p. 896.
InfoName is the name of an information item containing a message explaining why the
interview is being terminated. (Text in IOM.Texts.InterviewStopped is shown on the page that
the interviewing program displays when an interview is stopped.)
If the metadata section contains:
Region "What part of the country do you live in?" categorical [1..1]
Full "We already have enough interviews for the {#Region} region."
info;
899
Base Professional
your routing section might be as follows:

Dim RegionPendResult
If Not(IsSet(RegionPendResult, QuotaResultConstants.qrWasPended)) Then
IOM.Texts.InterviewStopped = Full.Label
End If
When the quota for people who live in the south has been met, the next interview for that region
will be terminated with the message “We already have enough interviews for the South region.”
and the DataCollection.Status field in the interview’s case data will show that the interview was
terminated due to quota control. See the “Signals” subsection in Ending or Stopping Interviews
for further information about sigOverQuota and signals in general.
Checking for Empty or Unfilled Cells
You can save time by checking whether a quota cell is full before the interviewer asks to speak to
a respondent with those characteristics. For example, interviewers may have to check whether
there are any women under age 21, between 21 and 30, or over 30 before saying that there are no
eligible respondents in the household. You can save the interviewer time by checking whether
each of these cells is full before prompting him/her to ask for women in each category. Thus,
if the cell for women over 30 is full, the interviewer need only ask to interview women under
21 or between 21 and 30.
The Quota Object Model, which interfaces with the quota database during interviews, provides
several methods of checking a quota cell’s status. You can:
use IsBelowQuota to test whether the sum of the pending and completed counts is less than
the target. For more information, see the topic Comparing the Sum of Pended Plus Completed
Interviews Against the Target on p. 899.
write an expression that compares the cell’s completed count, or the sum of the completed
and pend counts, against the cell target.For more information, see the topic Comparing the
Number of Completes Against the Target on p. 901.
Comparing the Sum of Pended Plus Completed Interviews Against the Target
This topic shows how to use IsBelowQuota to check for cells where the sum of pended and
completed interviews is below the target. This type of test ensures that any interview that starts
and completes will not cause the target to be exceeded. Of course, if you are allowing cells to go
over target you can just compare the number of completes against the target.
IsBelowQuota is a function that returns True or False, so you generally use it in an assignment
statement or in an If statement. Its syntax is:
QuotaEngine.QuotaGroups["GroupName"].Quotas[CellNumber].IsBelowQuota
where:
GroupName is the name of the quota question.
CellNumber is the number of the quota cell to be tested. Cells are initially numbered
sequentially from 1 according to the order of responses in the question’s response list, but if
you later insert additional responses in the response list, the cell numbers for those quotas will
900
Chapter 1
be whatever is the next free number in the sequence. For example, if you insert a response as
the third item in a list of five responses, the quota for that response will be found in cell 6.
You can check cell numbers by looking at the project’s QUOTA_Target table.
Here’s an example that shows how to check which age groups are available before asking the
interviewer to find a respondent in a suitable age group. The metadata for this example is:
WomanAge "INTERVIEWER: Ask to speak to someone in one of the following
categories and select the appropriate category from the list."
categorical [1..1]
{
FU21 "Woman under 21",
F21to30 "Woman 21 to 30",
F50Plus "Woman 50 or older",
None "No one available (DO NOT READ)"
};
NoneAvail "Unfortunately, there is no one in your household who is in
the categories I need for this interview. Thank you for your time.
Goodbye." info;
AllFull "All our interviewing targets have been met. I'm sorry to have
troubled you." info;
The routing code for this example is mainly concerned with testing the current state of the quota
cells and generating a response list that contains only those participant categories with unfilled
quotas. It also terminates interviews when all targets have been met or when there is no one
in the household in any of the unfilled cells.
Dim Cat, ThisCell
ThisCell = 0
For Each Cat in WomanAge.DefinedCategories()
If Not QuotaEngine.QuotaGroups["WomanAge"].Quotas[ThisCell].IsBelowQuota Then
WomanAge.Categories = WomanAge.Categories - Cat
End If
ThisCell = ThisCell +1
Next
' All targets have been met and only "None" is available
If WomanAge.Categories.Count = 1 Then
IOM.Texts.InterviewStopped = AllFull
End If
WomanAge.Ask()
' No one available in unfilled cells
If WomanAge = {None} Then
IOM.Texts.InterviewStopped= NoneAvail
Else
QuotaEngine.QuotaGroups["WomanAge"].Pend()
End If
The key steps in the routing are as follows:
1. Set the display filter for WomanAge to all categories in the response list on the assumption that
all cells will have unfilled quotas.
2. For each category in turn, check whether the target for that category has been met. If so, delete
that category from the list of possible answers because no more interviews are required with
participants in this group.
3. At the end of the loop, the response list for WomanAge will contain only those categories with
unfilled quotas. If there are none (apart from “None” for which there is no quota), issue an
appropriate message and terminate the interview, flagging it as terminated due to quota control.
901
Base Professional
4. The interviewer is instructed to speak to a participant in one of the unfilled quota cells. If there
is no one available in any of these categories, the interviewer selects “No one available”. The
interview is terminated due to quota control and a message explaining this is displayed for the
interviewer to read out.
5. If a suitable participant is available, the pend count for that quota cell is incremented and the
interview continues.
Note: Although this method reduces the number of interviews that will fail due to full quotas,
it is not foolproof. When quotas are very close to being filled and many interviews are running
concurrently, it is possible for a quota to be unfilled when an interview starts but to be filled by the
time the pend request is executed.
This example works even if you insert additional responses in the middle of the list once
interviewing has started (unlikely in this particular example, but possible if the quota controlled
list was a brand or product list). When the quota tables are created, each quota cell is given a
unique ID starting at 1. If you later add extra responses, these responses are inserted in the quota
tables at the point they appear in the response list but they are given the next free quota ID in the
list. So, for example, inserting an extra response in the third position of a five-response list will
show that response at the fourth position in the quota table but its ID will be 6.
Comparing the Number of Completes Against the Target
If you want to ignore pended interviews when checking quotas, you can compare each
cell’s count of completed interviews against the target. This may mean that you end up
exceeding targets in some cases if two interviews are running concurrently for the same
quota cell and only one interview is required to achieve the target. (For this to work, the
Allow OverQuota option must be switched on. You can do this when you define quotas (see
(UserGuide.chm::/Intug-definetablequotas.htm)) or at any time during the course of the project
(see (UserGuide.chm::/Intug-rq_change.htm).)
To check the completed count, type:
QuotaEngine.QuotaGroups["GroupName"].Quotas[CellNumber].Completed

GroupName is the name of the quota question.
CellNumber is the number of the quota cell to be tested. Cells are numbered sequentially
from 1 and their order corresponds to the order of responses in the question’s response list.
902
Chapter 1
Here’s an example that shows how to check which age groups are available before asking the
interviewer to find a respondent in a suitable age group. The metadata is:
WomanAge "INTERVIEWER: Ask to speak to someone in one of the following

categories and select the appropriate category from the list."
categorical [1..1]
{
FU21 "Woman under 21",
F50Plus "Woman 50 or older",
None "No one available (DO NOT READ)"
};
NoneAvail "Unfortunately, there is no one in your household who is in
the categories I need for this interview. Thank you for your time.
Goodbye." info;
AllFull "All our interviewing targets have been met. I'm sorry to have
troubled you." info;
The routing code is:
Dim Cat, ThisCell

ThisCell = 0
WomanAge.Categories = WomanAge.DefinedCategories()
For Each Cat in WomanAge.DefinedCategories()
If QuotaEngine.QuotaGroups["WomanAge"].Quotas[ThisCell].Completed >= _
QuotaEngine.QuotaGroups["WomanAge"].Quotas[ThisCell].Target Then
WomanAge.Categories = WomanAge.Categories - Cat
End If
ThisCell = ThisCell+1
Next
' All targets have been met and only "None" is available
If WomanAge.Categories.Count = 1 Then
IOM.Texts.InterviewStopped = AllFull
End If
WomanAge.Ask()
' No one available in unfilled cells
If WomanAge = {None} Then
IOM.Texts.InterviewStopped= NoneAvail
Else
QuotaEngine.QuotaGroups["WomanAge"].Pend()
End If
Prioritizing Quota Cells for Multiple Choice Answers
When you have quotas for multiple choice responses, the quota control system normally
terminates an interview only if the targets for all of the chosen responses have been met.
Otherwise, it pends the cells for the responses whose targets have not been met and returns the
names of those cells in the WasPendedList property. The pend result flags will be a collection of
values that reflects the actions taken.
For example, if the respondent has used brands A, B, and C and the target for brand B has
been met, the cells for brands A and B will be pended and the interview will continue. Quota
cells A and C will be named in WasPendedList, and the quota flags for the interview will be
qrWasPended, qrOverTarget, and qrBelowTarget.
You can change this behavior by assigning a priority value to each quota so that cells are
pended in a certain order, or you can set up least-full quota-ing that always pends the cells that are
currently the least full. Refer to Quota Prioritization for Multiple Response Categorical Questions
for further details about the various methods of prioritization.
903
Base Professional
If you use one of the standard prioritization methods, there is generally nothing that you need to
do in the questionnaire script except pend the quota cells at the appropriate point in the interview.
You will, however, need to set some variables in the project’s quota database to specify which type
of prioritization you want to use (see for details). The topics listed below provide some examples
of how you can use quota prioritization in your scripts. Unless otherwise stated, all examples work
equally well with all prioritization methods.
Pending One Cell Only using Prioritization
Here is a simple example that you can use for familiarizing yourself with the different methods of
prioritization. It is designed to work with quotas where only one cell is pended per question.
The metadata for the script is:
Brands define
{
Alpine,
HelenB "Helen Bradley's",
DFresh "Dairy Fresh",
Kentish "Kentish Farm",
Finborough,
Alsace
};
IceCream "Which brands of ice cream do you buy?" categorical [1..]
{use Brands};
Flavor "Which are your favorite flavors in the {#PendedBrands} brand
of ice cream?" categorical [1..]
{
Chocolate, Mint,
Toffee "Toffee crunch",
Raspberry "Raspberry ripple",
Strawberry, Vanilla,
OtherFlavor "Other"
};
AllFull "All our interviewing targets have been met. I'm sorry to
have troubled you." info;
The routing code is:

IceCream.Ask()
Dim Pendresult, category, PendedBrands
' Pend cells as specified in the quota database
PendResult = QuotaEngine.QuotaGroups["IceCream"].Pend()
If (IsSet(PendResult, QuotaResultConstants.qrWasPended)) Then
' Cell was pended so find out which one it was
For Each category in IceCream.Categories
If (Find _
(QuotaEngine.QuotaGroups["IceCream"].Quotas.WasPendedList[0].Expression, _
"{" + category.Name + "}") >= 0) Then
PendedBrands = category.Label
End If
Next
Else
' No cells pended so terminate interview
IOM.Texts.InterviewStopped = AllFull.Label
End If
' Ask more about the pended brand
Flavor.Ask()
In this routing code, the first If statement tests whether a cell was pended. If so, we need to find
the category (response) text so that it can be displayed in the text of the Flavor question. The For
Each loop cycles through the responses in the IceCream response list and compares them with the
text in the description of the pended quota cell.
904
Chapter 1
In the Find statement, WasPendedList contains a flat list of the names of the quota cells
that were pended. Numbering in this list starts at 0 so WasPendedList[0] refers to first (and
in this example, only) quota cell pended. The Expression object contains the definition of the
quota cell as it is stored in the quota database.
If a match is found between a category in the response list and a string in the description of the
pended quota cell, the category name is saved for use in the rest of the script.
The Else section of the code deals with interviews where no quotas were open for pending.
An explanatory text is set into the end of interview page and the interview is terminated.
The routing section ends by asking the respondent which flavor ice cream he or she likes best
for the brand whose quota cell was pended.
Before you can run this script you will need to set up the quotas as follows:
E Use the IBM® SPSS® Data Collection Quota program or the Quota option in IBM® SPSS®
Data Collection Base Professional to create a .mqd file. Set a target of, say, three interviews
for each brand.
E Activate the project and on the Quota tab select the option to create a new quota database.
E Specify the number of brands you want to pend and the method of pending you want to use.
There are two ways of doing this:
Open the Quotas activity in IBM® SPSS® Data Collection Interviewer Server
Administration and select Prioritization in the drop-down Edit box. See Prioritizing Quotas
(ms-its::UserGuide.chm::/Intug-rq_prioritize.htm) for details.
Open the QUOTA_Matrix table for the project and set PendLimit to 1 because you want to
pend one brand only. Set the value of PendMode appropriate to the type of test you want
to run:
Prioritization Type Value for PendMode
Priority 1
Random 2
Least full based on ratio (percentage) of completes 3
to target
Least full based on number of completes 4
E If you are testing Priority pending, open the QUOTA_Quota table and set Metadata to a unique
value in the range 1 to 6 for each quota. The lower the number the higher priority so, for example,
if Alpine is 2 and Dairy Fresh is 5 and the respondent chooses those two answers, the cell for
Alpine will always be pended as long as the target has not been met.
Run a set of interviews using each priority type and complete sufficient interviews to fill a number
of quota cells. Observe how the quota control system selects a different cell to pend based on
the prioritization type.
This is a very simple script designed to illustrate the different pending methods in a way that is
easy to follow. Often, you’ll want more complex quota control than this, usually with more than
one cell being pended each time. The following sections show how this can be done.
905
Base Professional
Pending a Number of Cells using Prioritization
This topic takes the simple example of pending a single cell and extends it to work with a number
of pended cells. Instead of asking respondents to choose their favorite flavor from one brand, the
script now asks them to choose flavors for a number of brands. The number of brands is set in the
PendLimit variable in the QUOTA_Matrix table.
The metadata section of the script now has the Flavor question displayed as a grid, with one
column for each brand pended. It also has a PendedBrands question that is used in the routing
section to filter the brand list for the grid so that it contains only the pended brands. (In the
example of pending one cell only, PendedBrands was a simple variable that was used for display
purposes only.)
Brands define
{
Alpine,
Finborough,
Alsace
};
{use Brands};
PendedBrands "Brands pended." categorical [1..]
{use Brands};
FlavorGrid "Which are your favorite flavors in the following brands
of ice cream?" loop
{use Brands} fields
(
Flavor "" categorical [1..1]
{
Chocolate, Mint,
Strawberry "Strawberry",
Vanilla "Vanilla",
OtherFlavor "Other"
};
) column expand grid;
906
Chapter 1
The routing code that pends the least full cell and then selects that brand as the filter for the
Flavor question is:
IceCream.Ask()
'Terminate interviews where no cells can be pended
If Not _
(PendQuotas(IceCream, PendedBrands, QuotaEngine.QuotaGroups["IceCream"])) _
Then
IOM.Texts.InterviewStopped = AllFull.Label
End If
FlavorGrid.QuestionFilter = PendedBrands.Response.Value
FlavorGrid.Ask()
' Pend quotas and return names of pended brands

Function PendQuotas(QuotaQuestion, CellsPended, QuotaGroupToPend)
Dim pend_result
' Initialize return to False
PendQuotas = False
' Pend quotas
pend_result = QuotaGroupToPend.Pend()
If (IsSet(pend_result, QuotaResultConstants.qrWasPended)) Then
' Save the pended cell information
CellsPended.Response.Value = _
CreateFilter(CellsPended.Categories, QuotaGroupToPend.Quotas)
PendQuotas = True
End If
End Function
' Build list of names of pended brands

Function CreateFilter(Categories, Quotas)
Dim pended_quota, filter
For Each pended_quota In Quotas.WasPendedList
filter = filter + GetCategoryFromQuota(Categories, pended_quota)
Next
CreateFilter = filter
End Function
' Get category names of pended brands

Function GetCategoryFromQuota(Categories, Quota)
Dim category
GetCategoryFromQuota = "{}"
For Each category in Categories
If (Find(Quota.Expression, "{" + category.Name + "}") >= 0) Then
GetCategoryFromQuota = CCategorical(category)
Exit Function
End If
Next
End Function
The comments in the script summarize what it does. The metadata requires respondents to answer
additional questions about certain brands that they have mentioned. Which brands these are
depends on the type of prioritization you are using, how many cells you want to pend, and whether
the quotas are still open for any of the brands mentioned. The script covers all these points.
The return value of the PendQuotas function determines whether the interview can continue
past the first question. If the function returns False, no quotas could be pended and the interview is
terminated.
If PendQuotas pends any cells, it calls the CreateFilter function to assign the corresponding
responses to the PendedBrands question. This question is used as a filter for FlavorGrid so
that the grid contains columns for just the pended brands. The response names are extracted by
the GetCategoryName function, which takes each category in the BrandsPended response list
in turn and compares it with the descriptions of the pended quota cells. When a match is found,
the function converts the name into a category number so that it can be assigned as a response in
the usual way.
907
Base Professional
Quota Control when Reviewing Interviews
The main purpose of reviewing interviews is for quality control so it is important that reviewers
are able to follow the original path through the interview. Often, the path that respondents take
through the interview script is determined by quota control. For example, if the project uses least
full prioritization for multiple choice responses, the rest of the rest of the interview is wholly
dependent on the state of the quotas at the point they were tested. Therefore, instead of retesting
the quotas when the interview is reviewed, you should reuse the original results of the pend
request even if they would normally be invalid for new interviews at this point.
The other important point about reviewing interviews is that the review process should not affect
the quota counts in any way. Instead, it needs to ignore any instructions to interact with the
quota control system. It is your responsibility to set this up. If you forget to do this, the review
process will repend quota cells during the review process and increment the counts of completed
interviews at the end of the review. In effect, it will be as if you conducted two separate but
identical interviews.
To reuse the original quota results for reviewed interviews and to ensure that the review does
not affect the quota counts in any way, place the following code around the code that implements
quota control. If there is more than one quota test in the script, place these statements around each
set of quota control code.
If IOM.Info.IsReview Then
Question = Question.Info.OffPathResponse
Else
QuotaScripting
End If
where:
Question is the name of a categorical question whose answer contains the quota cells that
were pended during the original interview. For example, if quotas were set for different
brands of ice cream, this question’s answer would be the brands that were pended when
the interview originally took place.
QuotaScripting is the code that carries out the quota tests.
This code takes advantage of the fact that when an interview is reviewed, all the data that is held
for it becomes off-path. As the reviewer steps through the interview and accepts the current
answers, that data becomes flagged as being on-path again. By placing the result of the quota
test on-path you make its value available to the review and the interview will continue as it
did when the quotas were originally tested.
If your script does not have a question that records the names of the pended cells, you can easily
change it to work in this fashion. Of course, this does not matter if you are sure that interviews for
the project will never be reviewed.
Quota Control and Snapbacks
Interviewers and respondents may use the Back or Go To button to return to an earlier question in
the interview. They can view the answer or change it. If no answers are changed during snapback,
any quota tests remain valid. However, if an answer is changed and the interviewer or respondent
uses the Forward or Go To button to skip forward in the interview, any quotas tests in the skipped
908
Chapter 1
portion of the script are redone. This may or may not result in a different set of cells being pended
or a different set of questions being asked.
When quotas are based on a multiple-choice response list, respondents may contribute towards
more than one quota cell. However, if a cell is already full, the quota control system ignores the
respondent’s answer for that cell and increments the pend counts for the others answers chosen.
For example, in a brand awareness survey, if the respondent mentions Alpine, Kentish Farm, and
Dairy Fresh and the quota for Kentish Farm has already been filled, the respondent will be added
into the Alpine and Dairy Fresh quotas only.
If there are later questions based on the brands known, the respondent will be asked those
questions for all the questions that he/she mentioned — that is, for Alpine, Kentish Farm, and
Dairy Fresh — even though he/she did not contribute to the quota for Dairy Fresh. If it is
important in your survey that respondents answer questions only for the quotas to which they
contribute, then you will need to write a dummy question or create a temporary variable that
keeps track of the cells that are pended for the respondent and use that question as the filter for
the additional questions. rather than the question that respondent actually answered. There are
examples of this type of filtering in Pending One Cell Only using Prioritization andPending a
Number of Cells using Prioritization.
Quota Control in Restarted Interviews

When an interview is stopped or times out, any cells that were pended for the interview are
rolled back (decremented by 1) so that it is as if the interview had never taken place. This ensures
that unfinished interviews do not contribute towards the targets when the interviewing program is
checking quotas for new interviews.
Restarting Timed Out Interviews by Clicking Next or Previous

Data for timed out interviews is held for a certain amount of time in the value cache, and can be
used for restarting an interview at or very near the point at which it timed out. If the interview
is restarted by clicking Next, the interviewing program reloads the interview from the value
cache and repends any quotas that were previously pended, even if this means exceeding the
quota targets for those cells.
If the interview is restarted by the interviewer or respondent clicking Previous, the interview
is restarted as described above and then the previous page of the interview is displayed. If the
answer to the quota-controlled question is changed, the quota tests are carried out using the new
answers. In this way, an interview that may have resulted in an over-quota cell count may actually
result in a completely different quota cell being pended by the time the interview ends. Refer to
Quota Control and Snapbacks for further information about snapbacks and quota control.
Restarting Stopped Interviews
Interviews that are stopped by clicking the Stop button or by a statement in the script can only be
restarted if the project uses sample management, since this allows the interviewing program to
locate the interview data using the ID of the respondent’s sample record.
When interviews are restarted via sample management, the interviewing program silently
replays the stopped portion of the interview using the data in the case database. If it reaches an
instruction to pend quota cells, the interviewing program passes the instruction to the quota object
model and the cells are pended as if this were a new interview. What happens next depends on
909
Base Professional
the amount of time that has elapsed between the original interview and the restart, how busy the
project is, and the data type of the quota-controlled question.
If the quota is based on a single-choice response list and the target for the respondent’s answer
has still not been met, the quota cell is repended and the replay continues. If the target has been
met, the interview is terminated and any data associated with subsequent questions is discarded.
If the quota is based on a multiple-choice response list and none of the targets for the
respondent’s answer have been met, the quota cells are repended and the replay continues using
the original data. If some cells are still open and others are now closed, the cells for the answers
with open quota cells are repended and the replay continues using the original data. If all targets
have been met for all the respondent’s answers, the interview is terminated and data for any
subsequent questions is discarded.
Note: If you have a set of questions that are based on the responses to a quota-controlled
question that allows multiple responses, and the cells that are pended change between the original
and the restarted interview, the interviewing program does not discard the data associated with the
cells that are no longer pended. You should consider whether this affects the validity of your data.
For example, suppose the BrandsBought question is quota controlled. The respondent chooses
brands A, B, and C, answers additional questions about those brands, and then clicks Stop. When
the respondent restarts the interview, the interviewing program reads the answer A, B, C for
BrandsBought but finds that the target for brand C has been met, so it pends just the cells for brands
A and B. The interviewing program comes to the questions based on BrandsBought and finds that
it still has valid data for the questions, so the replay continues. The data for brand C remains in the
case data even though it is no longer valid in terms of the current state of the interview.
Restarts and Snapbacks with Least Full Quotas
Least Full quota control takes a set multiple-choice answers and pends only the least full cell
related to those answers. You may choose how many cells to pend. For example, you may allow
respondents to choose any number of responses but will always pend only the two cells containing
the fewest number of respondents. Since the least full cells will vary as the survey progresses, it is
inevitable that the cells that are available to be pended when an interview starts and unlikely to be
the cells that are available for pending if the interview is stopped and then restarted. Indeed, in
very busy projects, the least full cells may change between the time the question is first answered
and the time the interviewer or respondent snaps back to check or change that answer.
Quota Control and Snapbacks and Quota Control in Restarted Interviews explain the general
rules and behavior in these situations and highlight the points at which extra care is required. In
particular, they note the times when you may need additional scripting to ensure consistency
between the quota cells and the interview data.
If you are using least-full pending, you may need to take even more account of this behavior in
your script because changes in the cells pended may have far reaching effects on your data. To
understand the full extent of what’s involved, take the previous example but, this time, assume
that only the least full brand bought is pended.
When the respondent starts the interview and chooses brands A, B, and C, the cell for brand
A is pended as being least full and the respondents answers subsequent questions about brand
A only. When the respondent restarts the interview, brand B is now the least full so that cell is
pended instead of the cell for brand A. The interviewing continues replaying the interview from
the case data because the answers are still valid responses for the questions that it needs to ask. It
910
Chapter 1
does not know that the answers refer to brand A rather than brand B. The interviewing program
reaches an unanswered question and displays it. If the question is filtered based on the cells
pended and the question text includes the brand name, the respondent will answer the question
based on his or her experience of brand B. So, not only will the final case data contain out-of-date
answers, it will also contain data related to a mixture of brands.
Use the following questions to help you make decisions about how to deal with this.
Do you want to pend the quota cells that were least full when the interview originally started
or would you rather pend based on the current counts? If you want to repend the original cells,
what if some cells are now full? Will you continue with the ones that are still unfilled even if
this means discarding some responses that would originally have been used?
If all the originally pended cells are now full, do you want to pend a new set of cells or would
you rather terminate the interview?
What if the respondent has snapped back to the quota controlled question and completely
changed the answer so that none of the originally pended responses are chosen?
If other cells have become available for pending since the original quota test (other interviews
with pended counts may have been terminated so that the pended counts were rolled back), do
you want to see whether those cells can be pended for this interview?
If the cells that are pended change and there are later questions that are based on the pended
answers, how are you going to ensure that the data for those questions is correct?
The following topics suggest ways of scripting to answer these questions:

Re-pending the Originally Pended Least-Full Cells
When the Original Least-Full Cells are Not Available
For a complete example that brings together all these decisions in a single
script, see the LeastFullQuota.mdd example script that is installed in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Quota\LeastFull.
Note that this script is an example of how to implement least full pending: it does not illustrate the
default method of quota control for multiple-choice response lists.
Note: In all cases, saving the names of the pended cells as the responses to a question makes
restart scripting much easier because you always have this question available for comparisons
between the original and restarted versions of the interview.
Re-pending the Originally Pended Least-Full Cells
This topic shows how you can reuse the cells that were pended as least full in the original
interview. The code is suitable for interviews that are restarted from sample management, where
the interviewing program replays the interview from the case data, and for snapbacks where the
respondent does not change the answers to the quota controlled question so that none of the pended
answers are present in the new answer. The procedure for restarts and snapbacks is as follows:
Terminate interviews if all the originally pended cells are full.
Repend the cells that were originally pended if they are still open.
If some cells are now full, pend only the unfilled cells even if this means that fewer cells
are pended.
911
Base Professional
Ignore any brands that were mentioned but not pended in the original portion of the interview.
Reset the value of the filter question so that later questions are re-asked about the cells that are
pended in the restarted portion of the interview.
You’ll find some worked examples that clarify these points later in the topic.
The script asks respondents which brands of ice cream they buy and then, for the two brands
whose quotas are least full, asks which is the favorite flavor in each brand. The number of cells to
pend (two) is set in the QUOTA_Matrix table. The metadata for the example is:
Brands define
{
Alpine,
Finborough,
Alsace
};
{use Brands};
PendedBrands "" categorical [1..]
{use Brands};
of ice cream?" loop
{use Brands} fields
(
{
Chocolate, Mint,
Vanilla "Vanilla",
OtherFlavor "Other"
};
In this section, the CellsPended question is designed to store the names of the brands that were
pended because their cells were the least full so that this information is readily available when
interviews are restarted.
912
Chapter 1
The routing section of the script is:

IceCream.Ask()
If Not _
(PendQuotas(IceCream, PendedBrands, QuotaEngine.QuotaGroups["IceCream"])) Then
'Quotas full so terminate interview
IOM.Texts.InterviewStopped= AllFull.Label
End If
FlavorGrid.QuestionFilter = PendedBrands.Response
FlavorGrid.Ask()

Dim pend_result, orig_answers
PendQuotas = False
' A new interview so pend brands and set question filter

If (CellsPended.Info.OffPathResponse Is Null) Then
If (IsSet(pend_result,QuotaResultConstants.qrWasPended)) Then
PendQuotas = True
Exit Function
End If
' Snapback/restarted interview. Re-pend originally pended brands if any

' of those cells are still unfilled. If some are now full, pend only the
' unfilled ones. Set/reset question filter accordingly.
Else
If (QuotaQuestion.ContainsAny(CellsPended.Info.OffPathResponse)) Then
orig_answers = QuotaQuestion.Response.Value
QuotaQuestion.Response.Value = _
QuotaQuestion.Response.Value * CellsPended.Info.OffPathResponse
QuotaQuestion.Response.Value = orig_answers
PendQuotas = True
Exit Function
End If
' All originally pended cells are full so flag for termination.
PendQuotas = False
End If
End If
End Function

filter = filter + GetCategoryFromQuota(Categories,pended_quota)
Next
End Function

Function GetCategoryFromQuota(Categories, Quota)
Dim category
GetCategoryFromQuota = "{}"
For Each category in Categories
If (Find(Quota.Expression, "{" + category.Name + "}") >= 0) Then
GetCategoryFromQuota = CCategorical(category)
Exit Function
End If
Next
End Function
913
Base Professional
The key part of this script is the PendQuotas function that checks and pends quotas. It separates
interviews into new interviews and restarted or replayed interviews. A new interview is one in
which the CellsPended question has no off-path response; that is, it has never been answered.
Restarted interviews that have previously passed through quota control will have the names
of the pended brands stored in this question.
If this is a new interview, the quota-controlled responses are checked to see which ones have
the least full cells, and the two cells with the lowest counts are pended. PendQuotas calls the
CreateFilter function to build a list of the names of the pended categories and this function calls
GetCategoryFromQuota to convert those names into category values so that they can be assigned
as the answers to the CellsPended question.
If this a restarted or replayed interview, PendQuotas starts by checking whether the current
answers to the quota-controlled question include any of the cells that were previously pended for
this interview. In an interview that is restarted from sample management this will always be
the case, but for a replay after a snapback it is possible that the respondent may have chosen a
completely different set of answers so there will be no correlation with the pended cells at all. The
statement that compares the previously pended cells with the current answers is:
QuotaQuestion.Response.Value = QuotaQuestion.Response.Value * CellsPended.Info.OffPathResponse
The * symbol is the . It merges the contents of two lists to produce a list of values that are present
in both lists. In other words, it sets the value of the quota-controlled question to be the brands that
were chosen this time and that were pended last time. Brands chosen this time but not pended last
time and brands that were pended last time but not chosen this time are ignored.
Note: Although this statement overwrites the brands that the respondent actually chose with the
brands that we want to try pending, the assignment is only temporary. The respondent’s answers
are saved in the temporary orig_answers variable before the comparison is made, and these are set
back into the question once the quota cells have been pended.
The script attempts to pend the two least full cells from this list. If the cells can be pended, the
interview continues, otherwise it is terminated. The target for each brand is two and only two
cells can be pended per interview.
The following table shows the results of five interviews. These interviews were the first that
took place on a new project. They were run consecutively in the order shown and no other
interviews took place during this period.
Interview ID IceCream PendedBrands FlavorGrid
1 Alpine, Helen Bradley’s, Alpine, Dairy Fresh Answered
Dairy Fresh
2 Alpine, Helen Bradley’s, Helen Bradley’s, Dairy Click Stop
Dairy Fresh Fresh
3 Helen Bradley’s, Dairy Helen Bradley’s, Dairy Answered
Fresh Fresh
2 (Restarted) Alpine, Helen Bradley’s, Helen Bradley’s Answered
Dairy Fresh
4 Dairy Fresh, Kentish Kentish Farm, Alsace Click Previous to go
Farm, Alsace back to IceCream
4 (Snapback) Alpine, Finborough Interview terminated
914
Chapter 1

5 Helen Bradley’s, Kentish Kentish Farm, Alsace Click Previous to go
5 (Snapback) Alpine, Finborough, Alsace Answered
Alsace
Interviews 1 to 3 show the effect of stopping an interview and then restarting it after some of
the quotas that were originally pended for that interview have been filled. When interview 2 is
stopped, the pend counts for Helen Bradley’s and Dairy Fresh are rolled back so that there is still
two interviews possible for Helen Bradley’s and one interview possible for Dairy Fresh. At the
end of interview 3 the quota Dairy Fresh has been filled, so when interview 2 restarts only the
quota for Helen Bradley’s can be pended. The quota for Alpine cannot be pended even though it is
still unfilled because it was not one of the brands that was originally pended for the interview.
Interview 4 shows the result of snapping back and completely changing the brands used. Even
though the quotas for Alpine and Finborough are not full, the interview is terminated because they
are not the brands that were originally pended for this interview.
Compare that with interview 5 in which only one of the pended answers is changed. Alsace
was one of the pended brands and it remains available for pending after the snapback, so the
interview continues with just this brand pended.
In most cases you’ll want to extend the script so that it allows other cells to be pended if the
original least full cells are no longer available for whatever reason. When the Original Least-Full
Cells are Not Available suggests a way of doing this.
When the Original Least-Full Cells are Not Available
This topic explains how you can choose other cells to pend when the cells that were originally
pended as being the least full are no longer available. This may be because one or more of those
cells has been filled during the period that the current interview has been stopped, or it may
be because the respondent has snapped back and changed the answers to the quota-controlled
question so that none of the original responses is now chosen.
Note: If you have not already read Re-pending the Originally Pended Least-Full Cells, you may
find it useful to do so before continuing with this topic because it takes you through the tasks that
lead up to the ones described in the current topic.
915
Base Professional
The script asks respondents which brands of ice cream they buy and then, for the two brands
whose quotas are least full, asks which is the favorite flavor in each brand. The number of cells to
pend (two) is set in the QUOTA_Matrix table. The metadata for the example is:
Brands define
{
Alpine,
Finborough,
Alsace
};
{use Brands};
PendedBrands "" categorical [1..]
{use Brands};
of ice cream?" loop
{use Brands} fields
(
{
Chocolate, Mint,
Vanilla "Vanilla",
OtherFlavor "Other"
};
In this section, the CellsPended question is designed to store the names of the brands that were
pended because their cells were the least full so that this information is readily available when
interviews are restarted.
916
Chapter 1
The routing section of the script is:

IceCream.Ask()
'Terminate interviews where no cells can be pended
If Not _
(PendQuotas(IceCream,PendedBrands, QuotaEngine.QuotaGroups["IceCream"])) Then
IOM.Texts.InterviewStopped= AllFull.Label
End If
FlavorGrid.QuestionFilter = PendedBrands.Response
FlavorGrid.Ask()

Dim pend_result, orig_answers
PendQuotas = False
' A new interview so pend brands and set question filter

If (CellsPended.Info.OffPathResponse Is Null) Then
CellsPended.Response = _
PendQuotas = True
End If
Exit Function
End If
' A snapback that replaces/deletes the answers whose quotas were previously
' pended, so pend new cells based on current answers.
If Not (QuotaQuestion.ContainsAny(CellsPended.Info.OffPathResponse)) Then
PendQuotas = True
Exit Function
End If
End If
' A restarted interview, or a snapback that retains some of the previously

' pended answers. Pend the cells that were previously pended if they are
' still open. If some cells are now full or the responses are no longer
' chosen, ignore them.
orig_answers = QuotaQuestion.Response.Value
QuotaQuestion.Response.Value = _
QuotaQuestion.Response.Value * CellsPended.Info.OffPathResponse
QuotaQuestion.Response.Value = orig_answers
PendQuotas = True
Exit Function
End If
End If
' A restarted interview or a snapback that that retains some of the

' previously pended answers, but where the originally pended cells are now
' full. If there are other answers that can be pended, do so.
If (QuotaQuestion.Response.Value > CellsPended.Info.OffPathResponse) Then
CellsPended.Response = _
PendQuotas = True
End If
Exit Function
End If
' Cannot pend any cells so terminate interview.
PendQuotas = False
End Function

filter = filter + GetCategoryFromQuota(Categories,pended_quota)
Next
End Function

917
Base Professional
The comments in the script summarize the key steps in the script. As you can see, the PendQuotas
function has five possible course of action.
If this is a new interview (that is, the CellsPended question has no value) then pend the two
cells with the least full quotas.
If the current response to the quota-controlled question does not contain either of the cells that
were previously pended, pend new cells based on the current answers to the question. Since a
restarted interview retrieves the answers to questions from the case data in the value cache,
you would expect the current answer to match the previous one, so this situation applies only
to snapbacks where the answer to the question has been manually changed.
If the current response to the quota-controlled question contains at least one of the previously
pended cells, test whether these cells can be repended. If so, repend them even if this means
that fewer cells are pended than would normally be the case. This situation applies to restarts
from sample management and also to snapbacks where the answer to the question has been
changed but still includes some of the previously pended responses. If the cells cannot be
repended, see whether there are other cells that can be pended instead.
If the previously pended cells are a subset of the current response to the quota-controlled
question (that is, the current question contains all the pended cells and more) and the
previously pended cells are now full, try pending other answers that were selected at the time
the cells were originally pended.
If no cells can be pended, set a flag for terminating the interview.
The following table shows four interviews that illustrate these actions taking place. The target for
each brand of ice cream is two interviews and the two least full cells can be pended each time.
These interviews were the first that took place on a new project. They were run consecutively in
the order shown and no other interviews took place during this period.
1 Alpine, Helen Bradley’s, Helen Bradley’s, Dairy Answered
Dairy Fresh Fresh
2 Alpine, Helen Bradley’s, Alpine, Helen Bradley’s Click Stop
Dairy Fresh
3 Alpine, Helen Bradley’s Alpine, Helen Bradley’s Answered
2 (Restarted) Alpine, Helen Bradley’s, Alpine Answered
Dairy Fresh
4 Alpine, Kentish Farm, Kentish Farm, Alsace Click Previous to go
Alsace back to IceCream
4 (Snapback) Helen Bradley’s, Finborough Answered
Finborough
5 Helen Bradley’s, Kentish Kentish Farm, Alsace Click Previous to go
5 (Snapback) Alpine, Finborough, Alsace Answered
Alsace
Interviews 1 to 3 show the effect of stopping an interview and then restarting it after some of
the quotas that were originally pended for that interview have been filled. When interview 2 is
stopped, the pend counts for Alpine and Helen Bradley’s are rolled back so that there are still two
interviews possible for Alpine and one interview possible for Helen Bradley’s. At the end of
interview 3 the quota for Helen Bradley’s has been filled, so when interview 2 restarts only Alpine
918
Chapter 1
is repended. The script does not attempt to pend additional responses (in this case, Dairy Fresh
which was originally chosen but not pended) because this may have mean that some questions
may be unnecessarily repeated if they are based on the pended brands.
For example, suppose that, in the original position of the interview, the respondent answered
nine out of ten questions about Alpine and Helen Bradley’s yogurts and then stopped the interview.
On the restart, Helen Bradley’s in no longer pended so the questions for that brand are ignored and
the replay runs all the way to the tenth question about Alpine yogurt. If the script had pended
Dairy Fresh as part of the replay, the replay could stop at the first question for Dairy Fresh and
the interview would runs in the normal way from there. The questions about Alpine would be
displayed with their existing answers while the questions about Dairy Fresh would be displayed
with no answers selected.
Note: If you want the script to behave in this way — that is, to pend additional answers to try
to ensure that two brands are always pended — remove the Exit Function statement from
the code section that starts:
so that the script continues with the test for other cells to pend.
Interview 4 starts. It shows the result of snapping back and completely changing the brands
used. Helen Bradley’s is already full, but Finborough is not so it is pended.
Interview 5 starts. It shows the result of snapping back, deleting one of the pended brands and
choosing another in its place. At first, Kentish Farm and Alsace are pended, but the respondent
snaps back, deletes Helen Bradley’s and Kentish Farm, and chooses Alpine and Finborough
in their place. Neither of these cells is full, but Finborough is pended because it is less full
than Alpine, which already has one interview. Alsace remains pended because it was one of
the originally pended cells.
Events
Events are predefined objects that you can use for specifying actions that are to take place at
certain points in an interview. You can define events for any of the following:
Start of interview. Actions to be carried out when an interview starts or restarts; for example,
creating global objects that can be used during the interview, like ADO recordsets or ODBC
connections. For more information, see the topic OnInterviewStart Event on p. 920.
End of interview. Actions to be carried out when an interview stops, times out or completes. These
are typically actions to clean up objects created at the start of the interview, or to generate question
and response summaries. For more information, see the topic OnInterviewEnd Event on p. 921.
Before asking a question. Actions to be executed before a question is asked; for example, setting
additional question properties. For more information, see the topic OnBeforeQuestionAsk Event
on p. 921.
After asking a question. Actions to be executed after a question has been asked, answered,
and validated using the standard validation procedure. For more information, see the topic
OnAfterQuestionAsk Event on p. 922.
919
Base Professional
Before response validation occurs. Actions to be executed after the respondent submits an answer
but before any validation is run, including the standard validation. For more information, see the
topic OnBeforeQuestionValidation Event on p. 922.
When an error occurs. Actions to be carried out when an interview terminates abnormally. For
more information, see the topic OnInterviewError Event on p. 923.
All events run automatically at the appropriate times but do nothing unless you define actions
for them.
This chapter also looks at objects within interviews and discusses both objects and events in
relation to the interview life-cycle and the starting, stopping, and restarting of interviews.
Events and the Interview Lifecycle
The following diagram illustrates the lifecyle of a simple interview and shows how the various
events fit into it.
Figure 1-205
Interview lifecycle with events
920
Chapter 1
If the respondent clicks Stop at point 1, or the script executes a Terminate() statement at point
2, the interview ends immediately and OnInterviewEnd() runs. If the interview is restarted
via sample management, OnInterviewStart() runs and the interview is silently replayed, but
without the events being run between questions.
If the respondent is idle for a long time at point 1, the interview times out and
OnInterviewEnd() runs. If the respondent leaves his/her browser open and later clicks Next,
OnInterviewStart() runs and the interview continues from the current point.
In both restarts there is quite a bit going on in the background that you, as a scriptwriter, need
to be aware of.
When OnInterviewEnd() runs, it saves the current state of the interview.
When the interview restarts, OnInterviewStart() reloads the saved interview state.
Any variables that are set to an external object, such as a database connection, cannot be
reconnected automatically. This must be done manually in OnInterviewStart().
Any scripting that appears before the first .Ask() statement is not rerun. For example, the
following will not work after a restart:
Dim AdoConn
Set AdoConn = CreateObject("...")
AdoConn.Connect("...")
Age.Ask()
rs = AdoConn.Execute(...)
' Do something with rs here
...
Gender.Ask()
If the interview times out on Gender, the lines shown in italics will be re-executed when
the interview restarts but AdoConn will be Null (or some undefined value). By placing the
statements that make the connection in OnInterviewStart() you ensure that they will be
run when a new interview starts and whenever an existing interview is restarted.
OnInterviewStart Event
The OnInterviewStart event runs when an interview starts or restarts. If your script uses an
ADO recordset or an ODBC database you can make the connection to that recordset or database
by placing the appropriate statements in this event.
To define actions for the start of an interview, place the following statements in the routing
statements
End Sub
where:
statements are interview scripting or mrScriptBasic statements that define the actions to
be carried out.
IOM is the interview object. This gives the event access to all the properties and objects
related to the interview.
921
Base Professional
Here’s an example that creates an ADO recordset from an SQL database. The records can then be
used later in the script to set up the response list to a question:
Dim rsLongBrandList
Set rsLongBrandList = CreateObject("ADODB.RecordSet")
rsLongBrandList.Open("SELECT Brand FROM Brands",_
"Provider=SQLOLEDB.1;Data Source=SVR1")
IOM.Objects.AddNew("rsBrandList", rsLongBrandList)
End Sub
Refer to Paradata Example Script for an example of using OnInterviewStart to create a

database that can be used for storing paradata about the data collection process.
OnInterviewEnd Event
The OnInterviewEnd event runs when an interview stops, times out or completes, and is
typically used to clean up objects created in OnInterviewStart.
To define actions for the end of an interview, place the following statements in the routing
statements
End Sub
where:
be carried out.
Here’s an example that closes an ADO recordset that was created at the start of the interview so
that response lists could be created from records in an SQL database:
Sub OnInterviewEnd(Interview)
Dim rsLongBrandList
Set rsLongBrandList = Interview.Objects["rsBrandList"]
rsLongBrandList.Close()
End Sub
Refer to Paradata Example Script for an example of using OnInterviewEnd to write data
collection information for the interview as a whole to a database.
OnBeforeQuestionAsk Event
The OnBeforeQuestionAsk event runs before a question is asked and can be used to set
additional question properties or to track some aspect of the interview.
To define actions to be carried out before a question is asked, place the following statements
in the routing section of the script:
statements
End Sub
922
Chapter 1
where:
Question represents the current question.
be carried out.
Refer to Paradata Example Script for an example of using OnBeforeQuestionAsk to write data
collection information about each question in the interview to a database.
OnAfterQuestionAsk Event
The OnAfterQuestionAsk event runs after a question has been asked, answered, and validated
using standard validation, and can be used to perform data cleaning (such as removing carriage
return/line feed characters from text responses) or to track some aspect of the interview.
To define actions to be carried out after a question is asked, place the following statements in the
routing section of the script:
statements
End Sub
where:
be carried out.
Refer to Paradata Example Script for an example of using OnAfterQuestionAsk to prepare a
record that can be written to the paradata database for the current question.
OnAfterQuestionAsk is an ideal way of building up a summary of the respondent’s answers

that can be displayed at the end of the interview. Because it runs after a question has been asked,
you can be sure that the summary will contain only the questions that the respondent answered
rather than all questions in the script. For more information, see the topic Displaying a Summary
of Answers at the End of the Interview on p. 715.
OnBeforeQuestionValidation Event
The OnBeforeQuestionValidation event runs after a question has been asked and answered
but before the standard validation begins. To define actions to be carried out before a question’s
response is validated, place the following statements in the routing section of the script:
Sub OnBeforeQuestionValidation(Question, IOM)Qname
statements
End Sub
where:
923
Base Professional
be carried out.
Refer to Paradata Example Script for an example of using OnBeforeQuestionValidation to
prepare a record that can be written to the paradata database for the current question.
OnInterviewError Event
The OnInterviewError event runs when an interview terminates due to a scripting error, and is
typically used for custom error reporting such as sending an email message to an administrator.
The interview object and the error message are passed to the event. To define actions to be carried
out in this situation, place the following statements in the routing section of the script:
Sub OnInterviewError(IOM, ErrorMsg)
statements
End Sub
where:
ErrorMsg represents the error message.
be carried out.
Using Events to Save Interview Paradata
Paradata is information about the data collection process. For interviews, the following paradata
is available as properties of IInterview.Info:
Property Data type Description
Browser nvarchar (255) The browser used to post the web
page. The Web Service captures
the browser version from the
browser. Only available when
using the Web player.
ElapsedTime datetime The total time taken for the
interview.
InterviewerID nvarchar (64) The interviewer ID.
InterviewerTimeZone int The interviewer’s time zone.
IsDebug bit True if the interview was run in
debug mode, otherwise False.
IsTest bit True if this is a test interview,
otherwise False.
LastAsked nvarchar (255) The name of the last question
asked.
LastAskedTime datetime The time at which the last question
was asked.
924
Chapter 1

Origin nvarchar (255) The name of the software
product that created the
data. Either HTMLPlayer,
CATI_HTMLPlayer,
CATI_TTYPlayer, or Other.
OriginName nvarchar (255) The source software
product name. Used when
Respondent.Origin is {Other}.
PagesAnswered int The number of pages (questions)
answered. Normally there is one
question per page.
PagesAsked int The number of pages (questions)
displayed during the interview.
Normally there is one question
per page.
Project nvarchar (255) The project name.
RandomSeed int The value used for randomizing
responses in a list.
Renderer nvarchar (255) The name of the renderer used for
the interview.
RespondentID nvarchar (64) The respondent ID.
RespondentTimeZone int The respondent’s time zone.
ReversalSeed int The value used for reversing the
order of responses in a list.
RotationSeed int The value used for rotating
responses in a list.
Serial int The interview serial number.
ServerTime datetime The amount of processing time
used for the interview.
ServerTimeZone int The time zone of the interviewing
server.
StartTime datetime The date and time at which the
interview started.
Timeouts int How many times the interview
timed out.
The following variables are also available at the question level, as properties of IQuestion.Info
to provide paradata for individual questions:
AskCount int How many times the question
has been asked. This includes
re-asking after using Previous as
well as after validation errors.
CategoriesAsked nvarchar The categories that were displayed
in the response list, taking into
account any filters applied. This
matches the value of the question’s
Question.Categories.Filter
property. For more information,
see the topic Filtering Categorical
Response Lists on p. 680.
925
Base Professional

ElapsedTime datetime The total amount of time between
displaying the question and the
respondent clicking a navigation
button.
InterviewID nvarchar (64) The interview session ID.
NavigationSelected nvarchar (64) The navigation button used to
leave the question.
Project nvarchar (255) The project name.
QuestionName nvarchar (64) The question name.
Refer to Paradata Example Script for an explanation of how you can use events to create a
database of general information about the data collection process.
Paradata Example Script
The DDL comes with an example script that illustrates how you can gather paradata using events.
You’ll find the script and its associated files in the DDL\Scripts\Interview\Frequently Asked
Questions\Events folder wherever you have installed the DDL. Follow the instructions in the
ReadMe file to set up and run the script.
The notes in this section explain how the events are used to gather and update the paradata
during the course of the interview. Refer to the function definitions and comments in the
EnglishMuseum_WithParadata.mdd example file for information about the functions themselves.
The events are defined as follows:
AddInterviewParadata(IOM)
End Sub
UpdateInterviewParadata(IOM)
End Sub

PrepareQuestionParadata(Question, IOM)
End Sub
Sub OnBeforeQuestionValidation(Question,IOM)
If IOM.Navigations.LastSelected <> NavigationTypes.nvNext And _
IOM.Navigations.LastSelected <> NavigationTypes.nvLast Then
AddQuestionParadata(Question, IOM)
End If
End Sub

AddQuestionParadata(Question, IOM)
End Sub
These definitions cause specific things to happen at the following points in an interview.
OnInterviewStart runs at the start of each interview and calls the AddInterviewParadata
function. This function:
Creates a connection to the paradata database and adds the connection to the global objects for
the interview.
926
Chapter 1
Creates a new interview property called QuestionStartTime and adds it to the properties
list for the current interview.
Runs the UpdateInterviewParadata function to check whether a paradata record already
exists for this interview (that is, whether this is a restarted interview). If a record exists, that
record is updated; if not, a new record is created.
OnBeforeQuestionAsk runs before each question is asked and calls the
PrepareQuestionParadata function, which sets the value of the QuestionStartTime
property to the current time. This gives you the time at which each question was displayed. This is
later used in the OnAfterQuestionAsk() event to determine the ElapsedTime for the question.
OnBeforeQuestionValidation runs as soon as the respondent clicks a navigation button (before
validation and the OnAfterQuestionAsk event) and, if the respondent clicked any navigation
button other than Next or Last, calls the AddQuestionParadata function. This records paradata
for questions that were displayed but were not immediately answered because the respondent
skipped to a different question (for example, used Previous to go back to the previous question).
This ensures that you have a complete record of every time a question was displayed rather
than just every time a question was answered. See the next paragraph for details about what
the function does. The event does nothing if the respondent clicks Next or Last because these
respondents pass through the OnAfterQuestionAsk event.
OnAfterQuestionAsk runs after the respondent has answered a question and after the question
has been validated. In the example, it applies to respondents who click Next or Last to leave the
question. The event runs the AddQuestionParadata function that performs the following tasks:
Gets the connection to the paradata database and checks whether there is already an entry for
this question in this interview — that is, it tests whether the respondent has already answered
this question, and may have gone back and changed the answer. (Whether or not a record
exists affects the SQL query used to update the paradata database.)
Sets up an appropriate command to update the paradata database — INSERT if there is no
existing record, or SELECT and UPDATE if there is already a record.
Builds a paradata record containing the following: the responses that were shown in the
response list (categorical questions and loops only); the navigation button used to leave the
question; the amount of time spent on the question; the number of errors; the project name;
the interview serial number; the question’s full name; and the number of times the question
has been asked.
Executes the command to update the paradata database with the record; that is, either inserts a
new record or updates the existing record for the question.
The event ends by updating the progress bar that the interview displays.
OnInterviewEnd runs at the end of the interview and calls the UpdateInterviewParadata
function. This function:
Gets the connection to the paradata database and checks whether there is already an entry for
this interview in the database — that is, it tests whether this is a new or restarted interview.
(Whether or not a record exists affects the SQL query used to update the paradata database.)
Sets up an appropriate command to update the paradata database — INSERT if there is no
existing record, or UPDATE if there is already a record.
927
Base Professional
Builds a paradata record containing the interview properties to do with paradata.

Executes the command to update the paradata database with the record; that is, either inserts a
new record or updates the existing record for the question.
Objects
In simple terms, objects are the components of a script. They include questions, categories, labels,
and styles; in fact, everything you can find in the Interview Object Model diagram. You can add
objects into an interview so that you can use them during the interview in the same way that you
use the standard objects. A typical example is where you want to use a set of records in an SQL
database as the response list to a question. The records still exist only in the SQL database, but by
creating an object that links to them, you are able to use them as if they were defined in the script.
Other examples of objects you might use are File System Objects or XML DOM objects.
Before you can use objects you must create and initialize them. You do this in the
OnInterviewStart event. First, create the object by typing:
Dim variable
Set variable = CreateObject("ObjectName")
where:
variable is a variable name that can be used to represent the object.
ObjectName is the name of the object you want to create.
Next, initialize the object. How you do this depends on what the object is for, but, for an ADO
recordset, for example, you would load records into the object.
Finally, add the record to the interview objects collection:

IOM.Objects.AddNew("ObjectName", variable)
where:
ObjectName is the name of the object.
variable is the name of the variable that represents the object (the one that you defined
with Dim).
For example:
Dim rsLongBrandList
Set rsLongBrandList = CreateObject("ADODB.RecordSet")
rsLongBrandList.Open("SELECT Brand FROM Brands",_
"Provider=SQLOLEDB.1;Data Source=SVR1")
IOM.Objects.AddNew("rsBrandList", rsLongBrandList)
End Sub
This example creates an ADO recordset for use later in the interview.
To use an object during the interview, refer to it as:
IOM.Objects.ObjectName
Objects exist only for the life of the interview. If the interview times out or is stopped, the
objects “disappear” and must be recreated if the interview is started.
928
Chapter 1
If your object has child objects, you can assign the child objects to variables in a similar way to
the way you assign objects to variables. For example:
Set MyFields = MyObject.Fields
Note, however, that the variables to which the child objects are assigned will not be available after
a restart unless they appear between two .Ask statements.
Temporary variables (that is, those that you define in the routing section using Dim) are not
objects, and cannot be added to the Objects collection. If you want to save or write out the
values of temporary variables, place them in project or interview properties as illustrated in the
EnglishMuseum_WithParadata.mdd example script discussed in Paradata Example Script.
Interactive Voice Response Interviews
Interactive Voice Response (IVR) is a system that allows telephone interviews to be conducted
with little or no interviewer intervention. The IVR system speaks the questions to the respondent
and waits for the respondent to enter the answers using the keypad on his/her telephone. A very
simple analogy is a telephone banking system, where you manage your account by responding to
automated prompts using the telephone handset.
Projects that use a combination of IBM® SPSS® Data Collection Interviewer Server and
IVR have the following advantages:
You can use an autodialer to dial numbers and then have the interviewer follow an Interviewer
Server script to interest the respondent in the survey. Having screened out unsuitable
respondents, you can then use the IVR system to conduct the rest of the interview without
interviewer intervention.
If you have projects that are concerned with very personal subjects or illegal activities such as
drug taking, you may find that you obtain more interviews using IVR because respondents
feel happier communicating with a machine rather than with another person.
An Interviewer Server script that hands off (transfers) interviews to IVR must perform the
following tasks:
Dial the IVR system and pass any relevant data from Interviewer Server to IVR as a DTMF
string. Typically, you will pass at least a respondent identification code to link the Interviewer
Server and IVR data.
Transfer the respondent to the IVR system ready to start the automated portion of the interview.
The simplest way to achieve this is to write a function that does these things and then to call
this function at the appropriate point in the script. You’ll find an example function described in
Writing an IVR Hand-Off Function and there is a complete example script that you can run in
Example Script.
This chapter also contains some notes explaining how Interviewer Server interfaces with IVR and
suggesting ways of setting up a simple IVR questionnaire to test the interface. These notes contain
some references to IVR commands, keywords, and screens where this is necessary to understand
the Interviewer Server side of the interface, but you should not assume that the information
provided about IVR is complete in any way. Always refer to your IVR manuals for full details.
929
Base Professional
Writing an IVR Hand-Off Function
To conduct IVR interviews, your IBM® SPSS® Data Collection Interviewer Server script needs
to perform the following tasks:
Dial the IVR system and pass any relevant data from Interviewer Server to IVR. Typically, you
will pass at least a respondent identification code to link the Interviewer Server and IVR data.
Connect the respondent to the IVR system ready to start the automated portion of the interview.
The simplest way to do this is to write a function. Here’s a simple example that you can adapt to
suit your company’s requirements:
Function TransferToIVR(IOM, QSampDialer, QSampExtension)

Const IVR_NO = "02071234567"
Const SAMPKEY = "ID"
Dim DTMF, IVRCall

' The DTMF to the IVR system consists of the sample record ID
' and a # symbol requesting IVR to start the interview
DTMF = IOM.SampleRecord[SAMPKEY] + "#"
' Dial the IVR system with a 5 second time-out and send the
' DTMF tone when it connects
Set IVRCall = QsampDialer.Groups["ivr_xfer"].DialCall(IVR_NO, , , , 5, , DTMF)
' Wait for the call to connect (2) or terminate (3)

While ((IVRCall.State <> 2) And (IVRCall.State <> 3))
Sleep(100)
End While
If (IVRCall.State = 2) Then
' Connection made. Transfer the call.
QsampExtension.Call.TransferToExtension(IVRCall.Extension.SlaveExtension)
' Wait until the transfer of the original call is complete (and it terminates (3))
While (QsampExtension.Call.State <> 3)
Sleep(20)
End While
TransferToIVR = True
Else
' No connection - something went wrong.
TransferToIVR = False
End If
End Function
Dialing the IVR System
To dial the IVR system, use the IGroup.DialCall method in the QSAMP dialer interface
component. A simplified explanation of this method as it applies to IVR hand-off is as follows
(follow the link for a full technical description):
Set variable = QsampDialer.Groups["GName"].DialCall(IVR_telnum,

, , , [NA_time-out], , DTMF)
where:
variable is the name of the Call object that will store the result of the call.
GName is the name of the extension group that will use IVR. The default is ivr_xfer (group
number 997). (This functionality has to be configured as part of your autodialer set-up.
Contact your local Support representative for details.)
930
Chapter 1
IVR_telnum is the IVR telephone number. You can either enter it directly in the statement,
enclosed in double quotation marks, or you can define it as a constant and use the constant’s
name in the statement. In both cases, type only the digits that are to be dialed; do not include
spaces or other formatting characters.
NA_time-out is the no-answer time-out delay for the call in seconds. The default is 30
seconds. If you do not specify a value, remember to include the terminating comma otherwise
the remaining parameters will be read incorrectly.
DTMF is the DTMF string to send to the IVR system immediately after connecting. For
example, if your IVR system requires a # character in order to jump to the first unanswered
question in the script, you would enter at least this character in the DTMF string. The string
must be enclosed in double quotation marks and can be entered directly into the DialCall
statement or defined as a constant that is then named in the statement. For more information,
see the topic Passing Information to the IVR System on p. 930.
(QSampDialer and QSampExtension are hidden variables in the main interview script and are
passed to the IVR hand-off function. They always exist, but are null if they are not relevant to
the interview, for example, if running in IBM® SPSS® Data Collection Base Professional or
if the interview is not a telephone interview.)
In the example function, the statement that calls the IVR system is:
Set IVRCall = QsampDialer.Groups["ivr_xfer"].DialCall(IVR_NO, , , , 5, , DTMF)
This places a call for the ivr_xfer extension group (this is a group that is created automatically as
soon as your dialer is configured to have at least one IVR seat). It dials the number defined in
the IVR_NO constant and waits a maximum of five seconds for the call to be answered. If the
call is answered, the string defined in the DTMF variable is passed to IVR. Defaults are used for
all other parameters.
When the interviewing program reads the DialCall statement, it places a call to the IVR
system. The Call.State property that records the status of the call changes to 2 if the call connects
or to 3 if the call is terminated for any reason, for example, if the call fails. See ICall.State for
details. Dial.Call does not wait to see whether the call is answered, so you will need to include
some code in your function that waits for the call to return a result before proceeding. The
example script contains the following statements to do this:

Sleep(100)
End While
This waits in periods of 100 milliseconds until a connection or failure occurs.
Passing Information to the IVR System
When the DialCall command obtains a connection, it passes a DTMF string to the IVR system.
This may contain one or more of the following:
The 16 tone generating symbols 0–9, *, #, A–D
A comma for a one-second pause.
A dot (period) for a five-second pause.
931
Base Professional
In interviewing terms, you can put whatever you like in the DTMF string as long as it has some
meaning to IVR. You must enclose the DTMF string in double quotation marks. You can type it
directly into to DialCall command or you can place it in a constant and then name the constant in
the command. Typically, your DTMF string might contain the following:
The serial number that the interviewing program has allocated to this respondent. We
recommend that you always pass at least this information as it ensures that you will be able
to combine the IVR data with the rest of the IBM® SPSS® Data Collection Interviewer
Server data for the interview later on.
Questionnaire data from the Interviewer Server portion of the interview that you want to be
available in the IVR interview or in the IVR database. This might include some screening
information such as age or gender. In theory, you could pass all the Interviewer Server data to
IVR so that the whole interview is stored in the IVR system. However, while this approach
may be satisfactory for short surveys or surveys that are mainly done using IVR, the time
required to transfer the data will usually make it unsuitable for longer surveys.
Special symbols to force a pause in the data. This can be necessary if the set-up of the audio
path is particularly slow, say, on intercontinental connections.
Special symbols such as # to mark the end of one question’s data, or to jump to the next
unanswered question in the script.
Passing an Interview Serial Number or Sample Record Key
To pass the interview serial number to IVR, include:
IOM.Info.Serial
in the DTMF string.

If the sample record key is wholly numeric you can pass that value to IVR so that you have
a link between the IVR data and the sample record. To get the sample record key, place one of
the following in the DTMF string:
IOM.Info.RespondentID
IOM.SampleRecord["KeyFieldName"]
where KeyFieldName is the name of the field that stores the record key.
Note: If you are not using sample management, the respondent ID returned by
IOM.Info.RespondentID is an automatically generated value that may or may not be wholly
numeric.
Passing Answers to IVR
You can pass responses to IBM® SPSS® Data Collection Interviewer Server questions to IVR.
You might do this if you want to save the answers to some of the screening questions in the IVR
data or if you want the IVR questionnaire to follow different paths dependent on respondents’
characteristics. However, do not pass data that is not needed in the IVR interview as this just
wastes time. If you want to analyze the Interviewer Server and IVR data together you can merge
the two datasets once interviewing is over.
932
Chapter 1
Because the respondent answers the IVR questions using the keys on the telephone handset,
most questions in an IVR questionnaire have to be answered using the digits 0 to 9. This restriction
affects which responses you can pass from Interviewer Server, because you have to be able to set
up a suitable question in the IVR questionnaire to receive the Interviewer Server data. It means
that you can pass numeric (integer) and single categorical responses but not real or open-ended
data. To pass multiple-choice categorical data you have to convert it to single-choice format first.
The most important thing about passing data from Interviewer Server to IVR is the number
of digits in a response or response code. IVR is not particularly concerned with whether the
digits are numeric values or response positions in a list. Instead, it is concerned with whether a
question can be answered by a single digit, by a fixed number of digits, or by a variable number of
digits. Examples of Interviewer Server response lists that result in a single digit being passed to
IVR are as follows:
long [1..9]
categorical [1..1] with up to ten responses (responses may be numbered from 0
depending on how you obtain their values).
An Interviewer Server response list that results in a fixed number of digits being passed to IVR is:
long [18..99]
Examples of Interviewer Server response lists that result in a variable number of digits being
passed to IVR are as follows:
long [1..99]
categorical [1..1] with more than ten responses.
When passing data to IVR, you must pass the questions in the order they appear in the IVR
questionnaire as the allocation of responses to questions is positional rather than by question name.
Numeric answers consisting of a fixed number of digits
When the answer to a question is always the same number of digits in Interviewer Server, you
can pass the answer to IVR by placing the question name in the DTMF string. For example, if
the metadata contains:
the DTMF string would be:
DTMF = IOM.Children + "#"
This example (and others in this section) assumes that the IVR system requires a # character to
jump to the first (or next) unanswered question in the script. Your system may require a different
character or no character at all.
Note: To be strictly correct, you should refer to answers as IOM.QuestionName.Response.Value,
but because Response.Value is the default property, IOM.QuestionName is equivalent to
IOM.QuestionName.Response.Value.
The IVR questionnaire must contain a blank Get Value command with the minimum and
maximum number of digits set to the same value (1 in this example).
933
Base Professional
You can pass lists of answers in the same way. For example, if the metadata is:
Age "And how old are you now?" long [18 .. 99];
Children "How many children do you have?" long [0 to 9]
you could pass these two answers to IVR by typing:

DTMF = IOM.Age + IOM.Children + "#"
If Age is defined in IVR as requiring two digits, the first two characters of the DTMF string will
be assigned to the first blank question in the IVR questionnaire and the third character will be
assigned to the second blank question.
Numeric answers with variable numbers of digits
If the number of digits in an answer may vary, you must send a symbol (#, for example) after each
answer to mark the end of that answer. For example, suppose you want to pass the respondent
serial number, and the respondent’s age (18+) to IVR. You would type:
DTMF = IOM.Info.RespondentID + "#" + IOM.Age + "#"
The respondent serial number can be anywhere between one and five digits long so you must send
a terminating symbol such as # to mark the end of the serial number. Age is a numeric two-digit
value, but because it comes at the end of the string it is followed by an end-of-DTMF # symbol.
Categorical answers
You cannot pass categorical values direct to the IVR system, but you can pass responses’ positions
in the response list (also known as their index) and IVR will recognize these as valid answers. If
the question is defined as:
Prefer "Which flavor do you like best?" categorical [1..1]
{
Peach, Pineapple, Apricot, Raspberry
Mango, Vanilla, Banana, Blackcurrant, Rhubarb,
AppleBlackberry "Apple and Blackberry",
ForestFruits "Forest Fruits",
BlackCherry "Black Cherry",
OtherFlavor "Other" other
};
you can pass the answer to IVR by typing:

DTMF = IOM.Prefer.DefinedCategories().Find(IOM.Prefer) + "#"
Response indexing starts at 0 for the first response in the list, and there are more than ten responses
in the list so the answer must be terminated by # in the DTMF string.
The IVR questionnaire must contain a blank Get Value or Get Response command to receive
the categorical data. Use Get Response for ten or fewer responses and Get Value for more than ten
responses.
See Creating an IVR Script to Receive IBM SPSS Data Collection Interviewer Server Data for
further information about the Get Value and Get Response commands.
934
Chapter 1
No answer, don’t know, and refused in numeric response lists
Be careful if a numeric response list contains any of the special responses na, dk, or ref as
these responses insert non-digits in the DTMF string, causing the IVR questionnaire to fail. It is
therefore best to avoid these keywords in numeric responses lists if you can. If you cannot — for
example, you want to allow respondents not to give their age — you should write some additional
code to process the response before it is added to the DTMF string. For example:
Dim agestr
If IOM.Age.Response.Coded = {Refused} Then
agestr = "00"
Else
agestr = IOM.Age
End If
Later, when collecting the SQL data from IVR, you can convert 00 back to Refused.
You could expand this example to cater for other special responses simply by allocating a
different code to each one.
Note: All unanswered questions have a null value even if null is not defined as a valid response
for the question. You must test your scripts thoroughly to ensure that you do not pass these
values to IVR.
Pause symbols
When testing your Interviewer Server script, you may find that you need to wait a few seconds
after dialing the IVR system before passing information to it. You can achieve whatever delay
you need by starting the DTMF string with a comma for a one-second pause or a dot/period
for a five-second pause. You can use any combination of these characters to achieve the delay
you want. The following example shows how to send a one-second pause followed by the
respondent’s serial number, age and gender:
DTMF = "," + IOM.Info.RespondentID + "#" + IOM.Age + _
IOM.Gender.DefinedCategories().Find(Gender) + "#"
Transferring the Respondent to IVR
If the call to IVR results in a connection you can transfer the interview by typing:
Although the transfer is very quick, your script should wait until it receives confirmation of the
transfer just in case this fails. For example, to wait until the call on the interviewer’s extension
terminates (which will happen when the transfer of the call to the IVR system is completes), type:
Sleep(20)
End While
When the transfer is complete, set a return value for your function:
FunctionName = True
Once an interview has been transferred to the IVR system it cannot return to IBM® SPSS® Data
Collection Interviewer Server, so the Interviewer Server script should not contain any more
questions for the respondent. It can, however, contain postprocessing statements that you want
935
Base Professional
to execute after the interview has been handed off, for example, to write accounting or other
details to the data file.
Dealing with Failed Calls
Your function must cater for failed connections. At a minimum, you should set the function’s
return value to False so that the main part of the interview script can display a suitable message
for the interviewer. The example script in Writing an IVR Hand-Off Function contains the
following code:
' Connection made. Transfer the call.
...
Else
' No connection - something went wrong.
End If
You may want to extend this so that the function provides the interviewer with more information
about why the call has failed. Here’s some code that passes back a description of the error that the
dialer returned when it was unable to place the call. The metadata contains an information item
that displays this description for the interviewer:
ErrMsg "I'm sorry, there is a technical problem transfering you to the automated
system. Thank you very much for your time.
(Error: {ErrorDescription})" info;
The Transfer function then contains the following code to deal with failed calls:
...
Else
' The call terminated - something went wrong.
IOM.Questions["ErrMsg"].Label.Inserts["ErrorDescription"] = _
GetOutcomeDescription(IVRCall.Outcome))
End If
GetOutcomeDescription is a user-defined function that looks like this:
Function GetOutcomeDescription(Outcome)
Select Case Outcome
Case 0
GetOutcomeDescription = "No outcome as the call is still in progress or connected."
Case 1
GetOutcomeDescription = "The number dialed was unobtainable. This is because the number is un
...
Case 22
GetOutcomeDescription = "The number is a fax or modem."
End Select
End Function
Refer to CallOutcome in the IBM® SPSS® Data Collection Developer Library for a full list
of the dialer’s call outcome codes.
936
Chapter 1
Creating an IVR Script to Receive IBM SPSS Data Collection Interviewer Server Data
This section provides some basic background details about IVR and offers suggestions for how to
create a simple IVR script to test that data is being passed correctly from your IBM® SPSS® Data
Collection Interviewer Server script to the IVR system. For full details about writing IVR scripts,
refer to your IVR documentation.
The DTMF String
The DTMF string is a string of characters that IBM® SPSS® Data Collection Interviewer Server
passes to the IVR system. It contains an instruction to IVR to start the interview, and it may also
contain Interviewer Server data that you want to use in the IVR interview or store in the IVR
database. Suppose your Interviewer Server metadata script is as follows:
' Questions to pass to IVR

UsedEver "Have you ever used breath fresheners on a regular basis?"
categorical [1..1] {Yes, No};
UseNow "And are you using a breath freshener regularly now?"
WeeklyUsage "How many times a week do/did you use a breath freshener?"
long [1..99];
Type "Which type of breath freshener do you mainly use or have you mainly
used in the past" categorical [1..1]
{
Spray, Mouthwash, Tablets, Gum, Other
};
IVROK "The rest of the interview will be conducted as an automated
survey. A machine will ask the questions, and you can answer by typing
numbers on your telephone keypad.<br/>
Are you willing to be interviewed in this way?"
categorical [1..1]
{Yes, No};
and the DTMF string is defined as:
DTMF = ",," + IVRID + "#" + _

CText(IOM.UsedEver.DefinedCategories().Find(UsedEver)) + _
CText(IOM.UseNow.DefinedCategories().Find(UseNow)) + _
CText(IOM.WeeklyUsage) + "#" + _
CText(IOM.Type.DefinedCategories().Find(Type)) + "#"
If respondent number 681 has used breath freshener regularly in the past (0) but does not currently
use it (1), used to use it 12 times a week, mainly in tablet form, the DTMF string that Interviewer
Server passes to the IVR system is:
,,681#0112#3#
The two commas are the two-second pause and the # at the end of the string tells IVR to proceed
to the first non-blank question. The IVR system speaks the question text for this question and
waits for the respondent to answer using his/her telephone keypad. To test this script you need
to write an IVR questionnaire that contains at least four blank questions to hold the data you
are passing from the Interviewer Server script, plus at least one non-blank question so that the
IVR interview can take place.
937
Base Professional
Look again at how the responses are added to the DTMF string. Notice the following:
Since the string is a text, all the responses in it need to be read as text. The function converts
nontext values into text values.
With categorical responses that can be represented by a single digit, we need to extract a
suitable value from the interview object model. The function returns a list of category
numbers, while the function returns the position in that list of the value representing the
respondent’s answer. Note that position numbering starts at 0 not 1.
IVR Basics
In the IVR system, the characters * and # are special. You should check their exact meanings in
your IVR documentation, but *often means repeat the last question, and # usually means that data
entry is complete for the current question or field.
The IVR system refers to questions as commands. It has a number of commands, most of
which have interview scripting equivalents. The ones you will need in your test questionnaire are
Get Response and Get Value.
Get Response accepts a single answer in the range 0 to 9, where 1 is the lowest value and 0
represents ten. You can use it to receive single-answer categorical data from IBM® SPSS®
Data Collection Interviewer Server, when the response list contains ten or fewer responses, or
to receive numeric responses in the range 0 to 9. Each answer may have logic associated with
it if appropriate. Once an answer has been received for a Get Response question, the system
automatically moves to the next question; there is no need to type # to indicate that data entry is
complete.
The following example from a questionnaire recording script shows that the fifth question in an
IVR script (which is labeled 50 in IVR) is receiving a single answer from Interviewer Server. The
question accepts any answer in the range 0 to 9:
Figure 1-206
IVR screen of a single-response question
938
Chapter 1
The IVR programming screen for this question looks like this:
Figure 1-207
IVR definition of a single-response question
For further information about the contents of questionnaire recording scripts and IVR
programming screens, refer to your IVR documentation.
You can pass a series of questions with single-digit responses from Interviewer Server into the
IVR system as a single string by copying them into a Get Value command (see below).
Get Value accepts a string of digits in the range 0 to 9. Use it when you want to pass integer
responses from the Interviewer Server script or to pass single-choice categorical data when the
response list contains more than ten responses. The number of digits that a Get Value command
accepts is controlled by the # Digits Min and Max fields. If # Digits Max is undefined or you want
to accept answers with fewer than the maximum number of digits, the Terminate With # check box
must be selected so that IVR terminates the data for this command when it receives a # symbol. (If
you do not request a termination symbol, IVR will wait until it times out before moving to the next
question. At this point, it clears the DTMF string so data for any other blank questions will be lost.)
939
Base Professional
The following example from a questionnaire recording script shows that the first question
in an IVR script (which is labeled 10 in IVR) is receiving the respondent serial number from
Interviewer Server. Up to five digits between 0 and 9 will be accepted, but since not all five values
are required the string can be terminated by the # character:
Figure 1-208
IVR recording screen for a multiple digit response
The IVR programming screen for this question looks like this:
Figure 1-209
IVR definition for a multiple-digit response
940
Chapter 1
If IVR receives an invalid answer to a Get Response command, it repeats the question. If it
receives three invalid answers for the same question it terminates the call. With Get Value
commands, if an invalid answer is given or there is too long a delay in responding, IVR repeats the
question up to three times and then hangs up the call.
Practical Suggestions for a Test Script
Here are some practical suggestions for writing a test script and then testing the interface between
IBM® SPSS® Data Collection Interviewer Server and IVR:
Since you’ll be using the SQL Analyzer to view data on the IVR system, it is a good idea to use
variable names in the Interviewer Server script that match the Question Sequence Numbers in
the IVR system. This makes it easy to see which Interviewer Server questions go with which
IVR questions. (The examples in this chapter do not follow this recommendation: they use
standard question names for easy reading since there is no related IVR script to match.)
A blank Get Response command (that is, one that is to receive data from Interviewer Server)
must define the same number of responses as its Interviewer Server counterpart. When IVR
receives data for a Get Response command, it checks that the data is within the range set for
that command. If not, it repeats the question. If this happens during hand-off, IVR will
take the next character in the DTMF string as the response to the repeated question. This
means that you lose synchronization between the DTMF string and the blank questions, and
all subsequent questions are offset by one.
When setting up blank Get Response commands, make sure that you define the responses in
the same order as they appear in Interviewer Server. Responses are set according to their
position in the list, and if the list orders differ responses will be allocated incorrectly.
When passing single categorical answers to an IVR Get Response command, be sure to check
that the Interviewer Server answers are being allocated to the correct IVR responses. If you
are extracting response positions using DefinedCategeories.Find(), remember that Find starts
numbering at position 0 whereas IVR starts numbering at 1. If you see that responses are out
by one position in IVR, add 1 to the answer values before passing them to IVR.
If you are passing an answer from Interviewer Server and all answers to the question will have
the same number of digits (for example, ages in the range 18 to 99), set the minimum and
maximum number of digits in the corresponding Get Value command to the appropriate
number and uncheck Terminate With #. Do not place # after the variable name in the DTMF
string.
If you are passing an answer from Interviewer Server and the number of digits in the response
may vary between respondents, you must select Terminate With # in the corresponding Get
Value command. In the DTMF string the variable must be followed with #. Any errors in
this respect will cause the data to be incorrectly assigned.
Get Value commands wait 30 seconds to receive either the specified maximum number of
digits or the # termination symbol. If neither is forthcoming, the question times out and the
DTMF string is cleared. If there is more data in the string it will be lost. If you follow the
previous two rules time-outs should never occur. However, to make certain, set the Timeout
field to a large value, say, 300 seconds.
941
Base Professional
Do not send data to IVR unless you need to use it in the IVR questionnaire script. If you don’t
have to send data, send just the respondent serial number or the sample record key (if it is
numeric). If you have to send responses because you want them to appear in IVR’s SQL
database, but you do not need to use them in the interview, pass the data into a Get Value
command as a single string, terminated by #. You can then separate this data afterwards
when you have retrieved it from the database.
To test the IVR questionnaire, print the Questionnaire Recording Script and mark answers to
the questions on the script as they would be answered in Interviewer Server. Then dial the
IVR system manually and enter these answers using the telephone keypad to test the IVR
script before you try passing any data from Interviewer Server.
Once you are satisfied that the IVR system is receiving data correctly, you can test it with
your Interviewer Server script. Mark the answers you will be giving on the Questionnaire
Recording Script and then enter these answers in your browser. Your Interviewer Server script
should write the responses you will be passing to the IVR system in the case data file so that
you can view it or display the answers on the interviewer’s screen.
Example Script
The following script brings together all the information provided in the other topics in this
chapter, and is ideal for use as a test script. It is installed as part of the
IBM® SPSS® Data Collection Developer Library and can be found in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Documentation\ivr.mdd.
The metadata section defines some initial screening questions to select respondents for the IVR
interview, and an error message for the interviewer in case the call or transfer to IVR fails.
' Questions to pass to IVR

UsedEver "Have you ever used breath fresheners on a regular basis?"
UseNow "And are you using a breath freshener regularly now?"
WeeklyUsage "How many times a week do/did you use a breath freshener?"
long [1..99];
Type "Which type of breath freshener do you mainly use or have you mainly
used in the past" categorical [1..1]
{
Spray, Mouthwash, Tablets, Gum, Other
};
Ivrchk "The rest of the interview will be conducted as an automated
survey. A machine will ask the questions, and you can answer by typing
numbers on your telephone keypad.<br/>
Are you willing to be interviewed in this way?"
categorical [1..1]
{Yes, No};
Handoff "Thank you for your help. You are now being transferred to
the automated system." info;
ErrMsg "There is a technical problem and the interview cannot continue.
Thank you for your help.
INTERVIEWER: Failure due to : {ErrorDescription}" info;
NotSuitable "This survey requires people who have used or who now
use mouthwash so you are not suitable for this survey.
Thank you for your help." info;
Thanks "Thank you for your help." info;
The routing section asks the screening questions, calls the IVR system and, if the call is successful
transfers the respondent to the IVR system ready to continue the interview.
942
Chapter 1
UsedEver.Ask()
UseNow.Ask()
If UsedEver = {No} And UseNow = {No} Then
NotSuitable.Show()
IOM.Terminate(Signals.sigCompleted, , TerminateStatus.tsCompleted)
End If
WeeklyUsage.Ask()
Type.Ask()
Ivrchk.Ask()
If Ivrchk = {Yes} Then
Handoff.Show()
If TransferToIVR(IOM, QSampDialer, QSampExtension) Then
' Transfer succeeded so terminate the interview and flag as
' Complete.
IOM.Terminate(Signals.sigCompleted, , TerminateStatus.tsCompleted)
Else
' Unable to transfer the call so terminate interview and
' flag as Terminated
ErrMsg.Show()
End If
Else
Thanks.Show()
End If
Function TransferToIVR(IOM, QSampDialer, QSampExtension)

' Transfer the call to the IVR system
Const IVR_NO = "02071234567"
Dim DTMF, IVRCall
On Error Goto DialerError
' The DTMF to the IVR system consists of the respondent serial
' number and the answers to the questions in the metadata section.
DTMF = CText(IOM.Info.RespondentID) + "#" + _
PrepareQ(IOM.Questions["UsedEver"]) + _
PrepareQ(IOM.Questions["UseNow"]) + _
PrepareQ(IOM.Questions["WeeklyUsage"]) + "#" + _
PrepareQ(IOM.Questions["Type"]) + "#"
' Dial the IVR system with a 5 second time-out and send the
' DTMF tone when it connects
Set IVRCall = _
QsampDialer.Groups["ivr_xfer"].DialCall(IVR_NO, , , , 5, , , DTMF)
' Wait until the call is connected (2) or terminates (3)

Sleep(100)
End While
' The call connected to the IVR system. Transfer the call.
Else
' The call terminated - something went wrong.
Err.Raise(-1, "", GetOutcomeDescription(IVRCall.Outcome))
End If
' Wait until the transfer of the original call is complete

' (and it terminates (3))
Sleep(20)
End While
Exit
DialerError:
IOM.Questions["ErrMsg"].Label.Inserts["ErrorDescription"] = Err.Description
End Function
Function PrepareQ(Question)
If Question.QuestionDataType = DataTypeConstants.mtCategorical Then
PrepareQ = CText(Question.DefinedCategories().Find(Question))
Else
PrepareQ = CText(Question)
End If
End Function
Function GetOutcomeDescription(Outcome)
Select Case Outcome
Case 0
GetOutcomeDescription = "No outcome as the call is still in progress or connected."
943
Base Professional
Keywords for Data Analysis
If the data for your project will be analyzed using IBM® SPSS® Data Collection products such as
IBM® SPSS® Data Collection Survey Tabulation or IBM SPSS Data Collection Survey Reporter,
you can include keywords in the script that will take effect only in those products. For example, if
you have a five-point rating scale response list, you may want to assign a factor to each response
so that a mean rating score can be calculated when the data is tabulated. Alternatively, you may
want to create some additional elements in a numeric response list that will appear in tables but
not in the interview. Statistics such as means are typical tabulation-only elements.
This chapter introduces the following metadata keywords:
axis Specifies element definitions for analysis elements
elementtype Specifies element types for analysis elements
expression Defines conditions for inclusion in an analysis
element
factor Specifies factors for statistics based on categorical
data
Topics in this chapter cover the following aspects of interview scripting for analysis:
Methods of analysis scripting and the advantages and disadvantages of each.
Base elements
Statistical elements in axis blocks
Subheadings in axis blocks
Subtotals and totals in axis blocks
Analysis-only elements.
Banding numeric, text, and date responses
Varying text between interviewing and analysis
Combining categorical responses in analyses
Additional variables for analysis (derived variables)
Incrementing counts by the value of a numeric variable (multipliers)
Analysis options in shared lists.
Defining Analysis Requirements
Each question in an interviewing script becomes a variable in a tabulation application. If you are
happy with the default variables that you get from simply opening an interviewing project with an
analysis application then you need not make any additions to your standard interviewing script.
The default variables produce the following output in analyses:
Question type Output in tables
Categorical A base and then one element (row or column) for
each response in the response list.
944
Chapter 1
Question type Output in tables

Numeric (long and double) IBM® SPSS® Data Collection Survey Tabulation
and IBM SPSS Data Collection Survey Reporter
generate a base, mean and standard deviation,
as well as elements showing the minimum and
maximum values for the variable. If you are writing
tables (TOM) scripts you will need to specify these
elements yourself.
Boolean A base and an element for those with a True/Yes
response.
Text Cannot be tabulated in its raw form, but can be
displayed in profiles.
Date Cannot be tabulated in its raw form, but can be
displayed in profiles.
Changes that you may want to make for analyses include:

Different response texts for interviewing and analysis.
Grouping numeric data into categorical ranges (bands) so that the data can be used more
easily in tables.
Grouping text or date/time data so that it can be tabulated.
Assigning factors to categorical responses such as rating scales so that an average rating
can be obtained.
Calculating totals and subtotals for numeric data.
Creating additional elements that appear only in analyses; for example, a “top two” element
that counts answers in the top two categories of a rating scale.
Redefining the base for percentages and statistics so that it includes everyone who answered
the question rather than everyone who was asked it.
Creating new variables by combining data for two or more questions; for example, a combined
gender and age question built from the responses to the individual gender and age questions.
Creating new variables that add up numeric answers given by respondents to a particular
question rather than by counting the number of respondents giving those answers (for
example, the number of children that people in various age groups have rather than the
number of people in each age group, or the number of visits made to various shops rather than
the number of people visiting each shop).
There are two ways of specifying your analysis requirements in an interviewing script:
Define an axis block. This is a section that appears at the end of the response list and defines all the
elements that you want to see in tables. The advantages of the axis block are that you can use it in
any type of question, and it keeps all analysis specifications together, making it immediately clear
which statements apply to interviewing and which to analysis.
The syntax for an axis block is:
QName 'Text' Type [Responses]

axis(
"{
element definitions
}"
)
945
Base Professional
If you use IBM® SPSS® Data Collection Base Professional for building and testing scripts, note
that it does not check the syntax of anything inside an axis block, so any syntax or other errors
will not become apparent until you use the question in analyses.
Use Analysis elements. You can place analysis-specific elements amongst interview responses in
categorical response lists and the interviewing program will ignore them. Analysis-only elements
contain an elementtype parameter that defines how the element will be used in tables. The
advantage of this approach is that you never have to define a response more than once; however,
you usually need to define an expression for each element that specifies who should be included in
the element or how its counts should be created.
Base Professional checks this type of element definition when you save the script, so if there
are syntax errors they will be picked up before you run the script.
Usually the two methods are interchangeable, but sometimes they are not.
Axis Block or Analysis Elements?
Axis blocks and analysis elements are two ways of defining analysis requirements in an interview
script. Sometimes the method you use is a matter of personal choice or company standards.
At other times you may find that only one method produces exactly the output you require.
The following table summarizes the differences between the two methods and the advantages
and disadvantages of each.
Analysis Elements Axis Blocks
Syntax checked when the script is saved. Not checked until the block is used in an analysis
application.
Text can be translated in the same way as other Text cannot be translated.
metadata texts.
Syntax can be long and complicated. Simple syntax.
Some analysis requirements not catered for. All analysis requirements catered for.
Here are a couple of examples that illustrate some of these differences.

The first example sets up a mean and standard deviation for a set of categorical responses. The
first version uses an axis block so you know that the top part of the definition is for interviewing
only, and the axis block is for analysis only. Notice the line containing the two dots near the start
of the axis block. This is a shorthand way of referring to all the categories in the main response
list that saves you having to retype or copy and paste the response texts. However, if you want
to put the responses in a different order in the tables then you can define them in full in the axis
block. Just be sure to keep the category names the same in both sections otherwise the analysis
program will not be able to match up the analysis elements with the correct data.
946
Chapter 1
Rating "What is your overall rating for the hotel?" categorical [1..1]
{
Excellent factor(5),
VGood "Very good" factor(4),
Satisfactory factor(3),
Poor factor(2),
VPoor "Very poor" factor(1)
}
axis (
"{
..,
RatingMean 'Mean rating' mean(),
RatingSD 'Std. dev' stddev()
}"
);
Now here’s the same question written using elements with Analysis keywords.
{
Poor factor(2),
VPoor "Very poor" factor(1),
RateMean "Mean rating"
[CalculationType=Mean, HasNoData=True, ExcludedFromSummaries=True]
elementtype(AnalysisMean),
RateSD "Std. dev"
[CalculationType=StdDev, HasNoData=True, ExcludedFromSummaries=True]
elementtype(AnalysisStdDev)
};
In this scenario, there’s not much to choose between the two methods, as they both produce the
same output, although there is less typing in the axis block version and you may find it easier to
follow. This is not always the case. Here’s an example that illustrates the opposite view. It defines
a question that respondents can skip. The question has a base element that reports the number of
people who answered the question, and the requirement is that the hidden “No answer” response
does not appear in analyses.
' The routing section contains Gender.MustAnswer=False.
' Respondents who click Next without answering are automatically coded as
' GenderNA. This response is not displayed during interviews.
Gender "Are you ...?" categorical[1..1]
{
Male, Female,
GenderNA "No answer" na
}
axis(
"{
..,
GenderNA [IncludeInBase=False, IsHidden=True]
}"
);
In this version, the axis block uses the “..” notation to pick up the responses defined in the main
part of the question. The “No answer” category is defined with additional properties that exclude
it from the automatic base element and hide it in analyses. Any tables that use Gender as the rows
or columns will show Male and Female only. Here’s the Analysis keyword version.
947
Base Professional

' Respondents who click Next without answering are automatically coded
' as GenderNA. This response is not displayed during interviews.
{
GenderBase "Base (all answering)"
elementtype(AnalysisBase) expression("Gender <> {GenderNA}"),
Male, Female,
};
This time we need to define the base ourselves as there is no way to exclude “No answer” from
the automatic base. The base element contains an expression that excludes anyone who did not
answer the question. However, excluding respondents from the base does not exclude them
from the analyses. All responses that appear in the response list automatically become part of
the analyses, so although “No answer” is excluded from the base it will still appear in tables.
This means that the definition does not suit the analysis requirements. (A way round this is to
hide the unwanted element using facilities in the analysis program, but this can be a nuisance if
you have to edit a lot of variables.)
A similar thing sometimes happens when you want to vary response texts between interviewing
and analysis, perhaps using longer texts in interviewing so that respondents are clear about what
each response means. If you use an axis block you can define whatever text variations you want,
whereas with Analysis keywords you have to use the same text in both types of output or define
different texts in the Analysis context. For more information, see the topic Different Response
Texts for Interviews and Analyses on p. 962.
Remember, also, that elements defined using Analysis keywords become part of the project’s
metadata and are checked when you saved the script in IBM® SPSS® Data Collection Base
Professional and when you activate the script. They can also be translated. Anything in an axis
block is not checked until you use the question in analyses and cannot be translated.
You can use Analysis elements and an axis block in the same question. If you want to refer to
an Analysis element in the axis block, just use its name the same as you do for ordinary responses.
Special Characters in Axis Blocks
Axis blocks are an easy way of specifying the elements you want to see in tables for a particular
question. In categorical questions, the axis block lists or references responses that appear in the
main response list as well as defining additional elements such as statistics and totals that apply
only when the question is used in tables.
The specifications you write in an axis block look similar to interview scripting statements,
but they are in fact statements in the table scripting language. This means that you can take
advantage of some other features of the table scripting language when writing axis blocks. These
features provide shortcuts for referring to responses in the main list, as well as allowing to omit
responses that apply only to interviews.
Type To
.. Refer to all responses in the main response list.
Name.. Refer to a range of responses starting with the
response named Name and continuing to the end
of the response list.
..Name Refer to a range of responses starting at the top of
the list and ending at the named response.
948
Chapter 1
Type To
Name1..Name2 Refer to all responses between Name1 and Name2
inclusive.
^Name Omit the named response from analyses.
In the following example, the “Not answered” response is omitted from analyses. The first line of
the axis block refers to all responses from the start of the list up to and including Widowed. The
second line indicates that “Not answered” should be ignored:
Mstat "Are you ..." categorical [1..1]
{
Single, Married,
Cohabit "Living with partner",
Divorced, Widowed,
MstatNA "Not answered" na
}
axis (
"{
..,
^MstatNA
}"
);
Base Elements
Base elements count the number of people who were asked a question. If the questionnaire routing
means that some questions do not apply to some respondents, the base for those questions will
be lower than for questions that everyone is asked. The IBM® SPSS® Data Collection analysis
applications automatically create base elements for all questions that do not have them, so you do
not have to define base elements unless you want the base to be something other than “all asked”.
You can manually exclude certain respondents from the base. For example, when a question
can be left unanswered you may want the base to be “all answering” rather than “all asked”. In
this case, you can flag the No Answer response so that it will not be included in the base.
You can also create your own base elements. This is most often necessary when you create a
new analysis variable based on data from an interview question. If necessary, you can hide these
elements if they are required only because the analysis variable contains statistics.
Using an axis block
To create a base element, place the following statement in the axis block for the question:
Name ['Text'] base('Expression')
where:
Name is the name for the base element.
Text is the text you want to display for the base in analyses. The default is Base.
Expression is an expression defining who should be included in the base.
Here is an example. The routing section (not shown) sets Gender.MustAnswer to False so that
respondents can click Next without answering. When this happens, the na response is written to
the data file. In analyses, we want to see only those respondents who gave their gender. We do not
want to see those who chose not to answer.
949
Base Professional

' Respondents who click Next without answering are automatically coded as
' GenderNA. This response is not displayed during interviews.
Gender "Are you ...?" categorical[1..1]
{
Male, Female,
}
axis(
"{
..,
}"
);
Notice the way the condition for inclusion in the base element is defined. The * means “Contains
Any”, so the base will count anyone who chose either Male or Female at the Gender question. It
will exclude everyone else.
Using an Analysis element
You can also create base elements in the main part of a categorical response list by writing
a statement that includes elementtype(AnalysisBase). To do this, place the following
statement in the response list at the point you want the base to appear in analyses:
Name ["Text"] elementtype(AnalysisBase) expression("Expr")
where:
Name is the element’s name.
Text is the text you want to display for the base in analyses (that is, the row or column
heading).
Expr is an expression that defines who to include in the base.
The following example shows an analysis-only variable that is derived from a numeric question
that records the number of children in a household. Only people who said they have children at
home are asked how many they have.
NumChildBanded "Number of school-age children in household"

categorical [1..1]
{
Base elementtype(AnalysisBase) expression("NumChild IS NOT NULL"),
One "1 child" expression("NumChild = 1"),
TwoThree "2 or 3 children" expression("NumChild = 2 Or NumChild = 3"),
FourMore "4 or more children" expression("NumChild >= 4")
};
Excluding elements from the base
To exclude elements from a base element set its IncludeInBase property to False in the question’s
axis block. You may want to do this if you are using the default base since, if you create the base
yourself, you can specify who to include in it. Define the excluded element as:
Name ['Text'] [IncludeInBase = False]

950
Chapter 1
For example:
{
Male, Female,
}
axis (
"{
Male, Female,
GenderNA [IncludeInBase=False]
}"
);
Excluding an element from the base does not hide that element in the tables. To do this, set the
element’s IsHidden property to True:
See Hiding Interview-Only Elements for further information about hiding elements in tables.
Statistical Elements
If you tabulate a standard numeric question in IBM® SPSS® Data Collection Survey Tabulation
or IBM SPSS Data Collection Survey Reporter, the application displays base, mean and standard
deviation elements, as well as elements showing the minimum and maximum values of responses.
The base counts the number of people eligible to answer the question, and the other values come
from or are calculated using the raw data held in the case data. If you want to see a more detailed
breakdown of the answers, you can expand the question definition to include analysis elements
that group the answers into ranges. When you do this, Survey Tabulation no longer creates the
statistical elements automatically so you must specify them manually in the question definition.
With categorical questions, the data contains codes that represent the answers chosen. These
codes cannot be used in statistical calculations so you must specify a set of numeric values
(called factors) that can be used in the statistical calculations instead. For example, to find the
mean rating in a five-point rating scale you might assign factors ranging from 5 for Excellent
to 1 for Very poor. The mean would then be calculated using the factors that represent each
respondent’s rating. Thus, if one respondent rates the product as very good (4) and another rates
it as satisfactory (3), the mean rating is 3.5.
The interview scripting language can request the following commonly used statistics:
Mean (the sum of values divided by the number of cases)
Standard deviation
Standard error
Sample variance
You can define statistics by placing statements in an axis block or by adding Analysis elements
to the main body of the response list. Using an axis block is the most straightforward method
regardless of whether you are using raw data or factors in the calculations. It also allows you to
request other statistics such as the median or mode (refer to the tables in for details).
The general rules for defining statistics are as follows:
In an axis block, name the statistic you want and, if using raw data in a derived variable, the
name of the question whose raw data is to be used in the calculations.
951
Base Professional
When using Analysis elements with factors, add Analysis elements for the statistics you want.
When using Analysis elements with raw data, add Analysis elements for the statistics you
want and define hidden elements for the intermediate values required for those statistics (for
example, sum-of-x (values) and sum-of-n (cases) for a mean).
Statistics Using an Axis Block
When a question or derived variable requires statistics, the easiest way to set them up in your
interviewing script is to use an axis block. There is very little difference between the syntax for
statistics based on raw data and statistics based on factors, and there is never any need to define
additional elements that store intermediate values used in the statistical calculations.
Defining factors
If the question or derived variable is categorical, you will need to define factors that can be
used in the calculations. To do this, append the following to the response definitions in the main
part of the response list, not in the axis block.
factor(n)
where n is a positive or negative integer or real number. Responses with no factor are ignored
when statistics are calculated.
Creating statistical elements in the axis block

To create the statistical elements, place the following statement in the axis block for the
question:
[Name] ['Text'] Statistic([NumQ])
where:
Name is a unique name for the element. If you do not specify a name, the name of the
statistic is used.
Text is the text you want to use for this element in analyses (that is, the row or column
heading). The default is the statistic’s name.
Statistic identifies the statistic you want to create — usually one of mean, stddev,
stderr, or sampvar.
NumQ is the name of the numeric question whose raw data is to be used in the calculations.
This is not required when factors are used.
Here are several variations of an age question. The first one defines the statistics as part of the
question that respondents will be asked.
952
Chapter 1

axis(
"{
A24 '18 to 24' expression('Age <= 24'),
A34 '25 to 34' expression('Age >= 25 And Age <= 34'),
A65 '65 plus' expression('age >= 65'),
AgeMean 'Mean' mean(Age),
AgeStddev 'Std.dev' stddev(Age)
}"
);
This is a standard numeric question that has been extended to include categorical elements for
analysis only. The question is displayed in the usual way during interviews, and respondents type
their exact age into a numeric input box. When you tabulate the question, each person’s age is
read from the case data and the appropriate element in the axis block is incremented by 1 for each
person in that age group. Because the question is numeric, the mean and standard deviation
are calculated using the raw age data, giving you the true average age of your respondents and
the standard deviation from that age.
The next example shows a categorical derived variable base on Age. (See Categorical Bands
for Numeric, Text, and Date Responses for further information about this type of derived variable.)
AgeGroup "Respondent's age" categorical [1..1]
{
AG24 "18 to 24" expression("Age <= 24"),
AG34 "25 to 34" expression("Age >= 25 And Age <= 34"),
AG65 "65 plus" expression("Age >= 65")
}
axis(
"{
..,
AGMean 'Mean' mean(Age),
AGStddev 'Std.dev' stddev(Age)
}"
);
The age ranges are defined in much the same way as they were in the previous example, using
expressions to determine who is counted in each group. Points to notice about this example are:
The “..” at the start of the axis block picks up all the elements defined in the main part of the
question.
Because the data for the variable come from a different question, the statistical elements name
Age as being the question whose data is to be used in the calculations.
Finally, here’s an example that uses factors rather than raw data.
953
Base Professional
EldestChild "How old is your eldest school-age child?" categorical [1..1]

{
EC3to4 "3 to 4 years" factor(3.5),
EC5to7 "5 to 7 years" factor(6),
EC8to11 "8 to 11 years" factor(9.5),
EC12to16 "12 to 16 years" factor(14),
EC17to18 "17 to 18 years" factor(17.5)
}
axis(
"{
..,
ECMean 'Mean' mean(),
ECStddev 'Std. dev' stddev()
}"
);
The factors are defined as part of the responses so that they will be saved in the metadata. When
the question is displayed, the respondent may choose one answer from the list. When the question
is tabulated, the age categories are incremented by one for each respondent, and the statistics are
calculated using the factors defined for each category. Anyone whose eldest child is aged three or
four will count as 3.5 in the mean calculation, whereas anyone whose eldest child is between five
and seven years old will count as 6 in the calculation. This generates an approximation of the true
mean age based on the factors rather than on children’s exact ages.
Statistics Using Analysis Elements
Defining factors
If the question or derived variable is categorical, you will need to define factors that can be
used in the calculations. To do this, append the following to the response definitions in the main
part of the response list, not in the axis block.
factor(n)
where n is a positive or negative integer or real number. Responses with no factor are ignored
when statistics are calculated.
Creating statistics using Analysis elements and factors
Place statements of the following form in the response list at the points you want the statistics to
appear in tables:
Name ["Text"] [Properties] elementtype(Type)
where:
Name is the element’s unique name.
Text is the text you want to use for this element in analyses (that is, the row or column
heading).
Properties is a list of analysis properties that are required for the element you are creating.
The property list must be enclosed in square brackets.
Type is the type of element you want to create. This parameter must follow the property list.
954
Chapter 1
The table shows the element type keywords and the properties that must be defined for each
element type. The property names are fairly self explanatory: CalculationType defines the
type of calculation to be made; HasNoData shows whether there is raw data associated with this
element; and ExcludedFromSummaries shows whether the element will be counted in summary
elements such as subtotals, totals, and statistics. CalculationScope determines which elements
will be included in the mean; the default is to include only those elements that come before the
mean element in the axis specification, but you can choose to include all elements if you wish.
Element Type Description Required Properties Optional Properties
AnalysisMean The mean value of CalculationType=Mean CalculationScope=AllElements
factors assigned to HasNoData=True
categorical responses. ExcludedFromSummaries=True
AnalysisSample- The sample variance CalculationType=SampleVar
CalculationScope=AllElements
Variance of factors assigned to HasNoData=True
AnalysisStdDev The standard deviation CalculationType=StdDev CalculationScope=AllElements
of factors assigned to HasNoData=True
AnalysisStdErr The standard error of CalculationType=StdErr CalculationScope=AllElements
factors assigned to HasNoData=True
For example:
{
Poor factor(2),
VPoor "Very poor" factor(1),
RateMean "Mean rating"
RateSD "Std. dev"
[CalculationType=StdDev, HasNoData=True, ExcludedFromSummaries=True]
elementtype(AnalysisStdDev)
};
Creating statistics using Analysis elements and raw data
When you have a derived variable who responses are based on numeric data you can use the raw
data to produce accurate statistics. You specify these elements in the same way that you do for
statistics based on factors, but because the data used in the calculation of the statistics is coming
from a different question or variable you must also define some hidden elements that contain
intermediate data that is required by your statistics.
For example, means are calculated by taking the sum of the numeric values (known as the
sum-of-x) and dividing it by the number of cases or respondents (known as the sum-of-n), while
standard deviations require the same information as well as the sum of the squared numeric
values (sum-of-x-squared). These are all additional elements that you must define as part of
the question. You do this by placing one of the following statements in the response list for
each additional element required. In the case of a mean you would type two statements, and for
a standard deviation you would type three. The statement has been written over three lines and
shows the points at which line breaks are allowed.
955
Base Professional
Name
[CalculationType=Type, Hidden=True, ExcludedFromSummaries=True, DataElement=""]
elementType(AnalysisSummaryData) [multiplier(use QName)]
where:
Name is the element’s name. This must be one of SumN, SumX, or SumXSquared.
Type is the type of calculation to be stored in this element. Refer to the table for details.
QName is the name of the numeric variable whose raw data is to be used in the calculation.
The multiplier parameter is not required for means.
The following table shows which calculation types are required for each of the common statistics:
Statistic Additional elements required, and in what order
Mean SumX, SumN
Standard deviation SumXSquared, SumX, SumN
Standard error SumXSquared, SumX, SumN
Sample variance SumXSquared, SumX, SumN, SumUnweightedN
Rules for defining the additional elements are as follows:

You must define these elements in the order they are listed in the table.
Do not insert other elements between SumXSquared, SumX, and SumN.
SumUnweightedN must come immediately before the Standard error or Sample variance
element it belongs to.
If a question has multiple statistics and some of the additional elements are common to several
of those elements, you may define the additional elements once, subject to the rules, and
they will be applied to all statistics.
Here’s a derived variable that generates age ranges based on the exact ages stored in the Age
question. See Categorical Ranges for Numeric, Text, and Date Responses for further information
about these types of derived variables.
HowOld "Respondent's age" categorical [1..1]

{
HowOld24 "18 to 24" expression("Age <= 24"),
HowOld34 "25 to 34" expression("Age >= 24 And Age <= 34"),
HowOld65 "65 plus" expression("age >= 65"),
SumXSquared [CalculationType="SumXSquared", Hidden=True, DataElement="",
ExcludedFromSummaries=True]
elementType(AnalysisSummaryData) multiplier(use Age),
SumX [CalculationType="SumX", Hidden=True, DataElement="",
elementType(AnalysisSummaryData) multiplier(use Age),
SumN [CalculationType="SumN", Hidden=True, DataElement="",
elementType(AnalysisSummaryData),
HowOldMean "Mean"
HowOldSD "Std. dev"
[CalculationType=Stddev, HasNoData=True, ExcludedFromSummaries=True]
elementtype(AnalysisStddev)
};
956
Chapter 1
Analysis Subheading Elements
Subheadings help break up long lists of responses by grouping similar responses under a title.
For instance, a long list of holiday destinations immediately becomes easier to use if it is broken
down by country. Sometimes, the same response may appear more than once in a list. This may
happen in product tests, for example, where the product is available in a number of forms such as
biological and non-biological washing powder, or regular, diet, and caffeine-free soft drinks. In
this case, subheadings are imperative in interviews to help respondents select the right product.
Similar requirements apply to analyses. Subheadings break the tables up making them easier
to follow.
To create subheadings in analyses, place the following statement in the question’s axis block:
Name 'Text' text()
where:
Text is the subheading text you want to display in analyses.
For example:
Countries "Which countries did you visit on your last
holiday abroad?" categorical [1..]
{
Europe
{
Austria, England, France, Germany, Ireland, Italy
},
Asia
{
China, India, Japan, Malaysia, Singapore
}
}
axis (
"{
Europe 'Europe' text(),
Austria..Italy,
Asia 'Asia' text(),
China..Singapore
}"
);
957
Base Professional
If responses in a list are namespaced because the same name appears more than once, the axis
block must give the full name for each response, as shown in the next example:
FoodProgs "Which of these food programs have you watched during the
last three months?" categorical [1..]
{
{
} namespace,
{
} namespace,
{
} namespace,
None "None of these" style(indent=0) exclusive
}
axis(
"{
TVSat 'TV/Satellite' text(),
TVSat.HellsKitchen,
TVSat.GoodFoodLive,
TVSat.CookingForOne,
VideoDVD 'Video/DVD' text(),
VideoDVD.HellsKitchen,
VideoDVD.GoodFoodLive,
VideoDVD.CookingForOne,
Internet 'Internet' text(),
Internet.HellsKitchen,
Internet.GoodFoodLive,
Internet.CookingForOne,
None
}"
);
The indentation of elements under their subheadings in the axis block is for ease of reading only.
It has no effect on the way the texts appear in analyses.
Totals and Subtotals
Totals and subtotals are useful in long response lists where you want to know the sum of the
counts in the preceding elements. For example, in a list of holiday destinations you could create
subtotals for each country or region and then a total for all countries or regions.
Subtotals count the number of answers between the subtotal element and the previous base,
subtotal, or total element, whichever is the most recent. Totals count the number of answers
between the total element and the previous base or total element, whichever is the most recent. If
there is no previous subtotal, total, or base element, subtotals and totals start counting from the
start of the response list. Both elements ignore statistical and other totalling elements, as well as
any other elements whose ExcludedFromSummaries property is True.
If a response list is multiple choice and some respondents choose more than one answer, the
subtotal or total shows the number of answers in the preceding elements, not the number of
respondents who gave those answers. If you want to count respondents rather than answers, create
a combined or net element as described in Combining Interview Responses in Analyses.
958
Chapter 1
To create subtotal or total elements, type the following in the question’s axis block:
Name 'Text' subtotal()
Name 'Text' total()
where:
Text is the text you want to display in analyses for these elements.
For example:
Destination "Which countries did you visit on your last
holiday abroad?" categorical [1..]
{
Europe
{
Austria, England, France, Germany, Ireland, Italy
},
Asia
{
China, India, Japan, Malaysia, Singapore
}
}
axis (
"{
Europe 'Europe' text(),
Austria..Italy,
AllEurope 'Subtotal (Europe)' subtotal(),
Asia 'Asia' text(),
China..Singapore,
AllAsia 'Subtotal (Asia)' subtotal(),
Total 'Total visits' total()
}"
);
Analysis-Only Elements
If there are some elements that you want in analyses but not in interviews, do one of the following.
959
Base Professional
Create an axis block for the question and define the analysis-only elements in that block but
not in the main body of the response list. For example:
HasPets "Do you have any pets?" categorical [1..1]

{Yes, No};
Pets "What pets do you have?" categorical [1..]
{
Rabbit, Cat, Dog, Fish, Bird, Other
}
axis (
"{
..Other,
NoPets 'Does not have pets' expression('HasPets={No}')
}"
);
Define the element in the main body of the response list and add
elementtype(AnalysisCategory) to its definition. For example:
ChildAtHome "Do you have children living at home?" categorical [1..1]

{Yes, No};
ChildAge "What ages are those children?" categorical [1..]
{
ChildU5 "Under 5 years",
Child5To11 "Aged 5 to 11",
ChildO18 "Older than 18 years",
NoChildren "No children at home" elementtype(AnalysisCategory)
expression("ChildAtHome={No}")
};
As shown in both examples, you’ll usually need to define some sort of expression that specifies
who to include in the element. See Combining Categorical Responses in Analyses and Analysis
Options in Shared Lists for examples.
Hiding Interview-Only Elements
From time to time there will be responses that you need to include in a script for interviewing
purposes that you do not want in analyses. The hidden “No answer” response that is required
when you set MustAnswer to False so that respondents can skip questions is a typical candidate
for suppression in analyses. To suppress interviewing elements you must create an axis block
in the question that specifies the elements you want in analyses. In the axis block, there are
three methods of hiding elements:
List the interviewing elements you want to include by name, and exclude the ones you do
not want to see.
Use the “..” notation to include blocks of interview elements. List the unwanted elements
separately, preceding their names with ^.
Include the unwanted elements in the axis block but set their IsHidden property to True.
Here are examples of these methods. All three examples have MustAnswer set to False so that
respondents can skip the question, and all three examples produce the same output in analyses.
The first example simply omits “Not answered” from the axis block.
960
Chapter 1

{
Single, Married,
Divorced, Widowed,
}
axis (
"{
..Widowed
}"
);
The second example uses the ^ notation to hide “Not answered”. You can use this method to hide
elements that are in the middle of the list too. Just follow the ^ element with another list of
elements you want to include.
{
Single, Married,
Divorced, Widowed,
}
axis (
"{
..,
^MstatNA
}"
);
The third example sets the element’s IsHidden property to True. This is a good method to use
if you also want to exclude the element from the base count.
{
Single, Married,
Divorced, Widowed,
}
axis (
"{
..,
MstatNA [IsHidden=True]
}"
);
Categorical Bands for Numeric, Text, and Date Responses

Numeric, text, and date questions store the exact value that each respondent gives as his/her
answer. Although this makes for very accurate data, it is not always so useful in analyses where
you may want to use the question as the rows or columns of a table.
When you use a numeric variable as the rows or columns of a table, the analysis application
displays five elements: base, mean, minimum, maximum, and standard deviation, but what may be
more useful is to group the numeric values into ranges or bands so that the data can be tabulated in
the same way as categorical data. For example, in an age question you might have age ranges
18 to 24, 25 to 34, 35 to 44, and so on. The situation is worse for text and date questions which
cannot be tabulated at all in their raw form.
The easiest way to satisfy the requirements of accurate data and easy analysis is to create all
numeric, text, and date questions with an axis block defining the elements you want to see in
analyses. Here’s the age example we talked about.
961
Base Professional

axis(
"{
A24 '18 to 24' expression('Age <= 24'),
A65 '65 plus' expression('age >= 65'),
AgeMean 'Mean' mean(Age),
AgeStddev 'Std.dev' stddev(Age)
}"
);
Even though the age ranges look like categorical specifications, the analysis program still has
access to respondents’ exact ages and is able to calculate the mean and standard deviation using
the raw data. There is no need to define factors as would be necessary if the ranges were truly
categorical.
Here’s an example for a text question.
Postcode "What is your full postcode?" text [1..9]
axis (
"{
TN8 'TN8' expression('Postcode.Find(""tn8"") <> -1'),
Othpc 'Invalid/other' expression('Postcode.Find(""tn8"") = -1
And Postcode.Find(""tn13"") = -1
Or Postcode.IsEmpty()')
}"
);
In this example, respondents supply their full postcodes, which are then grouped by area to form a
summary table showing how respondents are distributed across the region in which the survey ran.
The expression for each area code scans the Postcode data looking for a given string. If the string
is not found, the function returns −1 (if the string is found, the function returns its position in the
text, but that is not important here). The last element counts anyone whose postcode did not fall
into the preceding groups and also anyone who did not answer the question.
And now an example for a date question.
RenewDate "What is the renewal date for your travel insurance?"
date [1-Jan-07..31-Dec-07]
axis (
"{
Q12007 'Quarter 1 2007' expression('RenewDate.DatePart(""q"") = 1'),
Q42007 'Quarter 4 2007' expression('RenewDate.DatePart(""q"") = 4')
}"
);
This example groups responses into quarters by checking the DatePart function to convert the
months into quarters. Therefore, someone whose travel insurance is due for renewal in July,
August, or September will be placed in the Quarter 3 2007 element.
962
Chapter 1
Different Response Texts for Interviews and Analyses
Sometimes you’ll want to use different question and/or response texts for interviews and analyses.
Question and response texts in interviews tend to be longer and more explanatory so that
respondents can easily choose their answers. In analyses, the amount of space that texts take up
on a screen or page is often critical to the rest of the table or report, so you’ll want to abbreviate
them where possible. You can use contexts for this. Questionnaire files generally have two
contexts: Question, which defines texts for interviewing, and Analysis, which defines texts for
tables, profiles, and other reports.
If you write your interview script using IBM® SPSS® Data Collection Base Professional, all
the metadata text is saved in the Question context (this is set by the Question keyword in the
Metadata statement at the start of your script). If you want to use different texts in analyses you
will have to add them to the script and flag them as being belonging to the Analysis context. If
some texts exist only in the Question context, the analysis applications will use these texts, so
there is no need to redefine texts that are the same in both contexts.
To define texts in the Analysis context, start by placing a line of the following form at the start
of the script, just below the Metadata statement:
ContextLabel lcl ( , Analysis, );
where ContextLabel is a name that you will use to label all analysis-only texts in the script.
Since you’ll need to type the name for every analysis text you define, it’s worthwhile choosing a
short name that is easy to type. For example:
AC lcl ( , Analysis, );
Then, add the analysis texts to the questions and responses that need them. Type:
ContextLabel: "AnalysisText"
immediately after the question or response text, where:

ContextLabel is the name you chose for labeling analysis texts. Notice the colon that
separates it from the text. It’s easy to forget this, so if you get errors when you save your
script, check that you haven’t omitted a colon somewhere.
AnalysisText is the text you want to use in analyses.
The following example shows a question for a blind product test. Respondents were asked to try
three products which were referred to in the interview as A, B, and C. In analyses, we want to
display the product names instead so we define replacement texts as follows. We also define a
shorter question text that is more suited to analyses.
LikedBest "Which of the test products did you prefer overall?"
AC: "Product preferred overall" categorical [1..1]
{
A "Product A" AC: "Mamas Hot Chilli Sauce",
B "Product B" AC: "Sizzling Stir-In Sauce",
C "Product C" AC: "Hot, Hot, Hot"
};
If you are working in a multiple-language script, you can enter translations for analysis texts using
IBM® SPSS® Translation Utility, in the same way that you translate texts in the Question context.
Just remember to select both the Question and Analysis contexts when prompted as part of the file
opening procedure in SPSS Translation Utility.
963
Base Professional
Combining Categorical Responses in Analyses
You can create additional elements for analyses by combining interviewing responses so that they
are displayed as a single row or column in tables. A typical example of this is where you want
to create a “top two” or “bottom two” element that combines the counts for the first or last two
ratings in a scale. In questions with multiple choice response lists, the combined element will
count each eligible respondent once only regardless of how many of the named responses he or
she chooses. Elements of this type are called nets because they contain net counts of respondents.
Using an axis block
Define the combined element as follows. You may make it an additional element in tables or you
can make it a replacement for the response elements it merges.
Name 'Text' combine({RespName, ... RespNameN}),
where
Name is the name of the new element.
Text is the text you want to display for this element in analyses.
RespName to RespNameN are the names of the responses to be combined to form the new
element.
For example:
RateAOverall "How would you rate Product A overall?" categorical [1..1]
{
Excellent,
VGood "Very good",
Satisfactory,
Poor,
VPoor "Very poor"
}
axis (
"{
Top2A 'Excellent/Very Good' combine({Excellent, VGood}),
Excellent, VGood, Satisfactory, Poor, VPoor,
Bottom2A 'Poor/Very Poor' combine({Poor, VPoor})
}"
);
Using an Analysis element
Place the following statement in the appropriate position in the list of interview responses:
Name "Text" elementtype(AnalysisCategory) expression("QName *
{RespName1, ..., RespNameN}")
where
Name is the name of the new element.
Text is the text you want to display for this element in analyses.
QName is the question name.
RespName to RespNameN are the names of the responses to be combined to form the new
element.
964
Chapter 1
Here’s a variation of the previous question written using analysis elements:

RateBOverall "How would you rate Product B overall?"
categorical [1..1]
{
Top2B "Excellent/Very Good" elementtype(AnalysisCategory)
expression("RateBOverall * {Excellent, VGood}"),
Excellent, VGood "Very good",
Satisfactory,
Poor, VPoor "Very poor",
Bottom2B "Poor/Very Poor" elementtype(AnalysisCategory)
expression("RateBOverall * Poor, VPoor}")};
Additional Variables for Analysis Only
Sometimes you’ll know when you are writing the interviewing script that you’ll want to present
your results in ways that cannot be achieved simply by using the interview questions to create
tables. For example, you may be adding questions for age and gender to the interview script, but
you already know that you’ll need tables that show gender and age combined. There’s no point
and, indeed, no need to create a separate interviewing question that has these combined categories
as its responses since you will already have all the information you need in the data file. Instead,
you can set up a question whose responses come from the questions that you already have. We
call these questions derived variables.
You do not have to ask the question in interviews. Since it is defined in the metadata section,
the question will be stored in the questionnaire (.mdd) file, but it will never have any data of its
own because it is not asked. Instead, its data will be generated and made temporarily available
whenever you use the question in analyses.
To create a derived variable for analyses, define it as a question in the usual way. Set its type
according to the type of data it will contain. Then, add expressions defining the characteristics
that respondents must have in order to be included in the variable. For categorical questions, you
can append the expressions to the response definitions or you can create a separate axis block
containing the necessary statements. For other types of questions you can either append the
expression to the question definition or you can create an axis section.
Here is a specification for a derived age and gender variable:
GenderAge "Age and Gender" categorical [1..1]
{
YoungMan "Men under 30" expression("Gender={Male} And Age < 30"),
MiddleMan "Men 30 to 50" expression("Gender={Male} And Age >= 30 And Age <= 50"),
SeniorMan "Men over 50" expression("Gender={Male} And Age > 50"),
YoungWoman "Women under 30" expression("Gender={Female} And Age < 30"),
MiddleWoman "Women 30 to 50" expression("Gender={Female} And Age >=30 And Age <= 50"),
SeniorWoman "Women over 50" expression("Gender={Female} And Age > 50")
};
Here’s a numeric variable that combines the incomes of the two main wage earners in the
household:
Hhincome "Total household income" long expression("Earner1 + Earner2");
If you want to look at income in more detail, you can replace the expression with an axis block
that defines different income bands. The expressions would then test that the sum of the two
incomes was in the given range. See Categorical Ranges for Numeric, Text, and Date Responses
for an example of using an axis block in a numeric question.
965
Base Professional
Incrementing Cell Counts by the Value of a Numeric Variable
When you create tables from your interview data, most cells in the tables are counts of people and
cells are incremented by 1 for every respondent who belongs in them. You can also increment
cells using the value of a numeric variable. For example, if you have an age question that places
respondents in age groups, and a numeric question that asks how many portions of fruit each
respondent ate, you can create a variable that shows how many fruit portions were eaten by each
age group rather than the number of people in each group. Each time a respondent is counted
in an age group, the count for that group is incremented by the number of fruit portions that
person ate rather than by 1.
The numeric variable whose values you use to increment cell counts is sometimes called a
multiplier because counts are incremented by 1 multiplied by the respondent’s value in the
numeric variable.
To specify that you want to use a multiplier, add:
multiplier (use Qname)
to the response definition, where Qname is the name of the numeric question that you want to
use to increment the category counts in the current response.
Here are the question definitions for the age and fruit example. Age and Fruit are asked, but
FruitByAge is a derived variable whose counts are incremented by the number of fruit portions
eaten by respondents in each age group. See Derived Variables for further information about
creating derived variables.
Age "How old are you?" categorical [1..1]
{
AgeU30 "Under 30",
Age3050 "30 - 50",
AgeO50 "Over 50"
};
Fruit "How many portions of fruit did you eat last week?" long [0..99];
FruitByAge "Fruit consumption by age group" categorical [1..1]
{
AgeU30 "Under 30 years old"
expression("Age={AgeU30}") multiplier (use Fruit),
Age3050 "30 - 50 years old"
expression("Age={Age3050}") multiplier (use Fruit),
AgeO50 "Over 50 years old"
expression("Age={AgeO50}") multiplier (use Fruit)
};
Analysis Options in Shared Lists
If you always want to create the same analysis elements every time you use a shared list, you can
define those elements as part of the shared list rather than inserting them in every question that
uses the list. This is a good time saver in ratings lists, where you may always want to use a specific
set of factors or create a “top two” element. Here’s an example for a “top two” element:
RatingList "" define
{
Top2 "Top 2" elementtype(AnalysisCategory) expression("@ * {Excellent, VeryGood}"),
Excellent "Excellent",
VeryGood "Very Good",
Good "Good",
Fair "Fair",
Poor "Poor"
};
966
Chapter 1
The Top 2 element is flagged as an AnalysisCategory element so it does not appear in

interviews. However, more importantly, the expression that determines which data contributes
to this category uses the special @ parameter that tells the analysis program to use the data for
the current question. So, if questions RateA and RateB both use this shared list, an analysis
program will use the data for RateA if the user is tabulating RateA, and the data for RateB when
the user is tabulating RateB.
Note: This facility does not work if you use namedspaced shared lists in a question’s response list.
The script will run and will generate interviews, but will fail when you try to use the question in
analyses. The failure is because the response names in the Top 2 element do not match the response
names in the question. The response names in the Top 2 element are simple names whereas those
in the question are full names that include the list name as well as the response name.
Note: Axis blocks do not work in shared lists.
Odds and Ends
This chapter is a collection of miscellaneous topics that do not fit easily into any of the other
chapters. These topics include:
Checking that an Interview is Connected to a Call. This is a good way of checking that
telephone interviewers are conducting proper interviews with respondents rather than
completing bogus interviews for participants who have refused to be interviewed.
Testing and Debugging Scripts. When you are testing or debugging a script in IBM®
SPSS® Data Collection Base Professional you can choose to ignore statements that are not
applicable in those scenarios. You can also write statements that are to be executed only in
test or debug mode.
Checking that an Interview is Connected to a Call
One of the main concerns of any telephone room supervisor is to achieve as many completed
interviews as possible within the survey parameters. This entails not only monitoring and
managing the availability of numbers for calling and the parameters that control the selection of
sample records, but also checking that interviewers are working properly. Most interviewers are
honest and will conduct interviews according to your company rules, but you may come across
some who try various methods of artificially boosting their productivity. One such method is to
conduct interviews themselves for respondents who refuse to be interviewed. The respondent
terminates the call but, instead of selecting the appropriate Refused option, the interviewer selects
the Proceed with Interview option and fills in random answers to the questions.
You can catch interviewers who do this by checking, just before the end of the script, that the
interview is still connected to a call and writing a message to a log file if this is not the case.
The statement that checks the connection is:
variable = (QSampExtension.Call.State = CallState.csConnected)
where variable is a temporary (Dim’d) variable of your choice. Its value will be True if the
interview is connected to a call and False if it is not. The following example writes a message to
the interview log file (ISE*.log) whenever the variable is False.
967
Base Professional
IsConnected(IOM)
Thanks.Show()
Sub IsConnected(IOM)
Dim connected
Dim err_msg
connected = (QSampExtension.Call.State = CallState.csConnected)
If Not connected Then
err_msg "Interview not connected to call. Interviewer: " + IOM.InterviewerID
End If
End Sub
The message is written as an error rather than a warning so that the supervisor will notice it and
can take immediate action against the named interviewer. All messages in the log file include the
interview serial number (the –r parameter) so the supervisor can tell the project manager that this
interview needs to be removed from the data file.
Testing and Debugging Scripts
If you are using IBM® SPSS® Data Collection Base Professional to build interview scripts, you
can use its Debug (F5) and Auto Answer (F6) features to run interviews. In debug mode, each
question is displayed on the Browser tab and you can either enter an answer manually or click F5
again to have Base Professional select an answer for you. In auto answer mode, Base Professional
runs the interview itself and chooses answers for each question. (If you use auto answer with data
creation, you can quickly and easily create a case database for analysis tests.) In both cases, any
routing in the script is honored as it would be in a proper interview.
There are several ways that you can influence the answers that Base Professional chooses.
First, you can use hints. A hint is an instruction telling Base Professional to answer a question
in a particular way. For example, you may want the age question always to have the value 50,
or the brands preferred question to always be set to A and B. Using hints allows you to test
a specific scenario using auto answer without having any manual intervention to set the key
responses. Refer to the Refer to the Using Hints section in Running an interview automatically
The second way of influencing Base Professional is to set break points. These allow you to
auto answer an interview up to a certain question and then to switch into debug mode so the
remaining questions are displayed one at a time for answering manually. This is useful if you
have a problem towards the end of the script and do not want to have to answer every question
manually in order to reach the problem area.
Refer to Testing Interview Scripts for further details about these facilities.
Sometimes a script will contain statements that you want to ignore when in debug or auto
answer modes. Typical examples are quota control statements when you want to test scripts
without having to bother about quotas, or a custom validation function that should always pass
in test mode, or an error handler that you want to bypass when running in debug mode. There’s
no need to create a separate version of the script to achieve this; in fact, this is not a good idea
at all as you may make changes in the test version of the script that you then forget to make
in the version for live interviewing. Instead, use a single script and flag the statements as not
being appropriate in these situations and they will be ignored. You can also achieve the opposite,
whereby statements are executed only in debug or auto answer modes, in the same way.
968
Chapter 1
To ignore statements when interviews are being run in debug mode (F5), type:
If Not IOM.Info.IsDebug Then
statements
End If
The following example shows how to bypass a custom error handler when the script is being
run in debug mode.
If Not IOM.Info.IsDebug Then On Error Goto __DefaultErrHandler
Goto __StartOfScript
__DefaultErrHandler:
Dim __err_msg, __error
__err_msg = "Script error at line " + CText(Err.LineNumber) + ", " + Err.Description
IOM.Log(__err_msg, LogLevels.LOGLEVEL_ERROR)
If IOM.Info.IsTest Then
IOM.Banners.AddNew("__ScriptErrMsg" + CText(__error), __err_msg)
__error = __error + 1
If __error > IOM.Info.MaxTestErrors Then
End If
End If
Resume Next
__StartOfScript:
To ignore statements when interviews are being run in auto answer mode (F6), type:
If Not IOM.Info.IsAutoAnswer Then
statements
End If
The following example shows how to have a custom validation function always return True when
the script is being run in auto answer mode.
Function ValidateQuestion (Question, IOM, Attempt)
If (IOM.Info.IsAutoAnswer) Then
ValidateQuestion = True
Else
perform custom check
End If
End Function
Creating Questionnaire Wizards for IBM SPSS Data Collection Author
IBM® SPSS® Data Collection Author now includes wizards to simplify the creation of new
questionnaires. While Author ships with a variety of wizards, you may find it useful to create your
own using IBM® SPSS® Data Collection Base Professional. This chapter details the process for
creating questionnaire wizards that Author users can access through their local library, the IBM®
SPSS® Data Collection Question Repository, or project templates.
In order to create your own questionnaire wizard, you will need to be familiar with IBM® SPSS®
Data Collection scripting. It is also recommended that you read through this entire chapter and
review the provided examples.
This chapter includes the following topics:

Overview of the Wizard Creation Process. An overview of the wizard creation process,
including new concepts and terms used throughout this chapter.
969
Base Professional
Creating the Source. Describes the process of creating the Source .mdd file, which will be
used as the basis for the question to be inserted by the user.
Creating the Wizard. Describes the process of creating a Wizard .mdd file that will prompt the
user for the information that will customize the question to fit his or her needs.
Storing the Questionnaire Wizard for Use by IBM SPSS Data Collection Author Users.
Describes how to store your questionnaire wizard in the local Author library, the Question
Repository, or a project template.
Questionnaire Wizard Examples. Includes example scripts that you may find useful.
Overview of the Wizard Creation Process
Questionnaire wizards in IBM® SPSS® Data Collection Author work through the interaction
of three distinct questionnaire definition (.mdd) files. Throughout this chapter, these three .mdd
files are referred to by the following names:
Target - The .mdd file where the results of the wizard will be inserted. From the user’s
perspective, this is the file currently open in Author.
Source - The .mdd file that contains the basic structure for the question, and points to an
associated Wizard .mdd file. An Author user selects the Source .mdd from the local library,
the IBM® SPSS® Data Collection Question Repository, or the appropriate project template
_files directory when attempting to insert a wizard item.
Wizard - The .mdd file that contains the wizard questions. When the user inserts a
questionnaire wizard item, questions from the Wizard .mdd prompt the user for information
that is then used to modify the Source .mdd.
To create a new questionnaire wizard, you must create the Source and the Wizard, and then store
them in a place where Author users can access them (in a local library, the Question Repository, or
the appropriate project template _files directory).
Creating the Source
The Source .mdd file needs to contain the basic structure of the question to be inserted and point
to the Wizard .mdd file that will be used to prompt the user for details. To point to the Wizard,
simply add the following to the metadata section of the .mdd file:
WizardPath = "<path_to_wizard_mdd>"
where path_to_wizard_mdd is the directory path to the Wizard .mdd file. The path can be either
relative or absolute.
If WizardPath is not specified, or the Source cannot find the specified Wizard file, the Source acts
as a normal library item. When an IBM® SPSS® Data Collection Author user inserts it, the
Source is added to the Target as-is.
970
Chapter 1
Notes
If you are planning to store your wizard in the IBM® SPSS® Data Collection Question
Repository, you may eventually need to modify your WizardPath to account for the way
Question Repository stores .mdd files. For more information, see the topic Storing the
Questionnaire Wizard for Use by IBM SPSS Data Collection Author Users on p. 971.
When working with project templates, WizardPath should point to the appropriate project
template _file directory. Refer to Project Templates for more information on working with
project templates.
By default, Author checks for duplicate element names prior to launching the questionnaire
wizard. To disable this feature, you can set the optional WizardPreCheck property to false. This is
useful in cases where the Wizard will modify placeholder names in the Source.
To view an example of the metadata section of a Source .mdd file, see Questionnaire Wizard
Examples.
Creating the Wizard
The Wizard prompts the user for information when the user attempts to insert a questionnaire
wizard item in IBM® SPSS® Data Collection Author. When the user has entered the required
information, the Wizard generally modifies an in-memory version of the Source. This modified
version of the Source is then inserted into the Target (the .mdd file currently open in Author).
One or more Source .mdd files point to a Wizard through the WizardPath parameter. Because
more than one Source .mdd file can point to a single Wizard, you can use the same Wizard to
gather details for multiple Source files.
The wizard engine automatically inserts two variable definitions into the routing script:
source_mdm is a Document object that references the source document being inserted. It is an
in-memory copy of the document that is inserted into the Source .mdd file upon completion
of the wizard.
target_mdm is a Document object that references a copy of the Target .mdd file. This is
provided for informational purposes only; changes to this document will not affect the actual
Target file.
Because there is no way for IBM® SPSS® Data Collection Base Professional to set wizard
variables implicitly, for testing purposes, you will need to create the variables and set them equal
to IDocument instances. When testing is complete and the wizard is ready to be deployed, you
should comment out those lines of code.
For an example Wizard script, see Questionnaire Wizard Examples.

971
Base Professional
Storing the Questionnaire Wizard for Use by IBM SPSS Data Collection Author Users
Once you’ve created your new questionnaire wizard, you can store it in a local IBM® SPSS® Data
Collection Author library, the IBM® SPSS® Data Collection Question Repository, or a project
template where it can be accessed by Author users. This topic contains special considerations you
will need to follow when storing your new questionnaire wizard.
Storing a Questionnaire Wizard in the Local Library
To store a Questionnaire wizard in the local library, save the Source .mdd file to the
Author Library File Location (by default, C:\Documents and Settings\All Users\Application
Data\IBM\SPSS\DataCollection\6\Author\Library). The user should then be able to use the wizard
by selecting the Source file from the Library pane in Author.
The associated Wizard .mdd file can be stored anywhere as long as the Source file correctly
points to it in the WizardPath property. However, it is recommended that you store the Wizard
file close to the Source file. To prevent Author users from seeing the Wizard file in the Library
pane, save it in a directory named QWzd, or one that ends in .mdd_files. This tells Author not to
display the directory or its contents.
The following is an example of a recommended directory structure for a “Constant Sum”

questionnaire wizard:
C:/Documents…/Library
Constant Sum.mdd
Constant Sum.mdd_Files
Constant sum templates
QWzd
Constant Sum Wizard.mdd
Storing a Questionnaire Wizard in the Question Repository
This section contains information specific to storing a questionnaire wizard in the Question
Repository.
The Question Repository stores a root item (an .mdd file) along with any number of attached files.
When these items are extracted, the attached files then appear in a <rootitem>_files subdirectory
(where rootitem is the name of the root item being stored). If you do not take this change in
directory structure into account, your Source .mdd file may be unable to find the Wizard.
To illustrate the issue, this is how the above directory structure would be extracted from the
Question Repository:
C:/Documents…/Library
Constant Sum.mdd
Constant_Sum_files
Constant Sum.mdd_Files
Constant sum templates
QWzd
Constant Sum Wizard.mdd
972
Chapter 1
Notice that the Wizard files are now all contained in a new Constant_Sum_files directory.
Therefore, the WizardPath specified in Constant Sum.mdd would no longer be valid unless it took
this new directory structure into account. As a result, Constant Sum.mdd would be treated as a
normal, non-wizard library item by Author.
To address this issue, make a copy of the Source .mdd file and modify the
WizardPath to reflect the new directory structure used by the Question Repository.
For example, WizardPath=./QWzd/Constant Sum Wizard.mdd would become
WizardPath=./Constant_Sum_files/QWzd/Constant Sum Wizard.mdd.
Storing a Questionnaire Wizard in a Project Template
To store a Questionnaire wizard in project template, save the source .mdd file to the appropriate
project template _files directory (for example, C:\Documents and Settings\All Users\Application
Data\IBM\SPSS\DataCollection\6\example_files). WizardPath should point to this directory.
Refer to Project Templates for more information on working with project templates.
Questionnaire Wizard Examples
This section provides complete examples of the Source and Wizard scripts used for a working
questionnaire wizard. You may find it helpful to review these scripts before attempting to create
your own wizard.
Cosmetics Awareness Questionnaire Wizard
The scripts that follow are for a “Cosmetics Awareness Questionnaire” wizard. When the user
selects Cosmetics Awareness Questionnaire from the IBM® SPSS® Data Collection Author
Library and clicks Insert, the following wizard dialog box is displayed. The contents of this
dialog box are defined in the Wizard .mdd file.
973
Base Professional
Figure 1-210
Cosmetics Awareness Questionnaire Wizard
When the user clicks Next, the wizard creates a series of questions based on the information the
user entered. These questions are defined in the Source .mdd file, updated with the information the
user provided, and inserted into the Target .mdd file (the file currently open in Author). In this
case, the wizard inserts a series of general questions about the interview subject, followed by a
series of questions about the cosmetics brands the Author user specified. For example:
Figure 1-211
Example of Output from Cosmetics Awareness Questionnaire Wizard
The following examples include the full contents of the Source and Wizard .mdd files used for
this wizard.
974
Chapter 1
Example Source Metadata Section
The following is an example of the metadata section of a Source .mdd file. Notice that the
WizardPath property has been added and set to the location of the Wizard.
HDATA -
[
Creator = "InterviewBuilder",
CreatorVersion = "2.1",
WizardPath = ".\QWzd\Cosmetics Awareness Questionnaire Wizard.mdd"
];
Complete Source Example
The following is a complete example of a Source script:

FormatGrids:
'—Start of IOM Script item FormatGrids —
IOM.DefaultStyles.Grids[GridStyleTypes.gsCell].Cell.Width = "5em"
'—End of IOM Script item FormatGrids —
FormatTexts:
'—Start of IOM Script item FormatTexts —
Q1.Style.Control.Type = ControlTypes.ctSingleLineEdit
Q1a.Style.Control.Type = ControlTypes.ctSingleLineEdit
Q1b.Style.Control.Type = ControlTypes.ctSingleLineEdit
Q1c.Style.Control.Type = ControlTypes.ctSingleLineEdit
'—End of IOM Script item FormatTexts —
'—Start of page Page —
Page.Q1.Style.Columns = 40
Page.Q1.Style.Rows = 1
Page.Q1a.Style.Columns = 40
Page.Q1a.Style.Rows = 1
Page.Q1b.Style.Columns = 40
Page.Q1b.Style.Rows = 1
Page.Q1c.Style.Columns = 40
Page.Q1c.Style.Rows = 1
Page.Ask()
'—End of page Page —
'—Start of page Page1 —
Page1.Ask()
'—End of page Page1 —
'—Start of page Page2 —

975
Base Professional
Page2.Ask()
'—End of page Page2 —
Q9a.Ask()
Q9b.Categories.Filter = Q9b.DefinedCategories() - Q9a

Q9b.Ask()
Q10.Ask()
Q11.Ask()
Q12.Ask()
Q13.MustAnswer = true
Q13.Ask()
Q14.Ask()
Q15a.MustAnswer = true
Q15a.Ask()
Q15aGoTo:
If Not (Q15a.ContainsAny(Q15a.Categories[0])) Then
Goto Q16a
End If
Q15b.Ask()
Q15c.Ask()
Q15d.MustAnswer = true
Q15d.Ask()
If Q15d >= {NO} Then Goto Q16a
Q15e.Ask()
Q16a:
Q16a.MustAnswer = true
Q16a.Ask()
Q16b.MustAnswer = true
Q16b.Ask()
Q16c.Ask()
ThankU.Show()
Metadata (en-US, Question, Label)
'pubsmarker:m_nesting_start
HDATA -
976
Chapter 1
[
Creator = "InterviewBuilder",
CreatorVersion = "2.1",
WizardPath = ".\QWzd\Cosmetics Awareness Questionnaire Wizard.mdd"
];
'pubsmarker:m_nesting_end
MainBrand "" define

{
};
ComparisonBrands "" define
{
};
OtherBrands "" define
{
};
Q1 "Full name:"
text [..40];
Q1a "Address:"
text [..40];
Q1b "Postcode:"
text [..40];
Q1c "Telephone No."

text [..40];
Q2 "Head of Household's Occupation:"

text;
Q3 "Class:"
categorical [..1]
{
B "B",
C1 "C1",
C2 "C2"
};
Q4 "Age:"
categorical [..1]
{
_20_24 "20-24",
_25_34 "25-34",
_35_45 "35-45"
};
Q5 "Gender:"
categorical [..1]
{
Female "Female",
977
Base Professional
Male "Male"
};
Q6 "Marital Status:"
categorical [..1]
{
Married "Married",
Single "Single",
Div_Wid_Sep "Div/Wid/Sep"
};
Q7 "Children in Household"
categorical [..1]
{
_0_4 "0-4",
_5_10 "5-10",
_11_16 "11-16",
No_children "No children"
};
Q8 "Work Status:"
categorical [..1]
{
Full_time "Full-time",
Part_time "Part-time",
No_paid_job "No paid job"
};
Q9a "Please name some brands of brands of cosmetics and facial skincare products."
categorical
{
use MainBrand sublist "",
use ComparisonBrands sublist "",
use OtherBrands sublist ""
}
helperfields (
"Other" ""
text [1.. ];
);
Q9b "Which of these other brands of cosmetics and facial skincare products have you heard of?"
categorical
{
};
Q10 "Now I would like to ask your opinion of some of these brands. For each statement I read out, I would like you to tell me which of the bra
loop
{
978
Chapter 1

} fields -
(
GV1 "GV1"
categorical
{
Are_really_moder "Are really modern and up to date",
Are_quality_bran "Are quality brands",
Offers_a_wide_ra "Offers a wide range of products",
Offers_the_lates "Offers the latest colors",
Offer_good_value "Offer good value products",
Display_their_ra "Display their ranges in a way that makes it easy to find the products you want"
};
Q11 "Imagining __brand1__ came to life as a brand, which of the following do you think would best describe how you would feel about it?"
categorical [..1]
{
One_of_my_closes "One of my closest friends",
Quite_a_good_fri "Quite a good friend, who I'd have some thing in common with",
Someone_I_d_get_ "Someone I'd get along with OK, but not who I'd call a friend",
Someone_I_wouldn "Someone I wouldn't have much in common with, but I wouldn't actually dislike",
Someone_I_d_have "Someone I'd have nothing in common with and wouldn't really like",
None_of_these "None of these"
};
Q12 "Again, imagining __brand2__ & __brand3__ came to life as brands, which of the following do you think would best describe how you
loop
{
use ComparisonBrands sublist ""
} fields -
(
GV1 "GV1"
categorical [..1]
{
One_of_my_closes "One of my closest friends",
Quite_a_good_fri "Quite a good friend, who I'd have some things in common with",
Someone_I_d_get_ "Someone I'd get along with OK but not who I'd call a friend",
Offers_the_lates "Offers the latest colors",
Someone_I_d_have "Someone I'd have nothing in common with and wouldn't really like",
None_of_these "None of these"
};
Q13 "Which of these statements applies to you about __brand1__?"

categorical [..1]
{
I_always_buy_Bra "I always buy __brand1__",
I_Brand_1_most_o "I buy __brand1__ most often and occasionally buy other brands",
979
Base Professional
I_sometimes_buy_ "I sometimes buy __brand1__ as well as other brands",

I_occasionally_b "I occasionally buy __brand1__ but usually buy other brands",
I_never_buy_Bran "I never buy __brand1__"
};
Q14 "Which of these statements applies to you about..."

loop
{
} fields -
(
GV1 "GV1"
categorical [..1]
{
I_always_buy_thi "I always buy this brand",
I_buy_this_brand "I buy this brand most often and occasionally buy other brands",
I_sometimes_buy_ "I sometimes buy this brand as well as other brands",
I_occasionally_b "I occasionally buy this brand but usually buy other brands",
I_never_buy_this "I never buy this brand"
};
Q15a "Which, if any, of these brands have you seen advertised on TV recently?"
categorical
{
};
Q15b "Can you please describe the last TV advertisement you saw for __brand1__?"
text;
Q15c "What impression did it give you about __brand1__?"

text;
Q15d "Do you remember this advertisement having slogan?"

categorical [..1]
{
Yes "Yes",
No "No"
};
Q15e "What was the slogan?"

text;
Q16a "Which of these impressions, if any, did this advertisement give about __brand1__?"
categorical
{
Brand_1_understa "__brand1__ understand me",
Brand_1_offers_q "__brand1__ offers quality products",
Brand_1_is_for_p "__brand1__ is for people like me",
980
Chapter 1
None_of_these "None of these" exclusive

};
Q16b "Which of these phrases do you think describes this advertisement?"

categorical
{
It_grabbed_my_at "It grabbed my attention",
I_found_it_diffi "I found it difficult to follow",
It_made_me_feel_ "It made me feel good",
It_could_have_be "It could have been for any brand",
It_s_different_f "It's different from other ads",
It_told_me_somet "It told me something new about this brand",
It_was_humorous "It was humorous",
It_was_enjoyable "It was enjoyable to watch",
It_was_irritatin "It was irritating",
It_was_boring "It was boring",
None_of_these "None of these" exclusive
};
Q16c "How does this advertisement affect what you feel about __brand1__?"
categorical [..1]
{
I_am_much_more_l "I am much more likely to consider buying it in future",
I_am_little_more "I am little more likely to consider buying it in future",
I_m_no_more_like "I'm no more likely to consider buying it in the future",
I_would_buy_the_ "I would buy the brand anyway"
};
ThankU "Thank you for taking the time to complete this survey."
info;
Page -
page(
Q1,
Q1a,
Q1b,
Q1c
);
Page1 -
page(
Q2,
Q3,
Q4,
Q5
);
Page2 -
page(
Q6,
Q7,
Q8
);
981
Base Professional
End Metadata
Complete Wizard Example
The following is a complete example of a Wizard script.

982
Chapter 1
SetInitialValues:
'--- Start of IOM Script item SetInitialValues ---
QText.Response.Initial = ExampleQText.Label
QResponses.Response.Initial = ExampleQResponses.Label
Sum.Response.Initial = 100
Attempts.Response.Initial = 3
Template.Response.Initial = "Default"
'--- End of IOM Script item SetInitialValues ---
ExampleQText.MustAnswer = true
ExampleQResponses.MustAnswer = true
'--- Start of page Page ---

Page.QText.Style.Columns = 40
Page.QText.Style.Rows = 4
Page.QResponses.MustAnswer = true
Page.QResponses.Style.Columns = 40
Page.QResponses.Style.Rows = 6
Page.Attempts.MustAnswer = true
Page.Template.Style.Control.Type = ControlTypes.ctCheckButton
Page.Template.MustAnswer = true
Page.Ask()
'--- End of page Page ---
Script:
'--- Start of IOM Script item Script ---
' All QWzd questions have been asked. Use the answers to process
' the questionnaire library item.
Dim mdm, script, target

' A reference to the source is provided by the variable named source_mdm
' A reference to the target is provided by the variable named target_mdm
' target_mdm should not be modified – and may be a clone of the actual target MDD
Set mdm = source_mdm

' Add the responses
AddResponses(mdm, QResponses.Response, mdm.Fields["ConstantSumQ"].Elements)
' Set the max value to the sum

mdm.Fields["ConstantSumQ"].Fields["Value"].RangeExpression = "[1.." + CText(Sum.Response) + "]"
' Get the script from the Mdm, this includes both metadata and routing
script = mdm.Script
' Perform text replacement on the script version of the shell questionnaire
script = Replace(script, "<constantsum_qtext>", QText.Response)
script = Replace(script, "<constantsum_sum>", CText(Sum.Response))
script = Replace(script, "<constantsum_attempts>", CText(Attempts.Response))
If (Template.Response <> "Default") Then
script = Replace(script, "Card_Blue_TopAndBottomErrors.htm", Template.OtherTemplate.Response)
End If
' Apply the changed script back to the questionnaire library item
mdm.Script = script
source_mdm = mdm;
' we use the source_mdm variable as the value to insert upon completion
' because mdm is a reference to sourceMDM, modifications to the mdm
' variable affect the sourceMDM and will be picked up upon completion
' No need to save, calling program expects a variable called source_mdm with
' the MDM document
'--- End of IOM Script item Script ---
AddResponses:
'--- Start of IOM Script item AddResponses ---
Sub AddResponses(mdm, responses, elements)
' Takes multiple mr.Lf separated responses and adds them to the specified elements list
Dim elem, cats, cat_name, cat_label
cats = Split(responses, mr.Lf)
For Each cat_label in cats
If (cat_label <> "") Then
cat_name = mdm.MakeName(cat_label)
Set elem = mdm.CreateElement(cat_name, cat_label)
elem.Type = 0 'MDMLib.ElementTypeConstants.mtCategory
elements.Add(elem)
End If
Next
End Sub
'--- End of IOM Script item AddResponses ---
983
Base Professional
Tips for IBM SPSS Quancept and IBM SPSS Surveycraft Users
This section contains tips for people who are familiar with the IBM® SPSS® Quancept™ or
IBM® SPSS® Surveycraft™ scripting languages. It explains the differences between these
languages and writing interview scripts in the Interview Scripting Language.
Tips for IBM SPSS Quancept Users
In Quancept, each question item defines the question text, the responses and any routing associated
with those responses. Routing for multiple choice responses and routing based on the responses
to more than one question are defined separately at the appropriate points in the questionnaire.
Statements in the script are executed sequentially.
In scripts written in the Interview Scripting Language, questions and response texts (the metadata)
are defined separately from the logic (the routing). This distinction makes it easier for sections of
a questionnaire to be reused in other questionnaires, or for different methods of interviewing to
be defined within the same script.
The metadata in interview scripts is written in mrScriptMetadata. Some of the advantages

of mrScriptMetadata are:
Multiple lists in one question along with other responses
Subheadings
Ability to size the Other text box
Additional question types in grids
Tips for IBM SPSS Surveycraft Users
In Surveycraft, you define questions, codes and routing within one script , but they are dealt with
separately by the Surveycraft validation program. The validation program reads the questions
and codes, and then evaluates the routing. Questions are read, the order is determined from any
L000 specs, and then repeat specs and jumps are evaluated. This order would be obvious if the
specifications were recovered from a VQ file: the routing is all at the end.
With interview scripts, the process is similar to Surveycraft, except that as well as being evaluated
separately, the question and response texts (the metadata) are also defined separately from the
logic (the routing). This distinction makes it easier for sections of a questionnaire to be reused in
other questionnaires, or for different methods of interviewing to be defined within the same script.
Loops in interview scripts are similar to the design of Surveycraft question loops: you define a
question that controls a loop (similar to a Step Through Question) and then specify the questions
that are to be asked for each loop iteration.
The metadata in interview scripts is written in mrScriptMetadata. Some of the advantages

of mrScriptMetadata are:
Multiple lists in one question along with other responses
Subheadings
984
Chapter 1
Ability to size the Other text box

Ability to present a grid on one page that presents different options depending on the row
of the grid. For example:
Figure 1-212
A grid question generated from an interview script
Testing Interview Scripts
Debugging
For information on debugging interview scripts in IBM® SPSS® Data Collection Base
Professional, see Debugging.
The Browser Tab
The Browser tab lets you run an interview script in Base Professional, just as if you were
running it on a Web server. This means that you can try your interview at any time, to test that it
displays and responds exactly as you want. There is no need to set up a test server or activate
an interview project.
The Browser takes the XML that Base Professional generates from your interview script and
renders it as HTML. It also allows you to answer questions in the interview by passing your
answers back to the script so that it can continue.
985
Base Professional
A reference for all of the XML tags that the Browser uses can be found in the .
To run an interview using the Browser tab
E Select the Browser tab.
E Press F5 or click the run button.
Figure 1-213
The run button in IBM SPSS Data Collection Base Professional
Testing with Auto Answer
When you run an interview script in Base Professional, you can answer the questions yourself
in the browser pane, or you can continue through the questions by pressing F5 or clicking the
run button.
Figure 1-214
The run button in IBM SPSS Data Collection Base Professional
When you continue through the questions, answers are being automatically filled in by Auto
Answer. Auto Answer views the XML that Base Professional generates from your interview
script, randomly chooses a valid answer to the question, and then returns that answer to the
script so that it can proceed.
Running multiple interviews automatically

You can run a set number of interviews automatically, and then look at the results to check for any
unexpected or undesired behaviors. For example, if one of your questions is not being answered at
all, you can check your routing to make sure that it is being asked correctly in the Routing section.
E Open an interview script in Base Professional.
E Press F6 or choose
Debug > Start With Auto Answer
E Enter the number of interviews you would like to have automatically answered and click Start.
E Press Alt+F1 to view the Auto Answer pane.

986
Chapter 1
Figure 1-215
The Auto Answer pane in IBM SPSS Data Collection Base Professional
The blue completion bar over the question name, and the number beside the question, indicate the
number of times the question has been answered by Auto Answer.
E Double-click the question name in the Auto Answer pane to highlight the question in the Metadata
pane, or to highlight where the question is asked in the Routing pane.
Skipping to a specific place in an interview script

You can use Auto Answer to skip quickly through an interview until you get to a section that you
want to step through, or a question that you want to look at in the Browser pane.
E Open an interview in Base Professional.
E Set a breakpoint at the point in the script where you want the execution to stop. For more
information, see the topic Setting Breakpoints on p. 48.
E Press F6 or choose
Debug > Start With Auto Answer
E Enter the number of interviews you would like to have automatically answered as 1 and click Start.
The interview will run until the breakpoint is reached.
E Now you can inspect the variables in the Output pane, look at the question in the Browser pane,
or start stepping through the script.
987
Base Professional
Activating Interview Scripts

Activation is the process of making an interview script available for interviewing using IBM®
SPSS® Data Collection Interviewer Server. In most cases you will be activating a script on the
cluster on which it currently exists, but it is also possible to activate scripts from one cluster to
another. This typically happens when you have different clusters for development and production
work.
There are several ways of activating scripts:
Using the Activation option in IBM® SPSS® Data Collection Base Professional
From a command prompt
Run IBM® SPSS® Data Collection Interviewer Server Administration and upload the
interview script (the .mdd file) into the project folder in your User folder, and then use the
Launch activity in Interviewer Server Administration (this uses the same Activate dialog
box as Base Professional)
Run Interviewer Server Administration and use the Promote Project activity in Interviewer
Server Administration to activate the project from one cluster onto another.
Before Activating with IBM SPSS Data Collection Base Professional for the First Time
Before you activate with Base Professional for the very first time, you must specify the name of
the Project Management Server. This is the computer that controls project publishing. Your
Interviewer Server administrator will tell you which server to use. To define the activation server,
proceed as follows.
E In Base Professional, select

Tools > Options
988
Chapter 1
E In the Base Professional Options dialog box, enter the name of the Activate Server or URL:
Figure 1-216
When to Reactivate Interview Scripts
If you change the contents of the script after it has been activated, or you change the contents
of one of the templates files used by the script, then you must reactivate the project to make
those changes available in Interviewer Server.
If you change a cascading stylesheet, there is no need to reactivate. Simply copy the new
stylesheet into the appropriate location, and stop and restart your browser.
Using the Activation Option in IBM SPSS Data Collection Base Professional
To activate an interview script using IBM® SPSS® Data Collection Base Professional, select:
Tools > Activate
E In the IBM® SPSS® Data Collection Login dialog box, enter the name of your IBM® SPSS®
Data Collection Interviewer Server Administration server or URL.
E Enter your Interviewer Server Administration user name, password, and authentication method
and click Login.
The Activate - Current Project dialog displays. For more information, see the topic Activating
questionnaires on p. 113.
989
Base Professional
E After setting the appropriate activation settings, click Activate. Base Professional creates a new
project for the questionnaire, uploads the questionnaire files into the project folders, and updates
the interviewing servers.
When the process is complete, a confirmation message appears. You can now log into Interviewer
Server Administration and use the new project.
For further information, see the Interviewer Server Administration User’s Guide and the IBM®
SPSS® Data Collection Interviewer Server User’s Guide.
Note: Any changes that you make to the questionnaire file from now on will be saved as a new
version of the questionnaire file when you activate the file.
Activating Projects from the Command Line
You can activate projects from the command line. This is useful in the following circumstances:
You want to activate a number of projects, but do not want to have to wait while each one is
activated.
You want to activate to a number of clusters or servers.
You want activation to run unattended and/or at some time in the future.
The Activate Document
Activation from the command line uses an Activate Document that specifies how the project is to
be activated. It contains the same information as you would normally enter using the Activate
dialog box in IBM® SPSS® Data Collection Base Professional, but in XML format. This means
that if you have a number of projects with identical or similar activation requirements, you can
create the Activate Documents by copying and editing an existing file.
The easiest way to create an Activate Document from scratch is to fill in your requirements
on the Activate dialog box and then save the specification to a file, optionally without activating
the project at all.
If you have pre-version 2.3 activation .ini files, you can convert them into Activate Documents
by running the ActivateIniToXml tool.
If you create a new Activate Document by copying and editing an existing one, you need to
check the settings that specify whether activation is over the local network or across the internet.
These settings are as follows:
<?xml version="1.0"?>
<Activate usewebservice="False" webserviceurl="">
<ActivateSettings>
<Sites>
<Site dpmservername="MyDPMServer" username="" userticket="">
...
</Site>
</Site>
</ActivateSettings>
</Activate>
This example is set up for activation over a local network. To activate across the internet, change
usewebservice to True and webserviceurl to the URL for IBM® SPSS® Data Collection
Interviewer Server Administration on the destination server.
990
Chapter 1
If dpmservername is not defined, it defaults to the DPM server set on the machine running the
accessories service.
Activating Projects
You activate projects from the command line by running the Activate program in either console
or dialog box mode. In both cases you will need to run the command from C:\Program
Files\Common Files\IBM\SPSS\DataCollection\6\\Interviewer Server\5.6.
In console mode, activation is based solely on the contents of the Activate Document named
on the command line, and is ideal for activating remotely or on an unattended machine. To
activate in this mode type:
activate -a "actdoc" [-u username] [-t ticketname] [-r] [-c] [-l] [-?]
Optional parameters are as follows:

Option Description
–a “actdoc” Names the Activate Document.
–u username The user name to use for activating the document.
If none is specified, the activation process will use
the name specified in the Activate document. (It is
recommended that names are not stored in Activate
documents.) If there is no name or user ticket
specified in the Activate document, the activation
process attempts to log in as a trusted Windows user.
–t ticket The user ticket to use for activating the document.
(It is recommended that tickets are not stored in
Activate documents.) This option is valid for
command-line activation only.
–r Display a progress box.
–c Write information to the screen.
–l Display a login dialog box.
–? Display help.
In dialog box mode, Activate displays a dialog box in which you specify the activation
parameters (this is the mode in which Activate runs in IBM® SPSS® Data Collection Base
Professional). You can include options on the command line that pre-populate the dialog box with
certain types of information, such as the project name or interview script type. When you have
completed the dialog box, click Activate to start activation. This mode is ideal for creating new
Activate Documents. To activate in this mode type:
activate -g [-p proj_ID] [-s script_type] [-f "foldername"] [-d DPMservername]
[-w webservice URL] [-l] [-?]
Optional parameters are as follows:

Option Description
–g Displays the Activate dialog box. Use this option
when you want to create an Activate document. If
this option is not present, -a is required.
–p project_id The project ID.
991
Base Professional
Option Description
–s script_type Interview script type. Must be set to IBM® SPSS®
Data Collection.
–f “foldername” Pathname of the project’s source folder.
–d DPMservername Names the initial DPM server.
–w web-service URL Activate via the web-service URL. For example:
http://<servername>/spssmr/activatewebservice/activatewebservice.asmx
–l Display a login dialog box.
–? Display help.
Example Activation Commands
The following command displays the Activate dialog box:

activate
The following command activates using the myactdoc.xml Activate Document:

activate -a "c:\myactdoc.xml"
The following command activates using the myactdoc.xml Activate Document and writes any
output to the log.txt file:
activate -a "c:\myactdoc.xml" > log.txt
The following command activates using the myactdoc.xml Activate Document but displays a login
dialog box before activation starts.
activate -a "c:\myactdoc.xml" -l
The following command displays the Activate dialog box with the Project Id field containing
“museum” and the Source Files field containing “c:\myprojects\museum”:
activate -g -p museum -f "c:\myprojects\museum"
The following command displays help:

activate -?
Converting Activation .ini Files to .xml Format
If you used command line activation prior to version 2.3 and you want to reuse the activation .ini
files with Activate, you can convert them using the ActivateIniToXml tool. Go to the folder
called C:\Program Files\Common Files\IBM\SPSS\DataCollection\6\Interviewer Server\6.0.1.0.0
and type:
ActivateIniToXml -i "ini_filename" -x "xml_filename"
For example:
ActivateIniToXml -i "c:\mrproject\myproject.ini" -x "c:\mrproject\myproject.xml"
If you forget the command syntax, type:

ActivateIniToXml -?
992
Chapter 1
for a reminder.
Sample Management
Sample Management allows you to manage prospective participants in a survey.
Information about prospective participants is held in records in a Microsoft SQL Server database.
These records are referred to collectively as the Sample, and each record is known as a Sample
record.
There are two types of Sample Management: inbound, where participants connect to your web
site and click a link to run the survey, and outbound (telephone), where interviewers contact
participants by telephone and conduct the interviews verbally.
For inbound calls, IBM® SPSS® Data Collection Interviewer Server displays an authentication
page that asks the caller to enter some personal or other pre-agreed details, such as a user ID, so
that it can select the caller’s record from the Sample database. For outbound calls, Interviewer
Server selects a Sample record for each interviewer and displays the telephone number and other
information from the Sample record on the interviewer’s screen. The interviewer dials the number
and, if the respondent agrees to be interviewed, starts the interview.
At the end of each inbound or outbound call, the Sample record is returned to the Sample
Management system with an outcome code representing the outcome of the call and/or interview.
Sample Management files the Sample records in Queues according to their call outcomes. For
example, all records that have resulted in successfully completed interviews may be filed in a
COMPLETED queue so that they cannot be used again on this project.
The key part of each project’s Sample Management system is the Sample Management script.
This defines how all aspects of Sample Management will work for that project. Interviewer Server
comes with a number of Sample Management scripts that can be used without any intervention on
your part. Alternatively, you can customize these scripts, or even write your own if you wish.
This documentation describes the components and requirements of a Sample Management system,
and introduces an example project that you can run to try out Sample Management if you wish.
What’s New in Sample Management for IBM SPSS Data Collection Interviewer Server 6.0.1
The sample management scripts have been updated to support new 6.0.1 features. If you have
existing projects that use pre-version 5.6 sample management scripts, the new features may not
be recognized.
RemoteHangup call outcome code. The new RemoteHangup call outcome code is used when a
call is hung up immediately after connection. The call and the sample record are passed to the
interviewer, who will then select an appropriate call outcome from the list. For more information,
see the topic Call Outcome Codes on p. 1014.
993
Base Professional
What’s New Information for Previous Releases
What’s New information for previous IBM® SPSS® Data Collection\Dimensions releases can be
found in the Data Collection\Dimensions What’s New document.
The document is in Adobe Portable Document Format (.pdf) Viewing and printing the document
requires Adobe Reader. If necessary, you can download it at no cost from www.adobe.com. Use
the Adobe Reader online Help for answers to your questions regarding viewing and navigating
the document.
Sample Management Example Scenario
A market research agency has a client who plans to launch a new lifestyle magazine. The
client wants the agency to conduct a prelaunch Web interview to investigate the opinions of
approximately 2000 women between the ages of 18 and 25 (the magazine’s target audience)
and a post-launch interview a few months later to see whether the magazine is meeting reader
expectations. Both surveys will be run as inbound projects only.
Gathering and Routing Respondents. The agency uses two methods to come up with the sample
for the interview:
They place a link to the interview on a Web site that is popular with young women.
They rent lists of e-mail addresses for women up to 21 years old and for women 21 to 30
years old.
Respondents who arrive at the interview by clicking the link at the popular Web site are asked for
their gender and age. Women aged 18 to 25 are assigned an ID and password and are routed to the
interview. Respondents who do not fit this category are routed to a computer-user survey that is
being conducted for a different client of the market research agency.
The agency sends each of the women on the rented lists an invitation e-mail with the address
of the interview site. The e-mail provides an ID and password so that the respondent can be
authenticated when she begins the interview.
The scriptwriter programs Sample Management to move the records of respondents who
complete the interview into a custom FOLLOWUP queue. In a few months, these respondents are
sent an e-mail that invites them to participate in a follow-up interview that asks whether they have
read the magazine and what they thought about it.
Monitoring Progress. While the interview is in progress, the administrator periodically checks the
database to monitor the status of the sample group. By looking at how many respondents are in
each queue, the administrator can see how many:
Have not yet responded to the e-mail invitation (are still in the FRESH queue)
Have paused or stopped the interview (are in the STOPPED queue)
Have successfully completed the interview (are in the FOLLOWUP queue)
As the magazine launch approaches, the agency decides that respondents in the STOPPED queue
who have completed at least 80 per cent of the first questionnaire will be admitted to the follow-up
interview. These respondents are moved to the FOLLOWUP queue and will receive invitations
to the follow-up interview.
994
Chapter 1
Building a Respondent Database. The agency is building its own database of respondents so that
it won’t have to rely on rented lists and adds the respondents who successfully complete this
interview. The date of the interview is recorded in the database so that the agency can avoid
sending these respondents too many invitations to interviews.
Sample Management Facilities
This section describes the facilities that are available for sample management, and provides an
example of a typical scenario in which sample management is used to control the way in which
respondents participate in the survey.
Sample Management facilities include:
Sample table. A database table that holds information about respondents who may take part
in the survey, either by dialing in to your company’s Web page or by being contacted by an
interviewer working on an outbound calling project. For more information, see the topic Sample
Table on p. 995.
Sample history table. A database table that holds information about Sample records that were
used for outbound telephone interviewing. History records are written to this table whenever an
interview is terminated in some way—for example, stopped or completed—or when a telephone
interview drops a Sample record for some reason—for example, because the line is engaged. The
information in this table can be used for producing supervisory and productivity reports. For more
information, see the topic History Table on p. 1007.
Sample Management scripts. Scripts that define the way in which sample management will work
for a project. For more information, see the topic Sample Management Scripts on p. 1008.
Queues. Allow records to be grouped according to how the records have been or may be used
in the survey. At the start of a survey, all records are usually held in a single queue. When an
interview is in progress for an interview, the record moves into an Active or In-progress queue;
when the interview ends, the record moves into a third queue depending on the outcome of the
interview. For more information, see the topic Queues on p. 1011.
Call outcomes. (Known internally as Sample record return codes.) Define the result of an inbound
or outbound call. When a sample record is returned to sample management at the end of a call, the
interviewing program also returns a call outcome code indicating the result of the call. The sample
management script uses these codes to decide which queue it should place the sample record in.
For more information, see the topic Call Outcome Codes on p. 1014.
Telephone interviewing project parameters. Define values for variables that are used in the sample
management script; for example, callback delays for busy and no-answer callbacks, and the
maximum number of recalls permitted per record. For more information, see the topic Telephone
Interviewing Project Parameters on p. 1024.
Time zone management. If sample records contain a TimeZone field specifying the respondent’s
time zone, sample management can take into account time zone differences between interviewers
and respondents when selecting records with appointments for recall. For more information, see
the topic Time Zone Management on p. 1032.
995
Base Professional
Interviewer qualifications. Assign sample records to interviewers who have the appropriate
qualifications to deal with those calls. For example, if the respondent’s preferred language
is Spanish, the sample record may be assigned to a Spanish speaking interviewer. For more
information, see the topic Interviewer Qualifications on p. 1036.
Authentication. The process whereby respondents who connect to your Web page are validated
before an interview begins. For more information, see the topic Authentication of Inbound
Respondents on p. 1037.
End of interview. The action to take when Sample records are returned to the sample management
system at the ends of interviews. For more information, see the topic End of Interview on p. 1044.
Quotas. Define the requirements for the sample in terms of the numbers of respondents who
have certain characteristics or combinations of characteristics. For more information, see the
topic Quotas on p. 1045.
Project and interview properties. Each project has a collection of properties that store information
about the project, and each interview has its own set of properties that contain information
about that particular interview. You can access project and interview properties in the sample
management script and can perform different actions for different types of projects or interviews.
In some instances you can change property values or add new properties too. See Sample
Management Scripts and Project and Interview Properties for details.
Sample Table
The sample table is a database table in an SQL Server database that stores sample records. Each
sample record holds details about a prospective respondent such as ID, password, age, gender, and
so on. These individual items of information are known as sample record fields.
Before you can use sample management, you must set up the sample table in an SQL Server
database. The simplest way to create a sample table is to use the Participants activity in IBM®
SPSS® Data Collection Interviewer Server Administration to load some sample records. If you
choose to load the records into a new table, the load process will create the table for you.
If possible, create a separate table for each project. You can create a sample table that is shared
by a number of projects, but you then run the risk of overwriting a project’s data due to the
interview serial number field being populated on one project and then being used in the second
project. For example, if a record is used on project A and generates an interview with serial
number 100, the number 100 is written back into the Serial field. If the record is then used on
Project B, the interviewing program will read the serial number for the new interview from the
sample record and will create an interview with that serial number. If there is already an interview
with that serial number, its data will be overwritten. To avoid this, you should always prepopulate
the Serial field in shared sample tables.
When you activate a project, you specify whether it uses sample management. For projects that
use sample management, you must specify the server, database, and database table that correspond
to the sample table and the columns within the database table that correspond to the sample record
fields. This maps the columns in the database table to the sample record fields that you can access
with the sample management script. You must make sure that you map all of the fields that you
want to update with new information or that you want to access in the script.
996
Chapter 1
You can map columns of the nchar, ntext, nvarchar, bit, smallint, int, and datetime SQL Server
database data types. (You can also map columns of the varchar SQL Server database data type,
however the Unicode-compatible nvarchar is preferable, especially for new databases or if you
need to support extended character sets, or may need to in the future.) You cannot map columns
of any other SQL Server database data type.
It is strongly recommended that you initialize all of the fields in the sample table with a default
value. If you do not initialize a field, it will be transferred to the sample management script with a
zero value if it is a numeric field or an empty string if it is an alphanumeric field.
Required fields
The sample table must contain the columns shown in the following table. The column names must
appear exactly as shown (beginning with a capital letter followed by lowercase letters) and may
not be shown in all uppercase or lowercase letters (Id, not ID or id). The Id field should be an
alphanumeric data type and must not contain single quotation marks (‘).
Project does not use telephone interviewing

Active Long Yes No 0 Set to 1 while
the sample
management
functions are
running; that
is, while the
record is in
the ACTIVE
queue.
Id Text(64) No Yes The sample
record
ID which
uniquely
identifies
each sample
record.
Queue Text(255) Yes No FRESH Names the
queue in
which the
record is
currently
held.
997
Base Professional

Serial Long Yes No 0 The unique
serial number
that IBM®
SPSS® Data
Collection
Interviewer
Server
assigns
to each
respondent’s
case data.
Generally,
this serial
number is not
the same as
the sample
record ID.
When a
respondent
restarts an
interview,
Interviewer
Server uses
the serial
number to
retrieve the
respondent’s
case data
record and
to display
the responses
(stored in
the case
data record)
that the
respondent
has already
given.
Test Long Yes No Null Set to 1 if the
record is test
data, or 0 if
it is real data
(also known
as live data).
This column
is used by
the Phone
activity to
restrict the
type of data
that appears
in phone
reports. If the
value is Null,
the Phone
activity will
treat the
record as if
998
Chapter 1

it is both real
and test data.
Project uses telephone interviewing

Active Long Yes No 0 Set to 1 while the sample
management functions are
running; that is, while the
record is in the ACTIVE
queue..
ActivityStartTime
DateTime Yes No Null The StartTime of latest
record in the history table
for a specific sample.
Date
AppointmentTime Yes No The time in UTC at which
the respondent asked to be
called.
Long
AppointmentTryCount Yes No 0 The number of calls made
to this record after an
appointment was set.
during the upload.
Audit Text(2000) Yes No Records changes made
but see Notes to other fields (except
for more Comments) in the record.
information This field was new in
Interviewer Server 4.0.
In earlier versions, these
changes were stored in the
Comments field.
If you reuse a pre-v4.0
a Comments field of
SQL type ntext, the
Audit field is created as
nvarchar(2000) instead.
two ntext columns.
CallOutcome Text(64) Yes No The call outcome (return)
code for the previous call
to this record.
999
Base Professional

Long
CallRecordingsCount Yes No 0 for The number of call
telephone recordings for this record.
projects, Records loaded with this
otherwise field empty have this field
Null set to Null in the sample
table.
Comments Text(2000) Yes No Additional information
but see Notes about the participant.
for more Interviewers may update
information. this field when they call
the participant.
In pre-v4.0 sample tables,
the Comments field is
created as ntext(16). If
you reuse a pre-v4.0
a Comments field of
type ntext, its data type
remains unchanged and
the Audit field is created
as nvarchar(2000) instead.
two ntext columns.
The standard multimode
sample management
scripts display records
with comments before
dialing so that the
interviewer can read
the comments before
talking to the participant.
ConnectCount Long Yes No 0 The number of times
that the number has been
connected. This field is
updated when a sample is
dialed and connected.
DayPart Text(128) Yes No Null Records the call count for
each specific day part.
For example, assume there
are two day parts named
aa, ab. The value for
this field will be aa1|ab2
(or aa1). This means the
sample was used to call
one time in aa time range
and two times in ab time
range. If the sample has
not yet been used, the
value of this field is null.
1000
Chapter 1

ExpirationTimeDateTime Yes No 2099–12–31Defines the participant
23:59:000 record expiration date
and time. For example, a
project may dictate that
participant records can
only be called within a
specific date range.
Expired records are not
available for dialing
(except for retrieving
appointments).
Id Text(64) No Yes The sample record ID that
uniquely identifies each
sample record.
InternalDialerFlags
Text(64) Yes No NULL Used in conjunction with
a 3rd party dialer. In
full predictive mode, this
field should accompany
all numbers dialed
commands. It is set to
an initial value by the
CATI system for the first
dialer (for a different
dialer, the initial value can
be different).
IBM® SPSS® Data
Collection Dialer will
return a new value for
Internal Dialer Flag for
the number. After dialing,
this field will be updated
with the new value,
and this value will be
permanently set with the
sample record and passed
through for all subsequent
dialing attempts.
InterviewModeText(64) Yes No How the record may be
used: set to Web for an
inbound self-completion
interview or Web CATI
for outbound telephone
interviewing. In projects
that allow a mix of
inbound and outbound
calling, the sample
management script should
check the value of this
field and select records
for telephone interviewing
accordingly.
The value in this field
can be changed in the
questionnaire script, or by
editing the record directly
in SQL. You might
want to do this towards
1001
Base Professional

the end of a survey if
there are a number of
timed out or stopped
Web interviews and you
want your interviewers
to contact those people
to try to complete the
interviews.
Long
NoAnswerCount Yes No 0 How many times this
sample has been called
and received NoAnswer.
This field is updated
when a sample is dialed
and returned with a call
outcome of NoAnswer
PhoneNumber Text(64) Yes No Must contain a phone
number if the record is
to be used for telephone
interviewing.
If the project uses
an autodialer, phone
numbers that start with
a + sign will have that
character replaced by the
InternationalAccessCode
defined in DPM. + signs
preceded by white space
or other characters are not
replaced.
If the project allows
inbound calling, you can
add a question to the script
that asks respondents to
enter contact numbers,
and then update the
sample records with this
information.
PreviousInterviewerID
Text(64) Yes No The name of the
interviewer who made
the previous call to
this participant. This
allows appointments
to be returned to the
previous interviewer if the
current time is before the
AppointmentMarginAfter
interval has passed.
Appointments that are not
kept within this period
may be passed to any
interviewer.
When interviews are
reviewed, this field is
updated with the name of
the reviewer.
1002
Chapter 1

PreviousQueue Text(64) Yes No The name of the queue
in which the record was
previously held. When
records are displayed
for interviewers, the
record’s current queue
is always shown as
ACTIVE because the
record has been selected
for interviewing.
Displaying the value of
PreviousQueue can be
useful to interviewers
as it may provide
additional information
about the record’s calling
history. For example, if
PreviousQueue is FRESH,
the interviewer knows
the record has not been
called before, whereas
if PreviousQueue is
APPOINTMENT, he/she
knows that the respondent
has already been contacted
and has asked to be called
back to be interviewed.
Queue Text(64) Yes No FRESH Names the queue in which
the record is currently
held.
When replicate identifiers
are defined in the queue
field for specific records,
those records can
then be used to create
sample/participant record
subsets.
RecallTime Date Yes No The time in UTC that
was set as the callback
time for appointments that
are set automatically by
the sample management
script.
Long
RequiresManualDial Yes No Indicates that the record
must be manually dialed.
The sample management
script will set AutoDial=0
for these records.
The feature will not work
if RequiresManualDial
is not defined in the
participants table
1003
Base Professional

ReturnTime Date Yes No The time at which the
record was returned to
sample management. This
allows you to specify the
amount of time that must
elapse between repeat
calls to records whose
interviews timed out or
were stopped.
Serial Long Yes No 0 The unique serial
number that Interviewer
Server assigns to each
respondent’s case data.
Generally, this serial
number is not the same
as the sample record
ID. When a respondent
restarts an interview,
Interviewer Server uses
the serial number to
retrieve the respondent’s
case data record and to
display the responses
(stored in the case data
record) that the respondent
has already given.
Screener Text(64) Yes No Null Identifies which
respondents are the
suitable candidates for the
current survey. Screener
questions are designed to
filter respondents. If a
respondent answers do not
the respondent is not
allowed to continue the
survey, and the Screener
field is recorded as Failed.
If respondent answers
they are allowed to
continue the survey, and
the Screener field is
recorded as Passed.
This field can be set using
the following IOM script
in routing (it is the data
source for the Incidence
report).
Passed Screener:
IOM.SampleRecord.Item["Screener"].Value = "Passed"
Failed Screener:
IOM.SampleRecord.Item["Screener"].Value = "Failed"
IOM.Terminate(Signals.sigFailedScreener, True)
1004
Chapter 1

In order to accurately
calculate the project
incidence, the Screener
field is added to the
sample table. The field
is updated during the
survey with three values
– Null, Passed, and
Failed. The sum of
Passed is the incidence
numerator; the sum of
Passed and Failed is the
incidence denominator.
The incidence report is
generated using TOM
based on the data source,
sample table, and sample
history table.
SortId Text(64) Yes No Null A random value that
can be used for sorting
records prior to selection.
(Appointments and recalls
are not affected by this
property as they are
always sorted in ascending
date/time order.) The
Participants activity can
initialize this field with
a random value when
uploading records. If
records are uploaded in
batches, each record in the
sample table receives a
new random number, not
just those being uploaded
in the current batch. See
“Naming the Database
Server, Sample Database,
and Sample Table” in the
Interviewer Server User’s
Guide for details.
Test Long Yes No Null Set to 1 if the record is
test data, or 0 if it is real
data (also known as live
data). This column is used
by the Phone activity to
restrict the type of data
that appears in phone
reports. If the value is
Null, the Phone activity
will treat the record as if it
is both real and test data.
1005
Base Professional

TimeZone Long Yes No The respondent’s
timezone. This is
used in the setting
of appointments to
ensure that any time
differences between
the respondent’s and
interviewer’s locations are
taken into account when
the record is presented
for recalling. For more
on p. 1032.
TrunkGroup Long or Yes No NULL If sample records are used
Text(64) in telephone interviewing
projects, you can use
the TrunkGroup field to
specify which trunk group
of the dialer will be used
for dialing the sample
record. If you want the
dialer to automatically
select the trunk group,
the field should be set to
NULL or empty.
TryCount Long Yes No 0 The number of calls
made to this record.
during the upload.
UserId Text(64) Yes No NULL The UserId of latest record
in the history table for a
specific sample.
Optional Fields
The sample table can contain additional fields for storing other data, such as the respondent’s
name, e-mail address, gender, and age. You can use these fields to set quotas for the number of
respondents to be interviewed with specific sets of characteristics.
1006
Chapter 1
When sample records are used in telephone interviewing projects, you can use the Comment
field to store comments or other information to be displayed when the record is presented to the
interviewer for calling. The interviewer may add to the comments if appropriate. The Comments
field needs to be sufficiently large to store a useful amount of text, and should be defined as
being of SQL type nvarchar.
Authentication Fields
If the project allows inbound calling, where participants complete the questionnaires themselves,
you define which of the sample record fields are to be used for validation during authentication
when you activate the project. Generally, you use just one or two fields for authentication (for
example, Id or Id and Password).
Who can access the sample data?
By default, all users can access all data in all sample tables and sample databases on all
servers. You can restrict access to the sample data by specifying your requirements in the
SampleMgtGUI.Config.xml file. You might want to do this if you have different sample databases
for different customers, and you want to prevent users who work on one customer’s projects
from having access to the sample data for other customers. See “Controlling Access to Sample
Management Scripts” in the Interviewer Server Administration and Maintenance section of the
Data Collection Developer Library for further details.
Another privacy option to consider is read-only fields; that is, data that sample management can
read but not update. This type of access control is generally used when you are reading sample
data from an existing database that is not part of your IBM® SPSS® Data Collection system. For
more information, see the topic Using an Existing Database as a Sample Database on p. 1007.
Data Type Mapping for Columns in Sample Tables
The activities that display information about sample tables use IBM® SPSS® Data Collection
Data Model data types to describe the type of data that can be stored in each column of the table.
This is an external feature only and exists to provide a standard way of displaying data types
regardless of the database application you are using. When a IBM® SPSS® Data Collection
activity or component creates a table in a sample database, it maps the Data Model data types onto
the data types that exist in your database application and creates the columns with the appropriate
data types. You can open the tables in your database application to check the mapping, and can
change the data types of columns if some of them are not quite as you would like.
The data mappings for SQL databases are as follows:
Data Model data type Maps to SQL data type
Long If length is 2, then maps to smallint; otherwise maps
to int
Bool bit
Date datetime
Text(length) If length is less than 8000 then maps to
nvarchar(length); otherwise maps to ntext
1007
Base Professional
Using an Existing Database as a Sample Database
IBM® SPSS® Data Collection Interviewer Server expects the sample table to be part of an SQL
database. If you have an existing database of a different type (Oracle, for example) that contains
the records you want to use as the sample for a project, you can often read the data directly
from that database rather than having to export it and then load it into Interviewer Server. The
steps below outline a procedure whereby you can create a link from your external database into
Interviewer Server, while at the same time limiting the information in the external database that
can be accessed by Interviewer Server activities.
E Open SQL Server and do the following:

Create a linked server that links to your external database. (Linked servers run against OLE
DB data sources and the OLE DB provider for non-SQL databases runs over SQL*NET.)
Create a table that contains the sample fields that Interviewer Server requires (Active, Id,
Queue, Serial, and Test for Web projects, for example) and the foreign key to the sample table
in your external database.
Create a view that joins the SQL Server table with the table in the external database. Refer to
the SQL Server documentation for how to create distributed queries via linked servers.
E Activate the project as normal, selecting the new view as the sample table.
E In DPM Explorer, navigate to

Site>Servers>ServerName>SampleManagements>ProjectName>Queueing>Queues>Properties
and add a property called ReadOnlyFieldColumns. Make its value a comma-separated list
of the column names in the external database that should not be updated by the
sample management system.
History Table
The sample history table, called HistoryTable, is a database table in an SQL Server database
that stores history records containing information about how sample records have been used
for outbound calling. sample management writes a history record to this table whenever an
interview is terminated in some way — for example, it is completed or stopped — and whenever
the GetSampleRec function in an outbound telephone interviewing project drops a sample record
— for example, because the number is busy when called.
If a sample record is called more than once, the table will contain one history record for
each call.
The table contains the following columns.
Column Data type Size Null permitted Content
Id int 4 No History record ID.
UserId nvarchar 50 Yes Interviewer ID
(__Web for
inbound calls).
SampleId nvarchar 50 Yes Sample record ID.
StartTime datetime 8 Yes Interview start time
in UTC.
1008
Chapter 1
Column Data type Size Null permitted Content

Duration int 4 Yes Interview length in
seconds.
CallOutcome nvarchar 50 Yes Call outcome code.
Sample Management Scripts
The key to sample management is the sample management script, which is a text file with a .mrs
filename extension. The script controls any or all of the following:
How a respondent is validated against the sample table.
The interview or Web page to which respondents are routed when they pass or fail
authentication.
The Web page to which respondents are routed when they end an interview, if different from
the default set when the project is activated.
The selection of records for dialing.
The setting of appointment times when the respondent asks to be interviewed at a later date or
time.
The setting of callback times for calls that are busy or unanswered when called.
The rescheduling of missed appointments and callbacks.
Quota control checks made before respondents start an interview. These checks may simply
restrict the number of respondents taking a single survey, or they may be used to determine
which one of a number of surveys the respondent takes.
What happens to the sample record when an interview ends.
The movement of the sample records between different queues.
Checking and modification of certain project and interview properties. For more information,
see the topic Project and Interview Properties on p. 1087.
Normally, you’ll write sample management scripts using the IBM® SPSS® Data Collection
scripting language. However, for backwards compatibility with older versions of IBM® SPSS®
Data Collection Interviewer Server, support is still provided for scripts written using Microsoft
Visual Basic Scripting Edition (VBScript), which is a subset of Visual Basic and was developed
for programming in Web environments. You specify the script to be used for a project during
activation.
1009
Base Professional
Note: From Interviewer Server 4.0 onwards, the Data Collection scripting language is the
recommended language for sample management scripts for Data Collection projects, and you are
advised to convert any old VBScript scripts that you wish to continue using as soon as possible.
When a project uses sample management, Interviewer Server calls the following sample
management functions:
AuthenticateSampleRec. Called when a respondent connects to your Web site and attempts to
start the interview or posts the authentication page.
GetSampleRec. Called when an interviewer working on a telephone interviewing project
requests a number to dial.
ReturnSampleRec. Called when an interview ends.
The sample management script must always contain functions with these names. By changing the
script in these functions, you can change the authentication procedure, the way in which records
are selected for dialing, and the action that sample management takes when an interview ends.
Sample management scripts can also contain other functions (for example, AddSampleRec
and RemoveSampleRec), but these are not called directly by Interviewer Server.
Note: Changes that you make to a project’s sample management script after activation are not
implemented until you activate the project again.
Converting .sam Scripts into .mrs Format
Differences between IBM SPSS Data Collection Scripting and VBScript

Read and make the changes described in that topic.
Write an error handler to deal with errors and add the following statement that tells sample
management to use the error handler when errors occur:
On Error GoTo ErrorHandler
This syntax is available in mrScriptBasic but not in VBScript.

Use the IsNullObject function rather than Is Nothing when comparing objects. Set an
object to Null rather than Nothing to release it or indicate that it is not set.
Use While…End While instead of While…Wend.
Differences between the IBM SPSS Data Collection and VBScript Sample Management Objects
The VBScript objects support UtcNow. In IBM® SPSS® Data Collection scripts use
Now("UTC"). (All the functions in the Data Collection Function Library are available for
use in sample management scripts.)
Use Log.Log rather than Log.LogThisEx for logging.
Access the logging enums using logLevels.LOGLEVEL_INFO rather than LOGLEVEL_INFO
Use the SampleResult parameter (SampleResult.Code = RESULT_SUCCESS) rather than
the function (AuthenticateSampleRec = SUCCESS) to return success or failure
1010
Chapter 1
The return codes (SUCCESS, FAILURE, REJECT, NO_RECORDS) are not defined
intrinsically but must be defined as global constants or variables. Use the following definitions
to ensure that the values match what is expected by the system:
' SampleResult.Code values set to indicate script status

Const RESULT_SUCCESS = 0
Const RESULT_FAILURE = 1
Const RESULT_REJECT = 2
Const RESULT_NO_RECORDS = 3
Instead of returning the sample record through a SampleRec parameter to the function, return
it through the SampleResult parameter (SampleResult.SampleRec).
Function signatures have changed as follows:
VBScript Data Collection scripting
Function AuthenticateSampleRec(Sam- Sub AuthenticateSampleRec(SampleRe-
pleFields, SampleRec) sult, SampleFields)
Function ReturnSampleRec(SampleRec, Sub ReturnSampleRec(SampleResult,
SampleRecReturnCode) SampleRecReturnCode)
Function GetSampleRec(SampleFields, Sub GetSampleRec(SampleResult,
SampleRec) SampleFields)
This also means that Exit Function must be changed to Exit Sub.
Differences between Functions Available to IBM SPSS Data Collection and VBScript
Conversion functions have different names:

CBool CBoolean
CStr CText
Date manipulation functions have parameters in a different order.

DateAdd(Interval, Count, Val) DateAdd(Val, Interval, Count)
DatePart(Interval, Val) DatePart(Val, Interval)
Use Find instead of InStr. Note that Find is 0-based while InStr is 1-based. Also, Find
has the start index parameter at the end while InStr has it at the beginning.
The Data CollectionVarType function returns different numbers for the same types. Strings
are returned as 2 instead of 8, booleans are returned as 7 instead of 11, and categoricals are
returned as 3 instead of 9 (Object).
Differences in the IBM SPSS Data Collection Version of the Standard Scripts
The Data Collection versions avoid use of On Error Resume Next. Instead they use On
Error GoTo ErrorHandler as recommended earlier. The error handler logs a message
and exits with a FAILURE code.
1011
Base Professional
When attempting to find an object in a collection, the VBScript versions set the object to
Nothing, then attempt retrieve it. On Error Resume Next is used so if the attempt to
retrieve the object fails, it is set to Nothing. So after the attempt to retrieve the object, it is
checked against Nothing.
Two other functions, GetStringValue and GetIntValue, have been added to the Data
Collection scripts. These make it make it easy to return “” if a string property does not exist,
and 0 if an integer (Data Collection Long) property does not exist.
Queues
As sample records move through the survey process, sample management needs to keep track of
which records are available for calling, which records are currently in use by the interviewing
software, and which records have been called and their call outcomes. It does this using Queues.
Queues are not things that exist in the way that sample records or sample management scripts
exist. Instead, they exist because their names are defined in DPM or in the sample management
script. When a record is placed in a queue, the Queue field in the sample record is updated
with the queue’s name, and the queue then consists of all records that have that queue name in
the Queue field of the sample table.
The sample management system comes with a set of predefined queue names that cover most of
the common queueing requirements. These are defined as customizable site and project properties
in DPM. You can make whatever changes you need using . DPM Explorer. Refer to IBM®
SPSS® Data Collection Developer Library for information about DPM Explorer. This is available
on the IBM® SPSS® Data Collection Interviewer Server installation CD or as a free download
from http://www.ibm.com/software/analytics/spss/products/data-collection/.
Although it is useful to have all queues defined in a property, and it helps sample management
to work efficiently, this is not a requirement. If the sample management script refers to a queue
that is not defined in one of the predefined queues properties, it is added to the appropriate
property automatically and can be referenced in the same way as the predefined queues.
WebPredefinedQueues
The WebPredefinedQueues site-level property defines default queues for self-completion

(inbound) interviews.
Queue name Holds
FRESH Records that have not yet been used on this survey.
COMPLETED Records for participants that took and successfully
completed the survey. These records cannot be
reused in this survey.
ACTIVE Records for participants that are currently taking
the survey.
TIMED_OUT Records for participants who started the survey
but whose interviews timed out. The records will
be moved to another queue if the interviews are
restarted.
1012
Chapter 1
Queue name Holds

STOPPED Records where the participant clicked the Stop
button. Interviews for records in this queue can be
restarted.
FAILED Records for which the interview returns the FAILED
ReturnCode. It is usually possible to restart all
interviews in this queue.
CATIPredefinedQueues
The CATIPredefinedQueues site-level property defines default queues for telephone

(outbound) interviews. It defines the same queues as WebPredefinedQueues, plus the
following:
Queue name Holds
APPOINTMENT Records for which callback appointments have been
made with the respondent or someone else in the
household.
CHECK_NUMBER Records that could not be called due to possible
problems with the telephone numbers; for example,
too few digits, or number not allocated. Interviewers
may call these records using the Specific Contact
button and then select a different call outcome
according to what they hear when the number is
dialed. For example, if a recorded message gives
a new telephone number, the interviewer may
edit the sample record and then place it in the
APPOINTMENT queue for calling.
This queue is used only when a project uses an
autodialer.
MAX_TRIES Records where the TryCount value, or DayPart
TryCount value (if using Day Parts), exceeds the
MaxTries setting.
If the maximum TryCount and/or DayPart TryCount
value is increased, samples from this queue may
need to be manually moved to the RECALL queue.
NOT_IN_USE Records that supervisors want to remove from the
project. Since records in this queue are ignored
for interviewing purposes, this provides a safe
alternative to deleting records from the sample table.
Records in this queue are available to the Phone
activity that creates phone reports.
RECALL Records where callback appointments have been
set automatically due to a number being busy, not
answered, and so on.
REFUSED Records for respondents who refused to
be interviewed. There will often be a
HandleQueue_REFUSED interviewer qualification
that allows records in this queue to be assigned
to interviewers who are skilled at persuading
respondents to be interviewed. For more
information, see the topic Interviewer Qualifications
on p. 1036.
1013
Base Professional
Queue name Holds

SILENT Records that resulted in nuisance calls. Records
in this queue have an appointment time 72 hours
after the last call time, but are not automatically
redialed. A supervisor can move them into the
APPOINTMENTS queue if redialing is required.
This queue is used only when a project uses an
autodialer.
TRANSFER_TO_WEB Records for respondents who were initially called
using telephone interviewing but who have agreed
to take the interview over the Web.
UNUSABLE Records that are not usable in this project and will
not be dialed again. The CallOutcome field will
contain a code that explains why each record has
been placed in this queue.
This queue is also used for records associated with
completed interviews that have been rejected by
reviewers.
Because interviews are under the control of interviewers, telephone interviews should not
normally time out but if they do, they go into the TIMED_OUT queue. Similarly, sample records
for telephone interviews should never go into the STOPPED queue because interviewers should
choose call outcomes that place them in another queue. Any telephone interviewing records that
go into these queues will not be recalled unless the supervisor moves them into another queue,
perhaps with an appropriate appointment time set.
Predefined Queues
Each project has its own list of queue names defined in the PredefinedQueues project property.
The value of this property is set by copying the setting of the WebPredefinedQueues or
CATIPredefinedQueues site property according to whether or not the project was activated to
allow telephone interviewing.
Replicates
Replicates are a mechanism for making sets of participant records available for dialing. The sets
of participant records can be grouped based on a particular meaning (specific day of the week for
example) or may be arbitrary groups representing a portion of the available participant records.
The record sets are defined by applying replicate identifiers to each participants record’s Queue
field. These identifiers allow you to determine which replicates are being dialed.
Replicates are simply different queues, for example you could specifyQueue='REPLICATE1' for the
first replicate (or Queue='MIDWEST1' for the region specific replicate). Uploading participant
records that contain replicate identifiers does not make them immediately available for dialing.
You must first release the replicates by updating the participant table. For example:
UPDATE ParticipantTable SET Queue='FRESH' WHERE Queue='REPLICATE1'

1014
Chapter 1
This can be performed in the Interviewer Server’s Participants activity. You can report on Queue
by any other field. For example, a report of Queue by Region would show how many records are
available in each replicate (as well as all the other queues) for each Region.
Call Outcome Codes
Call outcome codes define the outcome of each inbound or outbound call, and are used in
determining the queues in which used records should be placed. (The sample management
scripting language refers to call outcomes as Sample record return codes.) Code numbers 1 to 149
are reserved for internal use by the sample management system, and are described in the following
section. If you want to define your own call outcome codes you must use numbers 150 or above.
Inbound calls
When respondents connect to your Web site to participate in a survey, the call outcome code is set
by the authentication or interviewing process. Records that fail the authentication process never
reach the interviewing program and have their outcome codes set by the sample management
script. Records that pass authentication are passed to the interviewing program. When the
interview ends for whatever reason, the interviewing program passes the record back to sample
management with an appropriate outcome code.
Outbound calls
Interviewers working on telephone interviewing projects see a list of possible call outcomes on
their screens. If the respondent agrees to be interviewed immediately, the interviewer clicks Start
Interview, otherwise he/she selects a call outcome from the list. Records for which telephone
interviews take place are assigned their outcome codes by the interviewing program in the same
way as for inbound calls.
The following call outcome codes are defined for telephone interviewing projects in the
site-level DefaultCatiSampleRecReturnsCodes property in DPM. These codes form
the basis of the call outcome menu that is displayed for interviewers working on telephone
interviewing projects. The Phone Surveys activity allows supervisors to modify this list for
a particular project.
Return Code Value Queue When displayed Description
Completed 1 COMPLETED Not displayed Interview
complete.
Stopped 2 TIMED_OUT Not displayed Interview timed
or STOPPED out or stopped.
If the TimedOut
interview
property is set
to 1, the record
is placed in the
TIMED_OUT
queue; if it is
set to 0, the
record goes into
the STOPPED
queue.
1015
Base Professional

Failed 4 FAILED Not displayed Error during call
or interview.
Records with this
status should be
investigated and,
if appropriate,
moved to another
queue for dialing
or redialing.
OverQuota 5 UNUSABLE Not displayed The interview
has been
terminated
because the
respondent failed
the quota checks.
EarlyComplete 6 COMPLETED Not displayed Interview
completed early
(that is, before all
questions have
been asked).
To make this
option available
to interviewers,
change its
visibility setting
using the Phone
Surveys activity.
FailedScreener 7 UNUSABLE Not displayed Respondent did
not qualify to
complete the
interview.
Abandoned 8 UNUSABLE During interview Respondent
refused to
complete
interview.
Reviewed 10 COMPLETED Not displayed Interview has
been reviewed.
Appointment 11 APPOINTMENT Before interview Respondent
starts made an
appointment.
NoAnswer 12 RECALL Before interview No answer.
starts
AnswerMachine 13 RECALL Before interview Answered by
starts answering
machine.
Busy 14 RECALL Before interview Respondent’s
starts phone is busy.
TransferToWeb 15 TRANSFER_TO_WEB
Before interview Flag this record
starts as being for
inbound (Web)
interviewing.
1016
Chapter 1

Rejected 16 RECALL Before interview Call rejected.
starts This may be a
mobile phone set
to “Do not ring”,
or a home phone
that requires the
caller to identify
him/herself
before it will
ring.
The Caller Id
property is
set to True
so that caller
identification
will be set for the
next call even if
it is disabled for
the project.
NetworkBusy 17 RECALL Before interview Call could not
starts be made because
the telephone
network was
busy. The first
appointment
time is set for
1 minute’s time.
Thereafter, the
appointment
time is based
on the standard
NoAnswer delay.
FastBusy 18 1st RECALL Before interview Call resulted in
2nd starts an in-band fast
UNUSABLE busy (reorder)
tone. This is
supposed to
be for network
congestion but
is used by some
North American
legacy switches
to indicate an
unallocated
number.
The record is
scheduled for
calling in one
minute’s time. If
the same result is
obtained on that
call, the number
if assumed to
be unallocated
and is moved to
the UNUSABLE
queue.
1017
Base Professional

The number of
call attempts is
not incremented
because the
record has not
been called.
DialerBusy 19 RECALL Before interview Call could not
starts be made because
the autodialer
was busy.
The appointment
time is set for 1
minute’s time.
The number of
call attempts is
not incremented
because the
record has not
been called.
Fax 21 UNUSABLE Before interview Fax answered.
starts
WrongNumber 22 UNUSABLE Before interview Phone number
starts incorrect for
respondent.
Disconnected 23 UNUSABLE Before interview Phone number
starts invalid.
CellPhone 24 UNUSABLE Before interview Cell phone—do
starts not interview.
Use, for
example, when
interviewing on
cell phones is
prohibitively
expensive.
BusinessNumber 25 UNUSABLE Before interview Type of number
starts not valid for
survey.
26
PossibleWrongNumber CHECK_NUMBER
Not displayed The number has
changed, or was
incomplete (for
example, too few
digits so the call
did not ring),
or a recorded
announcement
or special tone
was detected.
The number is
not redialed.
Interviewers
may use the
Specific Contact
button to retrieve
numbers from
this queue and
listen to the
1018
Chapter 1

audio in order
to disposition
them properly
or update the
number.
NotAvailable 27 UNUSABLE Before interview The designated
starts respondent is not
available within
the timescale
of the project;
for example,
he/she may be on
holiday.
Refused 31 REFUSED or Before interview Respondents
UNUSABLE starts who refuse
to start an
interview go into
the REFUSED
queue unless
they have
refused an
interviewer
with the
HandleQueue_REFUSED
qualification.
In this case
they go into the
UNUSABLE
queue.
LanguageBarrier 32 UNUSABLE Before interview Interviewer
starts does not speak
respondent’s
language. Do
not schedule an
appointment.
LanguageRecall 33 RECALL Not displayed Interviewer
by default. If does not speak
displayed, then respondent’s
only before language.
interview starts. Schedule an
appointment
with an
appropriately
qualified
interviewer for
five minutes’
time.
1019
Base Professional

34
RejectedByReviewer UNUSABLE When an The reviewer
interview is has rejected the
being reviewed. interview for
some reason. A
typical example
may be because
the reviewer
calls the
respondent and
discovers that
the interviewer
falsified the
interview.
Canceled 41 The queue from Before interview Interviewer
which the record starts clicked the
was selected Cancel Contact
button. The
contact is
returned to
the sample
management
system as if
it were never
retrieved.
DialerFailed 42 RECALL Not displayed Dialer unable to
make the call.
The next call is
scheduled for
72 hours’ time.
(The 72 hour
appointment
time is designed
to help
supervisors meet
regulations about
redialing silent
numbers.)
Note: This
return code
is used when
unexpected
events occur
(for example, an
ISDN protocol
error where
the telephone
network
sends some
information
which, according
to the protocol
specification,
it should not
send). If an
unplanned event
occurs after the
participant has
answered the
1020
Chapter 1

call but before
the call has been
connected to
the interviewer,
the call will
be cleared and
becomes a silent
call.
Silent 43 SILENT Not displayed A group call
was made but
no extension
was free to take
the call, or the
interviewer’s
phone was
on-hook. These
calls are often
referred to as
“nuisance calls”.
The next call is
scheduled for
72 hours’ time.
Records are not
redialed, but
a supervisor
can move
them into the
APPOINTMENT
queue when the
dialer returns.
(The 72 hour
appointment
time is
designed to help
supervisors
meet regulations
about redialing
silent numbers.)
Unknown 44 RECALL Not displayed Records with
this status will be
treated the same
as records with
a NoAnswer
status.
1021
Base Professional

Reviewed — — Not displayed. The interview
Reserved for has been
future use. reviewed after
completion. This
return code will
be used by Phone
Participants
when it returns
the sample
record after the
review.
RemoteHangup 45 1st RECALL Not displayed If the call is
2nd SILENT hung up after
connection, the
call and the
sample record
are passed to the
interviewer, who
will then select
an appropriate
call outcome
from the list.
Mapping Dialer Result Codes to Call Outcome Codes

If a telephone interviewing project uses an autodialer, the autodialer dials the numbers and returns
a result code that represents the outcome of the call. The interviewer session engine maps these
autodialer result codes into call outcome codes so that the sample management script can place the
sample record in the appropriate queue. Calls with unmapped and unrecognizable result codes are
passed to the interviewer for manual resolution.
The following mappings are defined in the site-level DefaultDialerCallOutcomes
property in DPM:
Dialer Result Code Description Maps to Sample Management
Call Outcome
Announcement Recorded announcement detected. PossibleWrongNumber
AnsweringMachine Answering machine detected. AnsweringMachine
BadNumber Unallocated number. WrongNumber
Busy Busy number. Busy
Changed The number has changed. Not PossibleWrongNumber
used very often (0.03% of random
digit dial calls in North America;
used in Europe mainly for
businesses).
Congested Network congestion prevented NetworkBusy
the call from being dialed. This
is often regional (during an
emergency, for example) so
numbers in other regions may still
go through.
1022
Chapter 1

Call Outcome
Connected The dialer has obtained a There is no default mapping
connection. because the call and the
sample record are passed to
the interviewer. The final
call outcome is set when the
interviewer returns the record to
sample management at the end of
the call.
DialerError The call failed due to an internal DialerFailed
dialer error. Dialer errors may be
transient but may result in silent
(nuisance) calls.
FastBusy In-band fast busy (reorder) tone. FastBusy
This is supposed to be for network
congestion but is used by some
North American legacy switches
to indicate unallocated number.
FaxModem The number is a fax or modem. Fax
Incomplete Incomplete number (the call never PossibleWrongNumber
rang).
LocalHangup Call hung up locally by the dialer. If the call is hung up after
connection, the call and the
sample record are passed to the
interviewer, who will then select
an appropriate call outcome from
the list.
NoAnswer Call not answered within the NoAnswer
no-answer time-out period.
NoAudio Call was disconnected because no PossibleWrongNumber
audio was detected.
NoDSPs No DSPs were available. DialerBusy
NoExtAvailable A group call was dialed but no Silent
extension was available to accept
the call. This is a nuisance call.
None This call outcome should never Failed
be returned for connected calls.
NoResources The dialer has insufficient DialerBusy
resources available to make the
call
NoTrunks No trunks were available to DialerBusy
make the call. Dialer congestion
prevented call from being dialed.
OnHook The extension is on-hook. This is Silent
a nuisance call.
OutOfOrder Number out of order. WrongNumber
Rejected Rejected call. This may be a Rejected
mobile phone set to “Do not ring”,
or a home phone that requires the
caller to identify before it will
ring.
1023
Base Professional

Call Outcome
RemoteHangup Call hung up by the respondent. If the call is hung up after
connection, the call and the
sample record are passed to the
interviewer, who will then select
an appropriate call outcome from
the list.
Transferred Call transferred to another No default mapping
extension or group.
TriTone Special information tone detected. PossibleWrongNumber
Unknown The network cleared the call but Unknown
did not indicate why.
Note: When a call outcome mapping cannot be found in DPM, and the call outcome is PhWrong,
the outcome is mapped to the mapping for InComplete. Otherwise the outcome is mapped to
the mapping for None. You will need to manually add a mapping in DPM if you want to map
PhWrong to another sample management return code.
You can change these mappings by editing the definitions in DPM.
When a project is first activated, the site mappings are copied into
the project’s sample management object and become available in
Site/Servers/ServerName/SampleManagements/SMName/DialerCallOutcomes. The dialing
provider does not reload these mappings unless the Sync property for the sample management
object changes. The mappings are not copied on subsequent activations either.
In the unlikely event that you need different mappings for different projects, you can activate the
project to pick up the site defaults and then edit them in the project’s sample management object.
Sample records automatically returned by the dial process are written with an Interviewer
ID of “__AutoDial”.
Result Codes Passed Between Sample Management and the Dialer
When a project uses a dialer, the sample management system uses an extra set of call result codes
to document its interaction with the dialer. You’ll see these codes in the IVW*.tmp log files,
recording the progress of each call attempted.
Result Code Value Description
Success 100 The call to the sample
management function succeeded.
Failed 101 The call to the sample
management function failed.
ParamError 102 An invalid parameter was passed
to the sample management
function. This is an internal code
and should not appear in log files.
Reject 103 Authentication was rejected
because the record failed sample
management quota control.
DialerUnavailable 104 The dialer is unavailable (usually
because its status in DPM is not
Active) or does not exist.
1024
Chapter 1
Result Code Value Description

ExtensionUnavailable 105 The extension is not available on
the current dialer.
AutoDialTimeout 106 Sample management has waited
too long dialing to connect a
record and has timed out the
request.
ExtensionOnHook 107 The extension cannot receive calls
because it is not off-hook.
ExtensionBusy 108 The extension cannot receive calls
because it is busy.
DialerStopped 109 The dialer cannot make calls
because it has been stopped.
OutOfRecords 110 There are no records to call. This
does not always mean that there
are no more records available. It
can mean that all suitable records
have appointment times that have
not yet been reached.
Interviewer Activity Codes
The sample management system has three codes that, while not exactly call outcome codes, are
still related to activity on a project that uses a dialer. These interviewer activity codes appear in
sample management history records and in monitoring and dialer reports, and are as follows:
Interviewer_Idle The interviewer is using the Phone Participants
activity but is not engaged in a call. For example,
he/she may be waiting between the start of Phone
Participants and choosing the Dial button.
Interviewer_Wait The interviewer is waiting for a record to be
returned. The interviewing engine may be retrieving
a sample record, dialing the call, or returning the
sample record as busy or to the interviewer.
Call_Connect The time spent dialing a call that results in a
connection. It is included in the Interviewer_Wait
time, and is recorded in the history table against the
__AutoDial interviewer, and appears in the Answer
Time Distribution report.
Call_Connect is also used in the Silent Call
Statistics report to count the number of calls where
a respondent answered the call.
Telephone Interviewing Project Parameters
Sample Management scripts for telephone interviewing projects must perform the following tasks:
Select records for the autodialer to call (or, for projects that do not use an autodialer, select
records for interviewers to call manually).
Set appointment times for records that were busy or unanswered when called.
Ensure that records with appointments are presented for calling at the correct times to the
correct interviewers.
1025
Base Professional
Assign records with specific requirements to interviewers with the appropriate qualifications.
Reschedule missed appointments.
Ensure that records are selected in a particular order of priority; for example, appointments
arranged with participants, then appointments that have been set automatically, and finally
new records.
Dispose of records that become ineligible for use due to being called too many times.
The Sample Management script needs to have certain information in order to accomplish these
tasks. For example, to set appointment times automatically it needs to know how much time must
elapse between the previous call and the appointment. This information is held in the following
variables that can be set in the Phone Surveys activity. Defaults will be used for unset variables.
The settings you can define are as follows; the Sample Management script will use defaults for
any settings that you do not define.
VariableSetting Description
OrderBy Defines the ordering of records in each queue.
When the OrderBy property is present, it overrides
any existing Order By SQL clauses.
PrioritizeRecalls Whether recalls (that is, records with appointment
times that have been generated automatically)
should take priority over fresh (uncalled)
records. The default is for recalls to take priority.
Appointments arranged between participants and
interviewers are always the top priority.
NoAnswerDelayNo answer delay The number of minutes that must elapse between
consecutive calls to an unanswered number. The
default is 30 minutes.
BusyDelayBusy delay The number of minutes that must elapse between
consecutive calls to a busy number. The default is
30 minutes.
AnswerMachineDelayAnswer machine delay The number of minutes that must elapse between
consecutive calls to a number that was answered by
an answering machine. The default is 30 minutes.
WebCallbackDelayWeb callback delay The number of minutes that must elapse before
a record that timed out or was stopped during a
self-completion (Web) interview may be called
using telephone interviewing. The default is zero
which means that records for timed out or stopped
Web interviews will not be called back.
RejectDelayReject delay The number of minutes that must elapse between
consecutive calls to a number that rejected a call.
Calls can be rejected if a mobile phone user has
activated a meeting profile that rejects calls, or if a
home phone has been set to reject calls that do not
also transmit the caller’s telephone number. The
default is 1620 minutes (or 27 hours).
1026
Chapter 1
SilentAppointmentSilent appointment The number of minutes that must elapse between
consecutive calls to a number that might have
received a silent call. Silent calls can occur when
an autodialer generates more connected calls than
there are interviewers available to handle the calls.
The default is 4320 minutes (or 72 hours). Note that
when a silent call occurs, the sample management
script will change the value of the Queue field on
the participant record to SILENT. To ensure that
the phone number will be recalled at the end of
the delay, the supervisor must change the value of
Queue from SILENT to APPOINTMENT.
MaxTries The maximum number of times that a record may
be called. The default is three. If an Appointment
is made, then an additional MaxTries“Maximum
Tries” tries can be made to connect the appointment.
AppointmentPreferArrangerNo preference for Whether the AppointmentMarginBefore”Before an
appointments / Give preference to the interviewer appointment, ...” setting applies to any available
who arranged the appointment interviewer, or only to the interviewer who arranged
the appointment. The default is that it applies
to any available interviewer. If instead, you
choose that it applies only to the interviewer who
arranged the appointment, and the project uses
group/predictive autodialing, the interviewer will
not be connected automatically to the participant
who has an appointment. Instead, the participant’s
details are displayed on the interviewer’s screen,
and the interviewer must then click the Start Dialing
button to dial the participant’s phone number.
AppointmentMarginBeforeBefore an appointment, by The number of minutes before Appointment-
any interviewer and Before an appointment, by the Timethe appointment time when a number with an
arranger only (these are actually a single setting) appointment can be called, either by any interviewer
or the arranger only, depending on the setting of
AppointmentPreferArranger”No preference for
appointments / Give preference to the interviewer
who arranged the appointment”. The default is five
minutes.
AppointmentMarginAfterAfter an appointment, by any The number of minutes after AppointmentTimethe
interviewer appointment time when a number with an
appointment can be called by any available
interviewer. The sample management
script uses this setting only when the
AppointmentPreferArranger”No preference
for appointments / Give preference to the
interviewer who arranged the appointment” setting
is to give preference to the arranger. The default
is five minutes.
RecallMarginBeforeBefore a recall The number of minutes before RecallTimethe
recall time when a number with an automatic
appointment can be called. The default is ten
minutes.
1027
Base Professional
TimeZonesTime zones The time zones in which participants are located.
The values that you enter in this field must be the
indexes of the time zones in the list of time zones
stored in the registry. For more information, see the
topic Time Zone Management on p. 1032. If more
than one time zone is specified, the numbers must be
separated by semicolons. If this property is blank,
Interviewer Server will ignore time zone and calling
times when selecting records for interviewers
to call.The time zones in which participants are
located. The values that you enter in this field
must be the indexes of the time zones in the list
of time zones stored in the registry. If you need to
enter more than one time zone, separate them with
semicolons, and do not include any spaces.

Greenwich (GMT) Casablanca, 90
Standard Time Monrovia
GMT Standard (GMT) Greenwich 85
Time Mean Time :
Dublin, Edinburgh,
Lisbon, London
Morocco Standard (GMT) Casablanca -2147483571
Time
W. Europe Standard (GMT+01:00) 110
Time Amsterdam, Berlin,
Bern, Rome,
Stockholm, Vienna
Central Europe (GMT+01:00) 95
Standard Time Belgrade,
Bratislava,
Budapest,
Ljubljana, Prague
Romance Standard (GMT+01:00) 105
Time Brussels,
Copenhagen,
Madrid, Paris
Central European (GMT+01:00) 100
Standard Time Sarajevo, Skopje,
Warsaw, Zagreb
W. Central Africa (GMT+01:00) West 113
Standard Time Central Africa
GTB Standard Time (GMT+02:00) 130
Athens, Istanbul,
Minsk
E. Europe Standard (GMT+02:00) 115
Time Bucharest
Egypt Standard (GMT+02:00) 120
Time Cairo
South Africa (GMT+02:00) 140
Standard Time Harare, Pretoria
FLE Standard Time (GMT+02:00) 125
Helsinki, Kyiv,
1028
Chapter 1
Riga, Sofia, Tallinn,
Vilnius
Israel Standard (GMT+02:00) 135
Time Jerusalem
Jordan Standard (GMT+02:00) -2147483582
Time Amman
Middle East (GMT+02:00) -2147483583
Standard Time Beirut
Namibia Standard (GMT+02:00) -2147483578
Time Windhoek
Arabic Standard (GMT+03:00) 158
Time Baghdad
Arab Standard Time (GMT+03:00) 150
Kuwait, Riyadh
Russian Standard (GMT+03:00) 145
Time Moscow, St.
Petersburg,
Volgograd
E. Africa Standard (GMT+03:00) 155
Time Nairobi
Georgian Standard (GMT+03:00) -2147483577
Time Tbilisi
Iran Standard Time (GMT+03:30) 160
Tehran
Arabian Standard (GMT+04:00) Abu 165
Time Dhabi, Muscat
Caucasus Standard (GMT+04:00) 170
Time Baku, Tbilisi,
Yerevan
Azerbaijan (GMT+04:00) Baku -2147483584
Standard Time
Mauritius Standard (GMT+04:00) Port -2147483569
Time Louis
Armenian Standard (GMT+04:00) -2147483574
Time Yerevan
Afghanistan (GMT+04:30) 175
Standard Time Kabul
Ekaterinburg (GMT+05:00) 180
Standard Time Ekaterinburg
West Asia Standard (GMT+05:00) 185
Time Islamabad, Karachi,
Tashkent
Pakistan Standard GMT+05:00) -2147483570
Time Islamabad, Karachi
India Standard Time (GMT+05:30) 190
Chennai, Kolkata,
Mumbai, New
Delhi
Nepal Standard (GMT+05:45) 193
Time Kathmandu
1029
Base Professional
N. Central Asia (GMT+06:00) 201
Standard Time Almaty,
Novosibirsk
Central Asia (GMT+06:00) 195
Standard Time Astana, Dhaka
Sri Lanka Standard (GMT+06:00) Sri 200
Time Jayawardenepura
Myanmar Standard (GMT+06:30) 203
Time Rangoon
SE Asia Standard (GMT+07:00) 205
Time Bangkok, Hanoi,
Jakarta
North Asia Standard (GMT+07:00) 207
Time Krasnoyarsk
China Standard (GMT+08:00) 210
Time Beijing, Chongqing,
Hong Kong,
Urumqi
North Asia East (GMT+08:00) 227
Standard Time Irkutsk, Ulaan
Bataar
Singapore Standard (GMT+08:00) 215
Time Kuala Lumpur,
Singapore
W. Australia (GMT+08:00) Perth 225
Standard Time
Taipei Standard (GMT+08:00) 220
Time Taipei
Tokyo Standard (GMT+09:00) 235
Time Osaka, Sapporo,
Tokyo
Korea Standard (GMT+09:00) 230
Time Seoul
Yakutsk Standard (GMT+09:00) 240
Time Yakutsk
Cen. Australia (GMT+09:30) 250
Standard Time Adelaide
AUS Central (GMT+09:30) 245
Standard Time Darwin
E. Australia (GMT+10:00) 260
Standard Time Brisbane
AUS Eastern (GMT+10:00) 255
Standard Time Canberra,
Melbourne, Sydney
West Pacific (GMT+10:00) 275
Standard Time Guam, Port
Moresby
Tasmania Standard (GMT+10:00) 265
Time Hobart
Vladivostok (GMT+10:00) 270
Standard Time Vladivostok
1030
Chapter 1
Central Pacific (GMT+11:00) 280
Standard Time Magadan, Solomon
Is., New Caledonia
New Zealand (GMT+12:00) 290
Standard Time Auckland,
Wellington
Fiji Standard Time (GMT+12:00) 285
Fiji, Kamchatka,
Marshall Is.
Tonga Standard (GMT+13:00) 300
Time Nuku’alofa
Azores Standard (GMT-01:00) 80
Time Azores
Cape Verde (GMT-01:00) Cape 83
Standard Time Verde Is.
Mid-Atlantic (GMT-02:00) 75
Standard Time Mid-Atlantic
Argentina Standard (GMT-03:00) -2147483572
Time Buenos Aires
E. South America (GMT-03:00) 65
Standard Time Brasilia
SA Eastern (GMT-03:00) 70
Standard Time Buenos Aires,
Georgetown
Greenland Standard (GMT-03:00) 73
Time Greenland
Montevideo (GMT-03:00) -2147483575
Standard Time Montevideo
Newfoundland (GMT-03:30) 60
Standard Time Newfoundland
Atlantic Standard (GMT-04:00) 50
Time Atlantic Time
(Canada)
Central Brazilian (GMT-04:00) -2147483576
Standard Time Manaus
SA Western (GMT-04:00) 55
Standard Time Caracas, La Paz
Pacific SA Standard (GMT-04:00) 56
Time Santiago
Venezuela Standard (GMT-04:30) -2147483573
Time Caracas
SA Pacific Standard (GMT-05:00) 45
Time Bogota, Lima,
Quito
Eastern Standard (GMT-05:00) 35
Time Eastern Time (US
and Canada)
US Eastern (GMT-05:00) 40
Standard Time Indiana (East)
Central America (GMT-06:00) 33
Standard Time Central America
1031
Base Professional
Central Standard (GMT-06:00) 20
Time Central Time (US,
Canada)
Central Standard (GMT-06:00) -2147483581
Time (Mexico) Guadalajara,
Mexico City,
Monterrey
Mexico Standard (GMT-06:00) 30
Time Guadalajara,
Mexico City,
Monterrey - Old
Canada Central (GMT-06:00) 25
Standard Time Saskatchewan
US Mountain (GMT-07:00) 15
Standard Time Arizona
Mexico Standard (GMT-07:00) 13
Time 2 Chihuahua, La Paz,
Mazatlan - Old
Mountain Standard (GMT-07:00) 10
Time Mountain Time
(US, Canada)
Mountain Standard (GMT-07:00) -2147483580
Time (Mexico) Chihuahua, La Paz,
Mazatlan
Pacific Standard (GMT-08:00) 4
Time Pacific Time (US,
Canada), Tijuana
Pacific Standard (GMT-08:00) -2147483579
Time (Mexico) Tijuana, Baja
California
Alaskan Standard (GMT-09:00) 3
Time Alaska
Hawaiian Standard (GMT-10:00) 2
Time Hawaii
Samoa Standard (GMT-11:00) 1
Time Midway Island,
Samoa
Dateline Standard (GMT-12:00) 0
Time International Date
Line West
If you leave this field blank, IBM® SPSS® Data

Collection Interviewer Server will ignore time
zones and calling times when selecting records for
interviewers to call.
WeekdayStart The earliest time at which participants may be
called on weekdays.
WeekdayEnd The latest time at which participants may be called
on weekdays.
WeekendStart The earliest time at which participants may be
called at weekends.
1032
Chapter 1
WeekendEnd The latest time at which participants may be called
at weekends.
By default, a weekend runs from 00:01 on Saturday
to midnight on Sunday. Regional differences in the
definition of weekdays and weekends can be dealt
with in the Sample Management script.
UseInterviewerQualificationsUse interviewer Whether or not to assign calls to interviewers based
qualifications on interviewer qualifications. For example, if the
participant’s native language is Spanish, then assign
the call to a Spanish speaking interviewer.
When you have respondents in more than one time zone or in a time zone that differs from the
time zone in which interviewers are located, you can specify each respondent’s time zone in the
TimeZone field in the sample record. If you want interviewers to be able to arrange appointments,
then you must ensure that this field contains a non-null value. It therefore important that you set a
non-null default TimeZone when loading sample records if you want appointments to be made.
This happens automatically if you create sample tables using the Participants activity, but if
you create the sample tables manually it is your responsibility to ensure that the default for the
TimeZone field is not null.
The value that you enter in this field must be the index of the time zone in the list of time zones
stored in the registry. The default is the local Windows server’s time zone setting. This will be used
if the TimeZone field is empty or undefined, or if there is a problem reading from the field. When
interviewers are presented with the appointment setting page, the time zone field will show the
respondent’s time zone as a text. Internally, all time zone handling is performed using UTC times.
The list of time zones held in the registry is as follows:
Greenwich Standard Time (GMT) Casablanca, Monrovia 90
GMT Standard Time (GMT) Greenwich Mean Time 85
: Dublin, Edinburgh, Lisbon,
London
Morocco Standard Time (GMT) Casablanca -2147483571
W. Europe Standard Time (GMT+01:00) Amsterdam, 110
Berlin, Bern, Rome, Stockholm,
Vienna
Central Europe Standard Time (GMT+01:00) Belgrade, 95
Bratislava, Budapest, Ljubljana,
Prague
Romance Standard Time (GMT+01:00) Brussels, 105
Copenhagen, Madrid, Paris
Central European Standard Time (GMT+01:00) Sarajevo, Skopje, 100
Warsaw, Zagreb
W. Central Africa Standard Time (GMT+01:00) West Central 113
Africa
GTB Standard Time (GMT+02:00) Athens, Istanbul, 130
Minsk
E. Europe Standard Time (GMT+02:00) Bucharest 115
1033
Base Professional

Egypt Standard Time (GMT+02:00) Cairo 120
South Africa Standard Time (GMT+02:00) Harare, Pretoria 140
FLE Standard Time (GMT+02:00) Helsinki, Kyiv, 125
Riga, Sofia, Tallinn, Vilnius
Israel Standard Time (GMT+02:00) Jerusalem 135
Jordan Standard Time (GMT+02:00) Amman -2147483582
Middle East Standard Time (GMT+02:00) Beirut -2147483583
Namibia Standard Time (GMT+02:00) Windhoek -2147483578
Arabic Standard Time (GMT+03:00) Baghdad 158
Arab Standard Time (GMT+03:00) Kuwait, Riyadh 150
Russian Standard Time (GMT+03:00) Moscow, St. 145
Petersburg, Volgograd
E. Africa Standard Time (GMT+03:00) Nairobi 155
Georgian Standard Time (GMT+03:00) Tbilisi -2147483577
Iran Standard Time (GMT+03:30) Tehran 160
Arabian Standard Time (GMT+04:00) Abu Dhabi, 165
Muscat
Caucasus Standard Time (GMT+04:00) Baku, Tbilisi, 170
Yerevan
Azerbaijan Standard Time (GMT+04:00) Baku -2147483584
Mauritius Standard Time (GMT+04:00) Port Louis -2147483569
Armenian Standard Time (GMT+04:00) Yerevan -2147483574
Afghanistan Standard Time (GMT+04:30) Kabul 175
Ekaterinburg Standard Time (GMT+05:00) Ekaterinburg 180
West Asia Standard Time (GMT+05:00) Islamabad, 185
Karachi, Tashkent
Pakistan Standard Time GMT+05:00) Islamabad, Karachi -2147483570
India Standard Time (GMT+05:30) Chennai, Kolkata, 190
Mumbai, New Delhi
Nepal Standard Time (GMT+05:45) Kathmandu 193
N. Central Asia Standard Time (GMT+06:00) Almaty, 201
Novosibirsk
Central Asia Standard Time (GMT+06:00) Astana, Dhaka 195
Sri Lanka Standard Time (GMT+06:00) Sri 200
Jayawardenepura
Myanmar Standard Time (GMT+06:30) Rangoon 203
SE Asia Standard Time (GMT+07:00) Bangkok, Hanoi, 205
Jakarta
North Asia Standard Time (GMT+07:00) Krasnoyarsk 207
China Standard Time (GMT+08:00) Beijing, 210
Chongqing, Hong Kong, Urumqi
North Asia East Standard Time (GMT+08:00) Irkutsk, Ulaan 227
Bataar
Singapore Standard Time (GMT+08:00) Kuala Lumpur, 215
Singapore
W. Australia Standard Time (GMT+08:00) Perth 225
Taipei Standard Time (GMT+08:00) Taipei 220
1034
Chapter 1

Tokyo Standard Time (GMT+09:00) Osaka, Sapporo, 235
Tokyo
Korea Standard Time (GMT+09:00) Seoul 230
Yakutsk Standard Time (GMT+09:00) Yakutsk 240
Cen. Australia Standard Time (GMT+09:30) Adelaide 250
AUS Central Standard Time (GMT+09:30) Darwin 245
E. Australia Standard Time (GMT+10:00) Brisbane 260
AUS Eastern Standard Time (GMT+10:00) Canberra, 255
Melbourne, Sydney
West Pacific Standard Time (GMT+10:00) Guam, Port 275
Moresby
Tasmania Standard Time (GMT+10:00) Hobart 265
Vladivostok Standard Time (GMT+10:00) Vladivostok 270
Central Pacific Standard Time (GMT+11:00) Magadan, 280
Solomon Is., New Caledonia
New Zealand Standard Time (GMT+12:00) Auckland, 290
Wellington
Fiji Standard Time (GMT+12:00) Fiji, Kamchatka, 285
Marshall Is.
Tonga Standard Time (GMT+13:00) Nuku’alofa 300
Azores Standard Time (GMT-01:00) Azores 80
Cape Verde Standard Time (GMT-01:00) Cape Verde Is. 83
Mid-Atlantic Standard Time (GMT-02:00) Mid-Atlantic 75
Argentina Standard Time (GMT-03:00) Buenos Aires -2147483572
E. South America Standard Time (GMT-03:00) Brasilia 65
SA Eastern Standard Time (GMT-03:00) Buenos Aires, 70
Georgetown
Greenland Standard Time (GMT-03:00) Greenland 73
Montevideo Standard Time (GMT-03:00) Montevideo -2147483575
Newfoundland Standard Time (GMT-03:30) Newfoundland 60
Atlantic Standard Time (GMT-04:00) Atlantic Time 50
(Canada)
Central Brazilian Standard Time (GMT-04:00) Manaus -2147483576
SA Western Standard Time (GMT-04:00) Caracas, La Paz 55
Pacific SA Standard Time (GMT-04:00) Santiago 56
Venezuela Standard Time (GMT-04:30) Caracas -2147483573
SA Pacific Standard Time (GMT-05:00) Bogota, Lima, 45
Quito
Eastern Standard Time (GMT-05:00) Eastern Time (US 35
and Canada)
US Eastern Standard Time (GMT-05:00) Indiana (East) 40
Central America Standard Time (GMT-06:00) Central America 33
Central Standard Time (GMT-06:00) Central Time (US, 20
Canada)
Central Standard Time (Mexico) (GMT-06:00) Guadalajara, -2147483581
Mexico City, Monterrey
1035
Base Professional

Mexico Standard Time (GMT-06:00) Guadalajara, 30
Mexico City, Monterrey - Old
Canada Central Standard Time (GMT-06:00) Saskatchewan 25
US Mountain Standard Time (GMT-07:00) Arizona 15
Mexico Standard Time 2 (GMT-07:00) Chihuahua, La Paz, 13
Mazatlan - Old
Mountain Standard Time (GMT-07:00) Mountain Time 10
(US, Canada)
Mountain Standard Time (GMT-07:00) Chihuahua, La Paz, -2147483580
(Mexico) Mazatlan
Pacific Standard Time (GMT-08:00) Pacific Time (US, 4
Canada), Tijuana
Pacific Standard Time (Mexico) (GMT-08:00) Tijuana, Baja -2147483579
California
Alaskan Standard Time (GMT-09:00) Alaska 3
Hawaiian Standard Time (GMT-10:00) Hawaii 2
Samoa Standard Time (GMT-11:00) Midway Island, 1
Samoa
Dateline Standard Time (GMT-12:00) International Date 0
Line West
In order for the time zone information in the sample records to be used, the telephone interviewing
supervisor must specify the following details using the Phone Surveys activity:
Time zones present in sample records. Sample records that have no time zone specified or
whose time zone does not match any of those specified for the project will never be used. If
the supervisor does not specify any time zones, then sample management will ignore time
zone and calling time information when selecting records for calling.
Calling times. These are the times at which respondents may be called on weekdays and at
weekends. A single calling period may be defined for weekdays and another for weekends.
The default weekend lasts from 00:01 on Saturday to midnight on Sunday; if certain regions
define weekends differently, you can specify these differences in the sample management
function that checks whether the current day is a weekday or weekend in the current time zone.
When an interviewer requests a record to call, the sample management script should check which
of the project’s time zones are currently within the valid calling times and restrict selections to
records in those time zones only when applying any other record selection criteria.
For example, suppose that interviewers based in time zone 85 (GMT) are calling respondents
in time zones 85 and 110 (Western Europe Standard time, which is one hour ahead of GMT). It
is a weekday, and weekday calling times are 9am to 5pm. If an interviewer requests a record
at 3:30pm, calls may be made to respondents in either time zone, and other factors such as
appointment times and interviewer qualifications will be used to determine which record is
assigned to the interviewer. If the same interviewer requests another record at 4:45pm, all
records for respondents in time zone 110 will be ignored because it is now too late to call those
respondents. Similarly, if an interviewer requests a record at 8:15am, only records in time zone
110 will be available because it is still too early for respondents in time zone 85 to be called.
1036
Chapter 1
Interviewer Qualifications
Interviewer qualifications allow the sample management script to match interviewers to sample
records according to the requirements of the sample record and the interviewers’ abilities.
Common examples are language requirements, where the interviewer needs to be able to speak
the same language as the respondent, and gender requirements, where it is preferable for the
respondent to be called by someone of the same gender. You can also define qualifications that
are related to individual queues so that records in those queues can be allocated to specific
interviewers. A typical example is a refusal converter qualification linked to the REFUSAL queue,
so that records in this queue can be allocated to interviewers who are skilled at persuading reluctant
respondents to be interviewed. Qualifications such as these are usually set as part of interviewers’
user accounts and are made available to the Phone Participants when interviewers start the activity.
Interviewer qualifications can also be used to implement sample segmentation. A typical
example is where sample records are divided by region or some other characteristic, with each
interviewer or group of interviewers being allocated calls to a particular subset of participants. In
this situation, supervisors may ask interviewers to call different subsets of participants at different
times or on different projects, so it is not appropriate to link these qualifications directly to user
accounts. Instead, supervisors configure projects to prompt interviewers for these qualifications
when they start Phone Participants. If the project’s interviewing requirements change so
that, for instance, more calls are required in a particular region, interviewers can change these
qualifications during the course of a session.
Interviewer qualifications are a particular type of user property. They are set up by the DPM
administrator using the User Administration activity. Any permanent qualifications such as
language or refusal conversion skills are allocated to interviewers at this time. Interviewing
supervisors determine which projects will use interviewer qualifications when setting up projects
using Phone Surveys. They also specify which sample segmentation qualifications interviewers
can set on each project.
When setting up qualifications, the DPM administrator specifies a default setting that will be
applied to interviewers who do not have a specific qualification value assigned, and who do not
select any sample segmentation qualifications during their session. With a language qualification,
for example, the default will usually be that the interviewer has no language qualification so will
receive only records that have do not specify a language requirement. With sample segmentation
qualifications, interviewers who do not have a specific qualification for a segment can be assigned
the “Matches any” setting which will allow them to receive all calls for that segment.
The default telephone interviewing sample management script that comes with IBM® SPSS®
Data Collection Interviewer Server recognizes two types of interviewer qualification: those that
are linked to a queue and those that are not. Qualifications related to queues must be called
HandleQueue_QueueName; for example, HandleQueue_REFUSED for the refusal converter
qualification. Queue-related qualifications take precedence over any other qualification that
the intyerviewer has, because the sample management script always checks for this type of
qualification first.
When interviewer qualifications are not related to queues, any columns in the sample table that
will be used in determining which interviewer will call those records must have the same name
as the interviewer qualification. For example, if the interviewer qualification called Language
defines the languages that an interviewer speaks, the column in the sample table that contains the
respondent’s native language must also be called Language.
1037
Base Professional
If you want to base interviewer qualifications on information that is not present in the sample
table, you can create a temporary (virtual) field in the sample table and place the information in
that field so that it becomes available to Interviewer Server. You might do this if you want the
interviewer’s name to be available to the sample management script.
When a project uses interviewer qualifications and an interviewer requests a record to call, the
sample management script proceeds as follows:
1. Does the interviewer have any HandleQueue_QueueName qualification? If so, find a record in
one of those queues.
2. If there are no suitable records or the interviewer does not have a queue-related qualification,
check what other qualifications the interviewer has. Locate a record that requires any of those
qualifications.
3. If there are no records that match the interviewer’s qualifications or the interviewer has no special
qualifications, selects a record that has no qualification requirements.
Authentication of Inbound Respondents
Authentication is the process whereby respondents dialing in to your Web site to take a survey
are validated before an interview begins. You define the validation that is to take place in the
AuthenticateSampleRec function.
A simple scenario would be that the administrator sends to all of the prospective respondents
an e-mail containing an invitation to participate in the survey, an ID, and a password. Before
starting the interview, each respondent must enter his or her ID and password on the authentication
page. When the page is posted, IBM® SPSS® Data Collection Interviewer Server calls the
AuthenticateSampleRec function, which searches the sample table for a record with a
matching ID and password. If a matching record is found, the respondent is authenticated and the
respondent proceeds to the first page of the interview. If there is no matching record, Interviewer
Server displays the authentication-retry page so that the respondent can reenter his or her details.
If the information cannot be authenticated after six attempts, the authentication-failed page is
displayed. In this example, Id and Password are the authentication fields.
Prior to starting the project, the administrator has setup a quota for various characteristics—for
example, 1000 men and 1000 women in three different age groups (18-24, 25-34, and 35-44).
Respondents do not receive a personal invitation but find their way to the interview by following
links on various popular Web sites. The authentication page asks each respondent to enter
various personal details, including his or her age and gender. The AuthenticateSampleRec
function checks the quota for these characteristics. Provided that the quota for the respondent’s
characteristics has not been filled, authentication succeeds, AuthenticateSampleRec creates a
sample record, and the respondent proceeds to the first page of the interview. If the quota has been
filled, the authentication fails and the interview-rejected page is displayed.
1038
Chapter 1
When Does Authentication Take Place?
Authentication is the process whereby respondents are validated before an interview begins.
The authentication process is defined in the AuthenticateSampleRec function in the sample
management script. IBM® SPSS® Data Collection Interviewer Server calls this function:
When the respondent posts the authentication or retry-authentication page.
When an interview is started using the project’s URL and the authentication field(s) are passed
as virtual parameters on the URL. Authentication at this stage is called auto-authentication
and it means that you can restart an interview after it has timed out without redisplaying the
authentication page, provided that the authentication fields are passed as virtual parameters on
the URL.
1039
Base Professional
Figure 1-217
Authentication in sample management flow
Authentication Page
You define the page that is to be used for authentication when you activate the project. IBM®
SPSS® Data Collection Interviewer Server uses this information to display the authentication
page. You can define the authentication page as either an Interviewer Server template or a URL.
However, you are very strongly advised to define authentication pages using templates at all times.
1040
Chapter 1
Template. The template must be an Interviewer Server template. When Interviewer Server displays
an authentication page defined as a template, it automatically inserts questions based on the
authentication fields at the position indicated by the <mrData> tag.
URL. The URL must link to a Web page containing a form that points to Interviewer Server
(mrIWeb.dll). When you define the authentication page as a URL, you can use Common Gateway
Interface (CGI) scripts and active server pages (ASPs). However ,Interviewer Server does not
insert questions based on the authentication fields into the page automatically—you must create
all of the fields on the page yourself. This method is not recommended because it causes a new
skeleton interview to be started each time auto-authentication is run and there is no way of
stopping the skeleton interview if the respondent then fails the authentication process.
Sometimes you may want to ask for additional information (such as age, gender, car owner, etc.).
The recommended way of doing this is to create an additional pre-authentication Web page to ask
this information outside of the Interviewer Server system. When respondents join the interview,
you route them to this page. The page should contain a form that points to Interviewer Server
(mrIWeb.dll) and a hidden field that defines the name of the project. When the respondent clicks
the Submit button, the information he or she has entered is passed to the authentication function.
All of the responses passed to the authentication function are available to the sample
management script in the SampleFields object, and they are copied to the corresponding fields
on the SampleRec object by the AuthenticateSampleRec and AddSampleRec methods.
However, when the SampleRec object is written, the information is stored in the sample table
only if the names of the questions in the HTML form match the names of the columns mapped in
the sample table during activation.
The details of the authentication page are held as interview properties that you can access from
the sample management script. This means that you can change the authentication page that is
to be shown from within the script.
Disabling button double-clicks in the default templates
Survey respondents are often presented the option of logging in to complete surveys. After a
respondent enters a user ID and clicks OK, it can sometimes takes a few seconds for the server
to authenticate the user credentials. If a respondent clicks OK a second time, the server may
generate a message similar to the following:
Thank you for your interest in participating in this survey.
A survey is active for your ID. Please continue the original survey or return in 10 minutes to restart.
You can avoid this by adding the following script to the header tags for all default templates:
<script language="javascript" defer="true">
function addEvent(target, eventName, handlerName)
{
if (target.addEventListener) // W3C
{
target.addEventListener(eventName, handlerName, false);
return true;
}
else if (target.attachEvent) // IE
{
1041
Base Professional
return target.attachEvent("on" + eventName, handlerName);

}
else
{
target["on" + eventName] = handlerName;
}
}
var ctrlNext;
ctrlNext = document.getElementsByName("_NNext")[0];
function NextClicked()
{
if(ctrlNext != null)
{
setTimeout('ctrlNext.disabled = true;', 1);
}
}
addEvent(ctrlNext, 'click', NextClicked);

</script>
The script prevents additional clicks from registering with the server.
Example Template for an Authentication Page
Following is an example of a simple template for an authentication page. This template is

designed to be used in a project that has two authentication fields—Id and Password.
<html>
<head></head>
<body bgcolor=linen>
<h1>ABC Market Research</h1>
<mrData>

<mrNavbar>
</body>
</html>
IBM® SPSS® Data Collection Interviewer Server automatically creates input fields for the two
authentication fields—Id andPassword. Interviewer Server uses thetype=password HTML tag
for authentication fields that are called Password.This means that when a respondent enters his
or her password, the characters are displayed as asterisks (*).
1042
Chapter 1
Figure 1-218
Authentication page in browser
Example ASP for a Pre-Authentication Page
Following is an example of a simple ASP for a pre-authentication page. This page is designed to
be used in a project that has one authentication field—Id—and five additional sample record fields
that are mapped to columns in the sample table—Language, Browser, Queue, Active, and Project.
<%@ Language=VBScript %>

<html>
<head>
<meta name=VI60_defaultClientScript content=JavaScript>
<meta name="GENERATOR" Content="Microsoft FrontPage 4.0">
<%
dim Language, Browser
Language=Request.ServerVariables("HTTP_ACCEPT_LANGUAGE")
Browser=Request.ServerVariables("HTTP_USER_AGENT")
%>
</head>
<body bgColor=linen>
<p>
<hr>
<h1>Survey Authentication</h1>
<p></p>
<form name=EntryForm method=post
action=http://MyServer/mrIWeb/mrIWeb.dll>
<p>Please enter your ID to
proceed <input id=Id name=Id Type=Text></p>
<p><input id=Language type=hidden
Name=Language value=<%=Language%>>
<input id=Browser type=hidden
Name=Browser value=<%=Browser%>></p>
<input type=hidden name=Project value=Example>
<p><input Type=Submit></p>
</form>
</body>
</html>
Notice that the page contains only one visible text input field—for the Id authentication field. The
page has three hidden input fields:
Language and Browser, which collect information about the language and browser used
by the respondent.
Project, which is preset to the name of the project, which in this case isExample.
1043
Base Professional
The information collected in all of these fields (except the Project field) is available to the script as
sample fields and is saved in the sample table when the sample record is written. The Project field
is recognized as a special field by IBM® SPSS® Data Collection Interviewer Server, and it is not
included in the sample fields. The Queue and Active sample fields are internal fields that must not
be collected from the respondent. sample management provides the values for these fields.
A name is not defined for the Submit input field, because we do not want it to be included as a
sample field, and all of the fields that have names are automatically included as sample fields.
Figure 1-219
Authentication page in browser
Authentication Failed
When you activate a project that uses sample management, you can specify:
The Web page that IBM® SPSS® Data Collection Interviewer Server displays when a
respondent fails authentication.
The Web page that Interviewer Server displays when a respondent who failed authentication
attempts authentication again.
The Web page that Interviewer Server displays when authentication rejects a respondent
because, for example, he or she has been rejected by quota control.
Like the authentication page, you can specify these Web pages as Interviewer Server templates
or as URLs. The templates must be Interviewer Server templates, whereas the URLs must
point to a Web page. However, you are strongly recommended to use only templates for the
retry-authentication page. This page works just like the authentication page, and you can
optionally use the same template for both the authentication page and the retry-authentication page.
If you define these pages using Interviewer Server templates, Interviewer Server can insert
some text at a specified position. You define the position using the <mrDisplayText>tag,
and you define the text to be displayed in the Sample Management script using the DisplayText
interview property. This means that you can display different texts in different situations—for
example, explaining why authentication has failed.
The details of the Web pages are held as interview properties and can be accessed from the
sample management script. This means that you can change these details when necessary from
within the script—for example, if you want to display one authentication-failed page when
authentication fails because the respondent enters an incorrect ID and a different one when the
authentication fails because the respondent has already completed the interview.
1044
Chapter 1
By default, a respondent can attempt authentication six times. However, you can optionally
change the number of times a respondent can attempt authentication in the script by setting the
MaxAuthRetriesinterview property. By default, this property is set to 5.
End of Interview
The action that sample management takes when an interview ends is controlled by the
ReturnSampleRec function. When the interview ends in any of the following ways, IBM®
SPSS® Data Collection Interviewer Server calls the ReturnSampleRec function:
The respondent completes the interview.
The respondent stops the interview using the Stop button.
The respondent loses his or her connection or goes to another page.
The interview script forces early termination of the interview.
The administrator stops the interview.
Interviewer Server cannot call the ReturnSampleRec function when the interview is terminated
abnormally through, for example, a serious hardware or software failure or by decision of the
administrator.
By default, Interviewer Server uses two codes to indicate whether the interview was completed
or stopped. However, you can use additional codes from the interview script, and Interviewer
Server sets the TimedOut interview property when an interview times out or the respondent loses
his or her connection or goes to another page.
The ReturnSampleRec function can define different actions for the different types of
interview endings. For example:
Interview completed. The sample record is moved into the COMPLETED queue and written
to the sample table.
Interview stopped or timed out. The sample record is moved into the STOPPED queue and
written to the sample table.
End of Interview Web Pages
When you activate a project that uses sample management for inbound calls, you can define the
Web pages that IBM® SPSS® Data Collection Interviewer Server displays to the respondent at
the end of an interview. You can define each Web page as either a template or a URL:
Completed-interview page. The Web page to be shown when an interview is completed.
Interview-stopped page. The Web page to be shown when:
A respondent stops an interview by clicking the Stop button.
The interview script forces early termination of the interview.
Interviewer Server does not insert any text into the templates for these pages. You must enter
the text yourself.
The details of these pages are held as interview properties that you can access from the
sample management script. However, if you want to change the end of interview Web pages
in the sample management script, youmust do so in theAuthenticateSampleRec function
1045
Base Professional
andnot in theReturnSampleRec function. This is because you cannot be sure that the
ReturnSampleRecfunction will have finished running by the time Interviewer Server displays
the page.
Quotas
You use quotas to define the requirements for the sample in terms of the numbers of respondents
who have certain characteristics or combinations of characteristics, such as, age, gender,
socioeconomic class, type of car owned, and so on.
Sample management quota requirements can be represented as a series of expressions, each of
which defines a particular characteristic or set of characteristics and the number of interviews
required with respondents having those characteristics. For example, if you want to interview 875
men and 875 women, you need two quota expressions, as follows:
gender={male} 875
gender={female} 875
Similarly, quotas based on age and gender could be defined as:

gender={male} And age<=30 350
gender={female} And age<=30 350
gender={male} And age>30 350
gender={female} And age>30 350
You define the quota requirements for projects using the IBM® SPSS® Data Collection Quota
Setup program.
Note:The characteristics on which you base sample management quotas must come either from
the sample records or from information that the respondent enters on a pre-authentication page.
For each quota expression, IBM® SPSS® Data Collection Interviewer Server keeps track of
the following:
Target. The number of respondents required for the expression.
Completed count. The number of respondents who meet the requirements for the expression
and have completed the interview.
Pending count. The number of respondents who meet the requirements for the expression
whose interviews are in progress.
Rollback count. The number of respondents who met the requirements for the expression but
whose interviews were terminated because the respondent also belonged to another quota
whose target had already been met.
The sample management script can check these counts to determine whether an interview should
go ahead.
You can specify in the sample management script when respondents are added to the Pending,
Completed, and Rollback counts. Generally, respondents are added to the Completed count when
they complete a questionnaire. However, you may sometimes want to add respondents when they
are only part-way through the questionnaire.
1046
Chapter 1
Quota control in sample management is just one aspect of the whole Interviewer Server quota
control system. The rest of the system covers quota control in the questionnaire script, where
quotas may be based on answers to questions in the script, or on a combination of script and sample
management data. For example, suppose that you have a panel of respondents who regularly
connect to your Web site to participate in various surveys. Each person’s sample record contains
personal data such as age, gender, and the region in which the respondent lives. For one particular
survey you want to interview only 875 men and 875 women. This information is available to
sample management, so the quota checks can be made in the sample management script.
Another survey requires interviews with 500 male car owners and 500 female car owners. Car
ownership information comes from a question in the interview so the quota control must be
applied within the interview, even though gender is available at the sample management stage.
To find out more about the complete Interviewer Server quota control system see Quota
Controlrefer to the Quota Control topic in the IBM® SPSS® Data Collection Base Professional
section of IBM® SPSS® Data Collection Developer Library.
How to Write a Quota Control System
The basic steps for implementing quota control when a project uses sample management are
as follows:
In AuthenticateSampleRec:
E Attach the sample record to the quota control system.
Note: You must do this even if all quotas are based on data gathered during the interview.
E If the project has quotas that need to be tested before the interview starts, check those quotas and
pend them if the respondent may continue with the interview. If the respondent fails the quota
check, reject the sample record from the authentication process.
In ReturnSampleRec:
E If the sample record is returned with codes 1 (completed) or 6 (early completion), decrement the
pending counts by 1 and increment the corresponding completed counts. For all other return
codes, decrement the pending counts by 1 and increment the corresponding rollback counts.
Attaching the Sample Record
Whenever a project uses sample management and quota control you must attach the sample record
to the quota control system, so that sample management can communicate with quota control once
it receives the sample record back from the interviewing program at the end of the interview. You
do this by placing the following statement at the end of AuthenticateSampleRec once you
have rejected everyone who has failed authentication for any reason not associated with quota
control:
QuotaEngine.AttachRecord(SampleRec)
For further information, refer to the Quota Object Model documentation in the IBM® SPSS®
Data Collection Developer Library.
1047
Base Professional
Processing Records Returned After Interviewing
When a project uses quota control without sample management, IBM® SPSS® Data Collection
Interviewer Server automatically converts pended interviews to completed or rolled back
interviews depending on the results of the quota tests. When a project uses quota control with
sample management, the QuotaAutoCommit property controls what happens to pended quota
cells. If QuotaAutoCommit is True (or 1) then pended quotas either increment the count
of completed interviews or are rolled back; if the property is False (or 0) nothing happens
automatically and all actions must be specified in the sample management script. This applies
even if all quotas are based only on interview data.
QuotaAutoCommit defaults to True, so the processing of pended quotas is dealt with
automatically at the ends of interviews.
Note: QuotaAutoCommit is not added to a project’s properties in DPM when you create a
project, but you may add it afterwards using Edit Project. Refer to “Adding Project Properties”
in the Edit Project section of IBM® SPSS® Data Collection Interviewer Server Administration
User’s Guide for details.
Whenever QuotaAutoCommit is False, you should include statements such as those shown
below in the ReturnSampleRec function in your sample management script.
If (SampleRecReturnCode.Code=1 Or SampleRecReturnCode.Code=6) Then
QuotaEngine.Complete()
Else
QuotaEngine.Rollback()
End If
Using this code, interviews that terminated successfully, either a fully or partially completed
interviews have their pending counts decremented by 1 and their corresponding completed
counts incremented by 1. All other interviews have their pending counts decremented by
1 and their corresponding rollback counts incremented by 1. For further information about
QuotaEngine.Complete and QuotaEngine.Rollback, refer to the Quota Object Model
documentation in the IBM® SPSS® Data Collection Developer Library.
Pending Quota Cells
If you have quotas based on sample management data that you need to check before the interview
starts, place statements such as the following inAuthenticateSampleRec once you have
rejected everyone who has failed authentication for any reason not associated with quota control:
' Pend all relevant quota cells for this respondent
Result=QuotaEngine.Pend()
' Respondent does not belong in any quota cell or
' the target for one or more of the quota cells for
' this respondent has been met.
If (Result And QUOTA_RESULT_WasPended) >< QUOTA_RESULT_WasPended Then
QuotaEngine.Rollback()
InterviewProperties("DisplayText").Value = "Thank you " &_
"for you interest in our survey, but this survey is" &_
"closed for people with your characteristics."
LogMsg = LogStart & "Failed quota control, Not pended."
Log.LogThisEx 21, LogMsg, LOGLEVEL_INFO
' Move sample record into a different queue
Queues.MoveSampleRec "SM_REJECTED", SampleRec
' Release sample record from quota control
Set SampleRec = Nothing
' Authentication fails so reject respondent from survey
AuthenticateSampleRec=REJECT
End If
1048
Chapter 1
This example checks all quotas that exist in the quota database and, as long as none of the targets
has been met, pends all the cells that the respondent belongs to. It does not matter that data
may not be available for all quotas yet—there may be quotas associated with script data, for
example—the quota control system simply ignores cells for which there is no data. Also, it does
not matter if some of the sample data is used in quotas in the questionnaire script. Once a cell
has been pended for a respondent, it is not pended again, so there is no chance of having falsely
inflated pending counts due to respondents being pended twice.
If the respondent fails quota control, an explanatory message is defined for the
authentication-reject page and a message is written to the log file. Then the record is filed in
the SM_REJECTED queue and released from quota control. Finally, the respondent fails
authentication and the message defined earlier is displayed in his or her browser window.
For further information about QuotaEngine.Pend and QuotaEngine.Rollback refer to the
Quota object model documentation in the IBM® SPSS® Data Collection Developer Library.
Checking Quota Return Codes and Other Information
When you pend quotas, the quota control system returns various information about the success or
failure of the request and about the current quota status. You can check this information in your
sample management script by using the following constants:
Constant Description
QUOTA_RESULT_WasPended Cells were pended for this respondent.
QUOTA_RESULT_OverTarget At least one cell for this respondent is over target.
QUOTA_RESULT_BelowTarget At least one cell for this respondent is below its
target.
QUOTA_RESULT_PendingOverTarget Cells for this respondent have been pended but
at least one of them will go over quota if the
respondent successfully completes the interview.
Note: Exactly when these constants are set depends on the quota type. For example, a Normal
quota does not allow an interview to be pended if completing that interview would cause the
target to be exceeded.
The following less commonly used constants are also available for checking the quota type and
how a quota has been defined in IBM® SPSS® Data Collection Quota Setup:
Constant Description
QUOTA_FLAGS_None This is a Normal quota.
QUOTA_FLAGS_AllowOverQuota This quota allows cells to be pended as long as the
target has not been met. If all pended interviews
complete, the target will be exceeded.
QUOTA_FLAGS_Counter This quota counts respondents but does not
implement any quota control.
QUOTA_TYPES_TableQuotas This quota was set up as a Table Quota.
QUOTA_TYPES_ExpressionQuotas This quota was set up as an Expression Quota.
1049
Base Professional
Scripts that Refer to Non-Existent Sample Fields
Sample Management scripts often test the data held in fields in the sample records in order to
determine how the record should be processed. For example, you may want to check whether the
respondent has a Panel Identification code and the take different actions depending on whether or
not this is the case.
The usual way of making this test would be to copy the value of the PanelId sample variable into a
script variable and then to use a pair of If statements to make the test and define the actions
to be taken. For example:
Set myField = SampleFields("PanelId")
LogMsg = LogStart & "Err.Number= & CStr(Err.Number)
If (myField Is Nothing) Then
LogMsg = LogStart & "No Panel Id"
End If
If Not (myField Is Nothing) Then
LogMsg = LogStart & "Record has a Panel Id"
LogMsg = LogStart & "PanelId=" & myField.Value
End If
However, the Is operator cannot be used with Empty and Nothing, so if a sample record has no
PanelId field at all, both tests will fail and you will see the log messages for both tests. This is
because when PanelId does not exist, myField is not initialized so in both cases the next statement
is executed due to the On Error Resume Next.
To avoid this problem, test for an empty object instead. For example:
If IsEmpty(myField) Then
LogMsg = LogStart & "No Panel Id"
End If
If Not (IsEmpty(myField)) Then
LogMsg = LogStart & "Record has a Panel Id"
LogMsg = LogStart & "PanelId=" & myField.Value
End If
Debugging and Testing Scripts
Before you use a sample management script in a live survey, you must test it rigorously to ensure
that it performs as you expect in all situations.
The activation process displays an error message if there is a syntax error in the script.
However, it cannot detect other errors, such as errors in the logic.
Try to think of every possible situation and then run trial interviews to test that the script works
correctly in each situation. Following are some suggestions:
Check that authentication finds the correct sample record when the authentication fields are
entered correctly and, where relevant, that the authentication fails when they are entered
incorrectly. For example, if there are two authentication fields, check what happens when the
respondent enters both correctly, both incorrectly, and one correctly and one incorrectly.
Check that the script creates sample records correctly for new respondents, when relevant.
1050
Chapter 1
Check that the script is handling the serial number correctly by restarting some interviews and
checking whether the correct case data record is retrieved.
Check that the sample records are moved to the appropriate queue at the end of the interview.
Check that all of the fields in the sample table are updated correctly.
If the script is routing respondents to different interviews, set up test interviews to test every
routing possibility.
If you are using custom Web pages—for example, to display different authentication-failed
pages in different situations—set up test interviews to test every possibility.
If the script includes quota control, check that quotas are being pended, completed, and rolled
back correctly, and that respondents who fail quota control are rejected from authentication
and see the interview-rejected page.
When you are debugging scripts, you may find it helpful to use the logging feature to instruct the
script to log each event. This enables you to trace the actions the script takes during the interview.
If you are writing or using sample management scripts written in the IBM® SPSS® Data
Collection scripting language, you can use the debugging framework script to test your script
for errors. For more information, see the topic Debugging IBM SPSS Data Collection Scripts
on p. 1050.
Debugging IBM SPSS Data Collection Scripts
The IBM® SPSS® Data Collection Developer Library installs framework scripts that you can use
for testing and debugging any sample management scripts that you write or customize yourself. In
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Sample Management
– IBM® SPSS® Data Collection script\Debugging you’ll find:
basic_example.mrs. Use this script to debug scripts that cater for inbound calls only (web
interviews).
multimode_example.mrs. Use this script to debug telephone interviewing scripts.
SMDebugging.mrs. This file is included in the other scripts, and contains common helper
functions and other settings. Do not change this file.
The two _example files are designed to be run in IBM® SPSS® Data Collection Base Professional
and mimic the behavior of the interviewing engine that runs interviews in IBM® SPSS® Data
Collection Interviewer Server. Edit one of the files (as described below) so that it refers to your
project and sample management script, and then run it against your project to test that your
script performs as intended.
How to Use the Debugging Framework
E Write or edit your sample management script.
E Create a project and use the Participants activity to upload some sample records.
E Activate the project using a sample management script that you know works. It doesn’t matter
which script this is as you won’t be running interviews using this script. The reason you are
1051
Base Professional
activating the project is to populate the project’s properties and the sample management tables so
that the debugging framework can access them later.
E In [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Sample
Management – Data Collection script\Debugging, make a back-up copy of the debugging script
you want to use.
E Using Base Professional, open the original version of the example script and replace the value
of the PROJECT_NAME constant with the name of your project. A few lines below this is a
#include line that reads a .mrs file. Replace the current name with the name of your sample
management script file. Save your changes.
E Run the example script in Base Professional. Since this script contains a #include statement to
read the script that you want to debug, you can set breakpoints in your script and single-step
through it looking at the parameters that come in from the framework. See Setting Breakpoints
and Stepping Through The Code in the Base Professional section of the Data Collection Developer
Library documentation for details. Test as many paths through your script as possible using
Base Professional.
Use the helper functions in basic_example.mrs and multimode_example.mrs to get some
ideas of what you might try.
Check that the logging (in the output window) is as expected.
Check that the records in the sample table are as expected.
Refer to the comments in the example scripts for tests that you can run to simulate
authenticating and returning records or getting and returning records.
E When you are sure that your sample management script functions as intended, return to IBM®
SPSS® Data Collection Interviewer Server Administration and reactivate your project, this time
using your sample management script.
E Run test interviews.
Standard Scripts
A number of sample management scripts are supplied with IBM® SPSS® Data Collection
Interviewer Server, and these are sufficient for many common scenarios. However, you can create
your own scripts. The easiest way to do this is to make a copy of the standard script that most
closely matches your requirements and to modify the copy as required. Make sure that the scripts
you work on have different names to the standard scripts or are stored in a different location, so
that they are not overwritten when you reinstall Interviewer Server.
Most of the standard scripts are installed into
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Sample
Management – Scripts, but you’ll also find scripts in
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\CATI and
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Quotas. Each script
subfolder contains a ReadMe file that gives step-by-step instructions for setting up and
running the project.
1052
Chapter 1
Scripts in the IBM SPSS Data Collection Sample Management Folder
Sample Management–IBM® SPSS® Data Collection contains subfolders of scripts showing a

variety of sample management facilities. Scripts are as follows:
Basic\basic_sample.mrs
This script is suitable for surveys in which a sample record already exists for each respondent and
in which respondents cannot respond to the interview after they have completed it.
This script requires a sample record field called Serial to be mapped to a column in the sample
table.
AuthenticateSampleRec rejects respondents whose authentication fields do not match a
record in the sample table and respondents who are in the sample table but who are in the
COMPLETED queue. In other words, the only respondents it accepts are those who are in the
sample table but who have not already completed the interview.
ReturnSampleRec moves the sample record into the COMPLETED, STOPPED, and
TIMED_OUT queues on the basis of the standard SampleRecReturnCode values of 1 and 2
and the TimedOut interview property. When other SampleRecReturnCode values are used
in the interview script, the record is moved into a queue with the name SIGNAL_n, where n is
the value of the SampleRecReturnCode.
ReturnSampleRec saves the respondent’s serial number in the sample table for use if the
respondent restarts the interview. AuthenticateSampleRec passes the serial number in
the sample table to IBM® SPSS® Data Collection Interviewer Server for interviews that are
restarted. Interviewer Server assigns a new serial number to new interviews.
basic_sample.mrs uses the same include files as multimode1_sample.mrs (Constants.mrs,
MainFunctions.mrs, and HelperFunctions.mrs). The #define INCLUDE_TELEPHONE property
is used to remove script parts that are not useful for Web-only interviewing.
basic_sample.mrs is a pared-down version of multimode1_sample.mrs. Customization
opportunities include the following, and can be documented the same as in
multimode1_sample.mrs:
– AuthenticateSampleRec_ClientSpecific
– RejectRecord_ClientSpecific - OverQuota reason but not Expired reason
– ReturnSampleRec_DCCodes_ClientSpecific
– ReturnSampleRec_ClientCodes_ClientSpecific
HTTP Variables\httpvar_sample.mrs
This script is designed for use with the sample httpvar.asp pre-authentication page, which collects
HTTP variable values. This script requires various sample record fields to be mapped to columns
in the sample table — Serial, Language, Browser, Server_Name, http_cookie, Remote_Address
— in addition to the standard required fields.
1053
Base Professional
Sample Fields\smvar_sample.mrs
This script provides an example of a sample management script that can be used to extract
information from the sample record for use in the interview, and to pass back data for storing
in the sample record.
addrandom_sample.mrs
This script can be used to create sample records for testing. It is designed for use in a project that
has one authentication field — Id — and an authentication page that does not collect the ID.
AuthenticateSampleRec generates an ID for the sample record using the RandomPassword
function and adds the record to the sample table. This script does not handle the serial number for
restarting interviews. When starting an interview in a project that uses this script, you need to pass
the Id authentication field as a virtual parameter on the URL to force auto-authentication to take
place. You can use this script to load test your sample management script.
repeat_sample.mrs
This script is similar to the “ “basic” script except that it accepts respondents who have already
completed the interview. The serial number saved in the sample record is not reused for these
respondents, and Interviewer Server assigns them a new serial number.
Scripts in the Quotas Folder
The Quotas folder contains Sample Management scripts for use with projects that use quota
control. The quotas may be based on questionnaire data, sample data, or a combination of both.
Scripts are as follows.
Basic\basic_sample.mrs
This script is suitable for use with projects that require basic quota control as part of the
authentication process and/or quota control within the questionnaire.
The example requires four quotas. The quotas for car ownership and internet access are Table
Quotas based on questions in the questionnaire; the quotas for age are Expression Quotas
based on data in each respondent’s sample record, with one expression for respondents who
are younger than 35 years of age and another for respondents who are aged 35 or older.
AuthenticateSampleRec attaches the sample record to the quota control system, tests
quotas and pends all cells that apply to the respondent. Because only age is available at this
point, only the appropriate age quota is pended. Respondents whose age quota is full and
respondents who do not belong in any of the quotas fail the quota check and the appropriate
pending counts are rolled back. These records are moved into the SM_REJECTED queue and
the link to quota control is broken.
1054
Chapter 1
Respondents who pass the sample management quota check also pass authentication and
proceed with the interview, where the other quota checks are made.
ReturnSampleRec tests the return code for each interview. If a respondent completes an
interview (return codes 1 or 6), then any pending counts for that respondent are converted into
completed counts. If an interview is returned with any other return code, it fails quota control
and the pending counts for that interview are converted into rollbacks.
LeastFull\LeastFullQuota.mdd
This script uses the “least full” quota feature to choose the two responses whose quota cells are the
least full from the set of responses that the respondent chooses. For example, if the respondent
chooses tea, coffee, and milk, and the tea quota has the greatest percentage of completed
interviews of those three categories, then only the coffee and milk quotas will be pended for that
interview. The remaining questions in the script are asked only for the responses that have been
pended. If a respondent does not belong in any of the quota controlled cells or chooses only
responses whose quotas have been filled, the interview is terminated.
Simple\SimpleQuota.mdd
This script illustrates how to pend a specific quota by name.
Scripts in the CATI Folder
The CATI folder contains sample management scripts for use with outbound telephone
interviewing projects.
Multimode1\multimode1_sample.mrs
This script is suitable for projects that allow a combination of inbound calling for self-completion
interviews and outbound telephone interviewing for interviews conducted by interviewers. The
script also supports autodialing for outbound interviewing.
The script is a client specific framework script that includes the functions most likely to require
modification for client specific processing and stub functions to support additional client specific
processing. The script includes the following IBM support scripts that are located in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Interview\Sample Management –
Scripts\Debugging folder:
Constants.mrs - Defines all constants used in the script. Misspelled constants are caught
during the parsing phase while misspelled queues, fields, and properties are not caught until
execution.
MainFunctions.mrs - Contains the main entry points for sample management (GetSampleRec,
AuthenticateSampleRec, and ReturnSampleRec).
HelperFunctions.mrs - Contains all helper functions.
Notes
– The above scripts are preprocessed into one script during activation.
1055
Base Professional
– All three scripts are shared with basic_sample.mrs script. As a result, the scripts include a
#define INCLUDE_TELEPHONE property that removes code that is not required in the shared
files.
Customization opportunities
You can modify any of the scripts, but updating to the latest IBM® SPSS® Data Collection
software version will be easier when modifications are restricted to the multimode1_sample.mrs
script. New features can be utilized by directly incorporating the support scripts and merging
only the client-specific script.
The following functions, and stub functions, are available for customization:
GetSampleRec_ClientSpecific - Gets records from client specific queues.
GetWhereClause_ClientSpecific - Provides a client specific WHERE clause, to be used in
addition to the system WHERE clause, when scanning the APPOINTMENT, RECALL,
or FRESH queues.
HandleThisInterviewerQualificationsQueue_ClientSpecific - Returns True if the client would
like to handle a specific interviewer qualification queue.
HandleQueueBasedInterviewerQualifications_ClientSpecific - Called if the above returns True
and allows the client to specify WHERE and ORDER BY clauses when scanning a particular
interviewer qualification queue.
HandleSpecificRequests_ClientSpecific - Allows the client to change which queues are
acceptable for HandleSpecificRequests and change the DisplayText when a record is not found.
CheckForPreview_ClientSpecific - Checks client specific preview criteria and returns True if
the record should be previewed by the interviewer before dialing.
AuthenticateSampleRec_ClientSpecific - Called if standard authenticate checks fail to allow the
client to create a new sample record (if required).
IncrementTries_ClientSpecific - Allows the client to modify existing TryCount rules and/or
add new rules.
RejectRecord_ClientSpecific - Allows the client to process rejected samples based on specific
rejection reasons (for example when records are rejected due to being past the expiration time,
not passing Quota, and so on). The client can write a history record based on the reason for
a record’s rejection.
When a survey is run against an Expired sample, a new IVW log entry is created (for
example, RejectRecord_ClientSpecific, Reason: Expired); when a survey is run against
an OverQuota sample in a Quota project, a new IVW log entry is created (for example,
RejectRecord_ClientSpecific, Reason: OverQuota). In both cases, the user is not provided the
true reason behind the rejected sample (they will instead receive a message such as Thank
you for your interest in the survey. This survey is closed for respondents matching your
characteristics). Refer to the IVW log file for more information on the rejection reasons.
ReturnSampleRec_DCCodes_ClientSpecific - Handles IBM® SPSS® Data Collection
Interviewer Server return codes/call outcomes. Modify if different handling is required.
ReturnSampleRec_ClientCodes_ClientSpecific - Handles new client specific return codes/call
outcomes.
1056
Chapter 1
Recall_ClientSpecific - Processes recalls. Modify if different processing is required.

GetCATIParamDefault_ClientSpecific - Sets defaults for any client specific CATI parameters.
These defaults will be used if the CATIParameter does not exist in DPM.
Number Selection Rules
It could prove helpful to familiarize yourself with the interface to the IBM® SPSS® Data
Collection Dialer described in the topic . The system supports extension dialing where the dialer
dials one number on demand for each extension (also known as power dialing), and group
dialing where interviewers are allocated into groups and the dialer dials numbers for the group
as a whole. Predictive dialing is a form of group dialing where several calls are made for each
interviewer in the group on the assumption that not all calls will result in connections. The system
also supports preview dialing while group dialing. This requires a record to be returned to the
interviewer without dialing (so that the record can be previewed). The record is then extension
dialed, allowing it to be returned to the previewing interviewer.
To support preview dialing, Interviewer Server retrieves records from sample management
as follows:
1. GetSampleRec is called to return a single preview record for an interviewer.
2. If the record that is returned requires preview, it is returned immediately to the interviewer to be
previewed and then extension dialed.
3. If the record does not require preview, it is used for group dialing (this is done to minimize the
number of calls to GetSampleRec by the group dial process).
4. If additional records are required by group dialing, GetSampleRec is again called. On this second
call, the Interviewer Server may request the sample management script retrieve multiple sample
records to return the number of records required for the group (as determined by the predictive
algorithm). The GroupDial property is used to ensure that preview records are not returned.
The GetSampleRec function selects records to pass to interviewers for calling in the
following order of priority: appointments, recalls (busy or no-answer callbacks, for example),
new numbers. Supervisors can use the Phone Surveys activity to give new numbers priority
over recalls.
Appointments are agreements that an interviewer makes with a respondent during the initial
contact. Appointments may also be arranged to continue an interview. If the current time is
between AppointmentMarginBefore minutes before and AppointmentMarginAfter
minutes after the record’s AppointmentTime, and the interviewer requesting a record is
the same as the interviewer who made the previous call, then the record is chosen. If it is a
different interviewer, sample management searches for a different record. Once a record
has an appointment time outside the AppointmentMarginAfter boundary, it may be
given to any interviewer. Appointments are returned sorted by appointment time from
the APPOINTMENT queue so that the first appointment chronologically is chosen. If an
appointment is missed, it is called as soon as it can be retrieved.
Appointments to recall a number are made automatically by the script for numbers that are
busy, unanswered or answered by an answering machine. Recalls are considered suitable for
calling up to RecallMarginBefore minutes before and RecallMarginAfter minutes
1057
Base Professional
after the RecallTime stored in the sample record. Recalls are returned sorted by recall time
from the RECALL queue.
If no appointments are due, the script looks for the next unused number in the FRESH queue.
Telephone Interviewing Parameters
The script takes account of any telephone interviewing parameters that have been set using the
Phone Surveys activity in IBM® SPSS® Data Collection Interviewer Server Administration.
This is how supervisors may alter the workings of the sample management script.
If PrioritizeRecalls is True (the default) then Recalls take priority over Fresh records as
described above. If PrioritizeRecalls is False, then Fresh records take priority over
Recalls.
Note: Prioritizing recalls to less than 100% is the best option for reducing clumping. However,
if there are no yet any FRESH records, randomizing the recall times can reduce the clumping
of recalls after the first clump in a shift or daypart. The multimode1_sample.mrs script
randomizes the recall time around the specified delay (using the specified before a recall time
as the margin, and adjusting that recall time between 2 and 10 minutes as the recall time
after). For example, when the busy delay is 30 minutes and the before a recall time is 10
minutes, numbers will be recalled between 20 and 40 minutes from their return time.
If WebCallbackDelay is set to a nonzero value (the default is zero), then interviews started
via the Web with a PhoneNumber will be called. The script checks for these records
after checking for recalls. Web interviews are returned sorted by ReturnTime from the
TIMEDOUT, STOPPED, or TRANSFER TO WEB queues.
The maximum number of times a record can be called is held in MaxTries. If an Appointment
is made, then an additional MaxTries tries can be made to connect the appointment.
If UseInterviewerQualifications is set to True via the Phone Surveys activity, then
any interviewer qualifications of the form HandleQueue_QueueName are handled first. This
means that if an interviewer has HandleQueue_QueueName=True, then the named queue
should be searched before any other queues.
Time Zones. The time zone, valid participant calling times, and day parts setup (if applicable) that
the supervisor sets in Phone Surveys are passed to the script in the CATIParameters property
collection. The script creates an SQL WHERE clause based on these properties and the current
time and passes the clause to the searches of the queues. For example, if the supervisor enters
four respondent time zones in the Time Zone field and only two are valid based on the current
day, time, and allowed calling period, then the two valid time zones are specified on the WHERE
clause. If the Time Zone field is empty, and day parts are not being used, time zone checking is
disabled and any respondent can be called. If day parts are in use, all time zones are checked. This
can result in long WHERE clauses so it is best to specify time zones whenever possible.
Interviewer Qualifications. A UserProperties property collection is available to the script in the
same way as the InterviewProperties and CATIParameters properties. If user properties have been
set up for the CATIinterviewer role in the Users activity, the UserProperties collection will contain
1058
Chapter 1
an InterviewerQualifications property collection. (The role and property collection names

are currently hard-coded.) The script handles two types of InterviewerQualification:
Queue-related qualification properties of the form HandleQueue_QUEUENAME indicate that
the interviewer receive records that have been moved to the named queue. Queues named in
this way are searched before all other queues.
Qualifications where the qualification name matches the name of a field in the sample
record. If a match is found, the script creates a WHERE clause based on the contents
of the InterviewerQualification. For example, if the interviewer has the qualification
Language={English, French}, the following WHERE clause will be added to the searches
of the queues: WHERE (Language IS NULL) OR (Language='English') OR
(Language='French'). This means that the interviewer will receive records where the
language field contains English or French, or is blank.
Call Outcomes
ReturnSampleRec defines the call outcome rules which specify what should happen to a
record once the call has been made.
The call outcome that the interviewer chooses is stored in the CallOutcome field in the
sample record. This is passed into ReturnSampleRec as a ReturnCode.
If the respondent has arranged a callback time, the interviewer sets the AppointmentTime
and the record goes to the APPOINTMENT queue.
Calls whose outcomes are Busy, NoAnswer, or AnswerMachine are scheduled for recall. They
are placed in the RECALL queue with the RecallTime set using the appropriate telephone
interviewing parameter (for example, BusyDelay for Busy numbers). Records that have
passed the maximum tries are moved to the MAX_TRIES queue.
Interviews that are completed successfully go in the COMPLETED queue.
Unusable numbers such as fax, disconnected, refused, and language problems go in the
UNUSABLE queue.
Call outcomes of Completed, Stopped and OverQuota are also possible but cannot be not set
by the interviewer. Completed interviews are sent to the COMPLETED queue. Stopped
interviews are sent to the STOPPED or TIMEDOUT queue depending on the value of the
TimedOut interview property. Interviews that are terminated by a signal statement in the
questionnaire script are sent to the OVERQUOTA queue if the signal is 5. Otherwise they
are sent to the UNUSABLE queue. The value of the signal is stored in the respondent’s
data record.
Call result codes returned by the dialer after making a call are mapped to sample management
call outcomes. The call outcomes for the result codes generally place records in the
UNUSABLE, CHECK NUMBER, or RECALL queues depending on the result of the call.
For example, the NETWORKBUSY call outcome is used when the dialer is unable to place
a call because the telephone network is busy. The sample record is placed in the RECALL
queue and is scheduled for calling in one minute’s time. If the network is still busy, the
sample record remains in the RECALL queue but is then treated as a No Answer and is
scheduled for recall after the NoAnswerDelay period. Numbers that connect, but cannot be
connected to an extension, are moved to the SILENT queue and must be manually returned to
a dialing queue before re-dialing.
1059
Base Professional
Multimodal Facilities
This script supports calling of timed out and stopped Web (respondent-completed)
interviews. It also allows interviews in any queue other than COMPLETED or OVER
QUOTA to be started or restarted as self-completion interviews. This is handled in the
AuthenticateSampleRec function.
The SMRecordsRequired property
When group dialing, the predictive algorithm will calculate the number of additional records
required and pass this to the sample management script in the SMRecordsRequired
property. The sample management script will then attempt to retrieve the defined number of
records. The script may return fewer records, as it returns records from only one queue, and
may not find the required number of records in one of the initial queues.
The MaxRecordsInBatch property
Defines the maximum number of records to pass to the sample management script. The
maximum value defaults to 25 when the property is not defined. The SMRecordsRequired
property is set as the batch size if its value is greater than NumSampleRecsInBatch with a
maximum value as defined by the MaxRecordsInBatch property value.
The NumSampleRecsInBatch constant
When scanning queues for an appropriate record to call, NumSampleRecsInBatch number
of records that match the selection criteria are returned. Each of these records is checked and,
if appropriate, locked and returned for dialing.
NumSampleRecsInBatch should be set to the smallest number that will have a high
percentage likelihood of getting a record in the first batch. To produce a suitable number,
calculate the maximum number of clients that could be attempting to request records for a
single project at one time. This will equal the number of interviewer session engines times the
number of projects that share the sample management table. For example, five interviewer
session engines times one project using the Sample table gives an answer of 5. This script
uses a default of 5.
The ProjectTimeout constant
Telephone interviews that time out cannot currently be restarted except by retrieving the
sample record. It is therefore suggested that telephone interviewing projects reset the default
time-out of five minutes to a higher value. This script uses a default of 20 minutes.
GetSampleRec Function. This function is called by the telephone interviewing activity to select a
sample record for calling. The function supports the retrieval of multiple records. The following
flowcharts illustrate the function’s logic. Separate flowcharts are provided for the blue-shaded
items. Purple-shaded items, with dotted outlines, indicate client modifiable functions or stubs.
1060
Chapter 1
Figure 1-220
GetSampleRec function flowchart
Create
Create Create Create Merge all Create
Prioritization
TimeZone InterviewerQualifications GroupDial to create Main Override
WHERE / ORDER
WHERE clause WHERE clause WHERE clause WHERE clause WHERE clause
BY clauses
Override set?
Yes
Handle
Record
No appointments
found
with Override
No record found
Handle Record
appointments found
No record found
Override set?
Prepare
record(s) for use
and return it
Yes
HandleQueues
No Record
WHERE clause includes
found
Override
No record found
HandleQueues Record
Main WHERE clause only found
No record found
Return
NO_RECORDS
Handle appointments and callbacks

1061
Base Professional
Figure 1-221
Appointments and callbacks flowchart
Queue = APPOINTMENTS
TimeField = AppointmentTime
Handle appointments BeforeInterval = AppointmentMarginBefore
AfterInterval = AppointmentMarginAfter
AddtlWhere = “”
strWhere =
“((AppointmentTime IS NOT NULL) AND (AppointmentTryCount < MaxTries))
Handle recalls
OR
((AppointmentTime IS NULL) AND (TryCount < MaxTries)))”
Queue = RECALL
TimeField = RecallTime
BeforeInterval = RecallMarginBefore GetRecords
AfterInterval = RecallMarginAfter
AddtlWhere = strWhere
HandleQueues - Scans queues based on priorities. Recalls can be prioritized based on a

requested percentage of FRESH versus RECALL queue.
1062
Chapter 1
Figure 1-222
HandleQueues flowchart
Process
Record
HandleQueue_QueueName
found
interviewer quals
No record found
Record
Prioritize recalls?
found
No
Handle
client specific queues Record
No record found
(GetSampleRec_ found
ClientSpecific)
Yes
Create client specific

GetRecords
WHERE clause for
Queue = FRESH Record
FRESH
No WHERE or found
(GetWhereClause_
ORDER BY clauses
ClientSpecific
Prepare
record(s) for use
and return it
No record found
Handle Web Record

interviews found
No record found

WHERE clause for
Record
RECALL Handle recalls
found
(GetWhereClause_
ClientSpecific
No record found
Record
No Prioritize recalls?
found
Return Yes
NO_RECORDS
Handle
client specific queues
No record found
(GetSampleRec_
ClientSpecific)

GetRecords
WHERE clause for
Queue = FRESH Record
FRESH
No WHERE or found
(GetWhereClause_
ORDER BY clauses
ClientSpecific
No record
found
Handle Web interviews

1063
Base Professional
Figure 1-223
Web interview handling flowchart
WebCallBackDelay
=0
No
WHERE clause =
(ReturnTime <= Now – WebCallBackDelay)
AND
(PhoneNumber IS NOT NULL)
ORDER BY clause =
ReturnTime ASC
GetFirstRecords
Queue = TIMED_OUT Record
Return no record
WHERE clause found
ORDER BY clause
No records found
GetFirstRecords
Queue = STOPPED Record
Return record
WHERE clause found
ORDER BY clause
No records found
GetFirstRecords
Queue =
Record
TRANSFER_TO_WEB
found
WHERE clause
ORDER BY clause
GetRecords - Retrieves unexpired records that pass quota from the specified queue using the
specified WHERE and ORDER BY clauses. When successful, typically returns between 1 and
NumSampleRecsInBatch records. SMRecordsRequired records are not required, which
allows the calling provider to recall GetSampleRec and return records from multiple queues.
1064
Chapter 1
Figure 1-224
GetRecords flowchart
ScanQueue
Queue = Queue passed in
NumSampleRecs in batch = constant
WHERE clause = WHERE clause passed in
ORDER BY clause = ORDER BY clause passed in
Records
returned? No
No
Yes
Remove record Another record Any records in Return record

No Yes
from collection available? collection? collection
Yes No
Yes Max required All records

records reached? locked?
No Yes
Fails
UnlockRecord
LockRecord Attempt 2? Yes Return no records
Succeeds
No
Double
Yes Record expired? NumSampleRecs
in batch
No
Fails Check quota?
Succeeds
Move record to
ACTIVE queue
Check quotas
1065
Base Professional
Figure 1-225
Check quota flowchart
Reviewing
interview? Yes
No
QuotaProjectName Yes
= “”
No
Attach record to
Return True
QuotaEngine
Quota not relevant
or Pended
0 (sample did not fall

QuotaEngine.Pend into a quota cell,
assuming SM quotas
not in effect)
QUOTA_RESULT_WasPended
Move record to
Return False
FAILED_QUOTA
Quota not Pended
queue
Create TimeZone WHERE clause

1066
Chapter 1
Figure 1-226
Create TimeZone WHERE clause flowchart
No Using DayParts? Yes
TimeZones set? TimeZones set? No

Return
No time zone checking No
disabled
Yes Yes Use all time zones
Another TimeZone Return Another TimeZone

No No
available? strTimeZoneWhere available?
Yes Yes No
Weekday or Another DayPart

Weekday weekend? Weekend available?
Yes
OK to call OK to call
respondents in respondents In OK to call
this TimeZone? this TimeZone? respondents In
(WeekdayStart < (WeekendStart < this DayPart in this TimeZone?
CurrentTimeInTimeZone CurrentTimeInTimeZone (DayPartStart <
< WeekdayEnd) < WeekendEnd) CurrentTimeInTimeZone
< DayPartEnd)
Yes Yes
Yes
Add new time zone to Add new day part and

strTimeZoneWhere time zone to
strTimeZoneWhere
WeekdayOrWeekend(Timezone). The Weekday function can be used to retrieve a number

indicating the day of the week. The WeekdayOrWeekend function uses Saturday and Sunday
as weekend days, but can be modified to use the value passed in TimeZone to determine
whether the day is a weekday or weekend in the time zone.
Create InterviewerQualifications WHERE clause. InterviewerQualifications may contain
multiple values formatted as a Categorical. SampleFields will contain only one value. Empty
SampleFields should match any interviewer qualification.
1067
Base Professional
Figure 1-227
Create InterviewerQualifications WHERE clause flowchart
strIntQualsWhere = “”
Check
CATIParameter
False
UseInterviewrQualificati
ons?
True
Create list of
QualificationFields
(fields in both
InterviewerQualifications
and SampleFields)
Another
QualificationField No Return strIntQualsWhere
available?
Yes
Empty
QualificationField.Value
strIntQualsWhere =
strIntQualsWhere + Not empty
AND strQFWhere
Initialize to handle
empty respondent field
strQFWhere =
QualificationField = ”
Another value in
No InterviewerQualifications
for this QualificationField
Yes
strQFWhere = strQFWhere +
OR QualificationField =
Value
HandleQueue_QueueName InterviewerQualifications.
1068
Chapter 1
Figure 1-228
HandleQueue_QueueName InterviewerQualifications
Check
CATIParameter
False
UseInterviewr
Qualifications?
True
Another
HandleQueue_QueueName No Return no record
QualificationField available?
Yes
Empty or False
QualificationField.
Value
True
Does client want to

handle this queue?
(HandleThisInterviewer No
Yes QualificationsQueue_
ClientSpecific)
No records found WHERE clause =

Client empty
Handles this queue
(HandleQueueBased
InterviewerQualifications_
ClientSpecific)
ORDER BY clause
= ReturnTime ASC
GetOneRecord
Queue = QueueName
WHERE clause
Record ORDER BY clause
found
Record
found
Return record
UseThisSampleRecsForCATI.
1069
Base Professional
Figure 1-229
UseThisSampleRecsForCATI flowchart
Another
No
SampleRec?
Yes
Comments or
RequiresManualDial
field set
No
Check
client specific preview
requirements No Appointment? Yes
(CheckForPreview_
ClientSpecific)
Yes
Save DayPart Disable answering
temp field machine detection
Set preview dial
Yes AutoDial = 0
No
Set CallerId Record found

property or with override
sample field
if required
Yes
Set TrunkGroup Save UseOverride

property temp field
if required
SampleResult
Client specific handling .Code =
(UseThisSample SUCCESS
RecForCATI_
ClientSpecific)
Initialize
Serial and Test
sample fields
AuthenticateSampleRec Function. This function is called by the core interviewing component to

authenticate respondent details and to pass the corresponding respondent record to the interviewer.
The AuthenticateSampleRec function implemented in multimode1_sample.mrs is very
similar to the standard version of the function implemented in basic_sample.mrs. You can setup
chaining using constants in the multimode1_sample.mrs script and add their specific processing in
AuthenticateSampleRec_ClientSpecific.
1070
Chapter 1
ReturnSampleRec Function. This function implements the project’s call outcome rules and is called
by the core interviewing component when an interview completes, times out, or is stopped. It is
also called by the telephone interviewing activity when an interviewer chooses a call outcome.
Figure 1-230
ReturnSampleRec flowchart
Save Serial
sample field
Finish quotas
CATI record Yes
Save
CATI specific
sample fields
No
Should the
try counts be
incremented?
Increment the
try counts
(IncrementTries_
ClientSpecific)
Handle Handle
data collection client specific
Unhandled return
return codes Return code return codes
code, move to
(ReturnSampleRec_ not handled (ReturnSampleRec_
UNUSABLE
DCCodes_ ClientCodes_
ClientSpecific) ClientSpecific)
Return code Return code

handled handled
SampleResult
.Code =
SUCCESS
1071
Base Professional
Sample Management Functions
You control the behavior of Sample Management using the following functions in your scripts:
AddSampleRec. Use to create new sample records and place them in the appropriate queue.
AuthenticateSampleRec. Called by IBM® SPSS® Data Collection Interviewer Server
whenever the authentication page is posted during inbound calling. Use to check whether a
respondent is valid.
GetSampleRec. Called by Interviewer Server to select a sample record from a queue for use
in an outbound interview.
ReturnSampleRec. Called by Interviewer Server whenever an interview is ended.
RemoveSampleRec. Use to remove sample records from a queue or from the sample table.
For all of these functions:
All of the parameters are of the Object type.
The return values are the predefined constants SUCCESS, FAILURE, and PARAM_ERROR.
These return values must be set in the function.
The AuthenticateSampleRec function also has a REJECT return value that can be used when
a respondent fails authentication and you do not want to display the retry-authentication page;
for example, because the respondent already has a record in the COMPLETED queue or because
the respondent failed quota control.
The GetSampleRec function also has a NO_RECORDS return value that is set when the ScanQueue
function returns no records.
These functions should start with On Error Resume Next if there is a risk that the script
may cause a Component Object Model (COM) error. For example, when there is no mapped
Serial sample record field, the following statement causes a COM error:
Set myVar=SampleRec.Fields("Serial")
Starting the function with On Error Resume Next stops the function failing when this occurs.
Sample Management also provides the UtcNow function for returning the current time in
UTC format.
AddSampleRec
Use this function to add a new sample record to the sample table. This function is not called by
IBM® SPSS® Data Collection Interviewer Server directly.
Syntax
Function AddSampleRec(SampleFields, SampleRec)
Part Description
SampleFields Input parameter of type SampleFields.
SampleRec Output parameter of type SampleRec. In case of
failure, SampleRec must be set to Nothing within
this function.
1072
Chapter 1
Example
The function in this example creates a new sample record from the sample fields passed to it,
initializes the record by placing it in the first queue (FRESH), and adds the record to the sample
table.
The function calls the Queues.AddSampleRecQueues.AddSampleRec method to create the
new sample record, add it to the FRESH queue, and return the sample record. If the sample record
is added successfully, the function sets the return value to SUCCESS. If it is not added successfully,
the function sets the return value to FAILURE.
Function AddSampleRec(SampleFields, SampleRec)
Set SampleRec = Queues.AddSampleRec("FRESH", SampleFields)
If (SampleRec Is Nothing) Then
AddSampleRec = FAILURE
Else
AddSampleRec = SUCCESS
End If
End Function
Refer to the Sample Management Object Model section of IBM® SPSS® Data Collection
Developer Library for further information about Queues.AddSampleRec.
AuthenticateSampleRec
This function is called by IBM® SPSS® Data Collection Interviewer Server at authentication. For
details about when authentication occurs, see When Does Authentication Take Place?.
Syntax
Function AuthenticateSampleRec(SampleFields, SampleRec)
Part Description
SampleRec Output parameter of type SampleRec. In case of
failure, SampleRec must be set to Nothing within
this function.
Examples
1. The function in this example calls the

Queues.AuthenticateSampleRecQueues.AuthenticateSampleRec method, which looks
in the sample table for a sample record with matching authentication fields. If a matching
record is found, the function sets the return value to SUCCESS and returns the sample record
(SampleRec object). Any sample fields passed in the SampleFields input parameter overwrite the
corresponding sample fields on the returned sample record. If a matching record is not found, the
function sets the return value to FAILURE and returns a SampleRec object with a value of
Nothing. The function does not explicitly need to set the SampleRec object to Nothing
because the Queues.AuthenticateSampleRecQueues.AuthenticateSampleRec method
automatically does this when a matching record is not found.
Set SampleRec = Queues.AuthenticateSampleRec(SampleFields)
If SampleRec Is Nothing Then
1073
Base Professional
AuthenticateSampleRec = FAILURE
Else
AuthenticateSampleRec = SUCCESS
End If
End Function
2. The function in this example calls the

Queues.AuthenticateSampleRecQueues.AuthenticateSampleRec method like the previous
example. However, if a matching record is found, the function performs an additional test.
If the matching sample record is in the COMPLETED queue, the function sets the return
code to REJECT and the SampleRec object to Nothing.
Set SampleRec = Queues.AuthenticateSampleRec(SampleFields)
If SampleRec Is Nothing Then
AuthenticateSampleRec = FAILURE
Else
If SampleRec.Fields("Queue") = "COMPLETED" Then
Set SampleRec = Nothing
AuthenticateSampleRec = REJECT
Else
AuthenticateSampleRec = SUCCESS
End If
End If
End Function
Developer Library for further information about Queues.AuthenticateSampleRec.
GetSampleRec
Use this function to select a sample record from a queue for outbound calling.
Syntax
Function GetSampleRec(SampleFields, SampleRec)
Part Description
SampleRec Output parameter of type SampleRec.
Example
The function in this example searches for a sample record in three stages. It starts by checking
for a previously called record whose appointment time is due. If a suitable record is found, the
function returns this record and sets GetSampleRec to SUCCESS.
If there are no sample records whose appointments are due, the function searches for a
previously called record whose recall time is due. Records with recall times are typically those
that gave a no-answer or busy signal the last time they were called. If a suitable record is found,
the function returns this record and sets GetSampleRec to SUCCESS.
If there are no suitable records whose recall time is due, the function selects the first record
from the FRESH queue. (This queue usually holds records that have not yet been called.) If the
FRESH queue is empty, there are no records available for calling at this point and GetSampleRec
is set to NO_RECORDS.
1074
Chapter 1
Function GetSampleRec(SampleFields, SampleRec)

Set SampleRec = HandleAppointments(LogStart, NumSampleRecsInBatch)
If Not (SampleRec Is Nothing) Then
UseThisSampleRecForCATI LogStart, SampleRec
GetSampleRec = SUCCESS
Exit Function
End If
Set SampleRec = HandleRecalls(LogStart, NumSampleRecsInBatch)

Exit Function
End If
Set SampleRec = GetFirstRecord(LogStart, "FRESH", NumSampleRecsInBatch)

Exit Function
End If
GetSampleRec = NO_RECORDS
End Function
ReturnSampleRec
This function is called by IBM® SPSS® Data Collection Interviewer Server when an interview
ends. Typically, this function places the sample record in the appropriate queue—for example,
STOPPED or COMPLETED.
Syntax
Function ReturnSampleRec(SampleRec, SampleRecReturnCode)
Part Description
SampleRec Input parameter of type SampleRec.
SampleRecReturnCode Input parameter of type SampleRecReturnCode.
Examples
1. The function in this example checks whether the interview was completed or stopped and calls
the Queues.MoveSampleRecQueues.MoveSampleRec method to move the sample record
into the appropriate queue.

If SampleRecReturnCode.Code = 1 Then
Queues.MoveSampleRec "COMPLETED", SampleRec
ReturnSampleRec = SUCCESS
Else
Queues.MoveSampleRec "STOPPED", SampleRec
Else
ReturnSampleRec = FAILURE ' Incorrect return code
End If
End If
End Function
1075
Base Professional
2. Before this function checks whether the interview was completed or stopped, it saves the
respondent’s serial number in the sample record in case the respondent needs to restart the
interview. (Interviewer Server needs the serial number to retrieve the correct case data record
when it restarts an interview.) However, before moving the serial number into the sample record,
the function checks that the sample record has a serial number field (because there would be an
error if it tried to move the serial number into a field that does not exist) and if there is no serial
number field, it logs a warning.
Set SerialField = SampleRec.Fields("Serial")
If (SerialField is Nothing) Then
LogMessage = "ReturnSampleRec: Unable to save serial number"
Log.LogThisEx 1001, LogMessage, LOGLEVEL_WARNING
Else
SampleRec.Fields("Serial").Value = _
InterviewProperties.Item("Serial").Value
End If
Queues.MoveSampleRec "COMPLETED", SampleRec
Else
Queues.MoveSampleRec "STOPPED", SampleRec
Else
ReturnSampleRec = FAILURE ' Incorrect return code
End If
End If
End Function
Developer Library for further information about Queues.MoveSampleRec.
RemoveSampleRec
Use this function to remove a sample record from a queue or from the sample table. This function
is not called by IBM® SPSS® Data Collection Interviewer Server directly.
Syntax
Function RemoveSampleRec(SampleRec)
Part Description
SampleRec Input parameter of type SampleRec.
Examples
1. The function in this example calls the Queues.RemoveSampleRecQueues.RemoveSampleRec
method to remove the sample record from the sample table.
Queues.RemoveSampleRec SampleRec
RemoveSampleRec = SUCCESS
End Function
2. The function in this example calls the Queues.RemoveSampleRecQueues.RemoveSampleRec

method to move the sample record into the DELETED queue rather than removing it from the
sample table.
1076
Chapter 1
Queues.MoveSampleRec "DELETED", SampleRec
RemoveSampleRec = SUCCESS
End Function
Developer Library for further information about Queues.RemoveSampleRec.
UtcNow Function
One of the common tasks in Sample Management scripts for CATI projects is the calculation of
appointment and other callback times. The calculations are all made relative to the current time.
For example, when setting a callback time for a busy number, the calculation may simply add five
or ten minutes to the current time. All times in Sample Management are stored in UTC format, and
you can use the UtcNow function whenever you need to retrieve the current time in this format.
Syntax
UtcNow
Examples
This example shows a subroutine for setting an appointment time. When entering the appointment
time, the interviewer can type “Now” for an immediate appointment or can enter the date and
time that the respondent says. If the interviewer types “Now”, the subroutine uses UtcNow to
find the time now.
Sub SetApptTime(SampleRec, strTimeField, _
strNewStart, strNewInterval, iNewNumber)
Select Case strNewStart
Case "Now"
SampleRec(strTimeField).Value = _
DateAdd(strNewInterval, iNewNumber, UtcNow)
Case Else
SampleRec(strTimeField).Value = _
DateAdd(strNewInterval, iNewNumber, SampleRec(strNewStart).Value)
End Select
End Sub
Another common use of UtcNow is in log messages where you want to record the time at which
the message was written. For example:
LogStart = CreateLogStart + "GetSampleRec: "
LogMsg = LogStart + "Entered, current time (UTC) = " + CStr(UtcNow)
Quota Control
Quotas are a method of controlling the number of people interviewed within a particular group.
You define the requirements for each group and the number of respondents to be interviewed.
Once the requisite number of respondents has been interviewed within a group, any subsequent
interviews with respondents who would be classed in that group will be terminated unless you
specify otherwise.
You can define quotas based on categorical, numeric, text, and Boolean variables.
1077
Base Professional
Quotas based on a single characteristic are known as independent quotas. For example, a
quota for age, or a quota for gender.
Quotas based on more than one characteristic are known as dependent quotas. Examples are a
quota for age and gender combined, or a quota for region and preferred brand combined.
Each independent or dependent quota that you create is unrelated to all other quotas, so two
independent quotas of age and gender are not the same as a dependent quota of age and gender.
How the Quota System Works
The quota system is based on a set of SQL tables that contain the quota definitions, targets, current
cell counts, and other information, and quota statements in the script. Each quota has a unique
name which you use in the script when you want to check that quota specifically. If you do not
name the quota then the interviewing program checks all quotas for which data exists at the current
point in the interview. This allows you maximum flexibility in the way you set up and test quotas.
Keeping Track of Quotas
While interviewing is in progress, IBM® SPSS® Data Collection Interviewer Server maintains
three counts for each cell. The main one is the count of completed interviews in that cell—for
example, the number of completed interviews with women or the number of completed interviews
with people aged 18 to 24. If the number of completed interviews matches the target for that cell,
the interview fails the quota and will be terminated.
The second count, known as the pending count, is the number of interviews currently in
progress in a cell. When the interviewing program reaches a quota testing statement in the script,
it checks which quota cells the respondent belongs to and, if the quotas have not been met,
increments the pending counts for those cells by 1. If the interview later completes successfully
(that is, is not stopped or does not time out), Interviewer Server decrements the pending counts by
one and increments the corresponding completed counts by one.
If the interview belongs to cells whose targets have all been met, the interview fails quota
control and is terminated.
If you are testing more than one quota at a time, and a respondent passes one quota and fails
another, the pending counts for the unfilled cells will be temporarily incremented by 1, and all
counts for the full cells will remain untouched.
Interviews of this type are usually terminated by quota control, although you can choose to flag
them as completed interviews by routing to the end of the script or by terminating them with a
sigCompleted or sigEarlyComplete status if you wish. If you terminate the interview by
quota control, the relevant pending counts are decremented by 1, and the corresponding rollback
counts are incremented. The corresponding completed counts remain unchanged. If you treat
the interview as a successful completion, the pending counts are decremented and the completed
counts are incremented for the quotas that did not fail. The counts for the quotas that were full
remain unchanged.
Pending counts are incremented once per respondent, regardless of the number of times the
quotas are tested. If a respondent snaps back during an interview causing a quota test to be
re-executed, the pending counts are not incremented when the test is executed the second time.
1078
Chapter 1
The third count stored in the cell is the rollback count. This counts the number of times the
pending counts have been rolled back to exclude interviews that have timed out, or that have been
stopped, or that have been terminated because the interview failed another quota that appears later
in the script. While the interview is running, the pending counts for the unfilled cells that the
respondent belongs to are incremented by 1. When the interview ends in an abnormal way, those
pending counts are decremented by 1 and the corresponding rollback counts are incremented by 1.
The interviews are not completed so the completed counts remain unchanged.
The following example illustrates how the pending and rollback counts are maintained. The
metadata section of the script is:
Region "Where do you live?" categorical [1..1]

FailRegion "We have enough people who live in the {#Region}" info;
{Male, Female};
Dim quota_pend_result
Region.Ask()
quota_pend_result = QuotaEngine.QuotaGroups["RegionQuota"].Pend()
If Not (IsSet(quota_pend_result, QuotaResultConstants.qrWasPended)) Then
FailRegion.Show()
End If
Gender.Ask()
quota_pend_result = QuotaEngine.QuotaGroups["GenderQuota"].Pend()
If Not (IsSet(quota_pend_result, QuotaResultConstants.qrWasPended)) Then
End If
After a period of interviewing the pending, completed and rollback counts are as follows.
Notice that the target for women has been met so any subsequent interviews with women will
be terminated.
Quota cell Target Pending Completed Rollback
North 25 0 22 0
South 25 0 23 0
East 25 0 19 0
West 25 0 23 0
Male 50 0 37 0
Female 50 0 50 0
The next interview is for a woman in the East. After the respondent has answered the region
question, the cell counts are as follows:
North 25 0 22 0
South 25 0 23 0
East 25 1 19 0
West 25 0 23 0
Male 50 0 37 0
Female 50 0 50 0
1079
Base Professional
Another interview starts, this time for a man in the East. When he has answered the region
question, but before either respondent answers the gender question, the cell counts are as follows:
North 25 0 22 0
South 25 0 23 0
East 25 2 19 0
West 25 0 23 0
Male 50 0 37 0
Female 50 0 50 0
When the female respondent fails the gender quota, nothing happens to the gender counts, but
the pending count for the East quota is decremented by 1 and the rollback counter for that cell in
incremented by 1. The table of cell counts at the end of the woman’s interview is as follows:
North 25 0 22 0
South 25 0 23 0
East 25 1 19 1
West 25 0 23 0
Male 50 0 37 0
Female 50 0 50 0
When the male respondent finishes his interview, the pending count for East is decremented by 1
and the completed count is incremented by 1. The completed count for Male is also incremented:
North 25 0 22 0
South 25 0 23 0
East 25 0 20 1
West 25 0 23 0
Male 50 0 38 0
Female 50 0 50 0
Quotas for Categorical Responses
When a quota is based on single categorical responses, IBM® SPSS® Data Collection Interviewer
Server increments the pending, completed and/or rollback counters for that response as described
above. When a cell’s completed count matches its target, all subsequent interviews in that cell will
be terminated.
When a quota is based on multiple categorical responses, Interviewer Server increments the
counters for all responses chosen by the respondent. The interview termination behavior is entirely
dependent on the script that checks the result of the quota Pend() function. For more information,
see the topic Pending Quota Cells on p. 896.
Note: Quotas based on questions with large numbers of multiple categorical responses makes
quota testing very slow, particularly when a number of interviews are running concurrently.
1080
Chapter 1
Quotas for Numeric and Text Responses
Expression quotas is the term used for quotas based on numeric or text responses. (You can
also use them for quotas based on specific combinations of characteristics, such as teenagers
who have a weekend job and who visit the cinema at least twice a month.) You can define any
number of expression quotas which may or may not be related to one another. For example, if
you want to define quotas for a numeric question, you would define a set of expressions that
group the possible responses into ranges so that you can set targets for each range. If you want
to define quotas for a text question, you might define expressions that specify a word or words
that must appear in the response text.
When IBM® SPSS® Data Collection Interviewer Server checks an expression quota, it
increments the counters for each expression that matches the respondent’s answer. With numeric
response ranges, the ranges are usually the equivalent of single categorical responses, so only the
counters for one range will be affected. With quotas based on text responses (or combinations of
responses) it is possible that more than one set of counters may be incremented if the respondent
satisfies more than one expression.
Quotas for No Answer, Don’t Know, Refused, and Other Specify
For quota purposes, No Answer, Don’t Know, Refused, and Other Specify are treated as ordinary
categorical responses. When you set up quotas for a question that allows these responses, you
must specify targets for these responses, and all interviews in a category will be terminated once
the sum of pending and completed interviews matches the target.
If you do not want to quota on these responses, you can either set a very large target for each
one, or set no quota at all, or you can accept the default target and flag these quota cells as being
counter quotas only. For more information, see the topic Overquota and Counter Quotas on p.
1081.
Quotas for Stopped or Timed Out Interviews
When an interview times out or is stopped, any pending counts for that interview are rolled back
and the corresponding rollback counts are incremented by 1. From a quota perspective it is
therefore as if the interview never took place.
When an interview is restarted, the interviewing program replays the earlier part of the
interview, filling in the original responses that the respondent chose. When the interviewing
program checks quotas, it tests the respondent’s answers against the current values in the quota
table, increments the appropriate pending counters and either passes or fails the interview in the
usual way. If the respondent belongs in cells whose targets have been met since the original
portion of the interview took place, the interview will be terminated by quota control and any
remaining answers from the original portion of the interview will be ignored.
Note: When an interview is restarted and the pending counts are re-incremented, the rollback
counts that were incremented when the interview was stopped or timed out are not decremented.
If the restarted interview becomes a completed interview, the rollback counts will still report
that an interview was rolled back.
1081
Base Professional
Overquota and Counter Quotas
Overquota and counter quotas are options that you can choose when setting up the quotas using
the IBM® SPSS® Data Collection Quota Setup program rather than scripting features. However,
they may affect the way the script behaves in certain instances.
When you define quotas, each cell is set up as a Normal quota. This means that as soon as the
sum of pending and completed interviews in a cell matches the target, the next interview in that
cell will fail quota control and will be terminated even if the other interviews are still running.
For example, if the cell target is 50 and you have 47 completed interviews, you can have up to
three interviews running that belong in that cell. If a fourth interview starts in that cell, it will
be terminated when the quota is tested. If one of the pending interviews fails a later quota test,
the pending counts are rolled back and you will be left with an unfilled cell where you could
have reached the target.
Depending on how strict your quota requirements are, you may be able to get round this
problem by allowing cells to go slightly over quota. This allows you to have any number of
pending interviews in a cell, even if this means that the sum of pending and completed interviews
exceeds the target. Once the target has been met, any interviews that are already pending for that
cell will be allowed to complete, but any new interviews in that cell will be terminated. For
example, if the cell target is 50 and there are 49 completed interviews and two pending, and one of
the pending interviews completes, no new interviews will be allowed in that cell but the other
pending interview will be allowed to complete, giving you a total of 51 completed interviews.
Counter quotas never fail; they simply count the number of interviews achieved in a cell. You
might want to use this facility for No Answer, Don’t Know, Refused and Other Specify.
Quotas in Projects that Use Sample Management
When a project uses sample management, quota control can be based on sample data,
questionnaire data, or a combination of the two. In fact, you can define dependent quotas where
some of the characteristics come from the sample and others come from the questionnaire. For
example, if the sample records contains personal data such as age and gender and the questionnaire
asks which make of car the respondent owns, you can set up quotas for men who own Porsches or
young people who own sports cars.
Refer to How to Write A Quota Control System to find out how to write these sorts of scripts.
When a project uses sample management and quota control, you need to be particularly careful
that none of the sample field names is the same as a question or variable name in the script. If
there are fields and variables with matching names (you have a sample field and a question called
gender, for example) you will not be able to quota on these sample fields or questions.
Quotas Based Solely on Sample Data

When a quota is based solely on sample data—in the example, only on age or gender—and the
quota is to be tested before respondents start the questionnaire, you should do the following:
Define the quota groups and targets using IBM® SPSS® Data Collection Quota Setup.
Write a sample management script (.mrs file) that tests the quotas and either starts the
questionnaire or terminates the interview depending on whether the quota target has been met.
1082
Chapter 1
There is no need to include quota testing statements in the interviewing script because quota
control takes place completely outside the script.
Note: The sample management script must deal with everything that the quota testing
statements do for script-based quotas. This includes not only deciding whether to terminate the
interview when the sample-based quotas are exceeded, but also incrementing or decrementing the
associated pending and rollback counts at the appropriate points. You must also specify what must
happen when an interview is stopped or times out.
Quotas Based Solely on Questionnaire Data

When a quota is based solely on questionnaire data—in the example, only on car ownership—all
the quota control takes place once the questionnaire has started, so you should do the following:
Define the quota groups and targets using Quota Setup.
Place one or more quota testing statements in the routing section of the script at the points
at which you want to test quotas.
If the project has a sample management script, write statements that will increment the
complete or rollback quota counts once the sample record has been returned from the
interview. If you forget to do this, none of the pending counts will be reset at the end of the
interview. (If the project does not use sample management, then you omit this step.)
Quotas Based on a Combination of Sample and Questionnaire Data

When quota control is based on a combination of sample and questionnaire data, as in the
example, you should do the following:
Import the sample data that is to be used with the questionnaire data into the script using
a statement of the form:
RespName.Label.Inserts["UserName"].Text = IOM.SampleRecord["UserName"]
This makes the sample data available in script variables.

Define the quota groups and targets using Quota Setup. Use the script variables that you used
with Inserts to access the sample data in Quota Setup. (You will not be able to use the
original sample variables in the same quota as questionnaire variables.)
Place one or more quota testing statements in the routing section of the script at the point you
want to test quotas.
Write a sample management script that increments the complete or rollback quota counts once
the sample record has been returned from the interview. If you forget to do this, none of the
pending counts will be reset at the end of the interview.
Using More Than One Quota Type in the Same Script

You can use more than one of these methods in any project. For example, you can use
sample-based quota control to restrict the number of people taking the survey, and then use
script-based quota control to restrict the number of respondents giving certain answers to
questions in the script. In this scenario, you must follow the rules for both types of quotas. In
other words, you must write a sample management script to process the sample-based quotas and
include quota testing statements in the script to test the script-based quotas. You must also use
Quota Setup to define all the quota groups and targets.
1083
Base Professional
Additional Functionality with Sample Management-Based Quota Control

As noted earlier, the sample management script controls everything to do with how
sample-based quota control works. This gives you flexibility and options that are not available
for script-based quotas. For example, suppose you have a project where you want to obtain 100
interviews for each of five different soft drinks. You want to make the best use of your sample, so
do not want to reject a respondent just because you already have 100 interviews for one of the
chosen soft drinks. You want to be able to ignore that drink and allocate the respondent to one
of the cells for a chosen drink in one of the unfilled cells, or perhaps even in the cell that is
least full. If the respondent drinks fizzy orange, lemonade and mineral water, for example, and
the mineral water quota is full, you can allocate the respondent to the fizzy orange or lemonade
categories, whichever is the least full.
Sample Quotas when you have No Access to the Sample Database
You do not need to have access to the sample database in order to set up and test quotas based
on sample data. This means that you can still set up quotas even if you are a remote worker
with only the IBM® SPSS® Data Collection Quota program and the questionnaire (.mdd) file
installed on your local machine.
There are three simple steps to setting up quotas in this way:
E In your questionnaire file, create a question whose name is identical to the name of the sample
field for which you want to set up quotas. Make the responses identical to the values in the sample
field. For example, if the respondent’s gender is held as M or F in a field called gender, you would
create a categorical question called gender with two responses named M and F.
E Start the Quota program and create an ordinary quota based on the question you have created, just
as you would if you were going to create a quota for a standard question. Do not use the Open
sample management option in the menu. Define the quota targets and save the quotas to a .mqd file.
E In IBM® SPSS® Data Collection Interviewer Server Administration, upload the .mqd file into the
project folder ready for activation.
Even though you have created a question and defined targets for it as if it were a proper question,
there is no need to add quota statements to the questionnaire script. because you want the quotas
to be treated as sample quotas. The reason that this approach works is because when you use a
sample management script that deals with quotas, and the quota control system finds a question
and a sample field that have the same name, it gives precedence to the sample field. This means
that the quota targets that you defined for, say, Gender are taken to be targets for the Gender
sample field instead.
The advantages of this approach to sample management quotas are:
You don’t have to connect to the database server (it still works even if you can connect to the
database)
You get a true categorical quota, with text, instead of individual expressions as is the case
with normal sample quotas.
Quota reports are much easier.
1084
Chapter 1
The disadvantage is:

The question name and the sample field name must match exactly, as must the responses and
the values in the sample field. This is solely your responsibility.
Note: In order to ensure that quotas properly increment, you will need to manually update the
sample management script to pend the appropriate quotas (switch from pending only expressions
to pending at the top level). This can be accomplished by setting the PEND_ALL constant in
the sample management script to True. When set to True the script is forced to pend quotas at
the top level. Setting the PEND_ALL constant to False (the default setting), forces the script to
only pend expressions
Quota Prioritization for Multiple Response Categorical Questions
When a quotas are defined for multiple response categorical questions, the quotas for all responses
chosen by the respondent are pended. If the interview is completed, then the corresponding
complete counts are incremented. When a respondent chooses more than one response, this results
in more than one quota cell being incremented.
Quota prioritization lets you decide how many cells to pend, and allows you to choose the method
by which those cells are chosen. There are four possibilities.
Priority Pending. Pend the cell with the highest priority, if this response is chosen. If this
response is not chosen, try the cell with the next highest priority, and so on. Cells with no
priority defined have the lowest priority of all.
Random Pending. Pend a cell at random from the cells for the responses that have been chosen.
If an interview times out and is restarted after a cell has been pended, the same cell will
be pended if the interview is restarted. If the questionnaire contains routing or other logic
based on the value of the pended cell, this ensures that the interview behavior will be the
same whether or not it times out.
LeastFull Pending based on the ratio of completes to targets. Pend the cell that is least full from
the cells for the responses that have been chosen. If an interview is restarted after timing out,
the LeastFull cell is recalculated using the latest quota information. This may mean that
a different cell is pended in the restarted interview to the one that was pended when the
interview was originally started. If the questionnaire has routing based on the pended cell,
the path through the interview may change once the completed portion of the interview
has been replayed.
LeastFull Pending based on the number of completes only. Pend the cell that has the fewest
completed interviews for the responses that have been chosen. If an interview is restarted
after timing out, the LeastFull cell is recalculated using the latest quota information. This
may mean that a different cell is pended in the restarted interview to the one that was pended
when the interview was originally started. If the questionnaire has routing based on the
pended cell, the path through the interview may change once the completed portion of the
interview has been replayed.
There are two ways of specifying the method you want to use. The easiest is to use the Quotas
activity in IBM® SPSS® Data Collection Interviewer Server Administration as described in .
Alternatively, you can edit the QUOTA_Matrix table in the project’s quota database. Refer to for
information about this table and technical details about how prioritization works.
1085
Base Professional
Sharing Quota Files Between Projects
Sometimes you may have a set of projects that share the same quotas. This typically happens
when you have sample-based quotas and the sample management script allocates respondents to
projects based on information in the sample records or gathered on the authentication page or by a
screening script. For example, suppose you have two questionnaires, one about winter holidays
and the other about summer holidays. A screening script gathers information about age, gender,
and the time of year when the respondent takes his/her main holiday. You want to obtain interviews
with 500 women in two age groups and 500 men in two age groups across the two projects.
You can vary this approach by having additional script-based quotas within the individual
questionnaire, or by having script-based quotas only so that any number of respondents may
take each survey.
To implement any form of quota control where a sample management script determines which
survey a respondent will take, do the following:
Create a master project with a dummy questionnaire script and a sample management script.
The dummy questionnaire must contain copies of all the quota-controlled questions in the
projects to which respondents may be routed. We call these projects slave projects. If there
are no script-based quotas in any of the slave projects, just create a master script containing
a dummy question.
Use IBM® SPSS® Data Collection Quota Setup to define all the quotas for the master and
the slave projects. This includes the master project’s sample management quotas as well as
any script-based quotas required for any of the slave projects. Save the quotas using the
name of the master project (this is why you need to have all the quota-controlled questions
available in one script).
Create the questionnaires for the slave projects in the master project’s source directory. To test
quotas, place quota testing statements in the routing section of the script that use the matrix
names defined in the master project’s .mqd file.
Activate the master project and create a quota database, as for a standard project.
Activate the slave projects and choose the master project’s quota database as the source of
quota information for each project.
When interviewing starts, the sample management script will allocate the respondent to a project.
The questionnaire script for that project will run, but all quotas will be controlled by the quota
tables in the master project’s database.
See for further information about choosing quota databases using the activation wizard.
Working with Quota Controlled Projects in IBM SPSS Data Collection Interviewer Server
Administration
When you work on a project that uses quota control in IBM® SPSS® Data Collection Interviewer
Server Administration, you still need to set up the quotas using the IBM® SPSS® Data
Collection Quota Setup program on your desktop. Quota Setup uses the project’s .mdd file to
obtain information about the variables in the questionnaire, and creates an .mqd file containing
information that the activation procedure needs for creating the quota database.
1086
Chapter 1
Because you will be using a combination of browser based and desktop applications, it is
important that you have the correct files available in the folders in which the browser based and
desktop applications expect to find them. This requires you to copy files between folders at
specific points in the project’s development cycle. If you follow the steps below you should
always have the right files in the right place at the right time.
E Create the project in Interviewer Server Administration.
This creates a project folder in your Users folder. This is where all Interviewer Server
Administration applications look for and create files.
E Create the interview script. You can either use Build to create an .mdd file (placing the appropriate
quota testing statements in an IOM Script item), or you can create the script in IBM® SPSS®
Data Collection Base Professional.
E If necessary, use the Files activity in Interviewer Server Administration to upload any other files
that the script uses, such as image files or presentation templates, into the project folder.
E Use Files to download the project’s .mdd file onto the machine on which you will be running
Quota Setup.
E Use Quota Setup with the .mdd file you have just downloaded to define the quota categories and
the targets for each category.
E In Interviewer Server Administration, use the Files activity to upload the .mqd file that Quota
Setup created. If your quotas are based on sample management data, you must also upload the
.mdd file that Quota Setup created for these variables. The upload process will ask whether you
want to rename this file so that it matches the project name. DO NOT do this as this will cause the
activation process to fail. You must keep the filename exactly as Quota Setup created it, so click
Cancel at this point and then close the Files activity.
E If the project uses sample, use the Participants activity in Interviewer Server Administration to
copy the sample records into a sample database.
E In Interviewer Server Administration, use the Launch activity to activate the project. The first time
you activate the project, the activation process will create a quota database for the project using the
information in the .mqd file. If you change the .mqd file and you want to update the quota database,
you must reactivate and select the option for synchronizing the quota database with the .mqd file.
Interview Scripting Reference

This section provides detailed reference information about the following:
Project and interview properties. Describes the full collection of project and interview
properties available for interviewing projects.
Question limits. Lists the minimum and maximum values for the question types you can
define in an interview script.
Default templates. Describes the default templates that will be used for displaying interview
pages when no project-specific templates have been named.
1087
Base Professional
Template XML schema. Describes the XML code that is substituted for tags used in interview
scripting templates.
CleanMDMForIVS Utility. Describes a component that performs various tidying and
conversion tasks required for creating an .ivs file out of a questionnaire document.
Interview Object Model. Describes the objects, methods, and properties of the interview
object model. Many of the topics in this section are the technical equivalents of topics in the
other chapters of the interview scripting documentation.
Sample Management Component. The sample management component manages the sample
records for the participants in a survey. This section describes the sample management
objects, methods, and properties that you can use when writing sample management scripts.
Quota Component. You can define a customized quota control system in the Sample
Management script. This section describes the quota objects and their properties and methods.
Interview Database Binder Component.
Project and Interview Properties
Every project and interview has a collection of properties that store information about the project
or interview. For projects, the properties include the project name, its type (interview or analysis),
and the names of the standard pages to display for authentication, interview completion, and so
on. Interview properties include the interviewer’s ID, and whether this is a test interview. You
can read and sometimes change project and interview properties in the routing section of the
questionnaire script or in the sample management script.
With the exception of the Status property, all properties are stored in the IBM®
SPSS® Data Collection Interviewer Server properties collection; for example, in
Agent.Server.Project["museum"].Properties["mrInterview"] for the museum project.
Project Properties
The majority of project properties are created when the project is created. The list of properties
to create and their default settings are taken from Properties Interviewer Server (Data
Collection).xml in C:\InetPub\wwwroot\SPSSMR\ProjectEditor\Settings, or the equivalent if
Interviewer Server was not installed to the default Web site. The file used depends on the project’s
type. Other project properties, such as those related to CATI, sample management, and quota
control usage, are created when the project is activated.
You can edit the values of a project’s properties or add customized properties to projects using
the Edit Project activity in IBM® SPSS® Data Collection Interviewer Server Administration.
To minimize calls to DPM, project properties are normally re-cached once every 60 seconds.
This means that you may see a small delay between changing a property and the change
taking effect. You can alter the frequency with which properties are re-cached by changing the
ProjectPropertiesTimeout setting in the registry.
1088
Chapter 1
Interview Properties
Interview properties are predefined parameters used to control the creation and execution of the
interview. They can be set on the URL that starts the interview or, if the project uses sample
management, in the sample management script. When specified on a URL, all interview properties
can be referred to as Interview.PropertyName. This can be shorted in URLs to I.Name. For
example:
http://websvr1/scripts/mrIWeb.dll?Interview.Project=museum&Interview.Test=1
can be shortened to:

http://websvr1/scripts/mrIWeb.dll?I.Project=museum&I.Test=1
Both examples start a test interview for the museum project.

In sample management, Interview properties are set via the InterviewProperties collection; for
example, InterviewProperties.Item("Serial") = 123
The built-in properties are available by default, but you can pass custom properties to the
interview by adding new properties to the InterviewProperties collection.
The interview properties used to create the interview are available in the interview script
through IInterview.Properties. Most interview properties are also available through
IInterview.Info. If you need to change interview properties once an interview has been
created, you should do so using the IInterview.Info object.
Properties that Exist at Both Levels
Some properties exist at both the project and the interview level. In this situation, the interview
property is created by copying the project property with its current value. The value of the
interview property can then be changed for specific interviews by the sample management script
without affecting the setting of the project property.
Table of Project and Interview Properties

This topic provides a general reference to all project, interview, and user properties associated
with projects that are created or run using any IBM® SPSS® Data Collection Interviewer Server
activity or application. See Project and Interview Properties for background information about
properties in general, how they are set, and what happens when the same property can exist at
both project and interview levels.
The following abbreviations have been used in the table:
P for project properties.
1089
Base Professional
I for interview properties.

PI for properties that are both project and interview properties.
Available Available
in in
AuthenticateSampleRec? ReturnSampleRec?
Name Description Data Available New Restarts New Restarts System Property
type and in interviews interviews variable type and
default interview saved in availability
value script?
ActiveVersion The active Text: The No No No No No N/A PI
metadata latest
version version.
to use for
interviewing.
AppointmentCode The call Text: 11 No No No No No N/A P
outcome Created
codes that during
can be used activation.
for setting
appointments
in CATI
interviews.
For more
information,
see the
topic Call
Outcome
Codes on p.
1014.
AuthenticatePageThe page to Text: No Yes Yes Yes Yes N/A PI
display for authenticate.htm
authentication.
This can
be a URL
or the
name of a
template.Recommended
that you use
a template
and not a
URL for
this page.
AuthenticateTypeThe form Text: No Yes Yes Yes Yes N/A PI
of the Au- Template
thenti-
catePage
property;
either URL
or template.
1090
Chapter 1
Available Available
in in
value script?
AuthFailedPage The page Text: No Yes Yes Yes Yes N/A PI
to display authfailed.htm
when
authentication
fails. This
can be a
URL or the
name of a
template.
AuthFailedType The form of Text: No Yes Yes Yes Yes N/A PI
the Auth- Template
Failed-
Page
property;
either URL
or template.
AuthRetryPage The page Text: No Yes Yes Yes Yes N/A PI
to display authretry.htm
when a
respondent
accesses
authentication
for the
second and
subsequent
times. This
can be a
URL or the
name of a
template.
Recommended
that you use
a template
and not a
URL for
this page.
AuthRetryType The form Text: No Yes Yes Yes Yes N/A PI
of the Au- Template
thRetry-
Page
property;
either URL
or template.
1091
Base Professional
Available Available
in in
value script?
AutoAnswer Whether the Boolean: No No
IInterviewInfo.IsAutoAnswer No No N/A I
interview False
is being
automatically
answered
by an
automated
script
testing tool
(1) or not
(0).
AutoDial Whether Long: 1 No No No No No N/A I
the dialing
provider
should dial
the phone
number
automatically.
AutoDialTimeoutThe Long:600 No No No No No N/A P
number of (10
seconds that minutes)
auto-dialing
should
continue
trying to dial
numbers
for an
Interviewer.
No No
AutoSelectOtherWhether to Boolean:FalseIInterview.AutoSelectOther No No N/A I
accept Other
responses if
the Other
check box
or radio
button is not
selected.
Whether to Long: 1
AutoUpdateDataModel No Yes Yes Yes Yes N/A PI
write data
immediately
for each
value (2),
write to the
data model
for each
submitted
page (1),
or at the
end of the
interview
(0).
1092
Chapter 1
Available Available
in in
value script?
Browser The browser Text Yes
IInterview.Info.Browser No Yes No N/A I
version used
to post the
page. The
Web Service
captures
the browser
version
from the
browser.
Only
available
when using
the Web
player.
A property Text
BrowserCapabilities No No
IInterview.Info.BrowserCapabilities No No N/A I
collection
that
contains the
respondent’s
browser
capabilities.
Unless
supplied by
the browser,
only
available
for Web
interviews.
CallerID The caller Text: 1 No No No No No N/A PI
ID to
send when
dialing with
a dialer. If
set to 0,
no caller
ID is sent.
If set to 1,
the dialer’s
phone
number
is sent.
Otherwise
the contents
of this field
are sent as
the ID.
1093
Base Professional
Available Available
in in
value script?
CancelCode The call Text: 41 No No No No No N/A P
outcome Created
code to during
use for activation.
interviews
that are
terminated
part-way
through.
For more
information,
see the
topic Call
Outcome
Codes on
p. 1014.
ClusterList The cluster Text: No No No No No N/A P
on which DefaultCluster;
the project
is activated.
Currently,
all projects
are activated
to the same
cluster.
CompletedInterviewPage
The page Text. No No No No No N/A PI
to display
when a
respondent
completes
an
interview.
This can be
a URL or
the name of
a template.
The form of Text: None No
CompletedInterviewType No No No No N/A PI
the Com-
plete-
dInter-
viewPage
property;
either URL
or template.
1094
Chapter 1
Available Available
in in
value script?
A semicolon Text: 15
ConfirmHangupOutcomes No No No No No N/A P
separated
list that
includes
all call
outcomes
that do not
immediately
disconnect
the call.
This
property
is only
employed
when used
with IBM®
SPSS®
Data
Collection
Dialer.
Interviewers
will need
to exit and
re-enter
the Phone
participants
activity in
order to pick
up changes
to this
property.
ConnectionID The Text. No No No No No N/A I
interview’s
connection
ID. Used
internally
by sample
management
and should
not be
changed.
Context The context Text. No No No No No N/A I
to use for
labels from
the MDM.
Debug Whether the Boolean: No
IInterviewInfo.IsDebug No No No I
DataCollection.Debug
interview False
is being
debugged
(1) or not
(0).
1095
Base Professional
Available Available
in in
value script?
DefaultCategoryType
The default Text: multi No No No No No N/A P
category Created
type for and used by
categorical the Build
questions. activity
only.
The name of Text.
DefaultPresentationTemplate No No No No No N/A P
the template Created
to use if no and used by
template is the Build
specified in activity
an item’s only.
definition.
DialerCallOutcome
The Text No No No No No N/A I
dialer’s call
outcome
for this
interview.
Used when
the dialer
returns a
sample
record for a
disconnected
call to the
interviewer
(for
example, a
fax machine
number).
DialingProvider The name of Text No No No No No N/A P
the dialing not set by
sample default
management
provider
to use,
specified
as the
ProgID of
the provider
class.
Existing
names are
QsampExtSM.Provider
and
QSampGroupSM.Provider.
The
property is
empty when
the project
1096
Chapter 1
Available Available
in in
value script?
does not use
a dialer.
Engine The session Text. No Yes Yes Yes Yes I
DataCollection.InterviewEn
engine on
which the
interview
is running.
When
starting
a new
interview,
the Web
Service
attempts
to run the
interview on
this engine
before any
other. Can
optionally
be used
as part of
interview
creation
to bypass
default load
balancing.
ExpiryDateTimeSpecifies Date No No No No No N/A PI
a project
expiry time
that controls
the last
time that an
interview
can occur
for a project
in web or
phone mode
including
prohibiting
appointments
to be set
after the
expiry time.
1097
Base Professional
Available Available
in in
value script?
GroupDial Indicates if Boolean: 0 Yes if set No No Yes Yes N/A PI
the record to 1.
should be
preview
or group
dialed, 0 for
preview dial
and 1 for
group dial.
HiddenCodesListCall Text: No Yes Yes No No N/A P
outcome 1;2;4;5;6;10;26;34;42;43;44;51;52;53
codes that
should not
appear in
the list
displayed
for
interviewers.
For more
information,
see the
topic Call
Outcome
Codes on p.
1014.
InterviewerID The ID Text Yes Yes
IInterviewInfo.InterviewerID Yes Yes I
DataCollection.InterviewerI
of the
interviewer
who
conducted
the
interview.
InterviewerTimezone
The Long: Yes Yes
IInterviewInfo.InterviewerTimeZone Yes Yes I
DataCollection.InterviewerT
interviewer’s Local
timezone timezone
(as a time
zone index).
The page
InterviewRejectedPage Text: No Yes Yes Yes Yes N/A PI
to display rejected.htm Do not Do not
when change this change
authentication property this prop-
fails and no here erty here
retries are to because because
be offered. you cannot you cannot
This can be be sure be sure
a URL or that Re- that Re-
the name of turnSam- turnSam-
a template. pleRec pleRec
will have will have
finished finished
running by running by
1098
Chapter 1
Available Available
in in
value script?
the time the time
Interviewer Interviewer
Server Server
displays displays
the page. the page.
The form of
InterviewRejectedType Text: No Yes Yes Yes Yes N/A PI
the Inter- Template
viewRe-
ject-
edPage
property;
either URL
or template.
InterviewRestartWhether to Boolean: 1 No Yes Yes Yes Yes N/A P
restart inter-
views using
the version
they started
with (0), or
the version
specified by
ActiveV-
ersion (1).
InterviewScriptType
The script Text. No No No No No N/A P
type.
Always
Data
Collection.
InterviewStartURL
The URL Text: No No No No No N/A P
used to http://{Site.IBM®
start an SPSS®
interview on Data
the project. CollectionURL}/
mrIWeb.dll?I.Project={Pro-
jectName}
InterviewStatus The current Text. No
IInterview.InterviewStatus No No No N/A I
status of the
interview.
1099
Base Professional
Available Available
in in
value script?
InterviewStoppedPage
The page Text. No No No No No N/A PI
to display
when a
respondent
clicks Stop
during an
interview
or when the
interview
script
forces early
termination
of the
interview.
This can be
a URL or
the name of
a template.
InterviewStoppedType
The form Text: None No No No No No N/A PI
of the In-
terview-
Stopped-
Page
property;
either URL
or template.
IsTest Whether Boolean: Yes
IInterviewInfo.IsTest Yes N/A N/A N/A I
this is a test False
interview.
IsUploadSampleUsed to Long: No No No No No N/A P
prevent ExpiryTimeSpan
multiple = 1800 (30
users from minutes)
uploading If one
samples, for user is
the same uploading a
project, sample, the
at the value for
same time. StartTime
Resource is set as
conflicts can the upload
occur when sample
multiple start time.
users access Normally,
the same the value is
table. set back to
This empty once
property the user
contains is finished
the two uploading
following the sample.
properties:
1100
Chapter 1
Available Available
in in
value script?
ExpiryTimeSpan
StartTime
StartTime =
empty OR
CurrentTime
> (StartTime
+ Expiry-
TimeSpan)
LabelType The label Text. No
IInterview.LabelType No No No N/A I
type to use
for labels
from the
MDM.
Language The Text. Yes
IInterview.Language No Yes No N/A I
language
to use for
labels from
the MDM.
The Web
Service
attempts to
capture the
language
from the
browser.
LastActivatedByThe name Text. No No No No No N/A P
of the user
who last
activated the
project.
MasterProject Text. No No No No No N/A I
MaxAuthRetriesThe Long: 5 No Yes No No No N/A PI.
maximum Note:
number Changes to
of times a the value
respondent of this
can retry property
authentication; must be
that is, the specified
number of at both the
times the project and
respondent interview
can try level.
authentication However,
after first sample
accessing it. management
uses
only the
interview
property
setting
1101
Base Professional
Available Available
in in
value script?
when
testing
authentication
retries.
MaxOpCodesExecuted
The Long: Yes Yes
IInterview.Info.MaxOpCodesExecuted Yes Yes N/A I
maximum 1000000
number of
instructions
to process
before the
script is
considered
to be in
an infinite
loop.
MaxPredictiveSilentCalls
The Double: No No No No No N/A P
maximum 3.0
percentage
of silent
calls
per total
connected
calls.
Predictive
dialing is
suspended if
this value is
exceeded.
MaxQuestionsOnReplay
The Long: Yes Yes
IInterview.Info.MaxQuestionsOnReplay Yes Yes N/A I
maximum 4000
number of
questions
that can be
automatically
answered
before the
script is
considered
to be in
an infinite
loop.
1102
Chapter 1
Available Available
in in
value script?
MaxSilentCalls The Double: No No No No No N/A P
maximum 1.0
percentage
of silent
calls
per total
connected
calls
that can
occur for
nonpredictive
dialing
before
group
dialing is
suspended.
The name of Text.
MessagesDocument No No
IInterview.MessagesDocument No No N/A I
the standard
messages
file.
MinimumRingTimeThe Double:0 No No No No No N/A P
minimum
number of
seconds that
the phone
must ring
before the
call can be
disconnected.
MonitoringAllowed
Whether Long: 2 No Yes Yes Yes Yes N/A PI
interviewers
may be
monitored.
Possible
settings are:
0=Never
allowed
1=Always
allowed
2=Ask
participant
See
“Interviewer
Monitoring”
in
Interviewer
Settings
(ms-its:UserGuide.chm::/Intug-cs_surveyintro.htm)the
Interview
Settings
topic, which
is in the
1103
Base Professional
Available Available
in in
value script?
Phone
Surveys
section
of the
Interviewer
Server
User’s
Guide, for
further
information.
Interviewer Properties Text. No No No No No N/A P
Server associated
with the
Interviewer
Server
application.
NoAnswerTimeout
The number Long:15 No No No No No N/A PI
of seconds Note: This
for the dialer default
to let a is for
number ring Interviewer
before it is Server
considered only. The
to be default
unanswered. for the
QSAMP
dialer
interface is
30 seconds.
Notes Notes about Text. No No No No No N/A P
the project.
Record
any special
information,
or details
of changes
between
versions,
about the
project
in this
property.
Origin The origin Yes
Categorical: IInterviewInfo.Origin Yes Yes Yes I
Respondent.Origin
of the {other}
respondent
data.
1104
Chapter 1
Available Available
in in
value script?
OriginName The source Text. No No
IInterviewInfo.OriginName No No N/A I
software
product
name.
Used when
the Other
category is
specified for
Respon-
dent.Ori-
gin.
PercentCallsRecorded
The Long: 0 No No No No No N/A P
percentage
of calls to
be recorded
per project
between 0
and 100.
Project The name of Text. Yes
IInterview.ProjectName No Yes No N/A I
the project
to which the
interview
belongs.
Used as part
of interview
creation
and restart.
If sample
management
is used,
the sample
management
script can
change the
project for
the new
interview.
This
property is
mandatory
for an
interview to
be started.
1105
Base Professional
Available Available
in in
value script?
The page
ProjectInactivePage Text: No No No No No N/A P
to display projinactive.htm
when a
respondent
attempts
to access
a project
that is not
available for
interviewing.
This can be
a URL or
the name of
a template.
The type of Text:
ProjectInactiveType No No No No No N/A P
the Pro- Template
jectInac-
tivePage
property;
either URL
or template.
QuotaAutoCommit
Whether Boolean: No No No No No N/A I
to commit True
changes
to quota
counts
automatically
when an
interview
completes
(1) or not
(0). This
property
applies
only when
a project
does not
use sample
management,
since this is
automatic
in those
projects.
1106
Chapter 1
Available Available
in in
value script?
QuotaFullPage The page Text. No Yes Yes Yes Yes N/A PI
to display
when an
interview
terminates
because the
quota is full.
This can be
a URL or
the name of
a template.
QuotaFullType The form of Text: None No Yes Yes Yes Yes N/A PI
the Quota-
FullPage
property;
either URL
or template.
QuotaProjectNameThe name of Text. No No No No No N/A P
the quota
project
associated
with this
project.
Blank if
quota is not
used.
RaisePositionError
Whether Boolean: No No No No No N/A P
to prevent False
interviewers
logging in
on positions
that are not
defined in
the dialer
configuration
file.
If
RaisePositionError
is False,
interviewers
logging in
on positions
not in
the dialer
configuration
file see a
warning
but may
continue to
work. This
supports
sites that
1107
Base Professional
Available Available
in in
value script?
have some
manual-dial
or
temporary
manual-dial
stations that
are not in
the dialer
configuration
file.
RecordCall Whether the Boolean: Yes if set No No Yes Yes N/A I
call should randomly to 1.
be recorded. initialized
May be based on
overridden Percent-
by Record- Call-
ingPro- sRecordedd,
hibited but can be
if the overridden
respondent in the
disallows sample
recording. script.
RecordingProhibited
Whether the Boolean: 0 Yes if set No No Yes Yes N/A I
respondent (recording to 1.
has disal- allowed)
lowed re-
cording.
Overrides
Record-
Call if both
are set to 1.
RecordInterviewOnly
Whether Boolean: 0 No No No No No N/A P
to record
the whole
call (0) or
just the
interview
(1)
1108
Chapter 1
Available Available
in in
value script?
Renderer The HTML Text: Yes
IInterview.Info.Renderer Yes No No N/A I
player to HTMLPlayer,While it
use for but Phone is possible
rendering Participants to change
the changes the player
interview. this default in script,
Possible to the CATI the player
settings are: keyboard used to
HTMLPlayer: player. create
The default a page
HTML should be
Player used to
CATI- generate
Player: the player
The CATI post XML
Player when
XMLPlayer: posting the
The XML page.
Player
used by
Interviewer
ServerIBM®
SPSS®
Data
Collection
Load Tool
RespondentID The Long. No No
IInterview.Info.RespondentID Yes Yes N/A I
respondent
ID for this
interview.
RespondentTimezone
The Yes Yes
Long: local IInterviewInfo.RespondentTimezone Yes Yes I
DataCollection.RespondentT
respondent’s time zone
time zone
(as a time
zone index).
The Web
Service
attempts to
capture the
time zone
from the
browser.
RestartString The Text. No No No No No N/A I
string for
restarting
the
interview.
1109
Base Professional
Available Available
in in
value script?
Review Whether the Boolean: No
IInterviewInfo.IsReview No No No N/A I
interview False
should be
restarted for
review.
RotationValue The initial Long. No No
IInterviewInfo.RotationSeed No No N/A I
rotation and and
reversal IInterviewInfo.ReversalSeed
seed value
for the
interview.
RoutingContext The default Text: No Yes Yes Yes Yes PI
DataCollection.RoutingCon
routing default for Created
context interviewing during
to use for application. activation
interviewing.
Typical
routing
contexts
are Paper
for printed
questionnaires,
Web for
inbound
interviews,
and
CATI for
outbound
calling.
RunningCodesList
Call Text: No No No No No N/A P
outcome 8;11;15 Created
codes that during
are available activation
during
interviews.
For more
information,
see the
topic Call
Outcome
Codes on
p. 1014.
1110
Chapter 1
Available Available
in in
value script?
RunNumber A four-byte Text: 0001 No Yes No Yes No N/A I
run number
for the
interview.
This is used
as part of
the session
ID to ensure
that the
session ID
is unique.
Set to −1
for restarted
interviews.
SampleID The sample Text No No No Yes No N/A I
ID for
sample
management.
This
property is
stored on
the cache
subscription
for when an
interview is
restarted.
The name of Text:
SampleManagementProvider No No No No No N/A P
the sample mrScriptBasicSM.Provider
management
provider
to use,
specified
as the
ProgID of
the provider
class.
Existing
names are
mrScriptBasicSM.Provider
and
VBScriptSM.Provider.
The
property is
empty when
the project
does not
use sample
management.
1111
Base Professional
Available Available
in in
value script?
The sample Text.
SampleParameters No No No Yes No N/A I
management
parameters
for this
interview.
SeedValue The Long: No No No No No I
DataCollection.SeedValue
randomization Based on
seed value the tick
for the count
interview.
Serial The Long: Yes
IInterview.Info.Serial Yes Yes Yes I
Respondent.Serial
respondent’s NULL.
serial
number.
Used to
identify the
respondent’s
case data
record.
Write it into
the sample
record if
you want
to be able
to link the
sample and
case data
records.
You can set
the serial
number in
the sample
management
script. This
is typically
done when
individual
respondents
may take
part in a
number of
projects and
you want
to use the
same serial
number
for a
respondent
in all of the
projects.
However,
you must
1112
Chapter 1
Available Available
in in
value script?
make
sure that
the serial
number
is always
unique
within each
project.
Server The name Text. No No No No No N/A I
of the server
on which the
interview is
running.
Session A unique Text Yes
IInterview.SessionToken Yes Yes Yes N/A I
token that
identifies
a running
interview.
Used to
differentiate
new
interviews
from
running
interviews.
If the
Session
parameter is
not present
in the
URL, any
parameters
not
namespaced
by
“Interview.”
are
treated as
authentication
parameters.
If the
Session
parameter is
present, the
Post string
is passed to
the specified
HTML
Player so
the player
post XML
can be
1113
Base Professional
Available Available
in in
value script?
generated.
This
property is
mandatory
in order for
a page to be
posted
SessionToken A unique Text. No
IInterview.Session.Token No No No N/A I
token that
identifies
the
interview.
ShowInterviewApps
Whether Boolean. No No No No No N/A P
to display Interview
interviewing projects:
activities True
in IBM® Analysis
SPSS® projects:
Data False
Collection
Interviewer
Server
Administration
for this
project.
ShowTableApps Whether Analysis No No No No No N/A P
to display projects:
tabulation True
activities in Interview
Interviewer projects:
Server False
Administration
for this
project.
Shutdown Whether the Long. No Yes Yes Yes Yes N/A I
interview Set to 0 Set to 0 on
was on entry entry to this
terminated to this function
because the function and should
interview and should not be
engine not be changed.
shut down changed.
(0) or not
(nonzero).
1114
Chapter 1
Available Available
in in
value script?
The name of Text.
SilentCallAudioFile No Yes No Yes No N/A I
a .wav file
to play to a
participant
if predictive
dialing
results in a
silent call.
The dialer
hangs up
the call after
playing the
file.
SMRetryCount The number Long. No Yes No Yes No N/A I
of times the
respondent
has retried
authentication.
Test Whether Boolean: Yes
IInterview.Info.IsTest Yes. Set Yes Yes. Set N/A I
this is a test False. to True to True
interview. on restart on restart
0=No;1=Yes. and to 1 and to 1
on original on original
start. start.
TestUseQuota Whether to Boolean: No No No No No N/A P
use quota True
control
for test
interviews
(1) or not
(0).
TestUseSampleMgmt
Whether to Boolean: No No No No No N/A P
use Sample True
Management
for test
interviews
(1) or not
(0). Only
used when
UseSam-
pleMgmt
is 1
TestVersion The The latest No No No No No N/A P
metadata version
version to
use for test
interviews.
1115
Base Professional
Available Available
in in
value script?
Whether to Boolean: 0
TextQuestionsOnly No No No No No N/A I
present all
questions
or only
questions
with text
and Other
Specify
responses
for review.
(Once in
this mode
you cannot
revert to
reviewing
all questions
without
restarting
the
interview.)
TimedOut Whether the Boolean No Yes Yes Yes Yes N/A I
interview
has timed
out. This
property is
set to 0 on
entry to the
Authen-
ticate-
SampleRec
function,
and is reset
to a nonzero
value if the
interview is
terminated
by a
time-out. If
you want
your script
to specify
the action
to be taken
when an
interview
times out,
test on the
value of this
property.
1116
Chapter 1
Available Available
in in
Name Description Data New
Available Restarts New Restarts System Property
value script?
TimeLastActivated
The date Date No No No No No N/A P
and time Created
at which during
the project activation.
was last
activated.
Timeout The number Long: Yes
IInterviewInfo.Timeouts No Yes No N/A I
of seconds 600 (10
idle time minutes),
before the defined
interview in the
will be registry in
timed out. \HKEY_LOCAL_MACHINE\Software\SPSS\mrInterview\3\
Interview\
InterviewTimeout
UseCATI Whether the Boolean. No No No No No N/A P
project uses Created
CATI. during
activation.
UseDataModel Whether Boolean No No No No No N/A P
to use the
Dimensions
Data
Model. This
property is
obsolete in
Interviewer
Server 2.1
and later.
UseDefaultURLsWhether the Boolean: No No No No No N/A P
project uses True
the default
templates
and URLs
(1) or not
(0).
UseImageCache Whether Boolean: No Yes Yes Yes Yes N/A P
to use the True
image cache
for project
templates
and images
(1) or not
(0).
1117
Base Professional
Available Available
in in
value script?
Whether to Boolean:
UseInMemoryCache No Yes Yes Yes Yes N/A P
hold the data False
cache in
memory (1)
or not (0).
There is no
automatic
restart on
fail-over
when the
in-memory
cache is
used.
UsePlayerNavigation
Whether Boolean: Yes Yes
IInterview.Info.UsePlayerNavigation Yes Yes N/A PI
the player True
can post
previous
questions.
For
example,
when
running
browser
based
interviews,
you could
allow
respondents
to use the
browser’s
Back button
to return to
a previous
page of the
interview
rather
than the
interviewing
program’s
Previous
Button.
User1 to Pass Text. Yes
IInterview.Info.User1 Yes Yes Yes N/A I
User9 user-defined
parameters
to the
interview
from the
URL.
1118
Chapter 1
Available Available
in in
value script?
UseSampleMgmtWhether Boolean: No No No No No N/A PI
the project False
uses sample
management
(1) or not
(0).
Version The MDM Yes
Text: The IInterview.Info.Version Yes Yes Yes I
DataCollection.MetadataVer
project default
version to version for
use when the project.
creating the This is
interview. based
on the
TestVersion
or
ActiveVersion
set in
DPM. If
these are
empty,
the latest
version is
used.
Question Limits
The following table describes the limits that apply when defining or responding to a question.
Question Type Limits
Long (also known as Integer) The minimum value is -2,147,483,648 and the
maximum value is 2,147,483,647.
Double (also known as Decimal or Real) The minimum value is -1.79769313486232E308 and
the maximum value is 1.79769313486232E308. The
smallest negative value is -4.94065645841247E-324
and the smallest positive value is
4.94065645841247E-324.
Text Can in theory be up to 2 billion characters in length.
In reality, the length is limited by the database being
used to store the response. In a IBM® SPSS® Data
Collection relational MR database, the maximum
length is 4,000 characters.
Date (also known as Date/Time) The earliest value is 1 January 100 and the latest
value is 31 December 9999.
1119
Base Professional
Question Type Limits

Categorical (also known as Single Response or Can in theory contain up to 2 billion categories.
Multiple Response) In reality, the number depends on the available
memory and the Data Source Component (DSC)
being used. A category name must contain between
1 and 128 characters.
All A question name must contain between 1 and 128
characters.
Default Templates
This section contains all of the default templates used by IBM® SPSS® Data Collection Base
Professional and IBM® SPSS® Data Collection Interviewer Server to display interviews when no
custom templates are defined in the interview script.
Default Layout Template
Layout templates control the overall appearance of interview pages. The default layout template
shown below is used to determine the positions of the questions, navigation buttons, banners, and
other items on an interview page when no custom layout template is defined in the interview script.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>
<mrPageTitle/>
</title>
<style type="text/css"><!–table.mrQuestionTable{border-collapse: collapse; padding: 0px;} –><!–
table.mrQuestionTable td{font-family: Arial; font-size: 10pt;} –><!–.mrErrorText{font-size: 11pt;} –><!–
textarea{font-family: Arial;} –></style>
</head>
<body>
<mrPage IncludeElementIDs="true"/>
<span style="font-family: Arial; font-size: 11pt;">
<mrBannerText/>
<span style="font-size: 10pt;">
<mrData/>
<div>
<br/>
</div>
<mrNavBar/>
</span>
</span>
</body>
</html>
Default Question Template
Question templates determine the appearance of questions and their responses on an interview
page. The default question template shown below is used if no custom question template is
defined in the interview script.
1120
Chapter 1
<mrSubTemplate>
<mrData QuestionElement=’Error’/>
<mrData QuestionElement=’Banner’/>
<mrData QuestionElement=’Label’/>
<div>
<br/>
</div>
<mrData QuestionElement=’Controls’/>
<div>
<br/>
</div>
</mrSubTemplate>
The MRData tags specify the position of the question and responses texts on the page. During
interviews, HTML code is placed around the texts to determine how those texts appear on the
page. For example, for categorical responses, code is inserted to display a radio button or check
box for each response, whereas for text responses an input box is displayed instead.
The general code for any question is as follows:
<span class="mrQuestionText" style="">QuestionText</span>

<div><br/></div>
<div></div>
<span class="mrQuestionText" style="">QuestionText</span>
<div style="margin-left: 2em"> <div></div>
<span style="display: inline-block;">
<table summary="" class="mrQuestionTable" style="">
Response controls
</table>
</span>
</div>
where:
QuestionText is the question text.
Response controls are one or more row specifications that lay out the response controls
according to the response type. Use the links in the Related Topics list to see more information
about specific response types.
Categorical Responses
The HTML code for a categorical response is.
<tr>
<td style="">
<div></div>
<input type="SelectionType" name="Ref" class="AnswerType" style="margin-left: 1em;" value="Name" [
<span class="TextType" style="">Label</span>
</input>
</td>
</tr>
The checked="" attribute is present only when the question already has an answer (usually after
a snapback or restart) and marks the respondent’s current answer. This causes the radio button or
check box for that answer to be preselected when the question is displayed.
1121
Base Professional
For example, the question:

TeaType "Do you use tea bags, loose tea or both?"
categorical [1..]
{
Bags, Loose
};
becomes:
<span class="mrQuestionText" style="">Do you use tea bags, loose tea or both?</span>
<div><br/></div>
<div></div>
<table summary="Do you use tea bags, loose tea or both?" class="mrQuestionTable" style="margin-left:
<tr>
<td style="">
<div></div>
<input type="checkbox" name="_QTeaType_CBags" class="mrMultiple" style="margin-left: 1em;" val
<span class="mrMultipleText" style="">Tea bags</span>
</input>
</td>
</tr>
<tr>
<td style="">
<div></div>
<input type="checkbox" name="_QTeaType_CLoose" class="mrMultiple" style="margin-left: 1em;" va
<span class="mrMultipleText" style="">Loose tea</span>
</input>
</td>
</tr>
</table>
</span>
For single rows/columns, the table element UseTablesLayout attribute in the intermediate XML
indicates whether the table uses tables layout. The corresponding intermediate XML is as follows:
<Questions>
- <Question>
<Style ElementAlign="NewLine" Indent="1" />
- <Table Summary="Male or Female?" UseTablesLayout= “false”>
- <Row Y="0">
- <Cell X="0" Y="0">
- <Control Type="RadioButton" QuestionName="_QGender_C" ElementID="_Q0_C">
- <Style ElementAlign="NewLine" Indent="1">
<Control Type="RadioButton" />
</Style>
- <Category Name="Male" CategoryID="0">
- <Label>
<Style ElementAlign="Right" />
<Text>Male</Text>
</Label>
</Category>
</Control>
</Cell>
</Row>
- <Row Y="1">
- <Cell X="0" Y="1">
- <Control Type="RadioButton" QuestionName="_QGender_C" ElementID="_Q0_C">
- <Style ElementAlign="NewLine" Indent="1">
<Control Type="RadioButton" />
</Style>
- <Category Name="Female" CategoryID="1">
- <Label>
<Style ElementAlign="Right" />
<Text>Female</Text>
</Label>
</Category>
</Control>
</Cell>
</Row>
</Table>
1122
Chapter 1
</Question>
</Questions>
The UseTablesLayout attribute is retrieved in the default Question.xsl, when creating HTML
codes for questions. When UseTablesLayout is false, tables are replaced with a span layout.
When UseTablesLayout is true, the existing table layout is used. The rules of replacing the table
layout as follows:
If UseTablesLayout = false
E Replace table tags with span tags. Span attributes are the same as the table node with the
exception that the summary attribute is removed.
E Replace td tags with span tags. Span attributes are the same as the td node. If the categorical
lists are in a single row, inline-block is used.
Note: The replacement could cause slight presentation differences. ICellStyle.ColSpan and
ICellStyle.RowSpan will no longer work.
Example HTML code with table and td tags is:

<div></div>
<span class="mrQuestionText" style="">Male or Female?</span>
<div><br/></div>
<div></div>
<span style=" ">
<table summary="Male or Female?" class="mrQuestionTable" style="margin-left: 1em;">
<tr>
<td style="">
<div></div>
<input type="radio" name="_QGender_C" class="mrSingle" style="margin-left: 1em;" value
<span class="mrSingleText" style="">Male</span>
</input>
</td>
</tr>
<tr>
<td style="">
<div></div>
<input type="radio" name="_QGender_C" class="mrSingle" style="margin-left: 1em;" value="Fe
<span class="mrSingleText" style="">Female</span>
</input>
</td>
</tr>
</table>
</span>
After replacing the table with span layout, the HTML code would be:
<div></div>
<span class="mrQuestionText" style="">Male or Female?</span>
<div><br/></div>
<div></div>
<span style=" ">
<span class="mrQuestionTable" style="margin-left: 1em ;">
<span style="">
<div></div>
<input type="radio" name="_QGender_C" class="mrSingle" style="margin-left: 1em;" value="Ma
</input>
</span ><span style="">
<div></div>
<input type="radio" name="_QGender_C" class="mrSingle" style="margin-left: 1em;" value="Fe
<span class="mrSingleText" style="">Female</span>
</input>
1123
Base Professional
</span >
</ span >
</span>
When categorical lists are in single column, the HTML code for a categorical response would be:
<span style="">
<div></div>
<input type="radio" name="_QGender_C" class="mrSingle" style="margin-left: 1em;" value="Male">
</input>
</span >
When categorical lists are in a single row, the HTML code for a categorical response would be:
<span style="display:inline-block;">
<div></div>
<input type="radio" name="_QGender_C" class="mrSingle" style="margin-left: 1em;" value="Male">
</input>
</span >
Note: “display: inline-block;” ensures that responses are in the same row.
Drop-down Lists and List Boxes
Categorical response lists can be displayed as drop-down lists or list boxes. The HTML code for
these types of response lists is as follows (the code in square brackets is present for list boxes but
not drop-down lists):
<div></div>
<select [size="NumLines" multiple=""] name="Ref" class="ListType" style="margin-left: 1em;">
<option style="" class="mrMultiple" [selected=""] value="Name">Label</option>
...
</select>
</span>
where:
QuestionText is the question to be asked.
NumLines is the height of the list box. The default is 4. This parameter is omitted for
drop-down lists which are always shown as a one-line box.
Ref is the internal name that IBM® SPSS® Data Collection Interviewer Server assigns to the
list. This has the form _Qqname_C, where qname is the question name.
ListType is either mrDropDown or mrListBox. If ListType is mrListBox, the
multiple parameter is added to the specification to allow more than one answer to be
chosen from the list.
Name is the category name defined in the metadata.
Label is the category label (response text) to display on the screen.
The selected="" attribute is present only when the question already has an answer (usually
after a snapback or restart) and marks the respondent’s current answer. This causes that answer to
be preselected when the question is displayed.
1124
Chapter 1
MostFrequentTea "Which type of tea do you drink most frequently?"

{
Assam, Darjeeling, Ceylon, China,
OtherTea "Other"
};
becomes:
<span class="mrQuestionText" style="">Which type of tea do you drink most frequently?</span>

<div><br/></div>
<div></div>
<div></div>
<select name="_QMostFrequentTea_C" class="mrDropdown" style="margin-left: 1em;">
<option style="" class="mrMultiple" value="Assam">Assam</option>
<option style="" class="mrMultiple" value="Darjeeling">Darjeeling</option>
<option style="" class="mrMultiple" value="Ceylon">Ceylon</option>
<option style="" class="mrMultiple" value="China">China</option>
<option style="" class="mrMultiple" value="EnglishBreakfast">English Breakfast</option>
<option style="" class="mrMultiple" value="OtherTea">Other</option>
</select>
</span>
Text Responses
The HTML code for a text response is:

<div></div>
<textarea name="Ref" class="mrEdit" autocomplete="off" style="margin-left: 1em;" rows="NumRows" cols
</span>
where:
text box. This has the form _Qqname, where qname is the question name.
NumRows is the height of the text box. The default is 6.
NumCols is the width of the text box. The default is 40 characters.
Answer is the respondent’s answer. This is present only after a snapback or restart and causes
the current answer to be displayed in the input box.
For example:
IdealTea "Please describe your ideal cup of tea."

text [0..1024];
becomes:
<span class="mrQuestionText" style="">Please describe your ideal cup of tea.</span>

<div><br/></div>
<div></div>
<div></div>
<textarea name="_QIdealTea" class="mrEdit" autocomplete="off" style="margin-left: 1em;" rows="6" col
</span>
1125
Base Professional
Numeric and Date/Time Responses
The HTML code for a numeric (long or double) or date/time response is:
<div></div>
<input type="text" name="Ref" class="mrEdit" autocomplete="off" style="margin-left: 1em;" maxlength=
</span>
where:
input box. This has the form _Qqname, where qname is the question name.
Number is the maximum number of characters that can be entered for the response. For
numeric responses, this is determined by the maximum value defined in the question’s
metadata; it is always 40 for date/time responses.
For example:
becomes:
<span class="mrQuestionText" style="">How old are you?</span>
<div><br/></div>
<div></div>
<div></div>
<input type="text" name="_QAge" class="mrEdit" autocomplete="off" style="margin-left: 1em;" maxlengt
</span>
Boolean Responses
The HTML code for boolean responses is:

<div></div>
<input type="SelectionType" name="Ref" class="AnswerType" style="margin-left: 1em;" value="TF" [chec
</span>
where
SelectionType is radio if a pair of true and false (yes/no) buttons are required, or
checkbox if a single true (yes) check box is required.
category. This has the form _Qqname_Fsettiing,where qname is the question name.settiing is
either “true” or “false”. When a single check box is used, settiing is always “true”.
AnswerType is mrSingle for two radio buttons or mrMultiple for a single check box.
TF is either true or false. When the response list is two radio buttons, you will have two
entries, one whose value is true and the other whose value is false. When the response list is a
single check box, the value is always true.
1126
Chapter 1

Newsletter "Click the check box if you would like to receive
our online newsletter." boolean;
becomes:
<div></div>
<input type="checkbox" name="_QNewsletter_Ftrue" class="mrMultiple" style="margin-left: 1em;" value=
</span>
No Answer, Don’t Know, and Refusals
The special responses No Answer (na), Don’t Know (dk) and Refused (ref) generate the same
HTML code as categorical responses. If the responses appear in a multiple-choice list and are
tagged as exclusive (that is, as single-choice), an additional style parameter is included so that the
response texts are displayed in a bold font. For example, if the question is defined as:
OtherTea "And which other types of tea do you drink?"
categorical [1..]
{
DrinkOtherTea "Others" other,
NoAnswer "No answer" NA
};
the row for No Answer becomes:

<tr>
<td style="">
<div></div>
<input type="checkbox" name="_QOtherTea_CNoAnswer" class="mrMultiple" style="margin-left: 1em;" va
<span class="mrMultipleText" style="font-weight: bold;">No answer</span>
</input>
</td>
</tr>
Other Specify Responses
The HTML code for an Other Specify response combines the code for a categorical response with
the code for text response, and appears as a single row in the question table.
<tr>
<td style="">
<div></div>
<input type="SelectionType" name="Ref" class="AnswerType" style="margin-left: 1em;" value="Name" [
<span class="TextType" style="">Label</span>
</input>
<span class="mrQuestionText" style=""></span>
<input type="text" name="BoxRef" class="mrEdit" autocomplete="off" style="" maxlength="NumChars"
</span>
</td>
</tr>
BoxRef is the internal name that IBM® SPSS® Data Collection Interviewer Server assigns to
the text box. This has the form _Qqname_Oothername,where qname is the question name and
othername is the name of the Other category.
1127
Base Professional
NumChars is the width of the text box.

OtherTea "And which other types of tea do you drink?"
categorical [1..]
{
DrinkOtherTea "Others" other,
NoAnswer "No answer" NA
};
the row for Other Drinks becomes:

<tr>
<td style="">
<div></div>
<input type="checkbox" name="_QOtherTea_CDrinkOtherTea" class="mrMultiple" style="margin-left: 1em
<span class="mrMultipleText" style="">Others</span>
</input>
<span class="mrQuestionText" style=""></span>
<input type="text" name="_QOtherTea_ODrinkOtherTea" class="mrEdit" autocomplete="off" style="" m
</span>
</td>
</tr>
Responses to Questions in Grids
Grids can contain subquestions with categorical, numeric, or text answers. However, the HTML
code that renders the grid is generally the same for all types of subquestion, apart from the code
that draws the radio button, check box, or input box in each cell.
Categorical Subquestions
The HTML code for a categorical subquestion is as follows:

<tr>
<td></td>
<td class="mrGridQuestionText" style="text-Align: Center;vertical-align: Middle;">
<span class="mrQuestionText" style="">ColHead</span>
</td>
Other column headings
</tr>
<tr>
<td class="mrGridCategoryText" style="text-Align: Left;vertical-align: Middle;">
<span class="mrQuestionText" style="">RowText</span>
</td>
<td style="text-Align: Center;vertical-align: Middle;">
<div></div>
<input type="SelectionType" name="CellID" class="AnswerType" style="" value="ColHead1"></input>
</td>
Other cells in row 1
</tr>
Specifications for other rows
1128
Chapter 1
where:
ColHead is the column heading text. There will be one <td> tag for each column.
RowText is the row heading text. There will be one <tr> tag for each row.
SelectionType is radio for single-choice responses or checkbox for multiple-choice
responses.
CellID is the unique name for the current grid cell. IBM® SPSS® Data Collection
Interviewer Server creates this as _Qloopname_Qloopcat_Qqname_Ccatname, where
loopname is the name of the main loop (grid) question, loopcat is the current item in the loop
control list (the current column), qname is the name of the repeated question, and catname is
the name of the current category in that question’s response list (the current row text). The
example shown below will make this naming convention clearer.
AnswerType is mrSingle for single-choice responses or mrMultiple for multiple-choice
responses.
For example, if the question is:
WhereFrom "Which country or countries produce ...?" loop
{
Gunpowder, Oolong, Puerh, Rooibos
} fields
(
Country "" categorical [1..]
{
China, India, Japan, Kenya,
CountryDK "Don't know"
};
) expand grid;
the first two column headings (China and India) and response rows (Gunpowder and Oolong)
become:
<span class="mrQuestionText" style="">Which country or countries produce ...?</span>
<div><br/></div>
<div></div>
<table summary="Which country or countries produce ...?" class="mrQuestionTable" style="">
<tr>
<td></td>
<span class="mrQuestionText" style="">China</span>
</td>
<span class="mrQuestionText" style="">India</span>
</td>
...
>/tr>
<tr>
<span class="mrQuestionText" style="">Gunpowder</span>
</td>
<div></div>
<input type="checkbox" name="_QWhereFrom_QGunpowder_QCountry_CChina" class="mrMultiple" style=
</td>
<div></div>
<input type="checkbox" name="_QWhereFrom_QGunpowder_QCountry_CIndia" class="mrMultiple" style=
</td>
...
</tr>
<tr>
<span class="mrQuestionText" style="">Gunpowder</span>
</td>
1129
Base Professional

<div></div>
<input type="checkbox" name="_QWhereFrom_QOOlong_QCountry_CChina" class="mrMultiple" style=""
</td>
<div></div>
<input type="checkbox" name="_QWhereFrom_QOOlong_QCountry_CIndia" class="mrMultiple" style=""
</td>
...
</tr>
...
</table>
</span>
After a snapback or restart, any answers that were chosen in the original portion of the interview
will have the checked="" attribute in their definition so that the appropriate radio button or
check box is preselected when the question is displayed. For more information, see the topic
Categorical Responses on p. 1120.
Numeric and Text Subquestions
The HTML code for a numeric or text subquestion is the same as for a categorical question
except that the <input> statement for a row containing input boxes rather than radio buttons or
check boxes is:
<input
type="text" name="CellID" class="mrEdit" autocomplete="off" style="" maxlength="Length" value=""/>
where:
CellID is the unique name for the current grid cell. Interviewer Server creates this as
_Qloopname_Qloopcat_Qqname, where loopname is the name of the main loop (grid)
question, loopcat is the current item in the loop control list (the current column), and qname is
the name of the repeated question.
Length is the maximum number of digits or characters that can be entered in the input box.
For example, if the grid is defined as:
CupsPerDay "How many cups of tea and other beverages do you

normally drink on ..." loop
{
Weekdays, Saturdays, Sundays
} fields
(
Tea "Tea" long [0..99];
NonTea "Other Beverages" long [0..99];
) expand grid;
the cell for cups of tea on weekdays will become:
<input type="text" name="_QCupsPerDay_QWeekdays_QTea" class="mrEdit" autocomplete="off" style="" maxle
After a snapback or restart, any answers that were entered in the original portion of the interview
will have the respondent’s answer set in the value="" attribute and will appear when the question
is displayed. See Numeric and Date/Time Responses and Text Responses for details.
1130
Chapter 1
You can display more than one question on a page using a page, block, or compound statement
in the metadata section of the questionnaire.
Questions defined using page or block are displayed as simple concatenations of the HTML
code for each question in the page or block. In other words, the HTML code for the first question
in the page or block is followed by the HTML code for the second question, and so on. There is no
attempt to use a common naming scheme for the questions’ components.
Compound questions are different in that the compound item is a question in its own right,
in a similar way to grids that contain more than one question. Therefore, a common naming
scheme is used for all the response cells in the compound item. The naming convention is
_Q@DynamicPage_Qcompname_Qqname_Ccatname, where compname is the name of the
compound item, qname is the name of the question in the compound item, and catname is the
name of the current category in the compound item.
Compound items use the same formatting as grids, so if the compound item is defined as:
CommMethodList define
{
FocusGroups "Focus groups",
Newsletter "Internal newsletters",
Website "Company web site",
Email "E-mail",
MyManager "My manager",
DeptManager "Department head",
OtherCommMethod "Other"
};
CommMethods "How do you find out what is going on in the company?"
compound
{use CommMethodList} fields
(
MainMethod "Main method" categorical [1..1];
OtherMethods "Other methods" categorical [1..1];
PrefMethod "Preferred method" categorical [0..];
);
the HTML code for the Email row will be:

<tr>
<td class="mrGridCategoryText" style="">
<span class="mrQuestionText" style="">E-mail</span>
</td>
<td style="">
<div></div>
<input type="radio" name="_Q@DynamicPage_QCommMethods_QMainMethod_C" class="mrSingle" style="margi
</td>
<td style="">
<div></div>
<input type="radio" name="_Q@DynamicPage_QCommMethods_QOtherMethods_C" class="mrSingle" style="mar
</td>
<td style="">
<div></div>
<input type="checkbox" name="_Q@DynamicPage_QCommMethods_QPrefMethod_CEmail" class="mrMultiple" st
</td>
</tr>
Default NavBar Template
This template is used to determine the appearance of the buttons at the bottom of an interview
page, if no custom template is defined in the interview script.
<mrSubTemplate>
<span style="float:left;">
1131
Base Professional
<span style="direction:rtl;float:left;margin-right:10px;">
<mrNavButton Name=’Next’/>
<mrNavButton Name=’Prev’/>
</span>
<mrNavButton Name=’First’/>
<mrNavButton Name=’Last’/>
<mrNavButton Name=’Goto’/>
<mrNavButton Name=’Stop’/>
</span>
</mrSubTemplate>
Default Error Template
This template is used to determine the appearance of any error messages on an interview page, if
no custom template is defined in the interview script.
<mrSubTemplate>
<mrErrorText/>
<br/>
</mrSubTemplate>
Default Banner Template
This template is used to determine the appearance of the banners on an interview page, if no
custom template is defined in the interview script.
<mrSubTemplate>
<mrBannerText/>
<br/>
</mrSubTemplate>
Template XML Schema
The Template XML Schema describes the XML code that is substituted for tags used in interview
scripting templates.
mrBannerText Element
Insertion marker for interview banner text

1132
Chapter 1
Table 1-1
Attributes for mrBannerText
Attribute Use Description Valid Values
Index optional The index of the banner positiveInteger
to be inserted. If an
index or name is not
supplied, all banners not
referenced by an index
or name are inserted
here.
Name optional The name of the banner string
to be inserted. If a
name or index is not
supplied, all banners not
referenced by an name
tag are inserted here.
XML Representation
<xs:element name="mrBannerText">
<xs:attribute name="Index" type="xs:positiveInteger" use="optional"></xs:attribute>
<xs:attribute name="Name" type="xs:string" use="optional"></xs:attribute>
</xs:element>
mrData Element
Insertion marker for questions

Table 1-2
Attributes for mrData
AutoComplete optional Controls whether boolean
auto-completion is
enabled for the question.
This is an IE specific
feature and by default is
disabled.
Index optional The Index of the positiveInteger
question to be inserted.
If the Index and
QuestionName is
not supplied, all
unreferenced questions
are inserted here.
Name optional The Name of the string
question banner to
be inserted.
1133
Base Professional

QuestionElement optional The question element to Error. The data tag
be inserted at this tag. If indicates the insertion
the question element is point for the error text.
not specified, all of the
question elements are Label. The data tag
inserted at this tag. indicates the insertion
point for the label text.
Controls. The data tag
indicates the insertion
point for the question
controls.
Banner. The data tag
indicates the insertion
point for the question
banners.
Parameter.
QuestionName optional The QuestionName string
of the question to be
inserted. If the Index
and QuestionName
is not supplied, all
unreferenced questions
are inserted here.
ShowErrors optional Controls what errors are All. Display all errors
shown.
TopMost. Display top
level errors only
BottomMost. Display
bottom level errors only
TopAndBottomMost.
Display top and bottom
level errors
Type optional QuestionName
FullQuestionName
Min
Max
ImageLocation
XML Representation
<xs:element name="mrData">
<xs:attribute name="Index" type="xs:positiveInteger" use="optional"></xs:attribute>
<xs:attribute name="QuestionName" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="QuestionElement" type="QuestionElementTypes" use="optional">
<xs:enumeration value="Error"></xs:enumeration>
<xs:enumeration value="Label"></xs:enumeration>
<xs:enumeration value="Controls"></xs:enumeration>
<xs:enumeration value="Banner"></xs:enumeration>
<xs:enumeration value="Parameter"></xs:enumeration>
</xs:attribute>
<xs:attribute name="Name" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="Type" type="ParameterTypes" use="optional">
<xs:enumeration value="QuestionName"></xs:enumeration>
<xs:enumeration value="FullQuestionName"></xs:enumeration>
1134
Chapter 1
<xs:enumeration value="Min"></xs:enumeration>
<xs:enumeration value="Max"></xs:enumeration>
<xs:enumeration value="ImageLocation"></xs:enumeration>
</xs:attribute>
<xs:attribute name="AutoComplete" type="xs:boolean" use="optional" default="true"></xs:attribute>
<xs:attribute name="ShowErrors" type="ShowErrorsTypes" use="optional" default="BottomMost">
<xs:enumeration value="All"></xs:enumeration>
<xs:enumeration value="TopMost"></xs:enumeration>
<xs:enumeration value="BottomMost"></xs:enumeration>
<xs:enumeration value="TopAndBottomMost"></xs:enumeration>
</xs:attribute>
</xs:element>
mrNavBar Element
Insertion marker for the navigation bar
XML Representation
<xs:element name="mrNavBar"></xs:element>
mrNavButton Element
Insertion marker for a navigation button

Table 1-3
Attributes for mrNavButton
Disabled optional The file name of the string
disabled button image.
The layout template
image overrides any
image specified in the
Player XML.
Enabled optional The file name of the string
enabled button image.
The layout template
image overrides any
image specified in the
Player XML.
Name required Next
Prev
First
Last
Stop
Goto
Text optional The navigation button string
text.
XML Representation
<xs:element name="mrNavButton">
<xs:attribute name="Name" type="NavButtonTypes" use="required">
<xs:enumeration value="Next"></xs:enumeration>
1135
Base Professional
<xs:enumeration value="Prev"></xs:enumeration>
<xs:enumeration value="First"></xs:enumeration>
<xs:enumeration value="Last"></xs:enumeration>
<xs:enumeration value="Stop"></xs:enumeration>
<xs:enumeration value="Goto"></xs:enumeration>
</xs:attribute>
<xs:attribute name="Text" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="Enabled" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="Disabled" type="xs:string" use="optional"></xs:attribute>
</xs:element>
mrPage Element
Defines the HTML generation settings for the page. All formatting should be defined via CSS.
Table 1-4
Attributes for mrPage
BannerTemplate optional The relative path to string
the banner template
to use when replacing
mrData tags that specify
a question Banner
element.
ErrorTemplate optional The relative path to string
the error template to
use when replacing
mrData tags that specify
a question Error element.
GridTemplate optional The relative path to string
the grid template to
use to format loop
categorical and loop
numeric questions
IncludeCSSNames optional Controls whether CSS boolean
class names will be
added to the rendered
HTML.
IncludeElementIDs optional Controls whether IDs boolean
will be added for
elements in the rendered
HTML. NOTE: This
may need to change
to an enum to control
where IDs get added.
IncludeGridControlAltLabels optional Controls whether boolean
alternative text will
be added to the rendered
HTML for controls
within a table.
IncludeTableHeadings optional Controls whether boolean
row/column headings
will be added to the
rendered HTML for
table questions.
1136
Chapter 1

LabelXSL optional The relative path to the string
label XSL file to use
when creating HTML
for the question label
element.
NavBarTemplate optional The relative path to string
the NavBar template
to use when replacing
mrNavBar tags.
NavgationXSL optional The relative path to the string
question XSL file to use
when creating HTML for
the navigation element.
QuestionTemplate optional The relative path to the string
question template to use
when replacing mrData
tags that do not specify a
question element.
QuestionXSL optional The relative path to the string
question XSL file to use
when creating HTML
for the question element.
XML Representation
<xs:element name="mrPage">
<xs:attribute name="IncludeCSSNames" type="xs:boolean" use="optional" default="true"></xs:attribute>
<xs:attribute name="IncludeElementIDs" type="xs:boolean" use="optional" default="false"></xs:attribute>
<xs:attribute name="IncludeGridControlAltLabels" type="xs:boolean" use="optional"
default="false"></xs:attribute>
<xs:attribute name="IncludeTableHeadings" type="xs:boolean" use="optional"
default="false"></xs:attribute>
<xs:attribute name="QuestionTemplate" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="NavBarTemplate" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="ErrorTemplate" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="BannerTemplate" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="GridTemplate" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="LabelXSL" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="QuestionXSL" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="NavgationXSL" type="xs:string" use="optional"></xs:attribute>
</xs:element>
mrPageTitle Element
Insertion marker for the interview title
XML Representation
<xs:element name="mrPageTitle"></xs:element>
1137
Base Professional
mrProgressBar Element
Insertion marker for a progress bar

Table 1-5
Attributes for mrProgressBar
Color optional The color of the progress string
bar
Image optional The image to be used for string
the progress bar
Orientation optional Progress bar orientation Horizontal
Vertical
ShowBar optional Controls the display of boolean
the progress bar
ShowCounts optional Controls the display of AsPercentage. Display
the progress counter counter as percentage
AsValues. Display
counter in the
form ‘Question
Answered’/’Estimated
number of questions’
False. Do not display a
progress counter
XML Representation
<xs:element name="mrProgressBar">
<xs:attribute name="Color" type="xs:string" use="optional" default="Blue"></xs:attribute>
<xs:attribute name="Image" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="ShowBar" type="xs:boolean" use="optional" default="true"></xs:attribute>
<xs:attribute name="ShowCounts" type="ShowCountsTypes" use="optional" default="False">
<xs:enumeration value="AsPercentage"></xs:enumeration>
<xs:enumeration value="AsValues"></xs:enumeration>
<xs:enumeration value="False"></xs:enumeration>
</xs:attribute>
<xs:attribute name="Orientation" type="Orientation" use="optional" default="Horizontal">
<xs:enumeration value="Horizontal"></xs:enumeration>
<xs:enumeration value="Vertical"></xs:enumeration>
</xs:attribute>
</xs:element>
mrRef Element
Insertion marker for reference tags (e.g IMG, A etc)

Table 1-6
Attributes for mrRef
href optional string
RefPosition optional string
1138
Chapter 1

RefType required HTML tag name to be string
inserted
src optional string
XML Representation
<xs:element name="mrRef">
<xs:attribute name="RefType" type="xs:string" use="required"></xs:attribute>
<xs:attribute name="RefPosition" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="href" type="xs:string" use="optional"></xs:attribute>
<xs:attribute name="src" type="xs:string" use="optional"></xs:attribute>
</xs:element>
Interview Object Model
The Interview Object Model (IOM) implements interview-specific logic for mrScript.
Sample Management Object Model
The sample management object model creates and manipulates respondent records as defined by
the functions in the sample management script. For example, you can use sample management
to move records between queues as a way of tracking the status of each respondent over the
course of the interview. This section describes the object model and the properties and methods
of each object.
When creating sample management objects, always use the Create methods of the object in its
collection. You must never use the generic VBScript CreateObject or New commands, because
these commands do not enable you to control the process in which the object is created. This
means that the object may be unusable by sample management.
Do not use the names of methods or properties in the object model as the names of local
variables in the sample management script as this will cause the script to fail. In many cases,
failure does not occur at the point at which the variable is first mentioned, but rather at some point
later in the script when the variable’s value is used.
Quota Object Model
In the Sample Management script, you can check quota counts, and control when respondents are
added to the Completed, Pending and Rollback counts. This chapter describes the quota objects
and their properties and methods.
For information about quotas based on data gathered via the interview script, refer to How the
Quota System Works (ms-its:Intro.chm::/quota_how_works.htm)How the Quota System Works .
1139
Base Professional
Figure 1-231
How quota objects relate to the quotas you define
Male Female
Under 18 125 125
18-24 150 150 QuotaGroup object
25-34 150 150
35-44 150 150
45-54 150 150
55-64 150 150 QuotaEngine object
containing two QuotaGroup
Over 65 125 125
objects
The Quotas collection in

North South West this QuotaGroup
AB 175 175 175
C1 175 175 175 Individual Quota object
C2 175 175 175
DE 175 175 175
Interview Database Binder Object Model
The Interview Database Binder object model provides support for unbounded loops and access
to unexpanded arrays by exposing the IInterviewDatabaseBinder interface; this component is
available for both VDATA and HDATA identifiers.
The following diagrams shows how data is read/written for bound versus unbounded loops:
1140
Chapter 1
Table Scripting
IBM SPSS Data Collection Survey Reporter Professional includes components that enable
you to create sophisticated survey and market research tables using a script. IBM SPSS Data
Collection Survey Reporter Professional is compatible with IBM® SPSS® Data Collection
Survey Tabulation, so you can use IBM® SPSS® Data Collection Base Professional to set up
tables in the form of a table document (.mtd) file, and then open the file in Survey Tabulation
for further analysis.
This section provides documentation on how to write scripts to generate tables. The following
table provides a summary of the documentation in this section.
Getting Started This section walks you through some basic sample
scripts, which demonstrate some of the most
commonly used features available in IBM SPSS
Data Collection Survey Reporter Professional.
Table Specification Syntax This section provides information about the table
specification syntax, including information on
how to create elements, the base element, and
understanding axes.
Cell Contents This section provides information about the cell
contents that you can include in your tables,
and explains the weighting and rounding that is
performed by IBM SPSS Data Collection Survey
Reporter Professional.
Hierarchical Data This section provides information about working
with hierarchical data.
Statistical Tests This section provides information about the
statistical tests you can run on your tables.
Table Presentation This section provides information about some of
the options that are available for adjusting the
presentation of your tables, such as sorting, hiding
low values, defining zero symbols, etc.
Annotations This section provides information about using
annotations to display additional details on your
tables.
1141
Base Professional
Working with Profile Tables This section provides information about how to
create profile tables to display non-aggregated data.
Working with Metadata This section provides information about working
with versions, labels, and languages.
Working with Change Tracker This section provides information about creating
variable folders and storing derived variables, or
other metadata edits, in .mtd files.
Working with the Variables Interface This section provides information on creating new
variables and folders, for tabulation, in script.
Exporting Tables This section provides information about exporting
your tables to HTML, Microsoft Excel, Word, and
PowerPoint, and text files.
Working with Axis Expressions This section provides information on saving axis
specifications in the metadata.
Sample Table Scripts This section provides a full list of the table script
example files that are provided with the IBM®
SPSS® Data Collection Developer Library, with
details of where to find further information about
them and how to run them.
Limits This section describes the limits built into IBM
SPSS Data Collection Survey Reporter Professional.
Table Object Model Reference This section provides detailed reference information
about the objects, methods and properties in the
Table Object Model.
Metadata Services Object Model Reference This section provides detailed reference information
Metadata Service Object Model.
QsfTom component object model reference This section provides detailed reference information
QsfTom Component Object Model.
The following table provides a summary of topics located in other sections of the Data Collection
Developer Library that contain related information.
What’s New Part of the Base Professional section, this section
includes details of What’s New in Table Scripting
in this release.
Table Scripting in a Data Management Script Part of the Data Management Scripting section, this
section describes how to create tables using a data
management script.
Part of the IBM® SPSS® Data Collection Scripting
section, this section contains information on
learning mrScriptBasic, including syntax reference
topics.
Requirements
This documentation includes a number of mrScriptBasic examples. To run these examples,

you need to have Base Professional Tables Option. Some of the examples have additional
requirements, which are explained in the text.
1142
Chapter 1
Getting Started
This section takes you through a number of sample scripts and introduces you to some of the main
features of IBM® SPSS® Data Collection Base Professional Tables option. This tutorial assumes
that you already have a basic understanding of mrScriptBasic. If you are new to mrScriptBasic,
see Table Scripting Syntax Quick Reference for information on the basic syntax of table scripting
files and links to topics providing detailed information on learning mrScriptBasic.
This tutorial has been designed to be worked through in order. Each topic builds on what you
learned in the previous topics. If you work through the topics from beginning to end, you will
have a good grasp of the basics of creating tables using scripts and should find it easy to add to
your knowledge by referring to the rest of the documentation in this section. How long it takes you
to work through the topics will depend to a certain extent on your familiarity with mrScriptBasic
and object-oriented programming and whether you also run the samples. In addition the length of
the topics vary. However, an average of 30 minutes per topic is probably a realistic estimate.
The examples in this tutorial use the sample data sets that are installed with the IBM®
SPSS® Data Collection Developer Library. By default, the sample data is installed in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data folder.
You can create your own scripts as you follow each topic in the tutorial. You
can also run the sample scripts supplied with the Data Collection Developer
Library (this is recommended). By default, the sample scripts are installed in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables folder. Before you run the
samples, check that the file and folder names and locations are correct for your system, and if
necessary edit the samples accordingly.
How table sequence affects population time
The table sequence directly affects the table population time. To understand this, we must first
understand aggregation. When aggregating data, TOM scans data from beginning to end. The
scanning is based on the HDATA structure. When variables on several tables are at the same level
structure, and share the same bottom level, data aggregation is accomplished in a single pass.
What is the same level structure?
Using household.mdd as an example, person[..].trip[..].country and person[..].gender are at the

same level structure because the trip level is the child of the person level. All of the variables
under the two levels are at the same level structure. All variables at the top level are considered to
be at the same level structure as the other levels.
Although person[..].trip[..].country and person[..].gender are at the same level structure, their level
is actually different. The level for person[..].trip[..].country is person[..].trip while the level for
person[..].gender is person.
What is bottom level?

1143
Base Professional
A table contains several variables on the side and top. Each variable has its own level, and the
lowest level is regarded as the bottom level. For example, the bottom level for the following
table is person[..].trip.
Person[..].trip[..].gender>region*person[..].occupation
Variable Level
Person[..].trip[..].gender person[..].trip
Region HDATA
Person[..].occupation person
The lowest level among HDATA, person, person[..].trip is person[..].trip.
How should tables be organized?
If tables that have the same bottom level are grouped together, you can aggregate the table values
in a single pass. For example, the following sequence of tables requires four passes in order to
aggregate data:
Table1 region*housetype
Table2 region*person[..].occupation
Table3 region* tenure
Table4 region*person[..].gender
Now examine the following sequence of tables that only requires two passes:
Table1 region*housetype
Table2 region* tenure
Table3 region*person[..].occupation
Table4 region*person[..].gender
Assuming that each pass takes one minute to complete, the first table sequence will take four
minutes to populate while the second will take two minutes to populate.
For step-by-step instructions for running the samples, see Running the Sample Table Scripts.
The following table lists the topics in this section and the names of the related samples.
Tutorial Topics Related Samples
1. Creating a Simple Table of Age by Gender MyFirstTable.mrs
2. Creating a Frequency Table and Defining Cell MyFirstFrequencyTable.mrs
Contents
3. Handling Zero Values and Setting Hide Rules ZeroValues.mrs
4. Concatenation and Nesting ConcatenatingAndNesting.mrs
5. More on Concatenation and Nesting MoreOnConcatenatingAndNesting.mrs
6. Reusing Axes ReusingAxes.mrs
7. Defining Your First Filter MyFirstFilter.mrs
8. More on Filters MoreOnFilters.mrs
1144
Chapter 1
Tutorial Topics Related Samples

9. Weighting Tables WeightedTables.mrs
10. Working with Numeric Variables NumericVariables.mrs
11. Creating a Grid Table MyFirstGridTable.mrs
12. Creating tables based on database questions CreatingTablesBasedOnDatabaseQuestions.mrs
13. Defining Statistical Tests StatisticalTests.mrs
14. Creating Charts HTMLCharts.mrs
15. Exporting to Excel ExcelExport.mrs
16. Loading Other Types of Data QuanceptTables.mrs
QuantumTables.mrs
QuanvertTables.mrs
RDBTables.mrs
SavTables.mrs
SurveyCraftTables.mrs
17. Opening an Existing Table Document MyFirstTable.mrs
18. Table Population and Failover FailoverDemo.mrs
Creating a Simple Table of Age by Gender
Sample script file: MyFirstTable.mrs
This example opens the Museum sample data set, creates a simple table of age by gender, and
exports it to an HTML file. It shows a complete script with the minimum setup required to create
and export a basic table.
Note: This topic explains how to create and run a script using IBM® SPSS® Data Collection Base
Professional, but you can also create the script using a text editor such as Notepad, and run it using
the mrScript Command Line Runner. The content of the script is the same whichever method you
use, but additional features are available in Base Professional to help you create and run the script.
E Open Base Professional.

File > New > File
E Click the mrScriptBasic File icon:

Figure 1-232
mrScriptBasic File icon
E Type MyFirstTable.mrs in the File Name field, then click Open.
This creates a new file in Base Professional.

E On the first line of the new file, type:
' My first table
Beginning the line with an apostrophe (‘) indicates that it is a comment. Everything after the
apostrophe is ignored when you run the script. Note that any completely blank lines are also
1145
Base Professional
ignored, so as you create your script you can insert extra blank lines if you wish, to make it
easier to read.
E On a new line, type:
Dim TableDoc
The first word, Dim, is highlighted as you type it, because Base Professional recognizes it as a
keyword. The Dim statement declares a new variable, in this case TableDoc, for use in your script.
Set TableDoc = CreateObject("TOM.Document")
This time, two keywords, Set and CreateObject, are highlighted as you type them. This line of
script does two things: it creates a new Table Object Model Document object (“TOM.Document”),
and it assigns this object to the new TableDoc variable that you declared in the previous line. This
means that from now on in your script, the variable TableDoc represents a Document object, and
all the properties and methods for this type of object are available whenever you use it. For more
detailed information on the properties and methods available to the Document object, see the topic
on the Document Object in the Table Object Model section.
E Next, type the following lines exactly as shown:
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\museum.mdd", _
, "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\museum.xml", _
"mrXmlDsc")
As you type the dot after TableDoc, you will see that a drop-down list appears. This is the Base
Professional ScriptAssist feature. As you have now set the TableDoc variable to represent a
Document object, ScriptAssist recognizes the variable as such and suggests a list of all the
properties and methods that are available for this object. If you wish, you can select the DataSet
property from the drop-down list by double-clicking it, rather than typing it in. The ScriptAssist
feature will appear again as you continue to build your script.
Although the above segment of script appears on three separate lines, it actually represents a
single line of script:
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\museum.mdd", , "[INSTALL_FOLDER]\IBM\SPSS\
As the line is very long, we have split it into three to make it easier to read using the line
continuation indicator, a space followed by an underscore ( _), immediately before each line break.
Note: Ensure that the underscore is the final character on the line; if any character follows the
underscore, even a space, the line will produce an error when you run the script. Also note that
as all the lines in this section are part of a single line of script, you cannot insert blank lines
between them.
The DataSet.Load method loads the survey data required to create the table. The three parameters
give the name and location of the Museum sample metadata (.mdd) file and case data (.xml) file
and specify that the XML CDSC is used to read the case data. In fact only the first parameter
1146
Chapter 1
(which specifies the name and location of the metadata file) is required. For example, you could
simply put:
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\museum.mdd")
When you do not specify the parameters for the XML file and the CDSC, this information is
automatically picked up from the default data source property in the metadata file. This is all
that is required if you have installed the sample data in the default location, because the default
data source in the Museum sample .mdd file points to the case data file in the default location.
However, if the sample data has been installed in another location, you must specify the XML
and CDSC parameters as shown in the sample script, or change the location specified in the .mdd
file. For more information, see the topic Editing the Default DataSource Information in the
Museum.mdd File on p. 419. Therefore, it is a good idea to include these parameters in your
scripts, to make them easier to update if you change the data set file name or path.
TableDoc.Tables.AddNew("Table1", "age * gender", "My First Table")
The Tables.AddNew method creates a new table. The first parameter is the table name, the second
defines the structure, and the third is the table description. In this example, the syntax of the table
structure is age * gender, which specifies that the age variable forms the side axis (the rows of the
table) and the gender variable forms the top axis (the columns of the table).
TableDoc.Populate()
This line generates the table structure and calculates the values for each cell of the table you
have specified.
TableDoc.Save("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.mtd")
This line saves all the information about the table document, including the data source details,
details of the table specification, and the results, to a file.
E Next, type the following lines:
With TableDoc.Exports.mrHtmlExport
.Export("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.htm")
End With
This block of script sets a number of properties to configure the export and exports the table in
HTML format to the file MyFirstTable.htm.
1147
Base Professional
The With...End With structure is a compact way of setting a number of properties and methods that
apply to the same object, and is the equivalent of writing the following lines, which specify each
property and method individually:
TableDoc.Exports.mrHTMLExport.Properties["Interactive"] = True
TableDoc.Exports.mrHTMLExport.Properties["LaunchApplication"] = True
TableDoc.Exports.mrHTMLExport.Properties["DisplayOption"] = "Table Only"
TableDoc.Exports.mrHTMLExport.Export("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.htm")
The complete script should now look like this:
' My first table

Dim TableDoc
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\museum.mdd", _
, "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\museum.xml", _
"mrXmlDsc")
TableDoc.Tables.AddNew("Table1", "age * gender", "My First Table")
TableDoc.Populate()
.Export("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.htm")
End With
E Press Ctrl+S to save the file, and select a suitable location to save it in. If you want to save it in
the same folder as the supplied sample files you will need to choose another file name, as the
sample MyFirstTable.mrs file is read-only. Alternatively, you can save the file in a different folder
provided that it is on a drive that can access the drive containing the sample data and output folders.
E Press F5 to run the script.

1148
Chapter 1
Here is the table produced by the script:

Figure 1-233
Table of age by gender
In the Museum sample data set, age and gender are categorical variables. These have a
limited number of distinct values or categories, and are typically based on questions that have a
predefined set of answers.
In the Museum data set, the gender variable contains two categories—Male and Female. Notice
that the top axis of the table contains three columns, one for each of the categories in the gender
variable and a special base column, which shows the number of cases for which the variable
stores a value that is not null. In a variable based on a question, this is typically the number of
respondents who were asked the question. Similarly, there is a base row on the side axis. The
Table Object Model automatically creates a base element in each variable, if the variable does not
already contain one.
This table shows two figures in each table cell. These are known as the cell contents and, because
we did not explicitly define the cell contents we wanted to show, the default cell contents are
used. These are counts (which show the number of respondents that satisfy the row and column
conditions for each cell) and column percentages. The next topic shows you how to display other
values in the cells, such as cumulative percentages.
Requirements
IBM SPSS Data Collection Survey Reporter Professional 2.0 or later

1149
Base Professional
Creating a Frequency Table and Defining Cell Contents
Sample script file: MyFirstFrequencyTable.mrs
This example creates a table that has one categorical variable on the side axis and includes
all of the information shown in a standard frequency table—counts, column percentages, and
cumulative column percentages.
Const MDD_FILE = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\Museum.mdd"

Const XML_FILE = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\Museum.xml"
Const EXPORT_FILE = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstFrequencyTable.htm"
Dim TableDoc, Table
TableDoc.DataSet.Load(MDD_FILE, , XML_FILE, "mrXmlDsc")
Set Table = TableDoc.Tables.AddNew("Education", "education", _

"Frequencies in full-time education")
Table.CellItems.AddNew(9, 2) ' itCumColPercent = 9
Table.CellItems[1].Decimals = 2
TableDoc.Populate()
.Export(EXPORT_FILE)
End With
User-Defined Constants
Notice that the DataSet.Load method highlighted above looks different from the version shown in
Creating a Simple Table of Age by Gender. This example uses exactly the same parameters to
open the museum sample data set, but specifies the file location parameters using user-defined
constants:

Const XML_FILE = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\Museum.xml"
This is a useful method of specifying file paths and other parameters that you need to change from
time to time or that you use more than once in a script. You specify the constant at the start of the
script, then each time you need to refer to the path, you can type the name of the constant instead.
When you change a file name or path you only need to make the change once, at the start of the file.
1150
Chapter 1
An additional constant specifies the export file path:
Const EXPORT_FILE = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstFrequencyTable.htm"
You will find that subsequent sample scripts in this tutorial use constants in this way, to make it
easier to adapt the scripts when data sets are not in the default locations, or when you want to use
the scripts with your own data sets.
Cell Contents Collection
Notice that the Table.CellItems collection is highlighted. This defines the cell contents for the
table. Each item in the cells of the table is a separate CellItem object in this collection. The second
highlighted line in the above example adds a new cell item for cumulative column percentages
to the collection and sets its decimal precision to 2.
Cell Item Constants
The Available Cell Contents topic lists all of the types of cell contents that are available and the
constants and their associated values that you use to specify them in your scripts. You can also
get a list of the constants and their associated values in the IBM® SPSS® Data Collection Base
Professional Types pane. For more information, see the topic The IBM SPSS Data Collection
Base Professional Window on p. 13.
Figure 1-234
IBM SPSS Data Collection Base Professional Types pane
1151
Base Professional
You can use the constants only if your script is part of a data management script (.dms) file,
because the Table Object Model is then registered with the mrScript engine, which makes the
constants built into the Object Model available to the script. If your script is a standalone
mrScriptBasic (.mrs) file, you must use the numeric value or set up user-defined constants to
represent the values. For example, if you want to include this example in a data management
script you could replace the highlighted line with the following:
Table.CellItems.AddNew(CellItemType.itCumColPercent, 2)
Note that unlike Visual Basic, you need to prefix the constant name with the type definition name,
otherwise you will get an error (typically “Undefined variable”). This is because mrScriptBasic
handles constant namespaces differently from Visual Basic.
Notice that the position of the new item in the collection is not specified in this example. This
means that the new item is automatically added to the end of the collection and so the cumulative
column percentages will appear after the counts and column percentages that are included as the
first and second items by default.
If you wanted the cumulative column percentages to appear first, you would set the Index
parameter to 0, like this:
Table.CellItems.AddNew(9, 2, , 0)
You specify the position as 0 because it is controlled by a zero-based index. Zero-based means
that the first item has index 0, the second item has index 1, etc.
Decimal Places
The third highlighted line in the script sets the decimal precision for the column percentages to 2.
Notice that we access the item in the collection by the index, which corresponds to its position in
the collection. As noted above, it is a zero-based index, which means that you access the first
item as 0, the second as 1, the third as 2, etc.
1152
Chapter 1

Figure 1-235
Table of Education variable showing cumulative column percentages
Default Cell Contents
You may be wondering where the default cell contents come from and whether you can change
them. The answer is that when you create a table, the default cell items are taken from the
Document.Default.CellItems collection. You can add items to this collection in the same way that
you can add items to the Table.CellItems collection. If you want to remove one of the default cell
contents, you use the Remove method, like this:
TableDoc.Default.CellItems.Remove(1)
Note that removing an item from the Default.CellItems collection only affects tables that you
subsequently create. It does not affect tables that you have already created. This means that if
you want to use this line to remove the column percentages from the table, you would need to
insert this line into the script before the line that creates the table.
Table Display Features
Details of the cell contents are shown in the table footer. Headers and footers show are created
using the annotation feature. In the example table above, the header and footer were created
automatically using the default annotations. However, it is easy to change the default annotations
or to set up customized annotations for individual tables. For more information, see the topic
Annotations on p. 1432.
If you look at the table again, you will notice that the column percentages for the Not answered row
are shown as a hyphen (-). This is the default character that is displayed for zero percentage values.
The next topic shows you how to change this character and to hide all-zero rows and columns.
1153
Base Professional
Requirements
Handling Zero Values and Setting Hide Rules
Sample script file: ZeroValues.mrs
In Creating a Frequency Table and Defining Cell Contents, we saw that the default character
for zero percentage values is a hyphen (-). You can define six separate special characters to
be displayed instead of 0 for zero counts, percentages, and other cell contents, and for counts,
percentages, and other cell contents values that are rounded to zero, respectively. You can use any
string for these characters and you define them using the table properties. You can define these
characters for individual tables or as defaults to apply to all new tables.
You can also hide rows and columns in which all of the values are zero by defining hide rules
or manually removing the rows and columns from the table.
The examples in this topic assume that you have already created the Table Document object and
loaded the Museum sample data set as shown in Creating a Simple Table of Age by Gender. The
examples in this topic create tables using the education and before variables, which both have a
Not answered category that was not selected by any respondents.
First let’s create a table that shows zero values as asterisks:
Dim Table1
Set Table1 = TableDoc.Tables.AddNew("ShowAsterisks", "education * before", _

"Show zero values as asterisks")
Table1.Properties["ZeroCountSymbol"] = "*"
Table1.Properties["ZeroPercentSymbol"] = "**"
Notice that the last two lines set the table’s ZeroCountSymbol and ZeroPercentSymbol properties to
“*” and “**”, respectively. This means any true zero count values in this table will be displayed as
a single asterisk and any true zero percentage values in this table will be displayed as two asterisks.
If you want to use these symbols in all your tables, you could set the default properties rather than
the properties on each individual table. Changing the default properties does not affect tables that
have already been created. This means that if we want the new default setting to apply to our table,
we need to put the line that sets the defaults before the line that creates the table, like this:
TableDoc.Default.Properties["ZeroCountSymbol"] = "*"
TableDoc.Default.Properties["ZeroPercentSymbol"] = "**"
Set Table1 = TableDoc.Tables.AddNew("ShowAsterisks", "education * before", _

"Show zero values as asterisks")
1154
Chapter 1
You can set a different display value for counts and percentages that are rounded to zero using the
RoundZeroCountSymbol and RoundZeroPercentSymbol properties. The default value for these
properties is an asterisk. For a full list of other similar properties that you can set on individual
tables or as table document defaults, see Table Properties.

Figure 1-236
Table showing zero values as asterisks
The next table has two hide rules, to hide rows and columns in which all of the values are zero.
Dim Table2
Set Table2 = TableDoc.Tables.AddNew("HideZeros", "education * before", _

"Hide zero rows and columns")
Table2.Rules.AddNew()
Table2.Rules.AddNew(, 1) ' rtColumn = 1
1155
Base Professional

Figure 1-237
Table with zero rows and columns hidden
Notice that details of the hide rules are shown in a footer. For more information, see the topic
Annotations on p. 1432.
Instead of defining hide rules to hide zero values, you can set up hide rules to hide values greater
or less than a certain value. In addition, you can set up default hide rules to apply to all new tables.
An alternative method of hiding rows or columns is by explicitly removing them from the axis.
For example, the following example actually removes from the table the row and column for
the two Not answered categories:
Dim Table3
Set Table3 = TableDoc.Tables.AddNew("RemoveEmptyElements", "education * before", _

"Remove empty elements")
Table3.Axes["Side"].SubAxes[0].Elements.Remove("Not_answered")
Table3.Axes["Top"].SubAxes[0].Elements.Remove("Not_answered")
1156
Chapter 1

Figure 1-238
Table with empty elements removed
Requirements
Concatenation and Nesting
Sample script file: ConcatenatingAndNesting.mrs
This topic shows you how to add two variables to the same axis of a table using two different
methods: concatenating and nesting. We will create two tables using the same three variables.
Both tables have the age variable on the side axis. However, in the first table interview and
gender are concatenated on the top axis, and in the second table gender is nested within interview
on the top axis.
These examples assume that you have already created the table Document object and loaded the
Museum sample data set as shown in Creating a Simple Table of Age by Gender.
First, remove the column percentages from the default cell items collection so that the table
will show only counts:
TableDoc.Default.CellItems.Remove(1)
Next, create the first table, in which interview and gender are concatenated on the top axis. To
concatenate variables on an axis, you use the + operator:
TableDoc.Tables.AddNew("Table1", "age * interview + gender", _

"My First Concatenated Table - Age by Interview and Gender")
1157
Base Professional
Figure 1-239
Table with concatenated variables
When you concatenate variables, the variable elements are displayed separately, as if each variable
is a separate table in the same display. The interview variable records whether respondents were
interviewed as they were entering or leaving the museum. This table shows the age breakdown of
the male and female respondents and the age breakdown of the respondents who were interviewed
entering and leaving. However, it does not show the gender breakdown of the respondents who
were interviewed as they were entering nor of those who were interviewed as they were leaving.
For that you need to nest gender within interview. When you nest variables, you use the > operator:
TableDoc.Tables.AddNew("Table2", "age * interview > gender", _

"My First Nested Table - Age by Gender within Interview")
Figure 1-240
Table with nested variables
1158
Chapter 1
Notice how the nested table gives the gender breakdown of the two groups of respondents (those
who were interviewed entering and those who were interviewed leaving).
Note: Only the weight or the multiplier in the lowest level is honored when applying weights,
for the element of different variables, at different nest levels. Refer to Element Properties for
additional information on setting a weight or a multiplier for a variable element.
The next topic, More on Concatenation and Nesting, provides more complex examples of
concatenation and nesting, for example, creating tables with more than one level of nesting and
combining nesting and concatenation in one table.
Requirements
More on Concatenation and Nesting
Sample script file: MoreOnConcatenatingAndNesting.mrs
In Concatenation and Nesting we learned about the difference between concatenating and nesting
variables on the table axes. This topic shows how to create tables with more complex nesting and
concatenation. It also shows you how to use a With statement to create multiple tables. Here
is the script that creates the tables:
.AddNew("Table1", "gender > age * before > interview > entrance")
.AddNew("Table2", "gender + interview + entrance * education + biology")
.AddNew("Table3", "gender > interview + entrance * education + biology")
.AddNew("Table4", "gender > (interview + entrance) * education + biology")
.AddNew("Table5", "(gender + entrance) > interview * education + biology")
.AddNew("Table6", "education as education1 > gender + education as education2 > biology")
End With
1159
Base Professional
Let’s look at the script for each table in turn. First, look at the line that creates the first table. The
table has one level of nesting on the side axis and two levels of nesting on the top axis. Here
is the table produced by the script:
Figure 1-241
Table showing multiple levels of nesting
1160
Chapter 1
Although there is no built-in limit to the number of nesting levels that you can specify, there is a
limit to the number of “sections” that a nested table can contain on the side or top axis. For more
information, see the topic Limits on p. 1555. However, as this example demonstrates, each
additional level of nesting rapidly increases the number of cells in the table. This increases the
time it takes to populate the table and can make the table hard to present, understand, and interpret.
Now look at the script that creates the second table. This concatenates three variables on the side
and two on the top.
.AddNew("Table2", "gender + interview + entrance * education + biology")

Figure 1-242
Table showing concatenation on side and top axes
There is no built-in limit to the number of variables you can concatenate on an axis. Generally it is
the problems involved in presenting and interpreting very large tables that set the limits.
You can combine nesting and concatenation in one axis, as shown in the third table:
.AddNew("Table3", "gender > interview + entrance * education + biology")
Notice that on the side axis of this table interview is nested within gender, and entrance is
concatenated with gender. This type of construction is sometimes referred to as an “unbalanced
tree”.
1161
Base Professional

Figure 1-243
Table combining concatenation and nesting
The > operator has a higher precedence than the + operator, but you can override the order of
precedence using parentheses. The fourth table uses parentheses to concatenate interview and
entrance before nesting them within gender:
.AddNew("Table4", "gender > (interview + entrance) * education + biology")

1162
Chapter 1

Figure 1-244
Table showing combination of concatenation and nesting
The fifth table uses parentheses to concatenate gender and entrance before nesting interview
within them:
.AddNew("Table5", "(gender + entrance) > interview * education + biology")

1163
Base Professional

Figure 1-245
Table showing combination of concatenation and nesting
In some cases you may want to use same variable twice in a single axis. For example, you may
want to nest two variables within a third variable, and display the results in the same table. You
can do this in IBM SPSS Data Collection Survey Reporter Professional 2.3 and later, by using
the As keyword:
variable as variable1 > variable as variable2
The sixth table uses two education variables, one with gender nested within it and the other with
biology nested within it, and concatenates the two education variables.
.AddNew("Table6", "education as education1 > gender + education as education2 > biology")

1164
Chapter 1

Figure 1-246
Table showing the same variable twice on one axis
Requirements
Reusing Axes
Sample script file: ReusingAxes.mrs
In More on Concatenation and Nesting we learned how to create tables with complex nesting and
concatenation. Sometimes you may want to build a complex “banner” axis containing nested or
concatenated variables for use in a set of tables. When you want to do this, you don’t have to
define the axis again and again for each table. You can simply create the axis once and then
reuse it in as many tables as you want.
You create a reusable axis by adding a new axis to the Document.Axes collection. For example,
this script concatenates age and gender to form a reusable axis:
Dim Axis
Set Axis = TableDoc.Axes.AddNew("MyBanner")

Axis.Specification = "age + gender"
1165
Base Professional
To add a reusable axis to a table, you precede the axis name with the axis keyword and enclose
the axis name in parentheses. For example, the following script uses the “MyBanner” axis as
the top axis in three tables:
.AddNew("Entrance", "entrance * axis(MyBanner)")
.AddNew("Education", "education * axis(MyBanner)")
.AddNew("Similar", "similar * axis(MyBanner)")
End With
Note: In the sample script this section is commented out, so to create these tables you need to
remove the initial apostrophe (') from each line of the With statement.
Here are the tables produced by the script:

Figure 1-247
Three tables using the same top axis
The next example is an advanced example of using the banner in multiple tables without
mentioning the variables by name. This means that you can use the script on any data set. The
example uses the Table Object Model Document.DataSet.MDMDocument property to access to the
metadata in the MDM Document. For more information, see the topic Working with Metadata
on p. 1453.
The script in this example loops through the MDM Document.Variables collection and tests each
VariableInstance object to see whether it is a simple categorical variable. If it is, the script creates
a table with the variable on the side axis and the reusable axis on the top axis.
Dim MyVariableInstance, MyCounter, MyTableName, MyTableSpec, MyTableDescription
' Set the counter to zero

MyCounter = 0
' Loop through the top-level variable instances

' and create a table using the new banner axis for all of
' the simple categorical variable instances
For Each MyVariableInstance in TableDoc.DataSet.MDMDocument.Variables
1166
Chapter 1
' Exclude grid, loop and helper variables and temporary or dummy variables that contain no data
If MyVariableInstance.DataType = mr.Categorical _
And MyVariableInstance.HasCaseData = True _
And MyVariableInstance.IsSystemVariable = False _
And BitAnd(MyVariableInstance.UsageType, 31) = 0 Then
MyCounter = MyCounter + 1
MyTableName = "Table" + CText(MyCounter)
MyTableSpec = MyVariableInstance.FullName + " * axis(MyBanner)"
MyTableDescription = MyVariableInstance.FullName
TableDoc.Tables.AddNew(MyTableName, MyTableSpec, MyTableDescription)
End If
Next
Note for advanced users: This example checks whether the variable is a simple variable by
using the function to test the bits set in the VariableInstance.UsageType property. The value 31
represents the combination of the following VariableUsageConstants: vtHelperField (16), vtGrid
(1), vtCompound (2), vtClass (4), and vtArray (8). The test makes sure that none of these bits
is set, which means that the variable instance is not inside a Grid, Class, Compound, or Array
object, or in a HelperFields collection.
Requirements
Defining Your First Filter
Sample script file: MyFirstFilter.mrs
Filters are a quick way of choosing which cases are included in a table. You can define filters
using any expression that is supported by the IBM® SPSS® Data Collection Data Model.
For example, you can create a simple table of age by gender and add a filter to the table like this:
TableDoc.Tables.AddNew("Table1", "age * gender")

TableDoc.Tables[0].Filters.AddNew("Exclude11_16s_A", _
"Not age.ContainsAny({e1116_years})")
This specifies that the table is to include all of the respondents except those who selected the 11-16
years category in response to the question on which the age variable is based. That is, respondents
between the ages of 11 and 16 will not be counted.
1167
Base Professional

Figure 1-248
Table of age by gender, filtered to exclude respondents between 11-16 years
Notice that now there are no respondents in the 11-16 years row. If you compare the values in the
Base row with those in the Base row in the table we created in Creating a Simple Table of Age by
Gender, you will see that the values in the Base row in the filtered table have been reduced by the
values that would have appeared in the 11-16 years row if no filter had been specified.
The filter has been defined using the function that is part of the IBM SPSS Data Collection
Function Library, which comes with the Data Model. You could also define the filter using the <>
comparison operator:

TableDoc.Tables[1].Filters.AddNew("Exclude11_16s_B", _
"age <> {e1116_years}")
For information about the functions that come with the Data Model, see and for examples of
using the operators, see .
Notice that in the table shown above the filter expression is displayed in a header. The header
is created automatically as a default annotation. If we had given the filter a description, the
header would show the filter description instead of the expression. Here is how you define a
description for a filter:
TableDoc.Tables[0].Filters.AddNew("Exclude11_16s_A", _
"Not age.ContainsAny({e1116_years})", "My First Filter")
You can change the default annotations or to set up customized annotations for individual tables.
For more information, see the topic Annotations on p. 1432.
In the next topic, we will look at different ways of creating filters.

1168
Chapter 1
Requirements
More on Filters
Sample script file: MoreOnFilters.mrs
In Defining Your First Filter we added a new filter to a table using the AddNew method of the
Table.Filters collection. You would typically create filters in this way when you want to specify a
filter for use in a specific table. However, you will often find that you want to use the same filter
for more than one table. The Table Object Model has a number of features to make this easy.
If you want to use the same filter on several tables, you can define the filter as a table document
filter. You do this by creating it in the Document.Filters collection. The filter is then available to
add to any table in the document. The following example creates a table document filter variable
called Exclude11_16s and uses it on a specific table:
TableDoc.Filters.AddNew("Exclude11_16s", "Not age.ContainsAny({e1116_years})")

TableDoc.Tables[0].Filters.Add("Exclude11_16s")
This time we have used the Filters.Add method to add the filter to the table. You use this method to
add a filter that has already been defined in the Document.Filters collection.
When you create a filter in this way, you need to explicitly add it to each table. However, you
may sometimes want to add the same filter to all of your tables. The easiest way to do this is to
define the filter as a global filter. You do this by creating the filter in the Document.Global.Filters
collection. The filter is then applied automatically to all of the tables. If any of the tables already
have a filter, the And operator is used to combine the global filter with the existing filters. Here is
an example of creating a global filter:
TableDoc.Global.Filters.AddNew("ExcludeOver65s", "Not age.ContainsAny({e65_years})")
However, you may sometimes want to add the same filter to some but not all of your tables.
The Document.Default.Filters collection is useful in this situation. You may remember that in
Handling Zero Values and Setting Hide Rules, we saw that when you changed the value of the
table document’s default ZeroValueSymbol property, it did not affect tables that had already been
created. Setting up a default filter works in a similar way.
Default filters are useful when, for example, you want to create two sets of tables, one of which is
filtered on men and the other on women. Here’s how you do it:
' Create a new default filter
TableDoc.Default.Filters.AddNew("Females", "gender = {female}")
' Create the second table

1169
Base Professional
' Remove the Females default filter and create a new Males default filter
TableDoc.Default.Filters.Remove("Females")
TableDoc.Default.Filters.AddNew("Males", "gender = {male}")
' Create the third table

Note that when you create a filter using the Table Object Model, it is saved with the table
document, but is not available to other table documents that use the same data set. If you want to
create filters that become “permanently” part of a data set, you should set them up as Boolean
variables in the metadata. See 3. Creating Filter Variables in the Data Management Scripting
section for more information.
Requirements
Weighting Tables
Sample script file: WeightedTables.mrs
Weighting is another term for sample balancing. You use it when you want the figures in your
tables to be an accurate reflection of the target population. For example, of the 602 respondents
interviewed in the Museum survey, 56.31% were male and 43.69% were female. However, you
may want to adjust the figures to reflect an even balance between the genders. You can do this
using the genbalance variable, which is a special weighting variable that has been set up to inflate
the responses from the female respondents and deflate the responses from the male responses so
that when you use it to weight your tables, they will reflect an even balance between the genders.
To use the genbalance variable to weight a table of age by gender like the one shown in Creating
a Simple Table of Age by Gender, you could use this script:
TableDoc.Tables.AddNew("Table1", "age * gender", "Weighted table of Age by Gender")

TableDoc.Table1.Weight = "GenBalance"
This example refers to the table in the Tables collection of the Table Document using its name.
This is possible only in mrScriptBasic because of its dynamic property expansion feature and
is equivalent to referring to the table by its index in the collection. For example, the following
lines are equivalent:
TableDoc.Tables.Table1.Weight = "GenBalance"
TableDoc.Tables[0].Weight = "GenBalance"
TableDoc.Tables["Table1"].Weight = "GenBalance"
1170
Chapter 1

Figure 1-249
Table of age by gender, weighted using genbalance variable
Notice that in this example the counts are shown with two decimal places by changing the number
of decimal places for the counts default cell item:
TableDoc.Default.CellItems[0].Decimals = 2
If you compare the results with the unweighted table we created in Creating a Simple Table of
Age by Gender, you will see that an Unweighted Base row and column have been added to the
table automatically and the base row now shows equal numbers of male and female respondents.
If a table is weighted, counts created using the Count keyword are always weighted. However,
you can add unweighted counts to the table. Here is the script to create a similar table, but this
time showing the unweighted counts as well as the weighted counts:
TableDoc.Tables.AddNew("Table2", "age * gender", "Weighted table showing unweighted counts")

TableDoc.Table2.CellItems.AddNew(8, 2) ' itUnweightedCount = 8
1171
Base Professional
Figure 1-250
Table of age by gender, weighted using genbalance variable, with weighted and unweighted counts
By default, an unweighted base element is added to all weighted tables. This is because it is
good practice to show the unweighted base values in addition to the weighted base values.
However, the unweighted base elements are not necessary in this table, because we are showing
the unweighted counts. You can stop the unweighted base elements being added to the table by
setting the AutoUnweightedBases table property to False. The unweighted base element is added
when you add the weighting to the table, so you need to set the property before you weight the
table. For example:
.AddNew("Table3", "age * gender", "Weighted table without automatic unweighted base elements")
.Table3.Properties["AutoUnweightedBases"] = False
.Table3.Weight = "GenBalance"
.Table3.CellItems.AddNew(8, 2) ' itUnweightedCount = 8
End With
Note that if we were not showing the unweighted counts in the table, we should include
the unweighted base elements, in order to comply with good practice guidelines. For more
information, see the topic The Base Element on p. 1230.
By default, details of the weighting variable are shown in the right header position. For more
information, see the topic Annotation Positions on p. 1432.
Weighting variables must be numeric variables. However, not all numeric variables are suitable
for use as weights. Generally, weighting variables are created specially, typically using the Weight
component. For more information, see the topic Working with the Weight Component on p. 406.
1172
Chapter 1
Requirements
Working with Numeric Variables
Sample script file: NumericVariables.mrs
If you have worked through the examples in this section methodically, you may have noticed that
all of the variables that we have used up to now in our tables have been categorical variables.
However, you can also use numeric variables if the variable has an axis specification defined for it
in the metadata, or if you create an axis specification that summarizes the variable or bands it
into categories.
For example, the visits variable in the Museum data set is a numeric variable that records the
number of times respondents have visited the museum before. This example creates an axis
specification for this variable, containing two elements that use expressions to group the numeric
values into categories and a special statistical element to show the mean value.
TableDoc.Tables.AddNew("Table1", _
"visits{visits1 '1 to 10' expression('visits > 0 And visits < 11'), " + _
"visits2 'More than 10' expression('visits > 10'), " + _
"mean 'Mean' mean(visits)}" + _
"* gender", "Number of visits by Gender")

Figure 1-251
Table showing visits by gender, with visits banded into two categories and additional mean row
Just like creating a filter, when you use an expression element to band a numeric variable, you can
use any expression that is supported by the IBM® SPSS® Data Collection Data Model, including
functions in the IBM SPSS Data Collection Function Library.
For more on creating special elements and using expressions to define elements (including
banding dates and autocoding open-ended responses), see Special Elements.
You can optionally store an axis specification for a variable in the metadata. Axis specifications
that are saved in the metadata are sometimes called axis expressions. If an axis expression already
exists in the metadata for a numeric variable, you can simply specify the variable name in the
table specification, just like you can for a categorical variable. IBM® SPSS® Data Collection
Base Professional then creates the table axis based on the axis expression defined in the metadata.
1173
Base Professional
For example, in the Museum sample data, Dinosaurs is a numeric variable that stores a rating for
the Dinosaurs gallery as an integer value. An axis expression has been stored for the variable in
the metadata. You can therefore use this numeric variable in an axis by simply specifying its name:
TableDoc.Tables.AddNew("Table2", "Dinosaurs * Gender", "Dinosaur rating by Gender")
You can create axis specifications for categorical, text, date, and Boolean variables in a similar
way and optionally store the axis expressions in the metadata. When you store an axis expression
for a categorical variable in the metadata, Base Professional will use it and not the variable
elements to define the table axes. For more information, see the topic Working with Axis
Expressions on p. 1536.
The Side_Main variable is a text variable that stores the text “Side” or “Main” depending on
which entrance the respondent used to enter the museum and for which an axis expression has
been defined in the metadata. You can therefore include this variable in a table by specifying its
name, just like the Dinosaurs numeric variable. For example:
TableDoc.Tables.AddNew("Table3", "Side_Main * Gender", "Entrance by Gender")

Figure 1-252
Table showing entrance used by gender
You can also show summary statistics of numeric variables for the cases in the cells of a table
created using ordinary categorical variables. The following example creates a table of age by
gender, which shows the total number of previous visits made to the museum by the respondents
in each cell.
TableDoc.Tables.AddNew("Table4", "age * gender", "Age by Gender showing total number of visits")
' Add the Sum item to the cell contents, specifying that it is to use the
' Visits numeric variable
TableDoc.Tables.Table4.CellItems.AddNew(5, 0, "visits") 'itSum = 5
1174
Chapter 1
Figure 1-253
Table showing age by gender, with a cell item showing the total visits for the respondents in each cell
In addition to the sum of a numeric variable, you can also show the mean, minimum value,
maximum value, range, median, percentile, standard deviation, standard error, and sample
variance. For more information, see the topic Available Cell Contents on p. 1247. In weighted
tables, with the exception of the minimum and maximum values, summary statistics are always
weighted. (If you want to show unweighted summary statistics, remove any weighting from
the table.)
Notes
You can create a derived categorical variable based on a numeric variable for use in your
tables. See 1. Creating a Categorical Variable From a Numeric Variable in the Data Management
section for more information.
Requirements
Creating a Grid Table
Sample script file: MyFirstGridTable.mrs

1175
Base Professional
Survey data frequently includes grid questions. These typically ask respondents to choose a rating
on a predefined scale for a number of products in a list. For example, the Museum sample survey
contains the following grid question (which is called rating):
Figure 1-254
Rating grid
It is generally easier to analyze data collected using a grid question as a grid table. You can create
a grid table based on the rating grid question as follows:
TableDoc.Tables.AddNewGrid("Table1", "rating")

Figure 1-255
Table showing rating grid variable
1176
Chapter 1
By default, the orientation of the grid table is taken from the definition of the grid question in
the metadata. However, you can override the default orientation. For example, if you want the
galleries to form the columns, you could use a script like this:
TableDoc.Tables.AddNewGrid("Table2", "rating", 2) ' 2 = doColumn
You can create grid tables only if you are using a data format that supports a hierarchical view of
the case data. For more information, see the topic Hierarchical Data on p. 1271.
Note: The TableDoc.Tables.AddNewGrid function cannot be used to add database array variables
to the table. Refer to Creating tables based on database questions for more information.
Requirements
Creating tables based on database questions
Sample script file: CreatingTablesBasedOnDatabaseQuestions.mrs
There are three kinds of database questions: single response, multiple response, and database
arrays. Database questions cannot be directly added to tables, they first need to be categorized to
derived categorical variables, which can then be added to tables. For example, to categorize a
multiple response database question, you could use following script:
TableDoc.Coding.CreateCategorizedDBVariable("languages_spoken", "languages_spoken.DBCodes", -1, True, True)
You could then add the derived categorical variable languages_spoken.DBCodes:
TableDoc.Tables.AddNew("Table2", "languages_spoken.DBCodes")
1177
Base Professional
The resulting table is:

Figure 1-256
Rating grid
You could use the following script to categorize a database array:
TableDoc.Coding.CreateCategorizedDBVariable("trip[..].countries[..].CitiesGrid", "trip[..].countries[..].CitiesGrid[..].DBCodes", -1, True, True)
You would then add the derived categorical variable languages_spoken.DBCodes:
TableDoc.Tables.AddNew("Table3", "trip[..].countries[..].CitiesGrid[..].DBCodes * trip[..].countries[..].CitiesGrid[..].Rating")
Note: The derived variable trip[..].countries[..].CitiesGrid[..].DBCodes acts as the loop iteration in

tabulation.
1178
Chapter 1

Figure 1-257
Table showing rating grid variable
Requirements
IBM SPSS Data Collection Survey Reporter Professional 6 or later
Defining Statistical Tests
Sample script file: StatisticalTests.mrs
You can define statistical tests to be run on your tables to show whether differences in the
distribution of counts in tables are statistically significant or whether they are merely due to
chance. Currently the following tests are available:
Chi-square test. This test looks at the variables on the side and top axes of a table and tests
whether they are independent. For example, it can be used to show whether variations in
political opinions depend on the respondent’s age or not.
Cell chi-square test. This test looks at the variables on the side and top axes of a table and tests
whether they are independent. For example, it can be used to show whether variations in
political opinions depend on the respondent’s age or not. Unlike the chi-square test, which
is carried out on a whole set of rows and columns, the cell chi-square test is carried out
independently on each table cell.
1179
Base Professional
Column proportions test. This test looks at each row of a table independently and compares
pairs of columns, testing whether the proportion of respondents in one column is significantly
different from the proportion in the other column.
Column means test. This test looks at means that are presented in a row of a table and compares
pairs of columns, testing whether the mean in one column is significantly different from the
mean in the other column.
Fisher’s exact test This test looks at the variables on the side and top axes of a table with two
rows and two columns and tests. It is suitable for use in a subset of the tables for which the
chi-square test is available.
Net difference test This test deals with each row independently and compares the proportions
in four columns at a time to test whether the difference between the values in the first pair of
columns is significantly different from the difference between the values in the second pair of
columns. For example, when comparing columns A, B, C and D, the difference between A
and B will be tested against the difference between C and D to see whether the difference
between the two is significant.
Paired preference test. This test deals with each column independently and compares pairs of
rows to see whether the figures in each pair differ significantly from one another.
T-test test. This test compares the means of two variables, computes the difference between
the two variables for each case, and tests to see if the average difference is significantly
different from zero.
Tukey test. This test uses the Studentized range statistic to make all pairwise comparisons
between groups.
These tests are suitable only for specific types of tables. When run on unsuitable tables, the results
can be misleading. For detailed information about the tests, the kinds of tables for which they are
suitable, and the statistical formulae that are used, see Statistical Tests.
The following example creates two tables, one with the chi-square test and the other with the
column proportions test. This example assumes that you have already created the table Document
object and loaded the Museum sample data set as shown in Creating a Simple Table of Age
by Gender.
' Create 2 tables

.AddNew("Table1", "age * expect", _
"Table of age by expectation with chi-square square test")
.AddNew("Table2", "interest * gender", _
"Table of interest rating by gender with column proportions test")
End With
' Remove the column percentages cell item and

' define the chi-square test on table 1
TableDoc.Table1.CellItems.Remove(1)
TableDoc.Table1.Statistics.Add("ChiSquare")
' Remove the counts cell item and

' define the column proportion test on table 2
1180
Chapter 1
TableDoc.Table2.Statistics.Add("ColumnProportions")
Here is the table with the chi-square test:

Figure 1-258
Table of age by expect with chi-square test
1181
Base Professional
Here is the table with the column proportions test:

Figure 1-259
Table of interest by gender with column proportions test
Requirements
Creating Charts
Sample script file: HTMLCharts.mrs

1182
Chapter 1
There are a number of options that are available when you export your tables to HTML. You
select the options by changing the export properties. For example, you can export the tables as
charts by changing the DisplayOption property to “Chart Only”:
.Properties["DisplayOption"] = "Chart Only"
.Export("HTMLCharts.htm")
End With
Here is a table of Age by Gender exported as a chart using this option:

Figure 1-260
Data from table of age by gender shown in chart form, with rows as series
By default, charts are clustered column charts based on column percentages. If a table does not
contain column percentages, the chart is based on the counts, as shown in this example. For
any tables that do not contain either column percentages or counts, the chart is based on the
first cell item. Note that base elements are omitted from the charts. You can optionally create
charts for statistical elements (such as elements that show the mean, minimum value, standard
deviation, etc.) If more than one such element is included in the table specification, or if the
table includes a mixture of categorical and other elements, a separate chart is created for each
statistical element in the table.
1183
Base Professional
By default, chart series are based on the table rows. You can base the chart series on table columns
by changing the ChartRowsAsSeries property to False:
Figure 1-261
Data from table of age by gender shown in chart form, with columns as series
The export uses the Office Web Components (OWC) version 10 or later to create charts. This
means that to export charts, you need to have Office Web Components (OWC) version 10 or later
installed on your desktop machine. However, this is not necessary if you only want to export tables.
You can also export the table and the chart. The following script exports both the table and the
chart, suppresses the logo (which is included by default), uses the black and white style sheet
and the frame table of contents layout option:
.Properties["DisplayLogo"] = False
.Export("HTMLTablesAndCharts.htm")
End With
1184
Chapter 1
Here is the table and chart:

Figure 1-262
Table and chart exported in html format
For more information about customizing the HTML export, see HTML Tables Export
For concatenated and nested tables, a separate chart is created for each section of the table. For
example, the following diagrams show the charts that are created for the concatenated and nested
tables created in Concatenation and Nesting.
1185
Base Professional
Here is the concatenated table:

Figure 1-263
Concatenated table and the same data shown in the form of two charts
1186
Chapter 1
Here is the nested table:

Figure 1-264
Nested table and the same data shown in the form of three charts
When you export charts to Excel, PowerPoint, or Word, you can optionally export the charts to a
user-defined custom chart type that you have set up using Excel. For more information, see the
topic Exporting Charts Using Microsoft Excel Custom Chart Types on p. 1508.
Requirements
Microsoft Office 2007 or later
1187
Base Professional
Exporting to Excel
Sample script file: ExcelExport.mrs
Exporting tables to Excel is similar to exporting to HTML—you select the options by changing
the export properties and you can optionally export charts. For example:
With TableDoc.Exports.mrExcelExport
.Properties["UseExcelStyles"] = True
.Export("ExcelExport.xls")
End With
Here is a table of Age by Gender that has been exported to Excel:

Figure 1-265
Table of age by gender, exported to Excel
Requirements
1188
Chapter 1
Loading Other Types of Data
Sample script files: RDBTables.mrs, SavTables.mrs, QuanvertTables.mrs, QuanceptTables.mrs,

QuantumTables.mrs, SurveycraftTables.mrs
If you have worked through the examples in this section methodically, you will have noticed that
up to now all of the examples use the Museum sample XML data set. This consists of metadata
in the form of an .mdd file and case data in an XML file. However, you are not limited to using
this type of data. The Table Object Model can read any type of data that is supported by the
IBM® SPSS® Data Collection Data Model provided a suitable metadata source is available. The
metadata can be in the form of an .mdd file or any other format for which a suitable read-enabled
MDSC is available. This topic provides examples of using data in various formats. The sample
files demonstrate loading each of the main data formats that are supported by the Data Model
by default.
Loading IBM® SPSS® Data Collection data stored in a relational MR (RDB) database
When Data Collection case data is stored in an RDB database, the metadata is typically stored in
an .mdd file. If the .mdd file is set up with the RDB database as the default data source, generally
you do not need to specify the case data location and so you can load the .mdd file without
specifying the case data location as shown in Creating a Simple Table of Age by Gender. This
would typically be true if you are using the main IBM® SPSS® Data Collection Interviewer
Server .mdd file (stored in the FMRoot\Shared folder).
However, sometimes you will need to specify the location of the database. For example:
' Load the short drinks sample .mdd file

TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Mdd\short_drinks.mdd", _
,_
"Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=short_drinks;Data Source=LocalHost", _
"mrRdbDsc2", _
"short_drinks")
The Document.DataSet.Load method has five parameters. For clarity in this example each
parameter has been placed on a separate line:
The first parameter defines the name and location of the metadata, which in this example
is the .mdd file.
The second parameter defines the MDSC. This parameter is blank in this example because the
metadata is in the form of an .mdd file, which means that an MDSC is not required.
The third parameter defines the name and location of the case data. When the case data is in
an RDB database, you can specify the location using an OLE DB connection string.
The fourth parameter defines the CDSC to be used. For an RDB database, this is mrRdbDsc2.
The fifth parameter defines the project name. This is typically used only with RDB data and
is usually the same as the database name.
Loading an SPSS .sav file

1189
Base Professional
You can load a .sav file using the SPSS Statistics SAV DSC to read the metadata like this:
' Load the Employee Data sample .sav file
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.sav", "mrSavDsc")
However, if the .sav file was created by exporting Data Collection data, it is usually preferable to
use the .mdd file that was used to create it. (This is the output metadata file if the .sav file was
created using a data management script) You would then specify the parameters like this:
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.mdd", _
,_
"[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Sav\Employee data.sav", "mrSavDsc")
Note that you need to create an .mdd file from the Employee data.sav file before running this
example, because the IBM® SPSS® Data Collection Developer Library does not come with
an .mdd file for the Employee data.sav file.
Loading a IBM® SPSS® Quanvert™ database
You can load an unpacked Quanvert database using the Quanvert DSC to read the metadata
like this:
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\qvinfo", "mrQvDsc")
You can load a packed Quanvert database using the Quanvert DSC to read the metadata like this:
TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\Museum.pkd", "mrQvDsc")
Loading IBM® SPSS® Quancept™ data
You can load data in the standard Quancept QDI/DRS format like this:
TableDoc.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\QdiDrs\museum.qdi", _
"mrQdiDrsDsc", _
"[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\QdiDrs\museum.drs", _
"mrQdiDrsDsc")
Loading IBM® SPSS® Quantum™ data
You can load data from a Quantum data file like this:
TableDoc.Dataset.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Quantum\skidemo.mdd", _
, "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Quantum\skidemo.dat", "mrPunchDsc")
Loading IBM® SPSS® Surveycraft™ data
You can load data from Surveycraftqdt/vq files like this:

TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Surveycraft\MUSEUM.VQ", "mrScDSC", _
"[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Surveycraft\MUSEUM.VQ", "mrScDsc")
1190
Chapter 1
Requirements
Opening an Existing Table Document
Sample script file: MyFirstTable.mrs
In Creating a Simple Table of Age by Gender, the following line of script was used to save the
table in a table document (.mtd) file:
This saves details of the table structure in an XML file format. If the script includes a line
to populate the table before saving the file, the .mtd file also includes the cell values for the
populated table. Once you have saved a table document, you can open it again using a script, or
using IBM® SPSS® Data Collection Survey Tabulation or IBM SPSS Data Collection Survey
Reporter. For example, you can set up a number of tables using IBM® SPSS® Data Collection
Base Professional Tables Option, save the tables as an .mtd file, and then upload the file into a
project in Survey Tabulation that uses the same data source so that it can be accessed by multiple
users. Alternatively, you could open the table document file using IBM SPSS Data Collection
Survey Reporter, make further changes to the tables, and then upload the file to Survey Tabulation.
For information on how to open table documents from Base Professional in Survey Tabulation
or IBM SPSS Data Collection Survey Reporter, see the Survey Tabulation User’s Guide or the
IBM® SPSS® Data Collection Survey Reporter User’s Guide.
Opening a Table Document Using a Script
To open an .mtd file using a script, you can use the Document.Open method. For example:
TableDoc.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.mtd")
By default, any results saved with the .mtd file are automatically loaded when you open the file.
However, you may want to remove the results and repopulate the table using the latest data. To do
this, you can add a second parameter when you open the file, to specify that any saved results
are not loaded:
TableDoc.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.mtd", 0)
This results in an empty table, so you also need to repopulate the table using the
TableDoc.Populate() method.
Notice that when using the Open method with a previously saved .mtd file, we did not specify a
data source. This information was stored in the .mtd file when it was originally saved. In some
cases, though, you may want to open a table document file using a different data source than the
one with which you originally created it. For example, you may want to use the same set of tables
on a number of different data sets that use the same variables, or you may want to set up your
1191
Base Professional
tables using a test data source and then use the same tables on a live data source with a different
name or in a different location. You can do this by using the Document.OpenWithDataSet method,
which enables you to specify data source details which override the details of the data source
saved in the .mtd file:
TableDoc.OpenWithDataSet("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyFirstTable.mtd", _
0, _
"[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\museum.mdd", _
"mrXmlDsc")
Caution: If you open a table document file with a data source that is not identical to the one with
which you created it, the tables may be invalid. Ensure that the new data source contains the same
variables, with the same names and categories, as the original data source.
Requirements
Table Population and Failover
Sample script file: FailoverDemo.mrs
In certain cases, you can populate many tables via a batch process. Occasionally some of the
tables may fail to populate (due to issues such as not enough memory for example).
Before version 6.0, a single table population failure would cause the entire batch process to fail.
Starting with version 6.0, you can now populate the remaining batch tables when one or more fail.
You can check if any tables failed and iterate the tables to repopulate failed tables.
The following sample demonstrates how to make use of the failover feature. The sample script
FailoverDemo.mrs uses the museum example to create and populate ten tables.
When calling the Populate method, using the following codes to determine if any tables failed.
bSuccess = TableDoc.Populate()
When bSuccess is false, you can attempt to repopulate the failed tables. When failure is the result
of insufficient resources, repopulating the failed tables one-at-a-time will usually resolve the
problem.
Example
If bSuccess <> True Then

Dim Table
For Each Table in TableDoc.Tables
If Len(Table.PopulateError) > 0 Then
TableDoc.Populate(Table.Name)
End If
Next
1192
Chapter 1
End If
When exporting a failed table, the population errors are displayed in the output’s population
warning section.
Requirements
Table Specification Syntax
This section provides full details of the table specification syntax. In most cases, you can create
tables without needing to understand the syntax, but for particularly complex tables, or to create
tables containing elements that are not available in the user interface, you can enter or edit the
syntax directly, either in the Advanced view of the , or in the of the New Variable, Edit Variable,
or Edit Axis dialogs.
Note: Detailed documentation on how to write scripts to generate tables is provided in the IBM®
This section provides full details of the table specification syntax. It also provides information
about the base element, creating special elements, navigating the axis structure, and the
mrScriptBasic dynamic property expansion feature.
Tip: When you are creating tables, you can use the IBM® SPSS® Data Collection Base
Professional Metadata Viewer to get details of the variable and category names in your data set.
For more information, see the topic Using the Metadata Viewer on p. 28.
Table Scripting Syntax Quick Reference
IBM SPSS Data Collection Survey Reporter Professional uses the mrScriptBasic syntax. This
topic shows examples of some of the scripting syntax that you may encounter when using the
sample table scripts, with a brief explanation of the purpose of each one. For more detailed
information on particular items of syntax, follow the links below to mrScriptBasic Reference
topics in the IBM® SPSS® Data Collection Scripting and other sections of the DDL.
’! ... !’
'! *********************************************
This sample creates a number of tables that
illustrate how the Base element is calculated.
********************************************* !'
'! and !' surrounding multiple lines of text indicate comment text that is ignored when the
script is run.
1193
Base Professional
' Create tables
The ' character at the start of a line indicates a single-line comment.
"meanvisits 'Average number of visits' mean(visits) }", _

"Modified Signs variable with mean of Visits")
A space followed by the underscore character ( _) at the end of a line signifies that the syntax
continues on the next line.
You cannot split a line in the middle of a parameter by simply using the underscore character.
This example splits a line in the middle of a parameter by closing the parameter, splitting the line,
and then reopening the parameter, using the syntax " + _. The " character closes the parameter, the
+ adds the two halves of the syntax together again, and the _ is the line continuation character.
Note that the next line begins with ", to reopen the parameter.
.AddNew("Table2", "salary{base() [IsHidden=True]," + _
"Mn 'Lowest' min(salary), Mx 'Highest' max(salary)," + _
"Av 'Average' mean(salary) [Decimals=0]} * gender", "Salary level by gender of employee")
”! ... !”
TableDoc.Tables.AddNew("Table1", "!
age {
E1116_years,
E1720_years,
E2124_years,
E2534_years,
E3544_years
}
*
gender
!")
"! and !" enclosing a string (instead of “ and “) enable you to split the string over several
lines for display purposes.
TableDoc.Tables.AddNew("Table1", "age * interview + gender")
Where the + symbol is used in a table specification, it indicates that two variables are
concatenated together on an axis. For more information, see the topic Concatenation and Nesting
on p. 1156.
>
TableDoc.Tables.AddNew("Table2", "age * interview > gender")

1194
Chapter 1
Where the > symbol is used in a table specification, it indicates that variables are nested. For more
information, see the topic Concatenation and Nesting on p. 1156.
The > symbol is also used in a different context as the “greater than” operator.
[...]
age{.., E65_years [IncludeInBase=False]}
Square brackets surround the definition of an element’s properties.
Note that if more than one property is defined for the same element, both are enclosed in a single
set of square brackets, separated by a comma.
age{.., E65_years [IsHidden=True, IncludeInBase=False]}
For more information, see the topic Element Properties on p. 1222.
{...}
TableDoc.Tables.AddNew("Table1", "interest{Whales, Fossils, Dinosaurs} * gender")
Braces surround the lists of categories and other elements that form a variable’s axis expression.
For more information, see the topic Element List Syntax on p. 1200.
”...”
TableDoc.Default.Annotations[7].Specification = "<IMG
SRC=""[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\logo.gif""/>"
In cases where you want to nest syntax containing quote marks inside other syntax that also
contains quote marks, you must “escape” the quote marks in the inner section of the script so
that they are not interpreted as forming the end of the outer section. You do this by using two
sets of quote marks instead of one.
.AddNew("Table7", "Region{.., ^No_answer} * NumRooms > Person.Gender", "Filtered table")
The ^ character represents the NOT operator; in this example, it excludes the No_answer
category from the variable.
^.
.Table7.Filters.AddNew("MalesAndMotorBikesAtPerson", _
"Gender = {Male} And ^.Sum(Vehicle.(VehicleType = {Motorbike})) > 0", , "person")
1195
Base Professional
The characters ^. represent the down-lev symbol.
.(
The characters .( represent the up-lev symbol.
Select Case

Case 0 ' mtVariable - Simple variable
' It's a numeric - autosummarize
AutoSummarizeNumeric(Field)
Field.FullName, Field.Label)
End If
Case 1, 2, 3, 18 ' Array, Grid, Class, or Compound
MakeTablesFromNumerics(TableDoc, Field.Fields)
End Select
Case statements conditionally execute a group of statements, depending on the value of

an expression.
Const
The Const keyword introduces a user-defined constant that you can use to replace parameters
that you want to reuse or change. The constant replaces the parameter elsewhere in the script, for
example:
Dim
Dim TableDoc
The Dim keyword introduces the syntax that declares one or more variables for use in your
script.
Do...Loop
Do Until AdoRS.EOF
For Each Field In AdoRS.Fields
Set XmlAnswerElement = XmlTextElement.appendChild(XmlDoc.CreateElement("answer"))
Set CDATASection = XmlDoc.createCDATASection(Field)
XmlAnswerElement.appendChild(CDATASection)
Next
AdoRS.MoveNext()
Loop
1196
Chapter 1
The Do Until Loop repeats a block of statements while a condition is True or until a condition
becomes True.
For...Next
For Each Field In AdoRS.Fields

Set XmlAnswerElement = XmlTextElement.appendChild(XmlDoc.CreateElement("answer"))
Set CDATASection = XmlDoc.createCDATASection(Field)
XmlAnswerElement.appendChild(CDATASection)
Next
For... Next repeats a group of statements a specified number of times. For Each... Next repeats
a group of statements for each element in a collection.
If...Then...Else
End If
If...Then...Else conditionally executes a group of statements, depending on the value of

an expression.
On Error
On Error is used to enable and disable error handling.
Set
The Set keyword introduces an assignment statement, which evaluates an expression and
assigns the results to a variable.
With
.AddNew("Signs", "signs", "Unmodified Signs variable")
.AddNew("SignsNew", "signs{Yes, No}", "Two elements of the Signs variable")
End With
The With and End With keywords surround a block of statements that all apply to the same
object (in the above example, adding two new tables to the Tables object). This provides a
compact way of carrying out a number of actions on a single object.
1197
Base Professional
Dynamic Property Expansion
Set MyElement = MyTable.Top.Gender.Elements.Male
Examples such as this use dynamic property expansion to provide a shorter way of writing a
complex line of script. The equivalent script without dynamic property expansion would look
like this:
Set MyElement = _
MyTable.Axes.Item["Top"].SubAxes.Item["gender"].Elements.Item["Male"]
For more information, see the topic Dynamic Property Expansion on p. 1246.
Additional reference topics

When you create variables and elements, you must follow the mrScriptBasic naming
conventions.
A number of keywords in scripts are reserved words; you can use reserved words in scripts.
See also in the mrScriptBasic section for suggestions on how to go about learning mrScriptBasic.
You may also want to look at the topic on See Creating Your First mrScriptBasic Script to learn
about the features in IBM® SPSS® Data Collection Base Professional that help you write
mrScriptBasic scripts and explain how to run an mrScriptBasic file in Base Professional.
Table and Axis Syntax
This topic provides a detailed description of the syntax you use to specify tables in a script. The
syntax has been designed to provide a fast and easy way of creating tables using a script.
The conventions used for defining the syntax in this topic are similar to those used in the IBM®
SPSS® Data Collection Scripting section. The conventions used for defining the syntax in this
topic are similar to those used in the Advanced Expressions section.
Table Specification
A table specification consists of up to two axis specifications that define the side and top of
the table in order as follows:
<table-spec> ::= [<axis-spec>] [* <axis-spec>]
These axis specifications (sometimes called the root-level axes) define the dimensions of the table.
The axis specification on the left of the * defines the side axis, which in turn defines the rows of
the table. The axis specification on the right of the * defines the top axis, which in turn defines
the columns of the table. IBM® SPSS® Data Collection Base Professional supports two table
dimensions (side and top).
Axis Specification
<axis-spec> ::= <axis>

1198
Chapter 1
<axis> ::= <axis> > <axis>

| <axis> + <axis>
| (<axis>)
| id as AxisName
| id ['label-text'] [as AxisName]
| id [LanguageID:'label-text'] [as AxisName]
| id {<element-list>} [MaxResponses = Value] [as AxisName]
| axis (id)
| axis ( {<element-list>} [MaxResponses = Value])
| axis ( {<element-list>} [MaxResponses = Value]) as AxisName
Part Description
> Indicates that the axis on the right of the > symbol is to be
nested within the axis on the left of the symbol. Generally the
evaluation of the axis specification takes place from left to
right. However, when an axis specification contains both > and
+ symbols, the > symbol takes precedence over the +. (This
means that the > symbol is evaluated before the + symbol.)
However, you can use parentheses to change the order of
precedence.
+ Indicates that the two axes separated by the symbol are to be
concatenated.
() Parentheses used to indicate that the symbols within the
parentheses are to be evaluated before the symbols outside
the parentheses.
id Indicates that the axis is to be created from the variable with
name id. If an axis expression has been defined in the metadata
(in the AxisExpression property), it is used to define the
elements. What happens if an axis expression has not been
defined in the metadata depends on the variable type. For a
categorical variable, all of the elements within the variable
are used. For numeric, text, date, and Boolean variables, you
will get an error.
id {<element-list>} Indicates that the axis is to be created from the variable with
name id and the elements are to be as specified in the element
list. You can define new analysis elements in the element list.
For more information, see the topic Element List Syntax on
p. 1200.
axis (id) Indicates that the axis is to be created from a reusable axis
with name id. A reusable axis is an axis that has been added to
the Document.Axes collection.
id as AxisName Indicates that the axis is to be created from the variable with
name id, but that the axis will have the name AxisName. Use
this if you want to add the same variable to an axis more than
once.
axis ( {<element-list>}) Indicates that the axis is to be created without reference to an
existing variable. The base for the new variable contains all
cases. If you do not specify an axis name, the axis is given the
default name of _Custom. If you want to create more than one
axis, you should give each one a unique name.
1199
Base Professional
Part Description
axis ( {<element-list>}) as AxisName Creates an axis without reference to an existing variable, and
saves it with a unique name.
[MaxResponses = Value] Custom property for axis. When using axis expressions to
edit a variable, the max response value could be changed.
For example, an axis expression can change a single response
variable to a multiple response by doing a net and keep
operation. It is important to identify when a variable, or an axis,
is single or multiple while performing statistic tests, as they
may require different formulas. You should set the appropriate
value when the response type is different from the variable.
Note: Do not take statistics elements into account.
Examples
The following table provides some example table specifications.

Table specification: Creates a table that has:
age a side axis only, based on a single variable called
age.
* age a top axis only, based on a single variable called age
age * gender a side axis based on the age variable and a top axis
based on the gender variable.
interest * axis(MyBanner) a side axis based on a single variable called interest
and a top axis based on the reusable axis called
MyBanner.
age + gender * interest > before a side axis based on the variables called age and
gender concatenated together and a top axis that is
based on the variable called before nested inside the
variable called interest.
interest * resident + axis(MyBanner) a side axis based on a single variable called interest
and a top axis based on a variable called resident
concatenated with a reusable axis called MyBanner.
interest{Dinosaurs, Fossils, Whales} * gender a side axis based on three specific elements of a
variable called interest and a top axis based on a
variable called gender. For more information, see
the topic Element List Syntax on p. 1200.
age 'Age Range' + gender a side axis only, based on a variable called age with
the label Age Range concatenated with a variable
called gender with the default label.
age ENU: 'Age Range' ESN: 'Edad' a side axis only, based on a variable called age
with labels in United States English (ENU) and
International Spanish (ESN). For languages where
no label is specified, the default label from the
metadata is used.
For details of recognized language codes, see
Languages (3-Character Codes).
education as education1 > gender + education as a side axis only, based on a variable called education
education2 > biology which is used twice in the axis, once with gender
and once with biology nested within it.
axis({base(), male expression('gender={Male}')}) a side axis only, with the default name _Custom.
The axis is not based on an existing variable.
1200
Chapter 1
Table specification: Creates a table that has:

axis({base(), male expression('gender={Male}')}) as a side axis only, with the name MyMaleAxis. The
MyMaleAxis axis is not based on an existing variable.
order{first, second} * order[..].column demonstrates editing grid and loop iterations.
For additional examples, see:

Concatenation and Nesting
More on Concatenation and Nesting
Reusing Axes
Example of Creating a New Axis
Requirements
Base Professional Tables Option
Example of Creating a New Axis
You can create an axis specification without basing it on an existing variable, using the syntax
axis{(<element-list>)} as MyAxis. For example, if you want to create a variable containing only the
Male category of the gender variable, instead of modifying the existing variable using the syntax:
Set Table = TableDoc.Tables.AddNew("Table1", "gender{base(), male expression('gender={Male}')} * age")
you can create a new variable directly, using the syntax:
Set Table = TableDoc.Tables.AddNew("Table2", "axis({base(), male expression('gender={Male}')}) * age")
This avoids the need to create a new derived variable using MDM script. It also makes it easier to
create several variables based on the same initial variable. For example, you could also create a
variable containing the Female category and add both variables to the table, using the syntax:
Set Table = TableDoc.Tables.AddNew("Table3", "axis({base(), male expression('gender={Male}')}) as MyMaleAxis + axis({base(), female exp
The variable is always created at the top (HDATA) level.
For an example script that uses the axis({}) syntax, see Creating Summary Statistic Tables.
Element List Syntax
Sample Script File: ElementSpecifications.mrs
The Table and Axis Syntax topic describes the syntax that you use to define the axes of your
tables. One of the options is to use an element list to specify the elements that are to be included.
1201
Base Professional
The term element includes categories, user-defined categories, means or other statistics, and any
other item that forms part of a variable (in the user interface, the term category is used to refer
to all of these items for the sake of simplicity, but strictly speaking they are elements). Each
element is usually displayed as a row or column on a table (though in some cases the element may
be included in the table but not displayed).
The element list syntax is:

VariableName {<Element-List>}
<Element-List> ::= <Element> (, <Element>)*
<Element> ::= [^] ElementName ['Label-text'] [<Properties>]

| ElementName ([LanguageID: 'Label-text'])*
| [^] [ElementName] .. [ElementName]
| <Special-Element>
Part Description
VariableName The name of a variable in the metadata.
ElementName The name of an element in the specified variable.
^ Indicates that the following item is to be excluded.
.. Indicates a range of elements.
LanguageID The code of a language that exists in the metadata.
For details of recognized language codes, see
Languages (3-Character Codes).
<Special-Element> Defines a special non-category element. For more
information, see the topic Special Elements on p.
1204.
<Properties> Defines one or more properties for the element. For
more information, see the topic Element Properties
on p. 1222.
The list of elements is evaluated from left to right and determines the order in which the elements
appear in the axis.
Element Names
Do not use the default names of special elements as element names unless you are creating a
special element. If you are creating multiple elements, ensure that the element names are unique.
Examples
The following examples are based on the interest variable in the Museum sample data set. The
interest variable has the following elements:
Position Element Name
1 Dinosaurs
2 Conservation
3 Fish_and_reptiles
4 Fossils
1202
Chapter 1
Position Element Name

5 Birds
6 Insects
7 Whales
8 Mammals
9 Minerals
10 Ecology
11 Botany
12 Origin_of_species
13 Human_biology
14 Evolution
15 Wildlife_in_danger
16 Other
17 Not_answered
By running the ElementSpecifications.mrs sample and examining the exported HTML tables, you
will be able to see each of the following axes in a table. (The first table contains the first example
axis, the second table contains the second example, etc.)
1. Single elements
interest{Whales, Fossils, Dinosaurs}
This creates an axis that has three elements from the interest variable in the order Whales,
Fossils, Dinosaurs.
2. All elements from the first to a specified element
interest{.. Whales}
This creates an axis that has a range of elements from the first element in the variable’s element
list through the Whales element (which in this example is the seventh element in the variable).
The elements appear in the order in which they appear in the variable (Dinosaurs, Conservation,
Fish_and_reptiles, Fossils, Birds, Insects, Whales).
3. All elements from a specified element to the last element
interest{Whales..}
This creates an axis that has a range of elements from the Whales element through the last element
in the variable’s element list. The elements appear in the order in which they appear in the variable
(Whales, Mammals, Minerals, Ecology, Botany, Origin_of_species, Human_biology, Evolution,
Wildlife_in_danger, Other, Not_answered).
4. A range of elements
interest{Whales..Botany}
1203
Base Professional
This creates an axis that has an element list starting with the Whales element and ending with
the Botany element and including all of the elements in between (Whales, Mammals, Minerals,
Ecology, Botany).
5. All elements
interest{..}
This creates an axis that has all of the elements in the variable in their default order. Although this
syntax is not generally used on its own, it is useful when you want to exclude categories from
the list as shown in the next example, or add special elements to the list of elements. For more
information, see the topic Special Elements on p. 1204.
6. All elements except those in a specified range

interest{.., Ôther..Not_answered}
This creates an axis that has all of the elements in the variable in their default order with the
exception of any elements in the list from Other through Not_answered. (The elements that
are included are Dinosaurs, Conservation, Fish_and_reptiles, Fossils, Birds, Insects, Whales,
Mammals, Minerals, Ecology, Botany, Origin_of_species, Human_biology, Evolution, and
Wildlife_in_danger.)
7. All elements in a range with the exception of one specified element

interest{Dinosaurs..Whales, ^Conservation}
This creates an axis that has all of the elements in the variable from Dinosaurs through Whales
with the exception of the Conservation element. (The elements that are included are Dinosaurs,
Fish_and_reptiles, Fossils, Birds, Insects, and Whales.)
8. Specified elements using custom labels

interest{Dinosaurs 'Extinct reptiles', Whales 'Large marine mammals'}
This creates an axis that has two elements (Dinosaurs and Whales). However, instead of using
the standard labels stored in the metadata for the current language, user context, and label type,
the elements will have labels of Extinct reptiles and Large marine mammals, respectively. These
custom labels will be used for the current language, user context, and label type only. If you
change the language, user context, or label type, the label stored in the metadata for the selected
language, user context and label type will be used. However, if you return to the original language,
user context, and label type, the custom labels will be used again.
When you specify a custom label, you need to enclose the label text in single quotation marks
(‘<label text>’) or two double quotation marks (“”<label text>“”). If you use single quotation
marks, you must escape any single or double quotation marks included in the label with a second
quotation mark of the same type. This indicates that the quotation mark used in the label does not
represent the end of the label. If you use two double quotation marks, you need to escape any
double quotation marks used in the label with three double quotation marks.
9. Custom labels in multiple languages

1204
Chapter 1
interest{Dinosaurs ENU:'Extinct reptiles' ESN:'Reptiles extintos',

Whales ENU:'Large marine mammals' ESN:'Mamíferos marinos grandes'}
This creates an axis that has the same two elements (Dinosaurs and Whales) as in the previous
example. However, this time custom labels have been defined for two languages (ENU—United
States English and ESN—International Spanish). These labels will be used for the specified
languages only and if you select another language, the label stored in the metadata for that
language will be used.
Special Elements
The Element List Syntax topic describes the syntax that you use to specify the elements to include
in the axis of a table. This topic documents the special elements that you can include in an axis.
By default, the element name is the same as the element type. For example, by default, a Standard
Error element is called stderr. However, if you create multiple elements of the same type, you
must specify names to ensure that each element is uniquely identified.
The following table provides a summary of the special elements that are available. The other
topics in this section contain examples of creating different types of element.
Description Syntax
Base. Shows the total number of cases in the variable after any base([‘Expression Text’])
weighting has been applied. Generally, the base includes every
case for which the value in the case data is not Null. (This is a
change from IBM® SPSS® Data Collection Survey Tabulation
1.1, where the base excluded empty values as well as Null values.)
Note that if an axis does not include a base element, IBM® SPSS®
Data Collection Base Professional creates one automatically at the
start of the axis. This means that normally you do not need to
use this syntax if you want the base element to appear at the start
of the axis. See The Base Element for further information and
examples. See also Restricting a Base Using an Expression.
Unweighted base. Shows the total number of cases in the variable unweightedbase([‘Expression Text’])
before any weighting has been applied. In an unweighted table, an
unweighted base element shows the same values as the counts in
the base element. Only one value is ever shown for an unweighted
base element, even when multiple types of cell contents have been
requested. The value that is shown is the unweighted base count,
regardless what type of cell contents have been requested for the
table. By default automatically adds an unweighted base element
at the start of each axis in a weighted table. See The Base Element
for further information and examples.
Mean. Shows the mean value of a specified numeric variable, mean([NumericVariable],
optionally restricted by an expression. See Displaying the Mean [‘Expression Text’])
of a Numeric Variable. If you do not specify a numeric variable,
the mean element shows the mean value of the factors associated
with the elements in the axis, and the expression is ignored. See
Displaying a Mean Based on Factors.
1205
Base Professional
Description Syntax
Standard deviation. Shows the standard deviation for a specified stddev([NumericVariable],
numeric variable, optionally restricted by an expression. If you do [‘Expression Text’])
not specify a numeric variable, the element shows the standard
deviation for the factors associated with the elements in the axis,
and the expression is ignored. For examples, see Mean.
Standard error. Shows the standard error for a specified numeric stderr([ NumericVariable ],
variable, optionally restricted by an expression. If you do not [‘Expression Text’])
specify a numeric variable, the element shows the standard error
for the factors associated with the elements in the axis, and the
expression is ignored. For examples, see Mean.
Sample variance. Shows the sample variance for a specified sampvar([NumericVariable],
numeric variable, optionally restricted by an expression. If you [‘Expression Text’])
do not specify a numeric variable, the element shows the sample
variance for the factors associated with the elements in the axis,
and the expression is ignored. For examples, see Mean.
Total. Shows the sum of the counts between the most recent base total()
or total element, whichever is the most recent, and the next total
or base, or the end of the axis, whichever occurs first. A total
element works in this way regardless of its position in the axis. See
Displaying Totals and Subtotals.
Subtotal. Shows the sum of the counts between the most recent subtotal()
base, total, or subtotal element, whichever is the most recent, and
the next base, total, or subtotal, or the end of the axis, whichever
occurs first. A subtotal element works in this way regardless of its
position in the axis. See Displaying Totals and Subtotals.
Text. A text-only element that can be used to form a subheading. text()
When the axis is on the side of the table, the element forms a
text-only row.
Minimum. Shows the minimum value of a numeric variable, min(NumericVariable, [‘Expression
optionally restricted by an expression. Text’] )
Maximum. Shows the maximum value of a numeric variable, max(NumericVariable, [‘Expression
optionally restricted by an expression. Text’] )
Net. In a multiple response variable this creates an element net({ElementList})
that shows the number of respondents who chose one or more
categories in a group of categories. A subtotal element for the
same categories would show the number of responses given. In
a single response variable a net shows the same values as the
subtotal. See Creating Nets.
Combine. This is like a net, except that the elements on which it is combine({ElementList})
based are not shown. See Combining Categories.
Expression. This creates a special element that is defined by a expression('ExpressionText')
custom expression. You can use any expression that is supported
by the IBM® SPSS® Data Collection Data Model, including
any of the functions in the IBM SPSS Data Collection Function
Library. When you are using the hierarchical (HDATA) view,
the level of the expression is defined by the level of the variable.
You must make sure that all variables included in the custom
expression are at this level or are up-leved/down-leved to this
level. See Creating an Element Based on a Custom Expression.
You can use expressions to band numeric variables, autocode text
variables, or band date variables.
Numeric. Shows a numeric variable, optionally restricted by an numeric(NumericVariable,
expression. You can use this element type to create summary [‘Expression Text’] )
statistic tables. See Creating Summary Statistic Tables for further
information and examples.
1206
Chapter 1
Description Syntax
Paired Preference. Shows the result of a paired preference test ppt()
run on a table. See Paired Preference Test for further information
and examples.
Derived. Shows a derived element calculated from other elements derived( ’Expression Text’ )
within the variable using an arithmetic expression. Derived
elements use an arithmetic expression based on the values of
other elements in the table. This differs from the expression()
syntax, which uses a logical expression that tests the case data
to determine whether a respondent is included in the count. See
Creating a Derived Element Calculated from Other Elements.
Sum. Shows the sum or total of the values in a specified numeric sum(NumericVariable, [‘Expression
variable, optionally restricted by an expression. See Displaying Text’])
the Sum of a Numeric Variable.
Effective base. Shows the effective base. For more information, effectivebase()
see the topic Displaying an Effective Base on a Weighted Table
on p. 1389.
Median. Shows the median for a specified numeric variable, median(NumericVariable,
optionally restricted by an expression. For more information, see [‘Expression Text’] )
the topic Displaying Median and Percentile Values on p. 1220.
You must specify a numeric variable.
Percentile. Shows a percentile for a specified numeric variable, percentile(NumericVariable,
optionally restricted by an expression. You must specify a numeric CutOffValue, [‘Expression Text’])
variable. You must also specify a cut-off value between 1 and 100
to indicate the percentile you want to use. Note that the median
element gives the same result as a percentile with a cut-off value
of 50. For more information, see the topic Displaying Median and
Percentile Values on p. 1220.
Mode. Shows the mode for a specified numeric variable, optionally mode(NumericVariable, [‘Expression
restricted by an expression. For more information, see the topic Text’] )
Displaying a Mode on p. 1221. If there is more than one mode
value, the lowest is displayed. You must specify a numeric
variable.
Net Difference. Shows the result of a net difference test run on the ntd()
table. For more information, see the topic Net Difference Test
on p. 1348.
When calculating the values for mean, standard deviation, standard error, sample variance, min,
and max elements, uses the same formulae used for the cell contents. For more information,
see the topic Statistical Formulae on p. 1268.
Notes
When you create a special element in Base Professional or Survey Tabulation, the Table
Object Model automatically takes care of creating any helper elements required by that
element. If you are adding special elements to the metadata using a programming language or
a data management script, you may sometimes want to create the helper elements explicitly,
rather than let the Table Object Model create them. For further information on the required
settings for creating special elements and their helper elements, see
NumericVariable (AnalysisVariable), Multiplier, and Weight properties need to be specified
as absolute references. However, variable references in expressions need to be specified
as relative references. Using the Household.mdd sample as an example, when editing a
1207
Base Professional
categorical variable at the person level, if you want to display the mean of man’s weight, you
can add the following mean element: mean(person[..].weight, 'gender.ContainsAny({Male})')
Use of analysis variables on parallel levels is not supported. Valid analysis variables must
meet the following conditions:
– The variables must be numeric
– The variables must be at the same ascendant level
Take the following variable as an example: variable "person[..].trip[..].purpose"
– Same level analysis variable (valid): person[5].trip[..].transportmodes
– Ascendant level analysis variable (valid): person[..].age, numpersons
– Parallel level (not valid): vehicle[..].mileage
The examples in the topics in this section are available in a sample mrScriptBasic file called
SpecialElements.mrs. By running this sample and examining the exported HTML tables, you will
be able to see each of the example axes in a table. For more information, see the topic Running the
Sample Table Scripts on p. 1554.
Note that in some of the examples, the axis specification is presented on multiple lines for clarity.
In practice you must specify the axis specification without line breaks.
Displaying the Mean of a Numeric Variable
Sample Script File: SpecialElements.mrs
This example is based on the Museum sample data set.

age{.., mean(visits)}
This creates an axis based on all of the elements in the age variable with the addition of a special
element that shows the mean value of the visits variable. This variable stores the number of
previous visits that respondents have made to the museum. Therefore this element shows the mean
number of previous visits that respondents have made to the museum.
Note that this example does not specify a label for the special element, so the default label is used.
The default label has the form “Mean : <variable name>”. The next example shows you how to
override the default label with a custom label.
Displaying the mean of a numeric variable with a custom label

age{.., meanvisits 'Average number of visits' mean(visits)}
This is similar to the previous example, except that it creates a custom label for the mean element.
When you specify a custom label, you need to enclose the label text in single quotation marks
(‘<label text>’) or in two double quotation marks (“”<label text>“”). If you use single quotation
marks, you must escape any single or double quotation marks included in the label with a second
1208
Chapter 1
quotation mark of the same type. This indicates that the quotation mark used in the label does not
represent the end of the label. If you use two double quotation marks, you need to escape any
double quotation marks used in the label with three double quotation marks.
Here is a table that has this axis on the side:

Figure 1-266
Table showing the mean of a numeric variable
Displaying a Mean Based on Factors
rating[{Dinosaurs}].Column{.., mean()}
This creates an axis based on all of the elements in the rating[{Dinosaurs}].Column variable with
the addition of a special mean element that shows the mean value of the factors associated with
the variable. (Factors are automatically used when you do not specify a numeric variable.)
A factor is a constant numerical value that can be assigned to an element in a categorical variable
for use in statistical calculations. Factors are used when you want to base a statistical element on
the categories of a categorical variable rather than on a numeric variable. This is because statistics
can be calculated on numeric data only and categories are not true numeric values. (Although the
Data Model represents the responses to categorical questions as numeric values, these are in fact
identifiers or codes and are not suitable for statistical analysis.)
1209
Base Professional
The rating[{Dinosaurs}].Column variable is the Dinosaurs “slice” of a grid question, which asks
respondents to rate the various galleries in the museum. Here is the grid question:
Figure 1-267
Rating grid question
Factors have been assigned to the categories as shown in the following table.
Category Factor
Not at all interested 1
Not particularly interested 2
No opinion 3
Slightly interested 4
Very interested 5
The mean element in this example shows the average factor value for categories chosen by the
respondents, and this can give an indication of the general feeling among all of the respondents.
In this example, a high mean factor value indicates that on average the respondents gave the
Dinosaurs gallery a high rating.

Figure 1-268
Table showing the mean value of rating factors
1210
Chapter 1
Note that when no factors are defined, the mean will be zero. You can set factor values for elements
in the axis specification. For more information, see the topic Element Properties on p. 1222.
Displaying Totals and Subtotals
age{.. E2534_years, youngpeople 'Younger people' subtotal(),

E3544_years.., maturepeople 'Older people' subtotal(),
total()}
This creates an axis based on the age variable, with the addition of two subtotal elements and a
total element. The range syntax specifies the categories that are to appear before the first subtotal.
These are the categories that will contribute to the subtotal. A subtotal element provides a subtotal
of the counts in the categories that precede it in the axis up to the last base, subtotal, or total
element. So the second subtotal sums the categories that appear between the first and second
subtotal. The total element provides a total of the counts in the categories that precede it up to the
most recent base or total element.
Notice how the subtotal elements have each been given a name. This is necessary when you create
two special elements of the same type in an axis, because otherwise the default names are used
and this will lead to a duplicate name error.

Figure 1-269
Table showing total and subtotal elements
Creating Nets

1211
Base Professional
remember{ExtinctLife 'Extinct life forms and evolution'

net({Dinosaurs, Fossils, Evolution, Origin_of_species}),
CurrentLife 'Current life forms'
net({Fish_and_reptiles, Whales, Birds, Insects, Mammals, Botany, Human_biology}),
Theoretical 'Theoretically-themed exhibits'
net({Conservation, Ecology, Wildlife_in_danger})}
This example creates three net elements, each one containing a specified list of elements. Nets are
useful in multiple response variables in which the categories fall into a number of groups (such
as favorable, unfavorable, and neutral). Net elements enable you to find out how many people
chose one or more responses in each group. Subtotal elements would tell you the total number of
responses that were chosen in each group, but not how many people chose those responses.

Figure 1-270
Table showing net elements
See Sorting Net Elements for information on how net elements are handled when a table is sorted.
Note on Naming Nets
When you create a net, if the name of the net is the same as that of any of the categories in the net,
a net expression will be generated on the category, which will slow performance. Because of this,
it is recommended that you do not use the same name for a net as for any of the categories in the
net (though you can use the same description). For example, instead of:
Blue 'Blue' net({Blue, PaleBlue, DarkBlue})

1212
Chapter 1
use:
Blue_net 'Blue' net({Blue, PaleBlue, DarkBlue})
Combining Categories

remember{ExtinctLife 'Extinct life forms and evolution'
combine({Dinosaurs, Fossils, Evolution, Origin_of_species}),
CurrentLife 'Current life forms'
combine({Fish_and_reptiles, Whales, Birds, Insects, Mammals, Botany, Human_biology}),
Theoretical 'Theoretically-themed exhibits' _
combine({Conservation, Ecology, Wildlife_in_danger})}
This example creates three combined elements. These are useful when you want to merge a
number of categories into one new category. Combined elements are similar to nets in that in a
multiple response variable they show the total number of respondents who chose one or more of
the elements that make up the combined element and not the total number of responses. However,
unlike nets, the individual categories are not displayed in the table.

Figure 1-271
Table showing combined elements
Creating an Element Based on a Custom Expression

biology{.., ^Not_answered, expression('visits > 4')}
This example creates an axis based on the biology variable. It includes all of the elements in the
axis with the exception of the Not answered category, but has an additional element, which is
based on a custom expression. The custom expression selects respondents who entered a value
1213
Base Professional
greater than four when answering the question on which the visits variable is based. Because we
have not specified a label for the special element, the label defaults to the expression text.
Just like when you specify a custom label, you must enclose the custom expression in single
quotation marks (‘<expression>’) or two double quotation marks (“”<expression>“”). If the
expression contains a text literal, you must escape the double quotation marks used to enclose
the text literal as you do when a label contains a double quotation mark. For example, if you use
single quotation marks, you must escape each of the double quotation marks that enclose the text
literal with a second double quotation mark.
Here is a table that has this axis on the top:

Figure 1-272
Table showing element based on a custom expression
Banding Numeric Variables

visits{visits1_5 '1 to 5' expression('visits > 0 And visits < 6'),
visits6_10 '6 to 10' expression('visits > 5 And visits < 11'),
visits11_20 '11 to 20' expression('visits > 10 And visits < 21'),
visits21ormore 'More than 20' expression('visits > 20'),
mean 'Mean' mean(visits), Stddev 'Standard deviation' stddev(visits)}
1214
Chapter 1
This example creates an axis based on the visits numeric variable and uses custom expressions to
band the responses into categories. It also includes mean and standard deviation special elements
based on the numeric variable.

Figure 1-273
Table showing banded numeric variable
Autocoding Text Variables
address{London 'London' expression('address.find(""london"") <> -1'),

Liverpool 'Liverpool' expression('address.find(""liverpool"") <> -1'),
Aberdeen 'Aberdeen' expression('address.find(""aberdeen"") <> -1'),
Leeds 'Leeds' expression('address.find(""leeds"") <> -1'),
Edinburgh 'Edinburgh' expression('address.find(""edinburgh"") <> -1'),
OtherCities 'Other cities' expression('address.find(""london"") = -1
And address.find(""liverpool"") = -1 And address.find(""aberdeen"") = -1
And address.find(""Leeds"") = -1 And address.find(""Edinburgh"") = -1
And Not address.IsEmpty()'),
NotAnswered 'Not answered' expression('address.IsEmpty()')}
This example creates an axis based on the address text variable and uses custom expressions to
automatically code the responses into categories by using the function to search for city names.
Notice that the text supplied as a parameter to the Find function is enclosed in two double
quotation marks (“”<text>“”).
1215
Base Professional

Figure 1-274
Table showing variable autocoded using a custom expression
Banding Date Variables
DataCollection.FinishTime{January 'January' expression('DataCollection.FinishTime.Month() = 1'),

February 'February' expression('DataCollection.FinishTime.Month() = 2'),
March 'March' expression('DataCollection.FinishTime.Month() = 3'),
April 'April' expression('DataCollection.FinishTime.Month() = 4'),
May 'May' expression('DataCollection.FinishTime.Month() = 5'),
June 'June' expression('DataCollection.FinishTime.Month() = 6'),
July 'July' expression('DataCollection.FinishTime.Month() = 7'),
August 'August' expression('DataCollection.FinishTime.Month() = 8'),
September 'September' expression('DataCollection.FinishTime.Month() = 9'),
October 'October' expression('DataCollection.FinishTime.Month() = 10'),
November 'November' expression('DataCollection.FinishTime.Month() = 11'),
December 'December' expression('DataCollection.FinishTime.Month() = 12')}
This example creates an axis based on the DataCollection.FinishTime date system variable and
uses the function in custom expressions to automatically band the dates into categories based on
the month.
Here is a table that has this axis on the side (a hide rule has been used to hide the all-zero rows):
Figure 1-275
Table showing date variable banded using a custom expression
1216
Chapter 1
Restricting a Base Using an Expression

base('gender={Male}')
This example uses an expression to add a restriction to the base element so that it includes
responses only where the respondent is male.

Figure 1-276
Table showing base element restricted to include only responses where respondent is male
Note: To exclude categories in a categorical variable from the calculation of the base, you can
also use the IncludeInBase element property. For more information, see the topic Excluding
Categories From the Base on p. 1226.
Restricting a Mean Using an Expression

mean(visits, 'gender={Male}')
This example uses an expression on the mean element to specify the cases to use in the
calculation of the value of the mean for the visits numeric variable. By adding the expression
"gender={Male}", you restrict the calculation of the mean to include only those cases where
the respondent is male. Apart from the mean element, you can create this type of expression for
standard deviation, standard error, sample variance, minimum, and maximum elements. You must
include a numeric variable when creating this type of expression, otherwise the expression is
1217
Base Professional
ignored and the special element (mean, standard deviation, standard error, or sample variance) is
calculated from the assigned factors.

Figure 1-277
Table showing mean element restricted to include only responses where respondent is male
Creating a Derived Element Calculated from Other Elements
age{.., Derived '55 or over' derived('E5564_years + E65_years')}
This example uses a derived element to display a value calculated from the values in two other
elements.

Figure 1-278
Table showing derived element ‘55 or over’ calculated from the sum of two other elements
1218
Chapter 1
Derived elements use an arithmetic expression based on the values of other elements in the table.
This differs from the expression() syntax, which uses a logical expression that tests the case data
to determine whether a respondent is included in the count.
Expressions in derived elements are calculated only for cell items based on counts, for example
count and column percent, not for summary statistic cell items such as mean or stddev.
Expressions are not calculated for cell items that display unweighted counts in a weighted table.
Note: Derived element expressions are calculated for all elements, including non-category
elements, in rows and columns.
The expression in a derived element can refer only to other elements in the same variable. For
example, you cannot define an expression for an element in the interest variable that references
the elements of the age variable. Derived elements are displayed only at the innermost nesting
level of a table. If a variable includes net elements, the expression in a derived element can
refer only to other elements in the same net.
Note for Quantum Users: Derived elements provide similar functionality to the m;ex= statement
in IBM® SPSS® Quantum™. If you are accessing IBM® SPSS® Quanvert™ data using IBM
SPSS Data Collection Survey Reporter Professional or IBM® SPSS® Data Collection Survey
Tabulation (version 2.3 and later), and a Quanvert variable has an m;ex= element or an n01;ex=
element, the expression is automatically evaluated and displayed on the table.
Create a derived element using relative position to reference elements
When referencing other elements in a derived element, the simplest method is to reference the
elements by name, as in the previous example. An alternative method of referencing elements
by relative position is also available, using the syntax @n to reference an element n positions
before the derived element. This example uses relative position syntax to create the same table
as in the previous example:
age{.., Derived '55 or over' derived('@1 + @2')}
This method can be useful if you want to reuse an expression for elements that are in the same
relative position but have different names. However, it is available only for referencing elements
that come before the derived element in the table. To reference elements that come after the
derived element, you must use the element name.
Create a derived element calculated from other elements using a function
interest{.., Derived 'Highest other than Dinosaurs' derived('maxof(Conservation,

Fish_and_Reptiles, Fossils, Birds, Insects, Whales, Mammals, Minerals, Ecology, Botany, Origin_of_species, Human_Biology,
Evolution, Wildlife_in_danger)')}
This example uses a derived element to compare other elements in the table and display the
maximum value, using the function.
1219
Base Professional

Figure 1-279
Table showing derived element calculated from other elements using a function
You can use any expression that is supported by the Data Model, including any of the functions
in the . .
Displaying the Sum of a Numeric Variable
age{.., sumvisits 'Total visits by respondents' sum(visits)}
This creates an axis based on all of the elements in the age variable with the addition of a special
element that shows the sum of the values in the visits variable. This variable stores the number
of previous visits that respondents have made to the museum. Therefore this element shows the
total number of previous visits that male and female respondents have made to the museum. A
custom label overrides the default.
1220
Chapter 1

Figure 1-280
Table showing the sum of a numeric variable
Displaying Median and Percentile Values
You can add a median as a row or column on a numeric variable. This shows the value above
and below which 50% of cases fall.
visits{base(), median(visits)}
You can also add one or more percentiles. This is the value below which a certain percentage of
the cases fall. To add a percentile you need to include a cut-off value to specify the percentage:
visits{base(), percentile(visits, 25)}
Note that the median is identical to a percentile with a cut-off value of 50.
Example
This example displays the base, lower quartile (cases that fall below the 25th percentile), median
(cases that fall below the 50th percentile) and upper quartile (cases that fall below the 75th
percentile) for the visits variable. As it uses two percentile elements, each has a unique name,
percentile25 and percentile75:
visits{base(), percentile25 'Lower quartile' percentile(visits,25), median 'Median' median(visits), percentile75 'Upper quartile' percentile(vis
1221
Base Professional

Figure 1-281
Table showing median and percentiles
For information on how to display medians and percentiles as cell items rather than as rows or
columns of a table, see .Cell Contents.
Displaying a Mode
You can add a row or column on a table to display the most frequently occurring value or mode.
In , where there is more than one mode value, the lowest is displayed.
visits{base(), mode(visits)}
This example displays a mode, together with a mean, median, and two percentiles, for the
visits variable.
visits{base(), mean 'Mean' mean(visits), mode 'Mode' mode(visits), percentile25 'Lower quartile' percentile(visits,25), median 'Median' me

Figure 1-282
Table showing mode and other summary statistics
For information on how to display modes as cell items rather than as rows or columns of a table,
see Cell Contents.
1222
Chapter 1
Element Properties
You can define properties for elements and special elements in the axis specification. You specify
the properties after the element to which they apply as follows:
<properties> ::= [<property> [, <property>]]
<property> ::= CalculationScope=AllElements|PrecedingElements

| CountsOnly=True|False
| Decimals=DecimalPlaces
| Factor=FactorValue
| IsFixed=True|False
| IsHidden=True|False
| IsHiddenWhenColumn=True|False
| IsHiddenWhenRow=True|False
| IncludeInBase=True|False
| IsUnweighted=True|False
| Multiplier=MultiplierVariable
| Weight=WeightVariable
The examples in this section show how to use element properties. and are available in a number of
sample mrScriptBasic files. By running these samples and examining the exported HTML tables,
you will be able to see each of the example axes in a table. See Running the Sample Table Scripts
for information on running the example scripts. Note that in the examples, the axis specification
is presented on multiple lines for clarity. In practice you must specify the axis specification
without line breaks.
Note: NumericVariable (AnalysisVariable), Multiplier, and Weight properties need to be specified

as absolute references. However, variable references in expressions need to be specified as relative
references. Using the Household.mdd sample as an example, when editing a categorical variable
at the person level, if you want to display the mean of man’s weight, you can add the following
mean element: mean(person[..].weight, 'gender.ContainsAny({Male})')
Specifying the Calculation Scope for Elements that use Factors
If you use factors to calculate a mean, standard deviation, standard error or sample variance, you
can specify whether you want the mean to be calculated for all the elements, or for just those
elements preceding the mean element in the table.
This example calculates the mean for the first two age categories, 11-16 years and 17-20 years:
age{base(), E1116_years, E1720_years, mean() [CalculationScope=PrecedingElements], E2124_years, E2534_years}
This example calculates the mean for all the specified age categories:
age{base(), E1116_years, E1720_years, mean() [CalculationScope=AllElements], E2124_years, E2534_years}
The default calculation scope is AllElements when you create the mean in IBM® SPSS® Data
Collection Survey Tabulation. The default is PrecedingElements when the mean exists in the
metadata. This is for compatibility with IBM® SPSS® Quanvert™ data sources.
1223
Base Professional
For further details see the Table Object Model Reference help for the CalculationScope property.
Specifying Decimal Places for a Summary Statistic Element
Sample Script File: DecimalPlacesOnSummaryElements.mrs
You can use the axis expression syntax to specify decimals for a summary statistic using the
Decimals property, as shown in the following script:
Set Table = TableDoc.Tables.AddNew("Table02", "age{.., mean() [Decimals=1]} *

gender", "Decimal places on elements")
This results in the following table:

Figure 1-283
Table showing mean element with 1 decimal place
For a full list of the element types for which you can specify decimal places, see the Table Object
Model Reference help for the Decimals property.
Specifying Factors for Existing Elements
Sample Script File: RDBTables.mrs

1224
Chapter 1
This example script is based on the Short Drinks sample data set. See Running the Sample Table
This example is based on the Short Drinks sample data set.
The Displaying a Mean Based on Factors topic provides an example of basing a mean on the
factor values stored for the elements in the metadata. This example shows you how to specify
factor values in the axis specification.
hhsize{HH_1 [Factor=1],
HH_2 [Factor=2],
HH_3 [Factor=3],
HH_4 [Factor=4],
HH_5 [Factor=5],
HH_6 [Factor=6],
HH_7 [Factor=7],
Mean 'Average number' mean()}
This example defines factors for the elements in the Household Size (hhsize) variable and creates
a special mean element based on the factors we have defined.

Figure 1-284
Table showing mean element calculated from factors defined for the elements of Household size
variable
Specifying factors for special elements
You can specify factors for elements you define in your script using custom expressions. This
example shows you how to specify factor values for elements used to band a numeric variable.
income{Low 'Low (1)' expression('income > 0 And Income < 50001') [Factor=1],
Mid 'Middle (2)' expression('income > 50000 And Income < 100001') [Factor=2],
High 'High (3)' expression('income > 100000') [Factor=3],
Mean 'Mean' mean()
This example bands the numeric income variable into three elements, defines a factor for each
element, and creates a special mean element based on the factors. Notice that the factor value
has been included in the element labels. This is useful for understanding the tabulated results
when you use arbitrary values.
1225
Base Professional

Figure 1-285
Table showing mean element calculated from factors applied to banded elements
However, when banding numeric variables, it is more usual to base the mean on the raw numeric
values. When you do this, you do not need to define factors. For example:
income{Low 'Low' expression('income > 0 And Income < 50001'),
Mid 'Middle' expression('income > 50000 And Income < 100001'),
High 'High' expression('income > 100000'),
Mean 'Mean' mean(income)}
Notice that when you want to base the statistical element on the raw numeric values, you must
specify the name of the variable inside the parentheses that follow the keyword that defines
the special element (mean in this example).

Figure 1-286
Table showing mean element calculated from raw values of banded numeric elements
For further details see the Table Object Model Reference help for the Factor property.
Fixing an Element’s Position in a Table
You use the IsFixed property when you want to specify that an element’s position in the axis
should be fixed when the table is sorted. For example:
hhsize{HH_1 [Factor=1],
HH_2 [Factor=2],
1226
Chapter 1
HH_3 [Factor=3],
HH_4 [Factor=4],
HH_5 [Factor = 5],
HH_6 [Factor = 6],
HH_7 [Factor = 7],
Mean 'Average number' mean() [IsFixed=True]}
Note that most special elements have a fixed position for sorting by default. This means that in
practice you do not need to set the property on a mean element. For more information, see the
topic Sorting Special Elements on p. 1417.
For further details see the Table Object Model Reference help for the IsFixed property.
Hiding Elements
You use the IsHidden property when you want to hide an element. Hiding an element is different
from removing or excluding the element from an axis, because a hidden element will contribute to
any subtotal, total, and other statistical elements, whereas elements that are removed or excluded
from an axis will not. However, both hidden and removed and excluded elements will be included
in the base. For more information, see the topic The Base Element on p. 1230.
This example hides the Other element in the sclass variable:

sclass{..Not_work, Other [IsHidden=True]}
Hiding elements that appear in a row or column
You use the IsHiddenWhenRow and IsHiddenWhenColumn properties when you want to hide
an element when it is used in one axis but display it when it is used in the other axis. These
properties are useful when you want to override the settings of elements brought in from IBM®
SPSS® Quantum™ using the IBM® SPSS® Quanvert™ DSC. You can also use it to create an
axis that can be used either on the side or top of a table, where you want to hide an element on
one axis but not the other.
This example hides the Other element when it appears on the side axis:
sclass{..Not_work, Other [IsHiddenWhenRow=True]}
For further details see the Table Object Model Reference help for the IsHidden property.
Excluding Categories From the Base
Sample Script File: IncludeInBase.mrs

1227
Base Professional
You can exclude particular categories from the calculation of the base, while still including the
categories in rows or columns in the table. For example, you may want to include rows for ‘No
Answer’ or ‘Refused’ responses in a table, while excluding these responses from the base, or from
any calculations that use the base, such as percentages.
One way to do this is by setting the IncludeInBase property of the categorical element to False.
This prevents the value for the category from being counted in the base, and automatically ensures
that any summary statistics calculated from the base also exclude the category.
"museums{..Northern_Gallery, Other 'Other (excluded)' [IncludeInBase=False]}* gender"
You can achieve this by entering the following into the top or side axis:
museums{..Northern_Gallery, Other 'Other (excluded)' [IncludeInBase=False]
The following table shows the results:

Figure 1-287
Table showing base element for museums variable, excluding value of Other category
For further details on how the IncludeInBase property affects base elements, see Excluding
Information from the Base Element.
Another way of excluding responses from a base is to create an expression for the base element.
You can also use expressions to exclude responses from special elements such as mean or sample
variance. For an example of how to add expressions to the base element, see Restricting a Base
Using an Expression.
For further details see the Table Object Model Reference help for the IncludeInBase property.
1228
Chapter 1
Languages (3-Character Codes)
The following table shows the 3-character language codes for many of the world’s languages.
Code Language
AFK Afrikaans
SQI Albanian
ARG Arabic - Algeria
ARH Arabic - Bahrain
ARE Arabic – Egypt
ARI Arabic – Iraq
ARJ Arabic – Jordan
ARK Arabic – Kuwait
ARB Arabic – Lebanon
ARL Arabic – Libya
ARM Arabic – Morocco
ARO Arabic – Oman
ARQ Arabic – Qatar
ARA Arabic – Saudi Arabia
ARS Arabic – Syria
ART Arabic – Tunisia
ARU Arabic – United Arab Emirates
ARY Arabic – Yemen
HYE Armenian
EUQ Basque – Basque
BEL Belarusian
BGR Bulgarian
CAT Catalan
CHS Chinese
ZHH Chinese – Hong Kong, SAR
ZHI Chinese – Singapore
CHT Chinese – Taiwan
HRV Croatian – Croatia
CSY Czech
DAN Danish
NLB Dutch – Belgium
NLD Dutch – The Netherlands
ENA English – Australia
ENL English – Belize
ENC English – Canada
ENB English – Caribbean
ENI English – Ireland
ENJ English – Jamaica
ENZ English – New Zealand
ENS English – South Africa
ENT English – Trinidad
1229
Base Professional
Code Language
ENG English – United Kingdom
ENU English – United States
ETI Estonian – Estonia
FOS Faroese – Faroe Islands
FAR Farsi
FIN Finnish
FRB French – Belgium
FRC French – Canada
FRA French – France
FRL French – Luxembourg
FRS French – Switzerland
DEA German – Austria
DEU German – Germany
DEC German – Liechtenstein
DEL German – Luxembourg
DES German – Switzerland
ELL Greek
HEB Hebrew
HIN Hindi
HUN Hungarian
ISL Icelandic
IND Indonesian
ITA Italian – Italy
ITS Italian – Switzerland
JPN Japanese
KOR Korean
LVI Latvian
LTH Lithuanian
MSL Malay – Malaysia
NOR Norwegian (Bokmal)
NON Norwegian (Nynorsk)
PLK Polish
PTB Portuguese – Brazil
PTG Portuguese – Portugal
ROM Romanian – Romania
RUS Russian – Russia
SRB Serbian (Cyrillic)
SRL Serbian (Latin)
SKY Slovak
SLV Slovenian
ESS Spanish – Argentina
ESB Spanish – Bolivia
ESL Spanish – Chile
ESO Spanish – Colombia
1230
Chapter 1
Code Language
ESC Spanish – Costa Rica
ESD Spanish – Dominican Republic
ESF Spanish – Ecuador
ESE Spanish – El Salvador
ESG Spanish – Guatemala
ESH Spanish – Honduras
ESM Spanish – Mexico
ESI Spanish – Nicaragua
ESA Spanish – Panama
ESZ Spanish – Paraguay
ESR Spanish – Peru
ESU Spanish – Puerto Rico
ESY Spanish – Uruguay
ESV Spanish – Venezuela
SVF Swedish – Finland
SVE Swedish – Sweden
THA Thai – Thailand
TRK Turkish
URK Ukrainian
URD Urdu
VIT Vietnamese – Vietnam
The Base Element
Base elements typically show the total number of cases in an axis and are used in the calculation of
percentages and statistical tests. IBM® SPSS® Data Collection Base Professional automatically
adds a base element to the start of every axis that does not already have a base element. The base
elements that Base Professional inserts automatically are sometimes called autobase elements.
An axis must always contain at least one base element. You cannot remove or clear the base
element from an axis that does not contain another base element. (You will get an error if you
attempt to use the Elements.Remove method to remove a base element from an axis that does not
contain another base element. Using the Elements.Clear method removes all the elements from the
axis and then adds an autobase.) However, you can hide a base element, as shown below.
The Base Calculation
Sample Script File: BaseElements.mrs
When calculating the base, IBM® SPSS® Data Collection Base Professional includes every case
for which the case data stored in the variable is not Null. A value of Null is a special marker
that indicates that the value is not known and generally indicates that the question on which the
variable is based was not asked. A value of Null is different from an empty or zero value.
1231
Base Professional
When a respondent is asked a categorical or open-ended question but for some reason does not
answer, the case data generally stores an empty categorical value ({}) or an empty string (“”)
respectively (although some questions have one or more special categories to indicate that the
respondent did not provide an answer). Consequently, for categorical and text data, it is possible
to distinguish between a question that was asked but not answered and one that was not asked
at all. However, in numeric data it is not possible to distinguish questions that were asked but
not answered from those that were not asked at all, because the Data Model currently stores a
Null value for both.
In a simple survey where a case corresponds to a respondent, the base generally includes every
respondent who was asked the question on which the variable is based, regardless of whether he
or she actually answered it or not.
When you create an axis based on a subset of the elements in a variable, the base is the same
as when you select all of the elements. To illustrate this, we will use the signs variable in the
Museum XML data set to create an unfiltered one-dimensional table:
TableDoc.Tables.AddNew("Signs", "signs", "Unmodified Signs variable")
Here is the table:

Figure 1-288
One-dimensional table showing signs on side axis
Notice that the base is 298, which is the sum of the counts in the three categories. This is a single
response variable and all of the respondents who were asked the question answered it. Note that if
any of the respondents had not answered the question, they would be included in the base too.
Now let’s modify the table to include only the first two categories:
TableDoc.Tables.AddNew("SignsNew", "signs{Yes, No}", _

"Two elements of the Signs variable")
Here is the table:

Figure 1-289
One dimensional table showing signs on side axis; including only Yes and No responses, base unfiltered
Notice that the base is still 298, but it no longer represents the sum of the counts in the categories
on the table. This is because the base represents the number of respondents who were asked the
question and is not based on the counts in the categories that have been selected for inclusion on
the table. If you want the base to reflect only the respondents who selected the categories that
are shown on the table, you would need to use a filter. For example, you could use the following
1232
Chapter 1
filter to exclude respondents from the table who did not choose either of the two categories that
are shown:
TableDoc.SignsNew.Filters.AddNew("ExcludeCases", _
"signs.ContainsAny({Yes, No})")
Here is the table after applying the filter:

Figure 1-290
One-dimensional table showing signs on side axis, including only Yes and No responses, base filtered
Notice that the base is now 271, which is the sum of the counts in the two categories that are
shown on the table.
Tip: An alternative would be to create a derived variable based on the Signs variable, but
containing only the Yes and No categories, and use the variable to create the table. The autobase
would then include the Yes and No categories only and there would be no need to filter the table.
For more information, see the topic Creating Built-in Base Elements on p. 463.
Now suppose we want to add a mean element based on the visits numeric variable to the axis in
the unfiltered table:
TableDoc.Tables.AddNew("SignsAndVisits", "signs{Yes, No, " + _

"meanvisits 'Average number of visits' mean(visits) }", _
"Modified Signs variable with mean of Visits")
Here is the table:

Figure 1-291
One dimensional table showing signs variable on side axis, including only Yes and No responses, base
filtered, with additional mean visits row
The visits variable is a numeric variable, which means that it stores a Null value for respondents
who were not asked or did not answer the question on which it is based. In the Museum sample,
the visits variable stores a Null value for some of the respondents who are included in the table.
When Base Professional calculates the base used by the mean value calculation, it includes only
respondents who are included in the table base and for whom the numeric variable does not
store a Null value.
1233
Base Professional
The following table lists some hypothetical responses and shows whether the case is included in
the base for the axis and the base for the mean element.
Case Value in Signs Value in Visits Included in Axis Included in Base
Variable Variable Base in Unfiltered for Mean Element
Table
1 {Yes} 4 Yes Yes
2 {No} Null Yes No
3 {Dont_Know} 5 Yes Yes
4 Null 2 No No
5 {} Null Yes No
Notes:
When working with the hierarchical view of the data, empty levels are considered to be Null
and are not counted in the base. See the seventh example table in Understanding Population
Levels for more information.
The base calculation is different from IBM® SPSS® Data Collection Survey Tabulation 1.1,
where the base excluded empty values as well as Null values.
The Unweighted Base in Weighted Tables
When working with weighted data, it is good practice to show the unweighted base values in your
tables in addition to the weighted base values. This is particularly important when showing
percentages. To facilitate this, by default, IBM® SPSS® Data Collection Base Professional
automatically adds an unweighted base element at the start of each axis in a weighted table. For an
example of a weighted table containing unweighted base elements, see Weighting Tables.
The unweighted base element shows the total number of cases in the variable before any weighting
has been applied. Only one value is ever shown in the table cells formed from the unweighted base
element, even when there are multiple cell contents. The value that is shown is the unweighted
base count, regardless of what cell contents have been requested for the table.
You can stop the automatic insertion of the unweighted base elements by setting the
AutoUnweightedBases table property to False. However, you would then need to insert
unweighted base elements into your axes manually, when necessary, to comply with good practice
guidelines. The following examples shows how to set the property:
MyTable.Properties["AutoUnweightedBases"] = False
The unweighted base element is added when you add the weighting to the table, so you need to
set the property before you weight the table.
Working with Built-in Base Elements
Sample Script File: QuanvertTables.mrs

1234
Chapter 1
Sometimes variables (such as those in a IBM® SPSS® Quanvert™ database) have base elements
actually built into the variable. Built-in base elements sometimes contain filtering, which may,
for example, exclude cases in a Don’t know or Not answered category. When one of these bases
appears in an axis, IBM® SPSS® Data Collection Base Professional does not add an autobase.
Note that when you use the element list syntax to specify which elements you want to include in
an axis, you need to explicitly specify any built-in base elements if you want to include them.
If you do not, Base Professional will automatically add an autobase to ensure that the axis has
a base element.
For example, the Museum Quanvert sample database has a base element built into all of the
categorical variables. In the following table, the side axis (which is based on the remember
variable) will include the Quanvert base element, because it is explicitly specified in the element
list, whereas the top axis (which is based on the gender variable) will not, because the built-in base
element is not included in the element list. Therefore, Base Professional will create an autobase
element for the top axis but not for the side axis.
TableDoc.Tables.AddNew("MyTable", "remember{Base, Dinosaurs, Fossils} * gender{Male, Female}", _
"Including and excluding the built-in base")
TableDoc.MyTable.Annotations[5].Specification = "<B>Specification: </B><BR/>{TableSpec}"
Both of the base elements in the table have the default label of “Base” and so the fact that one is
an autobase and the other is the built-in Quanvert base is not immediately obvious simply from
looking at the table. If necessary you can use the {TableSpec} annotation macro to display the
table specification as an annotation, as shown in the above example. Here is the table:
Figure 1-292
Table showing remember by gender, using annotation to display the table specification
You can create built-in base elements in your variables in the Metadata section of a data
management script (.dms) file. For more information, see the topic Creating Built-in Base
Elements on p. 463.
Excluding Information from the Base Element
Sample Script File: IncludeInBase.mrs
This example is based on the Museum sample data set. See Running the Sample Table Scripts for
information on running the example scripts.
1235
Base Professional
You can exclude particular elements from the calculation of the base element, while still including
the responses in rows or columns in the table. For category type elements, you can do this by
setting the IncludeInBase element property of the element to False. This prevents the value for the
category from being counted in the base, and automatically ensures that any summary statistics
calculated from the base also exclude the category.
This script excludes responses of ‘Other’ from the calculation of the base count:
Table.Side.Museums.Elements["Other"].IncludeInBase = False
Alternatively, you can use the axis expression to achieve the same effect:
"museums{..Northern_Gallery, Other 'Other (excluded)' [IncludeInBase=False]}* gender"
The following table shows the results:

Figure 1-293
Table showing museums by gender, excluding Other responses from the base
Notes:
Only the Count cell item is shown for excluded items, as it is not valid to calculate an element
percentage on a base if that element is not included in the base.
Setting the IncludeInBase property to False automatically excludes the category from both
base and unweighted base elements.
Items are excluded from the closest preceding base (or unweighted base) element.
The IncludeInBase property has no effect on ‘built-in’ base elements, for example, base
elements in IBM® SPSS® Quanvert™ datasets.
The property has no effect on elements other than base and unweighted base elements. It
does not exclude the category from, for example, subtotals or totals. To exclude a category
from a subtotal, place it after the subtotal.
If you set the IncludeInBase property to False in an element in a net, the element is excluded
only from base elements within the same net.
1236
Chapter 1
The IncludeInBase property can be set to False only for category type elements.
Setting the IncludeInBase property to False overrides any expression specified on the base
element.
If you want to exclude other types of element from the base, you need to create an expression
to exclude it, using the Expression special element type. For an example of how to use the
Expression special element type, see Special Elements.
Hiding the Base Element
Sample Script File: BaseElements.mrs
This example is based on the Museum sample data set. See Running the Sample Table Scripts for
information on running the example scripts.
By default, the autobase (or built-in base when this is used instead) is shown in all axes except
those formed from the iterations in a grid table. However, you can choose to hide the element
so that it is not shown on the table. You do this by setting the Element.IsHidden property to
True. For example, the following script creates a table of age by gender and hides the autobase
element in both axes:
TableDoc.Tables.AddNew("AgeByGender", "age * gender", "Age By Gender")

' Hide the base elements
TableDoc.AgeByGender.Side.Age.Elements.Base.IsHidden = True
TableDoc.AgeByGender.Top.Gender.Elements.Base.IsHidden = True
Here is the table:

Figure 1-294
Table of age by gender, with base elements hidden
An alternative would be to create the base elements using the base() syntax and set the IsHidden
element property to True. For example:
TableDoc.Tables.AddNew("AgeByGender", "age{Base() [IsHidden=true], ..} * gender{Base() [IsHidden=true], ..}", _

"Age By Gender")
For more information, see the topic Element Properties on p. 1222.

1237
Base Professional
Understanding Axes
Sample Script File: UnderstandingAxes.mrs
The examples in this topic are based on the Museum sample data set. See Running the Sample
Table Scripts for information on running the example scripts.
Suppose you use a script similar to the following to create a table of age by gender:
TableDoc.Tables.AddNew("MyTable", "age * gender", "Age by Gender")
When you run the script, the Table Object Model automatically creates two Axis objects called
Side and Top in the Table.Axes collection. Each Axis object in this collection defines a dimension
of the table and is sometimes called a root-level axis. The Table Object Model currently supports
a maximum of two root-level axes and their names must always be Side and Top.
The Table Object Model also creates an Axis object in the SubAxes collection in each of the Side
and Top Axis objects. The names of these subaxes are based on the variable names we used in
the table specification.
The following diagram shows the structure of the objects in the object model and the relationship
of the axes to one another in the table.
1238
Chapter 1
Figure 1-295
Graphical representation of axes in object model and in table
To understand why the Table Object Model creates the root-level Side and Top axes, let’s consider
a more complex table. Suppose you use the following script to create a table that has two variables
(age and gender) concatenated on the side and one variable nested within another on the top
(interview within before):
TableDoc.Tables.AddNew("Table2", "age + gender * before > interview", _
"Concatenation on side and nesting on top")
First let’s look at the structure of the side Axis objects (where age and gender are concatenated):
Figure 1-296
Graphical representation of side axis with age and gender concatenated
You can see that the Table Object Model has created a root-level Axis object called Side again.
However, this time it has created two subaxes within it. The subaxes are at the same level, just
as the variables are on the table. The root-level axis provides a convenient way of referring to
1239
Base Professional
the two axes concatenated together. Without the root-level axis, this would not be possible.
Now let’s look at the top Axis objects:
Figure 1-297
Graphical representation of top axis with interview nested inside before
Notice how the relationship of the Axis objects reflects the nesting we defined. The Table Object
Model has created the interview Axis as a child of the before Axis, which is in turn a child of the
root-level Top Axis.
Generally Axis objects form a tree structure with a single root node. Every node in the tree is
an Axis object and, with the exception of the root node, each Axis object is associated with a
variable. The next example creates a table in which the top axis of the table is formed by nesting
the interview variable within both the entrance and gender variables.
TableDoc.Tables.AddNew("Table3", "age * (entrance + gender) > interview", _

"Balanced tree")
The following diagram shows the axis structure, which is an example of what is sometimes
referred to as a “balanced tree”, because it leads to a balanced axis structure:
Figure 1-298
Graphical representation of axis with entrance and gender concatenated, interview nested within each
Here is the table (with the base elements in the top axis hidden to aid clarity).
1240
Chapter 1
Figure 1-299
Table showing age on side axis and (entrance + gender) > interview on top axis
You are not forced to create a balanced tree structure. The next example creates a table in which
the top axis of the table is formed by nesting the interview variable within the gender variable, but
not the entrance variable.
TableDoc.Tables.AddNew("Table4", "age * entrance + gender > interview", _

"Unbalanced tree")
The following diagram shows the axis structure, which is an example of what is sometimes
referred to as an “unbalanced tree”:
Figure 1-300
Top axis with entrance concatenated with gender, interview nested within gender
Here is the table (with the base elements in the top axis hidden to aid clarity).
Figure 1-301
Table showing age on side axis, entrance + gender > interview on top axis
1241
Base Professional
The structure of an axis can be extended indefinitely. However, the resulting tables can quickly
become very large and complex. The following example creates a complex unbalanced tree
structure on the top axis of the table:
TableDoc.Tables.AddNew("Table5", "age * entrance + gender > _
(interview + before{.., ^Not_answered} > biology{.., ^Not_answered})", _
"Complex unbalanced tree")
The specification is evaluated from left to right, but the nesting symbol (>) is evaluated before the
concatenation symbol (+). Notice how parentheses have been used to override the default order of
precedence. The following diagram shows the axis structure:
Figure 1-302
Complex unbalanced structure
The following diagram shows the structure of the overall axis on the table:
Figure 1-303
Unbalanced structure in table layout
You can find out the number of child subaxes that belong to an axis or subaxis using the
Axis.SubAxes.Count property and you can return the child Axis objects themselves using the
Axis.SubAxes.Item property.
The following script demonstrates how these properties work. The script loops through the axes
and subaxes on each table, writing their names and subaxis count to a text file:
Dim fso, txtfile, MyTable, MyAxis, MySubAxis, i, j, MyText
Set txtfile = fso.CreateTextFile("UnderstandingAxes.txt", True)
1242
Chapter 1
For Each MyTable in TableDoc.Tables

txtfile.WriteLine()
txtfile.WriteLine(MyTable.Name)
For Each MyAxis In MyTable.Axes
ListAxes(MyAxis, txtfile)
Next
Next
Sub ListAxes(MyAxis, txtfile)

Dim MyText, MySubAxis
MyText = MyAxis.Name + " - subaxis count: " + CText(MyAxis.SubAxes.Count)
txtfile.WriteLine(MyText)
For Each MySubAxis in MyAxis.SubAxes
ListAxes(MySubAxis, txtfile)
Next
End Sub
txtfile.Close()
If we run this script for the tables we created above, we would get the following output:
Table1
Side - subaxis count: 1
age - subaxis count: 0
Top - subaxis count: 1
gender - subaxis count: 0
Table2
before - subaxis count: 1
interview - subaxis count: 0
Table3
entrance - subaxis count: 1
Table4
Table5
1243
Base Professional

before - subaxis count: 1
biology - subaxis count: 0
Navigating the Axis Tree
Understanding Axes explains the structure of the Axis objects in the dimensions of a table. This
topic shows the various techniques that you can use to reference individual Axis objects within a
complex table axis structure. In this topic, we shall use the following table axis structure as an
example. (This is the top axis in the fifth table discussed in Understanding Axes.) This is a
deliberately complex example that is being used for illustration purposes. In practice, most axis
structures are less complex.
Figure 1-304
Graphical representation of complex axis: entrance + gender > (interview + (before > biology))
Assuming that the Top Axis object is part of a table, you can obtain a reference to this axis object
using the following:
Dim MyTopAxis
Set MyTopAxis = MyTable.Axes.Item["Top"]
After obtaining this reference to the axis, you can obtain a reference to the Male Element object in
the Gender axis using the following:
Dim MyElement
Set MyElement = MyTopAxis.SubAxes.Item["gender"].Elements.Item["Male"]
To obtain the element from the Table object using the full (combined) expression, you could use:
Set MyElement = MyTable.Axes.Item["Top"].SubAxes.Item["gender"].Elements.Item["Male"]

1244
Chapter 1
This is a long and complex expression to write. However, you can use the fact that the Item
property is the default property for both the Axes and Elements collections and shorten the
expression to:
Set MyElement = MyTable.Axes["Top"].SubAxes["gender"].Elements["Male"]
Similarly, the Axes property is the default property of the Table object. So you can shorten
it even further:
Set MyElement = MyTable["Top"].SubAxes["gender"].Elements["Male"]
Using a feature of mrScriptBasic called “dynamic property expansion”, this can be written even
more compactly. For more information, see the topic Dynamic Property Expansion on p. 1246.
Working with Elements and Element Headings
The Axes and Elements collections, and the Axis and Element objects, are used to define the
structure of a table, as described in the topics Understanding Axes and Navigating the Axis Tree.
However, the order of elements displayed in a table can differ from the order in which they were
defined for the table. This happens when a table is sorted, nested, or contains hidden elements.
When you need to work with the elements displayed in a table, as opposed to the elements in the
original structure defined for the table, use the AxisHeadings and ElementHeadings collections,
and the AxisHeading and ElementHeading objects. These objects are automatically updated
when a table is populated, and always reflect the sorted order and the status of hidden elements.
This ensures that they match the order of the rows and columns in the ADO recordset, accessed
using the Table.CellValues property. For more information, see the topic Working with the ADO
Recordset on p. 1265.
The following example shows the structure of a simple table, before and after sorting:
Figure 1-305
Table showing biology by base
The Elements collection for the table contains:
Gender: Elements - Base, Male, Female
Biology: Elements - Base, Yes, No, Not Answered
The ElementHeadings collection for the table is the same at this stage:
Gender: ElementHeadings - Base, Male, Female

1245
Base Professional
Biology: ElementHeadings - Base, Yes, No, Not Answered
If the table is sorted by the numbers of those holding a qualification in biology — MyTable.SortRow
= "biology{yes}" — the order of elements in the top axis changes:
Figure 1-306
Table showing biology by base, sorted on biology {yes}
This is not reflected in the Elements collection, which retains the original order defined for the
table. However, the order of elements in the ElementHeadings collection is automatically updated
to reflect the displayed order of the headings:
Gender: ElementHeadings - Base, Female, Male
Biology: ElementHeadings - Base, Yes, No, Not Answered
When a table is nested, elements occur more than once in the displayed table. The following
example shows the side axis of a table with Gender nested within Entrance:
Figure 1-307
Table showing gender nested within entrance on side axis
In the list of elements in the Elements collection, the elements occur only once:
Entrance: Elements - Base, Main, Side
Gender: Elements - Base, Male, Female
In the ElementHeadings collection, the list of elements matches that of the displayed table:
Entrance: Elements - Base, Main, Side
Gender: Elements - Base, Male, Female, Base, Male, Female, Base, Male, Female
1246
Chapter 1
If the table is sorted, the ElementHeadings collection is automatically updated to reflect the
new order.
Differences between the defined structure of a table and the displayed structure of a table also
occur if you create a table containing a hidden element. The Elements collection contains the
hidden element, but the ElementHeadings collection reflects the displayed table and does not
contain the hidden element.
Dynamic Property Expansion
Navigating the Axis Tree explains various techniques that you can use to reference individual
Axis objects within a complex table axis structure. In this topic, we will look at using the
mrScriptBasic dynamic property expansion feature to make your script more compact. We shall
use the following table axis structure as an example. (This is the top axis in the fifth table
discussed in Understanding Axes.)
Figure 1-308
Graphical representation of complex axis: entrance + gender > (interview + (before > biology))
A number of objects in the Table Object Model implement dynamic property expansion. For
example, the Axes collection object supports dynamic property expansion of the Item property.
This means you can access an item in the collection as if it were a property of the collection
object. Therefore:
Set MyTopAxis = MyTable.Axes.Item["Top"]
Can be written as
Set MyTopAxis = MyTable.Axes.Top
Dynamic property expansion is implemented in the following objects in the Table Object Model:
The Document object dynamically expands the Item property of its Tables property.
The Tables object dynamically expands its Item property.
The Table object dynamically expands the Item property of its Axes property.
The Axes object dynamically expands its Item property.
The Axis object dynamically expands the Item property of its SubAxes property.
The Elements object dynamically expands its Item property.
1247
Base Professional
The Element object dynamically expands the Item property of its SubElements property.
The Filters object dynamically expands its Item property.
The Exports object dynamically expands its Item property.
The Statistics object dynamically expands its Item property.
The Statistic object dynamically expands its Properties collection.
This means that using the dynamic property expansion feature on the Elements object, you can
write the following:
Set MyElement = _
MyTable.Axes.Item["Top"].SubAxes.Item["gender"].Elements.Item["Male"]
As:
Set MyElement = MyTable.Axes.Item["Top"].SubAxes.Item["gender"].Elements.Male
However, “MyTable.Axes.Item[”Top”]” is also an Axis object. So using the dynamic property

expansion on this object, we can write this:
Set MyElement = MyTable.Axes.Item["Top"].gender.Elements.Male
Then, making use of the dynamic property expansion on the Table object, we can rewrite this as:
Set MyElement = MyTable.Top.Gender.Elements.Male
This shows that Axis objects in a complex hierarchy can be accessed using a very compact
notation. For example, the biology Axis in the above example can be accessed as:
Dim BiologyAxis
Set BiologyAxis = MyTable.Top.Gender.Before.Biology
Note: The dynamic property expansion feature cannot handle axis or element names that contain a
period character (.). For example, you cannot use the dynamic property expansion when referring
to an axis called Vehicle.Rating[{Comfort}].Column. This is because the Table Object Model
cannot distinguish between a period that is embedded in a name from a period that indicates
the beginning of the next property.
Cell Contents
This section provides details of the cell contents and table properties that you can use, explains
about weighting and the rounding that is performed by IBM® SPSS® Data Collection Base
Professional, and provides a number of examples.
Available Cell Contents
The figures that are shown in the cells of a table are known as cell contents. The following table
lists the types of cell contents that you can define in your tables, along with the constants and their
associated values that you use to specify the various types of cell contents in your scripts. You
can use the constant (prefixed with “CellItemType.”) if your script is part of a data management
1248
Chapter 1
script (.dms) file. If your script is a standalone .mrs file, you must use the numeric value or set up
user-defined constants to represent the values (as shown in the CellContents.mrs sample).
Some of the types of cell contents show summary statistics of numeric variables for the cases in
the cells of a table. For example, the visits variable in the Museum data set is a numeric variable
that records the number of times respondents have visited the museum before. In a table of age by
gender, you can use the visits variable to show the sum of previous visits made to the museum
by the respondents in each cell. Alternatively you can show the mean number of previous visits
made by the respondents in each cell.
For some detailed examples of using the various types of cell contents, see Examples.
Description Constant Hexadecimal Value
Adjusted residuals. Reserved for itAdjustedResiduals &H0013
future use.
Column base. Shows the number itColBase &H0018
of cases in the column base. This
is shown in the base row of the
table. This cell item is useful
when the base row is hidden or
when tables are so large that the
row is not always visible.
Column percentages. Express itColPercent &H0001
the count or sum of a numeric
variable as a percentage of the
base for the column. Expressing
figures as percentages can make
it easier to interpret and compare
the data in a table.
Counts. Show the number of itCount &H0000
cases that satisfy the row and
column conditions for each cell.
If the table is weighted, the counts
are the weighted counts.
Cumulative column percent- itCumColPercent &H0009
ages. Express the column
percentages as cumulative
percentages.
Cumulative row percentages. itCumRowPercent &H000A
Express the row percentages as
cumulative percentages.
Expected values. Show the count itExpectedValues &H0014
or sum of a numeric variable that
would be expected in the cell if
the row and column variables
are statistically independent or
unrelated to each other.
1249
Base Professional

Indices. Calculated for each cell itIndices &H0016
by dividing the row percentage in
the cell by the row percentage for
the same column in the base row.
Indices show how closely row
percentages in a row reflect the
row percentages in the base row.
The nearer a row’s indices are to
100%, the more closely that row
mirrors the base row.
Maximum. This summary itMaximum &H0007
statistic of a numeric variable
shows the largest value.
Mean. This summary statistic itMean &H0004
of a numeric variable gives a
measure of central tendency. It
is the arithmetic average—the
sum divided by the number of
cases who gave a response for the
numeric variable.
Median. This summary statistic itMedian &H000D
of a numeric variable shows the
value above and below which
half of the cases fall (the 50th
percentile). If there is an even
number of cases, the median is the
average of the two middle cases
when they are sorted in ascending
or descending order. The median
is a measure of central tendency
not sensitive to outlying values
(unlike the mean, which can be
affected by one or more extremely
high or low values).
Minimum. This summary itMinimum &H0006
shows the smallest value
Mode. This summary statistic of itMode &H000C
a numeric variable shows the most
frequently occurring value. When
several values share the greatest
frequency of occurrence, each of
them is a mode. IBM® SPSS®
Data Collection Base Professional
displays only one mode in each
cell—when there is more than one
mode, Base Professional displays
the first mode that it encounters
in the data.
1250
Chapter 1

Percentile. This summary itPercentile &H000E
shows the value that divides cases
according to values below which
certain percentages fall. For
example, the 25th percentile is the
value below which 25% of cases
fall.
Range. This summary statistic itRange &H000B
of a numeric variable shows the
difference between the largest and
smallest values—the maximum
minus the minimum.
Residuals. Show the difference itResiduals &H0012
between the count or sum of a
numeric variable and the expected
values. Large absolute values
for the residuals indicate that the
observed values are very different
from the predicted values.
Row base. Shows the number itRowBase &H0019
of cases in the row base. This
is shown in the base column of
the table. This cell item is useful
when the base column is hidden
or when tables are so large that
the column is not always visible.
Row percentages. Express itRowPercent &H0002
base for the row.
Standard deviation. This itStdDev &H000F
summary statistic of a numeric
variable shows a measure of
dispersion around the mean. In a
normal distribution, 68% of cases
fall within one standard deviation
of the mean and 95% of cases fall
within two standard deviations.
For example, if the mean age is
45 with a standard deviation of
10, then 95% of the cases would
be between 25 and 65 in a normal
distribution.
1251
Base Professional

Standard error. This summary itStdErr &H0010
shows a measure of how much the
value of the mean may vary from
sample to sample taken from the
same distribution. The standard
error of the sample mean can be
used to estimate a mean value for
the population as a whole. In a
normal distribution, 95% of the
values of the mean should lie in
the range of plus or minus two
times the standard error from the
mean. Additionally, the standard
error can be used to roughly
compare the observed mean to
a hypothesized value of another
mean (that is, you can conclude
that the two values are different if
there is no overlap in the values
of the means plus or minus two
times the standard error).
Sum. This summary statistic of a itSum &H0005
numeric variable shows the sum
or total of the values.
Total percentages. Express itTotalPercent &H0003
base for the table.
Unweighted column base. itUnweightedColBase &H001A
Shows the unweighted base for
the column. This is shown in
the base row of the table. This
cell item is useful when the
unweighted base row is hidden or
when tables are so large that the
row is not always visible.
Unweighted counts. In a itUnweightedCount &H0008
weighted table, these are the
unweighted counts. In an
unweighted table, the counts
and the unweighted counts are
identical.
Unweighted row base. Shows itUnweightedRowBase &H001B
the unweighted base for the row.
This is shown in the base column
of the table. This cell item is
useful when the unweighted base
column is hidden or when tables
are so large that the column is not
always visible.
1252
Chapter 1

Valid N. Reserved for future use. itValidN &H0015
Variance. This summary statistic itVariance &H0011
of a numeric variable shows
the sample variance, which is a
measure of dispersion around the
mean, equal to the sum of squared
deviations from the mean divided
by one less than the number of
cases. The sample variance is
measured in units that are the
square of those of the variable
itself.
Weighting
Weighting is another term for sample balancing. During a survey, it is not possible to interview
everyone, so only a sample of the population is interviewed. If this sample group does not
accurately reflect the proportions of various groups in the total population, you can then weight
the survey results.
For example, of the 602 respondents interviewed in the Museum survey, 56.31% were male and
43.69% were female, which does not reflect the proportions of males and females in the general
population. However, by using the genbalance weighting variable to weight the tables, you
can inflate the responses from the female respondents and deflate the responses from the male
respondents to reflect the actual balance of the genders.
You use the Table.Weight property to set the weighting for an individual table. For an example,
see Weighting Tables.
You can use the Document.Default.Weight property to set the default weighting for all new
tables. For example:
' Set the default weight, so that all new tables are weighted by default
TableDoc.Default.Weight = "Weight"
For an example of a weighted table, see .
How Table Weighting Works
When calculates counts in an unweighted table (or unweighted counts in a weighted table), it
increments the count in each cell by 1 each time it finds a case that satisfies the conditions
that define the cell. However, when calculates counts in a table weighted with the genbalance
weighting variable, it increments the counts in each cell as follows:
By 1.14; that is, (1 * 50/43.69) for female respondents
By 0.89; that is, (1 * 50/56.31) for male respondents
This assumes that the male/female proportions required are 50% of each.
The genbalance variable is simply a variable that stores the value 1.14 for every female and
0.89 for every male.
1253
Base Professional
Weighting variables must be numeric variables. However, not all numeric variables are suitable
for use as weights. Generally, weighting variables are created specially, typically using IBM®
SPSS® Data Collection Base Professionalthe Weight component. For more information, see the
topic Working with the Weight Component on p. 406.
Weighting Hierarchical Data
When you are using a hierarchical view of the data, the level of the weighting variable restricts
the levels at which you can populate the table: you cannot populate a table at a level that is
higher than the level of the weighting variable. To illustrate this, consider a survey similar to the
Household sample that has following levels structure:
Figure 1-309
Household structure
If the weighting variable is at the household (top) level, you can populate the table at the
household, person, trip, or vehicle level (assuming the other variables on the table do not restrict
the population level). However, if the weighting variable is at the person level, you cannot
populate the table at the household level, because it is higher than the level of the weighting
variable and you cannot populate the table at the vehicle level because it is at a parallel level to
the weighting variable. However, you can populate the table at the trip level, because it is lower
than the level of the weighting variable. For more information, see the topic Understanding
Population Levels on p. 1279.
Showing the Unweighted Base in Weighted Tables
When working with weighted data, it is good practice to show the unweighted base figures
in addition to the weighted base figures. To facilitate this, by default, automatically adds an
unweighted base element at the start of each axis in a weighted table. For more information,
see the topic The Base Element on p. 1230.
Rounding
performs all calculations using the maximum possible accuracy and only performs rounding
immediately before it displays figures in a table. uses a standard rounding algorithm when it
performs rounding. When rounding a real number to an integer, for example, rounds to the nearest
integer, except where the decimal places are exactly 5. In these cases, it rounds to the even integer
by default. This means that of the two possible rounded values, the one that has an even number
as the last significant digit is returned. For example, 15.25 is rounded to 15.2 rather than 15.3. If
you want to instead round half values up, you can set the RoundingOptions property to 1.
1254
Chapter 1
Apparent anomalies when you change the accuracy of cell contents that are real numbers can
usually be explained by the fact that performs each rounding calculation separately using the
maximum possible accuracy. For example, when you display a weighted count of 51.4999999
with one decimal place, it is shown as 51.5. If you then choose to display it without decimal
places, it becomes 51. At first sight, you might think this is incorrect because 51.5 should be
rounded to the even number 52. However, performs each rounding calculation separately from the
unrounded value, which in this example is 51.4999999, and the figure of 51 is in fact correct.
During the calculation of a base in a weighted table (for example, from counts for use in a
percentage calculation), uses the maximum possible accuracy of the contributing values. If the
base is subsequently displayed in the table, rounds it to the same number of decimal places as the
counts. This means that sometimes a base displayed in a table is not exactly equal to the sum of
the counts displayed in the contributing cells. For example, the following table shows the values
both before and after rounding of the counts for two cells and the base that calculates:
Cell Value before rounding Value shown in table
1 2.3134123 2
2 5.4341142 5
Base 7.7475265 8
When you show row or column percentages in a table, can optionally manipulate the percentages
to eliminate anomalies such as these. You can do this by setting the AdjustRounding property to
True. For more information, see the topic Table Properties on p. 1396.You can do this by selecting
Adjust rounding so that percentages add up to 100%. You can do this by selecting Adjust rounding
so that percentages add up to 100% in the Display tab of the .
Note:IBM® SPSS® Statistics calculates table totals from the rounded values shown in the table. In
a corresponding SPSS Statistics table containing the same figures, the total would be shown as 7.
Examples
Sample Script File: CellContents.mrs
This topic provides examples of using various different types of cell contents. All of the
tables in the examples use the same two variables from the Museum sample (biology on the
top and expect on the side).
Counts and unweighted counts
Counts show the number of cases that satisfy the row and column conditions for each cell after
any weighting defined for the table has been applied. Counts are the basic values that are shown
in the cells of a table. Unweighted counts show the number of cases that satisfy the row and
column conditions for each cell before any weighting defined for the table has been applied. In an
unweighted table, the counts and unweighted counts are identical.
1255
Base Professional
The following table shows both weighted and unweighted counts in all of the cells apart from
those formed from the unweighted base elements. By default, an unweighted base element is
added to all weighted tables. For more information, see the topic The Base Element on p. 1230.
Figure 1-310
Table showing counts and unweighted counts
In this table, both the weighted and unweighted counts are shown with two decimal places. The
table is weighted using the genbalance weighting variable, which uses non-integer sample weights
to weight the sample to an equal balance between the two genders. More males than females were
interviewed in the survey, so the genbalance weighting variable inflates the responses from female
respondents and deflates the responses from male respondents.
If you look at the unweighted counts in the Enjoyment row, you can see that of the people who
selected this category, 14 have a biology qualification and 31 don’t. The unweighted counts are
always whole numbers because a respondent either does or does not select each category. If you
look at the weighted counts in the same row, you can see that the figures are 14.48 and 31.12,
respectively. The weighted counts are non-integers because they represent the unweighted counts
multiplied by the appropriate weights, which in this example are non-integer values. For more
information, see the topic Weighting on p. 1252.
In practice, counts are generally shown as whole numbers, as shown in the next example.
Percentages
1256
Chapter 1
Percentages express the count or sum of a numeric variable as a percentage of the base for the
column, row, or table. Expressing figures as percentages can make it easier to interpret and
compare the data in a table. The following table shows both counts and column percentages.
Figure 1-311
Table showing counts and column percentages
In this table, the first figure in each cell is the count and the second is the column percentage. The
count in the Base column of the Base row shows that 304 respondents were asked both of the
questions that the variables in the table are based on. These respondents form the sample base for
the table.
The counts in the first row after the Base row show that 118 people described their expectation
as General knowledge and education, and of these people, 25 hold a biology qualification and
93 do not. The column percentages show that 39% of the respondents in the table describe their
expectation as General knowledge and education. A higher percentage of those who do not
have a biology qualification (41%) expected to gain general knowledge than those with such a
qualification (32%).
Sometimes, rounding means that the percentages for single response variables do not always add
up to 100%. If you add up all of the percentages in the No column in the above table, you will
see that they add up to 101% rather than 100%. This is because IBM® SPSS® Data Collection
Base Professional performs all calculations using the maximum possible accuracy and only
performs rounding immediately before it displays figures in a table. For more information, see the
topic Rounding on p. 1253.
You can use the AdjustRounding table property to specify that the rounding should be adjusted so
that the percentages add up to 100%.
1257
Base Professional
Here is the table after the rounding has been adjusted. Notice that the percentages in the No
column now add up to 100%:
Figure 1-312
Table showing counts and column percentages with rounding adjusted to add up to 100%
Note that the biology and expect variables are both single response variables. In multiple
response variables, percentages do not usually add up to 100% and adjusting the figures to do
so would not make sense.
In the next table, the column percentages are shown as cumulative percentages.
1258
Chapter 1
Figure 1-313
Table showing counts and cumulative column percentages
In this table, the column percentages are shown with two decimal places. In all other respects the
column percentages in the first row after the Base row are the same as those shown in the column
percentages table shown earlier. However, the percentages in the subsequent rows differ. This is
because the column percentages for each successive row are added to those of the previous rows
to make a cumulative percentage, so the cumulative percentage for the final row is 100%.
Notice that in this table the column percentages are not shown in the Base row. This has been
achieved by setting the Show100Percent table property to False.
The next table shows counts, and row and total percentages.
1259
Base Professional
Figure 1-314
Table showing counts and row and total percentages
In this table the first figure in each cell is the count, the second is the row percentage, and the third
is the total percentage. Row percentages show us what percentage of the respondents in each
row fall in each column. For example, if you look at the General knowledge and education
row, you can see that 21% of the respondents in the row hold a biology qualification, whereas
79% of them do not.
Similarly, total percentages show us what percentage of the total number of respondents in
the table fall in each cell of the table. Looking at the General knowledge and education row
again, you can see that respondents in the row who hold a biology qualification make up 8% of
the respondents in the table and those in the same row without a biology qualification make up
31% of the total for the table.
Note: You can remove the percent signs from all cells in a table (for example, in tables that contain
only percentage values) by setting the ShowPercentSignstable property to False.
Indices
1260
Chapter 1
Indices are calculated for each cell by dividing the row percentage in the cell by the row
percentage for the same column in the base row. Indices show how closely row percentages in a
row reflect the row percentages in the base row. The nearer a row’s indices are to 100%, the more
closely that row mirrors the base row. The following table shows row percentages and indices.
Figure 1-315
Table showing row percentages and indices
Looking at the table, we can see that the indices in the Other row are closest to 100%. Let’s
look at the No column. The index of 99 was created by dividing the row percentage of 74% by
75%, the row percentage for the No cell in the Base row. If we look at the row percentages in
the Other row, we can see that at 26% and 74% they closely match the row percentages of 25%
and 75% in the Base row.
Summary statistics of numeric variables
You can show summary statistics of numeric variables for the cases in the cells of a table. For
example, you can show the total number of previous visits made to the museum by the respondents
in each cell by using the Sum cell contents option and the visits variable. Similarly, you can
use the Mean cell contents option to show the average number of previous visits made by the
respondents in each cell.
In weighted tables, all of the summary statistics apart from the minimum and maximum values
are weighted. If you want to show unweighted summary statistics, do not weight the table.
In the following table, the first figure in each cell is the count, the second is the sum of the visits
numeric variable, and the third is the mean value of the visits numeric variable.
1261
Base Professional
Figure 1-316
Table showing counts and total and mean number of visits
When Base Professional calculates counts in a unweighted table, it increments the count in each
cell by one each time it finds a case that satisfies the conditions that define the cell. In the above
table, the count for the Yes cell of the General knowledge and education row has a value of 10
because there were 10 respondents who chose both the Yes category of the biology question and
the General knowledge and education category of the expect question, and who pass the filter on
the table.
When you choose to base cell contents on the sum of a numeric variable, instead of incrementing
each cell by one when it finds a case that satisfies the cell conditions, Base Professional increments
the cell by the value held in the numeric variable for that case. If we look at the Yes cell of the
General knowledge and education row again, we can see that the 10 respondents in the cell made
a total of 34 previous visits to the museum.
The mean shows the mean value of that variable for the respondents in the cell. The mean in the
same cell is 3.40, which is what you get when you divide the total number of visits (34) by the
number of respondents (10).
1262
Chapter 1
The above table is filtered to exclude respondents for whom the visits variable stores a Null
value. This is a special value that indicates that the respondent didn’t answer the question on
which the visits variable is based.
The next table is unfiltered and if we look at the Yes cell of the General knowledge and education
row again, we can see that the mean is shown as 3.40. The number of visits is still 34, but there
are now 25 respondents in the cell, so the mean appears to be incorrect. This is because IBM®
SPSS® Data Collection Survey Tabulation calculates the means by dividing the sum by the
number of respondents in the cell who answered the question on which the numeric variable is
based, and not by the total number of respondents in the cell. In this cell, as in most cells in the
unfiltered table, these two values are different.
Figure 1-317
Unfiltered table showing counts and total and mean number of visits
Expected values and residuals
Expected values show the count or sum of a numeric variable that would be expected in the
cell if the row and column variables were statistically independent or unrelated to each other.
Residuals show the difference between the count or sum of a numeric variable and the expected
1263
Base Professional
values. Large absolute values for the residuals indicate that the observed values are very different
from the predicted values.
In the following table, the first figure in each cell is the count, the second is the expected value,
and the third is the residual.
Figure 1-318
Table showing counts, expected values, and residuals
Looking at this table, we can see that the General knowledge and education shows the biggest
discrepancy between the actual counts and the expected values in both the Yes and No columns.
However, the actual count is less than the expected value in the Yes column and this is reflected
in the negative residual value and the actual count is greater than the expected value in the No
column and this is reflected in the positive residual value.
' User-defined constants to represent the cell item types

Const itCount = &H0000
Const itColPercent = &H0001
Const itRowPercent = &H0002
Const itTotalPercent = &H0003
Const itMean = &H0004
Const itSum = &H0005
Const itMinimum = &H0006
1264
Chapter 1
Const itMaximum = &H0007

Const itUnweightedCount = &H0008
Const itCumColPercent = &H0009
Const itCumRowPercent = &H000A
Const itRange = &H000B
Const itMode = &H000C
Const itMedian = &H000D
Const itPercentile = &H000E
Const itStdDev = &H000F
Const itStdErr = &H0010
Const itVariance = &H0011
Const itResiduals = &H0012
Const itExpectedValues = &H0014
Const itIndices = &H0016
Dim TableDoc
' Create the Table Document object

' Load the Museum sample XML data set

TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Xml\museum.mdd", _
"mrXmlDsc")
' Clear the default cell contents

TableDoc.Default.CellItems.Clear()
' Change the Expect variable's description

TableDoc.DataSet.MDMDocument.Fields["expect"].Label = "Expectation of visit"
.AddNew("Table1", "expect * biology{Yes, No}", _

"Weighted and unweighted counts")
.Table1.CellItems.AddNew(itCount, 2)
.Table1.CellItems.AddNew(itUnweightedCount, 2)
.Table1.Weight = "GenBalance"

"Counts and column percentages")
.Table2.CellItems.AddNew(itCount)
.Table2.CellItems.AddNew(itColPercent)

"Counts and column percentages - rounding adjusted")
.Table3.CellItems.AddNew(itColPercent)
.Table3.Properties["AdjustRounding"] = True

1265
Base Professional
"Counts and cumulative column percentages")

.Table4.CellItems.AddNew(itCumColPercent, 2)
.Table4.Properties["Show100Percent"] = False

"Counts and row and total percentages")
.Table5.CellItems.AddNew(itRowPercent)
.Table5.CellItems.AddNew(itTotalPercent)

"Row percentages and indices")
.Table6.CellItems.AddNew(itRowPercent)
.Table6.CellItems.AddNew(itIndices)

"Counts and total and mean number of visits - filtered")
.Table7.CellItems.AddNew(itSum, 0, "visits")
.Table7.CellItems.AddNew(itMean, 2, "visits")
.Table7.Filters.AddNew("VisitedMuseumBefore", _
"visits IS NOT NULL", "Has visited museum before")

"Counts and total and mean number of visits - unfiltered")
.Table8.CellItems.AddNew(itSum, 0, "visits")
.Table8.CellItems.AddNew(itMean, 2, "visits")

"Counts, expected values, and residuals")
.Table9.CellItems.AddNew(itExpectedValues)
.Table9.CellItems.AddNew(itResiduals)
End With

TableDoc.Populate()
' Export the tables

.Export("CellContents.htm")
End With
Working with the ADO Recordset
Sample Script Files: CellValues.mrs, CellValuesAndLabels.mrs

1266
Chapter 1
These example scripts are based on the Museum sample data set. See Running the Sample Table
The contents of a populated table are stored in an ADO recordset, which is accessible using the
Table.CellValues property. This topic provides examples of working with the recordset. An ADO
Recordset object consists of records and fields. In general terms the records represent the rows
of the table and the fields represent the columns of the table.
The Table.CellValues property returns the recordset for a table. The property has a single
parameter, which is designed for use in the future when the Table Object Model supports layers. It
should always be set to zero, which is its default value.
The following mrScriptBasic example creates a simple table of biology by gender, populates it,
and writes the recordset to a text file.
' Create the table of Biology by Gender
TableDoc.Tables.AddNew("Table1", "biology * gender", "Biology By Gender")
' Remove the column percentages default cell contents from the table

TableDoc.Populate()
Dim rs, fso, txtfile
' Prepare the text file

Set txtfile = fso.CreateTextFile("CellValues.txt", True)
' Request the recordset for the table

Set rs = TableDoc.Table1.CellValues
' Write a heading to the text file
txtfile.WriteLine("Table1")
' Call the WriteRecordSet subroutine
WriteRecordSet(rs, txtfile)
txtfile.Close()
Sub WriteRecordSet(rs, txtfile)

Dim MyField
' Make sure we are at the first record

rs.MoveFirst()
' Loop through records until the end of file reached

While Not rs.EOF
For Each MyField In rs.Fields
'Write out field value
txtfile.Write(MyField.Value)
'Write out the tab character
txtfile.Write(mr.Tab)
Next
1267
Base Professional
' Move to next line in output file

txtfile.WriteLine()
' Get next record
rs.MoveNext()
End While
End Sub
Here is the table:
Figure 1-319
Table of age by gender showing counts cell contents
And here are the contents of the text file:
R1:1 602 339 263

R2:1 169 81 88
R3:1 433 258 175
R4:1 - - -
Each line in the text file corresponds to a record in the recordset and each record in the recordset
corresponds to an element on the side axis.
The first field in each record contains the row ID in the form Rn:L, where n is the index of the
corresponding element on the side axis and L is the layer number. When the table has one layer,
the layer number is always 1 (because it is a one-based index, unlike the zero-based index that is
used as the Layer parameter for the Table.CellValues property). The subsequent fields in the record
correspond to the elements on the top axis. In this example there is one field for each element on
the top axis because the table has one set of cell contents only, counts.
If we were to add a second set of cell contents to the table, there would be two fields for each
element on the top axis. For example, here is the output for a table that is exactly the same as the
previous one except that it shows column percentages with two decimal places as well as counts:
R1:1 602 100.00% 339 100.00% 263 100.00%

R2:1 169 28.07% 81 23.89% 88 33.46%
R3:1 433 71.93% 258 76.11% 175 66.54%
R4:1 - - - - - -
1268
Chapter 1
Notice that there are the same number of records in the recordset, but now each record has two
fields for each element on the top axis, and each field represents one of the items of cell contents
for the corresponding table cell. If we added a third set of cell contents, there would be three fields
in each record for each element on the top axis, etc.
You can use the ADO recordset with the axis and element labels to create complete tables. For an
example of doing this, see the CellValuesAndLabels.mrs sample script file.
Here is its output:

Top axis: Gender of respondent
Side axis: Holds biology qualification
Base Male Female
Base 602 339 263

Yes 169 81 88
No 433 258 175
Not answered - - -
This script uses the ElementHeadings collection to retrieve the labels of the elements in the
table and write them to the text file along with the data from the table. Using ElementHeadings
ensures that the order of the elements reflects that in the displayed table, taking into account any
sorting or hidden elements. For further information on using the ElementHeadings collection, see
Working with Elements and Element Headings.
Requirements
Statistical Formulae
This topic provides the formulae used by to calculate the various types of cell contents. The
topic is divided into two subsections. The first provides the formulae used to calculate the cell
contents that are not dependent on a numeric variable and the second provides the formulae for
the summary statistics of numeric variables.
Notation
The following table shows the notation used in this topic except where stated otherwise.
Notation Description
Sum of cell weights for cases in cell (i, j).
Number of rows contributing to the test
Number of columns contributing to the test

1269
Base Professional
The jth column subtotal:
The ith row subtotal:
The grand total:
The following table provides the formulae used by to calculate the cell contents that are not
dependent on a numeric variable.
Item Formula
Count
Column Percentage
Row Percentage
Total Percentage
Indice
Expected Count
Residual
Summary Statistics of Numeric Variables
Notation
1270
Chapter 1
The following table shows additional notation used in the remainder of this topic except where
stated otherwise.
Value of the variable for case i.
Weight for case i
Number of cases
Sum of the weights for the first i cases
Mean for the first i cases
The following table provides the formulae used by to calculate the cell contents that are dependent
on a numeric variable, with the exception of percentiles, the formula for which is shown below
the table.
Item Formula
Mean
Sum
Minimum
Maximum
Range
Mode Value of Xj that has the largest observed frequency.

If there are several modes, the first one encountered
in the data is selected.
Median The median is the 50th percentile. See Percentile,
which is shown below.
Variance
1271
Base Professional
Item Formula
Standard Deviation
Standard Error
Percentile
uses one method for computation of percentiles. Let
where p is the requested percentile divided by 100, and k1 and k2 satisfy
Then
Let x be the pth percentile; the definition is as follows:
Hierarchical Data
This section covers using scripts to create tables with hierarchical data. This is a complex subject
and this section assumes a basic understanding of how the IBM® SPSS® Data Collection Data
Model handles hierarchical data. Before you start working through this section, you may therefore
want to spend time studying the following topics, which will help you gain that understanding:
An introduction to the various types of hierarchical constructions that are typically found in
market research questionnaires and how the Data Model represents the response data.
1272
Chapter 1
A more detailed overview of how these survey constructions map to objects in the Metadata
Model (MDM) and the columns and tables that store the case data.
Tutorial-style exercises that are designed to help you understand how the Data Model
represents hierarchical response data in the flat VDATA virtual table and hierarchical HDATA
virtual tables.
Which View of the Data is Used?
uses the IBM® SPSS® Data Collection Data Model to access the underlying data, which can
be, for example, a .sav file, a IBM® SPSS® Quanvert™ database, a relational IBM® SPSS®
Data Collection database storing IBM® SPSS® Data Collection Interviewer Server data, IBM®
SPSS® Quancept™ data stored in .qdi and .drs files, etc.
The Data Model handles case data (which stores the actual responses) and metadata (which
describes the case data and stores the question and category texts, etc.) separately. requires
a metadata source as well as a case data source. The metadata source can be a Data Collection
Metadata Document (.mdd) file or any other metadata format for which a suitable read-enabled
Metadata Source Component (MDSC) is available. The case data can be in any format for which a
suitable read-enabled Case Data Source Component (CDSC) is available.
The Data Model has two ways of representing the case data:
Using a hierarchical view (sometimes called HDATA).
Using a flat view (sometimes called VDATA).
Using the Hierarchical View
By default, uses the hierarchical view when the CDSC you are using to access the case data
supports the hierarchical view. From version 3.5, it also uses the hierarchical view for DSCs that
do not support the hierarchical view, provided that a metadata file is available. This means that
you can tabulate data from the following CDSCs using the hierarchical view of the data:
In2Data DSC
QDI/DRS DSC
IBM® SPSS® Quantum™ DSC
Quanvert DSC
Relational MR CDSC (RDB DSC 2)
SPSS Statistics SAV DSC
IBM® SPSS® Surveycraft™ DSC
XML CDSC
When the hierarchical view is being used:

You can create grid tables.
You can use variables that are nested inside a loop or grid in your tables.
You can choose the level at which your tables are to be populated.
1273
Base Professional
Using the Flat View
IBM® SPSS® Data Collection Base Professional automatically uses the flat view when the CDSC
you are using to access the case data does not support the hierarchical view and no metadata is
available.
When the flat view is being used:

You cannot create grid tables or use the variables that are nested inside a loop or grid in your
tables. However, you can use a slice of a grid or loop in a table.
There is only one level, and so you do not need to choose the level at which your tables
are to be populated.
The Table Object Model can handle both views of the case data. When you load a data set using a
CDSC that supports the HDATA view, the Table Object Model automatically uses the HDATA
view and when you load a data set using a CDSC that does not support HDATA, it automatically
uses the flat VDATA view.
Provided the CDSC supports both views of the data, you can change the view using the
DataSet.View property. You must do this at the beginning of your script, before you start defining
your tables, axes, filters, and cell contents.
For example, by default the HDATA view is used for XML data sets. However, you could change
this to the VDATA view as follows:

TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\museum.mdd", _
, "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\museum.xml", _
"mrXmlDsc")
TableDoc.DataSet.View = 0 ' 0 = dvVdata = VDATA view
To return to the HDATA view:
TableDoc.DataSet.View = 1 ' 1 = dvHdata = HDATA view
However, it is generally preferable to use the HDATA view, if possible, because it enables you to
create grid tables and provides better support for tabulating data collected using loops.
Using the Flat (VDATA) View
Sample Script File: QuanceptTables.mrs
This example script is based on the Museum sample IBM® SPSS® Quancept™ data set. See
Running the Sample Table Scripts for information on running the example scripts.
When you use the flat (VDATA) view of the data, any hierarchical data is “flattened” and a separate
variable stores the responses to each question in each possible iteration. When you use the flat
view of the data, data in unbounded loops is unavailable because it cannot be flattened.
1274
Chapter 1
Note: The flat view of the data is always used when the case data is stored in an IBM® SPSS®
Statistics (.sav) or Quancept (.drs) file, regardless of whether you are using an .mdd file or reading
the metadata directly from the .sav or .qdi file.
When you use the flat view of the data, you specify a variable for use in an axis or filter using the
full name of the variable instance (VariableInstance object). You can use in an axis variables of
the following data types only:
Categorical
Long
Double
Date
Boolean
Text
For all variables apart from categorical variables that have the properties defined below, at least
one element must be defined, either in the Variable.AxisExpression MDM property or in the
axis specification.
When you tabulate a categorical variable, the axis will contain all of the elements of the variable,
unless an axis expression exists in the metadata or an element list is explicitly specified in the
axis specification. When the axis is based on the variable’s elements, the variable must have
the properties shown in the following table.
Variable Instance Property Valid Setting for Use in an Axis
DataType mtCategorical
SourceType sDataField
sExpression
sExpressions
Elements Must contain at least one Element object
The MDM Document.Variables collection provides a flat list of the variable instances that are
available when you are using the flat (VDATA) view of the data. In the IBM® SPSS® Data
Collection Base Professional Metadata Viewer, you can view the variable instances in the
Document.Variables collection. You do this by double-clicking the Document’s Variables folder.
This opens a list of the VariableInstance objects. Each object is shown with an icon that indicates
its type.
1275
Base Professional
Figure 1-320
Variables folder in the IBM SPSS Data Collection Base Professional Metadata Viewer
You can use the Properties pane to copy the full name of a VariableInstance object in order to
paste it into your script.
Figure 1-321
Properties Pane in the Metadata Viewer
This icon indicates that there is an

Axis Expresion stored in the
metadata for the variable.
Select a VariableInstance in the

list to display its full name in
the Properties pane.
To copy the full name into your

script: select the full name text here,
then right-click and from the shortcut
menu, choose Copy.
Then move the cursor back into the Edit

window and click the Paste tool.
For more information, see the topic Using the Metadata Viewer on p. 28.
1276
Chapter 1
You can access the MDM Document in your script using the DataSet.MDMDocument property.
The following example loops through the variable instances in the Document.Variables collection
and creates a frequency table for all categorical variables that have at least one element, and are
not helper variables or part of a compound, block, grid, or loop:
Dim MyVariableInstance, MyCounter, MyTableName, MyTableSpec, MyTableDescription
MyCounter = 0
For Each MyVariableInstance in TableDoc.DataSet.MDMDocument.Variables

If MyVariableInstance.DataType = mr.Categorical _
And MyVariableInstance.Elements.Elements.Count > 0 _
And BitAnd(MyVariableInstance.UsageType, 31) = 0 Then ' Exclude grid, loop and helper variables
MyTableSpec = MyVariableInstance.FullName
MyTableDescription = MyVariableInstance.FullName
End If
Next
Using the Hierarchical (HDATA) View
When you use the hierarchical (HDATA) view of the data, you can create grid tables, tabulate data
in unbounded loops (such as IBM® SPSS® Quanvert™ levels data), and choose the population
level for your tables.
Note: The hierarchical view of the data is used by default when the case data is stored in a
Quanvert database, an RDB database (provided you are using RDB DSC 2), or in an XML file.
When you use the hierarchical view of the data, the case data schema is defined by the MDM
Document.Fields collection and the Document.Variables collection provides a flat list of the
columns at the top (HDATA) level only. You specify a variable for use in an axis or filter using the
full name of the variable (Variable object). (For variables at the top level, the full names are the
same as the full names of the variable instances.)
Just as with the flat view, you can use in an axis variables of the following data types:
Categorical
Long
Double
Date
Boolean
Text
For all these variable types apart from categorical variables that have the properties defined
below, at least one element must be defined, either in the Variable.AxisExpression MDM property
or in the axis specification.
1277
Base Professional
When you tabulate a categorical variable, the axis will contain all of the elements of the variable,
unless an axis expression exists in the metadata or an element list is explicitly specified in the
axis specification. When the axis is based on the variable’s elements, the variable must have
the properties shown in the following table.
Variable Property Valid Setting for Use in an Axis
DataType mtCategorical
SourceType sDataField
sExpression
sExpressions
Elements Must contain at least one Element object
For a numeric loop, the MDM automatically creates elements if the loop is “bounded”, that is, if it
has MinValue and MaxValue values specified in the metadata.
When you are using the hierarchical view, you can also use in your axes grids and loops (Grid
and Array objects), provided they have at least one iteration. The following table shows the valid
values of the relevant properties of the MDM Array object. (A Grid object can be considered
a special case of an Array object.)
Array Property Valid Setting for Use in an Axis
Elements Must contain at least one Element object. For
numeric loops (Array objects of type itNumeric or
itNumericRanges) the MDM dynamically creates
an Element object for each iteration.
For more information, see the topic Grid Tables on p. 1290.
Note: Compounds and blocks (Class objects) are used to group questions for display or
convenience only and do not define a true hierarchical structure. Therefore, you cannot use a
Compound or Class object directly in an axis. However, you can include the variables (and
any Grid or Array objects) that are nested within a Compound or Class object in an axis in the
normal way.
The MDM Document.Fields collection is a hierarchical list of the structural objects in the
metadata. You can view the objects in the Document.Fields collection in a hierarchical tree view in
the IBM® SPSS® Data Collection Base Professional Metadata Viewer, by double-clicking the
Document’s Fields folder. Each object is shown with an icon that indicates its type.
1278
Chapter 1
Figure 1-322
Fields collection in the Metadata Viewer
Loops, grids, compounds, and blocks (Class objects) also have a Fields collection that list their
nested objects. Each one of these Fields collections is also visible in the Metadata Viewer as a
Fields folder. This means that you can drill down through the objects. For example, by opening a
loop’s Fields folder, you can explore the variables that are nested inside the loop.
Figure 1-323
Properties pane in the Metadata Viewer
1279
Base Professional
You can use the Properties pane to view a variable’s axis expression and the Type property of
a loop or grid in order to see whether it is expanded or not. And you can copy the full name
of a variable and then paste it into your script. For more information, see the topic Using the
Metadata Viewer on p. 28.
Understanding Population Levels
Sample Script File: HierarchicalData.mrs
This example script is based on the Household sample data set. See Running the Sample Table
When you use the hierarchical view of the data, you need to understand the significance of
populating tables at the various hierarchical levels. To illustrate this we will use the , which
represents the data collected using the following fictitious survey:
Household questions. Respondents are asked a number of questions about their household as a
whole, such as address, age of the building, and number of rooms.
Person questions. Respondents are then asked a number of questions about each person in the
household, such as the person’s name, age, gender, and occupation, and a grid question that
asks the number of days he or she watches various TV channels.
Overseas trip questions. Each person is also asked a number of questions about each overseas
trip that he or she has taken in the previous year (if any), such as the purpose of the trip,
number of days he or she was away from home, and countries that were visited.
Vehicle questions. Finally, respondents are asked a number of questions about each vehicle
that belongs to their household (if any), such as the vehicle’s type, color, and annual mileage,
and a grid question that asks the respondent to rate the vehicle’s features.
Loops called person, trip, and vehicle are used to ask the person, overseas trip, and vehicle
questions, respectively. The loops are iterated (and therefore the questions are asked) as many
times as necessary. For example, in a household of three people, the person loop will be iterated
three times, whereas in a single-person household it will be iterated once. In a household that
has no cars, bikes, or other vehicles, the vehicle questions will not be asked at all and the vehicle
loop will have no iterations.
In the IBM® SPSS® Quanvert™ database, each of the loops corresponds to an Array object of
type mlLevel in the metadata and a child table (called a level) in the case data. (In the XML data
set, the person Array object is of type mlExpand.) Each record in a child table is considered a
case at that level and corresponds to one iteration of its corresponding loop. This means that the
three-person household will have three records in the person child table and this corresponds
to three person-level cases.
The structure of the levels corresponds to the structure of the loops. This means that because the
trip loop is nested within the person loop, the trip level is a child of the person level. The two
grids are also represented in the case data as levels, each nested within its parent level. The
following diagram shows the levels structure.
1280
Chapter 1
Figure 1-324
Structure of levels
When you are using a hierarchical view of the data, you can define the level at which each table is
to be populated. The level that you choose affects the figures that are shown in the cells of the
table. When you populate a table at the top (HDATA) level, each case corresponds to a household
and therefore the counts show numbers of households; when you populate the table at the person
level, each case corresponds to a person and therefore the counts show numbers of people; when
you populate a table at the trip level, each case is an overseas trip and the counts show numbers of
trips, etc. To illustrate this, let’s look at some tables.
1. Top-level variables tabulated at the top level. This first table crosstabulates two top-level variables
(housetype and region) and is populated at the top (HDATA) level. The counts in the cells refer to
households because in this survey the top-level questions refer to households. Notice that the cell
in the top left corner of the table shows that there are 10 households in the sample.
Figure 1-325
Top-level variables tabulated at the top level
2. Person-level variables tabulated at the person level. The next table crosstabulates two
person-level variables (occupation and gender) and is populated at the person level. Each cell
shows the number of people of a given occupation and gender. Looking at the top left cell, we
can see that there are 25 cases at the person level, or, to put it another way, there are 25 people
in the sample.
1281
Base Professional
Figure 1-326
Person-level variables tabulated at the person level
3. Person-level variables tabulated at the top level. The next table crosstabulates the same two
person-level variables, but this time the table is populated at the top (HDATA) level. This means
that instead of showing the number of people of a given occupation and gender, each cell now
shows the number of households that contain people of the given occupation and gender. Looking
at the top left cell, we can see that the base for the table is the same as in the first table shown
above. This is what you would expect because both tables are counting the number of households
and are unfiltered, and every household contains at least one person.
Figure 1-327
Person-level variables tabulated at the top level
4. Trip-level variables tabulated at the trip level. The next table crosstabulates two trip-level
variables (country and purpose) and is populated at the trip level. This means that each cell
shows the number of overseas trips that involved a particular country and purpose. Looking at
the top left cell, we can see that there were a total of 24 overseas trips (or to put it another way,
there are 24 cases at the trip level).
1282
Chapter 1
Figure 1-328
Trip-level variables tabulated at the Trip level
5. Trip-level variables tabulated at the person level. The next table crosstabulates the same two
trip-level variables, but this time the table is populated at the person level. This means that instead
of showing the number of overseas trips that involved a particular country and purpose, each cell
now shows the number of people that took trips that involved a particular country and purpose.
Looking at the top left cell, we can see that the base for the table is 12. This is less than the base in
the second table shown above (which tabulates two person-level variables at the person level)
because some people did not take an overseas trip and therefore there are no records (cases) at the
trip level for those people.
Figure 1-329
Trip-level variables tabulated at the Person level
1283
Base Professional
6. Variables from different levels tabulated at the default level. You can create tables that use
variables from more than one level. The next table crosstabulates a person-level variable (gender)
with a trip-level variable (purpose). When you use variables from parent and child levels like this,
the population level defaults to the level of the lowest-level variable, which is the trip level in
this example. This means that each cell in this table shows the number of overseas trips for a
particular purpose and the gender of the person who took them. If we look at the Base column, we
can see that of the 24 overseas trips that were taken, 11 were taken by males and 13 by females.
Note that the base for the table (24) is the same as the base in the fourth table shown above (which
tabulates two trip-level variables at the trip level).
Figure 1-330
Variables from different levels tabulated at the default level
7. Variables from different levels tabulated at a higher level. The next table crosstabulates the same
person-level variable (gender) with the same trip-level variable (purpose). However, this time the
table is populated at the person level. This means that instead of showing the number of overseas
trips, each cell now shows the number of people of each gender who took trips that involved a
particular purpose. If we look at the Base column, we can see that of the 12 people who took
overseas trips, 6 were males and 6 were females.
The top left cell shows that the base for the table is 12, which corresponds with the base in the fifth
table shown above, which tabulates two trip-level variables at the person level. Note that the base
counts every person who took one or more overseas trips. People who did not take an overseas
trip are not counted in the base because the base calculation considers empty levels to be Null.
Figure 1-331
Variables from different levels tabulated at a higher level
1284
Chapter 1
8. Tabulating variables from different “parallel” levels. The next table crosstabulates a variable from
the vehicle level (vehicletype) with a person-level variable (gender). If you scroll back to the
diagram that shows the levels structure, you will see that the person and vehicle levels are parallel
to each other (on different branches of the tree). This means that the data at the two levels is not
directly related to each other. It would therefore make no sense to populate the table at either the
person or vehicle level and therefore this is not allowed. However, you can populate the table at a
higher level that is an ancestor of both of them. In this example, the only level that is an ancestor of
both the person and vehicle levels is the top (HDATA) level. Each cell therefore shows the number
of households that have the various types of vehicles and that contain people of the given gender.
Figure 1-332
Tabulating variables from different “parallel” levels
9. Tabulating variables from higher levels at a lower level. You can also tabulate higher level
variables at a lower level, provided that the variables are on the same branch of the structure and
are not on parallel branches. The next table crosstabulates two top-level variables (housetype and
region) as for table 1, but this time is populated at the person level. The counts in the cells refer to
people rather than households. Notice that the cell in the top left corner of the table shows that
there are 25 people in the sample.
Figure 1-333
Tabulating variables from higher levels at a lower level
10. Showing summary statistics of a numeric variable in the cell contents. In the next table, the cell
contents show not only the counts, but also the sum and mean summary statistics of the DaysAway
numeric variable. This is a trip-level variable that stores the length of the trip in days. The sum
values show the total number of days away and because the table is populated at the trip level, the
mean values show the mean number of days per trip.
1285
Base Professional
Figure 1-334
Summary statistics of a numeric variable in the cell contents, populated at Trip level
Let’s look at the three figures in the top left cell of the table. The first figure is 24, which
corresponds with the base in the fourth table shown above, which tabulates two trip-level variables
at the trip level. This figure shows the total number of overseas trips that were taken. The next
figure is 320, which is the total number of days for all the trips. The final figure is the mean, which
shows the average number of days per trip.
If we now populate the table at the person level, the sum values will stay the same but the mean
values will show the average number of days per person instead of per trip. Here is the table
populated at the person level.
1286
Chapter 1
Figure 1-335
Summary statistics of a numeric variable in the cell contents, populated at Person level
Let’s look at the three figures in the top left cell of this new table. The first figure is 12, which
corresponds with the base in the seventh table shown above, which tabulates the same variables
at the person level. This figure shows the total number of people who have taken at least one
overseas trip. The next figure is 320, which is the total number of days for all the trips. Notice that
this figure is the same as when we populated the table at the trip level. However, the mean value is
now 27, because it now shows the average number of days away per person instead of per trip.
Using weighting variables with hierarchical data
When you use weighting variables, the level of the weighting variable restricts the levels at which
you can populate the table. For more information, see the topic Weighting on p. 1252.
Setting the Population Level
Sample Script File: HierarchicalData.mrs
In Understanding Population Levels, we looked at the implication of populating tables at different

levels in a hierarchical data set. This topic explains more about the default population level, and
how to change the population level and get a list of the valid population levels.
1287
Base Professional
Setting the level. You set the population level for a table by setting the Table.Level property to the
name of the required level. The name of the top level is always HDATA and the names of the lower
levels are the same as the full names of the corresponding loops (Array objects). For example:
TableDoc.Table1.Level = "person"
TableDoc.Table2.Level = "person[..].trip"
If you specify a level that is not valid for the table, you will get an error. However, you can check
the available levels as shown below.
Note: You can show the population level as an annotation on the table. For example, the following
code creates a right header annotation that shows the population level:
TableDoc.Default.Annotations[3].Specification = "Population level: {Level}"
Note that the {Level} macro always inserts the text “Top” for the top level and the {Level \l} macro
is shown on the table by default. For more information, see the topic Annotations on p. 1432.
Default level. This is the level at which a table is populated when you do not explicitly specify the
population level. The default level depends on the levels of all of the variables that are in the table
(including any numeric variables included in the cell contents) and the level of any filters:
If the filters and all of the variables are at the same level, the default level is the level of the
variables.
If all of the filters and variables are at levels that are direct descendents of each other, the
default level is the level of the lowest-level filter or variable.
If some or all of the filters or variables are at parallel levels (levels that are not direct
descendents of each other), the default level is the first common parent level. (For an
example that illustrates this, see 8. Tabulating variables from different “parallel” levels in
Understanding Population Levels.)
Note that the default level is slightly different when a grid or loop slice is being used. For more
information, see the topic Grid and Loop Slices on p. 1299.
To illustrate this, let’s look at the code used to create the tables in Understanding Population
Levels:
.AddNew("Table1", "housetype * region", "Type of accommodation by Region - Household level")
.AddNew("Table2", "person.occupation * person.gender", "Occupation by Gender - Person level")
.AddNew("Table3", "person.occupation * person.gender", "Occupation by Gender - Household level")
.Table3.Level = "HDATA"
.AddNew("Table4", "person.trip.country * person.trip.purpose", "Countries visited by Purpose of trip - Trip level")
.AddNew("Table5", "person.trip.country * person.trip.purpose", "Countries visited by Purpose of trip - Person level")
.Table5.Level = "person"
.AddNew("Table6", "person.gender * person.trip.purpose", "Gender by Purpose of overseas trip - Trip level")
.AddNew("Table7", "person.gender * person.trip.purpose", "Gender by Purpose of overseas trip - Person level")
.Table7.Level = "person"
.AddNew("Table8", "vehicle.vehicletype * person.gender", "Vehicle type by person's gender")
.AddNew("Table9", "housetype * region", "Type of accommodation by Region - Person level")
1288
Chapter 1
.Table9.Level = "Person"
.AddNew("Table10", "Person.Trip.Purpose * Person.Gender", "Purpose of trip by Gender - Trip level")

.Table10.CellItems.AddNew(5, 0, "Person.Trip.DaysAway") ' Sum
.Table10.CellItems.AddNew(4, 0, "Person.Trip.DaysAway") ' Mean
.AddNew("Table11", "Person.Trip.Purpose * Person.Gender", "Purpose of trip by Gender - Person level")

.Table11.CellItems.AddNew(5, 0, "Person.Trip.DaysAway") ' Sum
.Table11.CellItems.AddNew(4, 0, "Person.Trip.DaysAway") ' Mean
.Table11.Level = "Person"
End With
Notice that the population level has been set for tables 3, 5, 7, 9, and 11. For the other tables, the
default level has been used:
Table 1 has two top-level variables only, so the default level is the top (HDATA) level.
Table 2 has two person-level variables only, so the default level is the person level.
Table 4 has two trip-level variables only, so the default level is the trip level.
Tables 6 and 9 have one person-level variable and one trip-level variable. The trip level is a
child of the person level, so the default level is the trip level.
Table 8 has one vehicle-level variable and one person-level variable. The vehicle level and the
person level are on different branches of the hierarchy, so the default level is the top (HDATA)
level, which is the only common ancestor level.
Available Levels. You can check which levels are valid for a table using the Table.AvailableLevels
property. The following example writes the valid levels to a text file:
Dim fso, txtfile
Set txtfile = fso.CreateTextFile("HierarchicalData.txt", True)
Dim MyTable
For Each MyTable in TableDoc.Tables

ListAvailableLevels(txtfile, MyTable.AvailableLevels, MyTable.Name)
Next
Sub ListAvailableLevels(TextFile, AvailableLevels, TableName)

Dim x
TextFile.WriteLine()
TextFile.WriteLine(TableName)
For x = LBound(AvailableLevels) To UBound(AvailableLevels)
TextFile.WriteLine(AvailableLevels[x])
Next
End Sub
Here is the output for our example tables:

Table1
HDATA
person
1289
Base Professional
person[..].trip
person[..].tvdays
vehicle
vehicle[..].rating
Table2
HDATA
person
person[..].trip
person[..].tvdays
Table3
HDATA
person
person[..].trip
person[..].tvdays
Table4
HDATA
person
person[..].trip
Table5
HDATA
person
person[..].trip
Table6
HDATA
person
person[..].trip
Table7
HDATA
person
person[..].trip
Table8
HDATA
Table9
HDATA
person
person[..].trip
person[..].tvdays
vehicle
vehicle[..].rating
Table10
HDATA
person
person[..].trip
1290
Chapter 1
Table11
HDATA
person
person[..].trip
Grid Tables
Sample Script File: GridTables.mrs
Creating a Grid Table shows an example of using the Tables.AddNewGrid method to create a grid
table. This topic provides more information about grid tables and how they work.
The Household sample has a grid question at the vehicle level that asks respondents to select
a rating category for some of the vehicle’s features. The full name of the grid question is
vehicle[..].rating, which we can simplify to vehicle.rating in the specification. We will use this
grid question as an example in this topic.
Grid questions can be considered categorical loops, which are loops in which a category list
defines the iterations and the iterations are presented simultaneously in a grid-like format. The
category list that defines the iterations is sometimes referred to as the controlling category
list. One or more variables inside the loop define the question(s) that are to be asked for each
iteration. The vehicle.rating grid contains one variable (called Column), which has a category
list that defines the rating categories.
1291
Base Professional
The following diagram shows a simplified representation of the internal structure of the loop in
the metadata and how it relates to the grid question when it is presented in paper questionnaire:
Figure 1-336
Vehicle.rating grid variable in the metadata and in the questionnaire
In this diagram, each iteration of the loop forms a row of the grid question and we can see that the
iterations correspond to the categories in the loop’s controlling category list. The columns of the
grid question are formed from the categories of the question inside the loop.
First we will use the Tables.AddNewGrid method to create a grid table for this grid question
using the default options:
TableDoc.Tables.AddNewGrid("Table1", "vehicle.rating", , "Rating of vehicle features")

1292
Chapter 1
Notice that we have used the simplified form of the loop’s full name. Here is the table:
Figure 1-337
Table of vehicle.rating grid
In this table, the iterations are displayed as columns because this is how the loop’s default
orientation is defined in the metadata. We can override this by setting the third parameter of the
Tables.AddNewGrid method to 1. This is equivalent to the DisplayOrientation.doRow constant,
which specifies that the iterations are to be displayed as rows:
TableDoc.Tables.AddNewGrid("Table2", "vehicle.rating", 1, "Rating of vehicle features")
Here is the table with the iterations forming the rows:

Figure 1-338
Table of vehicle.rating grid with iterations as rows
1293
Base Professional
Notice that an annotation has been used to display the table specification under each table. This
shows the specification that you would need to use if you were to create the tables using the
Tables.AddNew method. This means we can create similar tables (see The Base in Grid Tables
for details of how the base differs) like this:
TableDoc.Tables.AddNew("Table1", "vehicle.rating.column * vehicle.rating", "Rating of vehicle features")

TableDoc.Tables.AddNew("Table2", "vehicle.rating * vehicle.rating.column", "Rating of vehicle features")
When you use the Tables.AddNew method to create a grid table, there is no parameter to define the
orientation, because the orientation is implied in the specification. The iterations are displayed in
rows or columns according to whether you specify the loop as the side or top axis. In Table1, the
loop is specified as the top axis and so the iterations will form the columns of the table. In Table2,
the loop is specified as the side axis and so the iterations will form the rows of the table.
In this example we have also shortened the full name of the variable inside the grid. This is
optional. It would work just as well if we specified the full name as vehicle[..].rating[..].column.
The vehicle.rating loop contains only the Column variable. However, some loops contain more
than one variable. When you use the Tables.AddNewGrid method with a loop that contains more
than one variable, all of the categorical variables that are contained in the loop are concatenated
together in the grid table. Any non-categorical variables that are inside the loop are ignored.
This means that if you don’t want to include all of the variables in the grid table, you need to use the
Tables.AddNew method and specify the individual variables you do want to include. For example:
TableDoc.Tables.AddNew("MyTable", "MyLoop * MyLoop.Variable1 + MyLoop.Variable3")
You can create grid tables from any grid or loop that has at least one iteration. In MDM terms, this
is any Grid or Array object that has at least one Element object. (The MDM creates the Element
objects for a numeric loop automatically, provided that the loop is “bounded”; that is, that it has
MinValue and MaxValue values specified in the metadata.)
However, creating grid tables from numeric loops is less common than for categorical loops.
This is because generally the iterations in numeric loops don’t have a fixed meaning as they do
in categorical loops. For example, consider a numeric loop that asks questions about journeys
to the supermarket in which each iteration represents one of the journeys. Creating a grid table
to tabulate the questions in the loop by the iteration (which represents whether it was the first,
second, or third journey, etc. in the week) generally makes little sense.
Restrictions. You cannot specify a subset of the iterations to be included.
Derived Grid Tables
Sample Script File: DerivedGridTables.mrs
1294
Chapter 1
Where a survey contains a number of different questions that share the same response list (for
example, separate satisfaction questions across a range of different services), the results are often
reported as a single grid. In this scenario, data is collected as separate questions instead of in a
loop or grid, but the data still needs to be tabulated as if it is a grid. This issue is especially
relevant when the data to be tabulated comes from outside applications where loop constructs are
not available (for example, IBM® SPSS® Statistics .sav files).
When tabulating, it is convenient to combine identical shared lists as a single grid question. First
we will use the TableDoc.DataSet.Variables.AddNewVariable method to create a derived grid for
variables whose categories are “Yes”, “No”, and “Not_answered”:
TableDoc.DataSet.Variables.AddNewGrid("before, biology, education, resident", _

"DerivedGrid", _
"Derived grid", _
"Column")
Next we create the derived variables that references and combines the derived grid slice variables:
' Create a derived variable to reference the order grid's first slice
TableDoc.DataSet.Variables.AddNewVariable("!
orderFirst "grid order first slice"
categorical[0..16]
expression("order[{first}].column");
!")
' Create a derived variable to reference the order grid's second slice
TableDoc.DataSet.Variables.AddNewVariable("!
orderSecond "grid order second slice"
categorical[0..16]
expression("order[{second}].column");
!")
' Create a derived grid that combines the derived grid slice variables
TableDoc.DataSet.Variables.AddNewGrid("orderFirst, orderSecond", _
"NewOrder", _
"New order", _
"New order column")
Table 1 demonstrates the grouping of various columns using a derived grid.
.AddNew("Table1", "DerivedGrid * DerivedGrid[].Column", _

"Grid table that groups before, biology, education, and resident together using a derived grid")
1295
Base Professional
Figure 1-339
Columns grouped via a derived grid
Table 2 provides an example of grid table with a modified column axis expression.
.AddNew("Table2", "DerivedGrid * DerivedGrid[].Column{base(), Yes, No, Not_answered [IsHidden=true]}", _

"Grid table with a modified column axis expression")
Figure 1-340
Grid table with a modified column axis expression
Table 3 provides an example of grid table with a modified axis expression.
.AddNew("Table3", "!
DerivedGrid{
before,
before_male 'before - male' expression('levelid = {before} and ^.gender.ContainsAny({male})'),
before_female 'before - female' expression('levelid = {before} and ^.gender.ContainsAny({female})'),
biology,
biology_male 'biology - male' expression('levelid = {biology} and ^.gender.ContainsAny({male})'),
biology_female 'biology - female' expression('levelid = {biology} and ^.gender.ContainsAny({female})')
}
* DerivedGrid[].Column{
base(), Yes, No, Not_answered [IsHidden=True]
}
!", _
"Grid table with a modified axis expression")
1296
Chapter 1
Figure 1-341
Grid table with a modified axis expression
Table 4 provides an example of grid table whose elements are derived from another grid.
NewOrder[].column
*
NewOrder{
orderFirst,
orderSecond,
all 'all' combine({orderFirst, orderSecond})
}
!", _
"Grid table whose elements are derived from another grid")
1297
Base Professional
Figure 1-342
Grid table whose elements are derived from another grid
Rules and restrictions
The following rules and restrictions apply when selecting variables to create derived grids:
The selected variables must be of the same type.
If categorical variables are selected, the variables must share the same or similar category lists.
The selected variables must all be at the same level. The new grid variable will be created at
the level of the selected variables.
The maximum MaxValue from the selected variables will be used as the MaxValue for the
nested question in the grid.
The minimum MinValue from the selected variables will be used as the MinValue for the
nested question in the grid.
Axis expressions on individual questions will be ignored in the creation of the grid.
Given that the iteration category name will be based on the name of the question, grid slices or
variables in classes or compounds cannot be used in derived grids.
The Base in Grid Tables
Sample Script File: GridTables.mrs
1298
Chapter 1
If you look at the grid tables shown in the Grid Tables topic, you will notice that unlike a standard
table, there is either a base row or column, but not both. Specifically, the base is shown when
the rows or columns are created from the variable inside the grid and not when they are formed
from the iterations. The base is calculated in both the rows and columns, but by default it is not
displayed for the iterations. However, you can show this base if you want to. (See below for
details of how to do this.)
Here is a table that is populated at the default level (the level above the grid, in this case, vehicle)
that shows the base on both sides of the table:
Figure 1-343
Table populated at default (vehicle) level
When this grid table is populated at the vehicle level, each cell shows the number of vehicles for
which the given category was chosen in that iteration. In other words, in this table each case is a
vehicle. The base therefore shows the total number of vehicles.
Now let’s look at the same table populated at the grid level, which in this example is vehicle.rating
(the annotation displays the level as “Features”, as this is the label for the rating grid):
Figure 1-344
Table populated at grid (rating) level
1299
Base Professional
When the grid table is populated at the level of the grid, each cell shows the number of responses
for the given category in that iteration. This means that in this table each response to the rating
question in each iteration is a case. The base therefore shows the total number of responses in all
of the iterations. However, because each iteration was asked once for each vehicle, the number of
cases in all the other cells is the same as in the table that is populated at the vehicle level.
To show the base on the side of table that represents the iterations, set the Element.IsHidden
property on the Base element to False. For example:
MyTable.Side.SubAxes[0].Elements.Base.IsHidden = False
Setting up bases for grid iterations
The following example demonstrates how to setup bases for grid iterations to include all
respondents. The base expressions includes a higher-level question that forces the base to include
null values:
double[0..100] precision(5) scale(1) axis("{base1 'Base' base() [IsHidden=True], b 'Base' base('^.Respondent_Number is not null') [IsHidden
By default, null iterations are omitted because they can hinder performance. The
EvaluateEmptyIterations custom property must be applied to the grid in the metadata in order to
override the default behavior. For example:
Grid_AE "Attitudinal equity score"

[
EvaluateEmptyIterations = true
]
loop
When EvaluateEmptyIterations custom property is set to true, all iterations, including empty
iterations that do not exist in the CDSC, are returned.
Refer to the Custom Properties in Use in IBM SPSS Data Collection Products topic in the IBM®
SPSS® Data Collection Developer Library for more information regarding custom properties.
Grid and Loop Slices
Sample Script File: GridAndLoopSlices.mrs
Sometimes you may want to tabulate the results of one iteration of a grid or loop against another
variable. Using an iteration of a grid or loop is sometimes called a grid or loop slice. For example,
continuing with the vehicle rating example grid used in the Grid Tables topic, you may want to
1300
Chapter 1
tabulate the rating that respondents gave to the vehicle’s comfort by another variable (such as the
vehicle type). Here is the grid question with the comfort slice highlighted:
Figure 1-345
Rating grid question
In your table specification, you specify a grid or loop slice by including the iteration ID in the full
name of the variable. In this example, the vehicle rating grid is a categorical loop, so the iteration
ID is the category name (enclosed in braces):
TableDoc.Tables.AddNew("Table1", "vehicle[..].vehicletype * " + _
"vehicle[..].rating[{Comfort}].column", _
"Comfort rating for all vehicle types")
Here is the table:

Figure 1-346
Table showing type of vehicle by comfort rating
Notice that in this table, the label for the rating axis says “Comfort rating” rather than just
“Rating”. This could be achieved by changing the label of the axis like this:
TableDoc.Table1.Top.SubAxes["vehicle.rating[{Comfort}].column"].Label = _
"Comfort rating"
In a numeric loop, the iteration ID is a numeric value. For example, suppose you want to tabulate
the gender of the first person in each household by the region. You would specify the iteration ID
as 1 in the full name of the gender variable:
TableDoc.Tables.AddNew("Table2", "person[1].gender * region", _
"Gender of first person in household by Region")
1301
Base Professional
Figure 1-347
Table showing gender by region of main residence
Notice that in this table, the label for the Gender axis is “1: Gender”. When you create an axis
from a slice of a grid or loop, the full label is used instead of the standard label. This makes it
clear which slice is being used, because, by default, the full label is the label prefixed by the
iteration name. However, it is possible to customize the full label by defining text substitutions in
a variable’s label. For example, instead of manually setting the axis label to “Comfort rating” in
the first table, we could achieve the same result by setting the label on the variable to “\+loop2\-
rating” like this:
TableDoc.DataSet.MdmDocument.Fields["vehicle.rating[..].column"].Label = _
"\+loop2\- rating"
This uses the \+loop2\- insertion text, which inserts the label of the current iteration into the
full label.
Grid and loop slices can also be used to create derived variables. For example, the following
creates a derived variable based on person[1].gender:
Set Vars = TableDoc.DataSet.Variables
Vars.AddNewVariable("!
NewGender categorical
expression("person[1].gender");
!")
The variable is tabulated as follows:
.AddNew("Table3", "NewGender * region", _

"Gender of first person in household by Region")
The resulting table is similar to Table2.

1302
Chapter 1
Figure 1-348
Table showing gender by region of main residence
The restrictions on using a grid and loop slice are similar to those for grid tables. The grid or loop
must be defined as expanded and have at least one iteration. In MDM terms, this is any Grid or
Array object of type mlExpand that has at least one Element object. (The MDM creates the
Element objects for an expanded numeric loop automatically.) This means that you cannot create
this table in the IBM® SPSS® Quanvert™ museum sample because the person loop is not defined
as expanded. However, you can create this table in the XML data set, because the person loop is
defined as expanded (the Array object is of type mlExpand) in the Household.mdd file.
The Setting the Population Level topic explains that generally the default population level for a
table is the lowest common ancestor level of all the filters and variables that are included in the
table (including variables used in the cell contents). However, when a table contains a grid slice
at a lower level than any other variable included in the table, the default level will be the level
above the grid slice. This is because, when tabulating a grid slice, it is more common to want to
show the number of cases at the next level up rather than the number of responses at the grid level.
However, you can choose to populate the table at the level of the grid slice if necessary.
Combining Grid Slices
Sample Script File: CombineGridSlices.mrs
Sometimes you may want to combine the results of two or more iterations of a grid or loop to
display combined data for particular categories that you are interested in. For example, in the
Museum sample data set the Order grid shows the order in which visitors to the museum went
to see individual galleries.
1303
Base Professional
Figure 1-349
Table showing Order by Galleries
The following example shows how to combine grid slices to create a new variable showing the
numbers of visitors who went to see a particular gallery as one of their first three visited. This
example is available in a sample mrScriptBasic file called CombineGridSlices.mrs.
The script first displays the basic grid table as shown above:
.AddNew("Table1", "order * order.Column", "Order of galleries visited")
You can also tabulate each iteration of the grid independently. The script tabulates the first three
slices in separate tables:
.AddNew("Table2", "* order[{First}].Column", "The first gallery visited")

.AddNew("Table3", "* order[{Second}].Column", "The second gallery visited")
.AddNew("Table4", "* order[{Third}].Column", "The third gallery visited")
These are the resulting tables:

Figure 1-350
Table with slice showing galleries visited first
Figure 1-351
Table with slice showing galleries visited second
Figure 1-352
Table with slice showing galleries visited third
1304
Chapter 1
The script then defines a function, CombineSlices, which creates a new variable that combines the
results from the First, Second, and Third grid slices:
Function CombineSlices(MdmDoc, VariableName, Iterations, NewSliceName, _
NewSliceLabel)
The parameters of the function specify the metadata document, the existing variable that the new
variable derives from, the grid slices to combine, a name for the new variable, and a label. For
example, to combine the First, Second, and Third grid slices, the parameters have the values:
CombineSlices(MdmDoc, "order.Column", "{First, Second, Third}", _
"order_Initial", "One of first three galleries visited")
The function creates the new order_Initial variable as a derived categorical variable:
Set NewSlice = MdmDoc.CreateVariable(NewSliceName, NewSliceLabel)
NewSlice.DataType = 3 ' 3 = mtCategorical
NewSlice.SourceType = 4 ' 4 = sExpressions
The function then creates elements for the new variable by copying each element in the original
Order.Column variable:
For Each Element In Variable.Elements
Set NewElement = MdmDoc.CloneObject(Element)
NewSlice.Elements.Add(NewElement)
Expr = "SUM(" + VarLevel.FullName + ".(" + _

Variable.Name + " >= {" + NewElement.Name + "}" + _
"AND LevelId.ContainsAny(" + Iterations + "))) > 0"
NewSlice.Expressions.Add(NewElement.Name, Expr)
Next
The function also adds an expression for each element. The expression determines whether or
not to include a respondent in the count for that element.
For Each Element In Variable.Elements
Set NewElement = MdmDoc.CloneObject(Element)
NewSlice.Elements.Add(NewElement)
Expr = "SUM(" + VarLevel.FullName + ".(" + _

Variable.Name + " >= {" + NewElement.Name + "}" + _
"AND LevelId.ContainsAny(" + Iterations + "))) > 0"
NewSlice.Expressions.Add(NewElement.Name, Expr)
Next
For example, in the case of the Dinosaurs element, the expression would be:
"SUM(Order.(Column >= {Dinosaurs} AND
LevelId.ContainsAny({First, Second, Third}))) > 0"
Finally, the new variable is added as a field in the metadata:

MdmDoc.Fields.Add(NewSlice)
1305
Base Professional
For each iteration of the Order loop the central part of the expression determines if that iteration
was First, Second, or Third and if the response was Dinosaurs. The SUM() > 0 test checks to see if
at least one iteration of the loop meets this condition.
The following table shows the responses for selected respondents and the result of the expression
for the Dinosaurs element.
Respondent Grid Slice Gallery Result of Expression
307 {First} {Birds}
{Second} {Human_biology} False
{Third} {insects}
{Fourth} {other}
308 {First} {Dinosaurs}
{Second} {other} True
{Third} {Conservation}
{Fourth} {Birds}
309 {First} {Birds}
{Second} {Human_biology} True
{Third} {Dinosaurs}
{Fourth} {Evolution}
...
314 {First} {Human_biology}
{Second} {Fossils} False
{Third} {other}
{Fourth} {Dinosaurs}
When the table is populated, the IBM® SPSS® Data Collection Survey Tabulation Aggregator
counts the number of respondents where the element expression is true, and the total is displayed
for the Dinosaurs element in the table.
This is the table produced by the script:

Figure 1-353
Table with combined grid slice showing galleries that were one of first three visited
Note: The base in the final table includes only the numbers of respondents who answered the
question for the three iterations, whereas the base in the other tables includes all those who were
asked the question, whether or not they responded.
Filtering Hierarchical Data
Sample Script File: HierarchicalFilters.mrs
1306
Chapter 1
This topic provides a number of examples to illustrate how filters and expressions work when
you are using the hierarchical view of the data. The examples are based on the Household XML
sample.
First let’s create an unfiltered table at the Person level using the following table specification:
Region{.., ^No_answer} * NumRooms > Person.Gender
Notice that this table contains two variables (Region and NumRooms) at the household (HDATA)
level and one variable (Person.Gender) at the Person level. Here is the table:
Figure 1-354
Unfiltered table showing region by number of rooms
Now let’s add a filter to the table to select females only. We do this by creating a person-level filter,
because the Gender variable is at the Person level. The fourth parameter of the Filters.AddNew
method defines the level of the filter. For example:
TableDoc.MyTable.Filters.AddNew("Females", "Gender = {Female}", , "Person")
Figure 1-355
Table showing region by number of rooms, filtered to show females only
Notice that, unlike the axis specification, in the filter expression the Gender variable has been
specified as “Gender” and not using its full name of Person.Gender. This is because you must
always specify the names of the variables in the filter expression relative to the level of the filter.
In this example the filter is at the Person level and so we must use the variable’s name rather
than its full name.
1307
Base Professional
Now suppose we also want to filter the table on the household-level NumRooms variable. We
can achieve this by adding another separate filter at the top level. The level parameter of the
Filters.AddNew method automatically defaults to the top (HDATA) level, so we do not need to set
it explicitly. For example:
TableDoc.Tables.MyTable.Filters.AddNew("UpTo7Rooms", "NumRooms < 8")
Here is the table after applying both filters:

Figure 1-356
Table showing regions by number of rooms with local and global filters
When you specify multiple separate filters like this, IBM® SPSS® Data Collection Base
Professional automatically down-levs the expressions to the level of the lowest filter and combines
the resulting expressions using the And operator.
When you create a filter, all of the variables you use in the filter expression must be at the level
of the filter. However, you can include variables from a higher parent level by down-leving
them. For example, we can create a single Person-level filter that is identical to the combined
separate Person-level and Top-level filters we created above by down-leving the NumRooms
variable to the Person level:
TableDoc.Tables.MyTable.Filters.AddNew("FemalesAndUpTo7RoomsAtPerson", _
"Gender = {Female} And ^.NumRooms < 8", , "person")
Notice that the NumRooms variable has been preceded by the down-lev operator (^.). This filter
selects women and girls who live in households that have less than eight rooms, just as the
combination of the two separate filters does.
You can include variables from a lower child level by up-leving them. For example, if we wanted
to create our filter at the household level, we could up-lev the Gender variable. However, it is
not possible to create the previous filter at the household level. We can either select households
that contain at least one female and have less than eight rooms:
TableDoc.Tables.MyTable.Filters.AddNew("HouseholdsWithFemalesAndUpTo7RoomsAtTop", _
"Sum(Person.(Gender = {Female})) > 0 And NumRooms < 8")
1308
Chapter 1
Which gives this table:
Figure 1-357
Table showing regions by number of rooms with filters
Or we can select households that contain no males and have less than eight rooms:
TableDoc.Tables.MyTable.Filters.AddNew("AllFemaleHouseholdsAndUpTo7RoomsAtTop", _
"Sum(Person.(Gender = {Male})) = 0 And NumRooms < 8")
Figure 1-358
Table showing regions by number of rooms with filters
However, it is not possible to create a household-level filter to select females only, because that
information is not available when you up-lev the data to the household level. The reason for this is
that the person-level data for each household is collapsed together.
Notice that you up-lev data by using the up-lev operator ( .( ) in combination with one of the
aggregate functions supported by the IBM® SPSS® Data Collection Data Model.
You can create tables with filters that make use of loop slice expressions. When using a slice
expression, the level of the slice expression is the level of the first identifier. In the following
cases, the level is that of the Person (HDATA).
For a single filter that makes use of a loop slice expression:
TableDoc.Tables.MyTable.Filters.AddNew("FirstPersonIsMale","Person[1].Gender = {Male}", , "HDATA")

1309
Base Professional

Figure 1-359
Table showing single filter that makes use of a loop slice expression
For two filters filter that makes use of a loop slice expression:
TableDoc.Tables.MyTable.Filters.AddNew("FirstPersonIs","Person[1].Gender = {Male}", , "HDATA")

TableDoc.Tables.MyTable.Filters.AddNew("FirstPerson", "person[1].tvdays[{Channel_1}].Column.ContainsAny({E12_days, E34_days})", , "HD

Figure 1-360
Table showing two filters that make use of a loop slice expression
When creating multiple filters at different levels for individual tables, the filter levels must have
a direct parent-child relationship with each other and not be parallel to each other (on different
branches of the tree). For example, using the Household sample data, you cannot create separate
filters at the Person and the Vehicle levels for the same table, because these levels are parallel to
each other. However, you can create separate filters for the same table at the Person level and Trip
levels, because the Trip level is a direct descendent of the Person level. This restriction applies
regardless whether you define the filters as individual table filters or using global and default filters.
1310
Chapter 1
If you need to filter a table on variables from parallel levels, you must include the variables in the
same filter and up-lev the variables from one of the levels to the first common ancestor level and
then down-lev the data to the level of the filter. For example, the following Person-level filter
includes the VehicleType variable from the parallel Vehicle-level :
TableDoc.Tables.MyTable.Filters.AddNew("MalesAndMotorBikesAtPerson", _
"Gender = {Male} And ^.Sum(Vehicle.(VehicleType = {Motorbike})) > 0", , "person")
Statistical Tests
IBM® SPSS® Data Collection Base Professional provides a number of statistical tests that you
can run on your tables. You can use these tests to show whether differences in the distribution
of counts in tables are statistically significant or whether they are merely due to chance. The
following table lists the statistical tests that are available. Note that each test has a number of
requirements regarding the structure and contents of the tables on which it can be performed.
Name Description
Chi-Square Test This test looks at the variables on the side and the top of a table and
tests whether they are independent. For example, it can be used to
show whether or not variations in political opinions depend on the
respondent’s age.
Cell Chi-Square Test This test looks at each table cell and tests whether it is significantly
different from its expected value in the overall table.
Column Proportions Test This test looks at the rows of a table independently and compares
pairs of columns, testing whether the proportion of respondents in
one column is significantly different from the proportion in the other
column. The proportion is the count in the cell divided by the base
for the column.
Column Means Test This test looks at means that are presented in a row of a table and
compares pairs of columns, testing whether the mean in one column
is significantly different from the mean in the other column.
Fisher’s Exact Test This test looks at the variables on the side and top of a table with two
rows and two columns and tests whether they are independent. It
is suitable for use in a subset of the tables for which the chi-square
test is available.
Net Difference Test This test deals with each row independently and compares the
proportions in four columns at a time to test whether the difference
between the values in the first pair of columns is significantly different
from the difference between the values in the second pair of columns.
Paired Preference Test This test deals with each column independently and compares pairs
of rows to see whether the figures in each pair differ significantly
from one another.
Product Difference Test This is not a separate statistical test in its own right; instead, it applies
the column proportions or column means test to a combination of
variables that you select, to provide a detailed breakdown of results by
combinations of individual categories within the selected variables.
T-test Test This test compares the means of two variables, computes the
difference between the two variables for each case, and tests to see if
the average difference is significantly different from zero.
Tukey Test This test tests the significance of unplanned pairwise comparisons.
1311
Base Professional
Statistics Properties
The following table identifies the properties supported by each statistical test.
Chi-square/Fisher
Column Column Net Paired T-Test
proportions means difference Preference
(/prod diff) (/prod diff)
SigLevel No Yes Yes Yes Yes
SigLevelLow No Yes Yes Yes Yes
MinBase No Yes Yes Yes Yes
SmallBase No Yes Yes Yes Yes
ShowLSD No Yes Yes No No
UseQFormula No Yes Yes No No
No
UseContinuityCorrection Yes No No No
Requesting Statistical Tests
To add or remove a chi-square, column proportions or column means test for the table, display the
Preferences tab and click the Modify button that is just above the list of statistical tests. This opens
the Modify Table Statistics dialog box, in which you can add and remove tests from your table.
For information on adding a paired preference test, see To Add a Paired Preference Test
1312
Chapter 1
Figure 1-361
Preferences tab
Significance Level 1. You can select the significance level that you require for the column
proportions and column means tests. The options are 1%, 5%, and 10%.
Significance Level 2. If you want to perform the column proportions or column means test at two
levels of significance, select the second significance level. The options are 5% and 10%. Note that
the value you select must be greater than that of the first significance level.
Small Base. By default, tests on rows or columns where the base is above the minimum base but
below 100 are carried out, but an asterisk (*) appears next to the result to indicate that the base
size is small. You can enter a new value for the small base if required.
Minimum Base. By default, tests are not carried out on rows or columns where the base is below
30. Two asterisks (**) are placed in the cell to indicate this. You can enter a new value for the
minimum base if required.
1313
Base Professional
Use effective base. Select this check box if you want IBM® SPSS® Data Collection Survey
Tabulation to use the effective base rather than the simple weighted base in statistical tests on
weighted tables. This option has no effect on statistical tests run on unweighted tables. This option
is selected by default. For more information, see the topic Weighted Data on p. 1388.
The following commands are available in the menu at the top of the Preferences tab:
Copy. Copies all of the settings on the Preferences tab to the Survey Tabulation clipboard. This
means that you can copy the settings to another table.
Paste. Overwrites all of the options on the Preferences tab with the contents of the Survey
Tabulation clipboard.
Set as default for new tables. Select this option if you want to define these preferences for several
tables. Any new tables that you create will automatically have the same types of cell content and
all of the other options defined on the Preferences tab for this table.
Apply to all existing tables. Select this option if you want to define these preferences to all of
your existing tables.
Modify Table Statistics Dialog Box
You use the Modify Table Statistics dialog box to add or remove a chi-square, column proportion,
or column means statistical test on the current table.
For information on adding a paired preference test, see To Add a Paired Preference Test.
Figure 1-362
Modify Table Statistics dialog box
Available items. This lists all of the types of statistical tests that you can run on your tables. To add
an item, select the item and click the Add button.
Show items in this order. Lists the selected statistical tests in the order in which they will be
displayed on the Preferences tab. To remove a test, select the item and click the Remove button.
To move an item up the list, select the item and click Move Up. To move an item down the list,
select the item and click Move Down.
For a full list of the statistical tests that are available, see Statistical Tests.
1314
Chapter 1
To Open the Modify Table Statistics Dialog Box

E Select the Preferences tab.
The chi-square, column proportion, and column mean statistical tests that have been requested
for a table are listed on the Preferences tab.
For information on adding a paired preference test, see To Add a Paired Preference Test.
E To open the Modify Table Statistics dialog box, click the Modify button that is just above the
list of statistical tests.
To Add or Remove a Statistical Test
This topic explains how to add a column proportions, column means, or chi-square statistics test to
a table. For information on adding a paired preference test, see To Add a Paired Preference Test.
E In the Table List, select the table for which you want to request a statistical test.
The statistical tests that have been requested for a table are listed on the Preferences tab.
E Select the Preferences tab.
E Click the Modify button that is just above the list of statistical tests.
This opens the Modify Table Statistics dialog box.

E To add a test, select it in the Available Items list and click the Add button.
E To remove a test, select the item in the list on the right side and click the Remove button.
E Click OK.
This returns you to the Preferences tab.

E If required, change the significance level(s) and the minimum and small base values. For more
information, see the topic Requesting Statistical Tests on p. 1311.
To Add a Paired Preference Test
This topic explains how to add a paired preference test to a table. For information on adding
a column proportions, column means, or chi-square statistics test, see To Add or Remove a
Statistical Test.
You can add the paired preference test either to an axis or to a variable. Adding the test to an axis
affects only the current table, while adding the test to a variable means that it is also available for
use in other tables. The paired preference test is carried out at the 5% significance level.
To add a Paired Preference Test to an Axis
E In the Table List, select the required table, or create a new one.
E Select the Define tab.

1315
Base Professional
E In the Table Definition section, select the variable to which you want to attach the test.
Figure 1-363
Selecting a variable
E Click the Edit Axis icon:

Figure 1-364
Edit Axis icon
This opens the .

E From the menu at the top of the Edit tab, choose Insert. This opens the .
E From the Available Items list, select Paired Preference Test.
E Click Add, then click OK.
E Click OK again to close the Edit Axis dialog box.
E Click the Populate icon.

Figure 1-365
Populate icon
The table displays the paired preference test.
To add a Paired Preference Test to a Variable
E In the Variable List, select the variable to which you want to attach the test.
E From the Variables menu, choose Edit. This opens the .
E From the menu at the top of the Edit tab, choose Insert. This opens the .
E From the Available Items list, select Paired Preference Test.
E Click Add, then click OK.
E Click OK again to close the Edit Variable dialog box. The variable icon in the Variable List
changes to show that the variable has been edited.
E Create your table using the edited variable.
E Click the Populate icon.

1316
Chapter 1
Figure 1-366
Populate icon
The table displays the paired preference test.
To View Diagnostics Information for Statistical Tests
You can choose to generate diagnostics information for statistical tests you have added to your
tables, and the information is written to your IBM® SPSS® Data Collection Interviewer Server
Administration user folder, from where you can download it to your local computer or other
network location. To do this you need to have Interviewer Server Administration permissions to
use the Files activity.
The diagnostics information is written to a file in comma-delimited format, so that you can open it
in Microsoft Excel and perform calculations on the data. The file is called RawStatisticsData.csv.
To generate the diagnostics information:
E In the View Table Options dialog box, check the Generate Raw Statistics Data box.
E Populate the table.
To download the diagnostics information:
E From the main menu bar, click the Home button to return to Interviewer Server Administration:
Figure 1-367
Home button
IBM® SPSS® Data Collection Survey Tabulation gives you an option to save the table document
and then you are returned to Interviewer Server Administration.
E In Interviewer Server Administration, select the project and then choose Files from the list of
activities.
E In the list of files, select the RawStatisticsData.csv file.
E From the Actions menu, choose Download.
This opens the File Download dialog box.
E Click Open to open the file or Save to save the file in a location of your choice.
Chi-Square Test
The chi-square test looks at the variables on the side and top axes of a table and tests whether
they are independent. For example, it can be used to show whether or not variations in political
opinions depend on the respondent’s age.
1317
Base Professional
The test compares the actual counts in each cell with the counts that would be expected in
each cell if there were no relationship between the variables. The chi-square statistic provides a
summary of the discrepancy between the actual and expected counts. The greater the dependence
between the two variables, the larger the discrepancy will be, so a large chi-square statistic
indicates dependence between the two variables.
The p value associated with the chi-square test can be distorted if any cells in the table have
very low expected counts (below 5).
Fisher’s Exact Test
The chi-square test can be used for any number of rows and columns, but gives only an estimated
probability value. For a table (or section of a table) that contains two rows and two columns of
data, a more accurate test is Fisher’s exact test, which finds the exact probability value for the table.
Fisher’s exact test is appropriate only for tables, or parts of tables, with two rows and two columns
that contain values (for example, a nested section of a larger table may be valid for this test). Rows
and columns with no respondent data are ignored by the test, so a table with two rows and two
columns may not be valid if, for example, one of the rows has no data. Conversely, a table with
three rows and two columns may be suitable for the test if one of the rows has no data.
You can use this test on its own or in addition to the chi-square test. If you request the chi-square
test and Fisher’s exact test on the same table, a single chi-square column is used to display
the results for both tests. If you request Fisher’s exact test on a table that does not meet the
requirements, it is not carried out.
The value returned by Fisher’s exact test is the two-tailed p value, which does not distinguish
between significantly high and significantly low results.
Example of the Chi-Square Test
Sample Script File: ChiSquareAndFisherTests.mrs
The chi-square test in this example tests whether there is an association between respondents’
expectations of their visit to the museum and their age.
The script adds the test to the table as follows:
1318
Chapter 1
Figure 1-368
Table showing chi-square test
Notice that has added two rows to the table below the rows formed from the categories of the
age variable. Similarly, has added a column to the right of the columns formed from the categories
of the expect variable. The cell at the intersection of the first additional row and column displays
the chi-square statistic. In this table, the chi-square statistic is 70.459. The table also shows the p
value for this chi-square value, based on the degrees of freedom for the table (you can see the
degrees of freedom in the diagnostics file). In this case, the p value of 0.024 indicates that there is
approximately a 2.5% chance that the results are due to chance, and therefore a 97.5% probability
that there is a significant relationship between respondents’ expectations of their visit and their age.
Example of Fisher’s Exact Test
Sample Script File: ChiSquareAndFisherTests.mrs
This example tests whether having a biology qualification has any influence over whether
respondents prefer the dinosaurs exhibit or the human biology exhibit. In a simple table of
biology by prefer, the results appear to show that most people with no biology qualification
prefer dinosaurs, whereas people with a biology qualification display no particular preference
between dinosaurs and human biology. As this information is contained in two rows and two
columns, you can apply Fisher’s exact test to determine whether this difference is significant or
simply the result of chance.
Here is the script to add the test to the table:
TableDoc.Table2.Statistics.Add("Fisher")
1319
Base Professional
Notice that although the table of biology by prefer contains three rows and two columns, IBM®
SPSS® Data Collection Base Professional is able to apply Fisher’s exact test because it detects that
only two rows and two columns contain data and so the table meets the requirements of this test.
Figure 1-369
Table showing Fisher’s exact test
The resulting table has an additional Fisher Exact row below the rows formed from the categories
of the biology variable. Similarly, an additional ChiSq column appears to the right of the columns
formed from the categories of the prefer variable. The cell formed by the Fisher Exact row and the
ChiSq column displays the value returned by the test, which is the exact p value for the table.
In this table, the value is 0.021, which indicates that there is approximately a 2% probability of
the results in this table occurring by chance, and therefore a 98% percent probability that the
apparent difference in preference between those with and those without a biology qualification
is statistically significant.
Chi-square Test and Fisher’s Exact Test
You can apply both the chi-square test and Fisher’s exact test to the same table. For example,
you may decide to apply both tests on a table with several sections so that Fisher’s exact test will
display an exact p value in those sections where it is possible to do so, while the value for the
chi-square test will still be available in the other sections of the table.
Here is the script to add the tests to the table:
TableDoc.Table3.Statistics.Add("Fisher")
In this table the top section has more than two rows and is therefore unsuitable for Fisher’s exact
test, so only the chi-square result is calculated. The bottom section has two rows and two columns
of data, so the results for both Fisher’s exact test and the chi-square test are displayed.
1320
Chapter 1
Figure 1-370
Table showing chi-square and Fisher’s exact tests
Details and Restrictions of the Chi-Square Test
The chi-square test is not suitable for all tables. When you request the test on a table that is
structurally unsuitable, IBM® SPSS® Data Collection Base Professional simply skips the test,
leaves the chi-square and p value rows blank, and writes an explanation to the diagnostics data.
It is up to you to make sure that the data in the table is generally suitable for testing, that the
sample size is suitable, etc.
Base Professional displays a message if you define a chi-square test on an unsuitable table or if
you change a table that has a chi-square test defined so that it is no longer suitable for the test.
When this happens, you can either adjust the table so that it conforms to the restrictions, or you
can remove the test from the table. However, sometimes is unable to determine that a table or a
section of a table is unsuitable for the test until it actually attempts to perform it—for example,
when a table has only two category columns and all of the values in one of those columns are zero.
When that happens, simply skips the test and leaves the chi-square and p value rows blank.
Multiple response variables. This test is not suitable for tables that include a multiple response
variable.
1321
Base Professional
Hierarchical data. This test is unsuitable for running on lower level data when you are working
with hierarchical data a hierarchical view of the data. For more information, see the topic
Hierarchical Data on p. 1391.
Rows and columns For the chi-square test, the variables on the side and top axes must have at least
two categories. does not perform the test on rows and columns in which all of the values are zero
or on rows and columns that are formed from non-category elements, such as bases and means.
Fisher’s exact test is carried out only on tables that have exactly two categories containing data
on the top and side axes of the table (or on a subsection of the table, such as that formed by a
nested or concatenated table).
Nested and concatenated tables. The chi-square test compares the columns and rows formed from
the categories of two variables—one on the side axis and one on the top axis. If there is more
than one variable on either the side or the top axis, the test is performed separately for each
combination of variables at the innermost nesting level. This means that the innermost child
variables must have at least two categories.
Built-in bases. This test is not suitable for tables that include variables that contain more than
one built-in base.
Two by two tables. When performing the chi-square test on a table or a section of a table that has
two category columns and two category rows, computes Yates’ corrected chi-square (continuity
correction). When performing the Yates’ corrected chi-square, also computes Fisher’s exact test.
However, the results of Fisher’s exact test are shown only in the diagnostics data and not on the
table itself (unless you have also requested Fisher’s exact test on the table).
Excluded Elements. The IncludeInBase=False property has no effect on the chi-square test. If
a chi-square test is carried out on a table containing categories that are excluded from the base
using IncludeInBase=False, the calculation includes rows and columns corresponding to the
excluded categories.
Statistical Formula for the Chi-Square Test
The following table shows the notation used in this topic.

Observed frequency in row i, column j. This value
is weighted in a weighted table, unweighted in an
unweighted table.
Number of rows contributing to the test.
Number of columns contributing to the test.
The total in row i:

1322
Chapter 1
The total in column j:

The total in the table or section of the table being
tested:
The expected value in the table or section of the
table being tested:
where, for Pearson’s formula:
and for the Yates’ correction:
The degrees of freedom are:
For details of Fisher’s exact test, see Appendix 5, p562-564, SPSS 7.5 Statistical Algorithms
(1997), Chicago, IL: SPSS Inc. ISBN 1-56827-185-9.
Cell Chi-Square Test
The cell chi-square test looks at each table cell and tests whether it is significantly different
from its expected value in the overall table. For example, if it is thought that variations in
political opinions might depend on the respondent’s age, this test can be used to detect which cells
contribute significantly to that dependence.
1323
Base Professional
Unlike the chi-square test, which is carried out on a whole set of rows and columns, the cell
chi-square test is carried out independently on each table cell. This is done by treating each cell as
belonging to a two-by-two table, known as a contingency table, as follows:
Base In column Not in column
Base B C B-C
In row R V R-V
Not in row B-R C-V B-R-C+V
For each cell, the values B, C, R and V are taken from the table. The other values are calculated
from these values.
The formula applied to this two-by-two table is the standard Pearson chi-square formula, with
the Yates’ correction for small samples when relevant as the pvalue associated with the Pearson
chi-square test can be distorted if any cells in the table have very low expected counts (below 5).
Note: Although the significance level of the cell chi-square test is accurate for any given cell,
the cell tests cannot be used instead of the chi-square test carried out on the overall table. Their
purpose is simply to point to the parts of the table where dependencies between row and column
categories may exist.
Example of the Cell Chi-Square Test
Sample Script File: CellChiSquareTests.mrs
The cell chi-square test in this example tests whether there are any particular cells that contribute
significantly to any association between respondents’ expectations of their visit to the museum
and their age.
The script adds the test to the table as follows:
TableDoc.Table1.Statistics.Add("CellChiSquare")
1324
Chapter 1
Figure 1-371
Table showing cell chi-square test
When a cell chi-square test is requested, creates a cell item position for it, in the same way that it
does for the results of the column proportions and column means tests. This cell item is created
as the last item, or the last item before the column proportions/column means item (when both
statistics requested on the table).
Significance symbols
The cell chi-square test produces a result for each table cell. The result is one of three possibilities:
> — The cell value is significantly larger than expected
< — The cell value is significantly smaller than expected
The cell value is not significant (no symbol)
By default, the cell chi-square cell item position will contain the symbols indicating significance.
The default symbols are < and >. Alternatively, you can specify the strings. For example:
Tab.Statistics["CellChiSquare"].AboveExpected = ">>"
Tab.Statistics["CellChiSquare"].BelowExpected = "<<"
If chi-square values are also requested, these are displayed in the cell chi-square cell item position
with the symbols to the right of value. For any cell that has the Yates’ small sample correction
applied, (y) is displayed to the right of the chi-square or p value, with the significance symbol to
the right.
1325
Base Professional
The option to display values is also specified on the cell chi-square statistic:
Tab.Statistics["CellChiSquare"].Values = X
where X is None (the default), ChiSquare or PValue.
The default decimal places are two for ChiSquare and six for PValue. This can be changed by
specifying:
Tab.Statistics["CellChiSquare"].Decimals = N
Details and Restrictions of the Cell Chi-Square Test
Cell chi-square validity
The following conditions must be met in order for the cell chi-square test to be valid:
0 < column base < overall base
0 < row base < overall base
This means the test is not valid for a cell where all or no respondents belong in the whole column
or row for the cell.
Significance level
You can select an explicit significance level of 10%, 5%, 2.5% 0.5% or 0.1%. Alternatively,
an automatic selection can be requested, which sets the significance level to one of the above
depending on the overall base as follows:
Level Applied For overall base value “f” of
10% f <= 300
5% 300 < f <= 1000
2.5% 1000 < f <= 4000
0.5% 4000 < f <= 20000
0.1% f > 20000
Cell chi-square usage
The cell chi-square test is not suitable for all tables. When you request the test on a table that is
structurally unsuitable, IBM® SPSS® Data Collection Base Professional simply skips the test,
leaves the cell chi-square and p value rows blank, and writes an explanation to the diagnostics
data. It is up to you to make sure that the data in the table is generally suitable for testing, that the
displays a message if you define a cell chi-square test on an unsuitable table or if you change a
table that has a cell chi-square test defined so that it is no longer suitable for the test. When this
happens, you can either adjust the table so that it conforms to the restrictions, or you can remove
the test from the table.
1326
Chapter 1
with hierarchical dataa hierarchical view of the data. For more information, see the topic
Rows and columns For the cell chi-square test, the variables on the side and top axes must have at
least two categories. does not perform the test on rows and columns in which all of the values
are zero or on rows and columns that are formed from non-category elements, such as bases
and means.
Nested and concatenated tables. When variables are concatenated in , a base is inserted at the start
of each variable (variables can, in general, be different). With nesting, a base is needed for each
“nest section” (they are almost always different). When a cell has the cell chi-square test applied
to it, the base row and column used will be the nearest base in each dimension. This is consistent
with the base used for percentages and other statistics in . When applied to the automatic selection
option for significance level, this means that different parts of one table could have different
significance levels applied.
Excluded Elements. The IncludeInBase=False property has no effect on the cell chi-square test.
If a cell chi-square test is carried out on a table containing categories that are excluded from
the base using IncludeInBase=False, the calculation includes rows and columns corresponding
to the excluded categories.
Statistical Formula for the Cell Chi-Square Test
For each cell, a two-by-two contingency table is established, with the actual cell from the cross
table as the upper left cell, and the other cells derived by all three possible negations of the cross
table cell:
Total Column NOT column
Total f c f-c
Row r x r-x
NOT row f-r c-x f-r-c+x
The two-by-two contingency table has one degree of freedom; the other three cells are determined
when one of the four cells is known (x).

The observed values.
The expected values given the null hypothesis.

1327
Base Professional
The first index points to the two-by-two table rows and the second index to the columns:
Null hypothesis
The deviation between the observed values Oi,j and the expected values Ei,j are not significant and
are at random. That is the variables Row/NOT row and Column/NOT column are independent.
χ2 statistic
The null hypothesis is rejected if the p value for the χ2 statistic is smaller than the specified
significance level. The p value is calculated from the chi-square distribution with 1 degree of
freedom.
Yates’ correction for small samples
In the underlying theoretical assumptions of the test there is an assumption of continuity that
becomes dubious with very small samples and where some of the expected values are very small.
In order to avoid a situation where rejection is done when assumptions of continuity are dubious
the following correction is applied:
χ2 statistic with Yates’ correction when at least one of the expected cell values
1328
Chapter 1
(E1,1, E1,2, E2,1, E2,2) < 5 :
The consequence of the correction may be that an uncorrected rejection is cancelled.
Column Proportions Test
The column proportions test looks at the rows of a table independently and compares pairs of
columns, testing whether the proportion of respondents in one column is significantly different
from the proportion in the other column. The proportion is the count in the cell divided by the
base for the column. For details about the types of tables that are suitable for this test and what
happens when there is nesting or concatenation, see Details and Restrictions of the Column
Proportions Test.
automatically assigns a one-character ID to each column in the test. When there is a difference
between any pair of proportions at the chosen significance level, displays the ID of the column
that contains the smaller proportion below the cell contents of the cell that contains the larger
proportion.
Note: Column IDs are only applied to visible table elements. Hidden elements are not taken in
consideration when defining a Column IDs as a string.
Examples of the Column Proportions Test
Sample Script File: ColumnProportionsTest.mrs
The first column proportions test in this example tests whether there are any significant differences
in the proportions of male and female respondents who found the different galleries most
interesting.
1329
Base Professional
Figure 1-372
Table showing column proportions test
Notice that has assigned IDs of A to the Male column and B to the Female column and that these
are displayed below the column headings. Notice the B below the cell contents in the Male cell
of the Insects row, and the A below the cell contents in the Female cell of the Human biology
row. For the Insects row, this indicates that the proportion of male respondents is higher than the
proportion of female respondents and that this difference in proportions is statistically significant
at the 5% significance level. For the Human biology row, this indicates that the proportion of
female respondents is higher than the proportion of male respondents and that this difference in
proportions is statistically significant at the 5% significance level.
1330
Chapter 1
The column proportions test in this table shows us that, although the proportions of male and
female respondents who found the different galleries most interesting vary, the differences are
statistically significant only for the Insects and Human biology galleries. The differences in the
preferences for all of the other galleries can be explained by chance.
See also Adding a Minimum p Value to a Table for an example of this table that displays only
rows with significant results.
The next example tests whether there are any significant differences in the proportions of male and
female respondents who visited or planned to visit other museums.
Figure 1-373
Table showing column proportions test
Notice that has assigned IDs of A to the Male column and B to the Female column and that these
are displayed below the column headings. Notice the B below the cell contents in the Male cell
of the National Museum of Science row, and the A below the cell contents in the Female cell of
the National Art Gallery row. For the National Museum of Science row, this indicates that the
proportion of male respondents is higher than the proportion of female respondents and that
this difference in proportions is statistically significant at the 5% significance level. For the
National Art Gallery row, this indicates that the proportion of female respondents is higher than
the proportion of male respondents and that this difference in proportions is statistically significant
at the 5% significance level.
The column proportions test in this table shows us that, although the proportions of male and
female respondents who found the different galleries most interesting vary, the differences are
statistically significant only for National Museum of Science and National Art Gallery. The
differences for all of the other named museums can be explained by chance.
1331
Base Professional
Examples of Testing Different Columns
The next example shows the results of a column proportions test using the default columns, on a
table with Biology nested within Before on the top axis:
Figure 1-374
Column Proportions test with default columns tested
This example tests the default selection of columns; that is, it tests all columns in each section
of the table against each other. In this case, the test indicates whether there are any significant
differences between the expectations of those who have a biology qualification and those who
do not. The results show a significant difference in the expectation of general knowledge and
education, between those with and without a qualification who have visited the museum before
(columns C and D).
However, in this table, it is also possible that we might want to concentrate on significant
differences between those who have been to the museum before and those who have not.
The following example tests this:
"C/E, D/F"
The following example tests this, using the script:
TableDoc.Table6.Statistics.TestColumns = "C/E, D/F"

1332
Chapter 1
Figure 1-375
Column proportions test with selected columns
The results show a significant difference in the expectation of education for children, between
people with no biology qualification who have visited the museum before and those who have not
(columns D and F).
Example of Defining Column IDs as a String
Starting with IBM® SPSS® Data Collection Base Professional 5.6 you can define column IDs
as a string using the ColumnsID property. Each character in the string is used to allocate a
column ID, with a period or space character used to indicate that an ID should not be allocated.
A character needs to be added to the ID’s string for each column, even if the column is hidden.
When allocating column IDs a character should also be added for the base columns.
For the table below, the column IDs could be set as follows to test Yes-Male against No-Male,
and Yes-Female against No-Female:
Table.Statistics.ColumnIDs = "....MF.NG"
Table.Statistics.TestColumns = "M/N, F/G"
1333
Base Professional
Figure 1-376
Column Proportions Test with New Column IDs
Details and Restrictions of the Column Proportions Test
The column proportions test is not suitable for all tables. When you request the test on a table that
is structurally unsuitable, IBM® SPSS® Data Collection Base Professional changes the specified
table level (a warning message is not provided). It is up to you to make sure that the data in the
table is generally suitable for testing, that the sample size is suitable, etc.
displays a message if you define a column proportions test on an unsuitable table or if you change
a table that has a column proportions test defined so that it is no longer suitable for the test. When
this happens, you can either adjust the table so that it conforms to the restrictions described
here, or you can remove the test from the table. However, sometimes is unable to determine
that a table or a section of a table is unsuitable for the test until it actually attempts to perform
it—for example, when a table has only two category columns and all of the values in one of those
columns are zero. When this happens, simply skips the test.
with hierarchical data a hierarchical view of the data. For more information, see the topic
Grids. It is possible to run this test on grids, provided that the test is carried out on a grid table
structured in the format:
rating[..].Column * rating
This test is suitable for running on grid tables in the following format when you set the level of the
table to be the top (for example, TableDoc.Table1.Level="hdata"):
rating * rating[..].Column
Weighting. This test is unsuitable for running when weighting is applied to individual columns or
rows.
1334
Chapter 1
Rows. This test compares the proportions in each row that are formed from a variable category.
The test is not performed on rows that are formed from non-category elements, such as bases
and means.
Columns. For each category row, the test compares pairs of columns that are formed from variable
categories, testing whether the proportion of respondents in one column is significantly different
from the proportion in the other column. Base Professional does not test columns that are formed
from non-category elements or columns in which all of the values are zero. The test cannot be
performed on tables that contain more than 52 category columns if you request one significance
level, or 26 category columns if you request two significance levels, and it needs a minimum
of two category columns.
Built-in Column Proportions tests. If a column proportions test is included in the metadata for a
variable, the test is performed only if the variable is added as a single variable. If it is nested or
concatenated with other variables, the built-in test is ignored to prevent possible inconsistencies in
the results, and you must explicitly specify a column proportions test for the whole axis.
Nested tables. If there is nesting on the top axis, the test is performed separately for each set of
columns that is formed from the categories of the innermost child variables. This means that the
innermost child variables must have at least two categories. Nesting on the side axis does not
change the test—each category row is always tested.
Concatenated tables. If there is concatenation on the top axis, the test is performed separately for
each set of columns that is formed from the categories of a concatenated variable. Concatenation
on the side axis does not change the test—each category row is always tested.
Built-in bases. If any of the variables on the top axis has more than one base, the test is performed
separately for the columns formed from the categories before and after each base.
Sample size. This test relies on a large sample, which means that it may not be valid for a small
sample—for example, fewer than about 30 cases. checks for small sample sizes, and does not
carry out the test on columns with a base below 30. You can change the minimum sample size if
required, using the MinBase property, by entering a new value in the Minimum Base field in the
Statistics tab of the Table Properties dialog box, by entering a new value in the Minimum Base
field in the Preferences tab.
Multiple response variables. When there is a multiple response variable on the top axis, Base
Professional performs the overlap adjustment.
Two-tailed test. This is a two-tailed test, which means that it reports all significant differences
between the proportions in all of the columns regardless of which columns contain the greater
proportions.
Excluded elements. The column proportions test is not carried out for rows that have been excluded
from the base using the IncludeInBase=False property. The column proportions test is carried out
for columns that have been excluded from the base using the IncludeInBase=False property.
Overlap formula. Each axis can be derived from either an axis expression or an MDM variable.
When an axis is derived from an axis expression, TOM will honor the MaxResponses property.
When the MaxResponses value is greater or equal to 2, TOM regards the axis as overlapped.
Considering that the MaxResponses default value is 2, each axis is in an overlap state by default.
1335
Base Professional
When an axis is derived from an MDM variable, TOM will honor the variable’s EffectiveMaxValue
property. When the EffectiveMaxValue value is greater or equal to 2, TOM regards the axis as
overlapped. When there are any sub-axis that are overlapped for a table’s side and top, TOM
regards the side or top as overlapped.
When both the side and top are overlapped for a table, and UseGridOverlapFormula is true, the
grid overlap formula is applied to the table. The normal overlap formula is applied when the
table’s top is overlapped, otherwise the standard formula is used.
Refer to the following topics for more information regarding overlap:

TOM.IStatistics.UseGridOverlapFormula
TOM.IAxis.MaxResponses
MDM.IField.EffectiveMaxValue
Statistical Formula for the Column Proportions Test
The column proportions test is performed separately for each relevant pair of columns within each
relevant row and so the formula is presented in terms of one row and one pair of columns.

Weighted base in column i.
Sum of squared weights for column i.
Weighted count in this row for column i.
Weighted base for the overlap.
Sum of squared weights for the overlap.
Count in this row for the overlap.
The proportion in each column i is
If the effective base is being used, the effective base in each column i is
Otherwise
1336
Chapter 1
The test is not performed if:

wi <= 0
The effective base is being used and qi <= 0
The proportions in the two columns being tested are identical
The combined proportion for a pair of columns, 1 and 2, is
The covariance term, v, and the effective base, eo, are both set to 0 if:
The data are not overlapping
The data are overlapping and wo <= 0
The data are overlapping and the effective base is being used and qo <= 0
Otherwise
Figure 1-377
Figure 1-378
Figure 1-379
Except for grids, Z always reduces to the value of 1.0.
For grids, the formula for Z is:

Figure 1-380
Where
r0 = the count for this row in the overlap
r1 = the count for this row in column 1 for respondents in both columns
r2 = the count for this row in column 2 for respondents in both columns
1337
Base Professional
and w0 is the base in the overlap, that is, the number of respondents who were asked both columns.
The t value is calculated as

Figure 1-381
where,
If required, the continuity correction option can be applied using the property:
Statistics["ColumnProportions"].Properties["UseContinuityCorrection"] = True
If the option to include the continuity correction is used, the t value is calculated as
Figure 1-382
where c is the continuity correction,
The degrees of freedom, DF, are
DF = e1 + e2 - e0 - 2
The absolute value of t together with the degrees of freedom are used to calculate the probability,
p, for the t value. If p is less than the significance level requested, the proportions in the two
columns are deemed to be significantly different.
Note: The grid overlap formula is applied when the columns have respondents in common, but
some (or all) appear in different rows. The grid table normally complies with the rule that there
is at least a multiple response categorical variable, or a grid or loop iterator, on both the side
and the top.
Column Means Test
The column means test looks at means that are presented in a row of a table and compares pairs of
columns, testing whether the mean in one column is significantly different from the mean in the
other column. automatically assigns an ID to each column in the test. When there is a difference
between any pair of means at the chosen significance level, displays the ID of the column that
contains the smaller value below the cell contents of the cell that contains the larger value.
1338
Chapter 1
Note that the means must be formed from a mean element in the axis rather than from mean values
that are created using the Mean cell contents option. For full details about the types of tables that
are suitable for this test and what happens when there is nesting or concatenation, see Details
and Restrictions of the Column Means Test.
The Least Significant Difference
When you add a column means test to a table, you can optionally display a least significant
difference column for each row of the table. This is the variance for all specified columns at once,
rather than for the pairs of columns that the column means test uses.
When the column means test is applied to a group of columns (for example, ABC), each pair of
columns (AB, AC, BC) is tested separately to see if the mean values are significantly different.
The least significant difference calculation uses the data from all columns in the group to calculate
the smallest difference in means that would be significant at the requested significance level.
Notes
The least significant difference calculation is available only for independent samples (that
is, for non-overlapping columns).
The least significant difference test is available only for tables with a significance level of 1, 5,
10, 15, 20, 25, 32, or 50.
The least significant difference is available with nesting and concatenating on the top axis. It is
not available for tables that use the TestColumns option to carry out non-default column testing.
The characters XXXXX are displayed instead of the result if the table does not meet these
conditions.
This test is appropriate only when the groups being tested have similar base sizes. If the base sizes
differ by more than 25%, the test is not suitable for the table.
Examples of the Column Means Test
The column means test in this example tests whether there are any significant differences between:
The mean age of all respondents who do and do not have a biology qualification
The mean age of the male respondents who do and do not have a biology qualification
The mean age of the female respondents who do and do not have a biology qualification
1339
Base Professional
Figure 1-383
Table showing column means test
Notice that has assigned IDs to all of the columns in the test. Because this is a nested table, the
Yes and No columns formed from the categories of the child variable (biology) are repeated for
each element of the parent variable (gender). IBM® SPSS® Data Collection Base Professional
performs the column means test separately for each set of columns formed from the categories of
the biology variable. Notice how this is reflected in the footnote text.
The first set of Yes and No columns in the table (with IDs A and B respectively) are nested within
the Base column of the gender parent variable. They therefore relate to all of the respondents, both
male and female. The A below the cell contents in the Mean age row in the No column indicates
that the mean age of the respondents in this column is higher than the mean age of the respondents
in the Yes column and that the difference is statistically significant at the 5% significance level.
The second set of Yes and No columns in the table (with IDs C and D respectively) relate to the
male respondents. The C in the No column also indicates that the mean age of the respondents
in this column is higher than the mean age of the respondents in the Yes column and that the
difference is statistically significant at the 5% significance level.
1340
Chapter 1
The third set of Yes and No columns in the table (with IDs E and F respectively) relate to the female
respondents. Base Professional has not displayed any IDs in the mean age row in these columns,
because the difference in mean age is not statistically significant at the 5% significance level.
The column means test in this table shows us that the difference in mean age between the
respondents who have and do not have a biology qualification is significant at the 5% significance
level, but that this is only true for the male respondents and the whole sample. It is not true
for the female respondents.
This example was created using the Museum IBM® SPSS® Quanvert™ database, in which the
age variable has a built-in mean element based on the raw age data. Here is the script to load the
Museum data, create the table, and run the test:
Dim TableDoc

' Load the Museum sample .mdd file

TableDoc.DataSet.Load("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\Quanvert\Museum\qvinfo", "mrQvDsc")
...
TableDoc.Tables.AddNew("Table3", "age * gender > biology{Base(), Yes, No}", _
"Table of Age by Biology within Gender with column means test")
' Remove the column percentages cell item and

' define the column means test
TableDoc.Table3.Statistics.Add("ColumnMeans")
Example of Testing Different Columns
The previous example describes the results of testing the default selection of columns. However,
it is possible to test other combinations of columns instead. For example, you may want to test
for significant differences between:
The mean age of holders of a biology qualification who are male and those who are female
The mean age of those without a biology qualification who are male and those who are female
You can do this by specifying the columns you want to test:
"C/E, D/F"
You can do this by specifying the columns you want to test, using the following line of script:
TableDoc.Table4.Statistics.TestColumns = "C/E, D/F"

1341
Base Professional
This example shows the results of this test:

Figure 1-384
Column means test on selected columns
The result shows that there is a significant difference between the mean ages of male and female
holders of a biology qualification (columns C and E).
Example of Testing at Two Significance Levels
In the next example, two levels of significance have been specified, to test the same table both at
the 5% (higher) and the 10% (lower) level.
1342
Chapter 1
Figure 1-385
Table showing column means test at 2 levels of significance
Notice that in addition to the IDs assigned to the cells in the previous example, in the third set of
Yes and No columns in the table, relating to the female respondents, there is now a lowercase e
in the No column. This indicates that the mean age of the respondents in this column is higher
than the mean age of the respondents in the Yes column and that the difference is statistically
significant at the 10% level.
These lines of script add the two significance levels to the test:
TableDoc.Table5.Statistics.Add("ColumnMeans")
' Set the higher significance level
TableDoc.Table5.Statistics.ColumnMeans.SigLevel = 5
' Set the lower significance level
TableDoc.Table5.Statistics.ColumnMeans.SigLevelLow = 10
Example Showing the Least Significant Difference Column

1343
Base Professional
This example is based on the first table in Examples of the Column Means Test. The column
means test is run on the same table specification with the same significance level. In addition, a
least significant difference column is added to the table. The script to add the column is as follows:
TableDoc.Table8.Statistics.ColumnMeans.Properties["ShowLSD"] = True
Here is the table:

Figure 1-386
Table showing column means test with least significant difference
Notice that an additional column has been added in each section of the table. In the Mean age row,
the column contains the lowest value that would be required for the difference between columns
to be significant. For example, in the Female section of the table, the columns (E and F) are not
marked as significantly different. The difference between the two columns E and F is 3.0. The
least significant difference value for this section shows that, in order to be significant, the columns
in this section would need to differ by at least 3.387.
Details and Restrictions of the Column Means Test
The column means test is not suitable for all tables. When you request the test on a table that is
structurally unsuitable, IBM® SPSS® Data Collection Base Professional simply skips the test.
It is up to you to make sure that the data in the table is generally suitable for testing, that the
1344
Chapter 1
displays a message if you define a column means test on an unsuitable table or if you change a
table that has a column means test defined so that it is no longer suitable for the test. When this
happens, you can either adjust the table so that it conforms to the restrictions described here, or
you can remove the test from the table. However, sometimes is unable to determine that a table
or a section of a table is unsuitable for the test until it actually attempts to perform it. When
this happens, simply skips the test.
Grids. It is possible to run this test on grids, provided that the test is carried out on a grid table
structured in the format:
rating[..].Column * rating
This test is unsuitable for running on grid tables in the format:

rating * rating[..].Column
Weighting. This test is unsuitable for running when weighting is applied to individual columns or
rows.
Mean rows. can perform this test only if there is a mean row on the side axis. The mean row must
be formed from a mean element. This can be a built-in mean element or a mean element added to
the axis expression. For more information, see the topic Special Elements on p. 1204. The test
does not test mean values created using the Mean cell contents option.
The test does not test mean values created using the Mean cell contents option.
Columns. For each mean row, the test compares pairs of columns that are formed from variable
categories. Base Professional does not compare columns that are formed from non-category
elements or columns in which the number of cases contributing to the mean is zero. The test
cannot be performed on tables that contain more than 52 category columns if you request one
significance level, or 26 category columns if you request two significance levels, and it needs a
minimum of two category columns.
Built-in Column Means tests. If a column means test is included in the metadata for a variable, the
test is performed only if the variable is added as a single variable. If it is nested or concatenated
with other variables, the built-in test is ignored to prevent possible inconsistencies in the results,
and you must explicitly specify a column means test for the whole axis.
Nested tables. If there is nesting on the top axis, the test is performed separately for each set of
columns that are formed from the categories of the innermost child variables. This means that the
innermost child variables must have at least two categories. Nesting on the side axis does not
change the test—each mean row is always tested.
Concatenated tables. If there is concatenation on the top axis, the test is performed separately for
each set of columns that are formed from the categories of a concatenated variable. Concatenation
on the side axis does not change the test—each mean row is always tested.
1345
Base Professional
Built-in bases. If any of the variables on the top axis has more than one base element, the test will
be performed separately for the columns formed from the categories before and after each base.
Sample size. This test relies on a central limit theorem approximation to the normal distribution.
This means that a large sample (generally at least 30 cases) is required if the data is not distributed
normally. However, when the data is distributed normally, a large sample is not necessary. checks
for small sample sizes, and does not carry out the test on columns with a base below 30. You can
change the minimum sample size if required, using the MinBase property, by entering a new value
in the Minimum Base field in the Statistics tab of the Table Properties dialog box, by entering a new
value in the Minimum Base field in the Preferences tab.
Multiple response variables. When there is a multiple response variable on the top axis, performs
the overlap adjustment.
Excluded Elements. The column means test is performed whether or not it is carried out on a table
containing elements that are excluded from the base using IncludeInBase=False. The calculation
includes rows and columns corresponding to the excluded elements.
Overlap formula. Each axis can be derived from either an axis expression or an MDM variable.
When an axis is derived from an axis expression, TOM will honor the MaxResponses property.
When the MaxResponses value is greater or equal to 2, TOM regards the axis as overlapped.
Considering that the MaxResponses default value is 2, each axis is in an overlap state by default.
When an axis is derived from an MDM variable, TOM will honor the variable’s EffectiveMaxValue
property. When the EffectiveMaxValue value is greater or equal to 2, TOM regards the axis as
overlapped. When there are any sub-axis that are overlapped for a table’s side and top, TOM
regards the side or top as overlapped.
When both the side and top are overlapped for a table, and UseGridOverlapFormula is true, the
grid overlap formula is applied to the table. The normal overlap formula is applied when the
table’s top is overlapped, otherwise the standard formula is used.
Refer to the following topics for more information regarding overlap:

TOM.IStatistics.UseGridOverlapFormula
TOM.IAxis.MaxResponses
MDM.IField.EffectiveMaxValue
Statistical Formula for the Column Means Test
The column means test is performed separately for each relevant pair of columns within a row that
contains mean values and so the formula is presented in terms of one row and one pair of columns.

Weighted count of cases contributing to the mean
in column i.
1346
Chapter 1
Sum of squared weights for column i.

for the overlap.
Sum of squared weights for the overlap.
Weighted sum of the values in column i.
Weighted sum of the squared values in column i.
The mean in each column i is
If the effective base is being used, the effective base in each column i is
Otherwise
The test is not performed if:

wi <= 0
The effective base is being used and qi <= 0
The mean values in the two columns being tested are identical
The sample variance in column i is
If we set
Then the pooled estimate of the population variance is
The t value is
1347
Base Professional
With no overlap, Z and eo are both zero. With overlap, Z is 1.0, except in the case of grids,
where it is:
Figure 1-387
where:
X12 is the weighted sum, for respondents in both columns, of the value in column 1 multiplied
by the value in column 2
all X and Y terms in Z refer to respondents who are in both columns.
The degrees of freedom, DF, are
DF = e1 + e2 - e0 - 2
Note: The grid overlap formula is applied when the columns have respondents in common, but
some (or all) appear in different rows. The grid table normally complies with the rule that there
is at least a multiple response categorical variable, or a grid or loop iterator, on both the side
and the top.
Statistical Formula for the Least Significant Difference Test
The formula for the least significant difference value for independent values is as follows:
in column i.
Weighted sum of the values in column i.
Weighted sum of the squared values in column i.
NCOL The number of columns in the group.

1348
Chapter 1

Figure 1-388
degrees of freedom
and the LSD value is:

Figure 1-389
lsd formula
where MS is the mean square:

Figure 1-390
HM is the harmonic mean:

Figure 1-391
and SIGVAL is the critical value of T for DOF degrees of freedom at the significance level
defined by the user.
Net Difference Test
The net difference test deals with each row independently and compares the difference between
the proportions in one pair of columns with the difference between the proportions in another pair
of columns. The result is tested for significance at the selected level. The results of the test
are displayed in a separate column.
For example, if the difference between the proportion of women preferring Brand A before
and after testing is larger than those preferring Brand B, and the difference between those two
proportions is significant at the selected level, the result is flagged as significant and the letter S is
displayed in the net difference column of the row for women.
1349
Base Professional
When you specify a net difference test, to specify which columns to test and where to place the
result, you must also add a ntd special element to your table, immediately after the four columns
you want to test. If the table is nested, this must be in the innermost nesting level.
When you specify a net difference test, to specify which columns to test and where to place the
result, you must also add a net difference item to the variable. If the table is nested, this must
be in the innermost nesting level.
carries out the test on the four columns preceding the net difference item.
How the results are displayed
The null hypothesis is that the two figures being compared are equal, that is, the difference
between them is zero. The following table shows the symbols that are displayed on the table
for different results.
Result Displayed
Significant at the selected level S
Significant at the lower selected level but not the higher level s
Not significant at the selected level(s), but significant at the 32% level NS
Not significant at the 32% level E
That is:
If the result of the test is significant at the specified significance level, places the letter S
in the additional column.
If you run the test at two significance levels, results that are significant at the higher level are
displayed using an uppercase S, and results that are significant at the lower level are displayed
using a lowercase s.
If the result of the test is not significant at the selected level(s), but is significant at the 32%
significance level (equivalent to a p value of 0.32 or a confidence level of 68%, indicating
that the difference between the figures being compared is at least one standard deviation
away from zero) IBM® SPSS® Data Collection Base Professional places the letters NS
If the difference between the figures being compared is not significant at the 32% significance
level (that is, the difference is less than one standard deviation away from zero) places the
letter E in the additional column.
Example of the Net Difference Test
Sample Script File: NetDifferenceTest.mrs
This example script is based on the SkiDemo sample data set. See Running the Sample Table
In this example, based on the SkiDemo survey installed with the IBM® SPSS® Data Collection
Developer Library, a new variable that combines categories from the ownski and repeat variables
forms the top of the table and the age variable forms the side.
1350
Chapter 1
Here is the script to add the test to the table:

TableDoc.Default.Statistics.Add("NetDifference")
TableDoc.Default.Statistics.NetDifference.SigLevel = 5
This is the section of script that creates the table:

TableDoc.Tables.AddNew("Table1", "!
class *
axis({element1 'own skis not visited before'
expression('ownski={own} and repeat={no}'),
element2 'own skis visited before'
expression('ownski={own} and repeat={yes}'),
element3 'rented skis not visited before'
expression('ownski={rented} and repeat={no}'),
element4 'rented skis visited before'
expression('ownski={rented} and repeat={yes}'), ntd()})
'Ski ownership and previous visits'
!", "Net difference test")
Notice the net difference element (ntd()) in the specification for the top axis.
Here is the resulting table:

Figure 1-392
Net difference test
The test is based on proportions; that is, it takes the value in each row as a proportion of the total
for the whole column. For each row (socio-economic class in this example) it finds the difference
for this value (the proportion of the whole column) between those who have not visited the resort
before and those who have visited before. It does this separately for two groups of people, those
who own their skis (the first and second columns) and those who rent them (the third and fourth
1351
Base Professional
columns). It then finds the overall difference between the two groups of people, ski owners and
ski renters. This results in a single value for each row, which is then tested against the base for the
column to see if it is significantly different from the column as a whole. If the result is found to be
significant for any row, an S is placed in the net difference column for that row.
The net difference test in this example shows that there is a significant difference for the AB
and the C2 socio-economic classes.
Details and Restrictions of the Net Difference Test
Columns to be tested must be defined in groups of four. If there are more than four categories
the net difference test is carried out on the preceding four category elements nearest the net
difference element. If there are fewer than four categories, the net difference test is not carried out.
The net difference test is not available across the different sections of a table that are created by
nesting and concatenation.
When you specify a net difference test, you must also add a net difference element to the top of the
table. If the table is nested, this must be in the innermost nesting level.
Statistical Formula for the Net Difference Test
The following table shows the formulae used for conducting the net difference test in IBM®
SPSS® Data Collection Base Professional.
Formula for Proportions
For any row, and any of the four columns being tested (i=1,2,3, and 4):
Wi Sum of the weights (weighted base) for column i.
Qi Sum of the squared weights for column i.
Ei = (Wi * Wi) / Qi Effective base for column i.
Pi Proportion in column i
For a table with overlap or a grid table, and any pair of columns from the four being tested (i
and j=1,2,3, and 4):
Wij Sum of the weights (weighted base) for respondents
in both columns.
Qij Sum of the squared weights for respondents in both
columns.
Eij = (Wij * Wij) / Qij Effective base for respondents in both columns.
Pij Proportion for respondents belonging in the row
being tested for both columns.
1352
Chapter 1
The formula is:

Figure 1-393
where
numer = (P3 - P4) - (P1 - P2)
and for a non-grid, non-overlap table

Figure 1-394
For a table with overlap or a grid table

Figure 1-395
where
Figure 1-396

Figure 1-397
where, for a non-grid, non-overlap table

Figure 1-398
and
1353
Base Professional
Figure 1-399

Figure 1-400
and
Figure 1-401
Formula for Means
For any row, and any of the four columns being tested (i=1,2,3, and 4):
Wi Sum of the weights (weighted base) for column i.
Qi Sum of the squared weights for column i.
Ei = (Wi * Wi) / Qi Effective base for column i.
Xi sum of values for column i
Yi sum of squared values for column i
Mi mean for column i=Xi/Wi
The values may be either numeric values or factor values.
For a table with overlap or a grid table, and any pair of columns from the four being tested (i
and j=1,2,3, and 4):
Wij Sum of the weights (weighted base) for respondents
in both columns.
Qij Sum of the squared weights for respondents in both
columns.
Eij = (Wij * Wij) / Qij Effective base for respondents in both columns.
1354
Chapter 1
The intermediate term SX is:

Figure 1-402
The tstat is
Figure 1-403
where
numer = (M3 - M4) - (M1 - M2)
and for a grid, non-overlap table,

Figure 1-404

Figure 1-405
where
Figure 1-406
For a non-grid table with overlap, Rij reduces to 1.
Grid tables
For a grid table, it is not possible to display the net difference if the mean is a numeric mean rather
than a factor mean. In this case, an error is returned.
1355
Base Professional
For a grid table with factor means:

Xi* The weighted sum of factors for column i for all
respondents belonging in the mean for column i and
in the base of column j.
X*j The weighted sum of factors for column j for all
respondents belonging in the mean for column j and
in the base of column i.
Yi* The weighted sum of squared factors for column
i for all respondents belonging in the mean for
column i and in the base of column j
Y*j The weighted sum of squared factors for column
j for all respondents belonging in the mean for
column j and in the base of column i
Yij The weighted sum of (factor for column i) * (factor
for column j) for all respondents belonging in the
mean for both columns.
Using the above terms

Figure 1-407
where
Figure 1-408
Degrees of freedom

Figure 1-409
where, for a non-grid, non-overlap table:

Figure 1-410
1356
Chapter 1
and
Figure 1-411
For a table with overlap or a grid table:

Figure 1-412
and
Figure 1-413
For more on the theory of overlapping samples, see Kish, L (1965), Survey Sampling, New York:
John Wiley and Sons. ISBN 0-471-48900-X.
Paired Preference Test
The paired preference test compares pairs of values to see whether the figures in each pair differ
significantly from each other. The paired preference item is usually specified in a row. However,
you can specify it in a column. The test works as follows:
If specified in a row, the paired preference test deals with each column independently and
compares pairs of rows. The test needs a minimum of two rows to be able to compare their
figures.
If specified in a column, the paired preference test deals with each row independently and
compares pairs of columns. The test needs a minimum of two columns to be able to compare
their figures.
For example, if the proportion of women preferring Brand A is larger than those preferring Brand
B, and the difference between the two proportions is significant at the selected level, the letter S is
displayed in the paired preference row of the column for women.
To specify which rows to test and where to place the result, add the ppt special element to your
table, immediately after the two rows you want to test, for example:
TableDoc.Tables.AddNew("Table2", "prefer{base(), prefer_dinosaurs, prefer_human_biology, ppt()} * gender", "Paired Preference Test")
To specify which rows to test and where to place the result, you need to add a paired preference
item to the row or column. For more information, see the topic To Add a Paired Preference
Test on p. 1314.
1357
Base Professional
To specify which rows to test and where to place the result, you need to add a paired preference
item to the row or column.
When a paired preference element is placed in a row or column, searches for the nearest two
categories preceding the paired preference item, and carries out the paired preference test on
those two categories. For the purposes of the paired preference test the following element types
are classed as “category” elements:
category
expression
net
combine
numeric
The result of the test is placed at the position of the paired preference row or column.
The following information assumes specification as a column.
How the results are displayed
The null hypothesis is that the two figures being compared are equal, that is, the difference
between them is zero. The following table shows the symbols that are displayed on the table
for different results.
Result Displayed
Significant at the selected level S
Significant at the lower selected level but not the higher level s
Not significant at the selected level(s), but significant at the 32% level NS
Not significant at the 32% level E
That is:
If the result of the test is significant at the specified significance level, places the letter S
If you run the test at two significance levels, results that are significant at the higher level are
displayed using an uppercase S, and results that are significant at the lower level are displayed
using a lowercase s.
If the result of the test is not significant at the selected level(s), but is significant at the 32%
significance level (equivalent to a p value of 0.32 or a confidence level of 68%, indicating
that the difference between the figures being compared is at least one standard deviation
away from zero) IBM® SPSS® Data Collection Base Professional places the letters NS
If the difference between the figures being compared is not significant at the 32% significance
level (that is, the difference is less than one standard deviation away from zero) places the
letter E in the additional column.
1358
Chapter 1
Examples of the Paired Preference Test
Sample Script File: PairedPreferenceTest.mrs
The first paired preference test in this example is carried out on the rows of the table. It tests
whether there is a significant difference between the numbers of people who prefer dinosaurs
and the numbers preferring human biology.
The script creates a table with Prefer on the side axis and Gender on the top axis:
TableDoc.Tables.AddNew("Table2", "prefer{base(), prefer_dinosaurs, prefer_human_biology, ppt()} * gender", "Paired Preference Test on Ro
The difference is seen to be significant for males and not significant for females.
Figure 1-414
Table showing paired preference test
The paired preference test is usually carried out on rows. However, you can also carry out the test
on columns. In this example, Age is nested within Gender. As this would create a very wide table
if this were on the top of the table, Prefer is placed on the top and the test is carried out on columns.
1359
Base Professional
Figure 1-415
Table showing paired preference test on columns
Running the Paired Preference Test at Two Significance Levels
You can carry out the paired preference test at two significance levels in the same table. The next
example creates a table with the Prefer variable on the side of the table, and the Similar variable
on the top of the table, with a paired preference test applied to the rows of the table. This tests
whether there is a significant difference between the numbers who prefer dinosaurs and those who
prefer human biology, broken down by whether the respondents have visited similar museums
before. This test is run at the 5% significance level, representing a 95% chance that the results are
statistically significant and not just due to chance.
1360
Chapter 1
Figure 1-416
Table showing paired preference test at one significance level
This is the script to create the table:
TableDoc.Tables.AddNew("Table4", "prefer{base(),prefer_dinosaurs, prefer_human_biology, ppt()} * {base(), Yes 'Yes', No 'No'}", "Paired Pre
TableDoc.Tables["Table4"].Statistics.Add("PairedPreference")
TableDoc.Tables["Table4"].Statistics.PairedPreference.SigLevel = 5
Notice that for those who answered No, the letters NS are placed in the Paired Preference column,
indicating that at the 5% significance level the difference in the numbers who prefer dinosaurs and
those who prefer biology is not significant.
The next example shows the table when the test is run at both the 5% and the 10% level. The
10% significance level indicates a lower level of confidence, representing a 90% chance that the
results are statistically significant and not just due to chance.
Figure 1-417
Table showing paired preference test at two significance levels
1361
Base Professional
This is the script to create the table:
TableDoc.Tables.AddNew("Table5", "prefer{base(),prefer_dinosaurs, prefer_human_biology, ppt()} * similar {base(), Yes 'Yes', No 'No'}", "Pa
TableDoc.Tables["Table5"].Statistics.Add("PairedPreference")
TableDoc.Tables["Table5"].Statistics.PairedPreference.SigLevel = 5
TableDoc.Tables["Table5"].Statistics.PairedPreference.SigLevelLow = 10
Notice that for those who answered No the lowercase letter s is placed in the Paired Preference
column. This indicates that the difference in numbers of those who prefer dinosaurs and those
who prefer biology is significant at the lower (10%) level.
Details and Restrictions of the Paired Preference Test
The paired preference test is not suitable for all tables. It is up to you to make sure that the data in
the table is generally suitable for testing, that the sample size is suitable, etc.
The paired preference element is usually specified in a row to compare two rows for each column
independently. However, you can specify it in a column to compare two columns for each row
independently. The following information assumes specification as a row.
Rows. The test searches for the nearest two categories preceding the paired preference row (or
column) to perform the test on, but it stops searching at a base or another paired preference
item, and if it has not found two categories by then it does not perform the test. The test ignores
categories at a different net level.
Columns. The test works independently on all columns.
Sample size. This test relies on a large sample, which means that it may not be valid for a small
sample—for example, fewer than about 30 cases. checks for small sample sizes, and does not
carry out the test on columns with a base below 30. You can change the minimum sample size if
required, using the MinBase property.You can change the minimum sample size if required, by
entering a new value in the Minimum Base field in the Preferences tab.You can change the minimum
sample size if required, by entering a new value in the Minimum Base field in the Statistics tab.
Multiple response variables. The test is invalid if the two rows being tested can have overlap (that
is, one person can belong in both of them). However, there is no way that IBM® SPSS® Data
Collection Base Professional can check for this.
Two-tailed test. This is a two-tailed test, which means that it reports all significant differences
between the proportions in all of the columns regardless of which row contains the greater
proportions.
1362
Chapter 1
Statistical Formula for the Paired Preference Test
The paired preference element is usually specified as a row element to compare two rows for each
column independently. However, you can specify it as a column element to compare two columns
for each row independently. The following information assumes specification as a row.
The following table shows the formulae used for conducting the paired preference test in .
wo Sum of the weights for the column.
w o2 Sum of the squared weights for the column.
eo = (wo)2 / wo2 Effective base for the column.
ci Sum of the weights for the cell in the ithrow.
cj Sum of the weights for the cell in the jth row.
pi = ci/wo Column proportion in the ithrow.
pj = cj/wo Column proportion in the jthrow.
Test Statistic
Under the null hypothesis Ho : pi = pj
the paired preference test statistic is calculated using the following expression:
The test is undefined if pi = pj = 0 or if eo < 2.
P values
p values are computed using the t distribution with eo -1 degrees of freedom.
References
Kish, L (1965), Survey Sampling, New York: John Wiley and Sons. ISBN 0-471-48900-X.
Product Difference Test
The product difference test is not a separate statistical test in its own right. Instead, it enables
you to apply statistical testing (using the column proportions or column means tests) to all
combinations of categories in a number of variables. One use for this is to identify those attributes
of tested products that show significant differences between products.
The test creates a table specification by breaking down a number of variables, known as difference
attributes, added to the side of the table, and creating a separate row for each category in each
variable, and for each combination of categories from the variables.
1363
Base Professional
For example, if you use the variables education and biology as difference attributes, the test
first creates one row for each category (for simplicity, these examples omit the Not Answered
categories, but if you choose to include them the table will also include rows for those categories):
education Yes
education No
biology Yes
biology No
If you request two combinations of difference attributes, it also creates a row for each combination
of categories in the two variables to give the following rows:
education Yes
education No
biology Yes
biology No
education Yes biology Yes
education Yes biology No
education No biology Yes
education No biology No
Having created the side of the table, the test applies the column proportions and/or column means
test to the table, using the columns in the variable specified on the top of the table. The test also
hides any rows that do not contain significant results, and sorts the rows by significance. The
end result is a table that displays a detailed breakdown of significant results by combination of
categories.
Adding an inner side variable
You can further break down the analysis of the difference attributes by placing another variable
(known as the inner variable) on the side of the table. Instead of creating one row for each single
category and combination of categories, creates a whole section. For example, you could add
gender as the inner variable to give the following rows:
education Yes gender Base
education Yes gender Male
education Yes gender Female
education No gender Base
education No gender Male
education No gender Female
biology Yes gender Base
biology Yes gender Male
biology Yes gender Female
biology No gender Base
biology No gender Male
biology No gender Female
education Yes biology Yes gender Base
education Yes biology Yes gender Male
education Yes biology Yes gender Female
education Yes biology No gender Base
education Yes biology No gender Male
1364
Chapter 1
education Yes biology No gender Female

education No biology Yes gender Base
education No biology Yes gender Male
education No biology Yes gender Female
education No biology No gender Base
education No biology No gender Male
education No biology No gender Female
Rows are also created for the base of the inner variable and for non-categorical items such
as means.
You can configure the test so that it displays all results, or only those results that are statistically
significant.
The statistical formulae for the test are as shown for the column proportions and the column
means test. See Statistical Formula for the Column Proportions Test and Statistical Formula
for the Column Means Test.
Example of the Product Difference Test
Sample Script File: ProductDifferenceTest.mrs
The examples in this topic are based on the Museum sample data set. See Running the Sample
Table Scripts for information on running the example scripts.
The product difference test in this example is based on a table with gender on the side of the
table (the inner variable) and prefer on the top of the table. Three difference attributes are used:
education, biology, and before.
The test uses the “three combinations” option (though note that, in this case, the results are the
same as for one combination; that is, no additional significant results are found using two and
three combinations). Each category from each attribute variable is combined with each item in the
side variable. The default settings are used so that the test applied is the column proportions test,
with the default significance levels of 5% and 10%, and default minimum base and small base
settings of 30 and 100 respectively.
1365
Base Professional
Figure 1-418
Product difference test on table of gender by prefer, difference attributes are education, biology, before
The script begins by specifying the number of variables to combine on the side of the table (also
known as difference attributes) in the NSide variable. It also specifies the number of variable
combinations to apply in the NCombs variable:
Dim NSide, NCombs

NSide = 3
NCombs = 3
In this case, three difference attribute variables will be used, and three combinations will also
be used. This means that a row will be created for all combinations of each category in three
variables. Note that when a combination value greater than 1 is used, lower combinations are also
included, for example, in this case, one- and two- variable combinations are also created.
The script then specifies a single top variable, a SideInner variable, which is an additional side
variable that creates a further layer of combinations over and above those specified by the NCombs
variable, and three SideVars, which identify the three variables to use as the difference attributes:
Dim TopVar, SideInner, SideVars[20]

TopVar = "prefer"
SideInner = "gender"
SideVars[0] = "education"
1366
Chapter 1
SideVars[1] = "biology"
SideVars[2] = "before"
The script then adds an empty side axis variable called MainSide to the table, and creates a side
elements collection:
TableDoc.Tables.AddNew("T1", "axis({}) as MainSide * " + TopVar)

SideEls = TableDoc.T1.Side.MainSide.Elements
SideElno = 0
The script then builds up the side element specification using functions to create an element
for each combination of categories in the selected SideVar variables. If a SideInner variable is
specified, as in this example, each combination is further expanded by combining it with each
category in the SideInner variable. The result is a side axis containing a row for each category
combination.
The cell items for the table are adjusted to include a column base cell item as the first item on the
table. This is required because otherwise the base would not be visible on the finished table:
TableDoc.T1.CellItems.Clear()
TableDoc.T1.CellItems.AddNew(24, 0)
TableDoc.T1.CellItems.AddNew(1, 1)
A column proportions test is added to the table:
Dim SigLev
SigLev = 10.0
TableDoc.T1.Statistics.Add("ColumnProportions")
TableDoc.T1.Statistics["ColumnProportions"].SigLevel = SigLev
The script displays the minimum p value in a separate column on the table, and sorts the table in
ascending order based on the value in this column:
TableDoc.T1.Statistics.ShowMinPVal = True
TableDoc.T1.SortColumn = TopVar + "{MinPVal}"
TableDoc.T1.SortColumn.Order = 0
In addition, a hide rule suppresses any rows where the minimum p value is greater than a value
equivalent to the significance level (siglevel/100). This has the effect of hiding any rows that are
not significant at the selected level:
Dim R
Set R = TableDoc.T1.Rules.AddNew()
R.Type = 0 ' hide
R.Target = 0 ' row
R.CellItemRef = 1 ' if cellitem 1 (1st non-base one)
R.Operator = 4 ' is greater than
R.Value = SigLev / 100.0 ' siglevel / 100
R.ElementRef = TopVar + "{MinPVal}" ' for MinPVal column
R.IgnoreSpecialElements = False ' hide specials as well
1367
Base Professional
Note that, as the table includes a base count in the first cell item position (position 0) the hide rule
is based on the second cell item in the table (R.CellItemRef = 1).
Details and Restrictions of the Product Difference Test
Table Structure. The product difference test can be applied to tables that contain either no variables
or a single variable on the side of the table, and a single variable on the top of the table.
Statistical tests. The product difference test can be run using the column proportions and/or
column means test. By default the column proportions test is used.
Attribute combinations. You can use one, two, or three combinations of attributes. If a variable is
present on the side of the table, this forms an additional combination, and is used as the inner nest
variable; that is, the categories in this variable are changed first as the table rows are built up.
Variable types. Only categorical variables can be used to form the table and the difference
attributes.
T-test Test
The T-Test test is used to determine whether the mean of a numeric variable is significantly
different from zero or some other specified value. The test may also be used to test for differences
between means measured on matched samples (paired T-test), for example, between the means of
two variables both obtained from the same sample of respondents. Examples can include trials
of two drugs where the same person receives each drug at different times and observations are
taken on their resulting condition after using each drug. The test might also be employed to study
a comparison of a group of students’ competencies in two areas (verbal and mathematical, for
example) by analyzing two sets of test results.
The pairing of data must be taken into account as, for example, it is necessary to adjust for each
particular patient’s general reaction to treatments; similarly for each pupil’s overall academic
competence (students obtaining better marks in one test could be more likely to do well in the
other).
Example of the T-test Test
Sample Script File: TTestTests.mrs
The T-test test in this example determines whether:

The number of visits in the last twelve months is significantly different from zero for each
category in age.
The total number of visits is significantly different from six for each category in age.
1368
Chapter 1
The difference in numeric rating values for dinosaurs and mammals is significantly different
from zero for each category in age.
The entrance rating for fossils is significantly different from zero, once the factors have been
reset from (1 to 5) to (-2 to 2), for each category in age.
The first test determines if the number of visits in the last twelve months is significantly different
from zero for each category in age.
The script creates a table with visits12 on the side axis and age on the top axis:
Set Tab = TableDoc.Tables.AddNew("T1", _
"axis({base(), _
mean(visits12) [Decimals=2], _
stderr(visits12) [Decimals=2], _
tvalue(visits12), _
tprob(visits12)}) _
* age", _
"T-test on mean of numeric visits12")
Tab.Side.SubAxes[0].Label = "Visits in the last 12 months"
Figure 1-419
Table showing T-test test
The second test determines if the total number of visits is significantly different from six for
each category in age.
The script creates a table with visits6 on the side axis and age on the top axis:
Set Visits6 = MdmDoc.CreateVariable("visits6", "Visits minus 6")
MdmDoc.Fields.Add(Visits6)
Visits6.DataType = 1 ' Long
Visits6.SourceType = 2 ' Expression
Visits6.Expression = "visits - 6"
"axis({base(), _
mean(visits6) [Decimals=2], _
stderr(visits6) [Decimals=2], _
tvalue(visits6), _
1369
Base Professional
tprob(visits6)}) _
* age", _
"T-test on mean of derived numeric (visits - 6)")
Tab.Side.SubAxes[0].Label = "Visits minus 6"
Figure 1-420
The third test determines if the difference in numeric rating values for dinosaurs and mammals is
significantly different from zero for each category in age.
The script creates a table with dinmam on the side axis and age on the top axis:
Set Dinmam = MdmDoc.CreateVariable("dinmam", "Dinosaurs minus mammals")

MdmDoc.Fields.Add(Dinmam)
Dinmam.DataType = 1 ' Long
Dinmam.SourceType = 2 ' Expression
Dinmam.Expression = "dinosaurs - mammals"
"axis({base(), _
mean(dinmam) [Decimals=2], _
stderr(dinmam) [Decimals=2], _
tvalue(dinmam), _
tprob(dinmam)}) _
* age", _
"T-test on mean of derived numeric (dinosaurs - mammals)")
Tab.Side.SubAxes[0].Label = "dinosaurs - mammals"
Figure 1-421
1370
Chapter 1
The fourth test determines if the entrance rating for fossils is significantly different from zero,
once the factors have been reset from (1 to 5) to (-2 to 2), for each category in age.
The script creates a table with rating_ent[{fossils}] on the side axis and age on the top axis:

"rating_ent[{fossils}].column{.., _
mean() [Decimals=2], _
stderr() [Decimals=2], _
tvalue(), _
tprob()} _
* age", _
"T-test on mean of factors")
Set Ax = Tab.Side.SubAxes[0]
Set El = Ax.Elements["Not_at_all_interested_1"]
El.Label = "Not at all interested (-2)"
El.Factor = -2
Set El = Ax.Elements["Not_particularly_interested_2"]
El.Label = "Not particularly interested (-1)"
El.Factor = -1
Set El = Ax.Elements["No_opinion_3"]
El.Label = "No opinion (0)"
El.Factor = 0
Set El = Ax.Elements["Slightly_interested_4"]
El.Label = "Slightly interested (1)"
El.Factor = 1
Set El = Ax.Elements["Very_interested_5"]
El.Label = "Very interested (2)"
El.Factor = 2
Figure 1-422
1371
Base Professional
Details and Restrictions of the T-test Test
T-test usage
The T-test test is not suitable for all tables.

The value of T will be zero if there is no difference in the data.
The simplest use of the one-sample T-test is when testing whether the mean of a variable
already coded in columns of the data is zero.
There may be occasions when you want to use a one-sample T-test on values that are not the
same as those in the data.
To test whether a mean may be different from a non-zero value, subtract that value from each
data value. In other words, to test whether the mean number of visits to a supermarket is equal
to 2, you actually test whether the mean of (number of visits to supermarket – 2) is equal to 0.
To make a paired test between two data values, test whether the difference between them is
zero.
Statistical Formula for the T-test Test
In the formulae for axis-level test statistics, the formula is applied separately to the counts in each
column or row, according to whether the axis containing the stat= option is the row or column axis.
The number of basic count elements in the axis
or segment.
The (weighted) count in the ith cell of a row or
column representing that axis.
The (weighted) base of the row or column.
The unweighted base of the row or column.
Sum of factors
Mean
1372
Chapter 1
Standard deviation
Standard error of mean
One-sample and paired T-Test
is tested against Student’s t-distribution with N - 1 degrees of freedom.
Tukey Test
The Tukey test uses the Studentized range statistic to make all pairwise comparisons between
groups. The test sets the experimentwise error rate at the error rate for the collection for all pairwise
comparisons. The Tukey test is most effective when testing a large number of pairs of means.
The test performs well in terms of keeping the significance level of the simultaneous pairwise tests
at the prescribed level. For homogeneous subset testing, the test uses the harmonic sample mean
Qh and exhibits large errors in reported significance level for strongly unbalanced designs where
the group sample sizes are very different. The test is not recommended for use with such designs.
Example of the Tukey Test
Sample Script File: TukeyTest.mrs
This example script is based on the Ski Demo IBM® SPSS® Quantum™ data set. See Running
the Sample Table Scripts for information on running the example scripts.
Note: The Ski Demo Quantum data set is smaller than data sets normally used with the Tukey
Test. The Tukey Test allows for the testing of a large number of means. The Ski Demo Quantum
data set only provides four means.
The Tukey test in this example determines if there are significant differences in tour company
ratings between varying social classes. The detailed, diagnostic output in the .csv file contains
the results of Homogeneous Subset Detection (cannot be displayed in the table output). The
detailed output for table two indicates homogeneous subsets, as it contains overlap between
two detected subsets.
1373
Base Professional
The script adds the test to a single tables as follows:
Set Tab = TableDoc.Tables.AddNew(....)

Tab.Statistics.Add("Tukey")
The script adds the test to all tables as follows:
TableDoc.Default.Statistics.Add("Tukey")
Figure 1-423
Table showing Tukey test
When a Tukey test is requested, IBM® SPSS® Data Collection Base Professional creates a cell
item position for it, in the same way that it does for the results of the column proportions and
column means tests. This cell item is created as the last item, or the last item before the column
proportions/column means item (when both statistics requested on the table).
The following diagnostic information shows the Homogeneous Subset Detection for Table 2.
1374
Chapter 1
Figure 1-424
Diagnostic information showing Homogeneous Subset Detection for Table 2
Details and Restrictions of the Tukey Test
Tukey properties
The Tukey test provides the following optional properties:

Property Default Value
SigLevel 5
SigLevelLow none
MinBase 30
SmallBase 100
Tukey usage
The Tukey test is not suitable for all tables. When you request the test on a table that is structurally
unsuitable, IBM® SPSS® Data Collection Base Professional simply skips the test, leaves the
Tukey and p value rows blank, and writes an explanation to the diagnostics data. It is up to
you to make sure that the data in the table is generally suitable for testing, that the sample size
is suitable, etc.
displays a message if you define a Tukey test on an unsuitable table or if you change a table that has
a Tukey test defined so that it is no longer suitable for the test. When this happens, you can either
adjust the table so that it conforms to the restrictions, or you can remove the test from the table.
Rows and columns. The test is allowed only when the columns are independent (the columns do
not overlap). The test is not allowed on tables where there is overlap between the columns, which
includes all grid tables. The test is ignored when any of the test columns are empty, or when a
column’s base value is smaller than the minimum base value.
The test is only be implemented for rows of means. It is not implemented for rows of proportions.
1375
Base Professional
Effective base. The test does not use the effective base. In an unweighted table the test uses the
unweighted figures; in a weighted table the test uses the weighted figures.
Other Tests. The Tukey test is disallowed on a table that already includes the Column Means
and/or Column Proportions tests, because there would be no way to identify to which test the
significance letters refer.
Homogeneous subset detection
Homogeneous subset detection is included in the table builder, but the results can only be
displayed in the diagnostics file.
The pairwise test for whether two means are significantly different is:
mean2 - mean1 > Q(i,j) * threshold-value
while the test for whether two means do not belong in the same homogeneous subset is:
mean2 - mean1 > Q(h) * threshold-value
It is possible for the pairwise output to deem that two means are significantly different, while the
homogeneous subset detection deems they belong in the same subset - or conversely, that they
are not significantly different but belong in different subsets.
Statistical Formula for the Tukey Test

Number of levels for an effect.
j-th observation at i-th level.
Harmonic mean of the sample size.
Number of observations at level i, i=1,...,k.
Mean at level i, i=1,...,k.
Sum of squares at level i, i=1,…k.
Pooled standard deviation from all levels.
Degrees of freedom for the within-groups mean

square.
Experimentwise error rate under the complete
null hypothesis.
1376
Chapter 1
Number of steps between means.
The upper-ε critical point of the Studentized

range distribution.
Range values
for all values of r.
When finding the critical value Rε,r,f for any pair of means r columns apart, the value Sε,k,f is
always used where k is the total number of columns. The lookup table for ε is queried to find the
value in the appropriate row for f and the appropriate column for k, regardless of the value of r.
The confidence intervals of the mean difference are calculated using Qi,j instead of Qh.
For all pairs of means
For any two means i and j being tested
Constructing homogeneous subsets
Note: Homogenous subsets are only available via diagnostics.
The outermost pair of means have a significant range if:

1377
Base Professional
If so, test whether:
Once a whole set is found to be nonsignificant testing stops.
Each time a range proves nonsignificant, the means involved are included in a single group
(homogeneous subset). This mean that the columns within a nonsignificant range should be
combined into a single column and the test reapplied with the collapsed sets of columns.
Multiple comparisons test for all possible pairs
for all i < j.
Diagnostics Information
When you run a statistical test on a table, you can optionally write out diagnostics information
that shows the p values and some of the intermediate figures used to calculate the statistics. The
information is in comma-delimited format, so you can open it in Microsoft Excel and perform
calculations on the data.
The diagnostics file contains information for each table that contains a statistical test. The first
line of the section describes the table, whether there is overlap in the columns tested, whether the
table is weighted or unweighted, and whether the effective base was used. This is followed by
additional information for each test.
The first column indicates the type of test:

CHI. The chi-square test and/or Fisher’s exact test.
CPT. The column proportions test.
CMN. The column means test.
NTP. The net difference test for a category row.
NTM. The net difference test for a mean row.
PPT. The paired preference test.
The remaining information is different for each test.
You can write the diagnostics information to a text file using script similar to the following:
'Enable the generation of diagnostics information for the statistical test

TableDoc.RawStatisticsDataEnabled = True
'Create and populate the tables as required

'...
1378
Chapter 1
' Write out the diagnostics information for the statistical tests
Dim fso, txtfile
Set txtfile = fso.CreateTextFile("StatisticalTestsDiagnostics.csv", True)
txtfile.WriteLine(TableDoc.RawStatisticsData)
txtfile.Close()
Giving the text file a .csv filename extension makes it easy to subsequently open the file in Excel.
For details of how to view diagnostics information, see To View Diagnostics Information for
Statistical Tests
Diagnostics Information: Chi-Square Test
When you run a statistical test on a table, can create diagnostics information that shows the p
values and some of the intermediate figures used to calculate the statistics. The information is in
comma-delimited format, so you can open it in Microsoft Excel and perform calculations on the
data. The information varies according to the test. Here is the information for the chi-square test
example:
Figure 1-425
Diagnostics information for chi-square test example
formula. Displays the name of the formula used.
rows/cols. These indicate the category rows and columns that the test was performed on.
chisqd. The chi-square value.
chidof. The degrees of freedom.
pval. The p value.
The above example uses the Pearson test. When the Yates’ correction is used, the following
columns are also present:
absterm. The absolute value of the product of one diagonal minus the product of the other
diagonal. When the absterm value is less than the halfsum value, the Yates’ value is not calculated
and the chi-square value is set to zero.
halfsum. Half the sum of frequencies in all the cells.
fisher2. The two-tailed probability of chi-square as calculated by Fisher’s exact test.
fisher1. The one-tailed probability of chi-square as calculated by Fisher’s exact test.

1379
Base Professional
Diagnostics Information: Cell Chi-Square Test
When you run a statistical test on a table, can create diagnostics information that shows the
p values and some of the intermediate figures used to calculate the statistics. The information
is in comma-delimited format, so you can open it in Microsoft Excel and perform calculations
on the data. The information varies according to the test. Here is the information for the cell
chi-square test example:
Figure 1-426
Diagnostics information for cell chi-square test example
The above example uses the Pearson test with the Yates’ correction (when required).
Note that the diagnostic information for the cell chi-square test includes information for every
table cell.
formula. Displays the name of the formula used.
rows/cols. These indicate the category row and column that the test was performed on.
chisqd. The chi-square value.
chidof. The degrees of freedom.
pval. The p value.
1380
Chapter 1
siglevel. The significance level.
sample. The sample size.
Diagnostics Information: Column Proportions Test
on the data. The information varies according to the test. Here is the information for the first
column proportions test example:
Figure 1-427
Diagnostics information for column proportions test example
row/cols. This is in the form nxy, where n represents the category row (the first category row is 1,
the second category row is 2, etc.) and x and y are the IDs of the pair of columns.
pval. The p value.
tval. The t value.
dof. The degrees of freedom.
se. The standard error.
sig. The significance level chosen for the test.
p1, p2. The proportions in the two columns.
r1, r2. The counts in the two cells. If the table is weighted, these are weighted.
w1, w2. The bases in the two columns. If the table is weighted, these are weighted.
e1, e2. The effective base in the two columns. These are the same as the bases if the effective
base option was not used.
1381
Base Professional
Diagnostics Information: Column Means Test
When you run a statistical test on a table, can create diagnostics information that shows the p
values and some of the intermediate figures used to calculate the statistics. The information is
in comma-delimited format, so you can open it in Microsoft Excel and perform calculations on
the data. The information varies according to the test. Here is the information for the column
means test example:
Figure 1-428
Diagnostics information for column means test example
row/cols. This is in the form nxy, where n represents the category row (the first category row is 1,
the second category row is 2, etc.) and x and y are the IDs of the pair of columns.
pval. The p value.
tval. The t value.
m1, m2. The means in the two columns.
xx1, xx2. The weighted sum of squared values in each column (Yi).
x1, x2. The weighted sum of values in each column (Xi).
n1, n2. The weighted count of cases in the mean row in each column (wi).
e1, e2. The effective base in the two columns. These are the same as the bases if the effective
base option was not used.
Diagnostics Information: Net Difference Test
on the data. The information varies according to the test. Here is the information for the Net
difference test example:
row/cols. This is in the form n/(3-4)-(1-2), where n represents the category row (the first category
row is 1, the second category row is 2, etc.) and 1, 2, 3, and 4 are the IDs of the four columns.
pval. The p value.
tval. The t value.
1382
Chapter 1
eb. The effective base for the column.
p1, p2, p3, p4. The proportion in columns 1, 2, 3, and 4.
r1, r2, r3, r4. The counts in columns 1, 2, 3, and 4.
w1, w2, w3, w4. The sum of weights (weighted base) for columns 1, 2, 3, and 4.
e1, e2, e3, e4. The effective base in columns 1, 2, 3, and 4.
Diagnostics Information: Paired Preference Test
on the data. The information varies according to the test. Here is the information for the paired
preference test example:
Figure 1-429
Diagnostics information for the paired preference test
The paired preference test in the above example is specified as a row in the test on Table2 and as a
column in the test on Table3. The following information assumes specification as a row.
1383
Base Professional
rows/col. This is in the form a + b / c, where a and b are the rows being tested, numbered starting
from 0, corresponding to those displayed in the table, and c is the column being tested, numbered
starting from 0, corresponding to those displayed in the table.
pval. The p value.
tval. The t value.
denom. The denominator of the t value.
sig. The significance level selected for the test.
n. The count in the base row for the column. If the table is weighted, this is weighted.
eb. The effective base for the column.
p1, p2. The proportion in rows 1 and 2.
r1, r2. The counts in the two cells.
1384
Chapter 1
Diagnostics Information: Tukey Test
When you run a statistical test on a table, can create diagnostics information that shows and some
of the intermediate figures used to calculate the statistics. The information is in comma-delimited
format, so you can open it in Microsoft Excel and perform calculations on the data. The
information varies according to the test. Here is the information for the Tukey test example:
Figure 1-430
Diagnostics information for Tukey test example
threshold. The threshold value: Se,k,f.

qh_critval.QhSe,k,f
1385
Base Professional
qh.Qh
spp. Root mean square error.
mse. The mean square error.
ncol. The number of levels.
siglev. The significance level.
cols. The column labels.
diffmean. The difference of the mean value.
q12-critval.Qi,jSe,k,f
q12.Qi,j
stderr. The standard error for mean difference.
lowbnd. The confidence interval lower bound.
uppbnd. The confidence interval upper bound.
mean 1.X¯i
mean2.X¯j
p Values
The p (probability) value is the basis for deciding whether or not there is a relationship between
the data being tested. Generally you start with the null hypothesis, which is the assumption that
there is no relationship between the data. If the p value is small enough (usually less than 0.05 or
0.01), you can reject the assumption of no relationship and conclude that there is a relationship.
A full list of the p values for each pair of columns tested in each row is available in the
diagnostics information file for the table. See Diagnostics Information for further details. IBM®
SPSS® Data Collection Base Professional reports p values as a decimal value with six decimal
places (although trailing zeroes after the decimal symbol are not displayed by default when you
open the file in Microsoft Excel). A reported p value of 0.05 is equal to a significance level of
5%. If the p value is smaller than the significance level you select for the test, the test statistic is
significant.
The p value is also called the observed significance level.
1386
Chapter 1
Figure 1-431
p values for the column proportions test example
This example shows the p values for the first column proportions test example. It shows the
row/cols and pval columns from the diagnostics data with the addition of the row labels. In the
example, the column proportions test was run at the 5% significance level, and one row—Human
biology—was found to be significant. Notice that the p value in this row is 0.009396. This is
the only row with a p value of less than 0.05.
Adding a Minimum p Value to a Table
This example creates a table with the column proportions test. The table is similar to the first
example in Examples of the Column Proportions Test, with the addition of a column displaying
the minimum p value for each row. The rows are sorted in ascending order of the p value.
The script adds the minimum p value column to the table and sort the rows in ascending order
based on the value of that column:
TableDoc.Table6.Statistics.ShowMinPVal = True
TableDoc.Table6.SortColumn = "gender{MinPVal}"
TableDoc.Table6.SortColumn.Order = 0
1387
Base Professional

Figure 1-432
Column proportions test, table sorted by the minimum p-value
The next example shows a table with a similar specification, but in addition, rows where the
p value is greater than 0.05 have been hidden.
This is the script to hide the rows:
Set R = TableDoc.Table7.Rules.AddNew()
R.Type = 0 ' hide
1388
Chapter 1
R.Target = 0 ' row

R.CellItemRef = 0 ' if cellitem 0 (counts)
R.Operator = 4 ' is greater than
R.Value = 0.05 ' 0.05
R.ElementRef = "gender{MinPVal}" ' for MinPVal column
R.IgnoreSpecialElements = False ' hide specials as well

Figure 1-433
Column proportions, non-significant rows hidden
Only two rows are displayed, as these are the only rows where the results are significant at a
p value of 0.05 or less. This corresponds to the 5 percent significance level selected for the
test for this table.
Weighted Data
When you run statistical tests on weighted tables, the test is always run on the weighted counts. If
you want to run the tests on the unweighted data, you must first remove the weighting.
When the table is weighted, you can optionally use a special base called the effective base.
This option is selected by default. The effective base is designed to reduce the likelihood of the
statistical tests producing significant results because of the adjustments made by weighting; the
effective base takes these adjustments into account.
The effective base is also a test of how good the weighting is. If the weighting is inflating the
answers from a particular group by a large factor, the effective base tends to be much smaller than
both the unweighted and the weighted base. The closer the effective base is to the unweighted
base, the better the weighting is.
The effective base is calculated by dividing the squared sum of weights for all of the respondents
in the weighting matrix table by the sum of the squared weights.
1389
Base Professional
The Statistics.UseEffectiveBase property controls whether the effective base is used. The property
is set to True by default. You can deselect the option by setting the property to False. For example:
TableDoc.Tables.MyTable.Statistics.UseEffectiveBase = False
The option to use the effective base is selected by default. You turn it off by deselecting the Use
Effective Base option on the Statistics tab of the
The option to use the effective base is selected by default. You turn it off by deselecting the Use
Effective Base option on the Preferences tab. For more information, see the topic Requesting
Statistical Tests on p. 1311.
You can display the effective base on a table by adding an EffectiveBase element to a variable’s
axis expression. For example:
age{base(), effectivebase(), ..}
You cannot directly enter an expression on the effective base. The calculation of the effective
base is based on the preceding base and uses any expression attached to the base. For example,
in this axis expression the effective base includes only male respondents, as specified in the
base expression:
age{base('gender={Male}'), effectivebase(), ..}
Reference
For an article that describes some methods of adjusting the base to take into account weighting,
see Potthoff R., WoodBury M., Manton G. (1992). “Equivalent Sample Size” and “Equivalent
Degrees of Freedom” Refinements for Inference Using Survey Weights Under Superpopulation
Models, Journal of American Statistical Association, V87, 383-396. This article has an “equivalent
sample size” (formula 1.6) that is the same as the effective base.
Displaying an Effective Base on a Weighted Table
This example displays a table weighted by the genbalance weight variable. A column proportions
test is applied and the effective base is displayed. Here is the script to display the table:
.AddNew("Table8", "museums{effectivebase(), ..Northern_Gallery} * gender", _

"Weighted Table of Museums by Gender with column proportions test")
TableDoc.Table8.Statistics.Add("ColumnProportions")
TableDoc.Table8.Statistics.ColumnProportions.SigLevel = 10
1390
Chapter 1
museums{effectivebase(),..Northern_Gallery}
Figure 1-434
Weighted table with column proportions test and effective base
Overlapping Data
Most of the statistical tests are based on standard t tests that assume that the two samples being
compared are independent of each other. When the columns of a table are formed from the
categories of a multiple response variable, data from the same case can be present in both of the
columns being tested. This is known as overlapping data, and it means that the two samples
cannot be considered independent.
For example, the multiple response variable museums is based on the following question, for
which respondents can select any number of responses. When this variable is on the top of a table,
respondents who selected more than one response appear in more than one column.
Figure 1-435
Museums question: “Which museums or art galleries have you visited or do you intend to visit?”
1391
Base Professional
When the columns of a table are formed from the categories of a single response variable, the
data in the columns are mutually exclusive, although this does not necessarily guarantee that
they are independent.
can perform the column proportions and column means tests on overlapping data because it
can detect overlapping data in the columns being tested and use a formula to compensate for the
fact that some cases appear in more than one column. The chi-square test cannot be performed
on overlapping data.
For more on the theory of overlapping samples, see Kish, Survey Sampling. (Kish, L. Survey
Sampling. New York: John Wiley and Sons. ISBN 0-471-48900-X.)
Hierarchical Data
All of the statistical tests are based on the assumption that the samples being compared are
independent of each other. However, in hierarchical data, there is normally a relationship
between the lower levels and the higher levels, which means that cases at the lower level are not
independent of each other. For example, you would not expect the voting patterns of the members
of a household to be totally independent of each other, nor would you expect the various journeys
or shopping trips made by an individual to be unrelated to each other. These relationships mean
that the underlying assumptions required for the statistical tests are almost never satisfied when
you run the tests on lower level data.
Therefore, when you are working with hierarchical datausing the hierarchical view, changes the
specified table level (a warning message is not provided) if any of the variables included in the
table are from a lower level.
Selecting Columns to Test
For the column proportions and column means tests, by default columns are tested in groups that
are determined by the structure of the table. For example, in a table with three categories in the
column variable, columns would be labeled A, B, and C, and the test would be carried out on all
combinations of columns A-C. In nested tables, the columns of the inner nest level are repeated
(and given unique IDs), and the test is carried out for each set of columns within the nesting level.
All combinations of the columns that you specify are tested. Separate the column IDs using a
forward slash character, for example:
This tests all combinations of columns A, B, and C.
You can specify separate groupings of columns to test by separating groups of columns with a
comma, for example:
This tests all combinations of columns A, C, and E, and all combinations of columns B, D, and F.
Columns that you do not include are omitted from the tests. If you do not specify columns to
test, the default column groupings are used.
1392
Chapter 1
Note: If you specify columns to test, ensure that the column IDs you specify exist in the table, and
that they correspond to valid combinations of columns to test. You can check this by running the
test first using the same table specification but with the default column selection.
ColumnsID property
Starting with IBM® SPSS® Data Collection Base Professional 5.6 you can define column IDs
as a string using the ColumnsID property. Each character in the string is used to allocate a
column ID, with a period or space character used to indicate that an ID should not be allocated.
A character needs to be added to the ID’s string for each column, even if the column is hidden.
When allocating column IDs a character should also be added for the base columns.
For the table below, the column IDs could be set as follows to test Yes-Male against No-Male,
and Yes-Female against No-Female:
Table.Statistics.ColumnIDs = "....MF.NG"
Table.Statistics.TestColumns = "M/N, F/G"
Figure 1-436
Column Proportions Test with New Column IDs
Setting the Significance Levels
By default, the column proportions, column mean, net difference test, and paired preference tests
are run at the 5% significance level. However, you can optionally run a test at another significance
level, such as the 10% or 1% significance level.
You can also run the test at two significance levels on the same table. In the resulting table, the
IDs of columns that are significant at the higher level appear in upper case, and those that are
significant at the lower level appear in lower case.
1393
Base Professional
You select this option using the SigLevel statistics property. For example:
TableDoc.Tables.MyTable.Statistics[0].Properties["SigLevel"] = 1
The Statistics and Statistic objects implement the mrScriptBasic dynamic property expansion
feature. This means that an alternative way of writing this would be:
TableDoc.Tables.MyTable.Statistics.ColumnProportions.SigLevel = 1
For more information, see the topic Dynamic Property Expansion on p. 1246.
To run the test at two significance levels, use the SigLevelLow statistics property to display the
lower significance level. For example:
TableDoc.Tables.MyTable.Statistics.ColumnProportions.SigLevel = 1
TableDoc.Tables.MyTable.Statistics.ColumnProportions.SigLevelLow = 5
In the resulting table, the IDs of columns that are significant at the higher level appear in upper
case, and those that are significant at the lower level appear in lower case.
Note: If you are using two levels of significance, ensure that the value of the SigLevelLow property
is greater than that of the SigLevel property, as it represents a higher probability that the results
are due to chance, and therefore a lower level of significance.
Minimum Base and Small Base Values in Statistical Tests
By default, when you carry out a column proportions, column mean, net difference test, or paired
preference test, if a table includes a base value that is below the recommended minimum base of
30, the test is not carried out. This is denoted by two asterisks (**), which are placed on the table
instead of the result. If a table includes a base value that is above the minimum base but below a
“small base” value of 100, the test is carried out, but a single asterisk (*) next to the test denotes
that the base value is small. The annotations also indicate this.
Statistical Tests Compared to IBM SPSS Statistics
The formulae for the statistical tests in IBM® SPSS® Data Collection Base Professional
have been specifically developed for the market research industry. The tests differ from the
corresponding tests offered in IBM® SPSS® Statistics 10 in two main ways:
Overlapping data. allows you to run the column proportions and column means tests on
overlapping data. When detects overlapping data in the columns being tested, it automatically
uses a special formula to compensate, known as the overlap adjustment.
Weighted data. The statistical formulae in SPSS Statistics 10 are designed for data weighted
with replication weights, which are normally integer values, whereas the statistical formulae
in Base Professional are designed for data weighted with sample weights, which are normally
non-integer values.
1394
Chapter 1
Statistical Tests Compared to IBM SPSS Quantum and IBM SPSS Quanvert
During the development of , the algorithms for statistical formulae were rewritten, and the revised
formulae were reviewed by IBM Corp. statisticians. Although the formulae appear very different
to those used in IBM® SPSS® Quantum™ and IBM® SPSS® Quanvert™, tests have shown
that they give comparable p values.
This section provides a comparison of the formulae in and Quantum/Quanvert.
Column Proportions Test
In the column proportions test, where the data are not overlapping, the denominator of t =
sqrt(term), where term is
in IBM® SPSS® Data Collection Base Professional:
in Quantum/Quanvert:
Where there is overlap, the denominator of t = sqrt(term), where term is
in Base Professional:
In some cases, slight differences will be seen in your results as borderline cases that are significant
using the formula may not be significant using the Quantum/Quanvert formula.
Degrees of freedom:
DF = e1 + e2 - e0 - 2
DF = e1 + e2 - e0 - 1
Customers who want to reproduce the Quantum/Quanvert formula can do this using the property:
TOM.Statistics["ColumnProportions"].UseQFormula = True
1395
Base Professional
Customers who want to reproduce the Quantum/Quanvert formula can do this using the Use
Quantum/Quanvert column proportions formula option available from the popup box in the Statistics
tab of the Table Properties dialog box.
Column Means Test
Degrees of freedom:
DF = e1 + e2 - e0 - 2
DF = e1 + e2 - e0 - 1
Customers who want to reproduce the Quantum/Quanvert formula can do this using the property:
TOM.Statistics["ColumnProportions"].UseQFormula = True
Customers who want to reproduce the Quantum/Quanvert formula can do this using the Use
Quantum/Quanvert column proportions formula option available from the popup box in the Statistics
tab of the Table Properties dialog box.
Paired Preference Test
In the paired preference test, the denominator of t = sqrt(term), where term is
where
For full details of Quantum and Quanvert formulae, see the Quantum User’s Guide or the
Quanvert User’s Guide.
1396
Chapter 1
References
Kish, L. Survey Sampling. New York: John Wiley and Sons. ISBN 0-471-48900-X.
Table Presentation
This section provides information about some of the options that are available for adjusting the
presentation of your tables, such as sorting, hiding low values, defining zero symbols, etc.
Table Properties
The Properties collection on the Table object contains a collection of Property objects. Each
property consists of a name and value and controls a table option, such as what to display for
percentage values that are rounded to zero. The table properties automatically take their values
from the corresponding properties in the Document.Default.Properties collection. This means that
you can set up default properties for all new tables and optionally overwrite one or more of them
on individual tables. Note that changing the default properties does not change the properties of
tables that have already been created.
The following table lists the recognized table properties.

Name Description Default Value
AdjustRounding Rounding anomalies mean that False
row and column percentages
created from single response
variables do not always add up
to 100%. This property has
a Boolean value that controls
whether the rounding of row
and column percentages is to be
adjusted so that they add up to
100%. For more information, see
the topic Rounding on p. 1253.
AutoBaseSpecification Defines the specification for the
base element that the Table Object
Model automatically adds to
tables with no base. This enables
you to change the label, hide
the autobase, or base it on an
expression.
AutoUnweightedBases Controls whether the Table Object True
Model automatically adds an
unweighted base element to
all weighted tables. For more
information, see the topic The
Base Element on p. 1230.
AutoUnweightedBaseSpecification Defines the specification for the
unweighted base element that the
Table Object Model automatically
adds to weighted tables. This
enables you to change the label,
hide the autobase, or base it on an
expression.
1397
Base Professional

MinBase Specifies a minimum value for the 0.0 (indicates no suppression)
base. No results are displayed in
cells where the base is below this
value. If there are multiple bases
in an axis because of nesting or
because additional bases have
been specified, the nearest base to
the cell is used to determine the
cell’s suppression state.
MinBaseOptions Additional options for use when False
specifying a minimum base value.
Multiple options can be combined
by adding the values together. See
next table for details of individual
options.
MinBaseSymbol Specifies a symbol to display *
instead of the result when a
cell value is suppressed because
the base is below the minimum
specified in MinBase.
RespondentWaitTime For an outbound call, this is the 2 when the project property does
length of time to hold a connection not exist; -1 when the property
while waiting for an interviewer value is not valid (for example,
to become available, before the when the value is empty or is not
call is considered a nuisance call a short int value).
and disconnected. For an inbound
call, this is the length of time to
allow a call to ring while waiting
for an interviewer to become
available, before terminating the
call.
In effect, the
RespondentWaitTime parameter
controls the length of time the
respondent must wait before
talking to an interviewer.
The default RespondentWaitTime
is 2 seconds when the project
property does not exist; the default
value is -1 when the property
value is not valid (for example,
when the value is empty or is not
a short int value). For inbound
calls, a reasonable respondent
wait time would be at least 20
seconds, as it corresponds to the
length of time the call rings before
it is answered.
If inbound and outbound calls are
being made for the same project
it is normally preferable to create
two groups - one for outbound
calls and one for inbound calls.
1398
Chapter 1

RoundingOptions Defines the default rounding 0
options. A value of 0 means
round 0.5 to even; a value of 1
means round 0.5 up (away from
0). Refer to the “RoundOptions”
topic in the IBM® SPSS® Data
Collection Developer Library for
more information.
RoundZeroCountSymbol Defines one or more characters *
that are used to represent count
values that have been rounded to
zero. The value can be any text
string.
RoundZeroOtherSymbol Defines one or more characters *
that are used to represent values
that have been rounded to zero for
cell contents that are not counts
or percentages. The value can be
any text string.
RoundZeroPercentSymbol Defines one or more characters *
that are used to represent
percentage values that have been
rounded to zero. The value can be
any text string.
Show100Percent Controls whether the Table Object True
Model displays total percentages
in the base row or column.
ShowPercentSigns Controls whether the Table Object True
Model displays percent signs in
table cells.
ZeroCountSymbol Defines one or more characters -
that are used to represent zero
count values in table cells. The
value can be any text string.
ZeroOtherSymbol Defines one or more characters -
values in cell contents that are not
counts or percentages. The value
can be any text string.
ZeroPercentSymbol Defines one or more characters -
percentage values in table cells.
The value can be any text string.
1399
Base Professional
Notes on the Zero Symbols

Setting the value of any of the zero symbol properties to an empty string “switches off”
that symbol, so that the numeric value will be shown instead with the required number of
decimal places. However, you can set the value to a space character (“ ”) to set the symbol to
a blank space.
To reduce confusion, avoid using for the zero symbols any of the 52 characters that are used
for the column IDs in the statistical tests. The column IDs are the alphabetic characters
in upper and lower case (A–Z and a–z). Instead, consider using non-alphabetic characters
or other text strings.
Minimum Base Options
Option Hexadecimal Purpose

Value
sbSymbolInFirstCellItemOnly 0x01 Display the symbol in the first cell item
only
sbUseWeightedBase 0x02 Use the weighted base instead of the
unweighted one
sbSuppressSpecialElements 0x04 Make special elements eligible for
suppression
sbIgnoreTotals 0x08 Avoid suppressing totals, subtotals and
derived elements
sbRetainCounts 0x10 Retain counts but suppress other cell
items
sbColumnsOnly 0x20 Consider only columns
sbRowsOnly 0x40 Consider only rows
Profile Table Properties
Properties for profile tables automatically take their values from the corresponding properties
in the Document.ProfileDefault.Properties collection. The following table lists the recognized
profile table properties.
MaxRows Restricts the number of rows to 10,000
display on the table. To display
all records in the data set, set
MaxRows to -1.
FilterEmptyRows Removes rows that contain no True
data in all the selected variables.
For more information, see the topic Working with Profile Tables on p. 1443.
Creating Custom Table Properties
In addition to the existing table properties, you can create your own custom table properties. For
example, you can add a property to store notes about a table.
1400
Chapter 1
You can also display the value of a custom property in an annotation. See the final table in Adding
Hypertext Links and Images to Annotations for an example of this.
Examples
The following example sets the AutoUnweightedBases property to False.

MyTable.Properties["AutoUnweightedBases"] = False
For more information, see the topic Weighting Tables on p. 1169.
The following example sets the ZeroCountSymbol and ZeroPercentSymbol properties.

Table1.Properties["ZeroCountSymbol"] = "*"
Table1.Properties["ZeroPercentSymbol"] = "**"
For more information, see the topic Handling Zero Values and Setting Hide Rules on p. 1153.
The following example removes percent signs from all percentage values in a table.
Table1.Properties["ShowPercentSigns"] = False
The following example creates a table and adds a custom property called Notes.
Set Table = TableDoc.Tables.AddNew("Table2", "age * gender")
Set Property = Table.Properties.CreateProperty()
Property.Name = "Notes"
Property.Value = "Survey still in progress"
Table.Properties.Add(Property)
The following example labels the base and unweighted base elements as “Total” and “Unweighted
Total” on all new tables:
TableDoc.Default.Properties["AutoBaseSpecification"] = "Base 'Total' base()"
TableDoc.Default.Properties["AutoUnweightedBaseSpecification"] = "UnweightedBase 'Unweighted Total' unweightedbase()"
Displaying Prefixes and Suffixes for Cell Items
Sample Script File: CellPrefixAndSuffixUsage.mrs
This example script is based on the Employee Data SAV sample data set. For more information,
see the topic Running the Sample Table Scripts on p. 1554.
You can attach a prefix or suffix to a cell item, to provide additional information for a cell. For
example, you can add a currency symbol to cells, as shown in the following example:
.AddNew("Table2", _
"salary{base() [IsHidden=True]," + _
"Mn 'Lowest' min(salary), Mx 'Highest' max(salary)," + _
"Av 'Average' mean(salary) [Decimals=0]} * gender", _
"Salary level by gender of employee")
.Table2.CellItems[0].Prefix = "$" ' Salary values are in dollars
1401
Base Professional
This creates the following table:

Figure 1-437
Table of salary by gender, with $ sign added as cell prefix
You can also use the prefix or suffix property to add annotations to a cell item. For example, if
you have a set of tables that all display values in months, you can add the suffix “months” to the
default Count cell item using the following script:
TableDoc.Default.CellItems[0].Suffix = " months" 'include a space before the text
This adds the text after the cell item, as shown in the following table:
Figure 1-438
Table showing months since hire by gender, with months added as cell suffix
Creating Summary Statistic Tables
Sample Script File: SummaryStatisticTables.mrs
This example script is based on the Museum sample data set. For more information, see the topic
Running the Sample Table Scripts on p. 1554.
You can create tables containing just the summary statistics of numeric variables. This example
creates a table that summarizes a number of different numeric variables including number of
visits, number of visits in the last 12 months, and so on. Each row in the side axis of the table
contains the mean of a different numeric variable. This is tabulated by gender on the top axis.
The table contains a single cell item, a mean. The following script specifies the cell item:
CellItems.AddNew(itMean, 1, "-")
1402
Chapter 1
The “-” parameter indicates that the mean is calculated, not for a fixed variable, but for the
numeric variable specified by the numeric element in each row. The elements are defined in the
axis expression, for example:
visits{base() [IsHidden=True], numeric(visits)} +
visits12{base() [IsHidden=True], numeric(visits12)} +
...!"
An example of a table created using this method, with the individual numeric variables displayed
as subaxes of the side axis, is shown below:
Figure 1-439
Mean summary table showing mean values for several numeric variables on the side axis by gender
on the top axis
Alternatively, you can group all the variables into a single axis variable using the axis({})
syntax:
axis({base() [IsHidden=true],
visits 'Number of previous visits' numeric (visits),
visits12 'Number of previous visits in last 12 months' numeric (visits12),
...
mammals 'Interest rating for mammals - respondents leaving' numeric (mammals)
}) as SummaryVariable 'Summary of means of numeric variables'
* gender
1403
Base Professional
!", "Table of means for numeric variables. Each row is a numeric element based on a numeric variable.")
An example of a table created using this method is shown below:

Figure 1-440
Mean summary table showing mean values for several numeric variables grouped in a single side
axis variable, by gender on the top axis
In cells not corresponding to a row or column defined by a numeric element type (for example, the
base row or column), values for the summary statistics are shown as zero or 1, depending on the
statistic type. For example, means are shown as 1 and standard deviation and standard error are
shown as zero.
Counts in a row or column defined by a numeric element are counts of the variable associated
with the numeric element.
This example shows how to create a mean summary table. You can produce other types of
summary statistic tables for any cell item that can be based on a numeric variable, for example,
maximum, minimum, and standard deviation. For further information on the cell items you can
use in this way, see the CellItem.Variable information in the Table Object Model.
Note: The column means test cannot be run against the mean statistic in a summary statistic table.
It can only be run against the mean element (instead of mean cell item).
Specifying Decimal Places for Summary Statistic Elements
Sample Script File: DecimalPlacesOnSummaryElements.mrs
1404
Chapter 1
You can specify the number of decimal places to display for a summary statistic, using the
Decimals property of the Element object. The following script creates a table with the mean
age displayed to 1 decimal place:
Set Table = TableDoc.Tables.AddNew("Table01", "age{.., mean()} * gender", "Decimal places on elements")

Table.Side.Age.Elements["mean"].Decimals = 1
You can also use the axis expression syntax to specify decimals for a summary statistic, as shown
in the following script:


Figure 1-441
Table of age by gender, using Decimals property to change the decimal places for the mean element
Note: The Decimals property of the CellItems object is not affected by the Decimals property of
the Elements object. You can use the two Decimals properties within the same table, as shown in
the following example, which creates a table with mean age values displayed to 1 decimal place
and mean visits values displayed to 2 decimal places:

Table.CellItems.AddNew(4, 2, "visits") ' 4 = itMean
1405
Base Professional

Figure 1-442
Table of age by gender, changing the Decimals properties of both elements and cell items
For a full list of the Element types for which you can specify decimal places, see the
Element.Decimals property.
Displaying Images for Elements
Sample Script File: DisplayElementImages.mrs
In IBM SPSS Data Collection Survey Reporter Professional version 2.2 and later, you can attach
images to the rows or columns in a table using the Image and ImagePosition properties of the
Style object. It is not possible to add images directly in IBM® SPSS® Data Collection Survey
Tabulation, but images that have been attached using IBM® SPSS® Data Collection Interviewer
Server or IBM SPSS Data Collection Survey Reporter Professional are automatically displayed
in Survey Tabulation.
You can include the images when you export tables to HTML, using either a script or the Export
dialog box in Survey Tabulation. From IBM SPSS Data Collection Survey Reporter Professional
version 2.3 and later, you can also include the images when you export to Word.
1406
Chapter 1
To specify a single location where the script should look for all the images, you can use the
ImageLocation property of the Document object, for example:
TableDoc.ImageLocation = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables\Images"
If you use this property to specify a path, all images must be in the specified location.
You can specify a local path, a UNC path (\\server\folder\...), an HTTP server
location (http://server/folder/...), or an HTTP image cache location (for example,
http://server/folder/ImageCache/ImageCache.aspx?project=Museum&file=). If the images are
located in the directory where the exported document is saved, there is no need to specify a path.
To attach the image to the element, use the Style property of the Element object. The Style
object has two properties, Image and ImagePosition. Use the Image property to specify the
name of the image:
Table.Side.Interest.Elements.Dinosaurs.Style.Image = "Dinosaur.gif"
If you have not specified a path for all the images using the ImageLocation property, you can
specify paths for individual images using the Image property, for example:
Table.Side.Interest.Elements.Dinosaurs.Style.Image = "C:\Documents and Settings\All Users\Documents\My Pictures\Dinosaur.gif"
If you have specified the ImageLocation property, you can override it using the Image property,
provided that you are using an HTTP path, as the ImageLocation property is not added to the
image in this case. Note that you cannot override an ImageLocation property using a local or UNC
path in the Image property, as the path does not replace the existing path but is appended to it.
Use the ImagePosition property to position the image in the cell relative to the label text, or
to replace the label with the image:
Table.Side.Interest.Elements[..].Style.ImagePosition = 4 ' 4 = ipImageOnly
If images have been attached to elements in the metadata using the Picture and PicturePosition
custom properties, the Image and ImagePosition properties default to these values.
To include the images when you export a table to HTML or Word, set the UseStyles export
property to True. For further information, see HTML Tables Export Properties and Word Tables
Export Properties.
1407
Base Professional
Here is an example using Microsoft clipart images:

Figure 1-443
Table of Interest by Gender using the Style property to replace labels with images
Note: Style properties are ignored when you create a chart, and the labels are displayed instead.
Sorting Tables
This section provides information on sorting, with examples of sorting basic and more complex
tables.
Notes and General Limitations

If there is more than one item of cell contents, the first item is always used for the sort.
By default, values are sorted in descending order.
Sorting rows that contain cumulative column percentages or columns that contain cumulative
row percentages is not recommended, as the reordered percentage values do not give
meaningful results.
Axes are not sorted if they contain a combination of nesting and concatenation and IBM®
SPSS® Data Collection Base Professional does not issue a message to alert you to this.
You cannot use an element that is inside a net to sort the other axis of the table.
You cannot sort an axis that contains net elements in an outer nest level. Any sorting that
would apply to the axis is ignored.
There are a number of special rules that apply when sorting axes that contain special elements.
See Sorting Special Elements.
1408
Chapter 1
Note: The examples in this section are available in sample mrScriptBasic files called
MyFirstSortedTable.mrs and SortedTables.mrs. These example scripts are based on the Museum
sample data set. For more information, see the topic Running the Sample Table Scripts on p. 1554.
Introduction to Sorting Tables
Sample Script File: MyFirstSortedTable.mrs
Sometimes it is useful to sort your tables, so that you can see at a glance which is the most
important or popular response. Sorting tables is sometimes called ranking. To understand how it
works, first let’s consider an unsorted table of Remember by Biology:
Figure 1-444
Unsorted table showing remember by biology
Suppose you want to sort the table so that the rows that contain more respondents appear before
those containing fewer respondents. When you sort the rows, you need to select the column on
which you want to sort. You do this using the Table.SortColumn property. The following example
sorts the rows in descending order of the values in the base column:
.AddNew("Table2", "Remember * Biology", "Remember by Biology - Rows Sorted")
.Table2.SortColumn = "Biology{Base}"
End With
1409
Base Professional
Now let’s look at the table:

Figure 1-445
Table showing remember by biology, sorted on base column
If you compare this table with the unsorted table, you will notice that the rows have been
reordered, making it easy to see which categories were most popular. Although you generally
want to sort the rows on the base column, you are not restricted to doing this. For example, we can
sort the rows on the values in the Yes column:
.AddNew("Table3", "Remember * Biology", "Remember by Biology - Rows Sorted on Yes Column")
.Table3.SortColumn = "Biology{Yes}"
End With
Notice that you set the Table.SortColumn property to the axis name followed by the element name
enclosed in braces ({ }). You need to take care that the axis and element names are correct and
actually exist on the top of the table, otherwise you will get an error. (For information about
specifying the sort column in a nested table, see Sorting Nested and Concatenated Tables.)

Figure 1-446
Table showing remember by biology, sorted on Yes column
Notice that the order of the rows has changed to reflect the values in the Yes column.
1410
Chapter 1
You can sort the columns, just like you can sort the rows. When you sort the columns, you need to
specify the row on which you want to sort. For example:
.AddNew("Table4", "Remember * Biology", "Remember by Biology - Columns Sorted on Base Row")
.Table4.SortRow = "Remember{Base}"
End With

Figure 1-447
Table showing remember by biology, sorted on base row
Notice that now the order of the Yes and No columns has been reversed, making it easy to see
that more respondents chose the No category.
And of course, you can sort both rows and columns in the same table:
.AddNew("Table5", "Remember * Biology", "Remember by Biology - Rows and Columns Sorted")
.Table5.SortRow = "Remember{Base}"
.Table5.SortColumn = "Biology{Base}"
End With

Figure 1-448
Table showing remember by biology, sorted on base row and column, descending order
1411
Base Professional
You can sort a one-dimensional table by specifying the sort row or column as “Base”. For example:
.AddNew("Table6", "Remember", "Interest rating for the Remember gallery")
.Table6.SortColumn = "Base"
End With

Figure 1-449
One-dimensional Table showing remember, sorted on the base column
You can also sort tables on the first or last row or column in the table, without referring to a
specific row or column name. To so this, you use the appropriate line from the following syntax:
Table.SortRow = "first"
Table.SortColumn = "last"
Table.SortColumn = "first"
Table.SortColumn = "last"
This can be useful if you are running tracking studies to monitor change over time, as you can
reuse the same table with each wave of data without having to re-select the row or column to
sort on. For example, if you have a table containing monthly data, you might use the syntax
Table.SortColumn = "last" to sort the table by the latest month, rather than selecting the name
of the month each time you update the data.
By default, the sort is always carried out in descending order. However, you can sort tables in
ascending order by specifying the sort order for the row or column , for example:
.AddNew("Table7", "Remember", "Interest rating for the Remember gallery, sort ascending")
.Table7.SortColumn = "Base"
.Table7.SortColumn.Order = 0 ' Ascending order
End With
1412
Chapter 1

Figure 1-450
Table showing remember by biology, sorted on base row and column, ascending order
You have probably noticed that all of the tables shown in this topic have only one item of cell
contents and you may be wondering what happens when the table contains additional cell contents.
The answer is that if the table contains more than one item of cell contents, the sort is always
based on the first item of cell contents. When creating sorted tables that contain more than one
item of cell contents, you therefore need to give some consideration to the order in which you
specify the items of cell contents.
All of the examples in this topic are based on a very simple table. For information on sorting
concatenated and nested tables, grid tables, and special elements, see Sorting Tables.
Requirements
Sorting Nested and Concatenated Tables
Sample Script File: SortedTables.mrs
Concatenation
When you sort a table that contains concatenation in the dimension in which you are sorting, the
elements within each variable are sorted separately. To illustrate how it works, we will sort the
rows of a table that has two variables concatenated on both the side and the top axes. To do this,
we need to specify the column on which we want to sort the rows:
.AddNew("Concatenated", "age + gender * biology + before", "Sorting a concatenated table")
.Concatenated.SortColumn = "before{Base}"
End With
1413
Base Professional
Here is the table, with the sort column highlighted:

Figure 1-451
Concatenated table sorted on base Before column
Notice that the rows that relate to the Age variable have been sorted separately from the rows
that relate to the Gender variable.
Nesting
If there is nesting in the dimension of the table in which the sort row or column is located, you
specify the sort row or column using the following syntax:
AxisName{ElementName} > AxisName{ElementName} ...
To illustrate this, we will create a table with the Before variable nested within the Biology variable
on the top axis, and sort the rows of the table on the Base element of the Before variable that is
nested within the Yes element of the Biology variable:
.AddNew("Nested1", "age * biology{.., ^Not_answered} > before{.., ^Not_answered}", "Sorting on a nested element")
.Nested1.SortColumn = "biology{Yes} > before{Base}"
End With

Figure 1-452
Nested table sorted on base Before column
1414
Chapter 1
Notice that the sort order would be different if we had sorted the rows on the Base element of the
Before variable that is nested within the No element of the Biology variable.
If you do not specify an element at an inner nesting level, the first element of the nested axis will
automatically be used. For example, if we had merely specified an element of the outer variable
for the sort column for the above table, the first element of the inner axis would be used. In this
example the Base element is the first element of the Before variable, so in fact the following sort
column specification would give exactly the same results:
.Nested1.SortColumn = "biology{Yes}"
When you sort a table that contains nesting in the dimension in which you are sorting, the
elements within the inner nested variables are sorted. However, the elements of the outermost
variable are not sorted. For example:
.AddNew("Nested2", "interview > education{.., ^Not_answered} > before{.., ^Not_answered} * gender", "Sorting a nested dimension"
.Nested2.SortColumn = "Gender{Base}
End With

Figure 1-453
Nested table sorted on base Gender column; outermost variable is unsorted
Combination of Nesting and Concatenation
Axes are not sorted if they contain a combination of nesting and concatenation and the Table
Object Model does not issue a message to alert you to this.
1415
Base Professional
Sorting Net Elements
Nets are generally used in multiple response variables to show the number of respondents who
chose one or more responses in a group of responses. (A net is different from a subtotal, which
simply shows the number of responses that were given.) A typical example of how nets are used is
in a multiple response variable based on a question that asks respondents to choose categories from
a list that includes positive and negative responses. Two net elements would typically be used to
show how many respondents chose one or more positive and negative categories, respectively.
When you sort a table that contains nets, the elements within each net are kept together and
sorted separately. To illustrate how it works, we will use the following code to create a table that
contains a number of nets:
.AddNew("TableWithNets", _
"remember{Theoretical 'Theoretically-themed exhibits' net(" + _
"{Conservation, Ecology, Wildlife_in_danger}), " + _
"ExtinctLife 'Extinct life forms and evolution' net(" + _
"{Dinosaurs, Fossils, Evolution, Origin_of_species}), " + _
"CurrentLife 'Current life forms' net(" + _
"{Botany, " + _
"Cold 'Cold-blooded' net(" + _
"{Fish_and_reptiles, Insects}), " + _
"Warm 'Warm-blooded' net(" + _
"{Whales, Birds, Mammals, Human_biology})})}" + _
" * gender", "Unsorted table with nets")
End With
1416
Chapter 1
Here is the unsorted table:

Figure 1-454
Table with nets, unsorted
Now let’s add the following line to sort the rows of the table on the Base column.
.TableWithNets.SortColumn = "Gender{Base}"
Here is the sorted table:

Figure 1-455
Table with nets, sorted on base Gender column
Notice that the elements within each net have been sorted, and that the net groups have been
sorted, but that the elements within each net group have been kept together.
1417
Base Professional
Note that you cannot use an element that is inside a net to sort the other axis of the table.
Nets in Nested Tables
You cannot sort an axis that contains net elements in an outer nest level. Any sorting that would
apply to the axis is ignored.
Sorting Special Elements
There are a number of rules that apply when sorting axes that contain special elements. The
default behavior depends on the element type.
The following element types are sorted by default:

Elements formed from a standard category
Nets
Elements created using the Combine keyword
Derived elements
Elements created using the Expression keyword
Numeric elements
The following element types have a fixed position by default:

Base
Unweighted base
Mean
Standard deviation
Standard error
Sample variance
Subtotal
Total
Minimum
Maximum
When an element has a fixed position, it means that if the element is the third element in the
unsorted table, it will be the third element in the sorted table and elements that are sorted will
move around it, when necessary. For this reason, it is usual to place unsorted elements at the
beginning or end of the axis.
Text-only elements are never sorted. Unlike nets, they are not tied to the elements that follow.
This means that text-only elements are not generally suitable for use in sorted tables.
For all element types apart from text-only elements, you can change the default sort behavior
using the IsFixed property. For more information, see the topic Element Properties on p. 1222.
1418
Chapter 1
Sorting Grid Tables
You can sort the columns and rows of a grid table. For example, using the Museum Rating grid
table shown in Creating a Grid Table, we can sort the rows on one of the columns (which are
formed from the categories of the variable inside the grid) and we can sort the columns on one of
the rows (which are formed from the iterations). Here is the code:
.AddNewGrid("SortedRatingGrid", "rating", , "Rating grid - sorted")
' Sort on one of the rating categories
.SortedRatingGrid.SortColumn = "rating[..].Column{Very_interested_5}"
.AddNewGrid("SortedRatingGrid2", "rating", , "Rating grid - sorted #2")
' Sort on the iterations
.SortedRatingGrid2.SortRow = "rating{Dinosaurs}"
End With
Here is the first table in which the rows are sorted on the Very interested column:
Figure 1-456
Grid table sorted on Very Interested column
1419
Base Professional
Here is the second table in which the columns are sorted on the Dinosaurs row:
Figure 1-457
Grid table sorted on Dinosaurs row
Note that you do not normally sort a grid table on the base row or column. For more information,
see the topic The Base in Grid Tables on p. 1297.
Hiding Rows, Columns, and Cells
If some of the rows or columns in a table contain few or no responses, you may prefer to hide
them so that the table displays only the most important information. You can do this by setting
hide rules on your tables to hide rows or columns based on the values they contain. You can also
hide the information in individual cells based on the values that they contain, and you can specify
the values above or below which you want to hide rows, columns, or cells. This section contains
detailed information about using hide rules.
You can also specify that you always want to hide a particular row or column by changing the
properties of the category or other element that it contains, or you can specify that an element will
be hidden only when it is displayed in a row or only when it is displayed in a column. You do
this using the IsHidden, IsHiddenWhenColumn, or IsHiddenWhenRow properties. See Hiding
Elements in the Element Properties section for further information.
Hiding Rows and Columns
Sample Script File: HideRules.mrs
This example script is based on the Museum XML sample data set. For more information, see the
topic Running the Sample Table Scripts on p. 1554.
1420
Chapter 1
You may want to hide rows or columns in your tables in which all of the values are zero, such
as the Not answered row and column in the following table:
Figure 1-458
Table with no values in some rows and columns
To hide a row where all values are zero, you add a hide rule to the table definition, using the
AddNew method, as follows:
TableName.Rules.AddNew()
The default rule specification hides rows where all values in the first cell item in each cell are
equal to zero, so you do not need to specify any parameters for the rule. The AddNew method has
the following parameters, which you can use to specify more complex rules:
TableName.Rules.AddNew(Type, Target, CellItemRef, Operator, Value)
The first parameter, Type, specifies the rule type. As the default rule type is a hide rule, you do
not need to specify this (in the current release, hide rules are the only rule type available). The
second parameter, Target, specifies whether the rule applies to a row, column, or cell. To hide
columns instead of rows, enter a value of 1 in the Target parameter:
Table2.Rules.AddNew(, 1)
See for a list of the targets you can specify.
You can hide both rows and columns on the same table by setting two rules for the table, as
in the following example:
With Tables.AddNew("Table2", "education * before", _

"Education by before, hide zero rows and columns")
.Rules.AddNew() ' default
.Rules.AddNew(,1) ' rtColumn = 1
End With
1421
Base Professional

Figure 1-459
Table with zero rows and columns hidden
Instead of hiding rows or columns where all values are equal to zero, you can use different
operators and values to set the condition. For example, the following script displays a table of
museums by age, and hides any rows where all the values are less than or equal to 30, so that
only the museums that attracted the most interest are shown. The fourth parameter, Operator,
is set to 1 to specify “less than or equal to”. See for a list of the operators. The fifth parameter,
Value, specifies the value to test for:
With Tables.AddNew("Table4", "museums * age", _

"Museums by age, hide rows with values less than or equal to 30")
.Rules.AddNew(0,0,,1,30)
End With

Figure 1-460
Hide rows less than or equal to 30
1422
Chapter 1
Without the hide rule, the table has nine rows (see the output from Table 3 in the script
HideRules.mrs for the original table). After applying the hide rule, the Archeological Museum,
National Art Gallery, Northern Gallery, and Not answered rows are hidden.
Notice that, to meet the criteria for hiding the row, the values for that row must be less than or
equal to 30 in all columns. In this example, the Other row has a value of 37 in the base column,
so is not hidden. However, you can create a hide rule to test the value of a single column to
determine whether the row is hidden. For more information, see the topic Hide Rules Based on a
Single Row or Column on p. 1424.
Hiding special elements
By default, hide rules do not affect rows or columns containing special elements such as means or
standard deviation. If you want a hide rule to include special elements, you can specify this by
setting the IgnoreSpecialElements parameter for the hide rule to False. For example, the following
specification hides columns where all the values are less than 50. By default, this does not apply to
the mean column on the table, so it is displayed even though all the mean values are less than 50:
With Tables.AddNew("Table5", "interest * age{.., mean()}", _

"Interest by Age, hide columns with values less than or equal to 50")
Set Rule = .Rules.AddNew()
Rule.Type = 0 ' hide
Rule.Target = 1 ' column
Rule.CellItemRef = 0 ' if cellitem 0
Rule.Operator = 1 ' is less than or equal to
Rule.Value = 50 ' 50
End With
The script for this table uses a variable, Rule, to specify the properties for the hide rule, and sets
the values of all the relevant properties (including defaults) to make clear the purpose of the rule.
1423
Base Professional

Figure 1-461
Table of interest by age. All columns with a value below 50 are hidden, but the mean column is displayed
The next script creates the same table and hide rule, but this time sets IgnoreSpecialElements to
False, so that the hide rule is also applied to the mean column:

"Interest by Age, hide columns with values less than or equal to 50, including the mean column")
Rule.Target = 1 ' column
Rule.IgnoreSpecialElements = False ' hide rule includes mean column
End With
1424
Chapter 1

Figure 1-462
Table of interest by age. All columns with a value below 50 are hidden, including the mean column
Hide Rules Based on a Single Row or Column
Instead of hiding rows or columns where all the values in the row or column meet the condition,
you can base the condition on a specific row or column on the table. For example, in the following
table of interest by age, a column has been added to show the mean age:
Figure 1-463
Table of interest by age with added mean column
1425
Base Professional
The following script hides rows in this table where the value in the mean age column is 30 or
over. To do this, you use the ElementRef parameter to specify the element age{mean} as the
test for the hide rule.
"Interest by Age, hide rows based on value in mean age column")
Rule.Target = 0 ' row
Rule.Operator = 3 ' is greater than or equal to
Rule.ElementRef = "age{mean}" ' for column mean()
End With
Here is the table produced by the script.

Figure 1-464
Table of interest by age. Rows with a value for the mean age greater than or equal to 30 are hidden.
See also Adding a Minimum p Value to a Table for an example of using hide rules based on the
minimum p-value to hide non-significant values on a table.
Hiding based on first or last row or column
Instead of specifying the row or column on which the hide rule is based by name, you can specify
that the test should apply to the first or last row or column in the table. This is useful if you have
tracking studies that are regularly updated with new rows or columns containing data for the latest
month or quarter. For example, you may have a table containing data for customer satisfaction by
month, where a new element is added to the variable each month with the new responses. You can
set a hide rule based on the value of the last column in the table, so that you do not need to change
the element name in the table specification each time the new month’s data is added.
To do this, use the ElementRef parameter with the keyword first or last instead of the name of
the element:
1426
Chapter 1
Rule.Operator = 0 ' is less than

Rule.ElementRef = "last" ' for the final column in the table
End With
The table bases the hide rule on the final column in the table, so when a new column is added to
the end of the table, this is used instead.
Hide rules in nested tables
If the element on which you want to base the hide rule is in the inner variable of a nested table,
you can specify it using the syntax for nested elements in the ElementRef parameter. For example,
here is a nested table with the specification age * before{yes,no} > biology{yes,no}.
Figure 1-465
Table of age * before > biology
To hide rows where the value is less than 50 in the highlighted column (the column for those
who answered Yes to the biology question within the Base section of the before question) use
the following script:
With Tables.AddNew("Table12", "age * before{yes,no} > biology{yes,no}", _

"Nested table with hide rule on inner nested element")
Rule.ElementRef = "before{base} > biology{yes}" ' for inner nested element()
End With
1427
Base Professional

Figure 1-466
Table of age * before > biology, with hide rule
If the element on which you want to base the hide rule is in an outer nested variable, you need
only specify the outer element.
Figure 1-467
Table of age * before > biology
This script hides rows where the value is less than 50 in the Base section of the before question:
With Tables.AddNew("Table13", "age * before{yes,no} > biology{yes,no}", _

"Nested table with hide rule on outer nested element")
Rule.ElementRef = "before{base}" ' for outer nested element()
End With
1428
Chapter 1
Figure 1-468
Table of age * before > biology, with hide rule
Hiding Cells
You can hide individual cells in your tables where the values are equal to, above, or below a
value that you specify. For example, you can hide cells containing zero, or containing values
of less than 10.
The following script creates a table of museums by certificat, and hides any cells with values
less than or equal to zero:
With Tables.AddNew("Table15", "museums * certificat", _

"Museum by qualification, hide any empty cells")
Rule.Target = 2 ' cell
Rule.Value = 0 '0
End With
The Target parameter is set to 2 to specify that the hide rule applies to cells.
Here is the table produced by the script.

1429
Base Professional
Figure 1-469
Table of museum by certificate. Cells with values of zero are hidden
Note that when you hide cells, all the contents of each cell that meets the hide condition are
removed, but the cell still remains on the table, even if all the cells in the row or column are blank.
Hide Rules Based on Cell Items
By default, the cell item used to test the hide rule is the first cell item that appears in the table. In
the examples shown in the other topics in this section, this is the Counts cell item. If required, you
can specify a different cell item to use in the table. If you add new cell items or change the order
of cell items, ensure that you refer to the correct cell item when specifying a hide rule. Note that
the first cell item in the table is specified as cell item 0, not 1.
For example, suppose that you are using the cell items counts, column percents, and a sum based
on the dinosaurs variable:
With TableDoc.Default.CellItems
.Clear()
.AddNew(0) ' counts
.AddNew(1) ' column percents
.AddNew(5, 0, "dinosaurs") ' sum(dinosaurs)
End With
A table with these cell items, and with a hide rule based on the default cell item 0, will base
the hide rule on the value of counts.
"Interest by age with three cell items, hide rule on cell item 0 (counts)")
1430
Chapter 1

Rule.CellItemRef = 0 ' if cellitem 0 (counts)
End With
Figure 1-470
Table of interest by age. Rows where all columns have counts of less than 30 are hidden.
Note that three rows with counts of 30 or over in the base column are displayed, as the counts
must be less than 30 in all columns for the row to be hidden.
Alternatively, you can base the hide rule on column percentages, by specifying cell item 1:

"Interest by age with three cell items, hide rule on cell item 1 (column percents)")
Rule.CellItemRef = 1 ' if cellitem 1 (column percents)
End With
1431
Base Professional
This hides rows in which all columns have column percentages of less than 30:
Figure 1-471
Table of interest by age. Rows where all columns have column percentages of less than 30 are hidden.
You could also base the hide rule on the sum(dinosaurs) cell item.
Defining hide rules based on a reference to a single value element in tables with Row or Column
Base Cell Items
If you define a hide rule with an ElementRef parameter referring to a single-value element (for
example, a mean) you must make the CellItemRef parameter refer to the first cell item that is not a
Row Base, Column Base, Unweighted Row Base, or Unweighted Column Base. A single-value
element is one such as mean, standard deviation, minimum p-value, etc, where the single value
overrides the cell items that appear on the table.
For example, suppose that you create a default hide rule to hide columns for which the mean age
is less than 30:
Set Rule = TableDoc.Default.Rules.AddNew()
Rule.ElementRef = "age{mean}" ' for row mean()
Suppose that you also change your tables to include the following cell items:
Column base
Counts
Column percentages
The single value element (in this case, mean) is always placed in the first non-base cell item, in
this case, counts. However, the default hide rule refers to cell item 0. In a table with the above cell
items, this is the column base cell item, not the counts cell item, so will not give the correct results.
To display the table correctly, you must change the CellItemRef parameter to refer to cell item 1
(where counting starts at 0), the counts cell item.
1432
Chapter 1

"Interest by age with base as first cell item, hide rows where mean is less than 30")
' Change the cell item used in the hide rule to first non-base cell item (counts)
.Rules[0].CellItemRef = 1
End With
See also Example of the Product Difference Test for an example that uses column bases in tables
with hide rules.
Annotations
You use annotations to display information about your tables. You can display the information
in up to eight different positions around the table. Over 30 macros are available for inserting
information about the tables, filters, weighting, data set, population date and time, etc. You can
also include your own free-formatted text and use a limited number of standard HTML tags to
define formatting and hyperlinks.
The exact way that the annotations are displayed in the exported tables depends on the type of
export you use.
Annotation Positions
The Annotations collection always contains eight Annotation objects, each one of which
corresponds to a position around the table. There are four “header” positions above the
table—Title Header, Left Header, Center Header, and Right Header—and four “footer” positions
below the table—Title Footer, Left Footer, Center Footer, and Right Footer. The following
diagram shows these positions.
Figure 1-472
Annotation positions
1433
Base Professional
The following table shows the constants and their associated values that you use to specify
the various positions in your scripts. You can use the constant if your script is part of a data
management script (.dms) file. If your script is a standalone .mrs file, you must use the numeric
value or set up user-defined constants to represent the values (as shown in the Annotations.mrs
sample).
Position Constant Value
Title header AnnotationPosition.annTitle- 0
Header
Left header AnnotationPosition.annLeft- 1
Header
Center header AnnotationPosition.annCenter- 2
Header
Right header AnnotationPosition.annRight- 3
Header
Title footer AnnotationPosition.annTitleFooter 4
Left footer AnnotationPosition.annLeftFooter 5
Center footer AnnotationPosition.annCenter- 6
Footer
Right footer AnnotationPosition.annRight- 7
Footer
You can set up the texts to be displayed in these positions for individual tables, as defaults to apply
to new tables, or as global settings to apply to all of the tables in the table document.
The built-in default settings are shown in the following table.

Position Description Specification
Title Header Project description. {ProjectDescription}
Left Header Table description and filters. {TableDescription \n}
{Filters \p}
Right Header Table number and the description {TableNumber \p \n}
of the weighting variable and the {WeightVariable \l \n \p}
population level. {Level \l \p}
Left Footer Cell contents and footnotes about {CellContents \p \n}
the statistical tests, if any, and {Statistics \p \n \i-}
details of any hide rules that have {Rules \p}
been applied, as well as warning {CellItemSymbols \p}
messages for statistical tests and {PopulateWarnings \p}
explanations of symbols.
1434
Chapter 1
Annotation Macros
Annotation macros can be used in your annotation specifications to insert information about the
tables, filters, weighting, data set, population date and time, etc. You can use more than one
macro in a single annotation specification and you can combine the macros with plain text. The
following table lists the annotation macros that are available.
Macro Description Switches Corresponding Table Object
Model Property
{CDSCName} The name of the CDSC, such as “mrXmlDsc”. \n \p DataSet.CdscName
{CellContents} The table’s cell contents. If there is more than one, \n \p Properties of each CellItem object
they are separated by <BR/> tags. in Table.CellItems
{CellItemSymbols} Information about symbols displayed in the table \n \p
cells.
{Context} The user context being used, such as “Analysis”. \n \p Document.Context
{CurrentTime} The current date and time. By default this is in the \s \n \p
long date format for the current language’s default
regional setting (locale). Use the \s switch to use
the short date format.
{DBLocation} The name and location of the case data, such as \n \p DataSet.DBLocation
“[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\Museum.xml”.
{DocumentDescrip- The description of the table document, such as \n \p Document.Description
tion} “Analysis of age and education against interest in
the various galleries”.
{Filters} The descriptions of all of the filters, concatenated \d+ \d- \e \t \g \i+ Description or Expression
with the word “AND” in bold. If the filters are at \i- \n \p properties of each Filter object in
different levels, details of the levels are shown. If Table.Filters.
the filter doesn’t have a description, its expression
is shown.
You can use one or more of the optional switches
described in the table below.
{LabelType} The label type being used, such as “Label”. \n \p Document.LabelType
{Language} The metadata language being used, such as \n \p Document.Language
“English (United States)”.
{Level} The table’s population level. For example, \l \n \p \s Table.Level
“Person[..].Trip”. The top level is always shown
as “Top” when using English. Use the \l switch to
use the level’s description instead of the name. For
example, “Overseas trips taken by each person”.
{MDSCName} The name of the MDSC being used, such as \n \p DataSet.MdscName
“mrQvDsc”.
{MetaDataLocation} The name and location of the metadata, such as \n \p DataSet.MetaDataLocation
“[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\XML\Museum.mdd”.
{MetadataVersion} The version(s) of the metadata being used in the \n \p DataSet.Version
form of a , such as “{..}”.
{PopulateWarnings} Displays warnings generated during the generation \n \p
of statistical tests, for example, if the type of test
requested is not valid for the type of table.
{ProjectDescription} The description of the data set, such as “Museum \n \p DataSet.Description
Survey”.
1435
Base Professional
Macro Description Switches Corresponding Table Object

Model Property
{ProjectName} When you are using a CDSC that supports \n \p DataSet.Project
multiple projects (such as RDB DSC), you can
show the name of the project being used, such as
“short_drinks”.
{Rules} The rules defined for the table. Each rule is \n \p Table.Rules
separated by a <BR/> tag. For example,
“Hide cells where Count equals 0”.
{RunTime} The population date and time for the current \s \n \p Table.DatePopulated
language’s default regional setting (locale). By
default this is in the long date format. Use the \s
switch to use the short date format.
{SideSpec} The specification of the side axis. For example, \l \n \p \s Table.Axes["Side"].Specification
“age”. Use the \l switch if you want to replace
variable names with their descriptions. For
example, “Age of respondent”.
{SortColumn} The column by which the table is sorted. For \n \p \s Table.SortColumn
example, “Gender{Male}”.
{SortRow} The row by which the table is sorted. For example, \n \p \s Table.SortRow
“Age{Base}”.
{Statistics} Notes relating to the statistical tests, separated by a \n \p \i- Statistic.Annotation
<BR/> tag. This annotation should always be used
in tables that include a statistical text. For example,
“Column Proportions: Columns Tested (5%) A/B”.
If a statistic is invalid, the annotation indicates this.
The \i- switch suppresses annotations for invalid
statistics.
{TableBase} The table’s base value. For example, “602”. \n \p Table.Base
{TableDescription} The table description, such as “Age by gender for \n \p Table.Description
all respondents”.
{TableName} The name of the table, such as “MyTable”. \n \p Table.Name
{TableNumber} The index of the table in the table document, such \n \p \g
as “5”.
{TableProperty:Prop- The content of a custom table property. Add the \n \p
ertyName} name of the custom property after the colon. You
must first specify the custom property in your script
and enter a value for it.
{TableSpec} The table specification, such as “age * gender”. \l \n \p \s Table.Specification
Use the \l switch if you want to replace variable
names with their descriptions. For example, “Age
of respondent * Gender of respondent”.
{TopSpec} The specification of the top axis. For example, \l \n \p \s Table.Axes["Top"].Specification
“gender”. Use the \l switch if you want to replace
variable names with their descriptions. For
example, “Gender of respondent”.
{TotalNumberOfTa- The total number of tables in the table document, \n \p Document.Tables.Count
bles} such as “10”.
{WeightVariable} The name of the weighting variable. For example, \l \n \p \s Table.Weight
“agebalance”. Use the \l switch if you want to
display the weighting variable’s description. For
example, “Weighting factor for age balance”.
1436
Chapter 1
Optional switches
Switch Description
\d+ Include only filters that have the IsDimensionsFilter property set to True.
\d- Include only filters that have the IsDimensionsFilter property set to False.
\e Always use the filter expression instead of the description.
\g (Used with Filters macro) Include only global filters (that is, ignore any filters
applied directly to the table).
(Used with TableNumber macro) add hierarchical numbering if the tables are
stored in folders; for example, 2.1, 2.1.1, etc.
\i+ Include only filters that have the IsInterviewFilter property set to True.
\i- (Used with Filters macro) Include only filters that have the IsInterviewFilter
property set to False.
(Used with Statistics macro) Suppress annotations for invalid statistics.
\l Displays variable descriptions (labels) instead of names. You can also specify
the context for the labels using the syntax \l:ContextName. For example,
{TableSpec \l:Question} displays the table specification using the variable
descriptions used in the questionnaire (the Question context).
If no context is specified, the labels displayed are those of the context specified
for the table document.
\n When combining more than one macro in an annotation position, you can use
this switch to add a conditional line break after the text inserted by the macro.
The line break will only be inserted if the macro inserts some text.
\p This switch can be used with all macros to add a text prefix. For example,
when used with the Filters macro, it inserts the text “Filters: “ in front of the
details of the filters.
\s Used with the CurrentTime and RunTime fields, displays the short date format
rather than the long date format.
Used with the Level, SideSpec, SortColumn, SortRow, TableSpec, TopSpec,
and WeightVariable fields, displays the short name of the field instead of the
full name. This option is ignored if you use the \l option.
\t Include only filters applied directly to the table (that is, ignore global filters).
Defining Annotations
Sample Script File: Annotations.mrs
Setting up the project description
The {ProjectDescription} macro is used in the default annotation. To set up the text for this
property, use the Description property of the Document.DataSet object. For example:
' Set up the text in the property that will be displayed by the
' {ProjectDescription} macro
TableDoc.DataSet.Description = "Museum of the Living World" ' {ProjectDescription}
1437
Base Professional
Here is a table that has been exported to HTML with the default annotations after setting up this
property:
Figure 1-473
Table showing project description and document description in the annotations
Changing the default annotations
The following example clears the built-in default settings and sets up the following new defaults:
Title Header. The table description, which is inserted using the {TableDescription} macro.
Left Header. Information about the filter is inserted using the {Filters \p} macro (using the \p
switch inserts a text prefix) and formatted in italics.
Right Footer. The table number and the total number of tables, preceded by the text “Table: ”,
which is formatted in bold.
TableDoc.Default.Annotations.ClearAll()
TableDoc.Default.Annotations[0].Specification = "{TableDescription}"
TableDoc.Default.Annotations[1].Specification = "<i>{Filters \p}</i>"
TableDoc.Default.Annotations[7].Specification = "<b>Table: </b>{TableNumber} of {TotalNumberOfTables}"
1438
Chapter 1
Here is a table that has been exported to HTML with these annotations:
Figure 1-474
Table showing table description, filter information and number of tables in annotations
Note that you should always include the {Statistics} macro in one of the table annotations when
one or more statistical tests have been defined, because the macro inserts important information
about the tests that have been carried out. In all but the very simplest tables, you would normally
also use the cell contents, filter, and weighting macros, and if you are working with hierarchical
data, you should show the level as well.
Note: To define default annotations for profile tables, use the TableDoc.ProfileDefault property.
For more information, see the topic Working with Profile Tables on p. 1443.
Defining an annotation for an individual table
The next example shows defining an annotation for an individual table. If there is already a default
annotation in that position, it will be overwritten:
TableDoc.Tables.AddNew("AgeByGender", "age * gender", "Age by Gender")

TableDoc.AgeByGender.Annotations[1].Specification = "<i>This table is not filtered</i>"
1439
Base Professional
Here is the table:

Figure 1-475
Table showing individual annotation
Defining Global Annotations
The following example defines a global annotation in the left footer position to show when the
tables were last populated, using the short date format for the computer’s current regional setting
(locale). The population time is inserted using the {RunTime \s} macro (shown in red in the
example) and it is preceded by some explanatory text:
TableDoc.Global.Annotations[5].Specification = "Last populated: {RunTime \s}"
When you use a global annotation, it is automatically applied to all of the tables in the table
document. If any of the tables have an annotation defined at the same position, the two annotations
will be combined, and each one will be placed on a new line. Note that the global annotation will
always appear first.
1440
Chapter 1
Here is the table from the second example in Defining Annotations, to which this global
annotation has been applied:
Figure 1-476
Table with global annotation showing last populated time
Adding Hypertext Links and Images to Annotations
The following example defines an annotation in the left footer position to provide a hyperlink to a
Web site. The <b> tag has been used to emphasize the explanatory text:
TableDoc.AgeByGender.Annotations[5].Specification = "<b>Please visit our WWW site at </b>" + _
"<a href=""http://www.spss.com"">http://www.spss.com</a>"
1441
Base Professional
Here is the table from the second example in Defining Annotations, to which this annotation
has been added:
Figure 1-477
Table showing text formatting and hyperlink added to annotation using html tags
The following example adds a formatted annotation for a custom property called Notes in the
left footer position. First, the script creates a custom property, defines a name and value for
the property, and adds it to the table:
.AddNew("AgeByEntrance", "Age * Entrance", "Age by Entrance")

'Create a custom property and add it to the table
Set Property = .AgebyEntrance.Properties.CreateProperty()
Property.Name = "Notes"
Property.Value = "Survey still in progress"
.AgebyEntrance.Properties.Add(Property)
Next, the script adds a left footer annotation containing a macro to display the value of the custom
property. The text is formatted using the <font> tag. Notice that the <font> tag attributes have
been enclosed in single quotation marks. Finally, the script inserts a logo in the right footer
position using the <img> tag:
.AgeByEntrance.Annotations[annLeftFooter].Specification = _
"<font color='Red' size='3' face='Verdana'>{TableProperty:Notes \p\n}</font>"
.AgeByEntrance.Annotations[annRightFooter].Specification = _
"<img src='.\logo.png'/>"
1442
Chapter 1
Here is a table with these annotations:

Figure 1-478
Table showing formatting, custom property, and image added to annotation using html tags
Valid Annotation HTML Tags
You can use a limited number of HTML tags to insert hyperlinks or define formatting in texts to
display in headers and footers (annotations). When possible, it is generally preferable to control
the formatting of the headers and footers using the export style sheets rather than HTML tags
embedded in the header and footer specifications. However, the HTML tags are useful when you
want to emphasize individual words or phrases.
Tag Attributes Description
<b>...</b> — Stong emphasis (bold).
<i>...</i> — Emphasis (italics).
<u>...</u> — Underlined.
color
<font>...</font> Font. You can use the color attribute to specify a
size color, using either the hexadecimal value or the color
face name, the size attribute to specify a size from 1
(smallest) to 7 (largest), and the face attribute to
specify a comma-separated list of font names in order
of preference.
<a>...</a> href Anchor. You can use the href attribute to insert the
URL of a web page.
<img/> src Image link. Specify the name and location of the
alt graphic in the src attribute. You can also specify
alternate text to appear when you move the mouse over
the graphic using the alt attribute. (Note that this tag
does not require a separate closing tag.)
<br/> — Inserts a line break. (Note that this tag does not require
a separate closing tag.)
1443
Base Professional
The HTML tags used must be well-formed HTML, otherwise they may not be recognized as
HTML and will appear as plain text. For example:
You must close all tags. This is particularly easy to forget when using the <br> and <img> tags,
which do not have separate closing tags. Specify the line break tag as <br/> and not <br>, or it
may appear in the exports as “<br>”. Similarly, you need to close the <img> tag, for example:
<img src='C:\CorporateImages\logo.png' alt='SPSS logo'/>
You must use the same case for opening and closing tags.
You must enclose attributes in double or single quotation marks (for example, <font size='7'>).
When using double quotation marks in your script, you need to escape each one with a second
double quotation mark (for example, <font size=""7"">).
At the time of writing, information about well-formed HTML

is available at Microsoft: Authoring Well-Formed HTML
(http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wcexmlxs/html/ceconAuthoringWell-FormedHTM
(
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wcexmlxs/html/ceconAuthoringWell-FormedHTML
).
Working with Profile Tables
Profile tables display non-aggregated respondent data for selected variables. This is particularly
useful for displaying information that is meaningful without being aggregated, such as text
responses to an open-ended question. You can create profile tables from any type of variable, and
you can add filters in the same way as for aggregated tables. For example, this profile table shows
individual responses for the visits12 and distance variables, filtered to include only respondents
with more than 4 visits in the last 12 months:
Figure 1-479
Profile table showing responses for visits12 and distance for respondents with more than 4 visits in
last 12 months
You can create profile tables using IBM SPSS Data Collection Survey Reporter Professional,
export them to a number of different output formats, and save them in table document (.mtd) files.
You can include both profile tables and aggregated tables in the same table document file. Profile
tables can also be displayed and created in IBM SPSS Data Collection Survey Reporter. Profile
tables cannot be displayed in IBM® SPSS® Data Collection Survey Tabulation; table document
1444
Chapter 1
files containing a mixture of profile tables and aggregated tables can be opened in Survey
Tabulation 4.0, but all profile tables are ignored and only the aggregated tables are displayed.
This section provides information about how to create profile tables.
Creating Profile Tables
Sample Script File: ProfileTables.mrs
This example script is based on the Household sample data set. For more information, see the
The process for creating profile tables is similar to that for creating aggregated tables, but
instead of using the AddNew method, you use the AddNewProfile method and use the syntax
"profile({variable})" to specify the profile as an axis with the variables as elements. For example,
here is a script to create a profile table for the address variable:
Set Table = TableDoc.Tables.AddNewProfile("Table1", "profile({address})",

"Responses to address question")
The resulting table shows the individual responses to the question.

Figure 1-480
Profile table showing addresses
You can display multiple variables in a profile. This script creates a profile table for the address
and numpersons variables:
Set Table = TableDoc.Tables.AddNewProfile("Table2",

"profile({address, numpersons})", "Address and number of persons")
1445
Base Professional
The resulting table shows the individual responses to the two questions:
Figure 1-481
Profile table showing addresses
Notice that there are more rows in the second table. By default, rows that contain no data for all of
the selected variables are automatically removed. As the address question was not answered by all
respondents, rows with no answer for this question are not displayed in the first table.
Filtering profile tables
As shown above, profile tables are filtered to remove rows that are completely empty, using the
default profile property FilterEmptyRows. You can remove this filter if required, by setting the
FilterEmptyRows property to False:
Table.Properties["FilterEmptyRows"] = false
You can also filter profile tables on the values in a variable as you can with aggregated tables, to
display results only for certain respondents or data. For example, the following table has a filter to
exclude results for respondents who have no pets:

"profile({housetype, numrooms, pets})", "House type and number of rooms of pet owners")
Table.Filters.AddNew("WithPets", "pets > 0", "Has one or more pets")
1446
Chapter 1

Figure 1-482
Profile table showing accommodation type, number of rooms, and number of pets, filtered to show
pet owners
Limiting the number of rows displayed
You may want to limit the number of rows displayed in a profile table to an arbitrary maximum
value. By default, the maximum number of rows displayed is 10,000. To change this, use the
MaxRows property. This script restricts the table above to show only the first five rows:
Set Table = TableDoc.Tables.AddNewProfile("Table5", "profile({housetype, numrooms, pets})",

"House type and number of rooms of pet owners, first five")
Table.Properties["MaxRows"] = 5
Figure 1-483
Profile table showing accommodation type, number of rooms, and number of pets, filtered to show pet
owners, first five responses
To display all rows, set MaxRows to -1.
Sorting profile tables
In the above table, only the first five rows are displayed. The order of the rows is based on the
order of the case data in the data set, which is typically in order of the Respondent serial ID (this is
generally the order in which the responses were collected, so that people interviewed first appear
at the top of the table). However, you may be interested in the responses of people in smaller
1447
Base Professional
houses, in which case it would be useful to sort the table. You can sort profile tables by specifying
the column to sort on. Sorting is carried out on the case data in the specified column.
If you sort a table and specify a maximum number of rows, the sorting is carried out first. The
following script uses the same table specification as above, but sorts the table by the number of
rooms in the house:
Set Table = TableDoc.Tables.AddNewProfile("Table6", "profile({housetype, numrooms, pets})",

"House type and number of rooms of pet owners, first five, sorted")
Table.Properties["MaxRows"] = 5
Table.SortColumn = "profile{numrooms}"
Table.SortColumn.Order = 0 ' 0 = oAscending
The resulting table again has five rows, but displays different results because of the sorting:
Figure 1-484
Profile table showing accommodation type, number of rooms, and number of pets, filtered to show pet
owners, first five responses, sorted by number of rooms
This table is sorted in ascending order using the syntax Table.SortColumn.Order = 0, however, you
can also sort in descending order (descending order is the default, so in that case you would
not need to specify the sort order).
Using annotations in profile tables
You can use annotations in profile tables as you can in aggregated tables, though the following
annotation macros are not applicable to profile tables and therefore they are not displayed:
{Rules}
{SideSpec}
{SortRow}
{Statistics}
{WeightVariable}
For more information, see the topic Annotations on p. 1432.

1448
Chapter 1
Default settings for profile tables
You can set up defaults for profile tables. Profile table defaults are specified separately from the
defaults for aggregated tables, using the ProfileDefault table property instead of the Default
property. For example, here is a default annotation to display the base value on all profile tables:
TableDoc.ProfileDefault.Annotations.Item[7].Specification = "{TableBase \p}"
This displays the number of rows in the table in the right footer position (position 7). If the table is
filtered, it returns the number after filtering, and if the table is truncated by setting the MaxRows
property, it returns the number of rows specified in MaxRows.
Some default settings are not suitable for profile tables and therefore are not used. You can set
profile defaults for:
Filters.
Annotations. The default annotations are as for aggregated tables; however, the default
annotations in the left footer position are not relevant to profile tables and so are not included.
You can also set defaults for the FilterEmptyRows and MaxRows properties:
TableDoc.ProfileDefault.Properties["FilterEmptyRows"] = False
TableDoc.ProfileDefault.Properties["MaxRows"] = 100
Global settings for profile tables
Global filter and annotation properties apply to profile tables. Global cell items and statistics
properties are not applicable to profile tables and are therefore ignored.
Weighting and Statistical Tests
Profile tables contain unaggregated records and therefore weighting and statistical tests are not
applicable.
Nesting
Profile tables contain unaggregated records and therefore nesting is not applicable.
Exporting profile tables
You can export profile tables to HTML, Microsoft Excel, PowerPoint, or Word, or delimited text
files, using most of the same export options that are available for aggregated tables. As profile
tables do not produce charts, chart export options are not applicable.For more information, see the
topic Exporting Tables on p. 1477.
Saving profile results in a table document file
As with aggregated tables, you can save profile tables in a table document file. You can also
choose whether to omit profile results from the table document file and save only the table
structure. Profile tables are relatively quick to generate but can result in an extremely large table
1449
Base Professional
document file which is then slow to open, so it can be helpful to store only the structure of profile
tables in the .mtd file. Users can then generate the tables as required.
By default, profile tables are saved with results. Here is a script to save profile tables without
the results:
With TableDoc
.SaveProfileResults = False
.Save(OUTPUT_FILE)
End with
Creating Profile Tables with Hierarchical Data
Profile results are displayed at the level of the lowest level variable included on the table.
Respondent data from upper levels is down-leved to the lower level. For example, this table shows
the address variable with the addition of the person.name variable:

"profile({address, person.name})", "Variables at different levels")
1450
Chapter 1
Figure 1-485
Profile table of address and name
Notice that the address column contains duplicate addresses in some of the rows, as the addresses
are repeated for each person at that address.
It is also possible to specify a lower level if all the variables are at a higher level; for example, you
can create a table showing address and number of rooms, but display it at the person level:
Set Table = TableDoc.Tables.AddNewProfile("Table8", "profile({address, numrooms})",

"Higher level variables tabulated at a lower level")
Table.Level = "person"
1451
Base Professional
The resulting table has duplicate values for some rows, as they are repeated for each person:
Figure 1-486
Profile table of address and numrooms tabulated at person level
You can also tabulate a higher level variable with a slice of a lower level variable; for example,
this script creates a table to show names and addresses for the first person in the household:
Set Table = TableDoc.Tables.AddNewProfile("Table9", "profile({address, person[1].name})",

"Slice of lower level variable")
1452
Chapter 1
Figure 1-487
Profile table of address and name of first person in household
Profiling grid slices
You can create profile tables using grid slices, for example, this script creates a table for the
“Channel 1” slice of the person.tvdays grid variable:
Set Table = TableDoc.Tables.AddNewProfile("Table10", "profile({person.tvdays[{channel_1}].column})",

"Slice of grid variable")
The grid slice is considered to be at the level of the grid (person.tvdays in this example) and so
the table can only be populated at that level. The table shows the number of days that people
watched Channel 1.
1453
Base Professional
Figure 1-488
Profile table of channel 1 grid slice in person.tvdays
Note: You cannot create profile tables containing variables that are on parallel branches, as it is not
possible to up-lev the variables to a common level.
Formatting Profile Tables
You can format the content of the cells in the profile table in various ways. For example, you can
restrict the number of characters displayed using the FormatExpression property of the CellItem
object. This is useful when you have open-ended responses that contain very long text responses
to questions. For example, the following script restricts the size of responses so that only the first
50 characters are displayed:
TableDoc.ProfileDefault.CellItems[0].FormatExpression = "Left(CText(Value), 50)"
For further details see the Table Object Model Reference help for the FormatExpression property.
Working with Metadata

When you work with the Table Object Model, you can access the metadata in the MDM Document
using the Table Object Model Document.DataSet.MDMDocument property. The MDM Document
is returned in no-save mode, which means that any changes you make are not saved.
1454
Chapter 1
The MDM Document, part of the Metadata Model, is documented in the Data Model section of
the IBM® SPSS® Data Collection Developer Library. For a detailed reference to the MDM
Document, see MDM Object Model in the Data Collection Developer Library’s Data Model
Reference section
This section covers working with versions, labels, and languages.
Working with Versions
Sample Script Files: WorkingWithVersions.mrs, RDBTables.mrs.
These example scripts are based on the Short Drinks sample data set. To run examples using the
Short drinks sample data set, you need access to an SQL Server installation on which the Short
Drinks sample database has been restored, and appropriate user access rights. . See also Running
the Sample Table Scripts for information on running the example scripts.
As a survey progresses, changes are sometimes made to the questionnaire. For example, questions
and categories may be added and deleted. Typically a new version is created in the metadata each
time a change is made to the questionnaire and each version corresponds to a variation of the
questionnaire used for some of the interviews.
By default, when you load a data set that contains more than one version, all of the versions are
combined to form a superset (sometimes called a superversion). This means that all of the
variables and categories from all of the versions are available. When there is a conflict between,
for example, a text in one or more of the versions, the more recent versions generally take
precedence over the older versions. It is possible to load a particular version or versions and to
change the order of precedence. However the order of questions and categories is always taken
from the most recent version.
You select the metadata version you want to load by specifying a in the sixth parameter of the
DataSet.Load method. The order in which you specify the versions in the expression defines the
order of precedence. For example, the following loads version 2:
,_
"mrRdbDsc2", _
"short_drinks", _
"{2}")
The following script loads a superset of versions 2 through 4, with the older versions taking
precedence over the newer ones:
,_
"mrRdbDsc2", _
"short_drinks", _
"{4..2}")
1455
Base Professional
It is important to understand that the version of the metadata you select does not affect
the case data that is loaded. However, case data collected using IBM® SPSS® Data
Collection Interviewer Server has the name of the version used to collect it stored in the
DataCollection.MetadataVersionNumber This means that it is easy to filter Interviewer Server
case data based on the version used to collect it. Typically you would create the filter as a global
filter, which means that it will be applied to all tables automatically. For example:
TableDoc.Global.Filters.AddNew("Version2Only", _
"DataCollection.MetadataVersionNumber = ""2""")
Note: In data collected using tools other than Interviewer Server, the
DataCollection.MetadataVersionNumber system variable may not store the name of
the version, depending on how the data was set up.
You can request the DataCollection.MetadataVersion derived categorical system variable that
automatically contains a category for each version that is loaded. The categories have names of
the form Ver_n, where n is the version name. This variable provides an alternative way of filtering
the case data on the version of the metadata used to collect it. For example:
' Switch on the DataCollection.MetadataVersionNumber system variable
TableDoc.DataSet.MDMDocument.EnableMetadataVersionVariable = True
"DataCollection.MetadataVersion = {Ver_2})
You can also use this variable to tabulate variables by the version. For example:
"DataCollection.MetadataVersion * gender", "Metadata version by gender")
Here is the table:

Figure 1-489
Table showing Metadata Version by Gender
Note that you can use the {MetadataVersion} annotation macro to display the version expression
that was used when loading the data. For example:
TableDoc.Default.Annotations[1].Specification = "<B>Version: </B>{MetadataVersion}"
For more information, see the topic Annotation Macros on p. 1434.

1456
Chapter 1
Examples
This section walks you through some exercises that are designed to help you understand working
with a data set that has multiple versions. The exercises use the sample. The following table
provides details of the important differences in each of the five versions in the Short Drinks
sample .mdd file:
Version Name Description
Server project was activated in test mode and was
used for collecting test data. 5 cases were collected
using this version.
Server project was first activated in live mode. 45
cases were collected using this version. There were
no significant changes in this version.
3 In this version a new category (Fulltime parent)
was added to the sclass question. 24 cases were
collected using this version.
4 In this version the 7 or more people category was
deleted from the hhsize question and the text on the
6 people category was changed to 6 or more people.
20 cases were collected using this version.
5 In this version the text of the Fruit drinks category
in the numdrksz question was changed to Fruit and
vegetable drinks and the sclass categorical question
was deleted and replaced with an open-ended
question called occup. 27 cases were collected
using this version.
E First let’s run the WorkingWithVersions.mrs sample, which selects version 2 of the metadata and
filters the case data to select only respondents who were interviewed using version 2.
The WorkingWithVersions.mrs sample creates two tables, the first is a table of hhsize by gender
and the second is a table of sclass by gender. Here is the first table:
Figure 1-490
Table showing household size by gender: Version 2
1457
Base Professional
Notice that annotations have been used to show the metadata version and the case data filter.
E Now amend the WorkingWithVersions.mrs to select version 5 of the metadata and filter the case
data on version 5. You do this by changing the Version parameter of the DataSet.Load method to
“5” and the literal in the filter expression to 5:
TableDoc.DataSet.Load("("..\..\..\Data Model\Samples\Data\Mdd\short_drinks.mdd", _
,_
"mrRdbDsc2", _
"short_drinks", _
"{5}")
.
.
.
"DataCollection.MetadataVersionNumber = ""5""")
E Now try to run the sample.
You will find you will get the error: “The variable ‘sclass’ does not exist”. This is because the
sclass variable was deleted in version 5 and so is not available when you load version 5 only.
E Now delete or “comment out” the line that creates the second table and run the sample again.
Now the script should run successfully. Here is the table of hhsize by gender:
Figure 1-491
Table showing household size by gender: version 5
Notice that the 7 or more people category that was deleted in version 4 is no longer visible and
the text on the 6 people category now says 6 or more people, reflecting the change made to
the category in version 4.
E Now let’s run the RDBTables.mrs sample, which does not specify a version expression in the
Version parameter of the DataSet.Load method. This means that it uses the default behavior,
which is to open a combination of all versions.
Here is the table of hhsize by gender. This time the case data is not filtered.
1458
Chapter 1
Figure 1-492
Table showing household size by gender: all versions
Notice that the annotation shows the version expression as {..}, which indicates all versions. You
may also notice that all of the categories are present, including the 7 or more people category that
was deleted in version 4. The text on the 6 or more category now reflects the text in the latest
version and the order of the categories reflects the order of the latest version, except that the
category that was deleted in version 4 has been added at the end.
E Now, let’s make the texts reflect the texts in the earlier version, by changing the sample to specify
the versions in reverse order:
TableDoc.DataSet.Load("..\..\..\Data Model\Samples\Data\Mdd\short_drinks.mdd", _
,_
"mrRdbDsc2", _
"short_drinks", _
"{5..1}")
Here is the table:
Figure 1-493
Table showing household size by gender: all versions in reverse order
1459
Base Professional
Notice that although the texts are now taken from the earlier version, the order of the categories
has not changed. This is because the order of the categories is always taken from the latest version,
with categories that have been deleted from the latest selected version added at the end. However,
you can reorder the categories by specifying the required order in the element specification.
E Now let’s reorder the categories by using the following element specification syntax:
"hhsize{HH_1, HH_2, HH_3, HH_4, HH_5, HH_6, HH_7, NA} * gender", _
"Household size by gender")
Here is the table:

Figure 1-494
Table showing household size by gender: all versions with reordered categories
Changing the Base to Reflect the Version
Sample Script File: PercentageOnElementsAsked.mrs
This example script is based on the Short Drinks sample data set. To run examples using the Short
drinks sample data set, you need access to an SQL Server installation on which the Short Drinks
sample database has been restored, and appropriate user access rights. . See also Running the
Sample Table Scripts for information on running the example scripts.
In IBM SPSS Data Collection Survey Reporter Professional version 2.2 and later, you can
use the function to determine whether a particular element exists in a particular version of the
metadata. This can be used to take into account the fact that not all categories or all variables
may be available in all versions of a questionnaire. For example, in the Short Drinks data set the
Socioeconomic Class variable (sclass) occurs in versions 1-4 of the questionnaire and the Fulltime
Parent category of that variable exists only in versions 3 and 4.
One way to use this function is in an expression that defines a base element, for example:
base('<variable_name>.IsElementInVersions
({category_name}, DataCollection.MetadataVersionNumber)
AND <variable_name> IS NOT NULL)')
1460
Chapter 1
Note that in these examples, the expression is presented on multiple lines for clarity. In practice
you should specify the expression without line breaks.
For each record in the case data, the IsElementInVersions function checks to see if the specified
category was available in the version of the questionnaire that the respondent was asked (this is
determined by the value of the DataCollection.MetadataVersionNumber variable). If the category
was available and the question itself was asked, the expression returns True, otherwise it returns
False. The base element counts the number of respondents for which the expression is True.
The following expression shows the test being carried out on the Fulltime Parent category of
the Socioeconomic class variable.
base('sclass.IsElementInVersions
({PARENT},DataCollection.MetaDataVersionNumber)
AND (sclass IS NOT NULL)')
An example of the output of this expression for the Fulltime Parent category for selected
respondents is shown in the following table.
Respondent Response Metadata Version Result of Expression
15 {w_collar} 2 False
61 {not_work} 3 True
62 {parent} 3 True
68 null 3 False
87 {shopkeeper} 4 True
98 null 5 False
For respondents 15 and 98 (who were asked metadata versions 2 and 5) the expression returns
False because the parent category did not exist in those versions. For respondent 68 the expression
returns False because the respondent was not asked the sclass question (the response is null). For
respondents 61, 62, and 87, the expression returns True because the metadata version asked
contains the parent category (notice that this is independent of the actual answer given).
Example
The PercentageOnElementsAsked.mrs sample script is based on the Short Drinks data set. It uses
the IsElementInVersions function to define a unique base for each category in the sclass variable,
reflecting the number of times the category was available as a possible answer to respondents
who were asked the question about socioeconomic class. The script then uses this unique base
to calculate percentages for the number of respondents whose answers fell into each category,
compared to the number of respondents who were offered the category as a response.
The script creates three tables, all with Socioeconomic Class on the side axis and Metadata
Version on the top axis. In the first table, the percentages for each category are calculated using
the number of respondents who were asked the question about socioeconomic class:
"sclass * DataCollection.MetadataVersion", _
"The variable sclass tabulated as normal")
1461
Base Professional
Figure 1-495
Table showing Socioeconomic class by Metadata version. Percentages are calculated based on number
of respondents who were asked the question
Notice that the overall percentage across for the Fulltime Parent category is 5%. This figure
represents the percentage for this category across all versions, including those in which it was not
available.
In the second table, an axis expression is used to add unique base elements associated with each
category element. These bases show the number of times each sclass category was asked. The
percentages for each category are then calculated using the number of respondents who were
asked the particular category, rather than the entire question:
CreateAxisSpec(TableDoc, "sclass", True, "") + " * DataCollection.MetadataVersion", _
"The variable sclass with individual element bases inserted and percentaged on")
1462
Chapter 1
Figure 1-496
of respondents who were offered the category as a response to the question
Notice that the overall percentage for the Fulltime Parent category is now 12%, representing the
number of times the category was answered compared to the number of times it was available
to be answered.
The third table uses a similar axis expression, but this time it prevents the new base elements from
being displayed in the table, while still using them to calculate the percentages for each category:
Set Table = TableDoc.Tables.AddNew("Table03", _
CreateAxisSpec(TableDoc, "sclass", False, " *") + " * DataCollection.MetadataVersion", _
"The variable sclass with the individual element bases hidden")
An asterisk (*) is added to the label for any element that was not included in all the versions of the
metadata that appear in the table. An annotation provides a key for this symbol in the table:
Table.Annotations[annTitleFooter].Specification = "* - Category does not exist in all versions"
1463
Base Professional
Figure 1-497
of respondents who were offered the category as a response to the question. Bases are hidden.
The tables above show the results of running the script on versions 1-4 of the data. You can
see the effect of running this script on different versions of the questionnaire by changing the
MDD_VERSION constant at the start of the script.
' Const MDD_VERSION = "{..}" ' All versions of the metadata

Const MDD_VERSION = "{1..4}" ' sclass variable exists in versions 1 to 4
' Const MDD_VERSION = "{3,4}" ' "Fulltime Parent" category only exists in versions 3 and 4
Working with Labels
Sample Script File: WorkingWithLabels.mrs
By default, IBM SPSS Data Collection Survey Reporter Professional creates labels for the axes
and elements in your tables from the labels in the variables and categories on which they are based.
1464
Chapter 1
Figure 1-498
Axis and element labels in a table
In the MDM Document, labels for variables and elements are stored in a two-dimensional array
for each language, in which the dimensions are user contexts and label types.
User contexts. These define different usages for the metadata, so that different texts and
custom properties can be used depending on how the metadata is being used. For example,
the Question user context is typically used to define the texts for use during interviewing and
the Analysis user context is typically used to define shorter texts for use when analyzing the
response data.
Label types. These enable different types of labels to be created for different types of
information. For example, the default label type of Label is used for question and category
texts and variable descriptions, and the Instruction label type is used for interviewer
instructions.
By default, IBM SPSS Data Collection Survey Reporter Professional creates the axis and
element labels from the variable and element labels in the Analysis user context and the default
label type. However, you can change the user context and the label type if necessary, using the
Document.Context and Document.LabelType properties. For example, to use the Question user
context, set the Document.Context property to “Question”:
TableDoc.Context = "Question"
Note that changing the user context or label type in the table document does not change the
current user context or label type for the MDM document, which is exposed through the
Document.MDMDocument property.
Sometimes, you may find that you want to use a user context that doesn’t have texts for all the
variables and categories you want to use. When this happens, you can define an alternative context
that should be used when texts are not available in your first choice user context. For example, to
specify that texts should be taken from the Analysis user context when they are not available in
the Question user context, you would use script similar to this:
TableDoc.DataSet.MDMDocument.Contexts.Item["Question"].Alternatives.Add("Analysis")
1465
Base Professional
You can overwrite the labels that the Table Object Model creates for an axis using the Axis.Label
property. For example, the following changes the label of the expect axis, which is on the side of
the table:
MyTable.Side.expect.Label = "Expectation of visit"
This example makes use of the dynamic property expansion feature of mrScriptBasic, which
enables you to access the expect item as if it is a property of the Side axis. Note that you cannot
use this feature with variables that have a period (.) in their name (for example, variables that are
inside a grid or loop). For these variables you would define the axis label like this:
MyTable.Side.SubAxes["expect"].Label = "Expectation of visit"
If you want to change the label for use in multiple tables, it is easier to change it in the MDM
Document, because then it will apply to all tables. For example:
TableDoc.DataSet.MDMDocument.Fields["expect"].Label = "Expectation of visit"
The MDM Document is opened in no-save mode, which means that any changes you make are
not saved.
You can overwrite the labels that the Table Object Model creates for an element using the Element
List Syntax or the Element.Label property. For example, if you want to change the label on the
autobase element to read “Total” instead of “Base”, you can use script similar to the following:
MyTable.Side.MyAxis.Elements.Base.Label = "Total"
When defining labels for axes and elements, the language is assumed to be the currently selected
language if you do not specify otherwise. If you are working in a multilingual environment and
want to specify a label for a different language, you simply specify the language code. For more
information, see the topic Working with Languages on p. 1467.
When you export your tables, you can optionally export the axis and element names instead of the
labels. You do this by setting the UseVariableLabels and UseElementLabels export properties to
False. For example:
TableDoc.Exports["mrHtmlExport"].Properties["UseVariableLabels"] = False
A complete example
This example does the following:

Creates top line tables for all of the simple categorical variables in the IBM® SPSS® Data
Collection Paper routing. This means that the tables are created in the same order as they
appear on the questionnaire.
Sets the user context to Question in both the table document and the MDM document.
Changes the text on the autobase element to read “Total” instead of “Base”.
1466
Chapter 1
Sets up the table description to show the variable short name (which stores the question
number) as well as the question text.
Uses the UseVariableLabels export property to export the variable names rather than the
variable labels.
' Set the user context in the table document to Question

TableDoc.Context = "Question"
' Set the current user context in the MDM Document to Question
TableDoc.DataSet.MDMDocument.Contexts.Current = "Question"
' Set the Analysis context as an alternative for Question.

' This means that if texts are missing in the Question context,
' they will automatically be taken from the Analysis context.
TableDoc.DataSet.MDMDocument.Contexts.Item["Question"].Alternatives.Add("Analysis")
Dim MyCounter, i, MyRoutingItem, MyField, MyTableName, MyTableSpec, MyTableDescription
' Set the counter to zero

MyCounter = 0
' Loop through the IBM SPSS Data Collection Paper routing items
' and create a top-line table for all of
' the simple categorical variable instances in the routing
' that have a short name defined
For i = 0 To TableDoc.DataSet.MDMDocument.RoutingItems.Count - 1
Set MyRoutingItem = TableDoc.DataSet.MDMDocument.RoutingItems.Item[i]
Set MyField = TableDoc.DataSet.MDMDocument.Fields[MyRoutingItem.Name]
' Test that it is a simple variable and that the short name label isn't blank
If MyField.ObjectTypeValue = 0 _
And Not MyField.Labels["ShortName"].Text["Question"].IsEmpty() Then
' Check that it's a categorical variable
If MyField.DataType = mr.Categorical Then
MyTableSpec = MyField.FullName
MyTableDescription = MyField.Labels["ShortName"].Text
MyTableDescription = MyTableDescription + ": " + _
MyField.Labels["Label"].Text
' Set the label on the Autobase element to read "Total" instead of "Base"
TableDoc.Tables[MyTableName].Side.SubAxes[MyTableSpec].Elements.Base.Label = "Total"
End If
End If
Next

TableDoc.Populate()
' Export the tables

1467
Base Professional
' Export variable names rather than labels

.Properties["UseVariableLabels"] = False

.Export("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\WorkingWithLabels.htm")
End With
Figure 1-499
HTML file output by WorkingWithLabels.mrs script, showing table of contents with table 14 selected
Working with Languages
Sample Script Files: WorkingWithLanguages.mrs, JapaneseTables.mrs
These example scripts are based on the Museum sample data set. See Running the Sample Table
If the metadata has been translated, you can choose to create the tables in any of the languages that
are available. For example, the metadata in the Museum XML sample (museum.mdd) has been
translated into Spanish and Japanese, so you can easily create tables in either of these languages.
You select the language to be used by setting the Document.Language property to the
three-character code of the language you want to use. For example, to set the language to Spanish:
TableDoc.Language = "ESN"
1468
Chapter 1
The Element List Syntax topic provides examples of setting up custom element labels for use in
the current language and in more than one language. The following script creates two tables: the
first uses the default labels defined in the metadata and the second uses custom element labels that
are defined in two languages (English and Spanish):
.AddNew("Table1", "age * gender", "Edad por Género")
.AddNew("Table2", "interest{Dinosaurs ENU:'Extinct reptiles' " + _
"ESN:'Reptiles extintos', Whales ENU:'Large marine mammals' " + _
"ESN:'Mamíferos marinos grandes'} * gender", _
"La galería más interesante por Género")
End With
You can also define custom labels for the variables. For example, the following defines a custom
label in Spanish for the interest variable in the second table:
TableDoc.Tables.Table2.Side.Interest.Label["ESN"] = "La galería más interesante"
This example makes use of the dynamic property expansion feature of mrScriptBasic, which
enables you to access the Interest item as if it were a property of the Side axis. Note that you
cannot use this feature with variables that have a period (.) in their name (for example, variables
that are inside a grid or loop). For these variables you would specify the custom label like this:
TableDoc.Tables.Table2.Side.SubAxes["Interest"].Label["ESN"] = "La galería más interesante"
Note that if you do not specify the language code, the custom label will apply to the currently
selected language only.
When you are working with foreign languages, make sure that you save your script file using the
Unicode or UTF-8 text format option and not the ANSI option.
Here is the table that uses the default Spanish texts:

Figure 1-500
Table of Age by Gender with default Spanish labels
1469
Base Professional
Here is the table that uses the Spanish texts we defined in the script:
Figure 1-501
Table of Interest by Gender with customized Spanish labels
The default label (Base) that IBM SPSS Data Collection Survey Reporter Professional creates for
the autobase element is suitable for use in Spanish. However, in some languages you may want to
specify a translation. The following example sets the language to Japanese, sets up some tables
and changes the text on the autobase elements:
TableDoc.Language = "JPN"
.AddNew("Table1", "age * gender")
.Table1.Side.Age.Elements.Base.Label = "<Japanese text>"
.Table1.Top.Gender.Elements.Base.Label = "<Japanese text>"
.AddNew("Table2", "interest{Dinosaurs, Whales} * gender")
.Table2.Side.Interest.Elements.Base.Label = "<Japanese text>"
.Table2.Top.Gender.Elements.Base.Label = "<Japanese text>"
End With
Here is the second table:

Figure 1-502
Table of Age by Gender with labels in Japanese
Working with Change Tracker

Note: Whenever possible, the Variables Interface should be used instead of Change Tracker. The
Variables Interface provides the same functionality as Change Tracker, as well as simplifies
the creation of new variables and allows variable lists to be configured in script. For more
information, see the topic Working with the Variables Interface on p. 1475.
1470
Chapter 1
You may find it useful to script variable folders and store derived variables or other metadata edits
in .mtd files. Variable folders provide an effective means of improving data organization and
navigation. Change tracker supports the process of automated folder creation through scripting
which in turn provides key efficiency benefits.
This section covers the .mrs scripts that support change tracker.
For more information, see the topic Metadata Services Object Model Reference on p. 1560.
Change Tracker - Functions
Sample Script File:ChangeTrackerFunctions.mrs
This example script includes functions that assist in modifying Table Object Model metadata. See
For example:
Enable the change tracker
Function ChangeTracker_Enable(objTableDoc)
Const Context_ChangeTracker = "__MetadataServices_ChangeTracker"
Dim objMDMDoc, objChangeTracker, objContext, bHasChangeTracker
Set objMDMDoc = objTableDoc.DataSet.MdmDocument
bHasChangeTracker = False
For Each objContext in objMDMDoc.RoutingContexts
If objContext.Name = Context_ChangeTracker Then
bHasChangeTracker = True
Exit For
End If
Next
If Not bHasChangeTracker Then
objMDMDoc.RoutingContexts.AddEx(Context_ChangeTracker, True)
End If
objMDMDoc.RoutingContexts.Current = Context_ChangeTracker
' Get the ChangeTracker

Set objChangeTracker = ChangeTracker_GetChangeTrackerObject(objTableDoc)
objChangeTracker.RoutingContextNames = Context_ChangeTracker
' Add all fields to Rounting

Dim oField
For Each oField In objTableDoc.DataSet.MdmDocument.Fields
objTableDoc.DataSet.MdmDocument.Routing.AddNewItem(oField, Context_ChangeTracker)
Next
' Return
Set ChangeTracker_Enable = objChangeTracker
End Function
1471
Base Professional
Obtain the change tracker object
Function ChangeTracker_GetChangeTrackerObject(objTableDoc)
Set ChangeTracker_GetChangeTrackerObject = objTableDoc.DataSet.MdmChangeTracker
End Function
Record the specific field in the added tracker
Sub ChangeTracker_AddField(objTableDoc, objField)

objField.Properties.Item["IsUserDefined"] = True
Dim objChangeTracker
Set objChangeTracker = ChangeTracker_GetChangeTrackerObject(objTableDoc)
objChangeTracker.AddField(objField)
End Sub
Create a folder
Function ChangeTracker_CreateFolder(ObjMDMDoc, strFolderName, lngIndex)

Dim objFolder
Set objFolder = ObjMDMDoc.CreateFolder(strFolderName)

ObjMDMDoc.Routing.AddNewItem(objFolder, "__MetadataServices_ChangeTracker", lngIndex)
' Return
Set ChangeTracker_CreateFolder = objFolder
End Function
Add a field to a folder
Sub ChangeTracker_AddFieldToFolder(objMdmDoc, objFolder, objField)

objFolder.AddNewItem(objField, "__MetadataServices_ChangeTracker")
End Sub
'Return the index of the specific field's routing item

Function Routing_GetFieldIndexOf(objRouting, objField)
Dim lngIndex, objRoutingItem
For lngIndex = 0 To objRouting.Count("__MetadataServices_ChangeTracker") - 1

Set objRoutingItem = objRouting.Item[lngIndex]
If objRoutingItem.Item = objField Then
Routing_GetFieldIndexOf = lngIndex
Exit Function
End If
Next
' Return
Routing_GetFieldIndexOf = -1
End Function
1472
Chapter 1
Change Tracker - Modifying Metadata in a New Table Document
Sample Script File:ChangeTrackerTest1_NewDocument.mrs
This example script demonstrates how to modify metadata and save the modifications to a table
document file. The saved .mtd file is used by the script ChangeTrackerTest2_OpenDocument.mrs.
The script produces the following tables:

Figure 1-503
Change tracker using the modified ‘before’ field
1473
Base Professional
Figure 1-504
Change tracker using the renamed field ‘gender_new’
The following script modifies the before field, renames the gender field, creates a new folder, and
moves the fields age, before, and visits into the new folder:
' Modify field
Dim oField
Set oField = MDMDoc.Fields["before"]
oField.AxisExpression = "{base(), Yes, No, comb 'Answered' combine({Yes, No}), Not_answered}"
ChangeTracker_ModifyField(TableDoc, oField)
' Rename field

Set oField = MDMDoc.Fields["gender"]
Set oField = ChangeTracker_RenameField(TableDoc, oField, "gender_new")
' Create folder

Dim oFolder
Set oFolder = ChangeTracker_CreateFolder(MdmDoc, "Folder1", 0)
' Move field to folder1

Set oField = MdmDoc.Fields["age"]
ChangeTracker_MoveFieldToFolder(MdmDoc, oFolder, oField)
Set oField = MdmDoc.Fields["before"]
ChangeTracker_MoveFieldToFolder(MdmDoc, oFolder, oField)
' Add field to folder1

Set oField = MdmDoc.Fields["visits"]
ChangeTracker_AddFieldToFolder(MdmDoc, oFolder, oField)
1474
Chapter 1
Change Tracker - Modifying Metadata in an Existing Table Document
Sample Script File:ChangeTrackerTest2_OpenDocument.mrs
This example script demonstrates how to open a table document that includes change
tracker records, how to modify metadata, and how to save the modifications to a table
document file. The table document used in this example is created with the script
ChangeTrackerTest1_NewDocument.mrs.
The script produces the same tables as the ChangeTrackerTest1_NewDocument.mrs script, as

well as the following table:
Figure 1-505
Change tracker using the ‘biology’ field in Folder2
The following script modifies the renames the expect field, creates a new folder, and moves
the biology field into the new folder:
' Rename field
Set oField = MDMDoc.Fields["expect"]
ChangeTracker_RenameField(TableDoc, oField, "expect_new")
' Create folder

Dim oFolder
Set oFolder = ChangeTracker_CreateFolder(MDMDoc, "Folder2", 1)
1475
Base Professional
' Move field to Folder2

Set oField = MDMDoc.Fields["biology"]
ChangeTracker_MoveFieldToFolder(MDMDoc, oFolder, oField)
Working with the Variables Interface

The creation of new variables has been simplified and variable lists can now be configured in
script. The configuration of variable lists in script is similar to functionality that is available in
the Tables Object Model (TOM) for table grouping. For more information, see the topic Table
Object Model Reference on p. 1556.
The Dataset Variables object
The variables list functionality is accessible through a Variables property on the DataSet
object. The design of the Variables object is based on the design of the Grouped Tables object.
When accessed, the Variables list is populated based on the Metadata Services ChangeTracker
routing. If the routing does not exist, it is added and populated based on the metadata order. See
IVariableListItem (ms-its:tom.chm::/IVariableListItem.html) for more information.
Note: Variables that are added via TOM.DataSet.Variables are persisted in a .dms script, in the
output .mdd, but are not persisted in an.mrs script.
Organizing Questions with the Variables Interface
Sample Script File:TomVariablesDemo.mrs
This example script includes functions that assist in modifying Table Object Model metadata. See
For example:
Rename a variable
Set varItem = vars.Item["order[..].column"]

debug.LogIf(varItem.Name<>"Column", "Item Operation Error")
vars.Rename(varItem.MdmField, "NewColumn")
set varItem = vars.Item["order[..].NewColumn"]
debug.LogIf(varItem.Name<>"NewColumn", "Rename then Item Operation Error")
Create and rename a folder
' Create a folder as root

Set folderRoot = vars.AddNewFolder("RootFolder", 0)
' Rename the folder name as MyRootFolder

folderRoot.Rename(folderRoot.MdmField,"MyRootFolder")
1476
Chapter 1
debug.LogIf(folderRoot.Name <> "MyRootFolder", "Rename Error!")
folderRoot holds the reference to the folder. You can add other variables or folders to a folder
through folderRoot.
Add a child folder and add variables
' Add a child folder to the root folder

Set folderGrid = folderRoot.AddNewFolder("MyGridFolder")
debug.LogIf(folderRoot.Item[0].Name <> "MyGridFolder", "Item[0] is not MyGridFolder")
' Add the question "Age" to the root folder

Set field = TableDoc.DataSet.MdmDocument.Fields["age"]
folderRoot.Add(field)
debug.LogIf(folderRoot.Item[1].Name <> "age", "Item[1] is not age")
' Add the grid question "Order" to the foderGrid folder

Set field = MDMDoc.Fields["Order"]
folderGrid.Add(field)
Add new variables to a specific folder
' Add a new variable to the root folder

vars.AddNewVariable("age2 ""Address "" text;")
' Add a new variable to the MyRootFolder folder

Set varItem = folderRoot.AddNewVariable("!
MyAge "Age of respondent"
categorical [0..1]
{
E1116_years "11-16 years" factor(13.5),
E65_years "65+ years" factor(69.5)
};
!")
Modify and update a variable
Set field = MDMDoc.Fields["Age"]

field.AxisExpression = "{base()}"
folderGrid.Update(field)
1477
Base Professional
Iterate through the variables in a folder
' Test the forEach Interface of the IVariableListItem

for Each varListItem In folderRoot
debug.LogIf(varListItem.Name = "", "for Each error")
next
Retrieve a reference to IVariableListItem in a folder
' Test the Item property of IVariableItemList

Set varItem = folderGrid.Item["Order"]
debug.LogIf(varItem.MdmField.FullName <> "order", "error In VariableListItem.Item")
Create a derived grid variable
' Add a new grid based on categorical variables

Set varItem = vars.AddNewGrid("age,before", "MyDerivedCategoricalGrid", "Age and Before")
TableDoc.Tables.AddNewGrid("GridTable1", "MyDerivedCategoricalGrid")
' Add a new grid based on text variables

Set varItem = vars.AddNewGrid("address,name", "MyDerivedTextGrid", "Address and Name")
Obtain the count
count = folderRoot.Count
Remove a variable from a folder
folderRoot.Remove(1)
debug.LogIf(folderRoot.Count <> count -1, "Remove Error")
Exporting Tables
This section covers exporting your tables to HTML, Text (.csv), Microsoft Excel, PowerPoint,
and Word.
Note: You can greatly improve table export performance by selecting the Microsoft Office
Document Image Writer as the default print driver when exporting to Office applications. If the
print driver in not already installed on your system, you can install it from the Microsoft Office
installation CD.
Enabling security access for Microsoft Excel, Word, and PowerPoint exports
Security settings in Microsoft Excel, Word, or PowerPoint may prevent you from exporting to
these applications. If this occurs, you can enable the export to run by changing a security setting
in Microsoft Excel, Word, or PowerPoint. If you need to change the setting on your machine,
1478
Chapter 1
a message will inform you of this. Follow the instructions below to change the settings. If you
are in doubt about whether changing security settings is permitted by your organization, please
contact your system administrator.
Note: Ensure that you have the latest Microsoft Office service pack installed. To check this, choose
the Check for Updates option on the Microsoft Excel Help menu to display the Microsoft Office
Downloads page, where you can download the latest service pack.
Microsoft Office 2007 or above
Note: Setting the security options in one program does not set them in the other. You may need to
follow these steps for Excel, Word, and PowerPoint depending on your existing security settings.
In Microsoft Office 2007, macro security settings are located in the Trust Center.
E Ensure that IBM® SPSS® Data Collection Base Professional and all Microsoft Office applications
are closed.
E Open Excel, Word, or PowerPoint.
E Click the Microsoft Office button.
E Click the Excel Options, Word Options, or PowerPoint Options button.
E Click
Trust Center > Trust Center Settings
E In Excel, additionally click Macro Settings.
E Select the Trust access to the VBA project object model check box.
E Click OK to apply the setting.
E Close Excel, Word, or PowerPoint.
For more information, see Enable or disable macros in Office documents

(http://office.microsoft.com/en-us/help/HA100310711033.aspx) at
http://office.microsoft.com/en-us/help/HA100310711033.aspx.
HTML Tables Export
IBM SPSS Data Collection Survey Reporter Professional provides an HTML Export component
that enables you to export tables and charts to HTML. The component has been designed to be
easily configurable in order to make it easy to customize the HTML output.
Note: The HTML export uses the Office Web Components (OWC) version 10 or later to create
charts. This means that to export charts, you need to have Office Web Components (OWC)
version 10 or later installed on your desktop machine. However, this is not necessary if you
only want to export tables.
1479
Base Professional
HTML Tables Export Layout Styles
Sample Script File: HTMLExportOptions.mrs
The following table lists the layout styles that are built into the HTML Export component.
Layout Style Description
Single Document All of the tables and/or charts are exported to one
HTML document, which has a table of contents
at the top (provided that more than one table is
exported). By default the tables, charts, or table and
chart pairs are separated by a printing page break.
Table of Contents The table of contents and each table and/or chart are
exported to a separate HTML Document. You can
navigate the pages using the table of contents.
Frame Table of Contents Each table, chart, or table and chart pair are exported
to a separate document with the table of contents
visible in a separate frame on the left side.
You select the layout style using the LayoutStyle export property.
If the table document has been given a description (in the Document.Description property), all
three layout styles display the description above the table of contents. For example, in the
following examples, the Document.Description property has been set to “Museum Survey”.
Examples
1. Single Document
To select the Single Document layout style, set the LayoutStyle export property to “Single
Document”:
TableDoc.Exports.mrHtmlExport.Properties["LayoutStyle"] = "Single Document"
1480
Chapter 1
Here is an example of the output:

Figure 1-506
HTML export with single document layout
2. Table of Contents
To select the Table of Contents layout style, set the LayoutStyle export property to “Table of
Contents”:
TableDoc.Exports.mrHtmlExport.Properties["LayoutStyle"] = "Table of Contents"
1481
Base Professional

Figure 1-507
HTML export with table of contents layout
3. Frame Table of Contents
To select the Frame Table of Contents layout style, set the LayoutStyle export property to “Frame
Table of Contents”:
TableDoc.Exports.mrHtmlExport.Properties["LayoutStyle"] = "Frame Table of Contents"

Figure 1-508
HTML export with frame table of contents layout
HTML Tables Export Properties

1482
Chapter 1
When you export tables to HTML, you can control a number of options using the export
properties. The following table lists the available export properties.
Property Name Description Type Default Value
ChartCategoryElements Set to “Per element” String: “Per variable”
to produce a chart for “No chart”, “Per
each category element. element”, “Per variable”,
Set to “Per variable” “Per table”.
to produce a chart for
each variable block of
category elements. Set
to “Per table” to produce
a single chart for all
category elements in the
table.
Note: When using
a custom pie
chart or template,
ChartCategoryElements
must be set to “Per
element”.
ChartCellItem Where there is more String: “ColPercent”
than one cell item on the “Count”
table, specifies the cell “ColPercent”
item to chart. The cell “RowPercent”
item must be included in “TotalPercent”
the table. If the specified “Mean”
cell item does not exist “Sum”
then Count will be used, “Minimum”
and if Count does not “Maximum”
exist, the first cell item “UnweightedCounts”
is used. “CumColPercent”
“CumRowPercent”
“Range”
“Mode”
“Median”
“Percentile”
“StdDev”
“StdErr”
“Variance”
ChartRowsAsSeries If true, table rows are Boolean True
used to form the chart
series. If false, table
columns are used.
1483
Base Professional

ChartSpecialElements Set to “Per element” String: “Per element”
to create a chart for “No chart”, “Per
any special statistical element”, “Per variable”,
elements (mean, “Per table”.
standard deviation,
etc) in the orientation
specified in the
ChartRowsAsSeries
property. Set to
“Per variable” to
produce a chart for
special elements. Set to
“Per table” to produce
special elements in the
table.
ChartType Indicates the type of String: “Clustered Column”
chart that is to be created. “Clustered Bar”
“Stacked Bar”
“3D Clustered Bar”
“3D Stacked Bar”
“Clustered Column”
“Stacked Column”
“3D Clustered Column”
“3D Stacked Column”
“3D Column”
“Line”
“Stacked Line”
“Line with Markers”
“100% Stacked Line
with Markers”
“Pie”
“3D Pie”
“Separated Pie”
“3D Separated Pie”
CssLocation The location of the String “” (An empty string.)
custom style sheet.
It is not necessary to
specify this property if
the custom style sheet
is located in the output
folder.
CustomCss The exported HTML String “” (An empty string.)
files use CustomCss as
the CSS filename. Note:
CustomCss must exist
in the target folder or
the folder specified in
CssLocation.
1484
Chapter 1

Destination Location and filename of String “” (An empty string.)
the exported HTML file. When the location is not
specified, the HTML
output will be created in
your default temporary
folder. If you do not
know where this is, you
can find out by opening
a command prompt and
typing cd %temp%. This
displays the location of
the temporary folder.
You can then browse to
this folder in Windows
Explorer to find the
HTML output.
DisplayAnnotations Determines whether Boolean True
annotations are included
in the export.
DisplayLastCategoryBase Determines whether Boolean False
to display the base for
the last data point in
the chart legend. This
option is applicable only
when charting special
elements. If the Count
cell item is present,
this is used. If not, the
Unweighted Count cell
item is used.
DisplayLogo Specifies whether a logo Boolean True
should be inserted in
the top left corner of the
HTML file. The IBM
Corp. logo is provided
for use as a default logo,
but this can easily be
replaced with any other
suitable logo.
DisplayOption Specifies whether the String: “Table and Chart”
export should create “Table Only”
tables only, charts only, “Table and Chart”
or both tables and charts “Chart and Table”
and whether the chart “Chart Only”
or the table should be
shown first.
DisplaySeriesBase Indicates that the base for Boolean False
each of the chart series
should be displayed in
the legend for the chart.
DisplayTitle Determines whether Boolean True
or not the project
description is displayed
as the title in the HTML
output.
1485
Base Professional

EmbedCss Determines whether Boolean True
the style sheet is to
be embedded within
the HTML file or in a
separate file. Embedding
the style sheet is useful
when you want to
distribute the HTML
output, for example, by
email.
FormatPercentageAxes Determines whether to Boolean False
chart percentages on
a scale of 0 to 100%.
If this option is false,
the scale is based on
the biggest value in the
chart.
HorizontalSideAxis This option enables Boolean True
you to choose whether
to display text on the
side axis horizontally or
vertically.
IncludeTOC This option enables Boolean True
you to choose whether
to display a table of
contents. This option
only has an effect when
used with the “Single
Document” layout style.
Note: If only one table
is exported, no table of
contents is displayed.
Interactive Interactive mode. For Boolean False
more information, see
the topic HTML Tables
Export - Interactive
Mode on p. 1488.
LaunchApplication Display the exported Boolean False
tables in the default Web
browser.
LayoutStyle Specifies the layout String: “Single Document”
style to be used. For “Single Document”
more information, see “Table of Contents”
the topic HTML Tables “Frame Table of
Export Layout Styles on Contents”
p. 1479.
OverwriteOutput Determines whether Boolean False
an existing HTML file
should be overwritten.
For more information,
see the topic HTML
Tables Export -
Interactive Mode on
p. 1488.
1486
Chapter 1

PresentationStyle Specifies the style sheet String: “Default”
(CSS file) to be used. For “Black and White”
more information, see “Default”
Export - Customizing the
Style Sheet on p. 1490.
PrintingPageBreak Adds a printing page Boolean True
break between tables
(not between table and
chart). This is relevant
only for the Single
Document layout style.
UseElementLabels Determines whether Boolean True
element names or the (Use labels)
more friendly element
labels are to be used
for the row and column
labels in the exported
tables.
UseFormattedLabels This option enables you Boolean False
to use HTML formatting
of variable and element
labels in a similar way to
using HTML formatting
in the annotations. Note
that using this option
may make the export run
a little more slowly. For
Export - Formatted
Labels on p. 1488.
UseStyles Exports styles associated Boolean True
with elements. In the
current version, this
enables you to export
images associated with
elements. For more
information, see the
topic Displaying Images
for Elements on p. 1405.
UseVariableLabels Determines whether Boolean True
variable names or the (Use labels)
more friendly labels are
to be used for variable
texts in the exported
tables.
Examples
1. Suppressing the Logo

1487
Base Professional
By default, the exports include the IBM Corp. logo. You can change the logo by simply replacing
the logo file in the output folder. Alternatively, you can suppress the inclusion of the logo by
setting the DisplayLogo export property to False:
TableDoc.Exports.mrHtmlExport.Properties["DisplayLogo"] = False
2. Showing Charts and Tables
By default, tables and charts are exported. However, you can choose to export charts only
or tables only. You do this by setting the DisplayOption export property. If you want to show
tables and charts, you can specify that the chart should be shown first by setting the property
to “Chart and Table”:
TableDoc.Exports.mrHtmlExport.Properties["DisplayOption"] = "Chart and Table"
For details of how data is displayed in charts, see Creating Charts.
If you want to export tables only, set the property to “Table only”:
TableDoc.Exports.mrHtmlExport.Properties["DisplayOption"] = "Table only"
3. Changing the Style Sheet
The HTML Export component comes with two built-in style sheets—Default, which has a
blue background, and Black and White, which, as its name suggests, has black text on a white
background. You select the Black and White style sheet by setting the PresentationStyle export
property to “Black and White”:
TableDoc.Exports.mrHtmlExport.Properties["PresentationStyle"] = "Black and White"
4. Using a Custom Style Sheet
You can create your own style sheet and use it to replace the built-in style sheet. To use a custom
style sheet, specify the file name in the CustomCss property. The custom style sheet must be
present in the output folder, or in the folder specified in the CssLocation property.
If the custom style sheet is in the output folder, you do not need to specify the location of the
style sheet. However, if you use this method, you cannot embed the custom style sheet. Set the
EmbedCss export property to False:
TableDoc.Exports.mrHtmlExport.Properties["EmbedCss"] = False
TableDoc.Exports.mrHtmlExport.Properties["CustomCss"] = "MyCustomStyleSheet.css"
If you specify the location in the CssLocation property, you can either embed the style sheet or
export it as a separate file:
TableDoc.Exports.mrHtmlExport.Properties["EmbedCss"] = True
TableDoc.Exports.mrHtmlExport.Properties["CssLocation"] = “C:\MyTemplates\”
TableDoc.Exports.mrHtmlExport.Properties["CustomCss"] = "MyCustomStyleSheet.css"
For details of how to create and customize a style sheet, see Customizing the Style Sheet.
1488
Chapter 1
HTML Tables Export - Interactive Mode
You use interactive mode when you want to get feedback during the export. For example,
when you use the interactive mode, you will see a message if the output file already exists. The
following table summarizes the main differences between exporting tables to HTML with and
without interactive mode enabled.
Situation Interactive Mode Enabled Interactive Mode Disabled
File of same name already exists. The user is presented with a If the OverwriteOutput export
Yes/No message box that requests property is set to True, the file is
permission to overwrite the file. overwritten, otherwise the export
fails.
Overwrite of output file fails. The user is alerted with an OK The export fails.
message box and then the export
fails.
One or more invalid export The user is alerted with an OK Invalid properties are ignored and
properties have been specified. message box containing a list of any valid properties are accepted.
the invalid properties. The valid
properties are accepted.
Style sheet already exists in The existing style sheet is used The existing style sheet is used
output location. instead of the built-in style sheet. instead of the built-in style sheet.
The logo file already exists in The existing logo is used instead The existing logo is used instead
output location. of the built-in logo. of the built-in logo.
Charts have been requested The user is alerted with an OK If the export includes tables, these
but the Microsoft Office Web box. If the export includes tables, will be exported. The charts will
components are not available. these will be exported. The charts not be exported.
will not be exported.
Example
You select interactive mode by setting the Interactive export property to True:
TableDoc.Exports.mrHtmlExport.Properties["Interactive"] = True
HTML Tables Export - Formatted Labels
Sample Script File: FormattedLabels.mrs
The UseFormattedLabels HTML Export Property enables you to use HTML formatting of variable
and element labels when exporting to HTML. This is similar to using HTML formatting of
annotations and the same set of HTML tags are supported and like in annotations, the HTML must
be well-formed. For more information, see the topic Valid Annotation HTML Tags on p. 1442.
1489
Base Professional
In IBM® SPSS® Data Collection Base Professional 2.3, formatted labels are supported in the
HTML export only. If you export to any of the other formats (or to HTML without using this
option), any HTML tags in the variable or element labels will appear as plain text. Note that using
this option may make the export run a little more slowly.
Using the formatted labels option enables you to use graphics in element labels. For example, you
can use this option and the <img> tag to display logos or pictures of products in addition to (or
instead of) the element texts. The following script provides an example of doing this in a table
of Interest by Gender. The <img> tag has been used in the element labels to insert references to
pictures that represent the various galleries.
"interest{Dinosaurs '<img src=""C:\Images\Dinosaur.gif"" alt=""Dinosaurs""/>'," + _
"Fish_and_reptiles '<img src=""C:\Images\Fish.gif"" alt=""Fish and reptiles""/>'," + _
"Fossils '<img src=""C:\Images\Fossil.gif"" alt=""Fossils""/>'," + _
"Birds '<img src=""C:\Images\Bird.gif"" alt=""Birds""/>'," + _
"Insects '<img src=""C:\Images\Insects.gif"" alt=""Insects""/>'," + _
"Whales '<img src=""C:\Images\Whales.gif"" alt=""Whales""/>'," + _
"Botany '<img src=""C:\Images\Botany.gif"" alt=""Botany""/>'} " + _
"* gender", "Favorite Gallery by Gender")
Notice that the alt attribute has been used to display the element text when someone points with
their mouse at the pictures in the HTML output. Here is the table displayed using Microsoft
clipart images:
Figure 1-509
HTML export with formatted labels
1490
Chapter 1
Although it is generally preferable to format the texts using the style sheet wherever possible,
you can use the <font> tag to define formatting of the variable and element labels. For example,
the following script uses the Wingdings 2 and Webdings fonts to display symbols and the color
attribute to change the color of the text:
.AddNew("Table1", "gender{base '<b>< font color=""#CE0000"">Base</font>' base(), " + _
"male '<font color=""#CE0000"">Male</font>', " + _
"female '<font color=""#CE0000"">Female</font>'} * before{" + _
"base '<b><font color=""#CE0000"">Base</font>' base(), " + _
"Yes '<b><font face=""Wingdings 2"" color=""#CE0000"" size=""3"">P</font></b>'," + _
"No '<b><font face=""Webdings"" color=""#CE0000"" size=""2"">r</font></b>'}", _
"Gender by Whether Visited Before")
.Table1.Side.Gender.Label = "<b><font color=""#CE0000"">Gender</font></b>"
.Table1.Top.Before.Label = "<b><font color=""#CE0000"">Visited Before</font></b>"
End With
Here is the table:

Figure 1-510
HTML export with labels formatted to change color and font
When you create a custom label for an element in the axis specification, you need to enclose the
label text in single quotation marks (‘<label text>’) or two double quotation marks (“”<label
text>””). If you use single quotation marks, you must escape any single or double quotation
marks included in the label with a second quotation mark of the same type. This indicates that
the quotation mark used in the label does not represent the end of the label. If you use two
double quotation marks, you need to escape any double quotation marks used in the label with
three double quotation marks.
HTML Tables Export - Customizing the Style Sheet
A cascading style sheet (CSS) file is used to control the formatting of the output of the HTML
export. You can edit style sheets using any standard text editor or HTML-authoring tool.
The HTML Export option has two built-in style sheets—Default, which has a blue background,
and Black and White, which, as its name suggests, has black text on a white background. HTML
Tables Export Properties provides an example of selecting the Black and White style sheet. By
default, the style sheet is embedded in the HTML output, but you can export the style sheet
separately. This creates the style sheet (called mrTables Default.css or mrTables Black and
White.css) in the output folder. You can then amend the style sheet as required.
1491
Base Professional
Alternatively, you can create your own style sheet, and use the CustomCss Export property to
specify the style sheet to use. You may find it easier to begin by copying the default style sheet.
Note that if you use a custom style sheet it must be present in the output directory. You cannot
embed a custom style sheet.
When you subsequently export to the same location, the style sheet is not overwritten unless you
set the OverwriteOutput export property to True. (By default this property is set to False.). This
means that you can make changes to the style sheet and your changes will be preserved the
next time you export to the same output folder.
Example
Suppose you want to amend the Black and White style sheet to show the Left Header annotation
in color, a larger size, and bold, and to format the cell contents that show the sum of a numeric
variable in the same color and italics. In addition, you want to highlight the horizontal side axis
text by changing the font color, and also the background color of the cell and the side indent
cell. You could do this as follows:
E If a style sheet called mrTables Black and White.css already exists in the output folder, rename it
or move it to another folder.
E Run the export using the Black and White style sheet and with the EmbedCss export property set
to FalseEmbed style sheet option deselected.
E Open the mrTables Black and White.css file in a text or HTML editor and make the amendments
highlighted below:
...
TD.CellItemCount,
TD.CellItemUnweightedCounts
{
}
TD.CellItemSum
{
FONT-STYLE: italic;
COLOR: #800080;
}
TD.CellItemMin,
...
{
}
...
TD.AxisLabelHorizontalSide
{
FONT-WEIGHT: bold;
FONT-SIZE: 11pt;
FONT-STYLE: normal;
FONT-FAMILY: Arial, sans-serif;
TEXT-ALIGN: left;
COLOR: white;
BACKGROUND: gray;
1492
Chapter 1
}
TD.AxisLabelIndentSide
{
BACKGROUND: gray;
}
...
TD.LeftHeader
{
WIDTH: 30%;
TEXT-ALIGN: left;
FONT-WEIGHT: bold;
FONT-SIZE: 10pt;
COLOR: #800080;
}
...
E Use the Refresh option in your browser to view the exported file with the updated style sheet.
Here is a table of Age by Gender showing the sum of the visits variable exported using the
amended style sheet:
Figure 1-511
HTML export using amended style sheet
HTML Tables Export - Working with the HTML Export Render Object
Sample Script File: ExportHtmlRender.mrs
1493
Base Professional
There may be times when you want to export your TOM document to HTML, with the output
including both tables and charts. The HTML Export Render component allows you to export your
tables and charts to HTML. Instead of using a properties XML file, you can now use the IRender
interface properties to customize your output. You can also use the IRender interface to export
tables into a HTML string; the HTML string can then be inserted into an existing HTML page.
The following sample script allows you to export Museum tables to HTML. You can modify
the MDD_FILE and XML_FILE values if you want to use the other MetaData and CaseData files.
EXPORT_FILE is location of the output file.
'Define constants for file locations used in the script

Const MDD_FILE = "C:\Program Files\SPSSInc\PASWDataCollection6.0\DDL\Data\Xml\Museum.mdd"
Const XML_FILE = "C:\Program Files\SPSSInc\PASWDataCollection6.0\DDL\Data\Xml\Museum.xml"
Const EXPORT_FILE = "C:\Program Files\SPSSInc\PASWDataCollection6.0\DDL\Output\Test.html"
The following script creates and populates the tables. After loading and populate the tables, you
can generate the tables XML string via the TOM Document method. For more information, see
the topic Table Object Model Reference on p. 1556.
Dim TableDoc, TableXML

'— - Create the tables —
-
.AddNew("Table1", "age * gender", "Age by Gender")
.AddNew("Table2", "Distance", "Distance from home to museum")
.AddNew("Table3", "before * distance", "Before by Distance")
End With
'— - Populate the tables —
-
TableDoc.Populate()
TableXML = TableDoc.GetTablesXml("Table1, Table2, Table3", 1)
The following script allows you to create an ExportHtml.Renderer object and export the tables.
'—- Load Export Component —-

Dim HtmlRender, HtmlOut
Set HtmlRender = CreateObject("ExportHtml.Renderer")
HtmlRender.DisplayAnnotations = False
HtmlRender.DisplayOption = 0
HtmlRender.EmbedCss = False
HtmlRender.UseFormattedLabels = True
HtmlRender.IncludeTitleBlock = False
HtmlRender.IncludeTOC = False
HtmlRender.OutputBodyOnly = True
HtmlOut = HtmlRender.Render(TableXML)
1494
Chapter 1
In the above example, HtmlOut renders the export tables as an HTML string. You can retrieve the
HTML string via Debug.log(HtmlOut), and then insert the exported results into an existing HTML
page. If you want export the tables directly to an HTML file, you can define the save location
via the HtmlRender.Destination property value. For example:
HtmlRender.Destination = EXPORT_FILE
HtmlRender.Render(TableXML, EXPORT_FILE)
Style Sheet Settings
The style sheet contains a number of styles that define the format of the different items in the
tables, annotations, and table of contents. You can change the appearance of the various items
by changing the styles. The styles fall into a number of groups according to the items whose
formatting they control. The following diagram shows the main style groups and indicates which
area of the table they format.
Figure 1-512
HTML export styles
Data Cell Items
These styles control the formatting of the table cells that contain figures (cell contents).
Type Style Description
Cell TD.Cell The default style for the table
cells that contain figures (cell
contents).
1495
Base Professional

Cell position TD.CellTop These styles enable multiple cell
TD.CellBottom items to be enclosed within a
TD.CellMiddle single border.
TD.CellTopBottom
Cell element type TD.CellElementCategory These styles apply individual
TD.CellElementMean formatting to the cells that relate
TD.CellElementStdDev to particular types of category and
TD.CellElementStdErr other items appearing in rows or
TD.CellElementSampleVar columns, for example, to show
TD.CellElementTotal the cells formed from the base
TD.CellElementSubTotal rows and columns in bold.
TD.CellElementText
TD.CellElementNetDiffs
TD.CellElementPairedPrefs
TD.CellElementOtherDerived
TD.CellElementMinimum
TD.CellElementMaximum
TD.CellElementNet
TD.CellElementCombine
TD.CellElementExpression
TD.CellElementTableStatistic
TD.CellElementNumeric
TD.CellElementDerived
TD.CellElementSum
TD.CellElementMedian
TD.CellElementPercentile
TD.CellElementMode
TD.CellElementBase
TD.CellElementUnweightedBase
Cell items TD.CellItemCount These styles specify formatting
TD.CellItemUnweightedCounts for different types of cell contents,
TD.CellItemSum for example, to format column
TD.CellItemMinimum percentages differently from
TD.CellItemMaximum counts.
TD.CellItemMean
TD.CellItemRange
TD.CellItemMode
TD.CellItemMedian
TD.CellItemPercentile
TD.CellItemStdDev
TD.CellItemStdErr
TD.CellItemVariance
TD.CellItemResiduals
TD.CellItemAdjustedResiduals
TD.CellItemExpectedValues
TD.CellItemValidN
TD.CellItemIndices
TD.CellItemColPropResults
TD.CellItemColBase
TD.CellItemRowBase
TD.CellItemColPercent
TD.CellItemRowPercent
TD.CellItemTotalPercent
TD.CellItemCumColPercent
TD.CellItemCumRowPercent
TD.CellItemProfileResult
1496
Chapter 1
Table Axis Cell Items
These styles control the formatting of the cells that form the row and column headings.
Axis TD.Axis The default style for the table cells
that contain the row and column
headings.
Cell type TD.AxisLabelTop These styles apply formatting to
TD.AxisLabelSide the various items that make up the
TD.AxisLabelHorizontalSide column and row headings.
TD.AxisLabelIndentSide
TD.AxisElementTop
TD.AxisElementSide
TD.AxisSubElementLevelnTop
TD.AxisSubElementLevelnSide
TD.AxisColumnHeading
TD.AxisElementSortedOn
Element type TD.AxisElementCategory These styles apply individual
TD.AxisElementMean formatting to the row and column
TD.AxisElementStdDev headings that relate to particular
TD.AxisElementStdErr types of category or other items
TD.AxisElementSampleVar appearing in rows or columns, for
TD.AxisElementTotal example, to show the headers that
TD.AxisElementSubTotal relate to base rows and columns
TD.AxisElementText in bold.
TD.AxisElementNetDiffs
TD.AxisElementPairedPrefs
TD.AxisElementOtherDerived
TD.AxisElementMinimum
TD.AxisElementMaximum
TD.AxisElementNet
TD.AxisElementCombine
TD.AxisElementExpression
TD.AxisElementTableStatistic
TD.AxisElementNumeric
TD.AxisElementDerived
TD.AxisElementSum
TD.AxisElementMedian
TD.AxisElementPercentile
TD.AxisElementMode
TD.AxisElementBase
TD.AxisElementUnweightedBase
Table of Contents
These styles control the formatting of the table of contents.

Table of contents cell TD.TableOfContents Controls the formatting of the
table of contents cells.
Table of contents title cells TD.TableOfContentsTitle Controls the formatting of the
table of contents column headers.
1497
Base Professional
Annotations
These styles control the formatting of the annotations (headers and footers).
Annotation TD.Annotation The default style for the table
annotations.
Annotation type TD.TitleHeader These styles define individual
TD.LeftHeader formatting for the annotations in
TD.CenterHeader each annotation position.
TD.RightHeader
TD.TitleFooter
TD.LeftFooter
TD.CenterFooter
TD.RightFooter
Tip: The default annotation styles define the percentage of the total width that is to be used for the
left, center, and right header and left, center, and right footer annotations. If you do not use one or
two of the header or footer annotation positions, you may want to increase the percentage allocated
to the positions you do use and reduce the percentage allocated to the position or positions you
don’t use. This means that more text will be displayed on each line and reduce the line wrapping.
For example, if you never use center headers, you could reduce the width allocated to the
TD.CenterHeader style to 0% and increase the percentage width allocation in the TD.LeftHeader
and TD.LeftHeader styles.
General
These styles control the formatting of other items.

Top link A.TopLink Controls the formatting of the link
that returns the user to the top of
the HTML document. Used in
the Single Document layout style
only.
Survey Name and Description H1.SurveyName Controls the formatting of the
H1.SurveyDescription survey title and description.
Picture / Chart IMG.TableImage Enables images to have a specified
IMG.TableLogo background color.
Vertical Spacer .VerticalSpacer Controls the vertical gap between
the row headers and the cells that
form the body of the table.
Horizontal Spacer .HorizontalSpacer Controls the horizontal gap
between the column headers and
the cells that form the body of the
table.
For detailed information on working with styles, refer to standard CSS documentation. At the time
of writing, information about CSS technology is available at MSDN: Cascading Style Sheets (CSS)
(http://msdn.microsoft.com/library/default.asp?url=/workshop/author/css/css_node_entry.asp) (
http://msdn.microsoft.com/library/default.asp?url=/workshop/author/css/css_node_entry.asp ).
1498
Chapter 1
For a list of colors, see HTML Color Names

(http://www.w3schools.com/html/html_colornames.asp) at
http://www.w3schools.com/html/html_colornames.asp.
HTML Export Render Object Model Reference
This section provides information on the HTML Export Render component. The component
allows you to export your tables and charts to HTML.
Microsoft Excel Tables Export
IBM SPSS Data Collection Survey Reporter Professional 2.1 and later comes with an Excel Export
component, which enables you to export tables and charts to Microsoft Excel. The component has
been designed to create output in Excel that is suitable for printing and easy to manipulate. To use
the Excel Export component, you need to have Microsoft Office 2007 or later installed.
By default, each table is exported as a single table to a separate Excel worksheet. However,
you can optionally choose to export each type of cell contents to a separate table on the same
worksheet. You select this option by setting the SplitCells export property to True. This option is
useful when you want to perform calculations on the output or create your own charts in Excel.
You can optionally choose to export charts. The export creates the charts on a separate worksheet
immediately following the worksheet that contains the related table. For details of how data is
displayed in charts, see Creating Charts. You select the option to create charts by setting the
DisplayCharts export property to True.
The worksheets are named T1, T2, T3, etc. This is designed to reduce the length of the worksheet
names, in order to maximize the number of worksheet tabs that can be visible at once. The
worksheets that contain charts are called T1_Ch, T2_Ch, T3_Ch, etc. where T1, T2, and T3 are the
names of the worksheets containing the tables to which they relate.
installation CD.
Requirements
IBM SPSS Data Collection Survey Reporter Professional
Office 2007 or above. Unlike the PowerPoint Export component, which use automation in a
VBScript, the Excel Export component uses a Visual Basic for Applications (VBA) macro for
the export, because it provides superior performance when exporting to Excel. The macro is
temporarily inserted into Excel and removed at the end of the export process.
1499
Base Professional
This requires a security setting to be set. If you need to set this on your machine, a message will
inform you of this. For further details on how to set the security setting, see Enabling security
access for Microsoft Excel, Word, and PowerPoint exports.
Microsoft Excel Tables Export Formatting
Sample Script File: ExcelExport.mrs
When you export tables to Microsoft Excel, you can choose whether to use styles to control the
formatting. By default, the exported tables will look the same whether you use styles or not.
However, styles make it easy to alter the look of your tables and apply standard formatting to
multiple tables. If you want to use Excel to manipulate the data in the tables rather than printing
them, you may prefer to export without using styles.
To use styles, choose the Use Excel styles option in the .
To use styles, choose the Use Excel styles option in the .
In Excel, each style has a name and defines a combination of formatting characteristics, such as
font, font size, color, and emphasis, and indentation. When you apply a specified style to an item,
all of the formatting that is stored in that style is automatically applied to the item. By changing
the formatting defined for a style, you can quickly change the formatting of all of the items to
which the style has been applied.
The following table lists the styles that are used by the Excel export.
Style Type Style Name Description
Annotations Footer Used to format header and footer
Header annotations.
Variabletext VariableTextTop Used to format variable names or
VariableTextSide descriptions in the table column
headers.
Elementtext ElementTextTop Used to format category names
ElementTextSide or descriptions in the table row
headers.
Cell values Values Used to format cell contents.
The following diagram shows the styles used to format the various texts in a table.
1500
Chapter 1
Figure 1-513
Styles applied to texts in a table
Note that the export does not apply borders to the exported tables using styles. However, you
can switch borders on and off using the DisplayBorders export propertyDisplay borders option
in the Exports dialog box.
To select the styles option, set the UseExcelStyles export property to True:
TableDoc.Exports.mrExcelExport.Properties["UseExcelStyles"] = True
Sometimes you may want to apply a standard formatting to your exported tables—for example,
because you have a house style. You can do this in two steps:
E Export your tables using the UseExcelStyles export propertyUse Excel styles option.
E In Excel, adjust the formatting of the Excel Export styles shown in the table above to suit your
requirements.
E Save the Excel file.
E Export your tables using the UseExcelStyles export propertyUse Excel styles option.
E Open the master document you set up in step 1.
E Open the newly exported Excel workbook if not already open, and then choose Style on the
Format menu.
E Click Merge.
E In the Merge styles dialog box, double-click the master document that contains the formatting
you want to copy.
E Choose Yes when you are prompted whether you want to merge the styles with the same names.
1501
Base Professional
Annotations
All of the annotations are displayed left aligned, regardless of the annotation positions selected.
This has the advantage that in a wide table the annotations are easily visible. The following table
shows the order in which the annotations are presented.
Headers Footers
TitleHeader TitleFooter
LeftHeader LeftFooter
CenterHeader CenterFooter
RightHeader RightFooter
You can suppress the annotations from the export by setting the DisplayAnnotations export
property to False. For more information, see the topic Microsoft Excel Tables Export Properties
on p. 1501.
Requirements
Microsoft Excel Tables Export Properties
When you export tables to Microsoft Excel, you can control a number of options using the export
AutoFitColumnWidths If true, automatically Boolean False
change the width of
the table columns to
accommodate the width
of the text.
1502
Chapter 1

table.
Note: When using
a custom pie
chart or template,
element”.
the table. The cell item “Mean”
must be included in the “Sum”
table. If the specified “Minimum”
cell item does not exist “Maximum”
then Count will be used, “UnweightedCounts”
and if Count does not “CumColPercent”
exist, the first cell item “CumRowPercent”
is used. “Range”
“Mode”
“Median”
“Percentile”
“StdDev”
“StdErr”
“Variance”
ChartColPropResults If true, displays the Boolean False
column IDs beside the
category labels, and adds
the column proportions
test results to the chart
above the relevant
columns.
columns are used.
1503
Base Professional

standard deviation,
specified in the
ChartRowsAsSeries
property. Set to
produce a chart for
table.
ChartTemplate Indicates the chart String “” (Empty string)
template that is to be
used. If you want to use
a custom chart template
that you have created in
Excel, specify the name
of the chart template.
ChartTemplateLocation The location of the String “” (Empty string)
chart template. It is
not necessary to specify
this property because
its value is set when the
user specifies the chart
template file.
chart that is to be “Clustered Bar”
created. If you want “Stacked Bar”
to use a custom chart “3D Clustered Bar”
that you have created in “3D Stacked Bar”
Excel, specify the name “Clustered Column”
of the custom chart. “Stacked Column”
“3D Column”
“Line”
“Stacked Line”
with Markers”
“Pie”
“3D Pie”
“Separated Pie”
”Custom chart name”
Destination Location and filename of String “” (Empty string)
the exported Excel file.
in the export.
1504
Chapter 1

DisplayBorders Indicates whether tables Boolean True
are to be displayed with
borders.
DisplayCharts Indicates whether charts Boolean True
are to be created.
item is used.
chart.
HideApplication Indicates that Excel is Boolean False
to be hidden during the
export. This makes the
export faster.
HideBaseElements If true, suppresses Boolean False
all rows or columns
containing base elements
in all tables, so that they
are not displayed in the
output file. If false, base
elements are displayed
or hidden according to
the settings in the axis
expressions for each
table.
the topic Microsoft
Excel Tables Export -
Interactive Mode on p.
1507.
LaunchApplication Launch Excel after the Boolean False
export has completed.
1505
Base Professional

MergeColPropResults Combines the column Boolean False
proportion result with the
first cell item. (Note that
charts are not produced
for tables with merged
column proportion
results.)
OverwriteOutput When not using the Boolean False
interactive mode, this
property determines
whether an existing
output file should be
overwritten rather than
causing the export to fail.
see the topic Microsoft
Excel Tables Export -
1507.
PrintingOption Determines the printing String “Repeat axes”
option to be used for the “None”
exported tables. (Note “Fit to page”
this does not affect how “Repeat axes”
the tables appear in
Excel. It affects how the
tables appear when they
are printed only.)
SplitCells Indicates that each type Boolean False
of cell contents is to
appear in a separate
table. This is useful if
you want to perform
calculations on the
output or set up your
own charts in Excel.
tables.
UseExcelStyles Indicates that formatting Boolean False
is to be controlled
by styles. For more
information, see
the topic Microsoft
Excel Tables Export
Formatting on p. 1499.
1506
Chapter 1

UseFormattedAnnotations Enables you to use Boolean True
HTML formatting
of annotations when
exporting to Excel.
When the value of this
property is True, the
annotation is copied as
formatted HTML, using
the clipboard. When
the value is False, the
annotation is copied as
plain text, so that all tags
(except <br/>) appear in
the Excel output.
Note: Set this option
to False in a server
environment.
more friendly labels
(descriptions) are to be
used for variable texts in
the exported tables.
WrapLabelText Determines whether Boolean True
to wrap long labels
(descriptions) to the next
line.
Examples
1. Using Excel styles
You indicate that you want the formatting to be controlled by styles by setting the UseExcelStyles
export property to True:
TableDoc.Exports.mrExcelExport.Properties["UseExcelStyles"] = True
For more information, see the topic Microsoft Excel Tables Export Formatting on p. 1499.
2. Creating a separate table for each type of cell contents
By default, each table in your script is exported as a single table to a separate Excel worksheet.
However, you can optionally choose to export each type of cell contents to a separate table. All
of the tables are placed on the same worksheet. This option is useful if you want to perform
calculations on the output or set up your own charts in Excel. You select this option by setting the
SplitCells export property to True:
TableDoc.Exports.mrExcelExport.Properties["SplitCells"] = True
3. Exporting charts
You select the option to export charts by setting the DisplayCharts export property to True:
TableDoc.Exports.mrExcelExport.Properties["DisplayCharts"] = True
1507
Base Professional
For details of how data is displayed in charts, see Creating Charts.
Requirements
Microsoft Excel Tables Export - Interactive Mode
following table summarizes the main differences between exporting tables to Excel with and
without interactive mode enabled.
Yes/No message box that requests property is set to True, the output
permission to overwrite the file. file is overwritten, otherwise the
export fails.
Overwrite of output file fails. The user is presented with an OK The export fails.
box that explains that the output
file cannot be overwritten and
then the export fails.
Microsoft Office is not available The user is presented with an OK The export fails.
box and the export fails.
Example
TableDoc.Exports.mrExcelExport.Properties["Interactive"] = True
Requirements
1508
Chapter 1
Exporting Charts Using Microsoft Excel Custom Chart Types
When you export charts to Microsoft Excel, PowerPoint, or Word, you can optionally export the
charts to a user-defined custom chart type you have set up using Excel. This means you can set
up a chart in Excel and configure the type of chart, the placement of the chart legend, the colors
used, and so on, to any format available in Excel, and then enter the name of this chart type in
the Export dialog box when you export from .
Note: This documentation provides information on making Excel custom chart types available for
use with . It does not explain how to create charts in Excel. For details, see your Microsoft Excel
user documentation. These steps may vary depending on the version of Excel you are using.
To create a custom chart type in Excel
Note: When using a custom pie chart or template, ChartCategoryElements must be set to “Per
element”. Refer to the topic “Microsoft Excel Tables Export Properties” in the IBM® SPSS®
Data Collection Developer Library for more information.
E If you want to base the style of your custom chart type on a chart available in , export a sample
table from to Excel, checking the Display charts check box and selecting the appropriate chart type.
Alternatively, you may prefer to begin by creating a new chart in Microsoft Excel. Note that some
chart types require the data to be organized in a particular format. For details about creating
charts in Excel and the ways in which different chart types display data, see your Microsoft
Excel user documentation.
E In Excel, double-click an area of the chart to display the formatting dialog box for that area, and
adjust the settings to your requirements. For example, if you double-click a chart legend, the
Format Legend dialog box appears and enables you to change the patterns, font, and placement of
the legend.
E When you finish formatting the chart, select the whole chart area (selection handles appear around
the edges of the area) and choose
Chart > Chart Type
from the Excel menu.
E In the Chart Type dialog box, select the Custom Types tab.
E Click the User-defined option button, then click Add to display the Add Custom Chart Type
dialog box.
E Enter a name and description for the chart type and click OK.
This creates the new custom chart type. You can now use this chart type when exporting from to
Excel, PowerPoint, or Word.
1509
Base Professional
To share custom chart types
All user-defined custom chart types you create in Excel are stored in a file named xlusrgal.xls
in the following location:
C:\Documents and Settings\username\Application Data\Microsoft\Excel\Xlusrgal.xls
Note: If you are using Excel 2007, the file is saved as a .crtx file in the following location:
C:\Documents and Settings\username\Application Data\Microsoft\Templates\Charts
If you want to share chart types you have created, you can send other users this file, together with
a note of the exact name of the custom chart(s). To use the custom charts, they can either:
Place the file in their own user folder, replacing any existing file of the same name. This is the
easiest method if they have not created or do not wish to keep their own custom charts.
Open the file in Excel. Each custom chart type is displayed in a separate worksheet. They
can then select each chart in turn and save it as a user-defined custom chart type as described
above. This method is useful for anyone who has already created their own custom charts and
does not wish to lose them.
Microsoft PowerPoint Tables Export
IBM® SPSS® Data Collection Base Professional comes with a PowerPoint Export component,
which enables you to export results to Microsoft PowerPoint. Note that to use the PowerPoint
Export component, you need to have Microsoft Office 2007 or later installed. Considering that
PowerPoint Export relies on the Microsoft Excel component, you should close all Excel files (to
avoid an invalid export result) prior to starting the export.
You can export results as tables or charts, and each table or chart is created on a separate
PowerPoint slide. By default, only charts are exported. For details of how data is displayed in
charts, see Creating Charts.
installation CD.
Requirements
Microsoft PowerPoint Export Formatting
Sample Script File: PowerPointExport.mrs
1510
Chapter 1
The Microsoft PowerPoint export always creates a title slide consisting of a title page frame
that displays the text stored in the Document.DataSet.Description and Document.Description
properties. If these properties are empty, the title slide will be blank. If necessary, you can set
these properties in your script. For example:
' Set up the text in the properties that will be displayed on the
' title slide.
TableDoc.DataSet.Description = "Museum of the Living World"
TableDoc.Description = "Visitor Survey"
You can export annotations using the DisplayHeaders and DisplayFooters properties:
.Properties["DisplayHeaders"] = True
.Properties["DisplayFooters"] = True
You can display the series bases in the chart legend using the DisplaySeriesBases and
DisplaySeriesBase property:
.Properties["DisplaySeriesBase"] = True
The slides are formatted using the default PowerPoint template. You can attach a different
template to the slides using the TemplateFileName property to specify the template file name and
path. By default, PowerPoint templates are stored in subfolders under the folder C:\Program
Files\Microsoft Office\Templates\, and have the file extension .pot:
.Properties["TemplateFileName"] = "C:\Program Files\Microsoft Office\Templates\Presentation Designs\Glass Layers.pot"
You can also apply an alternative template after the export is complete.
To apply a different template:
E If necessary, open the slides in PowerPoint.
E From the PowerPoint Format menu, choose Apply Design Template (or Slide Design in PowerPoint
2003).
E In the Apply a Design Template dialog box, select the template you want to use.
E Click Apply.
For example, here are two of the slides created using the PowerPointExport.mrs sample
PowerPoint export and applying the Fireworks template that comes with PowerPoint.
1511
Base Professional
Figure 1-514
PowerPoint slides with template applied
Requirements
Microsoft PowerPoint Export Properties
1512
Chapter 1
When you export tables to Microsoft PowerPoint, you can control a number of options using the
export properties. The following table lists the available export properties.
AutoFitColumnWidths If true, automatically Boolean False
change the width of
the table columns to
accommodate the width
of the text.
table.
Note: When using
a custom pie
chart or template,
element”.
“Mode”
“Median”
“Percentile”
“StdDev”
“StdErr”
“Variance”
above the relevant
columns.
columns are used.
1513
Base Professional

standard deviation,
specified in the
ChartRowsAsSeries
property. Set to
produce a chart for
table.
template file.
“3D Column”
“Line”
“Stacked Line”
with Markers”
“Pie”
“3D Pie”
“Separated Pie”
Destination Location and filename of String “” (empty string)
the exported PowerPoint
file.
borders.
1514
Chapter 1

DisplayFooters Indicates that the Boolean False
table footers should
be displayed in the
PowerPoint slides.
DisplayHeaders Indicates that the Boolean False
table headers should
be displayed in the
PowerPoint slides.
item is used.
DisplayOption Specifies whether the String: “Table Only” “Chart Only”
export should create “Table and Chart” “Chart
charts only, tables only, and Table” “Chart Only”
or both charts and tables,
and whether the chart
shown first.
DisplayTitleSlide Determines whether to Boolean True
include a title slide in the
PowerPoint file.
chart.
HideApplication Indicates that Boolean False
PowerPoint is to be
hidden during the export.
This makes the export
faster.
the topic Microsoft
PowerPoint Export -
1515.
LaunchApplication Launch PowerPoint Boolean False
after the export has
completed.
1515
Base Professional

property determines
whether an existing
PowerPoint Export -
1515.
TemplateFileName Location and filename of String “” (empty string)
the PowerPoint template
to format the slides.
tables.
tables.
WrapLabelText Determines whether Boolean True
to wrap long labels
(descriptions) to the next
line.
Example
The following example sets the Destination, LaunchApplication, and Interactive export properties.
With TableDoc.Exports.mrPowerpointExport
.Properties["Destination"] = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\PowerPointExport.ppt"
.Export()
End With
Requirements
Microsoft PowerPoint Export - Interactive Mode

1516
Chapter 1
when you use the interactive mode, you will see a message if the output file already exists.
The following table summarizes the main differences between exporting tables to Microsoft
PowerPoint with and without interactive mode enabled.
export fails.
Example
TableDoc.Exports.mrPowerpointExport.Properties["Interactive"] = True
Requirements
Microsoft Word Tables Export
IBM SPSS Data Collection Survey Reporter Professional 2.1 and later comes with a Word Export
component, which enables you to export tables and charts to Microsoft Word. The component
has been designed to create output in Word that looks good, is suitable for printing, and easy to
customize. To use the Word Export component, you need to have Microsoft Office 2007 or
later installed.
You can optionally export charts as well as or instead of tables. The charts are created using
Excel, which means that you need to have both Word and Excel installed to be able to use this
option. If you export both charts and tables, the charts are placed before or after the table to which
they relate, depending on the display option chosen. For details of how data is displayed in
charts, see Creating Charts.
1517
Base Professional
installation CD.
Word 2007 and above. Unlike the PowerPoint Export component, which use automation in a
VBScript, the Word Export component uses a Visual Basic for Applications (VBA) macro for
the export, because it provides superior performance when exporting to Word (up to 20 times
faster than VBScript automation). The macro is temporarily inserted into the Word template and
removed at the end of the export process. The macro takes as input the tables XML (which defines
the tables to be exported) and the properties XML (which defines the custom properties), and a
reference to the ActiveX control. The macro then generates the Word document using the Word
object model (and the Excel object model for display options including charts). The macro uses
the Windows clipboard to copy and paste the annotations, in order to retain any HTML formatting.
The copy operation is implemented using a method in the Active X control, and this means a
reference to the control is passed into the macro.
This requires a security setting to be set. If you need to set this on your machine, a message will
inform you of this. For further details on how to set the security setting, see Enabling security
access for Microsoft Excel, Word, and PowerPoint exports.
For more information, see Microsoft: Knowledge Base Article - 282830

(http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/Q282/8/30.ASP
(
http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/Q282/8/30.ASP
).
“Chart Error” text in the Word document instead of charts. The Word Export uses Excel to create the
charts, so you must have Excel 2007 or later installed on your desktop machine in order to be able
to export charts to Word. If you get this error text for all charts, the first thing to do is to check
that you have Excel installed. If it is installed, check that it has been installed with the option to
embed Excel charts enabled. If this option is not enabled, it would explain the error. You can
tell whether this option is enabled as follows:
1. Start a new document in Word.
2. From the Insert menu, choose Object.
3. From the list of object types, select Microsoft Excel Chart.
4. Click OK.
If this fails, it generally means that the option is not enabled and you will need to install the option
before you can export charts to Word. If this succeeds, it means that the chart error is caused by
some other problem and may be related to a specific table.
Requirements
1518
Chapter 1
Microsoft Word Tables Export Properties
Sample Script File: WordExport.mrs
When you export tables to Microsoft Word, you can control a number of options using the export
table.
Note: When using
a custom pie
chart or template,
element”.
“Mode”
“Median”
“Percentile”
“StdDev”
“StdErr”
“Variance”
above the relevant
columns.
1519
Base Professional

columns are used.
standard deviation,
specified in the
ChartRowsAsSeries
property. Set to
produce a chart for
table.
template file.
“3D Column”
“Line”
“Stacked Line”
with Markers”
“Pie”
“3D Pie”
“Separated Pie”
1520
Chapter 1

CreateTableOfContents Determines whether Boolean True
a table of contents is
included in the Word
document. The table
of contents is generated
from text formatted
using any style based
on the Heading styles
in Word. In the default
template, the Annotation
LeftHeader style is based
on Word’s Heading 1
style, so all text that
is formatted in this
style is included in
the table of contents.
This works best when
you display the table
description (and nothing
else) in the left header
annotation position. For
the topic Changing the
Headers and Footers
Used in the Table of
Contents on p. 1525.
Destination Location and filename of String “” (Empty string)
the exported Word file.
in the export. Note that
annotations are never
exported when you use
the Chart Only option.
borders.
DisplayOption Specifies whether the String: “Table Only”
export should create “Table Only”
tables only, charts only, “Table and Chart”
or both tables and charts, “Chart and Table”
and whether the chart “Chart Only”
shown first.
item is used.
1521
Base Professional

chart.
HideApplication Indicates that Word is Boolean False
to be hidden during the
export. This makes the
export faster. However,
this option is not
recommended if you
are using Word 2000,
because it can lead to the
export failing.
the topic Microsoft
Word Tables Export -
1522.
LaunchApplication Launch Word after the Boolean False
export.
property determines
whether an existing
Word Tables Export -
1522.
PrintingPageBreak Inserts a page break Boolean True
between the tables.
RepeatTopAxis Determines whether the Boolean True
table column headings
should be repeated on
each page when a table
contains more rows than
can fit on a single page.
TemplateFileName The name of the Word String “” (Empty string)
template (.dot) file to use An empty string
to format the output. indicates that the default
template should be used.
1522
Chapter 1

tables.
UseStyles Exports styles associated Boolean True
with elements. In the
current version, this
enables you to export
images associated with
elements. For more
information, see the
topic Displaying Images
for Elements on p. 1405.
tables.
Example
This example sets five of the export properties and exports two specified tables to a file called
MyTables.doc.
With TableDoc.Exports.mrWordExport
.Properties["PrintingPageBreak"] = False
.Properties["TemplateFileName"] = "C:\Documents and Settings\afisher\Application Data\Microsoft\Templates\StandardTables.dot"
.Export("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\MyTables.doc", "Table1, Table2" )
End With
Requirements
Microsoft Word Tables Export - Interactive Mode
Sample Script File: WordExport.mrs
1523
Base Professional
following table summarizes the main differences between exporting tables to Microsoft Word
with and without interactive mode enabled.
export fails.
Example
TableDoc.Exports.mrWordExport.Properties["Interactive"] = True
Requirements
Formatting the Output in Microsoft Word
When you export your tables to Microsoft Word, the tables are placed one after the other in a
single Word document. The exported tables are inserted into Word tables using the “Automatically
resize to fit contents” option. This means that the Word export is not suitable for extremely
wide tables that cannot be displayed properly in the available page width. (Note that you can
use a custom template to set the page orientation to landscape.) Long tables do not pose the
same problem, because they can be split across multiple pages when necessary. You can select
the Repeat Heading Rows option in the select the Repeat Heading Rows option in the set the
RepeatTopAxis property if you want the table column headings to be repeated on each page when
this happens. Similarly, the Display Borders optionset the DisplayBorders property enables you to
specify whether or not the tables should have borders.
Formatting of the text is controlled using Word templates and styles. For further information, see:
Working with Microsoft Word Templates
Working with Microsoft Word Styles
1524
Chapter 1
Requirements
IBM® SPSS® Data Collection Base Professional Tables Option 2.1 or later
Working with Microsoft Word Templates
All Microsoft Word documents are based on templates. Templates apply to an entire document
and determine its basic structure, including the default page size and orientation, margins, styles,
and page headers and footers (not to be confused with table headers and footers). Templates can
also include logos and standard text that are to be included in the document before or after the
tables, etc. Templates help you standardize designs and can save you time, because they enable
you to create a formatting scheme and apply it to multiple exports.
There are two basic types of templates in Word—global templates and document templates.
Global templates are available to all documents, whereas a document template contains settings
that are available only to documents that are based on, or attached to, it. uses a document template
to format the exported tables.
When you export your tables, the Word document is formatted using a built-in template called
WordTemplate.dot, unless you specify a different template. The first time you run an export to a
new location using the built-in template, the export saves the default WordTemplate.dot template
in the output folder. If you do not specify a destination folder and you are using the built-in
template, the template is written to the default Word templates folder, if not already present
there. When you subsequently export to the same location, the template is not overwritten. This
means that you can make changes to the template and your changes will be preserved the next
time you export to the same location.
Alternatively, you can save your template in another location, such as the main Office templates
folder, and explicitly select the template when you run an export. Typically you would first run
an export using the built-in template to get a copy of the default WordTemplate.dot template and
then use this as a starting point for creating your own templates.
You can subsequently change the template that is attached to a document by using the
Templates and Add-Ins option on the Word Tools menu. When you attach a template, select
Automatically update document styles in the Word Templates and Add-Ins dialog box. This updates
all of the styles in the document with the styles in the template. Note that changing the template in
this way does not change the position of the various items or the page layout of the document (for
example, the margin settings and the page headers and footers are not changed).
The default template contains the following:

Bookmarks. These define the position of the tables, survey name and description, and table of
contents. For example, you can specify that the table of contents is to appear after the tables
by positioning the bookmarks appropriately.
Styles. Each part of the table is mapped to its own style in Word. You can change the
appearance of the various parts of the table by changing the styles. For a complete list of the
default styles, see The Default Microsoft Word Export Styles. The default styles have been
designed to enable you to easily customize the formatting of the elements that are found in
most common tables. If you find the default styles do not provide the level of control you
1525
Base Professional
need, you can define new styles. Provided the new style names follow the Word Export’s style
naming rules, the new styles will be used next time you run the export using the new or
amended template. This section provides information on how to do this.
Annotations Table headers and footers are positioned around the tables to which they relate (not
in Word page headers and footers) and are not exported when you select the option to export
charts only.
Changing the Microsoft Word Export Orientation to Landscape
The default Microsoft Word export template uses Portrait orientation. You can change this to
Landscape in an individual Word document, or you can create your own custom template by
editing the default template.
To create a custom Word template with Landscape orientation:
E Export an example table to Word, specifying an output file name and folder in the Export File
Name field in the ., specifying an output file name and folder in the Export File Name field in the .
E When the export is complete you will see in the output folder, in addition to the exported Word
document, a template file called WordTemplate.dot.
E Open Word, then open WordTemplate.dot (do not open the .dot file by double-clicking on it as
this would create a new document).
E From the File menu in Word, choose Page Setup, then select Landscape in the Orientation section
of the Page Setup dialog and click OK.
E You may also want to make other changes to the template, for example to resize or reposition the
logo.
E Save and close WordTemplate.dot. You can save this template in any folder (if you export to a
folder and finds an existing WordTemplate.dot in the folder, it does not overwrite it, so your
changes are not lost) but you may want to save it to the folder where all your other Word templates
are stored, and give it a new name. If you rename the template and/or save it to a folder other than
the output folder, you must explicitly select the template when you run the export.
E Using IBM® SPSS® Data Collection Base Professional, run the export again, using the
TemplateFileName property of the Export object to specify the path and filename of the amended
Word template.selecting the amended Word template in the Apply Word Template field of the
Export dialog box.
Changing the Headers and Footers Used in the Table of Contents
When you export a table from to a Microsoft Word document, each part of the table is mapped to
its own style in Word. A list of the styles is available in The Default Microsoft Word Export Styles.
The table of contents in Word documents exported from is compiled from any text that is
formatted in a style based on Word’s heading styles (Heading 1, Heading 2, or Heading 3). In the
default template, the only style that this applies to is the Annotation LeftHeader style, which is
1526
Chapter 1
based on the Heading 1 style. This style is used to format all text that appears in the left header of
the table. This means that all text in the left header is included in the table of contents. All other
header and footer styles are based on the Annotation style, which in turn is based on the Normal
style, and do not appear in the table of contents.
This example shows you how to display the table description in the Header Center annotation
position instead of in the Left Header position, but still use the description in the table of contents.
To do this, you need to change the content of the two annotation positions, and change the
formatting used in the annotation styles in the Word template.
To change the header or footer used in the table of contents:
E Using IBM® SPSS® Data Collection Base Professional, change the headers and footers so that
the text that you want to appear in the table of contents is in the correct position. For example,
remove the field {TableDescription \n} from the Header Left position, and add it to the Header
Center position.
E Export an example table to Word, specifying an output file name and folder in the Export File
Name field in the ., specifying an output file name and folder in the Export File Name field in the .
E When the export is complete you will see in the output folder, in addition to the exported Word
document, a template file called WordTemplate.dot.
E Open Word, then open WordTemplate.dot (do not open the .dot file by double-clicking on it as
this would create a new document).
E Open the Modify Style dialog:

From the Home tab in Word, expand the available styles under the Styles section. This opens
the Styles dialog box.
From the Styles list, select the AnnotationCenterHeader style, click the down arrow and
then select Modify....
E In the Style Based On field, change the style from Annotation to Heading 1. This changes the
formatting of the style, so you should also reset the font size and any other formatting to what it
was before. Then click OK.
E In the same way, select the AnnotationLeftHeader style and change the style that it is based
on from Heading 1 to Annotation.
E Save and close WordTemplate.dot. You can save this template in any folder (if you export to a
folder and finds an existing WordTemplate.dot in the folder, it does not overwrite it, so your
changes are not lost) but you may want to save it to the folder where all your other Word templates
are stored, and give it a new name. If you rename the template and/or save it to a folder other than
the output folder, you must explicitly select the template when you run the export.
E Using Base Professional, run the export again, using the TemplateFileName property of the
Export object to specify the path and filename of the customized Word template.selecting your
customized Word template in the Apply Word Template field of the Word Exports dialog box.
1527
Base Professional
Positioning the Output in a Microsoft Word Export File Using Bookmarks
Bookmarks are used in the default Microsoft Word template to position the tables, project and table
document descriptions, and table of contents. The following table lists the recognized bookmarks.
Bookmark Name Description
Export Indicates where the tables and/or charts are to be
inserted. If this bookmark does not exist in the
template, they are inserted after the table of contents.
SurveyTitle Indicates where the project and table document
descriptions are to be inserted. If this bookmark
does not exist in the template, these items are
inserted at the start of the document.
ContentsPage Indicates where the table of contents is to be
inserted. If this bookmark does not exist in the
template and the table of contents option is selected,
the table of contents is inserted after the project and
table document descriptions. If this bookmark exists
in the template when you are not using the table of
contents option, you will find that a blank page is
created at the bookmark.
To insert bookmarks in a template:
E Open the template in Word.
E If required, add any standard graphics or text (such as logos, introductory text, and page headers
and footers) that you want to appear in the Word documents.
E Place the cursor on a new line where you want the content to appear.
E From the Insert menu in Word choose Bookmark. This opens the Bookmark dialog box.
E Enter the Bookmark Name.
E Click Add.
E Repeat the steps 3-6 for any other bookmarks that are required.
E Save the template.
Working with Microsoft Word Styles
The Microsoft Word export uses a number of paragraph styles to format different types of text.
You can change the appearance of the various texts by changing the styles. You can do this in
the template or in the Word document itself. Working in the template has the advantage that
the styles can be used in multiple documents.
In Word, each paragraph style has a name and defines a combination of formatting characteristics,
such as font, font size, color, and emphasis, and text alignment, indentation, and spacing.
When you apply a specified style to an item, all of the formatting that is stored in that style is
automatically applied to the item. By changing the formatting defined for a style, you can quickly
change the formatting of all of the items to which the style has been applied.
1528
Chapter 1
The custom styles used by the Word export fall into four groups:
Annotation. Controls the formatting of the headers and footersannotations.
Axis. Controls the formatting of the row and column heading texts.
Cell. Controls the formatting of the cell contents.
Survey. Controls the formatting of the project and table document descriptions shown as a
document title, typically on the front page.
In the default template the base style in each group of styles is based on the Normal paragraph style.
This means you can change, for example, the base font in all of the tables that have been exported
using the default template, by simply changing the font in the template’s Normal paragraph style.
In addition all of the other styles within each group are in turn based on the previous style within
the group. This makes it easy to change the formatting of all of the styles in a group.
The names of all of the styles in the Axis group start with “Axis”, the names of the styles in the
Cell group start with “Cell”, and the names of the styles in the Survey group start with “Survey”.
When formatting a text, the export searches the appropriate group of styles for the closest
matching style. If there is no suitable style in the style group, the Normal style is used.
The table of contents in the Word document is compiled from any text that is formatted in a style
based on Word’s heading styles (Heading 1, Heading 2, Heading 3). In the default template, the
only style that this applies to is the Annotation LeftHeader style, which is based on the Header 1
style. This means that all text in the left header annotation is included in the table of contents. All
other annotation styles are based on the Annotation style and do not appear in the table of contents.
The easiest way to understand how it works is to create some tables of different types and export
them to Word using the default template, and then examine the styles that are applied to the
different texts. An easy way to find out which style is applied to a text is to use the Formatting
toolbar. When you place your cursor in a text in Word, the style that is applied to the text is shown
in the Styles box on the Formatting toolbar.
Tip: If the Styles box is not shown on the Formatting toolbar, you can add it using the Customize
dialog box. First open the dialog box by choosing Customize from the Tools menu. Then select
the Commands tab and drag the Styles category to the toolbar. When the Customize dialog box is
open, you can enlarge the Styles box by dragging the border with your mouse. When you close the
dialog box, the Styles box will retain its new size.
The following diagram shows the default styles that are applied to a table of Age by Gender that
has one item of cell contents (counts) and a mean element in the side axis.
1529
Base Professional
Figure 1-515
Word table with default styles
Notice that three different styles are used for the cell contents—Cell TopBottom Base Count,
Cell TopBottom Category Count, and Cell TopBottom and that all three of these styles are in
the Cell group:
The Cell TopBottom Base Count style is the closest match for the cell contents in the cells
formed from the base elements. The TopBottom subgroup is used because there is only one
item of cell contents, the Base subgroup is used because the cells are formed from a base
element, and the Count subgroup is used because the cell contents are counts.
A similar logic governs the choice of the Cell TopBottom Category Count style for the cell
contents in the cells formed from the category elements.
The Cell TopBottom style is the closest match for the cells formed from the mean element
because there is no Cell TopBottom Mean style in the default template.
If you want to define special formatting for the cells formed from the mean element, you would
create a new style called Cell TopBottom Mean if you want it to apply to all cell content types
or Cell TopBottom Mean Count if you want it to apply to counts only. Note that you need to
create the new style in a template and export the tables again using that template before the
new style will be applied.
Similar rules govern the styles that control the formatting of the row and column headings. For
more information, see the topic The Default Microsoft Word Export Styles on p. 1529.
Note: Unlike when using a cascading style sheet in HTML, in Word you can apply only one
paragraph style to an item.
The Default Microsoft Word Export Styles
The following table lists the custom styles in the default Microsoft Word template.
Annotation Annotation The default style for the headers
and footers.
1530
Chapter 1

Annotation TitleHeader The styles for the headers. When
Annotation LeftHeader the option to create a table of
Annotation CenterHeader contents is used, by default the
Annotation RightHeader table of contents is generated
from all of the text that has the
Annotation LeftHeader style
applied to it, as this style is
defined as inheriting from the
standard Heading 1 style.
Annotation TitleFooter The styles for the footers.
Annotation LeftFooter
Annotation CenterFooter
Annotation RightFooter
Axis Axis The default style for table row
and column headings.
Axis Side The default style for row headings.
Axis Side Variable The default style for row headings
that are formed from variable
names and labels. When there
is nesting on the side axis, this
style controls the formatting of
the outer nest only.
Axis Side SubElement The default style for row headings
that are formed from nested
variable names and labels.
Axis Side SubElement Base These styles enable you to apply
Axis Side SubElement Category formatting to the row headings
that relate to particular types of
nested elements. For example,
you may want to show the
headings that relate to nested base
rows in bold.
Axis Side Element The default style for row headings
that are formed from element
names and labels.
Axis Side Element Base These styles enable you to apply
Axis Side Element Category formatting to the row headings
elements. For example, you may
want to show the headings that
relate to base rows in bold. You
can add additional styles to define
formatting for row headings that
relate to other element types. For
example, you could add an Axis
Side Element Mean style to define
special formatting for mean rows.
See below for a list of the valid
element types.
Axis Top The default style for column
headings.
1531
Base Professional

Axis Top Variable The default style for column
headings that are formed from
variable names and labels. When
there is nesting on the Top axis,
this style controls the formatting
of the outer nest only.
Axis Top SubElement The default style for column
nested variable names and labels.
Axis Top SubElement Base These styles enable you to apply
Axis Top SubElement Category formatting to the column headings
nested elements. For example,
you may want to show the
headings that relate to nested base
rows in bold.
Axis Top Element The default style for column
element names and labels.
Axis Top Element Base These styles enable you to apply
Axis Top Element Category formatting to the column headings
elements. For example, you may
want to show the headings that
relate to base columns in bold.
You can add additional styles
to define formatting for column
headings that relate to other
element types. For example, you
could add an Axis Top Element
Mean style to define special
formatting for mean columns.
See below for a list of the valid
element types.
Cell Cell The default style for cell contents.
Cell Top These styles enable you to apply
Cell Top Base formatting to the first item of cell
Cell Top Base ColPercent contents in a table that has more
Cell Top Base Count than one type of cell contents
Cell Top Category (for example, counts and column
Cell Top Category ColPercent percentages). You can define
Cell Top Category Count formatting based on the element
and cell contents types. You can
add additional styles to define
formatting for other types of
elements and cell contents. See
below for the valid element and
cell contents types.
1532
Chapter 1

Cell Bottom These styles enable you to apply
Cell Bottom Base formatting to the last item of cell
Cell Bottom Base ColPercent contents in a table that has more
Cell Bottom Base ColPropResults than one type of cell contents
Cell Bottom Base Count (for example, counts and column
Cell Bottom Category percentages). You can define
Cell Bottom Category ColPercent formatting based on the element
Cell Bottom Category and cell contents types. You can
ColPropResults add additional styles to define
Cell Bottom Category Count formatting for other types of
elements and cell contents. See
below for the valid element and
cell contents types.
Cell Middle These styles enable you to apply
Cell Middle Base formatting to the middle items
Cell Middle Base ColPercent of cell contents in a table that
Cell Middle Base Count has three or more types of cell
Cell Middle Category contents (for example, counts, and
Cell Middle Category ColPercent column and total percentages).
Cell Middle Category Count You can define formatting based
on the element and cell contents
types. You can add additional
styles to define specific formatting
for other types of elements and
cell contents. See below for the
valid element and cell contents
types.
Cell TopBottom These styles enable you to apply
Cell TopBottom Base formatting to the items of cell
Cell TopBottom Base ColPercent contents in a table that has only
Cell TopBottom Base one type of cell contents (for
ColPropResults example, counts only). You can
Cell TopBottom Base Count define formatting based on the
Cell TopBottom Category element and cell contents types.
Cell TopBottom Category ColPercentYou can add additional styles
Cell TopBottom Category ColPropResults
to define specific formatting for
Cell TopBottom Category Count other types of elements and cell
contents. See below for the valid
element and cell contents types.
Survey Survey The default style for the document
title.
Survey Description The style for the table document
description.
Survey Name The style for the data set
description.
1533
Base Professional
The following table lists the valid element and cell contents types that you can use in the styles.
Valid Element Types Valid Cell Contents Types
Category Count
Mean UnweightedCount
StdDev Sum
StdErr Minimum
SampleVar Maximum
Total Mean
SubTotal Range
Text Mode
Minimum Median
Maximum Percentile
Net StdDev
Combine StdErr
Expression Variance
Base Residuals
UnweightedBase ExpectedValues
Indices
ColPropResults
ColPercent
RowPercent
TotalPercent
CumColPercent
CumRowPercent
Creating and Modifying Microsoft Word Paragraph Styles
You can modify styles in your exported Microsoft Word document, or in the template (.dot)
file, using Word’s Style dialog box.
To modify a paragraph style:
E Open the Modify Style dialog:

From the Styles list, select the paragraph style that you want to modify, click the down arrow,
and then select Modify....
E If you want to save the changes that you make to the template, select Add to template.
E To change the font, click Format and select Font. Select the required font and font size.
E To change the paragraph formatting, click Format and select Paragraph. Select the required options.
E Click OK.
To create a new paragraph style:
E Open the New Style dialog box:

Click the New Style icon.
1534
Chapter 1
E Enter the new style Name, using the naming rules explained in The Default Microsoft Word
Export Styles.
E Set the Style Type to Paragraph.
E If you want to base the formatting on another style, select the required style in the Based On
drop-down list.
E Select the appropriate formatting options you require.
E If you want to save the changes that you make to the template, select Add to template.
E Click OK.
Text Tables Export
Sample Script File: TextExport.mrs
IBM SPSS Data Collection Survey Reporter Professional comes with a Text Export component,
which enables you to export tables to a delimited text file (typically a .csv file).
The file encoding is UTF-8 and the output files contain the UTF-8 0xEF BB EF signature. The
exported data is in the character delimited format, and the default character is a tab. Tables are
also delimited by a character, which must be different from the field delimiting character. Here is
an example of the .csv output for a simple table of Age by Gender:
"Museum of the Living World"
"Visitor Survey"
"Museum of the Living World"

"Age by Gender<BR/>"
""
"Table: 1<BR/>Level: Top"
"Gender of respondent"
Base Male Female
"Age of respondent"
"Base" "602" "339" "263"
"11-16 years" "38" "23" "15"
"17-20 years" "82" "50" "32"
"21-24 years" "95" "51" "44"
"25-34 years" "192" "108" "84"
"35-44 years" "91" "49" "42"
"45-54 years" "55" "32" "23"
"55-64 years" "33" "16" "17"
"65+ years" "16" "10" "6"
""
"Cell Contents: <BR/>- Count<BR/>"
""
""
1535
Base Professional
Text Export Properties
Sample Script File: TextExport.mrs
When you export tables to a text file, you can control a number of options using the export
Destination Location and filename of String “” (An empty string.)
the exported text file. When the location is
not specified, the text
file will be created in
your default temporary
folder. If you do not
know where this is, you
can find out by opening
a command prompt and
typing cd %temp%. This
displays the location of
the temporary folder.
You can then browse to
this folder in Windows
Explorer to find the text
output.
in the export.
FieldDelimiter An integer value Long The integer representing
representing the the code for the comma
Unicode character code (,) character.
(sometimes called the
code point) for the
character to be used to
separate the fields.
LaunchApplication Launch the default Boolean False
application for the file
type after the export has
completed.
TableDelimiter An integer value Long The integer representing
representing the Unicode the code for the
character code for the form feed character.
character to be used to
separate tables. (This
should be different from
the FieldDelimiter.)
1536
Chapter 1

labels.
texts.
Example
The following example sets the Destination, TableDelimiter, and LaunchApplication export
properties.
With TableDoc.Exports.mrTextExport
.Properties["TableDelimiter"] = AscW(";")
.Properties["Destination"] = "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\TextExport.csv"
.Export()
End With
Notice that the TableDelimiter property has been set using the , which returns the integer code
for a given character. If you attempt to set this property (or the FieldDelimiter property) to the
character itself, you will get a “Type mismatch” error.
You should also use the AscW function if you use the mrScriptBasic to set these properties,
because these constants have a string value. For example:
Export.Properties["TableDelimiter"] = AscW(mr.FormFeed)
If you set the property using one of these constants without using the AscW function to convert it
to the integer value, it may be ignored and the default property value will be used instead or you
may get an “An error occurred accessing the Properties property for the XML element Export”
error, depending on the property’s position in the collection.
Requirements
Working with Axis Expressions

In IBM® SPSS® Data Collection Survey Tabulation and IBM SPSS Data Collection Survey
Reporter Professional, you can use numeric, text, and date variables in your tables by defining
an axis specification that bands or codes the values into categories. You can define the axis
specification for a variable at the time you create the table. Alternatively, you can save the axis
1537
Base Professional
specification in the metadata, and it will be used by default when you subsequently include the
variable on the side or top of a table.
Axis specifications that are saved in the metadata are sometimes called axis expressions. You
can create axis expressions for Boolean and categorical variables as well as for numeric, text,
and date variables. For example, you may want to set up axis expressions for multiple response
questions with nets or for rating questions with a mean element to show the average score. For an
introduction to axis expressions, see Working with Numeric Variables.
When defining axis expressions in the metadata, do not include the variable name, just specify the
element list syntax. For information about the element list syntax, see Element List Syntax.
There are a number of ways you can save an axis expression in the metadata. For example:
Manually. Sometimes it is useful to write individual axis specifications to an .mdd file. An easy
way of doing this is using MDM Explorer. For more information, see the topic Using MDM
Explorer to Store an Axis Expression on p. 1537.
mrScriptMetadata. You can define axis expressions using mrScriptMetadata in the Metadata
Section of a DMS file. For more information, see the topic Creating Axis Expressions and
Exporting to IBM SPSS Statistics on p. 456.
mrScriptBasic. You can define axis expressions using mrScriptBasic. This is particularly useful
when you want to use a standard axis expression for a number of variables. For information
on doing this in a standalone mrScriptBasic (.mrs) file, see Creating Axis Expressions in Your
Script. For information on doing this in a DMS file, see Creating Axis Expressions in the
OnBeforeJobStart Event Section.
Note: In the Metadata Model (MDM), axis expressions are saved in the AxisExpression property.
This is an unversioned property, which means that you can set it on locked versions of the
metadata.
Using MDM Explorer to Store an Axis Expression
Sometimes it is useful to write individual axis specifications to an .mdd file. An easy way of doing
this is using . This topic provides step-by-step instructions.
E Open the .mdd file in MDM Explorer.

1538
Chapter 1
Figure 1-516
MDM Explorer window with AxisExpression selected for the Age variable
E On the left side, open the Fields folder and then select the variable whose axis specification
you want to store.
E On the right side, double-click AxisExpression.

E Enter the required element list specification. Do not include the variable name, just the element
list syntax. For example:
{Under_25 'Under 25' expression('age < 25'),
Age25_34 '25-34 years' expression('age > 24 And age < 35'),
Over64 '65 and over' expression('age > 65'),
Mean 'Mean age' mean(age)}
Note that in this example the axis expression is shown on multiple lines, to aid readability.
However, in practice you must not include line breaks in the axis expression.
E Click OK.
E Save the file.
Creating Axis Expressions in Your Script
Sample Script Files: AutoSummarizeNumerics.mrs, AutoSummarizeNumericsAndSave.mrs
The AutoSummarizeNumerics.mrs example script is based on the Museum sample data set. The
AutoSummarizeNumericsAndSave.mrs example script is based on the Short Drinks sample data
set. To run examples using the Short drinks sample data set, you need access to an SQL Server
installation on which the Short Drinks sample database has been restored, and appropriate user
1539
Base Professional
access rights. . See also Running the Sample Table Scripts for information on running the
example scripts.
Sometimes you may want to include code in your mrScriptBasic table script to set up axis
expressions for some of your variables. This method is particularly suitable when you want to
use a standard axis expression for a number of variables. The following provides an example of
setting up standard axis expressions for summarizing all of the numeric variables in a data set.
The script also creates a simple one-dimensional table for each of the numeric variables using
the axis expressions.
' Create tables for all numeric variables
MakeTablesFromNumerics(TableDoc, TableDoc.DataSet.MDMDocument.Fields)
Sub MakeTablesFromNumerics(TableDoc, Fields)

Dim Field
' Loop through all fields and create a one-dimensional table for all
' of the numeric variables
' It's a numeric - autosummarize
AutoSummarizeNumeric(Field)
Field.FullName, Field.Label)
End If
MakeTablesFromNumerics(TableDoc, Field.Fields)
End Select
Next
End Sub
Sub AutoSummarizeNumeric(Field)
End Sub
Here is the table for the visits variable:

Figure 1-517
One-dimensional table with Visits on side axis. Min, max, mean, standard deviation and standard error
elements have been added by the axis expression.
1540
Chapter 1
This technique is useful when you want to set up multiple tables using a standard axis expression.
However, the axis expressions are stored in the metadata only while you run the script, because
the Table Object Model opens the metadata in no-save mode, which means that the changes you
make are not preserved after the script has finished running.
If you want to preserve the axis expressions, you need to open the metadata in read-write mode,
write the axis expressions, and then save the metadata. If you want to do this in the same .mrs
file that you use to set up the tables, you would typically do it before calling the Table Object
Model Document.Load method. For example:
Dim MDM
' Create the MDM object and open all versions of the
' short_drinks.mdd file in read-write mode
MDM.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Data\mdd\short_drinks.mdd", "{..}")
' Set up axis expressions for all numeric variables

' that don't already have one
CreateAxisExpressions(MDM.Fields)
Sub CreateAxisExpressions(Fields)
Dim Field
' Loop through all fields and create an axis expression for
' all of the numeric variables
' It's a numeric
End If
End If
CreateAxisExpressions(Field.Fields)
End Select
Next
End Sub
' Save the MDM Document to a new file

MDM.Save("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\short_drinks_new.mdd")
' Now create the Table Document object and load the metadata we just saved.
.
1541
Base Professional
.
.
Sample Table Scripts
The IBM® SPSS® Data Collection Developer Library comes with a number of sample
mrScriptBasic (.mrs) files that demonstrate how to create tables using the IBM® SPSS® Data
Collection Base Professional Tables Option. By default, these samples are installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables folder. You need to have
the Base Professional Tables Option to run these samples. Some of the samples have additional
requirements.
For step-by-step instructions on running the samples, see Running the Sample Table Scripts.
This topic lists the scripts that contain information on how to generate various types of tables
using Base Professional Tables Option.
Creating basic tables
To: See Topic: Sample Script:

Create a basic table Creating a Simple Table of Age by MyFirstTable.mrs
Gender
Create a basic frequency table For more information, see the topic MyFirstFrequencyTable.mrs
Creating a Frequency Table and Defining
Cell Contents on p. 1149.
Create tables with more than one variable on Concatenation and Nesting ConcatenatingAndNesting.mrs
an axis MoreonConcatenatingAndNesting.mrs
Create a banner for use in multiple tables Reusing Axes ReusingAxes.mrs
Create profile tables to display verbatims and Working with Profile Tables ProfileTables.mrs
non-aggregated respondent data.
Changing the information displayed in a table

Change the contents of a table cell For more information, see the topic CellContents.mrs
Examples on p. 1254.
Change the information included in the base For more information, see the topic The BaseElements.mrs
Base Element on p. 1230.
Change the information included in the base For more information, see the topic SpecialElements.mrs
using an expression Special Elements on p. 1204.
Change the categories included in the base For more information, see the topic IncludeInBase.mrs
Element Properties on p. 1222.
Specify the elements to display for a variable For more information, see the topic ElementSpecifications.mrs
Element List Syntax on p. 1200.
Add subtotals, totals and statistic values to a For more information, see the topic SpecialElements.mrs
table, create net elements Special Elements on p. 1204.
1542
Chapter 1

Hide zero values or rows/columns For more information, see the topic ZeroValues.mrs
Handling Zero Values and Setting Hide HideRules.mrs
Rules on p. 1153.
For more information, see the topic
Hiding Rows and Columns on p. 1419.
Show row percentages or column percentages - AllFieldsAndShowOpenEnds.mrs
depending on the orientation of a grid.
Adding filters

Create simple filters For more information, see the topic MyFirstFilter.mrs
Defining Your First Filter on p. 1166.
Create global, default and table For more information, see the topic MoreOnFilters.mrs
document filters More on Filters on p. 1168.
Modify the base element by applying For more information, see the topic The BaseElements.mrs
filters Base Element on p. 1230.
Filter a series of tables on each category - FilterOnAgeGroups.mrs
of a categorical variable
Filter hierarchical data For more information, see the topic HierarchicalFilters.mrs
Filtering Hierarchical Data on p. 1305.
Changing the format of a table

Add cell prefixes or suffixes Displaying Prefixes and Suffixes for CellPrefixAndSuffixUsage.mrs
Cell Items
Change the labels for an element For more information, see the topic ElementSpecifications.mrs
Element List Syntax on p. 1200.
Change the formatting for labels using For more information, see the topic FormattedLabels.mrs
HTML HTML Tables Export - Formatted
Labels on p. 1488.
Add images to labels For more information, see the topic DisplayElementImages.mrs
Displaying Images for Elements on p.
1405.
Change decimal places shown for an For more information, see the topic DecimalPlacesOnSummaryElements.mrs
element Specifying Decimal Places for
Summary Statistic Elements on p.
1403.
Sort the rows or columns of your tables For more information, see the topic MyFirstSortedTable.mrs
Introduction to Sorting Tables on p.
1408.
Sort complex tables For more information, see the topic SortedTables.mrs
Sorting Tables on p. 1407.
Set up annotations for tables For more information, see the topic Annotations.mrs
Defining Annotations on p. 1436.
Set up global table annotations For more information, see the topic Annotations.mrs
Defining Global Annotations on p.
1439.
1543
Base Professional
Tabulating numeric variables

Create a table using numeric variables For more information, see the topic NumericVariables.mrs
Working with Numeric Variables on p.
1172.
Create bands from numeric variables For more information, see the topic SpecialElements.mrs
Special Elements on p. 1204.
Show mean values of numeric variables For more information, see the topic SpecialElements.mrs
Special Elements on p. 1204.
Create summary statistic tables for For more information, see the topic AutoSummarizeNumerics.mrs
numeric variables by setting up standard Creating Axis Expressions in Your
axis expressions Script on p. 1538.
Save axis expressions to the metadata For more information, see the topic AutoSummarizeNumericsAndSave.mrs
Creating Axis Expressions in Your
Script on p. 1538.
Create summary statistics table with For more information, see the topic SummaryStatisticTables.mrs
statistics shown as elements Creating Summary Statistic Tables on
p. 1401.
Automatically generate summary - AllFieldsAndShowOpenEnds.mrs
statistics (mean, standard deviation,
etc.) for numeric variables
Automatically categorize numeric - AutoCategorizeWordTopLines.mrs
variables, or generate summary
statistics (mean, standard deviation,
etc.) depending on the number of
unique answers
Tabulating boolean variables

Automatically categorize boolean - AllFieldsAndShowOpenEnds.mrs
variables into True and False categories
- AutoCategorizeWordTopLines.mrs
Tabulating text variables

Autocode text variables For more information, see the topic NumericVariables.mrs
Working with Numeric Variables
on p. 1172.
Automatically categorize text answers to - AutoCategorizeWordTopLines.mrs
display one category for each unique answer
Autocode text questions or place individual - AutoCategorizeWordTopLines.mrs
answers in an HTML file and link to it from
the table annotations
Embed the answers to text questions - AllFieldsAndShowOpenEnds.mrs
directly within your tables
1544
Chapter 1
Working with grids and loops

Create simple grid tables For more information, see the topic MyFirstGridTable.mrs
Creating a Grid Table on p. 1174.
Tabulate data at different hierarchical For more information, see the topic HierarchicalData.mrs
levels, and set population levels Understanding Population Levels on p.
1279.
Set up tables for all categorical and - TabulateAllVariablesAtSpecifiedLevel.mrs
grid questions at a specified level.
Create grid tables from a grid question For more information, see the topic Grid GridTables.mrs
or a numeric loop Tables on p. 1290.
Create tables using slices from loops For more information, see the topic Grid GridAndLoopSlices.mrs
or grids and Loop Slices on p. 1299.
Combine two or more grid slices into For more information, see the topic CombineGridSlices.mrs
a single category within the grid Combining Grid Slices on p. 1302.
Loop through fields and create grid - AutoSummarizeNumericsAndSave.mrs
tables for numeric variables within the
grid
Data is collected as separate questions, For more information, see the topic DerivedGridTables.mrs
instead of in a loop or grid, but the data Derived Grid Tables on p. 1293.
is tabulated as if it is a grid
Working with weighted tables

Work with weighted and unweighted For more information, see the topic The BaseElements.mrs
bases Base Element on p. 1230.
Create tables using a weighting For more information, see the topic WeightedTables.mrs
variable Weighting Tables on p. 1169.
Create weighted tables using DMS see 7. Learning about Weighting in the DMSWeightedTables.mrs
scripting Data Management Scripting section
Running statistical tests on a table

Apply a chi-square test For more information, see the topic ChiSquareAndFisherTests.mrs
Example of the Chi-Square Test on p.
1317.
Apply a cell chi-square test For more information, see the topic CellChiSquareTests.mrs
Example of the Cell Chi-Square Test on
p. 1323.
Apply a column proportions test For more information, see the topic ColumnProportionsTest.mrs
Examples of the Column Proportions Test
on p. 1328.
Apply a column means test For more information, see the topic QuanvertTables.mrs
Examples of the Column Means Test on
p. 1338.
Apply Fisher’s exact test For more information, see the topic ChiSquareAndFisherTests.mrs
Example of Fisher’s Exact Test on p.
1318.
1545
Base Professional

Apply a net difference test For more information, see the topic NetDifferenceTest.mrs
Example of the Net Difference Test on
p. 1349.
Apply a paired preference test For more information, see the topic PairedPreferenceTest.mrs
Examples of the Paired Preference Test
on p. 1358.
Apply a product difference test For more information, see the topic ProductDifferenceTest.mrs
Example of the Product Difference Test
on p. 1364.
Apply a T-test test For more information, see the topic TTestTests.mrs
Example of the T-test Test on p. 1367.
Apply a Tukey test For more information, see the topic TukeyTest.mrs
Example of the Tukey Test on p. 1372.
Exporting tables

Export tables to HTML files For more information, see the topic HTMLExportOptions.mrs
HTML Tables Export on p. 1478.
Export charts to HTML files For more information, see the topic HTMLCharts.mrs
Creating Charts on p. 1181.
Export to tables and charts to For more information, see the topic WordExport.mrs
Microsoft Word Microsoft Word Tables Export on p.
1516.
Export to Microsoft Word using a - AutoCategorizeWordToplines.mrs
customized Word template
Export tables and charts to Microsoft For more information, see the topic ExcelExport.mrs
Excel Exporting to Excel on p. 1187.
Format Excel sheets from .mrs files. - MSExcelFormatting.mrs
Export to Microsoft PowerPoint For more information, see the topic PowerPointExport.mrs
Microsoft PowerPoint Tables Export on
p. 1509.
Export a table to a comma-separated For more information, see the topic Text TextExport.mrs
text file Tables Export on p. 1534.
Write the output from a table to a text For more information, see the topic CellValues.mrs
file using the ADO recordset Working with the ADO Recordset on p.
1265.
Write the output from a table, For more information, see the topic CellValuesAndLabels.mrs
including labels, to a text file using Working with the ADO Recordset on p.
the ADO recordset 1265.
Working with metadata

Understand the structure of a table For more information, see the topic UnderstandingAxes.mrs
Understanding Axes on p. 1237.
Work with versions of a metadata file For more information, see the topic WorkingWithVersions.mrs
Working with Versions on p. 1454. RDBTables.mrs
1546
Chapter 1

Calculate percentages based on For more information, see the topic PercentageOnElementsAsked.mrs
respondents who were asked a Changing the Base to Reflect the Version
question in a version compared to the on p. 1459.
number who answered.
Create topline tables for simple For more information, see the topic WorkingWithLabels.mrs
categorical variables in the IBM® Working with Labels on p. 1463.
SPSS® Data Collection Paper routing
if they have a short name.
Create tables in different languages For more information, see the topic WorkingWithLanguages.mrs
stored in the metadata Working with Languages on p. 1467.
Define a custom Japanese label. For more information, see the topic JapaneseLabels.mrs
Working with Languages on p. 1467.
Working with change tracker

Include functions that assist in For more information, see the topic ChangeTrackerFunctions.mrs
modifying Table Object Model Change Tracker - Functions on p. 1470.
metadata.
Modify metadata and save the For more information, see the topic ChangeTrackerTest1_NewDocument.mrs
modifications to a table document Change Tracker - Modifying Metadata in
file. a New Table Document on p. 1472.
Open a table document that includes For more information, see the topic ChangeTrackerTest2_OpenDocument.mrs
change tracker records, modify the Change Tracker - Modifying Metadata in
metadata, and save the modifications an Existing Table Document on p. 1474.
to a table document file.
Working with data in different file formats

Working with IBM® SPSS® For more information, see the topic QuanceptTables.mrs
Quancept™ files Loading Other Types of Data on p. 1188.
Working with IBM® SPSS® For more information, see the topic QuantumTables.mrs
Quantum™ files Loading Other Types of Data on p. 1188.
Working with IBM® SPSS® For more information, see the topic QuanvertTables.mrs
Quanvert™ files, and working with a Loading Other Types of Data on p. 1188.
built-in base element
Working with data from an RDB For more information, see the topic RDBTables.mrs
database Loading Other Types of Data on p. 1188.
Working with database questions. For more information, see the topic CreatingTablesBasedOnDatabaseQuestions.mrs
Creating tables based on database
questions on p. 1176.
Working with .SAV files For more information, see the topic SAVTables.mrs
Loading Other Types of Data on p. 1188.
Working with IBM® SPSS® For more information, see the topic SurveyCraftTables.mrs
Surveycraft™ files Loading Other Types of Data on p. 1188.
1547
Base Professional
Alphabetical List of Sample Table Scripts
The IBM® SPSS® Data Collection Developer Library comes with a number of sample
mrScriptBasic (.mrs) files that demonstrate how to create tables using the IBM® SPSS® Data
Collection Base Professional Tables Option. By default, these samples are installed into the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables folder. You need to have
the Base Professional Tables Option to run these samples. Some of the samples have additional
requirements.
For step-by-step instructions on running the samples, see Running the Sample Table Scripts.
This topic lists the scripts in alphabetical order.

Sample Description and related topics
AllFieldsAndShowOpenEnds.mrs This script demonstrates how to generate table
syntax to summarize numeric variables, how to
automatically categorize Boolean variables, how to
change the cell contents to show row percentages
in a grid table instead of the default column
percentages if the default orientation of the grid
requires this, and how to embed the answers to
text questions directly within your tables. (Note
that this is accomplished by accessing the IBM®
SPSS® Data Collection Data Model using ADO.)
Annotations.mrs Provides examples of setting up annotations to
display information about your tables. For more
information, see the topic Annotations on p. 1432.
AutoCategorizeWordTopLines.mrs An advanced script that demonstrates how to
intelligently define a table for a numeric question.
This is accomplished by determining the number of
unique answers to the numeric question (using the
Data Model). If there are fewer than a specified
number of unique answers, the script bands the
numeric question, defining one band for each
unique answer. If there are more than the specified
number of unique answers, it makes a summary
table. Similarly for text (open-ended) questions, the
script determines the number of unique answers.
If there are more than a specified number of
answers, it displays the text answers themselves
and if there are fewer than the maximum number
of unique answers, it autocodes them, defining
one category for each unique answer. The raw
text answers are placed in a separate HTML file
that can be URL-accessed from the Microsoft
Word export. Note that this is an advanced feature
and understanding this part of the script requires
knowledge of XML, XSLT, and the MSXML
DOM. This script also demonstrates using a
customized Word template. To run the script, two
files (TextAnswers.xsl and WordTopLines.dot) must
be present in the specified folder (by default, this
is [INSTALL_FOLDER]\IBM\SPSS\DataCollec-
tion\6\DDL\Scripts\Tables\Templates). Note that
this script may not be suitable for text variables
1548
Chapter 1

that store some non-alphabetic characters, such as
line feeds.
AutoSummarizeNumerics.mrs Provides an example of creating summary tables
for all of the numeric variables in a data set. This
is achieved by setting up standard axis expressions
for all the numeric variables. For more information,
see the topic Creating Axis Expressions in Your
Script on p. 1538.
AutoSummarizeNumericsAndSave.mrs This is similar to the AutoSummarizeNumerics.mrs
sample except that the axis expressions are written
to the metadata permanently and grid tables are
created for the numeric variables nested inside a
grid. For more information, see the topic Creating
Axis Expressions in Your Script on p. 1538.
BaseElements.mrs Provides examples of including and excluding
cases in the base element, and shows how to hide
the base element on a table. For more information,
see the topic The Base Element on p. 1230.
CellChiSquareTests.mrs Creates tables with Cell chi-square tests. For
further information, see Example of the Cell
Chi-Square Test.
CellContents.mrs Creates nine tables that demonstrate using different
types of cell contents. All of the tables crosstabulate
the same two variables and are described in detail
in Examples.
CellPrefixAndSuffixUsage.mrs Shows how to define prefix and suffix properties
for cell items. For more information, see the topic
Displaying Prefixes and Suffixes for Cell Items on
p. 1400.
CellValues.mrs Shows how to write the recordset for a table to a
text file. This is the first example in Working with
the ADO Recordset.
CellValuesAndLabels.mrs Shows how to combine the recordset for a table
with the element headings to write the complete
table to a text file. This is the second example in
Working with the ADO Recordset.
ChangeTrackerFunctions.mrs Includes functions that assist in modifying Table
Object Model metadata. For more information, see
the topic Change Tracker - Functions on p. 1470.
ChangeTrackerTest1_NewDocument.mrs Modifies metadata and saves the modifications to a
table document file. For more information, see the
topic Change Tracker - Modifying Metadata in a
New Table Document on p. 1472.
ChangeTrackerTest2_OpenDocument.mrs Opens a table document that includes change
tracker records, modifies the metadata, and saves
the modifications to a table document file. For
more information, see the topic Change Tracker
- Modifying Metadata in an Existing Table
Document on p. 1474.
ChiSquareAndFisherTests.mrs Creates tables with chi-square and Fisher’s exact
tests. For further information, see Example of the
Chi-Square Test and Example of Fisher’s Exact
Test.
1549
Base Professional

ColumnProportionsTest.mrs Creates tables with column proportions statistical
tests. For further information, seeExamples of the
Column Proportions Test.
CombineGridSlices.mrs Shows how to combine elements that are grid
iterations. For more information, see the topic
Combining Grid Slices on p. 1302.
ConcatenatingAndNesting.mrs Creates two tables using the same three variables. In
the first table two of the variables are concatenated
on the top axis and in the second table one of
the variables is nested inside the other. For more
information, see the topic Concatenation and
Nesting on p. 1156.
CreatingTablesBasedOnDatabaseQuestions.mrs Demonstrates how to create tables that are based on
Database Questions. For more information, see the
topic Creating tables based on database questions
on p. 1176.
DecimalPlacesOnSummaryElements.mrs Shows how to specify decimal places for summary
statistic elements. See Specifying Decimal Places
for a Summary Statistic Element in the Element
Properties topic.
DerivedGridTables.mrs Creates a number of tables that demonstrate
creating .mdm derived grids and using derived
grids in tables. For more information, see the topic
Derived Grid Tables on p. 1293.
DisplayElementImages.mrs Shows how to attach images to elements and export
them to HTML or Microsoft Word files. For more
information, see the topic Displaying Images for
Elements on p. 1405.
DMSWeightedTables.mrs This sample is designed to be run on the output
from the Weighting.dms sample DMS file. For
more information, see the topic 7. Learning about
Weighting on p. 222.
ElementSpecifications.mrs Contains examples of how to specify categories
and other elements you want to include in a table,
and how to display custom labels for elements.
For more information, see the topic Element List
Syntax on p. 1200.
ExcelExport.mrs Provides an example of exporting tables and charts
to Microsoft Excel and setting up properties for
the export. For more information, see the topic
Microsoft Excel Tables Export on p. 1498. To run
this sample, you need to have Microsoft Office
2007 or later installed.
FailoverDemo.mrs Provides an example for populating the remaining
batch tables when one or more tables fail. For more
information, see the topic Table Population and
Failover on p. 1191.
FilterOnAgeGroups.mrs Demonstrates setting up tables that are filtered on
each category of a categorical variable.
FormattedLabels.mrs Demonstrates setting up HTML formatting in the
variable and element labels and exporting them
to HTML using the UseFormattedLabels HTML
export property. For more information, see the
topic HTML Tables Export - Formatted Labels on
p. 1488.
1550
Chapter 1

GridAndLoopSlices.mrs Provides examples of creating tables using grid and
loop slices. For more information, see the topic
Grid and Loop Slices on p. 1299.
GridTables.mrs Provides examples of creating grid tables from both
a typical grid question and from a numeric loop.
For more information, see the topic Grid Tables on
p. 1290.
HideRules.mrs Provides examples of adding hide rules to tables to
hide rows, columns, or cells based on the values.For
more information, see the topic Hiding Rows and
Columns on p. 1419.
HierarchicalData.mrs Provides examples of creating tables for data in
a hierarchical data set and populating the tables
at different levels. See Understanding Population
Levels and Setting the Population Level for more
information.
HierarchicalFilters.mrs Contains examples of how to use filters with
hierarchical data. For more information, see the
topic Filtering Hierarchical Data on p. 1305.
HTMLCharts.mrs Creates some simple tables and exports them to
HTML as charts. For more information, see the
topic Creating Charts on p. 1181. To run this
sample, you need to have Microsoft Office 2007 or
later installed.
HTMLExportOptions.mrs Provides examples of setting up various options
when exporting tables to HTML. For more
information, see the topic HTML Tables Export
on p. 1478. To run this sample, you need to have
Microsoft Office 2007 or later installed.
IncludeInBase.mrs Provides examples of excluding categories from the
base calculation using the IncludeInBase property.
For further information see Excluding Categories
from the Base Element in the Element Properties
topic.
JapaneseTables.mrs Provides an example of selecting labels in Japanese
and defining a custom Japanese label for the
autobase elements. You need to have Japanese
installed on your computer to be able to view the
Japanese texts. For more information, see the topic
Working with Languages on p. 1467.
MoreOnConcatenatingAndNesting.mrs Creates a number of tables that demonstrate
complex concatenation and nesting of axes.
For more information, see the topic More on
Concatenation and Nesting on p. 1158.
MoreOnFilters.mrs Provides examples of setting up and using table,
global, and default filters. For more information,
see the topic More on Filters on p. 1168.
MSExcelFormatting.mrs Provides examples for formatting Excel sheets from
.mrs files. For example, the file provides examples
for freezing panes and including auto-filters.
1551
Base Professional

MyFirstFilter.mrs Creates two simple tables of Age by Gender,
both filtered to exclude respondents in the 11-16
age group. The first filter is created using the
ContainsAny function and the second using an
equivalent expression. For more information, see
the topic Defining Your First Filter on p. 1166.
MyFirstFrequencyTable.mrs Creates a simple frequency table and exports it
to HTML. For more information, see the topic
Creating a Frequency Table and Defining Cell
Contents on p. 1149.
MyFirstGridTable.mrs Provides simple examples of creating grid tables.
For more information, see the topic Creating a Grid
Table on p. 1174.
MyFirstSortedTable.mrs Provides simple examples of sorting tables on a
row or column. For more information, see the topic
Introduction to Sorting Tables on p. 1408.
MyFirstTable.mrs Creates the table described in the first topic in
the Tutorial. For more information, see the topic
Creating a Simple Table of Age by Gender on p.
1144.
NetDifferenceTest.mrs Creates tables with the net difference statistical test.
For further information, see Example of the Net
Difference Test.
NumericVariables.mrs Shows how to create tables using numeric
variables, by adding bands to group the values into
categories, and using summary statistics. For more
information, see the topic Working with Numeric
Variables on p. 1172.
PairedPreferenceTest.mrs Creates a paired preference test. For more
information, see the topic Paired Preference Test
on p. 1356.
PercentageOnElementsAsked.mrs Uses the IsElementInVersions function to determine
whether an element exists in a specific version of
the metadata and calculate percentages based on
numbers of respondents who were asked a question
compared to the number who answered. For more
information, see the topic Changing the Base to
Reflect the Version on p. 1459.
PowerPointExport.mrs Provides an example of exporting to Microsoft
PowerPoint and setting up properties for the export.
For more information, see the topic Microsoft
PowerPoint Tables Export on p. 1509. To run this
sample, you need to have Microsoft Office 2007 or
later installed.
ProductDifferenceTest.mrs Splits a number of variables on the side axis
into individual categories, creates a row for each
combination of categories, and carries out a column
proportions or column means test. For more
information, see the topic Example of the Product
Difference Test on p. 1364.
ProfileTables.mrs Contains examples of creating profile tables. For
more information, see the topic Working with
Profile Tables on p. 1443.
1552
Chapter 1

QuanceptTables.mrs Provides an example of creating tables using data
from IBM® SPSS® Quancept™qdi/drs files. For
further information, see Loading Other Types of
Data and Using the Flat (VDATA) View.
QuantumTables.mrs Provides an example of creating tables using data
from IBM® SPSS® Quantum™ .dat files. For
further information, see Loading Other Types of
Data.
QuanvertTables.mrs Provides an example of creating tables using data
from a IBM® SPSS® Quanvert™ database. See
Loading Other Types of Data. Tables created
include Examples of the Column Means Test, and
examples using the built-in Base Element.
RDBTables.mrs Demonstrates creating tables using case data
collected using IBM® SPSS® Data Collection
Interviewer Server and stored in an RDB
database. It also provides an example of using the
DataCollection.MetadataVersion system variable
in a table, setting up a custom label for an axis,
and defining properties for elements in the axis
specification. To run this sample, you need access
to an SQL Server installation on which the Short
Drinks sample database has been restored and
appropriate user access rights. See Loading Other
Types of Data, Working with Versions, and Element
Properties.
ReusingAxes.mrs Creates a reusable axis called MyBanner and
then uses this axis in multiple tables. For more
information, see the topic Reusing Axes on p. 1164.
SavTables.mrs Provides an example of creating tables using data
from a .sav file. For more information, see the topic
Loading Other Types of Data on p. 1188.
SortedTables.mrs Provides examples of sorting nested and
concatenated tables, tables containing nets and
other special elements, and grid tables. For more
information, see the topic Sorting Tables on p.
1407.
SpecialElements.mrs Provides examples of using special elements in
tables, including means based on numeric variables
and on factors, total and subtotal elements, net
elements, combined elements, derived elements and
sum elements. Also includes examples of banding
numeric and date variables and autocoding text
variables, and other examples using expressions
to define elements. For more information, see the
topic Special Elements on p. 1204.
StatisticalTests.mrs Creates tables with chi-square and column
proportions statistical tests. For further
information, see Example of the Chi-Square Test
and Examples of the Column Proportions Test.
SummaryStatisticTables.mrs Shows how to create tables containing summary
statistics of numeric variables (in this case, tables
of means). For more information, see the topic
Creating Summary Statistic Tables on p. 1401.
1553
Base Professional

SurveyCraftTables.mrs Provides an example of creating tables using data
from IBM® SPSS® Surveycraft™ .qdt/vq files.
For more information, see the topic Loading Other
Types of Data on p. 1188.
TabulateAllVariablesAtSpecifiedLevel.mrs This sample sets up tables for all categorical and
grid questions at a specified level. A message is
written to a text file if the level is invalid for a
particular variable.
TextExport.mrs Provides an example of exporting tables to a .csv
text file and setting up properties for the export.
For more information, see the topic Text Tables
Export on p. 1534.
TTestTests.mrs Creates tables with T-test tests. For further
information, see Example of the T-test Test.
TukeyTest.mrs Creates tables with Tukey tests. For further
information, see Example of the Tukey Test
UnderstandingAxes.mrs Illustrates the way in which the axis structure of
complex tables is built up in the Table Object
Model. For more information, see the topic
Understanding Axes on p. 1237.
WeightedTables.mrs Creates two simple tables of Age by Gender, both.
weighted using the Genbalance weighting variable.
For more information, see the topic Weighting
Tables on p. 1169.
WordExport.mrs Provides an example of exporting tables to
Microsoft Word and setting up properties for the
export. It also includes adding an image to the
annotations. For more information, see the topic
Microsoft Word Tables Export on p. 1516. To run
this sample, you need to have Microsoft Office
2007 or later installed.
WorkingWithLabels.mrs Provides an example of creating top line tables for
all the simple categorical variables in the IBM®
SPSS® Data Collection Paper routing that have a
short name defined. For more information, see the
topic Working with Labels on p. 1463.
WorkingWithLanguages.mrs Provides an example of creating tables in a language
that is stored in the metadata but is not the default
language and setting up element and variable labels
in that language. For more information, see the
topic Working with Languages on p. 1467.
WorkingWithVersions.mrs Provides an example of loading a specific version of
the metadata and filtering the case data on the same
version. To run this sample, you need access to an
SQL Server installation on which the Short Drinks
sample database has been restored and appropriate
user access rights. For more information, see the
topic Working with Versions on p. 1454.
ZeroValues.mrs Provides examples of using special characters
to represent zero values, and of hiding rows
and columns containing only zero values using
hide rules or element specifications. For more
information, see the topic Handling Zero Values
and Setting Hide Rules on p. 1153.
1554
Chapter 1
Note: In addition to these sample .mrs files, the Data Collection Developer Library comes with
some sample data management script (DMS) files that demonstrate creating tables in a DMS file.
For more information, see the topic Table Scripting Sample Data Management Scripts on p. 478.
Warning: You can use the samples as a starting point when you develop your own table scripts.
Requirements
Running the Sample Table Scripts
You can run the sample table script (.mrs files) in IBM® SPSS® Data Collection Base Professional
or using the mrScript Command Line Runner.
To run the Sample Scripts in IBM SPSS Data Collection Base Professional
E Open Base Professional.
E Open the .mrs file you want to run (by default, the sample table script files are installed in the
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables folder).
E Press Ctrl+F5 OR choose Start Without Debugging from the Debug menu OR select the Start Without
Debugging tool on the Debugging toolbar.
For more information on editing, running, and debugging mrScriptBasic files in Base Professional,
see Using IBM SPSS Data Collection Base Professional.
To run the Sample Scripts using the mrScript Command Line Runner
E Open a Command Prompt. For example, in Windows 2000, choose Programs from the Windows
Start menu, and then choose Accessories, followed by Command Prompt.
E Change to the folder in which the sample files are located (by default, the sample table script files
are installed in the [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Tables folder).
E Type mrScriptCL followed by the name of the file you want to run and the options you require. For
example, to run the MyFirstTable.mrs sample, enter:
mrScriptCl MyFirstTable.mrs
Requirements

1555
Base Professional
Limits
This topic describes the limits that apply when you create and populate tables.
Table Size in IBM SPSS Data Collection Survey Tabulation
By default, a warning message appears when you populate tables containing over 10,000 cells at a
time using IBM® SPSS® Data Collection Survey Tabulation. The number of cells is calculated by
multiplying the number of rows by the number of columns, for each table that you are populating.
Note that this includes any hidden rows and columns that are part of the table specification.
If you populate a number of tables at the same time using Populate All, the warning appears if
the total cell count for all tables added together is over the 10,000 limit. If you populate tables
individually, each table can contain up to the 10,000 limit.
If you want to populate tables containing more than the maximum number of cells, you can
ignore the warning message, but you may find that your tables take a long time to populate. If
this happens, consider making one or more of the following changes to bring the total cell count
below the limit:
reduce the number of tables in the table document
populate tables one at a time using Populate rather than Populate All
reduce the size of individual tables by removing unnecessary variables, elements, or levels
of nesting
redesign your tables so that the information in very large tables is split between two or more
smaller tables
Your system administrator can change the limit that triggers the warning message, to tailor it to
the system resources available to you. For example, if you find that the warning message is
appearing unnecessarily, you may want your system administrator to increase the limit at which
the message appears.
By default, there is no absolute limit that prevents you from populating tables with very large
numbers of cells. However, your system administrator can add an absolute limit, above which an
error message appears and prevents you from continuing to populate the tables. If you never intend
to create tables above a certain size, you may want your system administrator to add an absolute
limit at the maximum expected size, so that Survey Tabulation prevents you from populating large
tables created in error. See the Survey Tabulation Installation Instructions and Configuration Notes
help file for information on how to change the warning limit or add an absolute limit.
There is no limit to the size of the tables that you can create using Survey Tabulation Studio
option; the maximum table size depends on your system resources.
Tables with Nested Variables
When you nest variables in a table, the elements of a nested variable are displayed for each
element of the variable within which it is nested. An element that has elements of another variable
nested within it is sometimes called a section. For example, in the following table, the Gender
1556
Chapter 1
variable, which has two elements (Male and Female), is nested within the Interview variable,
which also has two elements (Entering and Leaving). This table has two sections, one formed
from the Entering element, the other from the Leaving element.
Figure 1-518
Table with two variables nested on the top axis
If we now nest the Before variable within the Gender variable, the table would have four sections.
You can calculate the number of sections by multiplying the number of elements in the outer
variable (Interview, which has two elements) by the number of elements in the variable nested
within it (Gender, which also has two elements). The number of elements in the innermost nesting
level is not relevant to this calculation.
Survey Tabulation and IBM SPSS Data Collection Survey Reporter Professional have a built-in
limit of 500 sections on the side or top axis of the table. If you create a table that exceeds this
limit, you are likely to encounter “Aggregator Error 290” when you attempt to populate the table.
Note: Only the weight in the lowest level is honored when applying weights, for the element
of different variables, at different nest levels.
Table Object Model Reference

At the heart of IBM SPSS Data Collection Survey Reporter Professional is the Table Object
Model. This implements the objects that define all of the tables in a table document, along with
the axes, elements, cell contents, statistical tests, filters, annotations, etc. The Table Object Model
uses additional components to calculate the numeric values inside the cells of the tables. However,
all interaction with these components takes place through the Table Object Model and in normal
circumstances, you do not access these components directly. The Table Object Model is also part
of IBM® SPSS® Data Collection Survey Tabulation, and information about these additional
components is available in the Survey Tabulation section.
The Table Object Model is a COM component that is easily accessed using mrScriptBasic and
other programming languages such as Visual Basic. Except where stated otherwise, all of the
examples in this section are in mrScriptBasic.
This section provides a description of the Table Object Model (TOM) interface.
1557
Base Professional
Requirements
Elements and Element Properties
The Element object supports the following read/write properties (in addition to some more
properties that are read-only):
AnalysisVariable
CalculationScope
CutOffValue
Decimals
Expression
Factor
IncludeInBase
IsFixed
IsHidden
IsHiddenWhenColumn
IsHiddenWhenRow
IsUnweighted
Label
Multiplier
Weight
The IsFixed, IsHidden, IsHiddenWhenColumn, IsHiddenWhenRow, and Label properties can be

specified for all elements. The default values for the IsFixed, IsHidden, IsHiddenWhenColumn,
and IsHiddenWhenRow properties depend on the element – more information on this is included
in Table 2 below. For elements based on an MDM element, the Label property will be the label of
the MDM element, otherwise it will be empty, “”.
The CutOffValue property can only be specified for the ePercentile element type.
Table 1 shows the remaining properties. For the AnalysisVariable, Decimals, Expression,
Multiplier, Weight, and IncludeInBase properties, “Yes” indicates that a value can be set, while
“No” indicates an error occurs when trying to set the property value. Note that “Yes” doesn’t
mean the value has an effect – see the footnotes for more information. For the CalculationScope
and Factor properties “Yes” indicates the property has an effect and “No” indicates that the
property doesn’t apply to that element type. For IsUnweighted an error occurs when trying to
set the property to False for the eBase and eUnweightedBase elements, otherwise a “No” in the
column indicates IsUnweighted doesn’t apply to that element type.
Table 1-7
Table 1
AnalysisVariable CalculationScope Decimals Expression IsUnweighted
eCategory No No No No Yes
1558
Chapter 1
AnalysisVariable CalculationScope Decimals Expression IsUnweighted

eBase No No No Yes 4 No
eTableStatistic No No Yes No No
eEffectiveBase No No No No No
eSumWeightsSquared No No No Yes 4 Yes
eSumN No No No Yes 4 Yes
eSumX Yes No No Yes 4 Yes
eSumXSquared Yes No No Yes 4 Yes
eSumUnweightedN No No No Yes 4 Yes
eMean Yes Yes Yes Yes 4 Yes
eStdDev Yes Yes Yes Yes 4 Yes
eStdErr Yes Yes Yes Yes 4 Yes
eSampleVar Yes Yes Yes Yes 4 Yes
eTotal No No Yes No No
eSubTotal No No Yes No No
eText No No No No No
eNetDiffs No No No No No
ePairedPref No No No No No
eMinimum Yes No Yes Yes 4 Yes 3
eMaximum Yes No Yes Yes 4 Yes 3
eOtherDerived No No No No Yes
eNet No Yes No No Yes
eCombine No No No No Yes
eExpression No No No Yes Yes
eUnweightedBase No No No Yes 4 No
eNumeric Yes No No Yes 4 Yes
eDerived No No Yes Yes 4 No
eSum Yes No Yes Yes 4 Yes
ePercentile Yes No Yes Yes 4 Yes
eMedian Yes No Yes Yes 4 Yes
eMode Yes No Yes Yes 4 Yes
1 For an eBase element it’s possible to set the Weight and Multiplier properties. This only takes
effect when an expression is specified for the element (i.e. the Expression property is set).
2 As with the eBase element, a Multiplier can be specified for the eUnweightedBase element but
this only takes effect if the element has an expression.
3 Weighting (the Weight and IsUnweighted properties) has no effect on the eMinimum and
eMaximum element types.
4 Attempting to set an Expression for an element added via IElements.Add will

generate an error. You can only set it for elements added via IElements.AddNew() and
IElements.AddNewFromMdmVariable().
1559
Base Professional
5 When using the Adjust roundings so percentages add up to 100% option, the values will not add up
to 100% when decimal places are not used. A work-around for this issue is to include the property
IncludeInBase=False against the eCombine and eExpression elements.
Table 1-8
Table 2
IsFixed IsHidden IsHiddenWhenColumn
eCategory FALSE FALSE FALSE
eBase TRUE FALSE FALSE
eTableStatistic TRUE FALSE FALSE
eEffectiveBase TRUE TRUE FALSE
eSumWeightsSquared TRUE TRUE FALSE
eSumN TRUE TRUE FALSE
eSumX TRUE TRUE FALSE
eSumXSquared TRUE TRUE FALSE
eSumUnweightedN TRUE TRUE FALSE
eMean TRUE FALSE FALSE
eStdDev TRUE FALSE FALSE
eStdErr TRUE FALSE FALSE
eSampleVar TRUE FALSE FALSE
eTotal TRUE FALSE FALSE
eSubTotal TRUE FALSE FALSE
eText TRUE FALSE FALSE
eNetDiffs TRUE FALSE FALSE
ePairedPref TRUE FALSE FALSE
eMinimum TRUE FALSE FALSE
eMaximum TRUE FALSE FALSE
eOtherDerived TRUE FALSE FALSE
eNet FALSE FALSE FALSE
eCombine FALSE FALSE FALSE
eExpression FALSE FALSE FALSE
eUnweightedBase TRUE FALSE FALSE
eNumeric FALSE FALSE FALSE
eDerived FALSE FALSE FALSE
eSum TRUE FALSE FALSE
ePercentile TRUE FALSE FALSE
eMedian TRUE FALSE FALSE
eMode TRUE FALSE FALSE
Table 2 shows the default values for the IsFixed, IsHidden, IsHiddenWhenColumn, and
IsHiddenWhenRow properties.
The default value for the IsFixed property is shown in the table and only depends on the element
type.
1560
Chapter 1
For elements added from the metadata (i.e. via IElements.Add() and AddNewFromMdmVariable()
), the default value for the IsHidden property depends on the setting of the “Hidden” custom
metadata property for the element. Some element types (added from the metadata) will always
be hidden by default (IsHidden=True) as shown in the table below. For elements added via
IElements.AddNew() and IElements.AddNewFromMdmVariable() the IsHidden property will
always default to False.
For elements added from the metadata, the default value for the IsHiddenWhenColumn
and IsHiddenWhenRow properties depend on the setting of the “HiddenWhenRow”
and “HiddenWhenCol” custom metadata property for the element (respectively). If
the custom property isn’t, or the element was added via IElements.AddNew() and
IElements.AddNewFromMdmVariable(), the default value is always False.
Metadata Services Object Model Reference

The Metadata Services Object Model implements objects that define the operations used to record
modifications of metadata in a table document. Modifications can include tasks such as modifying
a field, renaming a field, creating a folder, adding/moving fields into folder, and so on. The
Metadata Service Object Model is a COM component that is easily accessed using mrScriptBasic
and other programming languages such as Visual Basic. Except where stated otherwise, all of the
examples in this section are in mrScriptBasic.
This section provides a description of the Metadata Service Object Model.
Requirements
QsfTom component object model reference

The QsfTom component converts Quanvert saved table specs (as many as possible) to a set of
TOM table specs in an MTD file. The QsfTom component is a COM component that is easily
accessed using mrScriptBasic and other programming languages such as Visual Basic. Except
where stated otherwise, all of the examples in this section are in mrScriptBasic.
Accessibility Guide
This section provides an overview of alternative methods for accessing the functionality of the
product. More specifically, the following topics are covered:
Keyboard navigation of the software
Special issues for visually impaired users
Special issues for blind users
Special considerations
Important: If using a screen reader, use the F6 key to switch between this help system’s
Navigation pane and Contents pane.
1561
Base Professional
Keyboard Navigation
Much of the product’s functionality is accessible via the keyboard. At its most basic level, you
can press the Alt key to activate window menus or press the Tab key to scroll through dialog
box controls.
For complete details about keyboard shortcuts in the IBM® SPSS® Data Collection Base
Professional user interface, see the following topics:
The IBM SPSS Data Collection Base Professional menu
IBM SPSS Data Collection Base Professional toolbars
Accessibility for the Visually Impaired
You can specify a number of options to enhance your ability to use the software:
Use the Text Display settings in the Options dialog to increase the font size of menu and
toolbar text. For more information, see the topic IBM SPSS Data Collection Base Professional
options on p. 101.
For more information, see the topic Special Considerations on p. 1561.
Accessibility for Blind Users
Support for blind users is predominately dependent on the use of a screen reader. IBM® SPSS®
Data Collection Base Professional has been tested with JAWS® for Windows® (copyright
Freedom Scientific™, http://www.freedomscientific.com)
For more information, see the topic Special Considerations: Interference with Other Software
on p. 1562.
During testing with JAWS, it was found that listening to the table results is easier while in full
screen view. To enter full screen view, press the F11 key. To exit full screen view, press the
Esc key.
Important: If using a screen reader, use the F6 key to switch between this help system’s
Navigation pane and Contents pane.
Special Considerations
There are issues that deserve special attention, as outlined in the following topics.
Note: Although we are working to make IBM® SPSS® Data Collection Base Professional
accessible to all assistive technologies, Base Professional has been tested only with the JAWS for
Windows screen reader software version 8.0.
1562
Chapter 1
Special Considerations: Dialog Boxes
The initial focus in a dialog box is generally placed on the control in the upper left area. From
there, you can access other controls in the dialog box by pressing the Tab key. Alternatively, you
can use the dialog box keyboard shortcuts listed below.
The placement of a control in the tabbing order is determined by the section it belongs to, the type
of control it is, and its placement in the dialog box. Note that some dialog boxes may not have all
types of controls or the same number of controls.
For dialog boxes containing more than one user interface tab (the Options dialog box, for
example), the initial focus is generally placed on the first tab itself. Use the key combination
Ctrl+Tab to navigate to other tabs. Press the Tab key to navigate through the controls on each tab.
Special Considerations: Interference with Other Software
When testing IBM® SPSS® Data Collection Base Professional with screen readers such as JAWS,
other software may interfere. For example, our development team discovered that the use of a
Systems Management Server (SMS) within your organization may interfere with JAWS’ ability
to read some products. Disabling SMS will rectify this situation. Visit the Microsoft web site
for more information about SMS.
Troubleshooting
Q. Why are the keyboard shortcuts not working in when the application is run in a Citrix environment?
A. When running the application in a Citrix environment, the keyboard shortcuts/hot keys that are
defined for the application may conflict with the default Citrix keyboard shortcuts. You can resolve
the conflict by changing the conflicting Citrix keyboard shortcuts/hot keys. Refer to the following
Citrix Knowledge Center article for more information: How to Enable or Disable Hotkeys within
an ICA file (including Template.ica) (http://support.citrix.com/article/CTX140219).
Q. Why does the application not run in a Citrix environment when I set the Use Built-in Browser
setting to “False”?
A. This is a known limitation when running in a Citrix environment. You can successfully run the
application when the Use Built-in Browser option is set to True.
IBM SPSS Data Collection Base Professional FAQs

This section provides answers to some frequently asked questions that relate specifically to
working in the IBM® SPSS® Data Collection Base Professional IDE.
Q. How can you make the error message go away when you are debugging?
A. Press Esc.
Q. What types of files can you work with in Base Professional?

1563
Base Professional
A. For more information, see the topic Which File Types Can I Work With? on p. 12.
Q. When specifying a relative path in a script, to what location should the path be relative?
A. When you run or debug a script, Base Professional sets the “current location” to the location
of the script. This means that generally any relative paths should be specified relative to the
location of the script you are running.
However, when you specify the path to an include file, it must always be specified relative to the
folder in which the file that contains the Include statement is located.
Q. When using a For Each loop with the MDM Document.Fields collection, the ScriptAssist feature
does not work. Why is this?
A. This is because the MDM Document.Fields collection can contain objects of more than one
type. For example, the Document.Fields collection can contain Variable, Class, Array, Grid, and
Compound objects. Because Base Professional cannot tell the object’s type, it is not able to
provide ScriptAssist. The same thing applies to any other collection that can contain objects of
more than one type.
Q. I have used the following code to create an object in Base Professional, but I can’t see the type
library in the Types pane. Why is this?
Dim MyComponent
MyComponent = CreateObject("MRDSCReg.Components")
A. When you assign objects in mrScriptBasic, you need to use the Set keyword. So to make the
type library appear in the Types pane you need to change your script as follows:
Dim MyComponent
Set MyComponent = CreateObject("MRDSCReg.Components")

MyComponent.
Then reference the object and type the dot (.) that activates the ScriptAssist feature. Now the type
library will appear in the Types pane.
Q. I have rearranged the various panes in the Base Professional IDE. How can I return them to their
original positions?
A. For more information, see the topic Changing the Layout of the Window on p. 16.
Q. Is there a way for me to add my own object model so that I can get ScriptAssist on it?
A. Base Professional automatically makes ScriptAssist available for all suitable COM object
models that are created using the CreateObject function. However, ScriptAssist is not available
if the object model is based on IDispatch interfaces only, because then the necessary type
information is not available.
Q. Is ScriptAssist available for mrScriptMetadata?

1564
Chapter 1
A. No, ScriptAssist is not available for mrScriptMetadata.
Q. Why does a line feed appear as a small square in the Locals pane?
A. The square symbol is used to indicate a line feed, because the Locals pane can show only
one line for each variable.
Q. How does the Locals pane show variables that are declared within a function or subprocedure?
A. The Locals pane follows the mrScriptBasic scope rules and displays local variables only when
in the function or subprocedure.
Q. When I open an existing script, change it, and then close it without running it, I am asked whether I
want to save my changes. However, I am not asked this if I run the script before closing it. Why is this?
A. This is because you have the Save Before Execution option set to True. This option means that
scripts are automatically saved before you run them. If you want Base Professional to always
ask whether you want to save the script before running it, set this option to False. For more
information, see the topic IBM SPSS Data Collection Base Professional options on p. 101.
Q. Is there a way of viewing a variable’s label in the Metadata Viewer, like you can in MDM Explorer?
I need to see the labels in order to distinguish between the various variables, some of which have
similar names.
A. You need to show the Properties pane. You do this by choosing Properties from the View menu.
Then, when you select a variable (or category) in the Metadata Viewer, the Properties pane will
show the properties of the variable (or category), a bit like the right side of the window in MDM
Explorer does. If you scroll down through the properties, you will come to the label.
Q. Why do I get the message “The selected Font is not supported in Base Professional. Base
Professional will revert to the previously used Font” when I try to change the default Base Professional
font?
A. The font that you have selected does not meet the requirements for Base Professional. The
default requirement for an Base Professional font is that it must support bold and italic. To add or
remove font requirements, edit the Base Professional syntax definition files.
Q. When I closed and reopened my new interview script (.mdd) file, I noticed that the layout of the
code in the metadata section has changed. Why has this happened?
This is because the language used in the metadata section, mrScriptMetadata, contains its own
internal instructions that determine how the syntax of the language is displayed. This is designed
to make mrScriptMetadata easier to read, for example, by defining a single question over several
lines rather than on one long line.
Q. When I start Base Professional, a message appears telling me that my Base Professional license
has expired. How do I renew my license?
1565
Base Professional
Run C:\Documents and Settings\All Users\Application Data\IBM\SPSS\DataCollection\6\Base

Professional\licrenew.exe and when prompted, enter the new license code(s) that have been
supplied to you by IBM® SPSS® Data Collection.
Q. Why do I receive a message that says required variables are missing and reactivation is required
when I attempt to open an MDD in IBM® SPSS® Data Collection Interviewer 6.0.1?
IBM® SPSS® Data Collection Interviewer supports new system variables in the 6.0.1 release. If
an MDD file does not include these system variables, reactivation to Interviewer 6.0.1 is required.
For more information, see the topic Activating Interview Scripts on p. 987.
Error Messages
IBM® SPSS® Data Collection Base Professional displays a message in the Output pane
when an error occurs when you run a script. Some messages are simple and self-explanatory.
However, some error messages are more complex and can originate in more than one component.
For example, the following message was displayed when running a table script in which the
connection string for an RDB database was specified incorrectly.
Table aggregation failed: Aggregator error 239: Failed to initialise CDSC.:
Error creating RDB2 schema. Schema creation is required because the SchemaVersion
table is missing. A partial schema may have been created and this will need to be
dropped before attempting to reconnect: Unknown table 'SchemaVersion'
The first part of this message originated in the Table Aggregator, which is a component that is used
by the Table Object Model (TOM) to populate tables. () The second part of the message originated
in RDB DSC 2, which the Table Aggregator uses to access the case data in the RDB database. This
is merely an example of an error message that originates in two IBM® SPSS® Data Collection
components. Some error messages may originate in more than two components, and may include
messages from Windows components and any other components you reference in your scripts.
Error messages that originate in Data Collection components generally contain an identifying text
or a prefix, and this is helpful when attempting to track down the cause of the problem. For
example, knowing that the above error originated in RDB DSC 2, helped the scriptwriter establish
the cause of the error.
Data Management Troubleshooting and FAQs

This section provides some troubleshooting tips and answers to some of your frequently asked
questions. This section contains the following:
General Queries
FAQs on the Differences Between DMS and .mrs Files
General Queries
FAQs About How To Set Up Specific Jobs
FAQs About File Locations
SQL Syntax FAQs
1566
Chapter 1
Metadata Section FAQs

Event Section Problems
Problems Using Global Variables
Questions About the DMOM Object Model
Problems Using Other OLE DB Providers
Some Common DMS File Errors
Weighting FAQs
WinDMSRun FAQs
Programmer’s FAQs
Performance Problems
General Queries
Q. I want to learn about data management scripting, but I don’t know where to start. Do you have any
tips?
A. Try the Data Management Scripting Getting Started Guide. This walks you through running
your first transfer, setting up filters, queries, and connection strings, running a simple cleaning and
weighting script, and gives suggestions on how to use the resources in the IBM® SPSS® Data
Collection Developer Library to develop your skills.
Q. Is there a limit to the number of Include statements you can have in a single DMS file?
A. There are no built-in limits to the number of Include statements you can use in your DMS files.
Q. Is there a limit to the number of text substitutions you can define; for example, in an Include
statement?
A. There are no built-in limits to the number of text substitutions you can define. Remember that
you cannot use line-continuation characters in Include statements, so the text substutitions must be
defined on one line. However, there is no practical limit to the number of characters in a line.
Q. A number of XML files have been created in my DMS file folder. These files have names of the form
myFile_exception_20020702_120000.xml. What are these files?
A. If you use the /x option in DMS Runner, it creates one of these files (called exception XML
files) when the execution of a DMS file fails. In the event that you need to contact IBM® SPSS®
Data Collection Technical Support because of the failure of a DMS file, you should send the
exception XML file that relates to the failure. You should be able to identify the file using the
numbers in the filename, which are in the form yyyymmdd_hhmmss and represent the date and
time the file was written. (yyyy represents the year, mm the month, etc.) If you do not need to
contact Data Collection Technical Support, you can safely delete these files.
1567
Base Professional
Q. Can you explain how DMS Runner calculates the timings it displays? For example:
Time elapsed : 00:00:03.0846816

Records transferred : 107
Records per second : 34.69
A. “Time elapsed” refers to the time taken to actually transfer the records and to run the
OnJobStart, OnNextCase and OnJobEnd Event sections. This time is then used to calculate
the number of records transferred per second. The “Time elapsed” does not include the time
taken to validate the DMS file, merge and save the output metadata, run the OnBeforeJobStart,
OnAfterMetaDataTransformation, and OnAfterJobEnd Event sections or any update queries,
or initialize and close down the data sources.
Note that the number of records transferred per second is not shown when the “Time elapsed” is
less than one second.
Q. Watch out for the Data Source connection property.
A. If you type your connection strings in by hand (rather than generating them using the IBM®
SPSS® Data Collection Base Professional Connection String Builder or WinDMSRun) make
sure that you spell the Data Source connection property correctly. If you spell it as one word
(DataSource) the DMS file may fail. This is a very easy mistake to make because the DataSource
object in the MDM is one word, the InputDataSource section is one word, but the connection
property is two words.
FAQs on the Differences Between DMS and .mrs Files
Q. Can you clarify the difference between DMS files and .mrs files, and when to use DMS Runner
and when to use the mrScript Runner.
A. A DMS file is a text file with a .dms filename extension that defines a data transformation job.
A DMS file has two or more different sections, which have different coding rules and use different
technologies. For example, the InputDataSource section uses property definition and SQL syntax,
whereas the Metadata section is written in mrScriptMetadata, and the Event sections are written in
mrScriptBasic. You can run DMS files in IBM® SPSS® Data Collection Base Professional or
using the DMS Runner, which is available only if you have Base Professional installed.
On the other hand, .mrs files are simple mrScriptBasic files and you can run them directly using
the , which is installed with IBM® SPSS® Data Collection Data Model 2.5 and later. This means
that you do not need Base Professional to be able to run an .mrs file. However, if you do have
Base Professional, you can run your .mrs files in Base Professional.
However, the situation is not quite as clear cut as it might seem, because the code in any Event
sections in your DMS files is always written in mrScriptBasic. This means that you can sometimes
just copy code from an .mrs file straight into the Event section of a DMS file or even use the .mrs
file as an Incude file within an Event section. However, you always need to check that the code is
appropriate for the particular Event section, that variable names don’t clash, etc.
1568
Chapter 1
For example, the IBM® SPSS® Data Collection Developer Library comes with a sample .mrs
file (called ExportToQuancept.mrs) that generates a IBM® SPSS® Quancept™ script from an
MDM Document. You could use this file as an Include file in the OnAfterJobEnd Event section of
a DMS file. Here is an example of doing this:
Event(OnAfterJobEnd, Generate QC Script from output metadata)
Dim MDM
' Create the MDM Document object and open the output metadata file
MDM.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\Simple.mdd")
#Include "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\General\mrScriptBasic\ExportToQuancept.mrs"
End Event
This example has been designed for use with the Simple.dms sample file. If you used it in any
other DMS file, you would need to change the name and location of the .mdd file.
Conversely, you can sometimes copy the mrScriptBasic code from an Event section into an .mrs
file and run it as a stand-alone .mrs file using Base Professional or the mrScript Command Line
Runner. This is particularly likely to be true of the code in the OnBeforeJobStart section because
all of the objects used in this section are created using the CreateObject function, just as you
would create them in an .mrs file. However, the mrScriptBasic code in the other Event sections
often refers to objects that Base Professional automatically registers with the mrScript engine.
This code is therefore unlikely to be suitable for running as a stand-alone .mrs file.
Q. The sample DMS files show two main ways of connecting to the case data—using the
InputDataSource and OutputDataSource sections and using ADO in the Event sections. Why are these
two different methods used and which is recommended?
A. You define the input and output data sources in the InputDataSource and OutputDataSource
sections of the DMS file. When you do this Base Professional handles all of the connections for
you and sets up the job and transfers the data as defined. This has the great advantage that in the
OnNextCase Event section you have scripting access to the case data. For example, for cleaning
and setting up case data for new variables, etc. In addition, Base Professional automatically
merges any new metadata defined in the Metadata Section.
However, sometimes it is useful to use ADO to access the case data in the Event sections, for
example to write out top line tables or crosstabulations in Excel. You would typically do this
after the job has completed, in the OnAfterJobEnd Event section. And this is how it is mainly
used in the samples.
Q. Why do I need Base Professional if I can access the case data using ADO in a mrScriptBasic
(.mrs) file or in Visual Basic?
A. It is true that you do not need Base Professional to use ADO to access the case data and
many of the things that you can achieve using a DMS file could be achieved by using ADO in
mrScriptBasic or Visual Basic. However, using a DMS file (which requires Base Professional)
1569
Base Professional
makes it easier by handling the connections, the merging of the metadata, and the transfer for you.
And through the Data Management Object Model (DMOM), the DMS file gives you scriptable
access to the case data. When you use ADO, you are restricted to using SQL syntax, which is
generally harder to set up and to read. In addition, the DMS file enables you to use the Weight
component, which means you can set up sophisticated market research weighting.
For an example of an .mrs file that uses ADO to export case data, see the
ExportCaseDataToQuantum.mrs sample file.
Queries About Running DMS Files
Q. How can I check my DMS file without running it?
A. Use DMS Runner with the /norun option. This will check that the syntax of the file is correct
without running it. A message will be displayed for each error that is found. However, there are
some errors that cannot be detected until you actually run the file.
Q. I am trying to run a DMS file that contains Japanese characters, but the Japanese characters
are not recognized. What can I do?
A. Make sure that you save your DMS file using the Unicode or UTF-8 text format option and not
the ANSI option. After you have done this, you should be able to run your file in the normal way.
Q. Is there any way of stopping DMS Runner part way through a DMS file?
A. You can stop the execution of a DMS file by pressing Ctrl-C. However, note that when you do
this, any output that has been generated is likely to be corrupt or unusable.
Q. When I run a DMS file that transfers data to IBM® SPSS® Quantum™, I always get two warnings,
but the transfer seems to run OK. Why is this?
A. When IBM® SPSS® Data Collection Base Professional validates the DMS file, it tests the
connection to the Quantum .dat file. Quantum DSC always gives a warning because the validation
is performed before the output metadata has been created and without a metadata source Quantum
DSC cannot function. This is because Quantum DSC relies on the card, column, and punch
definitions in the metadata. You can safely ignore these warnings.
Q. Is there a scheduling option in Base Professional that let’s you run a DMS file at a certain date
and time?
A. Base Professional does not have a specific feature for doing this. However, you can use the At
command or the Windows Scheduled Task wizard to schedule the execution of DMS files. For
more information, see the topic Scheduling the Running of DMS Files on p. 294.
FAQs About How To Set Up Specific Jobs
Q. Can you include code in a DMS file to generate topline reports from data in a relational MR
database?
1570
Chapter 1
A. The answer is yes, and the IBM® SPSS® Data Collection Developer Library comes with a
number of samples that show you how to do this. If you have the IBM® SPSS® Data Collection
Base Professional Tables Option, you may want to look at the table scripting samples, which use
the Tables Object Model (TOM) to script topline tables. For more information, see the topic Table
There are also a number of samples that you can use if you do not have IBM SPSS Data Collection
Survey Reporter Professional. For example, the MSWordToplines.dms sample is an Include file
that contains an OnAfterJobEnd Event section that sets up in Word topline summaries for all
of the simple categorical questions in the data source. By adding the following to the second
example in the Transferring Data From IBM SPSS Quanvert topic (the QuanvertToRDB example),
you could use this Include file to create topline summaries from the output data that is stored in
a relational MR database:
#define MYMDDFILE "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output\QuanvertToRDB.mdd"

#define OUTPUTFOLDER "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Output"
#define MYPROJECT "Museum"
#Include ".\Include\MSWordToplines.dms"
Alternatively, you could run the MSWordAndIEToplinesRDB.mrs sample .mrs file after running
your DMS file.
Q. Does Base Professional have an easy way of setting up a IBM® SPSS® Quantum™ specification?
A. The new MDSC capability of Quantum DSC means that it is now easy to include code in
your DMS file to write out a basic Quantum specification to match the card, column, and punch
definitions in the metadata. For more information, see the topic Creating the IBM SPSS Quantum
Specification on p. 368.
Q. I want to combine data from various sources (such as IBM® SPSS® Quanvert™, IBM® SPSS®
Quancept™, and XML) into one relational MR database. Is this possible and how should I go about it?
A. You can do this by using a DMS script to merge the data sources. For more information,
see the topic Merging Case Data on p. 373.
Q. Is it possible to string two DMS files together—for example, so that the output of the first is used
as the input for the second?
A. One easy way of doing this is to make an MS-DOS batch file to run the jobs one after the other.
For example, to create a batch file to run the Simple.dms and MDM2Quantum.dms sample files:
E Use a text editor to create a new text file containing the following:
Call DMSRun Simple.dms

Call DMSRun MDM2Quantum.dms
E Save the text file in the same location as your DMS files with a name of the form MyBatchFile.bat.
E Double-click MyBatchFile.bat in Windows Explorer.

1571
Base Professional
This opens a command prompt and runs the DMS files in sequence. Note that if you create the
batch file in another location, you will need to change to the location of the DMS file or specify
the location of the DMS file in the batch file, for example:
Call DMSRun "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\DDL\Scripts\Data Management\DMS\Simple.dms"
Note: The Data Collection Developer Library comes with a number of sample batch files. For
more information, see the topic Sample Batch Files on p. 481.
Q. Is it possible to export data from Access or Excel to Quantum? If so, how do I go about doing this?
The DDL includes two sample data management scripts called MSAccessToQuantum.dms and
MSExcelToQuantum.dms that demonstrate how to do this.
For more information about these scripts, see Sample DMS Files That Integrate with Microsoft
Office.
FAQs About File Locations
Q. When specifying a relative path in a DMS file, to what location should the path be relative?
A. When you run or debug a script in IBM® SPSS® Data Collection Base Professional, DMS
Runner, or WinDMSRun, the current location is set to the location of the DMS file. This means
that generally any relative paths should be specified relative to the location of the DMS file.
However, when you specify the path to an include file, it must always be specified relative to the
folder in which the file that contains the Include statement is located.
Q. What happens to the log file if I do not specify a log file location in the Logging section?
A. If your DMS file contains a Logging section, but it does not specify the location for the log file,
Base Professional creates the log file in your default temporary folder. If you do not know where
this is, you can find out by opening a command prompt and typing cd %temp%. This displays
the location of the temporary folder. If you then browse to this folder in Windows Explorer, you
should be able to see the log files. The log files have a .tmp filename extension. If you sort the
files on the Modified column, the files will be listed in date and time order. If you have just run the
DMS file, the log file will typically be one of the most recent ones.
Q. In IBM® SPSS® Data Collection Interviewer Server, the Metadata Document (.mdd) file exists in
several locations. Which one should I use when I want to export my Interviewer Server data?
A. Generally you should use the .mdd file that is in the FMRoot\Shared folder when transferring
case data. For more information, see the topic Working with IBM SPSS Data Collection
1572
Chapter 1
If you are exporting the data to IBM® SPSS® Quantum™, you can set up card, column, and
punch definitions in the .mdd file in either the mrInterviewSource folder or the FMRoot\Shared
folder. However, it is important that you always set them up in the same one, or card, column, and
punch definitions may inadvertently get overwritten during activation.
SQL Syntax FAQs
Note: The SQL syntax that is supported varies according to the OLE DB Provider that you are
using. This topic applies to the IBM SPSS Data Collection OLE DB Provider (which is part of the
IBM® SPSS® Data Collection Data Model) only.
Q. Is it possible to use multiple SQL statements in an update query in the InputDataSource and
OutputDataSource sections?
A. The IBM® SPSS® Data Collection Developer Library - November 2002 said that this was
possible. However, it is not currently possible to use more than one SQL statement in an update
query when you are accessing the case data through the Data Model.
If you are using another OLE DB provider to access data in another format, you may be able to
use multiple SQL statements in an update query if this supported by the OLE DB provider you
are using.
Q. I am getting unexpected results when I use non-US English formatting of date, time, and numeric
values.
A. Different formatting conventions are used in different countries for dates and times and for
the decimal and thousands separators used in numeric data. The Data Model uses the locale
setting to parse and format date, time, and numeric data. This handling is generally invisible.
For example, when your locale is set to Danish, the Data Model will accept and format data
using the Danish formatting customs and when your locale is set to US English, it will accept
and format data according to the US English formatting customs. (You select the locale using
Regional Options in the Windows Control Panel.)
However, this handling does not apply to literals in SQL queries and mrScriptBasic. A literal is
a string of characters that represents a value. Literals are often used in scripts and SQL queries
when you want to compare values. For example, the following SQL query uses a literal to select
respondents whose income is above a specified value:
SELECT Respondent.Serial, Income FROM vdata WHERE Income > 10000.00
You must always specify literals using US English formatting otherwise you will get errors or
unexpected results. For example, if you specify the literal in the above query using Danish
formatting (10000,00), you will get a syntax error. However, you can use the to convert
locale-specific date, time, and numeric values. For example, you could use the following query
when you are working in a Danish locale:
SELECT Respondent.Serial, Income FROM vdata WHERE Income > CDouble(10000,00)

1573
Base Professional
Q. When I am using IBM® SPSS® Data Collection Base Professional to transfer data from a .sav file,
why are the category value IDs that I need to specify in the WHERE clause different from the value IDs
used in the .sav file? For example, in my .sav file, the gender variable is defined like this:
Name: gender
Type: numeric
Width: 10
Decimals: 0
Label: Gender
Values: 1 = "Male"
2 = "Female"
Missing: None
Columns: 8
Align: Right
Measure: Scale
However, when I want to specify one of the categories in the WHERE clause, I need to specify IDs
of 13 and 14. For example:
SELECT * FROM vdata WHERE gender = 13
Why is this?
A. The Data Model gives a unique value to each category in the MDM Document. This is known
as the MDM mapped category value. When you read a .sav file in a DMS file, you are reading it
through the Data Model. This means that you are using the select query through the Data Model
and it is looking at these mapped values. However, you can also specify the category in the
WHERE clause using the category names, which you may find easier to use. The Data Model
bases the category names on the value labels in the .sav file. For example:
SELECT * FROM vdata WHERE gender = {Male}
The advantage of this is that you specify the queries in the same way regardless of the underlying
format of the data. For example, the above query would be equally valid when reading data stored
in a IBM® SPSS® Quanvert™ or relational MR database through the Data Model.
For more detailed information about how the Data Model interprets the data in the .sav file, see the
SPSS Statistics SAV DSC documentation in the section of the Data Collection Developer Library.
Metadata Section FAQs
Q. When I create a derived single response variable using an expression, is it necessary to specify the
range as [1..1] in the definition of the variable?
A. When you create a derived variable using an expression, the case data for the variable is defined
by the expression(s) you define and specifying the range will not affect the variable’s case data.
However, if you do not specify the range, the variable will be defined in the output metadata as a
multiple response variable. Therefore, you should normally specify the range for the variable, so
that it is defined correctly in the output metadata.
1574
Chapter 1
Q. What format should I use for the dates in a range expression for a date variable?
A. If you enter the month as a number, you should use one of the following formats:
United States English date formatting (in which the month is specified before the day). For
example, in this format 07-12-05 represents 12th July 2005.
The international standard YYYY-MM-DD format, where YYYY is the year, MM is the month
between 01 (January) and 12 (December), and DD is the day (between 1 and 31). For
example, in this format 2005-07-12 represents 12th July 2005.
Event Section Problems
Q. When I use the For Each...Next syntax with the Questions collection, I get an execute error: “Method
call failed: Does not support a collection”. Why is this and what is the solution?
A. You will get this error when the script encounters a complex question like a loop or a block,
which is represented by DMOM as a nested Questions collection. mrScriptBasic attempts to
expand the default and fails. Therefore you should always test for the question type on the first
line of the For Each...Next loop. For example:
Dim objQuestion, NestedQuestion
For Each objQuestion in dmgrQuestions
If objQuestion.QuestionType <> QuestionTypes.qtSimple Then
For Each NestedQuestion in objQuestion
.
.
Next
End If
Next
For a cleaning example that illustrates this, see 6. Advanced Cleaning Example.
Q. My cleaning script fails with an “Undefined variable” error that then names a variable that is
definitely in the data being transferred. Why is this?
A. Check that you included the variable in the SelectQuery statement in the InputDataSource
section. Only variables that are explicitly named in the SelectQuery statement are available as
Question objects to mrScriptBasic in the OnJobStart, OnNextCase, and OnJobEnd Event sections.
Remember that if you are creating new variables in the Metadata section, you need to include
them in the SelectQuery statement too.
However, if your InputDataSource section does not contain a SelectQuery statement or uses a
“SELECT * FROM vdata” query, all of the variables in the InputDataSource and Metadata section
are automatically included.
Q. How can I access the name or full name of a variable in my cleaning script? For example, if I want
to write the name or full name to a report file?
A. You can access the variable’s name and full name using the QuestionName and
QuestionFullName properties of the Question object.
1575
Base Professional
Q. Is there any way of getting the category name that corresponds to the response(s) stored in the
case data in a categorical variable?
A. You can get the category name for a response to a categorical question from the Category.Name
property. You can get the Category object from the Question.Categories collection. If the question
response contains a single value, you can use it as the index into the collection. For an example,
see the MSExcelDataViewer.dms sample. For more information, see the topic Sample DMS Files
That Integrate with Microsoft Office on p. 475.
If the question response contains more than one value, you can use each value as an index into the
collection. For an example of iterating through the values in a multiple response variable, see the
CreateDRS.dms sample. For more information, see the topic Sample DMS Files on p. 467.
Q. I am trying to use the question response value as an index into the Question.Categories collection,
but I get an “Object required when accessing <Property Name>” error. What could be causing this?
A. One common reason for this is that there is a NULL value in the case data. Try using “Is Not
Null” to filter out the NULL values. For an example of doing this, see the MSExcelDataViewer.dms
sample. For more information, see the topic Sample DMS Files That Integrate with Microsoft
Office on p. 475.
Another reason for this error is that the response in the case data does not correspond to a category
in the metadata. Typically this happens when the category has been deleted in the current
version of the metadata and the case data was collected using an earlier version in which the
category was present. You can avoid this problem by selecting all versions of the metadata in the
InputDataSource section. For an example of doing this, see the the CreateDRS.dms sample. For
more information, see the topic Sample DMS Files on p. 467.
Q. How can I script my DMS file to stop? For example, when I encounter an error that makes me
want to stop the run altogether.
A. You can stop the job by raising an error and not trapping it. For example:
On Error Goto 0
Err.Raise(1, , "Job stopped")
Q. Some of the samples use “Is Not NULL”, rather than “<> NULL” to test for a Null value. Why is this?
A. You are likely to get incorrect results when you use “<> NULL” to test for a NULL value in
mrScriptBasic. This is because the comparison operations treat NULL values as empty or zero
values, depending on the data type. This does not happen when you use “Is Not NULL”.
Q. When I use the DefinedCategories function with a DMOM Question object in the OnNextCase
Event section, the DMS file fails with “An error occurred calling the function ‘DefinedCategories’:
No variable ID given”. Why is this?
1576
Chapter 1
A. Unfortunately there is a problem (mrBug00012862), which means that you cannot use the
function with the DMOM Question object in IBM® SPSS® Data Collection Base Professional
2.1. However, you can get a list of a Question object’s categories using the Question.Categories
property.
Q. I am having problems getting my DMS file to run. It is using the IBM® SPSS® Data Collection
Metadata Model to Quantum object and is failing on the line highlighted below. What is going wrong?
Event(OnBeforeJobStart, Set up the card, column, and punch definitions)

Dim M2Q, MDM, HasPunchDSC, i '1
Set MDM = CreateObject("MDM.Document") '2
MDM.Open("C:\MDD files\test.mdd") '3
' Check whether a Quantum DSC DataSource object already exists '5
HasPunchDSC = False '6
If MDM.DataSources.Count > 0 Then '7
For i = 0 To MDM.DataSources.Count - 1 '8
If MDM.DataSources.Item[i].CDSCName = "mrPunchDsc" Then '9
Set MDM.DataSources.Current = MDM.DataSources.Item[i] ' 10
HasPunchDSC = True
Exit For
Else
HasPunchDSC = False
End If
Next
End If
If HasPunchDSC = False Then

Set MDM.DataSources.Current = MDM.DataSources.AddNew("mrPunchDsc", "mrPunchDsc", "C:\DAT files\test.dat")
End If
...
A. This is probably an issue with case-sensitivity. The comparison on line 9 is case-sensitive,

which means that if there is a DataSource object named “mrPunchDSC”, the comparison will fail.
To solve this problem, change line 9 to the following (the changes are highlighted):
If LCase(MDM.DataSources.Item[i].CDSCName) = "mrpunchdsc" Then
For more on mrScriptBasic troubleshooting, see .
Problems Using Global Variables
Q. In the GlobalSQLVariables section, is it possible to define a multiple-row, multiple-column record

set as a GlobalSQLVariable?
A. You can define as a GlobalSQLVariable only a simple column or an expression based on one
or more columns, such as:
SelectQuery = SELECT 2 * Q1 * Q2 As @MyGlobalSQLVariable FROM VDATA

1577
Base Professional
Q. I have added an array variable to the global variables collection? However, it doesn’t work as I
expected. Why is this? Here is the code where I set up the global variable:
Event(OnJobStart, Do the set up)

Dim i, Switch[]
For i = 0 To 16
Switch[i] = 1
Next
dmgrGlobal.Add("Switch")
Set dmgrGlobal.Switch = Switch
End Event
A. Adding an array variable to the GlobalVariables collection is not recommended because

mrScriptBasic considers a variable to be a categorical when it contains an array but was not
defined as an array. For example:
Dim x, y[], z
y[0] = 1
y[1] = 2
x=y
' At this point y is an array and x is seen as a categorical

' The following is possible
z = y[0] ' OK
z = x[0] ' OK
' The following is not possible: setting a categorical element

X[0] = 1 ' Error
Q. I am using the following subroutine in my cleaning script to write to a text file set up as a global
variable. But the script fails with the error “Reference type ‘dmgrJob’ is not an enum. Only enum types
can be referenced”. Is it not possible to access a global variable in a subroutine?
EmptyCheck(age)
Sub EmptyCheck(vname)
If vname.AnswerCount() < 1 Then
dmgrJob.GlobalVariables.mytextfile.WriteLine(strDetails + ": " + vname + " has no answer")
End If
End Sub
A. The variable scope rules in mrScriptBasic differ from Visual Basic. Variables that are available
in the main script block are not visible in a Function or Sub procedure. This is to make it easier
to share functions and subroutines between scripts. Therefore you need to amend your code
as follows:
EmptyCheck(age, strDetails, dmgrJob.GlobalVariables.mytextfile)
Sub EmptyCheck(vname, strDetails, ReportFile)

If vname.AnswerCount() < 1 Then
1578
Chapter 1
ReportFile.WriteLine(strDetails + ": " + vname + " has no answer")

End If
End Sub
Q. When I attempt to run the following code, I get an error (“The ‘WordApp’ object does not support
the ‘Visible’ member”). What am I doing wrong?
Event(OnJobStart, Open up Word)

Dim WordApp, WordDoc
Set WordApp = CreateObject("Word.Application")
dmgrJob.GlobalVariables.Add("WordApplication", WordApp)
End Event
Event(OnJobEnd, Write cases to Word doc for Mail Merge Table and conduct the mail merge)
dmgrJob.GlobalVariables.WordApp.Visible = True
End Event
A. The call to the GlobalVariables.Add method is causing the default property on the
Word.Application object to be expanded. This means that the following lines are the same:
Job.GlobalVariables.Add("WordApplication", WordApp)
Job.GlobalVariables.Add("WordApplication", WordApp.Name) ' Name is the default property
The solution is to assign the object to the global variable after adding it to the GlobalVariables
collection, like this (the changes are highlighted):
Event(OnJobStart, Open up Word)

Dim WordApp, WordDoc
Set WordApp = CreateObject("Word.Application")
dmgrJob.GlobalVariables.Add("WordApplication")
Set dmgrJob.GlobalVariables.WordApplication = WordApp
End Event
Questions About the DMOM Object Model
Q. I am confused about the Value and ValueObj properties on the Response object. Can you explain
what is the difference between them and what they should be used for?
A. The Value property returns the value contained in the ValueObj. For example, Response.Value
is the same as Response.ValueObj.Value.
The Response.Value property is provided as shorthand, so that the default property of the
Response object is the value. The Response.ValueObj property is provided so that it is possible to
replace the entire value object for the Response object.
Q. I am confused about why the Question.Response property is read-only, because the examples show
setting this property programmatically in the OnNextCase Event section.
1579
Base Professional
A. It is true that the Question.Response property is read-only. However, if your OnNextCase Event
section uses code similar to the following, you are in fact assigning a value to the default property
of the Response object, which is Response.Value.
MyQuestion.Response = {Dont_know}
Q. Can I use a numeric index when accessing the OutputDataSources.Item on the Job object, and if
so, is it zero-based?
A. The answer to both of these questions is yes.
Q. What is the difference between the LogScript and LogScript_2 methods on the Log object?
A. These methods are identical except that the LogScript method has an additional ID parameter.
Q. Does the DMOM Object Model support HDATA?
A. Yes, as of the 5.6 release.
Problems Using Other OLE DB Providers
Q. I am trying to export data from an Access database using the Microsoft Jet 4.0 OLE DB Provider
and I get the following error even though I have specified in the select query the name of the table
in the Access database. What is going wrong?
Error : Failed to create target table: Output - Unknown table 'VDATA'
A. This error occurs when any of the database columns included in the export have names that
are not valid in the IBM® SPSS® Data Collection Data Model—for example, if a column
name has a space in it (such as Tree Type). When this happens you need to redefine it using the
AS keyword. For example:
SelectQuery = SELECT [Tree ID] As TreeID, [Tree Type] As TreeType FROM Trees
Note that you cannot use the AS keyword when you are transferring the data to a .sav file. For
more information, see the topic FAQs About How To Set Up Specific Jobs on p. 1569.
Q. I am attempting to run a transfer using a non-Data Model OLE DB provider to read the data, but my
script fails with an “Object reference not set to an instance of an object” error. Why is this?
A. This error occurs if your DMS file contains an OnAfterMetaDataTransformation, OnJobStart,

OnNextCase, or OnJobEnd Event section. These sections are not available when you are using a
non-Data Model OLE DB provider. If your DMS file contains any of these sections, you will need
to remove them and then try running the script again.
Weighting FAQs
Q. Is the Weight component subject to the same limits as IBM® SPSS® Quantum™ (for example,
in the number of variables you can use, etc.)?
1580
Chapter 1
A. The Weight component has no built-in limits.
Q. My weighting routine fails with the following error:
Execute Error(9): Cannot move to first record.
A. This error typically occurs when you attempt to use the Weight component with an unsuitable
data format. The Weight component is designed for use with the Data Model and a CDSC that
is write-enabled (Can Add is True for the CDSC) and supports changing the data in existing
records (Can Update is True for the CDSC).
Q. I am trying to get the PreWeightVar property to work, but I keep getting an “IWeight does not
support this property” error. Why is this?
A. In the IBM® SPSS® Data Collection Developer Library - November 2002, unfortunately the
General Weighting Options topic incorrectly said the preweight property was called PreWeightVar
instead of PreweightVariable. This error has now been corrected. Here is an example of setting
this property:
Dim WgtEng, Wgt

Wgt.PreWeightVariable = "visits"
.
.
.
Q. I have set up a weighting routine and the weighting is generated as I expected but the weighting
report contains only the following. Why is this?
<HTML><BODY BGCOLOR="#6699cc"></BODY></HTML>
A. The main weighting report is generated by the IWeightEngine.Execute method and additional
information (such as information about cases that do not belong in the weighting matrix) is
added by the IWeightEngine.Prepare method. Generally you should therefore write the report
to the text file twice, once after the call to WeightEngine.Prepare and once after the call to
WeightEngine.Execute. It sounds like you wrote the report to the text file after the call to
WeightEngine.Prepare but not after the call to WeightEngine.Execute. For more information, see
the topic Weighting Report on p. 412.
Some Common DMS File Errors
Q. My transfer to .sav fails with the following error:
Error : Failed to create target table: myOutputDataSource - Error creating target

schema myOutputDataSource - SAV Modification to the layout of data source 'MySavFile'
(a DDL operation) attempted at a point where this is not yet or no longer possible.
EXEC XP_SYNCDB
1581
Base Professional
A. This error usually occurs when you attempt to export data to an existing .sav file. How you
get around this error depends on what you are trying to achieve. If you want to export the data
to a new file, simply rename or delete the existing file or move it to another location before
running the transfer again.
However, if you want to export additional records to the existing file, you will only be able to
do this if:
You use the output metadata file from the previous export as the input metadata source for the
current export, and
The structure of the data exactly matches the data you exported previously.
If the structure of the data is unchanged and the output metadata file from the previous export is
available, the export should succeed if you change the DMS file accordingly and run the file again.
Q. When the InputDataSource section specifies an .mdd file that is created in the OnBeforeJobStart
Event section, you will get two validation errors. For example:
Error opening input data source: myInputDataSource

Failed to close the InputDataSource: myInputDataSource
A. This is because the validation takes place before the input metadata has been created. You can
safely ignore these errors.
Q. My DMS file is failing with an “Object reference not set to an instance of an object” error.
A. Check that you have specified a metadata source in the InputDataSource section. If
not, either because you are running a case data-only transfer or because you are using a
non-IBM® SPSS® Data Collection Data Model OLE DB provider, you will need to remove the
OnAfterMetaDataTransformation, OnJobStart, OnNextCase, and OnJobEnd Event sections.
These Event sections are available only when you have specified an input metadata source.
Q. My export from IBM® SPSS® Quanvert™ fails with the following error. Why is this?
Error : Metadata error, the specified input metadata could not be opened At line 3
Illegal xml character.
A. This problem can occur when the missing= keyword has been used in the IBM® SPSS®
Quantum™ specification that was used to set up the Quanvert database. This can lead to the illegal
Ctrl-A character appearing in the QVLabel custom property on the affected variable(s) in the
MDM Document. If you use the Quanvert MDSC to create an .mdd file in the OnBeforeJobStart
Event section, you can remove the illegal character using code similar to the following:
Dim MDMField, MDMGridField, CtrlA_Location
For Each MDMField In MDM.Fields
CtrlA_Location = Find(MDMField.Properties["QVLabel"], ChrW(1))
If CtrlA_Location > 0 Then
MDMField.Properties.Item["QVLabel"] = _
Left(MDMField.Properties["QVLabel"], CtrlA_Location-0)
End If
If MDMField.ObjectTypeValue = 2 Then
1582
Chapter 1
' MDMField is a grid

For Each MDMGridField in MDMField.Fields
CtrlA_Location = Find(MDMGridField.Properties["QVLabel"], ChrW(1))
If CtrlA_Location > 0 Then
MDMGridField.Properties.Item["QVLabel"] = _
Left(MDMGridField.Properties["QVLabel"], CtrlA_Location-0)
End If
Next
End If
Next
Note that the function is used to return the Ctrl-A character.
Some other common error messages and suggested solutions:
Error : Metadata error, the specified MetaDataOutputName could not be saved
Make sure that the location you specified for the output metadata file exists, is not read-only, and
that you have suitable permissions for it. IBM® SPSS® Data Collection Base Professional 2.1
does not create a new folder if the folder you specify does not exist. If necessary you must create
the folder yourself or specify a different folder that does exist.
Parser Error : Syntax error at '#' - unknown symbol
Check whether you have included one or more line-continuation characters in a #define or
#include statement. Line-continuation characters cannot be used in these statements.
Error extracting section body, section is empty
Check whether your DMS file includes one or more empty Metadata or Event sections, and
if necessary remove them.
Error : Miscellaneous Elan-related error
This error message originates from the Base Professional licensing system and occurs when you
attempt to run multiple instances of DMS Runner on separate CPUs on a dual-processor machine.
This is because of the single-user restriction that is built into the licensing. The solution is to run
the jobs one after the other or to use a single-processor machine.
Error : Rowset.Read - MoveFirst, Message: Either BOF or EOF is True,
or the current record has been deleted. Requested operation requires
a current record.
This rather confusing message indicates that no records passed the filter defined in the WHERE
clause in the select query in the InputDataSource section. For example, you would get this
message if the WHERE clause specifies records whose serial number is greater than 600 and the
highest serial number in the input data source is actually 599.
Error : Failed to create target table: Quantum - Error opening output datasource:
Quantum - DataSource Open Exception: MDM Document is Defect or Location is invalid
or Document property CardSize is missing
1583
Base Professional
This error occurs when you are exporting data to Quantum and typically means that no card,
column, and punch definitions have been set up in the metadata. If you are setting them up in the
DMS file, check the log or error message file generated by the Event section in which you set
them up for error messages.
An error occurred updating a row: RDB Update failed:

Timeout expired
- OR -
IDispatch error #3121
This error may occur when you have an update query in the InputDataSource section and you
are using RDB DSC 2 to connect to an RDB database or when you are transferring data to an
RDB database using RDB DSC 2. You can avoid this problem by using the Favor Memory
option. See the third example in Transferring Data From a Relational MR Database (RDB) for
more information.
The process cannot access the file because it is being used by another process
This error may occur when you have called the MDM Document.Open method in an Event
section and not called the Document.Close method to release it. You can avoid this problem by
calling Document.Close at the end of the Event section. For more information, see the topic
OnAfterMetaDataTransformation Event Section on p. 279.
Other errors
When you use the Data Model to read or write data, the DSCs that you are using will issue a
message when they encounter an error. Each DSC has specific requirements and therefore
the things that are likely to cause an error will vary according to which DSCs you are using.
Error messages that are issued by a DSC are prefixed by a code. However, sometimes the error
message generated by the DSC is preceded by a more general message that is generated by Base
Professional or the IBM SPSS Data Collection OLE DB Provider. For example, scroll up to
the top of this topic, and look at the first error message that is shown. Notice that the second
part of the error message is prefixed by “SAV”. This means that it has been generated by SPSS
Statistics SAV DSC.
The Transferring Data Using a DMS File section provides general information and tips on using
the DSCs provided with Data Model and links to relevant topics in the section.
WinDMSRun FAQs
Q. Help! I opened my DMS file in WinDMSRun and now some of my comments have disappeared.
A. Each time you open or save a file or switch between the tabs in WinDMSRun, WinDMSRun
regenerates the code. This involves removing some comments as well as expanding any #Include
and #Define statements. However, comments that are within the Event and Metadata sections will
be retained. You may therefore want to take a backup of your DMS files before opening them in
WinDMSRun. Alternatively, you can save your DMS file with a different name in WinDMSRun.
For more information, see the topic WinDMSRun on p. 300.
1584
Chapter 1
Q. When I click the Refresh button on the Input Data tab, I get the following error:
Unable to prepare the 'SELECT' command. Type mismatch error

converting '@<MyVariable>' from Text to ...
A. WinDMSRun displays this error when your DMS file contains a GlobalSQLVariables section.
WinDMSRun cannot display the case data on the Input Data tab when the DMS file contains a
GlobalSQLVariables section.
Writing to the console.
WinDMSRun will give an error if you attempt to run a DMS file that contains mrScriptBasic code
that writes to the console. For example, suppose you run a DMS file that includes the following
OnJobStart Event section to write some text to the console:
Event(OnJobStart, Write something to the console)
Dim fso, console
set fso = createobject("scripting.filesystemobject")
set console = fso.createtextfile("con")
console.Writeline("Some text")
End Event
WinDMSRun will display the following error:

Event(OnJobStart, Write something to the console) mrScriptEngine execution
error: Execute Error(3) Method call failed. Unknown error.
Programmer’s FAQs
Q. Does the fact that WinDMSRun was developed in Visual Basic .NET mean that you cannot use the
Data Management Object Model in Visual Basic?
A. The Data Management Object Model (DMOM) is a .NET assembly. However, all of the
objects within it are exposed as COM objects and can therefore be accessed from Visual Basic in
the normal way.
To show you how easy it is, here is some Visual Basic code that runs a DMS file:
Dim j As New Job
j.Load ("C:\Samples\MyFirstTransfer.dms")
j.Run
Here is another Visual Basic example that sets up a DMS file and runs it:
Dim job As New SPSSMR_Data_Transformations.job
' Set up and add input data source

Dim dsin As New SPSSMR_Data_Datasource.DataSource
dsin.Name = "Input"
dsin.SetConnectionString ( _
"Provider=mrOleDB.Provider.2 ; " + _
1585
Base Professional
"Data Source=mrDataFileDsc ;" + _

"Location=museum.ddf;" + _
"Initial Catalog=museum.mdd;")
dsin.QueryString = "SELECT * FROM VDATA"
job.InputDataSources.Add dsin
' Set up and add output data source

Dim dsout As New DataSource
dsout.Name = "Output"
dsout.SetConnectionString ( _
"Location=VBTest.ddf;")
dsout.MetaDataOutputName = "VBTest.mdd"
job.OutputDataSources.Add dsout
' Run the job

job.Run
job.Save ("VBTest.dms")
Before you can run this code in Visual Basic, you need to add SPSS MR Data Manager Object
Model for Transformations and SPSS MR Data Source to the Visual Basic project references.
Here is some roughly equivalent Visual Basic .NET code:
Imports SPSSMR.Data
Imports SPSSMR.Data.Transformations
Module Module1
Private Sub OnNextCaseEventHandler(ByVal sender As System.Object, ByVal e As System.EventArgs)
Console.WriteLine("Next case !")
End Sub
Sub Main()
Dim job As New Job()
' Set up and add input data source

Dim dsin As New DataSource()
dsin.Name = "Input"
dsin.SetConnectionString ( _
"Location=museum.ddf ;" + _
"Initial Catalog=museum.mdd ;")
dsin.QueryString = "SELECT * FROM VDATA"
job.InputDataSources.Add(dsin)
' Set up and add output data source

Dim dsout As New DataSource()
dsout.Name = "Output"
dsout.SetConnectionString ( _
1586
Chapter 1

"Location=MuseumOut.ddf ;")
dsout.MetaDataOutputName = "MuseumOut.mdd"
job.OutputDataSources.Add(dsout)
' Add event handler for NextCase

AddHandler job.NextCase, AddressOf OnNextCaseEventHandler
' Run the job

job.Run()
End Sub
End Module
Q. Is there any way of executing a DMS file from within an ASP.NET page? For example, I want to
create a Web page where you can select the IBM® SPSS® Data Collection Interviewer Server
project and an output format (such as IBM® SPSS® Quantum™ or IBM® SPSS® Statistics) and then
the page generates and executes a DMS file.
A. DMS Runner is a very thin client on top of the Data Management Object Model (DMOM),
which contains all of the data management functionality. The most elegant way to program
against DMOM is through managed code in Visual Studio .NET (C# or Visual Basic .NET). So
ASP.NET is perfect.
The IBM® SPSS® Data Collection Developer Library comes with the Visual Basic .NET source
code of the WinDMSRun sample application. If you look at this code, you will see an example of
programming using DMOM. For more information, see the topic WinDMSRun as Programmer’s
Reference on p. 309.
Q. How do you destroy the Job object in Visual Basic? The Job.Close method appears to close the job
without destroying the Visual Basic Variable.
A. You can destroy the Job object in the same way as you can destroy any COM variable in
Visual Basic using the following code:
Set MyJob = Nothing
This will decrease the reference count on the COM object and thus destroy the object if it is
the only reference left.
Q. Is there a method for removing the input data sources? I am working in Visual Basic and have
created a subroutine that populates the input and output data sources. However, if I change the input
or output data sources and call it again, I get an error saying that that I already have these in the job. I
get this error even if I call the DataSource.Close method.
A. In IBM® SPSS® Data Collection Base Professional 2.0 and later, DMOM has a
DataSources.Remove method, which you can use to remove the input data source.
Previously, you had to set the Job object to Nothing before calling the subroutine again or find
another solution. For example, WinDMSRun copies a “design” Job object into a “Run” Job object
and then runs that and destroys it. The relevant code is in ProgressForm.vb. If you do not have
1587
Base Professional
Visual Basic .NET, you can examine the code in a text editor. Although the Visual Basic .NET
syntax is different from Visual Basic, you should be able to follow the logic.
Q. When programming with DMOM, I consistently get a threading error (Wrong Apartment Model)
when attempting to create and execute a job. Why is this?
A. DMOM requires a single-threaded apartment (STA) threading model. In an ASP .NET

environment you can use the following code to run the Web application in an STA thread pool:
<%@ Page ASPCompat="true" %>
Performance Problems
Q. I am attempting to carry out some extensive data cleaning in the OnNextCase event section of my
DMS script. Because of the large number of records and variables in the data source, the script takes
an excessive amount of time to complete. How can I improve the performance of my script?
A. If your script includes code that removes erroneous characters from text variables, make sure
that you do not repeatedly look up the Response object. The following example looks up the
Response object eight times for each variable and is therefore inefficient:
Sub CheckText(dmgrJob, Q)
' Remove all newline characters, parentheses, and
' hyphens from the response text...
Q.Response.Value = Replace(CText(Q.Response.Value), mr.NewLine, " ")
Q.Response.Value = Replace(CText(Q.Response.Value),"(","")
Q.Response.Value = Replace(CText(Q.Response.Value),")","")
Q.Response.Value = Replace(CText(Q.Response.Value),"-","")
End Sub
A better approach would be as shown in the following example. The Response object is now
looked up only once or twice for each variable:
Sub CheckText(dmgrJob, Q)
' Remove all newline characters, parentheses, and
' hyphens from the response text...
Dim strOriginal, strVal
strOriginal = CText(Q.Response.Value)
strVal = Replace(strOriginal, mr.NewLine, " ")

strVal = Replace(strVal, "(", "")
strVal = Replace(strVal, ")", "")
strVal = Replace(strVal, "-", "")
If strVal <> strOriginal Then

Q.Response.Value = strVal
End If
End Sub
1588
Chapter 1
It is also more efficient to check the responses to a categorical variable using an intersection
operator instead of the ContainsAny function. For example, the following code sets a Don’t Know
special response if no categories were selected:
If (Q.Response.Value Is Not NULL) And Not (Q.Response.Value.ContainsAny({High, Medium, Low, DontKnow})) Then
Q.Response.Value = {DontKnow}
End If
However, by rewriting the code to use an intersection operator (*), the number of look ups on the
Response object is reduced by one:
If Q.Response.Value * {High, Medium, Low, DontKnow} = {} Then

Q.Response.Value = {DontKnow}
End If
Null variables will be handled correctly, because when Q.Response.Value is Null, the intersection
will evaluate to Null, the comparison of Null with {} will be False, and a Don’t Know response
won’t be set.
Appendix
A
Notices
This information was developed for products and services offered worldwide.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently
available in your area. Any reference to an IBM product, program, or service is not intended to
state or imply that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual property right
may be used instead. However, it is the user’s responsibility to evaluate and verify the operation
of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents.
You can send license inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785,
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing, Legal and Intellectual Property Law, IBM Japan Ltd., 1623-14,
Shimotsuruma, Yamato-shi, Kanagawa 242-8502 Japan.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES
PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties
in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are
periodically made to the information herein; these changes will be incorporated in new editions
of the publication. IBM may make improvements and/or changes in the product(s) and/or the
program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and
do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites
are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate
without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including
this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Software Group, Attention: Licensing, 233 S. Wacker Dr., Chicago, IL 60606, USA.
Licensed Materials - Property of IBM © Copyright 1589

IBM Corporation 2000, 2011
1590
Appendix A
Such information may be available, subject to appropriate terms and conditions, including in
some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are
provided by IBM under terms of the IBM Customer Agreement, IBM International Program
License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore,
the results obtained in other operating environments may vary significantly. Some measurements
may have been made on development-level systems and there is no guarantee that these
measurements will be the same on generally available systems. Furthermore, some measurements
may have been estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products,
their published announcements or other publicly available sources. IBM has not tested those
products and cannot confirm the accuracy of performance, compatibility or any other claims
related to non-IBM products. Questions on the capabilities of non-IBM products should be
addressed to the suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or withdrawal
without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations.
To illustrate them as completely as possible, the examples include the names of individuals,
companies, brands, and products. All of these names are fictitious and any similarity to the names
and addresses used by an actual business enterprise is entirely coincidental.
If you are viewing this information softcopy, the photographs and color illustrations may not
appear.
Trademarks
IBM, the IBM logo, ibm.com, and SPSS are trademarks of IBM Corporation, registered in
many jurisdictions worldwide. A current list of IBM trademarks is available on the Web at
http://www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel
Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft
Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
1591
Notices
Other product and service names might be trademarks of IBM or other companies.
Index
’ syntax Activating projects, 988
table scripting, 1192 Activate command, 990
+ _ syntax Activate command examples, 991
table scripting, 1192 Activate Document, 989
< operator converting .ini files to .xml format, 991
table scripting, 1192 converting .ini files to Activate Documents, 989
testing categorical responses, 652 from command line, 989
= operator activation
testing categorical responses, 651 templates, 117
> operator Activation
table scripting, 1192 advanced settings, 187
testing categorical responses, 651 answering machine detection settings, 181
^ operator appointments settings, 172
table scripting, 1192 autodialer settings, 177
<= operator call outcome settings, 156
testing categorical responses, 652 call times settings, 170
>= operator calling rules settings, 163
testing categorical responses, 651 changing just the project’s status, 194
() syntax Data Entry settings, 129
table scripting, 1192 database settings, 133
[] syntax deployment settings, 129
table scripting, 1192 dialing settings, 177
{} syntax disconnected settings, 126
table scripting, 1192 display fields settings, 128, 154
”...” syntax e-mail settings, 137
table scripting, 1192 fields settings, 134
’!...!’ syntax files settings, 191
table scripting, 1192 from IBM SPSS Data Collection Base Professional, 87,
”!...!” syntax 988
table scripting, 1192 interviewer settings, 159
interviewing settings, 153
introduction settings, 158
Access mapping sample record fields, 995
DMS files that integrate with, 475 no network access to FMRoot, 203
exporting data to, 352 ordering settings, 168
importing data from, 328 others settings, 194
Accessibility, 1560 overrides settings, 175
blind users, 1561 page template settings, 188
JAWS, 1561–1562 parameters settings, 163
keyboard navigation, 1561 participants settings, 131
screen reader, 1561–1562 predictive settings, 179
special considerations, 1561–1562 Project Interview settings, 124
visually impaired users, 1561 project roles settings, 125
Actions after asking questions, 922 Project settings, 121
Actions before asking questions, 921 Quota settings, 186
Actions before response validation, 922 registry settings, 203
Actions for end of interview, 921 review settings, 162
Actions for start of interview, 920 routing settings, 127
Actions on abnormal end of interview, 923 script settings, 136
Activate specifying authentication page, 1039
authentication page, 1039 tasks settings, 193
live questionnaire, 113 telephone settings, 152
questionnaire, 113 upload settings, 131
test questionnaire, 113 using .sam scripts for IBM SPSS Data Collection
Activating an interview projects, 203
in IBM SPSS Data Collection Base Professional, 87 using File Management component, 203
1592
1593
Index
Activation History tab, 196 At command

Active, sample record field, 995 using to schedule DMS files, 295
ActiveVersion, 1089 Audio files
AddSampleRec function, 1071 playing in interviews, 810
AddSampleRec method, 1071 AuthenticatePage, 1089
ADO DSC AuthenticateSampleRec function, 1072
and DMS files, 328 when it is called, 1038
Advanced menu, 21 AuthenticateSampleRec method, 1072
Advanced settings, 187 AuthenticateType, 1089
AllowThousandsSeparator, 548, 551 Authentication
in multiple-language scripts, 885–886 function, 1072
Alphabetic sorting of responses, 568 number of retries, 1038, 1043
Alternate grid rows/columns, formatting, 870 overview, 1037
Analysis context page, 1039, 1041–1042
adding texts to in IBM SPSS Data Collection Base when it is called, 1038
Professional, 56 Authentication fields
Analysis elements overview, 995
comparison with axis block method, 945 Authentication-failed page, 1043
Analysis-only elements AuthFailedPage, 1090
in interview scripts, 958 AuthFailedType, 1090
Analyzing a tracking study, 442 AuthRetryPage, 1090
Annotations AuthRetryType, 1090
changing annotations used in Word table of contents, Auto Answer, 66–67, 984
1525 in IBM SPSS Data Collection Base Professional, 61
exports to Excel, 1499 Auto Answer dialog box, 66–67
exports to Microsoft PowerPoint, 1509 Auto-authentication, 1038
exports to Microsoft Word, 1523 AutoAnswer, 66–67, 1091
macros for, 1434 Autobase, 1230
overview, 1432 Autocoding
positions, 1432, 1436, 1439 adding to axis specification, 1214
suppressing from Excel export, 1501 AutoDial, 1091
suppressing from HTML export, 1481 autodialer settings, 177
suppressing from Microsoft Word export, 1518 AutoDialTimeout, 1091
valid HTML tags, 1440, 1442 Autoexpansion macros, 25
AnswerCount, 650 Automatic-coding tools
data cleaning examples, 390 analyzing a tracking study, 442
Answering interview questions, 984 AutoSelectOther, 1091
answering machine detection settings, 181 AutoUpdateDataModel, 1091
AnswerMachineDelay, 1024 Axes
Answers foreign language labels, 1467
actions before validating, 922 labels in tables, 1463
color and font settings, 768 reusing, 454, 1164
summarizing at end of interview, 715 specification syntax, 1197
AppointmentCode , 1089 Axis
AppointmentMarginAfter, 1024 adding special elements, 1204, 1230
AppointmentMarginBefore, 1024 defining the specification in mrScriptBasic, 1538
AppointmentPreferArranger, 1024 defining the specification in mrScriptMetadata, 456
Appointments element list syntax, 1200
return to arranger, 1024 setting element properties, 1222
appointments settings, 172 specification syntax, 1197
Asking questions, 558 storing the specification, 1536
ASP pages top2-bottom2, 963
authentication pages, 1039 Axis block
pre-authentication page, 1042 comparison with analysis element method, 945
Assignments Axis blocks
repeating for all objects in a collection, 668 defining, 944
“double dot” notation in, 946
1594
Index
referring to response categories in, 946 Calculation scope

special characters in, 947 defining in an axis specification, 1222
Axis expressions Call outcome codes, 1014
defining in MDM Explorer, 1537 internal communication between dialer and sample
defining in mrScriptBasic, 459, 1538 management, 1023
defining in mrScriptMetadata, 456 mapping dialer result codes to, 1021
introduction, 1172 call outcome settings, 156
overview, 1536 call times settings, 170
Axis syntax CallerID, 1092
element list syntax, 1200 calling rules settings, 163
overview, 1197 CancelCode, 1093
setting element properties, 1222 CannotCombine, 724
special elements, 1204 Cascading style sheets, 879–880
format and location of, 879
naming in page templates, 882
Band case data
creating in a DMS file, 434 adding a data source in IBM SPSS Data Collection Base
Banding Professional, 78
adding to axis specification, 1213, 1215 changing the data source in IBM SPSS Data Collection
Banners, 596 Base Professional, 78
adding to questions/pages, 597 creating in IBM SPSS Data Collection Base Professional,
creating in a DMS file, 440 78
creating with reusable axis, 1164 Case Data
in multiple-language scripts, 889 cleaning, 388–389
position on page, 837 filtering in data management scripting, 243
removing from questions/pages, 600 merging, 373
setting up in a data management script, 454 transferring, 310
text substitution in, 602–603 Case data filter
Base setting up, 243
adding to axis specification, 1204 Categorical items
excluding categories from the base in an axis presenting side by side, 639
specification, 1216, 1226 Categorical response lists
Base elements background color, 755
filtered, 463 color, 755
in interview scripts, 948 display methods, 756
in tables, 1230, 1233–1234, 1236 indenting, 763
Bases number of columns/rows, 760
diagnostics file, 1380–1382, 1384 orientation for categorical lists, 760
effect of population level, 1279 Categorical responses
effective, 1311, 1388–1389 selecting by clicking response texts, 855
grid tables, 1297 sorting, 567
Blocks Categorical responses in non-categorical lists, 764
error messages for questions in, 836 Categorical variables
Bookmarks creating from numeric variables, 434
using in IBM SPSS Data Collection Base Professional, Categories
18 adding to existing variables, 442
Boolean, 553 alphabetic sorting, 568
Boolean questions display in a random order, 570
cleaning special responses to, 400 display in rotation, 569
Boolean variables hiding in tables, 1153
creating in a DMS file, 437 naming, 545
Breakdowns reverse order for alternate interviews, 572
creating in a DMS file, 440 single-choice in multiple-choice list, 543
Browser, 1092 sorting using routing statements, 577
Built-in base elements CATI
in tables, 1233 sample scripts, 1054
BusyDelay, 1024 CATIPredefinedQueues, 1011
1595
Index
CDSCs example, 1338

connecting to, 68–69, 76 least significant difference value, 1338, 1342, 1347
Null, 256, 262 overview, 1337
Cell chi-square test requesting, 1314
details and restrictions, 1325 statistical formula, 1345
diagnostics information, 1379 Column proportions test, 1178
example, 1323 details and restrictions, 1333
overview, 1322 diagnostics information, 1380
statistical formula, 1326 example, 1328
Cell contents overview, 1328
defining in a script, 1149 requesting, 1314
effect of population level, 1279 statistical formula, 1335
examples, 1254 Combined categories
list of available items, 1247 adding to axis specification, 1204, 1212
rounding, 1253 CombineIterations function, 484
statistical formulae, 1268 Comment selection, 21
summary statistics of numeric variables, 1172 Comments
Cell target weighting Data Management Script (DMS) file, 247
See Target weighting, 409 disappearing, 1583
Cells Comments in interview scripts, 530
hiding, 1419, 1428–1429 Comparison operators
CellValues defining filters using, 1166
examples, 1265 Completed count
Change Tracker, 1469–1470, 1472, 1474 overview, 1045
ChangeTrackerFunctions.mrs, 1470 Completed-interview page, 1044
ChangeTrackerTest1_NewDocument.mrs, 1472 CompletedInterviewPage, 1093
ChangeTrackerTest2_OpenDocument.mrs, 1474 CompletedInterviewType, 1093
Charts Concatenated tables
choosing whether to include in Excel table export, 1501 introduction, 1156
choosing whether to include in HTML table export, 1481 overview, 1158
choosing whether to include in Microsoft Word table sorting, 1412
export, 1518 Conditional actions in interview scripts, 662
creating from tables in HTML, 1181 Configure Project Templates dialog, 24
creating in Microsoft PowerPoint, 1509 ConfirmHangupOutcomes, 1094
custom charts, 1508 Connection properties
using DMS files to set up in PowerPoint and Excel, 475 setting in Data Link Properties dialog box, 68
Chi-square test, 1178 ConnectionID, 1094
details and restrictions, 1320 Const statement
diagnostics information, 1378 table scripting, 1192
example, 1317 ContainsAll, 651
overview, 1316 ContainsAny, 652
requesting, 1314 ContainsSome, 654
statistical formula, 1321 Context, 1094
Citrix Context-sensitive help
external browser, 1562 using in IBM SPSS Data Collection Base Professional,
hot keys, 1562 42
keyboard shortcuts, 1562 Contexts
Clean mode selecting, 73
selecting, 76 working with in IBM SPSS Data Collection Base
selecting in a DMS file, 336 Professional, 56
Clickable images in interview scripts, 798 Continuation lines in response texts
ClusterList, 1093 lining up with first line of text, 881
Coding tools CopyGrid function, 485
analyzing a tracking study, 442 Counts
Column means test effect of population level, 1279
details and restrictions, 1343 Create
diagnostics information, 1381 project template, 23
1596
Index
CreateGridSummary function, 487 Data Management

Creating functions, 483
Mean Summary Tables, 1401 Data Management Object Model (DMOM)
prefix or suffix, 1400 FAQs, 1578, 1584
Summary Statistic Tables, 1401 using WinDMSRun as programmer’s reference, 309
Cross-site scripting Data Management Script (DMS) file
preventing in text responses, 728 about the documentation, 204
Crosstabulations adding metadata, 268
concatenated, 1156, 1158, 1412 analyzing a tracking study, 442
creating in a DMS file, 285 case data-only operation, 236
nested, 1156, 1158, 1412 coding conventions, 247
using the Table Object Model, 1144 comments, 247
CSS creating .mdd file from proprietary metadata, 314
use in HTML table export component, 1490, 1494 creating and running using WinDMSRun, 300
csv file creating new variables, 433
exporting tables to, 1534 creating tables, 285
using a DMS file to transfer data to, 350 creating the IBM SPSS Quantum specification, 368
Currency responses data cleaning, 388–389
formatting in interviews, 610 data cleaning examples, 390
Custom charts, 1508 defining a job name and description, 253
Custom controls in interview scripts, 853–855 defining special elements, 460
Custom validation diagrams, 231
in multiple-language scripts, 889 example timeline, 240
Customized sorting of responses, 577 exporting IBM SPSS Data Collection Interviewer Server
data to a IBM SPSS Data Collection Data File, 373
exporting IBM SPSS Data Collection Interviewer Server
DAT files data to IBM SPSS Quantum, 364–365, 367
using a DMS file to transfer data from, 320 exporting IBM SPSS Data Collection Interviewer Server
using a DMS file to transfer data to, 346 data to IBM SPSS Statistics, 369–370
Data filename extension, 206
hierarchical, 1271 filtering data, 243
merging, 373 filtering on interview finish time, 358
transferring, 310 filtering on interview status, 357
Data analysis keywords in interview scripts, 943 filtering variables exported, 359
Data cleaning generating IBM SPSS Quancept script, 285
DMS file examples, 390 getting started, 208
getting started with, 217 global variables, 274, 1576
multiple response variables, 398 how is it different from a .mrs file?, 1567
Other Specify responses, 400 how to run, 293
overview, 388 infrastructure, 206
performance problems, 1587 listing and comparing metadata versions, 364
selecting highest and lowest response alternately, 398 merging case data, 373
single response variables, 390 metadata-only operation, 238
special responses to non-categorical questions, 400 overview, 206, 241
troubleshooting, 1574 parsing and running, 289
using a DMS file, 389 performance problems, 1587
using log file for report, 271 procedural code, 273
Data entry fields programmer FAQs, 1584
automatic completion of in interview scripts, 834 running multiple, 1570
Data Entry settings, 129 sample batch files, 481
Data link properties samples, 466–467, 473, 475, 479
Advanced tab, 76 scheduling the running of, 294
All tab, 77 sections, 252
Connection tab, 68–69 setting up logging parameters, 271
metadata properties, 73 simple example, 242
metadata versions, 74 table scripting in, 451
Provider tab, 68 table scripting samples, 478
1597
Index
transferring data, 310 Date questions

transferring data from a IBM SPSS Data Collection analysis specs in interview scripts, 960
Data File, 318 cleaning special responses to, 400
transferring data from IBM SPSS Quantum, 320 Date variables
transferring data from IBM SPSS Quanvert, 321 banding in axis specification, 1215
transferring data from IBM SPSS Statistics, 319 converting to UTC, 358
transferring data from log files, 326 Dates
transferring data from Microsoft Office, 328 on forms, 808
transferring data from QDI/DRS, 325 Dates and times
transferring data from RDB, 316 formatting in interviews, 611
transferring data from Triple-S, 327 Day
transferring data from XML, 332 date/time, 657
transferring data to a delimited text file, 350 Debug, 1094
transferring data to a IBM SPSS Data Collection Data Debugging
File, 341 using IBM SPSS Data Collection Base Professional, 46
transferring data to IBM SPSS Quantum, 346 Decimal places
transferring data to IBM SPSS Statistics, 342 rounding, 1253
transferring data to RDB, 337 specifying, 1403
transferring data to SAS, 349 Decimal responses
transferring data to Triple-S, 348 number of decimal places, 550
transferring data to XML, 351 number of digits, 550
troubleshooting, 1565 setting the decimal point character, 550
UseInputAsOutput option, 234, 264 Decimals
using include files in, 247 defining in an axis specification, 1222–1223
using non-IBM SPSS Data Collection Data Model Decrease line indent, 21
providers, 333 Default language
using non-IBM SPSS Data Collection Data Model setting in IBM SPSS Data Collection Base Professional
providers to write data, 352 for interview scripts, 89
using text substitution in, 250 Default responses, 565
validation options, 336 Default styles
weighting example, 431 overriding default font effects, 753
what’s new, 2 Default templates, 1119
working with IBM SPSS Data Collection Interviewer DefaultCategoryType, 1095
Server data, 356 DefaultPresentationTemplate, 1095
working with versions, 360–362 Degrees of freedom
Data management scripting cell chi-square test, 1323, 1379
See Data Management Script (DMS) file, 204 chi-square test, 1317, 1378
Data management scripts column means test, 1381
See Data Management Script (DMS) file, 204 column proportions test, 1380
Data sources paired preference test, 1382
changing default location, 419 T-test test, 1367
defining input in DMS file, 253 tukey test, 1384
defining output in DMS file, 261 Tukey test, 1372
exchanging data between different, 266 Delimited Text DSC
Data types and DMS files, 350
limits, 1118 Delimited text files
database questions using a DMS file to transfer data to, 350
creating tables from, 1176 deployment options, 201
database settings, 133 deployment settings, 129
Databases Derived elements
using a DMS file to transfer data to, 337 adding to axis specification, 1204, 1217
DataManagementScript (DMS) files derived grid
See Data Management Script (DMS) file, 204 tables, 1293
DataSources derived variables
changing default location, 419 grid slices, 1299
Date, 554 Derived variables
creating in DMS file, 268, 433
1598
Index
in interview scripts, 964 dvHDATA, 1272

DerivedGridTables.mrs, 1293 dvVDATA, 1272
Diagnostics information Dynamic Property Expansion
statistical tests, 1316, 1377 table scripting, 1192
DialerCallOutcome, 1095
dialing settings, 177
DialingProvider, 1096 e-mail settings, 137
Dialog boxes, 66–67 Edit menu
Dictionary file, 1561 Advanced menu, 21
Difference operator Effective base
example of use in interview scripts, 688 adding to axis specification, 1204
Dim statement diagnostics file, 1380–1382, 1384
table scripting, 1192 overview, 1388–1389
Dirty data selecting, 1311
see also Off-path data, 710 weighting report, 412
Dirty mode ElementHeadings, 1244
selecting, 76 Elements
selecting in a DMS file, 336 adding to axis specification, 1204
disconnected settings, 126 base, 1230
display fields settings, 128, 154 element list syntax when scripting tables, 1200
display options, 201 foreign language labels, 1467
DisplayText, 1043 hiding in tables, 1153
DM Query in Table Object Model, 1557
creating crosstabulations in, 225 labels in tables, 1463
DMOM Object Model setting properties, 1222
HDATA, 1579 sorting special elements, 1417
DMS files Elements and ElementHeadings, 1244
See Data Management Script (DMS) file, 204 End of interview
DMS Runner actions for, 921
overview, 289 Ending interviews, 677, 702
scheduling, 294 Engine, 1096
troubleshooting, 1569 Error messages
DMS scripts adding new, 729
See Data Management Script (DMS) file, 204 blocks, compounds, grids, and loops, 725
Do...Loop, 669 color and font properties, 833
Do...Loop statement divide by zero, 738
table scripting, 1192 DMS files, 289
Documents error handler, 740
creating and saving, 23 example of script errors, 739
Don’t know IBM SPSS Data Collection Base Professional, 1565
checking for, 655 interview, 722
Don’t Know response, 560 out-of-range subscripts, 738
Don’t Know responses position on page, 830
cleaning in non-categorical questions, 400 questions in loops/bocks, 836
Double, 549 replacing standard texts, 725
Double questions response validation procedure, 722
cleaning special responses to, 400 script errors, 738
double-click standard, 724
disable, 1040 StandardTexts.mdd, 725
Down-lev operator text substitution problems, 738
table scripting, 1192 translating, 725
Down-leving writing an error handler, 741
table scripting filters, 1305 Escaping characters
Drop-down lists in interview scripts, 756 table scripting, 1192
drs files EvaluateEmptyIterations, 1299
using a DMS file to transfer data from, 325 Event section
view of data when scripting tables, 1272 OnAfterJobEnd, 285
OnAfterMetaDataTransformation, 279
1599
Index
OnBadCase, 284 Expressions

OnBeforeJobStart, 277 adding to axis specification, 1204, 1212–1216
OnJobEnd, 285 reversing the meaning of, 660
OnJobStart, 281 use with Weight component, 425
OnNextCase, 282 external browser
overview, 273 Citrix, 1562
troubleshooting, 1574
troubleshooting global variables, 1576
using objects in, 274 F1 help
Events, 522 using in IBM SPSS Data Collection Base Professional,
scripting, 918 42
writing paradata, 923 Factor weighting
Examples general options, 410
creating new variables in a DMS file, 433 overview, 408
data cleaning, 390 script example, 429
project, 993 weighting report, 412
using Table Object Model, 1265 Factors
using the Table Object Model, 1142 adding to axis specification, 1204
using the Weight component, 417 defining in an axis specification, 1222–1223
Excel in interview scripts, 953
DMS file example, 285 FailoverDemo.mrs, 1191
DMS files that integrate with, 475 FAQs
exporting data to, 352 data management scripting, 1565
exporting tables to, 1187 fields settings, 134
exporting tables to Excel, 1477 Fields, property of SampleRec object, 1072
importing data from, 328 Files
using a DMS file to transfer data to, 350 creating and saving, 23
Excel tables export files settings, 191
formatting, 1499 Filter variables
interactive mode, 1507 creating in a DMS file, 437
overview, 1498 Filtering
properties, 1501 answers chosen at both questions, 686, 688
Exchange answers chosen at earlier questions, 683
DMS files that integrate with, 475 answers chosen in response to at least one question, 685
Exclude from Base, 1234 answers not chosen at earlier questions, 684
Exclusive responses, 543 asking subsets of questions from a
Exit block/compound/page, 679
terminate interview, 677 by category number, 681
Exit Do, 671 categorical loop control lists, 692
Exit For, 673–674 categorical ranking grids, 734
Expected values categorical response lists, 680
cell chi-square test, 1325 different questions for different loop repetitions, 691
chi-square test, 1320 filtering “nofilter” responses, 688
showing in cells of table, 1247, 1254 hiding grid cells, 697
T-test test, 1371 interview scripts, 678
Tukey test, 1374 loops, 690
expiry date and time options, 202 numeric loop control lists, 693
Exporting questions in loops, 690
tables to Word, Excel, and PowerPoint, 1477 random selections for loops, 696
Exports responses list that combine earlier answers, 685
HTML, 1478 responses that should never be filtered, 688
Microsoft Excel, 1498 Filters
Microsoft Word, 1516 cancelling, 700
PowerPoint, 1509 Data management scripting, 243
Text, 1534 hierarchical data, 1305
expression interview start and finish time, 358
loop slice, 1305 interview status, 357
loop slice expression, 1305
1600
Index
metadata, 359 Getting started

metadata versions, 361–362 table scripting, 1142
Table Object Model, 1166, 1168 Global questions in interview scripts, 644
using during weighting calculations, 425 GlobalSQLVariables section
Filters tab, 197 defining, 266
FinishTime GlobalVariables
filtering on in a DMS file, 358 how to set up, 274
Fisher’s exact test troubleshooting, 1576
example, 1318 GoTo, 676
overview, 1316 grid base, 1299
FlattenGrid function, 488 grid iterations
FlipGrid function, 491 setting up bases, 1299
Footers Grid questions
exporting to Microsoft Word, 1523 creating tables from, 1174
Footnotes Grid slices
tables, 1166 derived variables, 1299
For Each...Next, 673 overview, 1299, 1302
For Each...Next statement Grid tables
table scripting, 1192 overview, 1290
For Each...Next statements sorting, 1418
data cleaning examples, 395 the base in, 1297
For...Next, 672 Grid variables
For...Next statement creating tables from, 1174
table scripting, 1192 Grids
Form name of interview page, 882 alignment on page, 875
Forms background color, 859
designing for interviews, 806 body cell background color, 780
Frequency tables bold/italic text, 862
scripting, 1149 borders, 875
Frequently asked questions categorical ranking, 734
data management scripting, 1565 cell borders, 784
Full labels cell formatting, 868
customizing in table script, 1299 cell padding, 788
Function keyword column width, 781, 866
table scripting, 1192 default cell values, 629
Function library example layouts, 792, 876
CombineIterations, 484 filtering one by another, 695
CopyGrid, 485 formatting alternate rows/columns, 870
CreateGridSummary, 487 hiding cells in, 697
defining filters using, 1166 initial cell values, 629
FlattenGrid, 488 nested with radio buttons in each cell, 792
FlipGrid, 491 overall characteristics, 874
RemoveCategory, 493 precedence for styles in cells, 779
ReplaceCategory, 494 repeating header cells, 782
SubtractQuestion, 496 repeating row/column headings, 869
SumQuestions, 498 rotation/randomization of rows/columns, 578, 628
using with Weight component, 425 row & column headings, 868
Functions, 1071 row height, 781, 866
AddSampleRec, 1071 row/column/cell characteristics, 866
AuthenticateSampleRec, 1072 side by side, 641, 792
Data Management, 483 space around cell texts, 876
GetSampleRec, 1073 space between rows/columns, 875
RemoveSampleRec, 1075 special text effects, 865
ReturnSampleRec, 1074 splitting big, 633
UtcNow, 1076 styles, 778
templates for, 856, 858, 872
text alignment, 861
GetSampleRec function, 1073
1601
Index
text characteristics, 861 HTML Export Render

text color, 863 reference, 1498
text size, 862 HTML tables export
typeface, 862 customizing the style sheet, 1490
unique ranks in, 732 interactive mode, 1488
validating when contain more than one question, 735 layout styles, 1479
width, 875 overview, 1478
wrapping cell text, 789 properties, 1481
wrapping text within cells, 860 using the formatted labels option, 1488
Grids see also Repeated questions, 615 working with the HTML Export Render object, 1492
HTML tags in question & response texts, 557
HTML Tidy
HDATA using in IBM SPSS Data Collection Base Professional,
DMOM Object Model, 1579 87
grid and loop slices, 1299, 1302 HTTP variables, 1042
grid tables, 1290, 1297
setting the table population levels], 1286
statistical tests, 1391 IBM SPSS Data Collection Activation Console
switching to VDATA in table script, 1272 Activation History tab, 196
table scripting filters, 1305 Filters tab, 197
understanding table population levels, 1279 questionnaire, 195
using the HDATA view in table scripting, 1276 Settings tab, 198
Headers IBM SPSS Data Collection Base Professional
exporting to Microsoft Word, 1523 about the table scripting documentation, 1140
Headings activating an interview, 87
tables, 1166 adding a case data source, 78
HiddenCodesList, 1097 advanced find options, 44
Hide Auto Answer, 61
hiding rows, columns, and cells, 1419, 1424, 1428–1429 case data, 78
Hide rules, 1153, 1419 changing the case data source, 78
Hiding changing the language of the browser pages, 88
elements, 1222, 1226 changing the layout of the window, 16
Hiding the base element, 1236 contacting IBM SPSS Data Collection Technical
Hierarchical data Support, 1566
grid and loop slices, 1299, 1302 context-sensitive (F1) help, 42
grid tables, 1290, 1297 contexts in interview scripts, 56
setting the table population level, 1286 creating mtd file for use in IBM SPSS Data Collection
statistical tests, 1391 Survey Tabulation, 1190
table scripting, 1271, 1276 creating your first mrScriptBasic script, 4
table scripting filters, 1305 data management scripting, 204
understanding table population levels, 1279 debugging, 46
which view is used in table scripting, 1272 default language for interview scripts, 89
Hints, 67 different types of surveys, 57
using with Auto Answer in IBM SPSS Data Collection displaying a different language, 53
Base Professional, 61 error messages, 1565
HistoryTable table, 1007 examining the values of variables, 49
hot keys exporting metadata to proprietary formats, 54
Citrix, 1562 exporting tables, 1477
Hour, 657 expressions pane, 49
Household sample external web browser, 60
using to understand grid tables, 1290, 1297 FAQs, 1562
using to understand table population levels, 1279 file types, 12
HTML getting started with, 4
customizing the style sheet, 1490, 1494 hints when using Auto Answer, 61
Export Render object, 1492 how mrScriptMetadata is displayed, 54
exporting tables to, 1144, 1181 HTML Tidy, 87
using to format labels, 1488 importing metadata from proprietary formats, 54
interview metadata viewer, 58
1602
Index
interview script file type, 54 exporting data to a IBM SPSS Data Collection Data File,
interview template files, 87 373
interview testing, 60 exporting data to IBM SPSS Quantum, 364
introduction, 1 exporting data to IBM SPSS Statistics, 369
ivs file type, 54 filtering data on the interview finish time, 358
keyboard shortcuts, 99 filtering data on the interview status, 357
languages in interview scripts, 57 filtering variables for exporting, 359
layouts for different tasks, 17 properties, 1087–1088
Levels Export component, 501 quota control system, 1077
license renewal, 1564 response validation procedure, 722
localization, 53 run-time errors, 738
localization of the browser pages, 88 sample DMS files for use with, 473
locals pane, 49 understanding metadata versions, 360
macros, 25 using a DMS file to transfer data from, 316
Metadata Services reference section, 1560 using DMS files with, 356
Metadata viewer, 28, 31 validation function, 731
navigating an interview script, 58 IBM SPSS Data Collection Interviewer Server
notes for IBM SPSS Quantum users, 111, 113 Administration
options, 101 activate questionnaire to, 113, 195
paper routing context, 57 working on Quota projects in, 1085
QsfTom component reference section, 1560 IBM SPSS Data Collection Interviewer Server property,
quotas - testing, 83 1103
regular expressions, 45 IBM SPSS Data Collection Metadata Model to Quantum
routing contexts, 57 Component
sample management data - accessing, 81 DMS file example, 277, 279
Script Packager component, 501 IBM SPSS Data Collection Paper - Scan Add-on
ScriptAssist, 43 using DMS files with, 356
setting breakpoints, 48 IBM SPSS Data Collection Survey Reporter
stepping through code, 48 setting up an mtd file in IBM SPSS Data Collection Base
syntax errors, 46 Professional, 1190
table population and failover, 1191 table population and failover, 1191
table scripting reference section, 1557 IBM SPSS Data Collection Survey Reporter Professional
Tabulation Services component object model, 501 about the documentation, 1140
templates, 21 annotations, 1432, 1434, 1436, 1439–1440, 1442
toolbars, 93 derived grid tables, 1293
user contexts in interview scripts, 56 HTML export, 1478
using bookmarks, 18 Microsoft Excel export, 1498
using the IDE, 11 Microsoft PowerPoint export, 1509
using to develop interviews, 54 Microsoft Word export, 1516
viewing an interview script, 58 samples, 1547
viewing large files, 18 Text export, 1534
viewing multiple files, 18 tutorial, 1142
web browser, 60 working with Change Tracker, 1469–1470, 1472, 1474
Weight component, 406, 503 working with metadata, 1453
what’s new, 2 working with variables, 1475
window, 13 IBM SPSS Data Collection Survey Tabulation
workspace feature, 27 setting up an mtd file in IBM SPSS Data Collection Base
IBM SPSS Data Collection Base Professional Tables Option Professional, 1190
statistical formulae, 1268 statistical formulae, 1268
IBM SPSS Data Collection Data File CDSC table population and failover, 1191
and DMS files, 318 IBM SPSS Quancept script
exporting IBM SPSS Data Collection data to, 373 generating from the .mdd file in a DMS file, 285
using with a DMS file to transfer data, 341 IBM SPSS Quantum
IBM SPSS Data Collection Interviewer Server exporting IBM SPSS Data Collection Interviewer Server
custom validation, 729 data to, 364–365, 367
error messages, 722 table scripting, 1188
using a DMS file to transfer data from, 320
1603
Index
using a DMS file to transfer data to, 346 InputDataSource section

IBM SPSS Quantum DSC defining filtering in, 243
and DMS files, 320, 346 defining in WinDMSRun, 302
IBM SPSS Quantum users defining input data source, 311
getting started with IBM SPSS Data Collection Base overview, 253
Professional, 111 viewing data selected in, 307
IBM SPSS Quanvert Inserts
table scripting, 1188 in multiple-language scripts, 889
unpacking packed databases, 321 Inserts in interview texts, 601
using a DMS file to transfer data from, 321 Integer responses
view of data when scripting tables, 1272 number of digits, 549
IBM SPSS Quanvert DSC Interactive mode
and DMS files, 321 Excel table exports, 1507
table scripting, 1188 HTML table exports, 1488
IBM SPSS Statistics Microsoft PowerPoint exports, 1515
exporting IBM SPSS Data Collection Interviewer Server Word table exports, 1522
data to, 369–370 Interactive Voice Response
statistical tests compared to, 1393 dialing the IVR system, 929
using a DMS file to transfer data from, 319 DTMF string, 930, 936
using a DMS file to transfer data to, 342 example script, 941
IBM SPSS Surveycraft failed calls to, 935
table scripting, 1188 hand-off function, 929
IBM SPSS Text Analytics for Surveys overview, 928, 937
analyzing a tracking study, 442 passing data to, 931
Id passing information to, 930
sample record field, 995 passing serial numbers to, 931
If...Then...Else, 663 test script for, 940
If...Then...Else statement transferring respondent to, 934
table scripting, 1192 writing an IVR script, 936
IIF Intersection operator
example of using to set up Boolean derived variable, 438 example of use in interview scripts, 686
Images Interview activation
in templates, 851 in IBM SPSS Data Collection Base Professional, 87
Images/pictures Interview Database Binder
alt tags for, 798 object model, 1139
clicking to select responses, 798 Interview Object Model
format and location, 799 Category object, 537
Images/pictures in interview scripts, 795 IOM object, 536
Include files Label object, 538
DMS files, 247 Navigation object, 538
error messages, 289 non-programmer’s guide, 530
samples, 479 Question object, 537
using .mrs files as in a DMS file, 1567 referring to objects in Routing section, 532
IncludeInBase, 1234 Response object, 539
Increase line indent, 21 Style object, 538
Indenting response lists/boxes, 763 Interview page
Info item, 595 form name for, 882
Initial values for responses, 566 Interview properties, 1087–1088
Input boxes Interview scripting
color, 766 accessing filtered out items, 679
dimensions, 771 all specified responses chosen, 651
display methods, 774 any specified responses chosen, 652
overview, 765 asking questions, 558
Input data source Category object, 537–538
defining, 253 checking responses, 648
exchanging data with output data source, 266 comments, 530
compare a sum against a given value, 670, 672–673
1604
Index
conditional actions, 662 Interviewer qualifications

default styles, 814 overview, 1036
executing series of statements for one question, 674 interviewer settings, 159
filtering the categories of a loop, 693 InterviewerID, 1097
flow control statements, 675 Interviewer’s name
If...Then...Else, 663 making available to sample management script, 1037
indentation of response controls, 832 InterviewerTimezone, 1097
initial values for responses, 566 interviewing settings, 153
Interview object, 536 InterviewProperties object
Interview Object Model, 530 example, 1074
Javascript in, 528 InterviewRejectedPage, 1098
jumping to named location in routing script, 676 InterviewRejectedType , 1098
Multiple-language scripts, 883 InterviewRestart, 1098
named locations in the routing section, 676 Interviews
Navigation object, 538 actions at certain points in, 918
number of responses chosen, 650 actions on abnormal termination, 923
object collection iteration, 668 answer summary at end of, 715
Question object, 537 checking that calls are connected to, 966
referring to objects, 532 end of, 1044
repeating questions, 667 ending/stopping, 702
repeating statements a set number of times, 672 lifecycle, 919
repeating statements for each element in an messages at end of, 701
array/collection, 673 off-path data, 710
repeating statements until condition is true, 669 paradata, 923
repeating statements while condition is true, 669, 671 restarting, 704, 995, 1074
repeating statements/assignments for all objects in a reviewing completed, 714
collection, 668 scripted termination, 677
repetitive actions, 667 standard end-of-interview procedure, 701
Response object, 539 total time to complete, 719
rules for scriptwriting, 526 InterviewScriptType, 1098
Select Case, 662 InterviewStartURL, 1098
set number of specified responses chosen, 654 InterviewStatus, 1098
Style object, 538 InterviewStoppedPage, 1099
template XML schema, 1131 InterviewStoppedType, 1099
terminating interviews, 677 introduction settings, 158
using objects, 927 InvalidText, 724
what’s new, 504 IsHidden, 1236
writing questions, 539 IsHiddenWhenColumn, 1236
Interview Scripting IsHiddenWhenRow, 1236
limits for questions, 1118 IsTest , 1099
what is an interview script, 522 IsUploadSample , 1100
Interview scripting in IBM SPSS Data Collection Base IVFilesToBeCopied, 203
Professional ivs files, 54
setting default language for interview scripts, 89
what’s new, 2
Interview scripting reference, 1086 Jagged grids, 697
Interview scripts Japanese characters
activating, 988 in a DMS file, 1569
analysis elements in, 943, 945 Japanese data sources
execute/ignore statements when testing/debugging merging, 386
scripts, 967 Javascript in interview templates, 528, 851
Testing, 984 JAWS, 1561
Interview-only elements Job
hiding in analyses, 959 section in DMS file, 253
Interview-stopped page, 1044 JoinKey parameter
Interviewer activity codes, 1024 for merging case data, 381
Interviewer instructions in interview scripts, 595 JoinKeySorted parameter
for merging case data, 381
1605
Index
JoinType parameter Lines

for merging case data, 381 breaking long lines, 247
List boxes in interview scripts, 756
local deployment, 203
Keyboard navigation, 1561
Local Deployment Wizard
keyboard shortcuts
deployment options, 201
Citrix, 1562
display options, 201
Keyboard shortcuts, 91
expiry date and time options, 202
Known problems
overview, 199
IBM SPSS Quanvert DMS file exports, 321
summary options, 202
usage options, 199
Labels validation options, 200
for table axes and elements, 1463, 1467 Local variables
HTML tags in, 557 naming in sample management scripts, 1138
inserting text into, 608 Locale
using HTML tags to format, 1488 effect on decimal point and thousands separator, 550
LabelType, 1100 Locale for multiple-language interviews, 886
LabelTypes Localization
selecting, 73 IBM SPSS Data Collection Base Professional, 53
Landscape Log DSC
changing format for Microsoft Word export, 1525 and DMS files, 326
Language, 550, 1100 Log files
effect on decimal point and thousands separator, 550 DMS files, 271
Language for multiple-language interviews, 885 location when not specified, 1571
Languages using a DMS file to transfer data from, 326
adding to interview scripts in IBM SPSS Data Collection Logging
Base Professional, 57 Data Management Script (DMS) file, 271
selecting, 73 for debugging, 1049
setting default in IBM SPSS Data Collection Base Logo
Professional for interview scripts, 89 choosing whether to include in HTML table export, 1481
table scripting, 1467 LogThisEx, 1074
LastActivatedBy , 1100 Long, 547
Least significant difference, 1338, 1342, 1347 Long questions
Left cleaning special responses to, 400
data cleaning example, 399 loop slice, 1305
legal notices Loop slices
All tab, 1589 derived variables, 1299
Len overview, 1299, 1302
data cleaning example, 399 Loops
Level of significance asking different questions for different repetitions, 691
See significance level, 1311 asking selected iterations only, 624
LevelID, 1293 displaying loop control values in question texts, 603
Levels error messages for questions in, 836
grid and loop slices, 1299, 1302 filtering, 690
grid tables, 1297 filtering numeric control lists, 693
setting the table population level, 1286 filtering one grid by another, 695
table scripting filters, 1305 filtering questions, 690
understanding table population levels, 1279, 1290 filtering repetitions, 691–692
Levels Export component hiding grid cells, 697
about, 501 jagged grids, 697
Levels Export object model, 501 jumping out of, 671, 673–674
License for IBM SPSS Data Collection Base Professional random selections from control lists, 696
renewing, 1564 Loops see Repeated questions, 615
Limits, 1555
tables, 1555
Limits for data types, 1118 Macros
Line-continuation character IBM SPSS Data Collection Base Professional, 25
DMS files, 247
1606
Index
Manual-coding tools Metadata filter

analyzing a tracking study, 442 setting up, 243, 359
Mapping dialer return codes to call outcome codes, 1021 Metadata section
MasterProject, 1100 Data Management Script (DMS) file, 268
MAX_TRIES, 1012 FAQs, 1573
MaxAuthRetries, 1101 setting up card column definitions for variables created
default value, 1044 in, 279
Maximum value Metadata Services
adding to axis specification, 1204 object model documentation , 1560
showing in cells of table, 1247 reference section, 1560
showing in tables, 1172 Microsoft Excel
weighting, 410 exporting tables to, 1498
MaxOpCodesExecuted, 1101 using a DMS file to transfer data to, 350
MaxPredictiveSilentCalls, 1101 Microsoft Office
MaxQuestionsOnReplay, 1101 DMS files that integrate with, 475
MaxSilentCalls, 1102 importing data from, 328
MaxTries, 1024 Microsoft PowerPoint
.mdd file, 522 exporting to, 1509
mdd files Microsoft Word
changing default data source location, 419 exporting tables to, 1516
connecting to, 69 Microsoft Word tables export
creating from proprietary metadata, 314 formatting, 1523
listing and comparing versions in, 364 styles, 1527, 1529, 1533
setting default language in IBM SPSS Data Collection templates, 1524–1525
Base Professional for mdd files, 89 Minimum value
storing the axis expression, 1536 adding to axis specification, 1204
MDM document showing in cells of table, 1247
cleaning up IBM SPSS Quanvert-specific information, showing in tables, 1172
321 weighting, 410
listing and comparing versions in, 364 MinimumRingTime, 1102
MDM Explorer Mode
using to store axis expression, 1537 adding to axis specification, 1204
Mean Modify Table Statistics dialog box
adding to axis specification, 1204, 1207–1208 opening, 1314
calculation of base, 1230 overview, 1313
effect of population level, 1279 MonitoringAllowed, 1103
excluding categories from the mean in an axis Month, 657
specification, 1216 More than one question per interview page, 637
in interview scripts, 950–951, 953 MoveSampleRec, 1074
showing in cells of table, 1247, 1254 mrBannerText element, 1131
Mean Summary Tables mrData element, 1132
creating, 1401 mrigf.xsd grid template schema, 856
specifying decimal places, 1403 mrNavBar element, 1134
Median mrNavButton element, 1134
adding to axis specification, 1204, 1220 mrPage element, 1135
showing in cells of table, 1247 mrPageTitle element, 1136
showing in tables, 1172 mrProgressBar element, 1137
Menu options, 91 mrRef element, 1137
Menus, 91 mrs files, 1008
Merging case data, 373 debugging, 46
Merging multibyte data sources, 386 using as Include files in a DMS file, 1567
MessagesDocument, 1102 mrScriptBasic
Metadata, 522 data cleaning examples, 390
filtering in data management scripting, 243 Data Management Script (DMS) file, 206, 273
listing and comparing versions in, 364 debugging, 46
viewing in IBM SPSS Data Collection Base Professional, examples of using the Table Object Model, 1142
28, 31 learning, 221
1607
Index
setting up case data for new variables, 433 details and restrictions, 1351
using to create axis expressions, 459, 1538 diagnostics information, 1381
weighting examples, 417 example, 1349
working with in IBM SPSS Data Collection Base overview, 1348
Professional, 4 statistical formula, 1351
mrScriptMetadata Nets
creating new variables in, 433 adding to axis specification, 1204, 1210
Data Management Script (DMS) file, 206, 268 creating in a DMS file, 440
defining axis expressions, 456 sorting, 1415
defining base elements, 463 New
defining special elements, 460 project template, 23
learning, 227 No answer
mtd files checking for, 655
creating, 1144 No Answer response, 559
creating for use in IBM SPSS Data Collection Survey No Answer responses
Tabulation, 1190 cleaning in non-categorical questions, 400
Multibyte data sources NoAnswerDelay, 1024
merging, 386 Not, 660
Multiple response questions NotDate, 724
cleaning case data for, 398 Notes, 1103
Multiple response variables NotInRange, 724
cleaning, 398 NotInteger, 724
statistical tests, 1390 NotNumeric, 724
Multiple-language interviews NotSingleAnswer, 724
giving examples of input formats, 887 Now
interview language, 885 data management example, 265
interview locale, 886 Null
interviewer qualifications, 884 dynamically derived variables, 438
non-question texts, 889 Null DSC
templates for, 889 overview, 256, 262
writing and testing scripts, 883–884 null grid base, 1299
Multiple-language scripts, 883 Null hypothesis, 1385
Multiplier variable Numbers
including in an axis specification, 1222 formatting decimal in interviews, 610
Multipliers Numeric
in interview scripts, 965 adding to axis specification, 1204
Numeric questions
Allowing Don’t know as a response, 561
Namespacing, 545 Allowing No answer as a response, 560
navigation buttons Allowing Refuse to answer as a response, 561
control, 1040 analysis specs in interview scripts, 960
Navigation buttons cleaning special responses to, 400
automatic focus on Next, 841 Numeric responses
changing/translating, 613 checking sum of against a given value, 670, 672–673
hiding/displaying, 612, 775 Numeric variables
position on page, 839 creating categorical variable from, 434
question texts in the Goto list, 612 using in tables, 1172
removing from Navigations collection, 841
styles, 775
Nested tables Object collection iteration statements
introduction, 1156 data cleaning examples, 396
limits, 1555 object model
overview, 1158 Tabulation Services component, 501
sorting, 1412 Object models
Nesting variables finding documentation about, 229
limits, 1555 Interview Database Binder, 1139
Net difference test quota, 1138
adding to axis specification, 1204
1608
Index
Objects others settings, 194

referencing in interview scripts, 528 Outlook
Objects in interview scripts, 927 DMS files that integrate with, 475
Off-path data Output data source
in interviews, 710 defining, 261
On Error statement exchanging data with input data source, 266
table scripting, 1192 OutputDataSource section
OnAfterJobEnd section defining in WinDMSRun, 302
overview, 285 defining target data source, 325
troubleshooting, 1574 overview, 261
using objects in, 274 viewing output data in WinDMSRun, 308
OnAfterMetaDataTransformation section Overlap adjustment, 1390
overview, 279 Overlapping data, 1390
using objects in, 274 overrides settings, 175
OnBadCase section
overview, 284
using objects in, 274 p values, 1386
OnBeforeJobStart section cell chi-square test, 1322, 1379
axis expressions, 459 chi-square test, 1316, 1378
cleaning up IBM SPSS Quanvert-specific information, column means test, 1381
321 column proportions test, 1380
creating .mdd file from proprietary metadata, 314 overview, 1385
overview, 277 paired preference test, 1382
troubleshooting, 1574 T-test test, 1367
using objects in, 274 tukey test, 1384
OnJobEnd section Tukey test, 1372
overview, 285 Page banners, 596
troubleshooting, 1574 page template settings, 188
using objects in, 274 Page templates
OnJobStart section naming CSS in, 882
overview, 281 Page titles
troubleshooting, 1574 displaying, 839
using objects in, 274 Page titles in interview scripts, 595
OnNextCase section Pages
overview, 282 adding banners to, 597
troubleshooting, 1574 removing banners from, 600
using objects in, 274 Paired preference test
Operators adding to axis specification, 1204
defining filters using, 1166 details and restrictions, 1361
Order of mention for interview responses, 620 diagnostics information, 1382
OrderBy, 1024 Example, 1358
ordering settings, 168 overview, 1356
Origin, 1103 requesting, 1314
OriginName , 1104 statistical formula, 1362
Other specify Paper routing
substituting text of in another response list, 606 amending in IBM SPSS Data Collection Base
Other Specify, 562 Professional, 57
automatically select response when text entered, 563 Paradata
box color, 766 example script, 925
input box size, 771 Paradata for interviews, 923
input box style, 765–766 parameters settings, 163
styles for answers, 770 participants settings, 131
Other Specify category Passwords
accessing responses to in DMS file, 400 sample management, 1041
Other Specify variables Pending count
accessing in DMS file, 400 overview, 1045
OtherNotSelected, 724 Percentages
showing in tables, 1247, 1254
1609
Index
PercentCallsRecorded, 1104 in Table Object Model, 1557

Percentile Microsoft PowerPoint Export, 1511
adding to axis specification, 1204, 1220 Microsoft Word tables Export, 1518
Percentiles table scripting, 1153, 1396
showing in cells of table, 1247 Text Export, 1535
showing in tables, 1172 ptz files
Performance problems creating and saving, 23
in data management scripts, 1587
PlayerNavigationDisabled, 724
Populating tables qdi files
limits, 1555 using a DMS file to transfer data from, 325
Postweights view of data when scripting tables, 1272
overview, 410 QDI/DRS DSC
PowerPoint and DMS files, 325
DMS files that integrates with, 475 table scripting, 1188
exporting tables to PowerPoint, 1477 QsfTom component
PowerPoint export object model documentation , 1560
formatting, 1509 reference section, 1560
interactive mode, 1515 Question
overview, 1509 analysis elements in, 943
properties, 1511 Question banners, 596
Pre-authentication page, 1039, 1042 Question components
PredefinedQueues, 1011 position on page, 831
predictive settings, 179 Question context
Prefix adding texts to in IBM SPSS Data Collection Base
adding to cell items, 1400 Professional, 56
Presets, 117 Question texts
Preweights instead of question names in Goto navigation list, 612
overview, 410 Question types
PrioritizeRecalls, 1024 boolean, 553
Problems known about date, 554
IBM SPSS Quanvert DMS file exports, 321 double, 549
Product difference test long, 547
overview, 1362 text, 551
Profile tables Questionnaire Wizards for IBM SPSS Data Collection
properties, 1396 Author, 968
Profiles, 1443–1444, 1449 Creating the Source MDD, 969
Progress bars, 842 Creating the Wizard MDD, 970
calculation methods, 844 Examples, 972
Project, 1104 Overview, 969
Project Interview settings, 124 Saving the Wizard to the IBM SPSS Data Collection
Project properties, 1087–1088 Question Repository, 971
project roles settings, 125 Saving the Wizard to the Library, 971
Project Settings, 121 Questionnaires
project templates, 23 activating, 113
Project templates Activation History tab, 196
creating and saving, 23 activation templates, 117
Project Templates Filters tab, 197
Configure , 24 IBM SPSS Data Collection Activation Console, 195
working with unzipped , 25 Settings tab, 198
ProjectInactivePage, 1105 testing, 66–67, 113
ProjectInactiveType, 1105 Questions
Properties actions after asking, 922
Excel tables Export, 1501 actions before asking, 921
for IBM SPSS Data Collection Interviewer Server, adding banners to, 597
1087–1088 alignment, 799
HTML tables Export, 1481 all specified responses chosen, 651
allow respondents not to answer, 559
1610
Index
allowing a thousands separator, 548, 551 Queues, 1011

allowing respondents not to answer, 563 overview, 992
analysis elements in, 943, 945 Quota
any specified responses chosen, 652 attaching sample records to the quota control system,
asking, 558 1046
blocks, 642 checking return codes in the sample management script,
categorical, 540 1048
categorical, maximum number of responses to choose, object model, 1138
542 overview, 1045
checking responses, 648 pending quota cells in the sample management script,
choosing templates for, 827 1047
different interview and analysis responses, 962 processing records returned from interviews, 1047
display same at top of every page, 644 targets, 1045
display side by side, 806 writing a sample management quota control system,
displaying answers to previous questions in, 602 1046
displaying loop control values in repeated, 603 Quota control
displaying more than one per page, 636–637 based on sample data, 1081
displaying values of temporary variables in, 603 categorical responses, 1079
do not save data, 565 completed count, 1077
example responses in question texts, 887 counter quotas, 1081
executing series of statements for one question, 674 in projects that use sample management, 1081
filtering, 679 keeping track of quotas, 1077
global, 644 no access to sample database, 1083
HTML tags in, 557 null, dk, ref and other responses, 1080
images in, 795 numeric and text responses, 1080
limits, 1118 overquota quotas, 1081
more than one on a page, 834 pending count, 1077
multiple response categorical, 542 prioritization of multiple responses, 1084
namespacing, 545 projects in IBM SPSS Data Collection Interviewer
non-alphanumeric characters in, 557 Server Administration, 1085
number of responses chosen, 650 rollback count, 1077
number of responses to choose, 542 setting up, 186
order to ask, 646 sharing quotas between projects, 1085
position on page, 830 stopped or timed out interviews, 1080
question text side by side with input box, 833 types of, 1076
random selection within loops, 696 Quota settings, 186
recording, 810 QuotaAutoCommit, 1047, 1105
removing banners from, 600 QuotaFullPage, 1106
repeating, 667 QuotaFullType, 1106
responses with numeric labels, 542 QuotaProjectName, 1106
set number of specified responses chosen, 654 Quotas
side by side with responses, 800 IBM SPSS Data Collection Base Professional - testing
styles for, 745 quotas in IBM SPSS Data Collection Base Professional,
subheadings in response lists, 543 83
text background color, 746 sample scripts, 1053
text color, 746
text effects, 751
text settings, 753 RaisePositionError, 1107
text size, 750 Randomizing response order, 570
text substitution in, 601 Range
trade-off, 696 showing in tables, 1172
typeface, 748 Ranks
validating text responses, 552 checking for unique, 732
vertical alignment with responses, 804 ReadOnlyFieldColumns, 1007
writing, 539 RecallMarginBefore, 1024
Queue, sample record field, 995 RecordCall, 1107
RecordingProhibited, 1107
1611
Index
reference Respondent.Serial
HTML Export Render, 1498 exporting to RDB database using a DMS file, 314
Reference RespondentID, 1108
interview scripting, 1086 RespondentTimezone, 1108
Refuse to Answer response, 561 Response lists
Refuse to Answer responses filtering, 680, 683–686, 688
cleaning in non-categorical questions, 400 filtering by category number, 681
Refused responses that should not be filtered, 688
checking for, 655 shared lists as, 581
Registry settings sorting using routing statements, 577
activation, 203 sorting with subheadings, 573
Regular expressions Response texts
using in IBM SPSS Data Collection Base Professional, varying between interviews and analyses, 962
45 Responses
RejectDelay, 1024 alignment, 799
Relational databases all specified chosen, 651
exporting to using a DMS file, 314 any specified chosen, 652
using a DMS file to transfer data from, 316 banding in interview scripts, 960
using a DMS file to transfer data to, 337 categorical in non-categorical lists, 764
view of data when scripting tables, 1272 checking, 648
Relational MR Database (RDB) CDSC checking for unique ranks, 732
and DMS files, 316 clickable images, 798
exporting to using a DMS file, 314 combining interviewing in analyses, 963
table scripting, 1188 converting to sample data format, 893
using with a DMS file to transfer data, 337 copying into sample records, 892
view of data when scripting tables, 1272 customized validation, 729
RemoveCategory function, 493 default, 565
RemoveSampleRec function, 1075 drop-down lists, 756
RemoveSampleRec method, 1075 fixed position in a list, 573
Renderer, 1108 HTML tags in, 557
Repeated questions images in, 795
3-dimensional grids, 631 input boxes for non-categorical, 765
asking, 624 lining up continuation lines in wrapped texts, 881
asking certain iterations only, 624 list boxes, 756
based on answers to previous questions, 633 non-alphanumeric characters in, 557
case data format, 636 number chosen, 650
categorical loops, 620 order of mention, 620
default cell values in grids, 629 overriding default text effects, 753
displaying on separate pages, 624 position on page, 830
each repetition as a separate question, 620 reading from sample records, 890
grids, 615 recording, 810
how they work, 617 referring to in axis blocks, 946
initial cell values in grids, 629 set number of specified chosen, 654
nested loops, 635 showing example formats in question texts, 887
numeric loops, 620 styles for, 745
order for loop control list items, 628 text background color, 746
printing and tabulating as grids, 636 text color, 746
separately on multiple pages, 615 text effects, 751
splitting big grids, 633 text settings, 753
unbounded loops, 626 text size, 750
Repetitive actions in interview scripts, 667 typeface, 748
ReplaceCategory function, 494 variable text, 606
Replicates, 1011 RestartString, 1108
Residuals Retry-authentication page, 1038, 1043
showing in cells of table, 1247, 1254 ReturnSampleRec function, 1044, 1074
Respondent instructions in interview scripts, 595 Reverse alphabetic sorting of responses, 568
Reversing response order between interviews, 572
1612
Index
Review, 1109 using .sam files for IBM SPSS Data Collection projects,
review settings, 162 203
Reviewing completed interviews, 714 Sample Management
Rim weighting example scenario, 993
additional options, 411 functions, 1071
formulae, 415 IBM SPSS Data Collection Base Professional -
general options, 410 accessing sample data in IBM SPSS Data Collection
overview, 409 Base Professional, 81
script example, 429 overview, 992
weighting report, 412 what’s new, 992
RimFlagAbove Sample management scripts
overview, 411 examples installed with the DDL, 1052–1054
weighting report, 412 Sample quotas
RimFlagBelow quick way to set up, 1083
overview, 411 Sample record fields
weighting report, 412 overview, 995
RimIterations read-only, 1007
overview, 411 TimeZone, 1032
RimLimit Sample record return codes (see Call outcome codes), 1014
overview, 411 Sample records
Rolling back interviews, 705–706 overview, 995
save points instead of GoTo, 708 reading from existing database, 1007
Root mean square (RMS) Sample table
formula, 415 overview, 995
weighting report, 412 saving information to, 1039
Rotating response order between interviews, 569 using existing database as, 1007
RotationValue, 1109 Sample tables
Rounding column data types in, 1006
about, 1253 Sample variance
IBM SPSS Data Collection Survey Tabulation and IBM adding to axis specification, 1204, 1207–1208
SPSS Data Collection Survey Reporter Professional, in interview scripts, 950–951, 953
1253 SampleID, 1110
Routing, 522 SampleManagementProvider, 1110
events, 918 SampleParameters, 1111
Routing contexts Samples
adding in IBM SPSS Data Collection Base Professional, DMS files, 466
57 learning about, 228
deleting in IBM SPSS Data Collection Base Professional, SAS DSC
57 and DMS files, 349
routing options SAS files
data entry, 200 using a DMS file to transfer data to, 349
live interviewing, 201 sav files
routing settings, 127 creating .mdd file from in a DMS file, 314
RoutingContext, 1109 exporting IBM SPSS Data Collection Interviewer Server
RunningCodesList, 1109 data to, 369–370
RunNumber, 1110 table scripting, 1188
using a DMS file to transfer data from, 319
using a DMS file to transfer data to, 342
Sample data view of data when scripting tables, 1272
updating in interviews, 890, 892–893 Save
using in interviews, 890, 893 project template, 23
Sample management Save points, 705–706
debugging IBM SPSS Data Collection scripts, 1050 comparison with GoTo, 708
making interviewer name available to script, 1037 Scheduled Task wizard
naming local variables, 1138 using to schedule DMS files, 294, 296
object model, 1138 Screen readers, 1561
porting .sam scripts to .mrs format, 1009
scripts, 1008
1613
Index
Script Packager component SortDesc

about, 501 data cleaning example, 398
Script Packager object model, 501 Sorting
script settings, 136 fixing an element’s position, 1222, 1225
Scripts response lists, 577
CATI, 1054 response lists containing subheadings, 573
changing, 1008 responses in alphabetic/reverse alphabetic order, 568
debugging, 1049 responses in random order, 570
overview of sample management, 1008 responses in reverse order, 572
quota with sample management, 1053 responses in rotation, 569
referring to nonexistent sample fields in, 1049 responses with fixed positions in lists, 573
standard, 1051 rows/columns in grids, 578, 628
testing, 1049 tables, 1407–1408
Security settings Sorting responses
for exporting tables, 1477 subheadings, 592
SeedValue, 1111 Sound files
Select Case, 662 playing in interviews, 810
Select Case statement Special elements
table scripting, 1192 defining in data management script, 460
Select Project Template dialog, 25 Special responses
Serial, 1112 checking for, 560–562, 655
Serial number, 1074 cleaning in non-categorical questions, 400
in sample management, 995 dash/hyphen as response name, 560–562
Server, 1112 response name to match the keyword, 560–562
Session, 1113 SPSS
SessionToken, 1113 rounding, 1253
Set keyword SPSS Statistics SAV DSC
table scripting, 1192 and DMS files, 319, 342
setting up bases table scripting, 1188
grid iterations, 1299 SQL Server
Settings tab, 198 importing data from, 328
Shared lists using a DMS file to export data to, 352
analysis options in, 965 Standard deviation
as response lists, 581 adding to axis specification, 1204, 1207–1208
changing the order of responses in, 586, 592 in interview scripts, 950–951, 953
creating, 579–580 showing in tables, 1172
including one in another, 583 Standard error
rotating/randomizing responses in, 586, 592 adding to axis specification, 1204, 1207–1208
same response in more than one list, 585 column means test, 1381
special responses with, 593 column proportions test, 1380
subheadings, 587 in interview scripts, 950–951, 953
subheadings in, 588, 590 paired preference test, 1382
ShowInterviewApps, 1113 showing in tables, 1172
ShowTableApps, 1113 tukey test, 1384
Shutdown, 1113 StandardTexts.mdd, 613, 725
Significance level Start of interview
defining for a statistical test, 1311 actions for, 920
observed, 1385 StartTime
SilentAnswer, 1024 filtering on in a DMS file, 358
SilentCallAudioFile, 1114 Statements
Single response questions executing series for one question, 674
cleaning case data for, 390 repeating a set number of times, 672
Single response variables repeating for all objects in a collection, 668
cleaning, 390 repeating for each element in an array/collection, 673
Snapbacks See Rolling back interviews, 705 repeating until condition becomes True, 669
SortAsc repeating while condition is True, 669, 671
data cleaning example, 398
1614
Index
Statistical elements Sub keyword

in interview scripts, 950–951, 953 table scripting, 1192
Statistical formulae Sub-templates see Templates, 847
paired preference test, 1362 Subheadings
Statistical tests in interview scripts, 956
adding and removing tests, 1313 response indentation with, 591
cell chi-square test, 1322 shared lists, 587–588, 590
chi-square test, 1316 sorting, 592
column means test, 1337 sorting response lists containing, 573
column proportions test, 1328 sublist, 590
compared to IBM SPSS Statistics, 1393 Sublists
diagnostics, 1316, 1377 indentation of responses in, 591
effective base, 1311, 1388–1389 Substitutions
examples, 1178 fixed values, 887
Fisher’s exact test, 1316, 1318 formatting, 609
hierarchical data, 1391 Subtotal
Net difference test, 1348–1349, 1351 adding to axis specification, 1204, 1210
overlapping data, 1390 Subtotals
overview, 1310 in interview scripts, 957
p values, 1385–1386 SubtractQuestion function, 496
paired preference test, 1356, 1358, 1361–1362 Suffix
product difference test, 1362 adding to cell items, 1400
specifying, 1314 Sum
T-test test, 1367 adding to axis specification, 1204, 1219
Tukey test, 1372 effect of population level, 1279
Statistics showing in tables, 1172
See statistical tests and cell contents, 1310 summary options, 202
Status Summary Statistic Tables
filtering on interview status in a DMS file, 357 creating, 1401
Stopped interview page, 1044 specifying decimal places, 1403
Stopping interviews, 702 SumQuestions function, 498
Style sheet Superversions
customizing for HTML tables export, 1490, 1494 selecting in Data Link Properties dialog box, 73
selecting for HTML table export, 1481 Surveys
Styles different types in IBM SPSS Data Collection Base
categorical response lists, 754 Professional, 57
exporting tables to HTML, 1490, 1494 system variables, 1565
for text, 745
grid, 778
input boxes for non-categorical questions, 765 T-test test
Microsoft Word, 1527, 1529, 1533 details and restrictions, 1371
navigation buttons, 775 example, 1367
order of precedence, 743 overview, 1367
overview, 744 statistical formula, 1371
question-response alignment, 800, 804 Tabify selection, 21
respondents’ answers, 768 Table Object Model
text, 753 available cell contents, 1247
text background color, 746 axis and element labels, 1463
text color, 746 base element, 1230
text effects, 751 cell contents, 1149
text size, 750 concatenated examples, 1156, 1158, 1412
typeface, 748 creating HTML charts, 1181
using when exporting tables to Excel, 1499 database questions, 1176
using when exporting tables to Microsoft Word, 1523 defining grid tables, 1174
Sub defining statistical tests, 1178
data cleaning examples, 395 defining table structure, 1192
dynamic property expansion, 1246
element list syntax, 1200, 1204, 1222
1615
Index
Elements and ElementHeadings, 1244 exporting to Text, 1534

examples of cell contents, 1254 filtered base elements, 463
exporting tables, 1477 filtering hierarchical data, 1305
exporting to Excel, 1187 general information, 1247
filters, 1166, 1168 grid and loop slices, 1299, 1302
frequency tables, 1149 grid tables, 1290, 1297, 1418
general information, 1247 hiding rows, columns, and cells, 1419, 1424, 1428–1429
grid tables, 1290, 1418 HTML Export Render Reference, 1498
hide rules, 1153 in data management script file, 451
hiding rows, columns, and cells, 1419, 1424, 1428–1429 languages, 1467
languages, 1467 loading different types of data, 1188
loading different types of data, 1188 nets, 1415
navigating the axis tree, 1243 numeric variables, 1172
nested examples, 1156, 1158, 1412 sample dms files, 478
nets, 1415 setting element properties, 1222
opening an existing table document, 1190 setting the table population level, 1286
reusing axes, 1164 sorting tables, 1407–1408
simple crosstabulation, 1144 special elements, 1204, 1417
sorting tables, 1407–1408 specification syntax, 1197, 1200
special elements, 1417 table properties, 1153, 1396
table population and failover, 1191 tutorial, 1142
table properties, 1153, 1396 understanding population levels, 1279
table specification syntax, 1197 using the flat VDATA view of the data, 1273
tutorial, 1142 using the hierarchical HDATA view of the data, 1276
understanding the Axis object, 1237 versions, 1454
using in a data management script file, 451 weighting tables, 1169, 1252
using numeric variables, 1172 which view of the data is used, 1272
versions, 1454 working with hierarchical data, 1271, 1276
weighting tables, 1169, 1252 Table scripting in IBM SPSS Data Collection Base
working with Change Tracker, 1469–1470, 1472, 1474 Professional
working with hierarchical data, 1271 what’s new, 2
working with metadata, 1453 Table specification syntax
working with the ADO recordsets, 1265 reference, 1192
working with the hierarchical view of the data, 1276 Tables
working with variables, 1475 adding special elements, 1204
working with variables interface, 1475 creating in a DMS file, 285
Table Object Model (TOM) database questions, 1176
object model documentation , 1557 element list syntax, 1200
reference section, 1557 exporting to Excel, 1187
table population and failover, 1191 exporting to HTML, 1144
Table scripting, 1192 exporting to Word, Excel, and PowerPoint, 1477
about the documentation, 1140 filtering when using HDATA, 1305
axis and element labels, 1463 filtering when using loop slice expressions, 1305
axis expressions, 1536 filters, 1166, 1168
base elements, 1230 frequency, 1149
cell contents, 1149, 1247, 1254 grid, 1174, 1297
creating axis expressions, 1538 grid and loop slices, 1299, 1302
defining special elements, 460 grid tables, 1290
defining table presentation, 1396 hide rules, 1153
defining table structure, 1192 hiding rows, columns, and cells, 1419, 1424, 1428–1429
derived grid tables, 1293 limits, 1555
displaying images in tables, 1405 nesting and concatenation, 1156
exporting tables, 1477 opening an existing table document, 1190
exporting tables and charts to Excel, 1498 population and failover, 1191
exporting tables and charts to HTML, 1478 profile tables, 1443–1444, 1449
exporting tables and charts to Microsoft Word, 1516 rounding of cell contents, 1253
exporting to Microsoft PowerPoint, 1509 setting element properties, 1222
1616
Index
setting the population levels, 1286 progress bars, 842

simple, 1144 sub-templates, 847
sorting, 1407–1408 types of, 826
specification syntax, 1197 using when exporting to Microsoft PowerPoint, 1509
statistical tests, 1178 writing, 828
the base element, 1230 Temporary (Dim’ed) variables
understanding population levels, 1279 displaying values of in interviews, 603
using numeric variables in, 1172 Test, 1114
weighting, 225, 1169, 1252 questionnaire, 66–67, 113
Tabulation Services component Testing
about, 501 interview scripts, 984
Tabulation Services object model, 501 with Auto Answer, 984
Target weighting with the Browser, 984
further examples, 425 TestUseQuota, 1114
general options, 410 TestUseSampleMgmt, 1114
overview, 409 TestVersion, 1114
simple examples, 422 Text, 551
weighting report, 412 adding to axis specification, 1204
Task Scheduler background color, 746
using to schedule DMS files, 294, 296 color, 746
tasks settings, 193 combining settings , 753
Telephone interviewing project parameters, 1024 effects, 751
telephone settings, 152 inserting into labels, 608
Template XML schema size, 750
default, 1131 styles for, 745
templates substituting in DMS files, 250
activation, 117 substituting in DMS Include files, 247
Templates, 1119 typeface, 748
authentication pages, 1039, 1041, 1043 Text effects, 751
automatic completion of data entry fields, 834 Text export
automatic focus on Next button, 841 overview, 1534
banner text placement, 837 properties, 1535
bookmarks, 1527 Text only items, 595
cascading style sheets with, 879 Text questions
case sensitivity in grid templates, 856 analysis specs in interview scripts, 960
clickable response texts, 855 cleaning special responses to, 400
CSS class names in rendered HTML, 856 Text responses
custom controls, 853–855 formatting in interviews, 611
default layout, 827 preventing cross-site scripting in, 728
default styles, 825 Text substitution in question texts, 601
<!doctype> tags in, 878 Text Variables
element IDs in, 847 autocoding in axis specification, 1214
end of interview pages, 1044 TextQuestionsOnly, 1115
error messages for loop/block questions, 836 ThousandsSeparator, 724
example, 1041 Time
external file references in, 851 converting to UTC, 358
for multiple-language projects, 889 Time zones, defining for respondents, 1032
grid, 856, 858–863, 865–866, 868–870, 872, 874–876 TimedOut, 1115
IBM SPSS Data Collection Base Professional, 21 TimeLastActivated , 1116
images in, 851 Timeout, 1116
Javascript in, 851 Timezones, 1024
<meta> tags in, 878 TomVariablesDemo.mrs, 1475
Microsoft Word, 1524–1525 TooFewAnswers, 724
more than one question on a page, 834 TooLittleText, 724
naming in script, 827 TooManyAnswers, 724
navigation buttons, 839 TooManyDecimalPlaces, 724
page titles, 839 TooManyDigits, 724
1617
Index
TooMuchText, 724 Up-lev operator

Top-two elements table scripting, 1192
setting up in interview scripts, 965 Up-leving
Top2-Bottom2 axis, 963 table scripting filters, 1305
Total upload settings, 131
adding to axis specification, 1204, 1210 URLs
weighting to, 422 authentication pages, 1039, 1043
Total awareness variables end of interview pages, 1044
creating in a DMS file, 439 example Web page, 1042
Totals pre-authentication pages, 1042
in interview scripts, 957 usage options, 199
TotalType UseCATI , 1116
example of using, 422 UseDataModel, 1116
tracking studies UseDefaultURLs, 1116
sort options for reusable tables, 1408 UseImageCache, 1116
Tracking Studies, 442 UseInMemoryCache, 1117
Trade-off questions, 696 UseInputAsOutput option
trademarks, 1590 diagram, 234
Translations setting, 264
selecting, 73 UsePlayerNavigation, 1117
selecting when table scripting, 1467 User contexts
Trim working with in IBM SPSS Data Collection Base
data cleaning example, 399 Professional, 56
Triple-S DSC UserN, 1117
and DMS files, 327, 348 UseSampleMgmt, 1118
Triple-S files UTC
using a DMS file to transfer data from, 327 converting to, 358
using a DMS file to transfer data to, 348 UtcNow, current time in UTC format, 1076
Troubleshooting
data management scripting, 1565
Tukey test Validating mode
details and restrictions, 1374 selecting, 76
diagnostics information, 1384 Validation
example, 1372 grids containing more than one question, 735
overview, 1372 Validation function, 731
statistical formula, 1375 validation options, 200
Tutorials Validation options
table scripting, 1142 DMS files, 336
Typeface for text, 748 variables, 1475
Variables
adding categories to, 442
unbounded loops, 626 creating in a DMS file, 433
Uncomment selection, 21 filtering in data management scripting, 243
Union operator total awareness, 439
example of use in interview scripts, 685 using in tables, 1144
Untabify selection, 21 variables interface, 1475
Unweighted base Variance
adding to axis specification, 1204 showing in tables, 1172
Unweighted base elements VBScript
examples, 1169 and sample management, 1008
overview, 1233 examples of using Weight component, 417
property for suppressing the automatic creation, 1396 VDATA
Unweighted counts switching to HDATA in table script, 1272
showing in cells of table, 1247, 1254 using the VDATA view in table scripting, 1273
Unweighted total Version, 1118
weighting to, 422 Versions, 1459
unzipped project templates, 25 listing and comparing, 364
selecting, 73–74
1618
Index
selecting in WinDMSRun, 303 table scripting in IBM SPSS Data Collection Base
table scripting, 1454 Professional, 2
working with in a DMS file, 360–362 table scripting samples in IBM SPSS Data Collection
Visual Basic Base Professional, 2
data management, 1584 While...End While, 671
Visual Basic .NET WinDMSRun
samples, 309 as programmer’s reference, 309
case selection, 305
FAQs, 1583
wave studies Input Data tab, 307
sort options for reusable tables, 1408 Normal tab, 302
web browser Output Data tab, 308
using external browser in IBM SPSS Data Collection Script tab, 306
Base Professional, 60 selecting versions, 303
WebCallbackDelay, 1024 starting, 301
WebPredefinedQueues, 1011 using, 300
WeekDayEnd, 1024 variable selection, 305
WeekdayStart, 1024 Windows Task Scheduler
WeekendEnd, 1024 using to schedule DMS files, 294, 296
WeekendStart, 1024 With, 674
Weight component With statement
about, 503 table scripting, 1192
examples, 417 Word
general options, 410 DMS files that integrate with, 475
limits, 1579 exporting tables to Word, 1477
overview, 406 Word tables export
report, 412 defining the positions of the tables etc., 1527
troubleshooting, 1579 formatting, 1523
Weight variable interactive mode, 1522
including in an axis specification, 1222 overview, 1516
Weighting properties, 1518
base elements, 1233 styles, 1527, 1529, 1533
compared to IBM SPSS Statistics, 1393 templates, 1524–1525
examples, 417 Workspaces
factor, 408 IBM SPSS Data Collection Base Professional, 27
general options, 410 Writing questions, 539
getting started with, 222
matrix, 408
overview, 406 XML CDSC
report, 226, 411–412 and DMS files, 332
rim, 409 using with a DMS file to transfer data, 351
rim formulae, 415 view of data when scripting tables, 1272
rim options, 411
setting up in a data management script, 454
statistical tests, 1388–1389 Year, 657
tables, 1169, 1252
target, 409 Zero values, 1153
troubleshooting, 1579
Weighting matrix
overview, 408
What is an interview script, 522
What’s new
data management samples, 2
data management scripting, 2
IBM SPSS Data Collection Base Professional, 2
interview scripting in IBM SPSS Data Collection Base
Professional, 2
Sample Management, 992

Ibm Base Professional 6.0.1 User Guide PDF

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Ibm Base Professional 6.0.1 User Guide PDF

Încărcat de

Drepturi de autor:

Formate disponibile

i

IBM SPSS Data Collection Base

Licensed Materials - Property of IBM

Licensed Materials - Property of IBM © Copyright IBM Corporation 2000, 2011

Licensed Materials - Property of IBM © Copyright IBM Corporation 2000, 2011

About IBM Business Analytics

Licensed Materials - Property of IBM © iii

Two additional options are available for Base Professional:

Licensed Materials - Property of IBM © Copyright 1

What’s new in IBM SPSS Data Collection Base Professional 6.0.1

Refer to and for more information.

Census.mdd hierarchical data example. The new Census.mdd hierarchical

Table Scripting Samples

Creating Your First mrScriptBasic Script

This opens the New File dialog box.

E In the main Edit pane, type the following:

This inserts the name of the function into the script.

E Now type the opening parenthesis: (

E Type the parameter and the closing parenthesis: "MDM.Document")

E From the list, double-click the Open method.

This inserts the method into your script.

E Enter the following:

Dim FSO, MyTextFile

Set FSO = CreateObject("Scripting.FileSystemObject")

E From the Tools menu, choose Macros:

This opens the AutoExpansion Macros dialog box.

E Click on the mrScriptBasic tab.

E In the Macro Text text box, type the following:

For Each {0} In {1}

This adds the macro to the list of mrScriptBasic macros.

Now we will use the macro in our script.

E Now type Ctrl+M.

For Each MyVariableInstance In MDM.Variables

Using IBM SPSS Data Collection Base Professional

Which File Types Can I Work With?

The IBM SPSS Data Collection Base Professional Window

Tab Pane Description

Replace Use to search for text and replace

Tab Pane Description

Changing the Layout of the Window

Restoring the Default Layout

Creating Layouts for Different Tasks

Viewing Large or Multiple Files

Viewing Different Parts of a File Simultaneously

The following picture shows an example of using this feature.

Viewing Multiple Files Simultaneously

Working with Advanced Editing Options

Advanced Option Description

Working with Templates

1. From the File menu, choose:

2. From the File menu, choose Save As.

E To edit an existing template:

1. From the File menu, choose:

5. Edit and save the file in the normal way.

Creating and Saving Project Templates

Creating a new questionnaire from a template

E From the menu, choose:

E Select the template you want to use.

Saving a questionnaire as a project template

E From the menu, choose:

E Select the file extension .ptz.

E Enter a name for the file and choose Save.

Editing an existing project template

For Author: [INSTALL_FOLDER]\IBM\SPSS\DataCollection\6\\Author\Author.exe.config