LCPP Porting Guidelines

Issues common to FORTRAN and C/C++

• Calls to isavax()/ISAVAX() - isavax was created and used during the conversion from PDP-11 to VAX. Code called it to determine if it was executing on a VAX or a PDP-11. In the case of Linux on a PC, we are neither so we have to pick the best match, which is VAX. Therefore, when you see a call to isavax(), assume it is always TRUE and remove both the isavax() call and the code that becomes dead, i.e., PDP-11, code under this assumption. Do not use isavax() to distingish VAX from PC, instead use conditional compiliation with #ifdef VMS.
  • Example of isavax() removal.
  • Example of conditional compilation with #ifdef VMS.
• Undefined reference to lxcopy/LXCOPY. Just remove the call to lxcopy, this routine formerly defined in dwin/clib/core/lxshr.cpp did not do or return anything.
• ctime, ftime, and time on VMS returned the local time, but on Linux they return time in UTC/GMT. Therefore, results of ctime/ftime may need to be converted to local time to preserve the calling codes original logic. One case where they would not need to be converted is if the input to ctime came from a call to time. In this case time's use of UTC compensates for ctime's use of UTC. On VMS both routines used local time. If you need a replacement for VMS's time() you can use the new routine clib_local_secs_now(). It is only available on Linux.
• MTH_QUAD_EDIV, MTH_QUAD_SUB, MTH_QUAD_MUL, and MTH_QUAD_DIV - change int[2] types involved to (unsigned) long long and replace function calls with appropriate operator (+,-,*,/). Note that EDIV divides an 8-byte integer by a 4-byte integer and returns a 4-byte integer while DIV takes two 8-byte integers and returns a 8-byte integer. All this is according to http://mvb.saic.com/freeware/vax86d/fermilab/fermilib/fermilib.hlp.

• The vax MTH$ fuctions MTH$ABS & MTH$EXP can be replaced with one of the
  functions below (choose the correct one for the data type).
  
  double fabs(double x);
  float fabsf(float x);
  long double fabsl(long double x);
  
  double exp(double x);
  float expf(float x);
  long double expl(long double x);
  
  All the above require #include <math.h>
  
  
  For intgers, there are also:
  
  int abs(int j);
  long int labs(long int j);
  long long int llabs(long long int j);
  
  these last three require #include <stdlib.h> rather than math.h
  
  FORTRAN should still be able to call these as a replacement but the usage
  will of course be different.
  

C/C++ Issues

• Type mismatches

longs vs. ints

Replace long with int. Formating in printfs, etc. will need corrected as well, e.g., %ld becomes %d.

doubles vs. floats

The VAX/VMS system uses a floating point format(DEC) that is apparently little-endian. The PC/Linux system uses a floating point format(IEEE) that is apparently big-endian. Net result is that under VAX/VMS one could be sloppy about double vs. float type matching, but not so under PC/Linux. Therefore, if the compiler complains about a double vs. float type mismatch you will need to think more carefully about the code than just blindly adding a cast.

function pointers

Often this is the result of an explicit incorrect cast. Therefore, for named functions remove the explicit cast and see if the problem persists. If the function pointer is a NULL, then replace the explicit incorrect cast with an explicit correct cast to the typedef used in the clib defintion and prototype. If the argument is not a typedef, please add a typedef for it.

• Example code change for an incorrectly casted NULL.
• Example code change for an incorrectly casted named function. See the changes around line 160.

If a named function still has a mismatch after removal of the explicit cast, then things are more complicated. Carl Schumann would like to be made aware of such cases. In some cases such a mismatch is because the function is a callback which does not use all the arguments that could be provided to it, e.g., a void * pointer to data used by the callback. In such cases the function can correct the type mismatch by declaring the extra argument but without giving it a name, thus indicating to the compiler that the function will not actually use that argument to suppress any unused argument warnings.

unsigned vs. signed

• Frequently this is the result of sizeof() returning a size_t, which is unsigned. Therefore, cast the sizeof() result.
• Frequently this is the result of strlen(). Therefore, cast the strlen() result.
• Frequently this is the result of a special #define value, e.g.,WMNGR_AUTO_SIZE , that have their sign bit set to distingish them from normal, i.e., postive, values. Therefore, cast the macro when required.

incorrect prototypes

