Advanced use - accessing weather conversion capabilities[LINK]

Interface to the EPlusWth.dll[LINK]

To provide information for outside developers/interfaces that might want to use the basic weather processing utility from within their interface, the EPlusWth.dll was developed. It is actually used by the weather converter utility. In addition to the basic interface calls, six important files are also used by this library. These are placed in the WeatherConverter folder during install of EnergyPlus.

Files used by EPlusWth.dll[LINK]

Each of the files is in a general comma-delimited format. Thus, they can be easily viewed by importing into a spreadsheet program such as Excel^TM. The files are used to support information lacking in the source data files and/or supply additional information used during the conversion process. In each case (with one exception), there will be a single or set of “header” records describing each column of the file and then the data values of the file will follow on subsequent records. Each of the files is described briefly in the next few sections.

Abbreviations.csv[LINK]

This file does not have a header record, but it consists of 3 columns. It is used for data files that might have 2-character abbreviations for US States or Canadian provinces and provides a translation to the full name and 3-character country code. Likewise, it can use the full name of these items to obtain the 2-character abbreviation or 3-character country code.

WBANLocations.csv[LINK]

In many older data sets, the station identifier for the weather data uses the WBAN (Weather Bureau Army-Navy) designation system. This has largely been superseded by the WMO (World Meteorological Organization) designation for station collection site identifiers. This file provides a translation between the two identifier systems. In addition, this file contains latitude, longitude, time zone and elevation information for the sites.

Cal Climate Zone Lat Long data.csv[LINK]

Note that this file has spaces in the name. The California c limate zone data source files do not have standard station identifiers. Rather they use a climate zone designator from 1-16. This file is used to obtain the latitude, longitude, time zone and elevation data for these climate zones. The WYEC2 “File Source Code” (field 2, column 6 of each data record) is used to determine that the file is a California compliance type file.

ASHRAE_2009_Yearly_DesignConditions.csv[LINK]

The three files for design conditions have roughly the same format. These are the values from the ASHRAE Handbook of Fundamentals, 2009, Chapter 14, Appendix. The WMO station identifier is used to determine the design condition values that apply to a source data file and, thus, are included in the DESIGN CONDITION header record on the EPW file produced as part of the conversion. This information is also included in the statistical report file (STAT) produced from the weather converter utility. In addition, these are used to supply the information for the design day object (DDY) file creation.

Public calls to EPlusWth.dll[LINK]

Several points of the library are made available for use with external programs. In each case the parameters passed will be described along with the Visual Basic^TM (VB6) code that is used to declare them as well as Fortran 90 style “Interface” statements to the same calls. The library is placed in the same folder with the weather converter utility - you may need to copy it to your program’s folder if you choose to add external calls from your program to it.

SetupPWInternalDataPath[LINK]

This call designates the “path” to the files listed above. This is the location where the ProcessWeather call will expect to find the files. Having this incorrectly specified is not fatal, but will probably cause confusion.

VB declaration statement:

Private Declare Sub SetupPWInternalDataPath Lib “EPlusWth” (ByVal strPath As String, ByVal InPathLen As Long)

And a call from a VB program:

Call SetupPWInternalDataPath(AppPath, Len(AppPath))

Likewise for Fortran 90/95:

  INTERFACE
              SUBROUTINE SetupPWInternalDataPath (Path)
              CHARACTER(len = \*), INTENT(IN) :: Path    ! Path where data files reside
              END SUBROUTINE
            END INTERFACE

And then calling it from Fortran:

Character(len = 255) DataPath
          CALL SetupPWInternalDataPath(trim(DataPath))

SetFixOutOfRangeData[LINK]

As shown earlier (file menu option in the weather converter utility), there is an option to “fix” out of range data or not. By default, this is turned off (does not fix data). Again a character convention (“yes” for fixing; “no” for not fixing) is used. Case of the actual string is ignored.

VB Declaration statement:

Private Declare Sub SetFixOutOfRangeData Lib “EPlusWth” (ByVal strValue As String, ByVal strValueLen As Long)

And calling it from VB:

Global FixOutOfRangeData As String
FixOutOfRangeData = "Yes"
Call SetFixOutOfRangeData(FixOutOfRangeData, Len(FixOutOfRangeData))

For Fortran 90/95:

  INTERFACE
              SUBROUTINE SetFixOutOfRangeData (YesNo)
              CHARACTER(len = \*),INTENT(IN) :: YesNo    ! 'yes' to set fixing option;
                                                      ! 'no' to not
              END SUBROUTINE
            END INTERFACE

And then calling it:

CALL SetFixOutOfRangeData('no')

SetDefaultChgLimit[LINK]

This call sets the value for the DB trigger shown earlier. Both values passed in are strings and are specific to the dialog shown earlier:

You can also choose to ignore the calculated trigger entirely. If you do not “ignore” the calculated trigger, then the trigger is the minimum of the calculated and your trigger limit selection.

VB Declaration Statement:

Private Declare Sub SetDefaultChgLimit Lib "EPlusWth" (ByVal strValue As String, ByVal strValueLen As Long, ByVal strValue As String, ByVal strValueLen As Long)

And a call from VB:

Call SetDefaultChgLimit(TriggerLimit, Len(TriggerLimit), IgnoreCalcTrigger, Len(IgnoreCalcTrigger))

ProcessWeather[LINK]

The “meat” of the processing is done by this routine. It gets passed the input file name (source data), the input file type, output file name, and output file type. As an output it can provide a notice that the processing was successful or not.

VB Declaration Statement:

Private Declare Sub ProcessWeather Lib "EPlusWth" (ByVal strInType As String, ByVal InTypeLen As Long, ByVal strOutType As String, ByVal OutTypeLen As Long, ByVal strInFileName As String, ByVal InFileNameLen As Long, ByVal strOutFileName As String, ByVal OutFileNameLen As Long, ErrorFlag As Boolean, Optional ByVal strOutFileURL As String, Optional ByVal OutFileURLlen As Long)

Calling it from VB:

Call ProcessWeather(InputFileDataType, Len(InputFileDataType),
      OutputFileDataType, Len(OutputFileDataType),
      InputFileName, Len(InputFileName),
      OutputFileName, Len(OutputFileName),
      ErrorFlag)

Valid values for the Input File Data Type are shown in the following table:

Valid values for the Output File Type(s) are shown in the following table:

For Input and Output file names, the complete paths should be included.

ErrorFlag will be returned as “true” if an error occurs during processing or “false” if the process is successful.

Fortran 90/95 Declaration:

INTERFACE
            SUBROUTINE ProcessWeather(InType,OutType,InFileName,OutFileName,ErrFlag)
              CHARACTER(len = \*), INTENT(IN) :: InType       ! InputFile Type
              CHARACTER(len = \*), INTENT(IN) :: OutType      ! OutputFile Type
              CHARACTER(len = \*), INTENT(IN) :: InFileName   ! InputFile Name (Full path)
              CHARACTER(len = \*), INTENT(IN) :: OutFileName  ! OutputFileName (Full path)
              LOGICAL(Byte2), INTENT(OUT)  :: ErrFlag      ! If errors are found,
                                                           ! set to true and put
                                                           ! description put in file.
            END SUBROUTINE
          END INTERFACE

And calling it from Fortran:

call processweather(trim(intype),trim(outtype),    &
                              trim(infilename),trim(outfilename),errflag)

Note that the file where error messages will be placed is the RPT file. If the value of the output file path is incorrect, you may need to search for this file by using the RPT extension.