L_STATUS

Retrieve the status of a list

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall L_STATUS(list_id[, flags, ...])

Arguments

list_id

The ID of the list to retrieve information for. (n)

flags

(optional) One or more of the information request flags and its return values shown in the table below. (n)

Discussion

L_STATUS provides the only reliable means of obtaining information about the current state of a list. Attempts to retrieve or infer such information by other means may have unpredictable results. For instance, you might think that the placement of an associated input window could help you obtain the current item’s location within the visible list. However, this assumption might not always be true. (To keep the input window’s movement to a minimum, the window may not always be synchronized with the current item.)

Each information request flag, as shown in the table below, must be followed by its argument field(s). You can specify a maximum of 40 information request flags and return value fields in one call to L_STATUS.

Information request flags

Request flag and return values

Description

D_LABTRSN, reason

Returns the code that indicates the reason for aborting. See the tools.def file. (n)

D_LACTIVEX, list_typ

Returns true (1) if the list is an ActiveX Toolkit list; otherwise, returns false (0). (n)

D_LATBOTTOM, bottom_flag

Returns true (1) if the user is at the bottom of the list (with no more to load at the bottom); otherwise, returns false (0). (n)

D_LATPGBOT, pgbot_flag

Returns true (1) if the user is at the bottom of the page; otherwise, returns false (0). (n)

D_LATPGTOP, pgtop_flag

Returns true (1) if the user is at the top of the page; otherwise, returns false (0). (n)

D_LATTOP, top_flag

Returns true (1) if the user is at the top of the list (with no more to load at the top); otherwise, returns false (0). (n)

D_LAXCTRL, axlist_id

Returns the ID of the ActiveX control used for a list if the list is an ActiveX Toolkit list; otherwise, returns false (0). (n)

D_LCOLSIZED, resized

Returns true (1) if one or more columns in the list have been resized by the user and the list is an ActiveX list; otherwise returns false (0). (n)

D_LCTRID, container_id

Returns the list container window ID. (n)

D_LCURITM, current_item

Returns the current item number. (n)

D_LDATALEN, data_len

Returns the length of the data area passed to L_CREATE, or 0 if no data area was passed. (n)

D_LDISITEM, disable_flag

Returns true (1) if the current item in the list is disabled; otherwise, returns false (0). (n)

D_LENABLED, enabled_flag

Returns true (1) if the list is enabled; otherwise, returns false (0). (n)

D_LFINDCASE, case

Indicates whether the search is case sensitive or case insensitive. See the tools.def file. (n)

D_LFINDCURR, test_current

Indicates whether the current item will be tested as part of the search. See the tools.def file. (n)

D_LFINDDIR, direction

Returns the current direction in which to search. See the tools.def file. (n)

D_LFINDLEN, data_length

Returns the length of the area to search. (n)

D_LFINDPOS, data_position

Returns the current position of the area to search. (n)

D_LFINDSOURCE, find_source

Indicates the area to search, where find_source is D_LFND_DATA to search non-window data or D_LFND_DISPLAY to search display data (associated input window). (n)

D_LFINDSTR, data_string

Returns search string last supplied to L_FINDSPEC. (a)

D_LFINDSTRLEN, string_len

Returns length of last search string supplied to L_FINDSPEC. (n)

D_LFINDTYPE, find_type

Returns current type of search for a find operation. See the tools.def file. (n)

D_LFOUND, found_flag

Returns true (1) if the last D_LFIND request was successful; otherwise, false (0). (n)

D_LFTRID, ftr_win_id

Returns the ID of the window used internally by Toolkit for the list footer. (n)

D_LFTRLNS, #ftr_lns

Returns the number of footer lines in the list. (n)

D_LFTRSTATIC, ftr_static

Returns true (1) if footers are static; otherwise returns false (0). (n)

D_LGETEVENTS, method_set

Returns the method set ID for a list or a value of 0 if there is no method set for the list. (n)

D_LHDRID, hdr_win_id

Returns the ID of the window used internally by Toolkit for the list header. (n)

D_LHDRLNS, #hdr_lns

Returns the number of header lines in the list. (n)

D_LHDRSTATIC, hdr_static

Returns true (1) if headers are static; otherwise returns false (0). (n)

D_LHEIGHT, height

Returns the height of the list as the number of visible items. See the tools.def file. (n)

D_LINPID, input_id

Returns the ID of the input window. (n)

D_LLASTITM, last_item

Returns the highest item number loaded. (n)

