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_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 Pro-
vider registration. If the name is prefixed by the stringRO_AWARE_, 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 failwith DAT_INVALID_PARAMETER (with
DAT_SUBTYPE_STATUS of
DAT_INVALID_RO_COOKIE). This setting
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 parametercan be DAT_EVD_ASYNC_EXISTS to indi-
cate that there is already EVD for asynchronous events for this InterfaceAdapter or DAT_HANDLE_NULL for a Pro-
vider to generate EVD for it.SunOS 5.11 Last change: 28 Jan 2009 1
Direct Access Transport Library Functions dat_ia_open(3DAT)
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 requestedasync_evd_min_qlen. The async_evd_handle returns the handle
of the created Asynchronous Event Dispatcher. The first Con-
sumer 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 usingdat_evd_resize(3DAT) and dat_evd_modify_cno().
The Provider is required to provide a queue size at leastequal to async_evd_min_qlen, 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.If async_evd_handle is not DAT_HANDLE_NULL, the Provider
does not create an Event Dispatcher for an asynchronousevent 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 Pro-
vider (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 thatasync_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 determinesthat 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 IAare directed by the Provider to the Consumer passed in Asyn-
chronous Event Dispatcher specified by async_evd_handle.
SunOS 5.11 Last change: 28 Jan 2009 2
Direct Access Transport Library Functions dat_ia_open(3DAT)
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 Dispatcherfor this scenario, DAT_EVD_OUT_OF_SCOPE, to indicate that
there is a default Event Dispatcher assigned for this Inter-
face Adapter, but that it is not in a scope where this Con-
sumer 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 asynchronous event notifications for all Asynchronous Event Dispatchers. Also, transport and memory resources can be consumed per Event Dispatcher 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 fromdat_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 Pro-
vider, and, thus, all Objects. It is the root handle through which the Consumer obtains all other DAT handles. When theSunOS 5.11 Last change: 28 Jan 2009 3
Direct Access Transport Library Functions dat_ia_open(3DAT)
Consumer closes its handle, all its DAT Objects are released.The dat_ia_open() function is the workhorse method that pro-
vides an IA instance. It can also initialize the Providerlibrary 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 attri-
butes:__________________________________________________________________
| 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 Last change: 28 Jan 2009 4