U_START

Initialize the UI Toolkit environment

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) This argument was deprecated in Synergy DBL version 5 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

is opened in I:I mode with the “nolock” (\NL) option set.
is promoted to global status.
has its allocated channel placed in the g_utlib field (defined in tools.def).

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

The Renditions table for information on initial rendition settings established by U_START
U_FINISH routine for information about closing and purging channels at application shut down
U_OPEN routine for information on opening channels
U_CLOSE routine for information on closing or purging channels
U_GETCHN routine for information about how to allocate a channel (usually used only to convert applications)
E_STATE routine for information about modifying the environment states
E_SECT routine for information about how to display text in screen sections
USTART_METHOD routine for information about writing your application start-up method

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