%LL_PROCESS
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.
- If D_LL_JUMP is successful, the retrieved record becomes the new current record. Rec is returned with the internal record number for that record, data is returned with the data for the record, and error, if passed, is returned with 0.
- If no record has been marked by a previous call to D_LL_MARK, and mark is not passed or is passed as 0, D_LL_JUMP fails, and error (if passed) is returned with D_LL_NOTFND.
- If mark is passed with a non-zero value (including –1, the return value for D_LL_DELETE) and the specified record does not exist, D_LL_JUMP fails, and error (if passed) is returned with D_LL_NOTFND.
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)