⟦321e1e834⟧

TextFile

.TH LIBRTSAP 3N "23 Sep 1986"
.\" $Header: /f/osi/rtsap/RCS/librtsap.3n,v 7.0 89/11/23 22:22:15 mrose Rel $
.\"
.\"
.\" $Log:	librtsap.3n,v $
.\" Revision 7.0  89/11/23  22:22:15  mrose
.\" Release 6.0
.\" 
.SH NAME
librtsap \- Reliable Transfer Services library
.SH SYNOPSIS
.B "#include <isode/rtsap.h>"
.sp
\fIcc\fR\0...\0\fB\-lisode\fR
.SH DESCRIPTION
The \fIlibrtsap\fR library contains a set of routines which implement
reliable transfer facilities.
In essence,
they implement a Reliable Transfer Service Point (RtSAP) interface.
.PP
The information contained herein is skeletal:
consult the \fIUser's Manual\fR for actual examples of how ISO servers and
clients are coded and interact with the \fIlibrtsap\fR library.
.SH ADDRESSES
RtSAP addresses are represented by the \fBRtSAPaddr\fR structure.
This contains a session address,
and the port number of the RtSAP as found in the \fIisoservices\fR\0(5)
database.
.SH "SERVER INITIALIZATION"
A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
with the argument vector listed in the ISODE services database.
The server's very first action is to re\-capture the RtSAP state as
recorded by \fItsapd\fR.
This is accomplished by calling \fBRtBInit\fR.
Information returned by this call is equivalent to the parameters passed by
the X.410 OPEN.INDICATION event.
If the call is successful,
the program can then examine the argument vector that was passed via
\fIexecvp\fR
(it's important to call \fBRtBInit\fR prior to reading \fBargc\fR and
\fBargv\fR).
If the call to \fBRtBInit\fR is not successful,
information returned by the call indicates the reason for failure.
.PP
After examining the information provided by \fBRtBInit\fR
(and possibly the argument vector),
the server should either accept or reject the association.
If accepting, the \fBRtBeginResponse\fR routine is called with the parameter
\fBstatus\fR set to
.sp
.in +.5i
.nf
.ta \w'RTS_VALIDATE  'u
RTS_ACCEPT	association accepted
.re
.fi
.in -.5i
.sp
(which corresponds to the accepting RT\-BEGIN.RESPONSE action).
If the call is successful,
the association has been bound.
If un\-successful,
information returned by the call indicates the reason for failure.
If rejecting, the \fBRtBeginResponse\fR routine is also called,
but with the parameter \fBstatus\fR set to one of:
.sp
.in +.5i
.nf
.ta \w'RTS_VALIDATE  'u
RTS_BUSY	busy
RTS_RECOVER	cannot recover
RTS_VALIDATE	validation failure
RTS_MODE	unacceptable dialogue mode
.re
.fi
.in -.5i
.sp
(which corresponds to the refusing X.410 OPEN.RESPONSE action),
and the program may exit.
.SH "CLIENT INITIALIZATION"
A program requesting an ISO service calls \fBRtBeginRequest\fR
(which corresponds to the X.410 OPEN.REQUEST action).
If successful (depending on the responder's choice of \fBstatus\fR),
the association is bound.
If un\-successful,
information returned by the call indicates the reason for failure.
.SH ASSOCIATION\-DESCRIPTORS
Once an association has been bound via a successful return from
\fBRtBeginResponse\fR (for servers) or \fBRtBeginRequest\fR (for clients),
an association is referenced by a small integer
(returned in a structure passed to these calls) called an
\fIassociation\-descriptor\fR.
The association\-descriptor appears as an argument to the peer routines
described below.
.PP
By default,
events associated with a association\-descriptor are synchronous in nature:
activity in the network won't generate an INDICATION event without program
first asking to be told of any activity.
To mark an association\-descriptor as asynchronous,
a call to \fBRtSetIndications\fR is made with the address of an integer
function to handle incoming events.
Upon a successful return from \fBRtSetIndications\fR,
the event handler will be called in this fashion:
.sp
.in +.5i
.B "(*handler) (sd, rti);"
.in -.5i
.sp
where \fBsd\fR is the association\-descriptor,
and \fBrti\fR is a pointer to a \fBRtSAPindication\fR structure.
Any value returned by the event\-handler is ignored.
.PP
Note well: the \fB\-lisode\fR library uses the \fB\-ltsap\fR library to
provide this interface.
The latter library  uses the SIGEMT signal to provide this service.
Programs loaded with \fB\-ltsap\fR that use asynchronous
association\-descriptors should NOT use SIGEMT for other purposes.
.PP
For synchronous multiplexing of several associations,
the routine \fBRtSelectMask\fR
updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
.SH PEER
A fatal failure (consult the \fIUser's Manual\fR)
on return from any of these routines results in the association being unbound.
.sp
.in +.5i
.nf
.ta \w'\fBRtTransferRequest\fR  'u
\fIroutine\fR	\fIaction\fR
\fBRtPTurnRequest\fR	RT\-TURN\-PLEASE.REQUEST
\fBRtGTurnRequest\fR	RT\-TURN\-GIVE.REQUEST
\fBRtTransferRequest\fR	RT\-TRANSFER.REQUEST
\fBRtWaitRequest\fR	RT\-WAIT.REQUEST (synchronous wait)
\fBRtEndRequest\fR	X.410 CLOSE.REQUEST
\fBRtEndResponse\fR	X.410 CLOSE.RESPONSE
.re
.fi
.in -.5i
.sp
Note that the \fBRtWaitRequest\fR routine returns data from the peer by
allocating memory.
It should be freed before the structure is re\-used.
.PP
Finally,
the routine \fBRtErrString\fR takes a failure code from a \fBRtSAPabort\fR
structure and returns a null\-terminated diagnostic string.
.SH FILES
.nf
.ta \w'\*(EDisoservices  'u
\*(EDisoentities	ISODE entities database
\*(EDisobjects	ISODE objects database
\*(EDisoservices	ISODE services database
.re
.fi
.SH "SEE ALSO"
libacsap(3n), librosap (3n), isoentities(5), isobjects (5), isoservices(5)
.br
\fIThe ISO Development Environment: User's Manual\fR,
.br
ISO DIS 9066/1:
\fIInformation Processing Systems \-\- Text Communication \-\- MOTIS \-\-
Reliable Transfer Part 1: Model and Service Definition\fR,
.br 
CCITT Recommendation X.410:
\fIMessage Handling Systems: Remote Operations and Reliable Transfer Server\fR
.SH DIAGNOSTICS
All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
.SH AUTHORS
Marshall T. Rose,
The Wollongong Group
.SH BUGS
Do not confuse association\-descriptors with file\-descriptors.
Unlike file\-descriptors which are implemented by the kernel,
association\-descriptors to not work across \fIfork\fRs and \fIexec\fRs.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦321e1e834⟧ TextFile

Derivation

TextFile
