Synopsis:

       handle=adoConnection([name, prv_or_pub])

Arguments:

       name - An optional name that will uniquely identify the connect object (mainly for public connections)

       prv_or_pub - Set to 0 for Private connection, 1 for public connection (optional - default private)

Description:  This function creates a Connection object and returns a unique handle.     The connection object can be opened in private or public mode and can be given an optional name which can be used to retreive the handle using the adoConnGetHandle(name) function.

Important Note: Upon creating the underlying _Connection object the CusorLocation property is hard-coded to to adUseClient.     This is necessary in order for the libary to work in asyncronous (non-blocking) mode.         If you attempt to change the CusorLocation to adUseServer in the adoConnParmSet() function then this could cause some of the ado functions to work syncronously, thus blocking the Telecom Engine task scheduler and seriously effecting performance.     If you need to use server side cursors for any reason then it is suggested that you carefully trace all function calls to check that they don't block for significant periods of time (see Performance and blocking calls) and, if necesary, consider using a client-server model based on the CXSOCKETS.DLL library instead.

A private connection can only be accessed from the task that created it,  and any attempt to access a connection from another task will result in an error.    When a task ends (either through a chain to another task, a stop or restart statement is encountered, the end of program  is reached or the task is explicit killed),  then all private connections that the task created will be closed and released.      When a connection is closed then all recordsets associated with that connection will also be closed and released.

Public connections can be accessed from any task once it has been opened.      If the task that created it is ended for any reason then the connection will not be closed.           Often it is useful to make a single public connection to a datastore upon start-up, then all other tasks can create and open recordsets on that single connection.

The maximum number of simultaneous connections that can be open at any one time 1024 (ie there are 1024 handles available).

If a name is provided for a public connection then other tasks can obtain the connection handle by using adoConGetHandle(name).    All names must be unique, although a blank name can be given for multiple public connections, however then the handle cannot be retreived using adoConnGetHandle(name) and must be obtained another way (E.g. global variable).       Giving a name to a private connection is of little use since the handle will only be retrievable from the task that called the function (which should already have obtained the handle from the return value.

Both options can be omitted, in which case a private, nameless connection will be created.

Returns:  Returns the connection object handle or a negative error code.