Home | Previous Page | Next Page   Client Functions > Functions for Rows and Collections >

ifx_rc_insert()

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 value that was just 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:

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

Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]