Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Reference for Simple Datatype Classes

Caché uses a set of special classes for literal datatypes (containing simple data such as strings or numbers). See Data Types in Using Caché Objects for information about how datatype classes differ from standard object classes.

Every Caché data type is mapped to an appropriate C++ object, such as d_int or d_string. If a literal type instance is not null, it is possible to convert it to a standard C++ type: d_int can be converted to int, d_string to std::string or std::wstring, d_time, d_date, and d_timestamp to tm. The C++ object that represents a Caché datatype is determined via the CLIENTDATATYPE keyword value of the datatype class.

All simple types have:

  • Conversion operators that makes it possible to use them as C++ types. For example, d_int can be converted to int and d_double to double.

  • A value() method (for use in templates).

  • make_null() and is_null() methods.

  • An overloaded "<<" operator for output streams.

  • An overloaded "=" operator.

The following datatypes are supported:

  • Numeric — d_bool, d_int, d_double, d_numeric, d_decimal, and d_currency.

  • Binaryd_binary, d_longbinary, d_oid, d_status, d_string, and d_list.

  • Wide Strings — d_wstring, d_id, d_longwstring, and d_longstring.

  • Date and Time — d_date, d_timestamp, and d_timestamp.

Numeric Classes

These are simple numbers.

Class InterSystems::d_int

A d_int can be converted to int and be assigned an int. It doesn't have other overloaded operators. The intended usage is to get the int value and assign a changed value back to the object if the object should be changed. For example,

   d_int t = 2;
   d_int q = int(t) + 2;

in many cases like this one the conversion is implicit, so the second line can be just

   d_int q = t + 2;

but there are cases where it is necessary.

Binary Classes

These are classes containing variable-length binary data.

Class InterSystems::d_binary

A d_binary holds binary data. d_oid is a typedef of d_binary that represents a complete Object ID.

Member list

  • d_binary constructors

    • No parameters.

         d_binary();
    • From null terminated string

         d_binary(const char* cstr);
    • From std::string

         d_binary(const std::string& s);
    • From string of size sz, starting at cstr

         d_binary(const char* cstr, int sz);
  • std::string() operator — Return the data as std::string

       operator std::string() const;
  • Comparison operators — Compare to another d_binary

       bool operator==(const d_binary& t);
       bool operator!=(const d_binary& t);
  • append_bin() — Append binary data

       void append_bin(const char* buf, byte_size_t size);
  • assign() — Assign binary data

       void assign(const char* buf, byte_size_t size);
  • get_buf() — Get the address of the binary buffer

       const char* get_buf() const;
  • get_size() — Get the size of the binary buffer

       long get_size() const;

Class InterSystems::d_status

A d_status encapsulates %Library.Status. It should be used only for interpreting a status from the server.

