Return to ssap.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {Session Services}\label{libssap}
        !             4: The \man libssap(3n) library implements the session service.
        !             5: 
        !             6: As with most models of OSI services,
        !             7: the underlying assumption is one of a symmetric, asynchronous environment.
        !             8: That is,
        !             9: although peers exist at a given layer,
        !            10: one does not necessary view a peer as either a client or a server.
        !            11: Further,
        !            12: the service provider may generate events for the service user without the
        !            13: latter entity triggering the actions which led to the event.
        !            14: For example,
        !            15: in a synchronous environment,
        !            16: an indication that data has arrived usually occurs only when the service user
        !            17: asks the service provider to read data;
        !            18: in an asynchronous environment,
        !            19: the service provider may interrupt the service user at any time to announce
        !            20: the arrival of data.
        !            21: 
        !            22: The \verb"ssap" module in this release initially uses a client/server
        !            23: paradigm to start communications.
        !            24: Once the connection is established,
        !            25: a symmetric view is taken.
        !            26: In addition,
        !            27: initially the interface is synchronous;
        !            28: however once the connection is established,
        !            29: an asynchronous interface may be selected.
        !            30: 
        !            31: All of the routines in the \man libssap(3n) library are integer-valued.
        !            32: They return the manifest constant \verb"OK" on success,
        !            33: or \verb"NOTOK" otherwise.
        !            34: 
        !            35: \section      {Warning}
        !            36: Please read the following important message.
        !            37: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !            38: \bf NOTE:&     Readers of this chapter should have an intimate understanding
        !            39:                of the OSI session service.  It is not the intent of this
        !            40:                chapter to present a tutorial on these services, so novice
        !            41:                users will suffer greatly if they choose to read further.
        !            42: \end{tabular}}\]
        !            43: 
        !            44: \section      {Addresses}\label{ssap:addresses}
        !            45: Addresses at the session service access point are represented by the
        !            46: \verb"SSAPaddr" structure.
        !            47: \begin{quote}\index{SSAPaddr}\small\begin{verbatim}
        !            48: struct SSAPaddr {
        !            49:     struct TSAPaddr sa_addr;
        !            50: 
        !            51: #define SSSIZE  64
        !            52:     int     sa_selectlen;
        !            53:     char    sa_selector[SSSIZE];
        !            54: };
        !            55: #define NULLSA  ((struct SSAPaddr *) 0)
        !            56: \end{verbatim}\end{quote}
        !            57: This structure contains two elements:
        !            58: \begin{describe}
        !            59: \item[\verb"sa\_addr":]        the transport address,
        !            60: as described in Section~\ref{tsap:addresses} on page~\pageref{tsap:addresses};
        !            61: and,
        !            62: 
        !            63: \item[\verb"sa\_selector"/\verb"sa\_selectlen":] the session selector,
        !            64: as described in the \man isoservices(5) database in Chapter~\ref{isoservices},
        !            65: for the service provider \verb"ssap".
        !            66: \end{describe}
        !            67: 
        !            68: In Figure~\ref{getASprovider},
        !            69: an example of how one constructs the SSAP address for the Presentation provider
        !            70: on host \verb"RemoteHost" is presented.
        !            71: The routine \verb"is2saddr" takes a host and service,
        !            72: and then consults the \man isoentities(5) file described in
        !            73: Chapter~\ref{isoentities} of \volone/ to construct a session
        !            74: address.
        !            75: \begin{quote}\index{is2saddr}\small\begin{verbatim}
        !            76: struct SSAPaddr *is2saddr (host, service, is)
        !            77: char   *host,
        !            78:        *service;
        !            79: struct isoservent *is;
        !            80: \end{verbatim}\end{quote}
        !            81: \tagrind[tp]{grind5b-1}%
        !            82:        {Constructing the SSAP address for the Presentation provider}%
        !            83:        {getASprovider}
        !            84: 
        !            85: \subsection    {Calling Address}
        !            86: Certain users of the session service
        !            87: (e.g., the reliable transfer service)
        !            88: need to know the name of the local host when they initiate a connection.
        !            89: The routine \verb"SLocalHostName" has been provided for this reason.
        !            90: \begin{quote}\index{SLocalHostName}\small\begin{verbatim}
        !            91: char   *SLocalHostName ()
        !            92: \end{verbatim}\end{quote}
        !            93: 
        !            94: \subsection    {Address Encodings}
        !            95: It may be useful to encode a session address for viewing.
        !            96: Although a consensus for a standard way of doing this has not yet been
        !            97: reached,
        !            98: the routines \verb"saddr2str" and \verb"str2saddr" may be used in the interim.
        !            99: \begin{quote}\index{saddr2str}\small\begin{verbatim}
        !           100: char   *saddr2str (sa)
        !           101: struct SSAPaddr *sa;
        !           102: \end{verbatim}\end{quote}
        !           103: The parameter to this procedure is:
        !           104: \begin{describe}
        !           105: \item[\verb"sa":] the session address.
        !           106: \end{describe}
        !           107: If \verb"saddr2str" fails,
        !           108: it returns the manifest constant \verb"NULLCP".
        !           109: 
        !           110: The routine \verb"str2saddr" takes an ascii string encoding and
        !           111: returns a
        !           112: session address.
        !           113: \begin{quote}\index{str2saddr}\small\begin{verbatim}
        !           114: struct SSAPaddr *str2saddr (str)
        !           115: char   *str;
        !           116: \end{verbatim}\end{quote}
        !           117: The parameter to this procedure is:
        !           118: \begin{describe}
        !           119: \item[\verb"str":] the ascii string.
        !           120: \end{describe}
        !           121: If \verb"str2saddr" fails,
        !           122: it returns the manifest constant \verb"NULLSA".
        !           123: 
        !           124: \section      {Connection Establishment}
        !           125: Until the connection has been fully established,
        !           126: the implementation distinguishes between clients and servers,
        !           127: which are more properly referred to as {\em initiators\/} and
        !           128: {\em responders}, to use OSI terminology.
        !           129: 
        !           130: \subsection    {Connection Negotiation}\label{ssap:negotiation}
        !           131: From the user's perspective,
        !           132: there are several parameters which are negotiated by the session providers
        !           133: during connection establishment.
        !           134: Suggestions as to the values of some of these parameters are made by the user.
        !           135: 
        !           136: \subsubsection {Maximum SSDU Size}
        !           137: The session provider will accept arbitrarily large session service data units
        !           138: (SSDUs) and transparently fragment and re-assemble them during transit.
        !           139: Hence, the actual SSDU is of unlimited size.
        !           140: However, for efficiency reasons,
        !           141: it may be desirable for the user to send SSDUs which are no larger than a
        !           142: certain threshold.
        !           143: When a connection has been established,
        !           144: the service providers inform the initiator and responder as to what this
        !           145: threshold is.
        !           146: 
        !           147: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}\label{SSDU:atomic}
        !           148: \bf NOTE:&     In the current implementation,
        !           149:                SSDUs which are no larger than the maximum atomic SSDU size
        !           150:                are handled very efficiently.
        !           151:                For optimal performance,
        !           152:                users of the session service should strive to avoid sending
        !           153:                SSDUs which are larger than this threshold.
        !           154: \end{tabular}}\]
        !           155: 
        !           156: \subsubsection {Session Requirements}
        !           157: Users may specify the particular services that they will require from the
        !           158: session provider.
        !           159: The particular requirements supported in the current implementation are
        !           160: listed in Table~\ref{SSAPrequirements}.
        !           161: These requirements are always negotiated downward.
        !           162: That is,
        !           163: the initiator of the connection (i.e., the ``client'') indicates the
        !           164: desired session requirements.
        !           165: These are then given to the responder to the connection request
        !           166: (i.e., the ``server'') who may select any (or all) of the indicated session
        !           167: requirements.%
        !           168: \footnote{There is one exception,
        !           169: the responder may not select both the half- and full-duplex requirements.
        !           170: It must choose one.
        !           171: If the initiator selects both initially,
        !           172: it is indicating that the choice is made at the responder's discretion.}
        !           173: This selection is then indicated to the initiator.
        !           174: \tagtable[tp]{5b-1}{Session Requirements}{SSAPrequirements}
        !           175: 
        !           176: \subsubsection {Session Tokens}
        !           177: Depending on the session requirements selected,
        !           178: several session tokens may be available in order to coordinate the use of
        !           179: session services.
        !           180: 
        !           181: There are two terms commonly used when referring to a session token:
        !           182: \begin{itemize}
        !           183: \item  Availability\\
        !           184:        If a token is available, then it exists for use during the session
        !           185:        connection.
        !           186:        The availability of a token depends on the session requirements
        !           187:        selected for the connection.
        !           188: \item  Ownership\\
        !           189:        Certain session services are may not be requested by a user unless
        !           190:        that user owns the token associated with those services.
        !           191: \end{itemize}
        !           192: The particular tokens supported in the current implementation,
        !           193: along with their associated availability information are
        !           194: listed in Table~\ref{SSAPtokens}.
        !           195: \tagtable[tp]{5b-2}{Session Tokens}{SSAPtokens}
        !           196: 
        !           197: The session requirements are encoded as a single integer
        !           198: (actually, only the low-order 2~octets of an integer).
        !           199: To determine if a token is available,
        !           200: one can use a simple test involving the session requirements:
        !           201: \begin{quote}\small\begin{verbatim}
        !           202: if (requirements & SR_xxx_EXISTS) {
        !           203:     ...
        !           204: }
        !           205: \end{verbatim}\end{quote}
        !           206: For example,
        !           207: to determine if the negotiated release token is available:
        !           208: \begin{quote}\small\begin{verbatim}
        !           209: if (requirements & SR_RLS_EXISTS) {
        !           210:     ...
        !           211: }
        !           212: \end{verbatim}\end{quote}
        !           213: 
        !           214: Finally,
        !           215: the macro \verb"dotokens" may be used to execute {\em C\/} code for each
        !           216: session token (regardless of availability).\index{dotokens}
        !           217: This macro acts as if it executes:
        !           218: \begin{quote}\index{dotoken}\small\begin{verbatim}
        !           219: dotoken (SR_xxx_EXISTS, ST_xxx_SHIFT, ST_xxx_TOKEN, "xxx");
        !           220: \end{verbatim}\end{quote}
        !           221: for each token.
        !           222: Usually,
        !           223: \verb"dotoken" is a macro which executes some code for each token.
        !           224: An example is provided momentarily.
        !           225: 
        !           226: \subsubsection {Initial Token Settings}
        !           227: For each token which is made available during connection negotiation,
        !           228: the choice as to which user initially has the token is left to the discretion
        !           229: of the initiator.
        !           230: The three choices for the initial settings of a token are listed in
        !           231: Table~\ref{SSAPsettings}.
        !           232: \tagtable[tp]{5b-3}{Initial Token Settings}{SSAPsettings}
        !           233: 
        !           234: The initial settings for all available tokens are encoded in a single integer
        !           235: (actually, only the low-order 2~octets of an integer).
        !           236: To encode a value:
        !           237: \begin{quote}\small\begin{verbatim}
        !           238: settings &= ~(ST_MASK << ST_yyy_SHIFT);
        !           239: settings |= ST_xxx_VALUE << ST_yyy_SHIFT;
        !           240: \end{verbatim}\end{quote}
        !           241: For example,
        !           242: to indicate that the responder of the connection is to initially have the
        !           243: data token:
        !           244: \begin{quote}\small\begin{verbatim}
        !           245: settings &= ~(ST_MASK << ST_DAT_SHIFT);
        !           246: settings |= ST_RESP_VALUE << ST_DAT_SHIFT;
        !           247: \end{verbatim}\end{quote}
        !           248: The first statement,
        !           249: which clears the field in \verb"settings" by using \verb"ST_MASK",
        !           250: is not required if \verb"settings" is initially \verb"0".
        !           251: 
        !           252: If the initiator indicates that the initial setting of a token is left to
        !           253: the responder's choice,
        !           254: then the responder must decide.
        !           255: In Figure~\ref{setINITtokens},
        !           256: an example of the \verb"dotokens" macro is presented.
        !           257: In this example,
        !           258: the responder examines the initial setting for each available token,
        !           259: and:
        !           260: \begin{itemize}
        !           261: \item  Notes if the responder initially owns the token
        !           262:        (the \verb"ST_RESP_VALUE" case); or,
        !           263: \item  Gives ownership of the token to the initiator if the choice is
        !           264:        at the responder's discretion
        !           265:        (the \verb"ST_CALL_VALUE" case).
        !           266: \end{itemize}
        !           267: \tagrind[tp]{grind5b-2}{Determining the Initial Token Settings}{setINITtokens}
        !           268: 
        !           269: \subsection    {Server Initialization}
        !           270: The \man tsapd(8c) daemon,
        !           271: upon accepting a connection from an initiating host,
        !           272: consults the ISO services database to determine which program
        !           273: on the local system implements the desired TSAP entity.
        !           274: In the case of the session service,
        !           275: the \pgm{tsapd} program contains the bootstrap for the session provider.
        !           276: The daemon will again consult the ISO services database to determine which
        !           277: program on the system implements the desired SSAP entity.
        !           278: 
        !           279: Once the program has been ascertained,
        !           280: the daemon runs the program with any arguments listed in the database.
        !           281: In addition,
        !           282: it appends some {\em magic arguments\/} to the argument vector.
        !           283: Hence,
        !           284: the very first action performed by the responder is to re-capture the SSAP
        !           285: state contained in the magic arguments.
        !           286: This is done by calling the routine \verb"SInit",
        !           287: which on a successful return,
        !           288: is equivalent to a {\sf S-CONNECT.INDICATION\/} from the session service
        !           289: provider.
        !           290: \begin{quote}\index{SInit}\small\begin{verbatim}
        !           291: int     SInit (vecp, vec, ss, si)
        !           292: int     vecp;
        !           293: char  **vec;
        !           294: struct SSAPstart *ss;
        !           295: struct SSAPindication *si;
        !           296: \end{verbatim}\end{quote}
        !           297: The parameters to this procedure are:
        !           298: \begin{describe}
        !           299: \item[\verb"vecp":] the length of the argument vector;
        !           300: 
        !           301: \item[\verb"vec":] the argument vector;
        !           302: 
        !           303: \item[\verb"ss":] a pointer to a \verb"SSAPstart" structure, which is updated
        !           304: only if the call succeeds;
        !           305: and,
        !           306: 
        !           307: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !           308: updated only if the call fails.
        !           309: \end{describe}
        !           310: If \verb"SInit" is successful,
        !           311: it returns information in the \verb"ss" parameter,
        !           312: which is a pointer to a \verb"SSAPstart" structure.
        !           313: \begin{quote}\index{SSAPstart}\small\begin{verbatim}
        !           314: struct SSAPstart {
        !           315:     int     ss_sd;
        !           316: 
        !           317:     struct SSAPref  ss_connect;
        !           318: 
        !           319:     struct SSAPaddr ss_calling;
        !           320:     struct SSAPaddr ss_called;
        !           321: 
        !           322:     int     ss_requirements;
        !           323:     int     ss_settings;
        !           324:     long    ss_isn;
        !           325: 
        !           326:     int     ss_ssdusize;
        !           327: 
        !           328:     struct QOStype ss_qos;
        !           329: 
        !           330: #define SS_SIZE         512
        !           331:     int     ss_cc;
        !           332:     char    ss_data[SS_SIZE];
        !           333: };
        !           334: \end{verbatim}\end{quote}
        !           335: The elements of this structure are:
        !           336: \begin{describe}
        !           337: \item[\verb"ss\_sd":] the session-descriptor to be used to reference this
        !           338: connection;
        !           339: 
        !           340: \item[\verb"ss\_connect":] the connection identifier (a.k.a. SSAP reference)
        !           341: used by the initiator;
        !           342: 
        !           343: \item[\verb"ss\_calling":] the address of the peer initiating the connection;
        !           344: 
        !           345: \item[\verb"ss\_called":] the address of the peer being asked to respond;
        !           346: 
        !           347: \item[\verb"ss\_requirements":] the proposed session requirements;
        !           348: 
        !           349: \item[\verb"ss\_settings":] the initial token settings;
        !           350: 
        !           351: \item[\verb"ss\_isn":] the initial serial-number;
        !           352: 
        !           353: \item[\verb"ss\_ssdusize":] the largest atomic SSDU size that can be used on
        !           354: the connection (see the note on page~\pageref{SSDU:atomic});
        !           355: 
        !           356: \item[\verb"ss\_qos":] the quality of service on the connection
        !           357: (see Section~\ref{tsap:qos});
        !           358: and,
        !           359: 
        !           360: \item[\verb"ss\_data"/\verb"ss\_cc":] any initial data
        !           361: (and the length of that data).
        !           362: \end{describe}
        !           363: 
        !           364: The \verb"ss_connect" element is a \verb"SSAPref" structure,
        !           365: which is passed transparently by the session service.
        !           366: \begin{quote}\index{SSAPref}\small\begin{verbatim}
        !           367: struct SSAPref {
        !           368: #define SREF_USER_SIZE 64
        !           369:     u_char sr_ulen;
        !           370:     char    sr_udata[SREF_USER_SIZE];
        !           371: 
        !           372: #define SREF_COMM_SIZE 64
        !           373:     u_char  sr_clen;
        !           374:     char    sr_cdata[SREF_COMM_SIZE];
        !           375: 
        !           376: #define SREF_ADDT_SIZE 4
        !           377:     u_char  sr_alen;
        !           378:     char    sr_adata[SREF_ADDT_SIZE];
        !           379: 
        !           380:     u_char  sr_vlen;
        !           381:     char    sr_vdata[SREF_USER_SIZE];
        !           382: };
        !           383: \end{verbatim}\end{quote}
        !           384: The elements of this structure are:\label{SSAPref}
        !           385: \begin{describe}
        !           386: \item[\verb"sr\_udata"/\verb"sr\_ulen":] the user reference (and length of
        !           387: that reference, which may not exceed \verb"SREF_USER_SIZE" octets);
        !           388: 
        !           389: \item[\verb"sr\_cdata"/\verb"sr\_clen":] the common reference (and length of
        !           390: that reference, which may not exceed \verb"SREF_COMM_SIZE" octets);
        !           391: 
        !           392: \item[\verb"sr\_adata"/\verb"sr\_adata":] the additional reference (and length
        !           393: of that reference, which may not exceed \verb"SREF_ADDT_SIZE" octets);
        !           394: and,
        !           395: 
        !           396: \item[\verb"sr\_vdata"/\verb"sr\_vlen":] a second user reference (and length
        !           397: of that reference, which may not exceed \verb"SREF_USER_SIZE" octets),
        !           398: which is used only when starting or resuming an activity.
        !           399: \end{describe}
        !           400: 
        !           401: If the call to the \verb"SInit" routine is not successful,
        !           402: then a {\sf S-P-ABORT.IN\-DI\-CA\-TION\/} event is simulated,
        !           403: and the relevant information is returned in a \verb"SSAPindication"
        !           404: structure.\label{SSAPindication}
        !           405: \begin{quote}\index{SSAPindication}\small\begin{verbatim}
        !           406: struct SSAPindication {
        !           407:     int     si_type;
        !           408: #define SI_DATA         0x00
        !           409: #define SI_TOKEN        0x01
        !           410: #define SI_SYNC         0x02
        !           411: #define SI_ACTIVITY     0x03
        !           412: #define SI_REPORT       0x04
        !           413: #define SI_FINISH       0x05
        !           414: #define SI_ABORT        0x06
        !           415: 
        !           416:     union {
        !           417:         struct SSAPdata si_un_data;
        !           418:         struct SSAPtoken si_un_token;
        !           419:         struct SSAPsync si_un_sync;
        !           420:         struct SSAPactivity si_un_activity;
        !           421:         struct SSAPreport si_un_report;
        !           422:         struct SSAPfinish si_un_finish;
        !           423:         struct SSAPabort si_un_abort;
        !           424:     }   si_un;
        !           425: #define si_data         si_un.si_un_data
        !           426: #define si_token        si_un.si_un_token
        !           427: #define si_sync         si_un.si_un_sync
        !           428: #define si_activity     si_un.si_un_activity
        !           429: #define si_report       si_un.si_un_report
        !           430: #define si_finish       si_un.si_un_finish
        !           431: #define si_abort        si_un.si_un_abort
        !           432: };
        !           433: \end{verbatim}\end{quote}
        !           434: As shown, this structure is really a discriminated union
        !           435: (a structure with a tag element followed by a union).
        !           436: Hence, on a failure return,
        !           437: one first coerces a pointer to the \verb"SSAPabort" structure contained
        !           438: therein,
        !           439: and then consults the elements of that structure.
        !           440: \begin{quote}\index{SSAPabort}\small\begin{verbatim}
        !           441: struct SSAPabort {
        !           442:     int     sa_peer;
        !           443: 
        !           444:     int     sa_reason;
        !           445: 
        !           446: #define SA_SIZE         512
        !           447:     int     sa_cc;
        !           448:     char    sa_data[SA_SIZE];
        !           449: };
        !           450: \end{verbatim}\end{quote}
        !           451: The elements of a \verb"SSAPabort" structure are:
        !           452: \begin{describe}
        !           453: \item[\verb"sa\_peer":] if set, indicates that a user-initiated abort occurred
        !           454: (a {\sf S-U-ABORT.INDICATION\/} event);
        !           455: if not set, indicates that a provider-initiated abort occurred
        !           456: (a {\sf S-P-ABORT.INDICATION\/} event);
        !           457: 
        !           458: \item[\verb"sa\_reason":] the reason for the provider-initiated abort
        !           459: (codes are listed in Table~\ref{SSAPreasons}),
        !           460: meaningless if the abort is user-initiated;
        !           461: and,
        !           462: 
        !           463: \item[\verb"sa\_data"/\verb"sa\_cc":] any abort data (and the length of that
        !           464: data) from the peer (if \verb"sa_peer" is set) or
        !           465: a diagnostic string from the provider (if \verb"sa_peer" is not set).
        !           466: \end{describe}
        !           467: \tagtable[tp]{5b-4}{SSAP Failure Codes}{SSAPreasons}
        !           468: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !           469: \bf NOTE:&     Although both \cite{ISO.SP.Protocol} and
        !           470:                \cite{CCITT.SP.Protocol} both require a maximum length
        !           471:                of \verb"9" octets for a user-initiated abort, the
        !           472:                current implementation permits up to \verb"512" octets to
        !           473:                be used.  Without this freedom, higher-layer protocols
        !           474:                which use presentation encoding mechanisms would be unable
        !           475:                to successfully use the session abort facility.
        !           476: \end{tabular}}\]
        !           477: 
        !           478: After examining the information returned by \verb"SInit" on a successful call
        !           479: (and possibly after examining the argument vector),
        !           480: the responder should either accept or reject the connection.
        !           481: For either response,
        !           482: the responder should use
        !           483: the \verb"SConnResponse" routine
        !           484: (which corresponds to the {\sf S-CONNECT.RESPONSE\/} action).
        !           485: \begin{quote}\index{SConnResponse}\small\begin{verbatim}
        !           486: int     SConnResponse (sd, ref, called, result, requirements,
        !           487:                 settings, isn, data, cc, si)
        !           488: int     sd;
        !           489: struct SSAPref *ref;
        !           490: struct SSAPaddr *called;
        !           491: int     result,
        !           492:         requirements,
        !           493:         settings,
        !           494:         cc;
        !           495: long   isn;
        !           496: char   *data;
        !           497: struct SSAPindication *si;
        !           498: \end{verbatim}\end{quote}
        !           499: The parameters to this procedure are:
        !           500: \begin{describe}
        !           501: \item[\verb"sd":] the session-descriptor;
        !           502: 
        !           503: \item[\verb"ref":]  the connection identifier used by the responder
        !           504: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
        !           505: structure);
        !           506: 
        !           507: \item[\verb"called":] the SSAP address of the responder (defaulting to the
        !           508: called address, if not present);
        !           509: 
        !           510: \item[\verb"result":] the acceptance indicator
        !           511: (either \verb"SC_ACCEPT" if the connection is to be accepted,
        !           512: or one of the user-initiated abort error codes listed in
        !           513: Table~\ref{SSAPreasons} on page~\pageref{SSAPreasons});
        !           514: 
        !           515: \item[\verb"requirements":] the responder's session requirements
        !           516: (this may not include any requirements not listed in the initiator's session
        !           517: requirements);
        !           518: 
        !           519: \item[\verb"settings":] the initial token settings
        !           520: (for each token,
        !           521: if the initiator specified \verb"ST_CALL_VALUE",
        !           522: then the responder should specify either \verb"ST_INIT_VALUE" or
        !           523: \verb"ST_RESP_VALUE";
        !           524: instead,
        !           525: if the initiator specified \verb"ST_INIT_VALUE",
        !           526: and the responder wants the token,
        !           527: it can specify the value \verb"ST_RSVD_VALUE".
        !           528: This is interpreted by the service provider as a ``tokens please'' request;
        !           529: 
        !           530: \item[\verb"isn":] the initial serial-number;
        !           531: 
        !           532: \item[\verb"data"/\verb"cc":] any initial data (and the length of that data,
        !           533: which may not exceed \verb"SC_SIZE" octets);
        !           534: and,
        !           535: 
        !           536: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !           537: updated only if the call fails.
        !           538: \end{describe}
        !           539: If the call to \verb"SConnResponse" is successful,
        !           540: and if the \verb"result" parameter is set to \verb"SC_ACCEPT",
        !           541: then connection establishment has completed
        !           542: and the users of the session service now operate as symmetric peers.
        !           543: If the call is successful,
        !           544: but the \verb"result" parameter is not \verb"SC_ACCEPT",
        !           545: then the connection has been rejected and the responder may exit.
        !           546: Otherwise, if the call fails and the reason is not an interface error
        !           547: (see Table~\ref{SSAPreasons} on page~\pageref{SSAPreasons}),
        !           548: then the connection is closed.
        !           549: 
        !           550: Note that when the responder rejects the connection,
        !           551: it need not supply meaningful values for the the \verb"requirements",
        !           552: \verb"settings", and \verb"isn" parameters.
        !           553: The \verb"data"/\verb"cc" parameters are also optional,
        !           554: but it is recommended that the responder return some diagnostic information.
        !           555: 
        !           556: \subsection    {Client Initialization}
        !           557: A program wishing to connect to another user of session services calls the
        !           558: \verb"SConnRequest" routine,
        !           559: which corresponds to the {\sf S-CONNECT.REQUEST\/} action.
        !           560: \begin{quote}\index{SConnRequest}\small\begin{verbatim}
        !           561: int     SConnRequest (ref, calling, called, requirements,
        !           562:                 settings, isn, data, cc, qos, sc, si)
        !           563: struct SSAPref *ref;
        !           564: struct SSAPaddr *calling,
        !           565:                 *called;
        !           566: int     requirements,
        !           567:         settings,
        !           568:         cc;
        !           569: long   isn;
        !           570: char   *data;
        !           571: struct QOStype *qos;
        !           572: struct SSAPconnect *sc;
        !           573: struct SSAPindication *si;
        !           574: \end{verbatim}\end{quote}
        !           575: The parameters to this procedure are:
        !           576: \begin{describe}
        !           577: \item[\verb"ref":] the connection identifier used by the initiator
        !           578: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
        !           579: structure);
        !           580: 
        !           581: \item[\verb"calling":] the SSAP address of the responder;
        !           582: 
        !           583: \item[\verb"called":] the SSAP address of the initiator;
        !           584: 
        !           585: \item[\verb"requirements":] the session requirements;
        !           586: 
        !           587: \item[\verb"settings":] the initial token settings;
        !           588: 
        !           589: \item[\verb"isn":] the initial serial-number;
        !           590: 
        !           591: \item[\verb"data"/\verb"cc":] any initial data (and the length of that data,
        !           592: which may not exceed \verb"SS_SIZE" octets);
        !           593: 
        !           594: \item[\verb"qos":] the quality of service on the connection
        !           595: (see Section~\ref{tsap:qos});
        !           596: 
        !           597: \item[\verb"sc":] a pointer to a \verb"SSAPconnect" structure, which is
        !           598: updated only if the call succeeds;
        !           599: and,
        !           600: 
        !           601: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !           602: updated only if either:
        !           603: \begin{itemize}
        !           604: \item the call fails;
        !           605: or,
        !           606: 
        !           607: \item the call succeeds,
        !           608: but the value of the \verb"sc_result" element of the \verb"sc" parameter
        !           609: is not \verb"SC_ACCEPT" (see below).
        !           610: \end{itemize}
        !           611: \end{describe}
        !           612: If the call to \verb"SConnRequest" is successful
        !           613: (a successful return corresponds to a {\sf S-CONNECT.CONFIRMATION\/} event),
        !           614: then information is returned in the \verb"sc" parameter,
        !           615: which is a pointer to a \verb"SSAPconnect" structure.
        !           616: \begin{quote}\index{SSAPconnect}\small\begin{verbatim}
        !           617: struct SSAPconnect {
        !           618:     int     sc_sd;
        !           619: 
        !           620:     struct SSAPref  sc_connect;
        !           621:     
        !           622:     struct SSAPaddr sc_responding;
        !           623: 
        !           624:     int     sc_result;
        !           625: 
        !           626:     int     sc_requirements;
        !           627:     int     sc_settings;
        !           628:     int     sc_please;
        !           629:     lnog    sc_isn;
        !           630: 
        !           631:     int     sc_ssdusize;
        !           632: 
        !           633:     struct QOStype sc_qos;
        !           634: 
        !           635: #define SC_SIZE         512
        !           636:     int     sc_cc;
        !           637:     char    sc_data[SC_SIZE];
        !           638: };
        !           639: \end{verbatim}\end{quote}
        !           640: The elements of this structure are:
        !           641: \begin{describe}
        !           642: \item[\verb"sc\_sd":] the session-descriptor to be used to reference this
        !           643: connection;
        !           644: 
        !           645: \item[\verb"sc\_connect":] the connection identifier used by the responder
        !           646: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
        !           647: structure);
        !           648: 
        !           649: \item[\verb"sc\_responding":] the responding peer's address
        !           650: (which is the same as the \verb"called" parameter given to
        !           651: \verb"SConnRequest");
        !           652: 
        !           653: \item[\verb"sc\_result":] the connection response;
        !           654: 
        !           655: \item[\verb"sc\_requirements":] the (negotiated) session requirements;
        !           656: 
        !           657: \item[\verb"sc\_settings":] the (negotiated) initial token settings;
        !           658: 
        !           659: \item[\verb"sc\_please":] the tokens which the responder wants to own
        !           660: (if any);
        !           661: 
        !           662: \item[\verb"sc\_isn":] the (negotiated) initial serial-number;
        !           663: 
        !           664: \item[\verb"sc\_ssdusize":] the largest atomic SSDU size that can be used on
        !           665: the connection (see the note on page~\pageref{SSDU:atomic});
        !           666: 
        !           667: \item[\verb"sc\_qos":] the quality of service on the connection
        !           668: (see Section~\ref{tsap:qos});
        !           669: and,
        !           670: 
        !           671: \item[\verb"sc\_data"/\verb"sc\_cc":] any initial data (and the length of
        !           672: that data).
        !           673: \end{describe}
        !           674: If the call to \verb"SConnRequest" is successful,
        !           675: and the \verb"sc_result" element is set to \verb"SC_ACCEPT",
        !           676: then connection establishment has completed and the users of the session
        !           677: service now operate as symmetric peers.
        !           678: If the call is successful,
        !           679: but the \verb"sc_result" element is not \verb"SC_ACCEPT",
        !           680: then the connection has been rejected;
        !           681: consult Table~\ref{SSAPreasons} to determine the reason
        !           682: (further information can be found in the \verb"si" parameter).
        !           683: Otherwise, if the call fails then the connection is not established and the
        !           684: \verb"SSAPabort" structure of the \verb"SSAPindication" discriminated union
        !           685: has been updated.
        !           686: 
        !           687: Normally \verb"SConnRequest" returns only after a connection has succeeded or
        !           688: failed.
        !           689: This is termed a {\em synchronous\/} connection initiation.
        !           690: If the user desires, an {\em asynchronous\/} connection may be initiated.
        !           691: The routine \verb"SConnRequest" is really a macro which calls the routine
        !           692: \verb"SAsynConnRequest" with an argument indicating that a connection should
        !           693: be attempted synchronously.
        !           694: \begin{quote}\index{SAsynConnRequest}\small\begin{verbatim}
        !           695: int     SAsynConnRequest (ref, calling, called,
        !           696:                 requirements, settings, isn, data, cc,
        !           697:                 qos, sc, si, async)
        !           698: struct SSAPref *ref;
        !           699: struct SSAPaddr *calling,
        !           700:                 *called;
        !           701: int     requirements,
        !           702:         settings,
        !           703:         cc,
        !           704:         async;
        !           705: long   isn;
        !           706: char   *data;
        !           707: struct QOStype *qos;
        !           708: struct SSAPconnect *sc;
        !           709: struct SSAPindication *si;
        !           710: \end{verbatim}\end{quote}
        !           711: The additional parameter to this procedure is:
        !           712: \begin{describe}
        !           713: \item[\verb"async":] whether the connection should be initiated asynchronously.
        !           714: \end{describe}
        !           715: If the \verb"async" parameter is non-zero,
        !           716: then \verb"SAsynConnRequest" returns one of four values:
        !           717: \verb"NOTOK", which indicates that the connection request failed;
        !           718: \verb"DONE", which indicates that the connection request succeeded;
        !           719: or, either of \verb"CONNECTING_1" or \verb"CONNECTING_2", which indicates that
        !           720: the connection request is still in
        !           721: progress.
        !           722: In the first two cases,
        !           723: the usual procedures for handling return values from \verb"SConnRequest" are
        !           724: employed
        !           725: (i.e., a \verb"NOTOK" return from \verb"SAsynConnRequest" is equivalent to a
        !           726: \verb"NOTOK" return from \verb"SConnRequest", and,
        !           727: a \verb"DONE" return from \verb"SAsynConnRequest" is equivalent to a
        !           728: \verb"OK" return from \verb"SConnRequest").
        !           729: In the final case, when either \verb"CONNECTING_1" or
        !           730: \verb"CONNECTING_2" is returned,
        !           731: only the \verb"sc_sd" element of the \verb"sc" parameter has been updated;
        !           732: it reflects the session-descriptor to be used to reference this connection.
        !           733: Note that the \verb"data" parameter is still being referenced by
        !           734: \man libssap(3n) and should not be tampered with until the connection attempt
        !           735: has been completed.
        !           736: 
        !           737: To determine when the connection attempt has been completed,
        !           738: the routine \verb"xselect" (consult Section~\ref{acs:select} of \volone/)
        !           739: should be used after calling \verb"SSelectMask".
        !           740: In order to determine if the connection attempt is successful,
        !           741: the \verb"SAsynRetryRequest" routine is called:
        !           742: \begin{quote}\index{SAsynRetryRequest}\small\begin{verbatim}
        !           743: int     SAsynRetryRequest (sd, sc, si)
        !           744: int     sd;
        !           745: struct SSAPconnect *sc;
        !           746: struct SSAPindication  *si;
        !           747: \end{verbatim}\end{quote}
        !           748: The parameters to this procedure are:
        !           749: \begin{describe}
        !           750: \item[\verb"sd":] the session-descriptor;
        !           751: 
        !           752: \item[\verb"sc":] a pointer to a \verb"SSAPconnect" structure, which is
        !           753: updated only if the call succeeds;
        !           754: and,
        !           755: 
        !           756: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !           757: updated only if the call fails.
        !           758: \end{describe}
        !           759: Again, one of three values are returned:
        !           760: \verb"NOTOK", which indicates that the connection request failed;
        !           761: \verb"DONE", which indicates that the connection request succeeded;
        !           762: and, \verb"CONNECTING_1" or \verb"CONNECTING_2" which indicates that
        !           763: the connection request is still in progress.
        !           764: 
        !           765: Refer to Section~\ref{tsap:async} on page~\pageref{tsap:async} for information
        !           766: on how to make efficient use of the asynchronous connection facility.
        !           767: 
        !           768: \section      {Data Transfer}
        !           769: Once the connection has been established,
        !           770: a session-descriptor is used to reference the connection.
        !           771: This is usually the first parameter given to any of the remaining routines in
        !           772: the \man libssap(3n) library.
        !           773: Further,
        !           774: the last parameter is usually a pointer to a \verb"SSAPindication" structure
        !           775: (as described on page~\pageref{SSAPindication}).
        !           776: If a call to one of these routines fails,
        !           777: then the structure is updated.
        !           778: Consult the \verb"SSAPabort" element of the \verb"SSAPindication" structure.
        !           779: If the \verb"sa_reason" element of the \verb"SSAPabort" structure is
        !           780: associated with a fatal error,
        !           781: then the connection is closed.
        !           782: That is, a {\sf S-P-ABORT.INDICATION\/} event has occurred.
        !           783: The \verb"SC_FATAL" macro can be used to determine this.
        !           784: \begin{quote}\index{SC\_FATAL}\small\begin{verbatim}
        !           785: int     SC_FATAL (r)
        !           786: int     r;
        !           787: \end{verbatim}\end{quote}
        !           788: The most common interface error to occur is \verb"SC_OPERATION" which usually
        !           789: indicates that either the user is lacking ownership of a session token
        !           790: to perform an operation,
        !           791: or that a session requirement required by the operation was not negotiated
        !           792: during connection establishment.
        !           793: For protocol purists,
        !           794: the \verb"SC_OFFICIAL" macro can be used to determine if the error is an
        !           795: ``official'' error as defined by the specification,
        !           796: or an ``unofficial'' error used by the implementation.
        !           797: \begin{quote}\index{SC\_OFFICIAL}\small\begin{verbatim}
        !           798: int     SC_OFFICIAL (r)
        !           799: int     r;
        !           800: \end{verbatim}\end{quote}
        !           801: 
        !           802: \subsection    {Sending Data}
        !           803: There are six routines which may be used to send data.
        !           804: A call to the \verb"SDataRequest" routine is equivalent to a
        !           805: {\sf S-DATA.REQUEST\/} action on the part of the user.
        !           806: \begin{quote}\index{SDataRequest}\small\begin{verbatim}
        !           807: int     SDataRequest (sd, data, cc, si)
        !           808: int     sd;
        !           809: char   *data;
        !           810: int     cc;
        !           811: struct SSAPindication  *si;
        !           812: \end{verbatim}\end{quote}
        !           813: The parameters to this procedure are:
        !           814: \begin{describe}
        !           815: \item[\verb"sd":] the session-descriptor;
        !           816: 
        !           817: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
        !           818: data);
        !           819: and,
        !           820: 
        !           821: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           822: only if the call fails.
        !           823: \end{describe}
        !           824: If the call to \verb"SDataRequest" is successful,
        !           825: then the data has been queued for sending to the peer.
        !           826: Otherwise the \verb"SSAPabort" structure contained in
        !           827: the \verb"SSAPindication" parameter
        !           828: \verb"si" contains the reason for failure.
        !           829: 
        !           830: A call to the \verb"SExpdRequest" routine is equivalent to a
        !           831: {\sf S-EXPEDITED-DATA.REQUEST\/} action on the part of the user.
        !           832: \begin{quote}\index{SExpdRequest}\small\begin{verbatim}
        !           833: int     SExpdRequest (sd, data, cc, si)
        !           834: int     sd;
        !           835: char   *data;
        !           836: int     cc;
        !           837: struct SSAPindication  *si;
        !           838: \end{verbatim}\end{quote}
        !           839: The parameters to this procedure are:
        !           840: \begin{describe}
        !           841: \item[\verb"sd":] the session-descriptor;
        !           842: 
        !           843: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
        !           844: data, which may not exceed \verb"SX_SIZE" octets);
        !           845: and,
        !           846: 
        !           847: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           848: only if the call fails.
        !           849: \end{describe}
        !           850: If the call to \verb"SExpdRequest" is successful,
        !           851: then the data has been queued for expedited sending.
        !           852: Otherwise the \verb"SSAPabort" element of the \verb"si" parameter
        !           853: contains the reason for failure.
        !           854: 
        !           855: A call to the \verb"STypedRequest" routine is equivalent to a
        !           856: {\sf S-TYP\-ED-DA\-TA.RE\-QUEST\/} action on the part of the user.
        !           857: \begin{quote}\index{STypedRequest}\small\begin{verbatim}
        !           858: int     STypedRequest (sd, data, cc, si)
        !           859: int     sd;
        !           860: char   *data;
        !           861: int     cc;
        !           862: struct SSAPindication  *si;
        !           863: \end{verbatim}\end{quote}
        !           864: The parameters to this procedure are:
        !           865: \begin{describe}
        !           866: \item[\verb"sd":] the session-descriptor;
        !           867: 
        !           868: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
        !           869: data);
        !           870: and,
        !           871: 
        !           872: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           873: only if the call fails.
        !           874: \end{describe}
        !           875: If  the call to \verb"STypedRequest" is successful,
        !           876: then the data has been queued for sending to the peer.
        !           877: Otherwise the \verb"SSAPabort" structure contained in
        !           878: the \verb"SSAPindication" parameter
        !           879: \verb"si" contains the reason for failure.
        !           880: 
        !           881: A call to the \verb"SCapdRequest" routine is equivalent to a {\sf
        !           882: S-CAPABILITY-DATA.REQUEST\/} action on the part of the user.
        !           883: \begin{quote}\index{SCapdRequest}\small\begin{verbatim}
        !           884: int     SCapdRequest (sd, data, cc, si)
        !           885: int     sd;
        !           886: char   *data;
        !           887: int     cc;
        !           888: struct SSAPindication  *si;
        !           889: \end{verbatim}\end{quote}
        !           890: The parameters to this procedure are:
        !           891: \begin{describe}
        !           892: \item[\verb"sd":] the session-descriptor;
        !           893: 
        !           894: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
        !           895: data, which may not exceed \verb"SX_CDSIZE" octets);
        !           896: and,
        !           897: 
        !           898: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           899: only if the call fails.
        !           900: \end{describe}
        !           901: If the call to \verb"SCapdRequest" is successful,
        !           902: then the data has been queued for sending.
        !           903: When the {\sf S-CAPABILITY-DATA.CONFIRMATION\/} event is received,
        !           904: the data has been successfully received.
        !           905: Otherwise the \verb"SSAPabort" structure contained in
        !           906: the \verb"SSAPindication" parameter
        !           907: \verb"si" contains the reason for failure.
        !           908: 
        !           909: Upon receiving a {\sf S-CAPABILITY-DATA.INDICATION\/} event,
        !           910: the user is required to generate a {\sf S-CAPABILITY-DATA.RESPONSE\/} action
        !           911: using the \verb"SCapdResponse" routine.
        !           912: \begin{quote}\index{SCapdResponse}\small\begin{verbatim}
        !           913: int     SCapdResponse (sd, data, cc, si)
        !           914: int     sd;
        !           915: char   *data;
        !           916: int     cc;
        !           917: struct SSAPindication  *si;
        !           918: \end{verbatim}\end{quote}
        !           919: The parameters to this procedure are:
        !           920: \begin{describe}
        !           921: \item[\verb"sd":] the session-descriptor;
        !           922: 
        !           923: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
        !           924: data, which may not exceed \verb"SX_CDASIZE" octets);
        !           925: and,
        !           926: 
        !           927: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           928: only if the call fails.
        !           929: \end{describe}
        !           930: If  the call to \verb"SCapdResponse" is successful,
        !           931: then the data has been queued for sending to the peer.
        !           932: Otherwise the \verb"SSAPabort" structure contained in
        !           933: the \verb"SSAPindication" parameter
        !           934: \verb"si" contains the reason for failure.
        !           935: 
        !           936: The \verb"SWriteRequest" routine is similar in nature to the
        !           937: \verb"SDataRequest" and \verb"STypedRequest" routines,
        !           938: but uses a different set of parameters.
        !           939: The invocation is:
        !           940: \begin{quote}\index{SWriteRequest}\small\begin{verbatim}
        !           941: int     SWriteRequest (sd, typed, uv, si)
        !           942: int     sd;
        !           943: int     typed;
        !           944: struct udvec *uv;
        !           945: int     cc;
        !           946: \end{verbatim}\end{quote}
        !           947: The parameters to this procedure are:
        !           948: \begin{describe}
        !           949: \item[\verb"sd":] the session-descriptor;
        !           950: 
        !           951: \item[\verb"typed":] whether this is typed-data or not;
        !           952: 
        !           953: \item[\verb"uv":] the data to be written,
        !           954: described in a null-terimated array of scatter/gather elements;
        !           955: and,
        !           956: 
        !           957: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           958: only if the call fails.
        !           959: \end{describe}
        !           960: If the call to \verb"SWriteRequest" is successful,
        !           961: then the data has been queued for sending to the peer.
        !           962: Otherwise the \verb"SSAPabort" structure contained in
        !           963: the \verb"SSAPindication" parameter
        !           964: \verb"si" contains the reason for failure.
        !           965: 
        !           966: \subsection    {Receiving Data}
        !           967: There is one routine used to read data,
        !           968: \verb"SReadRequest",
        !           969: a call to which is equivalent to waiting for an event
        !           970: (usually an incoming data event) to occur.
        !           971: \begin{quote}\index{SReadRequest}\small\begin{verbatim}
        !           972: int     SReadRequest (sd, sx, secs, si)
        !           973: int     sd;
        !           974: struct SSAPdata *sx;
        !           975: int     secs;
        !           976: struct SSAPindication  *si;
        !           977: \end{verbatim}\end{quote}
        !           978: The parameters to this procedure are:
        !           979: \begin{describe}
        !           980: \item[\verb"sd":] the session-descriptor;
        !           981: 
        !           982: \item[\verb"sx":] a pointer to the \verb"SSAPdata" structure to be given
        !           983: the data;
        !           984: 
        !           985: \item[\verb"secs":] the maximum number of seconds to wait for the data
        !           986: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
        !           987: whereas a value of \verb"OK" indicates that the call should not block at all,
        !           988: e.g., a polling action);
        !           989: and,
        !           990: 
        !           991: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !           992: only if data is not read.
        !           993: \end{describe}
        !           994: Unlike the other routines in the \man libssap(3n) library,
        !           995: the \verb"SReadRequest" routine returns one of three values:
        !           996: \verb"NOTOK" (on failure),
        !           997: \verb"OK" (on reading data),
        !           998: or
        !           999: \verb"DONE" (otherwise).
        !          1000: 
        !          1001: If the call to \verb"SReadRequest" returns the manifest constant \verb"OK",
        !          1002: then the data has been read into the \verb"sx" parameter,
        !          1003: which is a pointer to a \verb"SSAPdata" structure.
        !          1004: \begin{quote}\index{SSAPdata}\small\begin{verbatim}
        !          1005: struct SSAPdata {
        !          1006:     int     sx_type;
        !          1007: #define SX_NORMAL       0x00
        !          1008: #define SX_EXPEDITED    0x01
        !          1009: #define SX_TYPED        0x02
        !          1010: #define SX_CAPDIND      0x03
        !          1011: #define SX_CAPDCNF      0x04
        !          1012: 
        !          1013:     int     sx_cc;
        !          1014:     struct qbuf sx_qbuf;
        !          1015: };
        !          1016: \end{verbatim}\end{quote}
        !          1017: The elements of a \verb"SSAPdata" structure are:
        !          1018: \begin{describe}
        !          1019: \item[\verb"sx\_type":] indicates how the data was received:
        !          1020: \[\begin{tabular}{|l|l|}
        !          1021: \hline
        !          1022:     \multicolumn{1}{|c|}{\bf Value}&
        !          1023:                \multicolumn{1}{c|}{\bf Event}\\
        !          1024: \hline
        !          1025:     \tt SX\_NORMAL&    \sf S-DATA.INDICATION\\
        !          1026:     \tt SX\_EXPEDITED& \sf S-EXPEDITED-DATA.INDICATION\\
        !          1027:     \tt SX\_TYPED&     \sf S-TYPED-DATA.INDICATION\\
        !          1028:     \tt SX\_CAPDIND&   \sf S-CAPABILITY-DATA.INDICATION\\
        !          1029:     \tt SX\_CAPDCNF&   \sf S-CAPABILITY-DATA.CONFIRMATION\\
        !          1030: \hline
        !          1031: \end{tabular}\]
        !          1032: 
        !          1033: \item[\verb"sx\_cc":] the total number of octets that was read;
        !          1034: and,
        !          1035: 
        !          1036: \item[\verb"sx\_qbuf":] the data that was read in a buffer-queue form
        !          1037: (see page~\pageref{tsap:qbuf} for a description of this structure).
        !          1038: \end{describe}
        !          1039: Note that the data contained in the structure was allocated via \man malloc(3),
        !          1040: and should be released by using the \verb"SXFREE" macro when no longer
        !          1041: referenced.
        !          1042: The \verb"SXFREE" macro,
        !          1043: behaves as if it was defined as:\label{SXFREE}
        !          1044: \begin{quote}\index{SXFREE}\small\begin{verbatim}
        !          1045: void    SXFREE (sx)
        !          1046: struct SSAPdata *sx;
        !          1047: \end{verbatim}\end{quote}
        !          1048: The macro frees only the data allocated by \verb"SReadRequest",
        !          1049: and not the \verb"SSAPdata" structure itself.
        !          1050: Further,
        !          1051: \verb"SXFREE" should be called only if the call to the \verb"SReadRequest"
        !          1052: routine returned \verb"OK".
        !          1053: 
        !          1054: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !          1055: \bf NOTE:&     Because the \verb"SSAPdata" structure contains a
        !          1056:                \verb"qbuf" element, care must be taken in initializing
        !          1057:                and copying variables of this type.
        !          1058:                The routines in \man libssap(3n) library will correctly
        !          1059:                initialize these structures when given as parameters.
        !          1060:                But, users who otherwise manipulate these structures 
        !          1061:                should take great care.
        !          1062: \end{tabular}}\]
        !          1063: 
        !          1064: Otherwise if the call to \verb"SReadRequest" returns the manifest constant
        !          1065: \verb"NOTOK",
        !          1066: then the \verb"SSAPabort" structure contained in
        !          1067: the \verb"SSAPindication" parameter
        !          1068: \verb"si" contains the reason for failure.
        !          1069: 
        !          1070: If the call to \verb"SReadRequest" returns the manifest constant \verb"DONE",
        !          1071: then some event other than data arrival has occurred.
        !          1072: This event is encoded in the \verb"si" parameter,
        !          1073: depending on the value of the \verb"si_type" element.
        !          1074: When \verb"SReadRequest" returns \verb"DONE",
        !          1075: the \verb"si_type" element may be set to one of five values:
        !          1076: \[\begin{tabular}{|l|l|}
        !          1077: \hline
        !          1078:     \multicolumn{1}{|c|}{\bf Value}&
        !          1079:                        \multicolumn{1}{c|}{\bf Event}\\
        !          1080: \hline
        !          1081:     \tt SI\_TOKEN&     Token management\\
        !          1082:     \tt SI\_SYNC&      Synchronization management\\
        !          1083:     \tt SI\_ACTIVITY&  Activity management\\
        !          1084:     \tt SI\_REPORT&    Exception reporting\\
        !          1085:     \tt SI\_FINISH&    Connection release\\
        !          1086: \hline
        !          1087: \end{tabular}\]
        !          1088: 
        !          1089: \subsubsection {Token Indications}
        !          1090: When an event associated with token management occurs,
        !          1091: the \verb"si_type" field of the \verb"si" parameter contains the value
        !          1092: \verb"SI_TOKEN",
        !          1093: and a \verb"SSAPtoken" structure is contained inside the \verb"si" parameter.
        !          1094: \begin{quote}\index{SSAPtoken}\small\begin{verbatim}
        !          1095: struct SSAPtoken {
        !          1096:     int     st_type;
        !          1097: #define ST_GIVE         0x00
        !          1098: #define ST_PLEASE       0x01
        !          1099: #define ST_CONTROL      0x02
        !          1100: 
        !          1101:     u_char  st_tokens;
        !          1102:     u_char  st_owned;
        !          1103: 
        !          1104: #define ST_SIZE         512
        !          1105:     int     st_cc;
        !          1106:     char    st_data[ST_SIZE];
        !          1107: };
        !          1108: \end{verbatim}\end{quote}
        !          1109: The elements of a \verb"SSAPtoken" structure are:
        !          1110: \begin{describe}
        !          1111: \item[\verb"st\_type":] defines the token management indication which
        !          1112: occurred:
        !          1113: \[\begin{tabular}{|l|l|}
        !          1114: \hline
        !          1115:     \multicolumn{1}{|c|}{\bf Value}&
        !          1116:                \multicolumn{1}{c|}{\bf Event}\\
        !          1117: \hline
        !          1118:     \tt ST\_GIVE&      \sf S-TOKEN-GIVE.INDICATION\\
        !          1119:     \tt ST\_PLEASE&    \sf S-TOKEN-PLEASE.INDICATION\\
        !          1120:     \tt ST\_CONTROL&   \sf S-GIVE-CONTROL.INDICATION\\
        !          1121: \hline
        !          1122: \end{tabular}\]
        !          1123: 
        !          1124: \item[\verb"st\_tokens":] the session tokens requested or given;
        !          1125: 
        !          1126: \item[\verb"st\_owned":] all of the session tokens currently owned by the
        !          1127: user;
        !          1128: and,
        !          1129: 
        !          1130: \item[\verb"st\_base"/\verb"st\_cc":]
        !          1131: associated data (and the length of that data) if tokens are requested.
        !          1132: \end{describe}
        !          1133: It is entirely at the discretion of the user what actions are to be taken when
        !          1134: an indication event associated with token management occurs.
        !          1135: 
        !          1136: \subsubsection {Synchronization Indications}
        !          1137: When an event associated with synchronization occurs,
        !          1138: the \verb"si_type" field of the \verb"si" parameter contains the value
        !          1139: \verb"SI_SYNC",
        !          1140: and a \verb"SSAPsync" structure is contained inside the \verb"si" parameter.
        !          1141: \begin{quote}\index{SSAPsync}\small\begin{verbatim}
        !          1142: struct SSAPsync {
        !          1143:     int     sn_type;
        !          1144: #define SN_MAJORIND     0x00
        !          1145: #define SN_MAJORCNF     0x01
        !          1146: #define SN_MINORIND     0x02
        !          1147: #define SN_MINORCNF     0x03
        !          1148: #define SN_RESETIND     0x04
        !          1149: #define SN_RESETCNF     0x05
        !          1150: 
        !          1151:     int     sn_options;
        !          1152: #define SYNC_CONFIRM    1
        !          1153: #define SYNC_NOCONFIRM  0
        !          1154: 
        !          1155: #define SYNC_RESTART    0
        !          1156: #define SYNC_ABANDON    1
        !          1157: #define SYNC_SET        2
        !          1158: 
        !          1159:     long    sn_ssn;
        !          1160: #define SERIAL_NONE     (-1L)
        !          1161: #define SERIAL_MIN      000000L
        !          1162: #define SERIAL_MAX      999998L
        !          1163: 
        !          1164:     int     sn_settings;
        !          1165: 
        !          1166: #define SN_SIZE         512
        !          1167:     int     sn_cc;
        !          1168:     char    sn_data[SN_SIZE];
        !          1169: };
        !          1170: \end{verbatim}\end{quote}
        !          1171: The elements of a \verb"SSAPsync" structure are:
        !          1172: \begin{describe}
        !          1173: \item[\verb"sn\_type":] defines the synchronization management indication
        !          1174: which occurred:
        !          1175: \[\begin{tabular}{|l|l|}
        !          1176: \hline
        !          1177:     \multicolumn{1}{|c|}{\bf Value}&
        !          1178:                \multicolumn{1}{c|}{\bf Event}\\
        !          1179: \hline
        !          1180:        \tt SN\_MAJORIND&       \sf S-MAJOR-SYNC.INDICATION\\
        !          1181:        \tt SN\_MAJORCNF&       \sf S-MAJOR-SYNC.CONFIRMATION\\
        !          1182:        \tt SN\_MINORIND&       \sf S-MINOR-SYNC.INDICATION\\
        !          1183:        \tt SN\_MINORCNF&       \sf S-MINOR-SYNC.CONFIRMATION\\
        !          1184:        \tt SN\_RESETIND&       \sf S-RESYNCHRONIZE.INDICATION\\
        !          1185:        \tt SN\_RESETCNF&       \sf S-RESYNCHRONIZE.CONFIRMATION\\
        !          1186: \hline
        !          1187: \end{tabular}\]
        !          1188: 
        !          1189: \item[\verb"sn\_options":] various modifiers of the indication.
        !          1190: For the minorsync indication (as described in Section~\ref{sync:mgmt}
        !          1191: on page~\pageref{sync:mgmt}):
        !          1192: \[\begin{tabular}{|l|l|}
        !          1193: \hline
        !          1194:     \multicolumn{1}{|c|}{\bf Value}&
        !          1195:                \multicolumn{1}{c|}{\bf Modifier}\\
        !          1196: \hline
        !          1197:     \tt SYNC\_CONFIRM&         peer wants explicit confirmation\\
        !          1198:     \tt SYNC\_NOCONFIRM&       peer doesn't want explicit confirmation\\
        !          1199: \hline
        !          1200: \end{tabular}\]
        !          1201: For the resync indication (also described in Section~\ref{sync:mgmt}):
        !          1202: \[\begin{tabular}{|l|l|}
        !          1203: \hline
        !          1204:     \multicolumn{1}{|c|}{\bf Value}&
        !          1205:                \multicolumn{1}{c|}{\bf Modifier}\\
        !          1206: \hline
        !          1207:     \tt SYNC\_RESTART& a ``restart'' resynchronization is requested\\
        !          1208:     \tt SYNC\_ABANDON& a ``abandon'' resynchronization is requested\\
        !          1209:     \tt SYNC\_SET&     a ``set'' resynchronization is requested\\
        !          1210: \hline
        !          1211: \end{tabular}\]
        !          1212: 
        !          1213: \item[\verb"sn\_ssn":] the serial-number associated with this synchronization
        !          1214: management event;
        !          1215: 
        !          1216: \item[\verb"sn\_settings":] for resync events,
        !          1217: the proposed (resync indication) or new (resync confirmation) token settings;
        !          1218: and,
        !          1219: 
        !          1220: \item[\verb"sn\_data"/\verb"sn\_cc":] associated data
        !          1221: (and the length of that data).
        !          1222: \end{describe}
        !          1223: Note that for minorsync events,
        !          1224: the user is not obligated to confirm the synchronization point
        !          1225: even if the originator requested it.
        !          1226: 
        !          1227: \subsubsection {Activity Indications}
        !          1228: When an event associated with activity management occurs,
        !          1229: the \verb"si_type" field of the \verb"si" parameter contains the value
        !          1230: \verb"SI_ACTIVITY",
        !          1231: and the \verb"si" parameter contains a \verb"SSAPactivity" structure.
        !          1232: \begin{quote}\index{SSAPactivity}\small\begin{verbatim}
        !          1233: struct SSAPactivity {
        !          1234:     int     sv_type;
        !          1235: #define SV_START        0x00
        !          1236: #define SV_RESUME       0x01
        !          1237: #define SV_INTRIND      0x02
        !          1238: #define SV_INTRCNF      0x03
        !          1239: #define SV_DISCIND      0x04
        !          1240: #define SV_DISCCNF      0x05
        !          1241: #define SV_ENDIND       0x06
        !          1242: #define SV_ENDCNF       0x07
        !          1243: 
        !          1244:     struct SSAPactid sv_id;
        !          1245: 
        !          1246:     struct SSAPactid sv_oid;
        !          1247:     struct SSAPref   sv_connect;
        !          1248: 
        !          1249:     long    sv_ssn;
        !          1250: 
        !          1251:     int     sv_reason;
        !          1252: 
        !          1253: #define SV_SIZE         512
        !          1254:     int     sv_cc;
        !          1255:     char    sv_data[SV_SIZE];
        !          1256: };
        !          1257: \end{verbatim}\end{quote}
        !          1258: The elements of a \verb"SSAPactivity" structure are:
        !          1259: \begin{describe}
        !          1260: \item[\verb"sv\_type":] defines the activity management indication which
        !          1261: occurred:
        !          1262: \[\begin{tabular}{|l|l|}
        !          1263: \hline
        !          1264:     \multicolumn{1}{|c|}{\bf Value}&
        !          1265:                \multicolumn{1}{c|}{\bf Event}\\
        !          1266: \hline
        !          1267:        \tt SV\_START&          \sf S-ACTIVITY-START.INDICATION\\
        !          1268:        \tt SV\_RESUME&         \sf S-ACTIVITY-RESUME.INDICATION\\
        !          1269:        \tt SV\_INTRIND&        \sf S-ACTIVITY-INTERRUPT.INDICATION\\
        !          1270:        \tt SV\_INTRCNF&        \sf S-ACTIVITY-INTERRUPT.CONFIRMATION\\
        !          1271:        \tt SV\_DISCIND&        \sf S-ACTIVITY-DISCARD.INDICATION\\
        !          1272:        \tt SV\_DISCCNF&        \sf S-ACTIVITY-DISCARD.CONFIRMATION\\
        !          1273:        \tt SV\_ENDIND&         \sf S-ACTIVITY-END.INDICATION\\
        !          1274:        \tt SV\_ENDCNF&         \sf S-ACTIVITY-END.CONFIRMATION\\
        !          1275: \hline
        !          1276: \end{tabular}\]
        !          1277: 
        !          1278: \item[\verb"sv\_id":] the activity identifier for an activity start
        !          1279: or resume indication;
        !          1280: 
        !          1281: \item[\verb"sv\_oid":] the previous activity identifier for an activity resume
        !          1282: indication (see page~\pageref{SSAPactref});
        !          1283: 
        !          1284: \item[\verb"sv\_connect":] the previous connection identifier for an activity
        !          1285: resume indication;
        !          1286: 
        !          1287: \item[\verb"sv\_ssn":] the serial-number for an activity resume or end
        !          1288: indication;
        !          1289: 
        !          1290: \item[\verb"sv\_reason":] the reason for an activity interrupt or discard
        !          1291: indication (codes are listed in Table~\ref{SSAPexceptions});
        !          1292: and,
        !          1293: 
        !          1294: \item[\verb"sv\_data"/\verb"sv\_cc":] associated data (and the length of that
        !          1295: data).
        !          1296: \end{describe}
        !          1297: \tagtable[tp]{5b-5}{SSAP Exception Codes}{SSAPexceptions}
        !          1298: 
        !          1299: \subsubsection {Report Indications}
        !          1300: When an event associated with exception reporting occurs,
        !          1301: the \verb"si_type" field of the \verb"si" parameter contains the value
        !          1302: \verb"SI_REPORT",
        !          1303: and a \verb"SSAPreport" structure is contained inside the \verb"si"
        !          1304: parameter.
        !          1305: \begin{quote}\index{SSAPreport}\small\begin{verbatim}
        !          1306: struct SSAPreport {
        !          1307:     int     sp_peer;
        !          1308: 
        !          1309:     int     sp_reason;
        !          1310: 
        !          1311: #define SP_SIZE         512
        !          1312:     int     sp_cc;
        !          1313:     char    sp_data[SP_SIZE];
        !          1314: };
        !          1315: \end{verbatim}\end{quote}
        !          1316: The elements of a \verb"SSAPreport" structure are:
        !          1317: \begin{describe}
        !          1318: \item[\verb"sp\_peer":] if set, indicates that a user-initiated
        !          1319: report occurred (a {\sf S-U-EXCEPTION-REPORT.INDICATION\/} event);
        !          1320: if not set,
        !          1321: indicates that a provider-initiated report occurred
        !          1322: (a {\sf S-P-EXCEPTION-REPORT.INDICATION\/} event);
        !          1323: 
        !          1324: \item[\verb"sp\_reason":] the reason for the report
        !          1325: (codes are listed in Table~\ref{SSAPexceptions} on
        !          1326: page~\pageref{SSAPexceptions});
        !          1327: and,
        !          1328: 
        !          1329: \item[\verb"sp\_data"/\verb"sp\_cc":] any report data
        !          1330: (and the length of that data) from the peer;
        !          1331: meaningless if the report is provider-initiated.
        !          1332: \end{describe}
        !          1333: 
        !          1334: \subsubsection {Finish Indication}
        !          1335: When a {\sf S-RELEASE.INDICATION\/} event occurs,
        !          1336: the \verb"si_type" field of the \verb"si" parameter contains the value
        !          1337: \verb"SI_FINISH",
        !          1338: and a \verb"SSAPfinish" structure is contained inside the \verb"si" parameter.
        !          1339: \begin{quote}\index{SSAPfinish}\small\begin{verbatim}
        !          1340: struct SSAPfinish {
        !          1341: #define SF_SIZE         512
        !          1342:     int     sf_cc;
        !          1343:     char    sf_data[SF_SIZE];
        !          1344: };
        !          1345: \end{verbatim}\end{quote}
        !          1346: The elements of a \verb"SSAPfinish" structure are:
        !          1347: \begin{describe}
        !          1348: \item[\verb"sf\_data"/\verb"sf\_cc":] any final data (and the length of that
        !          1349: data).
        !          1350: \end{describe}
        !          1351: 
        !          1352: \subsection    {Token Management}
        !          1353: The fundamental aspect of token management deals with transferring ownership
        !          1354: of the tokens.
        !          1355: 
        !          1356: \subsubsection {Sending Tokens}
        !          1357: To transfer ownership of one or more session tokens to the remote
        !          1358: user,
        !          1359: the \verb"SGTokenRequest" routine is called
        !          1360: (which corresponds to the {\sf S-TOKEN-GIVE.REQUEST\/} action).
        !          1361: \begin{quote}\index{SGTokenRequest}\small\begin{verbatim}
        !          1362: int     SGTokenRequest (sd, tokens, si)
        !          1363: int     sd;
        !          1364: int     tokens;
        !          1365: struct SSAPindication  *si;
        !          1366: \end{verbatim}\end{quote}
        !          1367: The parameters to this procedure are:
        !          1368: \begin{describe}
        !          1369: \item[\verb"sd":] the session-descriptor;
        !          1370: 
        !          1371: \item[\verb"tokens":] the tokens to be transferred;
        !          1372: and,
        !          1373: 
        !          1374: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1375: updated only if the call fails.
        !          1376: \end{describe}
        !          1377: If the call to \verb"SGTokenRequest" is successful,
        !          1378: then ownership of the tokens has been transferred to the remote user.
        !          1379: 
        !          1380: If activity management has been selected,
        !          1381: then the ownership of all tokens can be transferred using the
        !          1382: \verb"SGControlRequest" routine
        !          1383: (which corresponds to the {\sf S-CONTROL-GIVE.REQUEST\/} action).
        !          1384: \begin{quote}\index{SGControlRequest}\small\begin{verbatim}
        !          1385: int     SGControlRequest (sd, si)
        !          1386: int     sd;
        !          1387: struct SSAPindication  *si;
        !          1388: \end{verbatim}\end{quote}
        !          1389: The parameters to this procedure are:
        !          1390: \begin{describe}
        !          1391: \item[\verb"sd":] the session-descriptor;
        !          1392: and,
        !          1393: 
        !          1394: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1395: updated only if the call fails.
        !          1396: \end{describe}
        !          1397: If the call to \verb"SGControlRequest" is successful,
        !          1398: then ownership of all available tokens has been transferred to the remote user.
        !          1399: Until this transfer of ownership is acknowledged,
        !          1400: other token management functions will (non-fatally) fail.
        !          1401: 
        !          1402: \subsubsection {Requesting Tokens}
        !          1403: To request ownership of one or more session tokens,
        !          1404: the \verb"SPTokenRequest" routine is called
        !          1405: (which corresponds to the {\sf S-TOKEN-PLEASE.REQUEST\/} action).
        !          1406: \begin{quote}\index{SPTokenRequest}\small\begin{verbatim}
        !          1407: int     SPTokenRequest (sd, tokens, data, cc, si)
        !          1408: int     sd;
        !          1409: int     tokens,
        !          1410:         cc;
        !          1411: char   *data;
        !          1412: struct SSAPindication  *si;
        !          1413: \end{verbatim}\end{quote}
        !          1414: The parameters to this procedure are:
        !          1415: \begin{describe}
        !          1416: \item[\verb"sd":] the session-descriptor;
        !          1417: 
        !          1418: \item[\verb"tokens":] the tokens to requested;
        !          1419: 
        !          1420: \item[\verb"data"/\verb"cc":] any additional data
        !          1421: (and the length of that data, which may not exceed \verb"ST_SIZE" octets);
        !          1422: and,
        !          1423: 
        !          1424: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1425: updated only if the call fails.
        !          1426: \end{describe}
        !          1427: If the call to \verb"SPTokenRequest" is successful,
        !          1428: then the remote user has been notified of the request;
        !          1429: however, the ownership of the tokens is not actually transferred until the
        !          1430: session provider notifies the user with a {\sf S-TOKEN-GIVE-INDICATION\/}
        !          1431: event,
        !          1432: which typically occurs on the next call to \verb"SReadRequest".
        !          1433: 
        !          1434: \subsection    {Synchronization Management}\label{sync:mgmt}
        !          1435: There are three types of synchronization services:
        !          1436: majorsyncs, minorsyncs, and resyncs.
        !          1437: 
        !          1438: \subsubsection {Major Synchronization}
        !          1439: To indicate a major synchronization point,
        !          1440: the \verb"SMajSyncRequest" routine is used
        !          1441: (which corresponds to the {\sf S-MAJOR-SYNC.REQUEST\/} action).
        !          1442: \begin{quote}\index{SMajSyncRequest}\small\begin{verbatim}
        !          1443: int     SMajSyncRequest (sd, ssn, data, cc, si)
        !          1444: int     sd;
        !          1445: long   *ssn;
        !          1446: char   *data;
        !          1447: int     cc;
        !          1448: struct SSAPindication *si;
        !          1449: \end{verbatim}\end{quote}
        !          1450: The parameters to this procedure are:
        !          1451: \begin{describe}
        !          1452: \item[\verb"sd":] the session-descriptor;
        !          1453: 
        !          1454: \item[\verb"ssn":] a pointer to a long integer which,
        !          1455: on a successful return,
        !          1456: will be updated to reflect the current serial-number ($V(M)-1$);
        !          1457: 
        !          1458: \item[\verb"data"/\verb"cc":] any additional data
        !          1459: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
        !          1460: and,
        !          1461: 
        !          1462: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1463: updated only if the call fails.
        !          1464: \end{describe}
        !          1465: If the call to \verb"SMajSyncRequest" is successful,
        !          1466: then the major synchronization has been queued for the remote user.
        !          1467: When the {\sf S-MAJOR-SYNC.CON\-FIR\-MA\-TION\/} event is received,
        !          1468: the major synchronization is complete.
        !          1469: Otherwise the \verb"SSAPabort" structure contained in
        !          1470: the \verb"SSAPindication" parameter
        !          1471: \verb"si" contains the reason for failure.
        !          1472: 
        !          1473: Upon receiving a {\sf S-MAJOR-SYNC.INDICATION\/} event,
        !          1474: the user is required to generate a {\sf S-MAJOR-SYNC.RESPONSE\/} action
        !          1475: by calling the \verb"SMajSyncResponse" routine.
        !          1476: \begin{quote}\index{SMajSyncResponse}\small\begin{verbatim}
        !          1477: int     SMajSyncResponse (sd, data, cc, si)
        !          1478: int     sd;
        !          1479: char   *data;
        !          1480: int     cc;
        !          1481: struct SSAPindication *si;
        !          1482: \end{verbatim}\end{quote}
        !          1483: The parameters to this procedure are:
        !          1484: \begin{describe}
        !          1485: \item[\verb"sd":] the session-descriptor;
        !          1486: 
        !          1487: \item[\verb"data"/\verb"cc":] any additional data
        !          1488: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
        !          1489: and,
        !          1490: 
        !          1491: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1492: updated only if the call fails.
        !          1493: \end{describe}
        !          1494: If the call to \verb"SMajSyncResponse" is successful,
        !          1495: then the major synchronization has been completed.
        !          1496: Otherwise the \verb"SSAPabort" structure contained in
        !          1497: the \verb"SSAPindication" parameter
        !          1498: \verb"si" contains the reason for failure.
        !          1499: 
        !          1500: \subsubsection {Minor Synchronization}
        !          1501: To indicate a minor synchronization point,
        !          1502: the \verb"SMinSyncRequest" routine is used
        !          1503: (which corresponds to the {\sf S-MINOR-SYNC.REQUEST\/} action).
        !          1504: \begin{quote}\index{SMinSyncRequest}\small\begin{verbatim}
        !          1505: int     SMinSyncRequest (sd, type, ssn, data, cc, si)
        !          1506: int     sd;
        !          1507: int     type;
        !          1508: long   *ssn;
        !          1509: char   *data;
        !          1510: int     cc;
        !          1511: struct SSAPindication *si;
        !          1512: \end{verbatim}\end{quote}
        !          1513: The parameters to this procedure are:
        !          1514: \begin{describe}
        !          1515: \item[\verb"sd":] the session-descriptor;
        !          1516: 
        !          1517: \item[\verb"type":] the type of minor synchronization requested,
        !          1518: one of:
        !          1519: \[\begin{tabular}{|l|l|}
        !          1520: \hline
        !          1521:     \multicolumn{1}{|c|}{\bf Value}&
        !          1522:                \multicolumn{1}{c|}{\bf Type}\\
        !          1523: \hline
        !          1524:     \tt SYNC\_CONFIRM&         explicit confirmation requested\\
        !          1525:     \tt SYNC\_NOCONFIRM&       no confirmation requested\\
        !          1526: \hline
        !          1527: \end{tabular}\]
        !          1528: 
        !          1529: \item[\verb"ssn":] a pointer to a long integer which,
        !          1530: on a successful return,
        !          1531: will be updated to reflect the current serial-number ($V(M)-1$);
        !          1532: 
        !          1533: \item[\verb"data"/\verb"cc":] any additional data
        !          1534: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
        !          1535: and,
        !          1536: 
        !          1537: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1538: updated only if the call fails.
        !          1539: \end{describe}
        !          1540: If the call to \verb"SMinSyncRequest" is successful,
        !          1541: then the minor synchronization has been queued for the remote user.
        !          1542: If a {\sf S-MINOR-SYNC.CONFIRMATION\/} event is received,
        !          1543: the minor synchronization is complete.
        !          1544: However, the remote user is under no obligation to acknowledge the minorsync.
        !          1545: Otherwise the \verb"SSAPabort" structure contained in
        !          1546: the \verb"SSAPindication" parameter
        !          1547: \verb"si" contains the reason for failure.
        !          1548: 
        !          1549: Upon receiving a {\sf S-MINOR-SYNC.INDICATION\/} event,
        !          1550: the user may optionally use the \verb"SMinSyncResponse" routine
        !          1551: to generate a {\sf S-MINOR-SYNC.RESPONSE\/} action.
        !          1552: \begin{quote}\index{SMinSyncResponse}\small\begin{verbatim}
        !          1553: int     SMinSyncResponse (sd, ssn, data, cc, si)
        !          1554: int     sd;
        !          1555: long    ssn;
        !          1556: char   *data;
        !          1557: int     cc;
        !          1558: struct SSAPindication *si;
        !          1559: \end{verbatim}\end{quote}
        !          1560: The parameters to this procedure are:
        !          1561: \begin{describe}
        !          1562: \item[\verb"sd":] the session-descriptor;
        !          1563: 
        !          1564: \item[\verb"ssn":] the highest serial-number being confirmed;
        !          1565: 
        !          1566: \item[\verb"data"/\verb"cc":] any additional data
        !          1567: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
        !          1568: and,
        !          1569: 
        !          1570: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1571: updated only if the call fails.
        !          1572: \end{describe}
        !          1573: If the call to \verb"SMinSyncResponse" is successful,
        !          1574: then the minor synchronization has been completed.
        !          1575: Otherwise the \verb"SSAPabort" structure contained in
        !          1576: the \verb"SSAPindication" parameter
        !          1577: \verb"si" contains the reason for failure.
        !          1578: 
        !          1579: \subsubsection {ReSynchronization}
        !          1580: To resynchronize the connection to a known state,
        !          1581: the \verb"SReSyncRequest" is used
        !          1582: (which corresponds to the {\sf S-RESYNCHRONIZE.REQUEST\/} action).
        !          1583: \begin{quote}\index{SReSyncRequest}\small\begin{verbatim}
        !          1584: int     SReSyncRequest (sd, type, ssn, settings, data, cc, si)
        !          1585: int     sd;
        !          1586: int     type,
        !          1587:         settings;
        !          1588: long    ssn;
        !          1589: char   *data;
        !          1590: int     cc;
        !          1591: struct SSAPindication *si;
        !          1592: \end{verbatim}\end{quote}
        !          1593: The parameters to this procedure are:
        !          1594: \begin{describe}
        !          1595: \item[\verb"sd":] the session-descriptor;
        !          1596: 
        !          1597: \item[\verb"type":] the type of resynchronization requested
        !          1598: (either \verb"SYNC_RESTART", \verb"SYNC_ABANDON",
        !          1599: or \verb"SYNC_SET");
        !          1600: 
        !          1601: \item[\verb"ssn":] the serial-number to resynchronize to;
        !          1602: 
        !          1603: \item[\verb"settings":] the new token settings;
        !          1604: 
        !          1605: \item[\verb"data"/\verb"cc":] any additional data
        !          1606: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
        !          1607: and,
        !          1608: 
        !          1609: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1610: updated only if the call fails.
        !          1611: \end{describe}
        !          1612: If the call to \verb"SReSyncRequest" is successful,
        !          1613: then the resynchronization has been queued for the remote user.
        !          1614: When the {\sf S-RESYNCHRONIZE.CON\-FIR\-MA\-TION\/} event is received,
        !          1615: the resynchronization is complete.
        !          1616: Otherwise the \verb"SSAPabort" structure contained in
        !          1617: the \verb"SSAPindication" parameter
        !          1618: \verb"si" contains the reason for failure.
        !          1619: 
        !          1620: Upon receiving a {\sf S-RESYNCHRONIZE.INDICATION\/} event,
        !          1621: the user is required to generate a {\sf S-RESYNCHRONIZE.RESPONSE\/} action
        !          1622: using using the \verb"SReSyncResponse" routine.%
        !          1623: \footnote{Actually,
        !          1624: the user has other choices by using the rules of contention resolution.
        !          1625: Consult the ISO session service specification for the gruesome details.}
        !          1626: \begin{quote}\index{SReSyncResponse}\small\begin{verbatim}
        !          1627: int     SReSyncResponse (sd, ssn, settings, data, cc, si)
        !          1628: int     sd;
        !          1629: int     settings;
        !          1630: long    ssn;
        !          1631: char   *data;
        !          1632: int     cc;
        !          1633: struct SSAPindication *si;
        !          1634: \end{verbatim}\end{quote}
        !          1635: The parameters to this procedure are:
        !          1636: \begin{describe}
        !          1637: \item[\verb"sd":] the session-descriptor;
        !          1638: 
        !          1639: \item[\verb"ssn":] the serial-number to resynchronize to;
        !          1640: 
        !          1641: \item[\verb"settings":] the new token settings;
        !          1642: 
        !          1643: \item[\verb"data"/\verb"cc":] any additional data
        !          1644: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
        !          1645: and,
        !          1646: 
        !          1647: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1648: updated only if the call fails.
        !          1649: \end{describe}
        !          1650: 
        !          1651: \subsection    {Activity Management}
        !          1652: There are several types of activity management services:
        !          1653: activity start and resume,
        !          1654: activity interrupt and discard,
        !          1655: and activity end.
        !          1656: 
        !          1657: \subsubsection {Activity Start/Resume}
        !          1658: To initiate a new activity,
        !          1659: the \verb"SActStartRequest" routine is used
        !          1660: (which corresponds to the {\sf S-ACTIVITY-START.REQUEST\/} action).
        !          1661: \begin{quote}\index{SActStartRequest}\small\begin{verbatim}
        !          1662: int     SActStartRequest (sd, id, data, cc, si)
        !          1663: int     sd;
        !          1664: struct SSAPactid *id;
        !          1665: char   *data;
        !          1666: int     cc;
        !          1667: struct SSAPindication *si;
        !          1668: \end{verbatim}\end{quote}
        !          1669: The parameters to this procedure are:
        !          1670: \begin{describe}
        !          1671: \item[\verb"sd":] the session-descriptor;
        !          1672: 
        !          1673: \item[\verb"id":] the activity-identifier;
        !          1674: 
        !          1675: \item[\verb"data"/\verb"cc":] any additional data
        !          1676: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
        !          1677: and,
        !          1678: 
        !          1679: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1680: updated only if the call fails.
        !          1681: \end{describe}
        !          1682: 
        !          1683: The \verb"id" parameter is a pointer to a \verb"SSAPactid" structure,
        !          1684: which is passed transparently by the session service.
        !          1685: \begin{quote}\index{SSAPref}\small\begin{verbatim}
        !          1686: struct SSAPactid {
        !          1687: #define SID_DATA_SIZE   6
        !          1688:     u_char  sd_len;
        !          1689:     char    sd_data[SID_DATA_SIZE];
        !          1690: };
        !          1691: \end{verbatim}\end{quote}
        !          1692: The elements of this structure are:\label{SSAPactid}
        !          1693: \begin{describe}
        !          1694: \item[\verb"sd\_data"/\verb"sd\_len":] the data
        !          1695: (and length of that data, which may not exceed \verb"SID_DATA_SIZE" octets);
        !          1696: \end{describe}
        !          1697: If the call to the \verb"SActStartRequest" routine is successful,
        !          1698: then the activity is started.
        !          1699: Otherwise the \verb"SSAPabort" structure contained in
        !          1700: the \verb"SSAPindication" parameter
        !          1701: \verb"si" contains the reason for failure.
        !          1702: 
        !          1703: To resume a previously interrupted activity,
        !          1704: the \verb"SActResumeRequest" routine is used
        !          1705: (which corresponds to the {\sf S-ACTIVITY-RESUME.REQUEST\/} action).
        !          1706: \begin{quote}\index{SActResumeRequest}\small\begin{verbatim}
        !          1707: int     SActResumeRequest (sd, id, oid, ssn, ref, data, cc,
        !          1708:                 si)
        !          1709: int     sd;
        !          1710: struct SSAPactid *id,
        !          1711:                  *oid;
        !          1712: long    ssn;
        !          1713: struct SSAPref *ref;
        !          1714: char   *data;
        !          1715: int     cc;
        !          1716: struct SSAPindication *si;
        !          1717: \end{verbatim}\end{quote}
        !          1718: The parameters to this procedure are:
        !          1719: \begin{describe}
        !          1720: \item[\verb"sd":] the session-descriptor;
        !          1721: 
        !          1722: \item[\verb"id":] the activity-identifier
        !          1723: (consult page~\pageref{SSAPactid} for a description of the \verb"SSAPactid"
        !          1724: structure);
        !          1725: 
        !          1726: \item[\verb"oid":] the previous activity-identifier
        !          1727: (again, consult page~\pageref{SSAPactid});
        !          1728: 
        !          1729: \item[\verb"ssn":] the serial-number to resume the activity at;
        !          1730: 
        !          1731: \item[\verb"ref":] the previous connection identifier;
        !          1732: 
        !          1733: \item[\verb"data"/\verb"cc":] any additional data
        !          1734: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
        !          1735: and,
        !          1736: 
        !          1737: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1738: updated only if the call fails.
        !          1739: \end{describe}
        !          1740: 
        !          1741: The \verb"ref" parameter is a pointer to a \verb"SSAPref" structure.
        !          1742: Note that unlike the connection identifiers used during connection
        !          1743: establishment (as described on page~\pageref{SSAPref}),
        !          1744: there are four fields:\label{SSAPactref}
        !          1745: \[\begin{tabular}{|l|l|l|}
        !          1746: \hline
        !          1747:     \multicolumn{1}{|c|}{\bf Field}&
        !          1748:     \multicolumn{1}{c|}{\bf Contents}&
        !          1749:     \multicolumn{1}{c|}{\bf Length}\\
        !          1750: \hline
        !          1751:     calling SSAP user reference&
        !          1752:                        \tt sr\_calling&        \tt sr\_calling\_len\\
        !          1753:     called SSAP user reference&
        !          1754:                        \tt sr\_called& \tt sr\_called\_len\\
        !          1755:     common reference&
        !          1756:                        \tt sr\_cdata&  \tt sr\_clen\\
        !          1757:     additional reference&
        !          1758:                        \tt sr\_adata&  \tt sr\_alen\\
        !          1759: \hline
        !          1760: \end{tabular}\]
        !          1761: 
        !          1762: If the call to the \verb"SActResumeRequest" routine is successful,
        !          1763: then the activity is resumed.
        !          1764: Otherwise the \verb"SSAPabort" structure contained in
        !          1765: the \verb"SSAPindication" parameter
        !          1766: \verb"si" contains the reason for failure.
        !          1767: 
        !          1768: \subsubsection {Activity Interrupt/Discard}
        !          1769: To interrupt an activity in progress,
        !          1770: the \verb"SActIntrRequest" routine is used
        !          1771: (which corresponds to the {\sf S-ACTIVITY-INTERRUPT.REQUEST\/} action).
        !          1772: \begin{quote}\index{SActIntrRequest}\small\begin{verbatim}
        !          1773: int     SActIntrRequest (sd, reason, si)
        !          1774: int     sd;
        !          1775: int     reason;
        !          1776: struct SSAPindication *si;
        !          1777: \end{verbatim}\end{quote}
        !          1778: The parameters to this procedure are:
        !          1779: \begin{describe}
        !          1780: \item[\verb"sd":] the session-descriptor;
        !          1781: 
        !          1782: \item[\verb"reason":] the reason for the interrupt
        !          1783: (codes are listed in Table~\ref{SSAPexceptions});
        !          1784: and,
        !          1785: 
        !          1786: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1787: updated only if the call fails.
        !          1788: \end{describe}
        !          1789: If the call to \verb"SActIntrRequest" is successful,
        !          1790: then the activity interrupt has been queued for the remote user.
        !          1791: When the {\sf S-ACTIVITY-INTERRUPT.CON\-FIR\-MA\-TION\/} event is received,
        !          1792: the activity interrupt is complete.
        !          1793: Otherwise the \verb"SSAPabort" structure contained in
        !          1794: the \verb"SSAPindication" parameter
        !          1795: \verb"si" contains the reason for failure.
        !          1796: 
        !          1797: Upon receiving a {\sf S-ACTIVITY-INTERRUPT.INDICATION\/} event,
        !          1798: the user is required to generate a {\sf S-ACTIVITY-INTERRUPT.RESPONSE\/} action
        !          1799: using the \verb"SActIntrResponse" routine.
        !          1800: \begin{quote}\index{SActIntrResponse}\small\begin{verbatim}
        !          1801: int     SActIntrResponse (sd, si)
        !          1802: int     sd;
        !          1803: struct SSAPindication *si;
        !          1804: \end{verbatim}\end{quote}
        !          1805: The parameters to this procedure are:
        !          1806: \begin{describe}
        !          1807: \item[\verb"sd":] the session-descriptor;
        !          1808: and,
        !          1809: 
        !          1810: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1811: updated only if the call fails.
        !          1812: \end{describe}
        !          1813: If the call to \verb"SActIntrResponse" is successful,
        !          1814: then the activity interrupt has been completed.
        !          1815: Otherwise the \verb"SSAPabort" structure contained in
        !          1816: the \verb"SSAPindication" parameter
        !          1817: \verb"si" contains the reason for failure.
        !          1818: 
        !          1819: To discard an activity in progress,
        !          1820: the \verb"SActDiscRequest" routine is used
        !          1821: (which corresponds to the {\sf S-ACTIVITY-DISCARD.REQUEST\/} action).
        !          1822: \begin{quote}\index{SActDiscRequest}\small\begin{verbatim}
        !          1823: int     SActDiscRequest (sd, reason, si)
        !          1824: int     sd;
        !          1825: int     reason;
        !          1826: struct SSAPindication *si;
        !          1827: \end{verbatim}\end{quote}
        !          1828: The parameters to this procedure are:
        !          1829: \begin{describe}
        !          1830: \item[\verb"sd":] the session-descriptor;
        !          1831: 
        !          1832: \item[\verb"reason":] the reason for the discard
        !          1833: (codes are listed in Table~\ref{SSAPexceptions});
        !          1834: and,
        !          1835: 
        !          1836: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1837: updated only if the call fails.
        !          1838: \end{describe}
        !          1839: If the call to \verb"SActDiscRequest" is successful,
        !          1840: then the activity discard has been queued for the remote user.
        !          1841: When the {\sf S-ACTIVITY-DISCARD.CON\-FIR\-MA\-TION\/} event is received,
        !          1842: the activity discard is complete.
        !          1843: Otherwise the \verb"SSAPabort" structure contained in
        !          1844: the \verb"SSAPindication" parameter
        !          1845: \verb"si" contains the reason for failure.
        !          1846: 
        !          1847: Upon receiving a {\sf S-ACTIVITY-DISCARD.INDICATION\/} event,
        !          1848: the user is required to generate a {\sf S-ACTIVITY-DISCARD.RESPONSE\/} action
        !          1849: using the \verb"SActDiscResponse" routine.
        !          1850: \begin{quote}\index{SActDiscResponse}\small\begin{verbatim}
        !          1851: int     SActDiscResponse (sd, si)
        !          1852: int     sd;
        !          1853: struct SSAPindication *si;
        !          1854: \end{verbatim}\end{quote}
        !          1855: The parameters to this procedure are:
        !          1856: \begin{describe}
        !          1857: \item[\verb"sd":] the session-descriptor;
        !          1858: and,
        !          1859: 
        !          1860: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1861: updated only if the call fails.
        !          1862: \end{describe}
        !          1863: If the call to \verb"SActDiscResponse" is successful,
        !          1864: then the activity discard has been completed.
        !          1865: Otherwise the \verb"SSAPabort" structure contained in
        !          1866: the \verb"SSAPindication" parameter
        !          1867: \verb"si" contains the reason for failure.
        !          1868: 
        !          1869: \subsubsection {Activity End}
        !          1870: To end an activity in progress,
        !          1871: the \verb"SActEndRequest" routine is used
        !          1872: (which corresponds to the {\sf S-ACTIVITY-END.REQUEST\/} action).
        !          1873: \begin{quote}\index{SActEndRequest}\small\begin{verbatim}
        !          1874: int     SActEndRequest (sd, ssn, data, cc, si)
        !          1875: int     sd;
        !          1876: long   *ssn;
        !          1877: char   *data;
        !          1878: int     cc;
        !          1879: struct SSAPindication *si;
        !          1880: \end{verbatim}\end{quote}
        !          1881: The parameters to this procedure are:
        !          1882: \begin{describe}
        !          1883: \item[\verb"sd":] the session-descriptor;
        !          1884: 
        !          1885: \item[\verb"ssn":] a pointer to a long integer which,
        !          1886: on a successful return,
        !          1887: will be updated to reflect the current serial-number ($V(M)-1$);
        !          1888: 
        !          1889: \item[\verb"data"/\verb"cc":] any additional data
        !          1890: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
        !          1891: and,
        !          1892: 
        !          1893: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1894: updated only if the call fails.
        !          1895: \end{describe}
        !          1896: If the call to \verb"SActEndRequest" is successful,
        !          1897: then the activity end has been queued for the remote user.
        !          1898: When the {\sf S-ACTIVITY-END.CONFIRMATION\/} event is received,
        !          1899: the activity end is complete.
        !          1900: Otherwise the \verb"SSAPabort" structure contained in
        !          1901: the \verb"SSAPindication" parameter
        !          1902: \verb"si" contains the reason for failure.
        !          1903: 
        !          1904: Upon receiving a {\sf S-ACTIVITY-END.INDICATION\/} event,
        !          1905: the user is required to call the \verb"SActEndResponse" routine
        !          1906: to generate a {\sf S-ACTIVITY-END.RESPONSE\/} action.
        !          1907: \begin{quote}\index{SActEndResponse}\small\begin{verbatim}
        !          1908: int     SActEndResponse (sd, data, cc, si)
        !          1909: int     sd;
        !          1910: char   *data;
        !          1911: int     cc;
        !          1912: struct SSAPindication *si;
        !          1913: \end{verbatim}\end{quote}
        !          1914: The parameters to this procedure are:
        !          1915: \begin{describe}
        !          1916: \item[\verb"sd":] the session-descriptor;
        !          1917: 
        !          1918: \item[\verb"data"/\verb"cc":] any additional data
        !          1919: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
        !          1920: and,
        !          1921: 
        !          1922: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1923: updated only if the call fails.
        !          1924: \end{describe}
        !          1925: If the call to \verb"SActEndResponse" is successful,
        !          1926: then the activity end has been completed.
        !          1927: Otherwise the \verb"SSAPabort" structure contained in
        !          1928: the \verb"SSAPindication" parameter
        !          1929: \verb"si" contains the reason for failure.
        !          1930: 
        !          1931: \subsection    {Exception Reporting}
        !          1932: To report an exception and place the connection in a special error-recovery
        !          1933: state,
        !          1934: the \verb"SUReportRequest" routine is called
        !          1935: (which corresponds to the {\sf S-U-EXCEPTION-REPORT.REQUEST\/} action).
        !          1936: \begin{quote}\index{SUReportRequest}\small\begin{verbatim}
        !          1937: int    SUReportRequest (sd, reason, data, cc, si)
        !          1938: int    sd;
        !          1939: int     reason;
        !          1940: char   *data;
        !          1941: int    cc;
        !          1942: struct SSAPindication  *si;
        !          1943: \end{verbatim}\end{quote}
        !          1944: The parameters to this procedure are:
        !          1945: \begin{describe}
        !          1946: \item[\verb"sd":] the session-descriptor;
        !          1947: 
        !          1948: \item[\verb"reason":] the reason for the report
        !          1949: (codes are listed in Table~\ref{SSAPexceptions});
        !          1950: 
        !          1951: \item[\verb"data"/\verb"cc":] any report data
        !          1952: (and the length of that data, which may not exceed \verb"SP_SIZE" octets);
        !          1953: and,
        !          1954: 
        !          1955: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1956: updated only if the call fails.
        !          1957: \end{describe}
        !          1958: If the call to \verb"SUReportRequest" is successful,
        !          1959: then the connection is placed in an error state,
        !          1960: and any data queued for the connection may be lost until recovery is complete.
        !          1961: Otherwise the \verb"SSAPabort" structure contained in
        !          1962: the \verb"SSAPindication" parameter
        !          1963: \verb"si" contains the reason for failure.
        !          1964: 
        !          1965: Typically,
        !          1966: error recovery can be achieved by giving away the data token or by aborting
        !          1967: the connection (discussed next).
        !          1968: Error recovery is discussed in greater detail in the ISO session service
        !          1969: specification.
        !          1970: 
        !          1971: \subsection    {User-initiated Aborts}
        !          1972: To unilaterally initiate an abort of the connection,
        !          1973: the \verb"SUAbortRequest" routine is called
        !          1974: (which corresponds to the {\sf S-U-ABORT.REQUEST\/} action).
        !          1975: \begin{quote}\index{SUAbortRequest}\small\begin{verbatim}
        !          1976: int    SUAbortRequest (sd, data, cc, si)
        !          1977: int    sd;
        !          1978: char   *data;
        !          1979: int    cc;
        !          1980: struct SSAPindication  *si;
        !          1981: \end{verbatim}\end{quote}
        !          1982: The parameters to this procedure are:
        !          1983: \begin{describe}
        !          1984: \item[\verb"sd":] the session-descriptor;
        !          1985: 
        !          1986: \item[\verb"data"/\verb"cc":] any abort data
        !          1987: (and the length of that data, which may not exceed \verb"SA_SIZE" octets);
        !          1988: and,
        !          1989: 
        !          1990: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          1991: updated only if the call fails.
        !          1992: \end{describe}
        !          1993: If the call to \verb"SUAbortRequest" is successful,
        !          1994: then the connection is immediately closed,
        !          1995: and any data queued for the connection may be lost.
        !          1996: 
        !          1997: \subsection    {Asynchronous Event Handling}
        !          1998: The data transfer events discussed thus far have been synchronous in nature.
        !          1999: Some users of the session service may wish an asynchronous interface.
        !          2000: The \verb"SSetIndications" routine is used to change the service associated
        !          2001: with a session-descriptor to or from an asynchronous interface.
        !          2002: \begin{quote}\index{SSetIndications}\small\begin{verbatim}
        !          2003: int     SSetIndications (sd, data, tokens, sync, activity,
        !          2004:                 report, finish, abort, si)
        !          2005: int     sd;
        !          2006: int   (*data) (),
        !          2007:       (*tokens) (),
        !          2008:       (*sync) (),
        !          2009:       (*activity) (),
        !          2010:       (*report) (),
        !          2011:       (*finish) (),
        !          2012:       (*abort) ();
        !          2013: struct SSAPindication  *si;
        !          2014: \end{verbatim}\end{quote}
        !          2015: The parameters to this procedure are:
        !          2016: \begin{describe}
        !          2017: \item[\verb"sd":] the session-descriptor;
        !          2018: 
        !          2019: \item[\verb"data":] the address of an event-handler routine to be invoked when
        !          2020: data has arrived;
        !          2021: 
        !          2022: \item[\verb"tokens":] the address of an event-handler routine to be invoked
        !          2023: when a token management event occurs;
        !          2024: 
        !          2025: \item[\verb"sync":] the address of an event-handler routine to be invoked
        !          2026: when a synchronization management event occurs;
        !          2027: 
        !          2028: \item[\verb"activity":] the address of an event-handler routine to be invoked
        !          2029: when an activity management event occurs;
        !          2030: 
        !          2031: \item[\verb"report":] the address of an event-handler routine to be invoked
        !          2032: when an exception report event occurs;
        !          2033: 
        !          2034: \item[\verb"finish":] the address of an event-handler routine to be invoked
        !          2035: when the connection is ready to be released;
        !          2036: 
        !          2037: \item[\verb"abort":] the address of an event-handler routine to be invoked when
        !          2038: a user-initiated abort (a {\sf S-U-ABORT.INDICATION\/} event occurs)
        !          2039: or a provider-initiated abort
        !          2040: (a {\sf S-P-ABORT.INDICATION\/} event occurs);
        !          2041: and,
        !          2042: 
        !          2043: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !          2044: only if the call fails.
        !          2045: \end{describe}
        !          2046: If the service is to be made asynchronous,
        !          2047: then all event handlers are specified,
        !          2048: otherwise,
        !          2049: if the service is to be made synchronous,
        !          2050: then no event handlers should be specified
        !          2051: (use the manifest constant \verb"NULLIFP").
        !          2052: The most likely reason for the call failing is \verb"SC_WAITING",
        !          2053: which indicates that an event is waiting for the user.
        !          2054: 
        !          2055: When an event-handler is invoked,
        !          2056: future invocations of the event-hander are blocked until it returns.
        !          2057: The return value of the event-handler is ignored.
        !          2058: Further,
        !          2059: during the execution of a synchronous call to the library,
        !          2060: the event-handler will be blocked from being invoked.
        !          2061: 
        !          2062: When an event associated with data arrival occurs,
        !          2063: the event-handler routine is invoked with two parameters:
        !          2064: \begin{quote}\small\begin{verbatim}
        !          2065: (*data) (sd, sx);
        !          2066: int     sd;
        !          2067: struct SSAPdata *sx;
        !          2068: \end{verbatim}\end{quote}
        !          2069: The parameters are:
        !          2070: \begin{describe}
        !          2071: \item[\verb"sd":] the session-descriptor;
        !          2072: and,
        !          2073: 
        !          2074: \item[\verb"sx":] a pointer to the \verb"SSAPdata" structure containing
        !          2075: the data.
        !          2076: \end{describe}
        !          2077: Note that the data contained in the structure was allocated via \man malloc(3),
        !          2078: and should be released with the \verb"SXFREE" macro
        !          2079: (described on page~\pageref{SXFREE}) when no longer needed.
        !          2080: 
        !          2081: When an event associated with token management arrives
        !          2082: the event-handler routine is invoked with two parameters:
        !          2083: \begin{quote}\small\begin{verbatim}
        !          2084: (*tokens) (sd, st);
        !          2085: int       sd;
        !          2086: struct SSAPtoken *st;
        !          2087: \end{verbatim}\end{quote}
        !          2088: The parameters are:
        !          2089: \begin{describe}
        !          2090: \item[\verb"sd":] the session-descriptor;
        !          2091: and,
        !          2092: 
        !          2093: \item[\verb"st":] a pointer to the \verb"SSAPtoken" structure containing
        !          2094: the token management information.
        !          2095: \end{describe}
        !          2096: 
        !          2097: When an event associated with synchronization management arrives
        !          2098: the event-handler routine is invoked with two parameters:
        !          2099: \begin{quote}\small\begin{verbatim}
        !          2100: (*sync) (sd, sn);
        !          2101: int       sd;
        !          2102: struct SSAPsync *sn;
        !          2103: \end{verbatim}\end{quote}
        !          2104: The parameters are:
        !          2105: \begin{describe}
        !          2106: \item[\verb"sd":] the session-descriptor;
        !          2107: and,
        !          2108: 
        !          2109: \item[\verb"sn":] a pointer to the \verb"SSAPsync" structure containing
        !          2110: the synchronization management information.
        !          2111: \end{describe}
        !          2112: 
        !          2113: When an event associated with activity management arrives
        !          2114: the event-handler routine is invoked with two parameters:
        !          2115: \begin{quote}\small\begin{verbatim}
        !          2116: (*activity) (sd, sv);
        !          2117: int       sd;
        !          2118: struct SSAPactivity *sv;
        !          2119: \end{verbatim}\end{quote}
        !          2120: The parameters are:
        !          2121: \begin{describe}
        !          2122: \item[\verb"sd":] the session-descriptor;
        !          2123: and,
        !          2124: 
        !          2125: \item[\verb"sv":] a pointer to the \verb"SSAPactivity" structure containing
        !          2126: the activity management information.
        !          2127: \end{describe}
        !          2128: 
        !          2129: When an event associated with exception reporting arrives
        !          2130: the event-handler routine is invoked with two parameters:
        !          2131: \begin{quote}\small\begin{verbatim}
        !          2132: (*report) (sd, sp);
        !          2133: int       sd;
        !          2134: struct SSAPreport *sp;
        !          2135: \end{verbatim}\end{quote}
        !          2136: The parameters are:
        !          2137: \begin{describe}
        !          2138: \item[\verb"sd":] the session-descriptor;
        !          2139: and,
        !          2140: 
        !          2141: \item[\verb"sp":] a pointer to the \verb"SSAPreport" structure containing
        !          2142: the exception report information.
        !          2143: \end{describe}
        !          2144: 
        !          2145: When an event associated with connection termination arrives
        !          2146: the event-handler routine is invoked with two parameters:
        !          2147: \begin{quote}\small\begin{verbatim}
        !          2148: (*finish) (sd, sf);
        !          2149: int       sd;
        !          2150: struct SSAPfinish *sf;
        !          2151: \end{verbatim}\end{quote}
        !          2152: The parameters are:
        !          2153: \begin{describe}
        !          2154: \item[\verb"sd":] the session-descriptor;
        !          2155: and,
        !          2156: 
        !          2157: \item[\verb"sf":] a pointer to the \verb"SSAPfinish" structure containing
        !          2158: information concerning the request to terminate the connection.
        !          2159: \end{describe}
        !          2160: 
        !          2161: When an event associated with a user- or provider-initiated abort occurs,
        !          2162: the event-handler is invoked with two parameters:
        !          2163: \begin{quote}\small\begin{verbatim}
        !          2164: (*abort) (sd, sa);
        !          2165: int      sd;
        !          2166: struct SSAPabort *sa;
        !          2167: \end{verbatim}\end{quote}
        !          2168: The parameters are:
        !          2169: \begin{describe}
        !          2170: \item[\verb"sd":] the session-descriptor;
        !          2171: and,
        !          2172: 
        !          2173: \item[\verb"sa":] a pointer to the \verb"SSAPabort" structure
        !          2174: indicating why the connection was aborted.
        !          2175: \end{describe}
        !          2176: Note that the session-descriptor is no longer valid at the instant the
        !          2177: call is made.
        !          2178: 
        !          2179: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !          2180: \bf NOTE:&     The \man libssap(3n) library uses the SIGEMT signal to provide
        !          2181:                these services.
        !          2182:                Programs using asynchronous session-descriptors should NOT
        !          2183:                use SIGEMT for other purposes.
        !          2184: \end{tabular}}\]
        !          2185: 
        !          2186: \subsection    {Synchronous Event Multiplexing}
        !          2187: A user of the session service may wish to manage multiple
        !          2188: session-de\-scrip\-tors simultaneously;
        !          2189: the routine \verb"SSelectMask" is provided for this purpose.
        !          2190: This routine updates a file-descriptor mask and associated counter for use
        !          2191: with \verb"xselect".
        !          2192: \begin{quote}\index{SSelectMask}\small\begin{verbatim}
        !          2193: int     SSelectMask (sd, mask, nfds, si)
        !          2194: int     sd;
        !          2195: fd_set *mask,
        !          2196: int    *nfds;
        !          2197: struct SSAPindication  *si;
        !          2198: \end{verbatim}\end{quote}
        !          2199: The parameters to this procedure are:
        !          2200: \begin{describe}
        !          2201: \item[\verb"sd":] the session-descriptor;
        !          2202: 
        !          2203: \item[\verb"mask":] a pointer to a file-descriptor mask meaningful to
        !          2204: \verb"xselect";
        !          2205: 
        !          2206: \item[\verb"nfds":] a pointer to an integer-valued location meaningful to
        !          2207: \verb"xselect";
        !          2208: and,
        !          2209: 
        !          2210: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !          2211: only if the call fails.
        !          2212: \end{describe}
        !          2213: If the call is successful, then the \verb"mask" and \verb"nfds" parameters can
        !          2214: be used as arguments to \verb"xselect".
        !          2215: The most likely reason for the call failing is \verb"SC_WAITING",
        !          2216: which indicates that an event is waiting for the user.
        !          2217: 
        !          2218: If \verb"xselect" indicates that the session-descriptor is ready for reading,
        !          2219: \verb"SReadRequest" should be called with the \verb"secs" parameter equal to
        !          2220: \verb"OK".
        !          2221: If the network activity does not constitute an entire event for the user,
        !          2222: then \verb"SReadRequest" will return \verb"NOTOK" with error code
        !          2223: \verb"SC_TIMER".
        !          2224: 
        !          2225: \section      {Connection Release}
        !          2226: The \verb"SRelRequest" routine is used to request the release a connection,
        !          2227: and corresponds to a {\sf S-RELEASE.REQUEST\/} action.
        !          2228: The SSAP attempts to gracefully drain any queued data before closing
        !          2229: the connection.
        !          2230: \begin{quote}\index{SRelRequest}\small\begin{verbatim}
        !          2231: int     SRelRequest (sd, data, cc, secs, sr, si)
        !          2232: int     sd;
        !          2233: char   *data;
        !          2234: int     cc;
        !          2235: int     secs;
        !          2236: struct SSAPrelease  *sr;
        !          2237: struct SSAPindication  *si;
        !          2238: \end{verbatim}\end{quote}
        !          2239: The parameters to this procedure are:
        !          2240: \begin{describe}
        !          2241: \item[\verb"sd":] the session-descriptor;
        !          2242: 
        !          2243: \item[\verb"data"/\verb"cc":] any final data
        !          2244: (and the length of that data,
        !          2245: which may not exceed \verb"SF_SIZE" octets);
        !          2246: 
        !          2247: \item[\verb"secs":] the maximum number of seconds to wait for a response
        !          2248: (use the manifest constant \verb"NOTOK" if no time-out is desired);
        !          2249: 
        !          2250: \item[\verb"sr":] a pointer to a \verb"SSAPrelease" structure, which is updated
        !          2251: only if the call succeeds;
        !          2252: and,
        !          2253: 
        !          2254: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !          2255: only if the call fails.
        !          2256: \end{describe}
        !          2257: If the call to \verb"SRelRequest" is successful,
        !          2258: then this corresponds to a {\sf S-RELEASE.CONFIRMATION\/} event,
        !          2259: and it returns information in the \verb"sr" parameter,
        !          2260: which is a pointer to a \verb"SSAPrelease" structure.
        !          2261: \begin{quote}\index{SSAPrelease}\small\begin{verbatim}
        !          2262: struct SSAPrelease {
        !          2263:     int     sr_affirmative;
        !          2264: 
        !          2265: #define SR_SIZE         512
        !          2266:     int     sr_cc;
        !          2267:     char    sr_data[SR_SIZE];
        !          2268: };
        !          2269: \end{verbatim}\end{quote}
        !          2270: The elements of this structure are:
        !          2271: \begin{describe}
        !          2272: \item[\verb"sr\_affirmative":] the acceptance indicator;
        !          2273: and,
        !          2274: 
        !          2275: \item[\verb"sr\_data"/\verb"sr\_cc":] any final data
        !          2276: (and the length of that data).
        !          2277: \end{describe}
        !          2278: If the call to \verb"SRelRequest" is successful,
        !          2279: and the \verb"sr_affirmative" element is set,
        !          2280: then the connection has been closed.
        !          2281: If the call is successful,
        !          2282: but the \verb"sr_affirmative" element is not set (i.e., zero),
        !          2283: then the request to close the connection has been rejected by the remote user,
        !          2284: and the connection is still open.
        !          2285: Otherwise the \verb"SSAPabort" structure contained in
        !          2286: the \verb"SSAPindication" parameter
        !          2287: \verb"si" contains the reason for failure.
        !          2288: 
        !          2289: Note that if a non-negative value is given to the \verb"secs" parameter and a
        !          2290: response is not received within this number of seconds,
        !          2291: then the value contained in the \verb"sa_reason" element is \verb"SC_TIMER".
        !          2292: The user can then call the routine \verb"SRelRetryRequest" to continue waiting
        !          2293: for a response:
        !          2294: \begin{quote}\index{SRelRetryRequest}\small\begin{verbatim}
        !          2295: int     SRelRetryRequest (sd, secs, sr, si)
        !          2296: int     sd;
        !          2297: int     secs;
        !          2298: struct SSAPrelease  *sr;
        !          2299: struct SSAPindication  *si;
        !          2300: \end{verbatim}\end{quote}
        !          2301: The parameters to this procedure are:
        !          2302: \begin{describe}
        !          2303: \item[\verb"sd":] the session-descriptor;
        !          2304: 
        !          2305: \item[\verb"secs":] the maximum number of seconds to wait for a response
        !          2306: (use the manifest constant \verb"NOTOK" if no time-out is desired);
        !          2307: 
        !          2308: \item[\verb"sr":] a pointer to a \verb"SSAPrelease" structure, which is updated
        !          2309: only if the call succeeds;
        !          2310: and,
        !          2311: 
        !          2312: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
        !          2313: only if the call fails.
        !          2314: \end{describe}
        !          2315: If the call to \verb"SRelRetryRequest" is successful,
        !          2316: and the \verb"sr_affirmative" element is set,
        !          2317: then the connection has been closed.
        !          2318: If the call is successful,
        !          2319: but the \verb"sr_affirmative" element is not set (i.e., zero),
        !          2320: then the request to close the connection has been rejected by the remote user,
        !          2321: and the connection is still open.
        !          2322: Otherwise the \verb"SSAPabort" structure contained in
        !          2323: the \verb"SSAPindication" parameter
        !          2324: \verb"si" contains the reason for failure.
        !          2325: As expected,
        !          2326: the value \verb"SC_TIMER" indicates that no response was received within the
        !          2327: time given by the \verb"secs" parameter.
        !          2328: 
        !          2329: Upon receiving a {\sf S-RELEASE.INDICATION\/} event,
        !          2330: the user is required to generate a {\sf S-RELEASE.RESPONSE\/} action
        !          2331: using the \verb"SRelResponse" routine.
        !          2332: \begin{quote}\index{SRelResponse}\small\begin{verbatim}
        !          2333: int     SRelResponse (sd, status, data, cc, si)
        !          2334: int     sd;
        !          2335: int     status,
        !          2336:         cc;
        !          2337: char   *data;
        !          2338: struct SSAPindication  *si;
        !          2339: \end{verbatim}\end{quote}
        !          2340: The parameters to this procedure are:
        !          2341: \begin{describe}
        !          2342: \item[\verb"sd":] the session-descriptor;
        !          2343: 
        !          2344: \item[\verb"status":] the acceptance indicator
        !          2345: (either \verb"SC_ACCEPT" if the connection is to be closed,
        !          2346: or \verb"SC_REJECTED" otherwise);
        !          2347: 
        !          2348: \item[\verb"data"/\verb"cc":] any final data (and the length of that data,
        !          2349: which may not exceed \verb"SR_SIZE" octets);
        !          2350: and,
        !          2351: 
        !          2352: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
        !          2353: updated only if the call fails.
        !          2354: \end{describe}
        !          2355: If the call to \verb"SRelResponse" is successful,
        !          2356: and if the \verb"result" parameter is set to \verb"SC_ACCEPT",
        !          2357: then the connection has been closed.
        !          2358: If the call is successful,
        !          2359: but the \verb"result" parameter is not \verb"SC_ACCEPT",
        !          2360: then the connection still remains open.
        !          2361: Note that in order to specify a value other tha \verb"SC_ACCEPT" for the
        !          2362: \verb"result" parameter to \verb"SRelResponse",
        !          2363: the release token must exist but must not be owned by the user making the
        !          2364: call to \verb"SRelResponse".%
        !          2365: \footnote{Gentle reader, we don't write the standards;
        !          2366: we just try to implement them.}
        !          2367: 
        !          2368: \section      {Restrictions on User Data}
        !          2369: The \man libssap(3n) contains partial support for the use of unlimited user
        !          2370: data for session services.
        !          2371: With the exception of the {\sf S-DATA\/} and the {\sf S-TYPED-DATA\/} services,
        !          2372: the initial session service limited the amount of user data that could be
        !          2373: present. 
        !          2374: With the introduction of the unlimited user data
        !          2375: addendum\cite{ISO.SS.UserData,ISO.SP.UserData} to the session service and
        !          2376: protocol,
        !          2377: this restriction has been lifted.
        !          2378: 
        !          2379: During connection establishment,
        !          2380: the \man libssap(3n) library will attempt to negotate the use of unlimited
        !          2381: user data.
        !          2382: If this negotiation fails,
        !          2383: then session services which permit user data,
        !          2384: other than {\sf S-DATA\/} and {\sf S-TYPED-DATA},
        !          2385: are limited to 512~octets of user data.%
        !          2386: \footnote{Strictly speaking,
        !          2387: the {\sf S-U-ABORT} service permits only 9~octets of user data.
        !          2388: This limitation is unreasonable~---~upto 512~octets will be permitted.}
        !          2389: 
        !          2390: If the negotation succeeds,
        !          2391: then session services which permit user data,
        !          2392: other than {\sf S-DATA\/} and {\sf S-TYPED-DATA},
        !          2393: are limited to 65400~octets of user data,
        !          2394: with the exception of the {\sf S-CONNECT.REQUEST\/} primitive,
        !          2395: which is limited to 10240~octets of user data
        !          2396: (the {\sf S-CONNECT.RESPONSE\/} primitive is limited to 65528~octets).%
        !          2397: \footnote{Strictly speaking,
        !          2398: the amount should be unlimited.
        !          2399: However this full generality is not available at this time.}
        !          2400: 
        !          2401: There is one further limitation however:
        !          2402: although the initiator of a connection can send upto 10240~octets,
        !          2403: due to limitations in the \unix/ kernel,
        !          2404: if the \man tsapd(8c) is dispatching based on session selector,
        !          2405: then a responder can accept upto approximately 1536~octets.
        !          2406: To avoid this problem,
        !          2407: have \man tsapd(8c) dispatch based on transport selector
        !          2408: (see Section~\ref{service:standard} in \volone/).
        !          2409: 
        !          2410: \section      {Error Conventions}
        !          2411: All of the routines in this library return the manifest constant \verb"NOTOK"
        !          2412: on error,
        !          2413: and also update the \verb"si" parameter given to the routine.
        !          2414: The \verb"si_abort" element of the \verb"SSAPindication" structure contains a
        !          2415: \verb"SSAPabort" structure detailing the reason for the failure.
        !          2416: The \verb"sa_reason" element of this latter structure can be given as a
        !          2417: parameter to the routine \verb"SErrString" which returns a null-terminated
        !          2418: diagnostic string.
        !          2419: \begin{quote}\index{SErrString}\small\begin{verbatim}
        !          2420: char   *SErrString (c)
        !          2421: int     c;
        !          2422: \end{verbatim}\end{quote}
        !          2423: 
        !          2424: \section      {Compiling and Loading}
        !          2425: Programs using the \man libssap(3n) library should include
        !          2426: \verb"<isode/ssap.h>".
        !          2427: The programs should also be loaded with \verb"-lssap" and \verb"-ltsap"
        !          2428: (this latter library contains the routines which implement the transport
        !          2429: services used by the session provider).
        !          2430: 
        !          2431: \section      {An Example}
        !          2432: Let's consider how one might construct a source entity that resides on the
        !          2433: SSAP.
        !          2434: This entity will use a synchronous interface.
        !          2435: 
        !          2436: There are two parts to the program:
        !          2437: initialization and data transfer;
        !          2438: release will occur when the standard input has been exhausted.
        !          2439: In our example,
        !          2440: we assume that the routine \verb"error" results in the process being
        !          2441: terminated after printing a diagnostic.
        !          2442: 
        !          2443: In Figure~\ref{initSSsource},
        !          2444: the initialization steps for the source entity,
        !          2445: including the outer {\em C\/} wrapper,
        !          2446: is shown.
        !          2447: First, a lookup is done in the ISO services database,
        !          2448: and the \verb"SSAPaddr" is initialized.
        !          2449: The \verb"SSAPref" is zeroed.
        !          2450: Next, for each token associated with the session requirements,
        !          2451: initial ownership of that token is claimed.
        !          2452: Finally,
        !          2453: the call to \verb"SConnRequest" is made.
        !          2454: If the call is successful,
        !          2455: a check is made to see if the remote user accepted the connection.
        !          2456: If so,
        !          2457: the session-descriptor is captured,
        !          2458: along with the negotiated requirements and initial token settings.
        !          2459: 
        !          2460: In Figure~\ref{dataSSsource} on page~\pageref{dataSSsource},
        !          2461: the data transfer loop is realized.
        !          2462: The source entity reads a line from the standard input,
        !          2463: and then queues that line for sending to the remote side.
        !          2464: When an end-of-file occurs on the standard input,
        !          2465: the source entity requests release and then gracefully terminates.
        !          2466: Although no checking is done in this example,
        !          2467: for the calls to \verb"SDataRequest" and \verb"SRelRequest",
        !          2468: on failure
        !          2469: a check for the operational error \verb"SC_OPERATION" should be made.
        !          2470: For \verb"SDataRequest",
        !          2471: this would occur when the data token was not owned by the user;
        !          2472: for \verb"SRelRequest",
        !          2473: this would occur when the release token was not owned by the user.
        !          2474: \clearpage
        !          2475: \tagrind[tp]{grind5b-3a}{Initializing the SSAP source entity}{initSSsource}
        !          2476: \clearpage
        !          2477: \tagrind[tp]{grind5b-3b}{Initializing the SSAP source entity (continued)}\empty
        !          2478: \clearpage
        !          2479: \tagrind[tp]{grind5b-4}{Data Transfer for the SSAP source entity}%
        !          2480:        {dataSSsource}.
        !          2481: 
        !          2482: \section      {For Further Reading}
        !          2483: The ISO specification for session services is defined in
        !          2484: \cite{ISO.SP.Service},
        !          2485: while the complementary CCITT recommendation is defined in
        !          2486: \cite{CCITT.SP.Service}.
        !          2487: The corresponding protocol definitions are \cite{ISO.SP.Protocol} and
        !          2488: \cite{CCITT.SP.Protocol}, respectively.
        !          2489: 
        !          2490: %%% \section  {Changes Since the Last Release}\label{ssap:changes}
        !          2491: %%% A brief summary of the major changes between v~\ssaprevrsn/ and
        !          2492: %%% v~\ssapvrsn/ are now presented.
        !          2493: %%% These are the user-visible changes only;
        !          2494: %%% changes of a strictly internal nature are not discussed.
        !          2495: 

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