Return information about environment processing
|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
return = %E_INFO(subfunction[, arg, ...])
Return value
return
A value specific to the subfunction. (^VAL)
Arguments
subfunction
The specific function to perform. It must be one of the following: (n)
Return the environment level at which a channel is logged.
Return the highest channel number that Toolkit can use.
Return the number of channels logged in a level.
Return the current display level.
Return the current environment level.
Return the environment level at which a list is logged.
Return the number of lists logged in a level.
Return the maximum environment level.
Return the address of the current method routine.
Return true if successful; otherwise, false.
Return the month number (1-12).
Return the number of rows available in a section.
Return the length of text in a section.
Return a true/false flag indicating whether a state code is on or off.
Return the environment level for a toolbar.
Return a list of toolbars at a given environment level.
Return the environment level at which a window is logged.
Return the type of a window.
Return the number of windows logged in a level.
arg
(optional) One or more arguments, depending on subfunction.
Discussion
%E_INFO is used to return information about the current environment. See the individual subfunctions for details.
This example retrieves the total number of all windows in order to allocate an array to hold their IDs, determines which windows are input windows, and then displays all the IDs of the input windows.
.align
stack record
array_hndl ,i4 ;Handle to an allocated array
nmwnds ,i4 ;Number of windows in the array
ix ,i4 ;An index into the array
wndid ,i4 ;A window ID
structure window_array ;Structure for the allocated memory
id ,i4 ;A window ID
proc
nmwnds = %e_info(D_WINDOWS,,, D_ALL) ;Get number of windows
array_hndl = %mem_proc(DM_ALLOC, nmwnds * ^size(window_array))
;Allocate the array
xcall e_info(D_WINDOWS, nmwnds, ^m(window_array.id, array_hndl),
& D_ALL) ;Retrieve the IDs
for ix from 1 thru nmwnds ;Loop through the ID's
begin
wndid = ^m(window_array[ix].id, array_hndl);Get one
;Is it an input window?
if (%e_info(D_WINDOW_TYPE, wndid) .eq. D_WTYPE_INPUT)
xcall u_message("ID " + %string(wndid) + " is an input window")
end
xcall mem_proc(DM_FREE, array_hndl) ;Free the array
The following example is similar to the first, but it uses the maximum array size.
.include "WND:system.def"
.align
stack record
array ,[D_MAXWND] i4 ;Array of window IDs
nmwnds ,i4 ;Number of windows
ix ,i4 ;Index into the array
proc
;Retrieve the IDs and the count
nmwnds = %e_info(D_WINDOWS, D_MAXWND, array, D_ALL)
for ix from 1 thru nmwnds ;Loop thru the IDs
begin
;Is it an input window?
if (%e_info(D_WINDOW_TYPE, array[ix]) .eq. D_WTYPE_INPUT)
begin
xcall u_message("ID " + %string(array[ix]) + " is an input window")
end
end
In the next example, an EUTILS_METHOD environment method calls any previously registered method if it does not know how to handle a menu entry.
subroutine my_utils_method,reentrant
;
; Description: A utility menu entry method that can inherit from
; the previously registered method.
;
; Arguments:
a_record ,a ;(Optional) record passed to I_INPUT
;
.include "WND:tools.def"
.align
stack record
my_method ,D_ADDR ;Address of this routine
prev_method ,D_ADDR ;Address of previous level routine
lvl ,i4 ;An environment level index
proc
using g_entnam select ;Do we know this entry?
("U_ENTRY1 "),call entry1
("U_ENTRY2 "),call entry2
() ,call unknown ;No, let's pass it back to previous method
endusing
xreturn
entry1,
;(Code to process entry U_ENTRY1)
return
entry2,
;(Code to process entry U_ENTRY2)
return
unknown,
;First, get our address to compare against
my_method = %e_info(D_METHOD, D_METH_UTILS)
;Now, beginning with the previous level, find the method that was ; registered prior to this one
for lvl from (%e_info(D_ENV_LEVEL) - 1) thru 1 by -1
begin
prev_method = %e_info(D_METHOD, D_METH_UTILS, lvl)
;Get the method for level lvl
if (prev_method .ne. my_method)
begin ;Back to before my_method was registered
if (prev_method) ;Zero means "no method"
xcall xsubr(prev_method, a_record)
;Invoke previous method, if one was
; registered
exitloop ;Don't invoke any others
end
end
return
endsubroutine
env_level = %E_INFO(D_CHANNEL_LEVEL, channel)
Return value
env_level
The environment level at which the channel is logged or one of the following: (^VAL)
No channel is logged with the specified ID.
The channel is global.
The channel is owned by the Toolkit system processing.
Arguments
channel
The channel number. (n)
Discussion
The D_CHANNEL_LEVEL subfunction of %E_INFO obtains the environment level at which the specified channel is logged.
If the channel is invalid, a fatal error occurs.
max_channel = %E_INFO(D_CHANNEL_MAX)
Return value
max_channel
The highest channel number that Toolkit can use. (^VAL)
Discussion
The D_CHANNELS subfunction of %E_INFO returns the highest channel number that Toolkit can use. This limit is set by U_START.
channels_logged = %E_INFO(D_CHANNELS, [channels_req], [channels][, env_level])
or
xcall E_INFO(D_CHANNELS, [channels_req], [channels][, env_level])
Return value
channels_logged
The number of channels logged. (^VAL)
Arguments
channels_req
(optional) The number of channels requested. (n)
channels
(optional) The returned array of channel numbers. (n)
env_level
(optional) The environment level (a value between 1 and the current environment), or one of the following. (n)
All environment levels including global.
The global environment level.
The current environment level. (default)
Discussion
The D_CHANNELS subfunction of %E_INFO obtains the number of channels logged.
Because channels_req and channels are optional and the channels_logged return value indicates the size needed to contain channels, you can call D_CHANNELS once without passing channels_req and channels to get the necessary size. Then, allocate the required space before calling the subfunction again, passing channels_req and channels to obtain the array of channel numbers.
In the case of an array return argument like channels, the number of elements requested can be specified in the channels_req argument. This allows you to avoid overrunning the array boundary if the array passed is smaller than the total number of items. The array reference passed should refer to the array’s first element. %E_INFO will treat this as the base of a pseudo array into which to write the returned channels.
Instead of sizing the channels array dynamically, the calling routine can allocate the maximum possible size by passing D_MAXCHN for channels_req. D_MAXCHN is defined in system.def.
If env_level is not passed or 0, D_LOCAL is assumed. If a value is passed that is greater than the current environment level, a fatal error occurs.
dsp_level = %E_INFO(D_DSP_LEVEL)
Return value
dsp_level
The current display level. (^VAL)
Discussion
The D_DSP_LEVEL subfunction of %E_INFO obtains the current display level.
env_level = %E_INFO(D_ENV_LEVEL)
Return value
env_level
The current environment level, or 0 if Toolkit is not active. (^VAL)
Discussion
The D_ENV_LEVEL subfunction of %E_INFO enables you to determine if Toolkit is active (i.e., if it has been initialized with U_START but not terminated with U_FINISH). And if Toolkit is active, this subfunction returns the current environment level.
Examples
The following example checks whether or not you can enter a new environment.
if (%e_info(D_ENV_LEVEL) .le. %e_info(D_MAX_ENV_LEVEL)) then
xcall e_enter
else
xcall u_message("Cannot enter a new environment - " +
& "maximum levels already in use")
The next example determines whether Toolkit is active and initializes it if it’s not active:
if (!%e_info(D_ENV_LEVEL)) then xcall u_start . . .
Also see Examples.
env_level = %E_INFO(D_LIST_LEVEL, list_id)
Return value
env_level
The environment level at which list_id is logged or one of the following: (^VAL)
No list is logged with the specified ID.
The list is global.
The list is owned by the Toolkit system processing.
Arguments
list_id
The list ID. (n)
Discussion
The D_LIST_LEVEL subfunction of %E_INFO obtains the environment level at which the specified list is logged.
If list_id is invalid, a fatal error occurs.
lists_logged = %E_INFO(D_LISTS, [lists_req], [list_id][, env_level])
or
xcall E_INFO(D_LISTS, [lists_req], [list_id][, env_level])
Return value
lists_logged
The number of lists logged at the specified level. (^VAL)
Arguments
lists_req
(optional) The number of lists requested. (n)
list_ids
(optional) The returned array of list IDs. (n)
env_level
(optional) The environment level, or one of the following. (n)
All environment levels including global.
The global environment level.
The current environment level. (default)
Discussion
The D_LISTS subfunction of %E_INFO obtains the number of lists logged in a level.
Because the lists_req and list_ids arguments are optional and the lists_logged return value indicates the size needed to contain the list_ids argument, %E_INFO(D_LISTS) can be called once without passing lists_req and list_ids to get the necessary size. Then, allocate the required space before calling the D_LISTS subfunction again, passing lists_req and list_ids to obtain the array of list IDs.
In the case of an array return argument like list_ids, the number of elements requested can be specified in the lists_req argument. This allows you to avoid overrunning the array boundary if the array passed is smaller than the total number of items. The array reference passed should refer to the array’s first element. %E_INFO will treat this as the base of a pseudo array into which to write the returned lists.
Instead of sizing the list_ids array dynamically, the calling routine can also allocate the maximum possible size by passing D_MAXLST for lists_req. D_MAXLST is defined in WND: system.def.
max_env_level = %E_INFO(D_MAX_ENV_LEVEL)
Return value
max_env_level
The maximum environment level. (^VAL)
Discussion
The D_MAX_ENV_LEVEL subfunction of %E_INFO obtains the maximum environment levels specified at the time that U_START was called. This is usually D_DFLTENV, but it can be as high as D_MAXENV. Both of these constants are defined in WND: system.def.
Examples
The following example checks whether or not you can enter a new environment.
if (%e_info(D_ENV_LEVEL) .le. %e_info(D_MAX_ENV_LEVEL)) then
xcall e_enter
else
xcall u_message("Cannot enter a new environment - " +
& "maximum levels already in use")
method_addr = %E_INFO(D_METHOD, method_code[, env_level])
Return value
method_addr
The address (D_ADDR) of the specified method routine if registere0d, or 0 if not registered. (^VAL)
Arguments
method_code
Get one of the following addresses: (n)
Application close method.
Application move method.
Application resize method.
Application state method.
Century method.
User field validation method.
User field display method.
User field edit display method.
Key mapping method.
Help method.
Script compilation error method.
Utilities method.
env_level
(optional) Either the environment level or D_LOCAL (for current environment level; default). (n)
Discussion
The D_METHOD subfunction of %E_INFO obtains the address of the routine defined in method_code.
This subfunction is useful for nested components where each component provides a method for an environment-level event. In this case, the innermost component can add functionality without overloading the method of the outer component. Prior to registering the method for the new environment, the component can save off the address of the previous method, then invoke it within the new method using %XSUBR. Note also that this address can be used to re-register the previous method without invoking E_EXIT.
Env_level can be a value between 1 and the current environment level or D_LOCAL. If env_level is not passed or 0, D_LOCAL is assumed. If a value is passed that is greater than the current environment level, a fatal error occurs.
See also
E_METHOD routine for information on registering methods
Examples
See Examples above.
status = %E_INFO(D_MONTH_ABBREV, month_num, month_abbrev)
Return value
status
True if successful; false (0) if not. (^VAL)
Arguments
month_num
The month number (1-12). (n)
month_abbrev
The returned month abbreviation as defined by UI Toolkit. (a)
Discussion
The D_MONTH_ABBREV subfunction of %E_INFO obtains the month abbreviation for a specified month number.
If month_num is not between 1 and 12, this subfunction returns false and no month abbreviation is returned.
See also
U_MONTHS routine for assigning alpha characters to represent months
month _num = %E_INFO(D_MONTH_NUMBER, month_abbrev)
Return value
month_num
The month number (1-12) if found; otherwise, returns 0. (^VAL)
Arguments
month_abbrev
The month abbreviation as defined by UI Toolkit. (a)
Discussion
The D_MONTH_NUMBER subfunction of %E_INFO obtains the month number for a specified month abbreviation.
If month_abbrev is not a valid month abbreviation as defined by UI Toolkit, this subfunction returns 0.
See also
U_MONTHS routine for assigning alpha characters to represent months
rows = %E_INFO(D_SECT_ROWS, section)
Return value
rows
The number of rows available in a section, or 0 if the section doesn’t exist. (^VAL)
Arguments
section
One of the following sections: (n)
Reference a Microsoft Windows caption.
Reference the footer section.
Reference the header section.
Reference the information line.
Discussion
The D_SECT_ROWS subfunction of %E_INFO obtains the number of rows available in a specified section of the display screen.
If section doesn’t exist in the display screen, this subfunction returns 0.
text _length = %E_INFO(D_SECT_TEXT, [text_buffer], section, [row][, env_level])
or
xcall E_INFO(D_SECT_TEXT, [text_buffer], section, [row][, env_level])
Return value
text _length
The length of text in a section if successful; otherwise, returns 0. (^VAL)
Arguments
text_buffer
(optional) The returned text buffer. (a)
section
One of the following sections: (n)
Reference a Microsoft Windows caption.
Reference the footer section.
Reference the header section.
Reference the information line.
row
(optional) The row number. (n)
env_level
(optional) Either the environment level or D_LOCAL (for current environment level; default). (n)
Discussion
The D_SECT_TEXT subfunction of %E_INFO returns the entire text for a specified section within an environment.
In traditional Synergy on Windows the text may not be displayed as one string (for example, left-justified, centered, and right-justified sections), but within UI Toolkit it is stored internally as one logical string.
Because the text_buffer argument is optional and the text _length return value indicates the size needed to contain the text_buffer argument, %E_INFO (D_SECT_TEXT) can be called once without passing text_buffer to get the necessary size. Then, allocate the required space before calling the D_SECT_TEXT subfunction again, passing text_buffer to obtain the text.
If section doesn’t exist in the display screen, this subfunction returns 0.
Env_level can be a value between 1 and the current environment level or D_LOCAL. If env_level is not passed or 0, D_LOCAL is assumed. If a value is passed that is greater than the current environment level, a fatal error occurs.
See also
E_SECT routine for information on placing text into a section of the display screen
state_flag = %E_INFO(D_STATE, state[, env_level])
Return value
state_flag
A true/false flag indicating whether a state code is on or off. (^VAL)
Arguments
state
One of the following: (n)
Advance context for combo boxes.
Display a screen cursor.
Echo terminal input.
Follow European formatting conventions.
Apply the Input Field Processing or Read-Only Input Field Processing renditions to the field that has focus during input processing.
Override field-level rendition settings (color and attribute settings) with Input Field Processing or Read-Only Input Field Processing renditions.
Allow interrupt characters.
Wait for locked records.
Allow lowercase terminal input.
Wait for messages.
Enter key simulates a key press of the default button.
Validate immediately on a state change of certain field types.
env_level
(optional) Either the environment level (a value between 1 and the current environment level) or D_LOCAL (for current environment level; default). (n)
Discussion
The D_STATE subfunction of %E_INFO obtains the on/off status for a specified state code.
If env_level is not passed or 0, D_LOCAL is assumed. If the passed value is greater than the current environment level, a fatal error occurs.
See also
E_STATE routine for information on modifying the state of the current environment
env_level = %E_INFO(D_TOOLBAR_LEVEL, toolbar_id)
Return value
env_level
The environment level at which a toolbar is logged, or D_FREE (no toolbar is logged with the specified ID), or D_GLOBAL (the toolbar is global). (^VAL)
Arguments
toolbar_id
The toolbar ID. (n)
Discussion
The D_TOOLBAR_LEVEL subfunction of %E_INFO returns the environment level at which the specified toolbar is logged. If the toolbar was neither created nor logged with Toolkit, D_FREE is returned.
If toolbar_id is invalid, a fatal error occurs.
num_toolbars = %E_INFO(D_TOOLBARS, [toolbars_req], [toolbars_ids][, env_level])
or
xcall E_INFO(D_TOOLBARS, [toolbars_req], [toolbars_ids][, env_level])
Return value
num_toolbars
The number of toolbars logged for a given environment level. (^VAL)
Arguments
toolbars_req
(optional) The number of toolbars requested or D_MAXTB to allocate the maximum possible size for the returned array. (n)
toolbar_ids
(optional) The returned array of toolbar IDs. (n)
env_level
(optional) The environment level, or one of the following: (n)
All environment levels including global.
The global environment level.
The current environment level. (default)
Discussion
The D_TOOLBARS subfunction of %E_INFO obtains the number of toolbars logged for a given environment level.
Because the toolbars_req and toolbar_ids arguments are optional and the num_toolbars return value indicates the size needed to contain the toolbar_ids argument, %E_INFO (D_TOOLBARS) can be called once without passing toolbars_req and toolbar_ids to get the necessary size. Then, allocate the required space before calling the D_TOOLBARS subfunction again, passing toolbars_req and toolbar_ids to obtain the array of toolbar IDs.
The number of elements requested in the toolbar_ids array can be specified in the toolbars_req argument. This allows you to avoid overrunning the array boundary if the array passed is smaller than the total number of items. However, the array should have at least as many elements as the number passed for toolbars_req. The array reference passed should refer to the array’s first element. %E_INFO will then treat this as the base of a pseudo array into which to write the returned toolbar IDs.
The calling routine can also allocate the maximum possible size by passing D_MAXTB for the toolbars_req argument and sizing the array to this same maximum. D_MAXTB is defined in WND: system.def.
Env_level can be a value (between 1 and the current environment level), D_ALL, D_GLOBAL, or D_LOCAL. If env_level is not passed or is passed as 0, D_LOCAL is assumed. If env_level is greater than the current environment level, a fatal error occurs.
env_level = %E_INFO(D_WINDOW_LEVEL, window_id)
Return value
env_level
The environment level at which the window is logged, or one of the following: (^VAL)
No window is logged with the specified ID.
The window is global.
The window is owned by the Toolkit system processing.
Arguments
window_id
The window ID. (n)
Discussion
The D_WINDOW_LEVEL subfunction of %E_INFO obtains the environment level at which the specified window is logged.
If window_id is invalid, a fatal error occurs.
window_type = %E_INFO(D_WINDOW_TYPE, window_id)
Return value
window_type
One of the window types listed in the table below. (^VAL)
Arguments
window_id
The window ID whose type you want to retrieve. (n)
Discussion
The D_WINDOW_TYPE subfunction of %E_INFO obtains the window type for a specified window ID. It may return any of the following:
|
Return value |
Window description |
|---|---|
|
D_WTYPE_ACTIVEX |
Container window for an ActiveX control. (Created by %AX_TKWIN or %AX_TKSINGLE.) |
|
D_WTYPE_COLUMN |
Menu column. (Created by the .COLUMN script command or by calling MB_END.) |
|
D_WTYPE_CONTAINER |
Composite container window. (Created by the DC_CREATE subfunction to %C_CONTAINER.) |
|
D_WTYPE_DOTNET |
Container window for a .NET form, .NET control, or WPF element. (Created by %DOTNET_TKWIN.) |
|
D_WTYPE_INPUT |
Input window (Created by the .INPUT script command or by calling the IB_END routine.) |
|
D_WTYPE_LISTCLASS |
List class (Created by the .LISTCLASS script command or by calling L_CLASS.) |
|
D_WTYPE_SELECT |
Selection window (Created by the .SELECT script command, by calling S_SELBLD, or by calling I_LDINP for a .FIELD script command with a SELECT qualifier.) |
|
D_WTYPE_TABS |
Tabbed window (Created by %TS_TABSET.) |
|
D_WTYPE_TEXT |
Text window (A window for which T_SETUP has been called—there’s no other distinction in Toolkit between a text window and a general window.) |
|
D_WTYPE_OTHER |
None of the above. |
If U_DLWND was used to load the window, D_WINDOW_TYPE returns D_WTYPE_OTHER, making D_WINDOW_TYPE useful only for windows loaded with a type-specific routine—for example, I_LDINP for an input window.
|
The %U_WNDTYPE routine returns a window’s type regardless of the routine used to load the window. |
It is possible that more window types will be added to the list in the future and that D_WTYPE_OTHER could at some point encompass different types of windows. Consequently, it should only be used as an “else” case.
Examples
See Examples above.
num_windows = %E_INFO(D_WINDOWS, [windows_req], [window_ids][, env_level])
or
xcall E_INFO(D_WINDOWS, [windows_req], [window_ids][, env_level])
Return value
num_windows
The number of windows logged in a level. (^VAL)
Arguments
windows_req
(optional) The number of windows requested. (n)
window_ids
(optional) The returned array of window IDs. (n)
env_level
(optional) The environment level, or one of the following: (n)
All environment levels including global.
The global environment level.
The current environment level. (default)
Discussion
The D_WINDOWS subfunction of %E_INFO obtains the number of windows logged in a level.
Because windows_req and window_ids are optional and the num_windows return value indicates the size needed to contain window_ids, you can D_WINDOWS once without passing windows_req and window_ids to get the necessary size. Then, allocate the required space before calling the subfunction again, passing windows_req and window_ids to obtain the array of window IDs.
In the case of an array return argument like window_ids, the number of elements requested can be specified in the windows_req argument. This allows you to avoid overrunning the array boundary if the array passed is smaller than the total number of items. The array reference passed should refer to the array’s first element. %E_INFO will treat this as the base of a pseudo array into which to write the returned windows.
Instead of sizing the window_ids array dynamically, the calling routine can also allocate the maximum possible size by passing D_MAXWND for the windows_req argument. D_MAXWND is defined in WND: system.def.
Env_level can be a value between 1 and the current environment level, D_ALL, D_GLOBAL, or D_LOCAL. If env_level is not passed or 0, D_LOCAL is assumed. If a value is passed that is greater than the current environment level, a fatal error occurs.
See Examples above.
