dat_ia_open(3DAT) Direct Access Transport Library Functions dat_ia_open(3DAT)NAMEdat_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 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
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 Dis‐
patcher 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. Mul‐
tiple 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
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 cre‐
ate 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 Con‐
sumers is out of scope of the DAT specification. If the Provider deter‐
mines that the Consumer-provided async_evd_handle is invalid, the oper‐
ation 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 unambigu‐
ous. A special handle may be returned for the Asynchronous Event Dis‐
patcher 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 noti‐
fied of all asynchronous events, such that binding multiple Asynchro‐
nous 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 synchro‐
nizing 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 lim‐
itations.
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 ALSOdat_evd_modify_cno(3DAT), dat_evd_resize(3DAT), dat_ia_close(3DAT),
dat_registry_list_providers(3DAT), libdat(3LIB), attributes(5)SunOS 5.10 28 Jan 2009 dat_ia_open(3DAT)