Pleinpot introduction Programmer's manual Users's manual Installation manual

PLEINPOT Programmer's manual

Pleinpot is an environment to program applications, for astronomical data analysis, data management and distribution (database access).

Programs may be written in C, Fortran, Python, PHP and Perl (the API for these three latter scripting languages are under development).

The present documentation address the following topics:

The first basic programme

Developping a program with Pleinpot consists in (i) writing a source file and (ii) compiling and linking (for C and Fortran programmes) and/or installing and executing it (for scripts).

In the lines below we are showing very elementary examples. More elaborated ones may be found in the package and are indicated in various places of the manuals.

The pre-requisite for developping a program are to have already installed Pleinpot and have a started a session. See the Installation manual.

Example in Fortran language

The basic outline of a Fortran programme should be:

       implicit none
       call debut(0)
       ...... insert your code here ......
       call fin
       stop
       end

Two Pleinpot functions are called in this template. debut (in French begin; this is one of the only reference to the national origin of the package) is making some initialisations, in particular for the user's interface. fin (end), symetrically ends the evironment (eg. save an error status and history).

Try now this real example:

       implicit none
       character*80 answer
       call debut(0)

       call valnots(answer)
       call askdefs('Give the answer to The Ultimate Question Of Life', answer)
       print *, 'The anwser to Live the Universe and Everything is:', answer

       call fin
       stop
       end

The few lines above may be pasted to a file, say pleinpot1.f. To compile and link it do:

            plmake pleinpot1

This will take the source, pleinpot1.f and create the executable, pleinpot1.

If you get plmake: command not found it is probably that the environment is not properly started. If you get other error message, check your source file.

To execute is, do:

            ./pleinpot1

And answer the prompt. Alternatively, you can pass the input argument on the command line, as:

            ./pleinpot1 42

This is a general feature of the Pleinpot users interface that input arguments of applications can be either passed from the command line or entered at the prompt. Arguments are recognized by their position on the command line. Default values, and mixing of command line and prompt inputs are possible,

In this programme, two new functions are used, valnots (for an initialization) and askdefs (to get a string from the user).

Note, that this Fortran example does not care of the 72 characters F77-standard limit on the statements. Pleinpot user a compiler option allowing at least lines of 132 characters.

Example in C language

The basic outline of a Fortran programme should be:

#include "pleinpot.h"   /* prototypes for Pleinpot routines */
int main (int narg, char **carg) {
  plc_debut (0, narg, carg);    
  /* ...... insert your code here ...... */
  plc_fin();
  return 0;
}

Where the same, debut and fin functions, as in the Fortran example are called.

Below is a real exemple, strictly equivalent to the Fortran example:

#include "pleinpot.h"   /* prototypes for Pleinpot routines */
int main (int narg, char **carg) {
  char answer[80];
  plc_debut (0, narg, carg);    

  plc_valnots(answer);
  plc_askdefs("Give the answer to The Ultimate Question Of Life", answer);
  printf("The anwser to Live the Universe and Everything is:%s\n", answer);

  plc_fin();
  return 0;
}

Save it as pleinpot2.c, and compile and link as:

            plmake pleinpot2

It takes the source file pleinpot2.c to build the executable pleinpot2.

Scripting languages

Interfaces for some popular scripting languages, Python, PHP and Perl are available for some functions of the library. They are described in plapis.

Some (astronomical) functions are also interfaced in SQL. See pleinpot_sql.

The Application program interfaces (APIs) & the Pleinpot Library

The real example in patutorial can be used as a tutorial to guide the first steps toward Fortran programming with Pleinpot. The source can be copied from $PL_ROOT/src/main/patutorial.f, and instruction to modify and compile it are in the documentation (and in the file).

The real example in ctutorial can be used as a tutorial to guide the first steps toward C programming with Pleinpot. The source can be copied from $PL_ROOT/src/main/ctutorial.c, and instruction to modify and compile it are in the documentation (and in the file).

pythonTutorial is a similar example for the Python language.

The Pleinpot Library

The Pleinpot Library is organized in a series of inter-dependent modules listed below (see also libpleinpot). Consult the specific documentation of these modules for more details.

High level modules
img Image access and processing
env Pleinpot environment functions
gra High level graphic functions
hyp Database interface
web Process HyperLeda Query Language requests
gen Pleinpot general functions
gro Graphic objects functions
gra High level graphic functions
ast Astronomical recipes
ehs Pleinpot error handling system
app Functions for data processing
dynmem Dynamical memory allocation from the Fortran routines
nedm Interface to NED client
pgc Astronomical sources name resolver
pip Image pipeline processing
fit Data fitting functions
func Some mathematical functions
str Utilities for character strings in Fortran
Low-level modules
fitsm Access to FITS files though cfitsio library
rdl Interface to the readline library
   
grl Low-level graphic functions
grd Graphic devices drivers
denis Low-level graphic functions
pegase Interface to Pegase 1

There is a large number of routines (about 1400) and it may be difficult at first to identify those that will be useful for a specific task. But (i) the modular organization should be a precious help, (ii) the naming of the routines follow a logic that can become familiar, (iii) some tutorials (examples of programs), introduced below, may be a starting point and (iv) an approach when writing a new application can be to start from an existing application (see pleinpot_applications).

Sources of the Pleinpot library are in: $PL_ROOT/src/subr.

Tutorials

General tutorials for Fortran and C programs are respectively: patutorial and ctutorial.

Other tutorials on specific topics exist.

Compile and link

To install locally a program use:

           plmake "program-name"

If the program uses other libraries than Pleinpot and its dependencies, those libraries may be declared when Pleinpot is configured (see the installation procedure). You may re-configure Pleinpot after its initial installation if you did not declare them, unless you change compilation options, it may not be nececssay to re-install completely the package.

If you need to write your own makefile to build your package, see the file $PL_ROOT/unix/pmakefile (internally used by the script plmake) to learn how to link a program with the pleinpot library. You can also use the application pleinpot_config to find the various compilation flags (pleinpot_config is similar to pkg_config present for many packages pkg; try pleinpot_config -help for more information).

Documentation

HTML documentation can be found at: http://leda.univ-lyon1.fr/pleinpot/pleinpot.html.

Documentation in man format is also available from the shell. For example,

           man libpleinpot
           man hipi

The documentation is maintened in the sources of the library and applications, its formatted extraction and maintenance software are installed on the subdirectory $PL_ROOT/doc.


Pleinpot documentation (Tue May 30 22:23:44 CEST 2017 )