Using include files in the DMS file

Desktop User Guides > Professional > Data management scripting > Data Management Script (DMS) file > Using include files in the DMS file

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.

Syntax

#include "<filename>"

Parameter

The path and name of the file to include. Typically this is a text file with a .dms filename extension.

Notes

▪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. Example of using Include statements 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 might result in misleading line numbers in these error messages because the line numbers are calculated using the expanded file. However, you can use the /a: option for DMS Runner (see DMS Runner 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 Sample DMS files that integrate with Microsoft Office.

▪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. For more information, see #include.

Example of using Include statements

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:

InputDataSource(myInputDataSource)
  ConnectionString = "Provider=mrOleDB.Provider.2; _
    Data Source=mrDataFileDsc; _
    Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\<version>\DDL\Data\Data Collection File\
        museum.ddf; _
    Initial Catalog=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\<version>\DDL\Data\Data Collection File\
        museum.mdd"#Include ".\Include\Include1.dms"
End InputDataSource

OutputDataSource(myOutputDataSource)
  ConnectionString = "Provider=mrOleDB.Provider.2; _
    Data Source=mrDataFileDsc; _
    Location=[INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\DDL\
        Output\IncludeExample.ddf"
  MetaDataOutputName =
       "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\DDL\
       Output\IncludeExample.mdd"
End OutputDataSource

#define srvar museums
#define textvar address
#Include ".\Include\Include2.dms"

Here is the contents of include1.dms:

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

Here is the contents of the expanded file created using the /a: option of DMS Runner. The “srvar” and “textvar” text in include2.dms have been replaced by “museums” and “address” respectively:

InputDatasource(myInputDataSource)
  ConnectionString = _
  "Provider=mrOleDB.Provider.2; _
  Data Source=mrDataFileDsc; _
  Location=
      [INSTALL_FOLDER]\IBM\SPSS\DataCollection\<version>\DDL\Data\Data Collection File\ museum.ddf; _
  Initial Catalog=
      [INSTALL_FOLDER]\IBM\SPSS\DataCollection\<version>\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; _
    Data Source=mrDataFileDsc; _
    Location=
        [INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\DDL\ Output\IncludeExample.ddf"
  MetaDataOutputName =
     "[INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\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."
     DataCleaning.Status = {NeedsReview}
  End If
  Dim TextLength
  TextLength = Len(address.Trim())
  If TextLength > 90 Then
    address = Left(TextLength, 90)
  End If
End Event

The files in this example are provided as sample DMS files (called IncludeExample.dms, Include1.dms, and Include2.dms) that are installed with the UNICOM Intelligence Developer Documentation Library. For more information, see Sample DMS files.

See

Data Management Script (DMS) file