ERROR C ODE

errorCode is a standard TRNSYS error message number. Please refer to the initializeErrorMessages() subroutine in Messages.f90 for existing messages.

If you wish to generate a custom error message (as will most often be the case for user-written Types), simply set ErrorCode to a value of –1, indicating the messages that the second argument (message) contains the information to be printed.

MESSAGE

If you are generating a custom error message, this string variable will be printed in a standard format by the Messages subroutine. It should consist of one line of text, shorter than maxMessageLength. The example here below illustrates the use of Write to add run-time information to the message.

If you are using a standard error message, the string text will be printed in addition to the standard error message under the heading “Reported Information.” It is a method for providing additional information about the error.

SEVERITY

severity is a string that indicates the severity of the message. Messages understands 4 levels of severity:

• "Notice": A notice is simply information that you would like the user to know

• "Warning": The messages subroutine keeps track of how many "Warning" messages have been generated. If the maximum allowable number of warnings (set by the LIMITS statement in the input file) are exceeded, then the messages subroutine automatically generates a "Fatal" error.

• "Fatal": Designates a fatal error, i.e. an error that should stop the simulation. A call to Messages with such an error should be followed by a "return 1" statement in the calling Type. Note that TRNSYS will stop after going up the chain of "return" statements and giving

the chance to all subroutines to perform end-of-simulation operations. Further errors might be generated during that process.

• "Stop": The error will abort TRNSYS immediately without going up the chain of "return" statements, by generating an exception in the DLL and returning control to TRNExe.exe. This error type should only be used as a last resort, e.g. when returning from that error would result in memory access violations or other exceptions. Exiting from a DLL by generating an exception is generally considered as bad programming and users should only use this technique if the cost of modifying the Type to handle the error properly is too high.

Note: severity is a Fortran literal string and can be enclosed in single or double quotes. Messages will understand some case variants of the codes here above. e.g. notice, Notice and NOTICE are accepted (other variants are not)

EXAMPLE

The following example illustrates calls to Messages with different severity levels by a Type for which par(1)>10 is not acceptable (values <10.1 are just rounded to 10 and the simulation goes on).

subroutine type200(time,xin,out,t,dtdt,par,info,iCntrl,*) …

use TrnsysConstants …

character (len=maxMessageLength) :: myMessage

integer info(15) …

if ( par(1) < 10.0 ) then

write(myMessage,'("Par(1) = ",g," , which is OK")') par(1) call Messages(-1,trim(myMessage),'Notice',info(1),info(2))

else if ( par(1) <= 10.1) then

call Messages(-1,'Par(1) has been rounded to 10','Warning',info(1),info(2))

else

call Messages(-1,'Par(1) is outside the acceptable range.', & 'Fatal',info(1),info(2))

return 1

endif

…

Please note the use of RETURN 1 following the call to Messages with a severity of ‘Fatal.’ When the severity of the message is low (notice, message, or warning), the simulation should proceed; thus no RETURN statement is required. In the case of a ‘fatal’ message, however, the simulation should be immediately stopped and the Type should return control to the TRNSYS kernel through use of the RETURN 1 statement.

8.4.4.10. ParRead

This is an undocumented subroutine used internally by some standard Types. See the Source code in ParRead.f90 for additional information.

8.4.4.11. PSYCHROMETRICS (PSYCH)

This utility routine is available to calculate various moist air properties based on ASHRAE correlations and the Ideal Gas Law. A double precision version called PSYCHROMETRICS and a legacy single precision version called PSYCH are available. It is recommended that all user written routines employ the double precision version and that all non integer arguments to the Psychrometrics routine be declared as DOUBLE PRECISION variables in the calling Type. A call to Psychrometrics is of the form

DOUBLE PRECISION :: TIME,PSYDAT

INTEGER :: INFO(15),IUNITS,MODE,WBMODE,EMODE,STATUS ...

CALL PSYCHROMETRICS(TIME,INFO,IUNITS,MODE,WBMODE,PSYDAT,EMODE,STATUS) where

