Skip to main content
Previous section   Next section

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;
Copy code to clipboard

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

   d_int q = t + 2;
Copy code to clipboard

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();
      Copy code to clipboard
    • From null terminated string

         d_binary(const char* cstr);
      Copy code to clipboard
    • From std::string

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

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

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

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

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

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

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

       long get_size() const;
    Copy code to clipboard

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;
    Copy code to clipboard
  • get_code() — Get the error code (returns 0 if no error)

       int get_code() const;
    Copy code to clipboard
  • get_msg() — Get the error message

       const d_string& get_msg() const;
    Copy code to clipboard
  • 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);
    Copy code to clipboard
  • throw_err() — Throw a Db_err with the code and the message of the error

       void throw_err() const;
    Copy code to clipboard

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();
      
      Copy code to clipboard
    • From null terminated string or wide null terminated string

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

         d_string(const std::string& s);
         d_string(const std::wstring& s);
      Copy code to clipboard
    • 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);
      Copy code to clipboard
  • is_unicode() — Test whether the string is in unicode format

       bool is_unicode() const;
    Copy code to clipboard
  • 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;
      Copy code to clipboard
    • Convert to multibyte in place

         void to_mb();
      Copy code to clipboard
  • 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;
      Copy code to clipboard
    • Convert to unicode in place

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

       operator std::string() const;
       operator std::wstring() const;
    Copy code to clipboard
  • 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;
    Copy code to clipboard
  • assign()

    • From null terminated string or wide null terminated string.

         void assign(const char* buf);
         void assign(const wchar_t* buf);
      Copy code to clipboard
    • 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);
      Copy code to clipboard

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)
    Copy code to clipboard
  • 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);
    Copy code to clipboard
  • append_elem_null()

       void append_elem_null();
    Copy code to clipboard
  • at_end()

       bool at_end() const;
    Copy code to clipboard
  • clear() — Delete all elements

       void clear();
    Copy code to clipboard
  • count() — Count the number of elements

       int count();
    Copy code to clipboard
  • del_elem() — Delete the current element

       void del_elem();
    Copy code to clipboard
  • elem_null()

       void ins_elem_null();
    Copy code to clipboard
  • 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;
    Copy code to clipboard
  • get_elem_idx() — Get the index of the current element

       int get_elem_idx() const;
    Copy code to clipboard
  • get_elem_type()

       char get_elem_type() const;
    Copy code to clipboard
  • 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);
    Copy code to clipboard
  • is_elem_double()

       bool is_elem_double() const;
    Copy code to clipboard
  • is_elem_int()

       bool is_elem_int() const;
    Copy code to clipboard
  • is_elem_null()

       bool is_elem_null() const;
    Copy code to clipboard
  • is_elem_str()

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

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

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

       void next() const;
    Copy code to clipboard
  • reset() — Reset the buffer

       void reset(const char* buf, byte_size_t size);
    Copy code to clipboard
  • 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);
    Copy code to clipboard
  • set_elem_null()

       void set_elem_null();
    Copy code to clipboard

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);
      Copy code to clipboard
    • 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);
      Copy code to clipboard
  • get_elem_size() — Get element size

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

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

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

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

       static bool is_elem_str(const char* buf);
    Copy code to clipboard

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);
      Copy code to clipboard
    • From ODBC structure for time

         d_time(const TIME_STRUCT& t);
      Copy code to clipboard
    • From hour, minute, second

         d_time(int h, int m, int s);
      Copy code to clipboard
    • From ODBC structure for time

         d_time& operator=(const TIME_STRUCT& t);
      Copy code to clipboard

Class InterSystems::d_date

Member list

  • d_date

    • From tm

         d_date(const tm& ts);
      Copy code to clipboard
    • From ODBC structure for date

         d_date(const DATE_STRUCT& d);
      Copy code to clipboard
    • From year, month, day

         d_date(int y, int m, int d);
      Copy code to clipboard
    • From ODBC structure for date

         d_date& operator=(const DATE_STRUCT& d);
      Copy code to clipboard

Class InterSystems::d_timestamp

Member list

  • d_timestamp

    • From tm

         d_timestamp(const tm& ts);
      Copy code to clipboard
    • From ODBC structure for timestamp

         d_timestamp(const TIMESTAMP_STRUCT& ts);
      Copy code to clipboard