Documented Version-Info and a few more calls

doc/Protocol-A.texi

 \input texinfo                         @c -*-texinfo-*-
-@c $Id: Protocol-A.texi,v 1.3 1996/06/14 16:14:32 byers Exp $
+@c $Id: Protocol-A.texi,v 1.4 1996/07/27 11:43:04 byers Exp $
 @c %**start of header
 @setfilename protocol-a.info
 @settitle LysKOM Protocol A
@@ -7,7 +7,7 @@
 @c %**end of header
 @iftex
 @parindent 0pt
-@font@tensltt=cmsltt12
+@font@tensltt=cmsltt10
 @begin tex
 \global\def\rett#1{{\let\t\sltt\tt #1}}
 \global\def\sltt#1{{\fam\ttfam\tensltt\let\t\rett #1}}
@@ -18,7 +18,7 @@
 @ifinfo
 This is the specification of LysKOM Protocol A v. 9.0
 
-Copyright @copyright{} 1995 Lysator ACS.
+Copyright @copyright{} 1995, 1996 Lysator ACS.
 
 Permission is granted to make and distribute verbatim copies of this
 specification provided the copyright notice and this permission notice
@@ -785,8 +785,9 @@ type of the array elements.
 
 Arrays are transmitted as an @code{<n> @{ <element> <element> ... @}} where
 @code{<n>} is the number of elements and each @code{<element>} is an element
-of the array. A special case is when the array is empty, in which case it is
-transmitted as @code{0 *}.
+of the array. A special case is when the array is empty, in which case
+the server transmits it as @code{0 *}. Note that the client must always
+transmit empty arrays as @code{0 @{ @}}.
 
 In some calls the client can ask the server not to send the array contents,
 only its length. In these cases the array is transmitted as @code{<n> *} where
@@ -1127,9 +1128,16 @@ The number of days an article should be kept before being removed from the confe
                 kom-news-conf       :   Conf-No;
                 motd-of-lyskom      :   Text-No;
               )
+
+        Version-Info ::=
+              ( protocol-version    :   INT32;
+                server-software     :   HOLLERITH
+                software-version    :   HOLLERITH
+              )
 @end example
 
-This data type contains information about the LysKOM server. The fields are
+These data types contain information about the LysKOM server. The fields
+of @code{Info} are
 
 @table @code
 @item version
@@ -1150,6 +1158,18 @@ The number of an article to display when LysKOM is entered or zero if there is
 none.
 @end table
 
+The fields of @code{Version-Info} are:
+
+@table @code
+@item protocol-version
+The version of protocol A the server is using. This may be used to
+ascertain which calls are available.
+@item server-software
+Human-readable name of the server software.
+@item software-version
+Human-readable name of the server software version.
+@end table
+
 
 @subsection Person Status Types
 
@@ -1897,10 +1917,10 @@ create conferences (@pxref{Security}).
 @example
         1 50 8
         @t{%1 9 0}
-        1 10 13HInlägg åt mig 00001000
+        1 10 13HInlägg @}t mig 00001000
         @t{=1 8}
         1 50 8
-        @t{=1 13HInlägg åt mig 0000
+        @t{=1 13HInlägg @}t mig 0000
            43 9 17 14 5 96 5 165 1
            43 9 17 14 5 96 5 165 1
            5 0 5 0 5 0 77 0 1 0}
@@ -1922,10 +1942,10 @@ create conferences (@pxref{Security}).
 
 This example creates a new conference named
 @ifinfo
-``Inlägg åt
+``Inlägg @}t
 @end ifinfo
 @iftex
