1dat_ia_open(3DAT) Direct Access Transport Library Functions dat_ia_open(3DAT)
2
6 dat_ia_open - open an Interface Adapter (IA)
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_ia_open (
14 IN const DAT_NAME_PTR ia_name_ptr,
15 IN DAT_COUNT async_evd_min_qlen,
16 INOUT DAT_EVD_HANDLE *async_evd_handle,
17 OUT DAT_IA_HANDLE *ia_handle
18 )
19
22 ia_name_ptr Symbolic name for the IA to be opened. The name
23 should be defined by the Provider registration.
24 If the name is prefixed by the string RO_AWARE_,
26 then the prefix is removed prior to being passed
27 down and the existence of the prefix indicates
28 that the application has been coded to correctly
29 deal with relaxed ordering constraints. If the
30 prefix is not present and the platform on which
31 the application is running is utilizing relaxed
32 ordering, the open will fail with
33 DAT_INVALID_PARAMETER (with DAT_SUBTYPE_STATUS of
34 DAT_INVALID_RO_COOKIE). This setting also affects
35 dat_lmr_create(3DAT).
36 async_evd_min_qlen Minimum length of the Asynchronous Event Dis‐
39 patcher queue.
40 async_evd_handle Pointer to a handle for an Event Dispatcher for
43 asynchronous events generated by the IA. This
44 parameter can be DAT_EVD_ASYNC_EXISTS to indicate
45 that there is already EVD for asynchronous events
46 for this Interface Adapter or DAT_HANDLE_NULL for
47 a Provider to generate EVD for it.
48 ia_handle Handle for an open instance of a DAT IA. This
51 handle is used with other functions to specify a
52 particular instance of the IA.
53
56 The dat_ia_open() function opens an IA by creating an IA instance. Mul‐
57 tiple instances (opens) of an IA can exist.
58 The value of DAT_HANDLE_NULL for async_evd_handle (*async_evd_handle ==
61 DAT_HANDLE_NULL) indicates that the default Event Dispatcher is created
62 with the requested async_evd_min_qlen. The async_evd_handle returns the
63 handle of the created Asynchronous Event Dispatcher. The first Consumer
64 that opens an IA must use DAT_HANDLE_NULL because no EVD can yet exist
65 for the requested ia_name_ptr.
66 The Asynchronous Event Dispatcher (async_evd_handle) is created with no
69 CNO (DAT_HANDLE_NULL). Consumers can change these values using
70 dat_evd_modify_cno(3DAT). The Consumer can modify parameters of the
71 Event Dispatcher using dat_evd_resize(3DAT) and dat_evd_modify_cno().
72 The Provider is required to provide a queue size at least equal to
75 async_evd_min_qlen, but is free to provide a larger queue size or
76 dynamically enlarge the queue when needed. The Consumer can determine
77 the actual queue size by querying the created Event Dispatcher
78 instance.
79 If async_evd_handle is not DAT_HANDLE_NULL, the Provider does not cre‐
82 ate an Event Dispatcher for an asynchronous event and the Provider
83 ignores the async_evd_min_qlen value. The async_evd_handle value passed
84 in by the Consumer must be an asynchronous Event Dispatcher created for
85 the same Provider (ia_name_ptr). The Provider does not have to check
86 for the validity of the Consumer passed in async_evd_handle. It is the
87 Consumer responsibility to guarantee that async_evd_handle is valid and
88 for this Provider. How the async_evd_handle is passed between DAT Con‐
89 sumers is out of scope of the DAT specification. If the Provider deter‐
90 mines that the Consumer-provided async_evd_handle is invalid, the oper‐
91 ation fails and returns DAT_INVALID_HANDLE. The async_evd_handle
92 remains unchanged, so the returned async_evd_handle is the same the
93 Consumer passed in. All asynchronous notifications for the open
94 instance of the IA are directed by the Provider to the Consumer passed
95 in Asynchronous Event Dispatcher specified by async_evd_handle.
96 Consumer can specify the value of DAT_EVD_ASYNC_EXISTS to indicate that
99 there exists an event dispatcher somewhere else on the host, in user or
100 kernel space, for asynchronous event notifications. It is up to the
101 Consumer to ensure that this event dispatcher is unique and unambigu‐
102 ous. A special handle may be returned for the Asynchronous Event Dis‐
103 patcher for this scenario, DAT_EVD_OUT_OF_SCOPE, to indicate that there
104 is a default Event Dispatcher assigned for this Interface Adapter, but
105 that it is not in a scope where this Consumer may directly invoke it.
106 The Asynchronous Event Dispatcher is an Object of both the Provider and
109 IA. Each Asynchronous Event Dispatcher bound to an IA instance is noti‐
110 fied of all asynchronous events, such that binding multiple Asynchro‐
111 nous Event Dispatchers degrades performance by duplicating asynchronous
112 event notifications for all Asynchronous Event Dispatchers. Also,
113 transport and memory resources can be consumed per Event Dispatcher
114 bound to an IA
115 As with all Event Dispatchers, the Consumer is responsible for synchro‐
118 nizing access to the event queue.
119 Valid IA names are obtained from dat_registry_list_providers(3DAT).
122
124 DAT_SUCCESS The operation was successful.
125 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
128 itations.
129 DAT_INVALID_PARAMETER Invalid parameter.
132 DAT_PROVIDER_NOT_FOUND The specified provider was not registered
135 in the registry.
136 DAT_INVALID_HANDLE Invalid DAT handle; async_evd_handle is
139 invalid.
140
143 The dat_ia_open() function is the root method for the Provider, and,
144 thus, all Objects. It is the root handle through which the Consumer
145 obtains all other DAT handles. When the Consumer closes its handle, all
146 its DAT Objects are released.
147 The dat_ia_open() function is the workhorse method that provides an IA
150 instance. It can also initialize the Provider library or do any other
151 registry-specific functions.
152 The dat_ia_open() function creates a unique handle for the IA to the
155 Consumer. All further DAT Objects created for this Consumer reference
156 this handle as their owner.
157 The dat_ia_open() function can use a reference count for the Provider
160 Library to ensure that the Provider Library cannot be removed when it
161 is in use by a DAT Consumer.
162
164 See attributes(5) for descriptions of the following attributes:
165 ┌─────────────────────────────┬───────────────────────────────────┐
170 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
171 ├─────────────────────────────┼───────────────────────────────────┤
172 │Interface Stability │Committed │
173 ├─────────────────────────────┼───────────────────────────────────┤
174 │MT-Level │Safe │
175 ├─────────────────────────────┼───────────────────────────────────┤
176 │Standard │uDAPL, 1.1, 1.2 (except RO_AWARE_) │
177 └─────────────────────────────┴───────────────────────────────────┘
178
180 dat_evd_modify_cno(3DAT), dat_evd_resize(3DAT), dat_ia_close(3DAT),
181 dat_registry_list_providers(3DAT), libdat(3LIB), attributes(5)
182SunOS 5.11 28 Jan 2009 dat_ia_open(3DAT)