SWMM5 swmm5.h Summary

 Below is a step‐by‐step explanation of swmm5.h, the public header file for SWMM 5.2:

1. Overall Purpose

   • swmm5.h exposes the C API for SWMM 5.2. This allows applications (C, C++, or other languages via a DLL) to call SWMM’s functions directly, without needing internal source code.
   • Defines enums describing the SWMM object types and properties, plus function prototypes such as swmm_run, swmm_open, swmm_step, etc.

2. Conditional Definitions

   // --- define WINDOWS
   #undef WINDOWS
   #ifdef _WIN32
     #define WINDOWS
   #endif
   #ifdef __WIN32__
     #define WINDOWS
   #endif
   

   • Checks if _WIN32 or __WIN32__ is defined. If so, we assume the Windows platform. This leads to #define WINDOWS.

   // --- define DLLEXPORT
   #ifdef WINDOWS
       #define DLLEXPORT __declspec(dllexport) __stdcall
   #else
       #define DLLEXPORT
   #endif
   

   • If on Windows, DLLEXPORT expands to __declspec(dllexport) __stdcall, meaning exported functions use the __stdcall calling convention.
   • Otherwise (non‐Windows), DLLEXPORT is empty.

   Why: This ensures the library can export the SWMM functions so that other programs can import them from a DLL (on Windows) or a shared object library on other platforms.

3. C Linkage for C++

   #ifdef __cplusplus
   extern "C" {
   #endif
   ...
   #ifdef __cplusplus 
   }   
   #endif
   

   • Wraps everything in extern "C" if compiled under C++.
   • This prevents C++ name‐mangling and ensures the function names remain purely C (e.g., _swmm_run@12 on Windows).

4. Enumerations

   The file defines a set of enums that represent different categories of objects or properties in SWMM:

   4.1 swmm_Object

   typedef enum {
       swmm_GAGE     = 0,
       swmm_SUBCATCH = 1,
       swmm_NODE     = 2,
       swmm_LINK     = 3,
       swmm_SYSTEM   = 100
   } swmm_Object;
   

   • Distinguishes a rain gage, subcatchment, node, link, or system.

   4.2 swmm_NodeType

   typedef enum {
       swmm_JUNCTION = 0,
       swmm_OUTFALL  = 1,
       swmm_STORAGE  = 2,
       swmm_DIVIDER  = 3
   } swmm_NodeType;
   

   • The type of a node object: junction, outfall, storage, or divider.

   4.3 swmm_LinkType

   typedef enum {
       swmm_CONDUIT = 0,
       swmm_PUMP    = 1,
       swmm_ORIFICE = 2,
       swmm_WEIR    = 3,
       swmm_OUTLET  = 4
   } swmm_LinkType;
   

   • The type of link object: conduit, pump, orifice, weir, or outlet.

   4.4 Additional Enums

   • swmm_GageProperty, swmm_SubcatchProperty, swmm_NodeProperty, swmm_LinkProperty:
     Each enumerates numeric IDs for various properties (like subcatch area, node invert, link slope, etc.) that can be accessed via the SWMM API (swmm_getValue, swmm_setValue).
   • swmm_SystemProperty enumerates system-level properties: e.g., swmm_STARTDATE, swmm_CURRENTDATE, swmm_FLOWUNITS, etc.
   • swmm_FlowUnitsProperty enumerates flow unit codes (CFS, GPM, MGD, etc.).

