SPSS Data File Input/Output API

SPSS Data File Input/Output API

August 28, 1998

The data file I/O API provides a mechanism for reading and writing SPSS data files in user-developed programs. It was originally distributed as part of the SPSS 6.1 for Windows Developer's Kit, and it is documented in the manual which accompanied that product. An updated version of that manual is included in the SPSS 8.0 distribution materials as ioapi.pdf, which, as the extension suggests, is in Adobe Acrobat format.

The following section lists the updates that have been made to the File I/O API since its initial release. Full documentation for the features added through Release 8.0 may be found in the aforementioned manual.

Additions since 8.0

Since release 8.0, the I/O DLL has been made minimally compatible with the 32 bit Borland C++ compiler, and five functions have been added to the API.

Borland C++ users can use release 8.0.1 and later of spssio32.dll and the associated spssdio.h.  They cannot, however, use the distributed spssio32.lib.  It is necessary to generate an import library from the distributed DLL using the implib.exe console application which comes with the compiler using the following syntax:

    implib –w spssio32.lib spssio32.dll

The -w switch suppresses almost 100 warnings like the following:

    Warning duplicate symbol: spssCloseAppend

The new API functions include two for defining multiple response sets, one for querying the presence of specific “type 7” records on an existing SPSS data file, and two for dealing with a uniqueness indicator for the Data Entry for Windows information.  The two functions related to multiple response sets are more convenient and much less prone to error than spssSetMultRespDefs.

int spssAddMultRespDefC(
    int handle,
    const char *mrSetName,
    const char *mrSetLabel,
    int isDichotomy,
    const char *countedValue,
    const char **varNames,
    int numVars)

This function adds a multiple response set definition over short string variables to the dictionary.

Parameter                                          Description

handle                     Handle to the data file

mrSetName                                        Name of the multiple response set. A null-terminated string up to seven characters long but otherwise obeying the rules for a valid variable name. Case is immaterial.

mrSetLabel                                      Label for the multiple response set. A null-terminated string up to 60 characters long; only the first 60 characters are used if longer. May be NULL or the empty string to indicate no label is desired.

isDichotomy                                    Nonzero if the variables in the set are coded as dichotomies, zero otherwise.

countedValue                                  A null-terminated string containing the counted value. Necessary when isDichotomy is nonzero, in which case it must be 1–8 characters long, and ignored otherwise. May be NULL if isDichotomy is zero.

varNames                                          Array of null-terminated strings containing the names of the variables in the set. All variables in the list must be short strings. Case is immaterial.

numVars                                             Number of variables in the list (in varNames). Must be at least two.

If all goes well, adds the multiple response set to the dictionary and returns zero (SPSS_OK) or negative (a warning). Otherwise, returns a positive error code and does not add anything to the multiple response sets already defined, if any.

Error Code                                         Description

SPSS_OK                    No error

SPSS_EXC_LEN60             Only the first 60 characters of the label were used (warning)

SPSS_INVALID_HANDLE        The file handle is not valid

SPSS_OPEN_RDMODE           The file is open for input or append

SPSS_DICT_COMMIT           spssCommitHeader has already been called

SPSS_NO_VARIABLES          Fewer than two variables in list

SPSS_ EXC_STRVALUE         isDichotomy is nonzero and countedValue is NULL, empty, or longer than 8 characters

SPSS_INVALID_MRSETNAME     The multiple response set name is invalid

SPSS_DUP_MRSETNAME         The multiple response set name is a duplicate

SPSS_INVALID_MRSETDEF      Existing multiple response set definitions are invalid