.TH LIBACSAP 3N "23 Sep 1986"
.\" $Header: /f/osi/acsap/RCS/libacsap.3n,v 7.1 91/02/22 09:14:44 mrose Interim $
.\" $Log: libacsap.3n,v $
.\" Revision 7.1 91/02/22 09:14:44 mrose
.\" Revision 7.0 89/11/23 21:22:14 mrose
libacsap \- Application Control Services library
.B "#include <isode/acsap.h>"
\fIcc\fR\0...\0\fB\-lacsap\fR
The \fIlibacsap\fR library contains a set of routine which implement
association control services.
they implement an Association Control Service Entity (ACSE) interface for
Although the ISO model is symmetric,
this implmentation is based on a client/server paradigm and hence asymmetric.
The information herein is skeltal:
consult the \fIUser's Manual\fR for actual examples of how ISO servers and
clients are coded and interact with the \fIlibacsap\fR library.
Two objects are used to address an application using an ACSE:
application entity information and a presentation address.
The former object denotes the particular application desired;
the latter denotes where this application is located.
.SH "SERVER INITIALIZATION"
A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
with the argument vector listed in the ISODE services database.
The server's very first action is to re\-capture the ACSE state as
This is accomplished by calling \fBAcInit\fR.
Information returned by this call is equivalent to the parameters passed by a
A\-ASSOCIATE.INDICATION event.
If the call is successful,
the program can then examine the argument vector that was passed via
(it's important to call \fBAcInit\fR prior to reading \fBargc\fR and
If the call to \fBAcInit\fR is not successful,
information returned by the call indicates the reason for failure.
After examining the information provided by \fBAcInit\fR
(and possibly the argument vector),
the server should either accept or reject the connection.
If accepting, the \fBAcAssocResponse\fR routine is called with the parameter
.ta \w'ACS_NOTSPECIFIED 'u
ACS_ACCEPT association accepted
(which corresponds to the accepting A\-ASSOCIATE.RESPONSE action).
If the call is successful,
the interaction is henceforth symmetric.
information returned by the call indicates the reason for failure.
If rejecting, the \fBAcAssocResponse\fR routine is also called,
but with the parameter \fBstatus\fR set to one of:
.ta \w'ACS_NOTSPECIFIED 'u
(which corresponds to the refusing A\-ASSOCIATE.RESPONSE action),
and the program may exit.
.SH "CLIENT INITIALIZATION"
A program requesting an ISO service calls \fBAcAssocRequest\fR
(which corresponds to the A\-ASSOCIATE.REQUEST action).
If successful (depending on the responder's choice of \fBresult\fR),
the interaction is henceforth symmetric.
information returned by the call indicates the reason for failure.
.SH ASSOCIATION\-DESCRIPTORS
Once a connection has been established via a successful return from
\fBAcAssocResponse\fR (for servers) or \fBAcAssocRequest\fR (for clients),
a connection is referenced by a small integer
(returned in a structure passed to these calls) called a
\fIassociation\-descriptor\fR.
This association\-descriptor appears as an argument to the other application
service elements being used by the application
(e.g., the reliable transfer service entity (RTSE), or the
remote operates service entity (ROSE)).
.SH "ASSOCIATION RELEASE"
The routine \fBAcRelRequest\fR is used to release an association.
This triggers a P\-RELEASE.INDICATION event for the other peer.
The peer should use the \fBAcFINISHser\fR routine to map this into an
A\-RELEASE.INDICATION event.
It should then use the routine \fBAcRelResponse\fR to either accept or reject
the request to release the association.
The routine \fBAcUAbortRequest\fR is used to unilaterally abort an
This triggers a P\-U\-ABORT.INDICATION event for the other peer.
The peer should use the \fBAcABORTser\fR routine to map this into an
A\-ABORT.INDICATION event.
the routine \fBAcErrString\fR takes a failure code from a \fBAcSAPabort\fR
structure and returns a null\-terminated diagnostic string.
.ta \w'\*(EDisoservices 'u
\*(EDisoentities ISODE entities database
\*(EDisobjects ISODE objects database
\*(EDisoservices ISODE services database
isoentities(5), isobjects (5), isoservices(5), tsapd(8c),
\fIThe ISO Development Environment: User's Manual\fR,
\fIInformation Processing Systems \-\- Open Systems Interconnection
Service Definition for the Association Control Service Element\fR,
All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
those routines which take a pointer to a \fBAcSAPindication\fR structure
fill\-in the structure as appropriate.
Do not confuse association\-descriptors with file\-descriptors.
Unlike file\-descriptors which are implemented by the kernel,
association\-descriptors do not work across \fIfork\fRs and \fIexec\fRs.