U_OPEN

Open a channel/file

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall U_OPEN(channel, [I/O_mode], filename, [options], [search], [error] [, D_NOALLOC])

Arguments

channel

Returned with the allocated channel. (n)

I/O_mode

(optional) The I/O mode in which to open the file. If not passed, defaults to I:I. (a)

filename

The name of the file to open. (a)

options

(optional) The open OPTIONS string. (a)

search

(optional) The search variable. (n)

error

(optional) Returned with the error value. (n)

D_NOALLOC

(optional) The no channel allocation flag; use the passed channel. (n)

Discussion

U_OPEN allocates a global or local channel and opens a file.

The open is performed using an OPTIONS qualifier on the OPEN statement. The contents of the I/O_mode argument are appended to the string “/IO=” and the result is placed into the OPTIONS string. I/O_mode must be one of the valid Synergy DBL open modes for the file (I for input, U:I for ISAM update, O:S for output sequential, and so forth).

If options is present and non‑blank, a slash and the contents of that variable are appended to the OPTIONS string discussed above.

If search is not present, the file is opened on a new channel in the specified mode.

U_OPEN will search for filename in the specified I/O_mode if search is present and the file is not being opened for output. If filename is found, a successful open is simulated, channel is set to the channel on which the file is opened, and the search variable is set to true. If filename is not found, the search variable is cleared and the open continues normally. Note that the I/O_mode and filename must match in content exactly and that filename is case sensitive and can have up to 256 characters. (I/O_mode is not case sensitive.)

If error is present, it is returned with a value of 0 if the open request is successful, or the number of the Synergy DBL error that occurs if the open fails. The channel argument is not loaded if an error occurs. If error is not present, any error that occurs will cause a fatal Toolkit error.

If D_NOALLOC is present, no channel will be allocated and the channel argument is assumed to contain the channel to use on entry. This is useful for converting existing applications that have “hard‑wired” channels. D_NOALLOC is ignored if search is present.

Rather than explicitly allocating channels yourself, it is best to enable U_OPEN to manage channel allocation for you. Enabling U_OPEN to maintain channel usage will help you keep your application modular.

The available channels are from 1 to 255. (The maximum number of channels Toolkit can log is 255.)

See also

Examples

In the first example, the variable chnl is returned with the allocated channel. The “cusmas” file is opened in ISAM update mode.

xcall u_open(chnl, "u:i", "cusmas")

The variable chnl is returned with the allocated channel in this example also. The file named “tagfil” is opened in output mode and the success of the operation is reported in sts.

xcall u_open(chnl, "o", "tagfil",,, sts)

The third example is the same as the first example, except that U_OPEN will see if the file is already opened in U:I mode before opening it. If it is already opened, the existing channel number is returned in chnl. If it isn’t already opened, U_OPEN tries to open it and returns 0 to sts if the open is successful or the number of the Synergy DBL error if the operation is not successful.

xcall u_open(chnl, "u:i", "cusmas",, srchflg, sts)