⟦0f0d009e3⟧

TextFile

% run this through LaTeX with the appropriate wrapper

\f

\chapter       {Run-Time Environment}\label{librosy}
The \man librosap(3n) library implements the run-time environment for the
stubs generated by the \man rosy(1) program.

The routines described herein provide a more structured interface to the 
remote operations service (ROS).
They are used in the boilerplate routines which are described in the
following chapters.
Hence,
the more hasty reader may wish to skip this chapter on first reading of this
volume.

\f

\section	{Notice}
Please read the following important message.
\[\fbox{\begin{tabular}{lp{0.8\textwidth}}
\bf NOTE:&	When using the \man librosy(3n) library,
		no calls should be made to the \man librosap(3n) library.
		(That is, the \verb"RoXXX" routines should not be directly
		referenced.)

		There are three exceptions: \verb"RoSetService" and
		its related arguments (e.g., \verb"RoPService"),
		\verb"RoSelectMask", and \verb"RoErrString".
\end{tabular}}\]

\f

\section	{Conventions}
All of the routines in the \man librosy(3n) library are integer-valued.
Unless otherwise indicated,
they return the manifest constant \verb"OK" on success,
or \verb"NOTOK" otherwise.

The routines all work on an established association,
which is referenced by an association-descriptor.
This is usually the first parameter given to any of the routines in the
\man librosy(3n) library.
Further,
the last parameter is usually a pointer to a \verb"RoSAPindication" structure.
If a call to one of these routines fails,
then the structure is updated.
Section~\ref{ros:operations} of \volone/ describes this structure and how to
interpret error conditions and their severity.

\subsection	{Interface from ROSY}
For a given module, e.g., \verb"MODULE",
\pgm{rosy} will define two tables:
\begin{quote}\small\begin{verbatim}
struct RyOperation table_MODULE_Operations[];

struct RyError table_MODULE_Errors[];
\end{verbatim}\end{quote}

The \verb"RyOperation" structure is used to define the compiled parts of an
operation:
\begin{quote}\small\index{RyOperation}\begin{verbatim}
struct RyOperation {
    char   *ryo_name;
    int     ryo_op;

    IFP     ryo_arg_encode;
    IFP     ryo_arg_decode;
    IFP     ryo_arg_free;

    int     ryo_result;
    IFP     ryo_res_encode;
    IFP     ryo_res_decode;
    IFP     ryo_res_free;

    struct RyError **ryo_errors;
};
\end{verbatim}\end{quote}
The elements of this structure are:
\begin{describe}
\item[\verb"ryo\_name"/\verb"ryo\_op":] the operation name and code;

\item[\verb"ryo\_arg\_encode"/\verb"ryo\_arg\_decode":] the address of the
routines to encode or decode (respectively) the operation's argument from a
{\em C\/} structure to its corresponding abstract syntax
(present only if the operation takes an argument);

\item[\verb"ryo\_arg\_free":] the routine to free the {\em C\/} structure
created by the argument decode routine for the operation;

\item[\verb"ryo\_result":] non-zero if this operation returns a result;

\item[\verb"ryo\_res\_encode"/\verb"ryo\_res\_decode":] the address of the
routines to encode or decode (respectively) the operation's result from a
{\em C\/} structure to its corresponding abstract syntax
(present only if the operation returns a result);

\item[\verb"ryo\_res\_free":] the routine to free the {\em C\/} structure
created by the result decode routine for the operation;
and,

\item[\verb"ryo\_errors":] a pointer to null-terminated list of the errors
which this operation may generate (present only if the operation may returns
at least one error).
\end{describe}

The \verb"RyError" structure is used to define the compiled parts of an
error:
\begin{quote}\small\index{RyError}\begin{verbatim}
struct RyError {
    char   *rye_name;
    int     rye_err;

    IFP     rye_param_encode;
    IFP     rye_param_decode;
    IFP     rye_param_free;
};
\end{verbatim}\end{quote}
The elements of this structure are:
\begin{describe}
\item[\verb"rye\_name"/\verb"rye\_err":] the error name and code;

