IldRequest Objects

This section explains how to create, manipulate, and delete IldRequest objects. It is divided as follows:

No public constructor exists for the class IldRequest. The IldRequest constructor is private to its class so it cannot be called from your application.

To create an IldRequest object, you must have already created an IldDbms object using the function IldNewDbms.

The only way to create a cursor is to ask an IldDbms object to deliver one using the function IldDbms::getFreeRequest, as shown in the following example:

The IldDbms::getFreeRequest function does not necessarily allocate a new IldRequest object each time it is called, but instead, it may reuse any IldRequest object that has been previously released (see Releasing an IldRequest Object for more information).


Warning: It is possible for the allocation of an IldRequest object to succeed (partially, for example), while the creation of the object not succeed. In such a situation, memory was at least partially allocated, but the returned object cannot be used to execute a query. For that reason, you must always check that no errors were raised in the IldDbms object.

If an error is raised but you do not check it, you will be using a special object instead of the normal IldRequest object. Using this special object will, in turn, raise an error ILD_USING_ERROR_REQUEST each time any function is called with it.

The number of IldRequest objects you can create is limited only by the database system configuration (for example, 50 with the Oracle default configuration).

To get the number of active IldRequest objects, you call the member function IldDbms::getNumberOfRequests. This number corresponds to the number of IldRequest objects that actually exist, not the number of IldRequest objects for which an SQL statement is being processed. That is, even if an IldRequest object has been released, it is still considered active (see next section for more information).

Disposing of an IldRequest object involves releasing it and destroying it.

When you are finished using an IldRequest object, you can tell Rogue Wave DB Link that you are not going to use it any longer and that the object is at its disposal. To do so, use the member function IldRequest::release.


Warning: You must be careful not to use an IldRequest object once it has been released. Instead, you must ask the IldDbms object to supply a new IldRequest object (which could be the same).

An IldRequest object can be destroyed and its server-side allocated resources released on an explicit or implicit basis.

To destroy an IldRequest object explicitly, just call the C++ operator delete on it. The ~IldRequest destructor notifies the related IldDbms object of its disappearance.

To destroy an IldRequest object implicitly, all you have to do is leave the object where it is. Actually, the destruction of the related IldDbms object causes the appropriate destructor to be called.

Rogue Wave DB Link tries to manage the memory allocated for IldRequest objects as sparingly as possible. This is why you are strongly advised to use the function IldRequest::release rather than calling the operator delete when it comes to disposing of an IldRequest object.

Using the pair IldDbms::getFreeRequest/IldRequest::release is, on average, faster than using the pair IldDbms::getFreeRequest/delete because, with the first pair, the IldRequest object is not deleted and will be reused on a further call to IldDbms::getFreeRequest.