This class is the base class for Data Access Builder Large Object (LOB) support. Large object data access is supported only for DB2 database mappings.
Inherits from:
IDABase | +----IDALobDO
Inherited by:
IDALobDA | +----IDABlobDO | +----IDAClobDO | +----IDADBClobDO
Public Functions by Category
public: IBoolean isModified() const;Use this method to determine whether the LOB has been modified by one of the contents manipulation methods. It returns true if the LOB has been modified, or false if it has not.
Supported Platforms Windows OS/2 AIX Y Y Y public: void setModified(IBoolean flag=true);Use this method to change the isModified setting for the LOB. Pass in false to indicate that the LOB has not been modified, or true to indicate that it has. The contents manipulation methods also change this setting (to true).
Supported Platforms Windows OS/2 AIX Y Y Y
public: IString getContents() const;Use this method to return an IString object containing the LOB's contents.
Supported Platforms Windows OS/2 AIX Y Y Y public: void setContents(const IString& astring);Use this method to set the contents of the LOB to the passed-in string.
Supported Platforms Windows OS/2 AIX Y Y Y public: virtual void setContentsFromFile(const char* afileName);Use this method to copy the contents of the specifed file into the LOB. If the specified file does not exist, a "File Does Not Exist" exception will be thrown. If the file could not be opened or read, an "Unable to Read File" exception will be thrown.
Supported Platforms Windows OS/2 AIX Y Y Y public: virtual unsigned long putContentsToFile( const char* afileName, FileOption opt=DAX_FILE_OVERWRITE) const;Use this method to output the contents of the LOB to the specified file. Pass in the desired filename, and a file option. Eligible file options are:
- DAX_FILE_CREATE
- DAX_FILE_OVERWRITE - the default if no File Option is passed in.
- DAX_FILE_APPEND
The method returns an unsigned long that indicates the number of bytes written to the file. If you pass in an invalid file option, an "Invalid File Option" exception will be thrown. If the specified file cannot be opened or written to, an "Unable to Write to File" exception will be thrown.
Supported Platforms Windows OS/2 AIX Y Y Y
public: unsigned long length() const;Use this method to return the length, in bytes, of the LOB.
Supported Platforms Windows OS/2 AIX Y Y Y public: unsigned long indexOf(const IString& astring, unsigned long startPos=1) const; unsigned long indexOf(const IDALobDO& aLob, unsigned long startpos=1) const;Use this method to find the position of the passed-in string or LOB within the current LOB. To use this method, pass in the string or LOB that you want to find, and optionally, a start position (in bytes, where the first byte is numbered 1). The method looks for the next occurrence of the passed-in object and returns its index within the LOB. It returns an unsigned long that indicates the position of the passed-in object within the LOB.
For example, if the current LOB object is "123456789", and you want to find the position of the string "78" within the LOB, call the method as shown, where index is an unsigned long:
index = currentLOB.indexOf("78");The method will return an index value of 7. If the current LOB is "1234512345", and you call the method indexOf("23", 4); then it skips to the fourth position ("4"), looks for the next occurrence of "23", and returns its index (7).
Supported Platforms Windows OS/2 AIX Y Y Y
public: IString subString(unsigned long startpos, unsigned long length) const;Use this method to return a substring of the LOB. Pass in a start position (where the first byte is numbered 1) and a substring length (in bytes). The method returns an IString object containing the substring specified. For example, if the current LOB is "123456789", and you want to return the "567" portion, call the method as shown:
substring = currentLOB.subString(5, 3);
Supported Platforms Windows OS/2 AIX Y Y Y
public: void remove(unsigned long startpos, unsigned long length);Use this method to remove a portion of the LOB. Pass in the start position (in bytes, where the first byte is numbered 1) and the length (in bytes) of the portion to be removed.
Supported Platforms Windows OS/2 AIX Y Y Y public: void insert(const IString& astring, unsigned long startpos); void insert(const IDALobDO& aLob, unsigned long startpos);Use this method to insert a string or LOB into the current LOB. Pass in the desired string or LOB and the position for insertion (where the first byte is numbered 1). For example, if the current LOB is "123456789", and you want to insert the string "abc" after the "4", then call the method as shown:
currentLob.insert("abc", 5);Now, the current LOB will be "1234abc56789". If you try to insert an incompatible LOB (for example, a BLOB into a CLOB), an "Incompatible LOB Types" exception will be thrown. If you indicate a start position past the end of the LOB, a "Boundary Exceeded" exception will be thrown.
Supported Platforms Windows OS/2 AIX Y Y Y public: void overlayWith(const IString& astring, unsigned long startpos); void overlayWith(const IDALobDO& aLob, unsigned long startpos);Use this method to overlay a portion of the LOB with the passed-in string or LOB. Pass in the desired string or LOB and the start position the overlay (where the first byte is numbered 1). For example, if the current LOB is "123456789", and you want to overlay the string "abc" over the "567" portion, call the method as shown:
currentLOB.overlayWith("abc", 5);Now, the current LOB will be "1234abc89". If you try to overlay the LOB with an incompatible LOB (for example, overlaying part of a CLOB with a BLOB), an "Incompatible LOB Types" exception will be thrown. If you indicate a start position past the end of the LOB, a "Boundary Exceeded" exception will be thrown.
Supported Platforms Windows OS/2 AIX Y Y Y
public: IBoolean isStoredAtClient() const;Use this method to determine whether the current LOB is being stored at the client or at the server. It returns true if the LOB is stored on the client, or false if the LOB is stored on the server. Where the object is stored is affected by threshold and delta settings (see methods below).
Supported Platforms Windows OS/2 AIX Y Y Y public: void storeAtClient();Use this method to store the current LOB on the client. While this may require a lot of memory (especially if you download several big LOBs), it may be faster to manipulate the contents of the LOB if it is on the client (especially if your connection to the server is slow). This method sets the object's threshold to the maximum (2.0 GB).
To specify that all objects of this class are to be stored at the client, call the storeAtClientByDefault method. Change this setting by using the setObjectsThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: void storeAtServer();Use this method to store the current LOB on the server. Storing the LOB on the server while you manipulate it uses less of your client machine's memory than storing it on the client. However, if your connection to the server is slow, methods that manipulate the LOB may take longer to run than they would if the object were on the client. This method sets the object's threshold to zero.
To specify that all objects of this class are to be stored at the server, call the storeAtServerByDefault method. Change this setting by using the setObjectsThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: static void storeAtClientByDefault();Use this method to specify that all objects of this class are to be stored on the client. This method sets the class threshold to the maximum (2.0 GB). This setting can be overridden for a particular object by calling storeAtServer or setObjectsThreshold. It can be changed at the class level by calling the setClassThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: static void storeAtServerByDefault();Use this method to specify that all objects of this class are to be stored on the server. This method sets the class threshold to zero. This setting can be overridden for a particular object by calling storeAtClient or setObjectsThreshold. It can be changed at the class level by calling the setClassThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: void setConnection(const IDatastoreDB2 &dsm);Use this method to set the datastore connection that the LOB will use when being transferred to and from the client and server, and when contents manipulation methods run on the server. This must be a DB2 (ESQL or CLI) datastore.
Important! Disable the datastore autocommit setting (pass false into the enableAutoCommit method) since locator values for LOBs on the server are only valid for a single transaction, and become invalid after each commit or roll back.
Supported Platforms Windows OS/2 AIX Y Y Y
public: void setObjectsThreshold(unsigned long newThreshold, unsigned long delta = 0);Use this method to specify the object's threshold value and delta value (in bytes). The object's threshold represents the maximum object size (plus the delta value) that will be kept on the client, and the minimum object size (minus the delta value) that will be kept on the server. The delta value gives the object some flexibility by preventing the object being sent back and forth between the client and the server if its size is hovering about the threshold. The default delta value is zero.
For example, suppose you set the threshold to 500 bytes and the delta value to 25 bytes by running the following code:
currentLOB.setObjectThreshold( 500, 25)If the current LOB is 450 bytes, it will be stored on the client. If you add 60 bytes to it, for a total of 510 bytes, then it will still be kept on the client, even though it has passed the threshold, because of the delta (the upload threshold is effectively 525 bytes). If you then add 30 more bytes, for a total of 540 bytes, the LOB will be moved to the server. If you then remove 50 bytes from it, for a total of 490 bytes, it will still be kept on the server (the download threshold is effectively 475 bytes).
Threshold values can also be set at the class level (rather than at the object level, which is what this method does) by using the setClassThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: unsigned long getObjectsThreshold() const;Use this method to return the threshold value of the current LOB (in bytes). The object's threshold represents the maximum size of object (plus the delta value) to be kept on the client, and the minimum size (minus the delta value) to be kept on the server. Set this value by using the setObjectsThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: unsigned long getObjectsDelta() const;Use this method to return the delta value for the current LOB (in bytes). The delta is the tolerance for the threshold; it prevents the object being sent back and forth between the client and server if its size is hovering about the threshold. If the object is on the client, the delta is added to the threshold to determine the maximum size it can reach before being sent to the server. If the object is on the server, the delta is subtracted from the threshold to determine the minimum size it can reach before being sent to the client. Set the delta value by passing in the second parameter to the setObjectsThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: static void setClassThreshold(unsigned long newThreshold, unsigned long delta = 0);Use this method to specify a class-level threshold value and delta value (in bytes), to be used for all objects of this class. The class threshold represents the maximum object size (plus the delta value) that will be kept on the client, and the minimum object size (minus the delta value) that will be kept on the server. The delta value gives the object some flexibility by preventing the object being sent back and forth between the client and the server if its size is hovering about the threshold. The default delta value is zero.
For example, suppose you set the class threshold to 500 bytes and the delta value to 25 bytes by running the following code:
IDALobDO.setClassThreshold( 500, 25)If the current LOB is 450 bytes, it will be stored on the client. If you add 60 bytes to it, for a total of 510 bytes, then it will still be kept on the client, even though it has passed the threshold, because of the delta (the upload threshold is effectively 525 bytes). If you then add 30 more bytes, for a total of 540 bytes, the LOB will be moved to the server. If you then remove 50 bytes from it, for a total of 490 bytes, it will still be kept on the server (the download threshold is effectively 475 bytes).
This setting can be overridden for a particular object by calling storeAtClient, storeAtServer, or setObjectsThreshold. It can be changed at the class level by calling storeAtClientByDefault or setAtServerByDefault.
Supported Platforms Windows OS/2 AIX Y Y Y public: static unsigned long getClassThreshold();Use this method to return the default threshold value for objects of this class (in bytes). The threshold represents the maximum size of an object (plus the delta value) to be kept on the client, and the minimum size (minus the delta value) to be kept on the server. Set this value by using the setClassThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: static unsigned long getClassDelta();Use this method to return the default delta value for objects of this class (in bytes). The delta is the tolerance for the threshold; it prevents the object being sent back and forth between the client and server if its size is hovering about the threshold. If the object is on the client, the delta is added to the threshold to determine the maximum size it can reach before being sent to the server. If the object is on the server, the delta is subtracted from the threshold to determine the minimum size it can reach before being sent to the client. Set the delta value by passing in the second parameter to the setClassThreshold method.
Supported Platforms Windows OS/2 AIX Y Y Y public: void useClassThreshold();Use this method to use the class-level threshold and delta settings, rather than the object-level settings.
Supported Platforms Windows OS/2 AIX Y Y Y public: long getLocatorValue() const;If a LOB is stored on the server, this method returns the value of the database locator that is pointing to it.
Warning! If you use this value to work with the LOB, none of the provided Data Access class library methods will be able to access the object.
Supported Platforms Windows OS/2 AIX Y Y Y
Public Operators
public: virtual IBoolean operator==(const IDALobDO& aLob) const;This is the equals operator. It compartes two LOBs to test them for equality. It returns a value of true if the objects are equal, or false if they are not.
Supported Platforms Windows OS/2 AIX Y Y Y public: virtual IBoolean operator!=(const IDALobDO& aLob) const;Use this method to test two LOBs for inequality. It returns a value of true if the objects are inequal, or false if they are equal.
Supported Platforms Windows OS/2 AIX Y Y Y public: virtual IDALobDO& operator+=(const IString& aString); virtual IDALobDO& operator+=(const IDALobDO& aLob);Use this method to add a string or a LOB to the current LOB. The two objects are concatenated and a pointer to the sum is returned. Note that elsewhere an operator is defined that lets you add a LOB to an IString object. If you try to add incompatible LOB types (for example, a BLOB to a CLOB), an "Incompatible LOB Type" exception is thrown.
Supported Platforms Windows OS/2 AIX Y Y Y
Protected Functions
protected: IDALobDO( );
Supported Platforms Windows OS/2 AIX Y Y Y
