File: CBFlib.txt

package info (click to toggle)
cbflib 0.9.6%2Bdfsg1-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 56,196 kB
  • sloc: ansic: 103,920; python: 4,552; sh: 3,032; makefile: 1,822; yacc: 659; f90: 210; xml: 210; cpp: 58; java: 16
file content (12150 lines) | stat: -rw-r--r-- 473,416 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
7440
7441
7442
7443
7444
7445
7446
7447
7448
7449
7450
7451
7452
7453
7454
7455
7456
7457
7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
7474
7475
7476
7477
7478
7479
7480
7481
7482
7483
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569
7570
7571
7572
7573
7574
7575
7576
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
7647
7648
7649
7650
7651
7652
7653
7654
7655
7656
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674
7675
7676
7677
7678
7679
7680
7681
7682
7683
7684
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
7727
7728
7729
7730
7731
7732
7733
7734
7735
7736
7737
7738
7739
7740
7741
7742
7743
7744
7745
7746
7747
7748
7749
7750
7751
7752
7753
7754
7755
7756
7757
7758
7759
7760
7761
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
7781
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
7809
7810
7811
7812
7813
7814
7815
7816
7817
7818
7819
7820
7821
7822
7823
7824
7825
7826
7827
7828
7829
7830
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
7841
7842
7843
7844
7845
7846
7847
7848
7849
7850
7851
7852
7853
7854
7855
7856
7857
7858
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
7893
7894
7895
7896
7897
7898
7899
7900
7901
7902
7903
7904
7905
7906
7907
7908
7909
7910
7911
7912
7913
7914
7915
7916
7917
7918
7919
7920
7921
7922
7923
7924
7925
7926
7927
7928
7929
7930
7931
7932
7933
7934
7935
7936
7937
7938
7939
7940
7941
7942
7943
7944
7945
7946
7947
7948
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
7993
7994
7995
7996
7997
7998
7999
8000
8001
8002
8003
8004
8005
8006
8007
8008
8009
8010
8011
8012
8013
8014
8015
8016
8017
8018
8019
8020
8021
8022
8023
8024
8025
8026
8027
8028
8029
8030
8031
8032
8033
8034
8035
8036
8037
8038
8039
8040
8041
8042
8043
8044
8045
8046
8047
8048
8049
8050
8051
8052
8053
8054
8055
8056
8057
8058
8059
8060
8061
8062
8063
8064
8065
8066
8067
8068
8069
8070
8071
8072
8073
8074
8075
8076
8077
8078
8079
8080
8081
8082
8083
8084
8085
8086
8087
8088
8089
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
8127
8128
8129
8130
8131
8132
8133
8134
8135
8136
8137
8138
8139
8140
8141
8142
8143
8144
8145
8146
8147
8148
8149
8150
8151
8152
8153
8154
8155
8156
8157
8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
8198
8199
8200
8201
8202
8203
8204
8205
8206
8207
8208
8209
8210
8211
8212
8213
8214
8215
8216
8217
8218
8219
8220
8221
8222
8223
8224
8225
8226
8227
8228
8229
8230
8231
8232
8233
8234
8235
8236
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
8247
8248
8249
8250
8251
8252
8253
8254
8255
8256
8257
8258
8259
8260
8261
8262
8263
8264
8265
8266
8267
8268
8269
8270
8271
8272
8273
8274
8275
8276
8277
8278
8279
8280
8281
8282
8283
8284
8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
8308
8309
8310
8311
8312
8313
8314
8315
8316
8317
8318
8319
8320
8321
8322
8323
8324
8325
8326
8327
8328
8329
8330
8331
8332
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346
8347
8348
8349
8350
8351
8352
8353
8354
8355
8356
8357
8358
8359
8360
8361
8362
8363
8364
8365
8366
8367
8368
8369
8370
8371
8372
8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
8387
8388
8389
8390
8391
8392
8393
8394
8395
8396
8397
8398
8399
8400
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
8412
8413
8414
8415
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458
8459
8460
8461
8462
8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
8487
8488
8489
8490
8491
8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514
8515
8516
8517
8518
8519
8520
8521
8522
8523
8524
8525
8526
8527
8528
8529
8530
8531
8532
8533
8534
8535
8536
8537
8538
8539
8540
8541
8542
8543
8544
8545
8546
8547
8548
8549
8550
8551
8552
8553
8554
8555
8556
8557
8558
8559
8560
8561
8562
8563
8564
8565
8566
8567
8568
8569
8570
8571
8572
8573
8574
8575
8576
8577
8578
8579
8580
8581
8582
8583
8584
8585
8586
8587
8588
8589
8590
8591
8592
8593
8594
8595
8596
8597
8598
8599
8600
8601
8602
8603
8604
8605
8606
8607
8608
8609
8610
8611
8612
8613
8614
8615
8616
8617
8618
8619
8620
8621
8622
8623
8624
8625
8626
8627
8628
8629
8630
8631
8632
8633
8634
8635
8636
8637
8638
8639
8640
8641
8642
8643
8644
8645
8646
8647
8648
8649
8650
8651
8652
8653
8654
8655
8656
8657
8658
8659
8660
8661
8662
8663
8664
8665
8666
8667
8668
8669
8670
8671
8672
8673
8674
8675
8676
8677
8678
8679
8680
8681
8682
8683
8684
8685
8686
8687
8688
8689
8690
8691
8692
8693
8694
8695
8696
8697
8698
8699
8700
8701
8702
8703
8704
8705
8706
8707
8708
8709
8710
8711
8712
8713
8714
8715
8716
8717
8718
8719
8720
8721
8722
8723
8724
8725
8726
8727
8728
8729
8730
8731
8732
8733
8734
8735
8736
8737
8738
8739
8740
8741
8742
8743
8744
8745
8746
8747
8748
8749
8750
8751
8752
8753
8754
8755
8756
8757
8758
8759
8760
8761
8762
8763
8764
8765
8766
8767
8768
8769
8770
8771
8772
8773
8774
8775
8776
8777
8778
8779
8780
8781
8782
8783
8784
8785
8786
8787
8788
8789
8790
8791
8792
8793
8794
8795
8796
8797
8798
8799
8800
8801
8802
8803
8804
8805
8806
8807
8808
8809
8810
8811
8812
8813
8814
8815
8816
8817
8818
8819
8820
8821
8822
8823
8824
8825
8826
8827
8828
8829
8830
8831
8832
8833
8834
8835
8836
8837
8838
8839
8840
8841
8842
8843
8844
8845
8846
8847
8848
8849
8850
8851
8852
8853
8854
8855
8856
8857
8858
8859
8860
8861
8862
8863
8864
8865
8866
8867
8868
8869
8870
8871
8872
8873
8874
8875
8876
8877
8878
8879
8880
8881
8882
8883
8884
8885
8886
8887
8888
8889
8890
8891
8892
8893
8894
8895
8896
8897
8898
8899
8900
8901
8902
8903
8904
8905
8906
8907
8908
8909
8910
8911
8912
8913
8914
8915
8916
8917
8918
8919
8920
8921
8922
8923
8924
8925
8926
8927
8928
8929
8930
8931
8932
8933
8934
8935
8936
8937
8938
8939
8940
8941
8942
8943
8944
8945
8946
8947
8948
8949
8950
8951
8952
8953
8954
8955
8956
8957
8958
8959
8960
8961
8962
8963
8964
8965
8966
8967
8968
8969
8970
8971
8972
8973
8974
8975
8976
8977
8978
8979
8980
8981
8982
8983
8984
8985
8986
8987
8988
8989
8990
8991
8992
8993
8994
8995
8996
8997
8998
8999
9000
9001
9002
9003
9004
9005
9006
9007
9008
9009
9010
9011
9012
9013
9014
9015
9016
9017
9018
9019
9020
9021
9022
9023
9024
9025
9026
9027
9028
9029
9030
9031
9032
9033
9034
9035
9036
9037
9038
9039
9040
9041
9042
9043
9044
9045
9046
9047
9048
9049
9050
9051
9052
9053
9054
9055
9056
9057
9058
9059
9060
9061
9062
9063
9064
9065
9066
9067
9068
9069
9070
9071
9072
9073
9074
9075
9076
9077
9078
9079
9080
9081
9082
9083
9084
9085
9086
9087
9088
9089
9090
9091
9092
9093
9094
9095
9096
9097
9098
9099
9100
9101
9102
9103
9104
9105
9106
9107
9108
9109
9110
9111
9112
9113
9114
9115
9116
9117
9118
9119
9120
9121
9122
9123
9124
9125
9126
9127
9128
9129
9130
9131
9132
9133
9134
9135
9136
9137
9138
9139
9140
9141
9142
9143
9144
9145
9146
9147
9148
9149
9150
9151
9152
9153
9154
9155
9156
9157
9158
9159
9160
9161
9162
9163
9164
9165
9166
9167
9168
9169
9170
9171
9172
9173
9174
9175
9176
9177
9178
9179
9180
9181
9182
9183
9184
9185
9186
9187
9188
9189
9190
9191
9192
9193
9194
9195
9196
9197
9198
9199
9200
9201
9202
9203
9204
9205
9206
9207
9208
9209
9210
9211
9212
9213
9214
9215
9216
9217
9218
9219
9220
9221
9222
9223
9224
9225
9226
9227
9228
9229
9230
9231
9232
9233
9234
9235
9236
9237
9238
9239
9240
9241
9242
9243
9244
9245
9246
9247
9248
9249
9250
9251
9252
9253
9254
9255
9256
9257
9258
9259
9260
9261
9262
9263
9264
9265
9266
9267
9268
9269
9270
9271
9272
9273
9274
9275
9276
9277
9278
9279
9280
9281
9282
9283
9284
9285
9286
9287
9288
9289
9290
9291
9292
9293
9294
9295
9296
9297
9298
9299
9300
9301
9302
9303
9304
9305
9306
9307
9308
9309
9310
9311
9312
9313
9314
9315
9316
9317
9318
9319
9320
9321
9322
9323
9324
9325
9326
9327
9328
9329
9330
9331
9332
9333
9334
9335
9336
9337
9338
9339
9340
9341
9342
9343
9344
9345
9346
9347
9348
9349
9350
9351
9352
9353
9354
9355
9356
9357
9358
9359
9360
9361
9362
9363
9364
9365
9366
9367
9368
9369
9370
9371
9372
9373
9374
9375
9376
9377
9378
9379
9380
9381
9382
9383
9384
9385
9386
9387
9388
9389
9390
9391
9392
9393
9394
9395
9396
9397
9398
9399
9400
9401
9402
9403
9404
9405
9406
9407
9408
9409
9410
9411
9412
9413
9414
9415
9416
9417
9418
9419
9420
9421
9422
9423
9424
9425
9426
9427
9428
9429
9430
9431
9432
9433
9434
9435
9436
9437
9438
9439
9440
9441
9442
9443
9444
9445
9446
9447
9448
9449
9450
9451
9452
9453
9454
9455
9456
9457
9458
9459
9460
9461
9462
9463
9464
9465
9466
9467
9468
9469
9470
9471
9472
9473
9474
9475
9476
9477
9478
9479
9480
9481
9482
9483
9484
9485
9486
9487
9488
9489
9490
9491
9492
9493
9494
9495
9496
9497
9498
9499
9500
9501
9502
9503
9504
9505
9506
9507
9508
9509
9510
9511
9512
9513
9514
9515
9516
9517
9518
9519
9520
9521
9522
9523
9524
9525
9526
9527
9528
9529
9530
9531
9532
9533
9534
9535
9536
9537
9538
9539
9540
9541
9542
9543
9544
9545
9546
9547
9548
9549
9550
9551
9552
9553
9554
9555
9556
9557
9558
9559
9560
9561
9562
9563
9564
9565
9566
9567
9568
9569
9570
9571
9572
9573
9574
9575
9576
9577
9578
9579
9580
9581
9582
9583
9584
9585
9586
9587
9588
9589
9590
9591
9592
9593
9594
9595
9596
9597
9598
9599
9600
9601
9602
9603
9604
9605
9606
9607
9608
9609
9610
9611
9612
9613
9614
9615
9616
9617
9618
9619
9620
9621
9622
9623
9624
9625
9626
9627
9628
9629
9630
9631
9632
9633
9634
9635
9636
9637
9638
9639
9640
9641
9642
9643
9644
9645
9646
9647
9648
9649
9650
9651
9652
9653
9654
9655
9656
9657
9658
9659
9660
9661
9662
9663
9664
9665
9666
9667
9668
9669
9670
9671
9672
9673
9674
9675
9676
9677
9678
9679
9680
9681
9682
9683
9684
9685
9686
9687
9688
9689
9690
9691
9692
9693
9694
9695
9696
9697
9698
9699
9700
9701
9702
9703
9704
9705
9706
9707
9708
9709
9710
9711
9712
9713
9714
9715
9716
9717
9718
9719
9720
9721
9722
9723
9724
9725
9726
9727
9728
9729
9730
9731
9732
9733
9734
9735
9736
9737
9738
9739
9740
9741
9742
9743
9744
9745
9746
9747
9748
9749
9750
9751
9752
9753
9754
9755
9756
9757
9758
9759
9760
9761
9762
9763
9764
9765
9766
9767
9768
9769
9770
9771
9772
9773
9774
9775
9776
9777
9778
9779
9780
9781
9782
9783
9784
9785
9786
9787
9788
9789
9790
9791
9792
9793
9794
9795
9796
9797
9798
9799
9800
9801
9802
9803
9804
9805
9806
9807
9808
9809
9810
9811
9812
9813
9814
9815
9816
9817
9818
9819
9820
9821
9822
9823
9824
9825
9826
9827
9828
9829
9830
9831
9832
9833
9834
9835
9836
9837
9838
9839
9840
9841
9842
9843
9844
9845
9846
9847
9848
9849
9850
9851
9852
9853
9854
9855
9856
9857
9858
9859
9860
9861
9862
9863
9864
9865
9866
9867
9868
9869
9870
9871
9872
9873
9874
9875
9876
9877
9878
9879
9880
9881
9882
9883
9884
9885
9886
9887
9888
9889
9890
9891
9892
9893
9894
9895
9896
9897
9898
9899
9900
9901
9902
9903
9904
9905
9906
9907
9908
9909
9910
9911
9912
9913
9914
9915
9916
9917
9918
9919
9920
9921
9922
9923
9924
9925
9926
9927
9928
9929
9930
9931
9932
9933
9934
9935
9936
9937
9938
9939
9940
9941
9942
9943
9944
9945
9946
9947
9948
9949
9950
9951
9952
9953
9954
9955
9956
9957
9958
9959
9960
9961
9962
9963
9964
9965
9966
9967
9968
9969
9970
9971
9972
9973
9974
9975
9976
9977
9978
9979
9980
9981
9982
9983
9984
9985
9986
9987
9988
9989
9990
9991
9992
9993
9994
9995
9996
9997
9998
9999
10000
10001
10002
10003
10004
10005
10006
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
10023
10024
10025
10026
10027
10028
10029
10030
10031
10032
10033
10034
10035
10036
10037
10038
10039
10040
10041
10042
10043
10044
10045
10046
10047
10048
10049
10050
10051
10052
10053
10054
10055
10056
10057
10058
10059
10060
10061
10062
10063
10064
10065
10066
10067
10068
10069
10070
10071
10072
10073
10074
10075
10076
10077
10078
10079
10080
10081
10082
10083
10084
10085
10086
10087
10088
10089
10090
10091
10092
10093
10094
10095
10096
10097
10098
10099
10100
10101
10102
10103
10104
10105
10106
10107
10108
10109
10110
10111
10112
10113
10114
10115
10116
10117
10118
10119
10120
10121
10122
10123
10124
10125
10126
10127
10128
10129
10130
10131
10132
10133
10134
10135
10136
10137
10138
10139
10140
10141
10142
10143
10144
10145
10146
10147
10148
10149
10150
10151
10152
10153
10154
10155
10156
10157
10158
10159
10160
10161
10162
10163
10164
10165
10166
10167
10168
10169
10170
10171
10172
10173
10174
10175
10176
10177
10178
10179
10180
10181
10182
10183
10184
10185
10186
10187
10188
10189
10190
10191
10192
10193
10194
10195
10196
10197
10198
10199
10200
10201
10202
10203
10204
10205
10206
10207
10208
10209
10210
10211
10212
10213
10214
10215
10216
10217
10218
10219
10220
10221
10222
10223
10224
10225
10226
10227
10228
10229
10230
10231
10232
10233
10234
10235
10236
10237
10238
10239
10240
10241
10242
10243
10244
10245
10246
10247
10248
10249
10250
10251
10252
10253
10254
10255
10256
10257
10258
10259
10260
10261
10262
10263
10264
10265
10266
10267
10268
10269
10270
10271
10272
10273
10274
10275
10276
10277
10278
10279
10280
10281
10282
10283
10284
10285
10286
10287
10288
10289
10290
10291
10292
10293
10294
10295
10296
10297
10298
10299
10300
10301
10302
10303
10304
10305
10306
10307
10308
10309
10310
10311
10312
10313
10314
10315
10316
10317
10318
10319
10320
10321
10322
10323
10324
10325
10326
10327
10328
10329
10330
10331
10332
10333
10334
10335
10336
10337
10338
10339
10340
10341
10342
10343
10344
10345
10346
10347
10348
10349
10350
10351
10352
10353
10354
10355
10356
10357
10358
10359
10360
10361
10362
10363
10364
10365
10366
10367
10368
10369
10370
10371
10372
10373
10374
10375
10376
10377
10378
10379
10380
10381
10382
10383
10384
10385
10386
10387
10388
10389
10390
10391
10392
10393
10394
10395
10396
10397
10398
10399
10400
10401
10402
10403
10404
10405
10406
10407
10408
10409
10410
10411
10412
10413
10414
10415
10416
10417
10418
10419
10420
10421
10422
10423
10424
10425
10426
10427
10428
10429
10430
10431
10432
10433
10434
10435
10436
10437
10438
10439
10440
10441
10442
10443
10444
10445
10446
10447
10448
10449
10450
10451
10452
10453
10454
10455
10456
10457
10458
10459
10460
10461
10462
10463
10464
10465
10466
10467
10468
10469
10470
10471
10472
10473
10474
10475
10476
10477
10478
10479
10480
10481
10482
10483
10484
10485
10486
10487
10488
10489
10490
10491
10492
10493
10494
10495
10496
10497
10498
10499
10500
10501
10502
10503
10504
10505
10506
10507
10508
10509
10510
10511
10512
10513
10514
10515
10516
10517
10518
10519
10520
10521
10522
10523
10524
10525
10526
10527
10528
10529
10530
10531
10532
10533
10534
10535
10536
10537
10538
10539
10540
10541
10542
10543
10544
10545
10546
10547
10548
10549
10550
10551
10552
10553
10554
10555
10556
10557
10558
10559
10560
10561
10562
10563
10564
10565
10566
10567
10568
10569
10570
10571
10572
10573
10574
10575
10576
10577
10578
10579
10580
10581
10582
10583
10584
10585
10586
10587
10588
10589
10590
10591
10592
10593
10594
10595
10596
10597
10598
10599
10600
10601
10602
10603
10604
10605
10606
10607
10608
10609
10610
10611
10612
10613
10614
10615
10616
10617
10618
10619
10620
10621
10622
10623
10624
10625
10626
10627
10628
10629
10630
10631
10632
10633
10634
10635
10636
10637
10638
10639
10640
10641
10642
10643
10644
10645
10646
10647
10648
10649
10650
10651
10652
10653
10654
10655
10656
10657
10658
10659
10660
10661
10662
10663
10664
10665
10666
10667
10668
10669
10670
10671
10672
10673
10674
10675
10676
10677
10678
10679
10680
10681
10682
10683
10684
10685
10686
10687
10688
10689
10690
10691
10692
10693
10694
10695
10696
10697
10698
10699
10700
10701
10702
10703
10704
10705
10706
10707
10708
10709
10710
10711
10712
10713
10714
10715
10716
10717
10718
10719
10720
10721
10722
10723
10724
10725
10726
10727
10728
10729
10730
10731
10732
10733
10734
10735
10736
10737
10738
10739
10740
10741
10742
10743
10744
10745
10746
10747
10748
10749
10750
10751
10752
10753
10754
10755
10756
10757
10758
10759
10760
10761
10762
10763
10764
10765
10766
10767
10768
10769
10770
10771
10772
10773
10774
10775
10776
10777
10778
10779
10780
10781
10782
10783
10784
10785
10786
10787
10788
10789
10790
10791
10792
10793
10794
10795
10796
10797
10798
10799
10800
10801
10802
10803
10804
10805
10806
10807
10808
10809
10810
10811
10812
10813
10814
10815
10816
10817
10818
10819
10820
10821
10822
10823
10824
10825
10826
10827
10828
10829
10830
10831
10832
10833
10834
10835
10836
10837
10838
10839
10840
10841
10842
10843
10844
10845
10846
10847
10848
10849
10850
10851
10852
10853
10854
10855
10856
10857
10858
10859
10860
10861
10862
10863
10864
10865
10866
10867
10868
10869
10870
10871
10872
10873
10874
10875
10876
10877
10878
10879
10880
10881
10882
10883
10884
10885
10886
10887
10888
10889
10890
10891
10892
10893
10894
10895
10896
10897
10898
10899
10900
10901
10902
10903
10904
10905
10906
10907
10908
10909
10910
10911
10912
10913
10914
10915
10916
10917
10918
10919
10920
10921
10922
10923
10924
10925
10926
10927
10928
10929
10930
10931
10932
10933
10934
10935
10936
10937
10938
10939
10940
10941
10942
10943
10944
10945
10946
10947
10948
10949
10950
10951
10952
10953
10954
10955
10956
10957
10958
10959
10960
10961
10962
10963
10964
10965
10966
10967
10968
10969
10970
10971
10972
10973
10974
10975
10976
10977
10978
10979
10980
10981
10982
10983
10984
10985
10986
10987
10988
10989
10990
10991
10992
10993
10994
10995
10996
10997
10998
10999
11000
11001
11002
11003
11004
11005
11006
11007
11008
11009
11010
11011
11012
11013
11014
11015
11016
11017
11018
11019
11020
11021
11022
11023
11024
11025
11026
11027
11028
11029
11030
11031
11032
11033
11034
11035
11036
11037
11038
11039
11040
11041
11042
11043
11044
11045
11046
11047
11048
11049
11050
11051
11052
11053
11054
11055
11056
11057
11058
11059
11060
11061
11062
11063
11064
11065
11066
11067
11068
11069
11070
11071
11072
11073
11074
11075
11076
11077
11078
11079
11080
11081
11082
11083
11084
11085
11086
11087
11088
11089
11090
11091
11092
11093
11094
11095
11096
11097
11098
11099
11100
11101
11102
11103
11104
11105
11106
11107
11108
11109
11110
11111
11112
11113
11114
11115
11116
11117
11118
11119
11120
11121
11122
11123
11124
11125
11126
11127
11128
11129
11130
11131
11132
11133
11134
11135
11136
11137
11138
11139
11140
11141
11142
11143
11144
11145
11146
11147
11148
11149
11150
11151
11152
11153
11154
11155
11156
11157
11158
11159
11160
11161
11162
11163
11164
11165
11166
11167
11168
11169
11170
11171
11172
11173
11174
11175
11176
11177
11178
11179
11180
11181
11182
11183
11184
11185
11186
11187
11188
11189
11190
11191
11192
11193
11194
11195
11196
11197
11198
11199
11200
11201
11202
11203
11204
11205
11206
11207
11208
11209
11210
11211
11212
11213
11214
11215
11216
11217
11218
11219
11220
11221
11222
11223
11224
11225
11226
11227
11228
11229
11230
11231
11232
11233
11234
11235
11236
11237
11238
11239
11240
11241
11242
11243
11244
11245
11246
11247
11248
11249
11250
11251
11252
11253
11254
11255
11256
11257
11258
11259
11260
11261
11262
11263
11264
11265
11266
11267
11268
11269
11270
11271
11272
11273
11274
11275
11276
11277
11278
11279
11280
11281
11282
11283
11284
11285
11286
11287
11288
11289
11290
11291
11292
11293
11294
11295
11296
11297
11298
11299
11300
11301
11302
11303
11304
11305
11306
11307
11308
11309
11310
11311
11312
11313
11314
11315
11316
11317
11318
11319
11320
11321
11322
11323
11324
11325
11326
11327
11328
11329
11330
11331
11332
11333
11334
11335
11336
11337
11338
11339
11340
11341
11342
11343
11344
11345
11346
11347
11348
11349
11350
11351
11352
11353
11354
11355
11356
11357
11358
11359
11360
11361
11362
11363
11364
11365
11366
11367
11368
11369
11370
11371
11372
11373
11374
11375
11376
11377
11378
11379
11380
11381
11382
11383
11384
11385
11386
11387
11388
11389
11390
11391
11392
11393
11394
11395
11396
11397
11398
11399
11400
11401
11402
11403
11404
11405
11406
11407
11408
11409
11410
11411
11412
11413
11414
11415
11416
11417
11418
11419
11420
11421
11422
11423
11424
11425
11426
11427
11428
11429
11430
11431
11432
11433
11434
11435
11436
11437
11438
11439
11440
11441
11442
11443
11444
11445
11446
11447
11448
11449
11450
11451
11452
11453
11454
11455
11456
11457
11458
11459
11460
11461
11462
11463
11464
11465
11466
11467
11468
11469
11470
11471
11472
11473
11474
11475
11476
11477
11478
11479
11480
11481
11482
11483
11484
11485
11486
11487
11488
11489
11490
11491
11492
11493
11494
11495
11496
11497
11498
11499
11500
11501
11502
11503
11504
11505
11506
11507
11508
11509
11510
11511
11512
11513
11514
11515
11516
11517
11518
11519
11520
11521
11522
11523
11524
11525
11526
11527
11528
11529
11530
11531
11532
11533
11534
11535
11536
11537
11538
11539
11540
11541
11542
11543
11544
11545
11546
11547
11548
11549
11550
11551
11552
11553
11554
11555
11556
11557
11558
11559
11560
11561
11562
11563
11564
11565
11566
11567
11568
11569
11570
11571
11572
11573
11574
11575
11576
11577
11578
11579
11580
11581
11582
11583
11584
11585
11586
11587
11588
11589
11590
11591
11592
11593
11594
11595
11596
11597
11598
11599
11600
11601
11602
11603
11604
11605
11606
11607
11608
11609
11610
11611
11612
11613
11614
11615
11616
11617
11618
11619
11620
11621
11622
11623
11624
11625
11626
11627
11628
11629
11630
11631
11632
11633
11634
11635
11636
11637
11638
11639
11640
11641
11642
11643
11644
11645
11646
11647
11648
11649
11650
11651
11652
11653
11654
11655
11656
11657
11658
11659
11660
11661
11662
11663
11664
11665
11666
11667
11668
11669
11670
11671
11672
11673
11674
11675
11676
11677
11678
11679
11680
11681
11682
11683
11684
11685
11686
11687
11688
11689
11690
11691
11692
11693
11694
11695
11696
11697
11698
11699
11700
11701
11702
11703
11704
11705
11706
11707
11708
11709
11710
11711
11712
11713
11714
11715
11716
11717
11718
11719
11720
11721
11722
11723
11724
11725
11726
11727
11728
11729
11730
11731
11732
11733
11734
11735
11736
11737
11738
11739
11740
11741
11742
11743
11744
11745
11746
11747
11748
11749
11750
11751
11752
11753
11754
11755
11756
11757
11758
11759
11760
11761
11762
11763
11764
11765
11766
11767
11768
11769
11770
11771
11772
11773
11774
11775
11776
11777
11778
11779
11780
11781
11782
11783
11784
11785
11786
11787
11788
11789
11790
11791
11792
11793
11794
11795
11796
11797
11798
11799
11800
11801
11802
11803
11804
11805
11806
11807
11808
11809
11810
11811
11812
11813
11814
11815
11816
11817
11818
11819
11820
11821
11822
11823
11824
11825
11826
11827
11828
11829
11830
11831
11832
11833
11834
11835
11836
11837
11838
11839
11840
11841
11842
11843
11844
11845
11846
11847
11848
11849
11850
11851
11852
11853
11854
11855
11856
11857
11858
11859
11860
11861
11862
11863
11864
11865
11866
11867
11868
11869
11870
11871
11872
11873
11874
11875
11876
11877
11878
11879
11880
11881
11882
11883
11884
11885
11886
11887
11888
11889
11890
11891
11892
11893
11894
11895
11896
11897
11898
11899
11900
11901
11902
11903
11904
11905
11906
11907
11908
11909
11910
11911
11912
11913
11914
11915
11916
11917
11918
11919
11920
11921
11922
11923
11924
11925
11926
11927
11928
11929
11930
11931
11932
11933
11934
11935
11936
11937
11938
11939
11940
11941
11942
11943
11944
11945
11946
11947
11948
11949
11950
11951
11952
11953
11954
11955
11956
11957
11958
11959
11960
11961
11962
11963
11964
11965
11966
11967
11968
11969
11970
11971
11972
11973
11974
11975
11976
11977
11978
11979
11980
11981
11982
11983
11984
11985
11986
11987
11988
11989
11990
11991
11992
11993
11994
11995
11996
11997
11998
11999
12000
12001
12002
12003
12004
12005
12006
12007
12008
12009
12010
12011
12012
12013
12014
12015
12016
12017
12018
12019
12020
12021
12022
12023
12024
12025
12026
12027
12028
12029
12030
12031
12032
12033
12034
12035
12036
12037
12038
12039
12040
12041
12042
12043
12044
12045
12046
12047
12048
12049
12050
12051
12052
12053
12054
12055
12056
12057
12058
12059
12060
12061
12062
12063
12064
12065
12066
12067
12068
12069
12070
12071
12072
12073
12074
12075
12076
12077
12078
12079
12080
12081
12082
12083
12084
12085
12086
12087
12088
12089
12090
12091
12092
12093
12094
12095
12096
12097
12098
12099
12100
12101
12102
12103
12104
12105
12106
12107
12108
12109
12110
12111
12112
12113
12114
12115
12116
12117
12118
12119
12120
12121
12122
12123
12124
12125
12126
12127
12128
12129
12130
12131
12132
12133
12134
12135
12136
12137
12138
12139
12140
12141
12142
12143
12144
12145
12146
12147
12148
12149
12150
   [IUCr Home Page] [CIF Home Page] [CBF/imgCIF]

     ----------------------------------------------------------------------

            | IUCr Home Page | CIF Home Page | CBF/imgCIF | CBFlib |
                  | NOTICE | GPL | LGPL | imgCIF dictionary |
                       | Click Here to Make a Donation |

                                     CBFlib

                             An API for CBF/imgCIF
                Crystallographic Binary Files with ASCII Support
                                 Version 0.9.5
                                 27 April 2014
                              rev 22 February 2015

                                       by
                                 Paul J. Ellis
                   Stanford Synchrotron Radiation Laboratory

                                      and
                              Herbert J. Bernstein
                                Bernstein + Sons
                      yaya at bernstein-plus-sons dot com

     (c) Copyright 2006, 2007, 2008, 2011, 2013, 2014 Herbert J. Bernstein

     ----------------------------------------------------------------------

      YOU MAY REDISTRIBUTE THE CBFLIB PACKAGE UNDER THE TERMS OF THE GPL.

    ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS OF THE
                                     LGPL.

     ----------------------------------------------------------------------

                  Before using this software, please read the
                                     NOTICE
for important disclaimers and the IUCr Policy on the Use of the Crystallographic
          Information File (CIF) and for other important information.

   Work on imgCIF and CBFlib supported in part by the U. S. Department of
   Energy (DOE) under grants ER63601-1021466-0009501 and
   ER64212-1027708-0011962, by the U. S. National Science Foundation (NSF)
   under grants DBI-0610407, DBI-0315281 and EF-0312612, the U. S. National
   Institutes of Health (NIH) under grants 1R15GM078077 from NIGMS and
   1R13RR023192 from NCRR and funding from the International Union for
   Crystallographyn (IUCr). The content is solely the responsibility of the
   authors and does not necessarily represent the official views of DOE, NSF,
   NIH, NIGMS, NCRR or IUCr. Recent work on integration among CBF, HDF5 and
   NeXus supported in part by Pandata ODI (EU 7th Framework Programme)

     ----------------------------------------------------------------------

                                Version History

   Version   Date            By        Description                            
     0.1       Apr. 1998       PJE       This was the first CBFlib release.   
                                       It supported binary CBF files using    
                                       binary strings.                        
     0.2       Aug. 1998       HJB       This release added ascii imgCIF      
                                       support using MIME-encoded binary      
                                       sections, added the option of MIME     
                                       headers for the binary strings was     
                                       well. MIME code adapted from mpack     
                                       1.5. Added hooks needed for DDL1-style 
                                       names without categories.              
     0.3       Sep. 1998       PJE       This release cleaned up the changes  
                                       made for version 0.2, allowing         
                                       multi-threaded use of the code, and    
                                       removing dependence on the mpack       
                                       package.                               
     0.4       Nov. 1998       HJB       This release merged much of the      
                                       message digest code into the general   
                                       file reading and writing to reduce the 
                                       number of passes. More consistency     
                                       checking between the MIME header and   
                                       the binary header was introduced. The  
                                       size in the MIME header was adjusted   
                                       to agree with the version 0.2          
                                       documentation.                         
     0.5       Dec. 1998       PJE       This release greatly increased the   
                                       speed of processing by allowing for    
                                       deferred digest evaluation.            
     0.6       Jan. 1999       HJB       This release removed the redundant   
                                       information (binary id, size,          
                                       compression id) from a binary header   
                                       when there is a MIME header, removed   
                                       the unused repeat argument, and made   
                                       the memory allocation for buffering    
                                       and tables with many rows sensitive to 
                                       the current memory allocation already  
                                       used.                                  
     0.6.1     Feb. 2001       HP (per   This release fixed a memory leak due 
                             HJB)      to misallocation by size of cbf_handle 
                                       instead of cbf_handle_struct           
     0.7       Mar. 2001       PJE       This release added high-level        
                                       instructions based on the imgCIF       
                                       dictionary version 1.1.                
     0.7.1     Mar. 2001       PJE       The high-level functions were        
                                       revised to permit future expansion to  
                                       files with multiple images.            
     0.7.2     Apr. 2001       HJB       This release adjusted cbf_cimple.c   
                                       to conform to cif_img.dic version      
                                       1.1.3                                  
     0.7.2.1   May 2001        PJE       This release corrected an if nesting 
                                       error in the prior mod to              
                                       cbf_cimple.c.                          
     0.7.3     Oct. 2002       PJE       This release modified cbf_simple.c   
                                       to reorder image data on read so that  
                                       the indices are always increasing in   
                                       memory (this behavior was undefined    
                                       previously).                           
     0.7.4     Jan 2004        HJB       This release fixes a parse error for 
                                       quoted strings, adds code to get and   
                                       set character string types, and        
                                       removes compiler warnings              
     0.7.5     Apr 2006        HJB       This release cleans up some compiler 
                                       warnings, corrects a parse error on    
                                       quoted strings with a leading blank as 
                                       adds the new routines for support of   
                                       aliases, dictionaries and real arrays, 
                                       higher level routines to get and set   
                                       pixel sizes, do cell computations, and 
                                       to set beam centers, improves support  
                                       for conversion of images, picking up   
                                       more data from headers.                
     0.7.6     Jul 2006        HJB       This release reorganizes the kit     
                                       into two pieces:                       
                                       CBFlib_0.7.6_Data_Files and            
                                       CBFlib_0.7.6. An optional local copy   
                                       of getopt is added. The 1.4 draft      
                                       dictionary has been added. cif2cbf     
                                       updated to support vcif2 validation.   
                                       convert_image and cif2cbf updated to   
                                       report text of error messages.         
                                       convert_image updated to support tag   
                                       and category aliases, default to adxv  
                                       images. convert_image and img updated  
                                       to support row-major images. Support   
                                       added for binning. API Support added   
                                       for validation, wide files and line    
                                       folding. Logic changed for beam center 
                                       reporting. Added new routines:         
                                       cbf_validate, cbf_get_bin_sizes,       
                                       cbf_set_bin_sizes,                     
                                       cbf_find_last_typed_child,             
                                       cbf_compose_itemname,                  
                                       cbf_set_cbf_logfile,                   
                                       cbf_make_widefile, cbf_read_anyfile,   
                                       cbf_read_widefile,                     
                                       cbf_write_local_file,                  
                                       cbf_write_widefile, cbf_column_number, 
                                       cbf_blockitem_number, cbf_log,         
                                       cbf_check_category_tags,               
                                       cbf_set_beam_center                    
     0.7.7     February 2007   HJB       This release reflects changes for    
                                       base 32K support developed by G.       
                                       Darakev, and changes for support of    
                                       reals, 3d arrays, byte_offset          
                                       compression and J. P. Abrahams packed  
                                       compression made in consultation with  
                                       (in alphabetic order) E. Eikenberry,   
                                       A. Hammerley, W. Kabsch, M. Kobas, J.  
                                       Wright and others at PSI and ESRF in   
                                       January 2007, as well accumulated      
                                       changes fixing problems in release     
                                       0.7.6.                                 
     0.7.7.1   February 2007   HJB       This release is a patch to 0.7.7 to  
                                       change the treatment of the byteorder  
                                       parameter from strcpy semantics to     
                                       return of a pointer to a string        
                                       constant. Our thanks to E. Eikenberry  
                                       for pointing out the problem.          
     0.7.7.2   February 2007   HJB       This release is a patch to 0.7.7.1   
                                       to add testing for JPA packed          
                                       compression and to respect signs       
                                       declared in the MIME header.           
     0.7.7.3   April 2007      HJB       This release is a patch to 0.7.7.3   
                                       to add f90 support for reading of CBF  
                                       byte-offset and packed compression, to 
                                       fix problems with gcc 4.4.1 and to     
                                       correct errors in multidimensional     
                                       packed compression.                    
     0.7.7.4   May 2007        HJB       Corrects in handling SLS detector    
                                       mincbfs and reorder dimensions versus  
                                       arrays for some f90 compilers as per   
                                       H. Powell.                             
     0.7.7.5   May 2007        HJB       Fix to cbf_get_image for bug         
                                       reported by F. Remacle, fixes for      
                                       windows builds as per J. Wright and F. 
                                       Remacle.                               
     0.7.7.6   Jun 2007        HJB       Fix to CBF byte-offset compression   
                                       writes, fix to Makefiles and m4 for    
                                       f90 test programs to allow adjustable  
                                       record length.                         
     0.7.8     Jul 2007        HJB       Release for full support of SLS data 
                                       files with updated convert_minicbf,    
                                       and support for gfortran from gcc 4.2. 
     0.7.8.1   Jul 2007        HJB       Update to 0.7.8 release to fix       
                                       memory leaks reported by N. Sauter and 
                                       to update validation checks for recent 
                                       changes.                               
     0.7.8.2   Dec 2007        CN, HJB   Update to 0.7.8.1 to add ADSC jiffie 
                                       by Chris Nielsen, and to add ..._fs    
                                       and ..._sf macros.                     
     0.7.9     Dec 2007        CN, HJB Identical to 0.7.8.2 except for a      
                                       cleanup of deprecated examples, e.g.   
                                       diffrn_frame_data                      
     0.7.9.1   Jan 2008        CN, HJB   Update to 0.7.8.2 to add inverse     
                                       ADSC jiffie by Chris Nielsen, to clean 
                                       up problems in handling maps for       
                                       RasMol.                                
     0.8.0     Jul 2008        GT, HJB   Cleanup of 0.7.9.1 to start 0.8      
                                       series.                                
     0.8.1     Jul 2009        EZ, CN,    Release with EZ's 2008 DDLm support 
                             PC, GW,   using JH's PyCifRW, also cbff f95      
                             JH, HJB   wrapper code, PC's java bindings.      
     0.9.1     Aug 2010        PC, EE,    Release with EE's Dectris template  
                             JLM, NS,  software, also with vcif3, new         
                             EZ, HJB   arvai_test, sequence_match.            
     0.9.2     Feb 2011        PC, EE,    New default release with updated    
                             JLM, NS,  pycbf, tiff support, removal of        
                             EZ, HJB   default use of PyCifRW to avoid Fedora 
                                       license issue.                         
     0.9.3     Oct 2013        JS, HJB   Added low-level 'cbf_H5*' functions  
                                       for interacting with HDF5, higher      
                                       level functions for converting CBF or  
                                       miniCBF files to NeXus format, two     
                                       utility programs to convert CBF or     
                                       miniCBF files to NeXus format and some 
                                       unit tests for the low-level 'cbf_H5*' 
                                       functions. Add initial FEL detector    
                                       support.                               
     0.9.4     March 2014      JS, HJB   Refactored implementation of the     
                                       NXMX application defintion functional  
                                       mapping with improvements to cmake     
                                       support and a preliminary effort at    
                                       handling Stokes polarization mapping.  
                                       This release had serious issues in the 
                                       functional mapping axis mapping and    
                                       should not be used for production      
                                       involving NeXus files.                 
     0.9.5     April 2014      HJB       This is a production release for     
                                       single detector module single crystal  
                                       MX NeXus support.                      

     ----------------------------------------------------------------------

                                 Known Problems

   The example program tiff2cbf needs the enviroment variable LD_LIBRARY_PATH
   set to the location of the lib directory in CBFlib_0.9.2.11, unless a
   system install of tiff-3.9.4-rev-6Feb11 has been done.

   Due to license issues, PyCifRW is not included with default releases of
   CBFlib. Users can download PyCifRW separately.

   There are some issues with Peter Chang's lastest java wrapper under the
   CBFlib 0.9.2.11 release. Until they are resolved, the CBFlib 0.8.1 release
   should be used for Java applications.

   This version does not have support for predictor compression.

   Code is needed to support array sub-sections.

                                    Foreword

   In order to work with CBFlib, you need:

     * the source code, in the form of a "gzipped" tar, CBFlib_0.9.5.tar.gz;
       and
     * the test data:
          * CBFlib_0.9.5_Data_Files_Input.tar.gz (17 MB) a "gzipped" tar of
            the input data files needed to test the API;
          * CBFlib_0.9.5_Data_Files_Output.tar.gz (36 MB) a "gzipped" tar of
            the output data files needed to test the API, or, if space is at
            a premium;
          * CBFlib_0.9.5_Data_Files_Output_Sigs_Only.tar.gz (1 KB) is a
            "gzipped" tar of only the MD5 signatures of the output data files
            needed to test the API.

   If your system has the program wget, you only need the source code. The
   download of the other tar balls will be handled automatically.

   Be careful about space. A full build and test can use 450 MB or more. If
   space is tight, be sure to read the instructions below on using only the
   signatures of the test files.

   Uncompress and unpack :

     * gunzip < CBFlib_0.9.5.tar.gz | tar xvf -

   To run the test programs, you will also need Paul Ellis's sample MAR345
   image, example.mar2300, Chris Nielsen's sample ADSC Quantum 315 image,
   mb_LP_1_001.img, and Eric Eikenberry's SLS sample Pilatus 6m image,
   insulin_pilatus6m, as sample data. In addition there are is a PDB mmCIF
   file, 9ins.cif, and 3 special test files testflatin.cbf,
   testflatpackedin.cbf and testrealin.cbf. All these files will be dowloaded
   and extracted by the Makefile from CBFlib_0.9.2.11_Data_Files_Input. Do
   not download copies into the top level directory.

   In addition, the kit will need tiff and hdf5 libraries.

   Thare are various sample Makefiles for common configurations. The
   Makefile_OSX samples is for systems with gfortran from prior to the
   release of gcc 4.2. For the most recent gfortran, use Makefile_OSX_gcc42.
   All the Makefiles are generated from m4/Makefile.m4. For newer OS X
   systems, the default Makefile should work.

   The Makefiles use GNU make constructs, such as ifeq and ifneq. If you need
   to use a different version of make, you will need to edit out the
   conditionals

   The operation of the Makefiles is sensitive to the following environment
   variables:

     * CBFLIB_USE_PYCIFRW If you define this environment variable, you may
       rebuild the Makefiles to include James Hester's PyCifRW. The process
       under bash is:

 export CBFLIB_USE_PYCIFRW=yes
 cd CBFlib_0.9.5
 touch m4/Makefile.m4
 make Makefiles

     * CBF_DONT_USE_LONG_LONG If you define this environment variable, use of
       the long long data type in CBFlib is replaced by use of a struct. The
       Makefiles do not need to be rebuilt. Makefile_MINGW does not use the
       long long data type even without defining this variable.
     * NOFORTRAN If you define this environment variable, use of the fortran
       compiler is suppressed.

   If necessary, adjust the definition of CC and C++ and other defintions in
   Makefile to point to your compilers. Set the definition of CFLAGS to an
   appropriate value for your C and C++ compilers, the definition of F90C to
   point to your Fortan-90/95 compiler, and the definitions of F90FLAGS and
   F90LDFLAGS to approriate values for your Fortan-90/95 compilers, and then

   make all
   make tests

   or, if space is at a premium:

   make all
   make tests_sigs_only

   If you do not have a fortran compiler, you will need edit the Makefile or
   to define the variable NOFORTRAN, either in the Makefile or in the
   environment

   We have included examples of CBF/imgCIF files produced by CBFlib in the
   test data CBFlib_0.9.5_Data_Files_Output.tar.gz, the current best draft of
   the CBF Extensions Dictionary, and of Andy Hammersley's CBF definition,
   updated to become a DRAFT CBF/ImgCIF DEFINITION.

   CBFlib 0.9.5 includes a program, tiff2cbf, to convert from tiff files to
   CBF files, that requires an augmented version of tiff-3.9.4 called
   tiff-3.9.4-rev-6Feb11, that installs into the CBFlib_0.9.2.11 directory.
   If a system copy is desired, download and install
   http://downloads.sf.net/cbflib/tiff-3.9.4-rev-6Feb11.tar.gz

     ----------------------------------------------------------------------

                                    Contents

     * 1. Introduction
     * 2. Function descriptions
          * 2.1 General description
               * 2.1.1 CBF handles
               * 2.1.2 CBF goniometer handles
               * 2.1.3 CBF detector handles
               * 2.1.4 CBF positioner handles
               * 2.1.5 Return values
          * 2.2 Reading and writing files containing binary sections
               * 2.2.1 Reading binary sections
               * 2.2.2 Writing binary sections
               * 2.2.3 Summary of reading and writing files containing binary
                 sections
               * 2.2.4 Ordering of array indices
          * 2.3 Low-level function prototypes
               * 2.3.1 cbf_make_handle
               * 2.3.2 cbf_free_handle
               * 2.3.3 cbf_read_file, cbf_read_widefile
               * 2.3.4 cbf_write_file, cbf_write_widefile
               * 2.3.5 cbf_new_datablock, cbf_new_saveframe
               * 2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
               * 2.3.7 cbf_new_category
               * 2.3.8 cbf_force_new_category
               * 2.3.9 cbf_new_column
               * 2.3.10 cbf_new_row
               * 2.3.11 cbf_insert_row
               * 2.3.12 cbf_delete_row
               * 2.3.13 cbf_set_datablockname, cbf_set_saveframename
               * 2.3.14 cbf_reset_datablocks
               * 2.3.15 cbf_reset_datablock, cbf_reset_saveframe
               * 2.3.16 cbf_reset_category
               * 2.3.17 cbf_remove_datablock, cbf_remove_saveframe
               * 2.3.18 cbf_remove_category
               * 2.3.19 cbf_remove_column
               * 2.3.20 cbf_remove_row
               * 2.3.21 cbf_rewind_datablock
               * 2.3.22 cbf_rewind_category, cbf_rewind_saveframe,
                 cbf_rewind_blockitem
               * 2.3.23 cbf_rewind_column
               * 2.3.24 cbf_rewind_row
               * 2.3.25 cbf_next_datablock
               * 2.3.26 cbf_next_category, cbf_next_saveframe,
                 cbf_next_blockitem
               * 2.3.27 cbf_next_column
               * 2.3.28 cbf_next_row
               * 2.3.29 cbf_find_datablock
               * 2.3.30 cbf_find_category, cbf_find_saveframe,
                 cbf_find_blockitem
               * 2.3.31 cbf_find_column
               * 2.3.32 cbf_find_row
               * 2.3.33 cbf_find_nextrow
               * 2.3.34 cbf_count_datablocks
               * 2.3.35 cbf_count_categories, cbf_count_saveframes,
                 cbf_count_blockitems
               * 2.3.36 cbf_count_columns
               * 2.3.37 cbf_count_rows
               * 2.3.38 cbf_select_datablock
               * 2.3.39 cbf_select_category, cbf_select_saveframe,
                 cbf_select_blockitem
               * 2.3.40 cbf_select_column
               * 2.3.41 cbf_select_row
               * 2.3.42 cbf_datablock_name
               * 2.3.43 cbf_category_name
               * 2.3.44 cbf_column_name, cbf_set_column_name
               * 2.3.45 cbf_row_number
               * 2.3.46 cbf_get_value, cbf_require_value
               * 2.3.47 cbf_set_value
               * 2.3.48 cbf_get_typeofvalue
               * 2.3.49 cbf_set_typeofvalue
               * 2.3.50 cbf_get_integervalue, cbf_require_integervalue
               * 2.3.51 cbf_set_integervalue
               * 2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
               * 2.3.53 cbf_set_doublevalue
               * 2.3.54 cbf_get_integerarrayparameters,
                       cbf_get_integerarrayparameters_wdims,
                 cbf_get_integerarrayparameters_wdims_fs,
                 cbf_get_integerarrayparameters_wdims_sf
                       cbf_get_realarrayparameters,
                       cbf_get_realarrayparameters_wdims,
                 cbf_get_realarrayparameters_wdims_fs,
                 cbf_get_realarrayparameters_wdims_sf
               * 2.3.55 cbf_get_integerarray, cbf_get_realarray
               * 2.3.56 cbf_set_integerarray,
                       cbf_set_integerarray_wdims,
                 cbf_set_integerarray_wdims_fs,
                 cbf_set_integerarray_wdims_sf,
                       cbf_set_realarray,
                       cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs,
                 cbf_set_realarray_wdims_sf
               * 2.3.57 cbf_failnez
               * 2.3.58 cbf_onfailnez
               * 2.3.59 cbf_require_datablock
               * 2.3.60 cbf_require_category
               * 2.3.61 cbf_require_column
               * 2.3.62 cbf_require_column_value
               * 2.3.63 cbf_require_column_integervalue
               * 2.3.64 cbf_require_column_doublevalue
               * 2.3.65 cbf_get_local_integer_byte_order,
                 cbf_get_local_real_byte_order, cbf_get_local_real_format
               * 2.3.66 cbf_get_dictionary, cbf_set_dictionary,
                 cbf_require_dictionary
               * 2.3.67 cbf_convert_dictionary
               * 2.3.68 cbf_find_tag, cbf_find_local_tag
               * 2.3.69 cbf_find_category_root, cbf_set_category_root,
                 cbf_require_category_root
               * 2.3.70 cbf_find_tag_root, cbf_set_tag_root,
                 cbf_require_tag_root
               * 2.3.71 cbf_find_tag_category, cbf_set_tag_category
          * 2.4 High-level function prototypes (new for version 0.7)
               * 2.4.1 cbf_read_template
               * 2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id
               * 2.4.3 cbf_set_diffrn_id
               * 2.4.4 cbf_get_crystal_id
               * 2.4.5 cbf_set_crystal_id
               * 2.4.6 cbf_get_wavelength
               * 2.4.7 cbf_set_wavelength
               * 2.4.8 cbf_get_polarization
               * 2.4.9 cbf_set_polarization
               * 2.4.10 cbf_get_divergence
               * 2.4.11 cbf_set_divergence
               * 2.4.12 cbf_count_elements
               * 2.4.13 cbf_get_element_number, cbf_get_element_id
               * 2.4.14 cbf_get_gain
               * 2.4.15 cbf_set_gain
               * 2.4.16 cbf_get_overload
               * 2.4.17 cbf_set_overload
               * 2.4.18 cbf_get_integration_time
               * 2.4.19 cbf_set_integration_time
               * 2.4.20 cbf_get_time
               * 2.4.21 cbf_set_time
               * 2.4.22 cbf_get_date
               * 2.4.23 cbf_set_date
               * 2.4.24 cbf_set_current_time
               * 2.4.25 cbf_get_image_size, cbf_get_image_size_fs,
                 cbf_get_image_size_fs,
                       cbf_get_3d_image_size, cbf_get_3d_image_size_fs,
                 cbf_get_3d_image_size_sf
               * 2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,
                       cbf_get_real_image, cbf_get_real_image_fs,
                 cbf_get_real_image_sf,
                       cbf_get_3d_image, cbf_get_3d_image_fs,
                 cbf_get_3d_image_sf,
                       cbf_get_real_3d_image, cbf_get_real_3d_image_fs,
                 cbf_get_real_3d_image_sf
               * 2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
                       cbf_set_real_image, cbf_set_real_image_fs,
                 cbf_set_real_image_sf,
                       cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
                       cbf_set_real_3d_image, cbf_set_real_3d_image_fs,
                 cbf_set_real_3d_image_sf
               * 2.4.28 cbf_get_axis_ancestor, cbf_get_axis_depends_on,
                 cbf_get_axis_equipment, cbf_get_axis_equipment_component,
                 cbf_get_axis_offset, cbf_get_axis_rotation,
                 cbf_get_axis_rotation_axis, cbf_get_axis_setting,
                 cbf_get_axis_type, cbf_get_axis_vector
               * 2.4.29 cbf_set_axis_setting
               * 2.4.30 cbf_construct_goniometer
               * 2.4.31 cbf_free_goniometer
               * 2.4.32 cbf_get_rotation_axis
               * 2.4.33 cbf_get_rotation_range
               * 2.4.34 cbf_rotate_vector
               * 2.4.35 cbf_get_reciprocal
               * 2.4.36 cbf_construct_detector,
                 cbf_construct_reference_detector,
                 cbf_require_reference_detector
               * 2.4.37 cbf_free_detector
               * 2.4.38 cbf_construct_positioner,
                 cbf_construct_reference_positioner
               * 2.4.39 cbf_free_positioner
               * 2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs,
                 cbf_get_beam_center_sf,
                       cbf_set_beam_center, cbf_set_beam_center_fs,
                 cbf_set_beam_center_sf,
                       cbf_set_reference_beam_center,
                 cbf_set_reference_beam_center_fs,
                 cbf_set_reference_beam_center_sf
               * 2.4.41 cbf_get_detector_distance
               * 2.4.42 cbf_get_detector_normal
               * 2.4.43 cbf_get_detector_axis_slow,
                 cbf_get_detector_axis_fast, cbf_get_detector_axes,
                 cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
                 cbf_get_detector_surface_axes
               * 2.4.44 cbf_get_pixel_coordinates,
                 cbf_get_pixel_coordinates_fs, cbf_get_pixel_coordinates_sf
               * 2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs,
                 cbf_get_pixel_normal_sf
               * 2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs,
                 cbf_get_pixel_area_sf
               * 2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs,
                 cbf_get_pixel_size_sf
               * 2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs,
                 cbf_set_pixel_size_sf
               * 2.4.49 cbf_get_inferred_pixel_size,
                 cbf_get_inferred_pixel_size_fs,
                 cbf_get_inferred_pixel_size_sf
               * 2.4.50 cbf_get_unit_cell
               * 2.4.51 cbf_set_unit_cell
               * 2.4.52 cbf_get_reciprocal_cell
               * 2.4.53 cbf_set_reciprocal_cell
               * 2.4.54 cbf_compute_cell_volume
               * 2.4.55 cbf_compute_reciprocal_cell
               * 2.4.56 cbf_get_orientation_matrix,
                 cbf_set_orientation_matrix
               * 2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes
               * 2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise,
                 cbf_get_axis_reference_poise
          * 2.5 F90 function interfaces
               * 2.5.1 FCB_ATOL_WCNT
               * 2.5.2 FCB_CI_STRNCMPARR
               * 2.5.3 FCB_EXIT_BINARY
               * 2.5.4 FCB_NBLEN_ARRAY
               * 2.5.5 FCB_NEXT_BINARY
               * 2.5.6 FCB_OPEN_CIFIN
               * 2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2,
                 FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
                 FCB_DECOMPRESS_PACKED_3D_I4
               * 2.5.8 FCB_READ_BITS
               * 2.5.9 FCB_READ_BYTE
               * 2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4,
                 FCB_READ_IMAGE_3D_I2, FCB_READ_IMAGE_3D_I4
               * 2.5.11 FCB_READ_LINE
               * 2.5.12 FCB_READ_XDS_I2
               * 2.5.13 FCB_SKIP_WHITESPACE
          * 2.6 HDF5 abstraction layer and convenience functions
               * 2.6.1 cbf_H5Acreate
               * 2.6.2 cbf_H5Afind
               * 2.6.3 cbf_H5Aread
               * 2.6.4 cbf_H5Aread_string
               * 2.6.5 cbf_H5Awrite
               * 2.6.6 cbf_H5Arequire_cmp2
               * 2.6.7 cbf_H5Arequire_cmp2_ULP
               * 2.6.8 cbf_H5Arequire_string
               * 2.6.9 cbf_H5Afree
               * 2.6.10 cbf_H5Dcreate
               * 2.6.11 cbf_H5Dfind2
               * 2.6.12 cbf_H5Drequire
               * 2.6.13 cbf_H5Dinsert
               * 2.6.14 cbf_H5Dset_extent
               * 2.6.15 cbf_H5Dwrite2
               * 2.6.16 cbf_H5Dread2
               * 2.6.17 cbf_H5Drequire_scalar_F64LE2
               * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
               * 2.6.19 cbf_H5Drequire_flstring
               * 2.6.20 cbf_H5Dfree
               * 2.6.21 cbf_H5Fopen
               * 2.6.22 cbf_H5Fclose
               * 2.6.23 cbf_H5Gcreate
               * 2.6.24 cbf_H5Gfind
               * 2.6.25 cbf_H5Grequire
               * 2.6.26 cbf_H5Gfree
               * 2.6.27 cbf_H5Ivalid
               * 2.6.28 cbf_H5Ocmp
               * 2.6.29 cbf_H5Ofree
               * 2.6.30 cbf_H5Screate
               * 2.6.31 cbf_H5Sfree
               * 2.6.32 cbf_H5Tcreate_string
               * 2.6.33 cbf_H5Tfree
          * 2.7 High-level NeXus-related functions
               * 2.7.1 cbf_h5handle_get_file
               * 2.7.2 cbf_h5handle_set_file
               * 2.7.3 cbf_h5handle_get_entry
               * 2.7.4 cbf_h5handle_set_entry
               * 2.7.5 cbf_h5handle_require_entry
               * 2.7.6 cbf_h5handle_require_entry_definition
               * 2.7.7 cbf_h5handle_get_sample
               * 2.7.8 cbf_h5handle_set_sample
               * 2.7.9 cbf_h5handle_require_sample
               * 2.7.10 cbf_h5handle_get_beam
               * 2.7.11 cbf_h5handle_set_beam
               * 2.7.12 cbf_h5handle_require_beam
               * 2.7.13 cbf_h5handle_get_instrument
               * 2.7.14 cbf_h5handle_set_instrument
               * 2.7.15 cbf_h5handle_find_instrument
               * 2.7.16 cbf_h5handle_require_instrument
               * 2.7.17 cbf_h5handle_get_detector
               * 2.7.18 cbf_h5handle_set_detector
               * 2.7.19 cbf_h5handle_find_detector
               * 2.7.20 cbf_h5handle_require_detector
               * 2.7.21 cbf_h5handle_get_goniometer
               * 2.7.22 cbf_h5handle_set_goniometer
               * 2.7.23 cbf_h5handle_require_goniometer
               * 2.7.24 cbf_h5handle_get_monochromator
               * 2.7.25 cbf_h5handle_set_monochromator
               * 2.7.26 cbf_h5handle_require_monochromator
               * 2.7.27 cbf_h5handle_get_source
               * 2.7.28 cbf_h5handle_set_source
               * 2.7.29 cbf_h5handle_require_source
               * 2.7.30 cbf_free_h5handle
               * 2.7.31 cbf_create_h5handle3
               * 2.7.32 cbf_write_cbf_h5file
               * 2.7.33 cbf_write_cbf2nx
               * 2.7.34 cbf_write_minicbf_h5file
               * 2.7.35 cbf_write_nx2cbf
               * 2.7.36 cbf_config_create
               * 2.7.37 cbf_config_parse
               * 2.7.38 cbf_config_free
               * 2.7.39 cbf_config_strerror
     * 3. File format
          * 3.1 General description
          * 3.2 Format of the binary sections
               * 3.2.1 Format of imgCIF binary sections
               * 3.2.2 Format of CBF binary sections
          * 3.3 Compression schemes
               * 3.3.1 Canonical-code compression
               * 3.3.2 CCP4-style compression
               * 3.3.3 Byte_offset compression
               * 3.3.4 Nibble_offset compression
          * 3.4 Access to CBFlib compressions from HDF5
     * 4. Installation
     * 5. Example programs

  1. Introduction

   CBFlib (Crystallographic Binary File library) is a library of ANSI-C
   functions providing a simple mechanism for accessing Crystallographic
   Binary Files (CBF files) and Image-supporting CIF (imgCIF) files. The
   CBFlib API is loosely based on the CIFPARSE API for mmCIF files. Like
   CIFPARSE, CBFlib does not perform any semantic integrity checks; rather it
   simply provides functions to create, read, modify and write CBF binary
   data files and imgCIF ASCII data files.

   Starting with version 0.7.7, an envolving FCBlib (Fortran Crystallographic
   Binary library) has been added. As of this release it includes code for
   reading byte-offset and packed compression image files created by CBFlib.

  2. Function descriptions

    2.1 General description

   Almost all of the CBFlib functions receive a value of type cbf_handle (a
   CBF handle) as the first argument. Several of the high-level CBFlib
   functions dealing with geometry receive a value of type cbf_goniometer (a
   handle for a CBF goniometer object) or cbf_detector (a handle for a CBF
   detector object).

   All functions return an integer equal to 0 for success or an error code
   for failure.

    2.1.1 CBF handles

   CBFlib permits a program to use multiple CBF objects simultaneously. To
   identify the CBF object on which a function will operate, CBFlib uses a
   value of type cbf_handle.

   All functions in the library except cbf_make_handle expect a value of type
   cbf_handle as the first argument.

   The function cbf_make_handle creates and initializes a new CBF handle.

   The function cbf_free_handle destroys a handle and frees all memory
   associated with the corresponding CBF object.

    2.1.2 CBF goniometer handles

   To represent the goniometer used to orient a sample, CBFlib uses a value
   of type cbf_goniometer.

   A goniometer object is created and initialized from a CBF object using the
   function cbf_construct_goniometer.

   The function cbf_free_goniometer destroys a goniometer handle and frees
   all memory associated with the corresponding object.

    2.1.3 CBF detector handles

   To represent a detector surface mounted on a positioning system, CBFlib
   uses a value of type cbf_detector.

   A goniometer object is created and initialized from a CBF object using one
   of the functions cbf_construct_detector, cbf_construct_reference_detector
   or cbf_require_reference_detector.

   The function cbf_free_detector destroys a detector handle and frees all
   memory associated with the corresponding object.

    2.1.4 CBF positioner handles

   To represent an arbitrary positioning system designated by the terminal
   axis, CBFlib uses a value of type cbf_positioner.

   A positioner object is created and initialized from a CBF object using one
   of the functions cbf_construct_positioner,
   cbf_construct_reference_positioner or cbf_require_reference_positioner.

   The function cbf_free_positioner destroys a positioner handle and frees
   all memory associated with the corresponding object.

    2.1.5 Return values

   All of the CBFlib functions return 0 on success and an error code on
   failure. The error codes are:

  CBF_FORMAT           The file format is invalid                                
  CBF_ALLOC            Memory allocation failed                                  
  CBF_ARGUMENT         Invalid function argument                                 
  CBF_ASCII            The value is ASCII (not binary)                           
  CBF_BINARY           The value is binary (not ASCII)                           
  CBF_BITCOUNT         The expected number of bits does                          
                     not match the actual number written                         
  CBF_ENDOFDATA        The end of the data was reached                           
                     before the end of the array                                 
  CBF_FILECLOSE        File close error                                          
  CBF_FILEOPEN         File open error                                           
  CBF_FILEREAD         File read error                                           
  CBF_FILESEEK         File seek error                                           
  CBF_FILETELL         File tell error                                           
  CBF_FILEWRITE        File write error                                          
  CBF_IDENTICAL        A data block with the new name                            
                     already exists                                              
  CBF_NOTFOUND         The data block, category, column or                       
                     row does not exist                                          
  CBF_OVERFLOW         The number read cannot fit into the                       
                     destination argument. The destination has                   
                     been set to the nearest value.                              
  CBF_UNDEFINED        The requested number is not defined (e.g. 0/0; new for    
                     version 0.7).                                               
  CBF_NOTIMPLEMENTED   The requested functionality is not yet implemented (New   
                     for version 0.7).                                           

   If more than one error has occurred, the error code is the logical OR of
   the individual error codes.

    2.2 Reading and writing files containing binary sections

    2.2.1 Reading binary sections

   The current version of CBFlib only decompresses a binary section from disk
   when requested by the program.

   When a file containing one or more binary sections is read, CBFlib saves
   the file pointer and the position of the binary section within the file
   and then jumps past the binary section. When the program attempts to
   access the binary data, CBFlib sets the file position back to the start of
   the binary section and then reads the data.

   For this scheme to work:

   1. The file must be a random-access file opened in binary mode (fopen ( ,"
   rb")).
   2. The program must not close the file. CBFlib will close the file using
   fclose ( ) when it is no longer needed.

   At present, this also means that a program cant read a file and then write
   back to the same file. This restriction will be eliminated in a future
   version.

   When reading an imgCIF vs a CBF, the difference is detected automatically.

    2.2.2 Writing binary sections

   When a program passes CBFlib a binary value, the data is compressed to a
   temporary file. If the CBF object is subsequently written to a file, the
   data is simply copied from the temporary file to the output file.

   The output file can be of any type. If the program indicates to CBFlib
   that the file is a random-access and readable, CBFlib will conserve disk
   space by closing the temporary file and using the output file as the
   location at which the binary value is stored.

   For this option to work:

   1. The file must be a random-access file opened in binary update mode
   (fopen ( , "w+b")).
   2. The program must not close the file. CBFlib will close the file using
   fclose ( ) when it is no longer needed.

   If this option is not used:

   1. CBFlib will continue using the temporary file.
   2. CBFlib will not close the file. This is the responsibility of the main
   program.

    2.2.3 Summary of reading and writing files containing binary sections

   1. Open disk files to read using the mode "rb".
   2. If possible, open disk files to write using the mode "w+b" and tell
   CBFlib that it can use the file as a buffer.
   3. Do not close any files read by CBFlib or written by CBFlib with
   buffering turned on.
   4. Do not attempt to read from a file, then write to the same file.

    2.2.4 Ordering of array indices

   There are two major conventions in the ordering of array indices:
     * fs: Fast to slow. The first array index (the one numbered "1") is the
       one for which the values of that index change "fastest". That is, as
       we move forward in memory, the value of this index changes more
       rapidly than any other.
     * sf: Slow to fast. The first array index (the one numbered "1") is the
       one for which the values of that index change "slowest". That is as we
       move forward in memory, the value of this index changes more slowly
       than any other.

   During the development of CBFlib, both conventions have been used. In
   order to avoid confusion, the functions for which array indices are used
   are available in three forms: a default version which may used either one
   convention or the other, a form in which the name of the function has an
   "_fs" suffix for the fast to slow convention and a form in which the name
   of the function has a "_sf" suffix for the slow to fast convention.
   Designers of applications are advised to use one of the two suffix
   conventions. There is no burden on performance for using one convention or
   the other. The differences are resolved at compile time by use of
   preprocessor macros.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

    2.3 Low-level function prototypes

    2.3.1 cbf_make_handle

   PROTOTYPE

   #include "cbf.h"

   int cbf_make_handle (cbf_handle *handle);

   DESCRIPTION

   cbf_make_handle creates and initializes a new internal CBF object. All
   other CBFlib functions operating on this object receive the CBF handle as
   the first argument.

   ARGUMENTS

     handle   Pointer to a CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.2 cbf_free_handle

     ----------------------------------------------------------------------

    2.3.2 cbf_free_handle

   PROTOTYPE

   #include "cbf.h"

   int cbf_free_handle (cbf_handle handle);

   DESCRIPTION

   cbf_free_handle destroys the CBF object specified by the handle and frees
   all associated memory.

   ARGUMENTS

     handle   CBF handle to free. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.1 cbf_make_handle

     ----------------------------------------------------------------------

    2.3.3 cbf_read_file, cbf_read_widefile

   PROTOTYPE

   #include "cbf.h"

   int cbf_read_file (cbf_handle handle, FILE *file, int flags);
   int cbf_read_widefile (cbf_handle handle, FILE *file, int flags);

   DESCRIPTION

   cbf_read_file reads the CBF or CIF file file into the CBF object specified
   by handle, using the CIF 1.0 convention of 80 character lines.
   cbf_read_widefile reads the CBF or CIF file file into the CBF object
   specified by handle, using the CIF 1.1 convention of 2048 character lines.
   A warning is issued to stderr for ascii lines over the limit. No test is
   performed on binary sections.

   Validation is performed in three ways levels: during the lexical scan,
   during the parse, and, if a dictionary was converted, against the value
   types, value enumerations, categories and parent-child relationships
   specified in the dictionary.

   flags controls the interpretation of binary section headers, the parsing
   of brackets constructs and the parsing of treble-quoted strings.

     MSG_DIGEST:               Instructs CBFlib to check that the digest of   
                             the binary section matches any header digest     
                             value. If the digests do not match, the call     
                             will return CBF_FORMAT. This evaluation and      
                             comparison is delayed (a "lazy" evaluation) to   
                             ensure maximal processing efficiency. If an      
                             immediately evaluation is required, see          
                             MSG_DIGESTNOW, below.                            
     MSG_DIGESTNOW:            Instructs CBFlib to check that the digest of   
                             the binary section matches any header digeste    
                             value. If the digests do not match, the call     
                             will return CBF_FORMAT. This evaluation and      
                             comparison is performed during initial parsing   
                             of the section to ensure timely error reporting  
                             at the expense of processing efficiency. If a    
                             more efficient delayed ("lazy") evaluation is    
                             required, see MSG_DIGEST, above.                 
     MSG_DIGESTWARN:           Instructs CBFlib to check that the digest of   
                             the binary section matches any header digeste    
                             value. If the digests do not match, a warning    
                             message will be sent to stderr, but processing   
                             will attempt to continue. This evaluation and    
                             comparison is first performed during initial     
                             parsing of the section to ensure timely error    
                             reporting at the expense of processing           
                             efficiency. An mismatch of the message digest    
                             usually indicates a serious error, but it is     
                             sometimes worth continuing processing to try to  
                             isolate the cause of the error. Use this option  
                             with caution.                                    
     MSG_NODIGEST:             Do not check the digest (default).             
     PARSE_BRACKETS:           Accept DDLm bracket-delimited                  
                             [item,item,...item] or {item,item,...item} or    
                             (item,item,...item) constructs as valid,         
                             stripping non-quoted embedded whitespace and     
                             comments. These constructs may span multiple     
                             lines.                                           
     PARSE_LIBERAL_BRACKETS:   Accept DDLm bracket-delimited                  
                             [item,item,...item] or {item,item,...item} or    
                             (item,item,...item) constructs as valid,         
                             stripping embedded non-quoted, non-separating    
                             whitespace and comments. These constructs may    
                             span multiple lines. In this case, whitespace    
                             may be used as an alternative to the comma.      
     PARSE_TRIPLE_QUOTES:      Accept DDLm triple-quoted                      
                             """item,item,...item""" or                       
                             '''item,item,...item''' constructs as valid,     
                             stripping embedded whitespace and comments.      
                             These constructs may span multiple lines. If     
                             this flag is set, then ''' will not be           
                             interpreted as a quoted apoptrophe and """ will  
                             not be interpreted as a quoted double quote mark 
                             and                                              
     PARSE_NOBRACKETS:         Do not accept DDLm bracket-delimited           
                             [item,item,...item] or {item,item,...item} or    
                             (item,item,...item) constructs as valid,         
                             stripping non-quoted embedded whitespace and     
                             comments. These constructs may span multiple     
                             lines.                                           
     PARSE_NOTRIPLE_QUOTES:    No not accept DDLm triple-quoted               
                             """item,item,...item""" or                       
                             '''item,item,...item''' constructs as valid,     
                             stripping embedded whitespace and comments.      
                             These constructs may span multiple lines. If     
                             this flag is set, then ''' will be interpreted   
                             as a quoted apostrophe and """ will be           
                             interpreted as a quoted double quote mark.       

   CBFlib defers reading binary sections as long as possible. In the current
   version of CBFlib, this means that:

   1. The file must be a random-access file opened in binary mode (fopen ( ,
   "rb")).
   2. The program must not close the file. CBFlib will close the file using
   fclose ( ) when it is no longer needed.

   These restrictions may change in a future release.

   ARGUMENTS

     handle    CBF handle.                                         
     file      Pointer to a file descriptor.                       
     headers   Controls interprestation of binary section headers. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.4 cbf_write_file

     ----------------------------------------------------------------------

    2.3.4 cbf_write_file

   PROTOTYPE

   #include "cbf.h"

   int cbf_write_file (cbf_handle handle, FILE *file, int readable, int
   ciforcbf, int flags, int encoding);
   int cbf_write_widefile (cbf_handle handle, FILE *file, int readable, int
   ciforcbf, int flags, int encoding);

   DESCRIPTION

   cbf_write_file writes the CBF object specified by handle into the file
   file, following CIF 1.0 conventions of 80 character lines.
   cbf_write_widefile writes the CBF object specified by handle into the file
   file, following CIF 1.1 conventions of 2048 character lines. A warning is
   issued to stderr for ascii lines over the limit, and an attempt is made to
   fold lines to fit. No test is performed on binary sections.

   If a dictionary has been provided, aliases will be applied on output.

   Unlike cbf_read_file, the file does not have to be random-access.

   If the file is random-access and readable, readable can be set to non-0 to
   indicate to CBFlib that the file can be used as a buffer to conserve disk
   space. If the file is not random-access or not readable, readable must be
   0.

   If readable is non-0, CBFlib will close the file when it is no longer
   required, otherwise this is the responsibility of the program.

   ciforcbf selects the format in which the binary sections are written:

     CIF   Write an imgCIF file.       
     CBF   Write a CBF file (default). 

   flags selects the type of header used in CBF binary sections, selects
   whether message digests are generated, and controls the style of output.
   The value of flags can be a logical OR of any of:

     MIME_HEADERS             Use MIME-type headers (default).                
     MIME_NOHEADERS           Use a simple ASCII headers.                     
     MSG_DIGEST               Generate message digests for binary data        
                            validation.                                       
     MSG_NODIGEST             Do not generate message digests (default).      
     PARSE_BRACKETS           Do not convert bracketed strings to text fields 
                            (default).                                        
     PARSE_LIBERAL_BRACKETS   Do not convert bracketed strings to text fields 
                            (default).                                        
     PARSE_NOBRACKETS         Convert bracketed strings to text fields        
                            (default).                                        
     PARSE_TRIPLE_QUOTES      Do not convert triple-quoted strings to text    
                            fields (default).                                 
     PARSE_NOTRIPLE_QUOTES    Convert triple-quoted strings to text fields    
                            (default).                                        
     PAD_1K                   Pad binary sections with 1023 nulls.            
     PAD_2K                   Pad binary sections with 2047 nulls.            
     PAD_4K                   Pad binary sections with 4095 nulls.            

   Note that on output, the types "prns&, "brcs" and "bkts" will be converted
   to "text" fields if PARSE_NOBRACKETS has been set flags, and that the
   types "tsqs" and "tdqs" will be converted to "text" fields if the flag
   PARSE_NOTRIPLE_QUOTES has been set in the flags. It is an error to set
   PARSE_NOBRACKETS and to set either PARSE_BRACKETS or
   PARSE_LIBERAL_BRACKETS. It is an error to set both PARSE_NOTRIPLE_QUOTES
   and PARSE_TRIPLE_QUOTES.

   encoding selects the type of encoding used for binary sections and the
   type of line-termination in imgCIF files. The value can be a logical OR of
   any of:

     ENC_BASE64     Use BASE64 encoding (default).                            
     ENC_QP         Use QUOTED-PRINTABLE encoding.                            
     ENC_BASE8      Use BASE8 (octal) encoding.                               
     ENC_BASE10     Use BASE10 (decimal) encoding.                            
     ENC_BASE16     Use BASE16 (hexadecimal) encoding.                        
     ENC_FORWARD    For BASE8, BASE10 or BASE16 encoding, map bytes to words  
                  forward (1234) (default on little-endian machines).         
     ENC_BACKWARD   Map bytes to words backward (4321) (default on big-endian 
                  machines).                                                  
     ENC_CRTERM     Terminate lines with CR.                                  
     ENC_LFTERM     Terminate lines with LF (default).                        

   ARGUMENTS

     handle     CBF handle.                                                   
     file       Pointer to a file descriptor.                                 
     readable   If non-0: this file is random-access and readable and can be  
              used as a buffer.                                               
     ciforcbf   Selects the format in which the binary sections are written   
              (CIF/CBF).                                                      
     headers    Selects the type of header in CBF binary sections and message 
              digest generation.                                              
     encoding   Selects the type of encoding used for binary sections and the 
              type of line-termination in imgCIF files.                       

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.3 cbf_read_file

     ----------------------------------------------------------------------

    2.3.5 cbf_new_datablock, cbf_new_saveframe

   PROTOTYPE

   #include "cbf.h"

   int cbf_new_datablock (cbf_handle handle, const char *datablockname);
   int cbf_new_saveframe (cbf_handle handle, const char *saveframename);

   DESCRIPTION

   cbf_new_datablock creates a new data block with name datablockname and
   makes it the current data block. cbf_new_saveframe creates a new save
   frame with name saveframename within the current data block and makes the
   new save frame the current save frame.

   If a data block or save frame with this name already exists, the existing
   data block or save frame becomes the current data block or save frame.

   ARGUMENTS

     handle          CBF handle.                     
     datablockname   The name of the new data block. 
     saveframename   The name of the new save frame. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.7 cbf_new_category
   2.3.8 cbf_force_new_category
   2.3.9 cbf_new_column
   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.12 cbf_set_datablockname, cbf_set_saveframename
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe

   PROTOTYPE

   #include "cbf.h"

   int cbf_force_new_datablock (cbf_handle handle, const char
   *datablockname);
   int cbf_force_new_saveframe (cbf_handle handle, const char
   *saveframename);

   DESCRIPTION

   cbf_force_new_datablock creates a new data block with name datablockname
   and makes it the current data block. Duplicate data block names are
   allowed. cbf_force_new_saveframe creates a new savew frame with name
   saveframename and makes it the current save frame. Duplicate save frame
   names are allowed.

   Even if a save frame with this name already exists, a new save frame is
   created and becomes the current save frame.

   ARGUMENTS

     handle          CBF handle.                     
     datablockname   The name of the new data block. 
     saveframename   The name of the new save frame. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.7 cbf_new_category
   2.3.8 cbf_force_new_category
   2.3.9 cbf_new_column
   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.12 cbf_set_datablockname, cbf_set_saveframename
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.7 cbf_new_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_new_category (cbf_handle handle, const char *categoryname);

   DESCRIPTION

   cbf_new_category creates a new category in the current data block with
   name categoryname and makes it the current category.

   If a category with this name already exists, the existing category becomes
   the current category.

   ARGUMENTS

     handle         CBF handle.                   
     categoryname   The name of the new category. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.8 cbf_force_new_category
   2.3.9 cbf_new_column
   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.18 cbf_remove_category
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.8 cbf_force_new_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_force_new_category (cbf_handle handle, const char *categoryname);

   DESCRIPTION

   cbf_force_new_category creates a new category in the current data block
   with name categoryname and makes it the current category. Duplicate
   category names are allowed.

   Even if a category with this name already exists, a new category of the
   same name is created and becomes the current category. The allows for the
   creation of unlooped tag/value lists drawn from the same category.

   ARGUMENTS

     handle         CBF handle.                   
     categoryname   The name of the new category. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.7 cbf_new_category
   2.3.9 cbf_new_column
   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.18 cbf_remove_category
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.9 cbf_new_column

   PROTOTYPE

   #include "cbf.h"

   int cbf_new_column (cbf_handle handle, const char *columnname);

   DESCRIPTION

   cbf_new_column creates a new column in the current category with name
   columnname and makes it the current column.

   If a column with this name already exists, the existing column becomes the
   current category.

   ARGUMENTS

     handle       CBF handle.                 
     columnname   The name of the new column. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.7 cbf_new_category
   2.3.8 cbf_force_new_category
   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.19 cbf_remove_column
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.10 cbf_new_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_new_row (cbf_handle handle);

   DESCRIPTION

   cbf_new_row adds a new row to the current category and makes it the
   current row.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.7 cbf_new_category
   2.3.8 cbf_force_new_category
   2.3.9 cbf_new_column
   2.3.11 cbf_insert_row
   2.3.12 cbf_delete_row
   2.3.20 cbf_remove_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.11 cbf_insert_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_insert_row (cbf_handle handle, unsigned int rownumber);

   DESCRIPTION

   cbf_insert_row adds a new row to the current category. The new row is
   inserted as row rownumber and existing rows starting from rownumber are
   moved up by 1. The new row becomes the current row.

   If the category has fewer than rownumber rows, the function returns
   CBF_NOTFOUND.

   The row numbers start from 0.

   ARGUMENTS

     handle      CBF handle.                    
     rownumber   The row number of the new row. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.7 cbf_new_category
   2.3.8 cbf_force_new_category
   2.3.9 cbf_new_column
   2.3.10 cbf_new_row
   2.3.12 cbf_delete_row
   2.3.20 cbf_remove_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.12 cbf_delete_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_delete_row (cbf_handle handle, unsigned int rownumber);

   DESCRIPTION

   cbf_delete_row deletes a row from the current category. Rows starting from
   rownumber +1 are moved down by 1. If the current row was higher than
   rownumber, or if the current row is the last row, it will also move down
   by 1.

   The row numbers start from 0.

   ARGUMENTS

     handle      CBF handle.                      
     rownumber   The number of the row to delete. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.18 cbf_remove_category
   2.3.19 cbf_remove_column
   2.3.20 cbf_remove_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.13 cbf_set_datablockname, cbf_set_saveframename

   PROTOTYPE

   #include "cbf.h"

   int cbf_set_datablockname (cbf_handle handle, const char *datablockname);
   int cbf_set_saveframename (cbf_handle handle, const char *saveframename);

   DESCRIPTION

   cbf_set_datablockname changes the name of the current data block to
   datablockname. cbf_set_saveframename changes the name of the current save
   frame to saveframename.

   If a data block or save frame with this name already exists (comparison is
   case-insensitive), the function returns CBF_IDENTICAL.

   ARGUMENTS

     handle          CBF handle.              
     datablockname   The new data block name. 
     datablockname   The new save frame name. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.14 cbf_reset_datablocks
   2.3.15 cbf_reset_datablock, cbf_reset_saveframe
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.42 cbf_datablock_name

     ----------------------------------------------------------------------

    2.3.14 cbf_reset_datablocks

   PROTOTYPE

   #include "cbf.h"

   int cbf_reset_datablocks (cbf_handle handle);

   DESCRIPTION

   cbf_reset_datablocks deletes all categories from all data blocks.

   The current data block does not change.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.15 cbf_reset_datablock, cbf_reset_saveframe
   2.3.18 cbf_remove_category

     ----------------------------------------------------------------------

    2.3.15 cbf_reset_datablock, cbf_reset_datablock

   PROTOTYPE

   #include "cbf.h"

   int cbf_reset_datablock (cbf_handle handle);
   int cbf_reset_saveframe (cbf_handle handle);

   DESCRIPTION

   cbf_reset_datablock deletes all categories from the current data block.
   cbf_reset_saveframe deletes all categories from the current save frame.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.14 cbf_reset_datablocks
   2.3.18 cbf_remove_category

     ----------------------------------------------------------------------

    2.3.16 cbf_reset_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_reset_category (cbf_handle handle);

   DESCRIPTION

   cbf_reset_category deletes all columns and rows from current category.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.16 cbf_reset_category
   2.3.19 cbf_remove_column
   2.3.20 cbf_remove_row

     ----------------------------------------------------------------------

    2.3.17 cbf_remove_datablock, cbf_remove_saveframe

   PROTOTYPE

   #include "cbf.h"

   int cbf_remove_datablock (cbf_handle handle);
   int cbf_remove_saveframe (cbf_handle handle);

   DESCRIPTION

   cbf_remove_datablock deletes the current data block. cbf_remove_saveframe
   deletes the current save frame.

   The current data block becomes undefined.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.5 cbf_new_datablock, cbf_new_saveframe
   2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
   2.3.18 cbf_remove_category
   2.3.19 cbf_remove_column
   2.3.20 cbf_remove_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.18 cbf_remove_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_remove_category (cbf_handle handle);

   DESCRIPTION

   cbf_remove_category deletes the current category.

   The current category becomes undefined.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.7 cbf_new_category
   2.3.8 cbf_force_new_category
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.19 cbf_remove_column
   2.3.20 cbf_remove_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.19 cbf_remove_column

   PROTOTYPE

   #include "cbf.h"

   int cbf_remove_column (cbf_handle handle);

   DESCRIPTION

   cbf_remove_column deletes the current column.

   The current column becomes undefined.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.9 cbf_new_column
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.18 cbf_remove_category
   2.3.20 cbf_remove_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.20 cbf_remove_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_remove_row (cbf_handle handle);

   DESCRIPTION

   cbf_remove_row deletes the current row in the current category.

   If the current row was the last row, it will move down by 1, otherwise, it
   will remain the same.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.10 cbf_new_row
   2.3.11 cbf_insert_row
   2.3.17 cbf_remove_datablock, cbf_remove_saveframe
   2.3.18 cbf_remove_category
   2.3.19 cbf_remove_column
   2.3.12 cbf_delete_row
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.21 cbf_rewind_datablock

   PROTOTYPE

   #include "cbf.h"

   int cbf_rewind_datablock (cbf_handle handle);

   DESCRIPTION

   cbf_rewind_datablock makes the first data block the current data block.

   If there are no data blocks, the function returns CBF_NOTFOUND.

   The current category becomes undefined.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
   2.3.19 cbf_rewind_column
   2.3.24 cbf_rewind_row
   2.3.25 cbf_next_datablock

     ----------------------------------------------------------------------

    2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem

   PROTOTYPE

   #include "cbf.h"

   int cbf_rewind_category (cbf_handle handle);
   int cbf_rewind_saveframe (cbf_handle handle);
   int cbf_rewind_blockitem (cbf_handle handle, CBF_NODETYPE * type);

   DESCRIPTION

   cbf_rewind_category makes the first category in the current data block the
   current category. cbf_rewind_saveframe makes the first saveframe in the
   current data block the current saveframe. cbf_rewind_blockitem makes the
   first blockitem (category or saveframe) in the current data block the
   current blockitem. The type of the blockitem (CBF_CATEGORY or
   CBF_SAVEFRAME) is returned in type.

   If there are no categories, saveframes or blockitems the function returns
   CBF_NOTFOUND.

   The current column and row become undefined.

   ARGUMENTS

     handle   CBF handle. 
     type     CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.21 cbf_rewind_datablock
   2.3.19 cbf_rewind_column
   2.3.24 cbf_rewind_row
   2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem

     ----------------------------------------------------------------------

    2.3.23 cbf_rewind_column

   PROTOTYPE

   #include "cbf.h"

   int cbf_rewind_column (cbf_handle handle);

   DESCRIPTION

   cbf_rewind_column makes the first column in the current category the
   current column.

   If there are no columns, the function returns CBF_NOTFOUND.

   The current row is not affected.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.21 cbf_rewind_datablock
   2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
   2.3.24 cbf_rewind_row
   2.3.27 cbf_next_column

     ----------------------------------------------------------------------

    2.3.24 cbf_rewind_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_rewind_row (cbf_handle handle);

   DESCRIPTION

   cbf_rewind_row makes the first row in the current category the current
   row.

   If there are no rows, the function returns CBF_NOTFOUND.

   The current column is not affected.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.21 cbf_rewind_datablock
   2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
   2.3.19 cbf_rewind_column
   2.3.28 cbf_next_row

     ----------------------------------------------------------------------

    2.3.25 cbf_next_datablock

   PROTOTYPE

   #include "cbf.h"

   int cbf_next_datablock (cbf_handle handle);

   DESCRIPTION

   cbf_next_datablock makes the data block following the current data block
   the current data block.

   If there are no more data blocks, the function returns CBF_NOTFOUND.

   The current category becomes undefined.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.21 cbf_rewind_datablock
   2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
   2.3.27 cbf_next_column
   2.3.28 cbf_next_row

     ----------------------------------------------------------------------

    2.3.26 cbf_next_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_next_category (cbf_handle handle);

   DESCRIPTION

   cbf_next_category makes the category following the current category in the
   current data block the current category.

   If there are no more categories, the function returns CBF_NOTFOUND.

   The current column and row become undefined.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
   2.3.25 cbf_next_datablock
   2.3.27 cbf_next_column
   2.3.27 cbf_next_row

     ----------------------------------------------------------------------

    2.3.27 cbf_next_column

   PROTOTYPE

   #include "cbf.h"

   int cbf_next_column (cbf_handle handle);

   DESCRIPTION

   cbf_next_column makes the column following the current column in the
   current category the current column.

   If there are no more columns, the function returns CBF_NOTFOUND.

   The current row is not affected.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.19 cbf_rewind_column
   2.3.25 cbf_next_datablock
   2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
   2.3.28 cbf_next_row

     ----------------------------------------------------------------------

    2.3.28 cbf_next_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_next_row (cbf_handle handle);

   DESCRIPTION

   cbf_next_row makes the row following the current row in the current
   category the current row.

   If there are no more rows, the function returns CBF_NOTFOUND.

   The current column is not affected.

   ARGUMENTS

     handle   CBF handle. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.24 cbf_rewind_row
   2.3.25 cbf_next_datablock
   2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
   2.3.27 cbf_next_column

     ----------------------------------------------------------------------

    2.3.29 cbf_find_datablock

   PROTOTYPE

   #include "cbf.h"

   int cbf_find_datablock (cbf_handle handle, const char *datablockname);

   DESCRIPTION

   cbf_find_datablock makes the data block with name datablockname the
   current data block.

   The comparison is case-insensitive.

   If the data block does not exist, the function returns CBF_NOTFOUND.

   The current category becomes undefined.

   ARGUMENTS

     handle          CBF handle.                         
     datablockname   The name of the data block to find. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.21 cbf_rewind_datablock
   2.3.25 cbf_next_datablock
   2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
   2.3.31 cbf_find_column
   2.3.32 cbf_find_row
   2.3.42 cbf_datablock_name
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.30 cbf_find_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_find_category (cbf_handle handle, const char *categoryname);

   DESCRIPTION

   cbf_find_category makes the category in the current data block with name
   categoryname the current category.

   The comparison is case-insensitive.

   If the category does not exist, the function returns CBF_NOTFOUND.

   The current column and row become undefined.

   ARGUMENTS

     handle         CBF handle.                       
     categoryname   The name of the category to find. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
   2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
   2.3.29 cbf_find_datablock
   2.3.31 cbf_find_column
   2.3.32 cbf_find_row
   2.3.43 cbf_category_name
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.31 cbf_find_column

   PROTOTYPE

   #include "cbf.h"

   int cbf_find_column (cbf_handle handle, const char *columnname);

   DESCRIPTION

   cbf_find_column makes the columns in the current category with name
   columnname the current column.

   The comparison is case-insensitive.

   If the column does not exist, the function returns CBF_NOTFOUND.

   The current row is not affected.

   ARGUMENTS

     handle       CBF handle.                 
     columnname   The name of column to find. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.19 cbf_rewind_column
   2.3.27 cbf_next_column
   2.3.29 cbf_find_datablock
   2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
   2.3.32 cbf_find_row
   2.3.44 cbf_column_name
   2.3.59 cbf_require_datablock
   2.3.60 cbf_require_category
   2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.32 cbf_find_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_find_row (cbf_handle handle, const char *value);

   DESCRIPTION

   cbf_find_row makes the first row in the current column with value value
   the current row.

   The comparison is case-sensitive.

   If a matching row does not exist, the function returns CBF_NOTFOUND.

   The current column is not affected.

   ARGUMENTS

     handle   CBF handle.                   
     value    The value of the row to find. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.24 cbf_rewind_row
   2.3.28 cbf_next_row
   2.3.29 cbf_find_datablock
   2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
   2.3.31 cbf_find_column
   2.3.33 cbf_find_nextrow
   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue

    2.3.33 cbf_find_nextrow

   PROTOTYPE

   #include "cbf.h"

   int cbf_find_nextrow (cbf_handle handle, const char *value);

   DESCRIPTION

   cbf_find_nextrow makes the makes the next row in the current column with
   value value the current row. The search starts from the row following the
   last row found with cbf_find_row or cbf_find_nextrow, or from the current
   row if the current row was defined using any other function.

   The comparison is case-sensitive.

   If no more matching rows exist, the function returns CBF_NOTFOUND.

   The current column is not affected.

   ARGUMENTS

     handle   CBF handle.              
     value    the value to search for. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.24 cbf_rewind_row
   2.3.28 cbf_next_row
   2.3.29 cbf_find_datablock
   2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
   2.3.31 cbf_find_column
   2.3.32 cbf_find_row
   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue

     ----------------------------------------------------------------------

    2.3.34 cbf_count_datablocks

   PROTOTYPE

   #include "cbf.h"

   int cbf_count_datablocks (cbf_handle handle, unsigned int *datablocks);

   DESCRIPTION

   cbf_count_datablocks puts the number of data blocks in *datablocks .

   ARGUMENTS

     handle       CBF handle.                                  
     datablocks   Pointer to the destination data block count. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
   2.3.36 cbf_count_columns
   2.3.37 cbf_count_rows
   2.3.38 cbf_select_datablock

     ----------------------------------------------------------------------

    2.3.35 cbf_count_categories

   PROTOTYPE

   #include "cbf.h"

   int cbf_count_categories (cbf_handle handle, unsigned int *categories);

   DESCRIPTION

   cbf_count_categories puts the number of categories in the current data
   block in *categories.

   ARGUMENTS

     handle       CBF handle.                                
     categories   Pointer to the destination category count. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.34 cbf_count_datablocks
   2.3.36 cbf_count_columns
   2.3.37 cbf_count_rows
   2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem

     ----------------------------------------------------------------------

    2.3.36 cbf_count_columns

   PROTOTYPE

   #include "cbf.h"

   int cbf_count_columns (cbf_handle handle, unsigned int *columns);

   DESCRIPTION

   cbf_count_columns puts the number of columns in the current category in
   *columns.

   ARGUMENTS

     handle    CBF handle.                              
     columns   Pointer to the destination column count. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.34 cbf_count_datablocks
   2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
   2.3.37 cbf_count_rows
   2.3.40 cbf_select_column

     ----------------------------------------------------------------------

    2.3.37 cbf_count_rows

   PROTOTYPE

   #include "cbf.h"

   int cbf_count_rows (cbf_handle handle, unsigned int *rows);

   DESCRIPTION

   cbf_count_rows puts the number of rows in the current category in *rows .

   ARGUMENTS

     handle   CBF handle.                           
     rows     Pointer to the destination row count. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.34 cbf_count_datablocks
   2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
   2.3.36 cbf_count_columns
   2.3.41 cbf_select_row

     ----------------------------------------------------------------------

    2.3.38 cbf_select_datablock

   PROTOTYPE

   #include "cbf.h"

   int cbf_select_datablock (cbf_handle handle, unsigned int datablock);

   DESCRIPTION

   cbf_select_datablock selects data block number datablock as the current
   data block.

   The first data block is number 0.

   If the data block does not exist, the function returns CBF_NOTFOUND.

   ARGUMENTS

     handle      CBF handle.                         
     datablock   Number of the data block to select. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.34 cbf_count_datablocks
   2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
   2.3.40 cbf_select_column
   2.3.41 cbf_select_row

     ----------------------------------------------------------------------

    2.3.39 cbf_select_category

   PROTOTYPE

   #include "cbf.h"

   int cbf_select_category (cbf_handle handle, unsigned int category);

   DESCRIPTION

   cbf_select_category selects category number category in the current data
   block as the current category.

   The first category is number 0.

   The current column and row become undefined.

   If the category does not exist, the function returns CBF_NOTFOUND.

   ARGUMENTS

     handle     CBF handle.                       
     category   Number of the category to select. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
   2.3.38 cbf_select_datablock
   2.3.40 cbf_select_column
   2.3.41 cbf_select_row

     ----------------------------------------------------------------------

    2.3.40 cbf_select_column

   PROTOTYPE

   #include "cbf.h"

   int cbf_select_column (cbf_handle handle, unsigned int column);

   DESCRIPTION

   cbf_select_column selects column number column in the current category as
   the current column.

   The first column is number 0.

   The current row is not affected

   If the column does not exist, the function returns CBF_NOTFOUND.

   ARGUMENTS

     handle   CBF handle.                     
     column   Number of the column to select. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.36 cbf_count_columns
   2.3.38 cbf_select_datablock
   2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
   2.3.41 cbf_select_row

     ----------------------------------------------------------------------

    2.3.41 cbf_select_row

   PROTOTYPE

   #include "cbf.h"

   int cbf_select_row (cbf_handle handle, unsigned int row);

   DESCRIPTION

   cbf_select_row selects row number row in the current category as the
   current row.

   The first row is number 0.

   The current column is not affected

   If the row does not exist, the function returns CBF_NOTFOUND.

   ARGUMENTS

     handle   CBF handle.                  
     row      Number of the row to select. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.37 cbf_count_rows
   2.3.38 cbf_select_datablock
   2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
   2.3.40 cbf_select_column

     ----------------------------------------------------------------------

    2.3.42 cbf_datablock_name

   PROTOTYPE

   #include "cbf.h"

   int cbf_datablock_name (cbf_handle handle, const char **datablockname);

   DESCRIPTION

   cbf_datablock_name sets *datablockname to point to the name of the current
   data block.

   The data block name will be valid as long as the data block exists and has
   not been renamed.

   The name must not be modified by the program in any way.

   ARGUMENTS

     handle          CBF handle.                                         
     datablockname   Pointer to the destination data block name pointer. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.29 cbf_find_datablock

     ----------------------------------------------------------------------

    2.3.43 cbf_category_name

   PROTOTYPE

   #include "cbf.h"

   int cbf_category_name (cbf_handle handle, const char **categoryname);

   DESCRIPTION

   cbf_category_name sets *categoryname to point to the name of the current
   category of the current data block.

   The category name will be valid as long as the category exists.

   The name must not be modified by the program in any way.

   ARGUMENTS

     handle         CBF handle.                                       
     categoryname   Pointer to the destination category name pointer. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem

     ----------------------------------------------------------------------

    2.3.44 cbf_column_name, cbf_set_column_name

   PROTOTYPE

   #include "cbf.h"

   int cbf_column_name (cbf_handle handle, const char **columnname);
   int cbf_set_column_name (cbf_handle handle, const char *newcolumnname)

   DESCRIPTION

   cbf_column_name sets *columnname to point to the name of the current
   column of the current category.

   The column name will be valid as long as the column exists.

   The name must not be modified by the program in any way.

   cbf_set_column_name sets the name of the current column to newcolumnname

   ARGUMENTS

     handle          CBF handle.                                     
     columnname      Pointer to the destination column name pointer. 
     newcolumnname   New column name pointer.                        

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.31 cbf_find_column

     ----------------------------------------------------------------------

    2.3.45 cbf_row_number

   PROTOTYPE

   #include "cbf.h"

   int cbf_row_number (cbf_handle handle, unsigned int *row);

   DESCRIPTION

   cbf_row_number sets *row to the number of the current row of the current
   category.

   ARGUMENTS

     handle   CBF handle.                            
     row      Pointer to the destination row number. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.41 cbf_select_row

     ----------------------------------------------------------------------

    2.3.46 cbf_get_value, cbf_require_value

   PROTOTYPE

   #include "cbf.h"

   int cbf_get_value (cbf_handle handle, const char **value);
   int cbf_require_value (cbf_handle handle, const char **value, const char
   *defaultvalue );

   DESCRIPTION

   cbf_get_value sets *value to point to the ASCII value of the item at the
   current column and row. cbf_require_value sets *value to point to the
   ASCII value of the item at the current column and row, creating the data
   item if necessary and initializing it to a copy of defaultvalue.

   If the value is not ASCII, the function returns CBF_BINARY.

   The value will be valid as long as the item exists and has not been set to
   a new value.

   The value must not be modified by the program in any way.

   ARGUMENTS

     handle         CBF handle.                               
     value          Pointer to the destination value pointer. 
     defaultvalue   Default value character string.           

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.47 cbf_set_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.50 cbf_get_integervalue, cbf_require_integervalue
   2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
   2.3.54 cbf_get_integerarrayparameters,
   cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
   cbf_get_realarrayparameters_wdims
   2.3.55 cbf_get_integerarray, cbf_get_realarray
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.47 cbf_set_value

   PROTOTYPE

   #include "cbf.h"

   int cbf_set_value (cbf_handle handle, const char *value);

   DESCRIPTION

   cbf_set_value sets the item at the current column and row to the ASCII
   value value.

   ARGUMENTS

     handle   CBF handle.  
     value    ASCII value. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.51 cbf_set_integervalue
   2.3.53 cbf_set_doublevalue
   2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
   cbf_set_realarray, cbf_set_realarray_wdims
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.48 cbf_get_typeofvalue

   PROTOTYPE

   #include "cbf.h"

   int cbf_get_typeofvalue (cbf_handle handle, const char **typeofvalue);

   DESCRIPTION

   cbf_get_value sets *typeofvalue to point an ASCII descriptor of the value
   of the item at the current column and row. The strings that may be
   returned are:

     "null" for a null value indicated by a "." or a "?"                   
     "bnry" for a binary value                                             
     "word" for an unquoted string                                         
     "dblq" for a double-quoted string                                     
     "sglq" for a single-quoted string                                     
     "text" for a semicolon-quoted string (multiline text field)           
     "prns" for a parenthesis-bracketed string (multiline text field)      
     "brcs" for a brace-bracketed string (multiline text field)            
     "bkts" for a square-bracket-bracketed string (multiline text field)   
     "tsqs" for a treble-single-quote quoted string (multiline text field) 
     "tdqs" for a treble-double-quote quoted string (multiline text field) 

   Not all types are valid for all type of CIF files. In partcular the types
   "prns", "brcs", "bkts" were introduced with DDLm and are not valid in DDL1
   or DDL2 CIFS. The types "tsqs" and "tdqs" are not formally part of the CIF
   syntax. A field for which no value has been set sets *typeofvalue to NULL
   rather than to the string "null".

   The typeofvalue must not be modified by the program in any way.

   ARGUMENTS

     handle        CBF handle.                                              
     typeofvalue   Pointer to the destination type-of-value string pointer. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.47 cbf_set_value
   2.3.49 cbf_set_typeofvalue
   2.3.50 cbf_get_integervalue, cbf_require_integervalue
   2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
   2.3.54 cbf_get_integerarrayparameters,
   cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
   cbf_get_realarrayparameters_wdims
   2.3.55 cbf_get_integerarray, cbf_get_realarray
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.49 cbf_set_typeofvalue

   PROTOTYPE

   #include "cbf.h"

   int cbf_set_typeofvalue (cbf_handle handle, const char *typeofvalue);

   DESCRIPTION

   cbf_set_typeofvalue sets the type of the item at the current column and
   row to the type specified by the ASCII character string given by
   typeofvalue. The strings that may be used are:

     "null" for a null value indicated by a "." or a "?"                   
     "bnry" for a binary value                                             
     "word" for an unquoted string                                         
     "dblq" for a double-quoted string                                     
     "sglq" for a single-quoted string                                     
     "text" for a semicolon-quoted string (multiline text field)           
     "prns" for a parenthesis-bracketed string (multiline text field)      
     "brcs" for a brace-bracketed string (multiline text field)            
     "bkts" for a square-bracket-bracketed string (multiline text field)   
     "tsqs" for a treble-single-quote quoted string (multiline text field) 
     "tdqs" for a treble-double-quote quoted string (multiline text field) 

   Not all types may be used for all values. Not all types are valid for all
   type of CIF files. In partcular the types "prns", "brcs", "bkts" were
   introduced with DDLm and are not valid in DDL1 or DDL2 CIFS. The types
   "tsqs" and "tdqs" are not formally part of the CIF syntax. No changes may
   be made to the type of binary values. You may not set the type of a string
   that contains a single quote followed by a blank or a tab or which
   contains multiple lines to "sglq". You may not set the type of a string
   that contains a double quote followed by a blank or a tab or which
   contains multiple lines to "dblq".

   ARGUMENTS

     handle        CBF handle.                             
     typeofvalue   ASCII string for desired type of value. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.47 cbf_set_value
   2.3.48 cbf_get_typeofvalue
   2.3.51 cbf_set_integervalue
   2.3.53 cbf_set_doublevalue
   2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
   cbf_set_realarray, cbf_set_realarray_wdims
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.50 cbf_get_integervalue, cbf_require_integervalue

   PROTOTYPE

   #include "cbf.h"

   int cbf_get_integervalue (cbf_handle handle, int *number);
   int cbf_require_integervalue (cbf_handle handle, int *number, int
   defaultvalue);

   DESCRIPTION

   cbf_get_integervalue sets *number to the value of the ASCII item at the
   current column and row interpreted as a decimal integer.
   cbf_require_integervalue sets *number to the value of the ASCII item at
   the current column and row interpreted as a decimal integer, setting it to
   defaultvalue if necessary.

   If the value is not ASCII, the function returns CBF_BINARY.

   ARGUMENTS

     handle         CBF handle.            
     number         pointer to the number. 
     defaultvalue   default number value.  

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue
   2.3.51 cbf_set_integervalue
   2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
   2.3.54 cbf_get_integerarrayparameters,
   cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
   cbf_get_realarrayparameters_wdims
   2.3.55 cbf_get_integerarray, cbf_get_realarray
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.51 cbf_set_integervalue

   PROTOTYPE

   #include "cbf.h"

   int cbf_set_integervalue (cbf_handle handle, int number);

   DESCRIPTION

   cbf_set_integervalue sets the item at the current column and row to the
   integer value number written as a decimal ASCII string.

   ARGUMENTS

     handle   CBF handle.    
     number   Integer value. 

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.47 cbf_set_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.50 cbf_get_integervalue, cbf_require_integervalue
   2.3.51 cbf_set_integervalue
   2.3.53 cbf_set_doublevalue
   2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
   cbf_set_realarray, cbf_set_realarray_wdims
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.52 cbf_get_doublevalue, cbf_require_doublevalue

   PROTOTYPE

   #include "cbf.h"

   int cbf_get_doublevalue (cbf_handle handle, double *number);
   int cbf_require_doublevalue (cbf_handle handle, double *number, double
   defaultvalue);

   DESCRIPTION

   cbf_get_doublevalue sets *number to the value of the ASCII item at the
   current column and row interpreted as a decimal floating-point number.
   cbf_require_doublevalue sets *number to the value of the ASCII item at the
   current column and row interpreted as a decimal floating-point number,
   setting it to defaultvalue if necessary.

   If the value is not ASCII, the function returns CBF_BINARY.

   ARGUMENTS

     handle         CBF handle.                        
     number         Pointer to the destination number. 
     defaultvalue   default number value.              

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.50 cbf_get_integervalue, cbf_require_integervalue
   2.3.53 cbf_set_doublevalue
   2.3.54 cbf_get_integerarrayparameters,
   cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
   cbf_get_realarrayparameters_wdims
   2.3.55 cbf_get_integerarray, cbf_get_realarray
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.53 cbf_set_doublevalue

   PROTOTYPE

   #include "cbf.h"

   int cbf_set_doublevalue (cbf_handle handle, const char *format, double
   number);

   DESCRIPTION

   cbf_set_doublevalue sets the item at the current column and row to the
   floating-point value number written as an ASCII string with the format
   specified by format as appropriate for the printf function.

   ARGUMENTS

     handle   CBF handle.            
     format   Format for the number. 
     number   Floating-point value.  

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.47 cbf_set_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.51 cbf_set_integervalue
   2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
   2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
   cbf_set_realarray, cbf_set_realarray_wdims
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.54 cbf_get_integerarrayparameters,
          cbf_get_integerarrayparameters_wdims,
    cbf_get_integerarrayparameters_wdims_fs,
    cbf_get_integerarrayparameters_wdims_sf,       cbf_get_realarrayparameters,
          cbf_get_realarrayparameters_wdims,
    cbf_get_realarrayparameters_wdims_fs, cbf_get_realarrayparameters_wdims_sf

   PROTOTYPE

   #include "cbf.h"

   int cbf_get_integerarrayparameters (cbf_handle handle, unsigned int
   *compression, int *binary_id, size_t *elsize, int *elsigned, int
   *elunsigned, size_t *elements, int *minelement, int *maxelement);
    
   int cbf_get_integerarrayparameters_wdims (cbf_handle handle, unsigned int
   *compression, int *binary_id, size_t *elsize, int *elsigned, int
   *elunsigned, size_t *elements, int *minelement, int *maxelement, const
   char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
   *padding);
   int cbf_get_integerarrayparameters_wdims_fs (cbf_handle handle, unsigned
   int *compression, int *binary_id, size_t *elsize, int *elsigned, int
   *elunsigned, size_t *elements, int *minelement, int *maxelement, const
   char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
   *padding);
   int cbf_get_integerarrayparameters_wdims_sf (cbf_handle handle, unsigned
   int *compression, int *binary_id, size_t *elsize, int *elsigned, int
   *elunsigned, size_t *elements, int *minelement, int *maxelement, const
   char **byteorder, size_t *dimslow, size_t *dimmid, size_t *dimfast, size_t
   *padding);
    
   int cbf_get_realarrayparameters (cbf_handle handle, unsigned int
   *compression, int *binary_id, size_t *elsize, size_t *elements);
    
   int cbf_get_realarrayparameters_wdims (cbf_handle handle, unsigned int
   *compression, int *binary_id, size_t *elsize, size_t *elements, const char
   **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
   *padding);
   int cbf_get_realarrayparameters_wdims_fs (cbf_handle handle, unsigned int
   *compression, int *binary_id, size_t *elsize, size_t *elements, const char
   **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
   *padding);
   int cbf_get_realarrayparameters_wdims_sf (cbf_handle handle, unsigned int
   *compression, int *binary_id, size_t *elsize, size_t *elements, const char
   **byteorder, size_t *dimslow, size_t *dimmid, size_t *dimfast, size_t
   *padding);

   DESCRIPTION

   cbf_get_integerarrayparameters sets *compression, *binary_id, *elsize,
   *elsigned, *elunsigned, *elements, *minelement and *maxelement to values
   read from the binary value of the item at the current column and row. This
   provides all the arguments needed for a subsequent call to
   cbf_set_integerarray, if a copy of the array is to be made into another
   CIF or CBF. cbf_get_realarrayparameters sets *compression, *binary_id,
   *elsize, *elements to values read from the binary value of the item at the
   current column and row. This provides all the arguments needed for a
   subsequent call to cbf_set_realarray, if a copy of the arry is to be made
   into another CIF or CBF.

   The variants cbf_get_integerarrayparameters_wdims,
   cbf_get_integerarrayparameters_wdims_fs,
   cbf_get_integerarrayparameters_wdims_sf,
   cbf_get_realarrayparameters_wdims, cbf_get_realarrayparameters_wdims_fs,
   cbf_get_realarrayparameters_wdims_sf set **byteorder, *dimfast, *dimmid,
   *dimslow, and *padding as well, providing the additional parameters needed
   for a subsequent call to cbf_set_integerarray_wdims or
   cbf_set_realarray_wdims.

   The value returned in *byteorder is a pointer either to the string
   "little_endian" or to the string "big_endian". This should be the byte
   order of the data, not necessarily of the host machine. No attempt should
   be made to modify this string. At this time only "little_endian" will be
   returned.

   The values returned in *dimfast, *dimmid and *dimslow are the sizes of the
   fastest changing, second fastest changing and third fastest changing
   dimensions of the array, if specified, or zero, if not specified.

   The value returned in *padding is the size of the post-data padding, if
   any and if specified in the data header. The value is given as a count of
   octets.

   If the value is not binary, the function returns CBF_ASCII.

   ARGUMENTS

     handle        CBF handle.                                                
     compression   Compression method used.                                   
     elsize        Size in bytes of each array element.                       
     binary_id     Pointer to the destination integer binary identifier.      
     elsigned      Pointer to an integer. Set to 1 if the elements can be     
                 read as signed integers.                                     
     elunsigned    Pointer to an integer. Set to 1 if the elements can be     
                 read as unsigned integers.                                   
     elements      Pointer to the destination number of elements.             
     minelement    Pointer to the destination smallest element.               
     maxelement    Pointer to the destination largest element.                
     byteorder     Pointer to the destination byte order.                     
     dimfast       Pointer to the destination fastest dimension.              
     dimmid        Pointer to the destination second fastest dimension.       
     dimslow       Pointer to the destination third fastest dimension.        
     padding       Pointer to the destination padding size.                   

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.50 cbf_get_integervalue, cbf_require_integervalue
   2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
   2.3.55 cbf_get_integerarray, cbf_get_realarray
   2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
   cbf_set_realarray, cbf_set_realarray_wdims
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.55 cbf_get_integerarray, cbf_get_realarray

   PROTOTYPE

   #include "cbf.h"

   int cbf_get_integerarray (cbf_handle handle, int *binary_id, void *array,
   size_t elsize, int elsigned, size_t elements, size_t *elements_read);
   int cbf_get_realarray (cbf_handle handle, int *binary_id, void *array,
   size_t elsize, size_t elements, size_t *elements_read);

   DESCRIPTION

   cbf_get_integerarray reads the binary value of the item at the current
   column and row into an integer array. The array consists of elements
   elements of elsize bytes each, starting at array. The elements are signed
   if elsigned is non-0 and unsigned otherwise. *binary_id is set to the
   binary section identifier and *elements_read to the number of elements
   actually read. cbf_get_realarray reads the binary value of the item at the
   current column and row into a real array. The array consists of elements
   elements of elsize bytes each, starting at array. *binary_id is set to the
   binary section identifier and *elements_read to the number of elements
   actually read.

   If any element in the integer binary data cant fit into the destination
   element, the destination is set the nearest possible value.

   If the value is not binary, the function returns CBF_ASCII.

   If the requested number of elements cant be read, the function will read
   as many as it can and then return CBF_ENDOFDATA.

   Currently, the destination array must consist of chars, shorts or ints
   (signed or unsigned). If elsize is not equal to sizeof (char), sizeof
   (short) or sizeof (int), for cbf_get_integerarray, or sizeof(double) or
   sizeof(float), for cbf_get_realarray the function returns CBF_ARGUMENT.

   An additional restriction in the current version of CBFlib is that values
   too large to fit in an int are not correctly decompressed. As an example,
   if the machine with 32-bit ints is reading an array containing a value
   outside the range 0 .. 2^32-1 (unsigned) or -2^31 .. 2^31-1 (signed), the
   array will not be correctly decompressed. This restriction will be removed
   in a future release. For cbf_get_realarray, only IEEE format is supported.
   No conversion to other floating point formats is done at this time.

   ARGUMENTS

     handle          CBF handle.                                              
     binary_id       Pointer to the destination integer binary identifier.    
     array           Pointer to the destination array.                        
     elsize          Size in bytes of each destination array element.         
     elsigned        Set to non-0 if the destination array elements are       
                   signed.                                                    
     elements        The number of elements to read.                          
     elements_read   Pointer to the destination number of elements actually   
                   read.                                                      

   RETURN VALUE

   Returns an error code on failure or 0 for success.
   SEE ALSO

   2.3.46 cbf_get_value, cbf_require_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.50 cbf_get_integervalue, cbf_require_integervalue
   2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
   2.3.54 cbf_get_integerarrayparameters,
   cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
   cbf_get_realarrayparameters_wdims
   2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
   cbf_set_realarray, cbf_set_realarray_wdims
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.56 cbf_set_integerarray,
          cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs,
    cbf_set_integerarray_wdims_sf,
          cbf_set_realarray,
          cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs,
    cbf_set_realarray_wdims_sf

   PROTOTYPE

   #include "cbf.h"

   int cbf_set_integerarray (cbf_handle handle, unsigned int compression, int
   binary_id, void *array, size_t elsize, int elsigned, size_t elements);
    
   int cbf_set_integerarray_wdims (cbf_handle handle, unsigned int
   compression, int binary_id, void *array, size_t elsize, int elsigned,
   size_t elements, const char *byteorder, size_t dimfast, size_t dimmid,
   size_t dimslow, size_t padding);
   int cbf_set_integerarray_wdims_fs (cbf_handle handle, unsigned int
   compression, int binary_id, void *array, size_t elsize, int elsigned,
   size_t elements, const char *byteorder, size_t dimfast, size_t dimmid,
   size_t dimslow, size_t padding);
   int cbf_set_integerarray_wdims_sf (cbf_handle handle, unsigned int
   compression, int binary_id, void *array, size_t elsize, int elsigned,
   size_t elements, const char *byteorder, size_t dimslow, size_t dimmid,
   size_t dimfast, size_t padding);
    
   int cbf_set_realarray (cbf_handle handle, unsigned int compression, int
   binary_id, void *array, size_t elsize, size_t elements);
    
   int cbf_set_realarray_wdims (cbf_handle handle, unsigned int compression,
   int binary_id, void *array, size_t elsize, size_t elements, const char
   *byteorder, size_t dimfast, size_t dimmid, size_t dimslow, size_t
   padding);
   int cbf_set_realarray_wdims_fs (cbf_handle handle, unsigned int
   compression, int binary_id, void *array, size_t elsize, size_t elements,
   const char *byteorder, size_t dimfast, size_t dimmid, size_t dimslow,
   size_t padding);
   int cbf_set_realarray_wdims_sf (cbf_handle handle, unsigned int
   compression, int binary_id, void *array, size_t elsize, size_t elements,
   const char *byteorder, size_t dimslow, size_t dimmid, size_t dimfast,
   size_t padding);

   DESCRIPTION

   cbf_set_integerarray sets the binary value of the item at the current
   column and row to an integer array. The array consists of elements
   elements of elsize bytes each, starting at array. The elements are signed
   if elsigned is non-0 and unsigned otherwise. binary_id is the binary
   section identifier. cbf_set_realarray sets the binary value of the item at
   the current column and row to an integer array. The array consists of
   elements elements of elsize bytes each, starting at array. binary_id is
   the binary section identifier.

   The cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs,
   cbf_set_integerarray_wdims_sf, cbf_set_realarray_wdims,
   cbf_set_realarray_wdims_fs and cbf_set_realarray_wdims_sf variants allow
   the data header values of byteorder, dimfast, dimmid, dimslow and padding
   to be set to the data byte order, the fastest, second fastest and third
   fastest array dimensions and the size in byte of the post data padding to
   be used.

   The array will be compressed using the compression scheme specifed by
   compression. Currently, the available schemes are:

     CBF_CANONICAL       Canonical-code compression (section 3.3.1)           
     CBF_PACKED          CCP4-style packing (section 3.3.2)                   
     CBF_PACKED_V2       CCP4-style packing, version 2 (section 3.3.2)        
     CBF_BYTE_OFFSET     Simple "byte_offset" compression.                    
     CBF_NIBBLE_OFFSET   Simple "nibble_offset" compression.                  
     CBF_NONE            No compression. NOTE: This scheme is by far the      
                       slowest of the four and uses much more disk space. It  
                       is intended for routine use with small arrays only.    
                       With large arrays (like images) it should be used only 
                       for debugging.                                         

   The values compressed are limited to 64 bits. If any element in the array
   is larger than 64 bits, the value compressed is the nearest 64-bit value.

   Currently, the source array must consist of chars, shorts or ints (signed
   or unsigned), for cbf_set_integerarray, or IEEE doubles or floats for
   cbf_set_realarray. If elsize is not equal to sizeof (char), sizeof (short)
   or sizeof (int), the function returns CBF_ARGUMENT.

   ARGUMENTS

     handle        CBF handle.                                           
     compression   Compression method to use.                            
     binary_id     Integer binary identifier.                            
     array         Pointer to the source array.                          
     elsize        Size in bytes of each source array element.           
     elsigned      Set to non-0 if the source array elements are signed. 
                 elements: The number of elements in the array.          

   RETURN VALUE

   Returns an error code on failure or 0 for success.

   SEE ALSO

   2.3.47 cbf_set_value
   2.3.48 cbf_get_typeofvalue
   2.3.49 cbf_set_typeofvalue
   2.3.51 cbf_set_integervalue
   2.3.53 cbf_set_doublevalue
   2.3.54 cbf_get_integerarrayparameters,
   cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
   cbf_get_realarrayparameters_wdims
   2.3.55 cbf_get_integerarray, cbf_get_realarray
   2.3.62 cbf_require_column_value
   2.3.63 cbf_require_column_integervalue
   2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.57 cbf_failnez

   DEFINITION

   #include "cbf.h"

   #define cbf_failnez(f) {int err; err = (f); if (err) return err; }

   DESCRIPTION

   cbf_failnez is a macro used for error propagation throughout CBFlib.
   cbf_failnez executes the function f and saves the returned error value. If
   the error value is non-0, cbf_failnez executes a return with the error
   value as argument. If CBFDEBUG is defined, then a report of the error is
   also printed to the standard error stream, stderr, in the form

   CBFlib error f in "symbol"

   where f is the decimal value of the error and symbol is the symbolic form.

   ARGUMENTS

     f   Integer error value. 

   SEE ALSO

   2.3.58 cbf_onfailnez

     ----------------------------------------------------------------------

    2.3.58 cbf_onfailnez

   DEFINITION

   #include "cbf.h"

   #define cbf_onfailnez(f,c) {int err; err = (f); if (err) {{c; }return err;
   }}

   DESCRIPTION

   cbf_onfailnez is a macro used for error propagation throughout CBFlib.
   cbf_onfailnez executes the function f and saves the returned error value.
   If the error value is non-0, cbf_failnez executes first the statement c
   and then a return with the error value as argument. If CBFDEBUG is
   defined, then a report of the error is also printed to the standard error
   stream, stderr, in the form

   CBFlib error f in "symbol"

   where f is the decimal value of the error and symbol is the symbolic form.

   ARGUMENTS

     f   integer function to execute.     
     c   statement to execute on failure. 

   SEE ALSO
   * 2.3.57 cbf_failnez

     ----------------------------------------------------------------------

    2.3.59 cbf_require_datablock

     PROTOTYPE

     #include "cbf.h"

     int cbf_require_datablock (cbf_handle handle, const char
     *datablockname);

     DESCRIPTION

     cbf_require_datablock makes the data block with name datablockname the
     current data block, if it exists, or creates it if it does not.

     The comparison is case-insensitive.

     The current category becomes undefined.

     ARGUMENTS

       handle          CBF handle.                                   
       datablockname   The name of the data block to find or create. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.3.21 cbf_rewind_datablock
     2.3.25 cbf_next_datablock
     2.3.29 cbf_find_datablock
     2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
     2.3.31 cbf_find_column
     2.3.32 cbf_find_row
     2.3.42 cbf_datablock_name
     2.3.60 cbf_require_category
     2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.60 cbf_require_category

     PROTOTYPE

     #include "cbf.h"

     int cbf_require_category (cbf_handle handle, const char *categoryname);

     DESCRIPTION

     cbf_rewuire_category makes the category in the current data block with
     name categoryname the current category, if it exists, or creates the
     catagory if it does not exist.

     The comparison is case-insensitive.

     The current column and row become undefined.

     ARGUMENTS

       handle         CBF handle.                       
       categoryname   The name of the category to find. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
     2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
     2.3.29 cbf_find_datablock
     2.3.31 cbf_find_column
     2.3.32 cbf_find_row
     2.3.43 cbf_category_name
     2.3.59 cbf_require_datablock
     2.3.61 cbf_require_column

     ----------------------------------------------------------------------

    2.3.61 cbf_require_column

     PROTOTYPE

     #include "cbf.h"

     int cbf_require_column (cbf_handle handle, const char *columnname);

     DESCRIPTION

     cbf_require_column makes the columns in the current category with name
     columnname the current column, if it exists, or creates it if it does
     not.

     The comparison is case-insensitive.

     The current row is not affected.

     ARGUMENTS

       handle       CBF handle.                 
       columnname   The name of column to find. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.3.19 cbf_rewind_column
     2.3.27 cbf_next_column
     2.3.29 cbf_find_datablock
     2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
     2.3.32 cbf_find_row
     2.3.44 cbf_column_name, cbf_set_column_name
     2.3.59 cbf_require_datablock
     2.3.60 cbf_require_category

     ----------------------------------------------------------------------

    2.3.62 cbf_require_column_value

     PROTOTYPE

     #include "cbf.h"

     int cbf_require_column_value (cbf_handle handle, const char *columnname,
     const char **value, const char *defaultvalue);

     DESCRIPTION

     cbf_require_column_doublevalue sets *value to the ASCII item at the
     current row for the column given with the name given by *columnname, or
     to the string given by defaultvalue if the item cannot be found.

     ARGUMENTS

       handle         CBF handle.                                             
       columnname     Name of the column containing the number.               
       value          pointer to the location to receive the value.           
       defaultvalue   Value to use if the requested column and value cannot   
                    be found.                                                 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.3.46 cbf_get_value, cbf_require_value
     2.3.47 cbf_set_value
     2.3.48 cbf_get_typeofvalue
     2.3.49 cbf_set_typeofvalue
     2.3.51 cbf_set_integervalue
     2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
     2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
     cbf_set_realarray, cbf_set_realarray_wdims
     2.3.63 cbf_require_column_integervalue
     2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.63 cbf_require_column_integervalue

     PROTOTYPE

     #include "cbf.h"

     int cbf_require_column_integervalue (cbf_handle handle, const char
     *columnname, int *number, const int defaultvalue);

     DESCRIPTION

     cbf_require_column_doublevalue sets *number to the value of the ASCII
     item at the current row for the column given with the name given by
     *columnname, with the value interpreted as an integer number, or to the
     number given by defaultvalue if the item cannot be found.

     ARGUMENTS

       handle         CBF handle.                                             
       columnname     Name of the column containing the number.               
       number         pointer to the location to receive the integer value.   
       defaultvalue   Value to use if the requested column and value cannot   
                    be found.                                                 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.3.46 cbf_get_value, cbf_require_value
     2.3.47 cbf_set_value
     2.3.48 cbf_get_typeofvalue
     2.3.49 cbf_set_typeofvalue
     2.3.51 cbf_set_integervalue
     2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
     2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
     cbf_set_realarray, cbf_set_realarray_wdims
     2.3.62 cbf_require_column_value
     2.3.64 cbf_require_column_doublevalue

     ----------------------------------------------------------------------

    2.3.64 cbf_require_column_doublevalue

     PROTOTYPE

     #include "cbf.h"

     int cbf_require_column_doublevalue (cbf_handle handle, const char
     *columnname, double *number, const double defaultvalue);

     DESCRIPTION

     cbf_require_column_doublevalue sets *number to the value of the ASCII
     item at the current row for the column given with the name given by
     *columnname, with the value interpreted as a decimal floating-point
     number, or to the number given by defaultvalue if the item cannot be
     found.

     ARGUMENTS

       handle         CBF handle.                                             
       columnname     Name of the column containing the number.               
       number         pointer to the location to receive the floating-point   
                    value.                                                    
       defaultvalue   Value to use if the requested column and value cannot   
                    be found.                                                 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.3.46 cbf_get_value, cbf_require_value
     2.3.47 cbf_set_value
     2.3.48 cbf_get_typeofvalue
     2.3.49 cbf_set_typeofvalue
     2.3.51 cbf_set_integervalue
     2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
     2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
     cbf_set_realarray, cbf_set_realarray_wdims
     2.3.62 cbf_require_column_value
     2.3.63 cbf_require_column_integervalue

     ----------------------------------------------------------------------

    2.3.65 cbf_get_local_integer_byte_order, cbf_get_local_real_byte_order,
    cbf_get_local_real_format

     PROTOTYPE

     #include "cbf.h"

     int cbf_get_local_integer_byte_order (char ** byte_order);
     int cbf_get_local_real_byte_order (char ** byte_order);
     int cbf_get_local_real_format (char ** real_format );

     DESCRIPTION

     cbf_get_local_integer_byte_order returns the byte order of integers on
     the machine on which the API is being run in the form of a character
     string returned as the value pointed to by byte_order.
     cbf_get_local_real_byte_order returns the byte order of reals on the
     machine on which the API is being run in the form of a character string
     returned as the value pointed to by byte_order.
     cbf_get_local_real_format returns the format of floats on the machine on
     which the API is being run in the form of a character string returned as
     the value pointed to by real_format. The strings returned must not be
     modified in any way.

     The values returned in byte_order may be the strings "little_endian" or
     "big-endian". The values returned in real_format may be the strings
     "ieee 754-1985" or "other". Additional values may be returned by future
     versions of the API.

     ARGUMENTS

       byte_order    pointer to the returned string 
       real_format   pointer to the returned string 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.3.66 cbf_get_dictionary, cbf_set_dictionary, cbf_require_dictionary

     PROTOTYPE

     #include "cbf.h"

     int cbf_get_dictionary (cbf_handle handle, cbf_handle * dictionary);
     int cbf_set_dictionary (cbf_handle handle, cbf_handle dictionary_in);
     int cbf_require_dictionary (cbf_handle handle, cbf_handle * dictionary)

     DESCRIPTION

     cbf_get_dictionary sets *dictionary to the handle of a CBF which has
     been associated with the CBF handle by cbf_set_dictionary.
     cbf_set_dictionary associates the CBF handle dictionary_in with handle
     as its dictionary. cbf_require_dictionary sets *dictionary to the handle
     of a CBF which has been associated with the CBF handle by
     cbf_set_dictionary or creates a new empty CBF and associates it with
     handle, returning the new handle in *dictionary.

     ARGUMENTS

       handle          CBF handle.                          
       dictionary      Pointer to CBF handle of dictionary. 
       dictionary_in   CBF handle of dcitionary.            

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.3.67 cbf_convert_dictionary

     PROTOTYPE

     #include "cbf.h"

     int cbf_convert_dictionary (cbf_handle handle, cbf_handle dictionary )

     DESCRIPTION

     cbf_convert_dictionary converts dictionary as a DDL1 or DDL2 dictionary
     to a CBF dictionary of category and item properties for handle, creating
     a new dictionary if none exists or layering the definitions in
     dictionary onto the existing dictionary of handle if one exists.

     If a CBF is read into handle after calling cbf_convert_dictionary, then
     the dictionary will be used for validation of the CBF as it is read.

     ARGUMENTS

       handle       CBF handle.               
       dictionary   CBF handle of dictionary. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.3.68 cbf_find_tag, cbf_find_local_tag

     PROTOTYPE

     #include "cbf.h"

     int cbf_find_tag (cbf_handle handle, const char *tag)
     int cbf_find_local_tag (cbf_handle handle, const char *tag)

     DESCRIPTION

     cbf_find_tag searches all of the CBF handle for the CIF tag given by the
     string tag and makes it the current tag. The search does not include the
     dictionary, but does include save frames as well as categories.

     The string tag is the complete tag in either DDL1 or DDL2 format,
     starting with the leading underscore, not just a category or column.

     ARGUMENTS

       handle   CBF handle. 
       tag      CIF tag.    

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.3.69 cbf_find_category_root, cbf_set_category_root,
    cbf_require_category_root

     PROTOTYPE

     #include "cbf.h"

     int cbf_find_category_root (cbf_handle handle, const char* categoryname,
     const char** categoryroot);
     int cbf_set_category_root (cbf_handle handle, const char*
     categoryname_in, const char*categoryroot);
     int cbf_require_category_root (cbf_handle handle, const char*
     categoryname, const char** categoryroot);

     DESCRIPTION

     cbf_find_category_root sets *categoryroot to the root category of which
     categoryname is an alias. cbf_set_category_root sets categoryname_in as
     an alias of categoryroot in the dictionary associated with handle,
     creating the dictionary if necessary. cbf_require_category_root sets
     *categoryroot to the root category of which categoryname is an alias, if
     there is one, or to the value of categoryname, if categoryname is not an
     alias.

     A returned categoryroot string must not be modified in any way.

     ARGUMENTS

       handle            CBF handle.                               
       categoryname      category name which may be an alias.      
       categoryroot      pointer to a returned category root name. 
       categoryroot_in   input category root name.                 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.3.70 cbf_find_tag_root, cbf_set_tag_root, cbf_require_tag_root

     PROTOTYPE

     #include "cbf.h"

     int cbf_find_tag_root (cbf_handle handle, const char* tagname, const
     char** tagroot);
     int cbf_set_tag_root (cbf_handle handle, const char* tagname, const
     char*tagroot_in);
     int cbf_require_tag_root (cbf_handle handle, const char* tagname, const
     char** tagroot);

     DESCRIPTION

     cbf_find_tag_root sets *tagroot to the root tag of which tagname is an
     alias. cbf_set_tag_root sets tagname as an alias of tagroot_in in the
     dictionary associated with handle, creating the dictionary if necessary.
     cbf_require_tag_root sets *tagroot to the root tag of which tagname is
     an alias, if there is one, or to the value of tagname, if tagname is not
     an alias.

     A returned tagroot string must not be modified in any way.

     ARGUMENTS

       handle       CBF handle.                          
       tagname      tag name which may be an alias.      
       tagroot      pointer to a returned tag root name. 
       tagroot_in   input tag root name.                 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.3.71 cbf_find_tag_category, cbf_set_tag_category

     PROTOTYPE

     #include "cbf.h"

     int cbf_find_tag_category (cbf_handle handle, const char* tagname, const
     char** categoryname);
     int cbf_set_tag_category (cbf_handle handle, const char* tagname, const
     char* categoryname_in);

     DESCRIPTION

     cbf_find_tag_category sets categoryname to the category associated with
     tagname in the dictionary associated with handle. cbf_set_tag_category
     upddates the dictionary associated with handle to indicated that tagname
     is in category categoryname_in.

     ARGUMENTS

       handle            CBF handle.                          
       tagname           tag name.                            
       categoryname      pointer to a returned category name. 
       categoryname_in   input category name.                 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

    2.4 High-level function prototypes

    2.4.1 cbf_read_template

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_read_template (cbf_handle handle, FILE *file);

     DESCRIPTION

     cbf_read_template reads the CBF or CIF file file into the CBF object
     specified by handle and selects the first datablock as the current
     datablock.

     ARGUMENTS

       handle   Pointer to a CBF handle.      
       file     Pointer to a file descriptor. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_diffrn_id (cbf_handle handle, const char **diffrn_id);
     int cbf_require_diffrn_id (cbf_handle handle, const char **diffrn_id,
     const char *default_id)

     DESCRIPTION

     cbf_get_diffrn_id sets *diffrn_id to point to the ASCII value of the
     "diffrn.id" entry. cbf_require_diffrn_id also sets *diffrn_id to point
     to the ASCII value of the "diffrn.id" entry, but, if the "diffrn.id"
     entry does not exist, it sets the value in the CBF and in*diffrn_id to
     the character string given by default_id, creating the category and
     column is necessary.

     The diffrn_id will be valid as long as the item exists and has not been
     set to a new value.

     The diffrn_id must not be modified by the program in any way.

     ARGUMENTS

       handle       CBF handle.                               
       diffrn_id    Pointer to the destination value pointer. 
       default_id   Character string default value.           

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.3 cbf_set_diffrn_id

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_diffrn_id (cbf_handle handle, const char *diffrn_id);

     DESCRIPTION

     cbf_set_diffrn_id sets the "diffrn.id" entry of the current datablock to
     the ASCII value diffrn_id.

     This function also changes corresponding "diffrn_id" entries in the
     "diffrn_source", "diffrn_radiation", "diffrn_detector" and
     "diffrn_measurement" categories.

     ARGUMENTS

       handle      CBF handle.  
       diffrn_id   ASCII value. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.4 cbf_get_crystal_id

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_crystal_id (cbf_handle handle, const char **crystal_id);

     DESCRIPTION

     cbf_get_crystal_id sets *crystal_id to point to the ASCII value of the
     "diffrn.crystal_id" entry.

     If the value is not ASCII, the function returns CBF_BINARY.

     The value will be valid as long as the item exists and has not been set
     to a new value.

     The value must not be modified by the program in any way.

     ARGUMENTS

       handle       CBF handle.                               
       crystal_id   Pointer to the destination value pointer. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.5 cbf_set_crystal_id

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_crystal_id (cbf_handle handle, const char *crystal_id);

     DESCRIPTION

     cbf_set_crystal_id sets the "diffrn.crystal_id" entry to the ASCII value
     crystal_id.

     ARGUMENTS

       handle       CBF handle.  
       crystal_id   ASCII value. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.6 cbf_get_wavelength

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_wavelength (cbf_handle handle, double *wavelength);

     DESCRIPTION

     cbf_get_wavelength sets *wavelength to the current wavelength in AA.

     ARGUMENTS

       handle       CBF handle.                 
       wavelength   Pointer to the destination. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.7 cbf_set_wavelength

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_wavelength (cbf_handle handle, double wavelength);

     DESCRIPTION

     cbf_set_wavelength sets the current wavelength in AA to wavelength.

     ARGUMENTS

       handle       CBF handle.       
       wavelength   Wavelength in AA. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.8 cbf_get_polarization

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_polarization (cbf_handle handle, double
     *polarizn_source_ratio, double *polarizn_source_norm);

     DESCRIPTION

     cbf_get_polarization sets *polarizn_source_ratio and
     *polarizn_source_norm to the corresponding source polarization
     parameters.

     Either destination pointer may be NULL.

     ARGUMENTS

       handle                  CBF handle.                                    
       polarizn_source_ratio   Pointer to the destination                     
                             polarizn_source_ratio.                           
       polarizn_source_norm    Pointer to the destination                     
                             polarizn_source_norm.                            

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.9 cbf_set_polarization

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_polarization (cbf_handle handle, double
     polarizn_source_ratio, double polarizn_source_norm);

     DESCRIPTION

     cbf_set_polarization sets the source polarization to the values
     specified by polarizn_source_ratio and polarizn_source_norm.

     ARGUMENTS

       handle                  CBF handle.                         
       polarizn_source_ratio   New value of polarizn_source_ratio. 
       polarizn_source_norm    New value of polarizn_source_norm.  

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.10 cbf_get_divergence

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_divergence (cbf_handle handle, double *div_x_source, double
     *div_y_source, double *div_x_y_source);

     DESCRIPTION

     cbf_get_divergence sets *div_x_source, *div_y_source and *div_x_y_source
     to the corresponding source divergence parameters.

     Any of the destination pointers may be NULL.

     ARGUMENTS

       handle           CBF handle.                                
       div_x_source     Pointer to the destination div_x_source.   
       div_y_source     Pointer to the destination div_y_source.   
       div_x_y_source   Pointer to the destination div_x_y_source. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.11 cbf_ set_divergence

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_divergence (cbf_handle handle, double div_x_source, double
     div_y_source, double div_x_y_source);

     DESCRIPTION

     cbf_set_divergence sets the source divergence parameters to the values
     specified by div_x_source, div_y_source and div_x_y_source.

     ARGUMENTS

       handle           CBF handle.                  
       div_x_source     New value of div_x_source.   
       div_y_source     New value of div_y_source.   
       div_x_y_source   New value of div_x_y_source. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.12 cbf_count_elements

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_count_elements (cbf_handle handle, unsigned int *elements);

     DESCRIPTION

     cbf_count_elements sets *elements to the number of detector elements.

     ARGUMENTS

       handle     CBF handle.                       
       elements   Pointer to the destination count. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.13 cbf_get_element_number, cbf_get_element_id

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_element_number(cbf_handle handle, const char *element_id,
     const char *array_id, const char *array_section_id, unsigned int
     *element_number);
     int cbf_get_element_id (cbf_handle handle, unsigned int element_number,
     const char **element_id);

     DESCRIPTION

     cbf_get_element_number sets element_number to a number that can be used
     in other cbf_simple calls to identify the detector element element_id
     and optionally the specific array_id> and array_section_id.
     cbf_get_element_id sets *element_id to point to the ASCII value of the
     element_number'th "diffrn_data_frame.detector_element_id" entry,
     counting from 0. The element_number is the ordinal of the detector
     element in the DIFFRN_DETECTOR_ELEMENT category. If an array_section_id
     is specified (i.e. is not NULL), the element_number is the sum of the
     ordinal of the detector element plus the number of detector elements
     multiplied by the ordinal of array_section_id for the specified
     array_id> in the ARRAY_STRUCTURE_LIST_SECTION category.

     If the detector element does not exist, the function returns
     CBF_NOTFOUND.

     The element_id will be valid as long as the item exists and has not been
     set to a new value.

     The element_id must not be modified by the program in any way.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number     The number of the detector element counting from 0  
                        by order of appearance in the "diffrn_data_frame"     
                      category.                                               
       element_id         Pointer to the destination string for               
                        cbf_get_element_id, but the string itself for         
                        cbf_get_element_number.                               
       array_id           The optional array id or NULL.                      
       array_section_id   The optional array_section_id or NULL.              

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.14 cbf_get_gain

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_gain (cbf_handle handle, unsigned int element_number, double
     *gain, double *gain_esd);

     DESCRIPTION

     cbf_get_gain sets *gain and *gain_esd to the corresponding gain
     parameters for element number element_number.

     Either of the destination pointers may be NULL.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       gain             Pointer to the destination gain.                      
       gain_esd         Pointer to the destination gain_esd.                  

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.15 cbf_ set_gain

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_gain (cbf_handle handle, unsigned int element_number, double
     gain, double gain_esd);

     DESCRIPTION

     cbf_set_gain sets the gain of element number element_number to the
     values specified by gain and gain_esd.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       gain             New gain value.                                       
       gain_esd         New gain_esd value.                                   

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.16 cbf_get_overload

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_overload (cbf_handle handle, unsigned int element_number,
     double *overload);

     DESCRIPTION

     cbf_get_overload sets *overload to the overload value for element number
     element_number.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       overload         Pointer to the destination overload.                  

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.17 cbf_ set_overload

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_overload (cbf_handle handle, unsigned int element_number,
     double overload);

     DESCRIPTION

     cbf_set_overload sets the overload value of element number
     element_number to overload.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       overload         New overload value.                                   

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.18 cbf_get_integration_time

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_integration_time (cbf_handle handle, unsigned int reserved,
     double *time);

     DESCRIPTION

     cbf_get_integration_time sets *time to the integration time in seconds.
     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       handle     CBF handle.                                
       reserved   Unused. Any value other than 0 is invalid. 
       time       Pointer to the destination time.           

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.19 cbf_set_integration_time

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_integration_time (cbf_handle handle, unsigned int reserved,
     double time);

     DESCRIPTION

     cbf_set_integration_time sets the integration time in seconds to the
     value specified by time. The parameter reserved is presently unused and
     should be set to 0.

     ARGUMENTS

       handle             CBF handle.                                
       reserved           Unused. Any value other than 0 is invalid. 
       time Integration   time in seconds.                           

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.20 cbf_get_timestamp

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_timestamp (cbf_handle handle, unsigned int reserved, double
     *time, int *timezone);

     DESCRIPTION

     cbf_get_timestamp sets *time to the collection timestamp in seconds
     since January 1 1970. *timezone is set to timezone difference from UTC
     in minutes. The parameter reserved is presently unused and should be set
     to 0.

     Either of the destination pointers may be NULL.

     ARGUMENTS

       handle     CBF handle.                                      
       reserved   Unused. Any value other than 0 is invalid.       
       time       Pointer to the destination collection timestamp. 
       timezone   Pointer to the destination timezone difference.  

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.21 cbf_set_timestamp

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_timestamp (cbf_handle handle, unsigned int reserved, double
     time, int timezone, double precision);

     DESCRIPTION

     cbf_set_timestamp sets the collection timestamp in seconds since January
     1 1970 to the value specified by time. The timezone difference from UTC
     in minutes is set to timezone. If no timezone is desired, timezone
     should be CBF_NOTIM EZONE. The parameter reserved is presently unused
     and should be set to 0.

     The precision of the new timestamp is specified by the value precision
     in seconds. If precision is 0, the saved timestamp is assumed accurate
     to 1 second.

     ARGUMENTS

       handle      CBF handle.                                                
       reserved    Unused. Any value other than 0 is invalid.                 
       time        Timestamp in seconds since January 1 1970.                 
       timezone    Timezone difference from UTC in minutes or CBF_NOTIMEZONE. 
       precision   Timestamp precision in seconds.                            

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.22 cbf_get_datestamp

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_datestamp (cbf_handle handle, unsigned int reserved, int
     *year, int *month, int *day, int *hour, int *minute, double *second, int
     *timezone);

     DESCRIPTION

     cbf_get_datestamp sets *year, *month, *day, *hour, *minute and *second
     to the corresponding values of the collection timestamp. *timezone is
     set to timezone difference from UTC in minutes. The parameter <
     i>reserved is presently unused and should be set to 0.

     Any of the destination pointers may be NULL.

     ARGUMENTS

       handle     CBF handle.                                                 
       reserved   Unused. Any value other than 0 is invalid.                  
       year       Pointer to the destination timestamp year.                  
       month      Pointer to the destination timestamp month (1-12).          
       day        Pointer to the destination timestamp day (1-31).            
       hour       Pointer to the destination timestamp hour (0-23).           
       minute     Pointer to the destination timestamp minute (0-59).         
       second     Pointer to the destination timestamp second (0-60.0).       
       timezone   Pointer to the destination timezone difference from UTC in  
                minutes.                                                      

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.23 cbf_set_datestamp

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_datestamp (cbf_handle handle, unsigned int reserved, int
     year, int month, int day, int hour, int minute, double second, int
     timezone, double precision);

     DESCRIPTION

     cbf_set_datestamp sets the collection timestamp in seconds since January
     1 1970 to the value specified by time. The timezone difference from UTC
     in minutes is set to timezone. If no timezone is desired, timezone
     should be CBF_NOTIM EZONE. The parameter reserved is presently unused
     and should be set to 0.

     The precision of the new timestamp is specified by the value precision
     in seconds. If precision is 0, the saved timestamp is assumed accurate
     to 1 second.

     ARGUMENTS

       handle    CBF handle.                                                
       reserved  Unused. Any value other than 0 is invalid.                 
       time      Timestamp in seconds since January 1 1970.                 
       timezone  Timezone difference from UTC in minutes or CBF_NOTIMEZONE. 
       precision Timestamp precision in seconds.                            

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.24 cbf_set_current_timestamp

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_current_timestamp (cbf_handle handle, unsigned int reserved,
     int timezone);

     DESCRIPTION

     cbf_set_current_timestamp sets the collection timestamp to the current
     time. The timezone difference from UTC in minutes is set to timezone. If
     no timezone is desired, timezone should be CBF_NOTIMEZONE. If no
     timezone is used, the timest amp will be UTC. The parameter reserved is
     presently unused and should be set to 0.

     The new timestamp will have a precision of 1 second.

     ARGUMENTS

       handle     CBF handle.                                                
       reserved   Unused.   Any value other than 0 is invalid.               
       timezone   Timezone difference from UTC in minutes or CBF_NOTIMEZONE. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.25 cbf_get_image_size, cbf_get_image_size_fs, cbf_get_image_size_sf,
          cbf_get_3d_image_size, cbf_get_3d_image_size_fs,
    cbf_get_3d_image_size_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_image_size (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, size_t *ndimslow, size_t *ndimfast);
     int cbf_get_image_size_fs (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, size_t *ndimfast, size_t *ndimslow);
     int cbf_get_image_size_sf (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, size_t *ndimslow, size_t *ndimfast);
      
     int cbf_get_3d_image_size (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, size_t *ndimslow, size_t *ndimmid, size_t
     *ndimfast);
     int cbf_get_3d_image_size_fs (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, size_t *ndimfast, size_t *ndimmid, size_t
     *ndimslow);
     int cbf_get_3d_image_size_sf (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, size_t *ndimslow, size_t *ndimmid, size_t
     *ndimfast);

     DESCRIPTION

     cbf_get_image_size, cbf_get_image_size_fs and cbf_get_image_size_sf set
     *ndimslow and *ndimfast to the slow and fast dimensions of the image
     array for element number element_number. If the array is 1-dimensional,
     *ndimslow will be set to the array size and *ndimfast will be set to 1.
     If the array is 3-dimensional an error code will be returned.
     cbf_get_3d_image_size, cbf_get_3d_image_size_fs and
     cbf_get_3d_image_size_sf set *ndimslow, *ndimmid and *ndimfast to the
     slowest, next fastest and fastest dimensions, respectively, of the 3D
     image array for element number element_number. If the array is
     1-dimensional, *ndimslow will be set to the array size and *ndimmid and
     *ndimfast will be set to 1. If the array is 2-dimensional *ndimslow and
     *ndimmid will be set as for a call to cbf_get_image_size and *ndimfast
     will be set to 1.

     The _fs calls give the dimensions in a fast-to-slow order. The calls
     with no suffix and the calls _sf calls give the dimensions in
     slow-to-fast order

     Note that the ordering of dimensions is specified by values of the tag
     _array_structure_list.precedence with a precedence of 1 for the fastest
     dimension, 2 for the next slower, etc., which is opposite to the
     ordering of the dimension arguments for these functions, except for the
     ones with the _fs suffix..

     Any of the destination pointers may be NULL.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       handle           CBF handle.                                           
       reserved         Unused. Any value other than 0 is invalid.            
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       ndimslow         Pointer to the destination slowest dimension.         
       ndimmid          Pointer to the destination next faster dimension.     
       ndimfast         Pointer to the destination fastest dimension.         

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,
          cbf_get_real_image, cbf_get_real_image_fs, cbf_get_real_image_sf,
          cbf_get_3d_image, cbf_get_3d_image_fs, cbf_get_3d_image_sf,
          cbf_get_real_3d_image, cbf_get_real_3d_image_fs,
    cbf_get_real_3d_image_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_image (cbf_handle handle, unsigned int reserved, unsigned
     int element_number, void *array, size_t elsize, int elsign, size_t
     ndimslow, size_t ndimfast);
     int cbf_get_image_fs (cbf_handle handle, unsigned int reserved, unsigned
     int element_number, void *array, size_t elsize, int elsign, size_t
     ndimfast, size_t ndimslow);
     int cbf_get_image_sf (cbf_handle handle, unsigned int reserved, unsigned
     int element_number, void *array, size_t elsize, int elsign, size_t
     ndimslow, size_t ndimfast);
      
     int cbf_get_real_image (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, size_t
     ndimslow, size_t ndimfast);
     int cbf_get_real_image_fs (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, size_t
     ndimfast, size_t ndimslow);
     int cbf_get_real_image_sf (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, size_t
     ndimslow, size_t ndimfast);
      
     int cbf_get_3d_image (cbf_handle handle, unsigned int reserved, unsigned
     int element_number, void *array, size_t elsize, int elsign, size_t
     ndimslow, size_t ndimmid, size_t ndimfast);
     int cbf_get_3d_image_fs (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, int elsign,
     size_t ndimfast, size_t ndimmid, size_t ndimslow);
     int cbf_get_3d_image_sf (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, int elsign,
     size_t ndimslow, size_t ndimmid, size_t ndimfast);
      
     int cbf_get_real_3d_image (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, size_t
     ndimslow, size_t ndimmid, size_t ndimfast);
     int cbf_get_real_3d_image_fs (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, size_t
     ndimfast, size_t ndimmid, size_t ndimslow);
     int cbf_get_real_3d_image_sf (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, void *array, size_t elsize, size_t
     ndimslow, size_t ndimmid, size_t ndimfast);

     DESCRIPTION

     cbf_get_image, cbf_get_image_fs and cbf_get_image_sf read the image
     array for element number element_number into an array. The array
     consists of ndimslow *ndimfast elements of elsize bytes each, starting
     at array. The elements are signed if elsign is non-0 and unsigned
     otherwise. cbf_get_real_image, cbf_get_real_image_fs and
     cbf_get_real_image_sf read the image array of IEEE doubles or floats for
     element number element_number into an array. A real array is always
     signed. cbf_get_3d_image, cbf_get_3d_image_fs and cbf_get_3d_image_sf
     read the 3D image array for element number element_number into an array.
     The array consists of ndimslow *ndimmid *ndimfast elements of elsize
     bytes each, starting at array. The elements are signed if elsign is
     non-0 and unsigned otherwise. cbf_get_real_3d_image,
     cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf reads the 3D image
     array of IEEE doubles or floats for element number element_number into
     an array. A real array is always signed.

     The _fs calls give the dimensions in a fast-to-slow order. The calls
     with no suffix and the calls _sf calls give the dimensions in
     slow-to-fast order

     The structure of the array as a 1-, 2- or 3-dimensional array should
     agree with the structure of the array given in the ARRAY_STRUCTURE_LIST
     category. If the array is 1-dimensional, ndimslow should be the array
     size and ndimfast and, for the 3D calls, ndimmid, should be set to 1
     both in the call and in the imgCIF data being processed. If the array is
     2-dimensional and a 3D call is used, ndimslow and ndimmid should be the
     array dimensions and ndimfast should be set to 1 both in the call and in
     the imgCIF data being processed.

     If any element in the binary data canOt fit into the destination
     element, the destination is set the nearest possible value.

     If the value is not binary, the function returns CBF_ASCII.

     If the requested number of elements canOt be read, the function will
     read as many as it can and then return CBF_ENDOFDATA.

     Currently, the destination array must consist of chars, shorts or ints
     (signed or unsigned) for cbf_get_image, or IEEE doubles or floats for
     cbf_get_real_image. If elsize is not equal to sizeof (char), sizeof
     (short), sizeof (int), sizeof(double) or sizeof(float), the function
     returns CBF_ARGUMENT.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       handle           CBF handle.                                           
       reserved         Unused. Any value other than 0 is invalid.            
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       array            Pointer to the destination array.                     
       elsize           Size in bytes of each destination array element.      
       elsigned         Set to non-0 if the destination array elements are    
                      signed.                                                 
       ndimslow         Slowest array dimension.                              
       ndimmid          Next faster array dimension.                          
       ndimfast         Fastest array dimension.                              

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
          cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,
          cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
          cbf_set_real_3d_image, cbf_set_real_3d_image_fs,
    cbf_set_real_3d_image_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_image (cbf_handle handle, unsigned int reserved, unsigned
     int element_number, unsigned int compression, void *array, size_t
     elsize, int elsign, size_t ndimslow, size_t ndimfast);
     int cbf_set_image_fs(cbf_handle handle, unsigned int reserved, unsigned
     int element_number, unsigned int compression, void *array, size_t
     elsize, int elsign, size_t ndimfast, size_t ndimslow);
     int cbf_set_image_sf(cbf_handle handle, unsigned int reserved, unsigned
     int element_number, unsigned int compression, void *array, size_t
     elsize, int elsign, size_t ndimslow, size_t ndimfast);
      
     int cbf_set_real_image (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void
     *array,size_t elsize, size_t ndimslow, size_t ndimfast);
     int cbf_set_real_image_fs(cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void
     *array,size_t elsize, size_t ndimfast, size_t ndimslow);
     int cbf_set_real_image_sf(cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void
     *array,size_t elsize, size_t ndimslow, size_t ndimfast);
      
     int cbf_set_3d_image (cbf_handle handle, unsigned int reserved, unsigned
     int element_number, unsigned int compression, void *array, size_t
     elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t ndimfast);
     int cbf_set_3d_image_fs(cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void *array,
     size_t elsize, int elsign, size_t ndimfast, size_t ndimmid, size_t
     ndimslow);
     int cbf_set_3d_image_sf(cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void *array,
     size_t elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t
     ndimfast);
      
     int cbf_set_real_3d_image (cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void
     *array,size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);
     int cbf_set_real_3d_image_fs(cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void
     *array,size_t elsize, size_t ndimfast, size_t ndimmid, size_t ndimslow);
     int cbf_set_real_3d_image_sf(cbf_handle handle, unsigned int reserved,
     unsigned int element_number, unsigned int compression, void
     *array,size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);

     DESCRIPTION

     cbf_set_image, cbf_set_image_fs and cbf_set_image_sf write the image
     array for element number element_number. The array consists of ndimfast
     *ndimslow elements of elsize bytes each, starting at array. The elements
     are signed if elsign is non-zero and unsigned otherwise.
     cbf_set_real_image, cbf_set_real_image_fs and cbf_set_real_image_sf
     write the image array for element number element_number. The array
     consists of ndimfast *ndimslow IEEE double or float elements of elsize
     bytes each, starting at array. cbf_set_3d_image, cbf_set_3d_image_fs and
     cbf_set_3d_image_sf write the 3D image array for element number
     element_number. The array consists of ndimfast *ndimmid *ndimslow
     elements of elsize bytes each, starting at array. The elements are
     signed if elsign is non-0 and unsigned otherwise. cbf_set_real_3d_image,
     cbf_set_real_3d_image_fs and cbf_set_real_3d_image_sf writes the 3D
     image array for element number element_number. The array consists of
     ndimfast *ndimmid *ndimslow IEEE double or float elements of elsize
     bytes each, starting at array.

     The _fs calls give the dimensions in a fast-to-slow order. The calls
     with no suffix and the calls _sf calls give the dimensions in
     slow-to-fast order

     If the array is 1-dimensional, ndimslow should be the array size and
     ndimfast and, for the 3D calls, ndimmid, should be set to 1. If the
     array is 2-dimensional and the 3D calls are used, ndimslow and ndimmid
     should be used for the array dimensions and ndimfast should be set to 1.

     The array will be compressed using the compression scheme specifed by
     compression. Currently, the available schemes are:

     CBF_CANONICAL     Canonical-code compression (section 3.3.1)      
     CBF_PACKED        CCP4-style packing (section 3.3.2)              
     CBF_PACKED_V2       CCP4-style packing, version 2 (section 3.3.2) 
     CBF_BYTE_OFFSET     Simple "byte_offset" compression.             
     CBF_NIBBLE_OFFSET   Simple "nibble_offset" compression.           
     CBF_NONE          No compression.                                 

     The values compressed are limited to 64 bits. If any element in the
     array is larger than 64 bits, the value compressed is the nearest 64-bit
     value.

     Currently, the source array must consist of chars, shorts or ints
     (signed or unsigned)for cbf_set_image, or IEEE doubles or floats for
     cbf_set_real_image. If elsize is not equal to sizeof (short), sizeof
     (int), sizeof(double) or sizeof(float), the function returns
     CBF_ARGUMENT.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       handle           CBF handle.                                           
       reserved         Unused. Any value other than 0 is invalid.            
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       compression      Compression type.                                     
       array            Pointer to the image array.                           
       elsize           Size in bytes of each image array element.            
       elsigned         Set to non-0 if the image array elements are signed.  
       ndimslow         Slowest array dimension.                              
       ndimmid          Second slowest array dimension.                       
       ndimfast         Fastest array dimension.                              

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.28 cbf_count_axis_ancestors, cbf_get_axis_ancestor,
    cbf_get_axis_depends_on,
    cbf_get_axis_equipment, cbf_get_axis_equipment_component,
    cbf_get_axis_offset,
    cbf_get_axis_rotation, cbf_get_axis_rotation_axis,
    cbf_get_axis_setting,
    cbf_get_axis_type,
    cbf_get_axis_vector

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_count_axis_ancestors (cbf_handle handle, const char *axis_id,
     unsigned int *ancestors);

     int cbf_get_axis_ancestor (cbf_handle handle, const char *axis_id, const
     unsigned int ancestor_index, const char * *ancestor);

     int cbf_get_axis_depends_on (cbf_handle handle, const char *axis_id,
     const char * *depends_on);

     int cbf_get_axis_equipment (cbf_handle handle, const char *axis_id,
     const char * *equipment);

     int cbf_get_axis_equipment_component (cbf_handle handle, const char
     *axis_id, const char * *equipment_component);

     int cbf_get_axis_offset (cbf_handle handle, const char *axis_id, double
     *offset1, double *offset2, double *offset3);

     int cbf_get_axis_rotation (cbf_handle handle, const char *axis_id,
     double *rotation);

     int cbf_get_axis_rotation_axis (cbf_handle handle, const char *axis_id,
     const char * *rotation_axis);

     int cbf_get_axis_setting (cbf_handle handle, unsigned int reserved,
     const char *axis_id, double *start, double *increment);

     int cbf_get_axis_type (cbf_handle handle, const char *axis_id,
     cbf_axis_type *axis_type);

     int cbf_get_axis_vector (cbf_handle handle, const char *axis_id, double
     *vector1, double *vector2, double *vector3);

     DESCRIPTION

     cbf_count_axis_ancestors sets ancestors to the number of ancestors of
     axis axis_id. cbf_get_axis_ancestor sets *ancestor to the ancestor axis
     of index ancestor_index of axis axis_id, starting with axis_id for
     ancestor_index 0.

     cbf_get_axis_depends_on sets *depends_on to the immediate ancestor of
     axis_id or to "." if there is no such ancestor. cbf_get_axis_equipment
     sets *equipment to the equipment of axis_id or to "." if there is no
     such equipment. cbf_get_axis_equipment_component sets
     *equipment_component to the equipment_component of axis_id or to "." if
     there is no such equipment_component.

     cbf_get_axis_offset sets *offset1, *offset2 and *offset3 to the
     components of the ofset of axis_id.

     cbf_get_axis_rotation sets rotation to the rotation of axis_id or to 0
     if there is no such rotation. cbf_get_axis_rotation_axis sets
     *rotation_axis to the rotation_axis of axis_id or to "." if there is no
     such rotation_axis.

     cbf_get_axis_setting sets *start and *increment to the corresponding
     values of the axis axis_id. Any of the destination pointers may be NULL.

     cbf_get_axis_type sets axis_type to the type of axis_id.

     cbf_get_axis_vector sets *vector1, *vector2 and *vector3 to the
     components of the vector of axis_id.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       handle      CBF handle.                                 
       reserved    Unused. Any value other than 0 is invalid.  
       axis_id     Axis id.                                    
       ancestor_index        Integer index of the desired ancestor, starting  
                           with 0 for the current axis_id.                    
       ancestor              Pointer to destination ancestor name pointer.    
       depends_on            Pointer to destination depends_on name pointer.  
       equipment             Pointer to destination equipment name pointer.   
       equipment_component   Pointer to destination equipment_component name  
                           pointer.                                           
       offset1               Pointer to destination first offset component    
                           value.                                             
       offset2               Pointer to destination second offset component   
                           value.                                             
       offset3               Pointer to destination third offset component    
                           value.                                             
       rotation              Pointer to destination rotation value.           
       rotation_axis         Pointer to destination rotation_axisn name       
                           pointer.                                           
       start       Pointer to the destination start value.     
       increment   Pointer to the destination increment value. 
       type                  Pointer to destination axis type of type .       
       vector1               Pointer to destination first vector component    
                           value.                                             
       vector2               Pointer to destination second vector component   
                           value.                                             
       vector3               Pointer to destination third vector component    
                           value.                                             

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.29 cbf_set_axis_setting

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_axis_setting (cbf_handle handle, unsigned int reserved,
     const char *axis_id, double start, double increment);

     DESCRIPTION

     cbf_set_axis_setting sets the starting and increment values of the axis
     axis_id to start and increment.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       handle      CBF handle.                                
       reserved    Unused. Any value other than 0 is invalid. 
       axis_id     Axis id.                                   
       start       Start value.                               
       increment   Increment value.                           

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.30 cbf_construct_goniometer

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_construct_goniometer (cbf_handle handle, cbf_goniometer
     *goniometer);

     DESCRIPTION

     cbf_construct_goniometer constructs a goniometer object using the
     description in the CBF object handle and initialises the goniometer
     handle *goniometer.

     ARGUMENTS

       handle       CBF handle.                                   
       goniometer   Pointer to the destination goniometer handle. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.31 cbf_free_goniometer

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_free_goniometer (cbf_goniometer goniometer);

     DESCRIPTION

     cbf_free_goniometer destroys the goniometer object specified by
     goniometer and frees all associated memory.

     ARGUMENTS

       goniometer   Goniometer handle to free. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.32 cbf_get_rotation_axis

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_rotation_axis (cbf_goniometer goniometer, unsigned int
     reserved, double *vector1, double *vector2, double *vector3);

     DESCRIPTION

     cbf_get_rotation_axis sets *vector1, *vector2, and *vector3 to the 3
     components of the goniometer rotation axis used for the exposure.

     Any of the destination pointers may be NULL.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       goniometer   Goniometer handle.                                        
       reserved     Unused. Any value other than 0 is invalid.                
       vector1      Pointer to the destination x component of the rotation    
                  axis.                                                       
       vector2      Pointer to the destination y component of the rotation    
                  axis.                                                       
       vector3      Pointer to the destination z component of the rotation    
                  axis.                                                       

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.33 cbf_get_rotation_range

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_rotation_range (cbf_goniometer goniometer, unsigned int
     reserved, double *start, double *increment);

     DESCRIPTION

     cbf_get_rotation_range sets *start and *increment to the corresponding
     values of the goniometer rotation axis used for the exposure.

     Either of the destination pointers may be NULL.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       goniometer   Goniometer handle.                          
       reserved     Unused. Any value other than 0 is invalid.  
       start        Pointer to the destination start value.     
       increment    Pointer to the destination increment value. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.34 cbf_rotate_vector

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_rotate_vector (cbf_goniometer goniometer, unsigned int reserved,
     double ratio, double initial1, double initial2, double initial3, double
     *final1, double *final2, double *final3);

     DESCRIPTION

     cbf_rotate_vector sets *final1, *final2, and *final3 to the 3 components
     of the of the vector (initial1, initial2, initial3) after reorientation
     by applying the goniometer rotations. The value ratio specif ies the
     goniometer setting and varies from 0.0 at the beginning of the exposure
     to 1.0 at the end, irrespective of the actual rotation range.

     Any of the destination pointers may be NULL.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       goniometer   Goniometer handle.                                        
       reserved     Unused. Any value other than 0 is invalid.                
       ratio        Goniometer setting. 0 = beginning of exposure, 1 = end.   
       initial1     x component of the initial vector.                        
       initial2     y component of the initial vector.                        
       initial3     z component of the initial vector.                        
       vector1      Pointer to the destination x component of the final       
                  vector.                                                     
       vector2      Pointer to the destination y component of the final       
                  vector.                                                     
       vector3      Pointer to the destination z component of the final       
                  vector.                                                     

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.35 cbf_get_reciprocal

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_reciprocal (cbf_goniometer goniometer, unsigned int
     reserved, double ratio, double wavelength, double real1, double real2,
     double real3, double *reciprocal1, double *reciprocal2, double
     *reciprocal3);

     DESCRIPTION

     cbf_get_reciprocal sets *reciprocal1, * reciprocal2, and * reciprocal3
     to the 3 components of the of the reciprocal-space vector corresponding
     to the real-space vector (real1, real2, real3). The reciprocal-space
     vector is oriented to correspond to the goniometer setting with all axes
     at 0. The value wavelength is the wavlength in AA and the value ratio
     specifies the current goniometer setting and varies from 0.0 at the
     beginning of the exposur e to 1.0 at the end, irrespective of the actual
     rotation range.

     Any of the destination pointers may be NULL.

     The parameter reserved is presently unused and should be set to 0.

     ARGUMENTS

       goniometer    Goniometer handle.                                       
       reserved      Unused. Any value other than 0 is invalid.               
       ratio         Goniometer setting. 0 = beginning of exposure, 1 = end.  
       wavelength    Wavelength in AA.                                        
       real1         x component of the real-space vector.                    
       real2         y component of the real-space vector.                    
       real3         z component of the real-space vector.                    
       reciprocal1   Pointer to the destination x component of the            
                   reciprocal-space vector.                                   
       reciprocal2   Pointer to the destination y component of the            
                   reciprocal-space vector.                                   
       reciprocal3   Pointer to the destination z component of the            
                   reciprocal-space vector.                                   

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.36 cbf_construct_detector, cbf_construct_reference_detector,
    cbf_require_reference_detector

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_construct_detector (cbf_handle handle, cbf_detector *detector,
     unsigned int element_number);

     int cbf_construct_reference_detector (cbf_handle handle, cbf_detector
     *detector, unsigned int element_number);

     int cbf_require_reference_detector (cbf_handle handle, cbf_detector
     *detector, unsigned int element_number);

     DESCRIPTION

     cbf_construct_detector constructs a detector object for detector element
     number element_number using the description in the CBF object handle and
     initialises the detector handle *detector.

     cbf_construct_reference_detector constructs a detector object for
     detector element number element_number using the description in the CBF
     object handle and initialises the detector handle *detector using the
     reference settings of the axes. cbf_require_reference_detector is
     similar, but try to force the creations of missing intermediate
     categories needed to construct a detector object.

     ARGUMENTS

       handle           CBF handle.                                           
       detector         Pointer to the destination detector handle.           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.37 cbf_free_detector

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_free_detector (cbf_detector detector);

     DESCRIPTION

     cbf_free_detector destroys the detector object specified by detector and
     frees all associated memory.

     ARGUMENTS

       detector   Detector handle to free. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.38 cbf_construct_positioner, cbf_construct_reference_positioner,

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_construct_positioner (cbf_handle handle, cbf_positioner
     *positioner, const char *axis_id);

     int cbf_construct_reference_positioner (cbf_handle handle,
     cbf_positioner *positioner, const char *axis_id);

     DESCRIPTION

     cbf_construct_positioner constructs a positioner object for the axis
     given by axis_id using the description in the CBF object handle and
     initialises the positioner handle *positioner.

     cbf_construct_reference positioner constructs a positioner object for
     the axis given by axis_id using the description in the CBF object handle
     and initialises the detector handle *detector using the reference
     settings of the axes.

     ARGUMENTS

       handle     CBF handle.                                        
       detector   Pointer to the destination detector handle.        
       axis_id    The identifier of the axis in the "axis" category. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.39 cbf_free_positioner

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_free_positioner (cbf_positioner positioner);

     DESCRIPTION

     cbf_free_positioner destroys the positioner object specified by
     positioner and frees all associated memory.

     ARGUMENTS

       positioner   Positioner handle to free. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs, cbf_get_beam_center_sf,
          cbf_set_beam_center, cbf_set_beam_center_fs, cbf_set_beam_center_sf,
          set_reference_beam_center, set_reference_beam_center_fs,
    set_reference_beam_center_fs

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_beam_center (cbf_detector detector, double *indexslow,
     double *indexfast, double *centerslow, double *centerfast);
     int cbf_get_beam_center_fs (cbf_detector detector, double *indexfast,
     double *indexslow, double *centerfast, double *centerslow);
     int cbf_get_beam_center_sf (cbf_detector detector, double *indexslow,
     double *indexfast, double *centerslow, double *centerfast);

     int cbf_set_beam_center (cbf_detector detector, double *indexslow,
     double *indexfast, double *centerslow, double *centerfast);
     int cbf_set_beam_center_fs (cbf_detector detector, double *indexfast,
     double *indexslow, double *centerfast, double *centerslow);
     int cbf_set_beam_center_sf (cbf_detector detector, double *indexslow,
     double *indexfast, double *centerslow, double *centerfast);

     int cbf_set_reference_beam_center (cbf_detector detector, double
     *indexslow, double *indexfast, double *centerslow, double *centerfast);
     int cbf_set_reference_beam_center_fs (cbf_detector detector, double
     *indexfast, double *indexslow, double *centerfast, double *centerslow);
     int cbf_set_reference_beam_center_sf (cbf_detector detector, double
     *indexslow, double *indexfast, double *centerslow, double *centerfast);

     DESCRIPTION

     cbf_get_beam_center sets *centerfast and *centerslow to the
     displacements in mm along the detector axes from pixel (0, 0) to the
     point at which the beam intersects the detector and *indexfast and
     *indexslow to the corresponding indices. cbf_set_beam_center sets the
     offsets in the axis category for the detector element axis with
     precedence 1 to place the beam center at the position given in mm by
     *centerfast and *centerslow as the displacements in mm along the
     detector axes from pixel (0, 0) to the point at which the beam
     intersects the detector at the indices given *indexfast and *indexslow.
     cbf_set_reference_beam_center sets the displacments in the
     array_structure_list_axis category to place the beam center at the
     position given in mm by *centerfast and *centerslow as the displacements
     in mm along the detector axes from pixel (0, 0) to the point at which
     the beam intersects the detector at the indices given by *indexfast and
     *indexslow. In order to achieve consistent results, a reference detector
     should be used for detector to have all axes at their reference
     settings.

     Note that the precedence 1 axis is the fastest axis, so that *centerfast
     and *indexfast are the fast axis components of the center and
     *centerslow and *indexslow are the slow axis components of the center.

     The _fs calls give the displacments in a fast-to-slow order. The calls
     with no suffix and the calls _sf calls give the displacements in
     slow-to-fast order

     Any of the destination pointers may be NULL for getting the beam center.
     For setting the beam axis, either the indices of the center must not be
     NULL.

     The indices are non-negative for beam centers within the detector
     surface, but the center for an axis with a negative increment will be
     negative for a beam center within the detector surface.

     For cbf_set_beam_center if the diffrn_data_frame category exists with a
     row for the corresponding element id, the values will be set for
     _diffrn_data_frame.center_fast and _diffrn_data_frame.center_slow in
     millimetres and the value of _diffrn_data_frame.center_units will be set
     to 'mm'.

     For cbf_set_reference_beam_center if the diffrn_detector_element
     category exists with a row for the corresponding element id, the values
     will be set for _diffrn_detector_element.reference_center_fast and
     _diffrn_detector_element.reference_center_slow in millimetres and the
     value of _diffrn_detector_element.reference_units will be set to 'mm'.

     ARGUMENTS

       detector     Detector handle.                                          
       indexfast    Pointer to the destination fast index.                    
       indexslow    Pointer to the destination slow index.                    
       centerfast   Pointer to the destination displacement along the fast    
                  axis.                                                       
       centerslow   Pointer to the destination displacement along the slow    
                  axis.                                                       

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.41 cbf_get_detector_distance

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_detector_distance (cbf_detector detector, double *distance);

     DESCRIPTION

     cbf_get_detector_distance sets *distance to the nearest distance from
     the sample position to the detector plane.

     ARGUMENTS

       detector   Detector handle.                     
       distance   Pointer to the destination distance. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.42 cbf_get_detector_normal

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_detector_normal (cbf_detector detector, double *normal1,
     double *normal2, double *normal3);

     DESCRIPTION

     cbf_get_detector_normal sets *normal1, *normal2, and *normal3 to the 3
     components of the of the normal vector to the detector plane. The vector
     is normalized.

     Any of the destination pointers may be NULL.

     ARGUMENTS

       detector   Detector handle.                                            
       normal1    Pointer to the destination x component of the normal        
                vector.                                                       
       normal2    Pointer to the destination y component of the normal        
                vector.                                                       
       normal3    Pointer to the destination z component of the normal        
                vector.                                                       

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.43 cbf_get_detector_axis_slow, cbf_get_detector_axis_slow,
    cbf_get_detector_axes, cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
    cbf_get_detector_surface_axes

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_detector_axis_slow (cbf_detector detector, double
     *slowaxis1, double *slowaxis2, double *slowaxis3);
     int cbf_get_detector_axis_fast (cbf_detector detector, double
     *fastaxis1, double *fastaxis2, double *fastaxis3);
     int cbf_get_detector_axes (cbf_detector detector, double *slowaxis1,
     double *slowaxis2, double *slowaxis3, double *fastaxis1, double
     *fastaxis2, double *fastaxis3);
     int cbf_get_detector_axes_fs (cbf_detector detector, double *fastaxis1,
     double *fastaxis2, double *fastaxis3, double *slowaxis1, double
     *slowaxis2, double *slowaxis3);
     int cbf_get_detector_axes_sf (cbf_detector detector, double *slowaxis1,
     double *slowaxis2, double *slowaxis3, double *fastaxis1, double
     *fastaxis2, double *fastaxis3);
     int cbf_get_detector_surface_axes(cbf_detector detector, const char * *
     axis_id1, const char * * axis_id2);

     DESCRIPTION

     cbf_get_detector_axis_slow sets *slowaxis1, *slowaxis2, and *slowaxis3
     to the 3 components of the slow axis of the specified detector at the
     current settings of all axes. cbf_get_detector_axis_slow sets
     *fastaxis1, *fastaxis2, and *fastaxis3 to the 3 components of the fast
     axis of the specified detector at the current settings of all axes.
     cbf_get_detector_axes, cbf_get_detector_axes_fs and int
     cbf_get_detector_axes_sf set *slowaxis1, *slowaxis2, and *slowaxis3 to
     the 3 components of the slow axis and *fastaxis1, *fastaxis2, and
     *fastaxis3 to the 3 components of the fast axis of the specified
     detector at the current settings of all axes.
     cbf_get_detector_surface_axes sets *axis_id1 and *axis_id2 to the names
     of the two surface axes of the detector or ".",

     Any of the destination pointers may be NULL.

     ARGUMENTS

       detector    Detector handle.                                           
       slowaxis1   Pointer to the destination x component of the slow axis    
                 vector.                                                      
       slowaxis2   Pointer to the destination y component of the slow axis    
                 vector.                                                      
       slowaxis3   Pointer to the destination z component of the slow axis    
                 vector.                                                      
       fastaxis1   Pointer to the destination x component of the fast axis    
                 vector.                                                      
       fastaxis2   Pointer to the destination y component of the fast axis    
                 vector.                                                      
       fastaxis3   Pointer to the destination z component of the fast axis    
                 vector.                                                      
       axis_id1    Pointer to the destination first surface axis name.        
       axis_id1    Pointer to the destination first surface axis name.        
       axis_id2    Pointer to the destination second surface axis name.       

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.44 cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs,
    cbf_get_pixel_coordinates_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_pixel_coordinates (cbf_detector detector, double indexslow,
     double indexfast, double *coordinate1, double *coordinate2, double
     *coordinate3);
     int cbf_get_pixel_coordinates_fs (cbf_detector detector, double
     indexfast, double indexslow, double *coordinate1, double *coordinate2,
     double *coordinate3);
     int cbf_get_pixel_coordinates_sf (cbf_detector detector, double
     indexslow, double indexfast, double *coordinate1, double *coordinate2,
     double *coordinate3);

     DESCRIPTION

     cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs and
     cbf_get_pixel_coordinates_sf ses *coordinate1, *coordinate2, and
     *coordinate3 to the vector position of pixel (indexfast, indexslow) on
     the detector surface. If indexslow and indexfast are integers then the
     coordinates correspond to the center of a pixel.

     Any of the destination pointers may be NULL.

     ARGUMENTS

       detector      Detector handle.                        
       indexslow     Slow index.                             
       indexfast     Fast index.                             
       coordinate1   Pointer to the destination x component. 
       coordinate2   Pointer to the destination y component. 
       coordinate3   Pointer to the destination z component. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs,
    cbf_get_pixel_normal_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_pixel_normal (cbf_detector detector, double indexslow,
     double indexfast, double *normal1, double *normal2, double *normal3);
     int cbf_get_pixel_normal_fs (cbf_detector detector, double indexfast,
     double indexslow, double *normal1, double *normal2, double *normal3);
     int cbf_get_pixel_normal (cbf_detector detector, double indexslow,
     double indexfast, double *normal1, double *normal2, double *normal3);

     DESCRIPTION

     cbf_get_detector_normal, cbf_get_pixel_normal_fs and
     cbf_get_pixel_normal_sf set *normal1, *normal2, and *normal3 to the 3
     components of the of the normal vector to the pixel at (indexfast,
     indexslow). The vector is normalized.

     Any of the destination pointers may be NULL.

     ARGUMENTS

       detector    Detector handle.                                           
       indexslow   Slow index.                                                
       indexfast   Fast index.                                                
       normal1     Pointer to the destination x component of the normal       
                 vector.                                                      
       normal2     Pointer to the destination y component of the normal       
                 vector.                                                      
       normal3     Pointer to the destination z component of the normal       
                 vector.                                                      

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs, cbf_get_pixel_area_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_pixel_area (cbf_detector detector, double indexslow, double
     indexfast, double *area, double *projected_area);
     int cbf_get_pixel_area_fs(cbf_detector detector, double indexfast,
     double indexslow, double *area, double *projected_area);
     int cbf_get_pixel_area_sf(cbf_detector detector, double indexslow,
     double indexfast, double *area, double *projected_area);

     DESCRIPTION

     cbf_get_pixel_area, cbf_get_pixel_area_fs and cbf_get_pixel_area_sf set
     *area to the area of the pixel at (indexfast, indexslow) on the detector
     surface and *projected_area to the apparent area of the pixel as viewed
     from the sample position, with indexslow being the slow axis and
     indexfast being the fast axis.

     Either of the destination pointers may be NULL.

     ARGUMENTS

       detector         Detector handle.                                 
       indexfast        Fast index.                                      
       indexslow        Slow index.                                      
       area             Pointer to the destination area in mm2.          
       projected_area   Pointer to the destination apparent area in mm2. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs, cbf_get_pixel_size_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_pixel_size (cbf_handle handle, unsigned int element_number,
     int axis_number, double *psize);
     int cbf_get_pixel_size_fs(cbf_handle handle, unsigned int
     element_number, int axis_number, double *psize);
     int cbf_get_pixel_size_sf(cbf_handle handle, unsigned int
     element_number, int axis_number, double *psize);

     DESCRIPTION

     cbf_get_pixel_size and cbf_get_pixel_size_sf set *psize to point to the
     double value in millimeters of the axis axis_number of the detector
     element element_number. The axis_number is numbered from 1, starting
     with the slowest axis. cbf_get_pixel_size_fs sets *psize to point to the
     double value in millimeters of the axis axis_number of the detector
     element element_number. The axis_number is numbered from 1, starting
     with the fastest axis.

     If a negative axis number is given, the order of axes is reversed, so
     that -1 specifies the slowest axis for cbf_get_pixel_size_fs and the
     fastest axis for cbf_get_pixel_size_sf.

     If the pixel size is not given explcitly in the "array_element_size"
     category, the function returns CBF_NOTFOUND.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       axis_number      The number of the axis, starting from 1 for the       
                      fastest for cbf_get_pixel_size and                      
                      cbf_get_pixel_size_fs and the slowest for               
                      cbf_get_pixel_size_sf.                                  
       psize            Pointer to the destination pixel size.                

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs, cbf_set_pixel_size_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_pixel_size (cbf_handle handle, unsigned int element_number,
     int axis_number, double psize);
     int cbf_set_pixel_size_fs(cbf_handle handle, unsigned int
     element_number, int axis_number, double psize);
     int cbf_set_pixel_size_sf(cbf_handle handle, unsigned int
     element_number, int axis_number, double psize);

     DESCRIPTION

     cbf_set_pixel_size and cbf_set_pixel_size_sf set the item in the "size"
     column of the "array_structure_list" category at the row which matches
     axis axis_number of the detector element element_number converting the
     double pixel size psize from meters to millimeters in storing it in the
     "size" column for the axis axis_number of the detector element
     element_number. The axis_number is numbered from 1, starting with the
     slowest axis. cbf_set_pixel_size_fs sets the item in the "size" column
     of the "array_structure_list" category at the row which matches axis
     axis_number of the detector element element_number converting the double
     pixel size psize from meters to millimeters in storing it in the "size"
     column for the axis axis_number of the detector element element_number.
     The axis_number is numbered from 1, starting with the fastest axis.

     If a negative axis number is given, the order of axes is reversed, so
     that -1 specifies the slowest axis for cbf_get_pixel_size_fs and the
     fastest axis for cbf_get_pixel_size_sf.

     If the "array_structure_list" category does not already exist, it is
     created.

     If the appropriate row in the "array_structure_list" catgeory does not
     already exist, it is created.

     If the pixel size is not given explcitly in the "array_element_size
     category", the function returns CBF_NOTFOUND.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       axis_number      The number of the axis, fastest first, starting from  
                      1.                                                      
       psize            The pixel size in millimeters.                        

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.49 cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_fs,
    cbf_get_inferred_pixel_size_sf

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_inferred_pixel_size (cbf_detector detector, int axis_number,
     double *psize);
     int cbf_get_inferred_pixel_size_fs(cbf_detector detector, int
     axis_number, double *psize);
     int cbf_get_inferred_pixel_size_sf(cbf_detector detector, int
     axis_number, double *psize);

     DESCRIPTION

     cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_sf set *psize
     to point to the double value in millimeters of the pixel size for the
     axis axis_number value. The slow index is treated as axis 1 and the next
     faster index is treated as axis 2. cbf_get_inferred_pixel_size_fs sets
     *psize to point to the double value in millimeters of the pixel size for
     the axis axis_number value. The fast index is treated as axis 1 and the
     next slower index is treated as axis 2.

     If the axis number is negative, the axes are used in the reverse order
     so that an axis_number of -1 indicates the fast axes in a call to
     cbf_get_inferred_pixel_size or cbf_get_inferred_pixel_size_sf and
     indicates the fast axis in a call to cbf_get_inferred_pixel_size_fs.

     ARGUMENTS

       detector      Detector handle.                             
       axis_number   The number of the axis.                      
       area          Pointer to the destination pizel size in mm. 

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.50 cbf_get_unit_cell

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_unit_cell (cbf_handle handle, double cell[6], double
     cell_esd[6] );

     DESCRIPTION

     cbf_get_unit_cell sets cell[0:2] to the double values of the cell edge
     lengths a, b and c in AAngstroms, cell[3:5] to the double values of the
     cell angles a, b and g in degrees, cell_esd[0:2] to the double values of
     the estimated strandard deviations of the cell edge lengths a, b and c
     in AAngstroms, cell_esd[3:5] to the double values of the estimated
     standard deviations of the the cell angles a, b and g in degrees.

     The values returned are retrieved from the first row of the "cell"
     category. The value of "_cell.entry_id" is ignored.

     cell or cell_esd may be NULL.

     If cell is NULL, the cell parameters are not retrieved.

     If cell_esd is NULL, the cell parameter esds are not retrieved.

     If the "cell" category is present, but some of the values are missing,
     zeros are returned for the missing values.

     ARGUMENTS

       handle     CBF handle.                                                 
       cell       Pointer to the destination array of 6 doubles for the cell  
                parameters.                                                   
       cell_esd   Pointer to the destination array of 6 doubles for the cell  
                parameter esds.                                               

     RETURN VALUE

     Returns an error code on failure or 0 for success. No errors is returned
     for missing values if the "cell" category exists.

     SEE ALSO

     2.4.51 cbf_set_unit_cell
     2.4.52 cbf_get_reciprocal_cell
     2.4.53 cbf_set_reciprocal_cell
     2.4.54 cbf_compute_cell_volume
     2.4.55 cbf_compute_reciprocal_cell

     ----------------------------------------------------------------------

    2.4.51 cbf_set_unit_cell

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_unit_cell (cbf_handle handle, double cell[6], double
     cell_esd[6] );

     DESCRIPTION

     cbf_set_unit_cell sets the cell parameters to the double values given in
     cell[0:2] for the cell edge lengths a, b and c in AAngstroms, the double
     values given in cell[3:5] for the cell angles a, b and g in degrees, the
     double values given in cell_esd[0:2] for the estimated strandard
     deviations of the cell edge lengths a, b and c in AAngstroms, and the
     double values given in cell_esd[3:5] for the estimated standard
     deviations of the the cell angles a, b and g in degrees.

     The values are placed in the first row of the "cell" category. If no
     value has been given for "_cell.entry_id", it is set to the value of the
     "diffrn.id" entry of the current data block.

     cell or cell_esd may be NULL.

     If cell is NULL, the cell parameters are not set.

     If cell_esd is NULL, the cell parameter esds are not set.

     If the "cell" category is not present, it is created. If any of the
     necessary columns are not present, they are created.

     ARGUMENTS

       handle     CBF handle.                                                 
       cell       Pointer to the array of 6 doubles for the cell parameters.  
       cell_esd   Pointer to the array of 6 doubles for the cell parameter    
                esds.                                                         

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.4.50 cbf_get_unit_cell
     2.4.52 cbf_get_reciprocal_cell
     2.4.53 cbf_set_reciprocal_cell
     2.4.54 cbf_compute_cell_volume
     2.4.55 cbf_compute_reciprocal_cell

     ----------------------------------------------------------------------

     SEE ALSO

    2.4.52 cbf_get_reciprocal_cell

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_reciprocal_cell (cbf_handle handle, double cell[6], double
     cell_esd[6] );

     DESCRIPTION

     cbf_get_reciprocal_cell sets cell[0:2] to the double values of the
     reciprocal cell edge lengths a*, b* and c* in AAngstroms-1, cell[3:5] to
     the double values of the reciprocal cell angles a*, b* and g* in
     degrees, cell_esd[0:2] to the double values of the estimated strandard
     deviations of the reciprocal cell edge lengths a*, b* and c* in
     AAngstroms-1, cell_esd[3:5] to the double values of the estimated
     standard deviations of the the reciprocal cell angles a*, b* and g* in
     degrees.

     The values returned are retrieved from the first row of the "cell"
     category. The value of "_cell.entry_id" is ignored.

     cell or cell_esd may be NULL.

     If cell is NULL, the reciprocal cell parameters are not retrieved.

     If cell_esd is NULL, the reciprocal cell parameter esds are not
     retrieved.

     If the "cell" category is present, but some of the values are missing,
     zeros are returned for the missing values.

     ARGUMENTS

       handle     CBF handle.                                                 
       cell       Pointer to the destination array of 6 doubles for the       
                reciprocal cell parameters.                                   
       cell_esd   Pointer to the destination array of 6 doubles for the       
                reciprocal cell parameter esds.                               

     RETURN VALUE

     Returns an error code on failure or 0 for success. No errors is returned
     for missing values if the "cell" category exists.

     SEE ALSO

     2.4.50 cbf_get_unit_cell
     2.4.51 cbf_set_unit_cell
     2.4.53 cbf_set_reciprocal_cell
     2.4.54 cbf_compute_cell_volume
     2.4.55 cbf_compute_reciprocal_cell

     ----------------------------------------------------------------------

    2.4.53 cbf_set_reciprocal_cell

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_set_reciprocal_cell (cbf_handle handle, double cell[6], double
     cell_esd[6] );

     DESCRIPTION

     cbf_set_reciprocal_cell sets the reciprocal cell parameters to the
     double values given in cell[0:2] for the reciprocal cell edge lengths
     a*, b* and c* in AAngstroms-1, the double values given in cell[3:5] for
     the reciprocal cell angles a*, b* and g* in degrees, the double values
     given in cell_esd[0:2] for the estimated strandard deviations of the
     reciprocal cell edge lengths a*, b* and c* in AAngstroms, and the double
     values given in cell_esd[3:5] for the estimated standard deviations of
     the reciprocal cell angles a*, b* and g* in degrees.

     The values are placed in the first row of the "cell" category. If no
     value has been given for "_cell.entry_id", it is set to the value of the
     "diffrn.id" entry of the current data block.

     cell or cell_esd may be NULL.

     If cell is NULL, the reciprocal cell parameters are not set.

     If cell_esd is NULL, the reciprocal cell parameter esds are not set.

     If the "cell" category is not present, it is created. If any of the
     necessary columns are not present, they are created.

     ARGUMENTS

       handle     CBF handle.                                                 
       cell       Pointer to the array of 6 doubles for the reciprocal cell   
                parameters.                                                   
       cell_esd   Pointer to the array of 6 doubles for the reciprocal cell   
                parameter esds.                                               

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.4.50 cbf_get_unit_cell
     2.4.51 cbf_set_unit_cell
     2.4.52 cbf_get_reciprocal_cell
     2.4.54 cbf_compute_cell_volume
     2.4.55 cbf_compute_reciprocal_cell

     ----------------------------------------------------------------------

    2.4.54 cbf_compute_cell_volume

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_compute_cell_volume ( double cell[6], double *volume );

     DESCRIPTION

     cbf_compute_cell_volume sets *volume to point to the volume of the unit
     cell computed from the double values in cell[0:2] for the cell edge
     lengths a, b and c in AAngstroms and the double values given in
     cell[3:5] for the cell angles a, b and g in degrees.

     ARGUMENTS

       cell     Pointer to the array of 6 doubles giving the cell parameters. 
       volume   Pointer to the doubles for cell volume.                       

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.4.50 cbf_get_unit_cell
     2.4.51 cbf_set_unit_cell
     2.4.52 cbf_get_reciprocal_cell
     2.4.53 cbf_set_reciprocal_cell
     2.4.55 cbf_compute_reciprocal_cell

     ----------------------------------------------------------------------

    2.4.55 cbf_compute_reciprocal_cell

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_compute_reciprocal_cell ( double cell[6], double rcell[6] );

     DESCRIPTION

     cbf_compute_reciprocal_cell sets rcell to point to the array of
     reciprocal cell parameters computed from the double values cell[0:2]
     giving the cell edge lengths a, b and c in AAngstroms, and the double
     values cell[3:5] giving the cell angles a, b and g in degrees. The
     double values rcell[0:2] will be set to the reciprocal cell lengths a*,
     b* and c* in AAngstroms-1 and the double values rcell[3:5] will be set
     to the reciprocal cell angles a*, b* and g* in degrees.

     ARGUMENTS

       cell     Pointer to the array of 6 doubles giving the cell parameters. 
       rcell    Pointer to the destination array of 6 doubles giving the      
              reciprocal cell parameters.                                     
       volume   Pointer to the doubles for cell volume.                       

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     SEE ALSO

     2.4.50 cbf_get_unit_cell
     2.4.51 cbf_set_unit_cell
     2.4.52 cbf_get_reciprocal_cell
     2.4.53 cbf_set_reciprocal_cell
     2.4.54 cbf_compute_cell_volume

     ----------------------------------------------------------------------

    2.4.56 cbf_get_orientation_matrix, cbf_set_orientation_matrix

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_orientation_matrix (cbf_handle handle, double ub_matrix[9]);
     int cbf_set_orientation_matrix (cbf_handle handle, double ub_matrix[9]);

     DESCRIPTION

     cbf_get_orientation_matrix sets ub_matrix to point to the array of
     orientation matrix entries in the "diffrn" category in the order of
     columns:

                        "UB[1][1]" "UB[1][2]" "UB[1][3]"
                        "UB[2][1]" "UB[2][2]" "UB[2][3]"
                        "UB[3][1]" "UB[3][2]" "UB[3][3]"

     cbf_set_orientation_matrix sets the values in the "diffrn" category to
     the values pointed to by ub_matrix.

     ARGUMENTS

       handle     CBF handle.                                                 
       ubmatric   Source or destination array of 9 doubles giving the         
                orientation matrix parameters.                                

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_bin_sizes(cbf_handle handle, unsigned int element_number,
     double * slowbinsize, double * fastbinsize);
     int cbf_set_bin_sizes(cbf_handle handle, unsigned int element_number,
     double slowbinsize_in,double fastbinsize_in);

     DESCRIPTION

     cbf_get_bin_sizes sets slowbinsize to point to the value of the number
     of pixels composing one array element in the dimension that changes at
     the second-fastest rate and fastbinsize to point to the value of the
     number of pixels composing one array element in the dimension that
     changes at the fastest rate for the dectector element with the ordinal
     element_number. cbf_set_bin_sizes sets the the pixel bin sizes in the
     "array_intensities" category to the values of slowbinsize_in for the
     number of pixels composing one array element in the dimension that
     changes at the second-fastest rate and fastbinsize_in for the number of
     pixels composing one array element in the dimension that changes at the
     fastest rate for the dectector element with the ordinal element_number.

     In order to allow for software binning involving fractions of pixels,
     the bin sizes are doubles rather than ints.

     ARGUMENTS

       handle           CBF handle.                                           
       element_number   The number of the detector element counting from 0 by 
                      order of appearance in the "diffrn_data_frame"          
                      category.                                               
       slowbinsize      Pointer to the returned number of pixels composing    
                      one array element in the dimension that changes at the  
                      second-fastest rate.                                    
       fastbinsize      Pointer to the returned number of pixels composing    
                      one array element in the dimension that changes at the  
                      fastest rate.                                           
       slowbinsize_in   The number of pixels composing one array element in   
                      the dimension that changes at the second-fastest rate.  
       fastbinsize_in   The number of pixels composing one array element in   
                      the dimension that changes at the fastest rate.         

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

    2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise, cbf_get_reference_poise

     PROTOTYPE

     #include "cbf_simple.h"

     int cbf_get_axis_poise(cbf_handle handle, double ratio, double *
     vector1, double * vector2, double * vector3, double * offset1, double *
     offset2, double * offset3, double * angle, const char * axis_id, const
     char * frame_id);
     int cbf_get_goniometer_poise(cbf_goniometer goniometer, double ratio,
     double * vector1, double * vector2, double * vector3, double * offset1,
     double * offset2, double * offset3, double * angle);
     int cbf_get_axis_reference_poise(cbf_handle handle, double * vector1,
     double * vector2, double * vector3, double * offset1, double * offset2,
     double * offset3, const char * axis_id);

     DESCRIPTION

     cbf_get_axis_poise sets vector1, vector2, vector3 to point to the
     components of the axis vector for axis axis_id, offset1, offset2,
     offset3 to point to the components of the axis base offset vector for
     axis axis_id, and angle to point to the angle of rotation of axis
     axis_id after application of the axis settings for frame frame_id, using
     ratio, a value between 0 and 1, indicating how far into the internal
     motion in the frame to go. If frame_id is the string ".", the first
     frame found is used. If there is more than one frame, which frame will
     be found is indeterminate. If frame_id is NULL, the overall setting for
     the scan are used, rather than those for any particular frame. The
     vector and offset reported are the reference vector and offset of the
     axis axis_id transformed by application of all motions of the axes on
     which axis_id depends.

     cbf_get_goniometer_poise vector1, vector2, vector3 to point to the
     components of the axis vector for the goniometer axis, offset1, offset2,
     offset3 to point to the components of the axis base offset vector for
     the goniometer axis, and angle to point to the angle of rotation of the
     goniometer axis after application of all axis settings in the goniometer
     deriving the vector, offset and angle from the resulting matrix.
     Calculation of the vector is indeterminate if the angle is zero.

     cbf_get_axis_reference_poise sets vector1, vector2, vector3 to point to
     the components of the axis vector for axis axis_id, offset1, offset2,
     offset3 to point to the components of the axis base offset vector for
     axis axis_id unmodified by axis rotations. Any of the pointers may be
     specified as NULL.

     ARGUMENTS

       handle       CBF handle.                                               
       ratio        A number between 0 and 1 indication how far into the      
                  frame to go                                                 
       vector1      Pointer to the first component of the axis vector         
       vector2      Pointer to the second component of the axis vector        
       vector3      Pointer to the third component of the axis vector         
       offset1      Pointer to the first component of the axis offset         
       offset2      Pointer to the second component of the axis offset        
       offset3      Pointer to the third component of the axis offset         
       angle        Pointer to the rotation angle                             
       axis_id      The specified axis                                        
       frame_id     The specified frame                                       
       positioner   CBF goniometer                                            

     RETURN VALUE

     Returns an error code on failure or 0 for success.

     ----------------------------------------------------------------------

  2.5 F90 function interfaces

     At the suggestion of W. Kabsch, Fortran 90/95 routines have been added
     to CBFlib. As of this writing code has been written to allow the reading
     of CBF_BYTE_OFFSET, CBF_PACKED and CBF_PACKED_V2 binary images. This
     code has been gather into FCBlib (Fortran Crystallographic Binary
     library) as lib/libfcb.

     In general, most of the FCBlib functions return 0 for normal completion
     and a non-zero value in case of an error. In a few cases, such as
     FCB_ATOL_WCNT and FCB_NBLEN_ARRAY in order to conform to the conventions
     for commonly used C-equivalent functions, the function return is the
     value being computed.

     For each function, an interface is given to be included in the
     declarations of your Fortran 90/95 code. Some functions in FCBlIB are
     not intended for external use and are subject to change:
     FCB_UPDATE_JPA_POINTERS_I2, FCB_UPDATE_JPA_POINTERS_I4,
     FCB_UPDATE_JPA_POINTERS_3D_I2, FCB_UPDATE_JPA_POINTERS_3D_I4 and
     CNT2PIX. These names should not be used for user routines.

     The functions involving reading of a CBF have been done strictly in
     Fortran without the use of C code. This has required some compromises
     and the use of direct access I/O. Rather than putting the buffer and its
     control variables into COMMON these are passed as local arguments to
     make the routines inherently 'threadsafe' in a parallel programming
     environment. Note also, that a reading error could occur for the last
     record if it does not fill a full block. The code is written to recover
     from end-of-record and end-of-file errors, if possible. On many modern
     system, no special action is required, but on some systems it may be
     necessary to make use of the padding between the end of binary data and
     the terminal MIME boundary marker in binary sections. To ensure maximum
     portability of CBF files, a padding of 4095 bytes is recommended.
     Existing files without padding can be converted to files with padding by
     use of the new -p4 option for cif2cbf.

    2.5.1 FCB_ATOL_WCNT

       INTERFACE
       INTEGER(8) FUNCTION FCB_ATOL_WCNT(ARRAY, N, CNT)
       INTEGER(1),INTENT(IN):: ARRAY(N)
       INTEGER,   INTENT(IN):: N
       INTEGER,  INTENT(OUT):: CNT
       END FUNCTION
       END INTERFACE

     FCB_ATOL_WCNT converts INTEGER(1) bytes in ARRAY of N bytes to an
     INTEGER(8) value returned as the function value. The number of bytes of
     ARRAY actually used before encountering a character not used to form the
     number is returned in CNT.

     The scan stops at the first byte in ARRAY that cannot be properly parsed
     as part of the integer result.

     ARGUMENTS

       ARRAY   The array of INTEGER(1) bytes to be scanned       
       N       The INTEGER size of ARRAY                         
       CNT     The INTEGER size of the portion of ARRAY scanned. 

     RETURN VALUE

     Returns the INTEGER(8) value derived from the characters ARRAY(1:CNT)
     scanned.

     ----------------------------------------------------------------------

    2.5.2 FCB_CI_STRNCMPARR

       INTERFACE
       INTEGER FUNCTION FCB_CI_STRNCMPARR(STRING>, ARRAY, N, LIMIT)
       CHARACTER(LEN=*),INTENT(IN):: STRING>
       INTEGER,         INTENT(IN):: N, LIMIT
       INTEGER(1),      INTENT(IN):: ARRAY(N)
       END FUNCTION
       END INTERFACE

     The function FCB_CI_STRNCMPARR compares up to LIMIT characters of
     character string STRING and INTEGER(1) byte array ARRAY of dimension N
     in a case-insensitive manner, returning 0 for a match.

     ARGUMENTS

       STRING   A character string                                            
       ARRAY    The array of INTEGER(1) bytes to be scanned                   
       N        The INTEGER size of ARRAY                                     
       N        The INTEGER limit on the number of characters to consider in  
              the comparison                                                  

     RETURN VALUE

     Returns 0 if the string and array match, a non-zero value otherwise.

     ----------------------------------------------------------------------

    2.5.3 FCB_EXIT_BINARY

       INTERFACE
       INTEGER FUNCTION FCB_EXIT_BINARY(TAPIN,LAST_CHAR,FCB_BYTES_IN_REC,&
                                       BYTE_IN_FILE,REC_IN_FILE,BUFFER,  &
                                       PADDING )
       INTEGER,   INTENT(IN)   :: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE
       INTEGER(1),INTENT(INOUT):: LAST_CHAR,BUFFER(FCB_BYTES_IN_REC)
       INTEGER(8),INTENT(IN)   :: PADDING
       END FUNCTION
       END INTERFACE

     The function FCB_EXIT_BINARY is used to skip from the end of a binary
     section past any padding to the end of the text section that encloses
     the binary section. The values of the arguments must be consistent with
     those in the last call to FCB_NEXT_BINARY

     ARGUMENTS

       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       LAST_CHAR          The last character (as an INTEGER(1) byte) read.    
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                
       PADDING            The INTEGER(8) number of bytes of padding after the 
                        binary data and before the closing MIME boundary.     

     RETURN VALUE

     Returns 0 if the function is successful. Returns whatever non-zero error
     value is reported by FCB_READ_LINE if a necessary next line cannot be
     read.

     SEE ALSO

     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.9 FCB_READ_BYTE
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.4 FCB_NBLEN_ARRAY

       INTERFACE
       INTEGER FUNCTION FCB_NBLEN_ARRAY(ARRAY, ARRAYLEN)
       INTEGER,    INTENT(IN):: ARRAYLEN
       INTEGER(1), INTENT(IN):: ARRAY(ARRAYLEN)
       END FUNCTION
       END INTERFACE

     The function FCB_NBLEN_ARRAY returns the trimmed length of the
     INTEGER(1) byte array ARRAY of dimension ARRAYLEN after removal of
     trailing ASCII blanks, horizontal tabs (Z'09'), newlines (Z'0A') and
     carriage returns (Z'0D'). The resulting length may be zero.

     The INTEGER trimmed length is returned as the function value.

     ARGUMENTS

       ARRAY      The array of bytes for which the trimmed length is          
                required.                                                     
       ARRAYLEN   The dimension of the array of bytes to be scanned.          

     RETURN VALUE

     Returns the trimmed length of the array ARRAY.

     ----------------------------------------------------------------------

    2.5.5 FCB_NEXT_BINARY

       INTERFACE
       INTEGER FUNCTION FCB_NEXT_BINARY(TAPIN,LAST_CHAR,FCB_BYTES_IN_REC,&
                                       BYTE_IN_FILE,REC_IN_FILE,BUFFER,  &
                                       ENCODING,SIZE,ID,DIGEST,          &
                                       COMPRESSION,BITS,VORZEICHEN,REELL,&
                                       BYTEORDER,DIMOVER,DIM1,DIM2,DIM3, &
                                       PADDING )
       INTEGER,   INTENT(IN)   :: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE
       INTEGER(1),INTENT(INOUT):: LAST_CHAR,BUFFER(FCB_BYTES_IN_REC)
       INTEGER,   INTENT(OUT)  :: ENCODING
       INTEGER, INTENT(OUT)        :: SIZE    !Binary size
       INTEGER, INTENT(OUT)        :: ID      !Binary ID
       CHARACTER(len=*),INTENT(OUT):: DIGEST  !Message digest
       INTEGER,         INTENT(OUT):: COMPRESSION
       INTEGER,         INTENT(OUT):: BITS,VORZEICHEN,REELL
       CHARACTER(len=*),INTENT(OUT):: BYTEORDER
       INTEGER(8),      INTENT(OUT):: DIMOVER
       INTEGER(8),      INTENT(OUT):: DIM1
       INTEGER(8),      INTENT(OUT):: DIM2
       INTEGER(8),      INTENT(OUT):: DIM3
       INTEGER(8),      INTENT(OUT):: PADDING
       END FUNCTION
       END INTERFACE

     The function FCB_NEXT_BINARY skips to the start of the next binary
     section in the image file on unit TAPIN leaving the file positioned for
     a subsequent read of the image data. The skip may prior to the text
     field that contains the binary section. When the text filed is reached,
     it will be scanned for a MIME boundary marker, and, if it is found the
     subsequence MIME headers will be used to populate the arguments
     ENCODING, SIZE, ID, DIGEST, COMPRESSION, BITS, VORZEICHEN,REELL,
     BYTEORDER, DIMOVER, DIM1, DIM2,DIM3, PADDING.

     The value returned in ENCODING is taken from the MIME header
     Content-Transfer-Encoding as an INTEGER. It is returned as 0 if not
     specified. The reported value is one of the integer values ENC_NONE
     (Z'0001') for BINARY encoding, ENC_BASE64 (Z'0002') for BASE64 encoding,
     ENC_BASE32K (Z'0004') for X-BASE32K encoding, ENC_QP (Z'0008') for
     QUOTED-PRINTABLE encoding, ENC_BASE10 (Z'0010') for BASE10 encoding,
     ENC_BASE16 (Z'0020') for BASE16 encoding or ENC_BASE8 (Z'0040') for
     BASE8 encoding. At this time FCBlib only supports ENC_NONE BINARY
     encoding.

     The value returned in SIZE is taken from the MIME header X-Binary-Size
     as an INTEGER. It is returned as 0 if not specified.

     The value returned in ID is taken from the MIME header X-Binary-ID as an
     INTEGER. It is returned as 0 if not specified.

     The value returned in DIGEST is taken from the MIME header Content-MD5.
     It is returned as a character string. If no digest is given, an empty
     string is returned.

     The value returned in COMPRESSION is taken from the MIME header
     Content-Type in the conversions parameter. The reported value is one of
     the INTEGER values CBF_CANONICAL (Z'0050'), CBF_PACKED (Z'0060'),
     CBF_PACKED_V2 (Z'0090'), CBF_BYTE_OFFSET (Z'0070'), CBF_PREDICTOR
     (Z'0080'), CBF_NONE (Z'0040'). Two flags may be combined with CBF_PACKED
     or CBF_PACKED_V2: CBF_UNCORRELATED_SECTIONS (Z'0100') or CBF_FLAT_IMAGE
     (Z'0200'). At this time FCBlib does not support CBF_PREDICTOR or
     CBF_NONE compression.

     The values returned in BITS, VORZEICHEN and REELL are the parameters of
     the data types of the elements. These values are taken from the MIME
     header X-Binary-Element-Type, which has values of the form "signed
     BITS-bit integer", "unsigned BITS-bit integer", "signed BITS-bit real
     IEEE" or "signed BITS-bit complex IEEE". If no value is given, REELL is
     reported as -1. If the value in one of the integer types, REELL is
     reported as 0. If the value is one of the real or complex types, REELL
     is reported as 1. In the current release of FCBlib only the integer
     types for BITS equal to 16 or 32 are supported.

     The value returned in BYTEORDER is the byte order of the data in the
     image file as reported in the MIME header. The value, if specified, will
     be either the character string "LITTLE_ENDIAN" or the character string
     "BIG_ENDIAN". If no byte order is specified, "LITTLE_ENDIAN" is
     reported. This value is taken from the MIME header
     X-Binary-Element-Byte-Order. As of this writing, CBFlib will not
     generate "BIG_ENDIAN" byte-order files. However, both CBFlib and FCBlib
     read "LITTLE_ENDIAN" byte-order files, even on big-endian machines.

     The value returned in DIMOVER is the overall number of elements in the
     image array, if specified, or zero, if not specified. This value is
     taken from the MIME header X-Binary-Number-of-Elements. The values
     returned in DIM1, DIM2 and DIM3 are the sizes of the fastest changing,
     second fastest changing and third fastest changing dimensions of the
     array, if specified, or zero, if not specified. These values are taken
     from the MIME header X-Binary-Size-Fastest-Dimension,
     X-Binary-Size-Second-Dimension and X-Binary-Size-Third-Dimension
     respectively.

     The value returned in PADDING is the size of the post-data padding, if
     any, if specified or zero, if not specified. The value is given as a
     count of octets. This value is taken from the MIME header
     X-Binary-Size-Padding.

     ARGUMENTS

       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       LAST_CHAR          The last character (as an INTEGER(1) byte) read.    
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                
       ENCODING           INTEGER type of encoding for the binary section as  
                        reported in the MIME header.                          
       ID                 INTEGER binary identifier as reported in the MIME   
                        header.                                               
       SIZE               INTEGER size of compressed binary section as        
                        reported in the MIME header.                          
       DIGEST             The MD5 message digest as reported in the MIME      
                        header.                                               
       COMPRESSION        INTEGER compression method as reported in the MIME  
                        header.                                               
       BITS               INTEGER number of bits in each element as reported  
                        in the MIME header.                                   
       VORZEICHEN         INTEGER flag for signed or unsigned elements as     
                        reported in the MIME header. Set to 1 if the elements 
                        can be read as signed values, 0 otherwise.            
       REELL              INTEGER flag for real elements as reported in the   
                        MIME header. Set to 1 if the elements can be read as  
                        REAL                                                  
       BYTEORDER          The byte order as reported in the MIME header.      
       DIM1               Pointer to the destination fastest dimension.       
       DIM2               Pointer to the destination second fastest           
                        dimension.                                            
       DIM3               Pointer to the destination third fastest dimension. 
       PADDING            Pointer to the destination padding size.            

     RETURN VALUE

     Returns 0 if the function is successful. SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.9 FCB_READ_BYTE
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.6 FCB_OPEN_CIFIN

       INTERFACE
       INTEGER FUNCTION FCB_OPEN_CIFIN(FILNAM,TAPIN,LAST_CHAR,                &
       FCB_BYTES_IN_REC,BYTE_IN_FILE,REC_IN_FILE,BUFFER)
       CHARACTER(len=*),INTENT(IN) :: FILNAM
       INTEGER,         INTENT(IN) :: TAPIN,FCB_BYTES_IN_REC
       INTEGER(1),      INTENT(OUT):: LAST_CHAR
       INTEGER,         INTENT(OUT):: BYTE_IN_FILE,REC_IN_FILE
       INTEGER(1),    INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       INTEGER                        FCB_RECORD_SIZE
       END FUNCTION
       END INTERFACE

     The function FCB_OPEN_CIFIN opens the CBF image file given by the file
     name in the character string FILNAM on the logical unit TAPIN. The
     calling routine must provide an INTEGER(1) byte buffer BUFFER of some
     appropriate INTEGER size FCB_BYTES_IN_REC. The size must be chosen to
     suit the machine, but in most cases, 4096 will work. The values returned
     in LAST_CHAR, BYTE_IN_FILE, and REC_IN_FILE are for use in subsequent
     FCBlib I/O routines.

     The image file will be checked for the initial characters "###CBF: ". If
     there is no match the error value CBF_FILEREAD is returned.

     ARGUMENTS

       FILNAM             The character string name of the image file to be   
                        opened.                                               
       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       LAST_CHAR          The last character (as an INTEGER(1) byte) read.    
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                

     RETURN VALUE

     Returns 0 if the function is successful. SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.9 FCB_READ_BYTE
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4,
    FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4

       INTERFACE
       INTEGER FUNCTION FCB_DECOMPRESS_PACKED_I2 (ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2,  &
         TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,                   &
         REC_IN_FILE,BUFFER)
       INTEGER(2),  INTENT(OUT):: ARRAY(DIM1,DIM2)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN, COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

       INTERFACE
       INTEGER FUNCTION FCB_DECOMPRESS_PACKED_I4 (ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2,  &
         TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,                   &
         REC_IN_FILE,BUFFER)
        
       INTEGER(4),  INTENT(OUT):: ARRAY(DIM1,DIM2)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN, COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

       INTERFACE
       INTEGER FUNCTION FCB_DECOMPRESS_PACKED_3D_I2 (ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2, DIM3,  &
         TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,                   &
         REC_IN_FILE,BUFFER)
       INTEGER(2),  INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN, COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2,DIM3
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

       INTERFACE
       INTEGER FUNCTION FCB_DECOMPRESS_PACKED_3D_I4 (ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2, DIM3,  &
         TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,                   &
         REC_IN_FILE,BUFFER)
       INTEGER(4),  INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN, COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2,DIM3
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

     The functions FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4,
     FCB_DECOMPRESS_PACKED_3D_I2 and FCB_DECOMPRESS_PACKED_3D_I4, decompress
     images compress according the the CBF_PACKED or CBF_PACKED_V2
     compression described in section 3.3.2 on J. P. Abrahams CCP4 packed
     compression.

     The relevant function should be called immediately after a call to
     FCB_NEXT_BINARY, using the values returned by FCB_NEXT_BINARY to select
     the appropriate version of the function.

     ARGUMENTS

       ARRAY              The array to receive the image                      
       NELEM              The INTEGER(8) number of elements to be read        
       NELEM_READ         The INTEGER(8) returned value of the number of      
                        elements actually read                                
       ELSIGN             The INTEGER value of the flag for signed (1) OR     
                        unsigned (0) data                                     
       COMPRESSION        The compression of the image                        
       DIM1               The INTEGER(8) value of the fastest dimension of    
                        ARRAY                                                 
       DIM2               The INTEGER(8) value of the second fastest          
                        dimension                                             
       DIM3               The INTEGER(8) value of the third fastest dimension 
       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                

     RETURN VALUE

     Returns 0 if the function is successful.

     SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.9 FCB_READ_BYTE
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.8 FCB_READ_BITS

       INTERFACE
       INTEGER FUNCTION FCB_READ_BITS(TAPIN,FCB_BYTES_IN_REC,BUFFER,     &
                      REC_IN_FILE,BYTE_IN_FILE,BCOUNT,BBYTE,             &
                      BITCOUNT,IINT,LINT)
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       INTEGER,   INTENT(INOUT):: BCOUNT
       INTEGER(1),INTENT(INOUT):: BBYTE
       INTEGER,      INTENT(IN):: BITCOUNT
       INTEGER,      INTENT(IN):: LINT
       INTEGER(4),  INTENT(OUT):: IINT(LINT)
       END FUNCTION
       END INTERFACE

     The function FCB_READ_BITS gets the integer value starting at
     BYTE_IN_FILE from file TAPIN continuing through BITCOUNT bits, with sign
     extension. BYTE_IN_FILE is left at the entry value and not incremented.
     The resulting, sign-extended integer value is stored in the INTEGER(4)
     array IINT of dimension LINT with the least significant portion in
     IINT(1).

     ARGUMENTS

       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       BCOUNT             The INTEGER count of bits remaining unused from the 
                        last call to FCB_READ_BITS.                           
       BBYTE              The INTEGER(1) byte containing the unused bits from 
                        the last call to FCB_READ_BITS.                       
       BITCOUNT           The INTEGER count of the number of bits to be       
                        extracted from the image file.                        
       IINT               The INTEGER(4) array into which to store the value  
                        extracted from the image file.                        
       LINT               The INTEGER length of the array IINT.               

     RETURN VALUE

     Returns 0 if the function is successful. Because of the use of direct
     access I/O in blocks of size FCB_BYTES_IN_REC the precise location of
     the end of file may not be detected.

     SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.9 FCB_READ_BYTE
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.9 FCB_READ_BYTE

       INTERFACE
       INTEGER FUNCTION FCB_READ_BYTE(TAPIN,FCB_BYTES_IN_REC,BUFFER,     &
                              REC_IN_FILE,BYTE_IN_FILE,IBYTE)
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       INTEGER(1),  INTENT(OUT):: IBYTE
       END FUNCTION
       END INTERFACE

     The function FCB_READ_BYTE reads the byte at the position BYTE_IN_FILE
     in the image file TAPIN. The first byte in the file is at BYTE_IN_FILE =
     1. BYTE_IN_FILE should be set to the desired value before the call to
     the function and is not incremented within the function.

     The function attempts to suppress the error caused by a read of a short
     last record, and in most systems cannot determine the exact location of
     the end of the image file, returning zero bytes until the equivalent of
     a full final record has been read.

     ARGUMENTS

       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       IBYTE              The INTEGER(1) byte found in the image file at the  
                        byte position BYTE_IN_FILE.                           

     RETURN VALUE

     Returns 0 if the function is successful. Because of the use of direct
     access I/O in blocks of size FCB_BYTES_IN_REC the precise location of
     the end of file may not be detected.

     SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.9 FCB_READ_BITS
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4, FCB_READ_IMAGE_3D_I2,
    FCB_READ_IMAGE_3D_I4

       INTERFACE
       INTEGER FUNCTION FCB_READ_IMAGE_I2(ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2,                         &
         PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,             &
         REC_IN_FILE,BUFFER)
      
       INTEGER(2),  INTENT(OUT):: ARRAY(DIM1,DIM2)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN
       INTEGER,     INTENT(OUT):: COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2
       INTEGER(8),  INTENT(OUT):: PADDING
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

       INTERFACE
       INTEGER FUNCTION FCB_READ_IMAGE_I4(ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2,                         &
         PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,             &
         REC_IN_FILE,BUFFER)
       INTEGER(4),  INTENT(OUT):: ARRAY(DIM1,DIM2)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN
       INTEGER,     INTENT(OUT):: COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2
       INTEGER(8),  INTENT(OUT):: PADDING
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

       INTERFACE
       INTEGER FUNCTION FCB_READ_IMAGE_3D_I2(ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2, DIM3,                      &
         PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,                &
         REC_IN_FILE,BUFFER)
       INTEGER(2),  INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN
       INTEGER,     INTENT(OUT):: COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2,DIM3
       INTEGER(8),  INTENT(OUT):: PADDING
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

       INTERFACE
       INTEGER FUNCTION FCB_READ_IMAGE_3D_I4(ARRAY,NELEM,NELEM_READ, &
         ELSIGN, COMPRESSION, DIM1, DIM2, DIM3,                      &
         PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE,                &
         REC_IN_FILE,BUFFER)
       INTEGER(4),  INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
       INTEGER(8),  INTENT(OUT):: NELEM_READ
       INTEGER(8),   INTENT(IN):: NELEM
       INTEGER,      INTENT(IN):: ELSIGN
       INTEGER,     INTENT(OUT):: COMPRESSION
       INTEGER(8),   INTENT(IN):: DIM1,DIM2,DIM3
       INTEGER(8),  INTENT(OUT):: PADDING
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
       INTEGER,   INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
       END FUNCTION
       END INTERFACE

     The function FCB_READ_IMAGE_I2 reads a 16-bit twos complement INTEGER(2)
     2D image. The function FCB_READ_IMAGE_I4 read a 32-bit twos complement
     INTEGER(4) 2D image. The function FCB_READ_IMAGE_3D_I2 reads a 16-bit
     twos complement INTEGER(2) 3D image. The function FCB_READ_IMAGE_3D_I4
     reads a 32-bit twos complement INTEGER(4) 3D image. In each case the
     image is compressed either by a BYTE_OFFSET algorithm by W. Kabsch based
     on a proposal by A. Hammersley or by a PACKED algorithm by J. P.
     Abrahams as used in CCP4, with modifications by P. Ellis and H. J.
     Bernstein.

     The relevant function automatically first calls FCB_NEXT_BINARY to skip
     to the next binary section and then starts to read. An error return will
     result if the parameters of this call are inconsistent with the values
     in MIME header.

     ARGUMENTS

       ARRAY              The array to receive the image                      
       NELEM              The INTEGER(8) number of elements to be read        
       NELEM_READ         The INTEGER(8) returned value of the number of      
                        elements actually read                                
       ELSIGN             The INTEGER value of the flag for signed (1) OR     
                        unsigned (0) data                                     
       COMPRESSION        The actual compression of the image                 
       DIM1               The INTEGER(8) value of the fastest dimension of    
                        ARRAY                                                 
       DIM2               The INTEGER(8) value of the second fastest          
                        dimension                                             
       DIM3               The INTEGER(8) value of the third fastest dimension 
       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN                

     RETURN VALUE

     Returns 0 if the function is successful.

     SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.7 FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2,
     FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
     FCB_DECOMPRESS_PACKED_3D_I4
     2.5.9 FCB_READ_BYTE
     2.5.11 FCB_READ_LINE

     ----------------------------------------------------------------------

    2.5.11 FCB_READ_LINE

       INTERFACE
       INTEGER FUNCTION FCB_READ_LINE(TAPIN,LAST_CHAR,FCB_BYTES_IN_REC,  &
                          BYTE_IN_FILE,REC_IN_FILE,BUFFER,LINE,N,LINELEN)
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC,N
       INTEGER,   INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE
       INTEGER,     INTENT(OUT):: LINELEN
       INTEGER(1),INTENT(INOUT):: LAST_CHAR,BUFFER,(FCB_BYTES_IN_REC)
       INTEGER(1),  INTENT(OUT):: LINE(N)
       END FUNCTION
       END INTERFACE

     The function FCB_READ_LINE reads successive bytes into the INTEGER(1)
     byte array LINE of dimension N), stopping at N bytes or the first error
     or the first CR (Z'0D') or LF (Z'0A'), whichever comes first. It
     discards an LF after a CR. The variable LAST_CHAR is checked for the
     last character from the previous line to make this determination.

     The actual number of bytes read into the line, not including any
     terminal CR or LF is stored in LINELEN.

     ARGUMENTS

       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       LAST_CHAR          The INTEGER(1) byte holding the ASCII value of the  
                        last character read for each line read.               
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN.               
       LINE               The INTEGER(1) array of length N to hold the line   
                        to be read from TAPIN.                                
       N                  The INTEGER dimension of LINE.                      
       LINELEN            The INTEGER number of characters read into LINE.    

     RETURN VALUE

     Returns 0 if the function is successful.

     SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.7 FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2,
     FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
     FCB_DECOMPRESS_PACKED_3D_I4
     2.5.9 FCB_READ_BYTE

    2.5.12 FCB_READ_XDS_I2

       INTERFACE
       INTEGER FUNCTION FCB_READ_XDS_I2(FILNAM,TAPIN,NX,NY,IFRAME,JFRAME)
       CHARACTER(len=*),INTENT(IN) :: FILNAM
       INTEGER,         INTENT(IN) :: TAPIN,NX,NY
       INTEGER(2),      INTENT(OUT):: IFRAME(NX*NY)
       INTEGER(4),      INTENT(OUT):: JFRAME(NX,NY)
       END FUNCTION
       END INTERFACE

     The function FCB_READ_XDS_I2 read a 32-bit integer twos complement image
     into a 16-bit INTEGER(2) XDS image using the CBF_BYTE_OFFSET, CBF_PACKED
     or CBF_PACKED_V2 compressions for the 32-bit data. The BYTE_OFFSET
     algorithm is a variant of the September 2006 version by W. Kabsch which
     was based on a suggestion by A. Hammersley and which was further
     modified by H. Bernstein.

     The file named FILNAM is opened on the logical unit TAPIN and
     FCB_NEXT_BINARY is used to skip to the next binary image. The binary
     image is then decompressed to produce an XDS 16-bit integer image array
     IFRAME which is NX by NY. The dimensions must agree with the dimensions
     specified in MIME header.

     The conversion from a 32-bit integer I32 to 16-bit XDS pixel I16 is done
     as per W. Kabsch as follows: The value I32 is limited to the range -1023
     =< I32 =< 1048576. If I32 is outside that range it is truncated to the
     closer boundary. The generate I16, the 16-bit result, if I32 > 32767, it
     is divided by 32 (producing a number between 1024 and 32768), and then
     negated (producing a number between -1024 and -32768).

     For CBF_BYTE_OFFSET this conversion can be done on the fly directly into
     the target array IFRAME, but for the CBF_PACKED or CBF_PACKED_V2, the
     full 32 bit precision is needed during the decompression, forcing the
     use of an intermediate INTEGER(4) array JFRAME to hold the 32-bit image
     in that case.

     The image file is closed after reading one image.

     ARGUMENTS

       FILNAM   The character string name of the image file to be opened.     
       TAPIN    The INTEGER Fortran device unit number assigned to image      
              file.                                                           
       NX       The INTEGER fast dimension of the image array.                
       NY       The INTEGER slow dimension of the image array.                
       IFRAME   The INTEGER(2) XDS image array.                               
       JFRAME   The INTEGER(4) 32-bit image scratch array needed for          
              CBF_PACKED or CBF_PACKED_V2 images.                             

     RETURN VALUE

     Returns 0 if the function is successful, CBF_FORMAT (=1) if it cannot
     handle this CBF format (not implemented), -1 if it cannot determine
     endian architecture of this machine, -2: if it cannot open the image
     file, -3: if it finds the wrong image format and -4 if it cannot read
     the image.

     ----------------------------------------------------------------------

    2.5.13 FCB_SKIP_WHITESPACE

       INTERFACE
       INTEGER FUNCTION FCB_SKIP_WHITESPACE(TAPIN,LAST_CHAR,             &
                        FCB_BYTES_IN_REC,BYTE_IN_FILE,REC_IN_FILE,BUFFER,&
                        LINE,N,LINELEN,ICUR,FRESH_LINE)
       INTEGER,      INTENT(IN):: TAPIN,FCB_BYTES_IN_REC,N
       INTEGER,   INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE,LINELEN,ICUR, &
                                  FRESH_LINE
       INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC),LINE(N),      &
                                  LAST_CHAR
       END INTERFACE

     The function FCB_SKIP_WHITESPACE skips forward on the current INTEGER(1)
     byte array LINE of size N with valid data in LINE(1:LINELEN) from the
     current position ICUR moving over MIME header whitespace and comments,
     reading new lines into LINE if needed. The flag FRESH_LINE indicates
     that a fresh line should be read on entry.

     ARGUMENTS

       TAPIN              The INTEGER Fortran device unit number assigned to  
                        image file.                                           
       LAST_CHAR          The INTEGER(1) byte holding the ASCII value of the  
                        last character read for each line read.               
       FCB_BYTES_IN_REC   The INTEGER number of bytes in a record.            
       BYTE_IN_FILE       The INTEGER byte (counting from 1) of the byte to   
                        read.                                                 
       REC_IN_FILE        The INTEGER record number (counting from 1) of next 
                        record to read.                                       
       BUFFER             The INTEGER(1) array of length FCB_BYTES_IN_REC to  
                        hold the appropriate record from TAPIN.               
       LINE               The INTEGER(1) array of length N to hold the line   
                        to be read from TAPIN.                                
       N                  The INTEGER dimension of LINE.                      
       LINELEN            The INTEGER number of characters read into LINE.    
       ICUR               The INTEGER position within the line.               
       FRESH_LINE         The INTEGER flag that a fresh line is needed.       

     RETURN VALUE

     Returns 0 if the function is successful.

     SEE ALSO

     2.5.3 FCB_EXIT_BINARY
     2.5.5 FCB_NEXT_BINARY
     2.5.6 FCB_OPEN_CIFIN
     2.5.7 FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2,
     FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
     FCB_DECOMPRESS_PACKED_3D_I4
     2.5.9 FCB_READ_BYTE

     ----------------------------------------------------------------------

2.6 HDF5 abstraction layer and convenience functions

     The HDF5 abstraction layer mostly follows the HDF5 naming convention of
     H5Xfunction_name, where X is usually a single letter identifying the
     section of the API that the function resides in. A cbf_ prefix is used
     on all functions to avoid naming conflicts and make it clear that all
     these functions use the CBFlib error handling method whenever an error
     may occur.

     The main purpose of this API is to not to reimplement the HDF5 API, but
     to make common HDF5-related tasks easier when working with HDF5 files
     within CBFlib. The API therefore doesn't attempt to cover every possible
     use of HDF5, but to simplify common tasks. Use of the HDF5 API is not
     unexpected in library or user code, but functions in this section should
     be preferred in order to reduce development time and the amount of
     debugging required. A relatively comprehensive test program is provided,
     this should be used to verify that the functions in this section of the
     API are performing as expected and can be used as a source of example
     code.

     This section describes functions available for working with:

       * Attributes:
            * 2.6.1 cbf_H5Acreate
            * 2.6.2 cbf_H5Afind
            * 2.6.3 cbf_H5Aread
            * 2.6.4 cbf_H5Aread_string
            * 2.6.5 cbf_H5Awrite
            * 2.6.6 cbf_H5Arequire_cmp2
            * 2.6.7 cbf_H5Arequire_cmp2_ULP
            * 2.6.8 cbf_H5Arequire_string
            * 2.6.9 cbf_H5Afree
       * Datasets:
            * 2.6.10 cbf_H5Dcreate
            * 2.6.11 cbf_H5Dfind2
            * 2.6.12 cbf_H5Drequire
            * 2.6.13 cbf_H5Dinsert
            * 2.6.14 cbf_H5Dset_extent
            * 2.6.15 cbf_H5Dwrite2
            * 2.6.16 cbf_H5Dread2
            * 2.6.17 cbf_H5Drequire_scalar_F64LE2
            * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
            * 2.6.19 cbf_H5Drequire_flstring
            * 2.6.20 cbf_H5Dfree
       * Files:
            * 2.6.21 cbf_H5Fopen
            * 2.6.22 cbf_H5Fclose
       * Groups:
            * 2.6.23 cbf_H5Gcreate
            * 2.6.24 cbf_H5Gfind
            * 2.6.25 cbf_H5Grequire
            * 2.6.26 cbf_H5Gfree
       * Identifiers:
            * 2.6.27 cbf_H5Ivalid
       * Objects:
            * 2.6.28 cbf_H5Ocmp
            * 2.6.29 cbf_H5Ofree
       * Dataspaces:
            * 2.6.30 cbf_H5Screate
            * 2.6.31 cbf_H5Sfree
       * Datatypes:
            * 2.6.32 cbf_H5Tcreate_string
            * 2.6.33 cbf_H5Tfree

    Rank of a dataset

     Where a rank is required it must be equal to the length of the dim, max
     & chunk parameters, if they are given, and should be:

       * 0, for scalar data
       * 1, for vector data
       * 2, for matrix data
       * 3, for volume data
       * etc...

     The maximum rank is defined by the HDF5 library, a negative rank makes
     no sense and will often be treated as an error.

    HDF5-specific datatypes

     Any type parameters defining types for data stored in a file should
     usually be a value returned by cbf_H5Tcreate_string or one of the
     standard or IEEE types:

     H5T_STD_I8LE   H5T_STD_I16LE  H5T_STD_I32LE  H5T_STD_I64LE  
     H5T_STD_U8LE   H5T_STD_U16LE  H5T_STD_U32LE  H5T_STD_U64LE  
     H5T_STD_I8BE   H5T_STD_I16BE  H5T_STD_I32BE  H5T_STD_I64BE  
     H5T_STD_U8BE   H5T_STD_U16BE  H5T_STD_U32BE  H5T_STD_U64BE  
     H5T_IEEE_F32LE H5T_IEEE_F64LE H5T_IEEE_F32BE H5T_IEEE_F64BE 

     Any type parameters defining types for data stored in memory should
     usually be a value returned by cbf_H5Tcreate_string or one of the native
     types:

H5T_NATIVE_SCHAR H5T_NATIVE_SHORT  H5T_NATIVE_INT     H5T_NATIVE_LONG  H5T_NATIVE_LLONG  
H5T_NATIVE_UCHAR H5T_NATIVE_USHORT H5T_NATIVE_UINT    H5T_NATIVE_ULONG H5T_NATIVE_ULLONG 
H5T_NATIVE_FLOAT H5T_NATIVE_DOUBLE H5T_NATIVE_LDOUBLE 

     Functions are rarely (if ever) limited to the above values, and can take
     any valid HDF5 datatype. The above is not a complete list of all
     available types, check the HDF5 documentation for such a list if you
     need one.

    Comparing data

     Some of the functions in this section will require a comparison function
     and some comparison parameters to be provided. The function should
     return zero if the data in the two arrays are considered equal and
     non-zero otherwise, note that this is the same as C's strcmp(). The
     signature of the comparison functions used here is:

     int compare (const void * expected, const void * existing, size_t
     length, const void * params)

     This will be called with:

         Type       Name                      Description                     
     const void * expected A pointer to the array of requested values that    
                           was passed to the function.                        
     const void * existing An array of existing values read from the object.  
     size_t       length   The length of the expected and existing arrays.    
     const void * params   A pointer to the comparison parameters which were  
                           passed to the calling function.                    

     The comparison parameters allow more complex comparisons to be
     performed, such as a check that the numbers are 'close enough' as
     determined by some variable measure of closeness. It is the caller's
     responsibility to ensure that the comparison function is appropriate for
     the type of data expected and that params is of the appropriate type for
     the comparison function. The parameters expected and existing should
     normally be cast to the appropriate type before being used.

     An example function for comparing ints, taken from the implementation of
     CBFlib:

 /*
 Compare two arrays of ints.
 Most parameters are defined as being 'const' even though
 the expected signature allows them to be mutable.
 */
 int cmp_int
     (const void * const expected,
      const void * const existing,
      size_t length,
      const void * const params)
 {
     /*
     Cast the array pointers to the appropriate type, preserving the const-ness of the data.
     I won't be using any parameters for this comparison, so just ignore that argument.
     */
     const int * A = expected;
     const int * B = existing;

     /*
     Iterate through the arrays comparing each element and decrementing a counter.
     If any are not equal the loop will exit early with length being non-zero.
     */
     while (length && *A++ == *B++) --length;

     /*
     Return a value indicating whether the arrays are equal.
     */
     return length;
 }

     Some older functions use a simpler 3-argument comparison function, which
     doesn't have a parameter that can be used to pass some extra information
     to or retrieve information from the function.

     ----------------------------------------------------------------------

    2.6.1 cbf_H5Acreate

     Create a new attribute.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Acreate (const hid_t location, hid_t *const attr, const char
     *const name, const hid_t type, const hid_t space)

     DESCRIPTION

     Creates a new attribute of the object location with name given by name,
     optionally returning it in the attr variable. An error will occur if a
     similarly named attribute already exists.

     ARGUMENTS

     location The hdf5 group/file in which to put the attribute.              
              A pointer to a HDF5 object identifier that is set to the        
     attr     location of a valid object if the function succeeds, otherwise  
              is left untouched.                                              
     name     The name of the existing/new dataset.                           
     type     The type of data to be stored in the attribute.                 
     space    The dataspace of the attribute.                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.2 cbf_H5Afind

     Try to locate an existing attribute.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Afind (const hid_t location, hid_t *const attr, const char
     *const name, const hid_t type, const hid_t space)

     DESCRIPTION

     Checks for the existance of an attribute with the given name at location
     with a datatype of type and dataspace of space. Will return CBF_NOTFOUND
     if it cannot be found, or open it if it already exists.

     If type is not a datatype then no check of the attribute datatype will
     be done. If space is not a dataspace then no checks of the attribute
     dataspace wil be done.

     ARGUMENTS

     location The hdf5 group/file in which to put the attribute.              
              A pointer to a HDF5 object identifier that is set to the        
     attr     location of a valid object if the function succeeds, otherwise  
              is left untouched.                                              
     name     The name of the existing/new attribute.                         
     type     The type of data stored in the attribute, or an invalid         
              identifier if it should not be checked.                         
     space    The dataspace of the attribute, or an invalid identifier if it  
              should not be checked.                                          

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.3 cbf_H5Aread

     Read an entire attribute from a file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Aread (const hid_t attr, const hid_t type, void *const buf)

     DESCRIPTION

     Reads all of the data from attr into buf, which should have been
     allocated as the native type indicated by mem_type.

     ARGUMENTS

     attr A valid hdf5 handle for an attribute.        
     type The type of data in memory.                  
     buf  The location where the data is to be stored. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.4 cbf_H5Aread_string

     Read an entire string attribute from a file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Aread_string (const hid_t attr, const char **const val)

     DESCRIPTION

     Read a string attribute into memory, returning a pointer that must be
     free'd by the caller in val.

     ARGUMENTS

     attr The attribute to read from.                    
     val  A pointer to a place the string may be stored. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.5 cbf_H5Awrite

     Write an entire attribute to a file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Awrite (const hid_t attr, const hid_t type, void *const buf)

     DESCRIPTION

     Writes all of the data from buf, which should contain data if the type
     indicated by mem_type, into attr.

     ARGUMENTS

     attr A valid hdf5 handle for an attribute.  
     type The type of data in memory.            
     buf  The address of the data to be written. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.6 cbf_H5Arequire_cmp2

     Check for an attribute with the given space/type/value, or set one if it
     doesn't exist.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Arequire_cmp2 (const hid_t ID, const char * const name, const
     int rank, const hsize_t * const dim, const hid_t fileType, const hid_t
     memType, const void *const value, void *const buf, int(*cmp)(const void
     *, const void *, size_t))

     DESCRIPTION

     Checks the existance of an attribute of the given name, size, type and
     value. Equal value is determined by a custom comparison function which
     may use some extra data for more sophisticated tests. A new attribute
     with the given properties will be created if none currently exist, the
     function will fail if an incompatible attribute exists.

     ARGUMENTS

     ID       The HDF5 object that the attribute will be applied to.          
     name     The name of the attribute.                                      
     rank     The number of dimensions of the attribute data, 0 for scalar    
              data.                                                           
     dim      The length of each dimension, not used for scalar data.         
     fileType The HDF5 type of the attribute data in the file.                
     memType  The HDF5 type of the attribute data in memory.                  
     value    The data to be written to the attribute.                        
     buf      A buffer to be used when reading an existing attribute of the   
              same size.                                                      
     cmp      A comparison function to test if a previously set value is      
              equal to the value I asked for.                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.7 cbf_H5Arequire_cmp2_ULP

     Check for an attribute with the given space/type/value, or set one if it
     doesn't exist.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Arequire_cmp2_ULP (const hid_t ID, const char *const name,
     const int rank, const hsize_t * const dim, const hid_t fileType, const
     hid_t memType, const void *const value, void *const buf, int(*cmp)(const
     void *, const void *, size_t, const void *), const void *const
     cmp_params)

     DESCRIPTION

     Checks the existance of an attribute of the given name, size, type and
     value. Equal value is determined by a custom comparison function which
     may use some extra data for more sophisticated tests. A new attribute
     with the given properties will be created if none currently exist, the
     function will fail if an incompatible attribute exists.

     ARGUMENTS

     ID         The HDF5 object that the attribute will be applied to.        
     name       The name of the attribute.                                    
     rank       The number of dimensions of the attribute data, 0 for scalar  
                data.                                                         
     dim        The length of each dimension, not used for scalar data.       
     fileType   The HDF5 type of the attribute data in the file.              
     memType    The HDF5 type of the attribute data in memory.                
     value      The data to be written to the attribute.                      
     buf        A buffer to be used when reading an existing attribute of the 
                same size.                                                    
     cmp        A comparison function to test if a previously set value is    
                equal to the value I asked for.                               
     cmp_params A pointer to a data structure which may be used by the        
                comparison function.                                          

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.8 cbf_H5Arequire_string
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.8 cbf_H5Arequire_string

     Check for a scalar string attribute with a given value, or set one if it
     doesn't exist.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Arequire_string (const hid_t location, const char *const name,
     const char *const value)

     DESCRIPTION

     Forwarding function that calls cbf_H5Arequire_cmp2_ULP with the
     appropriate arguments to compare two strings. The strcmp function is
     used for string comparison, with a small wrapper to verify array length:

 /** a possible implementation of a function to compare two strings for equality */
 static int cmp_string
     (const void * const a,
      const void * const b,
      const size_t N,
      const void * const params)
 {
     /* first ensure the arrays have one element each */
     if (1 != N) return 1;
     /* then forward to 'strcmp' for the actual comparison */
     else return strcmp(a,b);
 }

     ARGUMENTS

     location HDF5 object to which the string attribute should/will belong. 
     name     The name of the attribute.                                    
     value    The value which the attribute should/will have.               

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.9 cbf_H5Afree

     ----------------------------------------------------------------------

    2.6.9 cbf_H5Afree

     Close a HDF5 attribute.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Afree (const hid_t ID)

     DESCRIPTION

     Attempt to close an attribute, but don't modify the identifier that
     described it.

     ARGUMENTS

     ID The HDF5 attribute to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.1 cbf_H5Acreate
       * 2.6.2 cbf_H5Afind
       * 2.6.3 cbf_H5Aread
       * 2.6.4 cbf_H5Aread_string
       * 2.6.5 cbf_H5Awrite
       * 2.6.6 cbf_H5Arequire_cmp2
       * 2.6.7 cbf_H5Arequire_cmp2_ULP
       * 2.6.8 cbf_H5Arequire_string

     ----------------------------------------------------------------------

    2.6.10 cbf_H5Dcreate

     Creates a new dataset in the given location.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dcreate (const hid_t location, hid_t * const dataset, const
     char * const name, const int rank, const hsize_t * const dim, const
     hsize_t * const max, const hsize_t * const chunk, const hid_t type)

     DESCRIPTION

     The dataset parameter gives a location to store the dataset for use by
     the caller, for example to add an attribute to it. If non-zero the
     returned handle MUST be free'd by the caller with cbf_H5Dfree.

     The dimensions of the dataset to create are given in dim. The maximum
     extents of the dataset are given in max, which uses the values in dim as
     defaults if set to a null pointer. Each element of max must be at least
     as large as the corresponding element of dim. The dataset created will
     be a fixed-size dataset unless one of the elements of max is set to
     H5S_UNLIMITED.

     A chunk size must be given in the chunk argument if any element of max
     is set to H5S_UNLIMITED or is greater than the corresponding element of
     dim. If the dataset should not be chunked then a null pointer should be
     given.

     The dim, max and chunk arrays - if given - must each contain rank
     elements.

     This function will fail if a link with the same name already exists in
     location.

     ARGUMENTS

     location The hdf5 group/file in which to put the dataset.                
     dataset  An optional pointer to a location where the dataset handle      
              should be stored.                                               
     name     The name of the new dataset.                                    
     rank     The rank of the data.                                           
     dim      The dimensions of the dataset to create. Unused if rank == 0.   
     max      The maximum size of each dimension. Unused if rank == 0.        
     chunk    The chunk size for the dataset.                                 
     type     The type of each data element in the file.                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.11 cbf_H5Dfind2

     Look for a dataset with the given properties.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dfind2 (const hid_t location, hid_t *const dataset, const char
     *const name, const int rank, const hsize_t *const max, hsize_t *const
     buf, const hid_t type)

     DESCRIPTION

     Returns CBF_NOTFOUND without modifying dataset if no dataset exists and
     fails without modifying dataset if one with different properties exists.
     A dataset will be 'found' if it has the same name and a maximum size
     which is at least as big as the size requested in max.

     A buffer of rank elements pointed to by buf may be used to store the
     array of maximum extents for a potentially matching dataset, in order to
     avoid the use of malloc & free for very small amounts of memory.

     Use as:

 /* Get the return code from the function call, */
 const int found = cbf_H5Dfind(location, &dataset, ...);
 /* and check what it was: */
 if (CBF_SUCCESS==found) {
     /* A dataset already existed and I have a handle for it: */
     use_existing_dataset(dataset);
 } else if (CBF_NOTFOUND==found) {
     /* No matching dataset existed, so I can create one: */
     cbf_H5Dcreate(location, &dataset, ...);
     use_new_datset(dataset);
 } else {
     /*
     The function call failed, do something with the error.
     In this case, store it for later use and print a message.
     */
     error |= found;
      cbf_debug_print(cbf_strerror(error));
 }
 /* clean up: */
 cbf_H5Dfree(dataset);

     ARGUMENTS

     location The hdf5 group/file in which to put the dataset.                
              A pointer to a HDF5 object identifier that is set to the        
     dataset  location of a valid object if the function succeeds, otherwise  
              is left in an undefined state.                                  
     name     The name of the existing/new dataset.                           
     rank     The rank of the data, must be equal to the length of the max    
              and buf arrays, if they are given.                              
              The (optional) maximum size of each dimension, pointer or an    
     max      array of length rank where 0 <= max[i] <= H5S_UNLIMITED for i = 
              [0, rank), unused if rank == 0.                                 
              An optional buffer with rank elements which may be used to      
     buf      store the current maximum dimensions of a potential match to    
              avoid a malloc/free call.                                       
     type     The type of each data element in the file. If an invalid type   
              is given a dataset of any type may be returned.                 

     RETURN VALUE

     CBF_SUCCESS if a matching dataset was found, CBF_NOTFOUND if nothing
     with the same name was found, some other error code otherwise.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.12 cbf_H5Drequire

     Ensure that a dataset exists, returning a handle to an existing dataset
     or creating a new dataset if needed.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Drequire (const hid_t location, hid_t * const dataset, const
     char * const name, const int rank, const hsize_t * const max, const
     hsize_t * const chunk, hsize_t * const buf, const hid_t type)

     DESCRIPTION

     Ensure a dataset of the given rank exists and can hold at least as many
     elements as specified in max. If no dataset exists then one will be
     created with dimensions of [0, 0, ... 0]. cbf_H5Dfind and cbf_H5Dcreate
     are used in the implementation of this function.

     An existing dataset may be found using cbf_H5Dfind2(location, dataset,
     name, rank, max, buf, type). If no dataset can be found then a dataset
     will be created by setting each element of a buffer of length rank to
     zero and using cbf_H5Dcreate(location, dataset, name, rank, buffer, max,
     chunk, type). A buffer of rank elements may be provided to avoid using
     malloc to allocate memory for a small array whose size may already be
     known.

     The value pointed to by dataset should be a valid object identifier if
     the function exits successfully, and will be left in an undefined state
     otherwise.

     This is roughly equivalent to:

 const int error = cbf_H5Dfind2(location, dataset, name, rank, max, buf, type);
 if (CBF_NOTFOUND==error) {
         int i;
         for (i = 0; i != rank; ++i) buf[i] = 0;
         return cbf_H5Dcreate(location, dataset, name, rank, buf, max, chunk, type);
 } else {
         /* 'error' may be 'CBF_SUCCESS' or could indicate an error: */
         return error;
 }

     but contains more sophisticated error handling code and allows for some
     parameters to be omitted.

     ARGUMENTS

     location The hdf5 group/file in which to put the dataset.                
     dataset  A pointer to a location to store the dataset.    
     name     The name of the existing/new dataset.                           
     rank     The rank of the data.                            
     max      The (optional) maximum size of each dimension.   
     chunk    The chunk size used if creating a new dataset.   
     buf      An optional buffer with rank elements.           
     type     The type of each data element in the file.                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.13 cbf_H5Dinsert

     Add some data to a datset, expanding the dataset to the appropriate size
     if needed.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dinsert (const hid_t dataset, const hsize_t * const offset,
     const hsize_t *const stride, const hsize_t *const count, hsize_t *const
     buf, const void *const value, const hid_t type)

     DESCRIPTION

     Insert a slice of data into dataset with the appropriate offset &
     stride, ensuring that no existing data is lost due to resizing the
     dataset but not checking that previous data isn't being overwritten.

     The offset, stride, count and buf arrays must each have rank elements.
     If stride is set to the null pointer then a default of [1, 1, 1, ..., 1]
     will be used. An optional buffer may be provided in buf to avoid using
     malloc to allocate a small amount of memory whose size may actually be
     known at compile time.

     The value array should contain count[0] * count[1] * ... * count[rank-1]
     === product(count) elements of data.

     ARGUMENTS

     dataset The dataset to write the data to.                                
     offset  Where to start writing the data.                                 
     stride  The number of elements in the dataset to step for each element   
             to be written.                                                   
     count   The number of elements in each dimension to be written.          
     buf     An optional buffer to avoid using the heap for small amounts of  
             memory.                                                          
     value   The address of the data to be written.                           
     type    The type of data in memory.                                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.14 cbf_H5Dset_extent

     Change the extent of a chunked dataset to the values in dim.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dset_extent (const hid_t dataset, const hsize_t * const dim)

     DESCRIPTION

     Forwards to a HDF5 function to change the extent of dataset. The dim
     array must have the same number of elements as the rank of the dataset,
     but this can't be checked within this function.

     ARGUMENTS

     dataset A handle for the dataset whose extent is to be changed.          
     dim     The new extent of the dataset, if the function succeeds. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.15 cbf_H5Dwrite2

     Add some data to the specified position in the dataset, without checking
     what (if anything) was there before.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dwrite2 (const hid_t dataset, const hsize_t * const offset,
     const hsize_t *const stride, const hsize_t *const count, const void
     *const value, const hid_t type)

     DESCRIPTION

     Assumes the dataset has the appropriate size to contain all the data and
     overwrites any existing data that may be there. The rank of the dataset
     is assumed to be known, and the size of the array parameters is not
     tested. When rank is zero - in the case of scalar datasets - the offset,
     stride and count parameters are meaningless and should be omitted by
     setting them to zero.

     ARGUMENTS

     dataset The dataset to write the data to.                                
     offset  Where to start writing the data, as an array of rank numbers.    
             The number of elements in the dataset to step for each element   
     stride  to be written, where null is equivalent to a stride of [1, 1, 1, 
             ..., 1], as an array of rank numbers.                            
     count   The number of elements in each dimension to be written, as an    
             array of rank numbers.                                           
     value   The address of the data to be written.                           
     type    The type of data in memory.                                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.16 cbf_H5Dread2

     Extract some existing data from a dataset at a known position with
     memtype.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dread2 (const hid_t dataset, const hsize_t * const offset,
     const hsize_t * const stride, const hsize_t * const count, void * const
     value, const hid_t type)

     DESCRIPTION

     Read some data from a given location in the dataset to an existing
     location in memory. Does not check the length of the array parameters,
     which should all have rank elements or (in some cases) be null. When
     rank is zero - in the case of scalar datasets - the offset, stride and
     count parameters are meaningless and should be omitted by setting them
     to zero.

     ARGUMENTS

     dataset The dataset to read the data from.                               
     offset  Where to start writing the data, as an array of rank numbers.    
             The number of elements in the dataset to step for each element   
     stride  to be written, where null is equivalent to a stride of [1, 1, 1, 
             ..., 1], as an array of rank numbers.                            
     count   The number of elements in each dimension to be written, as an    
             array of rank numbers.                                           
     value   The location where the data is to be stored.                     
     type    The type of data in memory.                                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.17 cbf_H5Drequire_scalar_F64LE2

     Write a scalar 64-bit floating point number as a dataset with
     comparison.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Drequire_scalar_F64LE2 (const hid_t location, hid_t * const
     dataset, const char * const name, const double value, int (*cmp)(const
     void *, const void *, size_t))

     DESCRIPTION

     Convenience function using the HDF5 abstraction layer to avoid the need
     to consider array-related parameters for a scalar dataset.It ensures
     that a scalar 64-bit IEEE floating point dataset exists with the
     appropriate name and (for an existing dataset) the correct value as
     determined by the comparison function cmp.

     ARGUMENTS

     location The group containing the new dataset.                           
     dataset  An optional pointer to a place to store the new dataset.        
     name     The name of the new dataset.                                    
     value    The value of the new dataset.                                   
     cmp      A comparison function to test if a previously set value is      
              equal to the value I asked for.                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP

     Write a scalar 64-bit floating point number as a dataset with a
     user-defined comparison.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Drequire_scalar_F64LE2_ULP (const hid_t location, hid_t *const
     dataset, const char *const name, const double value, int(*cmp)(const
     void *, const void *, size_t, const void *), const void *const
     cmp_params)

     DESCRIPTION

     Convenience function using the HDF5 abstraction layer to avoid the need
     to consider array-related parameters for a scalar dataset. It ensures
     that a scalar 64-bit IEEE floating point dataset exists with the
     appropriate name and (for an existing dataset) the correct value as
     determined by the user-supplied comparison function cmp.

     It is implemented using some of the other dataset functions:

       * cbf_H5Dfind2
       * cbf_H5Dcreate
       * cbf_H5Dread2
       * cbf_H5Dwrite2

     ARGUMENTS

     location   The group containing the new dataset.                         
     dataset    An optional pointer to a place to store the new dataset.      
     name       The name of the new dataset.                                  
     value      The value of the new dataset.                                 
     cmp        A comparison function to test if a previously set value is    
                equal to the value I asked for.                               
     cmp_params Some extra data which may be required by the comparison       
                function.                                                     

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.19 cbf_H5Drequire_flstring
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.19 cbf_H5Drequire_flstring

     Write a single fixed-length string as a dataset.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Drequire_flstring (const hid_t location, hid_t *const dataset,
     const char *const name, const char *const value)

     DESCRIPTION

     Convenience function using the HDF5 abstraction layer to avoid the need
     to consider array-related parameters for a scalar dataset and to
     automatically set the string type to the correct size.

     ARGUMENTS

     location The group containing the new dataset.                           
     dataset  An optional pointer to a place to store the new dataset.        
     name     The name of the new dataset.                                    
     value    The value of the new dataset.                                   

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.20 cbf_H5Dfree

     ----------------------------------------------------------------------

    2.6.20 cbf_H5Dfree

     Close a HDF5 dataset.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Dfree (const hid_t ID)

     DESCRIPTION

     Attempt to close a dataset, but don't modify the identifier that
     described it.

     ARGUMENTS

     ID The HDF5 dataset to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.10 cbf_H5Dcreate
       * 2.6.11 cbf_H5Dfind2
       * 2.6.12 cbf_H5Drequire
       * 2.6.13 cbf_H5Dinsert
       * 2.6.14 cbf_H5Dset_extent
       * 2.6.15 cbf_H5Dwrite2
       * 2.6.16 cbf_H5Dread2
       * 2.6.17 cbf_H5Drequire_scalar_F64LE2
       * 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
       * 2.6.19 cbf_H5Drequire_flstring

     ----------------------------------------------------------------------

    2.6.21 cbf_H5Fopen

     Attempt to open an HDF5 file by file name.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Fopen (hid_t * const file, const char * const name)

     DESCRIPTION

     Will try to open a file of the given name with suitable values for some
     of it's properties to make memory leaks less likely.

     Warning: this function will destroy any existing data in the file, do
     not pass the name of any file containing data you want to keep.

     ARGUMENTS

     file A pointer to an HDF5 ID where the newly opened file should be       
          stored.                                                             
     name The name of the file to attempt to open.                            

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.22 cbf_H5Fclose

     ----------------------------------------------------------------------

    2.6.22 cbf_H5Fclose

     Close a HDF5 file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Fclose (const hid_t ID)

     DESCRIPTION

     Attempt to close a file, but don't modify the identifier that described
     it.

     ARGUMENTS

     ID The HDF5 file to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.21 cbf_H5Fopen

     ----------------------------------------------------------------------

    2.6.23 cbf_H5Gcreate

     Attempt to create a group.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Gcreate (const hid_t location, hid_t * const group, const char
     * const name)

     DESCRIPTION

     Helper function to attempt to create a HDF5 group identified by name and
     return an error code, to make error handling more consistant. This will
     fail if a link with the same name already exists in parent.

     ARGUMENTS

     location The group that will contain the newly created group.        
     group    A pointer to a HDF5 ID type where the group will be stored. 
     name     The name that the group will be given.                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.24 cbf_H5Gfind
       * 2.6.25 cbf_H5Grequire
       * 2.6.26 cbf_H5Gfree

     ----------------------------------------------------------------------

    2.6.24 cbf_H5Gfind

     Check if a group exists.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Gfind (const hid_t location, hid_t *const group, const char
     *const name)

     DESCRIPTION

     Checks for the existance of a group with the given name and parent. Will
     return CBF_NOTFOUND if it cannot be found, or open it if it already
     exists. An error code will be returned if something other than a group
     exists at the specified location.

     ARGUMENTS

     location The group to be searched.                                   
     group    A pointer to a HDF5 ID type where the group will be stored. 
     name     The path (ie, name) of the group to be found.               

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.23 cbf_H5Gcreate
       * 2.6.25 cbf_H5Grequire
       * 2.6.26 cbf_H5Gfree

     ----------------------------------------------------------------------

    2.6.25 cbf_H5Grequire

     Ensure a group exists.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Grequire (const hid_t location, hid_t *const group, const char
     *const name)

     DESCRIPTION

     Checks for the existance of a group with the given name and parent. Will
     create the group if it cannot be found, or open it if it already exists.
     It is an error if a matching group cannot be found or created. This uses
     cbf_H5Gcreate to create any new groups.

     ARGUMENTS

     location The group that will contain the newly created group.        
     group    A pointer to a HDF5 ID type where the group will be stored. 
     name     The name that the group will be given.                      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.23 cbf_H5Gcreate
       * 2.6.24 cbf_H5Gfind
       * 2.6.26 cbf_H5Gfree

     ----------------------------------------------------------------------

    2.6.26 cbf_H5Gfree

     Close a HDF5 group.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Gfree (const hid_t ID)

     DESCRIPTION

     Attempt to close a group, but don't modify the identifier that described
     it.

     ARGUMENTS

     ID The HDF5 group to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.23 cbf_H5Gcreate
       * 2.6.24 cbf_H5Gfind
       * 2.6.25 cbf_H5Grequire

     ----------------------------------------------------------------------

    2.6.27 cbf_H5Ivalid

     Check the validity of an object identifier.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Ivalid (const hid_t ID)

     DESCRIPTION

     Function to check validity of a HDF5 identifier. HDF5's predefined types
     are never counted as valid by this function, so it can't be used to test
     the validity of a type constant. Types obtained by using H5Tcopy are
     safe to test.

     ARGUMENTS

     ID An HDF5 object identifier. 

     RETURN VALUE

     Non-zero if the type is valid, zero otherwise.

     SEE ALSO

       * 2.6.28 cbf_H5Ocmp

     ----------------------------------------------------------------------

    2.6.28 cbf_H5Ocmp

     A missing HDF5 function.

     PROTOTYPE

     #include "cbf_hdf5.h"
     htri_t cbf_H5Ocmp (const hid_t id0, const hid_t id1)

     DESCRIPTION

     Compare two HDF5 object ID's for equality. This follows the standard
     practice of returning zero if objects should be considered equal, and
     the HDF5 practice of returning a negative number if there is an error.

     ARGUMENTS

     id0 An HDF5 identifier. 
     id1 An HDF5 identifier. 

     RETURN VALUE

     0 if equal, a positive value if not equal, or a negative value if there
     is an error.

     SEE ALSO

       * 2.6.27 cbf_H5Ivalid

     ----------------------------------------------------------------------

    2.6.29 cbf_H5Ofree

     Close a HDF5 object identifier.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Ofree (const hid_t ID)

     DESCRIPTION

     Attempt to close an object identifier of unknown type, but don't modify
     the identifier that described it.

     ARGUMENTS

     ID The HDF5 object to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.28 cbf_H5Ocmp
       * 2.6.27 cbf_H5Ivalid

     ----------------------------------------------------------------------

    2.6.30 cbf_H5Screate

     Create a dataspace with some given values.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Screate (hid_t *const ID, const int rank, const hsize_t *const
     dim, const hsize_t *const max)

     DESCRIPTION

     Helper function which creates a HDF5 dataspace.

     Maximum dimensions can be set to infinity by passing H5S_UNLIMITED in
     the appropriate slot of the max parameter. If rank is zero then neither
     dim nor max are used and a scalar dataspace is created. If rank is
     non-zero and dim is a null pointer then ID will not be modified and the
     function will fail. If rank is non-zero and max is a null pointer the
     maximum length is set to the current length as given by dim.

     ARGUMENTS

     ID   A pointer to a HDF5 identifier that will contain the new dataspace. 
     rank The number of dimensions of the new dataspace.                      
     dim  The current size of each dimension of the dataspace, should be an   
          array of length rank.                                               
     max  The maximum size of each dimension, should be an array of length    
          rank.                                                               

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.31 cbf_H5Sfree

     ----------------------------------------------------------------------

    2.6.31 cbf_H5Sfree

     Close a HDF5 dataspace identifier.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Sfree (const hid_t ID)

     DESCRIPTION

     Attempt to close a dataspace identifier, but don't modify the identifier
     that described it.

     ARGUMENTS

     ID The HDF5 dataspace to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.30 cbf_H5Screate

     ----------------------------------------------------------------------

    2.6.32 cbf_H5Tcreate_string

     Get a HDF5 string datatype to describe a sting of the specified length.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Tcreate_string (hid_t *const type, const size_t len)

     DESCRIPTION

     Convenience function to create a string datatype suitable for use when
     storing a string of length len, returning it in the identifier pointed
     to by type.

     ARGUMENTS

     type A pointer to a the HDF5 handle of the new datatype, which should be 
          free'd with cbf_H5Tfree                                             
     len  The length of the string datatype - should be strlen() or           
          H5T_VARIABLE                                                        

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.33 cbf_H5Tfree

     ----------------------------------------------------------------------

    2.6.33 cbf_H5Tfree

     Close a HDF5 datatype identifier.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_H5Tfree (const hid_t ID)

     DESCRIPTION

     Attempt to close a datatype identifier, but don't modify the identifier
     that described it.

     ARGUMENTS

     ID The HDF5 datatype to be closed. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.6.32 cbf_H5Tcreate_string

     ----------------------------------------------------------------------

2.7 High-level NeXus-related functions

     These functions primarily allow interaction with a cbf_h5handle without
     being exposed to its structure or the complexities of using it
     correctly. Wherever possible these functions should be used instead of
     directly accessing a cbf_h5handle or cbf_config_t in order make code
     easier to read, to maintain the integrity of the data structures and to
     ensure all resources allocated to these object are correctly cleaned up.

     This section describes functions available for working with:

       * CBF's HDF5 handles:
            * 2.7.1 cbf_h5handle_get_file
            * 2.7.2 cbf_h5handle_set_file
            * 2.7.3 cbf_h5handle_get_entry
            * 2.7.4 cbf_h5handle_set_entry
            * 2.7.5 cbf_h5handle_require_entry
            * 2.7.6 cbf_h5handle_require_entry_definition
            * 2.7.7 cbf_h5handle_get_sample
            * 2.7.8 cbf_h5handle_set_sample
            * 2.7.9 cbf_h5handle_require_sample
            * 2.7.10 cbf_h5handle_get_beam
            * 2.7.11 cbf_h5handle_set_beam
            * 2.7.12 cbf_h5handle_require_beam
            * 2.7.13 cbf_h5handle_get_instrument
            * 2.7.14 cbf_h5handle_set_instrument
            * 2.7.15 cbf_h5handle_find_instrument
            * 2.7.16 cbf_h5handle_require_instrument
            * 2.7.17 cbf_h5handle_get_detector
            * 2.7.18 cbf_h5handle_set_detector
            * 2.7.19 cbf_h5handle_find_detector
            * 2.7.20 cbf_h5handle_require_detector
            * 2.7.21 cbf_h5handle_get_goniometer
            * 2.7.22 cbf_h5handle_set_goniometer
            * 2.7.23 cbf_h5handle_require_goniometer
            * 2.7.24 cbf_h5handle_get_monochromator
            * 2.7.25 cbf_h5handle_set_monochromator
            * 2.7.26 cbf_h5handle_require_monochromator
            * 2.7.27 cbf_h5handle_get_source
            * 2.7.28 cbf_h5handle_set_source
            * 2.7.29 cbf_h5handle_require_source
            * 2.7.30 cbf_free_h5handle
            * 2.7.31 cbf_create_h5handle3
            * 2.7.32 cbf_write_cbf_h5file
            * 2.7.33 cbf_write_cbf2nx
            * 2.7.34 cbf_write_minicbf_h5file
            * 2.7.35 cbf_write_nx2cbf
       * miniCBF configuration settings:
            * 2.7.36 cbf_config_create
            * 2.7.37 cbf_config_parse
            * 2.7.38 cbf_config_free
            * 2.7.39 cbf_config_strerror

    Reading miniCBF configuration settings

     This example demonstrates how a miniCBF configuration file should be
     parsed, what should be checked before the extracted settings are used
     and what should be cleaned up by the caller afterwards:

 /* Declare some important variables */
 int configError = cbf_configError_success;
 FILE * configFile = fopen("config.txt","r");
 cbf_config_t * const configSettings = cbf_config_create();

 /*
 Read and check the configuration settings,
 writing any error messages to stderr.
 */
 configError = cbf_config_parse(configFile,stderr,configSettings);
 /* I no longer need to keep the file open */
 fclose(configFile);

 /* Check if I could read the file successfully */
 if (cbf_configError_success != configError) {
     fprintf(stderr,"Error parsing configuration file 'config.txt': %s\n",
             cbf_config_strerror(configError));
 } else {
     /* Use the configuration settings here... */
 }

 /* Clean up the settings to avoid memory leaks */
 cbf_config_free(configSettings);

     ----------------------------------------------------------------------

    2.7.1 cbf_h5handle_get_file

     Get the current id of the file within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_file (const cbf_h5handle nx, hid_t *const file)

     DESCRIPTION

     Check the handle for the presence of a file, optionally returning it.

     ARGUMENTS

     nx   A handle to query for the presence of the requested information.    
     file A place to store the file (if found), or null if the file isn't     
          wanted.                                                             

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.2 cbf_h5handle_set_file

     ----------------------------------------------------------------------

    2.7.2 cbf_h5handle_set_file

     Set the id of the file within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_file (const cbf_h5handle nx, const hid_t file)

     DESCRIPTION

     Sets the file id within the handle to the given value. Doesn't check or
     modify any attributes in any way.

     ARGUMENTS

     nx   The handle to add information to.          
     file The file to be set as the current file id. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.1 cbf_h5handle_get_file

     ----------------------------------------------------------------------

    2.7.3 cbf_h5handle_get_entry

     Get the current id and name of the entry group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_entry (const cbf_h5handle nx, hid_t *const group,
     const char **const name)

     DESCRIPTION

     Check the handle for the presence of an entry group and its name,
     optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.4 cbf_h5handle_set_entry
       * 2.7.5 cbf_h5handle_require_entry

     ----------------------------------------------------------------------

    2.7.4 cbf_h5handle_set_entry

     Set the id and name of the entry group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_entry (const cbf_h5handle nx, const hid_t group,
     const char *const name)

     DESCRIPTION

     Sets the entry group and name within the handle to the given values.
     Doesn't check or modify the NX_class attribute in any way. The handle
     will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.              
     group The group to be set as the current entry group 
     name  The name which the group should be given.      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.3 cbf_h5handle_get_entry
       * 2.7.5 cbf_h5handle_require_entry

     ----------------------------------------------------------------------

    2.7.5 cbf_h5handle_require_entry

     Ensure I have an entry in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_entry (const cbf_h5handle nx, hid_t *const
     group, const char *name)

     DESCRIPTION

     This will check if the entry group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "entry".      

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.3 cbf_h5handle_get_entry
       * 2.7.4 cbf_h5handle_set_entry

     ----------------------------------------------------------------------

    2.7.6 cbf_h5handle_require_entry_definition

     Ensure I have an entry in the hdf5 handle with definition.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_entry_definition (const cbf_h5handle nx, hid_t
     *const group, const char *name, const char *definition, const char
     *version, const char *URL)

     DESCRIPTION

     This will check if the entry group and definition within the handle
     matches any existing group of the same name within the current file and
     has a definition designation that agrees. If the group name doesn't
     match a new group is opened or created and added to the handle. If the
     definition does not match, it is replaced with the new one. If the
     version attribute does not match it is replaced with the new one. If the
     URL> attribute does not match it is replace with the new one. The
     NX_class attributes are not checked, but if a new entry is created it
     will be created with NX_class NXentry.

     ARGUMENTS

     nx         The HDF5 handle to use.                                       
     group      An optional pointer to a place where the group ID should be   
                stored.                                                       
     name       The group name, or null to use the default name of "entry".   
     definition The definition name, or null to not specify a definition      
                name.                                                         
     version    The version string, or null to not specify a version string.  
     URL        The URL at which the definition is stored, or null to not     
                specify a URL                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.3 cbf_h5handle_get_entry
       * 2.7.4 cbf_h5handle_set_entry
       * 2.7.5 cbf_h5handle_require_entry

     ----------------------------------------------------------------------

    2.7.7 cbf_h5handle_get_sample

     Get the current id and name of the sample group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_sample (const cbf_h5handle nx, hid_t *const group,
     const char **const name)

     DESCRIPTION

     Check the handle for the presence of an sample group and its name,
     optionally returning any combination of them.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.8 cbf_h5handle_set_sample
       * 2.7.9 cbf_h5handle_require_sample

     ----------------------------------------------------------------------

    2.7.8 cbf_h5handle_set_sample

     Set the id and name of the sample group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_sample (const cbf_h5handle nx, const hid_t group,
     const char *const name)

     DESCRIPTION

     Sets the sample group and name within the handle to the given values.
     Doesn't check or modify the NX_class attribute in any way. The handle
     will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.               
     group The group to be set as the current sample group 
     name  The name which the group should be given.       

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.7 cbf_h5handle_get_sample
       * 2.7.9 cbf_h5handle_require_sample

     ----------------------------------------------------------------------

    2.7.9 cbf_h5handle_require_sample

     Ensure I have a sample in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_sample (const cbf_h5handle nx, hid_t *const
     group, const char *name)

     DESCRIPTION

     This will check if the sample group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "sample".     

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.7 cbf_h5handle_get_sample
       * 2.7.8 cbf_h5handle_set_sample

     ----------------------------------------------------------------------

    2.7.10 cbf_h5handle_get_beam

     Get the current id and name of the beam group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_beam (const cbf_h5handle nx, hid_t *const group,
     const char **const name)

     DESCRIPTION

     Check the handle for the presence of a beam group and its name,
     optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.11 cbf_h5handle_set_beam
       * 2.7.12 cbf_h5handle_require_beam

     ----------------------------------------------------------------------

    2.7.11 cbf_h5handle_set_beam

     Set the id and name of the beam group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_beam (const cbf_h5handle nx, const hid_t group,
     const char *const name)

     DESCRIPTION

     Sets the beam group and name within the handle to the given values.
     Doesn't check or modify the NX_class attribute in any way. The handle
     will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.             
     group The group to be set as the current beam group 
     name  The name which the group should be given.     

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.10 cbf_h5handle_get_beam
       * 2.7.12 cbf_h5handle_require_beam

     ----------------------------------------------------------------------

    2.7.12 cbf_h5handle_require_beam

     Ensure I have a beam in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_beam (const cbf_h5handle nx, hid_t *const
     group, const char *name)

     DESCRIPTION

     This will check if the beam group within the handle matches any existing
     group of the same name within the current file. If they don't match a
     new group is opened or created and added to the handle. The NX_class
     attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "beam".       

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.10 cbf_h5handle_get_beam
       * 2.7.11 cbf_h5handle_set_beam

     ----------------------------------------------------------------------

    2.7.13 cbf_h5handle_get_instrument

     Get the current id and name of the instrument group within the given
     handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_instrument (const cbf_h5handle nx, hid_t *const
     group, const char **const name)

     DESCRIPTION

     Check the handle for the presence of an instrument group and its name,
     optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.14 cbf_h5handle_set_instrument
       * 2.7.15 cbf_h5handle_find_instrument
       * 2.7.16 cbf_h5handle_require_instrument

     ----------------------------------------------------------------------

    2.7.14 cbf_h5handle_set_instrument

     Set the id and name of the instrument group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_instrument (const cbf_h5handle nx, const hid_t
     group, const char *const name)

     DESCRIPTION

     Sets the instrument group and name within the handle to the given
     values. Doesn't check or modify the NX_class attribute in any way. The
     handle will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.                   
     group The group to be set as the current instrument group 
     name  The name which the group should be given.           

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.13 cbf_h5handle_get_instrument
       * 2.7.15 cbf_h5handle_find_instrument
       * 2.7.16 cbf_h5handle_require_instrument

     ----------------------------------------------------------------------

    2.7.15 cbf_h5handle_find_instrument

     Find an existing instrument group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_find_instrument (const cbf_h5handle nx, hid_t *const
     group, const char **const name)

     ARGUMENTS

     nx    
     group 
     name  

     ----------------------------------------------------------------------

    2.7.16 cbf_h5handle_require_instrument

     Ensure I have an instrument in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_instrument (const cbf_h5handle nx, hid_t *const
     group, const char * name)

     DESCRIPTION

     This will check if the instrument group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group  An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "instrument". 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.13 cbf_h5handle_get_instrument
       * 2.7.14 cbf_h5handle_set_instrument
       * 2.7.15 cbf_h5handle_find_instrument

     ----------------------------------------------------------------------

    2.7.17 cbf_h5handle_get_detector

     Get the current id and name of the detector group within the given
     handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_detector (const cbf_h5handle nx, hid_t *const
     group, const char **const name)

     DESCRIPTION

     Check the handle for the presence of an detector group and its name,
     optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.18 cbf_h5handle_set_detector
       * 2.7.19 cbf_h5handle_find_detector
       * 2.7.20 cbf_h5handle_require_detector

     ----------------------------------------------------------------------

    2.7.18 cbf_h5handle_set_detector

     Set the id and name of the detector group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_detector (const cbf_h5handle nx, const hid_t group,
     const char *const name)

     DESCRIPTION

     Sets the detector group and name within the handle to the given values.
     Doesn't check or modify the NX_class attribute in any way. The handle
     will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.                 
     group The group to be set as the current detector group 
     name  The name which the group should be given.         

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.17 cbf_h5handle_get_detector
       * 2.7.19 cbf_h5handle_find_detector
       * 2.7.20 cbf_h5handle_require_detector

     ----------------------------------------------------------------------

    2.7.19 cbf_h5handle_find_detector

     Find an existing detector group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_find_detector (const cbf_h5handle nx, hid_t *const
     group, const char **const name)

     ARGUMENTS

     nx    
     group 
     name  

     ----------------------------------------------------------------------

    2.7.20 cbf_h5handle_require_detector

     Ensure I have a detector in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_detector (const cbf_h5handle nx, hid_t *const
     group, const char *name)

     DESCRIPTION

     This will check if the detector group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group  An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "detector".   

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.17 cbf_h5handle_get_detector
       * 2.7.18 cbf_h5handle_set_detector
       * 2.7.19 cbf_h5handle_find_detector

     ----------------------------------------------------------------------

    2.7.21 cbf_h5handle_get_goniometer

     Get the current id and name of the goniometer group within the given
     handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_goniometer (const cbf_h5handle nx, hid_t *const
     group, const char **const name)

     DESCRIPTION

     Check the handle for the presence of an goniometer group and its name,
     optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.22 cbf_h5handle_set_goniometer
       * 2.7.23 cbf_h5handle_require_goniometer

     ----------------------------------------------------------------------

    2.7.22 cbf_h5handle_set_goniometer

     Set the id and name of the goniometer group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_goniometer (const cbf_h5handle nx, const hid_t
     group, const char *const name)

     DESCRIPTION

     Sets the goniometer group and name within the handle to the given
     values. Doesn't check or modify the NX_class attribute in any way. The
     handle will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.                   
     group The group to be set as the current goniometer group 
     name  The name which the group should be given.           

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.21 cbf_h5handle_get_goniometer
       * 2.7.23 cbf_h5handle_require_goniometer

     ----------------------------------------------------------------------

    2.7.23 cbf_h5handle_require_goniometer

     Ensure I have a goniometer in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_goniometer (const cbf_h5handle nx, hid_t *const
     group, const char *name)

     DESCRIPTION

     This will check if the goniometer group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group  An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "goniometer". 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.21 cbf_h5handle_get_goniometer
       * 2.7.22 cbf_h5handle_set_goniometer

     ----------------------------------------------------------------------

    2.7.24 cbf_h5handle_get_monochromator

     Get the current id and name of the monochromator group within the given
     handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_monochromator (const cbf_h5handle nx, hid_t *const
     group, const char **const name)

     DESCRIPTION

     Check the handle for the presence of an monochromator group and its
     name, optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.25 cbf_h5handle_set_monochromator
       * 2.7.26 cbf_h5handle_require_monochromator

     ----------------------------------------------------------------------

    2.7.25 cbf_h5handle_set_monochromator

     Set the id and name of the monochromator group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_monochromator (const cbf_h5handle nx, const hid_t
     group, const char * const name)

     DESCRIPTION

     Sets the monochromator group and name within the handle to the given
     values. Doesn't check or modify the NX_class attribute in any way. The
     handle will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.                      
     group The group to be set as the current monochromator group 
     name  The name which the group should be given.              

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.24 cbf_h5handle_get_monochromator
       * 2.7.26 cbf_h5handle_require_monochromator

     ----------------------------------------------------------------------

    2.7.26 cbf_h5handle_require_monochromator

     Ensure I have a monochromator in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_monochromator (const cbf_h5handle nx, hid_t
     *const group, const char *name)

     DESCRIPTION

     This will check if the monochromator group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                            
     group  An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of                 
           "monochromator".                                                   

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.24 cbf_h5handle_get_monochromator
       * 2.7.25 cbf_h5handle_set_monochromator

     ----------------------------------------------------------------------

    2.7.27 cbf_h5handle_get_source

     Get the current id and name of the source group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_get_source (const cbf_h5handle nx, hid_t *const group,
     const char **const name)

     DESCRIPTION

     Check the handle for the presence of an source group and its name,
     optionally returning any combination of them. The error code
     'CBF_NOTFOUND' will be returned if any of the requested items of data
     cannot be found.

     The handle retains ownership of the returned object and/or string,
     neither of them should be free'd by the caller.

     ARGUMENTS

     nx    A handle to query for the presence of the requested information.   
     group A place to store the group (if found), or null if the group isn't  
           wanted.                                                            
     name  A place to store the name of the group (if found), or null if the  
           name isn't wanted.                                                 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.28 cbf_h5handle_set_source
       * 2.7.29 cbf_h5handle_require_source

     ----------------------------------------------------------------------

    2.7.28 cbf_h5handle_set_source

     Set the id and name of the source group within the given handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_set_source (const cbf_h5handle nx, const hid_t group,
     const char *const name)

     DESCRIPTION

     Sets the source group and name within the handle to the given values.
     Doesn't check or modify the NX_class attribute in any way. The handle
     will take ownership of the group id iff this function succeeds.

     ARGUMENTS

     nx    The handle to add information to.               
     group The group to be set as the current source group 
     name  The name which the group should be given.       

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.27 cbf_h5handle_get_source
       * 2.7.29 cbf_h5handle_require_source

     ----------------------------------------------------------------------

    2.7.29 cbf_h5handle_require_source

     Ensure I have a source in the hdf5 handle.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_h5handle_require_source (const cbf_h5handle nx, hid_t *const
     group, const char *name)

     DESCRIPTION

     This will check if the source group within the handle matches any
     existing group of the same name within the current file. If they don't
     match a new group is opened or created and added to the handle. The
     NX_class attributes are not checked.

     ARGUMENTS

     nx    The HDF5 handle to use.                                          
     group  An optional pointer to a place where the group should be stored. 
     name  The group name, or null to use the default name of "source".     

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.27 cbf_h5handle_get_source
       * 2.7.28 cbf_h5handle_set_source

     ----------------------------------------------------------------------

    2.7.30 cbf_free_h5handle

     Free a handle for an HDF5 file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_free_h5handle (cbf_h5handle h5handle)

     DESCRIPTION

     Checks if the handle appears to be valid, the free's the handle and any
     data that the handle owns.

     ARGUMENTS

     h5handle The handle to be free'd. 

     RETURN VALUE

     An error code

     SEE ALSO

       * 2.7.31 cbf_create_h5handle3

     ----------------------------------------------------------------------

    2.7.31 cbf_create_h5handle3

     Allocates space for a HDF5 file handle and associates it with the given
     file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_create_h5handle3 (cbf_h5handle *handle, hid_t file)

     DESCRIPTION

     This function expects the user to create or open a hdf5 file with the
     appropriate parameters for what they are trying to do, replacing older
     functions which would create a file with the H5F_ACC_TRUNC flag and
     H5F_CLOSE_STRONG property.

     ARGUMENTS

     handle A pointer to a handle which is to be allocated.       
     file   A HDF5 file to store within the newly created handle. 

     RETURN VALUE

     An error code

     SEE ALSO

       * 2.7.30 cbf_free_h5handle

     ----------------------------------------------------------------------

    2.7.32 cbf_write_cbf_h5file

     Extract the data from a CBF file & put it into a NeXus file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_write_cbf_h5file (cbf_handle handle, cbf_h5handle h5handle)

     DESCRIPTION

     Equivalent to cbf_write_cbf2nx(handle,h5handle,0,0,0).

     ARGUMENTS

     handle   The CBF file to extract data from. 
     h5handle The NeXuS file to write data to.   

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.34 cbf_write_minicbf_h5file
       * 2.7.33 cbf_write_cbf2nx
       * 2.7.35 cbf_write_nx2cbf

     ----------------------------------------------------------------------

    2.7.33 cbf_write_cbf2nx

     Extract the data from a CBF file & put it into a NeXus file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_write_cbf2nx (cbf_handle handle, cbf_h5handle h5handle, const
     char *const datablock, const char *const scan, const int list)

     DESCRIPTION

     Extracts data from handle and generates a NeXus file in h5handle. This
     will attempt to extract metadata and image data from each scan (or the
     named scan) within each datablock (or the the named datablock) and
     insert it into a given index into the NXentry group specified in
     h5handle.

     Each scan in the CBF file corresponds to one NXentry in NeXus, so a CBF
     datablock with multiple scans must be converted by calling this function
     with the appropriate value of scan once for each scan in the datablock.

     The flags (within h5handle) determine:

       * Compression algorithm: zlib/CBF/none
       * Plugin registration method: automatic/manual

     The strings given by h5handle->scan_id and h5handle->sample_id define:

       * The presence and value of an identifier for the scan, stored in
         /*:NXentry/entry_identifier.
       * The presence and value of an identifier for the sample, stored in
         /*:NXentry/*:NXsample/sample_identifier.

     ARGUMENTS

     handle    The CBF file to extract data from.                             
     h5handle  The NeXuS file to write data to.                               
     datablock The name of the datablock to convert, or NULL to convert all   
               datablocks.                                                    
     scan      The name of the scan to convert, or NULL if there is only one  
               scan in the datablock.                                         
     list      Boolean flag to determine if a list of processed items is      
               printed.                                                       

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.32 cbf_write_cbf_h5file
       * 2.7.34 cbf_write_minicbf_h5file
       * 2.7.35 cbf_write_nx2cbf

     ----------------------------------------------------------------------

    2.7.34 cbf_write_minicbf_h5file

     Extract the data from a miniCBF file & put it into a NeXus file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_write_minicbf_h5file (cbf_handle handle, cbf_h5handle h5handle,
     const cbf_config_t *const axisConfig)

     DESCRIPTION

     Extracts the miniCBF data directly - by parsing the header - and uses
     that plus the configuration options from axisConfig to generate a NeXus
     file in h5handle. This can extract metadata and image data from miniCBF
     files containing multiple datablocks which each contain a single image
     and insert it into a given index into the NXentry group specified in
     h5handle.

     Currently, only Pilatus 1.2 format headers are supported.

     The flags determine:

       * Compression algorithm: zlib/CBF/none
       * Plugin registration method: automatic/manual

     ARGUMENTS

     handle     The miniCBF file to extract data from.                        
     h5handle   The NeXus file to write data to.                              
     axisConfig The configuration settings desribing the axes and their       
                relation to the sample and to each other.                     

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.32 cbf_write_cbf_h5file
       * 2.7.35 cbf_write_nx2cbf

     ----------------------------------------------------------------------

    2.7.35 cbf_write_nx2cbf

     Extract data from a nexus file and store it in a CBF file.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_write_nx2cbf (cbf_h5handle nx, cbf_handle cbf)

     DESCRIPTION

     Reads NeXus-format data from the entry group defined in the nx handle,
     extracting data related to the frame with index nx->slice and in
     CBF-format within the the cbf handle.

     ARGUMENTS

     nx  The handle defining the NeXus data to be converted.  
     cbf The handle in which to store the resulting CBF data. 

     RETURN VALUE

     An error code.

     SEE ALSO

       * 2.7.32 cbf_write_cbf_h5file
       * 2.7.34 cbf_write_minicbf_h5file

     ----------------------------------------------------------------------

    2.7.36 cbf_config_create

     Obtain a new handle for some configuration settings.

     PROTOTYPE

     #include "cbf_hdf5.h"
     cbf_config_t* cbf_config_create ()

     DESCRIPTION

     Allocates a new collection of configuration settings on the heap, and
     initialises it. The returned pointer should be destroyed by the caller.

     ARGUMENTS

     This function takes no arguments.

     RETURN VALUE

     A newly allocated object for miniCBF configuration settings, or NULL.

     ----------------------------------------------------------------------

    2.7.37 cbf_config_parse

     Read a minicbf configuration file into the given handle, writing errors
     to logfile.

     PROTOTYPE

     #include "cbf_hdf5.h"
     int cbf_config_parse (FILE * const configFile, FILE * const logFile,
     cbf_config_t * const vec)

     DESCRIPTION

     Parses a configuration file to extract a collection of configuration
     settings for a miniCBF file, storing them in the given configuration
     settings object. The pointer should have been obtained by a call to
     cbf_config_create. The configuration file format is described in the
     minicbf2nexus documentation.

     ARGUMENTS

     configFile The file from which the config settings should be read. 
     logFile    A stream to be used for logging error messages.         
     vec        An object describing the configuration settings.        

     RETURN VALUE

     A parser error code.

     ----------------------------------------------------------------------

    2.7.38 cbf_config_free

     Free any heap memory associated with the given
     cbf_hdf5_configItemVectorhandle object.

     PROTOTYPE

     #include "cbf_hdf5.h"
     void cbf_config_free (const cbf_config_t *const vector)

     DESCRIPTION

     Destroys an existing collection of configuration settings. The settings
     should have been obtained by a call to cbf_config_create.

     ARGUMENTS

     vector The configuration data to be free'd. 

     RETURN VALUE

     Nothing.

     ----------------------------------------------------------------------

    2.7.39 cbf_config_strerror

     Convert a parse error to a descriptive string.

     PROTOTYPE

     #include "cbf_hdf5.h"
     const char * cbf_config_strerror (const int error)

     DESCRIPTION

     The returned string is "none" for success, "unknown error" if the given
     error code is not recognised and a non-empty string briefly describing
     the error otherwise.

     The returned string must not be free'd.

     ARGUMENTS

     error An error returned by a cbf_config_* function. 

     RETURN VALUE

     A string describing the error.

     ----------------------------------------------------------------------

  3. File format

    3.1 General description

     With the exception of the binary sections, a CBF file is an mmCIF-format
     ASCII file, so a CBF file with no binary sections is a CIF file. An
     imgCIF file has any binary sections encoded as CIF-format ASCII strings
     and is a CIF file whether or not it contains binary sections. In most
     cases, CBFlib can also be used to access normal CIF files as well as CBF
     and imgCIF files.

    3.2 Format of the binary sections

     Before getting to the binary data itself, there are some preliminaries
     to allow a smooth transition from the conventions of CIF to those of raw
     or encoded streams of "octets" (8-bit bytes). The binary data is given
     as the essential part of a specially formatted semicolon-delimited CIF
     multi-line text string. This text string is the value associated with
     the tag "_array_data.data".

     The specific format of the binary sections differs between an imgCIF and
     a CBF file.

    3.2.1 Format of imgCIF binary sections

     Each binary section is encoded as a semicolon-delimited string. Within
     the text string, the conventions developed for transmitting email
     messages including binary attachments are followed. There is secondary
     ASCII header information, formatted as Multipurpose Internet Mail
     Extensions (MIME) headers (see RFCs 2045-49 by Freed, et al.). The
     boundary marker for the beginning of all this is the special string

 --CIF-BINARY-FORMAT-SECTION--

     at the beginning of a line. The initial "--" says that this is a MIME
     boundary. We cannot put "###" in front of it and conform to MIME
     conventions. Immediately after the boundary marker are MIME headers,
     describing some useful information we will need to process the binary
     section. MIME headers can appear in different orders, and can be very
     confusing (look at the raw contents of a email message with
     attachments), but there is only one header which is has to be understood
     to process an imgCIF: "Content-Transfer-Encoding". If the value given on
     this header is "BINARY", this is a CBF and the data will be presented as
     raw binary, containing a count (in the header described in 3.2.2 Format
     of CBF binary sections) so that we'll know when to start looking for
     more information.

     If the value given for "Content-Transfer-Encoding" is one of the real
     encodings: "BASE64", "QUOTED-PRINTABLE", "X-BASE8", "X-BASE10" or
     "X-BASE16", the file is an imgCIF, and we'll need some other headers to
     process the encoded binary data properly. It is a good practice to give
     headers in all cases. The meanings of various encodings is given in the
     CBF extensions dictionary, cif_img_1.5.4.dic, as one html file, or as
     separate pages for each defintion.

     For certain compressions (e.g. CBF_PACKED) MIME headers are essential to
     determine the parameters of the compression. The full list of MIME
     headers recognized by and generated by CBFlib is:

       * Content-Type:
       * Content-Transfer-Encoding:
       * Content-MD5:
       * X-Binary-Size:
       * X-Binary-ID:
       * X-Binary-Element-Type:
       * X-Binary-Element-Byte-Order:
       * X-Binary-Number-of-Elements:
       * X-Binary-Size-Fastest-Dimension:
       * X-Binary-Size-Second-Dimension:
       * X-Binary-Size-Third-Dimension:
       * X-Binary-Size-Padding:

       * Content-Type:

         The &QUOT;Content-Type&QUOT; header tells us what sort of data we
         have (currently always &QUOT;application/octet-stream&QUOT; for a
         miscellaneous stream of binary data) and, optionally, the
         conversions that were applied to the original data. The default is
         to compress the data with the "CBF-PACKED" algorithm. The
         Content-Type may be any of the discrete types permitted in RFC 2045;
         'application/octet-stream' is recommended. If an octet stream was
         compressed, the compression should be specified by the parameter
         'conversions="X-CBF_PACKED"' or the parameter
         'conversions="X-CBF_PACKED_V2"' or the parameter
         'conversions="X-CBF_CANONICAL"' or the parameter
         'conversions="X-CBF_BYTE_OFFSET"' or the parameter
         'conversions="X-CBF_NIBBLE_OFFSET"'

         If the parameter 'conversions="X-CBF_PACKED"' or
         'conversions="X-CBF_PACKED_V2"' is given it may be further modified
         with the parameters '"uncorrelated_sections"' or '"flat"'

         If the '"uncorrelated_sections"' parameter is given, each section
         will be compressed without using the prior section for averaging. If
         the '"flat"' parameter is given, each the image will be treated as
         one long row.

       * Content-Transfer-Encoding:

         The "Content-Transfer-Encoding" may be 'BASE64', 'Quoted-Printable',
         'X-BASE8', 'X-BASE10', 'X-BASE16' or 'X-BASE32K', for an imgCIF or
         'BINARY' for a CBF. The octal, decimal and hexadecimal transfer
         encodings are provided for convenience in debugging and are not
         recommended for archiving and data interchange.

         In a CIF, one of the parameters 'charset=us-ascii', 'charset=utf-8'
         or 'charset=utf-16' may be used on the Content-Transfer-Encoding to
         specify the character set used for the external presentation of the
         encoded data. If no charset parameter is given, the character set of
         the enclosing CIF is assumed. In any case, if a BOM flag is detected
         (FE FF for big-endian UTF-16, FF FE for little-endian UTF-16 or EF
         BB BF for UTF-8) is detected, the indicated charset will be assumed
         until the end of the encoded data or the detection of a different
         BOM. The charset of the Content-Transfer-Encoding is not the
         character set of the encoded data, only the character set of the
         presentation of the encoded data and should be respecified for each
         distinct STAR string.

         In an imgCIF file, the encoded binary data begins after the empty
         line terminating the header. In an imgCIF file, the encoded binary
         data ends with the terminating boundary delimiter
         '\n--CIF-BINARY-FORMAT-SECTION----' in the currently effective
         charset or with the '\n; ' that terminates the STAR string.

         In a CBF, the raw binary data begins after an empty line terminating
         the header and after the sequence:

               Octet   Hex   Decimal  Purpose
                 0     0C       12    (ctrl-L) Page break
                 1     1A       26    (ctrl-Z) Stop listings in MS-DOS
                 2     04       04    (Ctrl-D) Stop listings in UNIX
                 3     D5      213    Binary section begins

         None of these octets are included in the calculation of the message
         size or in the calculation of the message digest.

       * Content-MD5:

         An MD5 message digest may, optionally, be used. The 'RSA Data
         Security, Inc. MD5 Message-Digest Algorithm' should be used. No
         portion of the header is included in the calculation of the message
         digest. The optional "Content-MD5" header provides a much more
         sophisticated check on the integrity of the binary data than size
         checks alone can provide.

       * X-Binary-Size:

         The "X-Binary-Size" header specifies the size of the equivalent
         binary data in octets. This is the size after any compressions, but
         before any ascii encodings. This is useful in making a simple check
         for a missing portion of this file. The 8 bytes for the Compression
         type (see below) are not counted in this field, so the value of
         "X-Binary-Size" is 8 less than the quantity in bytes 12-19 of the
         raw binary data ( 3.2.2 Format of CBF binary sections).

       * X-Binary-ID:

         The "X-Binary-ID" header should contain the same value as was given
         for "_array_data.binary_id".

       * X-Binary-Element-Type:

         The "X-Binary-Element-Type" header specifies the type of binary data
         in the octets, using the same descriptive phrases as in
         _array_structure.encoding_type. The default value is 'unsigned
         32-bit integer'.

       * X-Binary-Element-Byte-Order:

         The "X-Binary-Element-Byte-Order" can specify either '"BIG_ENDIAN"'
         or '"LITTLE_ENDIAN"' byte order of the image data. CBFlib only
         writes '"LITTLE_ENDIAN"', and in general can only process
         LITTLE_ENDIAN even on machines that are BIG_ENDIAN.

       * X-Binary-Number-of-Elements:

         The "X-Binary-Number-of-Elements" specifies the number of elements
         (not the number of octets) in the decompressed, decoded image.

       * X-Binary-Size-Fastest-Dimension:

         The optional "X-Binary-Size-Fastest-Dimension" specifies the number
         of elements (not the number of octets) in one row of the fastest
         changing dimension of the binary data array. This information must
         be in the MIME header for proper operation of some of the
         decompression algorithms.

       * X-Binary-Size-Second-Dimension:

         The optional "X-Binary-Size-Second-Dimension" specifies the number
         of elements (not the number of octets) in one column of the
         second-fastest changing dimension of the binary data array. This
         information must be in the MIME header for proper operation of some
         of the decompression algorithms.

       * X-Binary-Size-Third-Dimension:

         The optional "X-Binary-Size-Third-Dimension" specifies the number of
         sections for the third-fastest changing dimension of the binary data
         array.

       * X-Binary-Size-Padding:

         The optional "X-Binary-Size-Padding" specifies the size in octets of
         an optional padding after the binary array data and before the
         closing flags for a binary section. CBFlib always writes this
         padding as zeros, but this information should be in the MIME header
         for a binary section that uses padding, especially if non-zero
         padding is used.

     A blank line separator immediately precedes the start of the encoded
     binary data. Blank spaces may be added prior to the preceding "line
     separator" if desired (e.g. to force word or block alignment).

     Because CBFLIB may jump forward in the file from the MIME header, the
     length of encoded data cannot be greater than the value defined by
     "X-Binary-Size" (except when "X-Binary-Size" is zero, which means that
     the size is unknown), unless "X-Binary-Size-Padding" is specified to
     allow for the padding. At exactly the byte following the full binary
     section as defined by the length and padding values is the end of binary
     section identifier. This consists of the line-termination sequence
     followed by:

 --CIF-BINARY-FORMAT-SECTION----
 ;

     with each of these lines followed by a line-termination sequence. This
     brings us back into a normal CIF environment. This identifier is, in a
     sense, redundant because the binary data length value tells the a
     program how many bytes to jump over to the end of the binary data. This
     redundancy has been deliberately added for error checking, and for
     possible file recovery in the case of a corrupted file and this
     identifier must be present at the end of every block of binary data.

    3.2.2 Format of CBF binary sections

     In a CBF file, each binary section is encoded as a ;-delimited string,
     starting with an arbitrary number of pure-ASCII characters.

     Note: For historical reasons, CIFlib has the option of writing simple
     header and footer sections: "START OF BINARY SECTION" at the start of a
     binary section and "END OF BINARY SECTION" at the end of a binary
     section, or writing MIME-type header and footer sections (3.2.1 Format
     of imgCIF binary sections). If the simple header is used, the actual
     ASCII text is ignored when the binary section is read. Use of the simple
     binary header is deprecated.

     The MIME header is recommended.

     Between the ASCII header and the actual CBF binary data is a series of
     bytes ("octets") to try to stop the listing of the header, bytes which
     define the binary identifier which should match the "binary_id" defined
     in the header, and bytes which define the length of the binary section.

        Octet    Hex  Decimal              Purpose               
        1          0C   12      (ctrl-L) End of Page             
        2          1A   26      (ctrl-Z) Stop listings in MS-DOS 
        3          04   04      (Ctrl-D) Stop listings in UNIX   
        4          D5   213     Binary section begins            
        5..5+n-1                Binary data (n octets)           

     NOTE: When a MIME header is used, only bytes 5 through 5+n-1 are
     considered in computing the size and the message digest, and only these
     bytes are encoded for the equivalent imgCIF file using the indicated
     Content-Transfer-Encoding.

     If no MIME header has been requested (a deprecated use), then bytes 5
     through 28 are used for three 8-byte words to hold the binary_id, the
     size and the compression type:

        5..12            Binary Section Identifier        
                       (See _array_data.binary_id)        
                       64-bit, little endian              
        13..20           The size (n) of the              
                       binary section in octets           
                       (i.e. the offset from octet        
                       29 to the first byte following     
                       the data)                          
        21..28           Compression type:                
                                                          
                         CBF_NONE            0x0040 (64)  
                         CBF_CANONICAL       0x0050 (80)  
                         CBF_PACKED          0x0060 (96)  
                         CBF_PACKED_V2       0x0090 (144) 
                         CBF_BYTE_OFFSET     0x0070 (112) 
                         CBF_NIBBLE_OFFSET   0x00A0 (160) 
                         CBF_PREDICTOR       0x0080 (128) 
                         ...                              

     The binary data then follows in bytes 29 through 29+n-1.

     The binary characters serve specific purposes:

       o The Control-L (from-feed) will terminate printing of the current
         page on most operating systems.

       o The Control-Z will stop the listing of the file on MS-DOS type
         operating systems.

       o The Control-D will stop the listing of the file on Unix type
         operating systems.

       o The unsigned byte value 213 (decimal) is binary 11010101. (Octal
         325, and hexadecimal D5). This has the eighth bit set so can be used
         for error checking on 7-bit transmission. It is also asymmetric, but
         with the first bit also set in the case that the bit order could be
         reversed (which is not a known concern).

       o (The carriage return, line-feed pair before the START_OF_BIN and
         other lines can also be used to check that the file has not been
         corrupted e.g. by being sent by ftp in ASCII mode.)

         At present four compression schemes are implemented are defined:
         CBF_NONE (for no compression), CBF_CANONICAL (for and entropy-coding
         scheme based on the canonical-code algorithm described by Moffat, et
         al. (International Journal of High Speed Electronics and Systems,
         Vol 8, No 1 (1997) 179-231)), CBF_PACKED or CBF_PACKED_V2 for J. P.
         Abrahams CCP4-style packing schemes and CBF_BYTE_OFFSET for a simple
         byte_offset compression scheme.. Other compression schemes will be
         added to this list in the future.

     For historical reasons, CBFlib can read or write a binary string without
     a MIME header. The structure of a binary string with simple headers is:

     Byte       ASCII                 Decimal  Description                    
                symbol                value    
       1          ;                     59       Initial ; delimiter          
       2          carriage-return       13                                    
       3          line-feed             10       The CBF new-line code is     
                                               carriage-return, line-feed     
       4          S                     83                                    
       5          T                     84                                    
       6          A                     65                                    
       7          R                     83                                    
       8          T                     84                                    
       9                                32                                    
       10         O                     79                                    
       11         F                     70                                    
       12                               32                                    
       13         B                     66                                    
       14         I                     73                                    
       15         N                     78                                    
       16         A                     65                                    
       17         R                     83                                    
       18         Y                     89                                    
       19                               32                                    
       20         S                     83                                    
       21         E                     69                                    
       22         C                     67                                    
       23         T                     84                                    
       24         I                     73                                    
       25         O                     79                                    
       26         N                     78                                    
       27         carriage-return       13                                    
       28         line-feed             10                                    
       29         form-feed             12                                    
       30         substitute            26       Stop the listing of the file 
                                               in MS-DOS                      
       31         end-of-transmission   4        Stop the listing of the file 
                                               in unix                        
       32                               213      First non-ASCII value        
       33 .. 40                                  Binary section identifier    
                                               (64-bit little-endien)         
       41 .. 48                                  Offset from byte 57 to the   
                                               first ASCII character          
                                               following the binary data      
       49 .. 56                                  Compression type             
     57 .. 57 + n-1                              Binary data (nbytes)         
       57 + n     carriage-return       13                                    
       58 + n     line-feed             10                                    
       59 + n     E                     69                                    
       60 + n     N                     78                                    
       61 + n     D                     68                                    
       62 + n                           32                                    
       63 + n     O                     79                                    
       64 + n     F                     70                                    
       65 + n                           32                                    
       66 + n     B                     66                                    
       67 + n     I                     73                                    
       68 + n     N                     78                                    
       69 + n     A                     65                                    
       70 + n     R                     83                                    
       71 + n     Y                     89                                    
       72 + n                           32                                    
       73 + n     S                     83                                    
       74 + n     E                     69                                    
       75 + n     C                     67                                    
       76 + n     T                     84                                    
       77 + n     I                     73                                    
       78 + n     O                     79                                    
       79 + n     N                     78                                    
       80 + n     carriage-return       13                                    
       81 + n     line-feed             10                                    
       82 + n     ;                     59       Final ; delimiter            

    3.3 Compression schemes

     Two schemes for lossless compression of integer arrays (such as images)
     have been implemented in this version of CBFlib:

     1. An entropy-encoding scheme using canonical coding
     2. A CCP4-style packing scheme. 3. A simple and efficient byte-offset
     compression. 4. A slightly more complex nibble-offset compression.

     All encode the difference (or error) between the current element in the
     array and the prior element or neighboring elements.

    3.3.1 Canonical-code compression

     The canonical-code compression scheme encodes errors in two ways:
     directly or indirectly. Errors are coded directly using a symbol
     corresponding to the error value. Errors are coded indirectly using a
     symbol for the number of bits in the (signed) error, followed by the
     error iteslf.

     At the start of the compression, CBFlib constructs a table containing a
     set of symbols, one for each of the 2^n direct codes from -2^(n-1) ..
     2^(n-1)-1, one for a stop code, and one for each of the maxbits -n
     indirect codes, where n is chosen at compress time and maxbits is the
     maximum number of bits in an error. CBFlib then assigns to each symbol a
     bit-code, using a shorter bit code for the more common symbols and a
     longer bit code for the less common symbols. The bit-code lengths are
     calculated using a Huffman-type algorithm, and the actual bit-codes are
     constructed using the canonical-code algorithm described by Moffat, et
     al. (International Journal of High Speed Electronics and Systems, Vol 8,
     No 1 (1997) 179-231).

     The structure of the compressed data is:

     Byte                                             Value                   
       1 .. 8                         Number of elements (64-bit              
                                    little-endian number)                     
       9 .. 16                        Minimum element                         
       17 .. 24                       Maximum element                         
       25 .. 32                       (reserved for future use)               
       33                             Number of bits directly coded, n        
       34                             Maximum number of bits encoded, maxbits 
       35 .. 35+2^n-1                 Number of bits in each direct code      
       35+2^n                         Number of bits in the stop code         
       35+2^n+1 .. 35+2^n+maxbits-n   Number of bits in each indirect code    
       35+2^n+maxbits-n+1 ..          Coded data                              

    3.3.2 CCP4-style compression

     Starting with CBFlib 0.7.7, CBFlib supports three variations on
     CCP4-style compression: the "flat" version supported in versions of
     CBFlib prior to release 0.7.7, as well as both version 1 and version 2
     of J. P. Abrahams "pack_c" compression.

     The CBF_PACKED and CBF_PACKED_V2 compression and decompression code
     incorporated in CBFlib is derived in large part from the J. P. Abrahams
     pack_c.c compression code in CCP4. This code is incorporated in CBFlib
     under the GPL and the LGPL with both the permission Jan Pieter Abrahams,
     the original author of pack_c.c (email from Jan Pieter Abrahams of 15
     January 2007) and of the CCP4 project (email from Martyn Winn on 12
     January 2007). The cooperation of J. P. Abrahams and of the CCP4 project
     is gratefully acknowledged.

     The basis for all three versions is a scheme to pack offsets
     (differences from a base value) into a small-endian bit stream. The
     stream is organized into blocks. Each block begins with a header of 6
     bits in the flat packed version and version 1 of J. P. Abrahams
     compression, and 7 bits in version 2 of J. P. Abrahams compression. The
     header gives the number of offsets that follow and the number of bits in
     each offset. Each offset is a signed, 2's complement integer.

     The first 3 bits in the header gives the logarithm base 2 of the numer
     of offsets that follow the header. For example, if a header has a zero
     in bits, only one offset follows the header. If those same bits contain
     the number n, the number of offsets in the block is 2n.

     The following 3 bits (flat and version 1) or 4 bits (version 2) contains
     a number giving an index into a table of bit-lengths for the offsets.
     All offsets in a given block are of the same length.

     Bits 3 .. 5 (flat and version 1) or bits 3 .. 6 (version 2) encode the
     number of bits in each offset as follows:

                  Value in    Number of bits    Number of bits   
                 bits 3 .. 5 in each V1 offset in each V2 offset 
                      0              0                 0         
                      1              4                 3         
                      2              5                 4         
                      3              6                 5         
                      4              7                 6         
                      5              8                 7         
                      6             16                 8         
                      7             max                9         
                      8                               10         
                      9                               11         
                     10                               12         
                     11                               13         
                     12                               14         
                     13                               15         
                     14                               16         
                     15                               max        

     The value "max" is determined by the compression version and the element
     size. If the compression used is "flat", then "max" is 65. If the
     compression is version 1 or version 2 of the JPA compression, then "max"
     is the number of bits in each element, i.e. 8, 16, 32 or 64 bits.

     The major difference between the three variants of packed compression is
     the choice of the base value from which the offset is measured. In all
     cases the first offset is measured from zero, i.e. the first offset is
     the value of the first pixel of the image. If "flat" is chosen or if the
     dimensions of the data array are not given, then the remaining offset
     are measure against the prior value, making it similar in approach to
     the "byte offset" compression described in section 3.3.3 Byte offset
     compression, but with a more efficient representation of the offsets.

     In version 1 and version 2 of the J. P. Abrahams compression, the
     offsets are measured against an average of earlier pixels. If there is
     only one row only the prior pxiel is used, starting with the same
     offsets for that row as for "flat". After the first row, three pixels
     from the prior row are used in addition to using the immediately prior
     pixel. If there are multiple sections, and the sections are marked as
     correlated, after the first section, 4 pixels from the prior section are
     included in the average. The CBFlib code differs from the pack_c code in
     the handling of the beginnings and ends of rows and sections. The pack_c
     code will use pixels from the other side of the image in doing the
     averaging. The CBFlib code drops pixels from the other side of the image
     from the pool. The details follow.

     After dealing with the special case of the first pixel, The algorithm
     uses an array of pointers, trail_char_data. The assignment of pixels to
     the pool to be averaged begins with trail_char_data[0] points to the
     pixel immediately prior to the next pixel to be processed, either in the
     same row (fastest index) or, at the end of the prior row if the next
     data element to be processed is at the end of a row. The location of the
     pixel pointed to by trail_char_data[0] is used to compute the locations
     of the other pixels in the pool. It will be dropped from the pool before
     averaging if it is on the opposite side of the image. The pool will
     consist of 1, 2, 4 or 8 pixels.

     Assume ndim1, ndim2, ndim3 are the indices of the same pixel as
     trail_char_data[0] points to. These indices are incremented to be the
     indices of the next pixel to be processed before populating
     trail_char_data.

     On exit, trail_char_data[0 .. 7] will have been populated with pointers
     to the pixels to be used in forming the average. Pixels that will not be
     used will be set to NULL. Note that trail_char_data[0] may be set to
     NULL.

     If we mark the next element to be processed with a "*" and the entries
     in trail_char_data with their array indices 0 .. 7, the possible
     patterns of settings in the general case are:

     current section:

    
          - - - - 0 * - - - -
          - - - - 3 2 1 - - -
          - - - - - - - - - -

     prior section:

    
          - - - - - 4 - - - -
          - - - - 7 6 5 - - -
          - - - - - - - - - -

     If there is no prior section (i.e. ndim3 is 0, or the
     CBF_UNCORRELATED_SECTIONS flag is set to indicate discontinuous
     sections), the values for trail_char_data[4 .. 7] will all be NULL. When
     there is a prior section, trail_char_data[5..7] are pointers to the
     pixels immediately below the elements pointed to by
     trail_char_data[1..3], except trail_char_data[4] is one element further
     along its row to be directly below the next element to be processed.

     The first element of the first row of the first section is a special
     case, with no averaging.

     In the first row of the first section (ndim2 == 0, and ndim3 == 0),
     after the first element (ndim1 > 0), only trail_char_data[0] is used

     current section:

        
          - - - - 0 * - - - -

     For subsequent rows of the first section (ndim2 > 0, and ndim3 == 0),
     for the first element (ndim1 == 0), two elements from the prior row are
     used:

     current section:

    
          * - - - - - - - - -
          2 1 - - - - - - - -
          - - - - - - - - - -

     while for element after the first element, but before the last element
     of the row, a full set of 4 elements is used:

     current section:

    
          - - - - 0 * - - - -
          - - - - 3 2 1 - - -
          - - - - - - - - - -

     For the last element of a row (ndim1 == dim1-1), two elements are used

     current section:

   
          - - - - - - - - 0 *
          - - - - - - - - - 2
          - - - - - - - - - -

     For sections after the first section, provided the
     CBF_UNCORRELATED_SECTIONS flag is not set in the compression, for each
     non-NULL entry in trail_char_data [0..3] an entry is made in
     trail_char_data [4..7], except for the first element of the first row of
     a section. In that case an entry is made in trail_char_data[4].

     The structure of the compressed data is:

             Byte                          Value                        
            1 .. 8     Number of elements (64-bit little-endian number) 
            9 .. 16    Minumum element (currently unused)               
            17 .. 24   Maximum element (currently unused)               
            25 .. 32   (reserved for future use)                        
            33 ..      Coded data                                       

    3.3.3 Byte_offset compression

     Starting with CBFlib 0.7.7, CBFlib supports a simple and efficient
     "byte_offset" algorithm originally proposed by Andy Hammerley and
     modified by Wolgang Kabsch and Herbert Bernstein. The original proposal
     was called "byte_offsets". We distinguish this variant by calling it
     "byte_offset". The major differences are that the "byte_offsets"
     algorithm started with explicit storage of the first element of the
     array as a 4-byte signed two's integer, and checked for image edges to
     changes the selection of prior pixel. The CBFlib "byte_offset"
     alogorithm starts with an assumed zero before the first pixel and
     represents the value of the first pixel as an offset of whatever number
     of size is needed to hold the value, and for speed, treats the entire
     image as a simple linear array, allowing use of the last pixel of one
     row as the base against which to compute the offset for the first
     element of the next row.

     The algorithm is simple and easily implemented. This algorithm can never
     achieve better than a factor of two compression relative to 16-bit raw
     data or 4 relative to 32-bit raw data, but for most diffraction data the
     compression will indeed be very close to these ideal values. It also has
     the advantage that integer values up to 32 bits (or 31 bits and sign)
     may be stored efficiently without the need for special over-load tables.
     It is a fixed algorithm which does not need to calculate any image
     statistics, so is fast.

     The algorithm works because of the following property of almost all
     diffraction data and much other image data: The value of one element
     tends to be close to the value of the adjacent elements, and the vast
     majority of the differences use little of the full dynamic range.
     However, noise in experimental data means that run-length encoding is
     not useful (unless the image is separated into different bit-planes). If
     a variable length code is used to store the differences, with the number
     of bits used being inversely proportional to the probability of
     occurrence, then compression ratios of 2.5 to 3.0 may be achieved.
     However, the optimum encoding becomes dependent of the exact properties
     of the image, and in particular on the noise. Here a lower compression
     ratio is achieved, but the resulting algorithm is much simpler and more
     robust.

     The "byte_offset" compression algorithm is the following:

      1. Start with a base pixel value of 0.
      2. Compute the difference delta between the next pixel value and the
         base pixel value.
      3. If -127 =< delta =< 127, output delta as one byte, make the current
         pixel value the base pixel value and return to step 2.
      4. Otherwise output -128 (80 hex).
      5. We still have to output delta. If -32767 =< delta =< 32767, output
         delta as a little_endian 16-bit quantity, make the current pixel
         value the base pixel value and return to step 2.
      6. Otherwise output -32768 (8000 hex, little_endian, i.e. 00 then 80)
      7. We still have to output delta. If -2147483647 =< delta =<
         2147483647, output delta as a little_endian 32 bit quantity, make
         the current pixel value the base pixel value and return to step 2.
      8. Otherwise output -2147483648 (80000000 hex, little_endian, i.e. 00,
         then 00, then 00, then 80) and then output the pixel value as a
         little-endian 64 bit quantity, make the current pixel value the base
         pixel value and return to step 2.

     The "byte_offset" decompression algorithm is the following:

      1. Start with a base pixel value of 0.
      2. Read the next byte as delta
      3. If -127 =< delta =< 127, add delta to the base pixel value, make
         that the new base pixel value, place it on the output array and
         return to step 2.
      4. If delta is 80 hex, read the next two bytes as a little_endian
         16-bit number and make that delta.
      5. If -32767 =< delta =< 32767, add delta to the base pixel value, make
         that the new base pixel value, place it on the output array and
         return to step 2.
      6. If delta is 8000 hex, read the next 4 bytes as a little_endian
         32-bit number and make that delta
      7. If -2147483647 =< delta =< 2147483647, add delta to the base pixel
         value, make that the new base pixel value, place it on the output
         array and return to step 2.
      8. If delta is 80000000 hex, read the next 8 bytes as a little_endian
         64-bit number and make that delta, add delta to the base pixel
         value, make that the new base pixel value, place it on the output
         array and return to step 2.

     Let us look at an example, of two 1000 x 1000 flat field images
     presented as a mimimal imgCIF file. The first image uses 32-bit unsigned
     integers and the second image uses 16-bit unsigned integers.

     The imgCIF file begins with some identifying comments (magic numbers) to
     track the version of the dictionary and library:

 ###CBF: VERSION 1.5
 # CBF file written by CBFlib v0.7.7

     This is followed by the necessary syntax to start a CIF data block and
     by whatever tags and values are appropriate to describe the experiment.
     The minimum is something like

 data_testflat

     eventually we come to the actual binary data, which begins the loop
     header for the array_data category

 loop_
 _array_data.data

     with any additional tags needed, and then the data itself, which starts
     with the mini-header:

 ;
 --CIF-BINARY-FORMAT-SECTION--
 Content-Type: application/octet-stream;
      conversions="x-CBF_BYTE_OFFSET"
 Content-Transfer-Encoding: BINARY
 X-Binary-Size: 1000002
 X-Binary-ID: 1
 X-Binary-Element-Type: "unsigned 32-bit integer"
 X-Binary-Element-Byte-Order: LITTLE_ENDIAN
 Content-MD5: +FqUJGxXhvCijXMFHC0kaA==
 X-Binary-Number-of-Elements: 1000000
 X-Binary-Size-Fastest-Dimension: 1000
 X-Binary-Size-Second-Dimension: 1000
 X-Binary-Size-Padding: 4095

     followed by an empty line and then the sequence of characters:

 ^L^Z^D<D5>

     followed immediately by the compressed data.

     The binary data begins with the hex byte 80 to flag the need for a value
     that will not fit in one byte. That is followed by the small_endian hex
     value 3E8 saying that the first delta is 1000. Then 999,999 bytes of
     zero follow, since this is a flat field, with all values equal to zero.
     That gives us our entire 1000x1000 compressed flat field. However,
     because we asked for 4095 bytes of padding, there is an additional 4095
     bytes of zero that are not part of the compressed field. They are just
     pad and can be ignored. Finally, after the pad, the CIF text field that
     began with

 ;
 --CIF-BINARY-FORMAT-SECTION--

     is completed with

 --CIF-BINARY-FORMAT-SECTION----
 ;

     notice the extra --

     The second flat field then follows, with a very similar mini-header:

 ;
 --CIF-BINARY-FORMAT-SECTION--
 Content-Type: application/octet-stream;
      conversions="x-CBF_BYTE_OFFSET"
 Content-Transfer-Encoding: BINARY
 X-Binary-Size: 1000002
 X-Binary-ID: 2
 X-Binary-Element-Type: "unsigned 16-bit integer"
 X-Binary-Element-Byte-Order: LITTLE_ENDIAN
 Content-MD5: +FqUJGxXhvCijXMFHC0kaA==
 X-Binary-Number-of-Elements: 1000000
 X-Binary-Size-Fastest-Dimension: 1000
 X-Binary-Size-Second-Dimension: 1000
 X-Binary-Size-Padding: 4095

 ^L^Z^D<D5>

     The only difference is that we have declared this array to be 16-bit and
     have chosen a different binary id (2 instead of 1). Even the checksum is
     the same.

    3.3.4 Nibble_offset compression

     The nibble offset algorithm is a variant on A. P. Hammersley's byte
     offset algorithm. The major differences are that the compression modes
     are "sticky", the compression can be reset at any point to allow for
     block parallelism, and the basic unit of compression is the nibble, but
     for very clean data, the dibit is also supported.

     The data stream starts with and in general uses a mode-setting octet
     presented in one if three forms, a single dibit a0, two dibits a0, a1,
     or two dibits and a nibble a0, a1, b:

                +-----------------------------------------------+
                |  a0 a1 b   | octet |         meaning          |
                |------------+-------+--------------------------|
                | 00 00 0000 | 0x00  | reset to zero            |
                |------------+-------+--------------------------|
                | 01         | 0x01  | up 1 mode                |
                |------------+-------+--------------------------|
                | 10         | 0x02  | dibit mode               |
                |------------+-------+--------------------------|
                | 11         | 0x03  | up n modes               |
                |------------+-------+--------------------------|
                | 00 01      | 0x04  | nibble mode              |
                |------------+-------+--------------------------|
                | 00 11      | 0x0C  | 6-bit mode               |
                |------------+-------+--------------------------|
                | 00 10      | 0x08  | byte mode                |
                |------------+-------+--------------------------|
                | 00 00 0011 | 0x30  | 12-bit word mode         |
                |------------+-------+--------------------------|
                | 00 00 0001 | 0x10  | 16-bit word mode         |
                |------------+-------+--------------------------|
                | 00 00 0010 | 0x20  | 32-bit word mode         |
                |------------+-------+--------------------------|
                | 00 00 0100 | 0x40  | 64-bit word mode         |
                |------------+-------+--------------------------|
                | 00 00 1100 | 0xC0  | specify starting address |
                +-----------------------------------------------+

     The reset to zero is followed by a new mode octet A reset to zero resets
     the prior value for delta to zero

     The up n modes code is followed immediately by a dibit specifying 2 less
     than the number of modes by which to change, and then by a delta in the
     mode.

     Note that up n modes has no effect until an actual mode has been set and
     can be used immediately after a reset to pad to nibble, octet or
     double-word boundaries.

     Once a mode is established, it is followed by a stream of deltas of that
     size (for modes 2 or 4-64) or by one delta of that size and then a
     stream of deltas of the size that was in effect before an up or down
     giving little-endian offsets from the currently accumulated value. If
     the offset is one of the following in the indicated mode

                   +------------------------------------------+
                   | dibit mode       | 0x2                   |
                   |------------------+-----------------------|
                   | nibble mode      | 0x8                   |
                   |------------------+-----------------------|
                   | 6-bit mode       | 0x20                  |
                   |------------------+-----------------------|
                   | byte mode        | 0x80                  |
                   |------------------+-----------------------|
                   | 12-bit word mode | 0x800                 |
                   |------------------+-----------------------|
                   | 16-bit word mode | 0x8000                |
                   |------------------+-----------------------|
                   | 32-bit word mode | 0x8000 0000           |
                   |------------------+-----------------------|
                   | 64-bit word mode | 0x8000 0000 0000 0000 |
                   +------------------------------------------+

     it is followed by the new mode as 1 or 2 dibits or 2 dibits and a nibble
     a1 a1 b. If a1 is 1 or 2 or 3, that is the new mode. If a1 is zero and
     a2 is 1 or 2 the new mode is a2*4. If a2 is 3 the new mode is a2*2. If
     both a1 and a2 are zero, the new mode is b*16 unless b is 3. If b is 3
     the new mode is b*4

     The 0xC0 flag is followed by a second mode giving the number of bytes of
     image starting offset address followed by the image offset address
     followed by the mode of that data. 0xC0 also acts as a reset. Use of the
     0xC0 flag is not required. Addresses default to sequential starting from
     0, but is provided to faciliate parallel compression.

    3.4 Access to CBFlib compressions from HDF5

     Starting with CBFlib release 0.9.2.11, a plugin module in provided to
     allow access to CBFlib compressions from HDF5 1.8.11 and later. For
     general documentation on HDF5 dynamically loaded filters, see
     http://www.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf
     The discussion here will be confined to use of the CBFlib compressions
     plugin.

     The filter has been registered with the HDF5 group as 32006, and cbf.h
     includes the symbolic name for the filter CBF_H5Z_FILTER_CBF.

     The source and header of the CBFlib filter plugin are cbf_hdf5_filter.c
     and cbf_hdf5_filter.h. To use the filter in C applications, you will
     need to include cbf_hdf5_filter.h in the application and have the
     cbflib.so library in the search path used by HDF5 1.8.11. The HDF group
     says

       The default directory for an HDF5 filter plugin library is defined on
       UNIX- like systems as quot;/usr/local/hdf5/lib/plugin"
       and on Windows systems as "%ALLUSERSPROFILE%/hdf5/lib/plugin". The
       default path can be overwritten by a user with the HDF5_PLUGIN_PATH
       environment variable. Several directories can be specified for the
       search path using ":" as a path separator for UNIX-like systems and
       ";" for Windows.

     In the Makefile, tests are done by defining HDF5_PLUGIN_PATH to point to
     the build kit shared library directory:

     HDF5_PLUGIN_PATH=$(SOLIB); export HDF5_PLUGIN_PATH;

     In most cases that should be sufficient to allow code to read HDF5 files
     with datasets compressed with this filter.

     In order to write files that use this filter, several relevant values
     must first be stored into an unsigned int array, cd_values. The header,
     cbf_hdf5_filter.h, defines the follwing symbolic values for the indices
     of this array:

+------------------------------------------------------------------------------+
     |             symbol             | value |           meaning           |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_NELMTS      | 11    | size of cd_values           |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_COMPRESSION | 0     | one of the compressions (see 3.2.2) |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_RESERVED    | 1     | reserved for future use, should be  |
|                                |       | set to zero                         |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_BINARY_ID   | 2     | binary ID of the array (default 1)  |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_ELSIZE      | 3     | element size in octets      |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_ELSIGN      | 4     | 1 if signed, 0 if unsigned  |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_REAL        | 5     | 1 if a real array, 0 if an integer  |
|                                |       | array                               |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_DIMOVER     | 6     | the total number of elements in the |
|                                |       | array                               |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_DIMFAST     | 7     | the fast dimension          |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_DIMMID      | 8     | the middle dimension        |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_DIMSLOW     | 9     | the slow domension          |
|--------------------------------+-------+-------------------------------------|
     | CBF_H5Z_FILTER_CBF_PADDING     | 10    | the padding                 |
+------------------------------------------------------------------------------+

     Only chunked data may be written using this filter. The recommended
     chunk size is a single image. The filter writes the chunks using the
     imgCIF binary section format described in section 3.2.1 including the
     MIME header. If each chunk is the size of an image, programs such as XDS
     can use the patterns of the MIME header to skip directly to a frame even
     in a complex HDF5 file. Typical code to write such chunks would first
     define the cd_values array and an array of chunk dimensions and create
     the properties to be used in creating a dataset, as in

     unsigned int cd_values[CBF_H5Z_FILTER_CBF_NELMTS];
     hsize_t chunk[3];
     hid_t valspace;
     chunk[0] = 1;
     chunk[1] = dimmid;
     chunk[2] = dimfast;
     cd_values[CBF_H5Z_FILTER_CBF_COMPRESSION] = compression;
     cd_values[CBF_H5Z_FILTER_CBF_RESERVED]    = 0;
     cd_values[CBF_H5Z_FILTER_CBF_BINARY_ID]   = id;
     cd_values[CBF_H5Z_FILTER_CBF_PADDING]     = padding;
     cd_values[CBF_H5Z_FILTER_CBF_ELSIZE]      = (bits+7)/8;
     cd_values[CBF_H5Z_FILTER_CBF_ELSIGN]      = sign;
     cd_values[CBF_H5Z_FILTER_CBF_REAL]        = realarray;
     cd_values[CBF_H5Z_FILTER_CBF_DIMFAST]     = dimfast;
     cd_values[CBF_H5Z_FILTER_CBF_DIMMID]      = dimmid;
     cd_values[CBF_H5Z_FILTER_CBF_DIMSLOW]     = dimslow;
     valprop = H5Pcreate(H5P_DATASET_CREATE);
     H5Pset_chunk(valprop,3,chunk);
     H5Pset_filter(valprop,CBF_H5Z_FILTER_CBF,H5Z_FLAG_OPTIONAL,CBF_H5Z_FILTER_CBF_NELMTS,cd_values);

    4. Installation

     CBFlib should be built on a disk with at least 400 megabytes of free
     space. CBFlib-0.9.2.11.tar.gz is a "gzipped" tar of the code as it now
     stands. Place the gzipped tar in the directory that is intended to
     contain a new directory, named CBFlib_0.9.2.11 (the "top-level"
     directory) and uncompress it with gunzip and unpack it with tar:

      gunzip CBFlib.tar.gz
      tar xvf CBFLIB.tar

     As with prior releases, to run the test programs, you will also need
     Paul Ellis's sample MAR345 image, example.mar2300, and Chris Nielsen's
     sample ADSC Quantum 315 image, mb_LP_1_001.img as sample data. Both
     these files will be extracted by the Makefile from
     CBFlib_0.7.7_Data_Files. Do not download copies into the top level
     directory.

     After unpacking the archive, the top-level directory should contain a
     makefile:

                            Makefile   Makefile for unix 

     and the subdirectories:

          src/           CBFLIB source files                              
          include/       CBFLIB header files                              
          m4/            CBFLIB m4 macro files (used to build .f90 files) 
          examples/      Example program source files                     
          doc/           Documentation                                    
          lib/           Compiled CBFLIB library                          
          bin/           Executable example programs                      
          html_images/   JPEG images used in rendering the HTML files     

     For instructions on compiling and testing the library, go to the
     top-level directory and type:

      make

     The CBFLIB source and header files are in the "src" and "include"
     subdirectories. The FCBLIB source and m4 files are in the "src" and "m4"
     subdirectories. The files are:

src/                      include/             m4/                  Description         
  cbf.c                     cbf.h                                     CBFLIB API        
                                                                    functions           
  cbf_alloc.c               cbf_alloc.h                               Memory allocation 
                                                                    functions           
  cbf_ascii.c               cbf_ascii.h                               Function for      
                                                                    writing ASCII       
                                                                    values              
  cbf_binary.c              cbf_binary.h                              Functions for     
                                                                    binary values       
  cbf_byte_offset.c         cbf_byte_offset.h                         Byte-offset       
                                                                    compression         
  cbf_canonical.c           cbf_canonical.h                           Canonical-code    
                                                                    compression         
  cbf_codes.c               cbf_codes.h                               Encoding and      
                                                                    message digest      
                                                                    functions           
  cbf_compress.c            cbf_compress.h                            General           
                                                                    compression         
                                                                    routines            
  cbf_context.c             cbf_context.h                             Control of        
                                                                    temporary files     
  cbf_file.c                cbf_file.h                                File in/out       
                                                                    functions           
  cbf_lex.c                 cbf_lex.h                                 Lexical analyser  
  cbf_packed.c              cbf_packed.h                              CCP4-style        
                                                                    packing compression 
  cbf_predictor.c           cbf_predictor.h                           Predictor-Huffman 
                                                                    compression (not    
                                                                    implemented)        
  cbf_read_binary.c         cbf_read_binary.h                         Read binary       
                                                                    headers             
  cbf_read_mime.c           cbf_read_mime.h                           Read MIME-encoded 
                                                                    binary sections     
  cbf_simple.c              cbf_simple.h                              Higher-level      
                                                                    CBFlib functions    
  cbf_string.c              cbf_string.h                              Case-insensitive  
                                                                    string comparisons  
  cbf_stx.c                 cbf_stx.h                                 Parser (generated 
                                                                    from cbf.stx.y)     
  cbf_tree.c                cbf_tree.h                                CBF               
                                                                    tree-structure      
                                                                    functions           
  cbf_uncompressed.c        cbf_uncompressed.h                        Uncompressed      
                                                                    binary sections     
  cbf_write.c               cbf_write.h                               Functions for     
                                                                    writing             
  cbf_write_binary.c        cbf_write_binary.h                        Write binary      
                                                                    sections            
  cbf.stx.y                                                           bison grammar to  
                                                                    define cbf_stx.c    
                                                                    (see WARNING)       
  md5c.c                    md5.h                                     RSA message       
                                                                    digest software     
                                                                    from mpack          
                            global.h                                                    
  fcb_atol_wcnt.f90                                                   Function to       
                                                                    convert a string to 
                                                                    an integer          
  fcb_ci_strncmparr.f90                                               Function to do a  
                                                                    case-insensitive    
                                                                    comparison of a     
                                                                    string to a byte    
                                                                    array               
  fcb_nblen_array.f90                                                 Function to       
                                                                    determine the       
                                                                    non-blank length of 
                                                                    a byte array        
  fcb_read_byte.f90                                                   Function to read  
                                                                    a single byte       
  fcb_read_line.f90                                                   Function to read  
                                                                    a line into a byte  
                                                                    array               
  fcb_skip_whitespace.f90                                             Function to skip  
                                                                    whitespace and      
                                                                    comments in a MIME  
                                                                    header              
                                                 fcb_exit_binary.m4   Function to skip  
                                                                    past the end of the 
                                                                    current binary text 
                                                                    field               
                                                 fcb_next_binary.m4   Function to skip  
                                                                    to the next binary  
                                                 fcb_open_cifin.m4    Function to open  
                                                                    a CBF file for      
                                                                    reading             
                                                 fcb_packed.m4        Functions to read 
                                                                    a JPA CCP4          
                                                                    compressed image    
                                                 fcb_read_bits.m4     Functions to read 
                                                                    nay number of bits  
                                                                    as an integer       
                                                 fcb_read_image.m4    Functions to read 
                                                                    the next image in   
                                                                    I2, I4, 3D_I2 and   
                                                                    3D_I4 format        
                                                 fcb_read_xds_i2.m4   Function to read  
                                                                    a single xds image. 
                                                 fcblib_defines.m4    General m4 macro  
                                                                    file for FCBLIB     
                                                                    routines.           

     In the "examples" subdirectory, there are 2 additional files used by the
     example programs (section 5) for reading MAR300, MAR345 or ADSC CCD
     images:

                        img.c   img.h   Simple image library 

     and the example programs themselves:

       makecbf.c         Make a CBF file from an image                        
       img2cif.c         Make an imgCIF or CBF from an image                  
       cif2cbf.c         Copy a CIF/CBF to a CIF/CBF                          
       convert_image.c   Convert an image file to a cbf using a template file 
       cif2c.c           Convert a template cbf file into a function to       
                       produce the same template in an internal cbf data      
                       structure                                              
       testcell.C        Exercise the cell functions                          

     as well as three template files: template_adscquantum4_2304x2304.cbf,
     template_mar345_2300x2300.cbf, and
     template_adscquantum315_3072x3072.cbf.

     Two additional examples (test_fcb_read_image.f90 and
     test_xds_binary.f90) are created from two files (test_fcb_read_image.m4
     and test_xds_binary.m4) in the m4 directory.

     The documentation files are in the "doc" subdirectory:

         CBFlib.html               This document (HTML)                     
         CBFlib.txt                This document (ASCII)                    
         CBFlib_NOTICES.html       Important NOTICES -- PLEASE READ         
         CBFlib_NOTICES.txt        Important NOTICES -- PLEASE READ         
         gpl.txt                   GPL -- PLEASE READ                       
         lgpl.txt                  LGPL -- PLEASE READ                      
         cbf_definition_rev.txt    Draft CBF/ImgCIF definition (ASCII)      
         cbf_definition_rev.html   Draft CBF/ImgCIF definition (HTML)       
         cif_img.html              CBF/ImgCIF extensions dictionary (HTML)  
         cif_img.dic               CBF/ImgCIF extensions dictionary (ASCII) 
         ChangeLog,html            Summary of change history (HTML)         
         ChangeLog                 Summary of change history (ASCII)        

    5. Example programs

     The example programs makecbf.c, img2cif.c and convert_image.c read an
     image file from a MAR300, MAR345 or ADSC CCD detector and then uses
     CBFlib to convert it to CBF format (makecbf) or either imgCIF or CBF
     format (img2cif). makecbf writes the CBF-format image to disk, reads it
     in again, and then compares it to the original. img2cif just writes the
     desired file. makecbf works only from stated files on disk, so that
     random I/O can be used. img2cif includes code to process files from
     stdin and to stdout. convert_image reads a template as well as the image
     file and produces a complete CBF. The program convert_minicbf reads a
     minimal CBF file with just and image and some lines of text specifying
     the parameters of the data collection as done at SLS and combines the
     result with a template to produce a full CBF. The program cif2cbf can be
     used to convert among carious compression and encoding schemes. The
     program sauter_test.C is a C++ test program contributed by Nick Sauter
     to help in resolving a memory leak he found. The programs adscimg2cbf
     and cbf2adscimg are a "jiffies" contributed by Chris Nielsen of ADSC to
     convert ADSC images to imgCIF/CBF format and vice versa.

     makecbf.c is a good example of how many of the CBFlib functions can be
     used. To compile makecbf and the other example programs use the Makefile
     in the top-level directory:

      make all

     This will place the programs in the bin directory.

    makecbf

     To run makecbf with the example image, type:

      ./bin/makecbf example.mar2300 test.cbf

     The program img2cif has the following command line interface:

  img2cif     [-i  input_image]                               \
              [-o  output_cif]                                \
              [-c  {p[acked]|c[annonical]|[n[one]}]           \
              [-m  {h[eaders]|n[oheaders]}]                   \
              [-d  {d[igest]|n[odigest]}]                     \
              [-e  {b[ase64]|q[uoted-printable]|              \
                    d[ecimal]|h[exadecimal]|o[ctal]|n[one]}]  \
              [-b  {f[orward]|b[ackwards]}]                   \
              [input_image] [output_cif]

  the options are:

  -i  input_image (default: stdin)
      the input_image file in MAR300, MAR345 or ADSC CCD detector
      format is given.  If no input_image file is specified or is
      given as "-", an image is copied from stdin to a temporary file.

  -o  output_cif (default: stdout)
      the output cif (if base64 or quoted-printable encoding is used)
      or cbf (if no encoding is used).  if no output_cif is specified
      or is given as "-", the output is written to stdout

  -c  compression_scheme (packed, canonical or none, default packed)

  -m  [no]headers (default headers for cifs, noheaders for cbfs)
      selects MIME (N. Freed, N. Borenstein, RFC 2045, November 1996)
      headers within binary data value text fields.

  -d  [no]digest  (default md5 digest [R. Rivest, RFC 1321, April
      1992 using"RSA Data Security, Inc. MD5 Message-Digest
      Algorithm"] when MIME headers are selected)

  -e  encoding (base64, quoted-printable, decimal, hexadecimal,
      octal or none, default: base64) specifies one of the standard
      MIME encodings (base64 or quoted-printable) or a non-standard
      decimal, hexamdecimal or octal encoding for an ascii cif
      or "none" for a binary cbf

  -b  direction (forward or backwards, default: backwards)
      specifies the direction of mapping of bytes into words
      for decimal, hexadecimal or octal output, marked by '>' for
      forward or '<' for backwards as the second character of each
      line of output, and in '#' comment lines.


    cif2cbf

     The test program cif2cbf uses many of the same command line options as
     img2cif, but accepts either a CIF or a CBF as input instead of an image
     file:

     cif2cbf [-i input_cif] [-o output_cbf] \
       [-u update_cif] \
       [-c {p[acked]|c[annonical]|{b[yte_offset]}|\
         {v[2packed]}|{f[latpacked]}|{I|nIbble_offset}|n[one]}] \
       [-C highclipvalue] \
       [-D ] \
       [-I {0|2|4|8}] \
       [-R {0|4|8}] \
       [-L {0|4|8}] \
       [-m {h[eaders]|noh[eaders]}] \
         [-m {d[imensions]|nod[imensions}] \
       [-d {d[igest]|n[odigest]|w[arndigest]}] \
       [-B {read|liberal|noread}] [-B {write|nowrite}] \
       [-S {read|noread}] [-S {write|nowrite}] \
       [-T {read|noread}] [-T {write|nowrite}] \
       [-e {b[ase64]|q[uoted-printable]|\
         d[ecimal]|h[examdecimal|o[ctal]|n[one]}] \
       [-b {f[orward]|b[ackwards]}\
       [-p {1|2|4}\
       [-v dictionary]* [-w] [-W]\
       [-5 {r|w|rw|rn|wn|rwn|n[oH5]}\
       [-O] \
       [input_cif] [output_cbf]

   the options are:

        the options are:                                                 
                                                                         
        -i input_cif (default: stdin)                                    
          the input  file in CIF or CBF  format.  If input_cif is not    
          specified or is given as "-", it is copied from stdin to a     
          temporary file.                                                
                                                                         
        -o output_cbf (default: stdout)                                  
          the output cif (if base64 or quoted-printable encoding is used)
          or cbf (if no encoding is used).  if no output_cif is specified
          or is given as "-", the output is written to stdout            
          if the output_cbf is /dev/null, no output is written.          
                                                                         
        -u update_cif (no default)                                       
          and optional second input file in CIF or CBF format containing 
          data blocks to be merged with data blocks from the primary     
          input CIF or CBF                                               
                                                                         
        The remaining options specify the characteristics of the         
        output cbf.  Most of the characteristics of the input cif are    
        derived from context, except when modified by the -B, -S, -T, -v 
        and -w flags.                                                    
                                                                         
        -b byte_order (forward or backwards, default forward (1234) on   
          little-endian machines, backwards (4321) on big-endian machines
                                                                         
        -B [no]read or liberal (default noread)                          
          read to enable reading of DDLm style brackets                  
          liberal to accept whitespace for commas                        
                                                                         
        -B [no]write (default write)                                     
          write to enable writing of DDLm style brackets                 
                                                                         
        -c compression_scheme (Packed, Canonical, Byte_offset,           
          V2packed, Flatpacked, nIbble or None,                          
          default packed)                                                
                                                                         
        -C highclipvalue                                                 
          specifies a double precision value to which to clip the data   
                                                                         
        -d [no]digest or warndigest  (default md5 digest [R. Rivest,     
          RFC 1321, April 1992 using"RSA Data Security, Inc. MD5         
          Message-Digest Algorithm"] when MIME headers are selected)     
                                                                         
        -D test cbf_construct_detector                                   
                                                                         
        -e encoding (base64, k, quoted-printable or none, default base64)
          specifies one of the standard MIME encodings for an ascii cif  
          or "none" for a binary cbf                                     
                                                                         
        -I 0 or integer element size                                     
          specifies integer conversion of the data, 0 to use the input   
          number of bytes, 2, 4 or 8 for short, long or long long        
          output integers                                                
                                                                         
        -L lowclipvalue                                                  
          specifies a double precision value to cut off the data from    
          below                                                          
                                                                         
        -m [no]headers (default headers)                                 
          selects MIME (N. Freed, N. Borenstein, RFC 2045, November 1996)
          headers within binary data value text fields.                  
                                                                         
        -m [nod]imensions (default dimensions)                           
          selects detailed recovery of dimensions from the input CIF     
          for use in the MIME header of the output CIF                   
                                                                         
        -p K_of_padding (0, 1, 2, 4) for no padding after binary data    
          1023, 2047 or 4095 bytes of padding after binary data          
                                                                         
        -R 0 or integer element size                                     
          specifies real conversion of the data, 0 to use the input      
          number of bytes,  4 or 8 for float or double output reals      
                                                                         
        -S [no]read or (default noread)                                  
          read to enable reading of whitespace and comments              
                                                                         
        -S [no]write (default write)                                     
          write to enable writing of whitespace and comments             
                                                                         
        -T [no]read or (default noread)                                  
          read to enable reading of DDLm style triple quotes             
                                                                         
        -T [no]write (default write)                                     
          write to enable writing of DDLm style triple quotes            
                                                                         
        -v dictionary specifies a dictionary to be used to validate      
          the input cif and to apply aliases to the output cif.          
          This option may be specified multiple times, with dictionaries 
          layered in the order given.                                    
                                                                         
        -w process wide (2048 character) lines                           
                                                                         
        -W write wide (2048 character) lines                             
                                                                         
        -5 hdf5mode specifies whether to read and/or write in hdf5 mode  
           the n parameter will cause the CIF H5 datablock to be deleted 
           on both read and write, for both CIF, CBF and HDF5 files      
                                                                         
        -O when in -5 w (hdf5 write) mode, -O forces the use of opaque   
           objects for CBF binaries                                      
                                                                         
                                                                         


    convert_image

     The program convert_image requires two arguments: imagefile and cbffile.
     Those are the primary input and output. The detector type is extracted
     from the image file or from the command line, converted to lower case
     and used to construct the name of a template cbf file to use for the
     copy. The template file name is of the form template_name_columnsxrows.
     The full set of options is:


   convert_image [-i input_img] [-o output_cbf] [-p template_cbf]\
     [-d detector name]  -m [x|y|x=y] [-z distance]              \
     [-c category_alias=category_root]*                          \
     [-t tag_alias=tag_root]* [-F] [-R]                          \
     [input_img] [output_cbf]

   the options are:

   -i input_img (default: stdin)
     the input file as an image in smv, mar300, or mar345  format.
     If input_img is not specified or is given as "-", it is copied
     from stdin to a temporary file.

   -p template_cbf
     the template for the final cbf to be produced.  If template_cbf
     is not specified the name is constructed from the first token
     of the detector name and the image size as
        template_<type>_<columns>x<rows>.cbf

   -o output_cbf (default: stdout )
     the output cbf combining the image and the template.  If the
     output_cbf is not specified or is given as "-", it is written
     to stdout.

   -d detectorname
     a detector name to be used if none is provided in the image
     header.

   -F
     when writing packed compression, treat the entire image as
     one line with no averaging

   -m [x|y|x=y] (default x=y, square arrays only)
     mirror the array in the x-axis (y -> -y)
                      in the y-axis (x -> -x)
                   or in x=y ( x -> y, y-> x)

   -r n
     rotate the array n times 90 degrees counter clockwise
     x -> y, y -> -x for each rotation, n = 1, 2 or 3

   -R
     if setting a beam center, set reference values of
     axis settings as well as standard settings

   -z distance
     detector distance along Z-axis

   -c category_alias=category_root
   -t tag_alias=tagroot
     map the given alias to the given root, so that instead
     of outputting the alias, the root will be presented in the
     output cbf instead.  These options may be repeated as many
     times as needed.

    convert_minicbf

     The program convert_minicbf requires two arguments: minicbf and cbffile.
     Those are the primary input and output. The detector type is extracted
     from the image file or from the command line, converted to lower case
     and used to construct the name of a template cbf file to use for the
     copy. The template file name is of the form template_name_columnsxrows.
     The full set of options is:


   convert_minicbf [-i input_cbf] [-o output_cbf] [-p template_cbf]\
     [-q] [-C convention]                                        \
     [-d detector name]  -m [x|y|x=y] [-z distance]              \
     [-c category_alias=category_root]*                          \
     [-t tag_alias=tag_root]* [-F] [-R]                          \
     [input_cbf] [output_cbf]

   the options are:

   -i input_cbf (default: stdin)
     the input file as a CBF with at least an image.

   -p template_cbf
     the template for the final cbf to be produced.  If template_cbf
     is not specified the name is constructed from the first token
     of the detector name and the image size as
        template_<type>_<columns>x<rows>.cbf

   -o output_cbf (default: stdout )
     the output cbf combining the image and the template.  If the
     output_cbf is not specified or is given as "-", it is written
     to stdout.

   -q
     exit quickly with just the miniheader expanded
     after the data.  No template is used.

   -Q
     exit quickly with just the miniheader unexpanded
     before the data.  No template is used.

   -C convention
     convert the comment form of miniheader into the
         _array_data.header_convention convention
         _array_data.header_contents
     overriding any existing values

   -d detectorname
     a detector name to be used if none is provided in the image
     header.

   -F
     when writing packed compression, treat the entire image as
     one line with no averaging

   -m [x|y|x=y] (default x=y, square arrays only)
     mirror the array in the x-axis (y -> -y)
                      in the y-axis (x -> -x)
                   or in x=y ( x -> y, y-> x)

   -r n
     rotate the array n times 90 degrees counter clockwise
     x -> y, y -> -x for each rotation, n = 1, 2 or 3

   -R
     if setting a beam center, set reference values of
     axis settings as well as standard settings

   -z distance
     detector distance along Z-axis

   -c category_alias=category_root
   -t tag_alias=tagroot
     map the given alias to the given root, so that instead
     of outputting the alias, the root will be presented in the
     output cbf instead.  These options may be repeated as many
     times as needed.


    testreals, testflat and testflatpacked

     The example programs testreals, testflat and testflatpacked exercise the
     handling of reals, byte_offset compression and packed compression. Each
     is run without any arguments. testreals will read real images from the
     data file testrealin.cbf and write a file with real images in
     testrealout.cbf, which should be identical to testrealin.cbf. testflat
     and testflatpacked read 4 1000x1000 2D images and one 50x60x70 3D image
     and produce an output file that should be identical to the input.
     testflat reads testflatin.cbf and produces testflatout.cbf using
     CBF_BYTE_OFFSET compression. testflatpacked reads testflatpackedin.cbf
     and produces testflatpackedout.cbf. The images are:
       * A 1000 x 1000 array of 32-bit integers forming a flat field with all
         pixels set to 1000.
       * A 1000 x 1000 array of 16-bit integers forming a flat field with all
         pixels set to 1000.
       * A 1000 x 1000 array of 32-bit integers forming a flat field with all
         pixels set to 1000, except for -3 along the main diagonal and its
         transpose.
       * A 1000 x 1000 array of 16-bit integers forming a flat field with all
         pixels set to 1000, except for -3 along the main diagonal and its
         transpose.
       * A 50 x 60 x 70 array of 32-bit integers in a flat field of 1000,
         except for -3 along the main diagonal and the values i+j+k (counting
         from zero) every 1000th pixel

    test_fcb_read_image, test_xds_binary

     The example programs test_fcb_read_image and test_xds_binary are
     designed read the output of testflat and testflatpacked using the FCBlib
     routines in lib/libfcb. test_xds_binary reads only the first image and
     closes the file immediately. test_fcb_read_image reads all 5 images from
     the input file. The name of the input file should be provided on stdin,
     as in:

       * echo testflatout.cbf | bin/test_xds_binary
       * echo testflatpackedout.cbf | bin/test_xds_binary
       * echo testflatout.cbf | bin/test_fcb_read_image
       * echo testflatpackedout.cbf | bin/test_fcb_read_image

     In order to compile these programs correctly for the G95 compiler it is
     important to set the record size for reading to be no larger than the
     padding after binary images. This in controlled in Makefile by the line
     M4FLAGS = -Dfcb_bytes_in_rec=131072 which provides good performance for
     gfortran. For g95, this line must be changed to M4FLAGS =
     -Dfcb_bytes_in_rec=4096

    sauter_test

     The program sauter_test.C is a C++ test program contributed by Nick
     Sauter to help in resolving a memory leak he found. The program is run
     as bin/sauter_test and should run long enough to allow a check with top
     to ensure that it has constant memory demands. In addition, starting
     with release 0.7.8.1, the addition of -DCBFLIB_MEM_DEBUG to the compiler
     flags will cause detailed reports on memory use to stderr to be
     reported.

    adscimg2cbf

     The example program adscimg2cbf accepts any number of raw or compressed
     ADSC images with .img, .img.gz, .img.bz2 or .img.Z extensions and
     converts each of them to an imgCIF/CBF file with a .cbf extension.


   adscimg2cbf [--flag[,modifier]] file1.img ... filen.img     (creates file1.cbf ... filen.cbf)
          Image files may also be compressed (.gz, .bz2, .Z)

   Flags:
     --cbf_byte_offset   Use BYTE_OFFSET compression (DEFAULT)
     --cbf_packed        Use CCP4 packing (JPA) compression.
     --cbf_packed_v2     Use CCP4 packing version 2 (JPA) compression.
     --no_compression    No compression.

   The following two modifiers can be appended to the flags (syntax: --flag,modifier):
     flat            Flat (linear) images.
     uncorrelated    Uncorrelated sections.

    adscimg2cbf

     The example program cbf2adscimg accepts any number of cbfs of ADSC
     images created by adscimg1cbf or convert_image and produces raw or
     compressed adsc image files with .img, .img.gz or .img.bz2 extensions.


   cbf2adscimg [--flag] file1.cbf ... filen.cbf     (creates file1.img ... filen.img)
          Image files may be compressed on output: (.gz, .bz2) by using the flags below.\n");

   Flags:
     --gz    Output a .gz file  (e.g., filen.img.gz).
     --bz2   Output a .bz2 file (e.g., filen.img.bz2).

    tiff2cbf

     The test program tiff2cbf converts a tiff data file to a cbf data file.
     The program converts the tiff data samples directly into a minicbf with
     the tiff header stored at the value of _array_data.header_contents. This
     conversion is supported for the sample formats SAMPLEFORMAT_UINT
     (unsigned integer data), SAMPLEFORMAT_INT (unsigned integer data),
     SAMPLEFORMAT_INT (signed integer data), SAMPLEFORMAT_IEEEFP (IEEE
     floating point data), SAMPLEFORMAT_COMPLEXINT (complex signed int) and
     SAMPLEFORMAT_COMPLEXIEEEFP (complex ieee floating). Conversions from
     these formats to other CBF formats can be handled by cif2cbf. If you
     wish to convert and xxx.tif written with IEEE floating point samples
     into a CBF with integer values compressed by byte-offset compression for
     use by XDS, creating an xxx_view.cbf with values clipped between 0 and
     100, and an xxx_xds.cbf with unclipped values for processing:


   tiff2cbf xxx.tif xxx.cbf
   cif2cbf -I 4 -C 100. -L 0. -e n -c b -i xxx.cbf -o xxx_view.cbf
   cif2cbf -I 4 -e n -c b -i xxx.cbf -o xxx_xds.cbf
  

    minicbf2nexus

     This program takes some minicbf files describing a single scan and axis
     configuration settings for them and creates a nexus file containing the
     same data. As this is an early version of the program it lacks a lot of
     useful functionality and should not be assumed to be stable.

     It currently takes several command line arguments:

       * -c
         --compression
         These are optional and take a single case-insensitive argument which
         describes the compression used for the dataset.

         Currently implemented values are:

            * cbf
              Use the same CBFlib compression method as the miniCBF data uses
            * none
              Don't compress the data
            * zlib
              Use zlib compression

         More compression options will be added in later versions, including
         options for CBFlib compression schemes.

       * -C
         --config
         This takes a single argument giving the file name of a configuration
         file which describes how the axes of the minicbf file relate to each
         other.

       * -g
         --group
         This takes a string defining the name of the group where the data
         should be inserted. Currently, the file will begin in an empty state
         and this will cause a group of the given name to be created, but
         this will eventually allow data to be inserted into an existing
         user-defined group.

       * -o
         --output
         This takes a single argument which is used as the filename for the
         new nexus file. Any existing files of the same name are overwritten
         without warning, so be careful that the name of any existing files
         that you wish to keep are not passed as an argument here.

       * -Z
         --register
         Takes a single case-insensitive argument of 'manual' or 'plugin'
         defining the method of plugin registration used. May be specified
         multiple times to define a system default (via an alias) and
         optionally over-ride it later.

       * Other arguments are interpreted as file names identifying the
         miniCBF files to be packed into the new NeXus file. These must
         currently be pilatus v1.2 miniCBF files, but this restriction will
         be relaxed in later versions.

     An example, from the test scripts, is:

     minicbf2nexus -c zlib -C config X4_test_1.cbf X4_test_2&3.cbf
     X4_test_4.cbf X4_test_5.cbf -o minicbf.h5

     Where test files 1, 4 & 5 are each single-image miniCBF files and test
     file 2 & 3 is created by 'cat'ing together two single-image miniCBF
     files

     The config file used for this example is:

 # some sample config settings for a miniCBF file

 map Start_angle to CBF_axis_omega
 map Phi to CBF_axis_phi
 map Kappa to CBF_axis_kappa

 Sample depends-on CBF_axis_phi

 CBF_axis_phi vector [1 0 0] depends-on CBF_axis_kappa
 CBF_axis_kappa vector [0 1 0] depends-on .
 CBF_axis_omega vector [0 0 0]

     Text from any # character to the end of the line is ignored as a
     comment.

     Axes are declared by the map keyword as the name of the axis in the
     minicbf file, which must match exactly, followed by the keyword to and
     then the name that will be given to the axis in the resulting nexus
     file. Each axis is treated as a rotation axis and should have a vector
     which defines the axis of rotation in the 3D coordinate frame used by
     nexus, this should be 3 numbers within square brackets separated by
     spaces and does not need to be normalised. Each axis may also depend on
     a nother axis by using the keyword depends-on folowed by the name of the
     nexus axis it depends on, or . if it does not depend on another axis,
     omitting a dependency as shown on the final line of the example above is
     not recommended as it will eventually be a fatal error. The vector and
     depends-on declarations do not need to be on the same line.

     The Sample keyword is used to define a dependency for the sample being
     scanned and should be followed by a depends-on declaration which defines
     the name of the nexus axis that the sample depends on.

     The final line of the config file should be blank to allow for some
     simple integrity tests.

     A continuous chain of dependencies should be formed from the sample to
     the nexus coordinate system, otherwise there is insufficient information
     available to properly describe the orientation of the sample. This will
     be enforced in later versions, with a fatal error if insufficient
     information is provided.

    cbf2nexus

     This program takes some CBF files describing a single scan and converts
     them to a single NeXus file containing the same data. It can also be
     used to merge a CBF file into an existing NeXus file.

     It currently takes several command line arguments:

       * -c
         --compression
         These are optional and take a single case-insensitive argument which
         describes the compression used for the dataset.

         Currently implemented values are:

            * cbf
              Use the same CBFlib compression method as the miniCBF data uses
            * none
              Don't compress the data
            * zlib
              Use zlib compression

         More compression options will be added in later versions, including
         options for CBFlib compression schemes.

       * -g
         --group
         This takes a string defining the name of the group where the data
         should be inserted. Currently, the file will begin in an empty state
         and this will cause a group of the given name to be created, but
         this will eventually allow data to be inserted into an existing
         user-defined group.

       * -o
         --output
         This takes a single argument which is used as the filename for the
         new nexus file. Any existing files of the same name are overwritten
         without warning, so be careful that the name of any existing files
         that you wish to keep are not passed as an argument here.

       * -u
         --update
         This take a single argument which is used as the filename for an
         existing nexus file, to which the nexus translation of the input
         file will be added. This is a direct change in the specified file.
         It is not making a copy first.
       * -Z
         --register
         Takes a single case-insensitive argument of 'manual' or 'plugin'
         defining the method of plugin registration used. May be specified
         multiple times to define a system default (via an alias) and
         optionally over-ride it later. This is only relevant if the NeXus
         file is written with CBF compression algorithms, it doesn't have any
         effect for uncompressed data or data compressed uning HDF5's
         built-in compression algorithms.

       * --datablock
         Gives the name of a datblock to attempt to extract data from, or may
         be omitted to extract data from all datablocks.

       * --scan
         Gives the name of a scan to attempt to extract data from, or may be
         omitted if there is only one scan in the datablock(s).

       * --experiment_id
         Should be a unique identifier for the scan, which will be stored in
         /*:NXentry/entry_identifier.

       * --sample_id
         Should be a unique identifier for the sample, which will be stored
         in /*:NXentry/*:NXsample/sample_identifier.

       * --list & --no-list
         Determines whether the list of recognised data items is printed or
         not. These may be used multiple times, the last specified value is
         the one that is actually used.

       * Other arguments are interpreted as file names identifying the CBF
         files to be packed into the new NeXus file.

     An example, from the test scripts, is:

     cbf2nexus -c zlib adscconverted.cbf adscconverted.cbf -o cbf.zlib.h5

     This creates a single NeXus file containing two copies of the
     'adscconverted' CBF file.

    nexus2cbf

     This program converts a single frame of data from a nexus file to a cbf
     file with a given name. The primary purpose of this program is to help
     verify that data can be recovered after being converted to NeXus format,
     to check that it hasn't been lost or mangled.

     It currently takes several command line arguments:

       * -f
         --frame
         This should be an integer, in the range [0, frameCount), defining
         the index of the frame that is to be extracted, and defaults to 0.

       * -g
         --group
         This takes a string defining the name of the group where the data
         should be inserted. Currently, the file will begin in an empty state
         and this will cause a group of the given name to be created, but
         this will eventually allow data to be inserted into an existing
         user-defined group.

       * -o
         --output
         This takes a single argument which is used as the filename for the
         new NeXus file. Any existing files of the same name are overwritten
         without warning, so be careful that the name of any existing files
         that you wish to keep are not passed as an argument here.

       * -Z
         --register
         Takes a single case-insensitive argument of 'manual' or 'plugin'
         defining the method of plugin registration used. May be specified
         multiple times to define a system default (via an alias) and
         optionally over-ride it later. This is only relevant if the NeXus
         file was written with CBF compression algorithms, it doesn't have
         any effect for uncompressed data or data compressed uning HDF5's
         built-in compression algorithms.

       * The remaining argument(s) should be the file name of the NeXus file
         that is to be converted.

    testhdf5

     This program runs a set of unit tests on the HDF5 abstraction layer.
     These are designed to ensure everything is working correctly, to help
     locate bugs and prevent regressions. A short summary will be printed
     detailing the number of tests passed, the number of tests failed and the
     number of components skipped. If any tests fail or are skipped then some
     additional output should be produced to help identify the cause of the
     error so that it is easier to fix.

     The program does not take any command-line arguments, and creates a file
     called testfile.h5 in its working directory for use in the tests.

    testulp

     This program runs a set of unit tests on the ULP comparison functions.
     These are designed to ensure everything is working correctly, to help
     locate bugs and prevent regressions. A short summary will be printed
     detailing the number of tests passed, the number of tests failed and the
     number of components skipped. If any tests fail or are skipped then some
     additional output should be produced to help identify the cause of the
     error so that it is easier to fix.

     The program does not take any command-line arguments.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

     Updated 22 February 2015. Contact: yaya at bernstein-plus-sons dot com