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.
Binary — d_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.
d_bool — %Library.Boolean corresponds to CLIENTDATATYPE keyword INTEGER.
d_int — %Library.Integer corresponds to keyword INT or LONG.
d_double — %Library.Double corresponds to keyword DOUBLE.
d_numeric — %Library.Numeric corresponds to keyword NUMERIC. d_numeric is a typedef of d_double.
d_decimal — %Library.Decimal corresponds to keyword DECIMAL.
d_currency — %Library.Currency corresponds to keyword CURRENCY.
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.
d_binary — %Library.Binary corresponds to CLIENTDATATYPE keyword BINARY.
d_longbinary —
d_oid — A complete Object ID. corresponds to keyword OID. d_oid is a typedef of d_binary.
d_status — %Library.Status corresponds to keyword STATUS.
d_string — %Library.String corresponds to keyword VARCHAR or LONG VARCHAR.
d_list — %Library.List corresponds to Caché $list structure.
Class InterSystems::d_binary
A d_binary holds binary data. d_oid is a typedef of d_binary that represents a complete Object ID.
d_binary constructors
No parameters.
d_binary();
Copy code to clipboardFrom null terminated string
d_binary(const char* cstr);
Copy code to clipboardFrom std::string
d_binary(const std::string& s);
Copy code to clipboardFrom 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 clipboardComparison operators — Compare to another d_binary
bool operator==(const d_binary& t); bool operator!=(const d_binary& t);
Copy code to clipboardappend_bin() — Append binary data
void append_bin(const char* buf, byte_size_t size);
Copy code to clipboardassign() — Assign binary data
void assign(const char* buf, byte_size_t size);
Copy code to clipboardget_buf() — Get the address of the binary buffer
const char* get_buf() const;
Copy code to clipboardget_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.
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 clipboardget_msg() — Get the error message
const d_string& get_msg() const;
Copy code to clipboardget_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 clipboardthrow_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.
d_string constructors
No parameters.
d_string();
Copy code to clipboardFrom null terminated string or wide null terminated string
d_string(const char* cstr); d_string(const wchar_t* cstr);
Copy code to clipboardFrom std::string or std::wstring
d_string(const std::string& s); d_string(const std::wstring& s);
Copy code to clipboardFrom 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 clipboardto_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 clipboardConvert 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 clipboardConvert 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 clipboardComparison 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 clipboardassign()
From null terminated string or wide null terminated string.
void assign(const char* buf); void assign(const wchar_t* buf);
Copy code to clipboardFrom 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.
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 clipboardappend_elem_null()
void append_elem_null();
Copy code to clipboardat_end()
bool at_end() const;
Copy code to clipboardclear() — Delete all elements
void clear();
Copy code to clipboardcount() — Count the number of elements
int count();
Copy code to clipboarddel_elem() — Delete the current element
void del_elem();
Copy code to clipboardelem_null()
void ins_elem_null();
Copy code to clipboardget_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 clipboardget_elem_idx() — Get the index of the current element
int get_elem_idx() const;
Copy code to clipboardget_elem_type()
char get_elem_type() const;
Copy code to clipboardins_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 clipboardis_elem_double()
bool is_elem_double() const;
Copy code to clipboardis_elem_int()
bool is_elem_int() const;
Copy code to clipboardis_elem_null()
bool is_elem_null() const;
Copy code to clipboardis_elem_str()
bool is_elem_str() const;
Copy code to clipboardmove_to() — Change the current position to idx (0 based)
void move_to(int idx) const;
Copy code to clipboardmove_to_front() — Same as move_to(0) but optimized
void move_to_front() const;
Copy code to clipboardnext() — Similar to move_to(), but optimized for moving to the next element
void next() const;
Copy code to clipboardreset() — Reset the buffer
void reset(const char* buf, byte_size_t size);
Copy code to clipboardset_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 clipboardset_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).
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 clipboardGet 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 clipboardis_elem_double() — Test whether an element is stored as double
static bool is_elem_double(const char* buf);
Copy code to clipboardis_elem_int() — Test whether an element is stored as int
static bool is_elem_int(const char* buf);
Copy code to clipboardis_elem_null() — Test whether an element is null
static bool is_elem_null(const char* buf);
Copy code to clipboardis_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.
d_date — %Library.Date corresponds to CLIENTDATATYPE keyword DATE.
d_time — %Library.Time corresponds to keyword TIME.
d_timestamp — %Library.TimeStamp corresponds to keyword TIMESTAMP.
Class InterSystems::d_time
d_time
From tm
d_time(const tm& ts);
Copy code to clipboardFrom ODBC structure for time
d_time(const TIME_STRUCT& t);
Copy code to clipboardFrom hour, minute, second
d_time(int h, int m, int s);
Copy code to clipboardFrom ODBC structure for time
d_time& operator=(const TIME_STRUCT& t);
Copy code to clipboard
Class InterSystems::d_date
d_date
From tm
d_date(const tm& ts);
Copy code to clipboardFrom ODBC structure for date
d_date(const DATE_STRUCT& d);
Copy code to clipboardFrom year, month, day
d_date(int y, int m, int d);
Copy code to clipboardFrom ODBC structure for date
d_date& operator=(const DATE_STRUCT& d);
Copy code to clipboard
Class InterSystems::d_timestamp
d_timestamp
From tm
d_timestamp(const tm& ts);
Copy code to clipboardFrom ODBC structure for timestamp
d_timestamp(const TIMESTAMP_STRUCT& ts);
Copy code to clipboard