Return to librosap.3n CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/rosap/librosap.3n, revision 1.1

1.1     ! root        1: .TH LIBROSAP 3N "21 Aug 1986"
        !             2: .\" $Header: /f/osi/rosap/RCS/librosap.3n,v 7.0 89/11/23 22:21:11 mrose Rel $
        !             3: .\"
        !             4: .\" Based on an TCP-based implementation by George Michaelson of University
        !             5: .\" College London.
        !             6: .\"
        !             7: .\"
        !             8: .\" $Log:      librosap.3n,v $
        !             9: .\" Revision 7.0  89/11/23  22:21:11  mrose
        !            10: .\" Release 6.0
        !            11: .\" 
        !            12: .SH NAME
        !            13: librosap \- Remote Operations Services library
        !            14: .SH SYNOPSIS
        !            15: .B "#include <isode/rosap.h>"
        !            16: .sp
        !            17: \fIcc\fR\0...\0\fB\-lisode\fR
        !            18: .SH DESCRIPTION
        !            19: The \fIlibrosap\fR library contains a set of routines which implement
        !            20: remote operations facilities.
        !            21: In essence,
        !            22: they implement a Remote Operations Service Point
        !            23: (RoSAP) interface for connection-oriented user applications.
        !            24: .PP
        !            25: The information contained herein is skeletal:
        !            26: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
        !            27: clients are coded and interact with the \fIlibrosap\fR library.
        !            28: .SH "SERVICE DISCIPLINES"
        !            29: Three remote operation service disciplines are implemented by the library:
        !            30: \*(lqbasic\*(rq, \*(lqadvanced\*(rq, and \*(lqcomplete\*(rq.
        !            31: The basic service is based on the ECMA technical report and an underlying
        !            32: session service.
        !            33: This remote operation service is selected when the \fBRoBeginRequest\fR and
        !            34: \fBRoBeginResponse\fR routines are used.
        !            35: In addition to making minimal requirements on the provider at the remote site,
        !            36: the \*(lqbasic\*(rq discipline also limits the users by permitting only the
        !            37: initiator to make invocations.
        !            38: Certain applications, e.g., message handling systems, require more freedom
        !            39: (such as two\-way invocations) along with more reliability.
        !            40: The advanced service uses a different underlying service for ROS,
        !            41: namely the reliable transfer service.
        !            42: If the \fBRtBeginRequest\fR and \fBRtBeginResponse\fR routines
        !            43: (from the \fIlibrtsap\fR\0(3n) library)
        !            44: are used 
        !            45: to establish an association for remote operations services,
        !            46: then the \*(lqadvanced\*(rq remote operation service is selected.
        !            47: Finally,
        !            48: the complete service supports linked operations,
        !            49: and can be selected by using the \fBAcAssocRequest\fR and
        !            50: \fBAcAssocResponse\fR routines (from the \fIlibacsap\fR\0(3n) library) are
        !            51: used to establish an association.
        !            52: .PP
        !            53: In the addressing and initialization descriptions that follow,
        !            54: keep in mind the distinctions described above.
        !            55: Finally,
        !            56: note that the corresponding \*(lqend\*(rq routines should be used based on
        !            57: the \*(lqbegin\*(rq routines selected.
        !            58: .SH ADDRESSES
        !            59: RoSAP addresses are represented by the \fBRoSAPaddr\fR structure.
        !            60: This contains a session address,
        !            61: and the port number of the RoSAP as found in the \fIisoservices\fR\0(5)
        !            62: database.
        !            63: .SH "SERVER INITIALIZATION"
        !            64: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
        !            65: with the argument vector listed in the ISODE services database.
        !            66: The server's very first action is to re\-capture the RoSAP state as
        !            67: recorded by \fItsapd\fR.
        !            68: This is accomplished by calling \fBRoInit\fR.
        !            69: Information returned by this call is equivalent to the parameters passed by a
        !            70: RO\-BEGIN.INDICATION event.
        !            71: If the call is successful,
        !            72: the program can then examine the argument vector that was passed via
        !            73: \fIexecvp\fR
        !            74: (it's important to call \fBRoInit\fR prior to reading \fBargc\fR and
        !            75: \fBargv\fR).
        !            76: If the call to \fBRoInit\fR is not successful,
        !            77: information returned by the call indicates the reason for failure.
        !            78: .PP
        !            79: After examining the information provided by \fBRoInit\fR
        !            80: (and possibly the argument vector),
        !            81: the server should either accept or reject the association.
        !            82: If accepting, the \fBRoBeginResponse\fR routine is called with the parameter
        !            83: \fBstatus\fR set to
        !            84: .sp
        !            85: .in +.5i
        !            86: .nf
        !            87: .ta \w'ROS_VALIDATE  'u
        !            88: ROS_ACCEPT     association accepted
        !            89: .re
        !            90: .fi
        !            91: .in -.5i
        !            92: .sp
        !            93: (which corresponds to the accepting RO\-BEGIN.RESPONSE action).
        !            94: If the call is successful,
        !            95: the association has been bound.
        !            96: If un\-successful,
        !            97: information returned by the call indicates the reason for failure.
        !            98: If rejecting, the \fBRoBeginResponse\fR routine is also called,
        !            99: but with the parameter \fBstatus\fR set to one of:
        !           100: .sp
        !           101: .in +.5i
        !           102: .nf
        !           103: .ta \w'ROS_VALIDATE  'u
        !           104: ROS_VALIDATE   authentication failure
        !           105: ROS_BUSY       busy
        !           106: .re
        !           107: .fi
        !           108: .in -.5i
        !           109: .sp
        !           110: (which corresponds to the refusing RO\-BEGIN.RESPONSE action),
        !           111: and the program may exit.
        !           112: .SH "CLIENT INITIALIZATION"
        !           113: A program requesting an ISO service calls \fBRoBeginRequest\fR
        !           114: (which corresponds to the RO\-BEGIN.REQUEST action).
        !           115: If successful (depending on the responder's choice of \fBstatus\fR),
        !           116: the association is bound.
        !           117: If un\-successful,
        !           118: information returned by the call indicates the reason for failure.
        !           119: .SH ASSOCIATION\-DESCRIPTORS
        !           120: Once an association has been bound via a successful return from
        !           121: \fBRoBeginResponse\fR (for servers) or \fBRoBeginRequest\fR (for clients),
        !           122: an association is referenced by a small integer
        !           123: (returned in a structure passed to these calls) called an
        !           124: \fIassociation\-descriptor\fR.
        !           125: The association\-descriptor appears as an argument to the peer routines
        !           126: described below.
        !           127: .PP
        !           128: By default,
        !           129: events associated with a association\-descriptor are synchronous in nature:
        !           130: activity in the network won't generate an INDICATION event without program
        !           131: first asking to be told of any activity.
        !           132: To mark an association\-descriptor as asynchronous,
        !           133: a call to \fBRoSetIndications\fR is made with the address of an integer
        !           134: function to handle incoming events.
        !           135: Upon a successful return from \fBRoSetIndications\fR,
        !           136: the event handler will be called in this fashion:
        !           137: .sp
        !           138: .in +.5i
        !           139: .B "(*handler) (sd, roi);"
        !           140: .in -.5i
        !           141: .sp
        !           142: where \fBsd\fR is the association\-descriptor,
        !           143: and \fBroi\fR is a pointer to a \fBRoSAPindication\fR structure.
        !           144: Any value returned by the event\-handler is ignored.
        !           145: .PP
        !           146: Note well: the \fB\-lisode\fR library uses the \fB\-ltsap\fR library to
        !           147: provide this interface.
        !           148: The latter library  uses the SIGEMT signal to provide this service.
        !           149: Programs loaded with \fB\-ltsap\fR that use asynchronous
        !           150: association\-descriptors should NOT use SIGEMT for other purposes.
        !           151: .PP
        !           152: For synchronous multiplexing of several associations,
        !           153: the routine \fBRoSelectMask\fR
        !           154: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
        !           155: .SH PEER
        !           156: A fatal failure (consult the \fIUser's Manual\fR)
        !           157: on return from any of these routines results in the association being unbound.
        !           158: .sp
        !           159: .in +.5i
        !           160: .nf
        !           161: .ta \w'\fBRoRejectURequest\fR  'u
        !           162: \fIroutine\fR  \fIaction\fR
        !           163: \fBRoInvokeRequest\fR  RO\-INVOKE.REQUEST
        !           164: \fBRoResultRequest\fR  RO\-RESULT.REQUEST
        !           165: \fBRoErrorRequest\fR   RO\-ERROR.REQUEST
        !           166: \fBRoRejectURequest\fR RO\-REJECT\-U.REQUEST
        !           167: \fBRoWaitRequest\fR    RO\-WAIT.REQUEST (synchronous wait)
        !           168: \fBRoEndRequest\fR     RO\-END.REQUEST
        !           169: \fBRoEndResponse\fR    RO\-END.RESPONSE
        !           170: .re
        !           171: .fi
        !           172: .in -.5i
        !           173: .sp
        !           174: Note that the \fBRoWaitRequest\fR routine returns data from the peer by
        !           175: allocating memory.
        !           176: It should be freed before the structure is re\-used.
        !           177: .PP
        !           178: Finally,
        !           179: the routine \fBRoErrString\fR takes a failure code from a \fBRoSAPpreject\fR
        !           180: structure and returns a null\-terminated diagnostic string.
        !           181: .SH FILES
        !           182: .nf
        !           183: .ta \w'\*(EDisoservices  'u
        !           184: \*(EDisoentities       ISODE entities database
        !           185: \*(EDisobjects ISODE objects database
        !           186: \*(EDisoservices       ISODE services database
        !           187: .re
        !           188: .fi
        !           189: .SH "SEE ALSO"
        !           190: libacsap (3n), librtsap (3n), isoentities(5), isobjects (5), isoservices(5)
        !           191: .br
        !           192: \fIThe ISO Development Environment: User's Manual\fR,
        !           193: .br
        !           194: ISO 9072/1:
        !           195: \fIInformation Processing Systems \-\- Text Communication \-\- MOTIS \-\-
        !           196: Remote Operations Part 1: Model, Notation and Service Definition\fR,
        !           197: .br 
        !           198: CCITT Recommendation X.410:
        !           199: \fIMessage Handling Systems: Remote Operations and Reliable Transfer Server\fR,
        !           200: .br 
        !           201: ECMA Technical Report:
        !           202: \fIRemote Operations: Concepts, Notation and Connection\-Oriented Mappings\fR,
        !           203: Final Draft, July, 1985
        !           204: .SH DIAGNOSTICS
        !           205: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
        !           206: .SH AUTHOR
        !           207: Marshall T. Rose
        !           208: .PP
        !           209: This library is based on an initial implementation by George
        !           210: Michaelson,
        !           211: University College London.
        !           212: .SH BUGS
        !           213: Do not confuse association\-descriptors with file\-descriptors.
        !           214: Unlike file\-descriptors which are implemented by the kernel,
        !           215: association\-descriptors to not work across \fIfork\fRs and \fIexec\fRs.

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