THE TRNSYS DLL AND EXECUTABLE

A2.1-1

APPENDIX II CHANGING THE TRNSYS FORTRAN DYNAMIC LINK LIBRARY AND USING TRNSYS OUTSIDE THE WINDOWS ENVIRONMENT

Note: For information about using specific Fortran compiler software with TRNSYS, refer to the fact sheet titled Using Common Fortran Compilers with TRNSYS included with the TRNSYS package. Technology changes rapidly making it impossible to have a TRNSYS model of every thermal energy system component. Thus users may change or add to the TRNSYS program at their discretion. Users wishing to modify the TRNSYS Fortran source code for a component or add a new component must have a 32-bit Fortran compiler. The compiler converts ASCII (text) Fortran code (.FOR) to object (machine-readable) code (.OBJ). The creation of a new TRNSYS program is handled differently in TRNSYS 14.2 for Windows than in previous versions. In previous versions, the TRNSYS code was compiled and linked to form a stand-alone TRNSYS.EXE. With version 14.2 for Windows, TRNSYS32.EXE is a stand-alone Windows program that controls all Windows interactions, including the display of online plots, and calls a Windows Dynamic Link Library (DLL) called TRNLIB32.DLL containing all the compiled, linked TRNSYS subroutines. The calculations that occur in TRNSYS are handled in the Fortran DLL (TRNLIB32.DLL). TRNSYS32.EXE AND TRNLIB32.DLL are for use with the 32-bit operating systems (i.e. Windows 95 and NT 4.0). Any Fortran compiler capable of creating a 32bit DLL should work with TRNSYS32.EXE. The copy of TRNLIB32.DLL that is shipped with a new TRNSYS package contains all of the standard TRNSYS component subroutines described in the main TRNSYS reference manual. Simulations that require modification of the existing types or the use of user-written components will require creating a new TRNLIB32.DLL file. Linking the compiled Kernal, Option, Utility, Type, and Dummy subroutines creates the DLL file. A linking program (included with Fortran compiler software) takes the pieces of object code and linksthem together to form the DLL. TRNSYS makes use of a collection of Fortran subroutines subdivided into five categories: Kernel - Required subroutines to run the TRNSYS simulation program. Each of these routines should be compiled and linked to the TRNSYS DLL regardless of application. The Kernel routines process and order the information contained in the simulation input file and manage the simulation: checking convergence, calling component routines, and the like. The following files are designated as Kernel routines: TRNSYS.FOR PRINT.FOR TYPECK.FOR LINKCK.FOR STATE.FOR READIN.FOR DIFFEQ.FOR RCHECK.FOR CLOCK.FOR PROC.FOR SOLVER.FOR STRNUM.FOR MYSTOP.FOR TRNOUT.FOR EXEC.FOR SYSTEM.FOR

A2.1-2

THE TRNSYS DLL AND EXECUTABLE

INDVAR.FOR

NEWEQN.FOR

EVAL.FOR

ONLINE.FOR

Types - The actual component subroutines in TRNSYS. If a user specifies a TYPE in the input file, the corresponding Fortran TYPE subroutine must be linked into the DLL. The TYPE1.FOR source code describes the operation of the TRNSYS TYPE 1 solar collector and must be linked into the DLL if TYPE 1 is used in the input file. Some of the TYPE subroutines require linking in Utility subroutines (described below). All TYPE subroutines follow the naming convention TYPEn.FOR, where n is an integer ranging from 1 to 300. The output producing routines in TRNSYS (TYPE 24 through TYPE 29 and TYPE 65) do not exist as TYPES in TRNSYS, rather they exist as Option routines (described below). Therefore, TYPEs 24 through 29 and TYPE 65 should not be specified in the link file as TYPES. Rather they should be specified given their Option name. TYPE 15 must be linked if TYPE 28 is to be used. Option - Called by certain component routines. These must be linked if certain component routines are called. The following files are designated as OPTION subroutines with their associated component routines listed here for reference: PLOTER.FOR TRACE.FOR ECON.FOR HPLOT.FOR MAP.FOR SUMARY.FOR (TYPE 26) ( TRACECommand in input file ) (TYPE 29) (TYPE 27) ( MAPCommand in input file) (TYPE 24,28)

Utility - Called by many of the component (Type) routines. These must be linked in the TRNSYS DLL if certain Type routines are specified in the TRNSYS input file. The following files should be located in the Utility subdirectory. They are listed with the associated component routines that call these utility routines. DATA.FOR DFIT.FOR DINVRT.FOR ENCL.FOR FIT.FOR INVERT.FOR PSYCH.FOR SOLCEL.FOR TABLE.FOR TALF.FOR VIEW.FOR STEAM.FOR FLUIDS.FOR (TYPES 1, 19, and 20) (TYPES 51 and 53) (DFIT.FOR) (TYPE 19) (TYPES 19, 37, 56, and FIT.FOR) (TYPES 33, 51, and 52) (TYPES 49 and 50) (TYPE 19) (TYPES 1, 35, 36, 37, 45, and 56) (TYPES 1, 19, and 20) (TYPE 58) (TYPE 58)

THE TRNSYS DLL AND EXECUTABLE

A2.1-3

