U_GETCHN

Obtain a channel

xcall U_GETCHN(allocated_channel, [D_GLOBAL][, requested_channel])

Arguments

allocated_channel

Returned with the allocated channel. (n)

D_GLOBAL

(optional) Allocate channel as global. (n)

requested_channel

(optional) The channel number requested. (n)

Discussion

U_GETCHN obtains a channel for your own use.

If U_GETCHN is called without first calling U_START, U_GETCHN automatically calls U_START with no arguments. When U_START is called without specifying a first and last channel argument, all channels in the range of 1 to 255 are closed. To prevent the channel opened by your program from being closed by this behavior, call U_START before calling U_GETCHN. In the U_START call, specify a range of channels (using the first and last channel arguments) that does not include the channel your program has opened. See U_START for more information.

If D_GLOBAL is present, the channel is allocated as global rather than local (meaning that it has to be explicitly purged rather than being purged implicitly upon exit from the current environment). U_FINISH will purge the global channels.

If you do not specify requested_channel, the channel returned in allocated_channel is the first channel available. Allocated_channel is returned as 0 if requested_channel is not available for usage. If requested_channel is specified and available, it is used.

You can use this subroutine in conjunction with specifying U_OPEN’s D_NOALLOC flag. Its primary use is in converting existing applications. If you allocate channels ahead of time and make them global, your existing logic will work.

We recommend that you use U_GETCHN only when converting your applications to use UI Toolkit. Channel allocation is best handled by UI Toolkit’s U_OPEN subroutine and this subroutine can help you coincide your application’s current channel usage with U_OPEN’s future channel allocation. During conversion, you can request a certain channel number (with requested_channel) and then have U_OPEN use that channel rather than allocating a new one.

After conversion, we recommend that you don’t use U_GETCHN to explicitly allocate channels. Allowing U_OPEN to maintain channel usage will help you keep your application modular.