Sometimes an incorrect prototype is the culprit. If the function is prototyped within the cpp file itself, remove that prototype and instead pick up a hopefully correct prototype from a standard header file, e.g., clib.h. If there are still issues despite getting the prototype from a standard header file, then refer to the clib help and see if the prototype in the header matches the documentation. If there is an inconsistency please report it to Carl Schumann, the porting project may have broken the header file prototype.

anonymous structure type mismatch

Sometimes the type mismatch may involve an unnamed, i.e., anonymous, struct. In this case a name will need to be given to the anonymous struct. Give the struct a meaningful name if possible, else name it after the variable of its type, e.g., foo_struct if the/a variable of that struct is named foo.

const vs. non-const

The VMS C-compiler appears to have essentially ignored the keyword const, as a result there is a lot of incorrect usage of const. Rather than fixing up all the const usages, a decision has been made to just remove const where it appears and is causing trouble. As a result you may need to (char *) cast literal strings. This appears to be the case only when a literal string is assigned to void *, as assignments to char * do not generate an error.

• Unused stuff

unused variables

Remove it.

unused static functions

If the function is being kept as a debugging aid for the future, then use the unused attribute to prevent the warning.

    int unused_function () __attribute__ ((unused));
    

Otherwise, remove it and its prototype if it has one at the beginning of the source file.

static, i.e., internal-linkage, storage defined in include file

In the include file change storage definition to a mere declaration. Put the definition in a *.cpp file.

static function prototype without a definition

Remove the prototype.

• Uninitialized stuff

uninitialized variables of integer types, i.e., char, short, int, or long

Initialize the variable at its definition to UNINITIALIZED_INT. UNINITIALIZED_INT is a #define in cnsparam.h, which is included by all/almost all source files. If cnsparam.h is not being included please add it. (This symbolic constant allows one to quickly get past the compiler warning while leaving a enough information for a more experienced developer to take a look at the situation later.)

• Example code change for an uninitialized integer variable. See changes at about line 3600.

uninitialized variables of real types, i.e., float or double

Initialize the variable at its definition to UNINITIALIZED_FLOAT. UNINITIALIZED_FLOAT is a #define in cnsparam.h, which is included by all/almost all source files. If cnsparam.h is not being included please add it.

uninitialized variables of pointer types

Initialize the variable at its definition to UNINITIALIZED_POINTER. UNINITIALIZED_POINTER is a #define in cnsparam.h, which is included by all/almost all source files. If cnsparam.h is not being included please add it.

function returning something other than void that terminates without a return
Return one of the appropriate UNINITIALIZED #define values.
• VMS vs. g++ feature mismatches

VMS's delete()

Replace VMS's delete() with stdio's remove(). You may need to add a #include for stdio.h.

syntax errors in stdlib.h, or other standard header files, caused by clib_malloc, etc. #defines

memory_macro.h #defines malloc, etc. to be replaced by clib_malloc, which provides some useful mechanisms for tracking down things like freeing memory twice. The difficulty is when memory_macro.h is included before other header files, e.g., stdlib.h, that contain a reference to malloc and expect not to have it replaced by the clib_malloc macro. Therefore, instances of memory_macro.h that are causing problems should be moved after all other include files, so that it only munges the body of the particular source file that includes it.

• An example of such a change.

struct and C++ class packing and alignment

The VMS compiler does not add padding to put members on their natural alignment, but g++ does by default add such padding. Since a lot of structures are populated by binary data coming directly out of file-sharing, DB columns, or the DB SQL API, this padding can not in many cases be allowed. Such structures need to have a packed attribute added.

• An example of such a change.

Rich Neswold and Charlie King have written a tool, called the a Packinator(TM), that adds the packed attribute to all structs and C++ classes. The Packinator is run by the script that imports code into Linux/CVS from VMS. We do not yet have tools that allow the average user to import code themselves, so running the import script is for experts.

Bit fields

VMS's C compiler apparently did not add extra bits to bit fields to round the fields out to a 8,16,32, etc. bits. g++ does and needs to be reworked if the bit fields are being populated by some source outside the control of g++, e.g., filesharing data.

Case-sensitivity in filenames

