INFORMIX
DataBlade Developers Kit User's Guide
Chapter 6: Creating ActiveX Value Objects
Home Contents Index Master Index New Book

Support Methods Reference

 This section describes the internal object and support library methods that you can use when adding project-specific logic to your client and server projects. Use these methods (and the methods made available as ActiveX custom methods; see "Files to Edit") to ensure that your code is portable between client and server projects.

Internal Object Methods

For each ActiveX value object that you implement, a set of internal methods is created. Although these methods are not made available to the client application developer as ActiveX custom methods, you can use them when adding project-specific logic to your client and server projects.

These are the internal object methods, where Opaque is the name of the opaque type that defines the current object.

Method Description

static OpaqueCommon * CreateNew()

Creates an instance of the current object. The object name is OpaqueServer if called by server code, or OpaqueClient if called by client code.

void DkErrorRaise( MI_CONNECTION *conn, mi_integer msg_type, char *msg, ...)

Maps to mi_db_error_raise on the server, raises an error on the client; for details, see the DataBlade API Programmer's Manual.

OpaqueStruct * GetData()

Returns a pointer to the data structure representing the current object.

mi_boolean IsDirty()

Returns mi_true if the current object has been modified, mi_false if it has not.

OpaqueStruct * RawCopy()

Allocates a C data structure and fills it with a copy of the raw data of the current object.

void SetClean()

Flags the current object as having not been modified.

void SetData( const OpaqueStruct *value)

Fills the current object with the data supplied by the input data structure.

void SetDirty()

Flags the current object as having been modified.

void SetNotNull()

A protected method that sets the current object to not null.

C++ Support Library

When you use BladeSmith to generate source code for your ActiveX value objects, the following C++ support library files are generated:

These files are used to compile both the client project and the server project; they are automatically included in the appropriate source files.

The C++ support library contains these classes and routines:

There are two types of delimiters you must be aware of when using the DkInStream and DkOutStream classes: string delimiters and field delimiters.

String delimiters are a pair of single-byte characters that indicate the beginning and ending of a string. By default, the string delimiters are the open and close quote characters (" "), but you can specify other characters by using the SetStringDelimiters() method.

Important: If you set the DkInStream class string delimiters to a different pair than the DkOutStream string delimiters, then these text parser classes cannot exchange strings.
Field delimiters indicate the beginning and ending of a field. By default, space characters are always field delimiters. In addition, you can specify a multibyte string to also be a field delimiter, using the SetFieldDelimiters() method.

A string can contain multiple fields and their delimiters. However, a field cannot contain a string.

For example, if the default string and field delimiters are in use and given the characters "Date: 4 28 97", then there is one string, Date: 4 28 97, and four fields: Date:, 4, 28, 97.

To include a string-delimiter character in a string, precede it with a backslash character (\). For example, to read the string Date: "4 28 97", specify the string as follows: "Date: \"4 28 97\"".

The rest of this section provides reference information for the text parsing classes and memory management routines.

DkInStream

The DkInStream class provides methods that read an input text stream and populate an instance of the object (an opaque type if invoked by server code, an ActiveX value object if invoked by client code). This class has a built-in cursor that tracks how much of the input stream has been read.

All of the read methods return an mi_boolean value: mi_true if the read is successful; mi_false if it is not. In addition, all read methods except ReadChar, ReadGLWChar, and ReadWChar skip field and string delimiters before reading.

The gl_wchar data type is configurable, but it is a 4-byte character by default. For more information on this data type, see the discussion of the Informix GLS API in the Informix Guide to GLS Functionality.

The DkInStream class provides the following methods.

(1 of 4)

Method Description

DkInStream(mi_lvarchar* inputString)

DkInStream(const char* inputString)

Reads inputString, which can be a multibyte string.

char* CurString()

Returns a pointer to the string at the current cursor position.

mi_boolean Match(char* str)

Returns mi_true if the exact sequence of characters specified in str is found in the input string.

This method is the opposite of DkOutStream.WriteLiteral.

mi_boolean operator+=(size_t skip)

Returns mi_true if the number of characters specified in skip is successfully skipped.

