'\" te .\" This manual page is derived from the DAT/uDAPL 1.2 specification. .\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH dat_ia_open 3DAT "28 Jan 2009" "SunOS 5.11" "Direct Access Transport Library Functions" .SH NAME dat_ia_open \- open an Interface Adapter (IA) .SH SYNOPSIS .LP .nf cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] #include <\fBdat/udat.h\fR> DAT_RETURN dat_ia_open ( IN const DAT_NAME_PTR \fIia_name_ptr\fR, IN DAT_COUNT \fIasync_evd_min_qlen\fR, INOUT DAT_EVD_HANDLE *\fIasync_evd_handle\fR, OUT DAT_IA_HANDLE *\fIia_handle\fR ) .fi .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIia_name_ptr\fR\fR .ad .RS 22n .rt Symbolic name for the IA to be opened. The name should be defined by the Provider registration. .sp If the name is prefixed by the string \fBRO_AWARE_\fR, then the prefix is removed prior to being passed down and the existence of the prefix indicates that the application has been coded to correctly deal with relaxed ordering constraints. If the prefix is not present and the platform on which the application is running is utilizing relaxed ordering, the open will fail with \fBDAT_INVALID_PARAMETER\fR (with \fBDAT_SUBTYPE_STATUS\fR of \fBDAT_INVALID_RO_COOKIE\fR). This setting also affects \fBdat_lmr_create\fR(3DAT). .RE .sp .ne 2 .mk .na \fB\fIasync_evd_min_qlen\fR\fR .ad .RS 22n .rt Minimum length of the Asynchronous Event Dispatcher queue. .RE .sp .ne 2 .mk .na \fB\fIasync_evd_handle\fR\fR .ad .RS 22n .rt Pointer to a handle for an Event Dispatcher for asynchronous events generated by the IA. This parameter can be \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that there is already EVD for asynchronous events for this Interface Adapter or \fBDAT_HANDLE_NULL\fR for a Provider to generate EVD for it. .RE .sp .ne 2 .mk .na \fB\fIia_handle\fR\fR .ad .RS 22n .rt Handle for an open instance of a DAT IA. This handle is used with other functions to specify a particular instance of the IA. .RE .SH DESCRIPTION .sp .LP The \fBdat_ia_open()\fR function opens an IA by creating an IA instance. Multiple instances (opens) of an IA can exist. .sp .LP The value of \fBDAT_HANDLE_NULL\fR for \fIasync_evd_handle\fR (*\fIasync_evd_handle\fR == \fBDAT_HANDLE_NULL\fR) indicates that the default Event Dispatcher is created with the requested \fIasync_evd_min_qlen\fR. The \fIasync_evd_handle\fR returns the handle of the created Asynchronous Event Dispatcher. The first Consumer that opens an IA must use \fBDAT_HANDLE_NULL\fR because no EVD can yet exist for the requested \fIia_name_ptr\fR. .sp .LP The Asynchronous Event Dispatcher (\fIasync_evd_handle\fR) is created with no CNO (\fBDAT_HANDLE_NULL\fR). Consumers can change these values using \fBdat_evd_modify_cno\fR(3DAT). The Consumer can modify parameters of the Event Dispatcher using \fBdat_evd_resize\fR(3DAT) and \fBdat_evd_modify_cno()\fR. .sp .LP The Provider is required to provide a queue size at least equal to \fIasync_evd_min_qlen\fR, but is free to provide a larger queue size or dynamically enlarge the queue when needed. The Consumer can determine the actual queue size by querying the created Event Dispatcher instance. .sp .LP If \fIasync_evd_handle\fR is not \fBDAT_HANDLE_NULL\fR, the Provider does not create an Event Dispatcher for an asynchronous event and the Provider ignores the \fIasync_evd_min_qlen\fR value. The \fIasync_evd_handle\fR value passed in by the Consumer must be an asynchronous Event Dispatcher created for the same Provider (\fIia_name_ptr\fR). The Provider does not have to check for the validity of the Consumer passed in \fIasync_evd_handle\fR. It is the Consumer responsibility to guarantee that \fIasync_evd_handle\fR is valid and for this Provider. How the \fIasync_evd_handle\fR is passed between DAT Consumers is out of scope of the DAT specification. If the Provider determines that the Consumer-provided \fIasync_evd_handle\fR is invalid, the operation fails and returns \fBDAT_INVALID_HANDLE\fR. The \fIasync_evd_handle\fR remains unchanged, so the returned \fIasync_evd_handle\fR is the same the Consumer passed in. All asynchronous notifications for the open instance of the IA are directed by the Provider to the Consumer passed in Asynchronous Event Dispatcher specified by \fIasync_evd_handle\fR. .sp .LP Consumer can specify the value of \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that there exists an event dispatcher somewhere else on the host, in user or kernel space, for asynchronous event notifications. It is up to the Consumer to ensure that this event dispatcher is unique and unambiguous. A special handle may be returned for the Asynchronous Event Dispatcher for this scenario, \fBDAT_EVD_OUT_OF_SCOPE\fR, to indicate that there is a default Event Dispatcher assigned for this Interface Adapter, but that it is not in a scope where this Consumer may directly invoke it. .sp .LP The Asynchronous Event Dispatcher is an Object of both the Provider and IA. Each Asynchronous Event Dispatcher bound to an IA instance is notified of all asynchronous events, such that binding multiple Asynchronous Event Dispatchers degrades performance by duplicating asynchronous event notifications for all Asynchronous Event Dispatchers. Also, transport and memory resources can be consumed per Event Dispatcher bound to an IA .sp .LP As with all Event Dispatchers, the Consumer is responsible for synchronizing access to the event queue. .sp .LP Valid IA names are obtained from \fBdat_registry_list_providers\fR(3DAT). .SH RETURN VALUES .sp .ne 2 .mk .na \fB\fBDAT_SUCCESS\fR\fR .ad .RS 30n .rt The operation was successful. .RE .sp .ne 2 .mk .na \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR .ad .RS 30n .rt The operation failed due to resource limitations. .RE .sp .ne 2 .mk .na \fB\fBDAT_INVALID_PARAMETER\fR\fR .ad .RS 30n .rt Invalid parameter. .RE .sp .ne 2 .mk .na \fB\fBDAT_PROVIDER_NOT_FOUND\fR\fR .ad .RS 30n .rt The specified provider was not registered in the registry. .RE .sp .ne 2 .mk .na \fB\fBDAT_INVALID_HANDLE\fR\fR .ad .RS 30n .rt Invalid DAT handle; async_evd_handle is invalid. .RE .SH USAGE .sp .LP The \fBdat_ia_open()\fR function is the root method for the Provider, and, thus, all Objects. It is the root handle through which the Consumer obtains all other DAT handles. When the Consumer closes its handle, all its DAT Objects are released. .sp .LP The \fBdat_ia_open()\fR function is the workhorse method that provides an IA instance. It can also initialize the Provider library or do any other registry-specific functions. .sp .LP The \fBdat_ia_open()\fR function creates a unique handle for the IA to the Consumer. All further DAT Objects created for this Consumer reference this handle as their owner. .sp .LP The \fBdat_ia_open()\fR function can use a reference count for the Provider Library to ensure that the Provider Library cannot be removed when it is in use by a DAT Consumer. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe _ StandarduDAPL, 1.1, 1.2 (except \fBRO_AWARE_\fR) .TE .SH SEE ALSO .sp .LP \fBdat_evd_modify_cno\fR(3DAT), \fBdat_evd_resize\fR(3DAT), \fBdat_ia_close\fR(3DAT), \fBdat_registry_list_providers\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)