\item[\verb"rye\_param\_encode"/\verb"rye\_res\_decode":] the address of the
routines to encode or decode (respectively) the error's parameter from a
{\em C\/} structure to its corresponding abstract syntax
(present only if the error contains a parameter);
and,

\item[\verb"ryo\_param\_free":] the routine to free the {\em C\/} structure
created by the parameter decode routine for the error.
\end{describe}

\f

\section	{Routines for Initiators}
Initiators use the routines in the \man libacsap(3n) library for association
control.
These are described in Chapter~\ref{libacsap} of \volone/.

\f

\section	{Routines for Invokers}\label{ryoperation}
After forming an association,
invokers are able to request operations for execution by the performer.
Two interfaces are provided:
a synchronous interface and an asynchronous interface.

\subsection*	{Synchronous Interface}
Most invokers desire a simple interface for synchronous execution
of operations (the operation blocks until it is completed).
The \verb"RyOperation" routine is used to provide such an interface.
\begin{quote}\index{RyOperation}\small\begin{verbatim}
int     RyOperation (sd, ryo, op, in, out, response, roi)
int     sd;
struct RyOperation *ryo;
int     op,
       *response;
caddr_t in,
       *out;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"ryo":] a pointer to a \verb"RyOperation" table;

\item[\verb"op":] the operation code of the operation to invoke;

\item[\verb"response":] an integer-valued location which is updated if the
call succeeds;

\item[\verb"in":] the address of the {\em C\/} structure for the operation's
argument;

\item[\verb"out":] an address-valued location which is updated if the call
succeeds;
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the operation was not performed.
\end{describe}
The \verb"RyOperation" routine returns one of three values:
\verb"NOTOK" (on failure),
\verb"OK" (on reading a reply),
or
\verb"DONE" (when something else happens).

If the call to \verb"RyOperation" returns the manifest constant \verb"NOTOK",
then the \verb"RoSAPpreject" structure contained in
the \verb"RoSAPindication" parameter
\verb"roi" contains the reason for the failure.

If the call to \verb"RyOperation" returns the manifest constant \verb"OK",
then the \verb"response" and \verb"out" parameters are updated.
If the value of the integer pointed to by \verb"response" is \verb"RY_RESULT",
then the value of the address pointed to by \verb"out" is a newly allocated
{\em C\/} structure for the operation's result (if any).
If the value of the integer pointed to by \verb"response" is any other value,
then it indicates the error which the operation returned,
and the value of the address pointed to by \verb"out" is a newly allocated
{\em C\/} structure for the error's parameter (if any).
Note that if a result or parameter is returned,
then it is the invoker's responsibility to release the memory used by the
{\em C\/} structure, when appropriate.

If the call to \verb"RyOperation" returns the manifest constant \verb"DONE",
then an indication that the association is pending termination is returned.
The value of the \verb"roi_type" element of the \verb"RoSAPindication"
parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
Consult Section~\ref{ros:end} of \volone/ for the details,
as this normally does not happen to initiators.

The routine \verb"RyOperation" is simply a comprehensive interface for a more
general routine, \verb"RyOpInvoke", which invokes an operation:
\begin{quote}\index{RyOpInvoke}\small\begin{verbatim}
int     RyOpInvoke (sd, ryo, op, in, out, rfx, efx, class,
                invokeID, linkedID, priority, roi)
int     sd;
struct RyOperation *ryo;
int     op,
        class,
        invokeID,
       *linkedID,
        priority;
IFP     rfx,
        efx;
caddr_t in,
       *out;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"ryo":] a pointer to a \verb"RyOperation" table;

\item[\verb"op":] the operation code of the operation to invoke;

\item[\verb"in":] the address of the {\em C\/} structure for the operation's
argument;

\item[\verb"out":] an address-valued location which is updated if the call
succeeds;

\item[\verb"rfx":] the address of a dispatch routine to be invoked if
the operation returns a result;

\item[\verb"efx":] the address of a dispatch routine to be invoked if
the operation returns an error;

\item[\verb"class":] the operation class
(either \verb"ROS_SYNC" for a synchronous operation,
or \verb"ROS_ASYNC" for an asynchronous one);

