home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / fortran / pgplot5.1 / pgplot5 / pgplot5.1.0 / doc / cpgplot.doc < prev    next >
Encoding:
Text File  |  1995-03-30  |  9.0 KB  |  215 lines
  1. CPGPLOT - An ANSI-C interface to the FORTRAN PGPLOT library.
  2. -----------------------------------------------------------
  3.  
  4. Background
  5. ----------
  6. Calling PGPLOT directly from C is a messy, difficult and unportable
  7. exercise. This is due to the lack of a universal set of inter-language
  8. calling conventions, and to the lack of a standard on how FORTRAN
  9. LOGICAL and CHARACTER types are represented in terms of basic machine
  10. types. Furthermore, since C implements call-by-value argument passing
  11. semantics, whereas FORTRAN uses pass-by-reference, there is the added
  12. complication that literal values must be sent indirectly by way of
  13. references to dummy variables.
  14.  
  15. The CPGPLOT library adds an intermediate level of wrapper functions
  16. between C programs and the PGPLOT library. These functions hide the
  17. system dependencies of calling PGPLOT behind a system independent
  18. interface.
  19.  
  20. USING THE LIBRARY
  21. -----------------
  22. The most important thing to remember when using the CPGPLOT interface
  23. library is to include the library header file, cpgplot.h at the top of
  24. all C files containing calls to the library. Without this file, the
  25. functions will not be correctly prototyped and your code will not
  26. work.
  27.  
  28. IMPORTANT CONVENTIONS:
  29.  
  30. 1. The names of the C interface library functions are the same as
  31.    their PGPLOT counterparts, but are prefixed with a 'c' and written
  32.    in lower case.
  33.  
  34. 2. The interface implements pass-by-value argument passing semantics.
  35.    This removes the need for dummy variables, except where arguments
  36.    are used to return values.
  37.  
  38. 3. Where PGPLOT expects LOGICAL arguments, the C interface requires
  39.    (int) arguments. Integral zero is interpreted as FORTRAN .FALSE.
  40.    and non-zero as FORTRAN .TRUE..
  41.  
  42.     FORTRAN call.       C equivalent call(s).
  43.     --------------      ----------------------------
  44.     PGASK(.FALSE.)      cpgask(0)
  45.     PGASK(.TRUE.)       cpgask(1) or cpgask(2) etc..
  46.  
  47. 4. Functions that take strings as input require normal C '\0'
  48.    terminated (char *) strings.
  49.  
  50. 5. Arguments that are used to return FORTRAN strings, must be treated
  51.    with care. FORTRAN doesn't understand '\0' termination of strings
  52.    and instead requires that the dimension of the character array be
  53.    specified along with the array. The interface handles this
  54.    transparently for input-only strings by using strlen() to determine
  55.    the length of the string, but for return string arguments it needs
  56.    to be told the length available in the passed char array.
  57.    Fortunately all PGPLOT routines that return such strings also have
  58.    an argument to return the unpadded length of the return string. In
  59.    CPGPLOT, you must initialize this argument with the dimension of
  60.    the string array that has been sent. In the prototypes listed in
  61.    cpgplot.h the length arguments are distinguishable by virtue of
  62.    their having the name of the string to which they relate, postfixed
  63.    with "_length". For example, the PGPLOT routine PGQINF() is
  64.    prototyped as:
  65.  
  66.      void cpgqinf(char *item, char *value, int *value_length);
  67.  
  68.    Where the 'value_length' argument is the length argument for the
  69.    string argument 'value'.
  70.  
  71.    For example, to write a C function to return 1 if a PGPLOT device
  72.    is open, or 0 otherwise, one could write.
  73.  
  74.      #include "cpgplot.h"
  75.      int pgplot_is_open(void)
  76.      {
  77.        char answer[10];                 /* The PGQINF return string */
  78.        int answer_len = sizeof(answer); /* allocated size of answer[] */
  79.        cpgqinf("STATE", answer, &answer_len);
  80.        return strcmp(answer, "YES") == 0;
  81.      }
  82.  
  83.    Note that the dimension, sent as the third argument, is the total
  84.    number of characters allocated to the answer[] array. The
  85.    interface function actually subtracts one from this when it tells
  86.    PGPLOT how long the string is. This leaves room for the interface
  87.    function to terminate the returned string with a '\0'. All returned
  88.    strings are terminated in this manner at the length returned by
  89.    PGPLOT in the length argument.
  90.  
  91. LIMITATIONS
  92. -----------
  93. Note that PGPLOT procedures that take FORTRAN SUBROUTINEs or FUNCTIONs
  94. as arguments are not represented in the CPGPLOT library. Such
  95. procedures can not be handled on most systems.
  96.  
  97. RESIDUAL MACHINE DEPENDENCIES
  98. -----------------------------
  99. Many system vendors say that if you call FORTRAN functions that do any
  100. I/O, you should have a FORTRAN main program, so that the FORTRAN I/O
  101. module gets correctly initialized. Since PGPLOT uses FORTRAN I/O, this
  102. applies to C programs that call PGPLOT.
  103.  
  104. Linking a C PGPLOT program.
  105. --------------------------
  106. Since FORTRAN usually has to be linked with a lot of support
  107. libraries, it is usually most convenient to use the FORTRAN compiler
  108. to link your C program. If your compiler is not the system-supplied
  109. compiler, then it is unlikely that the FORTRAN compiler will cite the
  110. correct C run-time library to the linker. This means that you will
  111. have to do it yourself. For instance under SunOS, I use gcc, because
  112. the the native C compiler is a pre-ANSI variant. Code generated by
  113. this compiler must be linked with libgcc.a. Where this library is
  114. located is system dependent, but is often placed in either
  115. /usr/local/lib or /usr/local/lib/gcc-lib/machine_type/gcc_version/.
  116.  
  117. In either case, under SunOS/Solaris, if both this path and the path of
  118. the installation directory of the pgplot libraries exist in your
  119. LD_LIBRARY_PATH environment variable, you can link your program with a
  120. statement like:
  121.  
  122.  f77 -o blob *.o -lcpgplot -lpgplot -lX11 -lgcc -lm
  123.  
  124. Other systems will have a different name for the LD_LIBRARY_PATH
  125. variable, but in general it would be set with something like:
  126.  
  127.  "/usr/local/pgplot:/usr/local/lib/gcc-lib/sparc-sun-solaris2.3/2.5.8/"
  128.  
  129. Under csh or tcsh, use the setenv command to set this:
  130.  
  131.   setenv LD_LIBRARY_PATH "..."
  132.  
  133. Under sh, bash, ksh:
  134.  
  135.   LD_LIBRARY_PATH="..."
  136.   export LD_LIBRARY_PATH
  137.  
  138. On systems that don't support such a variable, you will have to
  139. explicitly specify both the libraries and their paths. For example,
  140. under SunOS:
  141.  
  142.   f77 -o blob *.o -L/usr/local/pgplot -lcpgplot -lpgplot -lX11 \
  143. -L/usr/local/lib/gcc-lib/sparc-sun-solaris2.3/2.5.8/ -lgcc -lm
  144.  
  145. PORTING TO A NEW SYSTEM
  146. -----------------------
  147. Not all systems are supported by the interface library. This is both
  148. because we don't have many of the systems here that we would need to
  149. create and test any such configuration, and because not all systems
  150. can be supported.
  151.  
  152. The program that creates the library for each system is called pgbind
  153. (situated in the pgplot/cpg/ directory). To determine whether your
  154. system can be supported by this program, compile it with an ANSI-C
  155. compiler and run it with no arguments. It will list the available
  156. configuration options.
  157.  
  158. If the current version of pgbind does not provide sufficient options
  159. to support your system, send us details of how your FORTRAN compiler
  160. acts. We need to know:
  161.  
  162. 1. In what form does the FORTRAN compiler export FORTRAN symbol names
  163.    to the linker. Are the symbol names exported in lower-case, upper
  164.    case, or in the case that FORTRAN symbols are declared with, and
  165.    does it prefix or postfix any character or string to symbol names?
  166.  
  167. 2. If you EQUIVALENCE a FORTRAN LOGICAL variable with a FORTRAN
  168.    INTEGER variable, what are the values of the integer variable when
  169.    the logical variable is set first to .FALSE. and then to .TRUE.?
  170.  
  171. 3. How does your FORTRAN compiler pass strings?
  172.  
  173. UNIX CONFIGURATION
  174. ------------------
  175. If your system is a UNIX system, configured using the makemake script,
  176. and it is possible to support your system with one of the available
  177. templates, plus zero or more feature overrides, then list the option
  178. arguments as the string assigned to the optional PGBIND_FLAGS variable
  179. in your system configuration file, re-run the makemake script and type:
  180.  
  181.   make cpg
  182.  
  183. This should create the cpgplot.a library, its header file cpgplot.h
  184. and a demo program called cpgdemo. If the demo program runs, you are
  185. in business. Please tell us what PGBIND_FLAGS string you used so that
  186. we can incorporate it in the system configuration file for the next
  187. PGPLOT release.
  188.  
  189. NON-UNIX SYSTEMS
  190. ----------------
  191. If your system is not a UNIX system, then you will need to find a way
  192. to extract specific lines from the PGPLOT source code. Most of the pg*.f
  193. files in the src PGPLOT subdirectory contain one or more lines that
  194. start with C%. These are C prototypes, which should be extracted
  195. complete with the C% prefix and placed, one line after another in a
  196. single file. The result of processing this file with pgbind will be a
  197. set of C files - one per interface function - and the cpgplot.h
  198. library header. Compile the functions and place them in an
  199. appropriately named library.
  200.  
  201. PROBLEMS
  202. --------
  203. The cpgplot library has not been thoroughly tested, and the
  204. pgbind configurations of some systems have not been tested at all. If
  205. you have any problems, please send me a list of symptoms, and I will
  206. endeavor to solve them through modifications to the pgbind program.
  207.  
  208. HISTORY
  209. -------
  210. The pgbind program that creates the library header and interface
  211. functions was written by Martin Shepherd. This followed in the
  212. footsteps of an earlier program called cbind, written by Jim Morgan.
  213.  
  214. Martin Shepherd  (mcs@astro.caltech.edu)
  215.