D_LLOADSTATE, end, state

Returns the load state for an end (top or bottom) of the list. See D_LLOADSTATE for details.

D_LMETHOD, methodtype, method

Returns the name or address for a list method, or the ID for the %UWNDEVENTS_METHOD set. See D_LMETHOD for details.

D_LNULL, null_flag

Returns true (1) if the current item is null; otherwise, returns false (0). (n)

D_LONENABLED, onenable_flag

Indicates whether the current item as well as the list as a whole, are enabled. See the tools.def file. (n)

D_LPLACED, placed_flag

Returns true (1) if the list is placed; otherwise, returns false (0). (n)

D_LPLACEMENT, row, col

Returns the list row (relative to the screen body) where the list is placed, and the column where the list is placed. (n)

D_LPRISTINE, data, pris_flag

Indicates whether the input window and data buffer are in their initial state. See D_LPRISTINE for details.

D_LQAVAIL, requests

Returns the number of requests that can be added to the request queue via L_QUEUE before the limit of 20 is exceeded. Requests will be one less than the number of requests that can be submitted (because L_PROCESS/L_SELECT use one entry). In other words, if there are three requests in the queue, requests will be returned as 16, though you can actually submit 17 requests. (n)

D_LROW, item_row

Returns the current item’s row number, which specifies the item’s position in the currently visible set of rows. (n)

D_LSTATE, state

Returns a value indicating the state of the list. See D_LSTATE for details. (n)

D_LLOADSTATE

D_LLOADSTATE, end, state

D_LLOADSTATE returns the load state for an end (top or bottom) of the list.

End is one of the following (defined in tools.def): (n)

D_LLOADBOT

Return the load state for the bottom of the list.

D_LLOADTOP

Return the load state for the top of the list.

State is returned as one of the following (defined in tools.def): (n)

DLS_BEGIN

Loading has not begun.

DLS_DONE

Received D_LEOF at the specified end.

DLS_FULL

No more items are needed at this time.

DLS_LOAD

Loading is in progress.

D_LMETHOD

D_LMETHOD, methodtype, method

D_LMETHOD returns the name or address for a list method, or the ID for the %UWNDEVENTS_METHOD set.

Methodtype is one of the following (defined in tools.def): (n)

D_ARRIVE

Return the arrive method name or address.

D_LDBLCLK

Return the double-click method name or address.

D_LLEAVE

Return the leave method name or address.

D_LLOAD

Return the load method name or address.

D_LWNDEVENT

Return the %UWNDEVENTS_METHOD set ID.

Method returns the name of the method if the argument is a or the address of the method if it is n for all methodtypes except D_LWNDEVENT, for which it returns the ID of the %UWNDEVENTS_METHOD. (Method is treated as n for D_LWNDEVENT, so if it is declared a, the ID is returned as a decimal value.) (a or n)

D_LPRISTINE

D_LPRISTINE, data, pris_flag

D_LPRISTINE indicates whether the input window and data buffer are in their initial state, that is, the state they were in when L_CREATE was called.

Data is the data buffer, supplied by the calling routine, rather than returned to it. Data is required here if the data argument was also passed to L_CREATE when the list was created. If data is passed here but was not passed to L_CREATE, a fatal error occurs. (a)

Pris_flag returns true (1) if the data buffer and input window are in their initial state; otherwise, it returns false (0). (n)

D_LSTATE

D_LSTATE, state

D_LSTATE returns one of the following, indicating the state of the list (defined in tools.def): (n)

D_LNORMAL

List is in normal state.

D_LMAXIMIZED

List is maximized.

D_LMINIMIZED

List is minimized.

D_LHIDDEN

List is hidden.

Examples

The following example retrieves the placement values and placement status of the list whose ID is stored in order_lst.

xcall l_status(order_lst, D_LPLACEMENT, row, column, D_LPLACED, placed)

The next example returns the reason for the abort flag, returned from a previous call to L_PROCESS, on the list whose ID is stored in mylst.

xcall l_status(mylst, D_LABTRSN, abort_code)

The next example submits a FIND request to the list processor and then calls L_STATUS to determine whether the FIND was successful. The find status is returned in found.

xcall l_findspec(lstid, fname)
req = D_LFIND                             ;Submit a FIND request
xcall l_process(lstid, req, data)         ;Process the request
xcall l_status(lstid, D_LFOUND, found)     ;Was it found?
if(.not.found)
  xcall u_message("Item not found")