The ifx_rc_insert() function

The ifx_rc_insert() function inserts a new element into a collection.

Syntax

ifx_rc_insert(rchandle, value, action, jump)

Arguments

The function accepts the following arguments.
Argument Type Use Description
rchandle HINFX_RC Input Handle for a collection buffer
value Data type of the element Input Value to insert
action SQL_SMALLINT Input Location of the element relative to the seek position. The possible values are:
  • SQL_INFX_RC_ABSOLUTE: Element number jump where the first element in the buffer is element number one
  • SQL_INFX_RC_CURRENT: Current® element
  • SQL_INFX_RC_FIRST: First element
  • SQL_INFX_RC_LAST: Last element
  • SQL_INFX_RC_NEXT: Next element
  • SQL_INFX_RC_PRIOR: Previous element
  • SQL_INFX_RC_RELATIVE: Element that is jump elements past the current element
jump SQL_SMALLINT Input Offset when action is SQL_INFX_RC_ABSOLUTE or SQL_INFX_RC_RELATIVE

Usage

The ifx_rc_insert() function inserts a new element into a collection before the location that is specified by action and jump. The function sets the seek position to the position of the value that was inserted. It is not possible to insert a new element into a row.

The following table describes the allowable insertion locations for each type of collection.
Type of collection Allowable insertion locations
List Anywhere in the buffer
Set or multiset At the end of the buffer

If the seek position specified by action and jump exceeds the end of the buffer, ifx_rc_insert() appends the new element at the end of the buffer. Likewise, if the seek position specified by action and jump precedes the beginning of the buffer, ifx_rc_insert() inserts the new element at the beginning of the buffer. If action specifies an insertion point other than the end for a set or multiset, ifx_rc_insert() fails.

For example, if action is SQL_INFX_RC_LAST, the function inserts the new element before the last element. To append a new element, take one of the following actions:
  • Set the seek position to the end of the buffer and set action to SQL_INFX_RC_NEXT.
  • Set action to SQL_INFX_RC_ABSOLUTE or SQL_INFX_RC_RELATIVE and set jump to a value that exceeds the end of the buffer.

To insert a new element at the beginning of a buffer, set action to SQL_INFX_RC_FIRST.