mi_boolean operator-=(size_t rew)

Returns mi_true if the number of characters specified in rew is successfully "rewound" (skipped backwards).

mi_boolean ReadBoolean( mi_boolean* value)

Returns mi_true if one of the following values is successfully read: TRUE, True, true, FALSE, False, false.

mi_boolean ReadChar(mi_char* value)

Returns mi_true if a value of type mi_char is successfully read. Field and string delimiters are not skipped before reading.

mi_boolean ReadDate(mi_date* value)

Returns mi_true if a date value is successfully read. If the date value contains spaces or field delimiters, enclose it in string delimiters.

mi_boolean ReadDateTime( mi_datetime* value)

Returns mi_true if a date-time value is successfully read. If the date-time value contains spaces or field delimiters, enclose it in string delimiters.

mi_boolean ReadDecimal( mi_decimal* value)

Returns mi_true if a decimal or numeric value is successfully read.

mi_boolean ReadDoublePrecision( mi_double_precision* value)

Returns mi_true if a double-precision value is successfully read.

mi_boolean ReadGLWChar( gl_wchar_t* value)

Returns mi_true if a value of type gl_wchar (a 4-byte character, by default) is successfully read. Field and string delimiters are not skipped before reading.

mi_boolean ReadGLWString( gl_wchar_t* value, size_t length)

Returns mi_true if a string of gl_wchar values, size length, is successfully read. If the string is longer than length, it is truncated and not null-terminated. To include a string-delimiter character in the string, precede it with the backslash character (\).

mi_boolean ReadInt1(mi_int1* value)

Returns mi_true if a 1-byte integer value is successfully read.

mi_boolean ReadInt8(mi_int8* value)

Returns mi_true if an 8-byte integer value is successfully read.

mi_boolean ReadInteger( mi_integer* value)

Returns mi_true if a 4-byte integer value is successfully read.

mi_boolean ReadInterval( mi_interval* value)

Returns mi_true if an interval value is successfully read.

mi_boolean ReadMoney( mi_money* value)

Returns mi_true if a money value is successfully read.

mi_boolean ReadReal(mi_real* value)

Returns mi_true if a real value is successfully read.

mi_boolean ReadSmallInt( mi_smallint* value)

Returns mi_true if a 2-byte integer value is successfully read.

mi_boolean ReadString( const mi_string* value, size_t length)

Returns mi_true if a string of mi_string values, size length, is successfully read. If the string is longer than length, it is truncated and not null-terminated. To include a string-delimiter character in the string, precede it with the backslash character (\).

mi_boolean ReadUChar1( mi_unsigned_char1* value)

Returns mi_true if a 1-byte unsigned integer value is successfully read. (Integer is correct; the data type is misnamed.)

mi_boolean ReadUInt8( mi_unsigned_int8* value)

Returns mi_true if an 8-byte unsigned integer value is successfully read.

mi_boolean ReadUInteger( mi_unsigned_integer* value)

Returns mi_true if a 4-byte unsigned integer value is successfully read.

mi_boolean ReadUSmallInt( mi_unsigned_smallint* value)

Returns mi_true if a 2-byte unsigned integer value is successfully read.

mi_boolean ReadWChar( mi_wchar* value)

Returns mi_true if a 2-byte character is successfully read. Field and string delimiters are not skipped before reading.

mi_boolean ReadWString( mi_wchar* value, size_t length)

Returns mi_true if a string of mi_wchar values, size length, is successfully read. If the string is longer than length, it is truncated and not null-terminated. To include a string-delimiter character in the string, precede it with the backslash character (\).

void SetFieldDelimiters( const char* delim)

By default, the space character is a field delimiter; this method adds delim as another delimiter. delim can be a multibyte string, but it cannot be longer than DK_MAXDELIMBYTES (default value of 20).

void SetStringDelimiters(char begin, char end)

Sets string delimiters to two, single-byte characters (begin and end). Default values are the open-quote character (") and the close-quote character (").

void Skip(char* delim)

Skips only the sequence of characters specified by delim.

void SkipBlanks()

Skips all space characters.

void SkipDelimiters()