5. Function Prototypes

   These are declared as int DLLEXPORT functionName(...) or void DLLEXPORT functionName(...). The DLLEXPORT macro expands to either __declspec(dllexport) __stdcall on Windows or empty on other platforms, ensuring they are properly exported from a compiled shared library (DLL).

   5.1 High-Level Running Functions

   int DLLEXPORT swmm_run(const char *f1, const char *f2, const char *f3);
   int DLLEXPORT swmm_open(const char *f1, const char *f2, const char *f3);
   int DLLEXPORT swmm_start(int saveFlag);
   int DLLEXPORT swmm_step(double *elapsedTime);
   int DLLEXPORT swmm_stride(int strideStep, double *elapsedTime);
   int DLLEXPORT swmm_end(void);
   int DLLEXPORT swmm_report(void);
   int DLLEXPORT swmm_close(void);
   

   • swmm_run(f1, f2, f3): A convenience function that in turn calls swmm_open(...), runs the simulation, writes a report, and closes.
   • swmm_open(...): Opens SWMM input file (f1), sets up results (f3), and report (f2).
   • swmm_start(...) & swmm_end(...): For advanced stepping usage (e.g., calling swmm_step(...) in a loop).
   • swmm_step(double *elapsedTime): Advances the simulation by one hydrodynamic routing step, returning the time advanced in elapsedTime.
   • swmm_stride(...): Same idea, but might skip multiple steps.
   • swmm_report() writes out final simulation results.
   • swmm_close() closes any remaining open structures/memory.

   5.2 Retrieving Information and Errors

   int DLLEXPORT swmm_getMassBalErr(float *runoffErr, float *flowErr, float *qualErr);
   int DLLEXPORT swmm_getVersion(void);
   int DLLEXPORT swmm_getError(char *errMsg, int msgLen);
   int DLLEXPORT swmm_getWarnings(void);
   

   • swmm_getMassBalErr(...): obtains % error in runoff, flow routing, water quality mass balance, etc.
   • swmm_getVersion(): returns an integer code for SWMM version (e.g. 52000 = 5.2.0).
   • swmm_getError(...): if an error occurred, returns > 0 and places an error message in errMsg.
   • swmm_getWarnings(): how many warning messages were generated?

   5.3 Object / Property Access

   int    DLLEXPORT swmm_getCount(int objType);
   void   DLLEXPORT swmm_getName(int objType, int index, char *name, int size);
   int    DLLEXPORT swmm_getIndex(int objType, const char *name);
   double DLLEXPORT swmm_getValue(int property, int index);
   void   DLLEXPORT swmm_setValue(int property, int index,  double value);
   double DLLEXPORT swmm_getSavedValue(int property, int index, int period);
   void   DLLEXPORT swmm_writeLine(const char *line);
   void   DLLEXPORT swmm_decodeDate(double date, int *year, int *month, int *day,
                 int *hour, int *minute, int *second, int *dayOfWeek);
   

   • swmm_getCount(objType): returns how many gages, subcatchments, nodes, or links are in the model.
   • swmm_getName(objType, index, name, size): retrieves the object’s name string.
   • swmm_getIndex(objType, name): gets the integer index given an object name.
   • swmm_getValue(property, index): fetches a real‐time property (like node depth, link flow, etc.).
   • swmm_setValue(property, index, value): modifies a real‐time property.
   • swmm_getSavedValue(property, index, period): fetches property from a stored result at a specific time period.
   • swmm_writeLine(...): writes a line to the SWMM report or console.
   • swmm_decodeDate(...): decodes SWMM’s internal date/time format (a double) into year/month/day/etc.

---

6. Why This Header?

• This file is the main interface for external code to call SWMM 5.2.
• By including swmm5.h, one can link against swmm5.dll (on Windows) or libswmm5.so (on Linux) to run or interact with SWMM from an external application or script.
• The enumerations define the possible arguments to functions like swmm_getValue() or swmm_setValue(). For example, swmm_NODE_DEPTH is 303 to read or set a node’s depth.

---

7. Summary

swmm5.h is the crucial C API header for EPA SWMM:

1. Detects if building on Windows, sets up DLL export macros.
2. Enables external C/C++ (and other) code to call SWMM’s engine via swmm_run, swmm_step, etc.
3. Enumerations map symbolic property/object types (e.g., swmm_NODE_DEPTH, swmm_SUBCATCH_AREA, swmm_LINK_FLOW) to integer constants.
4. Function prototypes show how to open a SWMM run, step it, read results, and handle errors.

Hence, developers can embed SWMM into a larger program or create custom GUIs that manipulate or monitor a SWMM simulation in real time.