company logo

Property :: openExtern - Open property handle for external file

In order to access data in external files, those might be opened as property handles. The data type for instances managed by the property handle might be passed within the data file (e.h. head line in a CSV file), as separated data definition file (e.g. ODL data definition) or the function may refer to a data type defined in the dictionary.

Directories, binary or ANSI files with different formats can be accessed via property handle. Data in ANSI files might be passed in CSV (comma separates file), ESDF (extended self delimiter file), OIF (object interchange format) or XML.

When the property handle is already opened, the current cursor will be released and a new cursor will be created.

The function throws an exception, when the object space handle is not valid or an error occurred while trying to access the external file.
Return value:  Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Implementation details

  1. Extended file open
    odaba::Property & Property  :: openExtern ( odaba::ObjectSpace &cObjectSpace, odaba::String &sFilePath, odaba::String &sFileDefinition, odaba::String &sFileType, odaba::AccessModes eAccessMode, bool bHeadline )

    Property handles for external files may be opened via predefined extents. Accessing external data files via extent definitions requires a complex data type definition for the file in the database schema and does not support external file definitions or head lines. Thus, It is, more flexible accessing incoming data directly without defining structure and extent in a dictionary. This kind of ad hoc collections can be attached to the object space passed in cObjectSpace.

    The file location is passed in sFilePath. When the file type is not defined by the extension, it must be passed explicitly in sFileType. Otherwise, sFileType might be empty.

    Since some external file types do not support self describing data formats, the file schema can be passed in a separate definition file. The file location for the definition file can be passed in sDefinitionFile. When no external file definition is required, an empty string can be passed, instead. The definition file format need not to correspond to the file format, e.g. one may provide an ODL definition for a CSV file.

    OIF or ESDF support inline file schema definition on the first line. The default headline for CSV files is a sufficient file schema definition in many cases. In order to indicate, that an inline file definition is provided, bHeadline should be set to true. Head lines are allowed for CSV and ESDF, only.

    In order to create an external file, write has to be passed in eAccessMode.
    • cObjectSpace - Object space reference

      The reference refers to an opened or not opened object space handle.
    • sFilePath - Complete file path
    • sFileDefinition - File definition for external data

      When external file definition is not part of the data file, the file definition may be passed as external file definition (file name) or as complex data type name defined in the dictionary (e.g. "xml::Person"). When the name passed does nor refer to a valid file location, is is checked as complex data type name in the dictionary. Referring to a file name, the following file definitions types may be passed:

          .odl - ODABA schema definition

          .csv, .esdf - (extended) comma separated variables

          .xml - XML schema with ODABA attribute extensions
    • sFileType - File type

      ODABA supports different external file types, which might be accessed directly via property handle. File types supported are:

      • bina - binary flat file (.bina)
      • csv, esdf - extended self delimiter file (.esdf, .csv)
      • oxml - ODABA xml file (.oxml, .xml)
      • oif - object interchange format (.oif)

      In order to pass no file type, an empty string ( String() ) has to be passed. In this case, the file type is usually extracted from the file extension.

    • eAccessMode - Access mode

      Access mode for a property handle or database.
    • bHeadline - Head line option

      OIF and ESDF files may provide a headline, which carries structure definition details for the data contained in the file. When the file contains a headline, the structure definition (especially field names) are extracted from the headline and the second line or record is considered as data record.

      The structure for the headline depends on the file type and is described in the corresponding file type documentation (ESDF/CSV or OIF documentation).
    2. to list
  2. Open file by extension
    odaba::Property & Property  :: openExtern ( odaba::ObjectSpace &cObjectSpace, odaba::String &sFilePath, odaba::String &sFileDefinition, odaba::String &sFileType, odaba::AccessModes eAccessMode, bool bHeadline, odaba::StringCodingTypes eStringCodingType )

    When the file to be read follows common conventions as described below, it might be opened simply by referring to the file name passed in sFilePath. Data in the file must be preceded by a head line or definition section containing at least the field names. The definition section may, however, also contains an extended definition as described in the ESDF data definition format. OIF files must contain a preceding data definition section (ODL). Only CSV, ESDF and OIF are supported by this function, since other file formats do not support inline definition.

    The file extension should refer to the file type (.csv, .esdf or .oif). When this is not the case, the file type is determined by the file content according to the following rules:

    Files which are structured as

    SCHEMA name ... { type definition }DATA { data records }

    are considered as OIF files. Since the file may contain nested data types, the name must refer to the main data type, i.e. the data type of the collection. Files with the following structure:

    { type definition } { record 1 } ... { record n }

    are considered as ESDF files. In the type definition any of the field separators ';' ',''|' or '\t' (tab) is allowed. The first field separator found is considered as field separator for the subsequent data. For ESDF files, ; is suggested as field separator.

    Any other files not starting with SCHEMA key word or '{' are considered as CSV files. Also for CSV files any of the field separators ';' '|' or '\t' (tab) might be used. The first of those characters found in the head line is considered as field separator for the file.

    In order to open a property handle for the file, an open object space has to be passed passed in cObjectSpace. Write access to external files is not supported by this function.

    When the text file to be processed is not encoded according to the coding type defined in DefaultEncoding option, the coding type is passed in eStringCodingType.
    • cObjectSpace - Object space reference

      The reference refers to an opened or not opened object space handle.
    • sFilePath - Complete file path
    • sFileDefinition - File definition for external data

      When external file definition is not part of the data file, the file definition may be passed as external file definition (file name) or as complex data type name defined in the dictionary (e.g. "xml::Person"). When the name passed does nor refer to a valid file location, is is checked as complex data type name in the dictionary. Referring to a file name, the following file definitions types may be passed:

          .odl - ODABA schema definition

          .csv, .esdf - (extended) comma separated variables

          .xml - XML schema with ODABA attribute extensions
    • sFileType - File type

      ODABA supports different external file types, which might be accessed directly via property handle. File types supported are:

      • bina - binary flat file (.bina)
      • csv, esdf - extended self delimiter file (.esdf, .csv)
      • oxml - ODABA xml file (.oxml, .xml)
      • oif - object interchange format (.oif)

      In order to pass no file type, an empty string ( String() ) has to be passed. In this case, the file type is usually extracted from the file extension.

    • eAccessMode - Access mode

      Access mode for a property handle or database.
    • bHeadline - Head line option

      OIF and ESDF files may provide a headline, which carries structure definition details for the data contained in the file. When the file contains a headline, the structure definition (especially field names) are extracted from the headline and the second line or record is considered as data record.

      The structure for the headline depends on the file type and is described in the corresponding file type documentation (ESDF/CSV or OIF documentation).
    • eStringCodingType - String encoding type

      In case of unknown text encoding type undefinedCoding is used.
    3. to list
  3. Open file by extension
    odaba::Property & Property  :: openExtern ( odaba::ObjectSpace &cObjectSpace, odaba::String &sFilePath )

    When the file to be read follows common conventions as described below, it might be opened simply by referring to the file name passed in sFilePath. Data in the file must be preceded by a head line or definition section containing at least the field names. The definition section may, however, also contains an extended definition as described in the ESDF data definition format. OIF files must contain a preceding data definition section (ODL). Only CSV, ESDF and OIF are supported by this function, since other file formats do not support inline definition.

    The file extension should refer to the file type (.csv, .esdf or .oif). When this is not the case, the file type is determined by the file content according to the following rules:

    Files which are structured as

    SCHEMA name ... { type definition }DATA { data records }

    are considered as OIF files. Since the file may contain nested data types, the name must refer to the main data type, i.e. the data type of the collection. Files with the following structure:

    { type definition } { record 1 } ... { record n }

    are considered as ESDF files. In the type definition any of the field separators ';' ',''|' or '\t' (tab) is allowed. The first field separator found is considered as field separator for the subsequent data. For ESDF files, ; is suggested as field separator.

    Any other files not starting with SCHEMA key word or '{' are considered as CSV files. Also for CSV files any of the field separators ';' '|' or '\t' (tab) might be used. The first of those characters found in the head line is considered as field separator for the file.

    In order to open a property handle for the file, an open object space has to be passed passed in cObjectSpace. Write access to external files is not supported by this function.
    • cObjectSpace - Object space reference

      The reference refers to an opened or not opened object space handle.
    • sFilePath - Complete file path
    4. to list
  4. Open file with dictionary type definition
    odaba::Property & Property  :: openExtern ( odaba::ObjectSpace &cObjectSpace, odaba::String &sFilePath, odaba::String &sTypeName, odaba::AccessModes eAccessMode )

    In order to open external files that do not contain a file description, the file structure (field names, at least) might be defined as complex data type in the dictionary. In order to open an external file, the type name has to be passed in sTypeName. The file path is passed in sFilePath. The function supports ANSI file formats CSV, ESDF, OIF and XML.

    The file extension should refer to the file type (.csv, .esdf, .oif or .xml). When this is not the case, the file type is determined by the file content according to the following rules:

    Files beginning which are structured as

    DATA { data records }

    are considered as OIF files. Files beginning with '(' or '{' after any number of spaces:

    ( { record 1 } ... { record n } )

    are considered as ESDF files. Files beginning with an xml tag after any number of spaces are considered as XML files:

    • <?xml version ...

    Any other file is supposed to be a CSV files. Field separator for CSV and ESDF is ';'. Alternate field separators might be defined in the complex data type definition.

    In order to open a property handle for the file, an open object space has to be passed passed in cObjectSpace. In order to write data to an external file, Write has to be passed in aAccessMode.
    • cObjectSpace - Object space reference

      The reference refers to an opened or not opened object space handle.
    • sFilePath - Complete file path
    • sTypeName - Type name

      The type name is the name of a data type (usually) defined in the database. The type name might be passed as simple identifier or as scoped name with preceding namespace names separated by double colon '::'.

      In order to pass no type name, an empty string ( String() ) may be passed.
    • eAccessMode - Access mode

      Access mode for a property handle or database.
    5. to list
to top previous next upper table of contents Comment