\item[\verb"invokeID":] the invocation ID of this request;

\item[\verb"linkedID":] the linked ID of this request
(use \verb"NULLIP" if not linked);

\item[\verb"priority":] the priority of this request
(use \verb"ROS_NOPRIO" if the priority is undetermined);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the operation was not performed.
\end{describe}
This routine is exactly equivalent to the \verb"RoInvokeRequest" routine in the
\man librosap(3n) library,
with the additional functions of:
automatically encoding and decoding arguments, results, and parameters.
Hence,
the routine \verb"RyOperation",
is essentially a call to \verb"RyOpInvoke" with a few hard-wired parameters:
\begin{describe}
\item[\verb"class":]  \verb"ROS_SYNC";

\item[\verb"invokeID":] a unique-number;

\item[\verb"linkedID":] \verb"NULLIP";
and,

\item[\verb"priority":] \verb"ROS_NOPRIO".
\end{describe}

\subsection*	{Asynchronous Interface}
Although
most invokers desire a simple interface for synchronous execution,
it is also useful to have an asynchronous interface.
Further,
since a synchronous interface can be thought of as a degenerate subset of an
asynchronous interface,
most invokers use the asynchronous interface and simply ask for it to block
after making the invocation.
The \verb"RyStub" routine is used to provide such an interface.
\begin{quote}\index{RyStub}\small\begin{verbatim}
int     RyStub (sd, ryo, op, id, linked, in, rfx, efx,
                class, roi)
int     sd;
struct RyOperation *ryo;
int     op,
        id,
       *linked,
        class;
caddr_t in;
IFP     rfx,
        efx;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"ryo":] a pointer to a \verb"RyOperation" table;

\item[\verb"op":] the operation code of the operation to invoke;

\item[\verb"id":] the invocation identifier to use;

\item[\verb"linked":] the linked invocation identifier to use, if any
(use \verb"NULLIP" if this is not a linked reply);

\item[\verb"in":] the address of the {\em C\/} structure for the operation's
argument;

\item[\verb"rfx":] the address of a dispatch routine to be invoked if
the operation returns a result;

\item[\verb"efx":] the address of a dispatch routine to be invoked if
the operation returns an error or is rejected;

\item[\verb"class":] the operation class
(either \verb"ROS_SYNC" for a synchronous operation,
\verb"ROS_ASYNC" for an asynchronous operation,
or \verb"ROS_INTR" for a synchronous but user-interruptable operation);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the operation was not performed.
\end{describe}
The \verb"RyStub" routine returns one of three values:
\verb"NOTOK" (on failure),
\verb"OK" (on success),
or
\verb"DONE" (when something else happens).

If the call to \verb"RyStub" returns the manifest constant \verb"NOTOK",
then the \verb"RoSAPpreject" structure contained in
the \verb"RoSAPindication" parameter
\verb"roi" contains the reason for the failure.

If the call to \verb"RyStub" returns the manifest constant \verb"OK",
then the operation was queued or completed,
depending on the value of the \verb"class" parameter.
If the value of the \verb"class" parameter was \verb"ROS_ASYNC",
then \verb"RyStub" returns immediately after queuing the invocation.
Otherwise,
\verb"RyStub" waits for a response to the operation,
invokes the appropriate dispatch routine,
and then returns.
Both the result and error dispatch routines are invoked in the same way:
\begin{quote}\small\begin{verbatim}
result = (*fnx) (sd, id, reason, value, roi)
int     sd;
int     id,
        reason;
caddr_t value;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"id":] the invocation identifier associated with the result or
error;

\item[\verb"reason":] either \verb"RY_RESULT" if the result dispatch routine
is invoked, the error code if the error dispatch routine is invoked with an
error, or \verb"RY_REJECT" if the error dispatch routine is invoked with a
rejection;

\item[\verb"value":] the address of the {\em C\/} structure for the result or
error parameter (if any);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the result, error, or rejection is faulty.
\end{describe}
The dispatch routine should return the manifest constant \verb"OK"
unless you know what you're doing.
Note that if \verb"value" is present,
then the \man librosy(3n) library will automatically release the memory used
by the {\em C\/} structure when the dispatch routine returns.