There was/is already some real C++ on the VMS side, e.g., ul_tca. Continuing this example, ul_tca defined C++ classes and as is the convention used mixed case in the classname, e.g., PointerField. Such a class was declared and defined in POINTERFIELD.HXX and POINTERFIELD.CPP. Including code would then include the file as PointerField.hxx. On VMS PointerField.hxx matches POINTERFIELD.HXX and all is well. On Linux they don't match. In such cases let Carl Schumann or Denise Finstrom know and we will rename the header inside the repository. The include directive should remain unchanged.

#include's of VMS's text libraries

Replace things like

#include stdio

with

#include <stdio.h>

#include with a VMS logical name specifing a user library in the filename

This should only happen for programs within mecca, as clib should not depend on user libraries.

• Remove the logical name and the trailing colon from the include filename. An example of such a change. (See the changes at line 44.)
• Add the user library to the depends.opt file for the mecca program. An example of such a change.

VMS stdio's support %02.2x format specifiers

Replace %02.2x with %02x.

• An example of such a change.

optional arguments

Both Linux's and VMS's compilers support the va_list mechanism, but VMS's allows the callee to get a count of the number of arguments. Linux needs other information to determine the arguments available on the stack, e.g., a printf format string. As a result VMS optional arguments are being converted to C++ defaulted arguments for the port. This requires that the include file prototyping the callee and the callee defintion be changed. The C/++ callers require now code change for this issue.

• Change the prototype to specify the default values. An example of such a change. This covers a lot of functions with optional arguments.
• Change the defintion appropriately. In some case the argument count will change the function behavior, in such tricker cases seek help if you need it. An example of the definition changes required for dio_event_controls(_c).

unspecified array dimension in a struct.

VAXC and g++ both allow one to terminate a struct with an array of unspecified length. However, something on the VAX did not support this, either VAX C++ or DECC, so conditional compilation was put around such array member. Where you find such an unspecified array dimension, remove the conditional check leaving just the body of the conditional. This is needed because while include files did the conditional compilation some source files just assumed a VAXC compiler and did not check the VAXC #define. An example of such a change.

• Bugs in the original code, which should be pretty rare.

calling FORTRAN style entry points from C incorrectly instead of calling the C style version correctly.

For many clib entry points there is a FORTRAN-style version, e.g., numeric_to_ascii, that expects all arguments to be passed by reference, and a C-style version, e.g., numeric_to_ascii_c, that expects some arguments to be passed by value. C-code should in general be calling the C-style version, and it should certainly not be calling the FORTRAN-style routine incorrectly. An example (See changes at about line 428) of converting an incorrect call to a FORTRAN-style entry point to a correct call toa C-style entry point. In the orginal incorrect code, notice that a literal 1 is being passed were a int * is expected. The fix in this case was to simply append the _c to the call; the required cast was specific to numeric_to_ascii(_c).

• Name conflicts

c++ keywords, e.g., new, delete, this, xor, used as indentifier

Prefix offending identifiers with "my_". In the case of this if you can determine the name of the of the "class", say for example foo, use this_foo.

X11 structures with member named class

The X11 include and source files are conditionaly compiled to handle C++ by renaming such members to c_class, so just replace class with c_class.

• Example of class to c_class change. See changes at about line 912.

static function has name conflict with an extern function

Prefix offending static function identifer with "my_".

• g++ bug(s)

intialization of a static struct defined within a function body

There is an example of code that reveals the bug and the change to work around the bug. If this issue shows up again please let me know.

• C++ rigor/strictness

calls without a prototype

C++ requires to have seen a prototype/declaration prior to a function being called. Where possible and an include directive of an include file that already contains the prototype. If no existing include file prototypes the function add the prototype to an existing file, ask for help if you are not sure what include file would be appropriate.

• Undefined references in the link

errno_location

In this case the code probably has an explict "extern int errno;". This extern needs removed and errno.h included instead to correctly prototype errno, which is now a macro that gets replaced by a function call to errno_location().

other cases

Make sure the source code is not prototyping any functions itself but is instead including the proper header files for prototypes.

C++ name-mangling

C++ compilers do something called name-mangling to support defining functions with the same name but different arguments, which is called overloading. If you define a function in a *.cpp file that is called by FORTRAN, the *.cpp file or some header file included by it will need to prototype the function with extern "C" directive, e.g., extern "C" foo(int,int);

C/C++ FORTRAN Interoperability Issues

• FORTRAN commons being accessed by C/C++. You will need to prototype the common in the C/C++ code as lowercase with no underscores or other pre/suffix.
• string descriptors vs. null terminated strings (mecca/uls/ul_clib/descrip.h)

