Return to acsap.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/acsap.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {Association Control}\label{libacsap}
        !             4: The \man libacsap(3n) library implements the Association Control Service
        !             5: (ACS).
        !             6: Logically,
        !             7: one views an application to consist of several {\em application service
        !             8: elements\/} (ASE's).
        !             9: Although these ASEs cooperate,
        !            10: each performs a different function for the application.
        !            11: The Association Control Service Element (ACSE) is concerned with the task of
        !            12: ``starting'' and ``stopping'' the network for the application.
        !            13: That is,
        !            14: an application uses the ACSE to establish a connection,
        !            15: termed an {\em association}, between two users.
        !            16: The association {\em binds\/} the two users,
        !            17: which are referred to as
        !            18: the {\em initiator\/} and the {\em responder}.
        !            19: This association, once established is used by other ASEs
        !            20: (e.g., the remote operations service element).
        !            21: Later,
        !            22: the ACSE is called upon to release the association,
        !            23: either gracefully (perhaps with some negotiation),
        !            24: or abruptly (with possible loss of information).
        !            25: 
        !            26: Like most models of OSI services,
        !            27: the underlying assumption is one of an asynchronous environment:
        !            28: the service provider may generate events for the service user without the
        !            29: latter entity triggering the actions which led to the event.
        !            30: For example,
        !            31: in a synchronous environment,
        !            32: an indication that data has arrived usually occurs only when the service user
        !            33: asks the service provider to read data;
        !            34: in an asynchronous environment,
        !            35: the service provider may interrupt the service user at any time to announce
        !            36: the arrival of data.
        !            37: 
        !            38: The \verb"acsap" module in this release presents a synchronous interface.
        !            39: However once the association is established,
        !            40: an asynchronous interface may be selected.
        !            41: The \verb"acsap" module itself is naive as to the interface being used:
        !            42: the particular application service element which is responsible for
        !            43: transferring data will manage the association once the ACSE has established it.
        !            44: 
        !            45: All of the routines in the \man libacsap(3n) library are integer-valued.
        !            46: They return the manifest constant \verb"OK" on success,
        !            47: or \verb"NOTOK" otherwise.
        !            48: In some circumstances,
        !            49: failures are fatal and cause (or are caused by) the association being released.
        !            50: Section~\ref{acs:errors} describes how such failures may be distinguished.
        !            51: 
        !            52: \section      {An Important Note}\label{acs:note}
        !            53: In the current release
        !            54: there are several ways to establish an association.
        !            55: This is due to recent changes in the OSI application layer,
        !            56: and a desire to remain compatible with previous work.
        !            57: Users are strongly encouraged to use the new facilities described herein,
        !            58: as the older facilities will eventually be removed.
        !            59: 
        !            60: Here are the new facilities available:
        !            61: \[\begin{tabular}{|l|l|l|}
        !            62: \hline
        !            63:     \multicolumn{1}{|c|}{\bf Desired Service}&
        !            64:     \multicolumn{1}{c|}{\bf Association Primitives}&
        !            65:     \multicolumn{1}{c|}{\bf Section(s)}\\
        !            66: \hline
        !            67:     Remote Operations&         {\sf A-ASSOCIATE}&  \ref{acs:associations}\\
        !            68:     \ (complete discipline)&
        !            69:                                {\sf A-RELEASE}&    \ref{ros:underlying}\\
        !            70:     \ \cite{ISO.ROS.Service,CCITT.ROS.Service}&
        !            71:                                {\sf A-ABORT}&      \\[0.1in]
        !            72: \hline
        !            73:     Remote Operations&         {\sf RT-OPEN}&      \ref{rts:associations}\\
        !            74:     \ (complete discipline&    {\sf RT-CLOSE}&     \ref{ros:underlying}\\
        !            75:     \ \ with reliable transfer)&&                  \\
        !            76:     \ \cite{ISO.ROS.Service,CCITT.ROS.Service}&
        !            77:                                &                   \\[0.1in]
        !            78: \hline
        !            79:     Reliable Transfer&         {\sf RT-OPEN}&      \ref{rts:associations}\\
        !            80:     \ \cite{ISO.RTS.Service,CCITT.RTS.Service}&
        !            81:                                {\sf RT-CLOSE}&     \\
        !            82: \hline
        !            83: \end{tabular}\]
        !            84: \clearpage     %%% yikes!
        !            85: 
        !            86: Here are the old facilities available:
        !            87: \[\begin{tabular}{|l|l|l|}
        !            88: \hline
        !            89:     \multicolumn{1}{|c|}{\bf Desired Service}&
        !            90:     \multicolumn{1}{c|}{\bf Association Primitives}&
        !            91:     \multicolumn{1}{c|}{\bf Section}\\
        !            92: \hline
        !            93:     Remote Operations&         {\sf RO-BEGIN}&     \ref{ros:old-style}\\
        !            94:     \ (basic discipline)&      {\sf RO-END}&       \\
        !            95:     \ \cite{ECMA.ROS}&         &                   \\[0.1in]
        !            96: \hline
        !            97:     Remote Operations&         {\sf X.410 OPEN}&   \ref{rts:old-style}\\
        !            98:     \ (advanced discipline&    {\sf X.410 CLOSE}&  \ref{ros:underlying}\\
        !            99:     \ \ with reliable transfer)&&                  \\
        !           100:     \ \cite{MHS.RTS}&          &                   \\[0.1in]
        !           101: \hline
        !           102:     Reliable Transfer&         {\sf X.410 OPEN}&   \ref{rts:old-style}\\
        !           103:     \ \cite{MHS.RTS}&          {\sf X.410 CLOSE}&  \\
        !           104: \hline
        !           105: \end{tabular}\]
        !           106: 
        !           107: In short, depending on whether a Reliable Transfer Service Element (RTSE) is
        !           108: desired,
        !           109: for the purposes of association control,
        !           110: all new applications should use either the library discussed below,
        !           111: or the reliable transfer routines discussed in
        !           112: Section~\ref{rts:associations} on page~\pageref{rts:associations}.
        !           113: 
        !           114: \section      {Associations}\label{acs:associations}
        !           115: There are three aspects of association management:
        !           116: {\em association establishment},
        !           117: {\em association release},
        !           118: and,
        !           119: {\em association abort}.
        !           120: Each of these are now described in turn.
        !           121: 
        !           122: \subsection    {Association Establishment}
        !           123: The \man libacsap(3n) library distinguishes between the user which started an
        !           124: association,
        !           125: the {\em initiator},
        !           126: and the user which was subsequently bound to the association,
        !           127: the {\em responder}.
        !           128: We sometimes term these two entities the {\em client\/} and the {\em server},
        !           129: respectively.
        !           130: 
        !           131: \subsubsection {Addresses}\label{acs:addresses}\label{acs:aei}
        !           132: Addresses for the association control service entity consist of two parts:
        !           133: a presentation address (as discussed in Section~\ref{psap:addresses} on
        !           134: page~\pageref{psap:addresses} of \voltwo/),
        !           135: and application-entity information.
        !           136: Internally,
        !           137: the \verb"AEInfo" is used to represent this notion:
        !           138: \begin{quote}\index{AEInfo}\small\begin{verbatim}
        !           139: typedef struct AEInfo {
        !           140:     PE      aei_ap_title;
        !           141:     PE      aei_ae_qualifier;
        !           142: 
        !           143:     int     aei_ap_id;
        !           144:     int     aei_ae_id;
        !           145: 
        !           146:     int     aei_flags;
        !           147: #define AEI_NULL        0x00
        !           148: #define AEI_AP_ID       0x01
        !           149: #define AEI_AE_ID       0x02
        !           150: }       AEInfo, *AEI;
        !           151: #define NULLAEI         ((AEI) 0)
        !           152: \end{verbatim}\end{quote}
        !           153: This structure contains several elements:
        !           154: \begin{describe}
        !           155: \item[\verb"aei\_ap\_title":] the application-process title;
        !           156: 
        !           157: \item[\verb"aei\_ae\_qualifier":] the application-entity qualifier;
        !           158: 
        !           159: \item[\verb"aei\_ap\_id":] the application-process invocation identifier;
        !           160: 
        !           161: \item[\verb"aei\_ae\_id":] the application-entity invocation identifier;
        !           162: and,
        !           163: 
        !           164: \item[\verb"aei\_flags":] flags, indicating which, if any,
        !           165: of the invocation-identifiers are present.
        !           166: \end{describe}
        !           167: 
        !           168: The routing \verb"sprintaei" can be used to return a null-terminated
        !           169: string describing the application-entity.
        !           170: \begin{quote}\index{sprintaei}\small\begin{verbatim}
        !           171: char   *sprintaei (aei)
        !           172: AEI     aei;
        !           173: \end{verbatim}\end{quote}
        !           174: 
        !           175: Finally,
        !           176: the routine \verb"oid2aei" converts object identifiers
        !           177: (discussed in Section~\ref{psap:oid} on page~\pageref{psap:oid})
        !           178: and converts them to application-entity information.
        !           179: This is used by the stub-directory service:
        !           180: \begin{quote}\index{oid2aei}\small\begin{verbatim}
        !           181: AEI     oid2aei (oid)
        !           182: OID     oid;
        !           183: \end{verbatim}\end{quote}
        !           184: 
        !           185: In Figure~\ref{getFTAMentity},
        !           186: an example of how one constructs the address for the File Transfer, Access
        !           187: and Management (FTAM) service on host \verb"RemoteHost" is presented.
        !           188: The key routine is \verb"_str2aei":
        !           189: \begin{quote}\index{\_str2aei}\small\begin{verbatim}
        !           190: AEI     _str2aei (designator, qualifier, context, interactive)
        !           191: char   *designator,
        !           192:        *qualifier,
        !           193:        *context;
        !           194: int     interactive;
        !           195: \end{verbatim}\end{quote}
        !           196: The parameters to this procedure are:
        !           197: \begin{describe}
        !           198: \item[\verb"designator":] input from the user
        !           199: (e.g., ``\verb"hubris, cs, ucl, gb"'' or ``\verb"hubris"'');
        !           200: 
        !           201: \item[\verb"qualifier":] the service qualifier (e.g., \verb"filestore");
        !           202: 
        !           203: \item[\verb"context":] the \verb"supportedApplicationContext" for the desired
        !           204: service (e.g., \verb"iso ftam");
        !           205: and;
        !           206: 
        !           207: \item[\verb"interactive":] non-zero if the user's terminal can be queried for
        !           208: additional information.
        !           209: \end{describe}
        !           210: The routine \verb"_str2aei" will first attempt to resolution using the
        !           211: ``user-friendly nameservice'' with the \verb"designator", \verb"context", and
        !           212: \verb"interactive" parameters.
        !           213: If this fails,
        !           214: the ``stub directory service'' will be used,
        !           215: with the \verb"designator" and \verb"qualifier" parameters.
        !           216: 
        !           217: For backwards-compatiblity,
        !           218: a macro, \verb"str2aei" is provided which is equivalent to:
        !           219: \begin{quote}\index{str2aei}\small\begin{verbatim}
        !           220: _str2aei (designator, qualifier, NULLCP, 0)
        !           221: \end{verbatim}\end{quote}
        !           222: 
        !           223: The routine \verb"aei2addr" takes application-entity information,
        !           224: and returns the appropriate presentation address.
        !           225: \begin{quote}\index{aei2addr}\small\begin{verbatim}
        !           226: struct PSAPaddr *aei2addr (aei)
        !           227: AEI     aei;
        !           228: \end{verbatim}\end{quote}
        !           229: \tagrind[tp]{grind2a-1}%
        !           230:        {Constructing the address for the FTAM entity}{getFTAMentity}
        !           231: 
        !           232: \subsubsection {Address Encodings}\label{addr:encodings}
        !           233: It may be useful to encode a presentation address for viewing.
        !           234: Although a consensus for a standard way of doing this has not yet been
        !           235: reached,
        !           236: the routines \verb"paddr2str" and \verb"str2paddr" may be used in the interim.
        !           237: These implement the encodings defined in \cite{String.Addresses}.
        !           238: The BNF syntax for this encoding is shown in Figure~\ref{str:format} on
        !           239: page~\pageref{str:format}.
        !           240: \begin{quote}\index{paddr2str}\small\begin{verbatim}
        !           241: char   *paddr2str (pa, na)
        !           242: struct PSAPaddr *pa;
        !           243: struct NSAPaddr *na;
        !           244: \end{verbatim}\end{quote}
        !           245: The parameters to this procedure are:
        !           246: \begin{describe}
        !           247: \item[\verb"pa":] the presentation address;
        !           248: and,
        !           249: 
        !           250: \item[\verb"na":] a network address to use instead of the network addresses
        !           251: in the \verb"pa" parameter
        !           252: (use the manifest constant \verb"NULLNA" otherwise).
        !           253: \end{describe}
        !           254: If \verb"paddr2str" fails,
        !           255: it returns the manifest constant \verb"NULLCP".
        !           256: 
        !           257: The routine \verb"str2paddr" takes an ascii string encoding and
        !           258: returns a
        !           259: presentation address.
        !           260: \begin{quote}\index{str2paddr}\small\begin{verbatim}
        !           261: struct PSAPaddr *str2paddr (str)
        !           262: char   *str;
        !           263: \end{verbatim}\end{quote}
        !           264: The parameter to this procedure is:
        !           265: \begin{describe}
        !           266: \item[\verb"str":] the ascii string.
        !           267: \end{describe}
        !           268: If \verb"str2paddr" fails,
        !           269: it returns the manifest constant \verb"NULLPA".
        !           270: \tagrind[tp]{grind2a-2f}{BNF Syntax for paddr2str/str2paddr}{str:format}
        !           271: \tagrind[tp]{grind2a-2g}{BNF Syntax for paddr2str/str2paddr (continued)}\empty
        !           272: 
        !           273: \verb"paddr2str" is really a macro which calls the routine \verb"_paddr2str":
        !           274: \begin{quote}\index{\_paddr2str}\small\begin{verbatim}
        !           275: char  *_paddr2str (pa, na, compact)
        !           276: struct PSAPaddr *pa;
        !           277: struct NSAPaddr *na;
        !           278: int    compact;
        !           279: \end{verbatim}\end{quote}
        !           280: The parameters to this procedure are:
        !           281: \begin{describe}
        !           282: \item[\verb"pa":] the presentation address;
        !           283: 
        !           284: \item[\verb"na":] a network address to use instead of the network addresses
        !           285: in the \verb"pa" parameter
        !           286: (use the manifest constant \verb"NULLNA" otherwise);
        !           287: and,
        !           288: 
        !           289: \item[\verb"compact":] indicates the style of encoding.
        !           290: \end{describe}
        !           291: If \verb"compact" is greater than zero,
        !           292: then the encoding reflects a normalized network address.
        !           293: This is useful for passing to arbitrary processes in the network.
        !           294: If \verb"compact" is less than zero,
        !           295: then the encoding reflects the BNF in Figure~\ref{str:format},
        !           296: without any macro substitutions.
        !           297: If \verb"compact" is equal to zero (which is what \verb"paddr2str" uses),
        !           298: then the encoding reflects the above BNF with macro substitutions.
        !           299: 
        !           300: The routine \verb"pa2str" takes a presentation address and returns a
        !           301: null-ter\-mi\-na\-ted ascii string suitable for viewing:
        !           302: \begin{quote}\index{pa2str}\begin{verbatim}
        !           303: char   *pa2str (pa)
        !           304: struct PSAPaddr *pa;
        !           305: \end{verbatim}\end{quote}
        !           306: The parameter to this procedure is:
        !           307: \begin{describe}
        !           308: \item[\verb"pa"]: the presentation address to be printed.
        !           309: \end{describe}
        !           310: 
        !           311: \subsubsection {Server Initialization}
        !           312: The \man tsapd(8c) daemon,
        !           313: upon accepting a connection from an initiating host,
        !           314: consults the ISO services database to determine which program
        !           315: on the local system implements the desired application context.
        !           316: 
        !           317: Once the program has been ascertained,
        !           318: the daemon runs the program with any arguments listed in the database.
        !           319: In addition,
        !           320: it appends some {\em magic arguments\/} to the argument vector.
        !           321: Hence,
        !           322: the very first action performed by the responder is to re-capture the ACSE
        !           323: state contained in the magic arguments.
        !           324: This is done by calling the routine \verb"AcInit",
        !           325: which on a successful return,
        !           326: is equivalent to a {\sf A-ASSOCIATE.INDICATION\/} event from the association
        !           327: control service provider.
        !           328: \begin{quote}\index{AcInit}\small\begin{verbatim}
        !           329: int     AcInit (vecp, vec, acs, aci)
        !           330: int     vecp;
        !           331: char  **vec;
        !           332: struct AcSAPstart *acs;
        !           333: struct AcSAPindication *aci;
        !           334: \end{verbatim}\end{quote}
        !           335: The parameters to this procedure are:
        !           336: \begin{describe}
        !           337: \item[\verb"vecp":] the length of the argument vector;
        !           338: 
        !           339: \item[\verb"vec":] the argument vector;
        !           340: 
        !           341: \item[\verb"acs":] a pointer to an \verb"AcSAPstart" structure,
        !           342: which is updated only if the call succeeds;
        !           343: and,
        !           344: 
        !           345: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !           346: which is updated only if the call fails.
        !           347: \end{describe}
        !           348: If \verb"AcInit" is successful,
        !           349: it returns information in the \verb"acs" parameter,
        !           350: which is a pointer to an \verb"AcSAPstart" structure.
        !           351: \begin{quote}\index{AcSAPstart}\small\begin{verbatim}
        !           352: struct AcSAPstart {
        !           353:     int     acs_sd;
        !           354: 
        !           355:     OID     acs_context;
        !           356: 
        !           357:     AEInfo  acs_callingtitle;
        !           358:     AEInfo  acs_calledtitle;
        !           359: 
        !           360:     struct PSAPstart acs_start;
        !           361: 
        !           362:     int     acs_ninfo;
        !           363:     PE      acs_info[NACDATA];
        !           364: };
        !           365: \end{verbatim}\end{quote}
        !           366: The elements of this structure are:\label{AcSAPstart}
        !           367: \begin{describe}
        !           368: \item[\verb"acs\_sd":] the association-descriptor to be used to reference
        !           369: this association;
        !           370: 
        !           371: \item[\verb"acs\_context":] the application context name;
        !           372: 
        !           373: \item[\verb"acs\_callingtitle":] information on the calling application-entity
        !           374: (if any); 
        !           375: 
        !           376: \item[\verb"acs\_calledtitle":] information on the called application-entity
        !           377: (if any);
        !           378: 
        !           379: \item[\verb"acs\_start":] an \verb"PSAPstart" structure
        !           380: (consult page~\pageref{PSAPstart} of \voltwo/);
        !           381: and,
        !           382: 
        !           383: \item[\verb"acs\_info"/\verb"acs\_ninfo":] any initial data
        !           384: (and the length of that data).
        !           385: \end{describe}
        !           386: Note that the proposed contexts list in the \verb"acs_start" element will
        !           387: contain a context for the ACSE.
        !           388: The routine \verb"AcFindPCI" can be used to determine the PCI being used by
        !           389: the ACSE:
        !           390: \begin{quote}\index{AcFindPCI}\small\begin{verbatim}
        !           391: int     AcFindPCI (sd, pci, aci)
        !           392: int     sd;
        !           393: int    *pci;
        !           394: struct AcSAPindication *aci;
        !           395: \end{verbatim}\end{quote}
        !           396: The parameters to this procedure are:
        !           397: \begin{describe}
        !           398: \item[\verb"sd":] the association-descriptor;
        !           399: 
        !           400: \item[\verb"pci":] a pointer to an integer location,
        !           401: which is updated only if the call succeeds;
        !           402: and,
        !           403: 
        !           404: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !           405: which is updated only if the call fails.
        !           406: \end{describe}
        !           407: 
        !           408: Further,
        !           409: note that the data contained in the structure was allocated via \man malloc(3),
        !           410: and should be released by using the \verb"ACSFREE" macro when no longer
        !           411: referenced.
        !           412: The \verb"ACSFREE" macro,
        !           413: behaves as if it was defined as:\label{ACSFREE}
        !           414: \begin{quote}\index{ACSFREE}\small\begin{verbatim}
        !           415: void    ACSFREE (acs)
        !           416: struct AcSAPstart *acs;
        !           417: \end{verbatim}\end{quote}
        !           418: The macro frees only the data allocated by \verb"AcInit",
        !           419: and not the \verb"AcSAPstart" structure itself.
        !           420: Further,
        !           421: \verb"ACSFREE" should be called only if the call to the \verb"AcInit"
        !           422: routine returned \verb"OK".
        !           423: 
        !           424: If the call to \verb"AcInit" is not successful,
        !           425: then a {\sf A-P-ABORT.INDICATION\/} event is simulated,
        !           426: and the relevant information is returned in an encoded
        !           427: \verb"AcSAPindication" structure.\label{AcSAPindication}
        !           428: \begin{quote}\index{AcSAPindication}\small\begin{verbatim}
        !           429: struct AcSAPindication {
        !           430:     int     aci_type;
        !           431: #define ACI_FINISH      0x00
        !           432: #define ACI_ABORT       0x01
        !           433: 
        !           434:     union {
        !           435:         struct AcSAPfinish aci_un_finish;
        !           436:         struct AcSAPabort aci_un_abort;
        !           437:     }   aci_un;
        !           438: #define aci_finish      aci_un.aci_un_finish
        !           439: #define aci_abort       aci_un.aci_un_abort
        !           440: };
        !           441: \end{verbatim}\end{quote}
        !           442: As shown, this structure is really a discriminated union
        !           443: (a structure with a tag element followed by a union).
        !           444: Hence, on a failure return,
        !           445: one first coerces a pointer to the \verb"AcSAPabort" structure contained
        !           446: therein,
        !           447: and then consults the elements of that structure.
        !           448: \begin{quote}\index{AcSAPabort}\small\begin{verbatim}
        !           449: struct AcSAPabort {
        !           450:     int     aca_source;
        !           451: 
        !           452:     int     aca_reason;
        !           453: 
        !           454:     int     aca_ninfo;
        !           455:     PE      aca_info[NACDATA];
        !           456: 
        !           457: #define ACA_SIZE        512
        !           458:     int     aca_cc;
        !           459:     char    aca_data[ACA_SIZE];
        !           460: };
        !           461: \end{verbatim}\end{quote}
        !           462: The elements of an \verb"AcSAPabort" structure are:
        !           463: \begin{describe}
        !           464: \item[\verb"aca\_source":] the source of the abort, one of:
        !           465: \[\begin{tabular}{|l|l|}
        !           466: \hline
        !           467:     \multicolumn{1}{|c|}{\bf Value}&
        !           468:                \multicolumn{1}{c|}{\bf Source}\\
        !           469: \hline
        !           470:     \tt ACA\_USER&             service-user (peer)\\
        !           471:     \tt ACA\_PROVIDER&         service-provider\\
        !           472:     \tt ACA\_LOCAL&            local ACPM\\
        !           473: \hline
        !           474: \end{tabular}\]
        !           475: 
        !           476: \item[\verb"aca\_reason":] the reason for the provider-initiated abort
        !           477: (meaningful only if \verb"aca_source" is not \verb"ACA_REQUESTOR"),
        !           478: consult Table~\ref{AcSAPreasons};
        !           479: 
        !           480: \item[\verb"aca\_info"/\verb"aca\_ninfo":] any abort data
        !           481: (and the length of that data) from the peer
        !           482: (if \verb"aca_source" is \verb"ACA_USER");
        !           483: and,
        !           484: 
        !           485: \item[\verb"aca\_data"/\verb"aca\_cc":] a diagnostic string from the provider.
        !           486: \end{describe}
        !           487: \tagtable[tp]{2a-1}{AcSAP Failure Codes}{AcSAPreasons}
        !           488: Note that the data contained in the structure was allocated via \man malloc(3),
        !           489: and should be released by using the \verb"ACAFREE" macro when no longer
        !           490: referenced.
        !           491: The \verb"ACAFREE" macro,
        !           492: behaves as if it was defined as:\label{ACAFREE}
        !           493: \begin{quote}\index{ACAFREE}\small\begin{verbatim}
        !           494: void    ACAFREE (aca)
        !           495: struct AcSAPabort *aca;
        !           496: \end{verbatim}\end{quote}
        !           497: The macro frees only the data contained in the structure,
        !           498: and not the \verb"AcSAPabort" structure itself.
        !           499: 
        !           500: After examining the information returned by \verb"AcInit" on a successful call
        !           501: (and possibly after examining the argument vector),
        !           502: the responder should either accept or reject the association.
        !           503: For either response,
        !           504: the responder should use the \verb"AcAssocResponse" routine
        !           505: (which corresponds to the {\sf A-ASSOCIATE.RESPONSE\/} action).
        !           506: \begin{quote}\index{AcAssocResponse}\small\begin{verbatim}
        !           507: int     AcAssocResponse (sd, status, reason, context, 
        !           508:         respondtitle, respondaddr, ctxlist, defctxresult,
        !           509:         prequirements, srequirements, isn, settings, ref,
        !           510:         data, ndata, aci)
        !           511: int     sd;
        !           512: int     status,
        !           513:         reason;
        !           514: OID     context;
        !           515: AEI     respondtitle;
        !           516: struct PSAPaddr *respondaddr;
        !           517: int     prequirements,
        !           518:         srequirements,
        !           519:         settings,
        !           520:         ndata;
        !           521: long    isn;
        !           522: struct PSAPctxlist *ctxlist;
        !           523: int     defctxresult;
        !           524: struct SSAPref *ref;
        !           525: PE     *data;
        !           526: struct AcSAPindication *aci;
        !           527: \end{verbatim}\end{quote}
        !           528: The parameters to this procedure are:\label{AcAssocResponse}
        !           529: \begin{describe}
        !           530: \item[\verb"sd":] the association-descriptor;
        !           531: 
        !           532: \item[\verb"status":] the acceptance indicator
        !           533: (either \verb"ACS_ACCEPT" if the association is to be accepted,
        !           534: or one of the user-initiated rejection codes listed in
        !           535: Table~\ref{AcSAPreasons} on page~\pageref{AcSAPreasons});
        !           536: 
        !           537: \item[\verb"reason":] the diagnostic
        !           538: (either \verb"ACS_USER_NULL" if the association is to be accepted,
        !           539: or one of the user-initiated diagnostic codes listed in
        !           540: Table~\ref{AcSAPdiagnostics} on page~\pageref{AcSAPdiagnostics});
        !           541: 
        !           542: \item[\verb"context":] the application context to be used over the
        !           543: association (defaults to the context proposed);
        !           544: 
        !           545: \item[\verb"respondtitle":] information on the responding application-entity
        !           546: (optional);
        !           547: 
        !           548: \item[\verb"data"/\verb"ndata":] an array of user data
        !           549: (and the number of elements in that array,
        !           550: consult the warning on page~\pageref{AcSAPdata});
        !           551: and,
        !           552: 
        !           553: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !           554: which is updated only if the call fails.
        !           555: \end{describe}
        !           556: The remaining parameters are for the presentation service,
        !           557: consult the description of the \verb"PConnResponse" routine on
        !           558: page~\pageref{PConnResponse} of \voltwo/.
        !           559: \tagtable[tp]{2a-2}{AcSAP Diagnostic Codes}{AcSAPdiagnostics}
        !           560: 
        !           561: If the call to \verb"AcAssocResponse" is successful,
        !           562: and the \verb"status" parameter is set to \verb"ACS_ACCEPT",
        !           563: then association establishment has now been completed.
        !           564: If the call is successful,
        !           565: but the \verb"status" parameter is not \verb"ACS_ACCEPT",
        !           566: then the association has been rejected and the responder may exit.
        !           567: Otherwise,
        !           568: if the call failed and the reason is ``fatal'',
        !           569: then the association is lost.
        !           570: 
        !           571: \subsubsection {Client Initialization}
        !           572: A program wishing to associate itself with another application-level user 
        !           573: calls the \verb"AcAssocRequest" routine,
        !           574: which corresponds to the user taking the {\sf A-ASSOCIATE.REQUEST\/} action.
        !           575: \begin{quote}\index{AcAssocRequest}\small\begin{verbatim}
        !           576: int     AcAssocRequest (context, callingtitle, calledtitle,
        !           577:         callingaddr, calledaddr, ctxlist, defctxname,
        !           578:         prequirements, srequirements, isn, settings, ref,
        !           579:         data, ndata, qos, acc, aci)
        !           580: OID     context;
        !           581: AEI     callingtitle,
        !           582:         calledtitle;
        !           583: struct PSAPaddr *callingaddr,
        !           584:                 *calledaddr;
        !           585: int     prequirements,
        !           586:         srequirements,
        !           587:         settings,
        !           588:         ndata;
        !           589: long    isn;
        !           590: struct PSAPctxlist *ctxlist;
        !           591: OID     defctxname;
        !           592: struct SSAPref *ref;
        !           593: PE    *data;
        !           594: struct QOStype *qos;
        !           595: struct AcSAPconnect *acc;
        !           596: struct AcSAPindication *aci;
        !           597: \end{verbatim}\end{quote}
        !           598: The parameters to this procedure are:\label{AcAssocRequest}
        !           599: \begin{describe}
        !           600: \item[\verb"context":] the application context to be used over the
        !           601: association;
        !           602: 
        !           603: \item[\verb"callingtitle":] information on the calling application-entity
        !           604: (use the manifest constant \verb"NULLAEI" if not specified);
        !           605: 
        !           606: \item[\verb"calledtitle":]  information on the called application-entity
        !           607: (use the manifest constant \verb"NULLAEI" if not specified);
        !           608: 
        !           609: \item[\verb"data"/\verb"ndata":] an array of initial data
        !           610: (and the number of elements in that array,
        !           611: consult the warning on page~\pageref{AcSAPdata});
        !           612: 
        !           613: \item[\verb"qos":] the quality of service on the connection
        !           614: (see Section~\ref{tsap:qos} in \voltwo/);
        !           615: 
        !           616: \item[\verb"acc":] a pointer to an \verb"AcSAPconnect" structure,
        !           617: which is updated only if the call succeeds;
        !           618: and,
        !           619: 
        !           620: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !           621: which is updated only if the call fails.
        !           622: \end{describe}
        !           623: The remaining parameters are for the presentation service,
        !           624: consult the description of the \verb"PConnRequest" routine on
        !           625: page~\pageref{PConnRequest} of \voltwo/ for additional information.
        !           626: Note that the \verb"ctxlist" parameter is mandatory:
        !           627: the association control service element will look for the ACSE PCI there.
        !           628: If not present,
        !           629: it will add the PCI to the list.
        !           630: 
        !           631: If the call to \verb"AcAssocRequest" is successful
        !           632: (the {\sf A-ASSOCIATE.CON\-FIR\-MA\-TION\/} event occurs),
        !           633: it returns information in the \verb"acc" parameter
        !           634: which is a pointer to an \verb"AcSAPconnect" structure.
        !           635: \begin{quote}\index{AcSAPconnect}\small\begin{verbatim}
        !           636: struct AcSAPconnect {
        !           637:     int     acc_sd;
        !           638: 
        !           639:     int     acc_result;
        !           640:     int     acc_diagnostic;
        !           641: 
        !           642:     OID     acc_context;
        !           643: 
        !           644:     AEInfo  acc_respondtitle;
        !           645: 
        !           646:     struct PSAPconnect acc_connect;
        !           647: 
        !           648:     int     acc_ninfo;
        !           649:     PE      acc_info[NACDATA];
        !           650: };
        !           651: \end{verbatim}\end{quote}
        !           652: The elements of an \verb"AcSAPconnect" structure are:\label{AcSAPconnect}
        !           653: \begin{describe}
        !           654: \item[\verb"acc\_sd":] the association-descriptor to be used to reference
        !           655: this association;
        !           656: 
        !           657: \item[\verb"acc\_result"/\verb"acc\_diagnostic":] the association response
        !           658: and diagnostic;
        !           659: 
        !           660: \item[\verb"acc\_context":] the application context name;
        !           661: 
        !           662: \item[\verb"acc\_respondtitle":] information on the responding
        !           663: application-entity (if any);
        !           664: 
        !           665: \item[\verb"acc\_connect":] an \verb"PSAPconnect" structure
        !           666: (consult page~\pageref{PSAPconnect} of \voltwo/);
        !           667: and,
        !           668: 
        !           669: \item[\verb"acc\_info"/\verb"acc\_ninfo":] any initial data
        !           670: (and the length of that data).
        !           671: \end{describe}
        !           672: Note that the negotiated contexts list in the \verb"acc_connect" element
        !           673: will contain a context for the ACSE.
        !           674: To determine the PCI for the ACSE context,
        !           675: the routine \verb"AcFindPCI" routine,
        !           676: described above can be used.
        !           677: 
        !           678: If the call to \verb"AcAssocRequest" is successful,
        !           679: and the \verb"acc_result" element is set to \verb"ACC_ACCEPT",
        !           680: then association establishment has completed.
        !           681: If the call is successful,
        !           682: but the \verb"acc_result" element is not \verb"ACC_ACCEPT",
        !           683: then the association attempt has been rejected;
        !           684: consult Table~\ref{AcSAPreasons} on page~\pageref{AcSAPreasons} 
        !           685: and Table~\ref{AcSAPdiagnostics} on page~\pageref{AcSAPdiagnostics} 
        !           686: to determine the reason for the rejection
        !           687: (further information can be found in the \verb"aci" parameter).
        !           688: Otherwise, if the call fails then the association is not established and
        !           689: the \verb"AcSAPabort" structure of the \verb"AsCAPindication" discriminated
        !           690: union has been updated.
        !           691: 
        !           692: Note that the data contained in the structure was allocated via \man malloc(3),
        !           693: and should be released by using the \verb"ACCFREE" macro when no longer
        !           694: referenced.
        !           695: The \verb"ACCFREE" macro,
        !           696: behaves as if it was defined as:\label{ACCFREE}
        !           697: \begin{quote}\index{ACCFREE}\small\begin{verbatim}
        !           698: void    ACCFREE (acc)
        !           699: struct AcSAPconnect *acc;
        !           700: \end{verbatim}\end{quote}
        !           701: The macro frees only the data allocated by \verb"AcAssocRequest",
        !           702: and not the \verb"AcSAPconnect" structure itself.
        !           703: Further,
        !           704: \verb"ACCFREE" should be called only if the call to the \verb"AcAssocRequest"
        !           705: routine returned \verb"OK".
        !           706: 
        !           707: Normally \verb"AcAssocRequest" returns only after an association has succeeded
        !           708: or failed.
        !           709: This is termed a {\em synchronous\/} association initiation.
        !           710: If the user desires, an {\em asynchronous\/} association may be initiated.
        !           711: This routine is really a macro which calls the routine
        !           712: \verb"AcAsynAssocRequest" with an argument indicating that a association should
        !           713: be attempted synchronously.
        !           714: \begin{quote}\index{AcAsynAssocRequest}\small\begin{verbatim}
        !           715: int     AcAsynAssocRequest (context, callingtitle, calledtitle,
        !           716:         callingaddr, calledaddr, ctxlist, defctxname,
        !           717:         prequirements, srequirements, isn, settings, ref,
        !           718:         data, ndata, qos, acc, aci, async)
        !           719: OID     context;
        !           720: AEI     callingtitle,
        !           721:         calledtitle;
        !           722: struct PSAPaddr *callingaddr,
        !           723:                 *calledaddr;
        !           724: int     prequirements,        
        !           725:         srequirements,
        !           726:         settings,
        !           727:         ndata,
        !           728:         async;
        !           729: long    isn;
        !           730: struct PSAPctxlist *ctxlist;
        !           731: OID     defctxname;
        !           732: struct SSAPref *ref;
        !           733: PE    *data;
        !           734: struct QOStype *qos;
        !           735: struct AcSAPconnect *acc;
        !           736: struct AcSAPindication *aci;
        !           737: \end{verbatim}\end{quote}
        !           738: The additional parameter to this procedure is:
        !           739: \begin{describe}
        !           740: \item[\verb"async":] whether the association should be initiated
        !           741: asynchronously.
        !           742: \end{describe}
        !           743: If the \verb"async" parameter is non-zero,
        !           744: then \verb"AcAsynAssocRequest" returns one of four values:
        !           745: \verb"NOTOK", which indicates that the association request failed;
        !           746: \verb"DONE", which indicates that the association request succeeded;
        !           747: or, either of \verb"CONNECTING_1" or \verb"CONNECTING_2", which indicates that
        !           748: the connection request is still in
        !           749: progress.
        !           750: In the first two cases,
        !           751: the usual procedures for handling return values from \verb"AcAssocRequest" are
        !           752: employed
        !           753: (i.e., a \verb"NOTOK" return from \verb"AcAsynAssocRequest" is equivalent to a
        !           754: \verb"NOTOK" return from \verb"AcAssocRequest", and,
        !           755: a \verb"DONE" return from \verb"AcAsynAssocRequest" is equivalent to a
        !           756: \verb"OK" return from \verb"AcAssocRequest").
        !           757: 
        !           758: In the final case, when either \verb"CONNECTING_1" or
        !           759: \verb"CONNECTING_2" is returned,
        !           760: only the \verb"acc_sd" element of the \verb"acc" parameter has been updated;
        !           761: it reflects the association-descriptor to be used to reference this
        !           762: association.
        !           763: To determine when the association attempt has been completed,
        !           764: the routine \verb"xselect" (consult Section~\ref{acs:select})
        !           765: should be used after calling \verb"PSelectMask".
        !           766: In order to determine if the association attempt is successful,
        !           767: the routine \verb"AcAsynRetryRequest" is called:
        !           768: \begin{quote}\index{AcAsynRetryRequest}\small\begin{verbatim}
        !           769: int     AcAsynRetryRequest (sd, acc, aci)
        !           770: int     sd;
        !           771: struct AcSAPconnect *acc;
        !           772: struct AcSAPindication  *aci;
        !           773: \end{verbatim}\end{quote}
        !           774: The parameters to this procedure are:
        !           775: \begin{describe}
        !           776: \item[\verb"sd":] the association-descriptor;
        !           777: 
        !           778: \item[\verb"acc":] a pointer to an \verb"AcSAPconnect" structure, which is
        !           779: updated only if the call succeeds;
        !           780: and,
        !           781: 
        !           782: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure, which is
        !           783: updated only if the call fails.
        !           784: \end{describe}
        !           785: Again, one of three values are returned:
        !           786: \verb"NOTOK", which indicates that the association request failed;
        !           787: \verb"DONE", which indicates that the association request succeeded;
        !           788: and, \verb"CONNECTING_1" or \verb"CONNECTING_2" which indicates that
        !           789: the connection request is still in progress.
        !           790: 
        !           791: Refer to Section~\ref{tsap:async} on page~\pageref{tsap:async} in \voltwo/
        !           792: for information on how to make efficient use of the asynchronous connection
        !           793: facility. 
        !           794: 
        !           795: \subsection    {Association Release}
        !           796: The \verb"AcRelRequest" routine is used to request the release of an
        !           797: association,
        !           798: and corresponds to a {\sf A-RELEASE.REQUEST\/} action.
        !           799: \begin{quote}\index{AcRelRequest}\small\begin{verbatim}
        !           800: int     AcRelRequest (sd, reason, data, ndata, secs, acr, aci)
        !           801: int     sd;
        !           802: int     reason;
        !           803: PE     *data;
        !           804: int     ndata;
        !           805: int     secs;
        !           806: struct AcSAPrelease *acr;
        !           807: struct AcSAPindication *aci;
        !           808: \end{verbatim}\end{quote}
        !           809: The parameters to this procedure:
        !           810: \begin{describe}
        !           811: \item[\verb"sd":] the association-descriptor;
        !           812: 
        !           813: \item[\verb"reason":] the reason why the association should be released,
        !           814: one of:
        !           815: \[\begin{tabular}{|l|l|}
        !           816: \hline
        !           817:     \multicolumn{1}{|c|}{\bf Value}&
        !           818:                \multicolumn{1}{c|}{\bf Reason}\\
        !           819: \hline
        !           820:     \tt ACF\_NORMAL&   normal\\
        !           821:     \tt ACF\_URGENT&   urgent\\
        !           822:     \tt ACF\_UNDEFINED&        undefined\\
        !           823: \hline
        !           824: \end{tabular}\]
        !           825: 
        !           826: \item[\verb"data"/\verb"ndata":] an array of final data
        !           827: (and the number of elements in that array,
        !           828: consult the warning on page~\pageref{AcSAPdata});
        !           829: 
        !           830: \item[\verb"secs":] the maximum number of seconds to wait for a response
        !           831: (use the manifest constant \verb"NOTOK" if no time-out is desired);
        !           832: 
        !           833: \item[\verb"acr":] a pointer to an \verb"AcSAPrelease" structure,
        !           834: which is updated only if the call succeeds;
        !           835: and,
        !           836: 
        !           837: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !           838: which is updated only if the call fails.
        !           839: \end{describe}
        !           840: If the call to \verb"AcRelRequest" is successful,
        !           841: then this corresponds to a {\sf A-RELEASE.CONFIRMATION\/} event,
        !           842: and it returns information in the \verb"acr" parameter,
        !           843: which is a pointer to an \verb"AcSAPrelease" structure.
        !           844: \begin{quote}\index{AcSAPrelease}\small\begin{verbatim}
        !           845: struct AcSAPrelease {
        !           846:     int     acr_affirmative;
        !           847: 
        !           848:     int     acr_reason;
        !           849: 
        !           850:     int     acr_ninfo;
        !           851:     PE      acr_info[NACDATA];
        !           852: };
        !           853: \end{verbatim}\end{quote}
        !           854: The elements of this structure are:\label{AcSAPrelease}
        !           855: \begin{describe}
        !           856: \item[\verb"acr\_affirmative":]        the acceptance indicator;
        !           857: 
        !           858: \item[\verb"acr\_reason":]     the reason for the indicator,
        !           859: one of:
        !           860: \[\begin{tabular}{|l|l|}
        !           861: \hline
        !           862:     \multicolumn{1}{|c|}{\bf Value}&
        !           863:                \multicolumn{1}{c|}{\bf Reason}\\
        !           864: \hline
        !           865:     \tt ACR\_NORMAL&           normal\\
        !           866:     \tt ACR\_NOTFINISHED&      not finished\\
        !           867:     \tt ACR\_UNDEFINED&                undefined\\
        !           868: \hline
        !           869: \end{tabular}\]
        !           870: 
        !           871: \item[\verb"acr\_info"/\verb"acr\_ninfo":]     any final data
        !           872: (and the length of that data).
        !           873: \end{describe}
        !           874: Note that the data contained in the structure was allocated via \man malloc(3),
        !           875: and should be released by using the \verb"ACRFREE" macro when no longer
        !           876: referenced.
        !           877: The \verb"ACRFREE" macro,
        !           878: behaves as if it was defined as:\label{ACRFREE}
        !           879: \begin{quote}\index{ACRFREE}\small\begin{verbatim}
        !           880: void    ACRFREE (acr)
        !           881: struct AcSAPrelease *acr;
        !           882: \end{verbatim}\end{quote}
        !           883: The macro frees only the data allocated by \verb"AcRelRequest",
        !           884: and not the \verb"AcSAPrelease" structure itself.
        !           885: Further,
        !           886: \verb"ACRFREE" should be called only if the call to the \verb"AcRelRequest"
        !           887: routine returned \verb"OK".
        !           888: 
        !           889: If the call to \verb"AcRelRequest" is successful,
        !           890: and the \verb"acr_affirmative" element is set,
        !           891: then the association has been released.
        !           892: If the call is successful,
        !           893: but the \verb"acr_affirmative" element is not set (i.e., zero),
        !           894: then the request to release the association has been rejected by the remote
        !           895: user,
        !           896: and the association is still established.
        !           897: Otherwise the \verb"AcSAPabort" element of the \verb"AcSAPindication"
        !           898: parameter \verb"aci" contains the reason for failure.
        !           899: 
        !           900: Note that if a non-negative value is given to the \verb"secs" parameter and a
        !           901: response is not received within this number of seconds,
        !           902: then the value contained in the \verb"aca_reason" element is \verb"ACS_TIMER".
        !           903: The user can then call the routine \verb"AcRelRetryRequest" to continue waiting
        !           904: for a response:
        !           905: \begin{quote}\index{AcRelRetryRequest}\small\begin{verbatim}
        !           906: int     AcRelRetryRequest (sd, secs, acr, aci)
        !           907: int     sd;
        !           908: int     secs;
        !           909: struct AcSAPrelease  *acr;
        !           910: struct AcSAPindication  *aci;
        !           911: \end{verbatim}\end{quote}
        !           912: The parameters to this procedure are:
        !           913: \begin{describe}
        !           914: \item[\verb"sd":] the association-descriptor;
        !           915: 
        !           916: \item[\verb"secs":] the maximum number of seconds to wait for a response
        !           917: (use the manifest constant \verb"NOTOK" if no time-out is desired);
        !           918: 
        !           919: \item[\verb"acr":] a pointer to a \verb"AcSAPrelease" structure, which is
        !           920: updated only if the call succeeds;
        !           921: and,
        !           922: 
        !           923: \item[\verb"aci":] a pointer to a \verb"AcSAPindication" structure, which is
        !           924: updated only if the call fails.
        !           925: \end{describe}
        !           926: If the call to \verb"AcRelRetryRequest" is successful,
        !           927: and the \verb"acr_affirmative" element is set,
        !           928: then the association has been closed.
        !           929: If the call is successful,
        !           930: but the \verb"acr_affirmative" element is not set (i.e., zero),
        !           931: then the request to release the assocation has been rejected by the remote
        !           932: user, and the association is still open.
        !           933: Otherwise the \verb"AcSAPabort" structure contained in
        !           934: the \verb"AcSAPindication" parameter
        !           935: \verb"aci" contains the reason for failure.
        !           936: As expected,
        !           937: the value \verb"ACS_TIMER" indicates that no response was received within the
        !           938: time given by the \verb"secs" parameter.
        !           939: 
        !           940: Upon receiving a {\sf A-RELEASE.INDICATION\/} event,
        !           941: the user is required to generate a {\sf A-RELEASE.RESPONSE\/} action
        !           942: using the \verb"AcRelResponse" routine.
        !           943: \begin{quote}\index{AcRelResponse}\small\begin{verbatim}
        !           944: int     AcRelResponse (sd, status, reason, data, ndata, aci)
        !           945: int     sd;
        !           946: int     status,
        !           947:         reason;
        !           948: PE     *data;
        !           949: int     ndata;
        !           950: struct AcSAPindication *aci;
        !           951: \end{verbatim}\end{quote}
        !           952: The parameters to this procedure:
        !           953: \begin{describe}
        !           954: \item[\verb"sd":] the association-descriptor;
        !           955: 
        !           956: \item[\verb"status":] the acceptance indicator
        !           957: (either \verb"ACS_ACCEPT" if the association is to be released,
        !           958: or \verb"ACS_REJECT" otherwise);
        !           959: 
        !           960: \item[\verb"reason":] the reason for the indicator,
        !           961: one of:
        !           962: \[\begin{tabular}{|l|l|}
        !           963: \hline
        !           964:     \multicolumn{1}{|c|}{\bf Value}&
        !           965:                \multicolumn{1}{c|}{\bf Reason}\\
        !           966: \hline
        !           967:     \tt ACR\_NORMAL&           normal\\
        !           968:     \tt ACR\_NOTFINISHED&      not finished\\
        !           969:     \tt ACR\_UNDEFINED&                undefined\\
        !           970: \hline
        !           971: \end{tabular}\]
        !           972: 
        !           973: \item[\verb"data"/\verb"ndata":] an array of final data
        !           974: (and the number of elements in that array,
        !           975: consult the warning on page~\pageref{AcSAPdata});
        !           976: and,
        !           977: 
        !           978: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !           979: which is updated only if the call fails.
        !           980: \end{describe}
        !           981: If the call to \verb"AcRelResponse" is successful,
        !           982: and if the \verb"result" parameter is set to \verb"ACS_ACCEPT",
        !           983: then the association has been released.
        !           984: If the call is successful,
        !           985: but the \verb"result" parameter is not \verb"ACS_ACCEPT",
        !           986: then the association remains established.
        !           987: 
        !           988: \subsection    {Association Abort}
        !           989: To unilaterally abort an association,
        !           990: the routine \verb"AcUAbortRequest" routine is used
        !           991: which corresponds to the {\sf A-ABORT.REQUEST\/} action.
        !           992: \begin{quote}\index{AcUAbortRequest}\small\begin{verbatim}
        !           993: int     AcUAbortRequest (sd, data, ndata, aci)
        !           994: int     sd;
        !           995: PE     *data;
        !           996: int     ndata;
        !           997: struct AcSAPindication *aci;
        !           998: \end{verbatim}\end{quote}
        !           999: The parameters to this procedure:
        !          1000: \begin{describe}
        !          1001: \item[\verb"sd":] the association-descriptor;
        !          1002: 
        !          1003: \item[\verb"data"/\verb"ndata":] an array of abort data
        !          1004: (and the number of elements in that array,
        !          1005: consult the warning on page~\pageref{AcSAPdata});
        !          1006: and,
        !          1007: 
        !          1008: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
        !          1009: which is updated only if the call fails.
        !          1010: \end{describe}
        !          1011: If the call to \verb"AcUAbortRequest" is successful,
        !          1012: then the association is immediately released,
        !          1013: and any data queued for the association may be lost.
        !          1014: 
        !          1015: \section      {Association Events}
        !          1016: Typically,
        !          1017: the presentation service generates events which lead to the
        !          1018: {\sf A-RELEASE.INDICATION}, {\sf A-ABORT.INDICATION},
        !          1019: and {\sf A-P-ABORT.IN\-DI\-CA\-TION\/} events being raised.
        !          1020: For those interested in writing application service elements which interpret
        !          1021: this information,
        !          1022: this section describes the necessary mappings.
        !          1023: 
        !          1024: \subsection    {Release Indication}
        !          1025: Upon receiving a {\sf P-RELEASE.INDICATION\/} event,
        !          1026: the routine \verb"AcFINISHser" should be called to map this into a
        !          1027: {\sf A-RELEASE.INDICATION\/} event.
        !          1028: \begin{quote}\index{AcFINISHser}\small\begin{verbatim}
        !          1029: int     AcFINISHser (sd, pf, aci)
        !          1030: int     sd;
        !          1031: struct PSAPfinish *pf;
        !          1032: struct AcSAPindication *aci;
        !          1033: \end{verbatim}\end{quote}
        !          1034: The parameters to this procedure:
        !          1035: \begin{describe}
        !          1036: \item[\verb"sd":] the association-descriptor;
        !          1037: 
        !          1038: \item[\verb"pa":] a pointer to an \verb"PSAPfinish" structure,
        !          1039: containing information on the presentation-level release;
        !          1040: and,
        !          1041: 
        !          1042: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure.
        !          1043: \end{describe}
        !          1044: If the call to \verb"AcFINISHser" is successful,
        !          1045: then the \verb"aci_type" field of the \verb"aci" parameter contains the value
        !          1046: \verb"ACI_FINISH",
        !          1047: and an \verb"AcSAPfinish" structure is contained inside the \verb"aci"
        !          1048: parameter.
        !          1049: \begin{quote}\index{AcSAPfinish}\small\begin{verbatim}
        !          1050: struct AcSAPfinish {
        !          1051:     int     acf_reason;
        !          1052: 
        !          1053:     int     acf_ninfo;
        !          1054:     char    acf_info[NACDATA];
        !          1055: };
        !          1056: \end{verbatim}\end{quote}
        !          1057: The elements of this structure are:
        !          1058: \begin{describe}
        !          1059: \item[\verb"acf\_reason":]     the reason for the release request,
        !          1060: one of:
        !          1061: \[\begin{tabular}{|l|l|}
        !          1062: \hline
        !          1063:     \multicolumn{1}{|c|}{\bf Value}&
        !          1064:                \multicolumn{1}{c|}{\bf Reason}\\
        !          1065: \hline
        !          1066:     \tt ACF\_NORMAL&   normal\\
        !          1067:     \tt ACF\_URGENT&   urgent\\
        !          1068:     \tt ACF\_UNDEFINED&        undefined\\
        !          1069: \hline
        !          1070: \end{tabular}\]
        !          1071: 
        !          1072: \item[\verb"acf\_info"/\verb"acf\_ninfo":]     any final data
        !          1073: (and the length of that data).
        !          1074: \end{describe}
        !          1075: Note that the data contained in the structure was allocated via \man malloc(3),
        !          1076: and should be released by using the \verb"ACFFREE" macro when no longer
        !          1077: referenced.
        !          1078: The \verb"ACFFREE" macro,
        !          1079: behaves as if it was defined as:\label{ACFFREE}
        !          1080: \begin{quote}\index{ACFFREE}\small\begin{verbatim}
        !          1081: void    ACFFREE (acf)
        !          1082: struct AcSAPfinish *acf;
        !          1083: \end{verbatim}\end{quote}
        !          1084: The macro frees only the data allocated by \verb"AcFINISHser",
        !          1085: and not the \verb"AcSAPfinish" structure itself.
        !          1086: Further,
        !          1087: \verb"ACFFREE" should be called only if the call to the \verb"AcFINISHser"
        !          1088: routine returned \verb"OK".
        !          1089: 
        !          1090: Otherwise,
        !          1091: if the call fails,
        !          1092: the \verb"aci" parameter contains information pertaining to the failure.
        !          1093: 
        !          1094: \subsection    {Abort Indication}
        !          1095: Upon receiving a {\sf P-U-ABORT.INDICATION\/} or {\sf P-P-ABORT.INDICATION\/}
        !          1096: event,
        !          1097: the routine \verb"AcABORTser" should be called to map this into a
        !          1098: {\sf A-ABORT.INDICATION\/} or {\sf A-P-ABORT.INDICATION\/} event.
        !          1099: \begin{quote}\index{AcABORTser}\small\begin{verbatim}
        !          1100: int     AcABORTser (sd, pa, aci)
        !          1101: int     sd;
        !          1102: struct PSAPabort *pa;
        !          1103: struct AcSAPindication *aci;
        !          1104: \end{verbatim}\end{quote}
        !          1105: The parameters to this procedure:
        !          1106: \begin{describe}
        !          1107: \item[\verb"sd":] the association-descriptor;
        !          1108: 
        !          1109: \item[\verb"pa":] a pointer to an \verb"PSAPabort" structure,
        !          1110: containing information on the presentation-level abort;
        !          1111: and,
        !          1112: 
        !          1113: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure.
        !          1114: \end{describe}
        !          1115: If the call to \verb"AcABORTser" is successful,
        !          1116: then the \verb"aci" parameter is updated to reflect information on the abort
        !          1117: indication.
        !          1118: Otherwise,
        !          1119: if the call fails,
        !          1120: the \verb"aci" parameter contains information pertaining to the failure.
        !          1121: 
        !          1122: \section      {Select Facility}\label{acs:select}
        !          1123: Ideally,
        !          1124: the \man select(2) system call should be used on all descriptors,
        !          1125: regardless of the level of abstraction
        !          1126: (e.g., association-descriptor, presentation-descriptor, and so on).
        !          1127: The routines with a \verb"SelectMask" suffix,
        !          1128: such as \verb"PSelectMask"
        !          1129: are supplied to determine if there are already queued events.
        !          1130: These routines should always be called prior to using the select facility
        !          1131: of the kernel.
        !          1132: Sadly, some networking subsystems used by the software do not support
        !          1133: \man select(2).
        !          1134: To provide a consistent interface,
        !          1135: the \verb"xselect" routine should be used instead of \man select(2).
        !          1136: \begin{quote}\index{xselect}\small\begin{verbatim}
        !          1137: int     xselect (nfds, rfds, wfds, efds, secs)
        !          1138: int     nfds;
        !          1139: fd_set *rfds,
        !          1140:        *wfds,
        !          1141:        *efds,
        !          1142:         secs;
        !          1143: \end{verbatim}\end{quote}
        !          1144: The parameters to this procedure are:
        !          1145: \begin{describe}
        !          1146: \item[\verb"nfds":] the number of descriptors present in the masks
        !          1147: (actually the \verb"width" of descriptors from zero to the highest meaningful
        !          1148: descriptor);
        !          1149: 
        !          1150: \item[\verb"rfds"/\verb"wfds"/\verb"efds":] the locations of
        !          1151: masks interested in read, write, and exception events;
        !          1152: and,
        !          1153: 
        !          1154: \item[\verb"secs":] the maximum number of seconds to wait for an event
        !          1155: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
        !          1156: whereas a value of \verb"OK" indicates that the call should not block at all,
        !          1157: e.g., a polling action).
        !          1158: \end{describe}
        !          1159: Unlike most routines,
        !          1160: the \verb"xselect" routine returns one of several values:
        !          1161: \verb"NOTOK" (on failure),
        !          1162: \verb"OK" (if no events occurred within the time limit),
        !          1163: or,
        !          1164: the number of descriptors on which events occurred
        !          1165: (the masks are updated appropriately).
        !          1166: 
        !          1167: \section      {Generic Server Dispatch}\label{acs:server}
        !          1168: Ideally,
        !          1169: one should write a server which can operate in one of two modes:
        !          1170: \begin{itemize}
        !          1171: \item  Each incoming connection results in \man tsapd(8c) invoking another
        !          1172:        instance of the server; or,
        !          1173: 
        !          1174: \item  All incoming connections are given to exactly one instance of the
        !          1175:        server (the server is invoked without arguments during system
        !          1176:        initialization).
        !          1177: \end{itemize}
        !          1178: The choice as to which mode is used is made by the system administrator.
        !          1179: By default,
        !          1180: the first mode, termed the {\em dynamic\/} approach, is used.
        !          1181: The second mode, termed the {\em static\/} approach,
        !          1182: is described in Section~\ref{static:services} on
        !          1183: page~\pageref{static:services}.
        !          1184: 
        !          1185: There are several ways in which this dual-approach scheme can be realized.
        !          1186: One such implementation is based on the routine
        !          1187: \verb"isodeserver".\label{isodeserver}
        !          1188: \begin{quote}\index{isodeserver}\small\begin{verbatim}
        !          1189: int     isodeserver (argc, argv, aei, initfnx, workfnx,
        !          1190:                 losefnx, td)
        !          1191: int     argc;
        !          1192: char  **argv;
        !          1193: AEI     aei;
        !          1194: IFP     initfnx,
        !          1195:         workfnx,
        !          1196:         losefnx;
        !          1197: struct TSAPdisconnect *td;
        !          1198: \end{verbatim}\end{quote}
        !          1199: The parameters to this procedure are:
        !          1200: \begin{describe}
        !          1201: \item[\verb"argc":] the length of the argument vector which the program was
        !          1202: invoked with;
        !          1203: 
        !          1204: \item[\verb"argv":] the argument vector which the program was invoked with;
        !          1205: 
        !          1206: \item[\verb"aei":] the information on the application-entity offering the
        !          1207: service;
        !          1208: 
        !          1209: \item[\verb"initfnx":] the address of an event-handler routine to be invoked
        !          1210: when a new connection arrives;
        !          1211: 
        !          1212: \item[\verb"workfnx":] the address of an event-handler routine to be invoked
        !          1213: when activity occurs on an association;
        !          1214: 
        !          1215: \item[\verb"losefnx":] the address of an event-handler routine to be invoked
        !          1216: if \verb"TNetAccept" (described in Section~\ref{tsap:listen}) fails 
        !          1217: and,
        !          1218: 
        !          1219: \item[\verb"td":] a pointer to an \verb"TSAPdisconnect" structure,
        !          1220: which is updated only if the call fails.
        !          1221: \end{describe}
        !          1222: If the call is successful,
        !          1223: then the program may terminate immediately,
        !          1224: as no work remains to be done
        !          1225: (in the case of the single instance mode,
        !          1226: \verb"isodeserver" returns only on error).
        !          1227: Otherwise,
        !          1228: the \verb"td" parameter indicates the reason for failure
        !          1229: (consult Section~\ref{TSAPdisconnect} on page~\pageref{TSAPdisconnect}
        !          1230: of \voltwo/).
        !          1231: 
        !          1232: When an event associated with a new connection occurs,
        !          1233: the event-handler routine is invoked with two parameters:
        !          1234: \begin{quote}\small\begin{verbatim}
        !          1235: (*initfnx) (vecp, vec);
        !          1236: int     vecp;
        !          1237: char  **vec;
        !          1238: \end{verbatim}\end{quote}
        !          1239: The parameters are:
        !          1240: \begin{describe}
        !          1241: \item[\verb"vecp":] the length of the argument vector;
        !          1242: and,
        !          1243: 
        !          1244: \item[\verb"vec":] the argument vector.
        !          1245: \end{describe}
        !          1246: The event-handler should then call \verb"AcInit" with these parameters
        !          1247: to achieve an {\sf A-ASSOCIATION.INDICATION\/} event.
        !          1248: If \verb"AcInit" is successful,
        !          1249: the event-handler should decide if it wishes to honor the association
        !          1250: and then call \verb"AcAssocResponse" with the appropriate parameters.
        !          1251: The event-handler should return the assocation-descriptor if it accepted the
        !          1252: association.
        !          1253: Otherwise (or upon any errors),
        !          1254: it should return \verb"NOTOK".
        !          1255: 
        !          1256: When an activity associated with an association occurs,
        !          1257: the event-handler routine is invoked with one parameter:
        !          1258: \begin{quote}\small\begin{verbatim}
        !          1259: (*workfnx) (fd);
        !          1260: int     fd;
        !          1261: \end{verbatim}\end{quote}
        !          1262: The parameter is:
        !          1263: \begin{describe}
        !          1264: \item[\verb"fd":] the association-descriptor of the association.
        !          1265: \end{describe}
        !          1266: The event-handler should then call the appropriate routine to read the next
        !          1267: event from the association
        !          1268: (e.g., \verb"RoWaitRequest" if remote operations are being used).
        !          1269: The event-handler should return \verb"NOTOK" if the association is terminated
        !          1270: or aborted,
        !          1271: or \verb"OK" otherwise.
        !          1272: 
        !          1273: The \verb"isodeserver" routine uses the \verb"TNetAccept" routine to
        !          1274: wait for the next event on existing associations and for new connections.
        !          1275: It is possible, though unlikely for a failure to occur during this operation.
        !          1276: In this event,
        !          1277: the event-handler routine is invoked with one parameter:
        !          1278: \begin{quote}\small\begin{verbatim}
        !          1279: (*losefnx) (td);
        !          1280: struct TSAPdisconnect *td;
        !          1281: \end{verbatim}\end{quote}
        !          1282: The parameter is:
        !          1283: \begin{describe}
        !          1284: \item[\verb"td":] a pointer to an \verb"TSAPdisconnect" structure updated
        !          1285: by \verb"TNetAccept".
        !          1286: \end{describe}
        !          1287: The event-handler should handle the error however it deems proper
        !          1288: (usually by logging it and then returning).
        !          1289: 
        !          1290: An example of this facility is presented in Section~\ref{acs:example} below.
        !          1291: 
        !          1292: Another interface to this approach is provided for servers that may be
        !          1293: engaged in other operations besides answering incoming calls (e.g.
        !          1294: initiating outgoing calls too). This interface provides indentical
        !          1295: functionality to the \verb|isodeserver| interface, but allows access
        !          1296: to other events.
        !          1297: 
        !          1298: The interface is provided by two calls. The first is \verb|iserver_init|.
        !          1299: \begin{quote}\index{iserver\_init}\small\begin{verbatim}
        !          1300: int     iserver_init (argc, argv, aei, initfnx, td)
        !          1301: int     argc;
        !          1302: char  **argv;
        !          1303: AEI     aei;
        !          1304: IFP     initfnx;
        !          1305: struct TSAPdisconnect *td;
        !          1306: \end{verbatim}\end{quote}
        !          1307: 
        !          1308: The parameters to this procedure are similar in part to the
        !          1309: \verb|isodeserver| procedure:
        !          1310: \begin{describe}
        !          1311: \item[\verb|argc|:]    the length of the argument vector which the
        !          1312: program was invoked with;
        !          1313: 
        !          1314: \item[\verb|argv|:]    the argument vector which the program was
        !          1315: invoked with;
        !          1316: 
        !          1317: \item[\verb|aei|:]     the information on the application-entity
        !          1318: offering the service;
        !          1319: 
        !          1320: \item[\verb"initfnx":] the address of an event-handler routine to be invoked
        !          1321: when a new connection arrives, and
        !          1322: 
        !          1323: \item[\verb|td|:]      a pointer to an \verb"TSAPdisconnect" structure,
        !          1324: which is updated only if the call fails.
        !          1325: \end{describe}
        !          1326: 
        !          1327: This procedure registers a listener for the address and may may call
        !          1328: the \verb|initfnx| if the server is running in dynamic mode. If the
        !          1329: call fails the \verb|td| parameter will indicate the reason for
        !          1330: failure.
        !          1331: 
        !          1332: One this function has been called, the \verb|iserver_wait| procedure
        !          1333: should be called at regular intervals to handle incoming events,
        !          1334: typically in a loop of some kind. It is called as follows:
        !          1335: \begin{quote}\index{iserver\_wait}\small\begin{verbatim}
        !          1336: int     iserver_wait (initfnx, workfnx, losefnx, nfds, 
        !          1337:                 nfds, rfds, wfds, efds, secs, td)
        !          1338: IFP     initfnx,
        !          1339:         workfnx,
        !          1340:         losefnx;
        !          1341: int     nfds;
        !          1342: fd_set *rfds,
        !          1343:        *wfds,
        !          1344:        *efds;
        !          1345: int     secs;
        !          1346: struct TSAPdisconnect *td;
        !          1347: \end{verbatim}\end{quote}
        !          1348: The parameters to this procedure are:
        !          1349: \begin{describe}
        !          1350: 
        !          1351: \item[\verb"initfnx":] the address of an event-handler routine to be invoked
        !          1352: when a new connection arrives;
        !          1353: 
        !          1354: \item[\verb"workfnx":] the address of an event-handler routine to be invoked
        !          1355: when activity occurs on an association;
        !          1356: 
        !          1357: \item[\verb"losefnx":] the address of an event-handler routine to be invoked
        !          1358: if \verb"TNetAccept" (described in Section~\ref{tsap:listen}) fails;
        !          1359: 
        !          1360: \item[\verb|nfds/rfds/wfds/efds|:]     additional
        !          1361: association-descriptors/file descriptors to await for activity on;
        !          1362: 
        !          1363: \item[\verb|secs|:]    the maximum number of seconds to wait for
        !          1364: activity (a value of \verb|NOTOK| indicates that the call should block
        !          1365: indefinitely, whereas a value of \verb|OK| indicates that the call
        !          1366: should not block at all, e.g., a polling action); and
        !          1367: 
        !          1368: \item[\verb"td":] a pointer to an \verb"TSAPdisconnect" structure,
        !          1369: which is updated only if the call fails.
        !          1370: \end{describe}
        !          1371: 
        !          1372: This routine calls the \verb|TNetAccept| routine to wait for incoming
        !          1373: calls. It will call the procedures \verb|initfnx|, \verb|workfnx| and
        !          1374: \verb|losefnx| in an indetical way to the \verb|isodeserver|. The
        !          1375: routine returns on a number of conditions.
        !          1376: \begin{itemize}
        !          1377: \item  If one of the supplied association/file descriptors registers
        !          1378: activity the procedure returns with the mask updated.
        !          1379: 
        !          1380: \item  If an incoming association occurs. It should be accepted or
        !          1381: rejected by the \verb|initfnx| then the procedure will return.
        !          1382: 
        !          1383: \item  If some activity happens on one of the accepted calls. This is
        !          1384: handled by the \verb|workfnx| then the procedure will return.
        !          1385: 
        !          1386: \item  If the time given runs out, the procedure will return.
        !          1387: \end{itemize}
        !          1388: 
        !          1389: An outline usage of these procedures might be something like:
        !          1390: \begin{quote}\small\begin{verbatim}
        !          1391: if (iserver_init (argc, argv, aei, ros_init, td) == NOTOK)
        !          1392:     /* error */
        !          1393: for (;;) {
        !          1394:     /* set up descriptors */
        !          1395:     switch (iserver_wait (ros_init, ros_work, ros_lose, nfds,
        !          1396:                 &rfds, &wfds, NULLFD, timeout, td)) {
        !          1397:         case DONE:
        !          1398:             exit (0);
        !          1399: 
        !          1400:         case NOTOK:
        !          1401:             /* error */
        !          1402: 
        !          1403:         case OK:
        !          1404:             /* check fds for activitiy, do other things */
        !          1405: }
        !          1406: \end{verbatim}\end{quote}
        !          1407: 
        !          1408: 
        !          1409: Please note that \verb"isodeserver" and \verb|iserver_wait| implement
        !          1410: one possible discipline for association management.  Many others are
        !          1411: possible, depending on the needs of the service being provided.
        !          1412: Further, note that while the text above and the example below are
        !          1413: expressed in terms of association control (i.e., they make use of
        !          1414: \verb"AcInit" and \verb"AcAssocResponse"), this facility will provide
        !          1415: similar support at any other layer in the system (e.g.,
        !          1416: \verb"isodeserver" can be used for transport or session entities).
        !          1417: 
        !          1418: Also note that as these routines use the \verb|TNetAccept| routines,
        !          1419: child process are collected automatically. If you wish to start child
        !          1420: processes and wait for their exit status, you should take note of the
        !          1421: warnings associated with the \verb|TNetAccept| procedure (see
        !          1422: Section~\ref{tsap:accept} on page~\pageref{tsap:accept} of \voltwo/).
        !          1423: 
        !          1424: \section      {Restrictions on User Data}\label{AcSAPdata}
        !          1425: To quote the \cite{ISO.ACS.Service} specification:
        !          1426: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !          1427: \bf NOTE:&     Use of the services $\ldots$ may be subject to some
        !          1428:                constraints from (the) session services until work on
        !          1429:                providing unlimited length user data field parameters 
        !          1430:                on session primitives is completed.
        !          1431: \end{tabular}}\]
        !          1432: 
        !          1433: \section      {Error Conventions}\label{acs:errors}
        !          1434: All of the routines in this library return the manifest constant \verb"NOTOK"
        !          1435: on error,
        !          1436: and also update the \verb"aci" parameter given to the routine.
        !          1437: The \verb"aci_abort" element of the \verb"AcSAPindication" structure encodes
        !          1438: the reason for the failure.
        !          1439: One coerces the pointer to an \verb"AcSAPabort" structure,
        !          1440: and consults the \verb"aca_reason" element of this latter structure.
        !          1441: This element can be given as a parameter to the routine \verb"AcErrString"
        !          1442: which returns a null-terminated diagnostic string.
        !          1443: \begin{quote}\index{AcErrString}\small\begin{verbatim}
        !          1444: char   *AcErrString (c)
        !          1445: int     c;
        !          1446: \end{verbatim}\end{quote}
        !          1447: The \verb"" macro can be used to determine if the failure is fatal
        !          1448: (the association has been lost).
        !          1449: \begin{quote}\index{ACS\_FATAL}\small\begin{verbatim}
        !          1450: int     ACS_FATAL(r)
        !          1451: int     r;
        !          1452: \end{verbatim}\end{quote}
        !          1453: For protocol purists,
        !          1454: the \verb"ACS_OFFICIAL" macro can be used to determine if the error is an
        !          1455: ``official'' error as defined by the specification,
        !          1456: or an ``unofficial'' error used by the implementation.
        !          1457: \begin{quote}\index{ACS\_OFFICIAL}\small\begin{verbatim}
        !          1458: int     ACS_OFFICIAL (r)
        !          1459: int     r;
        !          1460: \end{verbatim}\end{quote}
        !          1461: 
        !          1462: \section      {Compiling and Loading}
        !          1463: Programs using the \man libacsap(3n) library should include
        !          1464: \verb"<isode/acsap.h>".
        !          1465: The programs should also be loaded with \verb"-lisode".
        !          1466: 
        !          1467: \section      {An Example}\label{acs:example}
        !          1468: One example of the use of the \man libacsap(3n) library is found in
        !          1469: Section~\ref{ros:example:server} on page~\pageref{ros:example:server}.
        !          1470: This example is straight-forward in presenting the interaction of association
        !          1471: control and remote operations.
        !          1472: Now let's consider how to rewrite the server to use the facilities described
        !          1473: above in Section~\ref{acs:server}.
        !          1474: Instead of using an asynchronous interface,
        !          1475: a synchronous interface will be employed.
        !          1476: Only Figure~\ref{initROSresponder} from the example in
        !          1477: Section~\ref{ros:example:server} need be changed.
        !          1478: 
        !          1479: We assume that there are three exception-logging routines:
        !          1480: {\em fatal}, which prints a diagnostic and terminates the process;
        !          1481: {\em error}, which prints a diagnostic and then executes the statement
        !          1482: \begin{quote}\small\begin{verbatim}
        !          1483: longjmp (toplevel, NOTOK);
        !          1484: \end{verbatim}\end{quote}
        !          1485: and,
        !          1486: {\em warn}, which simply prints a diagnostic.
        !          1487: 
        !          1488: In Figure~\ref{doROSserver},
        !          1489: the replacement routines are shown.
        !          1490: First, the application-entity title for the service is deteremined.
        !          1491: The routine \verb"isodeserver" is then called with its requisite arguments.
        !          1492: If the routine fails, the process terminates after printing a diagnostic.
        !          1493: Otherwise the process exits.
        !          1494: In the case where the \man tsapd(8c) daemon invokes a new instance of
        !          1495: the server each time an incoming connection is received,
        !          1496: \verb"isodeserver" will return after that assocation has been released.
        !          1497: In the case where all incoming connections are given to a single
        !          1498: instance of the server,
        !          1499: then \verb"isodeserver" returns only if a fatal error is detected.
        !          1500: 
        !          1501: The routine \verb"ros_init" is called for each incoming connection.
        !          1502: First, the ACSE state is re-captured by calling \verb"AcInit".
        !          1503: If this succeeds,
        !          1504: then any command line arguments are parsed.
        !          1505: These arguments are present only if the server was invoked by
        !          1506: the \man tsapd(8c) daemon,
        !          1507: and are specified in the \man isoservices(5) file described in
        !          1508: Chapter~\ref{isoservices} of \voltwo/.
        !          1509: Assuming that the responder is satisfied with the proposed association,
        !          1510: the routine then calls \verb"AcAssocResponse" to accept the association.
        !          1511: Then,
        !          1512: \verb"RoSetService" is called
        !          1513: to set the underlying service to be used for remote operations.
        !          1514: Finally,
        !          1515: the association-descriptor is returned to \verb"isodeserver".
        !          1516: 
        !          1517: The routine \verb"ros_work" is called when activity occurs on an association.
        !          1518: The routine sets a global return vector using \man setjmp (3)
        !          1519: and then calls \verb"RoWaitRequest" to read the next indication.
        !          1520: This usually results in the routine \verb"ros_indication"
        !          1521: (found in Figure~\ref{doROSresponder} on page~\pageref{doROSresponder})
        !          1522: being called.
        !          1523: If the association was not released,
        !          1524: then \verb"ros_work" returns \verb"OK".
        !          1525: Otherwise if some error occurred,
        !          1526: use of the routine \verb"error" will cause control to return to the
        !          1527: \verb"setjmp" call.
        !          1528: In this case,
        !          1529: \verb"AcUAbortRequest" is called to make sure that the association is
        !          1530: (ungracefully) released,
        !          1531: then \verb"NOTOK" is returned to \verb"isodeserver".
        !          1532: 
        !          1533: The routine \verb"ros_lose" simply logs the failure of \verb"TNetAccept" when
        !          1534: called from \verb"isodeserver".
        !          1535: {\let\small=\scriptsize                        %%% yikes!
        !          1536: \clearpage
        !          1537: \tagrind[tp]{grind2a-2a}{The generic ROS server}{doROSserver}
        !          1538: \clearpage
        !          1539: \tagrind[tp]{grind2a-2b}{The generic ROS server (continued)}\empty
        !          1540: \clearpage
        !          1541: \tagrind[tp]{grind2a-2c}{The generic ROS server (continued)}\empty
        !          1542: \clearpage
        !          1543: \tagrind[tp]{grind2a-2d}{The generic ROS server (continued)}\empty}
        !          1544: 
        !          1545: \section      {For Further Reading}
        !          1546: The ISO specification for association control services is defined in
        !          1547: \cite{ISO.ACS.Service}.
        !          1548: The corresponding protocol definition is \cite{ISO.ACS.Protocol}.
        !          1549: 
        !          1550: %%% \section  {Changes Since the Last Release}\label{acsap:changes}
        !          1551: %%% A brief summary of the major changes between v~\acsaprevrsn/ and
        !          1552: %%% v~\acsapvrsn/ are now presented.
        !          1553: %%% These are the user-visible changes only;
        !          1554: %%% changes of a strictly internal nature are not discussed.
        !          1555: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.