If the call to \verb"RyStub" returns the manifest constant \verb"DONE",
then an indication that the association is pending termination is returned.
The value of the \verb"roi_type" element of the \verb"RoSAPindication"
parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
Consult Section~\ref{ros:end} of \volone/ for the details,
as this normally does not happen to initiators.

If the value of the \verb"class" parameter was \verb"ROS_INTR",
then \verb"RyStub" issues a synchronous call
(as described above for the \verb"ROS_SYNC" case).
However, if the user generates an interrupt,
usually by typing control-C (`\verb"^C"'),
while waiting for the response to the operation,
then \verb"RyStub" will return immediately with the value \verb"NOTOK"
and the \verb"rop_reason" element of the  \verb"RoSAPpreject" structure
contained in the \verb"RoSAPindication" parameter \verb"roi" will be set to
the value \verb"ROS_INTERRUPTED".

At this time,
the program may do other processing and later return to wait for the outcome
of the operation.
Instead,
the program may direct the run-time environment to silently discard any
outcome.
This is useful when the user wishes to abandon an inprogress operation and
really doesn't care what the results are
(i.e., when reading from a database).
The verb"RyDiscard" routine is used to accomplish this function:
\begin{quote}\index{RyDiscard}\small\begin{verbatim}
int     RyDiscard (sd, id, roi)
int     sd,
        id;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association descriptor;

\item[\verb"sd":] the invocation-identifier associated with the operation; and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only on failure.
\end{describe}
The \verb"RyDiscard" routine returns either \verb"NOTOK" (on failure)
or \verb"OK" (on success).

\f

\section	{Routines for Responders}
Responders use the routines in the \man libacsap(3n) library for association
control.
These are described in Chapter~\ref{libacsap} of \volone/.

\f

\section	{Routines for Performers}
After forming an association,
performers register the operations they are willing to perform.
They then typically wait for those operations to be invoked.

\subsection	{Registering Operations}\label{librosy:register}
The routine \verb"RyDispatch" is used to register a handler for an operation:
\begin{quote}\index{RyDispatch}\small\begin{verbatim}
int     RyDispatch (sd, ryo, op, fnx, roi)
int     sd;
struct RyOperation *ryo;
int     op;
IFP     fnx;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"ryo":] a pointer to a \verb"RyOperation" table;

\item[\verb"op":] the operation code of the operation to be registered;

\item[\verb"fnx":] the address of a dispatch routine to be invoked when
the operation is invoked;
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the call fails.
\end{describe}
An operation may be un-registered by using \verb"NULLIFP" for the \verb"fnx"
parameter.

When a registered operation is invoked
(from the routine \verb"RyWait" described in Section~\ref{librosy:waiting}),
the dispatch routine is invoked with five parameters:
\begin{quote}\small\begin{verbatim}
result = (*fnx) (sd, ryo, rox, in, roi)
int     sd;
struct RyOperation *ryo;
struct RoSAPinvoke *rox;
caddr_t in;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"ryo":] a pointer to a entry in the \verb"RyOperation" table
for this operation;

\item[\verb"rox":] a pointer to a \verb"RoSAPinvoke" structure containing
miscellaneous information regarding the operation being invoked
(e.g., the invocation id);

\item[\verb"in":] the address of the {\em C\/} structure for the operation's
argument (if any);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the operation was not performed.
\end{describe}
Note that if an argument is present for the operation,
then the \man librosy(3n) library will automatically release the memory used
by the {\em C\/} structure when the dispatch routine returns.

The return value of the dispatch routine is consulted to determine the
disposition of the invocation.
One of three values should be returned:
\verb"NOTOK", which indicates that some non-operational error occured;
\verb"OK", which indicates that the operation was handled;
or,
\verb"DONE", which indicates that the association is pending termination.

\subsection	{Responding to Operations}
If the operation corresponding to the dispatch routine does not return a
result,
then the routine may simply process the request and return.
Otherwise,
the dispatch routine should ultimately cause one of three routines to be
called to handle an invocation.

The routine \verb"RyDsResult" is used to return a result to an invocation.
\begin{quote}\index{RyDsResult}\small\begin{verbatim}
int     RyDsResult (sd, id, out, priority, roi)
int     sd;
int     id,
        priority;
caddr_t out;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"id":] the ID of the invocation being responded to;

\item[\verb"out":] the address of the {\em C\/} structure for the operation's
result (if any);

\item[\verb"priority":] the priority of the response
(use \verb"ROS_NOPRIO" if the priority is undetermined);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the call fails.
\end{describe}

The routine \verb"RyDsError" is used to return an error to an invocation.
\begin{quote}\index{RyDsError}\small\begin{verbatim}
int     RyDsError (sd, id, err, out, priority, roi)
int     sd;
int     id,
        err,
        priority;
caddr_t out;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"id":] the ID of the invocation being responded to;

\item[\verb"err":] the error code being returned;

\item[\verb"out":] the address of the {\em C\/} structure for the error's
parameter (if any);

\item[\verb"priority":] the priority of the response
(use \verb"ROS_NOPRIO" if the priority is undetermined);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the call fails.
\end{describe}

The routine \verb"RyDsUReject" is used to reject an invocation.
\begin{quote}\index{RyDsUReject}\small\begin{verbatim}
int	RyDsUReject (sd, id, reason, priority, roi)
int     sd;
int	id,
	reason,
	priority;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"id":] the ID of the invocation being rejected;

\item[\verb"reason":] the reason for the rejection
(codes are listed in Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons}
of \volone/);

\item[\verb"priority":] the priority of the response
(use \verb"ROS_NOPRIO" if the priority is undetermined);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the call fails.
\end{describe}

\f

\section	{Waiting for Events}\label{librosy:waiting}
The \verb"RyWait" routine is used by both invokers and performers to wait
for some event to occur.
Normally,
it is not used by invokers,
except when it is desired to wait for a previously invoked asynchronous
operation to complete.
\begin{quote}\index{RyWait}\small\begin{verbatim}
int     RyWait (sd, id, out, secs, roi)
int     sd,
       *id,
        secs;
caddr_t *out;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;

\item[\verb"id":] the integer-value address of the invocation ID to wait for
(use \verb"NULLIP" if any invocation ID is satisfactory);

\item[\verb"out":] an address-valued location which is updated if the call
succeeds;

\item[\verb"secs":] the maximum number of seconds to wait
(a value of \verb"NOTOK" indicates that the call should block indefinitely,
whereas a value of \verb"OK" indicates that the call should not block at all,
e.g., a polling action);
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the call fails.
\end{describe}
The \verb"RyWait" routine is analogous to the \verb"RoWaitRequest" routine in
the \man librosy(3n) library,
with the additional functions of:
automatically encoding and decoding arguments, results, and parameters;
invoking a dispatch routine for the performer on incoming invocations;
and,
also queuing events for future retrieval.

The \verb"RyWait" routine returns one of three values:
\verb"NOTOK" (on failure),
\verb"OK" (on reading a reply),
or
\verb"DONE" (when something else happens).

If the call to \verb"RyWait" returns the manifest constant \verb"NOTOK",
then the \verb"RoSAPpreject" structure contained in
the \verb"RoSAPindication" parameter
\verb"roi" contains the reason for the failure.

If the call to \verb"RyWait" returns the manifest constant \verb"OK",
then either a result or error has been returned from a previous invocation.
The value of the \verb"roi_type" element of the \verb"RoSAPindication"
parameter is either \verb"ROI_RESULT" or \verb"ROI_ERROR",
and the value of the address pointed to by \verb"out" is a newly allocated
{\em C\/} structure for the operations result or error's parameter (if any).
Note that if a result or parameter is returned,
then it is the invoker's responsibility to release the memory used by the
{\em C\/} structure, when appropriate.

If the call to \verb"RyWait" returns the manifest constant \verb"DONE",
then an indication that the association is pending termination is returned.
The value of the \verb"roi_type" element of the \verb"RoSAPindication"
parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
Consult Section~\ref{ros:end} of \volone/ for the details.

Note that because the \man librosy(3n) library may queue events while waiting
for a particular event,
it is important to call \verb"RyWait" with a \verb"secs" parameter of
\verb"OK" prior to deciding to explicitly block for activity
(e.g., calling \verb"RoSelectMask" or \verb"xselect").

\f

\section	{Miscellaneous Routines}
There are a few miscellaneous routines of interest.

\subsection	{Association Termination}
When an association is either released or aborted,
it is important to expunge any information regarding queued operations from
the run-time environment.
The \verb"RyLose" routine is used to perform this function.
\begin{quote}\index{RyLose}\small\begin{verbatim}
int     RyLose (sd, roi)
int     sd;
struct RoSAPindication *roi;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"sd":] the association-descriptor;
and,

\item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
which is updated only if the call fails.
\end{describe}

\subsection	{Utility Routines}
It may be useful,
primarily for diagnostic purposes,
to retrieve an entry for a particular operation or error from the tables
compiled by the \man rosy(1) compiler.
There are four routines for this purpose.

The routine \verb"findopbyop" takes a table and an operation code and returns
the corresponding entry for the operation in the table,
or the manifest constant \verb"NULL" on failure.
\begin{quote}\index{findopbyop}\small\begin{verbatim}
struct RyOperation *findopbyop (ryo, op)
struct RyOperation *ryo;
int     op;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"ryo":] a pointer to a \verb"RyOperation" table compiled by
\pgm{rosy};
and,

\item[\verb"op":] the operation code of the operation to search for in the
table.
\end{describe}

The routine \verb"findopbyname" takes a table and an operation name and returns
the corresponding entry for the operation in the table,
or the manifest constant \verb"NULL" on failure.
\begin{quote}\index{findopbyname}\small\begin{verbatim}
struct RyOperation *findopbyname (ryo, name)
struct RyOperation *ryo;
char   *name;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"ryo":] a pointer to a \verb"RyOperation" table compiled by
\pgm{rosy};
and,

\item[\verb"name":] the operation name of the operation to search for in the
table.
\end{describe}

The routine \verb"finderrbyerr" takes a table and an error code and returns
the corresponding entry for the error in the table,
or the manifest constant \verb"NULL" on failure.
\begin{quote}\index{finderrbyerr}\small\begin{verbatim}
struct RyError *finderrbyerr (rye, err)
struct RyError *rye;
int     err;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"rye":] a pointer to a \verb"RyError" table compiled by
\pgm{rosy};
and,

\item[\verb"err":] the error code of the error to search for in the
table.
\end{describe}

The routine \verb"finderrbyname" takes a table and an error code and returns
the corresponding entry for the error in the table,
or the manifest constant \verb"NULL" on failure.
\begin{quote}\index{finderrbyname}\small\begin{verbatim}
struct RyError *finderrbyname (rye, name)
struct RyError *rye;
char   *name;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"rye":] a pointer to a \verb"RyError" table compiled by
\pgm{rosy};
and,

\item[\verb"name":] the error name of the error to search for in the
table.
\end{describe}

\f

\section	{Error Conventions}
All of the routines in this library return the manifest constant \verb"NOTOK"
on error,
and also update the \verb"roi" parameter given to the routine.
The element called \verb"roi_preject" in the \verb"RoSAPindication" structure
encodes the reason for the failure.
To determine the reason,
one coerces a pointer to a \verb"RoSAPpreject" structure,
and consults the \verb"rop_reason" element of this latter structure.
This element can be given as a
parameter to the routine \verb"RoErrString" which returns a null-terminated
diagnostic string.
\begin{quote}\index{RoErrString}\small\begin{verbatim}
char   *RoErrString (c)
int     c;
\end{verbatim}\end{quote}

\f

\section	{Compiling and Loading}
Programs using the \man librosy(3n) library should include
\verb"<isode/rosy.h>".
The programs should also be loaded with \verb"-lisode".

%%% \f

\section	{Changes Since the Last Release}\label{rosy:changes}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦0f0d009e3⟧ TextFile

Derivation

TextFile
