Register
Login
Resources
Docs Blog Datasets Glossary Case Studies Tutorials & Webinars
Product
Data Engine LLMs Platform Enterprise
Pricing Explore
Connect to our Discord channel

GMT_API.tex 74 KB

You have to be logged in to leave a comment. Sign In
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
  1. %------------------------------------------
  2. % $Id$
  3. %
  4. % The GMT Documentation Project
  5. % Copyright (c) 2000-2012.
  6. % P. Wessel, W. H. F. Smith, R. Scharroo, and J. Luis
  7. %------------------------------------------
  8. %
  9. \documentclass{report}
  10. \newcommand{\GMTTITLE}{C/C++ Application Programming Interface}
  11. \input{GMT_macros}
  12. \makeindex
  13. %--------------------------------------------------------------------------
  14. \begin{document}
  15. \pagenumbering{roman}
  16. \input{GMT_Cover}
  17. \addcontentsline{toc}{chapter}{Front page}
  18. \clearpage
  19. \thispagestyle{headings}
  20. \tableofcontents
  21. \thispagestyle{headings}
  22. \chapter{Introduction}
  23. \index{Introduction}
  24. \pagenumbering{arabic}
  25. \thispagestyle{headings}
  26. \index{Purpose of the GMT API}
  27. \index{GMT API!Purpose}
  28. \section{Preamble}
  29. \index{Preamble}
  30. \begin{figure}[h]
  31. \centering
  32. \includegraphics[width=10cm,bb=0 0 485 255]{GMT4_mode.png}
  33. \caption{GMT 4 programs contain all the high-level functionality.}
  34. \end{figure}
  35. Prior to version 5, the bulk of \GMT\ functionality was coded directly
  36. in the standard \GMT\ C program modules (e.g., \filename{surface.c}, \filename{psxy.c}, \filename{grdimage.c}).
  37. The \GMT\ library only offered access to lower-level functions from which those
  38. high-level \GMT\ programs were built. The standard \GMT\ programs have been very successful,
  39. with tens of thousands of users world-wide. However, the design of the main programs
  40. prevented developers from leveraging \GMT\ functionality from within other
  41. programming environments since access to \GMT\ tools could only be achieved
  42. via system calls. Consequently, all data i/o had to be done via temporary files.
  43. The design also prevented the \GMT\ developers themselves from taking advantage of these
  44. modules directly. For instance, the tool \GMTprog{pslegend} needed to make extensive use of system calls
  45. to \GMTprog{psxy} and \GMTprog{pstext} in order to plot the lines, symbols and text
  46. that make up a map legend.
  47. \begin{figure}[h]
  48. \centering
  49. \includegraphics[width=10cm,bb=0 0 485 255]{GMT5_mode.png}
  50. \caption{GMT 4 programs contain all the high-level functionality.}
  51. \end{figure}
  52. Starting with \GMT\ version 5, all standard \GMT\ programs are split into short driver
  53. program (the ``new'' \GMT\ programs) and a function ``module''. The drivers simply call the corresponding \GMT\ modules;
  54. it is these modules that do most of the work. These new functions have been placed
  55. in a new \GMT\ high-level API library and can be called from a variety of environments
  56. (C/C++, Fortran, Python, Matlab, Visual Basic, etc.)\footnote{Currently, only C/C++ and Matlab are being tested.}.
  57. For example, the main program
  58. \filename{blockmean.c} has been reconfigured as a high-level function \GMTfunc{GMT\_blockmean()},
  59. which does the actual spatial averaging and passes the result back to the calling program.
  60. The previous behavior of \filename{blockmean.c} is replicated by a short driver program
  61. that simply collects user arguments and then calls \GMTfunc{GMT\_blockmean()}. Indeed, the driver
  62. programs for all the standard \GMT\ programs are so short and simple that the makefile generates them
  63. on-the-fly when it compiles and links them with the \GMT\ library into executables.
  64. Thus, \filename{blockmean.c} and others do no longer exist.
  65. In order for this interface to be as flexible as possible we have generalized the notion of input
  66. and output. Now, data that already reside in an application's memory may serve as
  67. input to a \GMT\ function. Other sources of input may be file pointers
  68. and file descriptors (as well as the already-supported mechanism for passing file names).
  69. For standard data table i/o, the \GMT\ API takes care of the task of assembling any combination
  70. of files, pointers, and memory locations into a single virtual data set from which the \GMT\
  71. function may read (a) all records at once into memory, or (b) read one record at a time.
  72. Likewise, \GMT\ functions may write their output to a virtual destination, which
  73. might be a memory location in the user's application, a file pointer or descriptor, or
  74. an output file. The \GMT\ functions are unaware of these details and simply
  75. read from a ``source'' and write to a ``destination''.
  76. Here, we document the new functions in the \GMT\ API library for application developers
  77. who wish to call these functions from their own custom programs. At this point,
  78. only the new high-level \GMT\ API is fully documented and intended for public use.
  79. The structure and documentation of the under-lying lower-level \GMT\ library is not finalized
  80. Developers using these functions may risk disruption to their programs due to changes we may
  81. make in the library in support of the \GMT\ API.
  82. \section{Definitions}
  83. For the purpose of this documentation a few definitions are needed:
  84. \begin{enumerate}
  85. \item ``Standard \GMT\ program'' refers to one of the traditional stand-alone command-line
  86. executables known to all \GMT\ users, e.g., \GMTprog{blockmean}, \GMTprog{psxy},
  87. \GMTprog{grdimage}, etc. Prior to version 5, these were the only \GMT\ executables available.
  88. \item ``\GMT\ module'' refers to the function in the \GMT\ API
  89. library that is responsible for all the action taken by the corresponding \GMT\ program. All
  90. such modules are given the same name as the corresponding program but carry the
  91. prefix \texttt{GMT\_}, e.g., \texttt{GMT\_blockmean}.
  92. \item ``\GMT\ application'' refers to a new application written by developers
  93. and may call one or more \GMT\ functions to create a new \GMT-compatible executable.
  94. \item In the API description that follows we will use the type \texttt{long} to mean
  95. a 4-byte (for 32-bit systems) or 8-byte (for 64-bit systems) integer. Since different
  96. operating systems have their own way of defining 8-byte integers it is recommended that
  97. developers use the type \texttt{GMT\_LONG} for this purpose; it is guaranteed to yield
  98. the correct type that the \GMT\ functions expect.
  99. \end{enumerate}
  100. In version 5, the standard \GMT\ programs are themselves specific but overly simple examples
  101. of \GMT\ applications that only call the single \GMT\ function they are associated with.
  102. However, some exceptions such as \GMTprog{pslegend} and \GMTprog{gmtconvert} call several modules.
  103. \section{Recognized resources}
  104. \index{Recognized resources}
  105. \index{Resources!Recognized by GMT}
  106. The \GMT\ API knows how to read and write five types of data common to \GMT\ operations:
  107. CPT palette tables, data tables (ASCII or binary), text tables, \GMT\ grids and images (reading only).
  108. In addition, we have two data types to facilitate the passing of simple user arrays (one or more data columns
  109. of any data type, e.g., double, char) and 2-D user matrices (of any data type and column/row organization).
  110. There are many attributes for each of these two entities and therefore we use a top-level structure for each
  111. to keep them all in one container. These containers are given or returned by the \GMT\ API
  112. functions using pointers (\texttt{void *}). Below we discuss these containers in some detail; we
  113. will later present how they are used when importing or exporting them to or from files,
  114. memory locations, or streams. The first five are the standard \GMT\ objects, while the latter two are the
  115. special user data containers.
  116. \subsection{CPT palette tables}
  117. \index{CPT palette tables}
  118. \index{Resources!CPT palette tables}
  119. The color palette table files, or just CPT tables, contain colors and patterns used for plotting
  120. data such as surfaces (i.e., \GMT\ grids) or symbols, lines and polygons (i.e., \GMT\ tables).
  121. \GMT\ programs will generally read in a CPT
  122. palette table, make it the current palette, do the plotting, and destroy the table when done.
  123. The information is referred to via a pointer to \texttt{struct GMT\_PALETTE}. Thus, the
  124. arguments to \GMT\ API functions that handle palettes expect this type of variable.
  125. \subsection{Data tables}
  126. \index{Data tables}
  127. \index{Resources!Data tables}
  128. Much data processed in \GMT\ come in the form of ASCII or binary data tables. These may
  129. have any number of header records (ASCII only) and perhaps segment headers. \GMT\ programs will
  130. read one or many such tables when importing data. However, to avoid memory duplication some programs may prefer to read
  131. records one at the time. The \GMT\ API has functions that let you read record-by-record
  132. by presenting a virtual data set that combines all the data tables specified as input.
  133. This simplifies record processing considerably. A \texttt{struct GMT\_DATASET} may contain
  134. any number of tables, each with any number of segments, and each segment with any number of records. Thus, the
  135. arguments to \GMT\ API functions that handle such data sets expect this type of variable. All segments
  136. are expected to have the same number of columns.
  137. \subsection{Text tables}
  138. \index{Text tables}
  139. \index{Resources!Text tables}
  140. Some data needed by \GMT\ are simply free-form ASCII text tables. These are handled
  141. similarly to data tables. E.g., they may have any number of header records and even segment headers,
  142. and \GMT\ programs can read one or more tables or get text records one at the time.
  143. A \texttt{struct GMT\_TEXTSET} may contain
  144. any number of tables, each with any number of segments, and each segment with any number of records. Thus, the
  145. arguments to \GMT\ API functions that handle such data sets expect this type of variable.
  146. \subsection{GMT grids}
  147. \index{GMT grids}
  148. \index{Resources!GMT grids}
  149. \GMT\ grids are used to represent equidistant and organized 2-D surfaces. These can be
  150. plotted as contour maps, color images, or as perspective surfaces. Because the native
  151. \GMT\ grid is simply a 1-D float array with all the metadata kept in a separate header, we
  152. pass this information via a \texttt{struct GMT\_GRID}, which is a container that holds both items.
  153. Thus, the arguments to \GMT\ API functions that handle such \GMT\ grids expect this type
  154. of variable.
  155. \subsection{GMT images}
  156. \index{GMT images}
  157. \index{Resources!GMT images}
  158. \GMT\ images are used to represent bit-mapped images obtained via the GDAL bridge. These can be
  159. reprojected internally, such as when used in grdimage. Since images and grids share the concept
  160. of a header, we use the same header structure for grids as for images; however, some additional
  161. metadata attributes are also needed. Finally, the image itself may be of any data type.
  162. Both image and header information are passed via a \texttt{struct GMT\_IMAGE}, which is a container that holds both items.
  163. Thus, the arguments to \GMT\ API functions that handle such \GMT\ images expect this type
  164. of variable. Unlike the other objects, images can only be read and not written.
  165. \subsection{User data columns}
  166. \index{User data columns}
  167. \index{Resources!User data columns}
  168. \begin{table}[h]
  169. \small
  170. \centering
  171. \begin{tabular}{ll} \hline
  172. \multicolumn{2}{l}{\texttt{union GMT\_UNIVECTOR \{}} \\
  173. \texttt{ unsigned char *uc1;} & /* \emph{Pointer for unsigned char array} */ \\
  174. \texttt{ char *sc1;} & /* \emph{Pointer for signed char array} */ \\
  175. \texttt{ unsigned short *ui2;} & /* \emph{Pointer for unsigned short array} */ \\
  176. \texttt{ short *si2;} & /* \emph{Pointer for signed short array} */ \\
  177. \texttt{ unsigned int *ui4;} & /* \emph{Pointer for unsigned int array} */ \\
  178. \texttt{ int *si4;} & /* \emph{Pointer for signed int array} */ \\
  179. \texttt{ unsigned long *ui8;} & /* \emph{Pointer for unsigned long array} */ \\
  180. \texttt{ long *si8;} & /* \emph{Pointer for signed long array} */ \\
  181. \texttt{ float *f4;} & /* \emph{Pointer for float array} */ \\
  182. \texttt{ double *f8;} & /* \emph{Pointer for double array} */ \\
  183. \texttt{\};} & \\ \hline
  184. \end{tabular}
  185. \caption{Definition of the GMT\_UNIVECTOR union that hold a pointer to any array type.}
  186. \label{tbl:univector}
  187. \index{Vectors!Structure}
  188. \end{table}
  189. \begin{table}[h]
  190. \small
  191. \centering
  192. \begin{tabular}{ll} \hline
  193. \multicolumn{2}{l}{\texttt{struct GMT\_VECTOR \{}} \\
  194. \texttt{ long id;} & /* \emph{An identification number} */ \\
  195. \texttt{ long n\_rows;} & /* \emph{Number of rows in each vector} */ \\
  196. \texttt{ long n\_columns;} & /* \emph{Number of vectors} */\\
  197. \texttt{ long alloc\_mode;} & /* \emph{Determines if we may free the vectors or not} */\\
  198. \texttt{ long *type;} & /* \emph{Array with data type for each vector} */\\
  199. \texttt{ union GMT\_UNIVECTOR *data;} & /* \emph{Array with unions for each column} */\\
  200. \texttt{\};} & \\ \hline
  201. \end{tabular}
  202. \caption{Definition of the GMT\_VECTOR structure used to pass user data columns.}
  203. \label{tbl:vector}
  204. \index{Vectors!Structure}
  205. \end{table}
  206. \noindent
  207. Programs that may wish to call \GMT\ modules may have input data in their own particular
  208. structures. For instance, the user's program may have three column arrays of type float
  209. and wishes to use these as the input source to the \texttt{GMT\_surface} module, which normally
  210. expects a \texttt{struct GMT\_DATASET} via file or reference. Simply create a \texttt{struct GMT\_VECTOR}
  211. (see section~\ref{sec:create}) and assign the union array pointers (see Table~\ref{tbl:univector}) to your data columns and provide
  212. the required information on length and data types (see Table~\ref{tbl:vector}).
  213. By letting the \GMT\ module know you are passing a data set via a \texttt{struct GMT\_VECTOR} it will know how to
  214. read the data properly.
  215. \subsection{User data matrices}
  216. \index{User data matrices}
  217. \index{Resources!User data matrices}
  218. \begin{table}[h]
  219. \small
  220. \centering
  221. \begin{tabular}{ll} \hline
  222. \multicolumn{2}{l}{\texttt{struct GMT\_MATRIX \{}} \\
  223. \texttt{ long id;} & /* \emph{An identification number} */ \\
  224. \texttt{ long n\_rows;} & /* \emph{Number of rows in the matrix} */ \\
  225. \texttt{ long n\_columns;} & /* \emph{Number of columns in the matrix} */\\
  226. \texttt{ long n\_layers;} & /* \emph{Number of layers in a 3-D matrix} */\\
  227. \texttt{ long registration;} & /* \emph{0 for gridline and 1 for pixel registration} */\\
  228. \texttt{ long shape;} & /* \emph{0 = C (rows) and 1 = Fortran (cols)} */\\
  229. \texttt{ long dim;} & /* \emph{Length of dimension for row (C) or column (Fortran)} */\\
  230. \texttt{ long alloc\_mode;} & /* \emph{Determines if we may free the vectors or not} */\\
  231. \texttt{ long type;} & /* \emph{The matrix data type} */\\
  232. \texttt{ double limit[6];} & /* \emph{The min and max limits on x-, y-, and z-ranges} */\\
  233. \texttt{ union GMT\_UNIVECTOR data;} & /* \emph{Union with pointers a data matrix of any type} */\\
  234. \texttt{\};} & \\ \hline
  235. \end{tabular}
  236. \caption{Definition of the GMT\_MATRIX structure used to pass a user data matrix.}
  237. \label{tbl:matrix}
  238. \index{Matrix!Structure}
  239. \end{table}
  240. \noindent
  241. Likewise, a programs may have an integer 2-D matrix in memory
  242. and wish to use that as the input grid to the \texttt{GMT\_grdfilter} module, which normally
  243. expects a \texttt{struct GMT\_GRID} via file or reference. As for user vectors, we create a
  244. \texttt{struct GMT\_MATRIX} (see section~\ref{sec:create}), assign the appropriate union pointer to your data
  245. matrix and provide information on dimensions and data type (see Table~\ref{tbl:matrix}).
  246. Letting the \GMT\ module know you are passing a grid via a
  247. \texttt{struct GMT\_MATRIX} it will know how to read the matrix properly.
  248. \chapter{Overview of the GMT C Application Program Interface}
  249. \index{C interface}
  250. \index{Interface!C}
  251. Users who wish to create their own \GMT\ applications based on the API
  252. must make sure their program goes through the steps below; details
  253. for each step will be revealed in the sections to follow. We have kept the
  254. API simple: In addition to the \GMT\ modules, there are only 17 public functions to become familiar with.
  255. All functions sets the variable \texttt{API->error} to the appropriate error code (when things go wrong);
  256. otherwise it is set to GMT\_OK (0).
  257. The layout here assumes you wish to use data in memory as input sources; if the data are simply
  258. command-line files then things simplify considerably.
  259. \begin{enumerate}
  260. \item Initialize a new \GMT\ session by calling \texttt{GMT\_Create\_Session}, which
  261. allocates a \GMT\ API control structure and returns a pointer to it. This pointer must be used
  262. as first argument to all subsequent \GMT\ API function calls within the same session.
  263. \item For each intended call to a \GMT\ function, several steps are involved:
  264. \begin{enumerate}
  265. \item Register the input sources and register the output destination
  266. using \texttt{GMT\_Register\_IO}, unless you know you are working with a single file
  267. or standard input/output.
  268. The resources will typically be files, memory locations, already-opened file handles,
  269. and even process streams.
  270. \item Each resource registration will generate a unique ID number. For memory resources, these numbers are
  271. then converted to unique filenames of the form ``@GMTAPI@-\#\#\#\#\#\#'' that are used with \GMT\ modules. When
  272. \GMT\ i/o library functions encounter such filenames they extract the ID and make a connection
  273. to the resource registered under that ID. Any number of table data or text sources
  274. will be combined into a single virtual source for \GMT\ functions to operate on.
  275. In contrast, CPT, Grid, and image resources are operated on individually.
  276. \item Enable data import once all registrations are complete.
  277. \item Read into memory all data that will be passed to \GMT\ modules via pointers. You may choose
  278. to read everything into memory at once or process the data record-by-record (tables only).
  279. \item Prepare the program options required and call the \GMT\ module you wish to use.
  280. \item Process the results that were returned to memory via pointers rather than written to files.
  281. \item Explicitly destroy the resources allocated by \GMT\ modules to hold the results, or let the
  282. garbage collector do this automatically at the end of the module and at the end of the session.
  283. \end{enumerate}
  284. \item Repeat steps a--f as many times as your application requires. All API functions
  285. return a status code which is GMTAPI\_OK (0) if all is well. For non-zero return values, use
  286. \texttt{GMT\_Report\_Error} to generate an error message.
  287. \item We terminate the GMT session by calling \texttt{GMT\_Destroy\_Session}.
  288. \end{enumerate}
  289. Advanced programs may be calling more than one \GMT\ session and thus run several
  290. sessions, perhaps concurrently as different threads on multi-core machines.
  291. We will now discuss these steps in more detail.
  292. \section{Initialize a new GMT\ session}
  293. \index{Initialize a new GMT session}
  294. \index{GMT session!Initialize}
  295. Most applications will need to initialize only a single \GMT\ session. This is true of all
  296. the standard \GMT\ programs since they only call one \GMT\ module and then exit. Most
  297. user-developed \GMT\ applications are likely to only initialize one session even though
  298. they may call many \GMT\ modules. However, the \GMT\ API supports any number of
  299. simultaneous sessions should the programmer wish to take advantage of it. This
  300. might be useful when you have access to several CPUs and want to spread the computing load\footnote{However,
  301. there is no thread-support yet.}.
  302. In the following discussion we will simplify our treatment to the use
  303. of a single session only.
  304. The \texttt{GMT\_Create\_Session} is used to initiate the new session. The full
  305. function prototype is
  306. \index{GMT\_Create\_Session}
  307. \begin{verbatim}
  308. struct GMTAPI_CTRL * GMT_Create_Session (char *tag, long mode)
  309. \end{verbatim}
  310. and you will typically call it thus:
  311. \begin{verbatim}
  312. GMT_LONG mode = GMTAPI_GMT;
  313. struct GMTAPI_CTRL *API = NULL;
  314. API = GMT_Create_Session ("Session name", mode);
  315. \end{verbatim}
  316. where \texttt{API} is a pointer to the allocated \GMT\ API control structure. You will need to
  317. pass this pointer to \emph{all} subsequent \GMT\ API functions. The key task of this initialization
  318. is to set up the \GMT\ machinery and its internal variables used for map projections, plotting,
  319. etc. The initialization also allocates space for internal structures used to register resources.
  320. If you expect to call modules that also require the PSL library, then set \texttt{mode} to
  321. GMTAPI\_GMTPSL (1); else simply pass GMTAPI\_GMT (0). Should something go wrong then \texttt{API}
  322. will be returned as \texttt{NULL}.
  323. \section{Register input or output resources}
  324. \index{Register input or output resources}
  325. \index{Resources!Register}
  326. \index{Resources!Input}
  327. \index{Resources!Output}
  328. \index{Sources!Register Input}
  329. \index{Sources!Register Output}
  330. When using the standard \GMT\ programs, you specify input files on
  331. the command line or via special program options (e.g., \Opt{I}\emph{intensity.nc}). The output of
  332. the programs are either written to standard output (which you redirect to files or pipe to other programs)
  333. or to files specified by specific program options (e.g., \Opt{G}\emph{output.nc}). However, the
  334. \GMT\ API allows you to also specify input (and output) to come from (or go to) open file handles
  335. or program memory locations. We will examine this more closely below. Registering a
  336. resource is a required step before attempting to import or export data other that via file options
  337. and standard input/output.
  338. \subsection{Resource registration}
  339. The basic registration machinery involves a direct or indirect call to
  340. \index{GMT\_Register\_IO}
  341. \begin{verbatim}
  342. long GMT_Register_IO (struct GMTAPI_CTRL *API, long family, long method, \
  343. long geometry, long direction, void *ptr, double wesn[])
  344. \end{verbatim}
  345. where \texttt{family} specifies what kind of resource is to be registered
  346. (see Table \ref{tbl:family} for list of all families), \texttt{method} specifies
  347. how we expect to access this resource (see Table \ref{tbl:methods} for recognized methods,
  348. as well as modifiers you can add; these are listed in Table \ref{tbl:via}),
  349. \texttt{geometry} specifies
  350. the geometry of the data (see Table \ref{tbl:geometry} for recognized geometries),
  351. \texttt{ptr} is the address of the pointer to the named input resource. If \texttt{direction}
  352. is GMT\_OUT and the \texttt{method} is not related to a file (filename, stream, or handle),
  353. then \texttt{ptr} must be NULL. After the \GMT\ module has written the data you can use
  354. \texttt{GMT\_Retrieve\_Data} to assign a pointer to the memory location where the output container was allocated.
  355. For grid (and image) resources you may request to obtain a subset via the \texttt{wesn}
  356. array (see Table~\ref{tbl:wesn} for information); otherwise, pass NULL to obtain the entire grid (or image).
  357. The \texttt{direction} indicates input or output and is either GMT\_IN (0) or GMT\_OUT (1).
  358. Finally, the function returns a unique resource ID, or GMTAPI\_NOTSET (-1) if there was an
  359. error (with error code returned via \texttt{API->error}).
  360. \subsection{Object ID encoding}
  361. If registered resources are to be given as program input or output arguments you will need to pass them via
  362. a text string that represents a special file name. The proper filename formatting is guaranteed by using the
  363. function
  364. \index{GMT\_Encode\_ID}
  365. \begin{verbatim}
  366. long GMT_Encode_ID (struct GMTAPI_CTRL *API, char *filename, long ID)
  367. \end{verbatim}
  368. which accepts the unique \texttt{ID} and writes the \texttt{filename} that
  369. you can use as argument to a program option. \texttt{filename} must have enough space to hold 16 bytes.
  370. The function returns TRUE (1) if there is an error (which is passed back with \texttt{API->error}),
  371. otherwise it returns FALSE (0).
  372. \begin{table}[h]
  373. \small
  374. \centering
  375. \begin{tabular}{|l|l|} \hline
  376. \multicolumn{1}{|c|}{\emph{family}} & \multicolumn{1}{c|}{\emph{source points to}} \\ \hline
  377. GMT\_IS\_DATASET & A [multi-segment] table file \\ \hline
  378. GMT\_IS\_TEXTSET & A [multi-segment] text file \\ \hline
  379. GMT\_IS\_GMTGRID & A \GMT\ grid file \\ \hline
  380. GMT\_IS\_CPT & A CPT file \\ \hline
  381. \end{tabular}
  382. \caption{Integer constants defined for use when specifying input or output data families.}
  383. \label{tbl:family}
  384. \index{Resources!Parameters!Floating point}
  385. \end{table}
  386. \begin{table}[h]
  387. \small
  388. \centering
  389. \begin{tabular}{|l|l|} \hline
  390. \multicolumn{1}{|c|}{\emph{method}} & \multicolumn{1}{c|}{\emph{how to read/write data}} \\ \hline
  391. GMT\_IS\_FILE & Pointer to name of a file \\ \hline
  392. GMT\_IS\_STREAM & Pointer to open file (or process) \\ \hline
  393. GMT\_IS\_FDESC & Pointer to integer file descriptor \\ \hline
  394. GMT\_IS\_COPY & Pointer to memory to \emph{copy} data from \\ \hline
  395. GMT\_IS\_REF & Pointer to memory to \emph{reference} data from (realloc OK) \\ \hline
  396. GMT\_IS\_READONLY & Pointer to memory to \emph{read} data from \\ \hline
  397. \end{tabular}
  398. \caption{Integer constants defined for use when specifying input or output methods.}
  399. \label{tbl:methods}
  400. \index{Resources!Methods}
  401. \end{table}
  402. \begin{table}[h]
  403. \small
  404. \centering
  405. \begin{tabular}{|l|l|} \hline
  406. \multicolumn{1}{|c|}{\emph{approach}} & \multicolumn{1}{c|}{\emph{how method is modified}} \\ \hline
  407. GMT\_VIA\_VECTOR & The user's data columns are addressed via a GMT\_VECTOR structure \\ \hline
  408. GMT\_VIA\_MATRIX & The user's grid is addressed via a GMT\_MATRIX structure \\ \hline
  409. \end{tabular}
  410. \caption{Integer constants defined for use when user data forms are involved. These are to be added
  411. to the \emph{method} used when registering the resource.}
  412. \label{tbl:via}
  413. \index{Resources!Conversions}
  414. \end{table}
  415. \begin{table}[h]
  416. \small
  417. \centering
  418. \begin{tabular}{|l|l|} \hline
  419. \multicolumn{1}{|c|}{\emph{geometry}} & \multicolumn{1}{c|}{\emph{description}} \\ \hline
  420. GMT\_IS\_TEXT & Not a geographic item \\ \hline
  421. GMT\_IS\_POINT & Multi-dimensional point data \\ \hline
  422. GMT\_IS\_LINE & Geographic or Cartesian line segments \\ \hline
  423. GMT\_IS\_POLYGON & Geographic or Cartesian closed polygons \\ \hline
  424. GMT\_IS\_SURFACE & 2-D gridded surface \\ \hline
  425. \end{tabular}
  426. \caption{Integer constants defined to register different geometries.}
  427. \label{tbl:geometry}
  428. \index{Resources!Geometries}
  429. \end{table}
  430. \begin{table}[h]
  431. \small
  432. \centering
  433. \begin{tabular}{|c|l|l|} \hline
  434. \multicolumn{2}{|c|}{\emph{Index}} & \multicolumn{1}{c|}{\emph{content}} \\ \hline
  435. 0 & XLO & x\_min (west) boundary of grid subset \\ \hline
  436. 1 & XHI & x\_max (east) boundary of grid subset \\ \hline
  437. 2 & YLO & y\_min (south) boundary of grid subset \\ \hline
  438. 3 & YHI & y\_max (north) boundary of grid subset \\ \hline
  439. \end{tabular}
  440. \caption{Domain boundaries (\texttt{wesn}) used when selecting subsets of grids.}
  441. \label{tbl:wesn}
  442. \index{Resources!Parameters!Domain}
  443. \end{table}
  444. \subsection{Resource initialization}
  445. \index{Resources!Initialization}
  446. \index{Initialization!Resources}
  447. All \GMT\ programs dealing with (a) input or output files given on the command line or (b) defaulting to
  448. the standard input or output streams if no files are given, must call the i/o initializer function
  449. \texttt{GMT\_Init\_IO} once for each direction required (i.e., input and output).
  450. For input it will determine how many input sources have already been registered.
  451. If none have been registered then it will scan the program arguments for any filenames given on the command line, and register
  452. these input resources. Finally, if we still have found no input sources we will specify the standard input stream
  453. as the single input source. Likewise, for output: If no single destination has been registered we specify the standard output stream
  454. as the output destination. Only one output destination is allowed to be active when the module writes data.
  455. The prototype for this function is
  456. \index{GMT\_Init\_IO}
  457. \begin{verbatim}
  458. long GMT_Init_IO (struct GMTAPI_CTRL *API, long family, long geometry, \
  459. long direction, long mode, struct GMT_OPTION *head)
  460. \end{verbatim}
  461. where \texttt{family} specifies what kind of resource is to be registered,
  462. \texttt{geometry} specifies the geometry of the data,
  463. the \texttt{direction} is either \texttt{GMT\_IN} or \texttt{GMT\_OUT}, the
  464. \texttt{mode} is a bit flag that determines what we do if no resources have been
  465. registered. The choices are
  466. \begin{description}
  467. \item [1] (or GMT\_REG\_FILES\_IF\_NONE) means ``add command line (option) files if none have been registered already''
  468. \item [2] (or GMT\_REG\_FILES\_ALWAYS) means ``always add any command line files''
  469. \item [4] (or GMT\_REG\_STD\_IF\_NONE) means ``add std* if no other input/output have been specified''
  470. \item [8] (or GMT\_REG\_STD\_ALWAYS) means ``always add std* even if resources have been registered''.
  471. \end{description}
  472. The standard behavior is 5 (or GMT\_REG\_DEFAULT).
  473. Finally, \texttt{head} is the first element of the option structure list.
  474. Many programs will register an export location to hold the results of a \GMT\ function (say,
  475. a filtered grid), but then wish to use that location as an \emph{input} resource in the next
  476. step. This is accomplished by re-registering the same array
  477. location as an import source, thereby changing the \emph{direction} of the data set.
  478. The function returns TRUE (1) if there is an error (which is passed back with \texttt{API->error}),
  479. otherwise it returns FALSE (0).
  480. \subsection{Dimension parameters for user column vectors}
  481. We refer to Table~\ref{tbl:vector}. The \texttt{type} array must hold the
  482. data type of each data column in the user's program. All types other than GMTAPI\_DOUBLE will need
  483. to be converted internally in \GMT\ to \texttt{double}, thus possibly increasing memory requirements.
  484. If the type is GMTAPI\_DOUBLE then \GMT\ will be able to use the column directly by reference. The \texttt{n\_columns}
  485. and \texttt{n\_rows} parameters inform of the number of vectors and their common length. These are known in
  486. the case of input but may be unknowable in the case of output; if so you may pass 0 for these values
  487. and set \texttt{alloc\_mode} to 1; this will make
  488. sure \GMT\ will allocate the necessary memory at the location you specify.
  489. \subsection{Dimension parameters for user 2-D table arrays}
  490. We refer to Table~\ref{tbl:matrix}. The \texttt{type} parameter specifies the
  491. data type used for the array in the user's program. All types other than GMTAPI\_FLOAT will need
  492. to be converted internally in \GMT\ to \texttt{float}, thus possibly increasing memory requirements.
  493. If the type is GMTAPI\_FLOAT then \GMT\ may be able to use the matrix directly by reference. The \texttt{n\_rows}
  494. and \texttt{n\_columns} parameters simply specify the dimensions of the matrix. These are known in
  495. the case of input but may be unknowable in the case
  496. of output; if so you may pass 0 for these values and set \texttt{alloc\_mode} to 1; this will make
  497. sure \GMT\ will allocate the necessary memory at the location you specify. Fortran users
  498. will instead have to specify a size large enough to hold the anticipated output data.
  499. The \texttt{registration} and \texttt{limit} gives the grid registration and domain.
  500. Finally, use the \texttt{dim} entry to indicate if the memory matrix has a dimension that
  501. exceeds that of the leading row (or column) dimension. Note: For GMT\_IS\_TEXTSET
  502. the user matrix is expected to be a 2-D character array with row length by \texttt{dim]}
  503. but we only consider the first \texttt{n\_columns} characters. For data grids you will
  504. also need to specify the \texttt{registration} (see the \GMT\ Cookbook and Reference,
  505. Appendix B for description of the two forms of registration) and data domain \texttt{limits}.
  506. \section{Create empty resources}
  507. \index{Create empty resources}
  508. \index{Resources!Create}
  509. \label{sec:create}
  510. If your session needs to build and populate \GMT\ resources in ways that do
  511. not depend on external resources (files, memory locations, etc.), then you
  512. can obtain a ``blank slate'' of certain \GMT\ structures.
  513. This is done with the \texttt{GMT\_Create\_Data} function, whose prototype is
  514. \index{GMT\_Create\_Data}.
  515. \begin{verbatim}
  516. void * GMT_Create_Data (struct GMTAPI_CTRL *API, long family, long par[])
  517. \end{verbatim}
  518. which returns a pointer to the allocated resource.
  519. Pass \texttt{family} as one of GMT\_IS\_GMTGRID, GMT\_IS\_DATASET, GMT\_IS\_TEXTSET, or GMT\_IS\_CPT,
  520. or the special families GMT\_IS\_VECTOR or GMT\_IS\_MATRIX when handling user data.
  521. Depending on the data type chosen you may need to pass additional parameters via
  522. the \texttt{par} array, as indicated below:
  523. \begin{description}
  524. \item [GMT\_IS\_GMTGRID]: An empty GMT\_GRID structure with a header is
  525. allocated; the data array is NULL. The \texttt{par} argument is not used.
  526. \item [GMT\_IS\_DATASET]: An empty GMT\_DATASET structure consisting of
  527. \texttt{par[0]} tables, each with \texttt{par[1]} segments, each with
  528. \texttt{par[2]} columns, all with \texttt{par[3]} rows, is allocated.
  529. \item [GMT\_IS\_TEXTSET]: An empty GMT\_TEXTSET structure consisting of
  530. \texttt{par[0]} tables, each with \texttt{par[1]} segments,
  531. all with \texttt{par[2]} text record, is allocated.
  532. \item [GMT\_IS\_CPT]: An empty GMT\_PALETTE structure with \texttt{par[0]}
  533. palette entries is allocated.
  534. \item [GMT\_IS\_VECTOR]: An empty GMT\_VECTOR structure with \texttt{par[0]}
  535. column entries is allocated.
  536. \item [GMT\_IS\_MATRIX]: An empty GMT\_VECTOR structure is allocated.
  537. \end{description}
  538. In all cases the data entries are initialized to zero (NULL in the case of text).
  539. Note: if you need to
  540. duplicate an existing data structure the simplest way is to use \texttt{GMT\_Get\_Data}
  541. after registering the original structure as the data source.
  542. The function returns a pointer to the data container. In case of an error we return a
  543. NULL pointer and pass an error code via \texttt{API->error}.
  544. \index{Duplicate!Data}
  545. \index{Data!Duplicate}
  546. \section{Import Data}
  547. \index{Import!Data}
  548. \index{Data!Import}
  549. \index{Resources!Import data}
  550. If your main program needs to read any of the five recognized data types (CPT files, data tables, text tables, \GMT\ grids, or images)
  551. you will use the \texttt{GMT\_Get\_Data} or \texttt{GMT\_Read\_Data} functions, which both returns entire data sets.
  552. In the case of data and text tables, you may also consider reading record-by-record using the \texttt{GMT\_Get\_Record} function.
  553. As a general rule, your program organization will simplify if you can read the entire resource into memory with
  554. \texttt{GMT\_Get\_Data} or \texttt{GMT\_Read\_Data}. However, if this leads to unacceptable waste of memory or if the program logic is particularly simple,
  555. it may be better to obtain one data record at the time via \texttt{GMT\_Get\_Record}.
  556. All of these input functions takes a parameter called \texttt{mode}. The \texttt{mode} parameter generally
  557. takes on different meanings for the different data types and will be discussed below.
  558. However, one bit setting is common to all types: By default, you are only allowed to read a
  559. data source once; the source is then flagged as having been read and subsequent attempts to read
  560. from the same source will result in a warning and no reading takes place. In the unlikely event you need to re-read a
  561. source you can override this default behavior by adding GMT\_IO\_RESET to your \texttt{mode} parameter.
  562. Note that this override does not apply to sources that are streams or file handles.
  563. \subsection{Enable Data Import}
  564. \index{Import!Enable}
  565. \index{Data!Import}
  566. \index{Resources!Import data}
  567. Once all input resources have been registered, we signal the API that we are done with the registration
  568. phase and are ready to start the actual data import. This step is only required when reading one record at the
  569. time. We initialize record-by-record reading by calling \texttt{GMT\_Begin\_IO}. This
  570. function enables dataset and text set record-by-record import and prepares the registered sources for the upcoming import.
  571. The prototype is
  572. \begin{verbatim}
  573. long GMT_Begin_IO (struct GMTAPI_CTRL *API, long family, long direction)
  574. \end{verbatim}
  575. where \texttt{family} specifies what kind of resources is about to be read or written (see Table \ref{tbl:family}
  576. for list of all families; only GMT\_IS\_DATASET and GMT\_IS\_TEXTSET are available for record-by-record handling).
  577. The \texttt{direction} is either GMT\_IN or GMT\_out, and for import we obviously use GMT\_IN.
  578. The function determines which is the first input file and sets up procedures for skipping to the next input file in a virtual data set.
  579. The \texttt{GMT\_Get\_Record} function will not be able to read any data before \texttt{GMT\_Begin\_IO} has been called. As you might
  580. guess, there is a companion \texttt{GMT\_End\_IO} function that completes, then disables record-by-record data access. You can use these several
  581. times to switch modes between registering data resources, doing the importing/exporting, and disabling further
  582. data access, perhaps to do more registration. We will discuss \texttt{GMT\_End\_IO} once we are done with the data import.
  583. The function returns TRUE (1) if there is an error (which is passed back with \texttt{API->error}),
  584. otherwise it returns FALSE (0).
  585. \subsection{Import a data set}
  586. \index{Import!Data set}
  587. \index{Data!Import data}
  588. \index{Resources!Import data set}
  589. If your main program needs to import any of the five recognized data types (CPT table, data table, text table, \GMT\ grid, or image)
  590. you will use either the \texttt{GMT\_Read\_Data} or \texttt{GMT\_Get\_Data} functions. The former is typically used when
  591. reading from files, streams (e.g., \texttt{stdin}), or an open file handle, while the latter is only used with a registered resource via
  592. its ID.
  593. Because of the similarities of these five import functions we use
  594. an generic form that covers all of them.
  595. \subsubsection{Import from a file, stream, or handle}
  596. \index{GMT\_Read\_Data}
  597. To read an entire data set from a file, a stream, or file handle, use
  598. \begin{verbatim}
  599. void * GMT_Read_Data (struct GMTAPI_CTRL *API, long family, long method, \
  600. long geometry, double wesn[], long mode, char *input, void *data)
  601. \end{verbatim}
  602. where \texttt{data} is usually NULL except when reading grids in two steps
  603. (i.e., first get a grid structure with a header, then read the data).
  604. Most of these arguments have been discussed earlier. This function can
  605. be called in three different situations:
  606. \begin{enumerate}
  607. \item If you have a single source (filename, stream pointer, etc.) you can call
  608. \texttt{GMT\_Read\_Data} directly; there is no need to first register the source
  609. with \texttt{GMT\_Register\_IO} or gather the sources with \texttt{GMT\_Init\_IO}.
  610. However, if you did register a single source you can still pass it via an encoded
  611. filename (see \texttt{GMT\_Encode\_ID}) or you can instead use \texttt{GMT\_Get\_Data}
  612. using the integer ID directly (see next section).
  613. \item If you want to specify \texttt{stdin} as source then use \texttt{input} as NULL.
  614. \item If you already registered all available sources with \texttt{GMT\_Init\_IO} then
  615. you pass \texttt{geometry} = 0.
  616. \end{enumerate}
  617. Space will be allocated to hold the results, if needed, and a pointer to the object is returned.
  618. If there are errors we simply return NULL and pass back the error code via \texttt{API->error}.
  619. The \texttt{mode} parameter takes on different meanings for the different data types.
  620. \begin{description}
  621. \item [CPT table]: \texttt{mode} are bit-flags that controls how the CPT file's back-, fore-, and NaN-colors
  622. should be initialized. Select 0 to read the CPT file's back-, fore-, and NaN-colors, 2
  623. to replace these with the \GMT\ default values, or 4 to replace them with the color tables
  624. entries for highest and lowest value.
  625. \item [Data table]: \texttt{mode} is not used.
  626. \item [Text table]: \texttt{mode} is not used.
  627. \item [GMT grid]: Here \texttt{mode} determines how we read the grid:
  628. \index{GMT\_GRID\_ALL}
  629. \index{GMT\_GRID\_HEADER}
  630. \index{GMT\_GRID\_DATA}
  631. \index{GMT\_GRID\_COMPLEX\_REAL}
  632. \index{GMT\_GRID\_COMPLEX\_IMAG}
  633. To get the entire grid and its header, pass GMT\_GRID\_ALL. However, if you
  634. need to extract a sub-region you must first get the header only by passing
  635. GMT\_GRID\_HEADER, then use the header structure attributes \texttt{wesn},
  636. to specify a subset via the array \texttt{wesn}, and then call
  637. \texttt{GMT\_Read\_Data} a second time, with \texttt{mode} = GMT\_GRID\_DATA and passing your \texttt{wesn} array
  638. and the grid structure returned from the first call.
  639. In the event your data array should be allocated to hold both the real and imaginary parts of a
  640. complex data set you must add either GMT\_GRID\_COMPLEX\_REAL or GMT\_GRID\_COMPLEX\_IMAG to \texttt{mode}
  641. so as to allow for the extra space and to position the input values correctly.
  642. \end{description}
  643. \subsubsection{Import from a memory location}
  644. However, if you are importing from memory locations or prefer to first register the source, then you
  645. should use \texttt{GMT\_Get\_Data} instead. This function requires fewer arguments since you simply
  646. pass the unique ID number of the resource. The function is described as follows:
  647. \index{GMT\_Get\_Data}
  648. \begin{verbatim}
  649. void * GMT_Get_Data (struct GMTAPI_CTRL *API, long ID, long mode, \
  650. void *data)
  651. \end{verbatim}
  652. The \texttt{ID} is the unique object ID you received when registering the resource earlier,
  653. \texttt{mode} controls some aspects of the import (see \texttt{GMT\_Read\_Data} above),
  654. while \texttt{data} is usually NULL except when reading grids in two steps
  655. (i.e., first get a grid structure with a header, then read the data).
  656. Most of the other arguments have been discussed earlier.
  657. Space will be allocated to hold the results, if needed, and a pointer to the object is returned.
  658. If there are errors we simply return NULL and pass back the error code via \texttt{API->error}.
  659. \subsubsection{Retrieve an allocated result}
  660. Finally, if you need to access the result that a GMT\ module normally will write to an output file,
  661. then you need to register an output destination with \texttt{GMT\_Register\_IO} first (passing \texttt{ptr} == NULL).
  662. The GMT\ module will then allocate space to hold the output and let the API know where this memory resides.
  663. You can then use \texttt{GMT\_Retrieve\_Data} to get a pointer to the container where the data was stored.
  664. This function requires fewer arguments since you simply
  665. pass the unique ID number of the resource. The function is described as follows:
  666. \index{GMT\_Retrieve\_Data}
  667. \begin{verbatim}
  668. void * GMT_Retrieve_Data (struct GMTAPI_CTRL *API, long ID)
  669. \end{verbatim}
  670. The \texttt{ID} is the unique object ID you received when registering the NULL resource earlier,
  671. Since this container has already been created, a pointer to the object is returned.
  672. If there are errors we simply return NULL and pass back the error code via \texttt{API->error}.
  673. \subsection{Importing a data record}
  674. \index{Importing a data record}
  675. \index{Data!Import data record}
  676. \index{Resources!Import data record}
  677. If your program must read data table records one-by-one you must first
  678. enable this input mechanism with \texttt{GMT\_Begin\_IO} and then use the
  679. \texttt{GMT\_Get\_Record} function in a loop; the prototype is
  680. \index{GMT\_Get\_Record}
  681. \begin{verbatim}
  682. void * GMT_Get_Record (struct GMTAPI_CTRL *API, long mode, long *nfields)
  683. \end{verbatim}
  684. where the returned value is either a pointer to a double array with the current row
  685. or a pointer to a character string with the current row, depending on \texttt{mode}.
  686. In either case these pointers point to memory internal to \GMT\ and should be considered read-only.
  687. When we reach end-of-file, encounter conversion problems, read header comments, or identify
  688. segment headers we return a NULL pointer, with the status of the current record returned via
  689. \texttt{API->GMT->current.io.status}. Typically, this status is examined using macros that
  690. return TRUE or FALSE depending on the particular check. There are 11 macros available to
  691. programmers; for a list see Table~\ref{tbl:iomacros}.
  692. The \texttt{nfields} pointer will return the number of fields read; pass NULL if your program
  693. does not need this information.
  694. Normally (\texttt{mode} == GMT\_READ\_DOUBLE or 0), we return a pointer to the double array.
  695. \index{GMT\_READ\_DOUBLE}
  696. \index{GMT\_READ\_TEXT}
  697. To read text record, supply instead \texttt{mode} == GMT\_READ\_TEXT (or 1) and we
  698. instead return a pointer to the text record.
  699. However, if you have input records that mixes organized floating-point columns with text
  700. items you could pass \texttt{mode} == GMT\_READ\_MIXED (2). Then, \GMT\ will attempt to extract the
  701. floating-point values; you can still access the record string, as discussed below.
  702. Finally, if your application needs to be notified when \GMT\ closes one file and opens another,
  703. add GMT\_FILE\_BREAK to \texttt{mode} and check for the return code GMT\_IO\_NEXT\_FILE (By
  704. default, we treat the combination of many input files as one virtual file).
  705. Using \texttt{GMT\_Get\_Record} requires you to first initialize the source(s)
  706. with \texttt{GMT\_Init\_IO}. This function returns NULL if there are problems and sets status codes that your
  707. program will need to examine to take appropriate response:
  708. \begin{description}
  709. \item [GMT\_IO\_TABLE\_HEADER]: We read a table header; to examine this text string
  710. (if working with ASCII data), see \texttt{API->GMT->current.io.segment\_header}.
  711. \index{GMT\_IO\_TABLE\_HEADER}
  712. \item [GMT\_IO\_SEGMENT\_HEADER]: We read a segment header; to examine this text string
  713. (if working with ASCII data), see \texttt{API->GMT->current.io.current\_record}.
  714. \index{GMT\_IO\_TABLE\_HEADER}
  715. \item [GMT\_IO\_MISMATCH]: The number of columns read is less than what the program expected.
  716. \index{GMT\_IO\_MISMATCH}
  717. \item [GMT\_IO\_EOF]: We have reached the end of the source.
  718. \index{GMT\_IO\_EOF}
  719. \item [GMT\_IO\_NAN]: The record has NaNs in fields that we do not allow to have NaNs, and
  720. hence, it is a bad record (see \GMT's IO\_NAN\_RECORD defaults).
  721. \index{GMT\_IO\_NAN}
  722. \item [GMT\_IO\_GAP]: A user-defined data gap has been encountered (see \GMT's \Opt{g} option)
  723. \index{GMT\_IO\_GAP}
  724. \end{description}
  725. Developers who need to import data on a record-by-record basis should consult the source
  726. code of, say, \filename{blockmean\_func.c} or \filename{pstext\_func.c}.
  727. \begin{table}[h]
  728. \small
  729. \centering
  730. \begin{tabular}{|l|l|} \hline
  731. \multicolumn{1}{|c|}{\emph{Macro}} & \multicolumn{1}{c|}{\emph{description}} \\ \hline
  732. \texttt{GMT\_REC\_IS\_TBL\_HEADER(API)} & TRUE if we read a table header \\ \hline
  733. \texttt{GMT\_REC\_IS\_SEG\_HEADER(API)} & TRUE if we read a segment header \\ \hline
  734. \texttt{GMT\_REC\_IS\_ANY\_HEADER(API)} & TRUE if we read either header type \\ \hline
  735. \texttt{GMT\_REC\_IS\_ERROR(API)} & TRUE if we had a read or conversion failure \\ \hline
  736. \texttt{GMT\_REC\_IS\_EOF(API)} & TRUE if we reached the end of the file (EOF) \\ \hline
  737. \texttt{GMT\_REC\_IS\_NAN(API)} & TRUE if we only read NaNs \\ \hline
  738. \texttt{GMT\_REC\_IS\_GAP(API)} & TRUE if this record implies a data gap \\ \hline
  739. \texttt{GMT\_REC\_IS\_NEW\_SEGMENT(API)}& TRUE if we enter a new segment \\ \hline
  740. \texttt{GMT\_REC\_IS\_LINE\_BREAK(API)} & TRUE if we encountered a segment header, EOF, NaNs or gap \\ \hline
  741. \texttt{GMT\_REC\_IS\_FILE\_BREAK(API)} & TRUE if we finished one file but not the last \\ \hline
  742. \texttt{GMT\_REC\_IS\_DATA(API)} & TRUE if we read a data record \\ \hline
  743. \end{tabular}
  744. \caption{Macros used to determine status of current data record. The gap macro depends on the current \Opt{g} settings.}
  745. \label{tbl:iomacros}
  746. \index{Record!Status}
  747. \end{table}
  748. \subsection{Disable Data Import}
  749. \index{Import!Disable}
  750. \index{Data!Import}
  751. \index{Resources!Import data}
  752. Once the record-by-record input processing has completed we disable further input to prevent accidental
  753. reading from occurring (due to poor program structure, bugs, etc.). We do so by calling \texttt{GMT\_End\_IO}. This
  754. function disables further record-by-record data import; its prototype is
  755. \begin{verbatim}
  756. long GMT_End_IO (struct GMTAPI_CTRL *API, long direction, long mode)
  757. \end{verbatim}
  758. \noindent
  759. and we specify \texttt{direction} = GMT\_IN. At the moment, \texttt{mode} is not used. This call
  760. will also reallocate any arrays obtained into their proper lengths.
  761. The function returns TRUE (1) if there is an error (which is passed back with \texttt{API->error}),
  762. otherwise it returns FALSE (0).
  763. \section{Prepare program options}
  764. \index{Program options!Prepare}
  765. \label{sec:func}
  766. The module prototype interface is
  767. \begin{verbatim}
  768. long GMT_module (struct GMTAPI_CTRL *API, long mode, void *args)
  769. \end{verbatim}
  770. All GMT modules may be called with one of three sets of \texttt{args} depending on \texttt{mode}.
  771. The three modes differ in how the options are passed to the module:
  772. \begin{description}
  773. \item [$mode > 0$]: Expects \texttt{args} to be an array of text options \texttt{mode} to be a count of
  774. how many options are passed (i.e., the \texttt{argc, argv[]} model).
  775. \item [$mode < 0$]: Expects \texttt{args} to be a pointer to a doubly-linked list of objects with individual options
  776. for the current program.
  777. \item [$mode == 0$]: Expects \texttt{args} to be a single text string with all required options.
  778. \end{description}
  779. Here, \texttt{GMT\_module} stands for any of the \GMT\ modules, such as \texttt{GMT\_psxy}.
  780. All modules returns FALSE (o) if they returned successfully; otherwise they return an error code
  781. back to the calling environment.
  782. \subsection{Set program options via text array arguments}
  783. \index{Set program options via text array arguments}
  784. \index{Program options!Text array arguments}
  785. When texttt{mode} $> 0$ we expect an array \texttt{args} of character strings that each
  786. holds a single command line argument (e.g., ``\Opt{R}\emph{120:30/134:45/8S/3N}'') and interpret \texttt{mode}
  787. to be the count of how many options are passed. This, of course, is almost exactly how the stand-alone \GMT\
  788. programs are called (and reflects how they themselves are activated internally). We call this the ``argc--argv'' mode.
  789. Depending on how your program obtains the necessary options you may find that this interface offers all you need.
  790. \subsection{Set program options via text command}
  791. \index{Set program options via text command}
  792. \index{Program options!Text command argument}
  793. If \texttt{mode} == 0 then \texttt{args} will be examined to see if it contains several options within a single command string.
  794. If so we will break these into separate options. This is useful if you wish to pass a single string such as
  795. ``\Opt{R}\emph{120:30/134:45/8S/3N} \Opt{JM}\emph{6i} mydata.txt \Opt{Sc}0.2c''. We call this the ``command'' mode.
  796. \subsection{Set program options via linked structures}
  797. \index{Set program options via linked structures}
  798. \index{Program options!Linked structures}
  799. The third, linked-list interface allows developers using higher-level programming languages to pass all command
  800. options via a pointer to a NULL-terminated, doubly-linked list of option structures, each containing
  801. information about a single option. Here, instead of text arguments we pass the pointer to the linked list of
  802. options mentioned above, and \texttt{mode} must be passed as -1 (or any negative value). Using
  803. this interface can be more involved since you need to generate the linked
  804. list of program options; however, utility functions exist to simplify its use.
  805. This interface is intended for programs whose internal workings are better suited to
  806. generate such arguments -- we call this the ``options'' mode. The order in the list is not important as \GMT\ will sort it internally
  807. according to need. The option structure is defined in Table \ref{tbl:options}.
  808. \begin{table}[h]
  809. \small
  810. \centering
  811. \begin{tabular}{ll} \hline
  812. \multicolumn{2}{l}{\texttt{struct GMT\_OPTION \{}} \\
  813. \texttt{char option;} & /* \emph{Single character of the option (e.g.,'G' for} \Opt{G} */ \\
  814. \texttt{char *arg;} & /* \emph{String pointer with arguments (NULL if not used)} */ \\
  815. \texttt{struct GMT\_OPTION *next;} & /* \emph{Pointer to next option (NULL for last option)} */\\
  816. \texttt{struct GMT\_OPTION *prev;} & /* \emph{Pointer to previous option (NULL for first option)} */\\
  817. \texttt{\};} & \\ \hline
  818. \end{tabular}
  819. \caption{Definition of the structure used to hold a single program option.}
  820. \label{tbl:options}
  821. \index{Option!Structure}
  822. \end{table}
  823. \subsection{Convert between text and linked structures}
  824. \index{Convert between text and linked structures}
  825. \index{Linked structures!Convert to text}
  826. \index{Text options!Convert to linked structures}
  827. To assist programmers there are also two convenience functions that
  828. allow you to convert between the two argument formats. They are
  829. \begin{verbatim}
  830. struct GMT_OPTIONS * GMT_Create_Options (struct GMTAPI_CTRL *API, \
  831. long argc, void *args)
  832. \end{verbatim}
  833. \index{GMT\_Create\_Options}
  834. This function accepts your array of text arguments (cast via a void pointer), allocates the necessary
  835. space, performs the conversion, and returns a pointer to the
  836. head of the linked list of program options. However, in case of an error
  837. we return a NULL pointer and set \texttt{API->error} to indicate the nature of the problem.
  838. Otherwise, the pointer may now be passed to the
  839. relevant \texttt{GMT\_module}. Note that if your list of text arguments
  840. were obtained from a C \texttt{main()} function then \texttt{argv[0]} will
  841. contain the name of the calling program. To avoid passing this as a file
  842. name option, call \texttt{GMT\_Create\_Options} with \texttt{argc-1}
  843. and \texttt{argv+1}. If, you wish to pass a single text string with
  844. multiple options (in lieu of an array of text strings), then pass \texttt{arg} = 0.
  845. When no longer needed you can remove the entire list by calling
  846. \begin{verbatim}
  847. long GMT_Destroy_Options (struct GMTAPI_CTRL *API, \
  848. struct GMT_OPTION **list)
  849. \end{verbatim}
  850. \index{GMT\_Destroy\_Options}
  851. The function returns TRUE (1) if there is an error (which is passed back with \texttt{API->error}),
  852. otherwise it returns FALSE (0).
  853. The inverse function prototype is
  854. \begin{verbatim}
  855. char ** GMT_Create_Args (struct GMTAPI_CTRL *API, long *argc, \
  856. struct GMT_OPTIONS *list)
  857. \end{verbatim}
  858. \index{GMT\_Create\_Args}
  859. which allocates space for the text strings and performs the conversion;
  860. it passes back the count of the arguments via \texttt{argc} and returns a pointer to the text array.
  861. In the case of an error we return a NULL pointer and set \texttt{API->error} to reflect the error type.
  862. Note that \texttt{argv[0]} will not contain the name of the program as
  863. is the case the arguments presented by a C \texttt{main()} function.
  864. When you no longer have any use for the text array, call
  865. \begin{verbatim}
  866. long GMT_Destroy_Args (struct GMTAPI_CTRL *API, long argc, char *argv[])
  867. \end{verbatim}
  868. \index{GMT\_Destroy\_Args}
  869. to deallocate the space used. This function returns TRUE (1) if there is an error
  870. (which is passed back with \texttt{API->error}),
  871. otherwise it returns FALSE (0).
  872. Finally, to convert the linked list of option structures to a single
  873. text string command, use
  874. \begin{verbatim}
  875. char * GMT_Create_Cmd (struct GMTAPI_CTRL *API, struct GMT_OPTION *list)
  876. \end{verbatim}
  877. \index{GMT\_Create\_Cmd}
  878. Developers who plan to import and export \GMT\ shell scripts might find it
  879. convenient to use these functions. In case of an error we return a NULL pointer
  880. and set \texttt{API->error}, otherwise a pointer to an allocated string is returned.
  881. It
  882. \subsection{Manage the linked list of options}
  883. \index{Manage the linked list of options}
  884. \index{Option!Manage}
  885. \index{Linked options!Manage}
  886. Several additional utility functions are available for programmers who wish to manipulate
  887. program option structures within their own programs. These allow you to create new
  888. option structures, append them to the linked list, replace existing options with new
  889. values, find a particular option, and remove options from the list. Note: The
  890. order in which the options appear in the linked list is of no consequence to \GMT.
  891. Internally, \GMT\ will sort and process the options in the manner required.
  892. Externally, you are free to maintain your own order.
  893. \subsubsection{Make a new option structure}
  894. \index{Make a new option structure}
  895. \index{Option!Make}
  896. \texttt{GMT\_Make\_Option} will allocate a new option structure, assign it values
  897. given the \texttt{option} and \texttt{arg} parameter (pass NULL if there is no
  898. argument for this option), and returns a pointer
  899. to the allocated structure. The prototype is
  900. \index{GMT\_Make\_Option}
  901. \begin{verbatim}
  902. struct GMT_OPTION *GMT_Make_Option (struct GMTAPI_CTRL *API, char option, \
  903. char *arg)
  904. \end{verbatim}
  905. Should memory allocation fail the function will print an error message
  906. set an error code via \texttt{API->error}, and return NULL.
  907. \subsubsection{Append an option to the linked list}
  908. \index{Append an option to the linked list}
  909. \index{Option!Append}
  910. \texttt{GMT\_Append\_Option} will append the specified \texttt{option} to the end
  911. of the doubly-linked \texttt{list}. The prototype is
  912. \index{GMT\_Append\_Option}
  913. \begin{verbatim}
  914. struct GMT_OPTION * GMT_Append_Option (struct GMTAPI_CTRL *API, \
  915. struct GMT_OPTION *option, struct GMT_OPTION *list)
  916. \end{verbatim}
  917. We return the list back, and if \texttt{list} is given as NULL we return \texttt{option} as the start of the new list.
  918. Any errors results in a NULL pointer with \texttt{API->error} holding the error type.
  919. \subsubsection{Find an option in the linked list}
  920. \index{Find an option in the linked list}
  921. \index{Option!Find}
  922. \texttt{GMT\_Find\_Option} will return a pointer \texttt{ptr} to the first option in the linked list starting
  923. at \texttt{list} whose option character equals \texttt{option}. If not found we return NULL. While this is
  924. not necessarily an error we still set \texttt{API->error} accordingly.
  925. The prototype is
  926. \index{GMT\_Find\_Option}
  927. \begin{verbatim}
  928. struct GMT_OPTION *GMT_Find_Option (struct GMTAPI_CTRL *API, char option, \
  929. struct GMT_OPTION *list)
  930. \end{verbatim}
  931. If you need to look for multiple occurrences of a certain option you will need to
  932. call \texttt{GMT\_Find\_Option} again, passing the option following the
  933. previously found option as the \texttt{list} entry, i.e.,
  934. \begin{verbatim}
  935. list = *ptr->next;
  936. \end{verbatim}
  937. \subsubsection{Update an existing option in the list}
  938. \index{Update an existing option in the list}
  939. \index{Option!Update}
  940. \texttt{GMT\_Update\_Option} will first determine if \texttt{option} exists;
  941. if so it will delete it. Then, it will make a new option from the arguments
  942. and append it to the end of the linked \texttt{list}. The prototype is
  943. \index{GMT\_Update\_Option}
  944. \begin{verbatim}
  945. long GMT_Update_Option (struct GMTAPI_CTRL *API, char option, \
  946. char *arg, struct GMT_OPTION *list)
  947. \end{verbatim}
  948. An error will be reported if (a) \texttt{list} is NULL or (b) the option is not found.
  949. The function returns TRUE (1) if there is an error (i.e., \texttt{list} is NULL or the
  950. option is not found); the error code is passed back via \texttt{API->error}.
  951. Otherwise it returns FALSE (0).
  952. \subsubsection{Delete an existing option in the linked list}
  953. \index{Delete an existing option in the linked list}
  954. \index{Option!Delete}
  955. You may use \texttt{GMT\_Delete\_Option} to remove \texttt{option} from
  956. the linked \texttt{list}. The prototype is
  957. \index{GMT\_Delete\_Option}
  958. \begin{verbatim}
  959. long GMT_Delete_Option (struct GMTAPI_CTRL *API, \
  960. struct GMT_OPTION *current)
  961. \end{verbatim}
  962. We return TRUE if the option is not found in the list and set \texttt{API->error} accordingly.
  963. Note: Only the first occurrence of the specified option will be deleted. If you need to delete all such
  964. options you will need to call this function in a loop until it returns a non-zero
  965. status.
  966. \subsubsection{Specify a file via an linked option}
  967. \index{Specify a file via an linked option}
  968. \index{Option!Files}
  969. To specify an input file name via an option, simply use $<$ as the option (this is what
  970. \texttt{GMT\_Create\_Options} does when it finds filenames on the command line).
  971. Likewise, $>$ can be used to explicitly indicate an output file. In order to append to
  972. an existing file, use $>>$. For example the following command would read from file.A
  973. and append to file.B:
  974. \begin{verbatim}
  975. gmtconvert -<file.A ->>file.B
  976. \end{verbatim}
  977. These options also work on the command line but usually one would have to escape the
  978. special characters $<$ and $>$ as they are used for file redirection.
  979. \subsection{Parsing GMT common options}
  980. \index{Parsing GMT common options}
  981. While all the main \GMT\ modules have their own specific option parser, we also provide a general
  982. parser that only examines the common \GMT\ options such as \Opt{R}, \Opt{J}, \Opt{V}, etc. The prototype
  983. of this parser is
  984. \index{GMT\_Parse\_Common}
  985. \begin{verbatim}
  986. long GMT_Parse_Common (struct GMTAPI_CTRL *API, \
  987. struct GMT_OPTION *list)
  988. \end{verbatim}
  989. An error will be reported via \texttt{API->error} if any of the common \GMT\ options fail to parse,
  990. and if so we return TRUE; if not errors we return FALSE. All other options,
  991. including file names, will be silently ignored. The parsing will update the internal \GMT\
  992. information structure that affects program operations.
  993. \section{Calling a GMT module}
  994. \index{Calling a GMT module}
  995. Given your linked list of program options (or text array) and possibly some registered resources, you
  996. can now call the required \GMT\ module using one of the two flavors discussed in section {\ref{sec:func}}.
  997. All modules return an error or status code that your program should consider before processing the results.
  998. \section{Exporting Data}
  999. \index{Exporting Data}
  1000. \index{Data!Export data}
  1001. \index{Resources!Export data}
  1002. If your program needs to write any of the four recognized data types (CPT files, data tables, text tables, or \GMT\ grids)
  1003. you can use the \texttt{GMT\_Put\_Data}. In the case of data and text tables, you may also consider the
  1004. \texttt{GMT\_Put\_Record} function.
  1005. As a general rule, your program organization may simplify if you can write the export the entire resource with
  1006. \texttt{GMT\_Put\_Data}. However, if the program logic is simple or already involves using \texttt{GMT\_Get\_Record},
  1007. it may be better to export one data record at the time via \texttt{GMT\_Put\_Record}.
  1008. Both of these output functions takes a parameter called \texttt{mode}. The \texttt{mode} parameter generally
  1009. takes on different meanings for the different data types and will be discussed below.
  1010. However, one bit setting is common to all types: By default, you are only allowed to write a
  1011. data resource once; the resource is then flagged to have been written and subsequent attempts to write
  1012. to the same resource will quietly be ignored. In the unlikely event you need to re-write a
  1013. resource you can override this default behavior by adding GMT\_IO\_RESET to your \texttt{mode} parameter.
  1014. \subsection{Enable Data Export}
  1015. \index{Export!Enable}
  1016. \index{Data!Export}
  1017. \index{Resources!Export data}
  1018. Similar to the data import procedures, once all output destinations have been registered, we signal the API that we are done with the registration
  1019. phase and are ready to start the actual data export. As for input, this step is only needed when dealing with record-by-record writing.
  1020. Again, we enable record-by-record writing by calling \texttt{GMT\_Begin\_IO}, this time with \texttt{direction} = GMT\_OUT.
  1021. This function enables data export and prepares the registered destinations for the upcoming writing.
  1022. \subsection{Exporting a data set}
  1023. \index{Exporting a data set}
  1024. \index{Data!Export data set}
  1025. \index{Resources!Export data set}
  1026. To have your program accept results from \GMT\ modules and write them
  1027. separately requires you to use the \texttt{GMT\_Write\_Data} or \texttt{GMT\_Put\_Data} functions. They are
  1028. very similar to the \texttt{GMT\_Read\_Data} and \texttt{GMT\_Get\_Data} functions encountered earlier.
  1029. \subsubsection{Exporting a data set to a file, stream, or handle}
  1030. \index{GMT\_Write\_Data}
  1031. The prototype for writing to a file (via name, stream, or file handle) is
  1032. \begin{verbatim}
  1033. long GMT_Write_Data (struct GMTAPI_CTRL *API, long family, long method, \
  1034. long geometry, double wesn[], long mode, void *output, void *data)
  1035. \end{verbatim}
  1036. where \texttt{data} is a pointer to any of the four structures
  1037. discussed previously. Again, the \texttt{mode} parameter is specific to
  1038. each data type:
  1039. \begin{description}
  1040. \item [CPT table]: \texttt{mode} controls if the CPT table's back-, fore-, and NaN-colors
  1041. should be written (1) or not (0).
  1042. \item [Data table]: If \texttt{method} is GMT\_IS\_FILE, then the value of
  1043. \texttt{mode} affects how the data set is written:
  1044. \index{GMT\_IS\_DATASET\_FILE}
  1045. \begin{description}
  1046. \item [GMT\_WRITE\_DATASET]: The entire data set will be written to the single file [0].
  1047. \index{GMT\_WRITE\_DATASET}
  1048. \item [GMT\_WRITE\_TABLES]: Each table in the data set is written to individual files [1].
  1049. You can either specify an output file name that \emph{must} contain one C-style
  1050. format specifier for a long variable (e.g., ``New\_Table\_\%6.6ld.txt''), which will be
  1051. replaced with the table number (a running number from 0) \emph{or} you must assign
  1052. to each table \emph{i} a unique output file name via the \texttt{D->table[i]->file[GMT\_OUT]}
  1053. variables prior to calling the function.
  1054. \index{GMT\_WRITE\_TABLES}
  1055. \item [GMT\_WRITE\_SEGMENTS]: Each segment in the data set is written to an individual file [2].
  1056. Same setup as for GMT\_WRITE\_TABLES except we use sequential segment numbers to build the file names.
  1057. \index{GMT\_WRITE\_SEGMENTS}
  1058. \item [GMT\_WRITE\_TABLE\_SEGMENTS]: Each segment in the data set is written to an individual file [3].
  1059. You can either specify an output file name that \emph{must} contain two C-style
  1060. format specifiers for two long variables (e.g., ``New\_Table\_\%6.6ld\_Segment\_\%3.3ld.txt''),
  1061. which will be replaced with the table and segment numbers, \emph{or}
  1062. you must assign to each segment \emph{j} in each table \emph{i} a unique output file name
  1063. via the \texttt{D->table[i]->segment[j]->file[GMT\_OUT]} variables prior to calling the function.
  1064. \index{GMT\_WRITE\_TABLE\_SEGMENTS}
  1065. \index{GMT\_WRITE\_OGR}
  1066. \item [GMT\_WRITE\_OGR]: Writes the dataset in OGR/GMT format in conjunction with the \Opt{a} setting [4].
  1067. \end{description}
  1068. \item [Text table]: The \texttt{mode} is used the same way as for data tables.
  1069. \item [GMT grid]: Here, \texttt{mode} may be GMT\_GRID\_HEADER to only update a file's header
  1070. structure, but normally it is simply GMT\_GRID\_ALL (0) so the entire
  1071. grid and its header will be exported (a subset is not allowed during export).
  1072. However, in the event your data array holds both the real and imaginary parts of a
  1073. complex data set you must add either GMT\_GRID\_COMPLEX\_REAL (4) or GMT\_GRID\_COMPLEX\_IMAG (16) to \texttt{mode}
  1074. so as to export the corresponding grid values correctly. Finally, for native binary grids you may skip writing
  1075. the grid header by adding GMT\_GRID\_NO\_HEADER (16); this setting is ignored for other grid formats.
  1076. \index{GMT\_GRID\_HEADER}
  1077. \index{GMT\_GRID\_ALL}
  1078. \index{GMT\_GRID\_COMPLEX\_REAL}
  1079. \index{GMT\_GRID\_COMPLEX\_IMAG}
  1080. \index{GMT\_GRID\_NO\_HEADER}
  1081. \end{description}
  1082. If successful the function returns FALSE (0); otherwise we return TRUE (1) and set \texttt{API->error} to reflect to cause.
  1083. \subsubsection{Exporting a data set to memory}
  1084. \index{GMT\_Put\_Data}
  1085. If writing to a memory destination you will want to first register that destination and then use the returned ID with
  1086. \texttt{GMT\_Put\_Data} instead:
  1087. \begin{verbatim}
  1088. long GMT_Put_Data (struct GMTAPI_CTRL *API, long ID, long mode, \
  1089. void *data)
  1090. \end{verbatim}
  1091. where \texttt{ID} is the unique ID of the registered destination, \texttt{mode}
  1092. is specific to each data type (and controls aspects of the output structuring),
  1093. and \texttt{data} is a pointer to any of the four structures
  1094. discussed previously. For more detail, see \texttt{GMT\_Write\_Data} above.
  1095. If successful the function returns FALSE (0); otherwise we return TRUE (1) and set \texttt{API->error} to reflect to cause.
  1096. \subsection{Exporting a data record}
  1097. \index{Exporting a data record}
  1098. \index{Data!Export data record}
  1099. \index{Resources!Export data record}
  1100. If your program must write data table records one-by-one you must first enable record-by-record
  1101. writing with \texttt{GMT\_Begin\_IO} and then use the \texttt{GMT\_Put\_Record} function in a loop;
  1102. the prototype is
  1103. \index{GMT\_Put\_Record}
  1104. \begin{verbatim}
  1105. long GMT_Put_Record (struct GMTAPI_CTRL *API, long mode, void *rec)
  1106. \end{verbatim}
  1107. where \texttt{rec} is a pointer to either (a) a double-precision array with the current row.
  1108. Then, \texttt{rec} is expected to hold at least as many items as the current setting of
  1109. \texttt{n\_col[GMT\_OUT]}, which represents the number of columns in the output destination.
  1110. Alternatively (b), \texttt{rec} points to a text string.
  1111. The \texttt{mode} parameter must be set to reflect what is passed. Using \texttt{GMT\_Put\_Record}
  1112. requires you to first initialize the destination with \texttt{GMT\_Init\_IO}.
  1113. Note that for families GMT\_IS\_DATASET and GMT\_IS\_TEXTSET the methods GMT\_IS\_COPY and GMT\_IS\_REF are not supported since
  1114. you can simply populate the GMT\_DATASET structure directly.
  1115. As mentioned, \texttt{mode} affects what is actually written:
  1116. \begin{description}
  1117. \item [GMT\_WRITE\_DOUBLE]: Normal operation that builds the current output record from
  1118. the values in \texttt{rec} [0].
  1119. \index{GMT\_WRITE\_DOUBLE}
  1120. \item [GMT\_WRITE\_TEXT]: For ASCII output mode we write the text string \texttt{rec}.
  1121. If \texttt{rec} is NULL then we use the current (last imported) text record.
  1122. If binary output mode we quietly skip writing this record [1].
  1123. \index{GMT\_WRITE\_TEXT}
  1124. \item [GMT\_WRITE\_TBLHEADER]: For ASCII output mode we write the text string \texttt{rec}.
  1125. If \texttt{rec} is NULL then we write the last read
  1126. header record (and ensures it starts with \#). If binary output mode we quietly skip writing this record [2].
  1127. \index{GMT\_WRITE\_TBLHEADER}
  1128. \item [GMT\_WRITE\_SEGHEADER]: For ASCII output mode we use the text string \texttt{rec} as the segment header.
  1129. If \texttt{rec} is NULL then we use the current (last read) segment header record.
  1130. If binary output mode instead we write a record composed of NaNs [1].
  1131. \index{GMT\_WRITE\_SEGHEADER}
  1132. \end{description}
  1133. The function returns TRUE (1) if there was an error associated with the writing (which is passed back with \texttt{API->error}),
  1134. otherwise it returns FALSE (0).
  1135. \subsection{Disable Data Export}
  1136. \index{Export!Disable}
  1137. \index{Data!Export}
  1138. \index{Resources!Export data}
  1139. Once the record-by-record output has completed we disable further output to prevent accidental
  1140. writing from occurring (due to poor program structure, bugs, etc.). We do so by calling \texttt{GMT\_End\_IO}. This
  1141. function disables further record-by-record data export; here, we obviously pass \texttt{direction} = GMT\_OUT.
  1142. \section{Destroy allocated resources}
  1143. \index{Destroy allocated resources}
  1144. \index{Resources!Destroy}
  1145. If your session imported any data sets into memory then you may explicitly free this
  1146. memory once it is no longer needed and before terminating the session.
  1147. This is done with the \texttt{GMT\_Destroy\_Data} function, whose prototype is
  1148. \index{GMT\_Destroy\_Data}
  1149. \begin{verbatim}
  1150. long GMT_Destroy_Data (struct GMTAPI_CTRL *API, long mode, void *data)
  1151. \end{verbatim}
  1152. where \texttt{data} is the address of the pointer to a data container.
  1153. Pass \texttt{mode} either as GMT\_ALLOCATED or GMT\_REFERENCE. The former
  1154. is used internally by the \GMT\ modules since they can only free resources that are
  1155. not destined to live on in the memory of their calling program. The latter mode is used
  1156. to free resources in your calling program. Note that when each module completes it will
  1157. automatically free memory created by the API; similarly, when the session is destroyed
  1158. we also automatically free up memory. Thus, \texttt{GMT\_Destroy\_Data} is therefore
  1159. generally only needed when you wish to directly free up memory to avoid running out of it.
  1160. \index{GMT\_ALLOCATED}
  1161. \index{GMT\_REFERENCE}
  1162. The function returns TRUE (1) if there is an error when trying to free the memory
  1163. (the error code is passed back with \texttt{API->error}), otherwise it returns FALSE (0).
  1164. \section{Terminate a GMT session}
  1165. \index{Terminate a GMT session}
  1166. \index{GMT session!Terminate}
  1167. Before your program exits it should properly terminate the \GMT\ session, which involves a call to
  1168. \begin{verbatim}
  1169. long GMT_Destroy_Session (struct GMTAPI_CTRL **API)
  1170. \end{verbatim}
  1171. \index{GMT\_Destroy\_Session}
  1172. which simply takes the address of the pointer to the \GMT\ API control structure as its only arguments. It terminates the \GMT\ machinery
  1173. with a call to \texttt{GMT\_end} and deallocates all memory used by the \GMT\ API book-keeping. If you
  1174. requested PSL during creation then the PSL resources are freed as well. It
  1175. also unregisters any remaining resources previously registered with the session.
  1176. The \GMT\ API will only close files that it was responsible for opening in the first place.
  1177. Finally, the API structure itself is freed so your main program does not need to do so.
  1178. The function returns TRUE (1) if there is an error when trying to free the memory
  1179. (the error code is passed back with \texttt{API->error}), otherwise it returns FALSE (0).
  1180. \section{Report errors}
  1181. \index{Report errors}
  1182. \index{Errors!Report}
  1183. Since all API functions returns a status code via \texttt{API->error}, you should always check this code before
  1184. moving to the next step. All API functions will issue an error message before returning control
  1185. to the calling program. This function is
  1186. \begin{verbatim}
  1187. long GMT_Report_Error (struct GMTAPI_CTRL *API, long error);
  1188. \end{verbatim}
  1189. \index{GMT\_Report\_Error}
  1190. where \texttt{error} is the status code return by any API function. Note: The error message is
  1191. only issued if the verbosity level of the \GMT\ session is not set to 0 [Default is 1], and
  1192. messages are normally written to \texttt{stderr} unless this stream has been redirected.
  1193. Note that this function also updates \texttt{API->error} to the given value.
  1194. \section{FORTRAN 77 interface}
  1195. \index{FORTRAN 77 interface}
  1196. \index{Interface!FORTRAN 77}
  1197. FORTRAN 77 developers who wish to use the \GMT\ API may use the same 17 API functions as discussed in Chapter 2.
  1198. However, as pointers to structures and such are not available, the FORTRAN bindings provided simplifies the
  1199. interface in two ways:
  1200. \begin{itemize}
  1201. \item The first argument to the functions (the GMTAPI Control structure pointer) is not provided. Instead,
  1202. the bindings use a hidden, global external structure for this purpose and pass the pointer to it down to
  1203. the C version of the functions.
  1204. \item The resource arguments in \texttt{GMT\_Register\_IO} are not pointers to
  1205. items but the items themselves.
  1206. \end{itemize}
  1207. The list of the basic 17 FORTRAN prototype functions thus becomes
  1208. \begin{verbatim}
  1209. function GMT_Create_Session (tag, mode)
  1210. function GMT_Destroy_Session ()
  1211. function GMT_Register_IO (family, method, geometry, direction, \
  1212. resource, wesn)
  1213. function GMT_Encode_ID (filename, ID)
  1214. function GMT_Init_IO (family, geometry, direction, head)
  1215. function GMT_Begin_IO (family, geometry, direction)
  1216. function GMT_Create_Data (family, geometry, ipar)
  1217. function GMT_Read_Data (family, method, geometry, wesn, mode, \
  1218. input, data)
  1219. function GMT_Get_Data (ID, mode, data)
  1220. function GMT_Retrieve_Data (ID)
  1221. function GMT_Get_Record (rec, mode, nfields)
  1222. function GMT_Write_Data (family, method, geometry, wesn, mode, \
  1223. output, data)
  1224. function GMT_Put_Data (ID, mode, data)
  1225. function GMT_Put_Record (mode, rec)
  1226. function GMT_End_IO (direction, mode)
  1227. function GMT_Destroy_Data (mode, ptr)
  1228. function GMT_Report_Error (error)
  1229. \end{verbatim}
  1230. where \texttt{method}, \texttt{geometry}, \texttt{direction}, \texttt{ID} and \texttt{error} are integers,
  1231. \texttt{ipar} is an integer parameter array, \texttt{wesn} is a real (double precision) array,
  1232. and \texttt{resource} are source or destination addresses.
  1233. \clearpage
  1234. \thispagestyle{headings}
  1235. %\addcontentsline{toc}{chapter}{INDEX}
  1236. \printindex
  1237. \thispagestyle{headings}
  1238. \end{document}
Tip!

Press p or to see the previous file or, n or to see the next file

Comments

Loading...