Ubuntu Manpage: NCAR Graphics C-binding - Description of how to use the NCAR Graphics C-binding.

Provided by: libncarg-dev_6.3.0-6build1_amd64

NAME

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

SYNOPSIS

       The  NCAR Graphics C-binding consists of a collection of C routines that allow you to call
       NCAR Graphics Fortran routines from a C program without having to worry  about  the  C  to
       Fortran interface yourself.  For detailed information about the C-binding for a particular
       routine, please see the man page for the corresponding Fortran routine.

       A C-binding has been created for every user entry point in  the  NCAR  Graphics  utilities
       with  the  exception  of  some  of the obsolete utilities listed below.  A GKS level 0A C-
       binding has also been created which adheres to the ISO/IEC standard.

       From here on, a utility C-binding refers to a C-binding for the  NCAR  Graphics  utilities
       (AREAS, CONPACK, etc.).

NAMING CONVENTION

       For  all  of the utility user entry points, the name of the C-binding function is the same
       as the Fortran routine name with a "c_" prepended.  For example, the name of the C-binding
       for  the CONPACK routine CPBACK is c_cpback.  This naming convention does not apply to the
       GKS   C-bindings.    Instead,   the   C-binding   names   are   more   descriptive,   like
       gset_fill_colr_ind  which is equivalent to the Fortran routine GSFACI.  Please see the man
       page for  ncarg_gks_cbind(3NCARG)  the  GKS  Fortran  routine  to  get  the  name  of  the
       corresponding GKS C-binding name.

       The  C  programming  language  is case sensitive, so for convenience the utility C-binding
       names and their arguments are all in lower case.  In this man page, the  Fortran  routines
       and their arguments will be referred to in upper-case.

ARGUMENT LISTS

       The  argument  list  of  each  utility C-binding corresponds with the argument list of the
       corresponding Fortran routine except in some cases where multi-dimensioned  arrays  and/or
       character strings are involved.  These exceptions will be described in separate sections.

       The  C-binding argument list being similar to the Fortran argument list makes using the C-
       bindings easier for people who already know the calling sequence of a  particular  Fortran
       routine.  For example, the NCAR Graphics routine PLCHHQ has the following argument list:

       PLCHHQ(REAL X, REAL Y, CHARACTER CHRS, REAL SZ, REAL ANG, REAL CNTR)

       and the corresponding C-binding c_plchhq has the same type of argument list:

       c_plchhq(float x, float y, char *chrs, float sz, float ang, float cntr)

ARRAYS

One of the exceptions to the utility C-binding argument lists has to do with multi-
dimensioned arrays. In Fortran, arrays are stored in column-major order, while in C they
are stored in row-major order. This means that the subscripts of a multi-dimensioned
array need to be switched before passing the array to a Fortran routine from C.

As an example, the CONPACK routine CPRECT takes as one of its arguments a two-dimensional
array, ZDAT. If the Fortran dimensions of ZDAT are to be 25 x 14, then in the C program
you must dimension ZDAT to be 14 x 25 before calling the C-binding c_cprect. The next
three arguments of CPRECT describe the array in question. The first of these three
arguments, KZDT, is the first dimension of the array ZDAT as it is declared in the Fortran
calling program. For CPRECT this value would be 25. For the C-binding c_cprect, however,
this argument is the second dimension of the array as declared in the C program. This
value would be 25 as well since the subscripts had to be switched in the C program. The
second and third of these three arguments (MZDT and NZDT) specify the number of elements
in each row and column (respectively) to be contoured. If you only want to contour 20 x
10 of the array ZDAT, then MZDT and NZDT should be 20 and 10 respectively in CPRECT. For
c_cprect, these variables specify the columns and rows, so again, the values would be 20
and 10 (because the subscripts have to be switched).

CHARACTER STRINGS

       Another exception to the argument lists for the utility C-bindings has to do with routines
       that return character strings.  The NCAR Graphics routines that return strings through the
       parameter list do not have a string length as part of their argument lists,  so  you  must
       pass  an extra argument to the C-binding which specifies the maximum length of the string.
       Also, all input strings passed to the C-bindings must be null-terminated!

       For example, in the routine PCGETC, you pass a parameter name and it returns the value  of
       that  parameter  which in this case is a string.  The two arguments to PCGETC are WHCH and
       CVAL, where WHCH is the parameter name and CVAL is the string to be returned.   Since  the
       C-binding  c_pcgetc needs to know the length of cval, an extra argument of type "int" must
       be passed.  Thus, the arguments for c_pcgetc would be whch, cval, and len,  where  len  is
       the  length  of  cval as it is declared in the C program.  In any case of having to add an
       extra argument for the string length, the extra argument will always be the  last  one  in
       the list.  If more than one string length argument needs to be added, then each one should
       be added at the end of the argument list in the order  that  their  corresponding  strings
       appear.

       There are some routines like AGDSHN which are defined as character strings themselves.  In
       this case, the user does not need to pass a string length since  it  is  already  defined.
       But,  the  string  that  is returned is declared statically, thus it will go away once you
       call the routine again.  If you need to save these character strings, be sure to copy them
       to your own local variable.

FUNCTION PROTOTYPES

       The  C-bindings  are  intended  to  be  ANSI  C  compliant.   To  get the correct function
       prototypes for the utility C-bindings, you can include <ncarg/ncargC.h>.  For the  GKS  C-
       bindings,  include  <ncarg/gks.h>.   In  some  cases,  it may be necessary to typecast the
       arguments in the utility C-bindings to get the prototypes correct.  For  example,  the  C-
       bindings  do not distinguish between singly and multiply dimensioned arrays, so if you are
       passing a multiply dimensioned float array, you may need to typecast it as a (float *)  if
       this is not how it is declared in the main program.

COMPILING YOUR PROGRAM

       To  compile  your  NCAR  Graphics C program with the C-bindings, use the NCARG application
       ncargcc.  ncargcc will take care of loading in the necessary C/Fortran interface libraries
       as  well  as  the  NCAR Graphics C and Fortran libraries.  You will either need to set the
       NCARG_ROOT or the NCARG_BIN, NCARG_LIB, and NCARG_INCLUDE environment variables  in  order
       to run ncargcc.  See "man ncargintro" for more information.

       If  you do not wish to use ncargcc, then you can just run it with no arguments to see what
       the necessary libraries are, and then put this information in your  Makefile  or  whatever
       else  you  are  using  to  compile  and  link  your program.  Note:  if you have an ANSI C
       compiler, it is important that you define the macro NeedFuncProto on the compile  line  so
       that function prototyping is included.

EXAMPLES

       A few examples of C programs that call the NCAR Graphics C-bindings have been provided for
       your convenience.  You may be familiar with the output from these C programs as they  were
       modeled after the Fortran programs that you can get with the ncargex command.  To copy any
       one of these C programs in your directory, and then compile, link, and run it, type:

       ncargex xxxx

       where xxxx is the name of the example you wish to generate.  To see a list of  all  the  C
       examples, type:

     ncargex -C -list

ncargex uses ncargcc to compile and link the C-binding example programs.

OBSOLETE ROUTINES

       C-bindings  have  not  been  provided  for  user  entry  points  in the following obsolete
       utilities:

     Conran_family, Conrec_family, Halftone, Isosrfhr, and Pwrite_family.

COPYRIGHT

       Copyright (C) 1987-2002
       University Corporation for Atmospheric Research

       The use of this Software is governed by a License Agreement.