Skips the characters specified by delim in the SetFieldDelimiters method and space characters.

DkOutStream

The DkOutStream class provides methods that write an object (an opaque type if invoked by server code, or an ActiveX value object if invoked by client code) to an output stream. All of the write methods append to the output string; they do not overwrite the existing contents of the string.

The gl_wchar data type is configurable, but it is a 4-byte character by default. For more information on this data type, see the discussion of the Informix GLS API in the Informix Guide to GLS Functionality.

The DkOutStream class provides the following methods.

(1 of 3)

Method Description

DkOutStream(size_t initial=50, size_t increment=50)

Creates an output string of size initial, allocating additional memory in chunks of size increment.

mi_lvarchar* CreateLvarChar()

Returns a pointer to a new mi_lvarchar that holds a copy of the output string.

const char* GetBuffer()

Returns a pointer to the internal buffer that contains the output string.

void SetStringDelimiters(char begin, char end)

Sets string delimiters to two, single-byte characters (begin and end). Default values are the open-quote character (") and the close-quote character (").

void WriteBoolean(mi_boolean value)

Writes a boolean value of true or false to the output string.

void WriteChar(mi_char value)

Writes a value of mi_char to the output string.

void WriteDate(mi_date value)

Writes a date value to the output string.

void WriteDateTime( const mi_datetime& value)

Writes a datetime value to the output string.

void WriteDecimal( const mi_decimal& value)

Writes a decimal or numeric value to the output string.

void WriteDoublePrecision( mi_double_precision value)

Writes a double precision value to the output string.

void WriteGLWChar( gl_wchar_t value)

Writes a value of type gl_wchar (a 4-byte character, by default) to the output string.

void WriteGLWString( const gl_wchar_t* value, size_t length)

Writes a string of gl_wchar values, size length, to the output string. This method precedes string-delimiter characters with backslash characters (\).

void WriteInt1(mi_int1 value)

Writes a 1-byte integer value to the output string.

void WriteInt8(const mi_int8& value)

Writes an 8-byte integer value to the output string.

void WriteInteger(mi_integer value)

Writes a 4-byte integer value to the output string.

void WriteInterval( const mi_interval& value)

Writes an interval value to the output string.

void WriteLiteral(const char* string)

Writes the specified string to the output string. Delimiter characters are written as is; they are neither skipped nor preceded by backslash characters.

This method is the opposite of DkInStream.Match.

void WriteMoney( const mi_money& value)

Writes a money value to the output string.

void WriteReal(mi_real value)

Writes a real value to the output string.

void WriteSmallInt( mi_smallint value)

Writes a 2-byte integer value to the output string.

void WriteString( const mi_string* value, size_t length)

Writes a string of mi_string values, size length, to the output string. This method precedes string-delimiter characters with backslash characters (\).

void WriteUChar1( mi_unsigned_char1 value)

Writes a 1-byte unsigned integer to the output string. (Integer is correct; the data type is misnamed.)

void WriteUInt8( const mi_unsigned_int8& value)

Writes an 8-byte unsigned integer to the output string.

void WriteUInteger( mi_unsigned_integer value)

Writes a 4-byte unsigned integer to the output string.

void WriteUSmallInt( mi_unsigned_smallint value)

Writes a 2-byte unsigned integer to the output string.

void WriteWChar(mi_wchar value)

Writes a 2-byte character to the output string.

void WriteWString( const mi_wchar* value, size_t length)

Writes a string of mi_wchar values, size length, to the output string. This method precedes string-delimiter characters with backslash characters (\).

Memory Management Routines

These routines do not form a class. They are provided for server-project use only. Informix recommends that you use the new and delete operators. Use malloc and free only if you must; for example, if you call into a C file.

Routine Description

void * ::operator new(size_t size)

Calls mi_alloc on the server side.

void ::operator delete(void *ptr)

Deletes the memory allocated with the new operator.

void * malloc(size_t size)

Calls mi_alloc on the server side.

void free(void *memblock)

Frees the memory allocated with the malloc routine.



DataBlade Developers Kit User's Guide, version 3.6
Copyright © 1998, Informix Software, Inc. All rights reserved.