%LL_PROCESS

Process a linked list

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
rec = %LL_PROCESS(control, operation, data, [error][, mark])

or

xcall LL_PROCESS(control, operation, data, [error][, mark])

Return value

rec

For operations other than D_LL_DELETE, this function returns the internal record number of the current record if the operation is successful. For D_LL_DELETE, this function returns –1 if successful. If unsuccessful, %LL_PROCESS returns 0. (^VAL)

Arguments

control

The linked list control structure. (a)

operation

The operation to perform: (n)

D_LL_FIRST = Retrieve first record.

D_LL_LAST = Retrieve last record.

D_LL_PREV = Retrieve previous record.

D_LL_NEXT = Retrieve next record.

D_LL_CURR = Read current record.

D_LL_WRITE = Rewrite current record.

D_LL_INSERT = Insert before current record.

D_LL_APPEND = Insert after current record.

D_LL_DELETE = Delete current record.

D_LL_SWAPPREV = Swap current and previous record.

D_LL_SWAPNEXT = Swap current and next record.

D_LL_MARK = Mark the current record.

D_LL_JUMP = Retrieve previously marked record.

data

The data for the operation. (a)

error

(optional) Returned with the error status. If not passed all errors are fatal. (n)

D_LL_NOCURR = No current record.

D_LL_NOTFND = Requested record not found.

D_LL_FSERR = File‑stack error.

D_LL_NOTTOP = Not at top level of file stack.

mark

(optional) The internal record number of the record you want to retrieve (for D_LL_JUMP only; all other operations ignore mark). (n)

Discussion

%LL_PROCESS processes a linked list on the file stack.

The data argument is returned with the data for the current record when using D_LL_JUMP and the D_LL_FIRST through D_LL_CURR operations. For D_LL_WRITE through D_LL_SWAPNEXT (except D_LL_DELETE), the data passed as data is written to the record. The data argument is ignored when using the D_LL_MARK operation.

After a D_LL_DELETE operation, the content of data is undefined and there is no current record (rec returns –1), but the next and previous pointers remain unchanged.

After a D_LL_SWAPPREV or D_LL_SWAPNEXT operation, the next and previous pointers are changed, but the current record pointer remains unchanged. If there is no previous record for a D_LL_SWAPPREV operation, or no next record for a D_LL_SWAPNEXT operation, a D_LL_NOTFND error occurs.

D_LL_MARK marks the current record for a subsequent D_LL_JUMP operation. If there is no current record, this operation will cause an error (D_LL_NOCURR).

D_LL_JUMP retrieves either the record specified by mark or, if mark is not passed or is passed as 0, the last record marked by D_LL_MARK.

Examples

The following example inserts a new record into the linked list. If the operation is successful, the record is inserted before the current record, the new record contains the data passed in new_rec, and the internal number for the record is returned in rec_num. If an error occurs, the error status is returned in sts.

rec_num = %ll_process(lnkctl, D_LL_INSERT, new_rec, sts)

The next example reads the first record in the linked list identified by lnkctl and returns the data for the first record in list_rec. If the operation is successful, rec_num is returned with the internal record number of the first record in the linked list. If an error occurs, the error status is returned in sts.

rec_num = %ll_process(lnkctl, D_LL_FIRST, list_rec, sts)

The next example retrieves the record specified by rec_num. If the operation is successful, the data for the record is returned in list_rec.

xcall ll_process(lnkctl, D_LL_JUMP, list_rec, sts, rec_num)