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

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:

	NAME	name of the FORTRAN subroutine in capital letters
	name	name of the FORTRAN subroutine in small letters
	p_send	parameter list (in brackets) with string lengths attached to the end of it (see below)
	p_sstruct	parameter list (in brackets) with strings passed as complex parameters, or structures
	p_sflw	parameter 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.

---

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:

	NAME	Subroutine name in upper case
	name	Subroutine name in lower case
	p_sun	Argument list in Sun style
	p_stardent	Argument list in Stardent style
	p_mvs	Argument list in MVS style

#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:

	val	Data type of return value.
	NAME	Function name in upper case
	name	Function name in lower case
	p_sun	Argument list in Sun style
	p_stardent	Argument list in Stardent style
	p_mvs	Argument 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:

	NAME	Subroutine name in upper case
	name	Subroutine name in lower case
	p_sun	Argument list in Sun style
	p_stardent	Argument list in Stardent style
	p_mvs	Argument list in MVS style

#define init_char_struct	(	s,
		str,
		size		)

Value:

s  = str;                      \
    s##_len = size;