Return to initiator.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter       {Boilerplate for Initiators}\label{cook:initiator}
        !             4: Let's consider how to build an initiator which is also an invoker.
        !             5: In Chapter~\ref{cook:discipline},
        !             6: two forms for an initiator were identified:
        !             7: {\em interactive}, and {\em embedded}.
        !             8: The interactive initiator can be thought of as simply being a special case of
        !             9: an embedded initiator.
        !            10: Hence,
        !            11: we will start by describing the embedded initiator and then describe the
        !            12: additional structure added to form an interactive initiator.
        !            13: 
        !            14: If you have access to the source tree for this release,
        !            15: the directory \file{others/lookup/} contains the boilerplate described herein.
        !            16: 
        !            17: \section      {Embedded Initiator}
        !            18: An embedded initiator is characterized as automatically managing an association
        !            19: and invoking operations as required.
        !            20: There are four areas: association establishment, operation invocation,
        !            21: association release, and error handling.
        !            22: 
        !            23: \subsection    {Association Establishment}
        !            24: The application-entity information and presentation address for the desired
        !            25: service are computed,
        !            26: along with the application context and default presentation context
        !            27: information for the service.
        !            28: In addition,
        !            29: a session reference identifier is chosen.
        !            30: 
        !            31: The routine \verb"AcAssocRequest" is called to establish an association for
        !            32: the service.
        !            33: The arguments are strictly boilerplate:
        !            34: they will work unaltered for most applications.
        !            35: If the association is established,
        !            36: then the routine \verb"RoSetService" is used to tell the remote operations
        !            37: library to use the presentation service as its underlying service.
        !            38: 
        !            39: \tgrindfile{ryinit-estab}
        !            40: \newpage
        !            41: 
        !            42: \subsection    {Operation Invocation}
        !            43: We'll consider how an operation is invoked using both the synchronous and
        !            44: asynchronous interfaces.
        !            45: 
        !            46: \subsubsection {Synchronous Invocation}
        !            47: First, the argument (if any) for the operation is allocated and initialized.
        !            48: Then the macro \verb"op_MODULE_operation" is called,
        !            49: which is really a call to the \verb"RyOperation" routine described in
        !            50: Section~\ref{ryoperation} on page~\pageref{ryoperation}.
        !            51: One of three values is expected to be returned.
        !            52: 
        !            53: If the manifest constant \verb"NOTOK" is returned,
        !            54: then some error has occured prior to invoking the operation.
        !            55: The most common error is the association being abruptly terminated due to
        !            56: network failure.
        !            57: 
        !            58: If the manifest constant \verb"OK" is returned,
        !            59: then the responder replied with either a result or an error for the invocation.
        !            60: The variable \verb"response" is consulted to determine if a result is
        !            61: present, or if not, which error is present.
        !            62: For each case,
        !            63: the \verb"out" variable is cast to the appropriate variable,
        !            64: the application-specific code is executed,
        !            65: and then the structure is freed.
        !            66: 
        !            67: If the manifest constant \verb"DONE" is returned,
        !            68: then the responder indicated that it wished to terminate the association.
        !            69: Since the association was established in a way which prohibited this behavior,
        !            70: this return is unlikely.
        !            71: 
        !            72: \tgrindfile{ryinit-invoke}
        !            73: \newpage
        !            74: 
        !            75: \subsubsection {ASynchronous Invocation}
        !            76: 
        !            77: \tgrindfile{ryinit-async}
        !            78: \newpage
        !            79: 
        !            80: 
        !            81: \subsection    {Association Release}
        !            82: Terminating the assocation is simple:
        !            83: the routine \verb"AcRelRequest" is called.
        !            84: 
        !            85: \tgrindfile{ryinit-release}
        !            86: \newpage
        !            87: 
        !            88: \subsection    {Error Handling}
        !            89: These routines for the most part are all straight-forward.
        !            90: \begin{describe}
        !            91: \item[\verb"ros\_adios":] used to report a ROS error and terminate;
        !            92: 
        !            93: \item[\verb"ros\_advise":] used to report a ROS error;
        !            94: 
        !            95: \item[\verb"acs\_adios":] used to report an ACS error and terminate;
        !            96: 
        !            97: \item[\verb"acs\_advise":] used to report an ACS error;
        !            98: 
        !            99: \item[\verb"adios":] used to report an error and terminate;
        !           100: and,
        !           101: 
        !           102: \item[\verb"advise":] used to report an error.
        !           103: \end{describe}
        !           104: It is assumed that there is a definition of the form
        !           105: \begin{quote}\small\begin{verbatim}
        !           106: char   *myname = "myname";
        !           107: \end{verbatim}\end{quote}
        !           108: for use by the \verb"advise" routine.
        !           109: 
        !           110: \tgrindfile{ryinit-error}
        !           111: \newpage
        !           112: 
        !           113: \section      {Interactive Initiator}
        !           114: Now, let's build on these routines to write an initiator which is interactive:
        !           115: the user runs a program and interactively directs the invocation of
        !           116: operations.
        !           117: 
        !           118: \subsection    {Include File}
        !           119: Let's consider what an \verb"#include" file, say \verb"ryinitiator.h",
        !           120: might look like.
        !           121: First, the standard \man librosy(3n) definitions are included,
        !           122: then a \verb"dispatch" structure is defined,
        !           123: along with the boilerplate routines.
        !           124: The \verb"dispatch" structure will be used by the boilerplate to invoke a
        !           125: user-supplied routine that will invoke the operation.
        !           126: 
        !           127: \tgrindfile{ryinitiator-h}
        !           128: \newpage
        !           129: 
        !           130: \subsection    {Worker Routines}
        !           131: Now, let's consider the routines which implement the interactive initiator.
        !           132: There are only two: \verb"ryinitiator" and \verb"getline".
        !           133: 
        !           134: The \verb"ryinitiator" routine does most of the work:
        !           135: \begin{quote}\index{ryinitiator}\small\begin{verbatim}
        !           136: int     ryinitiator (argc, argv, myservice, mycontext,
        !           137:                 mypci, ops, dispatches, quit)
        !           138: int     argc;
        !           139: char  **argv,
        !           140:        *myservice,
        !           141:        *mycontext,
        !           142:        *mypci;
        !           143: struct RyOperation ops[];
        !           144: struct dispatch *dispatches;
        !           145: IFP    quit;
        !           146: \end{verbatim}\end{quote}
        !           147: The parameters to this procedure are:
        !           148: \begin{describe}
        !           149: \item[\verb"argc"/\verb"argv":] the argument vector (and its length)
        !           150: that the program was invoked with;
        !           151: 
        !           152: \item[\verb"myservice":] the non-host portion of the application-entity
        !           153: information;
        !           154: 
        !           155: \item[\verb"mycontext":] the application context name of the service;
        !           156: 
        !           157: \item[\verb"mypci":] the abstract syntax of the service;
        !           158: 
        !           159: \item[\verb"ops":] the operations defined for the service;
        !           160: 
        !           161: \item[\verb"dispatches":] a pointer to a \verb"dispatch" table;
        !           162: and,
        !           163: 
        !           164: \item[\verb"quit":] a routine to call when the association is to be
        !           165: terminated.
        !           166: \end{describe}
        !           167: The function of this routine is straight-forward though tedious.
        !           168: First, \verb"myname" is initialized to the name that the program was invoked
        !           169: with.
        !           170: Next, a rudimentary argument check is done,
        !           171: and the application-entity information and presentation address for the desired
        !           172: service are computed.
        !           173: This is followed by computing the application context and default
        !           174: presentation context information for the service,
        !           175: along with a session reference identifier.
        !           176: Finally, some diagnostic information may be printed out if the program will
        !           177: operate in interactive mode.
        !           178: 
        !           179: The routine \verb"AcAssocRequest" is called to establish an association for
        !           180: the service.
        !           181: If successful,
        !           182: the routine \verb"RoSetService" is used to tell the remote operations library
        !           183: to use the presentation service as the underlying service.
        !           184: 
        !           185: The interactive loop is then entered:
        !           186: a line is read from the standard input (the \verb"getline" routine is called),
        !           187: it is broken into components,
        !           188: a search is performed on the dispatch table to find a matching keyword,
        !           189: and then finally the user-supplied routine is called.
        !           190: When end-of-file is reached
        !           191: (or if the user-supplied routine returns the manifest constant \verb"DONE"),
        !           192: the assocation is released.
        !           193: 
        !           194: If additional arguments were present on the invocation line,
        !           195: then the named operation is invoked instead of entering an interactive loop.
        !           196: 
        !           197: \tgrindfile{ryinitiator-c}
        !           198: \newpage
        !           199: 
        !           200: \subsection    {An Example}
        !           201: An example of an interactive initiator written using this boilerplate is
        !           202: shown in Section~\ref{passwd:initiator} on page~\pageref{passwd:initiator}.
        !           203: However,
        !           204: a brief exposition of the \verb"dispatch" structure and possible
        !           205: \verb"help" and \verb"quit" routines are shown here.
        !           206: 
        !           207: \tgrindfile{ryinit-example}

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