d = CS.Data.open(connection := ... ‖ name := ...
ʃ, dictionary := ...ʅ
ʃ, openFlags := ...ʅ) | Argument | Description | Types / Required |
|---|
| connection | The data connection string specifying the data source. | string, object
not required |
| name | The name of a dictionary associated with an application. | string
not required |
| dictionary | The dictionary that describes the data source's cases. | string, object
not required |
| openFlags | Flags to control how the data source is opened.
The default value is "read". | string
not required |
Either connection or name must be specified, with connection used for data sources that are not already connected to an application.
This action is similar to the CSPro
logic function
setfile. When using actions, multiple data sources associated with the same dictionary can be opened, whereas using CSPro logic, there is only one dictionary-based data source per call to
setfile.
If specifying name, the action connects to a data source that is connected to a dictionary that is part of an application. The access permissions and dictionary used by the application to open the data source are inherited, so the openFlags and dictionary arguments are ignored. For example, this code would create a connection to the data source associated with the dictionary named CORRUPTION_DICT:
The data source associated with the dictionary is evaluated every time the data resource ID is used, so if the application's data source changes, the resource ID will always refer to the current data source identified by the dictionary name.
If working with application dictionaries, you can "open" them as detailed, or you can simply use the dictionary name as the resource ID for other actions. For example, these two approaches are equivalent:
If specifying
connection, the action will open a data source that is not already open as part of an application's dictionaries. The argument
connection is a
data connection string, generally a path identifying a data file. Connection strings can be specified as a single string or as an object (with the rules for each
described here). Details about properties specific to each data source are available on the documentation describing each of the
data sources.
The openFlags argument controls how the data source is opened and can be one of the following:
- "read": The data source is opened in read-only mode, with an error occurring if the data source does not exist. Actions such as Data.writeCase will fail in this mode.
- "readWrite": The data source is opened in read and write mode, with an error occurring if the data source does not exist.
- "readWriteCreate": The data source is opened in read and write mode, with a new data source created if it does not already exist.
- "readWriteTruncate": The data source is opened in read and write mode, with all cases deleted from the data source if it already exists. If the data source does not exist, it is created. Deleting cases cannot be undone so be careful using this mode.
When opening an existing data source that has an embedded dictionary (e.g., a
CSPro DB data source), it is not necessary to specify the dictionary that describes the data source's cases, as the embedded dictionary will be used when processing cases. However, if creating a new data source, or opening a data source without an embedded dictionary (e.g., a
Text data source), you must specify the dictionary. The argument dictionary is determined as follows:
- If the connection string contains a "dictionaryPath" property, the dictionary will be read from the disk, evaluated relative to the path of the data source.
- If dictionary is an object, it is parsed as the JSON representation of a dictionary.
- If dictionary is a string that matches the name of an application dictionary, that dictionary is used.
- Otherwise, dictionary is parsed as a string with a file path identifying a dictionary on the disk.
The action returns a numeric
resource ID that is used to identify this data source in calls to future
Data actions.
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The data source does not exist when opening in a mode that requires an existing data source.
- The data source does not have an embedded dictionary and a dictionary is not specified.
- There is an error opening, creating, or otherwise connecting to the data source.
let dataId;
try {
// open the Popstan Census example data
dataId = CS.Data.open({
connection: "Popstan Census.csdb"
});
// display the number of cases
const numCases = CS.Data.countCases({
dataId: dataId
});
print(`Popstan Census contains ${numCases} cases.`);
}
catch (error) {
print("Error interacting with data source: " + error);
}
finally {
// close the data source
if( dataId != undefined ) {
CS.Data.close({
dataId: dataId
});
}
}
In an application with a dictionary CORRUPTION_DICT, statements like this might result in a similar result:
// access the data source currently associated with the application's CORRUPTION_DICT dictionary
CS.Data.open(name := "CORRUPTION_DICT");
// open a text data source using the application's CORRUPTION_DICT dictionary
CS.Data.open(connection := "data/justice.dat", dictionary := "CORRUPTION_DICT");
// open a text data source specifying the file path of the dictionary
CS.Data.open(connection := "data/justice.dat", dictionary := "dicts/corruption.dcf");
// open a text data source specifying the file path of the dictionary in the connection string
CS.Data.open(connection := "data/justice.dat|dictionaryPath=../dicts/corruption.dcf");
// open a text data source specifying the dictionary contents in JSON format
string dcfJson = CS.File.readText(path := "dicts/corruption.dcf");
CS.Data.open(connection := "data/justice.csdb", dictionary := @object dcfJson);