Direct Access Transport Library Functions datepcreate(3DAT)
NAME
datepcreate - create an instance of an Endpoint
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datepcreate (
IN DATIAHANDLE iahandle,
IN DATPZHANDLE pzhandle,
IN DATEVDHANDLE recvevdhandle,
IN DATEVDHANDLE requestevdhandle,
IN DATEVDHANDLE connectevdhandle,
IN DATEPATR *epattributes,
OUT DATEPHANDLE *ephandle
)
PARAMETERS
iahandle Handle for an open instance of the IA
to which the created Endpoint belongs.
pzhandle Handle for an instance of the Protec-
tion Zone.
recvevdhandle Handle for the Event Dispatcher where
events for completions of incoming
(receive) DTOs are reported.
DATHANDLENUL specifies that the
Consumer is not interested in events
for completions of receives.
requestevdhandle Handle for the Event Dispatcher where
events for completions of outgoing
(Send, RDMA Write, RDMA Read, and RMR
Bind) DTOs are reported.
DATHANDLENUL specifies that the
Consumer is not interested in events
for completions of requests.
connectevdhandle Handle for the Event Dispatcher where
Connection events are reported.
DATHANDLENUL specifies that the
Consumer is not interested in connec-
tion events for now.
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions datepcreate(3DAT)
epattributes Pointer to a structure that contains
Consumer-requested Endpoint attri-
butes. Can be NUL.
ephandle Handle for the created instance of an
Endpoint.
DESCRIPTION
The datepcreate() function creates an instance of an End-
point that is provided to the Consumer as ephandle. The
value of ephandle is not defined if the DATRETURN is not
DATSUCES.
The Endpoint is created in the Unconnected state.
Protection Zone pzhandle allows Consumers to control what
local memory the Endpoint can access for DTOs and what
memory remote RDMA operations can access over the connection
of a created Endpoint. Only memory referred to by LMRs and
RMRs that match the Endpoint Protection Zone can be accessed
by the Endpoint.
The recvevdhandle and requestevdhandle parameters are
Event Dispatcher instances where the Consumer collects com-
pletion notifications of DTOs. Completions of Receive DTOs
are reported in recvevdhandle Event Dispatcher, and com-
pletions of Send, RDMA Read, and RDMA Write DTOs are
reported in requestevdhandle Event Dispatcher. All com-
pletion notifications of RMR bindings are reported to a Con-
sumer in requestevdhandle Event Dispatcher.
All Connection events for the connected Endpoint are
reported to the Consumer through connectevdhandle Event
Dispatcher.
The epattributes parameter specifies the initial attributes
of the created Endpoint. If the Consumer specifies NUL, the
Provider fills it with its default Endpoint attributes. The
Consumer might not be able to do any posts to the Endpoint
or use the Endpoint in connection establishment until cer-
tain Endpoint attributes are set. Maximum Message Size and
Maximum Recv DTOs are examples of such attributes.
RETURN VALUES
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions datepcreate(3DAT)
DATSUCES The operation was successful.
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDHANDLE Invalid DAT handle.
DATINVALIDPARAMETER Invalid parameter. One of the
requested EP parameters or
attributes was invalid or a
combination of attributes or
parameters is invalid.
DATMODELNOTSUPORTED The requested Provider Model
was not supported.
USAGE
The Consumer creates an Endpoint prior to the establishment
of a connection. The created Endpoint is in
DATEPSTATEUNCONECTED. Consumers can do the following:
1. Request a connection on the Endpoint through
datepconnect(3DAT) or datepdupconnect(3DAT)
for the active side of the connection model.
2. Associate the Endpoint with the Pending Connection
Request that does not have an associated local End-
point for accepting the Pending Connection Request
for the passive/server side of the connection
model.
3. Create a Reserved Service Point with the Endpoint
for the passive/server side of the connection
model. Upon arrival of a Connection Request on the
Service Point, the Consumer accepts the Pending
Connection Request that has the Endpoint associated
with it
The Consumer cannot specify a requestevdhandle
(recvevdhandle) with Request Completion Flags (Recv Com-
pletion Flags) that do not match the other Endpoint Comple-
tion Flags for the DTO/RMR completion streams that use the
same EVD. If requestevdhandle (recvevdhandle) is used
for an EVD that is fed by any event stream other than DTO or
RMR completion event streams, only DATCOMPLETIONTHRESHOLD
is valid for Request/Recv Completion Flags for the Endpoint
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions datepcreate(3DAT)
completion streams that use that EVD. If requestevdhandle
(recvevdhandle) is used for request (recv) completions of
an Endpoint whose associated Request (Recv) Completion Flag
attribute is DATCOMPLETIONUNSIGNALEDFLAG, the Request
Completion Flags and Recv Completion Flags for all Endpoint
completion streams that use the EVD must specify the same.
Analogously, if recvevdhandle is used for recv completions
of an Endpoint whose associated Recv Completion Flags attri-
bute is DATCOMPLETIONSOLICITEDWAIT, the Recv Completion
Flags for all Endpoint Recv completion streams that use the
same EVD must specify the same Recv Completion Flags attri-
bute value and the EVD cannot be used for any other event
stream types.
If EP is created with NUL attributes, Provider can fill
them with its own default values. The Consumer should not
rely on the Provider-filled attribute defaults, especially
for portable applications. The Consumer cannot do any opera-
tions on the created Endpoint except for datepquery(3DAT),
datepgetstatus(3DAT), datepmodify(3DAT), and
datepfree(3DAT), depending on the values that the Provider
picks.
The Provider is encouraged to pick up reasonable defaults
because unreasonable values might restrict Consumers to the
datepquery(), datepgetstatus(), datepmodify(), and
datepfree() operations. The Consumer should check what
values the Provider picked up for the attributes. It is
especially important to make sure that the number of posted
operations is not too large to avoid EVD overflow. Depending
on the values picked up by the Provider, the Consumer might
not be able to do any RDMA operations; it might only be able
to send or receive messages of very small sizes, or it might
not be able to have more than one segment in a buffer.
Before doing any operations, except the ones listed above,
the Consumer can configure the Endpoint using
datepmodify() to the attributes they want.
One reason the Consumer might still want to create an End-
point with Null attributes is for the Passive side of the
connection establishment, where the Consumer sets up End-
point attributes based on the connection request of the
remote side.
Consumers might want to create Endpoints with NUL attri-
butes if Endpoint properties are negotiated as part the Con-
sumer connection establishment protocol.
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions datepcreate(3DAT)
Consumers that create Endpoints with Provider default attri-
butes should always verify that the Provider default attri-
butes meet their application's requirements with regard to
the number of request/receive DTOs that can be posted, max-
imum message sizes, maximum request/receive IOV sizes, and
maximum RDMA sizes.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.1, 1.2
MT-Level Safe
SEE ALSO
datepconnect(3DAT), datepdupconnect(3DAT),
datepfree(3DAT), datepgetstatus(3DAT),
datepmodify(3DAT), datepquery(3DAT), libdat(3LIB),
attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 5
|
