%E_INFO

Return information about environment processing

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
return = %E_INFO(subfunction[, arg, ...])

return

A value specific to the subfunction. (^VAL)

Arguments

subfunction

The specific function to perform. It must be one of the following: (n)

D_CHANNEL_LEVEL

Return the environment level at which a channel is logged.

D_CHANNEL_MAX

Return the highest channel number that Toolkit can use.

D_CHANNELS

Return the number of channels logged in a level.

D_DSP_LEVEL

Return the current display level.

D_ENV_LEVEL

Return the current environment level.

D_LIST_LEVEL

Return the environment level at which a list is logged.

D_LISTS

Return the number of lists logged in a level.

D_MAX_ENV_LEVEL

Return the maximum environment level.

D_METHOD

Return the address of the current method routine.

D_MONTH_ABBREV

Return true if successful; otherwise, false.

D_MONTH_NUMBER

Return the month number (1-12).

D_SECT_ROWS

Return the number of rows available in a section.

D_SECT_TEXT

Return the length of text in a section.

D_STATE

Return a true/false flag indicating whether a state code is on or off.

D_TOOLBAR_LEVEL

Return the environment level for a toolbar.

D_TOOLBARS

Return a list of toolbars at a given environment level.

D_WINDOW_LEVEL

Return the environment level at which a window is logged.

D_WINDOW_TYPE

Return the type of a window.

D_WINDOWS

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.

Examples

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

D_CHANNEL_LEVEL

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)

D_FREE

No channel is logged with the specified ID.

D_GLOBAL

The channel is global.

D_SYS

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.

D_CHANNEL_MAX

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.

D_CHANNELS

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)

D_ALL

All environment levels including global.

D_GLOBAL

The global environment level.

D_LOCAL

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.

D_DSP_LEVEL

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.

D_ENV_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.

D_LIST_LEVEL

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)

D_FREE

No list is logged with the specified ID.

D_GLOBAL

The list is global.

D_SYS

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.

D_LISTS

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)

D_ALL

All environment levels including global.

D_GLOBAL

The global environment level.

D_LOCAL

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.

D_MAX_ENV_LEVEL

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")

D_METHOD

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)

D_METH_APPCLOSE

Application close method.

D_METH_APPMOVE

Application move method.

D_METH_APPSIZE

Application resize method.

D_METH_APPSTATE

Application state method.

D_METH_CENTURY

Century method.

D_METH_CHKFLD

User field validation method.

D_METH_DSPFLD

User field display method.

D_METH_EDTDS

User field edit display method.

D_METH_FKEY

Key mapping method.

D_METH_HELP

Help method.

D_METH_SCRIPTERR

Script compilation error method.

D_METH_UTILS

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.

E_METHOD routine for information on registering methods

See Examples above.

D_MONTH_ABBREV

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.

U_MONTHS routine for assigning alpha characters to represent months

D_MONTH_NUMBER

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.

U_MONTHS routine for assigning alpha characters to represent months

D_SECT_ROWS

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)

D_CAPTION

Reference a Microsoft Windows caption.

D_FOOTER

Reference the footer section.

D_HEADER

Reference the header section.

D_INFO

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.

D_SECT_TEXT

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)

D_CAPTION

Reference a Microsoft Windows caption.

D_FOOTER

Reference the footer section.

D_HEADER

Reference the header section.

D_INFO

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.

E_SECT routine for information on placing text into a section of the display screen

D_STATE

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)

D_CBADVANCE

Advance context for combo boxes.

D_CURSOR

Display a screen cursor.

D_ECHO

Echo terminal input.

D_EURO

Follow European formatting conventions.

D_INPPRCRND

Apply the Input Field Processing or Read-Only Input Field Processing renditions to the field that has focus during input processing.

D_INPRNDOVER

Override field-level rendition settings (color and attribute settings) with Input Field Processing or Read-Only Input Field Processing renditions.

D_INTR

Allow interrupt characters.

D_LOCKWAIT

Wait for locked records.

D_LOWER

Allow lowercase terminal input.

D_MSGWAIT

Wait for messages.

D_RETURNBTN

Enter key simulates a key press of the default button.

D_VALSTCHG

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.

E_STATE routine for information on modifying the state of the current environment

D_TOOLBAR_LEVEL

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.

D_TOOLBARS

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)

D_ALL

All environment levels including global.

D_GLOBAL

The global environment level.

D_LOCAL

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.

D_WINDOW_LEVEL

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)

D_FREE

No window is logged with the specified ID.

D_GLOBAL

The window is global.

D_SYS

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.

D_WINDOW_TYPE

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.

Tip

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.

See Examples above.

D_WINDOWS

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)

D_ALL

All environment levels including global.

D_GLOBAL

The global environment level.

D_LOCAL

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.