Return to appendix2.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {Old-Style Associations}\label{old-style}
        !             4: As discussed in Section~\ref{acs:note},
        !             5: there are several ways to establish an association.
        !             6: In the interests of compatibility with previously specified applications,
        !             7: the \man librosap(3n) and \man librtsap(3n) libraries support ``old-style''
        !             8: mechanisms for binding associations.
        !             9: These are discussed in this appendix.
        !            10: Use of these facilities for new applications is strongly discouraged.
        !            11: 
        !            12: \section      {Remote Operations}\label{ros:old-style}
        !            13: Under old-style association handling for remote operations,
        !            14: the mechanism used for establishing the association determines the
        !            15: remote operations service discipline to be used.
        !            16: If the basic service discipline is desired,
        !            17: then continue reading this section which describes the addressing and
        !            18: initialization mechanisms for native ROS associations.
        !            19: These make use of the {\sf RO-BEGIN\/} and {\sf RO-END\/} primitives.
        !            20: Instead,
        !            21: if the advanced service discipline is desired,
        !            22: then read Section~\ref{rts:old-style} on page~\pageref{rts:old-style}
        !            23: which describes how
        !            24: associations are established and released by the reliable transfer service
        !            25: (RTS) using the {\sf X.410 OPEN\/} and {\sf X.410 CLOSE\/} primitives.
        !            26: (Be sure to also read Section~\ref{ros:underlying} on
        !            27: page~\pageref{ros:underlying}).
        !            28: 
        !            29: \subsection    {Addresses}
        !            30: Addresses at the remote operations service access point are represented by the
        !            31: \verb"RoSAPaddr" structure.
        !            32: \begin{quote}\index{RoSAPaddr}\small\begin{verbatim}
        !            33: struct RoSAPaddr {
        !            34:     struct SSAPaddr roa_addr;
        !            35: 
        !            36:     u_short     roa_port;
        !            37: };
        !            38: \end{verbatim}\end{quote}
        !            39: This structure contains two elements:
        !            40: \begin{describe}
        !            41: \item[\verb"roa\_addr":]       the session address,
        !            42: as described in Section~\ref{ssap:addresses} on page~\pageref{ssap:addresses}
        !            43: of \voltwo/;
        !            44: and,
        !            45: 
        !            46: \item[\verb"roa\_port":] the port number of the entity residing above the
        !            47: RoSAP,
        !            48: as described in the \man isoservices(5) database,
        !            49: for the service provider \verb"rosap".
        !            50: \end{describe}
        !            51: 
        !            52: In Figure~\ref{getDSentity},
        !            53: an example of how one constructs the RoSAP address for the directory services
        !            54: entity on host \verb"RemoteHost" is presented.
        !            55: (The routine \verb"is2saddr" is described on page~\pageref{ssap:addresses}
        !            56: of \voltwo/.)
        !            57: \tagrind[tp]{grindB-1}%
        !            58:         {Constructing the RoSAP address for the Directory Services entity}%
        !            59:         {getDSentity}
        !            60: 
        !            61: \subsection       {Association Establishment}
        !            62: The \man librosap(3n) library distinguishes between the user which started an
        !            63: association,
        !            64: the {\em initiator},
        !            65: and the user which subsequently was bound to the association,
        !            66: the {\em responder}.
        !            67: We sometimes term these two entities the {\em client\/} and the {\em server},
        !            68: respectively.
        !            69: 
        !            70: \subsubsection     {Server Initialization}
        !            71: The \man tsapd(8c) daemon,
        !            72: upon accepting a connection from an initiating host,
        !            73: consults the ISO services database to determine which program
        !            74: on the local system implements the desired RoSAP entity.
        !            75: In the case of the remote operations service,
        !            76: the \pgm{tsapd} program contains the bootstrap for the remote operations
        !            77: provider.
        !            78: The daemon will again consult the ISO services database to determine which
        !            79: program on the system implements the desired RoSAP entity.
        !            80: 
        !            81: Once the program has been ascertained,
        !            82: the daemon runs the program with any arguments listed in the database.
        !            83: In addition,
        !            84: it appends some {\em magic arguments\/} to the argument vector.
        !            85: Hence,
        !            86: the very first action performed by the responder is to re-capture the RoSAP
        !            87: state contained in the magic arguments.
        !            88: This is done by calling the routine \verb"RoInit",
        !            89: which on a successful return,
        !            90: is equivalent to a {\sf RO-BEGIN.INDICATION\/} from the remote operations
        !            91: service provider.
        !            92: \begin{quote}\index{RoInit}\small\begin{verbatim}
        !            93: int     RoInit (vecp, vec, ros, roi)
        !            94: int     vecp;
        !            95: char  **vec;
        !            96: struct RoSAPstart *ros;
        !            97: struct RoSAPindication *roi;
        !            98: \end{verbatim}\end{quote}
        !            99: The parameters to this procedure are:
        !           100: \begin{describe}
        !           101: \item[\verb"vecp":] the length of the argument vector;
        !           102: 
        !           103: \item[\verb"vec":] the argument vector;
        !           104: 
        !           105: \item[\verb"ros":] a pointer to a \verb"RoSAPstart" structure, which is
        !           106: updated only if the call succeeds;
        !           107: and,
        !           108: 
        !           109: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           110: updated only if the call fails.
        !           111: \end{describe}
        !           112: If \verb"RoInit" is successful,
        !           113: it returns information in the \verb"ros" parameter,
        !           114: which is a pointer to a \verb"RoSAPstart" structure.
        !           115: \begin{quote}\index{RoSAPstart}\small\begin{verbatim}
        !           116: struct RoSAPstart {
        !           117:     int     ros_sd;
        !           118: 
        !           119:     struct RoSAPaddr ros_initiator;
        !           120: 
        !           121:     u_short ros_port;
        !           122: 
        !           123:     PE      ros_data;
        !           124: };
        !           125: \end{verbatim}\end{quote}
        !           126: The elements of this structure are:
        !           127: \begin{describe}
        !           128: \item[\verb"ros\_sd":] the association-descriptor to be used to
        !           129: reference this association;
        !           130: 
        !           131: \item[\verb"ros\_initiator":] the ``unique identifier'' of the initiator
        !           132: (containing the initiator's host address);
        !           133: 
        !           134: \item[\verb"ros\_port":] the application number the initiator wishes to use
        !           135: to govern the association;
        !           136: and
        !           137: 
        !           138: \item[\verb"ros\_data":] any initial data (this is a pointer to a
        !           139: \verb"PElement" structure, which is fully explained in Chapter~\ref{libpsap}).
        !           140: \end{describe}
        !           141: Note that the \verb"ros_data" element is allocated via \man malloc(3) and
        !           142: should be released using the \verb"ROSFREE" macro  when no longer referenced.
        !           143: The \verb"ROSFREE" macro behaves as if it was defined as:
        !           144: \begin{quote}\index{ROSFREE}\small\begin{verbatim}
        !           145: void    ROSFREE (ros)
        !           146: struct RoSAPstart *ros;
        !           147: \end{verbatim}\end{quote}
        !           148: The macro frees only the data allocated by \verb"RoInit",
        !           149: and not the \verb"RoSAPstart" structure itself.
        !           150: Further,
        !           151: \verb"ROSFREE" should be called only if the call to the \verb"RoInit"
        !           152: routine returned \verb"OK".
        !           153: 
        !           154: If the call to \verb"RoInit" is not successful,
        !           155: then a {\sf RO-P-REJECT.IN\-DI\-CA\-TION\/} event is simulated,
        !           156: and the relevant information is returned in an encoded
        !           157: \verb"RoSAPindication" structure.
        !           158: 
        !           159: After examining the information returned by \verb"RoInit" on a successful call
        !           160: (and possibly after examining the argument vector),
        !           161: the responder should either accept or reject the association.
        !           162: For either response,
        !           163: the responder should use
        !           164: the \verb"RoBeginResponse" routine
        !           165: (which corresponds to the {\sf RO-BEGIN.RESPONSE\/} action).
        !           166: \begin{quote}\index{RoBeginResponse}\small\begin{verbatim}
        !           167: int     RoBeginResponse (sd, status, data, roi)
        !           168: int     sd;
        !           169: int     status;
        !           170: PE      data;
        !           171: struct RoSAPindication *roi;
        !           172: \end{verbatim}\end{quote}
        !           173: The parameters to this procedure are:
        !           174: \begin{describe}
        !           175: \item[\verb"sd":] the association-descriptor;
        !           176: 
        !           177: \item[\verb"status":] the acceptance indicator
        !           178: (either \verb"ROS_ACCEPT" if the association is to be accepted,
        !           179: or one of the ``fatal'' user-initiated rejection codes listed in
        !           180: Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons});
        !           181: 
        !           182: \item[\verb"data":] any initial data if the association is to be accepted;
        !           183: and,
        !           184: 
        !           185: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           186: updated only if the call fails.
        !           187: \end{describe}
        !           188: If the call to \verb"RoBeginResponse" is successful,
        !           189: and the \verb"status" parameter is set to \verb"ROS_ACCEPT",
        !           190: then association establishment has now been completed.
        !           191: If the call is successful,
        !           192: but the \verb"status" parameter is not \verb"ROS_ACCEPT",
        !           193: then the association has been rejected and the responder may exit.
        !           194: Otherwise,
        !           195: if the call fails and the reason is ``fatal'',
        !           196: then the association is closed.
        !           197: 
        !           198: \subsubsection     {Client Initialization}
        !           199: A program wishing to associate itself with another user of remote operation
        !           200: services calls the \verb"RoBeginRequest" routine,
        !           201: which corresponds to the {\sf RO-BEGIN.REQUEST\/} action.
        !           202: \begin{quote}\index{RoBeginRequest}\small\begin{verbatim}
        !           203: int     RoBeginRequest (called, data, roc, roi)
        !           204: struct  RoSAPaddr *called;
        !           205: PE      data;
        !           206: struct RoSAPconnect *roc;
        !           207: struct RoSAPindication *roi;
        !           208: \end{verbatim}\end{quote}
        !           209: The parameters to this procedure are:
        !           210: \begin{describe}
        !           211: \item[\verb"called":] the RoSAP address of the responder;
        !           212: 
        !           213: \item[\verb"data":] any initial data;
        !           214: 
        !           215: \item[\verb"roc":] a pointer to a \verb"RoSAPconnect" structure, which is
        !           216: updated only if the call succeeds;
        !           217: and,
        !           218: 
        !           219: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           220: updated only if the call fails.
        !           221: \end{describe}
        !           222: If the call to \verb"RoBeginRequest" is successful
        !           223: (this corresponds to a {\sf RO-BEGIN.CONFIRMATION\/} event),
        !           224: it returns information in the \verb"roc" parameter,
        !           225: which is a pointer to a \verb"RoSAPconnect" structure.
        !           226: \begin{quote}\index{RoSAPconnect}\small\begin{verbatim}
        !           227: struct RoSAPconnect {
        !           228:     int     roc_sd;
        !           229: 
        !           230:     int     roc_result;
        !           231: 
        !           232:     PE      roc_data;
        !           233: };
        !           234: \end{verbatim}\end{quote}
        !           235: The elements of this structure are:
        !           236: \begin{describe}
        !           237: \item[\verb"roc\_sd":] the association-descriptor to be used to
        !           238: reference this association;
        !           239: 
        !           240: \item[\verb"roc\_result":] the association response;
        !           241: and,
        !           242: 
        !           243: \item[\verb"roc\_data":] any initial data if the association was accepted.
        !           244: \end{describe}
        !           245: If the call to \verb"RoBeginRequest" is successful,
        !           246: and the \verb"roc_result" element is set to \verb"ROS_ACCEPT",
        !           247: then association establishment has completed.
        !           248: If the call is successful,
        !           249: but the \verb"roc_result" element is not \verb"ROS_ACCEPT",
        !           250: the the association attempt has been rejected,
        !           251: consult Table~\ref{RoSAPreasons} to determine the reason for the reject.
        !           252: Otherwise, if the call fails then the association is not established and
        !           253: the \verb"RoSAPpreject" structure of the \verb"RoSAPindication" discriminated
        !           254: union has been updated.
        !           255: 
        !           256: Note that the \verb"roc_data" element is allocated via \man malloc(3) and
        !           257: should be released using the \verb"ROCFREE" macro  when no longer referenced.
        !           258: The \verb"ROCFREE" macro behaves as if it was defined as:
        !           259: \begin{quote}\index{ROCFREE}\small\begin{verbatim}
        !           260: void    ROCFREE (roc)
        !           261: struct RoSAPconnect *roc;
        !           262: \end{verbatim}\end{quote}
        !           263: The macro frees only the data allocated by \verb"RoBeginRequest",
        !           264: and not the \verb"RoSAPconnect" structure itself.
        !           265: Further,
        !           266: \verb"ROCFREE" should be called only if the call to the \verb"RoBeginRequest"
        !           267: routine returned \verb"OK".
        !           268: 
        !           269: Note that in the basic service the arguement parameter to an Invoke request
        !           270: cannot be NULL.
        !           271: As well only the initiator may make invoke requests.
        !           272: 
        !           273: \subsection       {Association Release}
        !           274: The \verb"RoEndRequest" routine is used to request the release of an
        !           275: association,
        !           276: and corresponds to a {\sf RO-END.REQUEST\/} action.
        !           277: This action may be taken by only the initiator of an association.
        !           278: \begin{quote}\index{RoEndRequest}\small\begin{verbatim}
        !           279: int     RoEndRequest (sd, priority, roi)
        !           280: int     sd;
        !           281: int     priority;
        !           282: struct RoSAPindication *roi;
        !           283: \end{verbatim}\end{quote}
        !           284: The parameters to this procedure are:
        !           285: \begin{describe}
        !           286: \item[\verb"sd":] the association-descriptor;
        !           287: 
        !           288: \item[\verb"priority":] the priority of this request;
        !           289: and,
        !           290: 
        !           291: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           292: updated only if the call fails.
        !           293: \end{describe}
        !           294: If the call to \verb"RoEndRequest" is successful,
        !           295: then the association has been released.
        !           296: Otherwise if the call fails and the error is not fatal,
        !           297: then the association remains established and the \verb"RoSAPpreject" structure
        !           298: contained in
        !           299: the \verb"RoSAPindication" parameter \verb"roi" contains the reason for the
        !           300: failure.
        !           301: 
        !           302: Upon receiving a {\sf RO-END.INDICATION\/} event,
        !           303: the user is required to generate a {\sf RO-END.RESPONSE\/} action
        !           304: using the \verb"RoEndResponse" routine.
        !           305: \begin{quote}\index{RoEndResponse}\small\begin{verbatim}
        !           306: int     RoEndResponse (sd, roi)
        !           307: int     sd;
        !           308: struct RoSAPindication *roi;
        !           309: \end{verbatim}\end{quote}
        !           310: The parameters to this procedure are:
        !           311: \begin{describe}
        !           312: \item[\verb"sd":] the association-descriptor;
        !           313: and,
        !           314: 
        !           315: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           316: updated only if the call fails.
        !           317: \end{describe}
        !           318: If the call to \verb"RoEndResponse" is successful,
        !           319: then the association has been released.
        !           320: 
        !           321: \subsection    {An Example}
        !           322: Let's consider how one might construct a generic server which uses remote
        !           323: operations services.
        !           324: This entity will use an asynchronous interface and the basic service
        !           325: discipline.
        !           326: Note that we could have selected the advanced service discipline by using
        !           327: \verb"RtBInit" instead of \verb"RoInit",
        !           328: \verb"RtBeginResponse" instead of \verb"RoBeginResponse",
        !           329: and
        !           330: \verb"RtEndResponse" instead of \verb"RoEndResponse" (respectively).
        !           331: This is demonstrated later in this appendix.
        !           332: 
        !           333: There are two parts to the program:
        !           334: initialization and the request/reply loop.
        !           335: In our example,
        !           336: we assume that the routine \verb"error" results in the process being
        !           337: terminated after printing a diagnostic.
        !           338: 
        !           339: In Figure~\ref{initROS:OLDresponder},
        !           340: the initialization steps for the generic responder,
        !           341: including the outer {\em C\/} wrapper,
        !           342: is shown.
        !           343: First, the RoSAP state is re-captured by calling \verb"RoInit".
        !           344: If this succeeds,
        !           345: then the association is authenticated and any command line arguments (as
        !           346: specified in the \man isoservices(5) file) are parsed.
        !           347: Assuming that the responder is satisfied with the proposed association,
        !           348: it calls \verb"RoBeginResponse" to accept the association.
        !           349: Then,
        !           350: \verb"RoSetIndications" is set to specify an asynchronous event handler.
        !           351: Finally,
        !           352: the main request/reply loop is realized.
        !           353: The server simply uses \man pause(2) to wait for the next event.
        !           354: {\let\small=\scriptsize                        %%% yikes!
        !           355: \tagrind[tp]{grindB-2}{Initializing the generic ROS responder}%
        !           356:        {initROS:OLDresponder}}
        !           357: 
        !           358: Figure~\ref{doROSresponder} on page~\pageref{doROSresponder}
        !           359: contains the definition of the
        !           360: \verb"ros_indication" routine and associated routines.
        !           361: Since the remote operations service was used to establish the association,
        !           362: a different closing handler must be used.
        !           363: This is shown in Figure~\ref{finROS:OLDresponder}.
        !           364: {\let\small=\scriptsize                        %%% yikes!
        !           365: \tagrind[tp]{grindB-3}%
        !           366:        {Finalizing the generic ROS responder}{finROS:OLDresponder}}
        !           367: 
        !           368: \section      {Reliable Transfer}\label{rts:old-style}
        !           369: Under old-style association handling for reliable transfer,
        !           370: the {\sf X.410 OPEN\/} and {\sf X.410 CLOSE\/} primitives are used.
        !           371: 
        !           372: \subsection    {Addresses}
        !           373: Addresses at the reliable transfer service access point are represented by the
        !           374: \verb"RtSAPaddr" structure.
        !           375: \begin{quote}\index{RtSAPaddr}\small\begin{verbatim}
        !           376: struct RtSAPaddr {
        !           377:     struct SSAPaddr rta_addr;
        !           378: 
        !           379:     u_short     rta_port;
        !           380: };
        !           381: \end{verbatim}\end{quote}
        !           382: This structure contains two elements:
        !           383: \begin{describe}
        !           384: \item[\verb"rta\_addr":]       the session address,
        !           385: as described in Section~\ref{ssap:addresses} on page~\pageref{ssap:addresses}
        !           386: of \voltwo/;
        !           387: and,
        !           388: 
        !           389: \item[\verb"rta\_port":] the port number of the entity residing above the
        !           390: RtSAP,
        !           391: as described in the \man isoservices(5) database,
        !           392: for the service provider \verb"rtsap".
        !           393: \end{describe}
        !           394: 
        !           395: In Figure~\ref{getP1entity},
        !           396: an example of how one constructs the RtSAP address for the message transfer
        !           397: entity on host \verb"RemoteHost" is presented.
        !           398: (The routine \verb"is2saddr" is described on page~\pageref{ssap:addresses}
        !           399: of \voltwo/.)
        !           400: \tagrind[tp]{grindB-4}%
        !           401:         {Constructing the RtSAP address for the Message Transfer entity}%
        !           402:         {getP1entity}
        !           403: 
        !           404: \subsection       {Association Establishment}
        !           405: The \man librtsap(3n) library distinguishes between the user which started an
        !           406: association,
        !           407: the {\em initiator},
        !           408: and the user which was subsequently bound to the association,
        !           409: the {\em responder}.
        !           410: We sometimes term these two entities the {\em client\/} and the {\em server},
        !           411: respectively.
        !           412: 
        !           413: \subsubsection     {Server Initialization}
        !           414: The \man tsapd(8c) daemon,
        !           415: upon accepting a connection from an initiating host,
        !           416: consults the ISO services database to determine which program
        !           417: on the local system implements the desired SSAP entity.
        !           418: In the case of the reliable transfer service,
        !           419: the \pgm{tsapd} program contains the bootstrap for the reliable transfer
        !           420: provider.
        !           421: The daemon will again consult the ISO services database to determine which
        !           422: program on the system implements the desired RtSAP entity.
        !           423: 
        !           424: Once the program has been ascertained,
        !           425: the daemon runs the program with any arguments listed in the database.
        !           426: In addition,
        !           427: it appends some {\em magic arguments\/} to the argument vector.
        !           428: Hence,
        !           429: the very first action performed by the responder is to re-capture the RtSAP
        !           430: state contained in the magic arguments.
        !           431: This is done by calling the routine \verb"RtBInit",
        !           432: which on a successful return,
        !           433: is equivalent to a {\sf X.410 OPEN.INDICATION\/} from the reliable transfer
        !           434: service provider.
        !           435: \begin{quote}\index{RtBInit}\small\begin{verbatim}
        !           436: int     RtBInit (vecp, vec, rts, rti)
        !           437: int     vecp;
        !           438: char  **vec;
        !           439: struct RtSAPstart *rts;
        !           440: struct RtSAPindication *rti;
        !           441: \end{verbatim}\end{quote}
        !           442: The parameters to this procedure are:
        !           443: \begin{describe}
        !           444: \item[\verb"vecp":] the length of the argument vector;
        !           445: 
        !           446: \item[\verb"vec":] the argument vector;
        !           447: 
        !           448: \item[\verb"rts":] a pointer to a \verb"RtSAPstart" structure, which is
        !           449: updated only if the call succeeds;
        !           450: and,
        !           451: 
        !           452: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
        !           453: updated only if the call fails.
        !           454: \end{describe}
        !           455: If \verb"RtBInit" is successful,
        !           456: it returns information in the \verb"rts" parameter,
        !           457: which is a pointer to a \verb"RtSAPstart" structure.
        !           458: \begin{quote}\index{RtSAPstart}\small\begin{verbatim}
        !           459: struct RtSAPstart {
        !           460:     int     rts_sd;
        !           461: 
        !           462:     struct RtSAPaddr rts_initiator;
        !           463: 
        !           464:     int     rts_mode;
        !           465: #define RTS_MONOLOGUE   0
        !           466: #define RTS_TWA         1
        !           467: 
        !           468:     int     rts_turn;
        !           469: #define RTS_INITIATOR   0
        !           470: #define RTS_RESPONDER   1
        !           471: 
        !           472:     u_short rts_port;
        !           473: 
        !           474:     PE      rts_data;
        !           475: };
        !           476: \end{verbatim}\end{quote}
        !           477: The elements of this structure are:
        !           478: \begin{describe}
        !           479: \item[\verb"rts\_sd":] the association-descriptor to be used to
        !           480: reference this association;
        !           481: 
        !           482: \item[\verb"rts\_initiator":] the address of the initiator;
        !           483: 
        !           484: \item[\verb"rts\_mode":] the dialogue mode (either monologue or two-way
        !           485: alternate),
        !           486: 
        !           487: \item[\verb"rts\_turn":] the owner of the turn initially;
        !           488: 
        !           489: \item[\verb"rts\_port":] the application number the initiator wishes to use
        !           490: to govern the association;
        !           491: and
        !           492: 
        !           493: \item[\verb"rts\_data":] any initial data (this is a pointer to a
        !           494: \verb"PElement" structure, which is fully explained in Chapter~\ref{libpsap}).
        !           495: \end{describe}
        !           496: Note that the \verb"rts_data" element is allocated via \man malloc(3) and
        !           497: should be released by using the \verb"RTSFREE" macro when no longer referenced.
        !           498: The \verb"RTSFREE" macro behaves as if it was defined as:
        !           499: \begin{quote}\index{RTSFREE}\small\begin{verbatim}
        !           500: void    RTSFREE (rts)
        !           501: struct RtSAPstart *rts;
        !           502: \end{verbatim}\end{quote}
        !           503: The macro frees only the data allocated by \verb"RtBInit",
        !           504: and not the \verb"RtSAPstart" structure itself.
        !           505: Further,
        !           506: \verb"RTSFREE" should be called only if the call to the \verb"RtBInit"
        !           507: routine returned \verb"OK".
        !           508: 
        !           509: If the call to \verb"RtBInit" is not successful,
        !           510: then a {\sf RT-P-ABORT.INDICATION\/} event is simulated,
        !           511: and the relevant information is returned in an encoded
        !           512: \verb"RtSAPindication" structure.
        !           513: 
        !           514: After examining the information returned by \verb"RtBInit" on a successful call
        !           515: (and possibly after examining the argument vector),
        !           516: the responder should either accept or reject the association.
        !           517: For either response,
        !           518: the responder should use
        !           519: the \verb"RtBeginResponse" routine
        !           520: (which corresponds to the {\sf X.410 OPEN.RESPONSE\/} action).
        !           521: \begin{quote}\index{RtBeginResponse}\small\begin{verbatim}
        !           522: int     RtBeginResponse (sd, status, data, rti)
        !           523: int     sd;
        !           524: int     status;
        !           525: PE      data;
        !           526: struct RtSAPindication *rti;
        !           527: \end{verbatim}\end{quote}
        !           528: The parameters to this procedure are:
        !           529: \begin{describe}
        !           530: \item[\verb"sd":] the association-descriptor;
        !           531: 
        !           532: \item[\verb"status":] the acceptance indicator
        !           533: (either \verb"RTS_ACCEPT" if the association is to be accepted,
        !           534: or one of the ``fatal'' user-initiated rejection codes,
        !           535: other tha \verb"RTS_REJECT",
        !           536: listed in Table~\ref{RtSAPreasons} on page~\pageref{RtSAPreasons});
        !           537: 
        !           538: \item[\verb"data":] any initial data if the association is to be accepted;
        !           539: and,
        !           540: 
        !           541: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
        !           542: updated only if the call fails.
        !           543: \end{describe}
        !           544: If the call to \verb"RtBeginResponse" is successful,
        !           545: and the \verb"status" parameter is set to \verb"RTS_ACCEPT",
        !           546: then association establishment has now been completed.
        !           547: If the call is successful,
        !           548: but the \verb"status" parameter is not \verb"RTS_ACCEPT",
        !           549: then the association has been rejected and the responder may exit.
        !           550: Otherwise,
        !           551: if the call fails and the reason is ``fatal'',
        !           552: then the association is closed.
        !           553: 
        !           554: \subsubsection     {Client Initialization}
        !           555: A program wishing to associate itself with another user of reliable transfer
        !           556: services calls the \verb"RtBeginRequest" routine,
        !           557: which corresponds to the {\sf X.410 OPEN.REQUEST\/} action.
        !           558: \begin{quote}\index{RtBeginRequest}\small\begin{verbatim}
        !           559: int     RtBeginRequest (called, mode, turn, data, rtc, rti)
        !           560: struct  RtSAPaddr *called;
        !           561: int     mode,
        !           562:         turn;
        !           563: PE      data;
        !           564: struct RtSAPconnect *rtc;
        !           565: struct RtSAPindication *rti;
        !           566: \end{verbatim}\end{quote}
        !           567: The parameters to this procedure are:
        !           568: \begin{describe}
        !           569: \item[\verb"called":] the RtSAP address of the responder;
        !           570: 
        !           571: \item[\verb"mode":] the dialogue mode;
        !           572: 
        !           573: \item[\verb"turn":] who gets the initial turn;
        !           574: 
        !           575: \item[\verb"data":] any initial data;
        !           576: 
        !           577: \item[\verb"rtc":] a pointer to a \verb"RtSAPconnect" structure, which is
        !           578: updated only if the call succeeds;
        !           579: and,
        !           580: 
        !           581: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
        !           582: updated only if the call fails.
        !           583: \end{describe}
        !           584: If the call to \verb"RtBeginRequest" is successful
        !           585: (this corresponds to a {\sf X.410 OPEN.CONFIRMATION\/} event),
        !           586: it returns information in the \verb"rtc" parameter,
        !           587: which is a pointer to a \verb"RtSAPconnect" structure.
        !           588: \begin{quote}\index{RtSAPconnect}\small\begin{verbatim}
        !           589: struct RtSAPconnect {
        !           590:     int     rtc_sd;
        !           591: 
        !           592:     int     rtc_result;
        !           593: 
        !           594:     PE      rtc_data;
        !           595: };
        !           596: \end{verbatim}\end{quote}
        !           597: The elements of this structure are:
        !           598: \begin{describe}
        !           599: \item[\verb"rtc\_sd":] the association-descriptor to be used to
        !           600: reference this association;
        !           601: 
        !           602: \item[\verb"rtc\_result":] the association response;
        !           603: and,
        !           604: 
        !           605: \item[\verb"rtc\_data":] any initial data if the association was accepted.
        !           606: \end{describe}
        !           607: If the call to \verb"RtBeginRequest" is successful,
        !           608: and the \verb"rtc_result" element is set to \verb"RTS_ACCEPT",
        !           609: then association establishment has completed.
        !           610: If the call is successful,
        !           611: but the \verb"rtc_result" element is not \verb"RTS_ACCEPT",
        !           612: the the association attempt has been rejected;
        !           613: consult Table~\ref{RtSAPreasons} to determine the reason for the reject.
        !           614: Otherwise, if the call fails then the association is not established and
        !           615: the \verb"RtSAPabort" structure of the \verb"RtSAPindication" discriminated
        !           616: union has been updated.
        !           617: 
        !           618: Note that the \verb"rtc_data" element is allocated via \man malloc(3) and
        !           619: should be released using the \verb"RTCFREE" macro  when no longer referenced.
        !           620: The \verb"RTCFREE" macro behaves as if it was defined as:
        !           621: \begin{quote}\index{RTCFREE}\small\begin{verbatim}
        !           622: void    RTCFREE (rtc)
        !           623: struct RtSAPconnect *rtc;
        !           624: \end{verbatim}\end{quote}
        !           625: The macro frees only the data allocated by \verb"RtBeginRequest",
        !           626: and not the \verb"RtSAPconnect" structure itself.
        !           627: Further,
        !           628: \verb"RTCFREE" should be called only if the call to the \verb"RtBeginRequest"
        !           629: routine returned \verb"OK".
        !           630: 
        !           631: \subsection       {Association Release}
        !           632: The \verb"RtEndRequest" routine is used to request the release of an
        !           633: association,
        !           634: and corresponds to a {\sf X.410 CLOSE.REQUEST\/} action.
        !           635: This action may be taken by only the initiator of an association,
        !           636: and, if the dialogue mode is two-way alternate,
        !           637: if the initiator has the turn as well.
        !           638: \begin{quote}\index{RtEndRequest}\small\begin{verbatim}
        !           639: int     RtEndRequest (sd, rti)
        !           640: int     sd;
        !           641: struct RtSAPindication *rti;
        !           642: \end{verbatim}\end{quote}
        !           643: The parameters to this procedure are:
        !           644: \begin{describe}
        !           645: \item[\verb"sd":] the association-descriptor;
        !           646: and,
        !           647: 
        !           648: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
        !           649: updated only if the call fails.
        !           650: \end{describe}
        !           651: If the call to \verb"RtEndRequest" is successful,
        !           652: then the association has been released.
        !           653: Otherwise if the call fails and the error is not fatal,
        !           654: then the association remains established and the \verb"RtSAPabort" structure
        !           655: contained in
        !           656: the \verb"RtSAPindication" parameter \verb"rti" contains the reason for the
        !           657: failure.
        !           658: 
        !           659: Upon receiving a {\sf X.410 CLOSE.INDICATION\/} event,
        !           660: the user is required to generate a {\sf X.410 CLOSE.RESPONSE\/} action
        !           661: using the \verb"RtEndResponse" routine.
        !           662: \begin{quote}\index{RoEndResponse}\small\begin{verbatim}
        !           663: int     RtEndResponse (sd, rti)
        !           664: int     sd;
        !           665: struct RtSAPindication *rti;
        !           666: \end{verbatim}\end{quote}
        !           667: The parameters to this procedure are:
        !           668: \begin{describe}
        !           669: \item[\verb"sd":] the association-descriptor;
        !           670: and,
        !           671: 
        !           672: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
        !           673: updated only if the call fails.
        !           674: \end{describe}
        !           675: If the call to \verb"RtEndResponse" is successful,
        !           676: then the association has been released.
        !           677: 
        !           678: \subsection    {An Example}
        !           679: Let's consider how one might construct a generic server that uses
        !           680: reliable transfer services to establish an association,
        !           681: but then uses remote operation services to communicate with its peer.
        !           682: This entity will use a synchronous interface.
        !           683: 
        !           684: There are two parts to the program:
        !           685: initialization and the request/reply loop.
        !           686: In our example,
        !           687: we assume that the routine \verb"error" results in the process being
        !           688: terminated after printing a diagnostic.
        !           689: 
        !           690: In Figure~\ref{initRTS:OLDresponder},
        !           691: the initialization steps for the generic responder,
        !           692: including the outer {\em C\/} wrapper,
        !           693: is shown.
        !           694: First, the RtSAP state is re-captured by calling \verb"RtBInit".
        !           695: If this succeeds,
        !           696: then the association is authenticated and any command line arguments (as
        !           697: specified in the \man isoservices(5) file) are parsed.
        !           698: Assuming that the responder is satisfied with the proposed association,
        !           699: it calls \verb"RtBeginResponse" to accept the association.
        !           700: The \verb"RoSetService" routine is called to set the underlying service to be
        !           701: used for remote operations.
        !           702: Finally,
        !           703: the main request/reply loop is realized.
        !           704: The responder calls \verb"RoWaitRequest" to get the next event,
        !           705: and then calls \verb"ros_indication" to decode that event.
        !           706: {\let\small=\scriptsize                        %%% yikes!
        !           707: \tagrind[tp]{grindB-5}{Initializing the generic RTS responder}%
        !           708:        {initRTS:OLDresponder}}
        !           709: 
        !           710: Figure~\ref{doROSresponder} on page~\pageref{doROSresponder}
        !           711: contains the definition of the
        !           712: \verb"ros_indication" routine and associated routines.
        !           713: Since the reliable transfer service was used to establish the association,
        !           714: a different closing handler must be used.
        !           715: This is shown in Figure~\ref{finRTS:OLDresponder}.
        !           716: {\let\small=\scriptsize                        %%% yikes!
        !           717: \tagrind[tp]{grindB-6}{Finalizing the generic RTS responder}%
        !           718:        {finRTS:OLDresponder}}

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