source: tags/0.9/doc/description.lyx @ 9

Last change on this file since 9 was 9, checked in by willem, 11 years ago

willem
File size: 62.3 KB
Line 
1#LyX 2.0 created this file. For more info see http://www.lyx.org/
2\lyxformat 413
3\begin_document
4\begin_header
5\textclass article
6\use_default_options true
7\maintain_unincluded_children false
8\language english
9\language_package default
10\inputencoding auto
11\fontencoding global
12\font_roman default
13\font_sans default
14\font_typewriter default
15\font_default_family default
16\use_non_tex_fonts false
17\font_sc false
18\font_osf false
19\font_sf_scale 100
20\font_tt_scale 100
21
22\graphics default
23\default_output_format default
24\output_sync 0
25\bibtex_command default
26\index_command default
27\paperfontsize 10
28\spacing single
29\use_hyperref false
30\papersize a4paper
31\use_geometry true
32\use_amsmath 1
33\use_esint 1
34\use_mhchem 1
35\use_mathdots 1
36\cite_engine basic
37\use_bibtopic false
38\use_indices false
39\paperorientation portrait
40\suppress_date false
41\use_refstyle 1
42\index Index
43\shortcut idx
44\color #008000
45\end_index
46\secnumdepth 3
47\tocdepth 3
48\paragraph_separation indent
49\paragraph_indentation 0bp
50\quotes_language english
51\papercolumns 1
52\papersides 1
53\paperpagestyle default
54\tracking_changes false
55\output_changes false
56\html_math_output 0
57\html_css_as_file 0
58\html_be_strict false
59\end_header
60
61\begin_body
62
63\begin_layout Title
64STOPOS
65\end_layout
66
67\begin_layout Author
68Willem Vermin, willem.vermin@surfsara.nl
69\end_layout
70
71\begin_layout Date
722013-02-01
73\end_layout
74
75\begin_layout Abstract
76In this article we describe the internals and externals of the program stopos.
77 Stopos is primarily designed to facilitate the running of many tasks on
78 a cluster computer.
79 It is based on managing lines in a pool.
80 These lines will in general be used as command lines to define tasks.
81 Stopos is heavily inspired by ToPoS (https://grid.sara.nl/wiki/index.php/Using_the
82_Grid/ToPoS) and experiences with disparm (https://www.surfsara.nl/systems/lisa/so
83ftware/disparm).
84 This project was carried out as a
85\begin_inset Quotes eld
86\end_inset
87
88seed-fund project
89\begin_inset Quotes erd
90\end_inset
91
92 at SURFsara.
93\end_layout
94
95\begin_layout Subsection*
96Introduction
97\end_layout
98
99\begin_layout Standard
100A typical use of a cluster computer, such as SURFsara's Lisa system
101\begin_inset Foot
102status open
103
104\begin_layout Plain Layout
105https://www.surfsara.nl/systems/lisa
106\end_layout
107
108\end_inset
109
110, is running many tasks each task with different parameters.
111 A typical example is a parameter scan.
112 A typical job allocates a node, and runs a number of tasks in parallel.
113 The number of tasks should in general be equal to the amount of cores and/or
114 the amount of memory.
115 Sometimes, thousands of these jobs are necessary, and normally, the job
116 scripts are generated by a script.
117 In a homogeneous cluster (all nodes have the same amount of cores and the
118 same amount of memory) this is clumsy but doable, but when the cluster
119 is heterogeneous (such as the Lisa cluster), it becomes very hard to use
120 all types of nodes available, and adapt the number of processes to the
121 node where the job runs on.
122 To deal with this problems, stopos was created: a server that manages a
123 pool of lines.
124 These lines are defined by the user, and the server serves the lines to
125 jobs, such that each line is produced once.
126 Earlier successful solutions are ToPoS
127\begin_inset Foot
128status open
129
130\begin_layout Plain Layout
131https://grid.sara.nl/wiki/index.php/Using_the_Grid/ToPoS
132\end_layout
133
134\end_inset
135
136 and disparm
137\begin_inset Foot
138status open
139
140\begin_layout Plain Layout
141https://www.surfsara.nl/systems/lisa/software/disparm
142\end_layout
143
144\end_inset
145
146.
147 ToPoS is designed to be used on a server that can be accessed from the
148 Grid, while disparm is based on files in the user's home directory.
149 We think that ToPoS is not optimal for the Lisa system because of lack
150 of cluster-based authentication and the universal access.
151 The disparm approach is in these respects better, but in practice it appeared
152 that the performance under heavy usage the performance was too low, and
153 the reliability was not 100%: sometimes a line was produced more than once,
154 or lines were not produced at all.
155 Also, it is not possible to add lines dynamically: all lines have to be
156 inserted at the beginning.
157 We think that the approach followed in stopos is a well balanced solution,
158 particularly fit to be used in a cluster environment.
159\end_layout
160
161\begin_layout Subsection*
162Usage
163\end_layout
164
165\begin_layout Standard
166A typical usage of stopos is:
167\end_layout
168
169\begin_layout Itemize
170fill the pool with lines
171\end_layout
172
173\begin_layout Itemize
174start jobs, each job gets one or more lines from the pool, and remove the
175 lines that are not needed any more
176\begin_inset Foot
177status open
178
179\begin_layout Plain Layout
180Normally, a line is produced only once.
181 However, the user can request that a line is produced and used again, for
182 example in the case the previous task handling this line ran into a time
183 limit.
184\end_layout
185
186\end_inset
187
188
189\end_layout
190
191\begin_layout Itemize
192maybe: add more lines to the pool
193\end_layout
194
195\begin_layout Standard
196Stopos is implemented as a shell function in the bash shell, or as an alias
197 in the (t)csh shell.
198 Stopos calls the program stoposclient and transforms it's output to environment
199 variables, the most important being STOPOS_RC and STOPOS_VALUE.
200\end_layout
201
202\begin_layout Standard
203The commands to create the pool:
204\begin_inset Newline newline
205\end_inset
206
207
208\end_layout
209
210\begin_layout Standard
211
212\family typewriter
213\begin_inset space ~
214\end_inset
215
216module load stopos
217\begin_inset space ~
218\end_inset
219
220
221\begin_inset space ~
222\end_inset
223
224
225\begin_inset space ~
226\end_inset
227
228
229\begin_inset space ~
230\end_inset
231
232
233\begin_inset space ~
234\end_inset
235
236
237\begin_inset space ~
238\end_inset
239
240# activate the stopos software
241\end_layout
242
243\begin_layout Standard
244
245\family typewriter
246\begin_inset space ~
247\end_inset
248
249stopos create
250\begin_inset space ~
251\end_inset
252
253
254\begin_inset space ~
255\end_inset
256
257
258\begin_inset space ~
259\end_inset
260
261
262\begin_inset space ~
263\end_inset
264
265
266\begin_inset space ~
267\end_inset
268
269
270\begin_inset space ~
271\end_inset
272
273
274\begin_inset space ~
275\end_inset
276
277
278\begin_inset space ~
279\end_inset
280
281
282\begin_inset space ~
283\end_inset
284
285
286\begin_inset space ~
287\end_inset
288
289
290\begin_inset space ~
291\end_inset
292
293
294\begin_inset space ~
295\end_inset
296
297# create the pool
298\end_layout
299
300\begin_layout Standard
301
302\family typewriter
303\begin_inset space ~
304\end_inset
305
306stopos add parmfile
307\begin_inset space ~
308\end_inset
309
310
311\begin_inset space ~
312\end_inset
313
314
315\begin_inset space ~
316\end_inset
317
318
319\begin_inset space ~
320\end_inset
321
322
323\begin_inset space ~
324\end_inset
325
326
327\begin_inset space ~
328\end_inset
329
330# add the lines in the file parmfile to the pool
331\begin_inset Newline newline
332\end_inset
333
334
335\end_layout
336
337\begin_layout Standard
338In a job script, one could use code like this:
339\begin_inset Newline newline
340\end_inset
341
342
343\begin_inset Newline newline
344\end_inset
345
346
347\family typewriter
348
349\begin_inset space ~
350\end_inset
351
352module load stopos
353\begin_inset space ~
354\end_inset
355
356
357\begin_inset space ~
358\end_inset
359
360
361\begin_inset space ~
362\end_inset
363
364
365\begin_inset space ~
366\end_inset
367
368
369\begin_inset space ~
370\end_inset
371
372
373\begin_inset space ~
374\end_inset
375
376
377\begin_inset space ~
378\end_inset
379
380
381\begin_inset space ~
382\end_inset
383
384
385\begin_inset space ~
386\end_inset
387
388
389\begin_inset space ~
390\end_inset
391
392
393\begin_inset space ~
394\end_inset
395
396# activate the stopos software
397\end_layout
398
399\begin_layout Standard
400
401\family typewriter
402\begin_inset space ~
403\end_inset
404
405stopos next
406\begin_inset space ~
407\end_inset
408
409
410\begin_inset space ~
411\end_inset
412
413
414\begin_inset space ~
415\end_inset
416
417
418\begin_inset space ~
419\end_inset
420
421
422\begin_inset space ~
423\end_inset
424
425
426\begin_inset space ~
427\end_inset
428
429
430\begin_inset space ~
431\end_inset
432
433
434\begin_inset space ~
435\end_inset
436
437
438\begin_inset space ~
439\end_inset
440
441
442\begin_inset space ~
443\end_inset
444
445
446\begin_inset space ~
447\end_inset
448
449
450\begin_inset space ~
451\end_inset
452
453
454\begin_inset space ~
455\end_inset
456
457
458\begin_inset space ~
459\end_inset
460
461
462\begin_inset space ~
463\end_inset
464
465
466\begin_inset space ~
467\end_inset
468
469
470\begin_inset space ~
471\end_inset
472
473# get a line from the pool
474\end_layout
475
476\begin_layout Standard
477
478\family typewriter
479\begin_inset space ~
480\end_inset
481
482if [ $STOPOS_RC = OK] ; then # check the return code
483\end_layout
484
485\begin_layout Standard
486
487\family typewriter
488\begin_inset space ~
489\end_inset
490
491
492\begin_inset space ~
493\end_inset
494
495
496\begin_inset space ~
497\end_inset
498
499run_my_prog $STOPOS_VALUE
500\begin_inset space ~
501\end_inset
502
503
504\begin_inset space ~
505\end_inset
506
507# run the program using the line as parameter
508\end_layout
509
510\begin_layout Standard
511
512\family typewriter
513\begin_inset space ~
514\end_inset
515
516fi
517\begin_inset Newline newline
518\end_inset
519
520
521\end_layout
522
523\begin_layout Standard
524A more elaborate job script, using all cores available on a node is available
525 in the Appendix, together with the man page of stopos.
526\end_layout
527
528\begin_layout Subsection*
529Tasks and communication
530\end_layout
531
532\begin_layout Standard
533Stopos is a shell function or an alias that calls stoposclient.
534 Stoposclient communicates with stoposserver via an http server (apache
535\begin_inset Foot
536status open
537
538\begin_layout Plain Layout
539http://httpd.apache.org/
540\end_layout
541
542\end_inset
543
544, thttpd
545\begin_inset Foot
546status open
547
548\begin_layout Plain Layout
549http://opensource.dyc.edu/sthttpd
550\end_layout
551
552\end_inset
553
554, ...).
555 The server sends commands to the server, and transforms the answers to
556 a format that are sourced by stopos to define environment variables.
557 Care is taken that communications between the client and the server are
558 short in length: at most a few kilobytes are sent between client and server.
559 
560\end_layout
561
562\begin_layout Subsubsection*
563Tasks of the client
564\end_layout
565
566\begin_layout Standard
567The client parses it's command line, sends the appropriate command to the
568 server and receives the response.
569 This response is put in a form that can be 'eval-ed' so that environment
570 variables are set.
571\begin_inset Newline newline
572\end_inset
573
574
575\begin_inset Newline newline
576\end_inset
577
578The client recognizes the following commands on its command line:
579\end_layout
580
581\begin_layout Itemize
582
583\family typewriter
584-h,--h
585\begin_inset space ~
586\end_inset
587
588
589\begin_inset space ~
590\end_inset
591
592
593\begin_inset space ~
594\end_inset
595
596
597\begin_inset space ~
598\end_inset
599
600
601\begin_inset space ~
602\end_inset
603
604
605\begin_inset space ~
606\end_inset
607
608
609\begin_inset space ~
610\end_inset
611
612
613\begin_inset space ~
614\end_inset
615
616
617\begin_inset space ~
618\end_inset
619
620
621\begin_inset space ~
622\end_inset
623
624
625\begin_inset space ~
626\end_inset
627
628
629\begin_inset space ~
630\end_inset
631
632
633\begin_inset space ~
634\end_inset
635
636
637\begin_inset space ~
638\end_inset
639
640
641\begin_inset space ~
642\end_inset
643
644
645\begin_inset space ~
646\end_inset
647
648
649\begin_inset space ~
650\end_inset
651
652
653\begin_inset space ~
654\end_inset
655
656
657\begin_inset space ~
658\end_inset
659
660
661\begin_inset space ~
662\end_inset
663
664
665\begin_inset space ~
666\end_inset
667
668
669\begin_inset space ~
670\end_inset
671
672
673\begin_inset space ~
674\end_inset
675
676
677\begin_inset space ~
678\end_inset
679
680
681\begin_inset space ~
682\end_inset
683
684
685\begin_inset space ~
686\end_inset
687
688
689\begin_inset space ~
690\end_inset
691
692
693\begin_inset space ~
694\end_inset
695
696: prints a short usage message
697\end_layout
698
699\begin_layout Itemize
700
701\family typewriter
702-v,--v
703\begin_inset space ~
704\end_inset
705
706
707\begin_inset space ~
708\end_inset
709
710
711\begin_inset space ~
712\end_inset
713
714
715\begin_inset space ~
716\end_inset
717
718
719\begin_inset space ~
720\end_inset
721
722
723\begin_inset space ~
724\end_inset
725
726
727\begin_inset space ~
728\end_inset
729
730
731\begin_inset space ~
732\end_inset
733
734
735\begin_inset space ~
736\end_inset
737
738
739\begin_inset space ~
740\end_inset
741
742
743\begin_inset space ~
744\end_inset
745
746
747\begin_inset space ~
748\end_inset
749
750
751\begin_inset space ~
752\end_inset
753
754
755\begin_inset space ~
756\end_inset
757
758
759\begin_inset space ~
760\end_inset
761
762
763\begin_inset space ~
764\end_inset
765
766
767\begin_inset space ~
768\end_inset
769
770
771\begin_inset space ~
772\end_inset
773
774
775\begin_inset space ~
776\end_inset
777
778
779\begin_inset space ~
780\end_inset
781
782
783\begin_inset space ~
784\end_inset
785
786
787\begin_inset space ~
788\end_inset
789
790
791\begin_inset space ~
792\end_inset
793
794
795\begin_inset space ~
796\end_inset
797
798
799\begin_inset space ~
800\end_inset
801
802
803\begin_inset space ~
804\end_inset
805
806
807\begin_inset space ~
808\end_inset
809
810
811\begin_inset space ~
812\end_inset
813
814: prints the version number
815\end_layout
816
817\begin_layout Itemize
818
819\family typewriter
820create [ -p,--pool POOL ]
821\begin_inset space ~
822\end_inset
823
824
825\begin_inset space ~
826\end_inset
827
828
829\begin_inset space ~
830\end_inset
831
832
833\begin_inset space ~
834\end_inset
835
836
837\begin_inset space ~
838\end_inset
839
840
841\begin_inset space ~
842\end_inset
843
844
845\begin_inset space ~
846\end_inset
847
848
849\begin_inset space ~
850\end_inset
851
852
853\begin_inset space ~
854\end_inset
855
856:
857\family default
858 create a pool
859\end_layout
860
861\begin_layout Itemize
862
863\family typewriter
864status [ -p,--pool POOL ]
865\begin_inset space ~
866\end_inset
867
868
869\begin_inset space ~
870\end_inset
871
872
873\begin_inset space ~
874\end_inset
875
876
877\begin_inset space ~
878\end_inset
879
880
881\begin_inset space ~
882\end_inset
883
884
885\begin_inset space ~
886\end_inset
887
888
889\begin_inset space ~
890\end_inset
891
892
893\begin_inset space ~
894\end_inset
895
896
897\begin_inset space ~
898\end_inset
899
900:
901\family default
902 get status from a pool
903\end_layout
904
905\begin_layout Itemize
906
907\family typewriter
908purge [ -p,--pool POOL]
909\begin_inset space ~
910\end_inset
911
912
913\begin_inset space ~
914\end_inset
915
916
917\begin_inset space ~
918\end_inset
919
920
921\begin_inset space ~
922\end_inset
923
924
925\begin_inset space ~
926\end_inset
927
928
929\begin_inset space ~
930\end_inset
931
932
933\begin_inset space ~
934\end_inset
935
936
937\begin_inset space ~
938\end_inset
939
940
941\begin_inset space ~
942\end_inset
943
944
945\begin_inset space ~
946\end_inset
947
948
949\begin_inset space ~
950\end_inset
951
952:
953\family default
954 remove a pool
955\end_layout
956
957\begin_layout Itemize
958
959\family typewriter
960pools
961\begin_inset space ~
962\end_inset
963
964
965\begin_inset space ~
966\end_inset
967
968
969\begin_inset space ~
970\end_inset
971
972
973\begin_inset space ~
974\end_inset
975
976
977\begin_inset space ~
978\end_inset
979
980
981\begin_inset space ~
982\end_inset
983
984
985\begin_inset space ~
986\end_inset
987
988
989\begin_inset space ~
990\end_inset
991
992
993\begin_inset space ~
994\end_inset
995
996
997\begin_inset space ~
998\end_inset
999
1000
1001\begin_inset space ~
1002\end_inset
1003
1004
1005\begin_inset space ~
1006\end_inset
1007
1008
1009\begin_inset space ~
1010\end_inset
1011
1012
1013\begin_inset space ~
1014\end_inset
1015
1016
1017\begin_inset space ~
1018\end_inset
1019
1020
1021\begin_inset space ~
1022\end_inset
1023
1024
1025\begin_inset space ~
1026\end_inset
1027
1028
1029\begin_inset space ~
1030\end_inset
1031
1032
1033\begin_inset space ~
1034\end_inset
1035
1036
1037\begin_inset space ~
1038\end_inset
1039
1040
1041\begin_inset space ~
1042\end_inset
1043
1044
1045\begin_inset space ~
1046\end_inset
1047
1048
1049\begin_inset space ~
1050\end_inset
1051
1052
1053\begin_inset space ~
1054\end_inset
1055
1056
1057\begin_inset space ~
1058\end_inset
1059
1060
1061\begin_inset space ~
1062\end_inset
1063
1064
1065\begin_inset space ~
1066\end_inset
1067
1068
1069\begin_inset space ~
1070\end_inset
1071
1072
1073\begin_inset space ~
1074\end_inset
1075
1076:
1077\family default
1078 what are my pools
1079\end_layout
1080
1081\begin_layout Itemize
1082
1083\family typewriter
1084add [ -p,--pool POOL] [ FILENAME ]:
1085\family default
1086 add a file to the pool
1087\end_layout
1088
1089\begin_layout Itemize
1090
1091\family typewriter
1092next [-m,--multi]
1093\begin_inset space ~
1094\end_inset
1095
1096
1097\begin_inset space ~
1098\end_inset
1099
1100
1101\begin_inset space ~
1102\end_inset
1103
1104
1105\begin_inset space ~
1106\end_inset
1107
1108
1109\begin_inset space ~
1110\end_inset
1111
1112
1113\begin_inset space ~
1114\end_inset
1115
1116
1117\begin_inset space ~
1118\end_inset
1119
1120
1121\begin_inset space ~
1122\end_inset
1123
1124
1125\begin_inset space ~
1126\end_inset
1127
1128
1129\begin_inset space ~
1130\end_inset
1131
1132
1133\begin_inset space ~
1134\end_inset
1135
1136
1137\begin_inset space ~
1138\end_inset
1139
1140
1141\begin_inset space ~
1142\end_inset
1143
1144
1145\begin_inset space ~
1146\end_inset
1147
1148
1149\begin_inset space ~
1150\end_inset
1151
1152
1153\begin_inset space ~
1154\end_inset
1155
1156
1157\begin_inset space ~
1158\end_inset
1159
1160:
1161\family default
1162 get next line from the pool
1163\end_layout
1164
1165\begin_layout Itemize
1166
1167\family typewriter
1168remove [ KEY ]
1169\begin_inset space ~
1170\end_inset
1171
1172
1173\begin_inset space ~
1174\end_inset
1175
1176
1177\begin_inset space ~
1178\end_inset
1179
1180
1181\begin_inset space ~
1182\end_inset
1183
1184
1185\begin_inset space ~
1186\end_inset
1187
1188
1189\begin_inset space ~
1190\end_inset
1191
1192
1193\begin_inset space ~
1194\end_inset
1195
1196
1197\begin_inset space ~
1198\end_inset
1199
1200
1201\begin_inset space ~
1202\end_inset
1203
1204
1205\begin_inset space ~
1206\end_inset
1207
1208
1209\begin_inset space ~
1210\end_inset
1211
1212
1213\begin_inset space ~
1214\end_inset
1215
1216
1217\begin_inset space ~
1218\end_inset
1219
1220
1221\begin_inset space ~
1222\end_inset
1223
1224
1225\begin_inset space ~
1226\end_inset
1227
1228
1229\begin_inset space ~
1230\end_inset
1231
1232
1233\begin_inset space ~
1234\end_inset
1235
1236
1237\begin_inset space ~
1238\end_inset
1239
1240
1241\begin_inset space ~
1242\end_inset
1243
1244
1245\begin_inset space ~
1246\end_inset
1247
1248:
1249\family default
1250 remove line
1251\end_layout
1252
1253\begin_layout Itemize
1254
1255\family typewriter
1256dump [ -p,--p POOL ]
1257\begin_inset space ~
1258\end_inset
1259
1260
1261\begin_inset space ~
1262\end_inset
1263
1264
1265\begin_inset space ~
1266\end_inset
1267
1268
1269\begin_inset space ~
1270\end_inset
1271
1272
1273\begin_inset space ~
1274\end_inset
1275
1276
1277\begin_inset space ~
1278\end_inset
1279
1280
1281\begin_inset space ~
1282\end_inset
1283
1284
1285\begin_inset space ~
1286\end_inset
1287
1288
1289\begin_inset space ~
1290\end_inset
1291
1292
1293\begin_inset space ~
1294\end_inset
1295
1296
1297\begin_inset space ~
1298\end_inset
1299
1300
1301\begin_inset space ~
1302\end_inset
1303
1304
1305\begin_inset space ~
1306\end_inset
1307
1308
1309\begin_inset space ~
1310\end_inset
1311
1312:
1313\family default
1314 dump a line from the pool
1315\end_layout
1316
1317\begin_layout Standard
1318For example:
1319\begin_inset Newline newline
1320\end_inset
1321
1322
1323\begin_inset Newline newline
1324\end_inset
1325
1326
1327\family typewriter
1328stopos create -p mypool1
1329\end_layout
1330
1331\begin_layout Standard
1332
1333\family typewriter
1334stopos add -p mypool1 parmfile
1335\begin_inset Newline newline
1336\end_inset
1337
1338
1339\end_layout
1340
1341\begin_layout Standard
1342The -p (or --pool) flag defines the name of the pool file to be used (
1343\begin_inset Quotes eld
1344\end_inset
1345
1346parmfile
1347\begin_inset Quotes erd
1348\end_inset
1349
1350 in this example).
1351 If no -p or --pool flag is present, the value of the pool is taken from
1352 the environment variable STOPOS_POOL.
1353 If that is not available, the value
1354\begin_inset Quotes eld
1355\end_inset
1356
1357pool
1358\begin_inset Quotes erd
1359\end_inset
1360
1361 is used.
1362\end_layout
1363
1364\begin_layout Standard
1365The -m (or --multi) flag signifies that lines that are already produces,
1366 may be produced again.
1367\end_layout
1368
1369\begin_layout Standard
1370The default for FILENAME is standard input.
1371\end_layout
1372
1373\begin_layout Standard
1374If no value is given for KEY with the
1375\begin_inset Quotes eld
1376\end_inset
1377
1378remove
1379\begin_inset Quotes erd
1380\end_inset
1381
1382 command, the value of the environment variable STOPOS_KEY is used.
1383 This value is set by the
1384\begin_inset Quotes eld
1385\end_inset
1386
1387next
1388\begin_inset Quotes erd
1389\end_inset
1390
1391 command.
1392\begin_inset Newline newline
1393\end_inset
1394
1395
1396\begin_inset Newline newline
1397\end_inset
1398
1399The following environment variables are set by the command
1400\begin_inset Quotes eld
1401\end_inset
1402
1403stopos
1404\begin_inset Quotes erd
1405\end_inset
1406
1407:
1408\end_layout
1409
1410\begin_layout Itemize
1411
1412\family typewriter
1413STOPOS_RC
1414\begin_inset space ~
1415\end_inset
1416
1417
1418\begin_inset space ~
1419\end_inset
1420
1421
1422\begin_inset space ~
1423\end_inset
1424
1425
1426\begin_inset space ~
1427\end_inset
1428
1429
1430\begin_inset space ~
1431\end_inset
1432
1433
1434\begin_inset space ~
1435\end_inset
1436
1437
1438\begin_inset space ~
1439\end_inset
1440
1441:
1442\family default
1443 return code of the command.
1444 The value
1445\begin_inset Quotes eld
1446\end_inset
1447
1448OK
1449\begin_inset Quotes erd
1450\end_inset
1451
1452 means that things went well
1453\end_layout
1454
1455\begin_layout Itemize
1456
1457\family typewriter
1458STOPOS_VALUE
1459\begin_inset space ~
1460\end_inset
1461
1462
1463\begin_inset space ~
1464\end_inset
1465
1466
1467\begin_inset space ~
1468\end_inset
1469
1470
1471\begin_inset space ~
1472\end_inset
1473
1474 :
1475\family default
1476 result of the
1477\begin_inset Quotes eld
1478\end_inset
1479
1480next
1481\begin_inset Quotes erd
1482\end_inset
1483
1484 and
1485\begin_inset Quotes eld
1486\end_inset
1487
1488pools
1489\begin_inset Quotes erd
1490\end_inset
1491
1492 command
1493\end_layout
1494
1495\begin_layout Itemize
1496
1497\family typewriter
1498STOPOS_COMMITTED :
1499\family default
1500 number of times the
1501\begin_inset Quotes eld
1502\end_inset
1503
1504next
1505\begin_inset Quotes erd
1506\end_inset
1507
1508 line was produced
1509\end_layout
1510
1511\begin_layout Itemize
1512
1513\family typewriter
1514STOPOS_KEY
1515\begin_inset space ~
1516\end_inset
1517
1518
1519\begin_inset space ~
1520\end_inset
1521
1522
1523\begin_inset space ~
1524\end_inset
1525
1526
1527\begin_inset space ~
1528\end_inset
1529
1530
1531\begin_inset space ~
1532\end_inset
1533
1534
1535\begin_inset space ~
1536\end_inset
1537
1538:
1539\family default
1540 set by the
1541\begin_inset Quotes eld
1542\end_inset
1543
1544next
1545\begin_inset Quotes erd
1546\end_inset
1547
1548 command.
1549 Used by the
1550\begin_inset Quotes eld
1551\end_inset
1552
1553remove
1554\begin_inset Quotes erd
1555\end_inset
1556
1557 command
1558\end_layout
1559
1560\begin_layout Itemize
1561
1562\family typewriter
1563STOPOS_COUNT
1564\begin_inset space ~
1565\end_inset
1566
1567
1568\begin_inset space ~
1569\end_inset
1570
1571
1572\begin_inset space ~
1573\end_inset
1574
1575
1576\begin_inset space ~
1577\end_inset
1578
1579:
1580\family default
1581 set by
1582\begin_inset Quotes eld
1583\end_inset
1584
1585status
1586\begin_inset Quotes erd
1587\end_inset
1588
1589: number of lines added to the pool
1590\end_layout
1591
1592\begin_layout Itemize
1593
1594\family typewriter
1595STOPOS_PRESENT
1596\begin_inset space ~
1597\end_inset
1598
1599
1600\begin_inset space ~
1601\end_inset
1602
1603
1604\begin_inset space ~
1605\end_inset
1606
1607:
1608\family default
1609 set by
1610\begin_inset Quotes eld
1611\end_inset
1612
1613status
1614\begin_inset Quotes erd
1615\end_inset
1616
1617: number of lines in the pool
1618\end_layout
1619
1620\begin_layout Itemize
1621
1622\family typewriter
1623STOPOS_PRESENT0
1624\begin_inset space ~
1625\end_inset
1626
1627
1628\begin_inset space ~
1629\end_inset
1630
1631:
1632\family default
1633 set by
1634\begin_inset Quotes eld
1635\end_inset
1636
1637status
1638\begin_inset Quotes erd
1639\end_inset
1640
1641: number of lines never been committed
1642\end_layout
1643
1644\begin_layout Standard
1645Another task is creating a unique id for the user.
1646 This id, combined with the login name of the user and the name of the pool,
1647 will be used by the server to identify the pool to be used.
1648 The id is stored in the HOME directory of the user, in the file $HOME/.stopos/rc.
1649 If this file is missing, or inappropriate, the client will create this
1650 file.
1651\begin_inset Newline newline
1652\end_inset
1653
1654
1655\begin_inset Newline newline
1656\end_inset
1657
1658All commands result in a single communication with the server, except the
1659 
1660\begin_inset Quotes eld
1661\end_inset
1662
1663add
1664\begin_inset Quotes erd
1665\end_inset
1666
1667 command: the client will send a number of
1668\begin_inset Quotes eld
1669\end_inset
1670
1671add
1672\begin_inset Quotes erd
1673\end_inset
1674
1675 commands to the server, one for each line of the file.
1676\begin_inset Newline newline
1677\end_inset
1678
1679
1680\begin_inset Newline newline
1681\end_inset
1682
1683The
1684\begin_inset Quotes eld
1685\end_inset
1686
1687dump
1688\begin_inset Quotes erd
1689\end_inset
1690
1691 command is kind of special.
1692 It is created for the case a user wants to inspect the actual contents
1693 of the pool.
1694 The
1695\begin_inset Quotes eld
1696\end_inset
1697
1698dump
1699\begin_inset Quotes erd
1700\end_inset
1701
1702 command will produce one line per call, and does not interfere with the
1703 other commands.
1704 (More specific: the
1705\begin_inset Quotes eld
1706\end_inset
1707
1708next
1709\begin_inset Quotes erd
1710\end_inset
1711
1712 command and the
1713\begin_inset Quotes eld
1714\end_inset
1715
1716dump
1717\begin_inset Quotes erd
1718\end_inset
1719
1720 command use different pointers) When the last line has been produced, the
1721 next call will result in an error code (STOPOS_RC != OK).
1722 Then the next call will start again at the first available record in the
1723 pool.
1724 
1725\end_layout
1726
1727\begin_layout Subsubsection*
1728Messages from client to server
1729\end_layout
1730
1731\begin_layout Standard
1732A message from client to server consists of the following fields:
1733\end_layout
1734
1735\begin_layout Itemize
1736
1737\family typewriter
1738stopos
1739\begin_inset space ~
1740\end_inset
1741
1742
1743\begin_inset space ~
1744\end_inset
1745
1746
1747\begin_inset space ~
1748\end_inset
1749
1750:
1751\family default
1752 the string
1753\begin_inset Quotes eld
1754\end_inset
1755
1756stopos
1757\begin_inset Quotes erd
1758\end_inset
1759
1760
1761\end_layout
1762
1763\begin_layout Itemize
1764
1765\family typewriter
1766prot
1767\begin_inset space ~
1768\end_inset
1769
1770
1771\begin_inset space ~
1772\end_inset
1773
1774
1775\begin_inset space ~
1776\end_inset
1777
1778
1779\begin_inset space ~
1780\end_inset
1781
1782
1783\begin_inset space ~
1784\end_inset
1785
1786:
1787\family default
1788 the protocol to be used (i.e.
1789 which kind of database)
1790\end_layout
1791
1792\begin_layout Itemize
1793
1794\family typewriter
1795id
1796\begin_inset space ~
1797\end_inset
1798
1799
1800\begin_inset space ~
1801\end_inset
1802
1803
1804\begin_inset space ~
1805\end_inset
1806
1807
1808\begin_inset space ~
1809\end_inset
1810
1811
1812\begin_inset space ~
1813\end_inset
1814
1815
1816\begin_inset space ~
1817\end_inset
1818
1819
1820\begin_inset space ~
1821\end_inset
1822
1823:
1824\family default
1825 the identification of the user
1826\end_layout
1827
1828\begin_layout Itemize
1829
1830\family typewriter
1831pool
1832\begin_inset space ~
1833\end_inset
1834
1835
1836\begin_inset space ~
1837\end_inset
1838
1839
1840\begin_inset space ~
1841\end_inset
1842
1843
1844\begin_inset space ~
1845\end_inset
1846
1847
1848\begin_inset space ~
1849\end_inset
1850
1851:
1852\family default
1853 the name of the pool to be used
1854\end_layout
1855
1856\begin_layout Itemize
1857
1858\family typewriter
1859command
1860\begin_inset space ~
1861\end_inset
1862
1863
1864\begin_inset space ~
1865\end_inset
1866
1867:
1868\family default
1869 the command for the server
1870\end_layout
1871
1872\begin_layout Itemize
1873
1874\family typewriter
1875multi
1876\begin_inset space ~
1877\end_inset
1878
1879
1880\begin_inset space ~
1881\end_inset
1882
1883
1884\begin_inset space ~
1885\end_inset
1886
1887
1888\begin_inset space ~
1889\end_inset
1890
1891:
1892\family default
1893 the value of
1894\begin_inset Quotes eld
1895\end_inset
1896
1897multi
1898\begin_inset Quotes erd
1899\end_inset
1900
1901: can a line be produced more than once?
1902\end_layout
1903
1904\begin_layout Itemize
1905
1906\family typewriter
1907value
1908\begin_inset space ~
1909\end_inset
1910
1911
1912\begin_inset space ~
1913\end_inset
1914
1915
1916\begin_inset space ~
1917\end_inset
1918
1919
1920\begin_inset space ~
1921\end_inset
1922
1923:
1924\family default
1925 a parameter
1926\end_layout
1927
1928\begin_layout Standard
1929All fields are coded in hexadecimal strings, embraced by a fixed header
1930 and trailer.
1931 This is to ensure that no problematic things (spaces, tabs, slashes, empty
1932 strings etc.) have to be transmitted.
1933 The fields are separated with the character
1934\begin_inset Quotes eld
1935\end_inset
1936
1937-
1938\begin_inset Quotes erd
1939\end_inset
1940
1941.
1942 Example: to send a message to the server located at
1943\begin_inset Quotes eld
1944\end_inset
1945
1946http://www.stoposserver.surfsara.nl
1947\begin_inset Quotes erd
1948\end_inset
1949
1950 with:
1951\end_layout
1952
1953\begin_layout Itemize
1954protocol =
1955\begin_inset Quotes eld
1956\end_inset
1957
1958gdbm
1959\begin_inset Quotes erd
1960\end_inset
1961
1962
1963\end_layout
1964
1965\begin_layout Itemize
1966user identification =
1967\begin_inset Quotes eld
1968\end_inset
1969
1970willem.qR7w3XQp
1971\begin_inset Quotes erd
1972\end_inset
1973
1974
1975\end_layout
1976
1977\begin_layout Itemize
1978poolname =
1979\begin_inset Quotes eld
1980\end_inset
1981
1982mypool
1983\begin_inset Quotes erd
1984\end_inset
1985
1986
1987\end_layout
1988
1989\begin_layout Itemize
1990command =
1991\begin_inset Quotes eld
1992\end_inset
1993
1994add
1995\begin_inset Quotes erd
1996\end_inset
1997
1998
1999\end_layout
2000
2001\begin_layout Itemize
2002multi =
2003\begin_inset Quotes eld
2004\end_inset
2005
2006no
2007\begin_inset Quotes erd
2008\end_inset
2009
2010
2011\end_layout
2012
2013\begin_layout Itemize
2014parameter =
2015\begin_inset Quotes eld
2016\end_inset
2017
20181 2 3
2019\begin_inset Quotes erd
2020\end_inset
2021
2022
2023\end_layout
2024
2025\begin_layout Standard
2026The client would create the following url:
2027\begin_inset Newline newline
2028\end_inset
2029
2030
2031\begin_inset Newline newline
2032\end_inset
2033
2034
2035\family typewriter
2036http://www.stoposserver.surfsara.nl?ZZZ73746f706f73YY
2037\begin_inset space ~
2038\end_inset
2039
2040
2041\begin_inset space ~
2042\end_inset
2043
2044
2045\begin_inset space ~
2046\end_inset
2047
2048
2049\begin_inset Quotes eld
2050\end_inset
2051
2052stopos
2053\begin_inset Quotes erd
2054\end_inset
2055
2056
2057\end_layout
2058
2059\begin_layout Standard
2060
2061\family typewriter
2062\begin_inset space ~
2063\end_inset
2064
2065
2066\begin_inset space ~
2067\end_inset
2068
2069
2070\begin_inset space ~
2071\end_inset
2072
2073
2074\begin_inset space ~
2075\end_inset
2076
2077
2078\begin_inset space ~
2079\end_inset
2080
2081
2082\begin_inset space ~
2083\end_inset
2084
2085
2086\begin_inset space ~
2087\end_inset
2088
2089
2090\begin_inset space ~
2091\end_inset
2092
2093
2094\begin_inset space ~
2095\end_inset
2096
2097
2098\begin_inset space ~
2099\end_inset
2100
2101
2102\begin_inset space ~
2103\end_inset
2104
2105
2106\begin_inset space ~
2107\end_inset
2108
2109
2110\begin_inset space ~
2111\end_inset
2112
2113
2114\begin_inset space ~
2115\end_inset
2116
2117
2118\begin_inset space ~
2119\end_inset
2120
2121
2122\begin_inset space ~
2123\end_inset
2124
2125
2126\begin_inset space ~
2127\end_inset
2128
2129
2130\begin_inset space ~
2131\end_inset
2132
2133
2134\begin_inset space ~
2135\end_inset
2136
2137
2138\begin_inset space ~
2139\end_inset
2140
2141
2142\begin_inset space ~
2143\end_inset
2144
2145
2146\begin_inset space ~
2147\end_inset
2148
2149
2150\begin_inset space ~
2151\end_inset
2152
2153
2154\begin_inset space ~
2155\end_inset
2156
2157
2158\begin_inset space ~
2159\end_inset
2160
2161
2162\begin_inset space ~
2163\end_inset
2164
2165
2166\begin_inset space ~
2167\end_inset
2168
2169
2170\begin_inset space ~
2171\end_inset
2172
2173
2174\begin_inset space ~
2175\end_inset
2176
2177
2178\begin_inset space ~
2179\end_inset
2180
2181
2182\begin_inset space ~
2183\end_inset
2184
2185
2186\begin_inset space ~
2187\end_inset
2188
2189
2190\begin_inset space ~
2191\end_inset
2192
2193
2194\begin_inset space ~
2195\end_inset
2196
2197
2198\begin_inset space ~
2199\end_inset
2200
2201
2202\begin_inset space ~
2203\end_inset
2204
2205-ZZZ6764626dYY
2206\begin_inset space ~
2207\end_inset
2208
2209
2210\begin_inset space ~
2211\end_inset
2212
2213
2214\begin_inset space ~
2215\end_inset
2216
2217
2218\begin_inset space ~
2219\end_inset
2220
2221
2222\begin_inset space ~
2223\end_inset
2224
2225 
2226\begin_inset Quotes eld
2227\end_inset
2228
2229gdbm
2230\begin_inset Quotes erd
2231\end_inset
2232
2233
2234\end_layout
2235
2236\begin_layout Standard
2237
2238\family typewriter
2239\begin_inset space ~
2240\end_inset
2241
2242
2243\begin_inset space ~
2244\end_inset
2245
2246
2247\begin_inset space ~
2248\end_inset
2249
2250
2251\begin_inset space ~
2252\end_inset
2253
2254
2255\begin_inset space ~
2256\end_inset
2257
2258
2259\begin_inset space ~
2260\end_inset
2261
2262
2263\begin_inset space ~
2264\end_inset
2265
2266
2267\begin_inset space ~
2268\end_inset
2269
2270
2271\begin_inset space ~
2272\end_inset
2273
2274
2275\begin_inset space ~
2276\end_inset
2277
2278
2279\begin_inset space ~
2280\end_inset
2281
2282
2283\begin_inset space ~
2284\end_inset
2285
2286
2287\begin_inset space ~
2288\end_inset
2289
2290
2291\begin_inset space ~
2292\end_inset
2293
2294-ZZZ77696c6c656d2e7152377733585170YY
2295\begin_inset space ~
2296\end_inset
2297
2298
2299\begin_inset space ~
2300\end_inset
2301
2302
2303\begin_inset space ~
2304\end_inset
2305
2306
2307\begin_inset space ~
2308\end_inset
2309
2310
2311\begin_inset space ~
2312\end_inset
2313
2314 
2315\begin_inset Quotes eld
2316\end_inset
2317
2318willem.
2319\family default
2320qR7w3XQp
2321\begin_inset Quotes erd
2322\end_inset
2323
2324
2325\end_layout
2326
2327\begin_layout Standard
2328
2329\family typewriter
2330\begin_inset space ~
2331\end_inset
2332
2333
2334\begin_inset space ~
2335\end_inset
2336
2337
2338\begin_inset space ~
2339\end_inset
2340
2341
2342\begin_inset space ~
2343\end_inset
2344
2345
2346\begin_inset space ~
2347\end_inset
2348
2349
2350\begin_inset space ~
2351\end_inset
2352
2353
2354\begin_inset space ~
2355\end_inset
2356
2357
2358\begin_inset space ~
2359\end_inset
2360
2361
2362\begin_inset space ~
2363\end_inset
2364
2365
2366\begin_inset space ~
2367\end_inset
2368
2369
2370\begin_inset space ~
2371\end_inset
2372
2373
2374\begin_inset space ~
2375\end_inset
2376
2377
2378\begin_inset space ~
2379\end_inset
2380
2381
2382\begin_inset space ~
2383\end_inset
2384
2385
2386\begin_inset space ~
2387\end_inset
2388
2389
2390\begin_inset space ~
2391\end_inset
2392
2393
2394\begin_inset space ~
2395\end_inset
2396
2397
2398\begin_inset space ~
2399\end_inset
2400
2401
2402\begin_inset space ~
2403\end_inset
2404
2405
2406\begin_inset space ~
2407\end_inset
2408
2409
2410\begin_inset space ~
2411\end_inset
2412
2413
2414\begin_inset space ~
2415\end_inset
2416
2417
2418\begin_inset space ~
2419\end_inset
2420
2421
2422\begin_inset space ~
2423\end_inset
2424
2425
2426\begin_inset space ~
2427\end_inset
2428
2429
2430\begin_inset space ~
2431\end_inset
2432
2433
2434\begin_inset space ~
2435\end_inset
2436
2437
2438\begin_inset space ~
2439\end_inset
2440
2441
2442\begin_inset space ~
2443\end_inset
2444
2445
2446\begin_inset space ~
2447\end_inset
2448
2449
2450\begin_inset space ~
2451\end_inset
2452
2453
2454\begin_inset space ~
2455\end_inset
2456
2457-ZZZ6d79706f6f6cYY
2458\begin_inset space ~
2459\end_inset
2460
2461
2462\begin_inset space ~
2463\end_inset
2464
2465
2466\begin_inset space ~
2467\end_inset
2468
2469
2470\begin_inset space ~
2471\end_inset
2472
2473
2474\begin_inset space ~
2475\end_inset
2476
2477 
2478\begin_inset Quotes eld
2479\end_inset
2480
2481mypool
2482\begin_inset Quotes erd
2483\end_inset
2484
2485
2486\end_layout
2487
2488\begin_layout Standard
2489
2490\family typewriter
2491\begin_inset space ~
2492\end_inset
2493
2494
2495\begin_inset space ~
2496\end_inset
2497
2498
2499\begin_inset space ~
2500\end_inset
2501
2502
2503\begin_inset space ~
2504\end_inset
2505
2506
2507\begin_inset space ~
2508\end_inset
2509
2510
2511\begin_inset space ~
2512\end_inset
2513
2514
2515\begin_inset space ~
2516\end_inset
2517
2518
2519\begin_inset space ~
2520\end_inset
2521
2522
2523\begin_inset space ~
2524\end_inset
2525
2526
2527\begin_inset space ~
2528\end_inset
2529
2530
2531\begin_inset space ~
2532\end_inset
2533
2534
2535\begin_inset space ~
2536\end_inset
2537
2538
2539\begin_inset space ~
2540\end_inset
2541
2542
2543\begin_inset space ~
2544\end_inset
2545
2546
2547\begin_inset space ~
2548\end_inset
2549
2550
2551\begin_inset space ~
2552\end_inset
2553
2554
2555\begin_inset space ~
2556\end_inset
2557
2558
2559\begin_inset space ~
2560\end_inset
2561
2562
2563\begin_inset space ~
2564\end_inset
2565
2566
2567\begin_inset space ~
2568\end_inset
2569
2570
2571\begin_inset space ~
2572\end_inset
2573
2574
2575\begin_inset space ~
2576\end_inset
2577
2578
2579\begin_inset space ~
2580\end_inset
2581
2582
2583\begin_inset space ~
2584\end_inset
2585
2586
2587\begin_inset space ~
2588\end_inset
2589
2590
2591\begin_inset space ~
2592\end_inset
2593
2594
2595\begin_inset space ~
2596\end_inset
2597
2598
2599\begin_inset space ~
2600\end_inset
2601
2602
2603\begin_inset space ~
2604\end_inset
2605
2606
2607\begin_inset space ~
2608\end_inset
2609
2610
2611\begin_inset space ~
2612\end_inset
2613
2614
2615\begin_inset space ~
2616\end_inset
2617
2618
2619\begin_inset space ~
2620\end_inset
2621
2622
2623\begin_inset space ~
2624\end_inset
2625
2626
2627\begin_inset space ~
2628\end_inset
2629
2630
2631\begin_inset space ~
2632\end_inset
2633
2634
2635\begin_inset space ~
2636\end_inset
2637
2638
2639\begin_inset space ~
2640\end_inset
2641
2642-ZZZ616464YY
2643\begin_inset space ~
2644\end_inset
2645
2646
2647\begin_inset space ~
2648\end_inset
2649
2650
2651\begin_inset space ~
2652\end_inset
2653
2654
2655\begin_inset space ~
2656\end_inset
2657
2658
2659\begin_inset space ~
2660\end_inset
2661
2662 
2663\begin_inset Quotes eld
2664\end_inset
2665
2666add
2667\begin_inset Quotes erd
2668\end_inset
2669
2670
2671\end_layout
2672
2673\begin_layout Standard
2674
2675\family typewriter
2676\begin_inset space ~
2677\end_inset
2678
2679
2680\begin_inset space ~
2681\end_inset
2682
2683
2684\begin_inset space ~
2685\end_inset
2686
2687
2688\begin_inset space ~
2689\end_inset
2690
2691
2692\begin_inset space ~
2693\end_inset
2694
2695
2696\begin_inset space ~
2697\end_inset
2698
2699
2700\begin_inset space ~
2701\end_inset
2702
2703
2704\begin_inset space ~
2705\end_inset
2706
2707
2708\begin_inset space ~
2709\end_inset
2710
2711
2712\begin_inset space ~
2713\end_inset
2714
2715
2716\begin_inset space ~
2717\end_inset
2718
2719
2720\begin_inset space ~
2721\end_inset
2722
2723
2724\begin_inset space ~
2725\end_inset
2726
2727
2728\begin_inset space ~
2729\end_inset
2730
2731
2732\begin_inset space ~
2733\end_inset
2734
2735
2736\begin_inset space ~
2737\end_inset
2738
2739
2740\begin_inset space ~
2741\end_inset
2742
2743
2744\begin_inset space ~
2745\end_inset
2746
2747
2748\begin_inset space ~
2749\end_inset
2750
2751
2752\begin_inset space ~
2753\end_inset
2754
2755
2756\begin_inset space ~
2757\end_inset
2758
2759
2760\begin_inset space ~
2761\end_inset
2762
2763
2764\begin_inset space ~
2765\end_inset
2766
2767
2768\begin_inset space ~
2769\end_inset
2770
2771
2772\begin_inset space ~
2773\end_inset
2774
2775
2776\begin_inset space ~
2777\end_inset
2778
2779
2780\begin_inset space ~
2781\end_inset
2782
2783
2784\begin_inset space ~
2785\end_inset
2786
2787
2788\begin_inset space ~
2789\end_inset
2790
2791
2792\begin_inset space ~
2793\end_inset
2794
2795
2796\begin_inset space ~
2797\end_inset
2798
2799
2800\begin_inset space ~
2801\end_inset
2802
2803
2804\begin_inset space ~
2805\end_inset
2806
2807
2808\begin_inset space ~
2809\end_inset
2810
2811
2812\begin_inset space ~
2813\end_inset
2814
2815
2816\begin_inset space ~
2817\end_inset
2818
2819
2820\begin_inset space ~
2821\end_inset
2822
2823
2824\begin_inset space ~
2825\end_inset
2826
2827
2828\begin_inset space ~
2829\end_inset
2830
2831
2832\begin_inset space ~
2833\end_inset
2834
2835-ZZZ6e6fYY
2836\begin_inset space ~
2837\end_inset
2838
2839
2840\begin_inset space ~
2841\end_inset
2842
2843
2844\begin_inset space ~
2845\end_inset
2846
2847
2848\begin_inset space ~
2849\end_inset
2850
2851
2852\begin_inset space ~
2853\end_inset
2854
2855 
2856\begin_inset Quotes eld
2857\end_inset
2858
2859no
2860\begin_inset Quotes erd
2861\end_inset
2862
2863
2864\end_layout
2865
2866\begin_layout Standard
2867
2868\family typewriter
2869\begin_inset space ~
2870\end_inset
2871
2872
2873\begin_inset space ~
2874\end_inset
2875
2876
2877\begin_inset space ~
2878\end_inset
2879
2880
2881\begin_inset space ~
2882\end_inset
2883
2884
2885\begin_inset space ~
2886\end_inset
2887
2888
2889\begin_inset space ~
2890\end_inset
2891
2892
2893\begin_inset space ~
2894\end_inset
2895
2896
2897\begin_inset space ~
2898\end_inset
2899
2900
2901\begin_inset space ~
2902\end_inset
2903
2904
2905\begin_inset space ~
2906\end_inset
2907
2908
2909\begin_inset space ~
2910\end_inset
2911
2912
2913\begin_inset space ~
2914\end_inset
2915
2916
2917\begin_inset space ~
2918\end_inset
2919
2920
2921\begin_inset space ~
2922\end_inset
2923
2924
2925\begin_inset space ~
2926\end_inset
2927
2928
2929\begin_inset space ~
2930\end_inset
2931
2932
2933\begin_inset space ~
2934\end_inset
2935
2936
2937\begin_inset space ~
2938\end_inset
2939
2940
2941\begin_inset space ~
2942\end_inset
2943
2944
2945\begin_inset space ~
2946\end_inset
2947
2948
2949\begin_inset space ~
2950\end_inset
2951
2952
2953\begin_inset space ~
2954\end_inset
2955
2956
2957\begin_inset space ~
2958\end_inset
2959
2960
2961\begin_inset space ~
2962\end_inset
2963
2964
2965\begin_inset space ~
2966\end_inset
2967
2968
2969\begin_inset space ~
2970\end_inset
2971
2972
2973\begin_inset space ~
2974\end_inset
2975
2976
2977\begin_inset space ~
2978\end_inset
2979
2980
2981\begin_inset space ~
2982\end_inset
2983
2984
2985\begin_inset space ~
2986\end_inset
2987
2988
2989\begin_inset space ~
2990\end_inset
2991
2992
2993\begin_inset space ~
2994\end_inset
2995
2996
2997\begin_inset space ~
2998\end_inset
2999
3000
3001\begin_inset space ~
3002\end_inset
3003
3004-ZZZ3120322033YY
3005\begin_inset space ~
3006\end_inset
3007
3008
3009\begin_inset space ~
3010\end_inset
3011
3012
3013\begin_inset space ~
3014\end_inset
3015
3016
3017\begin_inset space ~
3018\end_inset
3019
3020
3021\begin_inset space ~
3022\end_inset
3023
3024 
3025\begin_inset Quotes eld
3026\end_inset
3027
30281 2 3
3029\begin_inset Quotes erd
3030\end_inset
3031
3032
3033\begin_inset Newline newline
3034\end_inset
3035
3036
3037\end_layout
3038
3039\begin_layout Standard
3040The header is
3041\begin_inset Quotes eld
3042\end_inset
3043
3044ZZZ
3045\begin_inset Quotes erd
3046\end_inset
3047
3048, the trailer is
3049\begin_inset Quotes eld
3050\end_inset
3051
3052YY
3053\begin_inset Quotes erd
3054\end_inset
3055
3056.
3057\begin_inset Newline newline
3058\end_inset
3059
3060
3061\begin_inset Newline newline
3062\end_inset
3063
3064
3065\end_layout
3066
3067\begin_layout Subsubsection*
3068Tasks for the server
3069\end_layout
3070
3071\begin_layout Standard
3072The server parses the message from the client, executes the command and
3073 sends the results back.
3074 The commands the the server recognizes are:
3075\end_layout
3076
3077\begin_layout Itemize
3078
3079\family typewriter
3080create
3081\begin_inset space ~
3082\end_inset
3083
3084
3085\begin_inset space ~
3086\end_inset
3087
3088
3089\begin_inset space ~
3090\end_inset
3091
3092:
3093\family default
3094 create a pool
3095\end_layout
3096
3097\begin_layout Itemize
3098
3099\family typewriter
3100status
3101\begin_inset space ~
3102\end_inset
3103
3104
3105\begin_inset space ~
3106\end_inset
3107
3108
3109\begin_inset space ~
3110\end_inset
3111
3112:
3113\family default
3114 send the status of the pool
3115\end_layout
3116
3117\begin_layout Itemize
3118
3119\family typewriter
3120purge
3121\begin_inset space ~
3122\end_inset
3123
3124
3125\begin_inset space ~
3126\end_inset
3127
3128
3129\begin_inset space ~
3130\end_inset
3131
3132
3133\begin_inset space ~
3134\end_inset
3135
3136:
3137\family default
3138 remove the pool
3139\end_layout
3140
3141\begin_layout Itemize
3142
3143\family typewriter
3144add
3145\begin_inset space ~
3146\end_inset
3147
3148
3149\begin_inset space ~
3150\end_inset
3151
3152
3153\begin_inset space ~
3154\end_inset
3155
3156
3157\begin_inset space ~
3158\end_inset
3159
3160
3161\begin_inset space ~
3162\end_inset
3163
3164
3165\begin_inset space ~
3166\end_inset
3167
3168:
3169\family default
3170 add a line, taken from the
3171\begin_inset Quotes eld
3172\end_inset
3173
3174value
3175\begin_inset Quotes erd
3176\end_inset
3177
3178 field of the message
3179\end_layout
3180
3181\begin_layout Itemize
3182
3183\family typewriter
3184next
3185\begin_inset space ~
3186\end_inset
3187
3188
3189\begin_inset space ~
3190\end_inset
3191
3192
3193\begin_inset space ~
3194\end_inset
3195
3196
3197\begin_inset space ~
3198\end_inset
3199
3200
3201\begin_inset space ~
3202\end_inset
3203
3204:
3205\family default
3206 send the next line together with the
3207\begin_inset Quotes eld
3208\end_inset
3209
3210key
3211\begin_inset Quotes erd
3212\end_inset
3213
3214 and
3215\begin_inset Quotes eld
3216\end_inset
3217
3218committed
3219\begin_inset Quotes erd
3220\end_inset
3221
3222.
3223 Take care of
3224\begin_inset Quotes eld
3225\end_inset
3226
3227multi
3228\begin_inset Quotes erd
3229\end_inset
3230
3231
3232\end_layout
3233
3234\begin_layout Itemize
3235
3236\family typewriter
3237remove
3238\begin_inset space ~
3239\end_inset
3240
3241
3242\begin_inset space ~
3243\end_inset
3244
3245
3246\begin_inset space ~
3247\end_inset
3248
3249:
3250\family default
3251 remove a line with key given in the
3252\begin_inset Quotes eld
3253\end_inset
3254
3255value
3256\begin_inset Quotes erd
3257\end_inset
3258
3259 field
3260\end_layout
3261
3262\begin_layout Itemize
3263
3264\family typewriter
3265dump
3266\begin_inset space ~
3267\end_inset
3268
3269
3270\begin_inset space ~
3271\end_inset
3272
3273
3274\begin_inset space ~
3275\end_inset
3276
3277
3278\begin_inset space ~
3279\end_inset
3280
3281
3282\begin_inset space ~
3283\end_inset
3284
3285:
3286\family default
3287 return next line to be dumped, together with
3288\begin_inset Quotes eld
3289\end_inset
3290
3291key
3292\begin_inset Quotes erd
3293\end_inset
3294
3295 and
3296\begin_inset Quotes eld
3297\end_inset
3298
3299committed
3300\begin_inset Quotes erd
3301\end_inset
3302
3303
3304\end_layout
3305
3306\begin_layout Itemize
3307
3308\family typewriter
3309pools
3310\begin_inset space ~
3311\end_inset
3312
3313
3314\begin_inset space ~
3315\end_inset
3316
3317
3318\begin_inset space ~
3319\end_inset
3320
3321
3322\begin_inset space ~
3323\end_inset
3324
3325:
3326\family default
3327 return the names of the available pools for the user
3328\end_layout
3329
3330\begin_layout Standard
3331Not accidentally: these commands have the same names as the commands for
3332 the client, but the context is different.
3333\end_layout
3334
3335\begin_layout Subsubsection*
3336Communication from server to client
3337\end_layout
3338
3339\begin_layout Standard
3340The server parses the message from the client and sends the result back,
3341 using
3342\begin_inset Quotes eld
3343\end_inset
3344
3345Content-type: text/plain
3346\begin_inset Quotes erd
3347\end_inset
3348
3349.
3350 The server puts the following string in the output:
3351\begin_inset Newline newline
3352\end_inset
3353
3354
3355\begin_inset Newline newline
3356\end_inset
3357
3358
3359\family typewriter
3360STOPOS:
3361\family default
3362
3363\begin_inset Newline newline
3364\end_inset
3365
3366
3367\begin_inset Newline newline
3368\end_inset
3369
3370This string is immediately followed by the desired output, which consists
3371 of the following fields:
3372\end_layout
3373
3374\begin_layout Itemize
3375
3376\family typewriter
3377return message
3378\begin_inset space ~
3379\end_inset
3380
3381:
3382\family default
3383 
3384\begin_inset Quotes eld
3385\end_inset
3386
3387OK
3388\begin_inset Quotes erd
3389\end_inset
3390
3391 or some error message
3392\end_layout
3393
3394\begin_layout Itemize
3395
3396\family typewriter
3397key
3398\begin_inset space ~
3399\end_inset
3400
3401
3402\begin_inset space ~
3403\end_inset
3404
3405
3406\begin_inset space ~
3407\end_inset
3408
3409
3410\begin_inset space ~
3411\end_inset
3412
3413
3414\begin_inset space ~
3415\end_inset
3416
3417
3418\begin_inset space ~
3419\end_inset
3420
3421
3422\begin_inset space ~
3423\end_inset
3424
3425
3426\begin_inset space ~
3427\end_inset
3428
3429
3430\begin_inset space ~
3431\end_inset
3432
3433
3434\begin_inset space ~
3435\end_inset
3436
3437
3438\begin_inset space ~
3439\end_inset
3440
3441
3442\begin_inset space ~
3443\end_inset
3444
3445:
3446\family default
3447 key of the record just retrieved or empty
3448\end_layout
3449
3450\begin_layout Itemize
3451
3452\family typewriter
3453committed
3454\begin_inset space ~
3455\end_inset
3456
3457
3458\begin_inset space ~
3459\end_inset
3460
3461
3462\begin_inset space ~
3463\end_inset
3464
3465
3466\begin_inset space ~
3467\end_inset
3468
3469
3470\begin_inset space ~
3471\end_inset
3472
3473
3474\begin_inset space ~
3475\end_inset
3476
3477:
3478\family default
3479 number of times the record has been committed or empty
3480\end_layout
3481
3482\begin_layout Itemize
3483
3484\family typewriter
3485count
3486\begin_inset space ~
3487\end_inset
3488
3489
3490\begin_inset space ~
3491\end_inset
3492
3493
3494\begin_inset space ~
3495\end_inset
3496
3497
3498\begin_inset space ~
3499\end_inset
3500
3501
3502\begin_inset space ~
3503\end_inset
3504
3505
3506\begin_inset space ~
3507\end_inset
3508
3509
3510\begin_inset space ~
3511\end_inset
3512
3513
3514\begin_inset space ~
3515\end_inset
3516
3517
3518\begin_inset space ~
3519\end_inset
3520
3521
3522\begin_inset space ~
3523\end_inset
3524
3525:
3526\family default
3527 number of records added so far or empty
3528\end_layout
3529
3530\begin_layout Itemize
3531
3532\family typewriter
3533present
3534\begin_inset space ~
3535\end_inset
3536
3537
3538\begin_inset space ~
3539\end_inset
3540
3541
3542\begin_inset space ~
3543\end_inset
3544
3545
3546\begin_inset space ~
3547\end_inset
3548
3549
3550\begin_inset space ~
3551\end_inset
3552
3553
3554\begin_inset space ~
3555\end_inset
3556
3557
3558\begin_inset space ~
3559\end_inset
3560
3561
3562\begin_inset space ~
3563\end_inset
3564
3565:
3566\family default
3567 number of records present or empty
3568\end_layout
3569
3570\begin_layout Itemize
3571
3572\family typewriter
3573present0
3574\begin_inset space ~
3575\end_inset
3576
3577
3578\begin_inset space ~
3579\end_inset
3580
3581
3582\begin_inset space ~
3583\end_inset
3584
3585
3586\begin_inset space ~
3587\end_inset
3588
3589
3590\begin_inset space ~
3591\end_inset
3592
3593
3594\begin_inset space ~
3595\end_inset
3596
3597
3598\begin_inset space ~
3599\end_inset
3600
3601:
3602\family default
3603 number of records never been committed or empty
3604\end_layout
3605
3606\begin_layout Itemize
3607
3608\family typewriter
3609value
3610\begin_inset space ~
3611\end_inset
3612
3613
3614\begin_inset space ~
3615\end_inset
3616
3617
3618\begin_inset space ~
3619\end_inset
3620
3621
3622\begin_inset space ~
3623\end_inset
3624
3625
3626\begin_inset space ~
3627\end_inset
3628
3629
3630\begin_inset space ~
3631\end_inset
3632
3633
3634\begin_inset space ~
3635\end_inset
3636
3637
3638\begin_inset space ~
3639\end_inset
3640
3641
3642\begin_inset space ~
3643\end_inset
3644
3645
3646\begin_inset space ~
3647\end_inset
3648
3649:
3650\family default
3651 return value or empty
3652\end_layout
3653
3654\begin_layout Itemize
3655
3656\family typewriter
3657new line character
3658\end_layout
3659
3660\begin_layout Standard
3661The client will search for the string
3662\begin_inset Quotes eld
3663\end_inset
3664
3665STOPOS:
3666\begin_inset Quotes erd
3667\end_inset
3668
3669 and use the string immediately following as the result.
3670 The developer can, if she wishes, print extra information and have a look
3671 at the total output of the server, as long as she does not use the string
3672 
3673\begin_inset Quotes eld
3674\end_inset
3675
3676STOPOS:
3677\begin_inset Quotes erd
3678\end_inset
3679
3680.
3681 The fields are encoded, just like is done with the message from the client
3682 to the server, only the separator here is
3683\begin_inset Quotes eld
3684\end_inset
3685
3686+
3687\begin_inset Quotes erd
3688\end_inset
3689
3690 for no special reason.
3691 
3692\end_layout
3693
3694\begin_layout Subsection*
3695Internals of the client
3696\end_layout
3697
3698\begin_layout Standard
3699The client parses the command line, using getopt(3).
3700 It performs some basic checks on the parameters given, and sends an appropriate
3701 command to the server, using libcurl(3).
3702 The output from the server is parsed and transformed into statements that
3703 can be executed in the shell.
3704 These commands set environment variables, with names starting with
3705\begin_inset Quotes eld
3706\end_inset
3707
3708STOPOS_
3709\begin_inset Quotes erd
3710\end_inset
3711
3712.
3713\end_layout
3714
3715\begin_layout Subsection*
3716Internals of the server
3717\end_layout
3718
3719\begin_layout Standard
3720The server parses the command sent from the client and an http-server (apache,
3721 thttpd), executes it and sends the results back to the client.
3722 Most of the interesting work is done in the class
3723\begin_inset Quotes eld
3724\end_inset
3725
3726stopos_pool
3727\begin_inset Quotes erd
3728\end_inset
3729
3730.
3731 This class, from which a database-specific class has to be derived, maintains
3732 a double linked list of lines.
3733 The addressing of the lines is based on keys that are computed from the
3734 counter that is incremented each time a line is added.
3735 The derived class has to deal with some basic I/O operations: creating,
3736 opening, closing and removing of the database; reading, writing and removing
3737 records.
3738 In this code, four database implementations are provided:
3739\end_layout
3740
3741\begin_layout Itemize
3742based on gdbm
3743\begin_inset Foot
3744status open
3745
3746\begin_layout Plain Layout
3747http://www.gnu.org.ua/software/gdbm/
3748\end_layout
3749
3750\end_inset
3751
3752
3753\end_layout
3754
3755\begin_layout Itemize
3756based om mysql
3757\begin_inset Foot
3758status open
3759
3760\begin_layout Plain Layout
3761http://www.mysql.com/
3762\end_layout
3763
3764\end_inset
3765
3766
3767\end_layout
3768
3769\begin_layout Itemize
3770based on a flat ascii file
3771\end_layout
3772
3773\begin_layout Itemize
3774based on files in a folder, each file containing one line
3775\end_layout
3776
3777\begin_layout Standard
3778The client determines which implementation the server has to use.
3779 Storage of a record is based on the key, but, if desirable, the derived
3780 class can provide a suitable slot for storing the record.
3781 This feature is used in the
3782\begin_inset Quotes eld
3783\end_inset
3784
3785flat file
3786\begin_inset Quotes erd
3787\end_inset
3788
3789 solution, in order to be able to re-use space occupied by removed records.
3790 
3791\end_layout
3792
3793\begin_layout Subsubsection*
3794Storage of lines
3795\end_layout
3796
3797\begin_layout Standard
3798Lines are stored in records, which also contain extra fields.
3799 The records are hexadecimal coded, just like the communication from client
3800 to server.
3801 The separation character is here '/'.
3802 Records are stored using unique keys, generated by the class
3803\begin_inset Quotes eld
3804\end_inset
3805
3806stopos_pool
3807\begin_inset Quotes erd
3808\end_inset
3809
3810.
3811 The derived class has no knowledge about the meaning of the records: it's
3812 only task is to store, retrieve and delete them.
3813\end_layout
3814
3815\begin_layout Subsection*
3816Performance
3817\end_layout
3818
3819\begin_layout Standard
3820A program
3821\begin_inset Quotes eld
3822\end_inset
3823
3824test_pool.cpp
3825\begin_inset Quotes erd
3826\end_inset
3827
3828 has been provided which runs all four implementations, without an http
3829 server, but directly calling the functions from the class
3830\begin_inset Quotes eld
3831\end_inset
3832
3833stopos_pool
3834\begin_inset Quotes erd
3835\end_inset
3836
3837 and reports how much time a implementation takes.
3838 Furthermore, it does some consistency checks.
3839 The pool consists of a few hundreds of lines.
3840 The results are
3841\begin_inset Foot
3842status open
3843
3844\begin_layout Plain Layout
3845The program was run on a Linux workstation, equipped with a
3846\begin_inset Quotes eld
3847\end_inset
3848
3849normal
3850\begin_inset Quotes erd
3851\end_inset
3852
3853 (no SSD) disk
3854\end_layout
3855
3856\end_inset
3857
3858:
3859\begin_inset Newline newline
3860\end_inset
3861
3862
3863\begin_inset Newline newline
3864\end_inset
3865
3866
3867\family typewriter
3868database
3869\begin_inset space ~
3870\end_inset
3871
3872
3873\begin_inset space ~
3874\end_inset
3875
3876
3877\begin_inset space ~
3878\end_inset
3879
3880time (sec)
3881\begin_inset Newline newline
3882\end_inset
3883
3884gdbm
3885\begin_inset space ~
3886\end_inset
3887
3888
3889\begin_inset space ~
3890\end_inset
3891
3892
3893\begin_inset space ~
3894\end_inset
3895
3896
3897\begin_inset space ~
3898\end_inset
3899
3900
3901\begin_inset space ~
3902\end_inset
3903
3904
3905\begin_inset space ~
3906\end_inset
3907
3908
3909\begin_inset space ~
3910\end_inset
3911
3912
3913\begin_inset space ~
3914\end_inset
3915
39163.31
3917\end_layout
3918
3919\begin_layout Standard
3920
3921\family typewriter
3922flatfile
3923\begin_inset space ~
3924\end_inset
3925
3926
3927\begin_inset space ~
3928\end_inset
3929
3930
3931\begin_inset space ~
3932\end_inset
3933
39340.19
3935\end_layout
3936
3937\begin_layout Standard
3938
3939\family typewriter
3940files
3941\begin_inset space ~
3942\end_inset
3943
3944
3945\begin_inset space ~
3946\end_inset
3947
3948
3949\begin_inset space ~
3950\end_inset
3951
3952
3953\begin_inset space ~
3954\end_inset
3955
3956
3957\begin_inset space ~
3958\end_inset
3959
3960
3961\begin_inset space ~
3962\end_inset
3963
39640.73
3965\end_layout
3966
3967\begin_layout Standard
3968
3969\family typewriter
3970mysql
3971\begin_inset space ~
3972\end_inset
3973
3974
3975\begin_inset space ~
3976\end_inset
3977
3978
3979\begin_inset space ~
3980\end_inset
3981
3982
3983\begin_inset space ~
3984\end_inset
3985
3986
3987\begin_inset space ~
3988\end_inset
3989
3990
3991\begin_inset space ~
3992\end_inset
3993
39944.7
3995\family default
39961
3997\begin_inset Newline newline
3998\end_inset
3999
4000 
4001\begin_inset Newline newline
4002\end_inset
4003
4004The winner is clearly the
4005\begin_inset Quotes eld
4006\end_inset
4007
4008flat file
4009\begin_inset Quotes erd
4010\end_inset
4011
4012 implementation.
4013 Disadvantage of this solution (and also of the
4014\begin_inset Quotes eld
4015\end_inset
4016
4017files
4018\begin_inset Quotes erd
4019\end_inset
4020
4021 and
4022\begin_inset Quotes eld
4023\end_inset
4024
4025mysql
4026\begin_inset Quotes erd
4027\end_inset
4028
4029 solution) is the amount of space that is used for the database: each line
4030 takes 4 Kbyte.
4031 The
4032\begin_inset Quotes eld
4033\end_inset
4034
4035gdbm
4036\begin_inset Quotes erd
4037\end_inset
4038
4039 solution does not have this problem.
4040 
4041\begin_inset Newline newline
4042\end_inset
4043
4044Normally, the stopos software will be used using an http server, so it is
4045 more relevant to have look at the timings in this case.
4046 As an example, that man page of bash (5459 lines) was put in the pool,
4047 and all lines were retrieved and removed:
4048\begin_inset Newline newline
4049\end_inset
4050
4051
4052\begin_inset Newline newline
4053\end_inset
4054
4055
4056\family typewriter
4057database
4058\begin_inset space ~
4059\end_inset
4060
4061
4062\begin_inset space ~
4063\end_inset
4064
4065time(sec)
4066\end_layout
4067
4068\begin_layout Standard
4069
4070\family typewriter
4071gdbm
4072\begin_inset space ~
4073\end_inset
4074
4075
4076\begin_inset space ~
4077\end_inset
4078
4079
4080\begin_inset space ~
4081\end_inset
4082
4083
4084\begin_inset space ~
4085\end_inset
4086
4087
4088\begin_inset space ~
4089\end_inset
4090
4091
4092\begin_inset space ~
4093\end_inset
4094
4095
4096\begin_inset space ~
4097\end_inset
4098
4099187
4100\end_layout
4101
4102\begin_layout Standard
4103
4104\family typewriter
4105flatfile
4106\begin_inset space ~
4107\end_inset
4108
4109
4110\begin_inset space ~
4111\end_inset
4112
4113
4114\begin_inset space ~
4115\end_inset
4116
4117182
4118\end_layout
4119
4120\begin_layout Standard
4121
4122\family typewriter
4123files
4124\begin_inset space ~
4125\end_inset
4126
4127
4128\begin_inset space ~
4129\end_inset
4130
4131
4132\begin_inset space ~
4133\end_inset
4134
4135
4136\begin_inset space ~
4137\end_inset
4138
4139
4140\begin_inset space ~
4141\end_inset
4142
4143
4144\begin_inset space ~
4145\end_inset
4146
4147190
4148\end_layout
4149
4150\begin_layout Standard
4151
4152\family typewriter
4153mysql
4154\begin_inset space ~
4155\end_inset
4156
4157
4158\begin_inset space ~
4159\end_inset
4160
4161
4162\begin_inset space ~
4163\end_inset
4164
4165
4166\begin_inset space ~
4167\end_inset
4168
4169
4170\begin_inset space ~
4171\end_inset
4172
4173
4174\begin_inset space ~
4175\end_inset
4176
4177
4178\family default
4179309
4180\begin_inset Newline newline
4181\end_inset
4182
4183
4184\begin_inset Newline newline
4185\end_inset
4186
4187These timings show, that for performance reasons, there is not much difference
4188 between
4189\begin_inset Quotes eld
4190\end_inset
4191
4192gdbm
4193\begin_inset Quotes erd
4194\end_inset
4195
4196,
4197\begin_inset Quotes eld
4198\end_inset
4199
4200flatfile
4201\begin_inset Quotes erd
4202\end_inset
4203
4204 and
4205\begin_inset Quotes eld
4206\end_inset
4207
4208files
4209\begin_inset Quotes erd
4210\end_inset
4211
4212.
4213 We choose the
4214\begin_inset Quotes eld
4215\end_inset
4216
4217gdbm
4218\begin_inset Quotes erd
4219\end_inset
4220
4221 implementation, because of it's economy with disk space used.
4222\end_layout
4223
4224\begin_layout Subsection*
4225Installation
4226\end_layout
4227
4228\begin_layout Standard
4229The source tree contains a file
4230\begin_inset Quotes eld
4231\end_inset
4232
4233Make.inc
4234\begin_inset Quotes erd
4235\end_inset
4236
4237, defining variables that determine the version of the program, the installation
4238 directories and which database versions should be produced.
4239 This file will be included in the Makefile.
4240 A trivial script
4241\begin_inset Quotes eld
4242\end_inset
4243
4244makeit
4245\begin_inset Quotes erd
4246\end_inset
4247
4248 sets the umask and calls make(1) to create and install the executables.
4249 The script
4250\begin_inset Quotes eld
4251\end_inset
4252
4253clean
4254\begin_inset Quotes erd
4255\end_inset
4256
4257 executes a
4258\begin_inset Quotes eld
4259\end_inset
4260
4261make clean
4262\begin_inset Quotes erd
4263\end_inset
4264
4265 to get rid of compilation products.
4266\end_layout
4267
4268\begin_layout Subsubsection*
4269Extra tools
4270\end_layout
4271
4272\begin_layout Standard
4273The source tree also contains the scripts
4274\begin_inset Quotes eld
4275\end_inset
4276
4277sara-get-num-cores
4278\begin_inset Quotes erd
4279\end_inset
4280
4281 and
4282\begin_inset Quotes eld
4283\end_inset
4284
4285sara-get-mem-size
4286\begin_inset Quotes erd
4287\end_inset
4288
4289, along with their man pages.
4290 Sara-get-num-cores prints the number of available cores, while sara-get-mem-siz
4291e prints the amount of memory.
4292 Both numbers can be used to determine how many processes should run in
4293 parallel on a given node.
4294 These scripts and man pages will be installed also by calling
4295\begin_inset Quotes eld
4296\end_inset
4297
4298./makeit
4299\begin_inset Quotes erd
4300\end_inset
4301
4302.
4303\end_layout
4304
4305\begin_layout Subsection*
4306Man page of stopos
4307\end_layout
4308
4309\begin_layout Standard
4310
4311\family typewriter
4312\begin_inset listings
4313inline false
4314status open
4315
4316\begin_layout Plain Layout
4317
4318\end_layout
4319
4320\begin_layout Plain Layout
4321
4322\end_layout
4323
4324\begin_layout Plain Layout
4325STOPOS(1)                                                            STOPOS(1)
4326\end_layout
4327
4328\begin_layout Plain Layout
4329
4330\end_layout
4331
4332\begin_layout Plain Layout
4333
4334\end_layout
4335
4336\begin_layout Plain Layout
4337
4338\end_layout
4339
4340\begin_layout Plain Layout
4341NAME
4342\end_layout
4343
4344\begin_layout Plain Layout
4345       stopos - alias to call the program stoposclient and eval it's output
4346\end_layout
4347
4348\begin_layout Plain Layout
4349
4350\end_layout
4351
4352\begin_layout Plain Layout
4353SYNOPSIS
4354\end_layout
4355
4356\begin_layout Plain Layout
4357       stopos  -h,--help
4358\end_layout
4359
4360\begin_layout Plain Layout
4361
4362\end_layout
4363
4364\begin_layout Plain Layout
4365       stopos  -v,--version
4366\end_layout
4367
4368\begin_layout Plain Layout
4369
4370\end_layout
4371
4372\begin_layout Plain Layout
4373       stopos  create    [ -p,--pool POOL ]
4374\end_layout
4375
4376\begin_layout Plain Layout
4377
4378\end_layout
4379
4380\begin_layout Plain Layout
4381       stopos  status    [ -p,--pool POOL]
4382\end_layout
4383
4384\begin_layout Plain Layout
4385
4386\end_layout
4387
4388\begin_layout Plain Layout
4389       stopos  purge     [ -p,--pool POOL ]
4390\end_layout
4391
4392\begin_layout Plain Layout
4393
4394\end_layout
4395
4396\begin_layout Plain Layout
4397       stopos  pools
4398\end_layout
4399
4400\begin_layout Plain Layout
4401
4402\end_layout
4403
4404\begin_layout Plain Layout
4405       stopos  add       [ -p,--pool POOL ] [ FILENAME ]
4406\end_layout
4407
4408\begin_layout Plain Layout
4409
4410\end_layout
4411
4412\begin_layout Plain Layout
4413       stopos  next      [ -p,--pool POOL ] [ -m,--multi ]
4414\end_layout
4415
4416\begin_layout Plain Layout
4417
4418\end_layout
4419
4420\begin_layout Plain Layout
4421       stopos  remove    [ -p,--pool POOL] [ KEY  ]
4422\end_layout
4423
4424\begin_layout Plain Layout
4425
4426\end_layout
4427
4428\begin_layout Plain Layout
4429       stopos  dump      [ -p,--pool POOL]
4430\end_layout
4431
4432\begin_layout Plain Layout
4433
4434\end_layout
4435
4436\begin_layout Plain Layout
4437       The -q,--quiet flag supresses most output.
4438\end_layout
4439
4440\begin_layout Plain Layout
4441
4442\end_layout
4443
4444\begin_layout Plain Layout
4445DESCRIPTION
4446\end_layout
4447
4448\begin_layout Plain Layout
4449       Stopos  is an alias using the program stoposclient, an utility to
4450 store
4451\end_layout
4452
4453\begin_layout Plain Layout
4454       and retrieve text lines in a pool.
4455  In general, the text lines are used
4456\end_layout
4457
4458\begin_layout Plain Layout
4459       as command parameters, see Examples.
4460\end_layout
4461
4462\begin_layout Plain Layout
4463
4464\end_layout
4465
4466\begin_layout Plain Layout
4467COMMANDS
4468\end_layout
4469
4470\begin_layout Plain Layout
4471       -h,--help
4472\end_layout
4473
4474\begin_layout Plain Layout
4475           Prints usage information.
4476\end_layout
4477
4478\begin_layout Plain Layout
4479
4480\end_layout
4481
4482\begin_layout Plain Layout
4483       -v,--version
4484\end_layout
4485
4486\begin_layout Plain Layout
4487           Prints version.
4488\end_layout
4489
4490\begin_layout Plain Layout
4491
4492\end_layout
4493
4494\begin_layout Plain Layout
4495       create [ -p,--pool POOL ] [ FILENAME ]
4496\end_layout
4497
4498\begin_layout Plain Layout
4499           Creates new pool.
4500  A pool with the same name will be removed first.
4501\end_layout
4502
4503\begin_layout Plain Layout
4504
4505\end_layout
4506
4507\begin_layout Plain Layout
4508       status
4509\end_layout
4510
4511\begin_layout Plain Layout
4512           Prints to standard error       environment variable
4513\end_layout
4514
4515\begin_layout Plain Layout
4516           ---------------------------------------------------
4517\end_layout
4518
4519\begin_layout Plain Layout
4520           total number of lines added      STOPOS_COUNT
4521\end_layout
4522
4523\begin_layout Plain Layout
4524           number of lines present          STOPOS_PRESENT
4525\end_layout
4526
4527\begin_layout Plain Layout
4528           number of lines never committed  STOPOS_PRESENT0
4529\end_layout
4530
4531\begin_layout Plain Layout
4532
4533\end_layout
4534
4535\begin_layout Plain Layout
4536
4537\end_layout
4538
4539\begin_layout Plain Layout
4540       purge [-p,--pool POOL ]
4541\end_layout
4542
4543\begin_layout Plain Layout
4544           Removes the pool.
4545\end_layout
4546
4547\begin_layout Plain Layout
4548
4549\end_layout
4550
4551\begin_layout Plain Layout
4552       pools [-p,--pool POOL ]
4553\end_layout
4554
4555\begin_layout Plain Layout
4556           Lists on standard error the pools available.
4557 The environment
4558\end_layout
4559
4560\begin_layout Plain Layout
4561           variable STOPOS_VALUE is set accordingly.
4562\end_layout
4563
4564\begin_layout Plain Layout
4565
4566\end_layout
4567
4568\begin_layout Plain Layout
4569       add [ -p,--pool POOL ] [ FILENAME ]
4570\end_layout
4571
4572\begin_layout Plain Layout
4573           Adds lines from FILENAME, default from stdin.
4574  The  environ‐
4575\end_layout
4576
4577\begin_layout Plain Layout
4578           ment variables STOPOS_RC and STOPS_KEY are set.
4579\end_layout
4580
4581\begin_layout Plain Layout
4582           NOTE: when stopos is reading from a pipe as in:
4583\end_layout
4584
4585\begin_layout Plain Layout
4586              cat parmfile | stopos add
4587\end_layout
4588
4589\begin_layout Plain Layout
4590           no environment variables are set.
4591\end_layout
4592
4593\begin_layout Plain Layout
4594
4595\end_layout
4596
4597\begin_layout Plain Layout
4598       next [ -p,--pool POOL ] [ -m,--multi ]
4599\end_layout
4600
4601\begin_layout Plain Layout
4602           Gets the next line from the pool.
4603  The environment variables
4604\end_layout
4605
4606\begin_layout Plain Layout
4607           STOPOS_VALUE, STOPOS_COMMITTED and STOPOS_KEY are  set,  see
4608\end_layout
4609
4610\begin_layout Plain Layout
4611           ENVIRONMENT.
4612   By default, the same line in the pool will be
4613\end_layout
4614
4615\begin_layout Plain Layout
4616           produced only once.
4617 When all lines  are  commited,  STOPS_RC
4618\end_layout
4619
4620\begin_layout Plain Layout
4621           will  not  be  equal to OK.
4622 Using the --multi flag, the same
4623\end_layout
4624
4625\begin_layout Plain Layout
4626           line can be produced more than  once,  if  necessary  stopos
4627\end_layout
4628
4629\begin_layout Plain Layout
4630           will  wrap  around.
4631   This  can  be  useful for dealing with
4632\end_layout
4633
4634\begin_layout Plain Layout
4635           crashed jobs.
4636\end_layout
4637
4638\begin_layout Plain Layout
4639
4640\end_layout
4641
4642\begin_layout Plain Layout
4643       remove [-p,--pool POOL ] [ KEY ]
4644\end_layout
4645
4646\begin_layout Plain Layout
4647           Removes the line with key KEY as ready.
4648  If not specified on
4649\end_layout
4650
4651\begin_layout Plain Layout
4652           the  commandline,  the  value  of  environment variable STO‐
4653\end_layout
4654
4655\begin_layout Plain Layout
4656           POS_KEY is used.
4657\end_layout
4658
4659\begin_layout Plain Layout
4660
4661\end_layout
4662
4663\begin_layout Plain Layout
4664       dump [-p,--pool POOL ]
4665\end_layout
4666
4667\begin_layout Plain Layout
4668           Reads the next available line, and puts it, preceded by it's
4669\end_layout
4670
4671\begin_layout Plain Layout
4672           key  and  number of commitments in environment variable STO‐
4673\end_layout
4674
4675\begin_layout Plain Layout
4676           POS_VALUE.
4677 The first call will produce the first line.
4678  When
4679\end_layout
4680
4681\begin_layout Plain Layout
4682           all  lines have been delivered, STOPOS_RC gets a value other
4683\end_layout
4684
4685\begin_layout Plain Layout
4686           than OK.
4687 A subsequent call will  start  the  dump  with  the
4688\end_layout
4689
4690\begin_layout Plain Layout
4691           first line again.
4692\end_layout
4693
4694\begin_layout Plain Layout
4695
4696\end_layout
4697
4698\begin_layout Plain Layout
4699OPTIONS
4700\end_layout
4701
4702\begin_layout Plain Layout
4703       -p,--pool POOL
4704\end_layout
4705
4706\begin_layout Plain Layout
4707           POOL is a unique name of the pool.
4708  Default: pool.
4709  The name
4710\end_layout
4711
4712\begin_layout Plain Layout
4713           of the pool can also be set using the  environment  variable
4714\end_layout
4715
4716\begin_layout Plain Layout
4717           STOPOS_POOL.
4718 The command line flag has precedence.
4719\end_layout
4720
4721\begin_layout Plain Layout
4722
4723\end_layout
4724
4725\begin_layout Plain Layout
4726
4727\end_layout
4728
4729\begin_layout Plain Layout
4730ENVIRONMENT
4731\end_layout
4732
4733\begin_layout Plain Layout
4734       Stopos sets the following environment variables:
4735\end_layout
4736
4737\begin_layout Plain Layout
4738
4739\end_layout
4740
4741\begin_layout Plain Layout
4742       STOPOS_RC if the value is OK, than no errors were found
4743\end_layout
4744
4745\begin_layout Plain Layout
4746
4747\end_layout
4748
4749\begin_layout Plain Layout
4750       STOPOS_KEY  contains  the keyvalue of the line produced with the
4751\end_layout
4752
4753\begin_layout Plain Layout
4754       'next' command
4755\end_layout
4756
4757\begin_layout Plain Layout
4758
4759\end_layout
4760
4761\begin_layout Plain Layout
4762       STOPOS_COMMITTED contains the number of times the line has  been
4763\end_layout
4764
4765\begin_layout Plain Layout
4766       committed
4767\end_layout
4768
4769\begin_layout Plain Layout
4770
4771\end_layout
4772
4773\begin_layout Plain Layout
4774       STOPOS_VALUE contains the line produced by the 'next' command or
4775\end_layout
4776
4777\begin_layout Plain Layout
4778       the result of the 'pools' command
4779\end_layout
4780
4781\begin_layout Plain Layout
4782
4783\end_layout
4784
4785\begin_layout Plain Layout
4786       STOPOS_COUNT STOPOS_PRESENT  STOPOS_PRESENT0  see  the  'status'
4787\end_layout
4788
4789\begin_layout Plain Layout
4790       command above
4791\end_layout
4792
4793\begin_layout Plain Layout
4794
4795\end_layout
4796
4797\begin_layout Plain Layout
4798       Stopos uses the following environment variables:
4799\end_layout
4800
4801\begin_layout Plain Layout
4802
4803\end_layout
4804
4805\begin_layout Plain Layout
4806       STOPOS_POOL see the description of the --pool flag under OPTIONS
4807\end_layout
4808
4809\begin_layout Plain Layout
4810
4811\end_layout
4812
4813\begin_layout Plain Layout
4814       STOPOS_KEY see the 'remove' flag above
4815\end_layout
4816
4817\begin_layout Plain Layout
4818
4819\end_layout
4820
4821\begin_layout Plain Layout
4822       STOPOS_SERVER_URL  the  url  stopos  uses  to access the server,
4823\end_layout
4824
4825\begin_layout Plain Layout
4826       default http://stopos.osd.surfsara.nl/cgi-bin/stoposserver
4827\end_layout
4828
4829\begin_layout Plain Layout
4830
4831\end_layout
4832
4833\begin_layout Plain Layout
4834
4835\end_layout
4836
4837\begin_layout Plain Layout
4838EXAMPLES
4839\end_layout
4840
4841\begin_layout Plain Layout
4842       Create a pool with the first 10 lines from the man page of sed:
4843\end_layout
4844
4845\begin_layout Plain Layout
4846
4847\end_layout
4848
4849\begin_layout Plain Layout
4850            man sed | head > parmfile
4851\end_layout
4852
4853\begin_layout Plain Layout
4854            stopos create
4855\end_layout
4856
4857\begin_layout Plain Layout
4858            stopos add parmfile
4859\end_layout
4860
4861\begin_layout Plain Layout
4862
4863\end_layout
4864
4865\begin_layout Plain Layout
4866           Get a line:
4867\end_layout
4868
4869\begin_layout Plain Layout
4870
4871\end_layout
4872
4873\begin_layout Plain Layout
4874            stopos next
4875\end_layout
4876
4877\begin_layout Plain Layout
4878
4879\end_layout
4880
4881\begin_layout Plain Layout
4882           The environment variable STOPOS_VALUE contains  now  one  of
4883\end_layout
4884
4885\begin_layout Plain Layout
4886           the first ten lines of the man page of sed.
4887\end_layout
4888
4889\begin_layout Plain Layout
4890
4891\end_layout
4892
4893\begin_layout Plain Layout
4894           You can use this in a command like this:
4895\end_layout
4896
4897\begin_layout Plain Layout
4898
4899\end_layout
4900
4901\begin_layout Plain Layout
4902            eval "myparser $STOPOS_VALUE"
4903\end_layout
4904
4905\begin_layout Plain Layout
4906
4907\end_layout
4908
4909\begin_layout Plain Layout
4910           The line can be removed by:
4911\end_layout
4912
4913\begin_layout Plain Layout
4914
4915\end_layout
4916
4917\begin_layout Plain Layout
4918            stopos remove
4919\end_layout
4920
4921\begin_layout Plain Layout
4922
4923\end_layout
4924
4925\begin_layout Plain Layout
4926           Finally, the pool can be completely removed by:
4927\end_layout
4928
4929\begin_layout Plain Layout
4930
4931\end_layout
4932
4933\begin_layout Plain Layout
4934            stopos purge
4935\end_layout
4936
4937\begin_layout Plain Layout
4938
4939\end_layout
4940
4941\begin_layout Plain Layout
4942
4943\end_layout
4944
4945\begin_layout Plain Layout
4946FILES
4947\end_layout
4948
4949\begin_layout Plain Layout
4950       $HOME/.stopos/id
4951\end_layout
4952
4953\begin_layout Plain Layout
4954       This  file  is  set  by  stopos  to  store  an unique id, which,
4955\end_layout
4956
4957\begin_layout Plain Layout
4958       together with the login name, will be  used  to  identify  which
4959\end_layout
4960
4961\begin_layout Plain Layout
4962       pools are yours.
4963\end_layout
4964
4965\begin_layout Plain Layout
4966
4967\end_layout
4968
4969\begin_layout Plain Layout
4970SEE ALSO
4971\end_layout
4972
4973\begin_layout Plain Layout
4974       sara-get-mem-size(1),   sara-get-num-cores(1),  stoposclient(1),
4975\end_layout
4976
4977\begin_layout Plain Layout
4978       stoposdump(1)
4979\end_layout
4980
4981\begin_layout Plain Layout
4982
4983\end_layout
4984
4985\begin_layout Plain Layout
4986AUTHORS
4987\end_layout
4988
4989\begin_layout Plain Layout
4990       Willem Vermin
4991\end_layout
4992
4993\begin_layout Plain Layout
4994
4995\end_layout
4996
4997\begin_layout Plain Layout
4998BUGS
4999\end_layout
5000
5001\begin_layout Plain Layout
5002       No bugs known yet.
5003\end_layout
5004
5005\begin_layout Plain Layout
5006
5007\end_layout
5008
5009\begin_layout Plain Layout
5010
5011\end_layout
5012
5013\begin_layout Plain Layout
5014
5015\end_layout
5016
5017\begin_layout Plain Layout
5018                                                                     STOPOS(1)
5019\end_layout
5020
5021\begin_layout Plain Layout
5022
5023\end_layout
5024
5025\end_inset
5026
5027
5028\end_layout
5029
5030\end_body
5031\end_document
Note: See TracBrowser for help on using the repository browser.