1NCARG_CBIND(3NCARG)              NCAR GRAPHICS             NCARG_CBIND(3NCARG)
2
3
4

NAME

6       NCAR  Graphics  C-binding - Description of how to use the NCAR Graphics
7       C-binding.
8

SYNOPSIS

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
16       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
21       From  here  on,  a utility C-binding refers to a C-binding for the NCAR
22       Graphics utilities (AREAS, CONPACK, etc.).
23

NAMING CONVENTION

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
34       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

ARGUMENT LISTS

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
45       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
50       PLCHHQ(REAL X, REAL Y, CHARACTER CHRS, REAL SZ, REAL ANG, REAL CNTR)
51
52       and the corresponding C-binding c_plchhq has the same type of  argument
53       list:
54
55       c_plchhq(float x, float y, char *chrs, float sz, float ang, float cntr)
56
57

ARRAYS

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
65       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

CHARACTER STRINGS

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
91       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
104       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

FUNCTION PROTOTYPES

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

COMPILING YOUR PROGRAM

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
130       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

EXAMPLES

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
145       ncargex xxxx
146
147       where  xxxx  is the name of the example you wish to generate.  To see a
148       list of all the C examples, type:
149
150     ncargex -C -list
151
153
154

OBSOLETE ROUTINES

156       C-bindings have not been provided for user entry points in the  follow‐
157       ing obsolete utilities:
158
159     Conran_family, Conrec_family, Halftone, Isosrfhr, and Pwrite_family.
160

SEE ALSO

162       Online:   ncargcc(1NCARG),   ncargex(1NCARG),  ncarg_gks_cbind(3NCARG),
163       ncargintro(5NCARG).
164
165       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
172       The use of this Software is governed by a License Agreement.
173
174
175
176NCAR                             February 1993             NCARG_CBIND(3NCARG)
Impressum