-``Inl@"a{}gg @aa{}t 
+``Inl@"a{}gg @}t 
 @end iftex
 mig''@footnote{This conference is a standard Lysator conference. It's
 all Padrone's fault.}  which accepts all users as members and accepts
@@ -1952,7 +1972,7 @@ delete it. @b{[Is it possible to delete mailboxes?]}
         1 11 7
         @t{=1}
         1 50 7
-        @i{%1 9 0}
+        @t{%1 9 0}
 @end example
 
 This example shows the successful deletion of conference number seven.
@@ -2002,11 +2022,11 @@ member of the conference.
 
 @example
         1 46 119 0 10 0
-        @t{=1 @t{1} @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
+        @t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
         1 14 1 119 250 0
         @t{=1}
         1 46 119 0 10 0
-        @t{=1 @t{2} @{ @t{52 30 14 11 5 96 2 162 1   1 250 0 0 *}
+        @t{=1 2 @{ 52 30 14 11 5 96 2 162 1 1 250 0 0 *
                49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
 @end example
 
@@ -2031,12 +2051,12 @@ memberships.
 @i{Example:}
 @example
         1 46 5 0 100 0
-        @t{=1 @t{2} @{ @t{44 14 19 10 5 96 1 161 1 1   0 0 0 *}
+        @t{=1 2 @{ 44 14 19 10 5 96 1 161 1 1   0 0 0 *
                49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
         1 15 1 5
         @t{=1}
         1 46 5 0 100 0
-        @t{=1 @t{1} @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
+        @t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
 @end example
 
 This example shows how person 5 is removed from conference one. The
@@ -2065,14 +2085,14 @@ count on presentation texts.
         @t{=1 11HDavid Byers 1001
            26 15 11 9 5 96 0 160 1
            26 15 11 9 5 96 0 160 1
-           5 @t{0} 5 0 5 0 77 1 1 0}
+           5 0 5 0 5 0 77 1 1 0}
         1 16 6 1
         @t{=1}
         1 50 6
         @t{=1 11HDavid Byers 1001
            26 15 11 9 5 96 0 160 1
            26 15 11 9 5 96 0 160 1
-           5 @t{1} 5 0 5 0 77 1 1 0}
+           5 1 5 0 5 0 77 1 1 0}
 @end example
 
 This example shows how the presentation of person 6 is being changed. To
@@ -2103,14 +2123,14 @@ as @ref{set-presentation}.
         @t{=1 11HDavid Byers 1001
            26 15 11 9 5 96 0 160 1
            26 15 11 9 5 96 0 160 1
-           5 0 5 0 5 @t{0} 77 1 1 0}
+           5 0 5 0 5 0 77 1 1 0}
         1 17 6 1
         @t{=1}
         1 50 6
         @t{=1 11HDavid Byers 1001
            26 15 11 9 5 96 0 160 1
            26 15 11 9 5 96 0 160 1
-           5 0 5 0 5 @t{1} 77 1 1 0}
+           5 0 5 0 5 1 77 1 1 0}
 @end example
 
 This example shows how text number one is used as the message of the day
@@ -2139,14 +2159,14 @@ Typically, but not always, @code{admin} will be a letterbox.
         @t{=1 17HNyheter om LysKOM 0000
            48 11 17 13 8 91 5 255 1
            15 12 11  9 5 96 0 160 1
-           0 0 @t{0} 0 0 0 77 1 1 1}
+           0 0 0 0 0 0 77 1 1 1}
         1 18 4 6
         @t{=1}
         1 50 4
         @t{=1 17HNyheter om LysKOM 0000
            48 11 17 13 8 91 5 255 1
            15 12 11  9 5 96 0 160 1
-           0 0 @t{6} 0 0 0 77 1 1 1}
+           0 0 6 0 0 0 77 1 1 1}
 @end example
 
 This example makes the members of conference six supervisors of
@@ -2180,14 +2200,14 @@ the super-conference instead.
         @t{=1 17HNyheter om LysKOM 0000
            48 11 17 13 8 91 5 255 1
            15 12 11  9 5 96 0 160 1
-           0 0 6 @t{0} 0 0 77 1 1 1}
+           0 0 6 0 0 0 77 1 1 1}
         1 19 4 1
         @t{=1}
         1 50 4
         @t{=1 17HNyheter om LysKOM 0000
            48 11 17 13 8 91 5 255 1
            15 12 11  9 5 96 0 160 1
-           0 0 6 @t{1} 0 0 77 1 1 1}
+           0 0 6 1 0 0 77 1 1 1}
 @end example
 
 This example shows how all members of conference one are given
@@ -2219,14 +2239,188 @@ set to conference 8. the calls to @ref{get-conf-stat} demonstrate the
 change in the conference structure.
 
 
-
 @node set-conf-type, set-garb-nice, set-super-conf, Protocol Requests
+@subsection set-conf-type (1) Recommended
+
+@example
+        set-conf-type [21] (( conf-no : Conf-No;
+                                 type : Any-Conf-Type ))
+                -> ( );
+@end example
+
+Sets the conference type of conference @code{conf-no} to @code{type}.
+Before protocol version 8, @code{type} could only be four bits. Starting
+with protocol version 8, either a four-bit conference type or an
+@code{Extended-Conf-Type} is allowed.
+
+@example
+        1 78 4
+        @t{=1 17HNyheter om LysKOM 00001000 1 77}
+        1 21 4 00000000
+        @t{=1}
+        1 78 4
+        @t{=1 17HNyheter om LysKOM 00000000 1 77}
+@end example
+
+This example show a user removing the anarchy bit from conference four.
+The @ref{get-uconf-stat} call shows all eiht bits of the conference type
+before and after the set-conf-type call.
+
+
 @node set-garb-nice, get-marks, set-conf-type, Protocol Requests
+@subsection set-garb-nice (1) Recommended
+
+@example
+        set-garb-nice [22] (( conf-no : Conf-No;
+                                 nice : Garb-Nice ))
+                -> ( );
+@end example
+
+Sets the expiration time for articles in conference @code{conf-no} to
+@code{nice} days. An article that is older than the maximum expiration
+time of each conference it is sent to may be deleted by the LysKOM
+server unless it has marks.
+
+@example
+        1 78 4
+        @t{=1 17HNyheter om LysKOM 00000000 1 77}
+        1 22 4 7
+        @t{=1}
+        1 78 4
+        @t{=1 17HNyheter om LysKOM 00000000 1 7}
+@end example
+
+This example shows the expiration time of conference four being lowered
+from 77 to just seven days.
+
+
 @node get-marks, mark-text-old, set-garb-nice, Protocol Requests
+@subsection get-marks (1) Recommended
+
+@example
+        set-marks [23] ( )
+                -> ( result : Mark-List );
+@end example
+
+This call returns the list of marks the current user has set. 
+
+@example
+        1 23
+        @t{=1 3 @{ 13020 100 13043 95 12213 95 @}}
+@end example
+
+In this example, the current user has three marks, one on text 13020
+with mark type 100, one on text 13042 with mark type 95 and one on text
+12213 with mark type 95. The maximum number of marks may be arbitrarily
+limited in the LysKOM server.
+
 @node mark-text-old, get-text, get-marks, Protocol Requests
+@subsection mark-text-old (1) Obsolete
+
+@example
+        mark-text-old [24] (( text      : Text-No;
+                              mark-type : INT8 ))
+                -> ( );
+@end example
+
+This call has been replaced by @ref{mark-text} and @ref{unmark-text} and
+should no longer be used.
+
 @node get-text, get-text-stat, mark-text-old, Protocol Requests
+@subsection get-text (1) Recommended
+
+@example
+        get-text [25] (( text       : Text-No;
+                         start-char : INTEGER;
+                         end-char   : INTEGER; ))
+                -> ( result : HOLLERITH );
+@end example
+
+Retreive text number @code{text} from the LysKOM database, starting at
+position @code{start-char} and ending at position @code{end-char}. The
+first character in the text is numbered 0 and the last can be retrieved
+using @ref{get-text-stat}. It is also permitted to request a character
+position beyond the actual end of the text, in which case as much text
+as is available will be returned.
+
+@example
+        1 25 100 0 32766
+        @t{=1 25HYawn^JNothing is happening}
+        2 25 100 5 32766
+        @t{=2 20HNothing is happening}
+        3 25 100 0 3
+        @t{=3 4HYawn}
+@end example
+
+In this example, text 100 is requested three times, first from position
+0 to position 32766, then from position 5 to position 32766 and finally
+from position 0 to position 4. The first reply contains the entire text,
+the following two contain only the requested portion.
+
 @node get-text-stat, mark-as-read, get-text, Protocol Requests
+@subsection get-text-stat (1) Recommended
+
+@example
+        get-text-stat [26] ( text-no : Text-No )
+                -> ( result : Text-Stat );
+@end example
+
+Get information about text number @code{text-no}. The text-stat contains
+information about the size of the text, its recipients, comments, author
+and more.
+
+@example
+        1 26 100
+        =1 7 35 16 15 6 96 1 196 1 14 1 22 1
+        @t{7 @{ 0 7 6 85 0 15 6 1 
+            8 13 9 12 37 16 15 6 96 1 196 1
+            3 311 @}}
+@end example
+
+In this example, text number 100 was created by person 7 at
+approximately 4:35PM on July 15 1996. Its recipients are conferences 7
+and 15, and it was sent to conference 15 by person 13 at 16:37 on the
+day it was created. The text has a single comment: text 311.
+
 @node mark-as-read, create-text, get-text-stat, Protocol Requests
+@subsection mark-as-read (1) Recommended
+
+@example
+        mark-as-read [27] (( conference : Conf-No;
+                             text       : ARRAY Local-Text-No; ))
+                -> ( );
+@end example
+
+Marks text @code{text} in confernece number @code{conference} as read
+for the current user. This call updates the membership record for the
+user.
+
+@example
+        1 9 6 7
+        @t{=1 20 32 11 17 6 96 3 198 1 7 1 240 0 *}
+        1 78 7
+@ifinfo
+        @t{=1 13HInlägg @}t mig 00001000 241 1}
+@end ifinfo
+@iftex
+        @t{=1 13HInl@"a{}gg @}t mig 00001000 241 1}
+@end iftex
+        1 27 7 1 @{ 241 @}
+        @t{=1}
+        1 9 6 7
+        @t{=1 20 32 11 17 6 96 3 198 1 7 1 241 0 *}
+@end example
+
+This example shows person 6 marking local text number 241 in conference
+7 as read. In the firs query-read-texts call the person has read local
+text 240, but nothing higher. The mark-as-read call is reflected in the
+second query-unread-texts call, where the user is seen to have read text
+241 in conference 7.
+
+To mark a global text number as read it is necessary to translate it
+into local text numbers by looking as the Misc-Info List in the
+Text-Stat and calling mark-as-read once for each recipient.
+
 @node create-text, delete-text, mark-as-read, Protocol Requests
 @node delete-text, add-recipient, create-text, Protocol Requests
 @node add-recipient, sub-recipient, delete-text, Protocol Requests