U_OPEN

Open a channel/file

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. (a)

filename

The name of the file to open. (a)

options

(optional) The OPEN statement OPTIONS string. (a)

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

If I/O_mode is passed, it must have the form mode[:sub], where mode is a mode for the OPEN statement, and sub (optional) is a submode for OPEN. (When U_OPEN is called, Toolkit calls OPEN behind the scenes, passing mode[:sub] if it’s in the U_OPEN call.) For example, “U:I” specifies ISAM update mode. The default is i:i. For more information on mode and sub, see Modes and submodes.

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

U_CLOSE routine for information about how to close or purge channels
U_FINISH routine for information about how to close and purge channels at application shut down
U_START routine for information about how to open channels to the window library, text library, and the terminal and to determine the number of channels available to your application
U_GETCHN routine for information about how to convert applications

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)