Return to rosap.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter       {Remote Operations}\label{librosap}
        !             4: The \man librosap(3n) library implements the Remote Operations Service (ROS).
        !             5: Three service disciplines are implemented:
        !             6: when the ECMA interpretation of the ROS is used,
        !             7: we term this the {\em basic\/} service discipline;
        !             8: when the CCITT X.400 interpretation is used,
        !             9: we term this the {\em advanced\/} service discipline;
        !            10: and,
        !            11: when the new ISO and CCITT MOTIS interpretation is used,
        !            12: we term this the {\em complete\/} service discipline.
        !            13: The advanced discipline is somewhat less restrictive than the basic
        !            14: discipline,
        !            15: at the cost of requiring a more complex implementation on the part of both
        !            16: the provider and the user.
        !            17: The complete discipline, in addition to all of the facilities provided by the
        !            18: advanced discipline, also supports the notion of {\em linked\/} operations.
        !            19: 
        !            20: The abstraction provided to applications is that of an {\em association\/}
        !            21: for remote operations.
        !            22: An association is a binding between two users:
        !            23: the {\em initiator\/} of the association,
        !            24: and the {\em responder\/} to the association.
        !            25: Once an association is established,
        !            26: the initiator requests the responder to perform remote operations.
        !            27: The responder in turn attempts these operations,
        !            28: replying with either a result or an error.
        !            29: This process continues until the initiator decides to release the association.
        !            30: 
        !            31: Like most models of OSI services,
        !            32: the underlying assumption is one of an asynchronous environment:
        !            33: the service provider may generate events for the service user without the
        !            34: latter entity triggering the actions which led to the event.
        !            35: For example,
        !            36: in a synchronous environment,
        !            37: an indication that data has arrived usually occurs only when the service user
        !            38: asks the service provider to read data;
        !            39: in an asynchronous environment,
        !            40: the service provider may interrupt the service user at any time to announce
        !            41: the arrival of data.
        !            42: 
        !            43: The \verb"rosap" module in this release presents a synchronous interface.
        !            44: However once the association is established,
        !            45: an asynchronous interface may be selected.
        !            46: 
        !            47: All of the routines in the \man librosap(3n) library are integer-valued.
        !            48: They return the manifest constant \verb"OK" on success,
        !            49: or \verb"NOTOK" otherwise.
        !            50: 
        !            51: \section      {Notice}
        !            52: Please read the following important message.
        !            53: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !            54: \bf NOTE:&     The interface described herein is a ``raw'' interface to the
        !            55:                remote operations service.
        !            56:                Consult \volfour/ for a ``cooked'' interface.
        !            57: \end{tabular}}\]
        !            58: 
        !            59: \section      {Service Disciplines and Associations}\label{ros:disciplines}
        !            60: There are three service disciplines for remote operations:
        !            61: {\em basic}, {\em remote}, and {\em complete}.
        !            62: The basic service discipline limits its users by permitting only the
        !            63: initiator to invoke remote operations.
        !            64: Certain applications,
        !            65: e.g., message handling systems,
        !            66: require more freedom than this,
        !            67: along with more reliability.
        !            68: 
        !            69: The Remote Operations Service Element does not establish associations.
        !            70: Consult Section~\ref{acs:note} to determine which mechanism you should use to
        !            71: manage associations for your application.
        !            72: Since the advanced and complete disciplines are both proper supersets of the
        !            73: basic service discipline,
        !            74: two users of an association can utilize exactly the features of the basic
        !            75: service discipline even though the advanced or complete service discipline has
        !            76: been selected,
        !            77: without a loss of generality.
        !            78: 
        !            79: \section       {Remote Operations}\label{ros:operations}
        !            80: Once the association has been established,
        !            81: an association-descriptor is used to reference the association.
        !            82: This is usually the first parameter given to any of the remaining routines in
        !            83: the \man librosap(3n) library.
        !            84: Further,
        !            85: the last parameter is usually a pointer to a \verb"RoSAPindication"
        !            86: structure.
        !            87: If a call to one of these routines fails,
        !            88: then the structure is updated.
        !            89: \begin{quote}\index{RoSAPindication}\small\begin{verbatim}
        !            90: struct RoSAPindication {
        !            91:     int     roi_type;
        !            92: #define ROI_INVOKE      0x00
        !            93: #define ROI_RESULT      0x01
        !            94: #define ROI_ERROR       0x02
        !            95: #define ROI_UREJECT     0x03
        !            96: #define ROI_PREJECT     0x04
        !            97: #define ROI_END         0x05
        !            98: #define ROI_FINISH      0x06
        !            99: 
        !           100:     union {
        !           101:         struct RoSAPinvoke roi_un_invoke;
        !           102:         struct RoSAPresult roi_un_result;
        !           103:         struct RoSAPerror roi_un_error;
        !           104:         struct RoSAPureject roi_un_ureject;
        !           105:         struct RoSAPpreject roi_un_preject;
        !           106:         struct RoSAPend roi_un_end;
        !           107:         struct AcSAPfinish roi_un_finish;
        !           108:     }   roi_un;
        !           109: #define roi_invoke      roi_un.roi_un_invoke
        !           110: #define roi_result      roi_un.roi_un_result
        !           111: #define roi_error       roi_un.roi_un_error
        !           112: #define roi_ureject     roi_un.roi_un_ureject
        !           113: #define roi_preject     roi_un.roi_un_preject
        !           114: #define roi_end         roi_un.roi_un_end
        !           115: #define roi_finish      roi_un.roi_un_finish
        !           116: };
        !           117: \end{verbatim}\end{quote}
        !           118: As shown, this structure is really a discriminated union
        !           119: (a structure with a tag element followed by a union).
        !           120: Hence, on a failure return,
        !           121: one first coerces a pointer to the \verb"RoSAPpreject" structure contained
        !           122: therein,
        !           123: and then consults the elements of that structure.
        !           124: \begin{quote}\index{RoSAPpreject}\small\begin{verbatim}
        !           125: struct RoSAPpreject {
        !           126:     int     rop_reason;
        !           127: 
        !           128:     int     rop_id;
        !           129:     PE      rop_apdu;
        !           130: 
        !           131: #define ROP_SIZE        512
        !           132:     int     rop_cc;
        !           133:     char    rop_data[ROP_SIZE];
        !           134: };
        !           135: \end{verbatim}\end{quote}
        !           136: The elements of a \verb"RoSAPpreject" structure are:
        !           137: \begin{describe}
        !           138: \item[\verb"rop\_reason":] the reason for the provider-initiated reject
        !           139: (codes are listed in Table~\ref{RoSAPreasons}),
        !           140: 
        !           141: \item[\verb"rop\_id"/\verb"rop\_apdu":] if an APDU could not be transferred
        !           142: (\verb"rop_reason" is \verb"ROS_APDU"), then this is the invocation ID
        !           143: of the APDU and (possibly) the APDU itself, respectively;
        !           144: and,
        !           145: 
        !           146: \item[\verb"rop\_data"/\verb"rop\_cc":] a diagnostic string from the provider.
        !           147: \end{describe}
        !           148: \tagtable[tp]{2b-1a}{RoSAP Failure Codes}{RoSAPreasons}
        !           149: \tagtable[tp]{2b-1b}{RoSAP Failure Codes (continued)}\empty
        !           150: Note that the \verb"rop_apdu" element is allocated via \man malloc(3) and
        !           151: should be released using the \verb"ROPFREE" macro  when no longer referenced.
        !           152: The \verb"ROPFREE" macro behaves as if it was defined as:
        !           153: \begin{quote}\index{ROPFREE}\small\begin{verbatim}
        !           154: void    ROPFREE (rop)
        !           155: struct RoSAPpreject *rop;
        !           156: \end{verbatim}\end{quote}
        !           157: The macro frees only the data allocated in the \verb"RoSAPpreject" structure
        !           158: and not the structure itself.
        !           159: 
        !           160: On a failure return,
        !           161: if the \verb"rop_reason" element of the \verb"RoSAPpreject" structure is
        !           162: associated with a fatal error,
        !           163: the the association is released.
        !           164: The \verb"ROS_FATAL" macro can be used to determine this.
        !           165: \begin{quote}\index{ROS\_FATAL}\small\begin{verbatim}
        !           166: int     ROS_FATAL (r)
        !           167: int     r;
        !           168: \end{verbatim}\end{quote}
        !           169: For protocol purists,
        !           170: the \verb"ROS_OFFICIAL" macro can be used to determine if the error is an
        !           171: ``official'' error as defined by the specification,
        !           172: or an ``unofficial'' error used by the implementation.
        !           173: \begin{quote}\index{ROS\_OFFICIAL}\small\begin{verbatim}
        !           174: int     ROS_OFFICIAL (r)
        !           175: int     r;
        !           176: \end{verbatim}\end{quote}
        !           177: 
        !           178: Finally,
        !           179: some of these routines also take a \verb"priority" parameter indicating the
        !           180: relative importance of the remote operation.
        !           181: Under the basic service discipline,
        !           182: this parameter is ignored.
        !           183: Under the advanced or complete service discipline,
        !           184: each application decides on its own integer-valued definitions.
        !           185: The manifest constant \verb"ROS_NOPRIO" can be used if the application is
        !           186: unconcerned with the priority.
        !           187: 
        !           188: \subsection    {Selecting an Underlying Service}\label{ros:underlying}
        !           189: As should be obvious from Section~\ref{ros:disciplines},
        !           190: the \man librosap(3n) library supports the use of three different underlying
        !           191: services,
        !           192: depending on the method used to establish the association.
        !           193: The \man librosap(3n) library is constructed in such a way as to 
        !           194: avoid loading the object code for all three underlying services
        !           195: when only one is desired.
        !           196: In order to effect this,
        !           197: it is necessary to give the loader a small hint.
        !           198: 
        !           199: Once an association has been established,
        !           200: the \verb"RoSetService" routine should be called.
        !           201: \begin{quote}\index{RoSetService}\small\begin{verbatim}
        !           202: int     RoSetService (sd, bfunc, roi)
        !           203: int     sd;
        !           204: IFP     bfunc;
        !           205: struct RoSAPindication *roi;
        !           206: \end{verbatim}\end{quote}
        !           207: The parameters to this procedure are:
        !           208: \begin{describe}
        !           209: \item[\verb"sd":] the association-descriptor;
        !           210: 
        !           211: \item[\verb"bfunc":] a {\em magic\/} argument, use:
        !           212: \[\begin{tabular}{|l|l|l|}
        !           213: \hline
        !           214:     \multicolumn{1}{|c|}{\bf Value}&
        !           215:                \multicolumn{1}{c|}{\bf Underlying Service}&
        !           216:                \multicolumn{1}{c|}{\bf Routine}\\
        !           217: \hline
        !           218:     \tt RoRtService&   Reliable Transfer&      \tt RtOpenResponse\\
        !           219:        &               &                       \tt RtOpenRequest\\
        !           220:        &               &                       \tt RtBeginResponse\\
        !           221:        &               &                       \tt RtBeginRequest\\
        !           222: \hline
        !           223:     \tt RoPService&    Presentation&           \tt AcAssocResponse\\
        !           224:        &               &                       \tt AcAssocRequest\\
        !           225: \hline
        !           226:     \tt RoSService&    Session&                \tt RoBeginResponse\\
        !           227:        &               &                       \tt RoBeginRequest\\
        !           228: \hline
        !           229: \end{tabular}\]
        !           230: 
        !           231: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           232: which is updated only if the call fails.
        !           233: \end{describe}
        !           234: The call to \verb"RoSetService" should be made after a succesful return from
        !           235: any of the routines listed above.
        !           236: 
        !           237: \subsection     {Invoking Operations}
        !           238: The \verb"RoInvokeRequest" routine is used to request an operation to be
        !           239: performed remotely,
        !           240: and corresponds to a {\sf RO-INVOKE.REQUEST\/} action.
        !           241: Under the basic service discipline,
        !           242: this action may be taken by only the initiator of an association;
        !           243: under the advanced or complete service discipline,
        !           244: no such restriction is made.
        !           245: \begin{quote}\index{RoInvokeRequest}\small\begin{verbatim}
        !           246: int     RoInvokeRequest (sd, op, class, args, invoke,
        !           247:                 linked, priority, roi)
        !           248: int     sd;
        !           249: int     op,
        !           250:         class,
        !           251:         invoke,
        !           252:        *linked,
        !           253:         priority;
        !           254: PE      args;
        !           255: struct RoSAPindication *roi;
        !           256: \end{verbatim}\end{quote}
        !           257: The parameters to this procedure are:
        !           258: \begin{describe}
        !           259: \item[\verb"sd":] the association-descriptor;
        !           260: 
        !           261: \item[\verb"op":] the operation code;
        !           262: 
        !           263: \item[\verb"class":] the operation class
        !           264: (either \verb"ROS_SYNC" for a synchronous operation,
        !           265: or \verb"ROS_ASYNC" for an asynchronous one);
        !           266: 
        !           267: \item[\verb"args":] the arguments for the operation;
        !           268: 
        !           269: \item[\verb"invoke":] the invocation ID of this request;
        !           270: 
        !           271: \item[\verb"linked":] the linked ID of this request
        !           272: (only present if the complete service discipline has been selected,
        !           273: use \verb"NULLIP" otherwise);
        !           274: 
        !           275: \item[\verb"priority":] the priority of this request
        !           276: (use \verb"ROS_NOPRIO" if the priority is undetermined);
        !           277: and,
        !           278: 
        !           279: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           280: always updated on synchronous operations,
        !           281: and only updated if the call fails for asynchronous operations.
        !           282: \end{describe}
        !           283: If the \verb"class" parameter was \verb"ROS_ASYNC",
        !           284: then \verb"RoInvokeRequest" returns immediately.
        !           285: Otherwise,
        !           286: after queuing the request,
        !           287: the \verb"RoWaitRequest" routine
        !           288: (described in Section~\ref{replies} on page~\pageref{replies})
        !           289: is called implicitly to return the reply of the request.
        !           290: Every attempt will be made to return the corresponding reply to the request.
        !           291: Nevertheless,
        !           292: it is the responsibility of the user to verify the invocation ID which is
        !           293: returned.
        !           294: 
        !           295: The routine \verb"RoIntrRequest" is similar to \verb"RoInvokeRequest"
        !           296: with a \verb"class" argument of \verb"ROS_SYNC":
        !           297: it invokes an operation and then waits for a response.
        !           298: However,
        !           299: if the user generates an interrupt,
        !           300: usually by typing control-C (`\verb"^C"'),
        !           301: then \verb"RoIntrRequest" will return immediately by simulating
        !           302: a {\sf RO-U-REJECT.INDICATION\/} with reason \verb"ROS_INTERRPUTED"
        !           303: (see section~\ref{rejections} on page~\pageref{rejections}).
        !           304: This is useful for users of remote operations which support an
        !           305: ``abandon'' functionality (e.g., the OSI Directory).
        !           306: \begin{quote}\index{RoInvokeRequest}\small\begin{verbatim}
        !           307: int     RoIntrRequest (sd, op, args, invoke, linked,
        !           308:                 priority, roi)
        !           309: int     sd;
        !           310: int     op,
        !           311:         invoke,
        !           312:        *linked,
        !           313:         priority;
        !           314: PE      args;
        !           315: struct RoSAPindication *roi;
        !           316: \end{verbatim}\end{quote}
        !           317: The parameters to this procedure are:
        !           318: \begin{describe}
        !           319: \item[\verb"sd":] the association-descriptor;
        !           320: 
        !           321: \item[\verb"op":] the operation code;
        !           322: 
        !           323: \item[\verb"args":] the arguments for the operation;
        !           324: 
        !           325: \item[\verb"invoke":] the invocation ID of this request;
        !           326: 
        !           327: \item[\verb"linked":] the linked ID of this request
        !           328: (only present if the complete service discipline has been selected,
        !           329: use \verb"NULLIP" otherwise);
        !           330: 
        !           331: \item[\verb"priority":] the priority of this request
        !           332: (use \verb"ROS_NOPRIO" if the priority is undetermined);
        !           333: and,
        !           334: 
        !           335: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           336: always updated on synchronous operations,
        !           337: and only updated if the call fails for asynchronous operations.
        !           338: \end{describe}
        !           339: 
        !           340: 
        !           341: \subsection     {Replying to Requests}
        !           342: When a request to perform a remote operation has been received by the
        !           343: responder to an association,
        !           344: the responder either returns a result or an error
        !           345: (or in some cases, returns nothing at all).
        !           346: 
        !           347: The \verb"RoResultRequest" routine is used to return a result,
        !           348: and corresponds to the {\sf RO-RESULT.REQUEST\/} action.
        !           349: Under the basic service discipline,
        !           350: this action may only be taken by the responder to an association;
        !           351: under the advanced or complete service discipline,
        !           352: no such restriction is made.
        !           353: \begin{quote}\index{RoResultRequest}\small\begin{verbatim}
        !           354: int     RoResultRequest (sd, invoke, op, result, priority, roi)
        !           355: int     sd;
        !           356: int     invoke,
        !           357:         op,
        !           358:         priority;
        !           359: PE      result;
        !           360: struct RoSAPindication *roi;
        !           361: \end{verbatim}\end{quote}
        !           362: The parameters to this procedure are:
        !           363: \begin{describe}
        !           364: \item[\verb"sd":] the association-descriptor;
        !           365: 
        !           366: \item[\verb"invoke":] the invocation ID of the request corresponding to this
        !           367: reply;
        !           368: 
        !           369: \item[\verb"op":] the operation code of the operation performed
        !           370: (meaningful only in the complete service discipline);
        !           371: 
        !           372: \item[\verb"result":] the results of the operation;
        !           373: 
        !           374: \item[\verb"priority":] the priority of this reply;
        !           375: and,
        !           376: 
        !           377: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           378: updated only if the call fails.
        !           379: \end{describe}
        !           380: 
        !           381: The \verb"RoErrorRequest" routine is used to return an error,
        !           382: and corresponds to the {\sf RO-ERROR.REQUEST\/} action.
        !           383: Under the basic service discipline,
        !           384: this action may only be taken by the responder to an association;
        !           385: under the advanced or complete service discipline,
        !           386: no such restriction is made.
        !           387: \begin{quote}\index{RoErrorRequest}\small\begin{verbatim}
        !           388: int     RoErrorRequest (sd, invoke, error, params,
        !           389:                 priority, roi)
        !           390: int     sd;
        !           391: int     invoke,
        !           392:         error,
        !           393:         priority;
        !           394: PE      params;
        !           395: struct RoSAPindication *roi;
        !           396: \end{verbatim}\end{quote}
        !           397: The parameters to this procedure are:
        !           398: \begin{describe}
        !           399: \item[\verb"sd":] the association-descriptor;
        !           400: 
        !           401: \item[\verb"invoke":] the invocation ID of the request corresponding to this
        !           402: reply;
        !           403: 
        !           404: \item[\verb"op":] the error code;
        !           405: 
        !           406: \item[\verb"params":] the parameters for the error;
        !           407: 
        !           408: \item[\verb"priority":] the priority of this request;
        !           409: and,
        !           410: 
        !           411: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           412: updated only if the call fails.
        !           413: \end{describe}
        !           414: 
        !           415: \subsection     {Reading Replies}\label{replies}
        !           416: The \verb"RoWaitRequest" routine is used to await either a request or a
        !           417: reply from the other user.
        !           418: \begin{quote}\index{RoWaitRequest}\small\begin{verbatim}
        !           419: int     RoWaitRequest (sd, secs, roi)
        !           420: int     sd;
        !           421: int     secs;
        !           422: struct RoSAPindication *roi;
        !           423: \end{verbatim}\end{quote}
        !           424: The parameters to this procedure are:
        !           425: \begin{describe}
        !           426: \item[\verb"sd":] the association-descriptor;
        !           427: 
        !           428: \item[\verb"secs":] the maximum number of seconds to wait for the data
        !           429: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
        !           430: whereas a value of \verb"OK" indicates that the call should not block at all,
        !           431: e.g., a polling action);
        !           432: and,
        !           433: 
        !           434: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           435: which is always updated.
        !           436: \end{describe}
        !           437: Unlike the other routines in the \man librosap(3n) library,
        !           438: the \verb"RoWaitRequest" routine returns one of three values:
        !           439: \verb"NOTOK" (on failure),
        !           440: \verb"OK" (on reading a request or a reply),
        !           441: or
        !           442: \verb"DONE" (when something else happens).
        !           443: 
        !           444: If the call to \verb"RoWaitRequest" returns the manifest constant
        !           445: \verb"NOTOK",
        !           446: then the \verb"RoSAPpreject" structure contained in
        !           447: the \verb"RoSAPindication" parameter
        !           448: \verb"roi" contains the reason for the failure.
        !           449: 
        !           450: Otherwise if the call to \verb"RoWaitRequest" returns the manifest constant
        !           451: \verb"OK",
        !           452: then a request or a reply has arrived.
        !           453: This event is encoded in the \verb"roi" parameter,
        !           454: depending on the value of the \verb"roi_type" element.
        !           455: Currently,
        !           456: when \verb"RoWaitRequest" returns \verb"OK",
        !           457: the \verb"roi_type" element is set to one of four values:
        !           458: \[\begin{tabular}{|l|l|}
        !           459: \hline
        !           460:     \multicolumn{1}{|c|}{\bf Value}&
        !           461:                        \multicolumn{1}{c|}{\bf Event}\\
        !           462: \hline
        !           463:     \tt ROI\_INVOKE&   \sf RO-INVOKE.INDICATION\\
        !           464:     \tt ROI\_RESULT&   \sf RO-RESULT.INDICATION\\
        !           465:     \tt ROI\_ERROR&    \sf RO-ERROR.INDICATION\\
        !           466:     \tt ROI\_UREJECT&  \sf RO-U-REJECT.INDICATION\\
        !           467: \hline
        !           468: \end{tabular}\]
        !           469: 
        !           470: Otherwise if the call to \verb"RoWaitRequest" returns the manifest constant
        !           471: \verb"DONE",
        !           472: then some event other than a request or reply arriving has occurred.
        !           473: This event is encoded in the \verb"roi" parameter,
        !           474: depending on the value of the \verb"roi_type" element.
        !           475: Currently,
        !           476: when \verb"RoWaitRequest" returns \verb"DONE",
        !           477: the \verb"roi_type" element is set to one of two values:
        !           478: \[\begin{tabular}{|l|l|}
        !           479: \hline
        !           480:     \multicolumn{1}{|c|}{\bf Value}&
        !           481:                        \multicolumn{1}{c|}{\bf Event}\\
        !           482: \hline
        !           483:     \tt ROI\_END&      \sf RO-END.INDICATION\\
        !           484:        &               \ \ (for old-style associations)\\
        !           485: \hline
        !           486:     \tt ROI\_FINISH&   \sf A-RELEASE.INDICATION\\
        !           487:        &               \ \ (or {\sf RT-CLOSE.INDICATION\/})\\
        !           488: \hline
        !           489: \end{tabular}\]
        !           490: 
        !           491: \subsubsection  {Invocation Indication}
        !           492: When an {\sf RO-INVOKE.INDICATION\/} event occurs,
        !           493: the \verb"roi_type" field of the \verb"roi" parameter contains the value
        !           494: \verb"ROI_INVOKE",
        !           495: and a \verb"RoSAPinvoke" structure is contained inside the \verb"roi"
        !           496: parameter.
        !           497: \begin{quote}\index{RoSAPinvoke}\small\begin{verbatim}
        !           498: struct RoSAPinvoke {
        !           499:     int     rox_id;
        !           500: 
        !           501:     int     rox_linkid;
        !           502:     int     rox_nolinked;
        !           503: 
        !           504:     int     rox_op;
        !           505:     PE      rox_args;
        !           506: };
        !           507: \end{verbatim}\end{quote}
        !           508: The elements of this structure are:
        !           509: \begin{describe}
        !           510: \item[\verb"rox\_id":] the invocation ID of this request;
        !           511: 
        !           512: \item[\verb"rox\_linkid":] if \verb"rox_nolinked" is not set,
        !           513: then this contains the invocation ID of the linked request;
        !           514: 
        !           515: \item[\verb"rox\_nolinked":] the linked ID indicator
        !           516: (if set, then this invocation is not linked to another operation);
        !           517: 
        !           518: \item[\verb"rox\_op":] the operation code;
        !           519: and,
        !           520: 
        !           521: \item[\verb"rox\_args":] the arguments for the operation.
        !           522: \end{describe}
        !           523: Note that the \verb"rox_data" element is allocated via \man malloc(3) and
        !           524: should be released using the \verb"ROXFREE" macro  when no longer referenced.
        !           525: The \verb"ROXFREE" macro behaves as if it was defined as:
        !           526: \begin{quote}\index{ROXFREE}\small\begin{verbatim}
        !           527: void    ROXFREE (rox)
        !           528: struct RoSAPinvoke *rox;
        !           529: \end{verbatim}\end{quote}
        !           530: The macro frees only the data allocated in the \verb"RoSAPinvoke" structure
        !           531: and not the structure itself.
        !           532: 
        !           533: Under the basic service discipline,
        !           534: only the responder to an association will receive this event;
        !           535: it is expected that the user will (eventually) call either
        !           536: the \verb"RoResultRequest", the \verb"RoErrorRequest",
        !           537: or perhaps the \verb"RoURejectRequest" routine in response.
        !           538: 
        !           539: \subsubsection  {Result Indication}
        !           540: When an {\sf RO-RESULT.INDICATION\/} event occurs,
        !           541: the \verb"roi_type" field of the \verb"roi" parameter contains the value
        !           542: \verb"ROI_RESULT",
        !           543: and a \verb"RoSAPresult" structure is contained inside the \verb"roi"
        !           544: parameter.
        !           545: \begin{quote}\index{RoSAPresult}\small\begin{verbatim}
        !           546: struct RoSAPresult {
        !           547:     int     ror_id;
        !           548: 
        !           549:     PE      ror_result;
        !           550: };
        !           551: \end{verbatim}\end{quote}
        !           552: The elements of this structure are:
        !           553: \begin{describe}
        !           554: \item[\verb"ror\_id":] the invocation ID of this reply,
        !           555: which is identical to the ID of the request which generated the results;
        !           556: 
        !           557: \item[\verb"ror\_op":] the operation code of the operation performed
        !           558: (meaningful only in the complete service discipline);
        !           559: and,
        !           560: 
        !           561: \item[\verb"ror\_result":] the results of the operation.
        !           562: \end{describe}
        !           563: Note that the \verb"ror_result" element is allocated via \man malloc(3) and
        !           564: should be released using the \verb"RORFREE" macro  when no longer referenced.
        !           565: The \verb"RORFREE" macro behaves as if it was defined as:
        !           566: \begin{quote}\index{RORFREE}\small\begin{verbatim}
        !           567: void    RORFREE (ror)
        !           568: struct RoSAPresult *ror;
        !           569: \end{verbatim}\end{quote}
        !           570: The macro frees only the data allocated in the \verb"RoSAPresult" structure
        !           571: and not the structure itself.
        !           572: 
        !           573: Under the basic service discipline,
        !           574: only the initiator to an association will receive this event in response to
        !           575: an earlier call to \verb"RoInvokeRequest".
        !           576: 
        !           577: \subsubsection  {Error Indication}
        !           578: When an {\sf RO-ERROR.INDICATION\/} event occurs,
        !           579: the \verb"roi_type" field of the \verb"roi" parameter contains the value
        !           580: \verb"ROI_ERROR",
        !           581: and a \verb"RoSAPerror" structure is contained inside the \verb"roi"
        !           582: parameter.
        !           583: \begin{quote}\index{RoSAPerror}\small\begin{verbatim}
        !           584: struct RoSAPerror {
        !           585:     int     roe_id;
        !           586: 
        !           587:     int     roe_error;
        !           588:     PE      roe_param;
        !           589: };
        !           590: \end{verbatim}\end{quote}
        !           591: The elements of this structure are:
        !           592: \begin{describe}
        !           593: \item[\verb"roe\_id":] the invocation ID of this reply,
        !           594: which is identical to the ID of the request which generated the error;
        !           595: 
        !           596: \item[\verb"roe\_error":] the error code;
        !           597: and,
        !           598: 
        !           599: \item[\verb"roe\_param":] the parameters of the error.
        !           600: \end{describe}
        !           601: Note that the \verb"roe_param" element is allocated via \man malloc(3) and
        !           602: should be released using the \verb"ROEFREE" macro  when no longer referenced.
        !           603: The \verb"ROEFREE" macro behaves as if it was defined as:
        !           604: \begin{quote}\index{ROEFREE}\small\begin{verbatim}
        !           605: void    ROEFREE (roe)
        !           606: struct RoSAPerror *roe;
        !           607: \end{verbatim}\end{quote}
        !           608: The macro frees only the data allocated in the \verb"RoSAPerror" structure
        !           609: and not the structure itself.
        !           610: 
        !           611: Under the basic service discipline,
        !           612: only the initiator to an association will receive this event in response to
        !           613: an earlier call to \verb"RoInvokeRequest".
        !           614: 
        !           615: \subsubsection  {User-Reject Indication}\label{rejections}
        !           616: When an {\sf RO-U-REJECT.INDICATION\/} event occurs,
        !           617: the \verb"roi_type" field of the \verb"roi" parameter contains the value
        !           618: \verb"ROI_UREJECT",
        !           619: and a \verb"RoSAPureject" structure is contained inside the \verb"roi"
        !           620: parameter.
        !           621: \begin{quote}\index{RoSAPureject}\small\begin{verbatim}
        !           622: struct RoSAPureject {
        !           623:     int     rou_id;
        !           624:     int     rou_noid;
        !           625: 
        !           626:     int     rou_reason;
        !           627: };
        !           628: \end{verbatim}\end{quote}
        !           629: The elements of this structure are:
        !           630: \begin{describe}
        !           631: \item[\verb"rou\_id":] if \verb"rou_noid" is not set,
        !           632: then this contains the invocation ID of the request which generated the
        !           633: rejection;
        !           634: 
        !           635: \item[\verb"rou\_noid":] the invocation ID indicator
        !           636: (if set, then no request in particular caused the rejection to be generated);
        !           637: and,
        !           638: 
        !           639: \item[\verb"rou\_reason":] the reason for the rejection
        !           640: (a ``non-fatal'' user-initiated rejection code listed in
        !           641: Table~\ref{RoSAPreasons}).
        !           642: \end{describe}
        !           643: 
        !           644: \subsubsection  {End Indication}\label{ros:end}
        !           645: When the \verb"roi_type" field of the \verb"roi" parameter contains the value
        !           646: \verb"ROI_END",
        !           647: a \verb"RoSAPend" structure is contained inside the \verb"roi"
        !           648: parameter.
        !           649: \begin{quote}\index{RoSAPend}\small\begin{verbatim}
        !           650: struct RoSAPend {
        !           651:     int     roe_dummy;
        !           652: };
        !           653: \end{verbatim}\end{quote}
        !           654: Depending on whether the reliable transfer service was used to start the
        !           655: association,
        !           656: a {\sf X.400 CLOSE.INDICATION\/} or a {\sf RO-END.INDICATION\/} event has
        !           657: occurred,
        !           658: and the user should respond appropriately.
        !           659: 
        !           660: \subsubsection {Finish Indication}\label{ros:finish}
        !           661: When the \verb"roi_type" field of the \verb"RoSAPindication" parameter
        !           662: \verb"roi" contains the value
        !           663: \verb"ROI_FINISH",
        !           664: a \verb"AcSAPfinish" structure is contained inside the \verb"roi" parameter.
        !           665: Depending on whether the reliable transfer service was used to start the
        !           666: association,
        !           667: an {\sf RT-CLOSE.INDICATION\/} or an {\sf A-RELEASE.INDICATION\/} event has
        !           668: occurred, and the user should respond appropriately.
        !           669: 
        !           670: \subsection     {Rejecting Requests and Replies}
        !           671: The \verb"RoURejectRequest" routine is used to perform user-level
        !           672: error-recovery.
        !           673: Usually,
        !           674: it signals the rejection of a previously received request or reply.
        !           675: \begin{quote}\index{RoURejectRequest}\small\begin{verbatim}
        !           676: int     RoURejectRequest (sd, invoke, reason, priority, roi)
        !           677: int     sd;
        !           678: int    *invoke,
        !           679:         reason,
        !           680:         priority;
        !           681: struct RoSAPindication *roi;
        !           682: \end{verbatim}\end{quote}
        !           683: The parameters to this procedure are:
        !           684: \begin{describe}
        !           685: \item[\verb"sd":] the association-descriptor;
        !           686: 
        !           687: \item[\verb"invoke":] a pointer to the invocation ID of the request in
        !           688: question (or \verb"NULLIP" if this rejection does not apply to a particular
        !           689: request or reply);
        !           690: 
        !           691: \item[\verb"reason":] a ``non-fatal'' user-initiated rejection code as
        !           692: listed in Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons};
        !           693: 
        !           694: \item[\verb"priority":] the priority of this request;
        !           695: and,
        !           696: 
        !           697: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           698: updated only if the call fails.
        !           699: \end{describe}
        !           700: Upon a successful return from this call,
        !           701: a {\sf ROU-U-REJECT.INDICATION\/} event has been queued for the other user.
        !           702: 
        !           703: \subsection     {Asynchronous Event Handling}
        !           704: The request/reply events discussed thus far have been synchronous in nature.
        !           705: Some users of the remote operations service may wish an asynchronous interface.
        !           706: The \verb"RoSetIndications" routine is used to change the service associated
        !           707: with an association-descriptor to an asynchronous interface.
        !           708: \begin{quote}\index{RoSetIndications}\small\begin{verbatim}
        !           709: int   RoSetIndications (sd, indication, roi)
        !           710: int   sd;
        !           711: IFP   indication;
        !           712: struct RoSAPindication *roi;
        !           713: \end{verbatim}\end{quote}
        !           714: The parameters to this procedure are:
        !           715: \begin{describe}
        !           716: \item[\verb"sd":] the association-descriptor;
        !           717: 
        !           718: \item[\verb"indication":] the address of an event-handler routine to be
        !           719: invoked when an event occurs;
        !           720: and,
        !           721: 
        !           722: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           723: updated only if the call fails.
        !           724: \end{describe}
        !           725: If the service is to be made asynchronous,
        !           726: then \verb"indication" is specified;
        !           727: otherwise,
        !           728: if the service is to be made synchronous,
        !           729: it is not specified (use the manifest constant \verb"NULLIFP").
        !           730: The most likely reason for the call failing is \verb"ROS_WAITING",
        !           731: which indicates that an event is waiting for the user.
        !           732: 
        !           733: When an event occurs,
        !           734: the event-handler routine is invoked with two parameters:
        !           735: \begin{quote}\small\begin{verbatim}
        !           736: (*handler) (sd, roi);
        !           737: int     sd;
        !           738: struct RoSAPindication *roi;
        !           739: \end{verbatim}\end{quote}
        !           740: The parameters are:
        !           741: \begin{describe}
        !           742: \item[\verb"sd":] the association-descriptor;
        !           743: and,
        !           744: 
        !           745: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure encoding
        !           746: the event.
        !           747: \end{describe}
        !           748: Note that the data contained in the structure was allocated via \man malloc(3),
        !           749: and should be released with the appropriate macro
        !           750: (i.e., \verb"ROPFREE", \verb"ROXFREE", \verb"RORFREE", or \verb"ROEFREE")
        !           751: when no longer needed.
        !           752: 
        !           753: When an event-handler is invoked,
        !           754: future invocations of the event-hander are blocked until it returns.
        !           755: The return value of the event-handler is ignored.
        !           756: Further,
        !           757: during the execution of a synchronous call to the library,
        !           758: the event-handler will be blocked from being invoked.
        !           759: The one exception to this is a call to \verb"RoInvokeRequest" with the
        !           760: \verb"class" parameter set to \verb"ROS_SYNC".
        !           761: In this circumstance,
        !           762: replies to invocations other than the one being waited for will result in the
        !           763: event-handler being invoked as appropriate.
        !           764: 
        !           765: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !           766: \bf NOTE:&     The \man librosap(3n) library uses the SIGEMT signal to
        !           767:                provide these services.
        !           768:                Programs using asynchronous association-descriptors should NOT
        !           769:                use SIGEMT for other purposes.
        !           770: \end{tabular}}\]
        !           771: 
        !           772: \subsection     {Synchronous Event Multiplexing}
        !           773: A user of the remote operations service may wish to manage multiple
        !           774: association-descriptors simultaneously;
        !           775: the routine \verb"RoSelectMask" is provided for this purpose.
        !           776: This routine updates a file-descriptor mask and associated counter for use
        !           777: with \verb"xselect" (consult Section~\ref{acs:select}),
        !           778: as assocation-descriptors are file-descriptors.
        !           779: \begin{quote}\index{RoSelectMask}\small\begin{verbatim}
        !           780: int     RoSelectMask (sd, mask, nfds, roi)
        !           781: int     sd;
        !           782: fd_set *mask;
        !           783: int    *nfds;
        !           784: struct RoSAPindication *roi;
        !           785: \end{verbatim}\end{quote}
        !           786: The parameters to this procedure are:
        !           787: \begin{describe}
        !           788: \item[\verb"sd":] the association-descriptor;
        !           789: 
        !           790: \item[\verb"mask":] a pointer to a file-descriptor mask meaningful to
        !           791: \verb"xselect";
        !           792: 
        !           793: \item[\verb"nfds":] a pointer to an integer-valued location meaningful to
        !           794: \verb"xselect";
        !           795: and,
        !           796: 
        !           797: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
        !           798: updated only if the call fails.
        !           799: \end{describe}
        !           800: If the call is successful, then the \verb"mask" and \verb"nfds" parameters can
        !           801: be used as arguments to \verb"xselect".
        !           802: The most likely reason for the call failing is \verb"ROS_WAITING",
        !           803: which indicates that an event is waiting for the user.
        !           804: 
        !           805: If \verb"xselect" indicates that the association-descriptor is ready for
        !           806: reading,
        !           807: \verb"RoWaitRequest" should be called with the \verb"secs" parameter equal to
        !           808: \verb"OK".
        !           809: If the network activity does not constitute an entire event for the user,
        !           810: then \verb"RoWaitRequest" will return \verb"NOTOK" with error code
        !           811: \verb"ROS_TIMER".
        !           812: 
        !           813: \section       {Error Conventions}
        !           814: All of the routines in this library return the manifest constant \verb"NOTOK"
        !           815: on error,
        !           816: and also update the \verb"roi" parameter given to the routine.
        !           817: The element called \verb"roi_preject" in the \verb"RoSAPindication" structure
        !           818: encodes the reason for the failure.
        !           819: To determine the reason,
        !           820: one coerces a pointer to a \verb"RoSAPpreject" structure,
        !           821: and consults the \verb"rop_reason" element of this latter structure.
        !           822: This element can be given as a
        !           823: parameter to the routine \verb"RoErrString" which returns a null-terminated
        !           824: diagnostic string.
        !           825: \begin{quote}\index{RoErrString}\small\begin{verbatim}
        !           826: char   *RoErrString (c)
        !           827: int     c;
        !           828: \end{verbatim}\end{quote}
        !           829: 
        !           830: \section       {Compiling and Loading}
        !           831: Programs using the \man librosap(3n) library should include
        !           832: \verb"<isode/rosap.h>",
        !           833: which automatically includes the header file \verb"<isode/psap.h>" described in
        !           834: Chapter~\ref{libpsap} and the header file \verb"<isode/acsap.h>" described in
        !           835: Chapter~\ref{libacsap}.
        !           836: The programs should also be loaded with \verb"-lisode".
        !           837: 
        !           838: \section       {Two Examples}\label{ros:example}
        !           839: Two examples are now presented:
        !           840: a detailed exposition on the construction of a responder for remote operations;
        !           841: and,
        !           842: a terse presentation of an initiator process.
        !           843: 
        !           844: \subsection    {The Generic Server}\label{ros:example:server}
        !           845: Let's consider how one might construct a generic server which uses remote
        !           846: operations services.
        !           847: This entity will use an asynchronous interface.
        !           848: 
        !           849: There are two parts to the program:
        !           850: initialization and the request/reply loop.
        !           851: In our example,
        !           852: we assume that the routine \verb"error" results in the process being
        !           853: terminated after printing a diagnostic.
        !           854: 
        !           855: In Figure~\ref{initROSresponder},
        !           856: the initialization steps for the generic responder,
        !           857: including the outer {\em C\/} wrapper,
        !           858: is shown.
        !           859: First, the ACSE state is re-captured by calling \verb"AcInit".
        !           860: If this succeeds,
        !           861: then any command line arguments
        !           862: (as specified in the \man isoservices(5) file described in
        !           863: Chapter~\ref{isoservices} of \voltwo/)
        !           864: are parsed.
        !           865: Assuming that the responder is satisfied with the proposed association,
        !           866: it calls \verb"AcAssocResponse" to accept the association.
        !           867: Then,
        !           868: \verb"RoSetService" is called
        !           869: to set the underlying service to be used for remote operations.
        !           870: The
        !           871: \verb"RoSetIndications" routine is called
        !           872: to specify an asynchronous event handler.
        !           873: Finally,
        !           874: the main request/reply loop is realized.
        !           875: The server simply uses \man pause(2) to wait for the next event.
        !           876: 
        !           877: In Figure~\ref{doROSresponder} on page~\pageref{doROSresponder},
        !           878: the \verb"ros_indication" routine simply dispatches based on the value of the
        !           879: \verb"roi_type" element of the \verb"RoSAPindication" structure.
        !           880: {\let\small=\scriptsize                        %%% yikes!
        !           881: \clearpage
        !           882: \tagrind[tp]{grind2b-2}{Initializing the generic ROS responder}%
        !           883:        {initROSresponder}
        !           884: \clearpage
        !           885: \tagrind[tp]{grind2b-3a}{The request/reply loop for the generic ROS responder}%
        !           886:        {doROSresponder}
        !           887: \clearpage
        !           888: \tagrind[tp]{grind2b-3b}%
        !           889:        {The request/reply loop for the generic ROS responder (continued)}%
        !           890:        \empty
        !           891: \clearpage
        !           892: \tagrind[tp]{grind2b-3c}%
        !           893:        {The request/reply loop for the generic ROS responder (continued)}%
        !           894:        \empty
        !           895: \clearpage
        !           896: \tagrind[tp]{grind2b-3d}%
        !           897:        {The request/reply loop for the generic ROS responder (continued)}%
        !           898:        \empty
        !           899: \clearpage
        !           900: \tagrind[tp]{grind2b-3e}%
        !           901:        {The request/reply loop for the generic ROS responder (continued)}%
        !           902:        \empty}
        !           903: 
        !           904: If the event was caused by a request to invoke an operation,
        !           905: then \verb"ros_invoke" is called.
        !           906: This routine consults a dispatch table to find the function which will
        !           907: execute the operation.
        !           908: Based on the return value of the function,
        !           909: either the result is returned,
        !           910: an error is returned,
        !           911: or the request to perform the operation is rejected.
        !           912: 
        !           913: If the event was caused by a reply to the invocation of an operation
        !           914: (i.e., either  results or an error),
        !           915: this is rejected.
        !           916: The basic service discipline prohibits this event from happening to
        !           917: responders;
        !           918: hence, the \verb"ros_result" and \verb"ros_error" routines are used as stubs.
        !           919: 
        !           920: If the event was caused by a rejection of a previous reply,
        !           921: then the \verb"ros_ureject" routine is called to handle this.
        !           922: If the event was caused by the provider initiating a rejection,
        !           923: then the \verb"ros_preject" routine is called to handle this.
        !           924: 
        !           925: Finally,
        !           926: if the event was caused by the association being released,
        !           927: the \verb"ros_finish" routine is called to handle this.
        !           928: 
        !           929: \subsection    {The Generic Client}
        !           930: As the previous example described~---~in great detail~---~how users of the
        !           931: remote operations services employ the \man librosap(3n) library,
        !           932: we now present a short example of how a client connects to the server.
        !           933: 
        !           934: In Figure~\ref{initROSinitiator},
        !           935: the initialization steps for the generic initiator,
        !           936: including the outer {\em C\/} wrapper,
        !           937: is shown.
        !           938: First, the application-entity information and presentation address are
        !           939: looked-up.
        !           940: Second, the application context and protocol control information objects are
        !           941: looked-up
        !           942: (and copied, since \verb"ode2oid" returns a pointer to a static area).
        !           943: Next, the session connection reference is initialized.
        !           944: Then, the call to \verb"AcAssocRequest" is made.
        !           945: The arguments to this routine are the minimal required for remote operations.
        !           946: If the call succeeds,
        !           947: then the client checks to see if the association is successfully established.
        !           948: If so, the association descriptor is captured, and then the routine
        !           949: \verb"invoke",
        !           950: which is not described in this example,
        !           951: is called.
        !           952: This routine presumably requests remote operations from the responder
        !           953: previously described.
        !           954: Upon the return of the \verb"invoke" routine,
        !           955: the association is (forcibly) released,
        !           956: and the program exits.
        !           957: {\let\small=\scriptsize                        %%% yikes!
        !           958: \clearpage
        !           959: \tagrind[tp]{grind2b-4a}{Initializing the generic ROS initiator}%
        !           960:        {initROSinitiator}
        !           961: \clearpage
        !           962: \tagrind[tp]{grind2b-4b}{Initializing the generic ROS initiator (continued)}%
        !           963:        \empty}
        !           964: 
        !           965: \section       {For Further Reading}\label{ros:reading}
        !           966: The ECMA technical report on remote operation services is defined in
        !           967: \cite{ECMA.ROS}.
        !           968: The CCITT recommendation describing remote operations,
        !           969: as supported by the reliable transfer service,
        !           970: is \cite{MHS.RTS}.
        !           971: These both assume the use of old-style associations;
        !           972: the draft CCITT work which assumes the use of new-style associations is
        !           973: defined in \cite{CCITT.ROS.Service} and \cite{CCITT.ROS.Protocol}.
        !           974: Similarly,
        !           975: the corresponding ISO work is
        !           976: \cite{ISO.ROS.Service} and \cite{ISO.ROS.Protocol}.
        !           977: 
        !           978: %%% \section  {Changes Since the Last Release}\label{rosap:changes}
        !           979: %%% A brief summary of the major changes between v~\rosaprevrsn/ and
        !           980: %%% v~\rosapvrsn/ are now presented.
        !           981: %%% These are the user-visible changes only;
        !           982: %%% changes of a strictly internal nature are not discussed.
        !           983: 

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