C routines called only by C

In this case rip out the vestigial string descriptor usage and replace it with a char*. If the string argument has an implied length, e.g., if it is an ACNET taskname, or if the called funtion has an explicit length argument for the string, then replacement of the string descriptor by a potentialy non-null terminated char* is all that is needed. If there is no such implicit or explicitly specified length then the callers will need to insure null termination and the callee will need to determine the length based on null termination not from the length member of the string descriptor.

FORTRAN routines called only by FORTRAN

This should not require any code changes, since it is intra-language and the VMS LEN() function maps cleanly to ifort's LEN() function for determining a string's length.

C routines called by both C and FORTRAN

In this case rip out the string descriptor usage and replace it with a char*. If the string argument has an implied length, e.g., if it is an ACNET taskname, or if the called funtion has an explicit length argument for the string, then replacement of the string descriptor by a potentialy non-null terminated char* is all that is needed. If there is no such implicit or explicitly specified length then the callers will need to insure null termination and the callee will need to determine the length based on null termination not from the length member of the string descriptor. The FORTRAN compiler will provide null-termination for literal strings. Any %ref's should be removed, these are not handled correctly by the intel FORTRAN compiler if indexing is used.

FORTRAN routines called by both C and FORTRAN

All such FORTRAN routines should already be adapted to be called from C and changes should not be needed. Evidence to the contrary will always be considered.

FORTRAN Issues

• unused variable warnings for includers of clib.inc. The compiler configuration has been changed to prevent this.
• rad50, which was built-in under VMS, needs an explicit prototype under Linux. rad50 is INTEGER*4 and prototyped in clib.inc.
• pause() is now a system call on Linux. Therefore, calls to pause() should now be replaced with calls to clib_pause(), the same function only with the name changed.
• FTPPLT needs replaced with calls to FSTPLT. FTPPLT takes some of its "arguments" from a common block named PLTLOC, which is initialized with default values for these "arguments". So there are two cases - one where the caller does not make assignments into PLTLOC and the second where the caller does. The first case is the easiest, in this case FTPPLT(1,foo1,foo2) needs replaced with FSTPLT(1,2,9,0) and FTPPLT(,foo1,foo2) needs replaced with FTPPLT(,foo1,foo2,0). If the first argument is a variable or the caller messes with PLTLOC, you will need to do some thinking and more than just a simple replacement. The code for FTPPLT() should help you make the correct modifications.
• Some people call "_c" functions from fortran, using %VAL() for auguments which need to be passed by value - %VAL supported by ifort so not an issue
• FORTRAN calls expecting optional arguments to be supplied by callee. Just append "," to call for each optional argument not supplied by the caller. ifort will pass a NULL for each such "," and the callee will be expected to check for a NULL and supply an appropriate default. This null checking behavior should already be the case for clib entry points.
• FORTRAN include files not found. This can be because of case-senstivity and/or the /NOLIST qualifier. Therefore remove the /nolist and lowercase the filename. In addition *.ftn include files have been renamed to *.for, so in that case change the extension as well.
• For uninitialized variables include cnsparam.inc, if the source does not already do so. Then initialize uninitialized variables with the appropriate UNINITIALIZED_<type> #define, where <type> is INT for INTEGER*4, SHORT for INTEGER*2, FLOAT for REAL*4, and DOUBLE for REAL*8.
• For function that is supposed to return a value but that terminates without a return, return the appropriate UNINITIALIZED #define values.
• FORTRAN calling an entry point that had optional arguments but are now C++ default arguments. The C++ compiler silently supplies the default arguments so C/C++ code can still call such entry points as they always have. FORTRAN, does not however do this, so the additional arguments must be added manualy in the caller's source code. To do this append as many additional arguments as required. The additional arguments should all be %VAL(0). %VAL(0) is required by the Intel FORTRAN compiler, which may be our compiler of choice.
  • Example of adding default arguments.
• FORTRAN has deprecated DATE() and TIME() because of Y2K issues. Therefore replace calls to these functions with clib calls for acquiring the date and time.
  • Example replacing DATE() and TIME() calls with single clib call.
• RAD 50 encoding in a literal needs replaced with a call to a rad50 conversion function.
  • An example of such a change.

ACL Script Issues

• VMS specific stuff in ftp, call_proc, system, and maybe other commands.