.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
.\" Interim 6.8
.\" 
.\" Revision 7.0  89/11/23  21:22:14  mrose
.\" Release 6.0
.\" 
.SH NAME
libacsap \- Application Control Services library
.SH SYNOPSIS
.B "#include <isode/acsap.h>"
.sp
\fIcc\fR\0...\0\fB\-lacsap\fR
.SH DESCRIPTION
The \fIlibacsap\fR library contains a set of routine which implement
association control services.
In essence,
they implement an Association Control Service Entity (ACSE) interface for
user applications.
.PP
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.
.SH ADDRESSES
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
recorded by \fItsapd\fR.
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
\fIexecvp\fR
(it's important to call \fBAcInit\fR prior to reading \fBargc\fR and
\fBargv\fR).
If the call to \fBAcInit\fR is not successful,
information returned by the call indicates the reason for failure.
.PP
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
\fBstatus\fR set to
.sp
.in +.5i
.nf
.ta \w'ACS_NOTSPECIFIED  'u
ACS_ACCEPT	association accepted
.re
.fi
.in -.5i
.sp
(which corresponds to the accepting A\-ASSOCIATE.RESPONSE action).
If the call is successful,
the interaction is henceforth symmetric.
If un\-successful,
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:
.sp
.in +.5i
.nf
.ta \w'ACS_NOTSPECIFIED  'u
ACS_PERMANENT	permanent
ACS_TRANSIENT	transient
.re
.fi
.in -.5i
.sp
(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.
If un\-successful,
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.
.SH "ASSOCIATION ABORT"
The routine \fBAcUAbortRequest\fR is used to unilaterally abort an
association.
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.
.PP
Finally,
the routine \fBAcErrString\fR takes a failure code from a \fBAcSAPabort\fR
structure and returns a null\-terminated diagnostic string.
.SH FILES
.nf
.ta \w'\*(EDisoservices  'u
\*(EDisoentities	ISODE entities database
\*(EDisobjects	ISODE objects database
\*(EDisoservices	ISODE services database
.re
.fi
.SH "SEE ALSO"
isoentities(5), isobjects (5), isoservices(5), tsapd(8c),
.br
\fIThe ISO Development Environment: User's Manual\fR,
.br
ISO 8649:
\fIInformation Processing Systems \-\- Open Systems Interconnection
\-\-
Service Definition for the Association Control Service Element\fR,
.SH DIAGNOSTICS
All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
In addition,
those routines which take a pointer to a \fBAcSAPindication\fR structure
fill\-in the structure as appropriate.
.SH AUTHOR
Marshall T. Rose
.SH BUGS
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.