Dummy - Required by most Fortran compilers which do not support unresolved externals (Fortran subroutines called by another routine but not linked in the DLL). The kernal TRNSYS code contains calls to 300 subroutines named SUBROUTINE TYPEn, although only those TYPE subroutines used in a given TRNSYS input file are actually called during execution. The Dummy routines, with file names in the format DUMn.FOR (where n ranges from 1 to 300), are of the form: SUBROUTINE TYPEn (TIME,XIN,OUT,T,DTDT,PAR,INFO,ICNTRL,*) DIMENSION INFO(15) CALL TYPECK(8,INFO,0,0,0) RETURN 1 END The Dummy subroutines are present so that when the compiler does not find a certain SUBROUTINE TYPEn during the linking of TRNLIB32.DLL, the error unresolved external is avoided by the presence of DUMn. For example, if TYPE 219 is not used in the TRNSYS input file and does not exist, the copy of SUBROUTINE TYPE219 contained in DUM219.FOR will satisfy the Fortran compiler. SUBROUTINE TYPE219 will not be called during the simulation. Creating A New TRNSYS Dynamic Link Library To add a new or modified component subroutine to TRNLIB32.DLL, follow the steps listed below. The steps are provided for a generic Fortran compiler. 1. Run the SET.BAT file (in the \TRNWIN\KERNAL directory) before compiling and linking for the first time. This batch file will create the proper include files (.INC) for your particular compiler. 2. Compile all of the TRNSYS source code (.FOR). This includes all subroutines in the KERNAL, OPTION, UTILITY, TYPES, and DUMMY subdirectories along with any userwritten components in other locations. This procedure may be completed from the command line (DOS prompt) or from within the development environment of the Fortran compiler used. Components may also be compiled from the TRNSHELL program, provided certain settings are made correctly for the specific compiler. In all cases, the compile command should include all necessary compiler options. See the reference manual for your Fortran compiler for specific information. Compiling the subroutines produces object code (.OBJ). If the Fortran compiler produces errors during compilation, these must be addressed before moving on to the next step of linking. 3. Link the compiled object code (.OBJ) from the KERNAL, OPTION, UTILITY, and TYPES subdirectories, that from user-written subroutines, and the appropriate dummy library file (.LIB) located in the DUMMY subdirectory into a DLL called TRNLIB32.DLL. See Using Common Fortran Compilers with TRNSYS for the name of the dummy library file to link for your compiler. Linking components from the command line (DOS prompt) requires execution

A2.1-4

THE TRNSYS DLL AND EXECUTABLE

of the link command with a link file as its argument. The list file lists all of the object code (.OBJ) to be linked into TRNLIB32.DLL. Standard TRNSYS link files for some common compilers are included in the \TRNWIN directory. The order of the routines listed in the link file may be important. The file TRNSYS.OBJ should be linked first, followed by the object code for the remaining KERNAL routines, the required OPTION and UTILITY routines, and the desired TYPES routines and DUMMY library. The format of the link file will depend on the Fortran compiler used. Be sure to enter the entire path to the component object code in the link file. Refer to your Fortran compiler manual for more details. Linking only those component subroutines required for the simulation will reduce the file size of TRNLIB32.DLL and may improve simulation speed. Modern Fortran compilers generally offer powerful development environments which can compile and link components very easily. In this case, command line statements are not required. See Using Common Fortran Compilers with TRNSYS for details. 4. The next time a change is made to any subroutine used in the TRNSYS input file or a new component is used which is not contained in TRNLIB32.DLL, repeat steps 2 and 3 above.

A Note on DUMMY Subroutine Libraries In Windows 95 and NT 4.0, the object code (.OBJ) for the 300 dummy subroutines is linked into TRNLIB32.DLL in the form of a static library (.LIB). The 300 DUMn.OBJ files are linked into one static library which is subsequently linked into TRNLIB32.DLL along with the object code for the rest of the required TRNSYS subroutines. Static libraries of DUMMY object code for several common compilers are included with TRNSYS in the DUMMY subdirectory. See Using Common Fortran Compilers with TRNSYS for details. See the documentation for your Fortran compiler for information on creating static libraries of compiled code.

Using TRNSYS Outside the Windows Environment It is possible to create a non-Windows (DOS or UNIX) executable program using the TRNSYS Fortran source code. The file TRNSYS.FOR shipped with the TRNSYS package is written to be part of a DLL and not an executable program. However, another copy of the main TRNSYS routine (TRNSYS.DOS) has been included that is designed to be used to create an executable program. To use this other routine, copy \TRNWIN\ KERNAL\TRNSYS.DOS to \TRNWIN\ KERNAL\TRNSYS.FOR and \TRNWIN\ KERNAL\CLOCK.DOS to \TRNWIN\ KERNAL\CLOCK.FOR.

THE TRNSYS DLL AND EXECUTABLE

A2.1-5

To switch back to Windows DLL mode, copy \TRNWIN\ KERNAL\TRNSYS.WIN to \TRNWIN\ KERNAL\TRNSYS.FOR and \TRNWIN\ KERNAL\CLOCK.WIN to \TRNWIN\ KERNAL\CLOCK.FOR. These operations can be completed automatically by use of the batch file SET.BAT described above.