Direct Manipulation of Large Objects
In some cases, (for example, two-pass algorithms,) defining a function instance does not work. For these situations, your code can get the peripheral object segments directly through the use of the large object handler. The handler routine performs a variety of operations on large objects.
The handler is called with two arguments. The first is the operation code, which tells the handler which operation to perform. The second argument is a peripheral object control block, II_POP_CB. This control block structure is used to pass information to and from the caller of the handler. The first part of this structure is a standard header used in the DBMS Server.
The exact description of this control block structure can be found in the iiadd.h header file.
• pop_next
• pop_prev
• pop_length
• pop_type
• pop_s_reserved
• pop_l_reserved
• pop_ascii_id
The pop_type field must always be set to II_POP_TYPE. The pop_length field must always be set to the size of the structure. The pop_s_reserved and pop_l_reserved fields must not be set or altered. These fields are used by the DBMS Server memory management routines. You can set the other fields as required.
The rest of the II_POP_CB control block consists of the following fields:
pop_error
The err_code field of this structure contains any error that results from the requested operation. The II_E_NOMORE error indicates that there are no more segments to get. Other errors indicate coding errors.
pop_continuation
Tells the handler routine whether this is the first and/or last invocation of this routine. The use of this field varies by function (refer to the operations that follow for specific use). This field is a mask, so a single operation can be the first (II_C_BEGIN_MASK), the last (II_C_END_MASK), neither (0), or both (II_C_BEGIN_MASK | II_C_END_MASK).
pop_temporary
Indicates the lifetime of the object being created (through an II_PUT operation). A value of II_POP_SHORT_TEMP indicates that the object must be destroyed at the end of the current query. There are no other valid values.
pop_underdv
Contains information about the underlying data type for the operation. The underlying data type describes the segment being manipulated. The field is partially filled in by the caller (db_datatype) and partially by the II_INFORMATION operation (db_length). Because the length allowed can change in future releases of the software, using the information operation as described aids in upward compatibility. The db_data field is unused.
pop_coupon, pop_segment
Pointers to II_DATA_VALUES that describe the overall object (the pop_coupon field) being manipulated, and the individual segment being worked on (pop_segment).
pop_user_arg
Provided for the handler's use. This field must not be touched by your code between the first and last call in a series to the handler (that is, between the II_C_BEGIN_MASK instance and the II_C_END_MASK instance). The handler uses this field to maintain a context. This is necessary due to the multi-threaded nature of the DBMS Server.