Member list

  • operator int() — Convert to int with the value of the error code

       operator int() const;
  • get_code() — Get the error code (returns 0 if no error)

       int get_code() const;
  • get_msg() — Get the error message

       const d_string& get_msg() const;
  • get_from_srv() — Analyze the status on the server with potential translation of the message to language lang (if it's a system error)

       void get_from_srv(Database* db, const char* lang = "", Db_err* err = 0);
  • throw_err() — Throw a Db_err with the code and the message of the error

       void throw_err() const;

Class InterSystems::d_string

A d_string holds string data. It differs from d_binary in that it automatically converts data when necessary and also provides conversion methods.

Member list

  • d_string constructors

    • No parameters.

         d_string();
      
    • From null terminated string or wide null terminated string

         d_string(const char* cstr);
         d_string(const wchar_t* cstr);
    • From std::string or std::wstring

         d_string(const std::string& s);
         d_string(const std::wstring& s);
    • From string or wide string of size sz, starting at cstr

         d_string(const char* cstr, int sz);
         d_string(const wchar_t* cstr, int sz);
  • is_unicode() — Test whether the string is in unicode format

       bool is_unicode() const;
  • to_mb() — Convert to multibyte.

    • in buffer buf of capacity cap, return the number of bytes put in buf.

         byte_size_t to_mb(char* buf, char_size_t cap) const;
    • Convert to multibyte in place

         void to_mb();
  • to_uni() — Convert to unicode.

    • Store the result in buffer buf of capacity cap, return the number of characters put in buf

         char_size_t to_uni(wchar_t* buf, char_size_t cap) const;
    • Convert to unicode in place

         void to_uni();
  • std::string() operator — Convert to std::string or std::wstring.

       operator std::string() const;
       operator std::wstring() const;
  • Comparison operators — Compare to another d_string

       bool operator==(const d_string& val) const;
       bool operator!=(const d_string& val) const;
       bool operator<(const d_string& val) const;
  • assign()

    • From null terminated string or wide null terminated string.

         void assign(const char* buf);
         void assign(const wchar_t* buf);
    • From string or wide string of size sz, starting at cstr

         void assign(const char* buf, char_size_t size);
         void assign(const wchar_t* buf, char_size_t size);

Class InterSystems::d_list

A d_list object is a C++ implementation of the $list structure in Caché. In addition to its standard methods, the d_list class has a set of static methods that allow you to extract data from a buffer containing a $list without copying it into a d_list object.

d_list methods

A d_list object is essentially a forward iterator, but it also provides methods for inserting, deleting and replacing an element at the current position, as well as other methods that work with $list as a whole. A d_list position is 0 based. Since $list is stored in contiguous memory, any operation that changes a $list element may cause a dynamic memory reallocation or copying, which may be expensive.

Member list

  • d_list()

       d_list(const char* buf, byte_size_t size)
  • append_elem()

       void append_elem(__int64 val); 
       void append_elem(double val); 
       void append_elem(const d_string& val); 
       void append_elem(const d_binary& val); 
       void append_elem(const wchar_t* p, char_size_t size); 
       void append_elem(const char* p, char_size_t size);
  • append_elem_null()

       void append_elem_null();
  • at_end()

       bool at_end() const;
  • clear() — Delete all elements

       void clear();
  • count() — Count the number of elements

       int count();
  • del_elem() — Delete the current element

       void del_elem();
  • elem_null()

       void ins_elem_null();
  • get_elem()

       void get_elem(__int64* val) const; 
       void get_elem(double* val) const; 
       void get_elem(d_string& val) const; 
       void get_elem(d_binary& val) const; 
       void get_elem(bool* is_uni, const char** p_buf, 
          byte_size_t* p_size) const;
  • get_elem_idx() — Get the index of the current element

       int get_elem_idx() const;
  • get_elem_type()

       char get_elem_type() const;
  • ins_elem()

       void ins_elem(__int64 val); 
       void ins_elem(double val); 
       void ins_elem(const d_string& val); 
       void ins_elem(const d_binary& val); 
       void ins_elem(const wchar_t* p, char_size_t size); 
       void ins_elem(const char* p, char_size_t size);
  • is_elem_double()

       bool is_elem_double() const;
  • is_elem_int()

       bool is_elem_int() const;
  • is_elem_null()

       bool is_elem_null() const;
  • is_elem_str()

       bool is_elem_str() const;
  • move_to() — Change the current position to idx (0 based)

       void move_to(int idx) const;
  • move_to_front() — Same as move_to(0) but optimized

       void move_to_front() const;
  • next() — Similar to move_to(), but optimized for moving to the next element

       void next() const;
  • reset() — Reset the buffer

       void reset(const char* buf, byte_size_t size);
  • set_elem()

       void set_elem(__int64 val); 
       void set_elem(double val); 
       void set_elem(const d_string& val); 
       void set_elem(const d_binary& val); 
       void set_elem(const wchar_t* p, char_size_t size); 
       void set_elem(const char* p, char_size_t size);
  • set_elem_null()

       void set_elem_null();

d_list static member functions

The static member functions allow you to extract data from a buffer that is a $list without copying it into a d_list object. The interface deals with the $list element specified by the buffer. The next element starts at buffer + d_list::get_elem_size(buffer).

Member list

  • get_elem() — Get an element

    • Get an element as _int64, double, d_string, or d_binary.

         static void get_elem(const char* buf, __int64* val);
         static void get_elem(const char* buf, double* val);
         static void get_elem(const char* buf, d_string& val);
         static void get_elem(const char* buf, d_binary& val);
    • Get an element as a pointer to the string, the string size, and find whether it's unicode or narrow

         static void get_elem(const char* buf, bool* is_uni, 
            const char** p_buf, byte_size_t* p_size);
  • get_elem_size() — Get element size

       static byte_size_t get_elem_size(const char* buf);
  • is_elem_double() — Test whether an element is stored as double

       static bool is_elem_double(const char* buf);
  • is_elem_int() — Test whether an element is stored as int

       static bool is_elem_int(const char* buf);
  • is_elem_null() — Test whether an element is null

       static bool is_elem_null(const char* buf);
  • is_elem_str() — Test whether an element is stored as string

       static bool is_elem_str(const char* buf);

Time and Date Classes

Objects of these types can be converted to a tm structure object with all irrelevant values set to -1. They can also be assigned a tm object. The irrelevant values from the tm structure will be ignored. Interfaces of these classes differ only in constructors and assignment operators.

Class InterSystems::d_time

Member list

  • d_time

    • From tm

         d_time(const tm& ts);
    • From ODBC structure for time

         d_time(const TIME_STRUCT& t);
    • From hour, minute, second

         d_time(int h, int m, int s);
    • From ODBC structure for time

         d_time& operator=(const TIME_STRUCT& t);

Class InterSystems::d_date

Member list

  • d_date

    • From tm

         d_date(const tm& ts);
    • From ODBC structure for date

         d_date(const DATE_STRUCT& d);
    • From year, month, day

         d_date(int y, int m, int d);
    • From ODBC structure for date

         d_date& operator=(const DATE_STRUCT& d);

Class InterSystems::d_timestamp

Member list

  • d_timestamp

    • From tm

         d_timestamp(const tm& ts);
    • From ODBC structure for timestamp

         d_timestamp(const TIMESTAMP_STRUCT& ts);
Feedback