TIME (double precision) This is the standard TIME used in TRNSYS. It is used in the PSYCHROMETRICS subroutine only to identify the time at which warnings or errors occur.

INFO This is the standard integer INFO array used in TRNSYS (see Section 8.4.3). It is used in the PSYCHROMETRICS subroutine to identify the unit and type number of the component which calls the subroutine, which will be printed during a simulation if warnings or errors occur.

IUNITS an integer variable equal to 1 or 2 identifying the units desired for the properties. IUNITS = 1 results in properties in SI units. IUNITS = 2 results in properties in English units.

MODE an integer variable from 1 through 6. Three properties are needed to specify the moist air state. The MODE identifies which two properties besides pressure are need to be input, leaving the other properties to be calculated. The modes are as follows:

1: input dry bulb and wet bulb temperatures (PSYDAT(2) and PSYDAT(3))

2: input dry bulb temperature and relative humidity (PSYDAT(2) and PSYDAT(4))

3: input dry bulb and dew point temperatures (PSYDAT(2) and PSYDAT(5))

4: input dry bulb temperature and humidity ratio (PSYDAT(2) and PYSDAT(6))

5: input dry bulb temperature and enthalpy (PSYDAT(2) and PSYDAT(7))

6: input humidity ratio and enthalpy (PSYDAT(6) and PSYDAT(7)) . If saturation conditions occur, enthalpy is reset to saturation enthalpy at the given value of humidity ratio.

7: input humidity ratio and enthalpy (PSYDAT(6) and PSYDAT(7)) . If saturation conditions occur, humidity ratio is reset to saturation humidity ratio at the given

value of enthalpy. 8: input relative humidity and enthalpy (PSYDAT(6) and PSYDAT(4)).

WBMODE an integer variable equal to 0 or 1. If WBMODE = 0, the wet bulb temperature will not be calculated in MODEs 2 through 6. If WBMODE = 1, the wet bulb temperature is calculated. At PATM = 1.0 and temperatures common to HVAC applications, a correlation (1) is used to find the wet bulb temperature given enthalpy. For other pressures and temperatures, a Newton's iterative method is used with the equations given by ASHRAE (2) to calculate the wet bulb temperature. If the wet bulb temperature is not needed, WBMODE should be set to 0 to decrease the computational effort. If WBMODE = 0, the wet bulb temperature is set to the dry bulb temperature. PSYDAT an array containing the properties of the moist air. This array must be dimensioned to 9 in the routine that calls PSYCHROMETRICS. Each location in this array is described below:

PSYDAT(1) (double precision) The total system pressure in atmospheres. The subroutine prints a warning if PATM is over 5 atmospheres, which is considered here to be an upper limit for using ideal gas relations for air and water mixtures.

PSYDAT(2) (double precision) dry bulb temperature (°C). PSYDAT(3) (double precision) wet bulb temperature (°C). PSYDAT(4) (double precision) relative humidity (fraction). PSYDAT(5) (double precision) dew point temperature (°C). PSYDAT(6) (double precision) humidity ratio (kg water/kg dry air). PSYDAT(7) (double precision) enthalpy (kJ/kg dry air).

PSYDAT(8) (double precision) density of the air water mixture (kg/m3) PSYDAT(9) (double precision) density of the air portion of the mixture (kg dry

air/m3)

EMODE an integer variable equal to 0, 1, or 2 specifying how warnings are handled. If EMODE=0, no warnings will be printed. If EMODE=1, only one warning for each condition will be printed throughout the simulation. If EMODE=2, warnings will be printed every time step. (EMODE=2 is useful for program and simulation development, but it can produce an excessive amount of output). STATUS an integer variable equal to 0 through 13 identifying the warning

condition that occurred within subroutine PSYCH. 0 indicates no warnings. For a complete listing of warnings 1 through 13 the subroutine source code should be reviewed.

N the corresponding line number to jump to if the subprogram is present.