dat_ia_open(3DAT)				     Direct Access Transport Library Functions					 dat_ia_open(3DAT)

NAME

       dat_ia_open - open an Interface Adapter (IA)

SYNOPSIS

       cc [ flag... ] file... -ldat [ library... ]
       #include <dat/udat.h>

       DAT_RETURN
	   dat_ia_open (
	   IN const DAT_NAME_PTR       ia_name_ptr,
	   IN	    DAT_COUNT	       async_evd_min_qlen,
	   INOUT    DAT_EVD_HANDLE     *async_evd_handle,
	   OUT	    DAT_IA_HANDLE      *ia_handle
	   )

PARAMETERS

       ia_name_ptr	     Symbolic name for the IA to be opened. The name should be defined by the Provider registration.

			     If  the name is prefixed by the string RO_AWARE_, then the prefix is removed prior to being passed down and the exis-
			     tence of the prefix indicates that the application has been coded	to  correctly  deal  with  relaxed  ordering  con-
			     straints.	If  the  prefix  is  not present and the platform on which the application is running is utilizing relaxed
			     ordering, the open will fail with DAT_INVALID_PARAMETER (with DAT_SUBTYPE_STATUS of DAT_INVALID_RO_COOKIE). This set-
			     ting also affects dat_lmr_create(3DAT).

       async_evd_min_qlen    Minimum length of the Asynchronous Event Dispatcher queue.

       async_evd_handle      Pointer  to  a  handle  for  an  Event  Dispatcher for asynchronous events generated by the IA. This parameter can be
			     DAT_EVD_ASYNC_EXISTS to indicate that there is already EVD for asynchronous events  for  this  Interface  Adapter	or
			     DAT_HANDLE_NULL for a Provider to generate EVD for it.

       ia_handle	     Handle for an open instance of a DAT IA. This handle is used with other functions to specify a particular instance of
			     the IA.

DESCRIPTION

       The dat_ia_open() function opens an IA by creating an IA instance. Multiple instances (opens) of an IA can exist.

       The value of DAT_HANDLE_NULL for async_evd_handle (*async_evd_handle == DAT_HANDLE_NULL) indicates that the  default  Event  Dispatcher	is
       created	with  the  requested async_evd_min_qlen. The async_evd_handle returns the handle of the created Asynchronous Event Dispatcher. The
       first Consumer that opens an IA must use DAT_HANDLE_NULL because no EVD can yet exist for the requested ia_name_ptr.

       The Asynchronous Event Dispatcher (async_evd_handle) is created with no CNO (DAT_HANDLE_NULL). Consumers  can  change  these  values  using
       dat_evd_modify_cno(3DAT). The Consumer can modify parameters of the Event Dispatcher using dat_evd_resize(3DAT) and dat_evd_modify_cno().

       The Provider is required to provide a queue size at least equal to async_evd_min_qlen, but is free to provide a larger queue size or dynam-
       ically enlarge the queue when needed. The Consumer can determine the actual queue size by querying the created Event Dispatcher instance.

       If async_evd_handle is not DAT_HANDLE_NULL, the Provider does not create an Event Dispatcher for an asynchronous  event	and  the  Provider
       ignores the async_evd_min_qlen value. The async_evd_handle value passed in by the Consumer must be an asynchronous Event Dispatcher created
       for the same Provider (ia_name_ptr). The Provider does not have to check for the validity of the Consumer passed in async_evd_handle. It is
       the  Consumer  responsibility to guarantee that async_evd_handle is valid and for this Provider. How the async_evd_handle is passed between
       DAT Consumers is out of scope of the DAT specification. If the Provider determines that the Consumer-provided async_evd_handle is  invalid,
       the  operation  fails  and returns DAT_INVALID_HANDLE. The async_evd_handle remains unchanged, so the returned async_evd_handle 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 async_evd_handle.

       Consumer  can  specify  the  value of DAT_EVD_ASYNC_EXISTS 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, DAT_EVD_OUT_OF_SCOPE, 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.

       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  asyn-
       chronous  event	notifications  for all Asynchronous Event Dispatchers. Also, transport and memory resources can be consumed per Event Dis-
       patcher bound to an IA

       As with all Event Dispatchers, the Consumer is responsible for synchronizing access to the event queue.

       Valid IA names are obtained from dat_registry_list_providers(3DAT).

RETURN VALUES

       DAT_SUCCESS		     The operation was successful.

       DAT_INSUFFICIENT_RESOURCES    The operation failed due to resource limitations.

       DAT_INVALID_PARAMETER	     Invalid parameter.

       DAT_PROVIDER_NOT_FOUND	     The specified provider was not registered in the registry.

       DAT_INVALID_HANDLE	     Invalid DAT handle; async_evd_handle is invalid.

USAGE

       The dat_ia_open() 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.

       The  dat_ia_open()  function  is  the  workhorse method that provides an IA instance. It can also initialize the Provider library or do any
       other registry-specific functions.

       The dat_ia_open() 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.

       The dat_ia_open() 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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------------+
       |      ATTRIBUTE TYPE	     |	       ATTRIBUTE VALUE		 |
       +-----------------------------+-----------------------------------+
       |Interface Stability	     |Committed 			 |
       +-----------------------------+-----------------------------------+
       |MT-Level		     |Safe				 |
       +-----------------------------+-----------------------------------+
       |Standard		     |uDAPL, 1.1, 1.2 (except RO_AWARE_) |
       +-----------------------------+-----------------------------------+

SEE ALSO

       dat_evd_modify_cno(3DAT), dat_evd_resize(3DAT), dat_ia_close(3DAT), dat_registry_list_providers(3DAT), libdat(3LIB), attributes(5)

SunOS 5.11							    28 Jan 2009 						 dat_ia_open(3DAT)