L_DATA

Manipulate the data in a list

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall L_DATA(list_id, request, window_id, [data], [disabled], no_find
&     [, a_methoddata1, …, a_methoddata20])

Arguments

list_id

The ID of the list to manipulate. (n)

request

The requested operation: (n)

D_LCURRENT = Retrieve L_PROCESS’s current item.

D_LFIRST = Retrieve the first loaded item.

D_LLAST = Retrieve the last loaded item.

D_LNEXT = Retrieve the next loaded item.

D_LPREV = Retrieve the previous loaded item.

D_LWRITE = Rewrite an item.

window_id

The ID of the associated input window. (n)

data

(optional) The associated non‑window data. (a)

disabled

(optional) The disabled item status. (n)

no_find

A true/false flag that indicates whether the operation failed. (n)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional arguments for field methods. (any)

Discussion

L_DATA enables you to read or write items that have already been loaded into the list without modifying the context for the next call to L_PROCESS.

L_DATA retrieves and rewrites the input window display, reading and writing data for items in the list that the L_PROCESS subroutine has already loaded. It can also retrieve and rewrite the associated non‑window data, the disabled flag, and the input set controls.

Disabled is a true/false flag that indicates whether the current item is disabled. Whether or not the disabled argument is passed must correspond to whether it was passed to other list routines such as L_CHR, L_INPFLD, L_INPUT, L_PROCESS, and L_SELECT. See L_PROCESS for more information about the disabled item status. It is both passed (with D_LWRITE) and returned.

If the display of any visible item is modified by D_LWRITE, that change is reflected in the list. The context of L_PROCESS, however, is not modified. The purpose of this subroutine is to enable the calling routine to peruse and/or modify data in other items of the list without changing the list’s context.

We recommend that you use a different input window and data area for this subroutine than for L_PROCESS. Another option is to issue the request D_LRESTORE before attempting any other operation when you are ready to proceed with L_PROCESS.

Note

For ActiveX Toolkit lists, the display of each field in the input window is mapped to the associated column in the list. So if the input window whose ID you pass to L_DATA has different field definitions than the input window used to create the list, you may get unexpected field/column mappings, and some fields may not be mapped at all. (Each column in the list maps to the Toolkit field number used to create that column initially, and if that field number is greater than the number of fields in the input window passed to L_DATA, the field won’t be mapped.)

Unlike L_PROCESS, the L_DATA subroutine only records information in the list when the D_LWRITE flag is specified.

The D_LCURRENT flag retrieves the current item being used by L_PROCESS. This item is not necessarily the same as the item retrieved by the most recent call to L_DATA. If the current item has not been loaded (as in the case of a null list), no_find will be returned with a value of true.

The D_LFIRST flag retrieves the first item currently loaded into the list. If the list permits item loading at the top and a D_LEOF has not yet been signaled, D_LFIRST retrieves the uppermost item loaded and does not cause a load request to be issued. If the list doesn’t contain any items, the no_find argument is returned with a value of true.

The D_LLAST flag retrieves the last item currently loaded into the list. If the list permits item loading at the bottom and a D_LEOF has not yet been signaled, D_LLAST will retrieve the lowermost item loaded and will not cause a load request to be issued. If the list doesn’t contain any items, the no_find argument will be returned with a value of true.

The D_LNEXT flag retrieves the item that follows the last item retrieved by this subroutine. If L_DATA has not retrieved any items, or if no item follows the last item retrieved, the no_find argument will be returned with a value of true, and no item will be retrieved. D_LNEXT will only retrieve an item that has already been loaded.

The D_LPREV flag retrieves the item that precedes the last item retrieved by this subroutine. If L_DATA has not retrieved any items, or if no item precedes the last item retrieved, the no_find argument will be returned with a value of true, and no item will be retrieved. D_LPREV will only retrieve an item that has already been loaded.

The D_LWRITE flag rewrites the last item that was retrieved by L_DATA. (If L_DATA has not retrieved an item, no_find is returned with the value of true, and no rewrite occurs.) D_LWRITE updates both the display and non‑window data for the list, but the display will reflect changes only if I_DSPFLD or I_DISPLAY is called with the window that’s passed to L_DATA and if that call occurs before the call to L_DATA. Non‑window data is updated with changes in any case.

If L_PROCESS deletes the last item that was retrieved, no context exists for D_LNEXT, D_LPREV, or D_LWRITE. You can use D_LCURRENT, D_LFIRST, or D_LLAST to re‑establish a context for this subroutine.

A_methoddata1 through a_methoddata20 are up to 20 additional (and optional) arguments. These arguments are used only if the INPUT_SNAPSHOT qualifier was specified in the list class when the list was created and you specify a request that updates the input window (D_LCURRENT, D_LFIRST, D_LNEXT, or D_LPREV—not D_LWRITE). When L_DATA updates the input window by calling I_SNAPSHOT, it redisplays the data into the input window, which requires it to use any display methods for the fields. The method data arguments are passed to those display methods.

Examples

In this example, the only associated data in the list is a number, which is renumbered beginning with the current item in the list and starting with the current item’s value for the number plus one. For example, starting with the current item, if the items in the list were numbered 5 through 20, the items would be renumbered 6 through 21 after the code below was executed. Any visible item would reflect that change.

xcall l_data(mylist, D_LCURRENT, inpid, number,, eof)
while (.not. eof)
  begin
    incr number
    xcall i_dspfld(inpid, "number", number)
    xcall l_data(mylist, D_LWRITE, inpid, number,, eof)
    xcall l_data(mylist, D_LNEXT, inpid, number,, eof)
  end