Direct Access Transport Library Functions datiaopen(3DAT)
NAME
datiaopen - open an Interface Adapter (IA)
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datiaopen (
IN const DATNAMEPTR ianameptr,
IN DATCOUNT asyncevdminqlen,
INOUT DATEVDHANDLE *asyncevdhandle,
OUT DATIAHANDLE *iahandle
)
PARAMETERS
ianameptr 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 string
ROAWARE, 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 DATINVALIDPARAMETER (with
DATSUBTYPESTATUS of
DATINVALIDROCOKIE). This setting
also affects datlmrcreate(3DAT).
asyncevdminqlen Minimum length of the Asynchronous
Event Dispatcher queue.
asyncevdhandle Pointer to a handle for an Event
Dispatcher for asynchronous events
generated by the IA. This parameter
can be DATEVDASYNCEXISTS to indi-
cate that there is already EVD for
asynchronous events for this Interface
Adapter or DATHANDLENUL for a Pro-
vider to generate EVD for it.
SunOS 5.11 Last change: 28 Jan 2009 1
Direct Access Transport Library Functions datiaopen(3DAT)
iahandle 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 datiaopen() function opens an IA by creating an IA
instance. Multiple instances (opens) of an IA can exist.
The value of DATHANDLENUL for asyncevdhandle
(*asyncevdhandle == DATHANDLENUL) indicates that the
default Event Dispatcher is created with the requested
asyncevdminqlen. The asyncevdhandle returns the handle
of the created Asynchronous Event Dispatcher. The first Con-
sumer that opens an IA must use DATHANDLENUL because no
EVD can yet exist for the requested ianameptr.
The Asynchronous Event Dispatcher (asyncevdhandle) is
created with no CNO (DATHANDLENUL). Consumers can change
these values using datevdmodifycno(3DAT). The Consumer
can modify parameters of the Event Dispatcher using
datevdresize(3DAT) and datevdmodifycno().
The Provider is required to provide a queue size at least
equal to asyncevdminqlen, 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 asyncevdhandle is not DATHANDLENUL, the Provider
does not create an Event Dispatcher for an asynchronous
event and the Provider ignores the asyncevdminqlen value.
The asyncevdhandle value passed in by the Consumer must be
an asynchronous Event Dispatcher created for the same Pro-
vider (ianameptr). The Provider does not have to check for
the validity of the Consumer passed in asyncevdhandle. It
is the Consumer responsibility to guarantee that
asyncevdhandle is valid and for this Provider. How the
asyncevdhandle is passed between DAT Consumers is out of
scope of the DAT specification. If the Provider determines
that the Consumer-provided asyncevdhandle is invalid, the
operation fails and returns DATINVALIDHANDLE. The
asyncevdhandle remains unchanged, so the returned
asyncevdhandle 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 Asyn-
chronous Event Dispatcher specified by asyncevdhandle.
SunOS 5.11 Last change: 28 Jan 2009 2
Direct Access Transport Library Functions datiaopen(3DAT)
Consumer can specify the value of DATEVDASYNCEXISTS 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, DATEVDOUTOFSCOPE, 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 from
datregistrylistproviders(3DAT).
RETURN VALUES
DATSUCES The operation was successful.
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDPARAMETER Invalid parameter.
DATPROVIDERNOTFOUND The specified provider was not
registered in the registry.
DATINVALIDHANDLE Invalid DAT handle;
asyncevdhandle is invalid.
USAGE
The datiaopen() 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 the
SunOS 5.11 Last change: 28 Jan 2009 3
Direct Access Transport Library Functions datiaopen(3DAT)
Consumer closes its handle, all its DAT Objects are
released.
The datiaopen() function is the workhorse method that pro-
vides an IA instance. It can also initialize the Provider
library or do any other registry-specific functions.
The datiaopen() 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 datiaopen() 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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
Standard uDAPL, 1.1, 1.2 (except ROAWARE)
SEE ALSO
datevdmodifycno(3DAT), datevdresize(3DAT),
datiaclose(3DAT), datregistrylistproviders(3DAT),
libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 28 Jan 2009 4
|
