gpp4  1.3.1
Defines | Typedefs | Functions
src/ccp4_fortran.h File Reference

Header file for Fortran APIs. More...

#include "ccp4_types.h"

Go to the source code of this file.

Defines

#define _LVTOB(l)   ((long) ((l) == 0 ? 0 : 1))
#define _BTOLV(l)   ((int) ((l) == 0 ? 0 : 1))
#define FTN_STR(s)   s
#define FTN_LEN(s)   s##_len
#define char_struct(s)
#define fill_char_struct(s, str)
#define init_char_struct(s, str, size)
#define FORTRAN_SUBR(NAME, name, p_sun, p_stardent, p_mvs)   void name##_ p_sun
#define FORTRAN_CALL(NAME, name, p_sun, p_stardent, p_mvs)   name##_ p_sun
#define FORTRAN_FUN(val, NAME, name, p_sun, p_stardent, p_mvs)   val name##_ p_sun

Typedefs

typedef pstr fpstr
typedef unsigned int ftn_logical

Functions

char * ccp4_FtoCString (fpstr str1, int str1_len)
void ccp4_CtoFString (fpstr str1, int str1_len, const char *cstring)

Detailed Description

Header file for Fortran APIs.

Author:
Eugene Krissinel

Define Documentation

#define char_struct (   s)
Value:
pstr  s;              \
    int   s##_len;
#define fill_char_struct (   s,
  str 
)
Value:
s  = str;                      \
    s##_len = strlen(str);
#define FORTRAN_CALL (   NAME,
  name,
  p_sun,
  p_stardent,
  p_mvs 
)    name##_ p_sun

Macro to call a Fortran subroutine from a C function.

Parameters:
NAMESubroutine name in upper case
nameSubroutine name in lower case
p_sunArgument list in Sun style
p_stardentArgument list in Stardent style
p_mvsArgument list in MVS style

Referenced by FORTRAN_SUBR().

#define FORTRAN_FUN (   val,
  NAME,
  name,
  p_sun,
  p_stardent,
  p_mvs 
)    val name##_ p_sun

Macro to define a function such that it is callable as a Fortran function.

Parameters:
valData type of return value.
NAMEFunction name in upper case
nameFunction name in lower case
p_sunArgument list in Sun style
p_stardentArgument list in Stardent style
p_mvsArgument list in MVS style
#define FORTRAN_SUBR (   NAME,
  name,
  p_sun,
  p_stardent,
  p_mvs 
)    void name##_ p_sun

Macro to define a function such that it is callable as a Fortran subroutine.

Parameters:
NAMESubroutine name in upper case
nameSubroutine name in lower case
p_sunArgument list in Sun style
p_stardentArgument list in Stardent style
p_mvsArgument list in MVS style
#define init_char_struct (   s,
  str,
  size 
)
Value:
s  = str;                      \
    s##_len = size;

Typedef Documentation

typedef pstr fpstr

Macro FORTRAN_SUBR(NAME,name,p_send,p_sstruct,p_sflw) makes function header statements that allow for linking with programs written in FORTRAN.

Parameters:
NAMEname of the FORTRAN subroutine in capital letters
namename of the FORTRAN subroutine in small letters
p_sendparameter list (in brackets) with string lengths attached to the end of it (see below)
p_sstructparameter list (in brackets) with strings passed as complex parameters, or structures
p_sflwparameter list (in brackets) with string lengths following immediately the string parameters (see below)

All non-string parameters must be passed as pointers, in the same order as they enter the FORTRAN call. Rules for the string parameters are as follows.

  1. All strings should be specified as of 'fpstr' type. The 'fpstr' type is defined below and depends on the platform:
    a)

    whenever length of string is passed as a separate parameter ( CALL_LIKE_SUN, CALL_LIKE_HPUX, CALL_LIKE_MVS ) 'fpstr' is identical to 'pstr'. You may choose arbitrary name for the string, but you MUST use the same name, appended with suffix '_len', for its length (see example below).

    b)
    whenever string and its length are passed as complex parameter, 'fpstr' is identical to the pointer on the corresponding structure:
                   CALL_LIKE_STARDENT :
                       'fpstr' is identical to 'PSStrPar'
                   CALL_LIKE_VMS      :
                       'fpstr' is identical to 'dsc$descriptor_s *'
    
    With 'fpstr' type, two important macro definition come:
    i) FTN_STR(s)
    returns pointer to fortran-passed string s. This pointer is always of 'pstr' type
    ii) FTN_LEN(s)
    returns integer length of fortran- passed string s. For this macro to work properly with SUN- and MVS-like machines, always use suffix '_len' for the string length parameters as described in a) above.
  2. Three parameter lists, each enclosed in brackets, should be given. These lists retain the general order of parameters in the corresponding fortran call. Non-string parameters are passed as pointers. String parameters and their lengths are passed differently in different lists:

    p_send
    strings enter their place in the list as in the corresponding FORTRAN call, having 'fpstr' parameter type. Their lengths are appended as 'int' to the end of the list. They should retain the order in which the strings appear in the list.
    p_sstruct
    strings enter their place in the list as in the corresponding FORTRAN call, having 'fpstr' parameter type.
    p_sflw
    strings enter their place in the list as in the corresponding FORTRAN call, having 'fpstr' type and being immediately followed by their lengths as 'int' parameters.

    Example:

    FORTRAN statement

           subroutine  SomeSub ( k,s1,a,s2,m )
           integer       k,m
           real          a
           character*(*) s1,s2
    

    is translated to

           FORTRAN_SUBR ( SOMESUB, somesub,
             ( int * k, fpstr s1, float * a, fpstr s2, int * m,
               int s1_len, int s2_len ),
             ( int * k, fpstr s1, float * a, fpstr s2, int * m ),
             ( int * k, fpstr s1, int s1_len, float * a,
               fpstr s2, int s2_len, int * m ) )
    

    The macro should replace ordinary function header statements to assure compatibility with FORTRAN links. In header files, do not forget to add semicolon:

         FORTRAN_SUBR ( .... );
    

    while in source files use simply

         FORTRAN_SUBR ( .... )  {
          <source body, operators>
         }
    

Macro FORTRAN_CALL(NAME,name,p_send,p_sstruct,p_sflw) calls function defined with macro FORTRAN_SUBR(...), from a C/C++ application. Its parameters and their meaning are exactly identical to those of FORTRAN_SUBR(...). FORTRAN_CALL(...) should be followed by semicolon.


Function Documentation

void ccp4_CtoFString ( fpstr  str1,
int  str1_len,
const char *  cstring 
)

Creates a Fortran string from an input C string for passing back to Fortran call. Characters after null-terminator may be junk, so pad with spaces. If input cstring is NULL, return blank string.

Parameters:
str1pointer Fortran to string
str1_lenFortran length of string
cstringinput C string

References float_uint_uchar::i.

Referenced by FORTRAN_SUBR().

char* ccp4_FtoCString ( fpstr  str1,
int  str1_len 
)

Creates a null-terminated C string from an input string obtained from a Fortran call. Trailing blanks are removed. If input string is blank then return string "\0". Memory assigned by malloc, so can be freed.

Parameters:
str1pointer to string
str1_lenFortran length of string

References ccp4_utils_flength(), and ccp4_utils_malloc().

Referenced by FORTRAN_SUBR().