1. APPENDIX a WRITING SUBROUTINES IN C

2. WHAT IS IN THIS APPENDIX?
Overview
General rules for success
Compiling and linking

3. OVERVIEW
Adams/Solver subroutines may also be written in the C programming language
As of Adams 2005r2 a new interface is available for those wishing to program in C
Note: the following material assumes familiarity with the traditional FORTRAN user-written subroutine interface for Adams

4. OVERVIEW (CONT.)
The C version of this user interface is a work in progress. MSC reserves the right to make necessary, minor adjustments to this interface in Adams releases in the immediate future. Please recognize that this may require that your C user subroutines be adjusted and re-complied to work with future versions of Adams.
The Adams C user subroutine interface is modeled after the FORTRAN user subroutine interface, and Adams users with familiarity with the FORTRAN interface and proficiency in the C programming language will quickly adapt to the C interface if the following differences are observed.

5. GENERAL RULES FOR SUCCESS
The C program file should include the header file slv_c_utils.h, which can be found in the solver/c_usersubs directory of the Adams installation.
This header file defines the type of all the Adams user subroutines and declares all the functions in the Adams utility subroutine interface
Users are encouraged to use this file as a resource, to find the correct argument lists for user subroutines and utility subroutines
Including this header file unleashes one of the most important attributes of ANSI C – strong type checking. Errors in argument lists will be clearly identified when the program is compiled.
There is no need to explicitly specify to Adams whether the user subroutine has been written in the C or FORTRAN programming language. Adams discovers this automatically when the subroutine is loaded from the user’s Adams/Solver library file as long as the user has followed one simple rule: (see next slide)

6. GENERAL RULES FOR SUCCESS (CONT.)
User subroutines are assumed to be written in C if the name of the user subroutine contains at least one uppercase character
Hence, ‘Sfosub’ or ‘SFOSUB’ will be reliably recognized as a C user subroutine whereas ‘sfosub’ may, on certain computer platforms, be mistaken for a FORTRAN subroutine
If Adams calls a C user subroutine thinking it is a FORTRAN subroutine, a failure will occur
This rule applies regardless of whether the name is specified with the ROUTINE= argument or default user subroutine name is used
Note carefully that since FORTRAN source code is not case sensitive, the ROUTINE= string can be considered to not be case sensitive when specifying FORTRAN user subroutine names. However, when ROUTINE= is used to specify a C user subroutine, the correct case must be specified in ROUTINE=.

7. GENERAL RULES FOR SUCCESS (CONT.)
Whereas FORTRAN passes all arguments by reference, the C user subroutine interface conforms carefully to an argument passing style which will be more natural to a C programmer:
Scalar input variables are passed by value
Array input variables are passed as const pointers
Output variables are passed as pointers
This is illustrated by the following Varsub declaration:
void Varsub(const struct sAdamsVariable* variable, double time, int dflag, int iflag, double* value)
Where
time, dflag, and iflag are examples of (a)
value is an example of (c)

8. GENERAL RULES FOR SUCCESS (CONT.)
Among the contents of the slv_c_utils.h header files are type definitions for all the subroutines in the interface. Users are strongly encouraged to declare their user subroutines to be of the appropriate type.
For example, a Varsub written in C, before it is defined should be declared as
adams_c_Varsub Varsub
This will allow the complier to check for type errors in the argument list and many frustrating errors can be avoided.
Adams implements a C flavor of its utility subroutine interface. This is distinguished form its FORTRAN counterpart by a “c_” prefix on the subroutine name, example c_sysfnc, which gives access to the same functionality as the FORTRAN subroutine SYSFNC.

9. GENERAL RULES FOR SUCCESS (CONT.)
Like the C user subroutines, the C utility subroutines introduce a natural C style argument passing convention:
Scalar input variables are passed by value
Array input variables are passed on const pointers
Output variables are passed as pointers
For example:
void c_sysfnc(const char *fncanam, const int *ipar, int nsize, double *states, int *errflag)
Row order vs. column order matrix storage
There is only one area where it has not been possible to implement C style programming conventions. This is in the handling of the matrix return values of the FIESUB user subroutine for the FIELD element.
The matrices of partial derivatives which are populated by the user and returned from the FIESUB must be ordered according to FORTRAN column order. In other words, the second entry in the array of partials should be the second entry in the first column, also know as the partial derivative of the Y component of the force, w.r.t. the X translation.

10. GENERAL RULES FOR SUCCESS (CONT.)
Row-order vs. column-order matrix storage (cont.)
It is recommended that users avoid the use of doubly dimensioned C arrays (A [] [] ) and manually index into a singly dimensioned array according to the FORTRAN dictated storage order.