Return to librosy.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter       {Run-Time Environment}\label{librosy}
        !             4: The \man librosap(3n) library implements the run-time environment for the
        !             5: stubs generated by the \man rosy(1) program.
        !             6: 
        !             7: The routines described herein provide a more structured interface to the 
        !             8: remote operations service (ROS).
        !             9: They are used in the boilerplate routines which are described in the
        !            10: following chapters.
        !            11: Hence,
        !            12: the more hasty reader may wish to skip this chapter on first reading of this
        !            13: volume.
        !            14: 
        !            15: \section      {Notice}
        !            16: Please read the following important message.
        !            17: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !            18: \bf NOTE:&     When using the \man librosy(3n) library,
        !            19:                no calls should be made to the \man librosap(3n) library.
        !            20:                (That is, the \verb"RoXXX" routines should not be directly
        !            21:                referenced.)
        !            22: 
        !            23:                There are three exceptions: \verb"RoSetService" and
        !            24:                its related arguments (e.g., \verb"RoPService"),
        !            25:                \verb"RoSelectMask", and \verb"RoErrString".
        !            26: \end{tabular}}\]
        !            27: 
        !            28: \section      {Conventions}
        !            29: All of the routines in the \man librosy(3n) library are integer-valued.
        !            30: Unless otherwise indicated,
        !            31: they return the manifest constant \verb"OK" on success,
        !            32: or \verb"NOTOK" otherwise.
        !            33: 
        !            34: The routines all work on an established association,
        !            35: which is referenced by an association-descriptor.
        !            36: This is usually the first parameter given to any of the routines in the
        !            37: \man librosy(3n) library.
        !            38: Further,
        !            39: the last parameter is usually a pointer to a \verb"RoSAPindication" structure.
        !            40: If a call to one of these routines fails,
        !            41: then the structure is updated.
        !            42: Section~\ref{ros:operations} of \volone/ describes this structure and how to
        !            43: interpret error conditions and their severity.
        !            44: 
        !            45: \subsection    {Interface from ROSY}
        !            46: For a given module, e.g., \verb"MODULE",
        !            47: \pgm{rosy} will define two tables:
        !            48: \begin{quote}\small\begin{verbatim}
        !            49: struct RyOperation table_MODULE_Operations[];
        !            50: 
        !            51: struct RyError table_MODULE_Errors[];
        !            52: \end{verbatim}\end{quote}
        !            53: 
        !            54: The \verb"RyOperation" structure is used to define the compiled parts of an
        !            55: operation:
        !            56: \begin{quote}\small\index{RyOperation}\begin{verbatim}
        !            57: struct RyOperation {
        !            58:     char   *ryo_name;
        !            59:     int     ryo_op;
        !            60: 
        !            61:     IFP     ryo_arg_encode;
        !            62:     IFP     ryo_arg_decode;
        !            63:     IFP     ryo_arg_free;
        !            64: 
        !            65:     int     ryo_result;
        !            66:     IFP     ryo_res_encode;
        !            67:     IFP     ryo_res_decode;
        !            68:     IFP     ryo_res_free;
        !            69: 
        !            70:     struct RyError **ryo_errors;
        !            71: };
        !            72: \end{verbatim}\end{quote}
        !            73: The elements of this structure are:
        !            74: \begin{describe}
        !            75: \item[\verb"ryo\_name"/\verb"ryo\_op":] the operation name and code;
        !            76: 
        !            77: \item[\verb"ryo\_arg\_encode"/\verb"ryo\_arg\_decode":] the address of the
        !            78: routines to encode or decode (respectively) the operation's argument from a
        !            79: {\em C\/} structure to its corresponding abstract syntax
        !            80: (present only if the operation takes an argument);
        !            81: 
        !            82: \item[\verb"ryo\_arg\_free":] the routine to free the {\em C\/} structure
        !            83: created by the argument decode routine for the operation;
        !            84: 
        !            85: \item[\verb"ryo\_result":] non-zero if this operation returns a result;
        !            86: 
        !            87: \item[\verb"ryo\_res\_encode"/\verb"ryo\_res\_decode":] the address of the
        !            88: routines to encode or decode (respectively) the operation's result from a
        !            89: {\em C\/} structure to its corresponding abstract syntax
        !            90: (present only if the operation returns a result);
        !            91: 
        !            92: \item[\verb"ryo\_res\_free":] the routine to free the {\em C\/} structure
        !            93: created by the result decode routine for the operation;
        !            94: and,
        !            95: 
        !            96: \item[\verb"ryo\_errors":] a pointer to null-terminated list of the errors
        !            97: which this operation may generate (present only if the operation may returns
        !            98: at least one error).
        !            99: \end{describe}
        !           100: 
        !           101: The \verb"RyError" structure is used to define the compiled parts of an
        !           102: error:
        !           103: \begin{quote}\small\index{RyError}\begin{verbatim}
        !           104: struct RyError {
        !           105:     char   *rye_name;
        !           106:     int     rye_err;
        !           107: 
        !           108:     IFP     rye_param_encode;
        !           109:     IFP     rye_param_decode;
        !           110:     IFP     rye_param_free;
        !           111: };
        !           112: \end{verbatim}\end{quote}
        !           113: The elements of this structure are:
        !           114: \begin{describe}
        !           115: \item[\verb"rye\_name"/\verb"rye\_err":] the error name and code;
        !           116: 
        !           117: \item[\verb"rye\_param\_encode"/\verb"rye\_res\_decode":] the address of the
        !           118: routines to encode or decode (respectively) the error's parameter from a
        !           119: {\em C\/} structure to its corresponding abstract syntax
        !           120: (present only if the error contains a parameter);
        !           121: and,
        !           122: 
        !           123: \item[\verb"ryo\_param\_free":] the routine to free the {\em C\/} structure
        !           124: created by the parameter decode routine for the error.
        !           125: \end{describe}
        !           126: 
        !           127: \section      {Routines for Initiators}
        !           128: Initiators use the routines in the \man libacsap(3n) library for association
        !           129: control.
        !           130: These are described in Chapter~\ref{libacsap} of \volone/.
        !           131: 
        !           132: \section      {Routines for Invokers}\label{ryoperation}
        !           133: After forming an association,
        !           134: invokers are able to request operations for execution by the performer.
        !           135: Two interfaces are provided:
        !           136: a synchronous interface and an asynchronous interface.
        !           137: 
        !           138: \subsection*   {Synchronous Interface}
        !           139: Most invokers desire a simple interface for synchronous execution
        !           140: of operations (the operation blocks until it is completed).
        !           141: The \verb"RyOperation" routine is used to provide such an interface.
        !           142: \begin{quote}\index{RyOperation}\small\begin{verbatim}
        !           143: int     RyOperation (sd, ryo, op, in, out, response, roi)
        !           144: int     sd;
        !           145: struct RyOperation *ryo;
        !           146: int     op,
        !           147:        *response;
        !           148: caddr_t in,
        !           149:        *out;
        !           150: struct RoSAPindication *roi;
        !           151: \end{verbatim}\end{quote}
        !           152: The parameters to this procedure are:
        !           153: \begin{describe}
        !           154: \item[\verb"sd":] the association-descriptor;
        !           155: 
        !           156: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
        !           157: 
        !           158: \item[\verb"op":] the operation code of the operation to invoke;
        !           159: 
        !           160: \item[\verb"response":] an integer-valued location which is updated if the
        !           161: call succeeds;
        !           162: 
        !           163: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
        !           164: argument;
        !           165: 
        !           166: \item[\verb"out":] an address-valued location which is updated if the call
        !           167: succeeds;
        !           168: and,
        !           169: 
        !           170: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           171: which is updated only if the operation was not performed.
        !           172: \end{describe}
        !           173: The \verb"RyOperation" routine returns one of three values:
        !           174: \verb"NOTOK" (on failure),
        !           175: \verb"OK" (on reading a reply),
        !           176: or
        !           177: \verb"DONE" (when something else happens).
        !           178: 
        !           179: If the call to \verb"RyOperation" returns the manifest constant \verb"NOTOK",
        !           180: then the \verb"RoSAPpreject" structure contained in
        !           181: the \verb"RoSAPindication" parameter
        !           182: \verb"roi" contains the reason for the failure.
        !           183: 
        !           184: If the call to \verb"RyOperation" returns the manifest constant \verb"OK",
        !           185: then the \verb"response" and \verb"out" parameters are updated.
        !           186: If the value of the integer pointed to by \verb"response" is \verb"RY_RESULT",
        !           187: then the value of the address pointed to by \verb"out" is a newly allocated
        !           188: {\em C\/} structure for the operation's result (if any).
        !           189: If the value of the integer pointed to by \verb"response" is any other value,
        !           190: then it indicates the error which the operation returned,
        !           191: and the value of the address pointed to by \verb"out" is a newly allocated
        !           192: {\em C\/} structure for the error's parameter (if any).
        !           193: Note that if a result or parameter is returned,
        !           194: then it is the invoker's responsibility to release the memory used by the
        !           195: {\em C\/} structure, when appropriate.
        !           196: 
        !           197: If the call to \verb"RyOperation" returns the manifest constant \verb"DONE",
        !           198: then an indication that the association is pending termination is returned.
        !           199: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
        !           200: parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
        !           201: Consult Section~\ref{ros:end} of \volone/ for the details,
        !           202: as this normally does not happen to initiators.
        !           203: 
        !           204: The routine \verb"RyOperation" is simply a comprehensive interface for a more
        !           205: general routine, \verb"RyOpInvoke", which invokes an operation:
        !           206: \begin{quote}\index{RyOpInvoke}\small\begin{verbatim}
        !           207: int     RyOpInvoke (sd, ryo, op, in, out, rfx, efx, class,
        !           208:                 invokeID, linkedID, priority, roi)
        !           209: int     sd;
        !           210: struct RyOperation *ryo;
        !           211: int     op,
        !           212:         class,
        !           213:         invokeID,
        !           214:        *linkedID,
        !           215:         priority;
        !           216: IFP     rfx,
        !           217:         efx;
        !           218: caddr_t in,
        !           219:        *out;
        !           220: struct RoSAPindication *roi;
        !           221: \end{verbatim}\end{quote}
        !           222: The parameters to this procedure are:
        !           223: \begin{describe}
        !           224: \item[\verb"sd":] the association-descriptor;
        !           225: 
        !           226: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
        !           227: 
        !           228: \item[\verb"op":] the operation code of the operation to invoke;
        !           229: 
        !           230: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
        !           231: argument;
        !           232: 
        !           233: \item[\verb"out":] an address-valued location which is updated if the call
        !           234: succeeds;
        !           235: 
        !           236: \item[\verb"rfx":] the address of a dispatch routine to be invoked if
        !           237: the operation returns a result;
        !           238: 
        !           239: \item[\verb"efx":] the address of a dispatch routine to be invoked if
        !           240: the operation returns an error;
        !           241: 
        !           242: \item[\verb"class":] the operation class
        !           243: (either \verb"ROS_SYNC" for a synchronous operation,
        !           244: or \verb"ROS_ASYNC" for an asynchronous one);
        !           245: 
        !           246: \item[\verb"invokeID":] the invocation ID of this request;
        !           247: 
        !           248: \item[\verb"linkedID":] the linked ID of this request
        !           249: (use \verb"NULLIP" if not linked);
        !           250: 
        !           251: \item[\verb"priority":] the priority of this request
        !           252: (use \verb"ROS_NOPRIO" if the priority is undetermined);
        !           253: and,
        !           254: 
        !           255: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           256: which is updated only if the operation was not performed.
        !           257: \end{describe}
        !           258: This routine is exactly equivalent to the \verb"RoInvokeRequest" routine in the
        !           259: \man librosap(3n) library,
        !           260: with the additional functions of:
        !           261: automatically encoding and decoding arguments, results, and parameters.
        !           262: Hence,
        !           263: the routine \verb"RyOperation",
        !           264: is essentially a call to \verb"RyOpInvoke" with a few hard-wired parameters:
        !           265: \begin{describe}
        !           266: \item[\verb"class":]  \verb"ROS_SYNC";
        !           267: 
        !           268: \item[\verb"invokeID":] a unique-number;
        !           269: 
        !           270: \item[\verb"linkedID":] \verb"NULLIP";
        !           271: and,
        !           272: 
        !           273: \item[\verb"priority":] \verb"ROS_NOPRIO".
        !           274: \end{describe}
        !           275: 
        !           276: \subsection*   {Asynchronous Interface}
        !           277: Although
        !           278: most invokers desire a simple interface for synchronous execution,
        !           279: it is also useful to have an asynchronous interface.
        !           280: Further,
        !           281: since a synchronous interface can be thought of as a degenerate subset of an
        !           282: asynchronous interface,
        !           283: most invokers use the asynchronous interface and simply ask for it to block
        !           284: after making the invocation.
        !           285: The \verb"RyStub" routine is used to provide such an interface.
        !           286: \begin{quote}\index{RyStub}\small\begin{verbatim}
        !           287: int     RyStub (sd, ryo, op, id, linked, in, rfx, efx,
        !           288:                 class, roi)
        !           289: int     sd;
        !           290: struct RyOperation *ryo;
        !           291: int     op,
        !           292:         id,
        !           293:        *linked,
        !           294:         class;
        !           295: caddr_t in;
        !           296: IFP     rfx,
        !           297:         efx;
        !           298: struct RoSAPindication *roi;
        !           299: \end{verbatim}\end{quote}
        !           300: The parameters to this procedure are:
        !           301: \begin{describe}
        !           302: \item[\verb"sd":] the association-descriptor;
        !           303: 
        !           304: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
        !           305: 
        !           306: \item[\verb"op":] the operation code of the operation to invoke;
        !           307: 
        !           308: \item[\verb"id":] the invocation identifier to use;
        !           309: 
        !           310: \item[\verb"linked":] the linked invocation identifier to use, if any
        !           311: (use \verb"NULLIP" if this is not a linked reply);
        !           312: 
        !           313: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
        !           314: argument;
        !           315: 
        !           316: \item[\verb"rfx":] the address of a dispatch routine to be invoked if
        !           317: the operation returns a result;
        !           318: 
        !           319: \item[\verb"efx":] the address of a dispatch routine to be invoked if
        !           320: the operation returns an error or is rejected;
        !           321: 
        !           322: \item[\verb"class":] the operation class
        !           323: (either \verb"ROS_SYNC" for a synchronous operation,
        !           324: \verb"ROS_ASYNC" for an asynchronous operation,
        !           325: or \verb"ROS_INTR" for a synchronous but user-interruptable operation);
        !           326: and,
        !           327: 
        !           328: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           329: which is updated only if the operation was not performed.
        !           330: \end{describe}
        !           331: The \verb"RyStub" routine returns one of three values:
        !           332: \verb"NOTOK" (on failure),
        !           333: \verb"OK" (on success),
        !           334: or
        !           335: \verb"DONE" (when something else happens).
        !           336: 
        !           337: If the call to \verb"RyStub" returns the manifest constant \verb"NOTOK",
        !           338: then the \verb"RoSAPpreject" structure contained in
        !           339: the \verb"RoSAPindication" parameter
        !           340: \verb"roi" contains the reason for the failure.
        !           341: 
        !           342: If the call to \verb"RyStub" returns the manifest constant \verb"OK",
        !           343: then the operation was queued or completed,
        !           344: depending on the value of the \verb"class" parameter.
        !           345: If the value of the \verb"class" parameter was \verb"ROS_ASYNC",
        !           346: then \verb"RyStub" returns immediately after queuing the invocation.
        !           347: Otherwise,
        !           348: \verb"RyStub" waits for a response to the operation,
        !           349: invokes the appropriate dispatch routine,
        !           350: and then returns.
        !           351: Both the result and error dispatch routines are invoked in the same way:
        !           352: \begin{quote}\small\begin{verbatim}
        !           353: result = (*fnx) (sd, id, reason, value, roi)
        !           354: int     sd;
        !           355: int     id,
        !           356:         reason;
        !           357: caddr_t value;
        !           358: struct RoSAPindication *roi;
        !           359: \end{verbatim}\end{quote}
        !           360: The parameters to this procedure are:
        !           361: \begin{describe}
        !           362: \item[\verb"sd":] the association-descriptor;
        !           363: 
        !           364: \item[\verb"id":] the invocation identifier associated with the result or
        !           365: error;
        !           366: 
        !           367: \item[\verb"reason":] either \verb"RY_RESULT" if the result dispatch routine
        !           368: is invoked, the error code if the error dispatch routine is invoked with an
        !           369: error, or \verb"RY_REJECT" if the error dispatch routine is invoked with a
        !           370: rejection;
        !           371: 
        !           372: \item[\verb"value":] the address of the {\em C\/} structure for the result or
        !           373: error parameter (if any);
        !           374: and,
        !           375: 
        !           376: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           377: which is updated only if the result, error, or rejection is faulty.
        !           378: \end{describe}
        !           379: The dispatch routine should return the manifest constant \verb"OK"
        !           380: unless you know what you're doing.
        !           381: Note that if \verb"value" is present,
        !           382: then the \man librosy(3n) library will automatically release the memory used
        !           383: by the {\em C\/} structure when the dispatch routine returns.
        !           384: 
        !           385: If the call to \verb"RyStub" returns the manifest constant \verb"DONE",
        !           386: then an indication that the association is pending termination is returned.
        !           387: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
        !           388: parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
        !           389: Consult Section~\ref{ros:end} of \volone/ for the details,
        !           390: as this normally does not happen to initiators.
        !           391: 
        !           392: If the value of the \verb"class" parameter was \verb"ROS_INTR",
        !           393: then \verb"RyStub" issues a synchronous call
        !           394: (as described above for the \verb"ROS_SYNC" case).
        !           395: However, if the user generates an interrupt,
        !           396: usually by typing control-C (`\verb"^C"'),
        !           397: while waiting for the response to the operation,
        !           398: then \verb"RyStub" will return immediately with the value \verb"NOTOK"
        !           399: and the \verb"rop_reason" element of the  \verb"RoSAPpreject" structure
        !           400: contained in the \verb"RoSAPindication" parameter \verb"roi" will be set to
        !           401: the value \verb"ROS_INTERRUPTED".
        !           402: 
        !           403: At this time,
        !           404: the program may do other processing and later return to wait for the outcome
        !           405: of the operation.
        !           406: Instead,
        !           407: the program may direct the run-time environment to silently discard any
        !           408: outcome.
        !           409: This is useful when the user wishes to abandon an inprogress operation and
        !           410: really doesn't care what the results are
        !           411: (i.e., when reading from a database).
        !           412: The verb"RyDiscard" routine is used to accomplish this function:
        !           413: \begin{quote}\index{RyDiscard}\small\begin{verbatim}
        !           414: int     RyDiscard (sd, id, roi)
        !           415: int     sd,
        !           416:         id;
        !           417: struct RoSAPindication *roi;
        !           418: \end{verbatim}\end{quote}
        !           419: The parameters to this procedure are:
        !           420: \begin{describe}
        !           421: \item[\verb"sd":] the association descriptor;
        !           422: 
        !           423: \item[\verb"sd":] the invocation-identifier associated with the operation; and,
        !           424: 
        !           425: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           426: which is updated only on failure.
        !           427: \end{describe}
        !           428: The \verb"RyDiscard" routine returns either \verb"NOTOK" (on failure)
        !           429: or \verb"OK" (on success).
        !           430: 
        !           431: \section      {Routines for Responders}
        !           432: Responders use the routines in the \man libacsap(3n) library for association
        !           433: control.
        !           434: These are described in Chapter~\ref{libacsap} of \volone/.
        !           435: 
        !           436: \section      {Routines for Performers}
        !           437: After forming an association,
        !           438: performers register the operations they are willing to perform.
        !           439: They then typically wait for those operations to be invoked.
        !           440: 
        !           441: \subsection    {Registering Operations}\label{librosy:register}
        !           442: The routine \verb"RyDispatch" is used to register a handler for an operation:
        !           443: \begin{quote}\index{RyDispatch}\small\begin{verbatim}
        !           444: int     RyDispatch (sd, ryo, op, fnx, roi)
        !           445: int     sd;
        !           446: struct RyOperation *ryo;
        !           447: int     op;
        !           448: IFP     fnx;
        !           449: struct RoSAPindication *roi;
        !           450: \end{verbatim}\end{quote}
        !           451: The parameters to this procedure are:
        !           452: \begin{describe}
        !           453: \item[\verb"sd":] the association-descriptor;
        !           454: 
        !           455: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
        !           456: 
        !           457: \item[\verb"op":] the operation code of the operation to be registered;
        !           458: 
        !           459: \item[\verb"fnx":] the address of a dispatch routine to be invoked when
        !           460: the operation is invoked;
        !           461: and,
        !           462: 
        !           463: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           464: which is updated only if the call fails.
        !           465: \end{describe}
        !           466: An operation may be un-registered by using \verb"NULLIFP" for the \verb"fnx"
        !           467: parameter.
        !           468: 
        !           469: When a registered operation is invoked
        !           470: (from the routine \verb"RyWait" described in Section~\ref{librosy:waiting}),
        !           471: the dispatch routine is invoked with five parameters:
        !           472: \begin{quote}\small\begin{verbatim}
        !           473: result = (*fnx) (sd, ryo, rox, in, roi)
        !           474: int     sd;
        !           475: struct RyOperation *ryo;
        !           476: struct RoSAPinvoke *rox;
        !           477: caddr_t in;
        !           478: struct RoSAPindication *roi;
        !           479: \end{verbatim}\end{quote}
        !           480: The parameters to this procedure are:
        !           481: \begin{describe}
        !           482: \item[\verb"sd":] the association-descriptor;
        !           483: 
        !           484: \item[\verb"ryo":] a pointer to a entry in the \verb"RyOperation" table
        !           485: for this operation;
        !           486: 
        !           487: \item[\verb"rox":] a pointer to a \verb"RoSAPinvoke" structure containing
        !           488: miscellaneous information regarding the operation being invoked
        !           489: (e.g., the invocation id);
        !           490: 
        !           491: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
        !           492: argument (if any);
        !           493: and,
        !           494: 
        !           495: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           496: which is updated only if the operation was not performed.
        !           497: \end{describe}
        !           498: Note that if an argument is present for the operation,
        !           499: then the \man librosy(3n) library will automatically release the memory used
        !           500: by the {\em C\/} structure when the dispatch routine returns.
        !           501: 
        !           502: The return value of the dispatch routine is consulted to determine the
        !           503: disposition of the invocation.
        !           504: One of three values should be returned:
        !           505: \verb"NOTOK", which indicates that some non-operational error occured;
        !           506: \verb"OK", which indicates that the operation was handled;
        !           507: or,
        !           508: \verb"DONE", which indicates that the association is pending termination.
        !           509: 
        !           510: \subsection    {Responding to Operations}
        !           511: If the operation corresponding to the dispatch routine does not return a
        !           512: result,
        !           513: then the routine may simply process the request and return.
        !           514: Otherwise,
        !           515: the dispatch routine should ultimately cause one of three routines to be
        !           516: called to handle an invocation.
        !           517: 
        !           518: The routine \verb"RyDsResult" is used to return a result to an invocation.
        !           519: \begin{quote}\index{RyDsResult}\small\begin{verbatim}
        !           520: int     RyDsResult (sd, id, out, priority, roi)
        !           521: int     sd;
        !           522: int     id,
        !           523:         priority;
        !           524: caddr_t out;
        !           525: struct RoSAPindication *roi;
        !           526: \end{verbatim}\end{quote}
        !           527: The parameters to this procedure are:
        !           528: \begin{describe}
        !           529: \item[\verb"sd":] the association-descriptor;
        !           530: 
        !           531: \item[\verb"id":] the ID of the invocation being responded to;
        !           532: 
        !           533: \item[\verb"out":] the address of the {\em C\/} structure for the operation's
        !           534: result (if any);
        !           535: 
        !           536: \item[\verb"priority":] the priority of the response
        !           537: (use \verb"ROS_NOPRIO" if the priority is undetermined);
        !           538: and,
        !           539: 
        !           540: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           541: which is updated only if the call fails.
        !           542: \end{describe}
        !           543: 
        !           544: The routine \verb"RyDsError" is used to return an error to an invocation.
        !           545: \begin{quote}\index{RyDsError}\small\begin{verbatim}
        !           546: int     RyDsError (sd, id, err, out, priority, roi)
        !           547: int     sd;
        !           548: int     id,
        !           549:         err,
        !           550:         priority;
        !           551: caddr_t out;
        !           552: struct RoSAPindication *roi;
        !           553: \end{verbatim}\end{quote}
        !           554: The parameters to this procedure are:
        !           555: \begin{describe}
        !           556: \item[\verb"sd":] the association-descriptor;
        !           557: 
        !           558: \item[\verb"id":] the ID of the invocation being responded to;
        !           559: 
        !           560: \item[\verb"err":] the error code being returned;
        !           561: 
        !           562: \item[\verb"out":] the address of the {\em C\/} structure for the error's
        !           563: parameter (if any);
        !           564: 
        !           565: \item[\verb"priority":] the priority of the response
        !           566: (use \verb"ROS_NOPRIO" if the priority is undetermined);
        !           567: and,
        !           568: 
        !           569: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           570: which is updated only if the call fails.
        !           571: \end{describe}
        !           572: 
        !           573: The routine \verb"RyDsUReject" is used to reject an invocation.
        !           574: \begin{quote}\index{RyDsUReject}\small\begin{verbatim}
        !           575: int    RyDsUReject (sd, id, reason, priority, roi)
        !           576: int     sd;
        !           577: int    id,
        !           578:        reason,
        !           579:        priority;
        !           580: struct RoSAPindication *roi;
        !           581: \end{verbatim}\end{quote}
        !           582: The parameters to this procedure are:
        !           583: \begin{describe}
        !           584: \item[\verb"sd":] the association-descriptor;
        !           585: 
        !           586: \item[\verb"id":] the ID of the invocation being rejected;
        !           587: 
        !           588: \item[\verb"reason":] the reason for the rejection
        !           589: (codes are listed in Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons}
        !           590: of \volone/);
        !           591: 
        !           592: \item[\verb"priority":] the priority of the response
        !           593: (use \verb"ROS_NOPRIO" if the priority is undetermined);
        !           594: and,
        !           595: 
        !           596: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           597: which is updated only if the call fails.
        !           598: \end{describe}
        !           599: 
        !           600: \section      {Waiting for Events}\label{librosy:waiting}
        !           601: The \verb"RyWait" routine is used by both invokers and performers to wait
        !           602: for some event to occur.
        !           603: Normally,
        !           604: it is not used by invokers,
        !           605: except when it is desired to wait for a previously invoked asynchronous
        !           606: operation to complete.
        !           607: \begin{quote}\index{RyWait}\small\begin{verbatim}
        !           608: int     RyWait (sd, id, out, secs, roi)
        !           609: int     sd,
        !           610:        *id,
        !           611:         secs;
        !           612: caddr_t *out;
        !           613: struct RoSAPindication *roi;
        !           614: \end{verbatim}\end{quote}
        !           615: The parameters to this procedure are:
        !           616: \begin{describe}
        !           617: \item[\verb"sd":] the association-descriptor;
        !           618: 
        !           619: \item[\verb"id":] the integer-value address of the invocation ID to wait for
        !           620: (use \verb"NULLIP" if any invocation ID is satisfactory);
        !           621: 
        !           622: \item[\verb"out":] an address-valued location which is updated if the call
        !           623: succeeds;
        !           624: 
        !           625: \item[\verb"secs":] the maximum number of seconds to wait
        !           626: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
        !           627: whereas a value of \verb"OK" indicates that the call should not block at all,
        !           628: e.g., a polling action);
        !           629: and,
        !           630: 
        !           631: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           632: which is updated only if the call fails.
        !           633: \end{describe}
        !           634: The \verb"RyWait" routine is analogous to the \verb"RoWaitRequest" routine in
        !           635: the \man librosy(3n) library,
        !           636: with the additional functions of:
        !           637: automatically encoding and decoding arguments, results, and parameters;
        !           638: invoking a dispatch routine for the performer on incoming invocations;
        !           639: and,
        !           640: also queuing events for future retrieval.
        !           641: 
        !           642: The \verb"RyWait" routine returns one of three values:
        !           643: \verb"NOTOK" (on failure),
        !           644: \verb"OK" (on reading a reply),
        !           645: or
        !           646: \verb"DONE" (when something else happens).
        !           647: 
        !           648: If the call to \verb"RyWait" returns the manifest constant \verb"NOTOK",
        !           649: then the \verb"RoSAPpreject" structure contained in
        !           650: the \verb"RoSAPindication" parameter
        !           651: \verb"roi" contains the reason for the failure.
        !           652: 
        !           653: If the call to \verb"RyWait" returns the manifest constant \verb"OK",
        !           654: then either a result or error has been returned from a previous invocation.
        !           655: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
        !           656: parameter is either \verb"ROI_RESULT" or \verb"ROI_ERROR",
        !           657: and the value of the address pointed to by \verb"out" is a newly allocated
        !           658: {\em C\/} structure for the operations result or error's parameter (if any).
        !           659: Note that if a result or parameter is returned,
        !           660: then it is the invoker's responsibility to release the memory used by the
        !           661: {\em C\/} structure, when appropriate.
        !           662: 
        !           663: If the call to \verb"RyWait" returns the manifest constant \verb"DONE",
        !           664: then an indication that the association is pending termination is returned.
        !           665: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
        !           666: parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
        !           667: Consult Section~\ref{ros:end} of \volone/ for the details.
        !           668: 
        !           669: Note that because the \man librosy(3n) library may queue events while waiting
        !           670: for a particular event,
        !           671: it is important to call \verb"RyWait" with a \verb"secs" parameter of
        !           672: \verb"OK" prior to deciding to explicitly block for activity
        !           673: (e.g., calling \verb"RoSelectMask" or \verb"xselect").
        !           674: 
        !           675: \section      {Miscellaneous Routines}
        !           676: There are a few miscellaneous routines of interest.
        !           677: 
        !           678: \subsection    {Association Termination}
        !           679: When an association is either released or aborted,
        !           680: it is important to expunge any information regarding queued operations from
        !           681: the run-time environment.
        !           682: The \verb"RyLose" routine is used to perform this function.
        !           683: \begin{quote}\index{RyLose}\small\begin{verbatim}
        !           684: int     RyLose (sd, roi)
        !           685: int     sd;
        !           686: struct RoSAPindication *roi;
        !           687: \end{verbatim}\end{quote}
        !           688: The parameters to this procedure are:
        !           689: \begin{describe}
        !           690: \item[\verb"sd":] the association-descriptor;
        !           691: and,
        !           692: 
        !           693: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
        !           694: which is updated only if the call fails.
        !           695: \end{describe}
        !           696: 
        !           697: \subsection    {Utility Routines}
        !           698: It may be useful,
        !           699: primarily for diagnostic purposes,
        !           700: to retrieve an entry for a particular operation or error from the tables
        !           701: compiled by the \man rosy(1) compiler.
        !           702: There are four routines for this purpose.
        !           703: 
        !           704: The routine \verb"findopbyop" takes a table and an operation code and returns
        !           705: the corresponding entry for the operation in the table,
        !           706: or the manifest constant \verb"NULL" on failure.
        !           707: \begin{quote}\index{findopbyop}\small\begin{verbatim}
        !           708: struct RyOperation *findopbyop (ryo, op)
        !           709: struct RyOperation *ryo;
        !           710: int     op;
        !           711: \end{verbatim}\end{quote}
        !           712: The parameters to this procedure are:
        !           713: \begin{describe}
        !           714: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table compiled by
        !           715: \pgm{rosy};
        !           716: and,
        !           717: 
        !           718: \item[\verb"op":] the operation code of the operation to search for in the
        !           719: table.
        !           720: \end{describe}
        !           721: 
        !           722: The routine \verb"findopbyname" takes a table and an operation name and returns
        !           723: the corresponding entry for the operation in the table,
        !           724: or the manifest constant \verb"NULL" on failure.
        !           725: \begin{quote}\index{findopbyname}\small\begin{verbatim}
        !           726: struct RyOperation *findopbyname (ryo, name)
        !           727: struct RyOperation *ryo;
        !           728: char   *name;
        !           729: \end{verbatim}\end{quote}
        !           730: The parameters to this procedure are:
        !           731: \begin{describe}
        !           732: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table compiled by
        !           733: \pgm{rosy};
        !           734: and,
        !           735: 
        !           736: \item[\verb"name":] the operation name of the operation to search for in the
        !           737: table.
        !           738: \end{describe}
        !           739: 
        !           740: The routine \verb"finderrbyerr" takes a table and an error code and returns
        !           741: the corresponding entry for the error in the table,
        !           742: or the manifest constant \verb"NULL" on failure.
        !           743: \begin{quote}\index{finderrbyerr}\small\begin{verbatim}
        !           744: struct RyError *finderrbyerr (rye, err)
        !           745: struct RyError *rye;
        !           746: int     err;
        !           747: \end{verbatim}\end{quote}
        !           748: The parameters to this procedure are:
        !           749: \begin{describe}
        !           750: \item[\verb"rye":] a pointer to a \verb"RyError" table compiled by
        !           751: \pgm{rosy};
        !           752: and,
        !           753: 
        !           754: \item[\verb"err":] the error code of the error to search for in the
        !           755: table.
        !           756: \end{describe}
        !           757: 
        !           758: The routine \verb"finderrbyname" takes a table and an error code and returns
        !           759: the corresponding entry for the error in the table,
        !           760: or the manifest constant \verb"NULL" on failure.
        !           761: \begin{quote}\index{finderrbyname}\small\begin{verbatim}
        !           762: struct RyError *finderrbyname (rye, name)
        !           763: struct RyError *rye;
        !           764: char   *name;
        !           765: \end{verbatim}\end{quote}
        !           766: The parameters to this procedure are:
        !           767: \begin{describe}
        !           768: \item[\verb"rye":] a pointer to a \verb"RyError" table compiled by
        !           769: \pgm{rosy};
        !           770: and,
        !           771: 
        !           772: \item[\verb"name":] the error name of the error to search for in the
        !           773: table.
        !           774: \end{describe}
        !           775: 
        !           776: \section      {Error Conventions}
        !           777: All of the routines in this library return the manifest constant \verb"NOTOK"
        !           778: on error,
        !           779: and also update the \verb"roi" parameter given to the routine.
        !           780: The element called \verb"roi_preject" in the \verb"RoSAPindication" structure
        !           781: encodes the reason for the failure.
        !           782: To determine the reason,
        !           783: one coerces a pointer to a \verb"RoSAPpreject" structure,
        !           784: and consults the \verb"rop_reason" element of this latter structure.
        !           785: This element can be given as a
        !           786: parameter to the routine \verb"RoErrString" which returns a null-terminated
        !           787: diagnostic string.
        !           788: \begin{quote}\index{RoErrString}\small\begin{verbatim}
        !           789: char   *RoErrString (c)
        !           790: int     c;
        !           791: \end{verbatim}\end{quote}
        !           792: 
        !           793: \section      {Compiling and Loading}
        !           794: Programs using the \man librosy(3n) library should include
        !           795: \verb"<isode/rosy.h>".
        !           796: The programs should also be loaded with \verb"-lisode".
        !           797: 
        !           798: %%% \section  {Changes Since the Last Release}\label{rosy:changes}
        !           799: %%% A brief summary of the major changes between v~\rosyprevrsn/ and
        !           800: %%% v~\rosyvrsn/ are now presented.
        !           801: %%% These are the user-visible changes only;
        !           802: %%% changes of a strictly internal nature are not discussed.
        !           803: 

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