NCARG_CBIND(3NCARG)

📦 version 6.6.2, in epel 9, fedora 43, fedora 44

💖 NCARG_CBIND — the C-binding tea 💖

okay bestie, welcome to NCARG_CBIND(3NCARG), from the NCAR GRAPHICS manual set. This is the page that explains how to use the NCAR Graphics C-binding, and ngl it's lowkey one of the most useful pages in the whole collection because it's literally the bridge between your cute C code and all those Fortran routines. Let's get into it 🦋

✨ NAME ✨

NCAR Graphics C-binding — the whole description of how to use the NCAR Graphics C-binding. that's it, that's the vibe.

🌸 SYNOPSIS 🌸

So the NCAR Graphics C-binding is literally a whole collection of C routines that let you call NCAR Graphics Fortran routines from a C program without you having to deal with the C-to-Fortran interface yourself. you get to skip all that cursed glue code, we love that for you 💅

If you want the detailed info about the C-binding for one specific routine, go read the man page for the corresponding Fortran routine. that's where the real details live.

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 (more on those later, bestie, don't worry). A GKS level 0A C-binding has also been created, and it adheres to the ISO/IEC standard. standards queen 👑

From here on out, when we say "a utility C-binding" we mean a C-binding for the NCAR Graphics utilities (AREAS, CONPACK, etc.). got it? good.

🎀 NAMING CONVENTION 🎀

okay so for all of the utility user entry points, the name of the C-binding function is the same as the Fortran routine name, just with a "c_" prepended. that's the whole rule, it's giving simple and iconic.

For example: the C-binding for the CONPACK routine CPBACK is c_cpback. see the pattern? CPBACK → c_cpback. slay.

⚠️ But bestie, this naming convention does NOT apply to the GKS C-bindings! Those get more descriptive names instead, like gset_fill_colr_ind, which is equivalent to the Fortran routine GSFACI.

Please see the man page for ncarg_gks_cbind(3NCARG) and the GKS Fortran routine to get the name of the corresponding GKS C-binding name.

C is case sensitive (as you know, and as it should be 😌), so for convenience the utility C-binding names and their arguments are all in lower case. And in this man page, the Fortran routines and their arguments get referred to in UPPER-CASE. so if you see all caps, that's Fortran energy. iykyk.

🧚 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. Those exceptions get described in separate sections (they're coming right up, bestie, stay with me).

Why does the C-binding argument list being similar to the Fortran one matter? because it makes life so much easier for people who already know the calling sequence of a particular Fortran routine. you already know it, you just write it in C now. periodt.

For example, the NCAR Graphics routine PLCHHQ has this 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)

see? same shape, different language. we love a consistent queen 🫶

🦋 ARRAYS 🦋

okay this is one of the exceptions to the utility C-binding argument lists, and it's about multi-dimensioned arrays. pay attention bestie, this one bites people.

In Fortran, arrays are stored in column-major order. In C, they're stored in row-major order. This means that the subscripts of a multi-dimensioned array need to be switched before you pass the array to a Fortran routine from C. no cap.

Let's do the 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. subscripts: swapped. 🔄

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. (same number, different meaning, stay woke 👀)
  • 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).

literally just switch the subscripts and you're golden ✨

💅 CHARACTER STRINGS 💅

Another exception to the argument lists for the utility C-bindings, and this one is about 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, and this is important: all input strings passed to the C-bindings must be null-terminated! every single one. don't forget the \0 bestie, i'm begging 😭

Example time. 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.

Rules for these extra length arguments, so you never have to guess:

  • 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. this is not a drill, bestie, copy that string 💀

🌈 FUNCTION PROTOTYPES 🌈

The C-bindings are intended to be ANSI C compliant. iconic behaviour honestly.

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. little typecast moment, nbd 💅

⭐ 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. it handles all the messy stuff so you don't have to. king behaviour 👑

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. do not skip this, i'm serious, the vibes will be off if you skip this.

🌸 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. cute little pipeline, we love to see it 💖

🙈 OBSOLETE ROUTINES 🙈

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

  • Conran_family
  • Conrec_family
  • Halftone
  • Isosrfhr
  • Pwrite_family

so if you were looking for those... yeah. no C-binding for you, sorry bestie 😭

👑 SEE ALSO 👑

Online: ncargcc(1NCARG), ncargex(1NCARG), ncarg_gks_cbind(3NCARG), ncargintro(5NCARG).

Hardcopy: NCAR Graphics Fundamentals, UNIX Version; User's Guide for NCAR GKS-0A Graphics

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

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

and that's the whole page, bestie!! this one came from NCAR, dated February 1993 (a vintage queen, honestly), and it lives in the manual as NCARG_CBIND(3NCARG). now go write some C that calls Fortran and feel powerful about it 🦋✨💖

📦 where this page comes from