I_LDINP

Load an input window from a library

xcall I_LDINP(window_id, [channel], window_name, [D_NOPLC], [search], [error]
&     [, saved_name])

Arguments

window_id

Returned with the ID of the input window. (n)

channel

(optional) The channel of the window library. If not passed, g_utlib is used. (n)

window_name

The name of the window to load (a maximum of 15 characters). (a)

D_NOPLC

(optional) Don’t place the loaded input window on the screen. (n)

(optional) The search variable. (n)

error

(optional) The error return variable. (n)

saved_name

(optional) The name of the window when it was originally saved. (a)

Discussion

I_LDINP loads an input window from a library. An input window must be loaded before it can be referenced by any other I_xxx routine.

When an input window is loaded, all associated selection windows are also loaded. These selection windows are marked as being owned by the input window. When you delete the window (with U_WINDOW or E_EXIT), the selection windows using the .FIELD SELECT qualifier are also deleted. (Those using the .FIELD SELWND qualifier are not.)

If you pass a null string (“ ”) for window_name, Toolkit assigns a unique window name in the form _W_nnn, where nnn is the window ID. You must pass saved_name in this case.

If you want to create multiple instances of the same window, you can call I_LDINP as many times as you need, using window_name to give each succeeding window a new unique name. You must also pass saved_name, if window_name is different than the name under which the window was saved.

If you place the window (you omit D_NOPLC), the window must fit on the screen or you will receive a Window Manager error ($ERR_WNDERR) when Toolkit loads the window.

If search is present, I_LDINP searches for an existing window with the specified name before attempting to load the window. If the window is found, a successful load is simulated, window_id is set to the ID of the window that was found, and the search variable is set to true. If the window is not found, the search variable is cleared and loading continues normally.

You can use search to make your subroutines more modular. If you have written your routines to call E_ENTER on entry and E_EXIT before returning, use the search variable with I_LDINP within your subroutines to load windows.

Search will find the window, if already loaded, or it will enable I_LDINP to load it if it can’t find it. Since the window will be a local window in the latter case, E_EXIT will delete it when it returns to the calling routine. If search finds the window already loaded and if it was loaded at a prior level, E_EXIT will leave it loaded when it returns.

If error is present, it is returned with one of the following values:

0 (false) if the requested window was found in the specified library.
1 (true) if the window was not found.
-1 if the window (window_id) has an associated selection window that cannot be loaded. You can use %U_GETWNDERR to get the text of the error: “Window name not found in library channel,” where name is the name of the missing selection window, and channel is the channel number passed to I_LDINP (or the value of g_utlib if no channel was passed).

A fatal error occurs if error is not present and the window (window_id) or an associated selection window cannot be found.

See also

M_LDCOL routine for information on loading menu columns
U_LDWND routine for information on loading general windows and for information on directly loading selection windows that may not be associated with input windows

Examples

In the first example, the subroutine attempts to load the window named cusmas from the library opened on channel g_utlib. The variable inpid is returned with the ID of the input window. If the window isn’t in the library, a fatal error occurs.

xcall i_ldinp(inpid,, "cusmas")

In the second example, I_LDINP attempts to load but does not place the window artran from the library opened on libchn. Again, inpid is returned with the ID of the input window. The success of the operation is reported in errcode. If the window already exists, an error occurs.

xcall i_ldinp(inpid, libchn, "artran", D_NOPLC,, errcode)

In the third example, I_LDINP searches for the window named cusmas before it attempts to load it and place it on the screen. If it finds the window, it will store the window ID in inpid and set find to true; otherwise, it will load the window named cusmas. If the window is loaded successfully, errcode is returned with a value of false.

xcall i_ldinp(inpid,, "cusmas",, find, errcode)