U_START

Initialize the UI Toolkit environment

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall U_START([util_lib], [header_lines], [footer_lines], [pool_size], [screen_rows], 
&     [screen_columns], [text_lib], [first_channel], [#env_levels], [last_channel]
&     [, start_method[, elb]])

Arguments

util_lib

(optional) The utility (window) library filename. (a)

header_lines

(optional) The number of lines (in the range 0 to 4) in the screen header section. If not passed or 0, the header section is not created or displayed on the screen. (n)

footer_lines

(optional) The number of lines (in the range 0 to 4) in the screen footer section. If not passed or 0, the footer section is not created or displayed on the screen. (n)

pool_size

(optional) The size of the windows pool, in bytes. This argument is deprecated for Synergy DBL version 5 and higher, and is therefore ignored. (n)

screen_rows

(optional) The number of rows on the screen. (n)

screen_columns

(optional) The number of columns on the screen. (n)

text_lib

(optional) The text library filename. (a)

first_channel

(optional) The number (from 1 to 253) of the first channel available. If not passed, defaults to 1. (n)

#env_levels

(optional) The number (from 2 to 32) of allowed environment levels. If not passed, defaults to 16 to conserve memory. (n)

last_channel

(optional) The number (from 3 to 255) of the last channel available. If not passed or greater than 255, defaults to 255. (n)

start_method

(optional) The name of a USTART_METHOD subroutine you have written. (a)

elb

(optional) The name of the library from which start_method will be drawn. If not passed, Toolkit searches for start_method in the program image or previously opened ELBs. (a)

Discussion

U_START initializes the UI Toolkit environment. It should be the first call in your application’s Toolkit layer. It detects and records (but does not change) any pre‑existing environment states. If you want to modify these states, use E_STATE.

If util_lib is present and non‑blank, the specified library

On Windows, if header_lines is specified as 1 (one) line, the Windows environment application “caption” is used to display the header instead of the typical Toolkit header section. If the header is more than one line in size, an area is still allocated within the application window. The text for a Windows application window caption can be explicitly referenced using the D_CAPTION argument flag in the E_SECT subroutine.

The default value for screen_rows is 24 (25 on Windows). The default value for screen_columns is 80. (You cannot call U_START to resize the screen.) On Windows, if screen_rows or screen_columns is not passed, UI Toolkit uses the APP_WIDTH and APP_HEIGHT initialization settings to determine the screen size. If those are not specified, the size is 25 rows by 80 columns.

The text_lib argument enables you to use translated text in your Toolkit applications by specifying a text message file. This text message file, or library, is an ISAM file that will be opened in read‑only mode. If you don’t specify text_lib, UI Toolkit uses SYNTXT:syntxt.ism by default. If not found, UI Toolkit uses DBLDIR:syntxt.ism.

If first_channel and last_channel are passed, U_START closes only channels in use in the range defined by these arguments. If they are not passed, U_START closes all channels in use from 1 to 255, which could close channels in use by other Synergy programs that are using the runtime. To prevent this, specify a range. For information on how this could affect xfServerPlus, see Removing user interface elements.

If you specify first_channel and last_channel, any channel previously in use within the range specified by these arguments will be purged. If you don’t specify these arguments, UI Toolkit defaults to “owning” the entire range (1 to 255).

First_channel is the first channel number available to Toolkit. If not passed, it defaults to 1. This will also be the channel used for the terminal unless W_INIT has been called previously and specifies another channel. All channel numbers less than first_channel will be logged as “system” channels to Toolkit, and should not be referenced again through any Toolkit subroutine.

Last_channel is the last channel number available to Toolkit. Since Toolkit requires at least 3 channels, last_channel should never be less than 3. If it is not passed or more than 255, it defaults to 255. All channel numbers greater than last_channel will be logged as “system” channels to UI Toolkit, and should not be referenced again through any Toolkit subroutine.

If start_method is passed, just prior to returning to the calling routine, U_START calls this method to allow application‑specific start‑up processing. Note that if DTKDBG is set, the Toolkit debugger checks to make sure the method can be invoked.

See also

Examples

In the following example, U_START opens the window library WND:util and initializes the Toolkit environment. The header section has 3 lines, and the footer section has 2 lines.

xcall u_start("WND:util", 3, 2)

The following example opens a window library called WND:util and initializes the Toolkit environment. The header and footer sections are not created.

xcall u_start("WND:util")

In this example, the opened window library is also called WND:util. The header and footer screen sections are not created, the screen has 25 rows, and text messages are located in WND:txtlib.

xcall u_start("WND:util",,,, 25,, "WND:txtlib")