1NCARG_CBIND(3NCARG) NCAR GRAPHICS NCARG_CBIND(3NCARG)
2
6 NCAR Graphics C-binding - Description of how to use the NCAR Graphics
7 C-binding.
8
10 The NCAR Graphics C-binding consists of a collection of C routines that
11 allow you to call NCAR Graphics Fortran routines from a C program with‐
12 out having to worry about the C to Fortran interface yourself. For
13 detailed information about the C-binding for a particular routine,
14 please see the man page for the corresponding Fortran routine.
15 A C-binding has been created for every user entry point in the NCAR
17 Graphics utilities with the exception of some of the obsolete utilities
18 listed below. A GKS level 0A C-binding has also been created which
19 adheres to the ISO/IEC standard.
20 From here on, a utility C-binding refers to a C-binding for the NCAR
22 Graphics utilities (AREAS, CONPACK, etc.).
23
25 For all of the utility user entry points, the name of the C-binding
26 function is the same as the Fortran routine name with a "c_" prepended.
27 For example, the name of the C-binding for the CONPACK routine CPBACK
28 is c_cpback. This naming convention does not apply to the GKS C-bind‐
29 ings. Instead, the C-binding names are more descriptive, like
30 gset_fill_colr_ind which is equivalent to the Fortran routine GSFACI.
31 Please see the man page for ncarg_gks_cbind(3NCARG) the GKS Fortran
32 routine to get the name of the corresponding GKS C-binding name.
33 The C programming language is case sensitive, so for convenience the
35 utility C-binding names and their arguments are all in lower case. In
36 this man page, the Fortran routines and their arguments will be
37 referred to in upper-case.
38
40 The argument list of each utility C-binding corresponds with the argu‐
41 ment list of the corresponding Fortran routine except in some cases
42 where multi-dimensioned arrays and/or character strings are involved.
43 These exceptions will be described in separate sections.
44 The C-binding argument list being similar to the Fortran argument list
46 makes using the C-bindings easier for people who already know the call‐
47 ing sequence of a particular Fortran routine. For example, the NCAR
48 Graphics routine PLCHHQ has the following argument list:
49 PLCHHQ(REAL X, REAL Y, CHARACTER CHRS, REAL SZ, REAL ANG, REAL CNTR)
51 and the corresponding C-binding c_plchhq has the same type of argument
53 list:
54 c_plchhq(float x, float y, char *chrs, float sz, float ang, float cntr)
56
59 One of the exceptions to the utility C-binding argument lists has to do
60 with multi-dimensioned arrays. In Fortran, arrays are stored in col‐
61 umn-major order, while in C they are stored in row-major order. This
62 means that the subscripts of a multi-dimensioned array need to be
63 switched before passing the array to a Fortran routine from C.
64 As an example, the CONPACK routine CPRECT takes as one of its arguments
66 a two-dimensional array, ZDAT. If the Fortran dimensions of ZDAT are
67 to be 25 x 14, then in the C program you must dimension ZDAT to be 14 x
68 25 before calling the C-binding c_cprect. The next three arguments of
69 CPRECT describe the array in question. The first of these three argu‐
70 ments, KZDT, is the first dimension of the array ZDAT as it is declared
71 in the Fortran calling program. For CPRECT this value would be 25.
72 For the C-binding c_cprect, however, this argument is the second dimen‐
73 sion of the array as declared in the C program. This value would be 25
74 as well since the subscripts had to be switched in the C program. The
75 second and third of these three arguments (MZDT and NZDT) specify the
76 number of elements in each row and column (respectively) to be con‐
77 toured. If you only want to contour 20 x 10 of the array ZDAT, then
78 MZDT and NZDT should be 20 and 10 respectively in CPRECT. For
79 c_cprect, these variables specify the columns and rows, so again, the
80 values would be 20 and 10 (because the subscripts have to be switched).
81
83 Another exception to the argument lists for the utility C-bindings has
84 to do with routines that return character strings. The NCAR Graphics
85 routines that return strings through the parameter list do not have a
86 string length as part of their argument lists, so you must pass an
87 extra argument to the C-binding which specifies the maximum length of
88 the string. Also, all input strings passed to the C-bindings must be
89 null-terminated!
90 For example, in the routine PCGETC, you pass a parameter name and it
92 returns the value of that parameter which in this case is a string.
93 The two arguments to PCGETC are WHCH and CVAL, where WHCH is the param‐
94 eter name and CVAL is the string to be returned. Since the C-binding
95 c_pcgetc needs to know the length of cval, an extra argument of type
96 "int" must be passed. Thus, the arguments for c_pcgetc would be whch,
97 cval, and len, where len is the length of cval as it is declared in the
98 C program. In any case of having to add an extra argument for the
99 string length, the extra argument will always be the last one in the
100 list. If more than one string length argument needs to be added, then
101 each one should be added at the end of the argument list in the order
102 that their corresponding strings appear.
103 There are some routines like AGDSHN which are defined as character
105 strings themselves. In this case, the user does not need to pass a
106 string length since it is already defined. But, the string that is
107 returned is declared statically, thus it will go away once you call the
108 routine again. If you need to save these character strings, be sure to
109 copy them to your own local variable.
110
112 The C-bindings are intended to be ANSI C compliant. To get the correct
113 function prototypes for the utility C-bindings, you can include
114 <ncarg/ncargC.h>. For the GKS C-bindings, include <ncarg/gks.h>. In
115 some cases, it may be necessary to typecast the arguments in the util‐
116 ity C-bindings to get the prototypes correct. For example, the C-bind‐
117 ings do not distinguish between singly and multiply dimensioned arrays,
118 so if you are passing a multiply dimensioned float array, you may need
119 to typecast it as a (float *) if this is not how it is declared in the
120 main program.
121
123 To compile your NCAR Graphics C program with the C-bindings, use the
124 NCARG application ncargcc. ncargcc will take care of loading in the
125 necessary C/Fortran interface libraries as well as the NCAR Graphics C
126 and Fortran libraries. You will either need to set the NCARG_ROOT or
127 the NCARG_BIN, NCARG_LIB, and NCARG_INCLUDE environment variables in
128 order to run ncargcc. See "man ncargintro" for more information.
129 If you do not wish to use ncargcc, then you can just run it with no
131 arguments to see what the necessary libraries are, and then put this
132 information in your Makefile or whatever else you are using to compile
133 and link your program. Note: if you have an ANSI C compiler, it is
134 important that you define the macro NeedFuncProto on the compile line
135 so that function prototyping is included.
136
138 A few examples of C programs that call the NCAR Graphics C-bindings
139 have been provided for your convenience. You may be familiar with the
140 output from these C programs as they were modeled after the Fortran
141 programs that you can get with the ncargex command. To copy any one of
142 these C programs in your directory, and then compile, link, and run it,
143 type:
144 ncargex xxxx
146 where xxxx is the name of the example you wish to generate. To see a
148 list of all the C examples, type:
149 ncargex -C -list
151
153
156 C-bindings have not been provided for user entry points in the follow‐
157 ing obsolete utilities:
158 Conran_family, Conrec_family, Halftone, Isosrfhr, and Pwrite_family.
160
162 Online: ncargcc(1NCARG), ncargex(1NCARG), ncarg_gks_cbind(3NCARG),
163 ncargintro(5NCARG).
164 Hardcopy: NCAR Graphics Fundamentals, UNIX Version; User's Guide for
166 NCAR GKS-0A Graphics
167
169 Copyright (C) 1987-2002
170 University Corporation for Atmospheric Research
171 This documentation is free software; you can redistribute it and/or
173 modify it under the terms of the GNU General Public License as pub‐
174 lished by the Free Software Foundation; either version 2 of the
175 License, or (at your option) any later version.
176 This software is distributed in the hope that it will be useful, but
178 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
179 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
180 Public License for more details.
181 You should have received a copy of the GNU General Public License along
183 with this software; if not, write to the Free Software Foundation,
184 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
185NCAR February 1993 NCARG_CBIND(3NCARG)