/**
    * The contents of this file are subject to the Mozilla Public License Version 1.1
    * (the "License"); you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at http://www.mozilla.org/MPL/
    * Software distributed under the License is distributed on an "AS IS" basis,
    * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the
    * specific language governing rights and limitations under the License.
    *
    * The Original Code is "CommmonTM.java".  Description:
   * "Note: The class description below has been excerpted from the Hl7 2.4 documentation"
   *
   * The Initial Developer of the Original Code is University Health Network. Copyright (C)
   * 2001.  All Rights Reserved.
   *
   * Contributor(s): ______________________________________.
   *
   * Alternatively, the contents of this file may be used under the terms of the
   * GNU General Public License (the "GPL"), in which case the provisions of the GPL are
   * applicable instead of those above.  If you wish to allow use of your version of this
   * file only under the terms of the GPL and not to allow others to use your version
   * of this file under the MPL, indicate your decision by deleting  the provisions above
   * and replace  them with the notice and other provisions required by the GPL License.
   * If you do not delete the provisions above, a recipient may use your version of
   * this file under either the MPL or the GPL.
   *
   */
  
  package ca.uhn.hl7v2.model.primitive;
  
  import java.util.Calendar;
  import java.util.Date;
  import java.util.GregorianCalendar;
  import java.util.TimeZone;
  import java.io.Serializable;
  
  import ca.uhn.hl7v2.model.DataTypeException;
  import ca.uhn.hl7v2.model.DataTypeUtil;
  
  /**
   * This class contains functionality used by the TM class
   * in the version 2.3.0, 2.3.1, and 2.4 packages
   *
   * Note: The class description below has been excerpted from the Hl7 2.4 documentation. Sectional
   * references made below also refer to the same documentation.
   *
   * Format: HH[MM[SS[.S[S[S[S]]]]]][+/-ZZZZ]
   * In prior versions of HL7, this data type was always specified to be in the
   * format HHMM[SS[.SSSS]][+/-ZZZZ] using a 24 hour clock notation. In the
   * current and future versions, the precision of a time may be expressed by
   * limiting the number of digits used with the format specification as shown
   * above. By site-specific agreement, HHMM[SS[.SSSS]][+/-ZZZZ] may be used where
   * backward compatibility must be maintained.
   * Thus, HH is used to specify a precision of "hour," HHMM is used to specify a
   * precision of "minute," HHMMSS is used to specify a precision of seconds, and
   * HHMMSS.SSSS is used to specify a precision of ten-thousandths of a second.
   * In each of these cases, the time zone is an optional component. The fractional
   * seconds could be sent by a transmitter who requires greater precision than whole
   * seconds. Fractional representations of minutes, hours or other higher-order units
   * of time are not permitted.
   * Note: The time zone [+/-ZZZZ], when used, is restricted to legally-defined time zones
   * and is represented in HHMM format.
   * The time zone of the sender may be sent optionally as an offset from the coordinated
   * universal time (previously known as Greenwich Mean Time). Where the time zone
   * is not present in a particular TM field but is included as part of the date/time
   * field in the MSH segment, the MSH value will be used as the default time zone.
   * Otherwise, the time is understood to refer to the local time of the sender.
   * Midnight is represented as 0000.
   * Examples:|235959+1100| 1 second before midnight in a time zone eleven hours
   * ahead of Universal Coordinated Time (i.e., east of Greenwich).
   * |0800| Eight AM, local time of the sender.
   * |093544.2312| 44.2312 seconds after Nine thirty-five AM, local time of sender.
   * |13| 1pm (with a precision of hours), local time of sender.
   * @author Neal Acharya
   */
  
  @SuppressWarnings("serial")
  public class CommonTM implements Serializable {
      
  	/**
       * Value returned by {@link #getGMTOffset()} if no offset is set
       */
      public static final int GMT_OFFSET_NOT_SET_VALUE = -99;
  
      private String value;
      private int hour;
      private int minute;
      private int second;
      private float fractionOfSec;
      private int offSet;
      private boolean omitOffsetFg = false;
  
      /**
       * Constructs a TM datatype with fields initialzed to zero and the value set to
       * null.
       */
      public CommonTM() {
          //initialize all DT fields
          value = null;
          hour = 0;
         minute = 0;
         second = 0;
         fractionOfSec = 0;
         offSet = GMT_OFFSET_NOT_SET_VALUE;
     } //end constructor
 
     /**
      * Constructs a TM object with the given value.
      * The stored value will be in the following
      * format HH[MM[SS[.S[S[S[S]]]]]][+/-ZZZZ].
      */
     public CommonTM(String val) throws DataTypeException {
         this.setValue(val);
     } //end constructor
 
     /**
      * This method takes in a string HL7 Time value and performs validations
      * then sets the value field.  The stored value will be in the following
      * format HH[MM[SS[.S[S[S[S]]]]]][+/-ZZZZ].
      * Note: Trailing zeros supplied in the time value (HH[MM[SS[.S[S[S[S]]]]]])
      * and GMT offset ([+/-ZZZZ]) will be preserved.
      * Note: If the GMT offset is not supplied then the local
      * time zone (using standard time zone format which is not modified for daylight savings)
      * will be stored as a default. Passing in <code>null</code> clears any existing value.
      */
     public void setValue(String val) throws DataTypeException {
 
         if (val != null && !val.equals("") && !val.equals("\"\"")) {
             //check to see if any of the following characters exist: "." or "+/-"
             //this will help us determine the acceptable lengths
 
             int d = val.indexOf(".");
             int sp = val.indexOf("+");
             int sm = val.indexOf("-");
             int indexOfSign = -1;
             boolean offsetExists = false;
             if ((sp != -1) || (sm != -1))
                 offsetExists = true;
             if (sp != -1)
                 indexOfSign = sp;
             if (sm != -1)
                 indexOfSign = sm;
 
             try {
                 //If the GMT offset exists then extract it from the input string and store it
                 //in another variable called tempOffset. Also, store the time value
                 //(without the offset)in a separate variable called timeVal.
                 //If there is no GMT offset then simply set timeVal to val.
                 String timeVal = val;
                 String tempOffset = null;
                 if (offsetExists) {
                     timeVal = val.substring(0, indexOfSign);
                     tempOffset = val.substring(indexOfSign);
                 } //end if
 
                 if (offsetExists && (tempOffset.length() != 5)) {
                     //The length of the GMT offset must be 5 characters (including the sign)
                     String msg =
                         "The length of the TM datatype value does not conform to an allowable"
                             + " format. Format should conform to HH[MM[SS[.S[S[S[S]]]]]][+/-ZZZZ]";
                     throw new DataTypeException(msg);
                 } //end if
 
                 if (d != -1) {
                     //here we know that decimal exists
                     //thus length of the time value can be between 8 and 11 characters
                     if ((timeVal.length() < 8) || (timeVal.length() > 11)) {
                         String msg =
                             "The length of the TM datatype value does not conform to an allowable"
                                 + " format. Format should conform to HH[MM[SS[.S[S[S[S]]]]]][+/-ZZZZ]";
                         throw new DataTypeException(msg);
                     } //end if
                 } //end if
 
                 if (d == -1) {
                     //here we know that the decimal does not exist
                     //thus length of the time value can be 2 or 4 or 6 characters
                     if ((timeVal.length() != 2) && (timeVal.length() != 4) && (timeVal.length() != 6)) {
                         String msg =
                             "The length of the TM datatype value does not conform to an allowable"
                                 + " format. Format should conform to HH[MM[SS[.S[S[S[S]]]]]][+/-ZZZZ]";
                         throw new DataTypeException(msg);
                     } //end if
                 } //end if
 
                 //We will now try to validate the timeVal portion of the TM datatype value
                 if (timeVal.length() >= 2) {
                     //extract the hour data from the input value.  If the first 2 characters
                     //are not numeric then a number format exception will be generated
                     int hrInt = Integer.parseInt(timeVal.substring(0, 2));
                     //check to see if the hour value is valid
                     if ((hrInt < 0) || (hrInt > 23)) {
                         String msg = "The hour value of the TM datatype must be >=0 and <=23";
                         throw new DataTypeException(msg);
                     } //end if
                     hour = hrInt;
                 } //end if
 
                 if (timeVal.length() >= 4) {
                     //extract the minute data from the input value
                     //If these characters are not numeric then a number
                     //format exception will be generated
                     int minInt = Integer.parseInt(timeVal.substring(2, 4));
                     //check to see if the minute value is valid
                     if ((minInt < 0) || (minInt > 59)) {
                         String msg = "The minute value of the TM datatype must be >=0 and <=59";
                         throw new DataTypeException(msg);
                     } //end if
                     minute = minInt;
                 } //end if
 
                 if (timeVal.length() >= 6) {
                     //extract the seconds data from the input value
                     //If these characters are not numeric then a number
                     //format exception will be generated
                     int secInt = Integer.parseInt(timeVal.substring(4, 6));
                     //check to see if the seconds value is valid
                     if ((secInt < 0) || (secInt > 59)) {
                         String msg = "The seconds value of the TM datatype must be >=0 and <=59";
                         throw new DataTypeException(msg);
                     } //end if
                     second = secInt;
                 } //end if
 
                 if (timeVal.length() >= 8) {
                     //extract the fractional second value from the input value
                     //If these characters are not numeric then a number
                     //format exception will be generated
                     float fract = Float.parseFloat(timeVal.substring(6));
                     //check to see if the fractional second value is valid
                     if ((fract < 0) || (fract >= 1)) {
                         String msg = "The fractional second value of the TM datatype must be >= 0 and < 1";
                         throw new DataTypeException(msg);
                     } //end if
                     fractionOfSec = fract;
                 } //end if
 
                 //We will now try to validate the tempOffset portion of the TM datatype value
                 if (offsetExists) {
                     //in case the offset are a series of zeros we should not omit displaying
                     //it in the return value from the getValue() method
                     omitOffsetFg = false;
                     //remove the sign from the temp offset
                     String tempOffsetNoS = tempOffset.substring(1);
                     //extract the hour data from the offset value.  If the first 2 characters
                     //are not numeric then a number format exception will be generated
                     int offsetInt = Integer.parseInt(tempOffsetNoS.substring(0, 2));
                     //check to see if the hour value is valid
                     if ((offsetInt < 0) || (offsetInt > 23)) {
                         String msg = "The GMT offset hour value of the TM datatype must be >=0 and <=23";
                         throw new DataTypeException(msg);
                     } //end if
                     //extract the minute data from the offset value.  If these characters
                     //are not numeric then a number format exception will be generated
                     offsetInt = Integer.parseInt(tempOffsetNoS.substring(2, 4));
                     //check to see if the minute value is valid
                     if ((offsetInt < 0) || (offsetInt > 59)) {
                         String msg = "The GMT offset minute value of the TM datatype must be >=0 and <=59";
                         throw new DataTypeException(msg);
                     } //end if
                     //validation done, update the offSet field
                     offSet = Integer.parseInt(tempOffsetNoS);
                     //add the sign back to the offset if it is negative
                     if (sm != -1) {
                         offSet = -1 * offSet;
                     } //end if
                 } //end if
 
                 //If the GMT offset has not been supplied then set the offset to the
                 //local timezone
                 //[Bryan: changing this to omit time zone because erroneous if parser in different zone than sender]
                 if (!offsetExists) {
                     omitOffsetFg = true;
                     // set the offSet field to the current time and local time zone
                     //offSet = DataTypeUtil.getLocalGMTOffset();
                 } //end if
 
                 //validations are now done store the time value into the private value field
                 value = timeVal;
             } //end try
 
             catch (DataTypeException e) {
                 throw e;
             } //end catch
 
             catch (Exception e) {
                 throw new DataTypeException(e);
             } //end catch
         } //end if
         else {
             //set the private value field to null or empty space.
             value = val;
         } //end else
     } //end method
 
     /**
      * This method takes in an integer value for the hour and performs validations,
      * it then sets the value field formatted as an HL7 time
      * value with hour precision (HH).
      */
     public void setHourPrecision(int hr) throws DataTypeException {
         try {
             //validate input value
             if ((hr < 0) || (hr > 23)) {
                 String msg = "The hour value of the TM datatype must be >=0 and <=23";
                 throw new DataTypeException(msg);
             } //end if
             hour = hr;
             minute = 0;
             second = 0;
             fractionOfSec = 0;
             offSet = 0;
             //Here the offset is not defined, we should omit showing it in the
             //return value from the getValue() method
             omitOffsetFg = true;
             value = DataTypeUtil.preAppendZeroes(hr, 2);
         } //end try
 
         catch (DataTypeException e) {
             throw e;
         } //end catch
 
         catch (Exception e) {
             throw new DataTypeException(e.getMessage());
         } //end catch
 
     } //end method
 
     /**
      * This method takes in integer values for the hour and minute and performs validations,
      * it then sets the value field formatted as an HL7 time value
      * with hour&minute precision (HHMM).
      */
     public void setHourMinutePrecision(int hr, int min) throws DataTypeException {
         try {
             this.setHourPrecision(hr);
             //validate input minute value
             if ((min < 0) || (min > 59)) {
                 String msg = "The minute value of the TM datatype must be >=0 and <=59";
                 throw new DataTypeException(msg);
             } //end if
             minute = min;
             second = 0;
             fractionOfSec = 0;
             offSet = 0;
             //Here the offset is not defined, we should omit showing it in the
             //return value from the getValue() method
             omitOffsetFg = true;
             value = value + DataTypeUtil.preAppendZeroes(min, 2);
         } //end try
 
         catch (DataTypeException e) {
             throw e;
         } //end catch
 
         catch (Exception e) {
             throw new DataTypeException(e.getMessage());
         } //end catch
     } //end method
 
     /**
      * This method takes in integer values for the hour, minute, seconds, and fractional seconds
      * (going to the tenthousandths precision).
      * The method performs validations and then sets the value field formatted as an
      * HL7 time value with a precision that starts from the hour and goes down to the tenthousandths
      * of a second (HHMMSS.SSSS).
      * Note: all of the precisions from tenths down to tenthousandths of a
      * second are optional. If the precision goes below tenthousandths of a second then the second
      * value will be rounded to the nearest tenthousandths of a second.
      */
     public void setHourMinSecondPrecision(int hr, int min, float sec) throws DataTypeException {
         try {
             this.setHourMinutePrecision(hr, min);
             //multiply the seconds input value by 10000 and round the result
             //then divide the number by tenthousand and store it back.
             //This will round the fractional seconds to the nearest tenthousandths
             int secMultRound = Math.round(10000F * sec);
             sec = secMultRound / 10000F;
             //Now store the second and fractional component
             second = (int) Math.floor(sec);
 			//validate input seconds value
 			if ((second < 0) || (second >= 60)) {
 				String msg = "The (rounded) second value of the TM datatype must be >=0 and <60";
                 throw new DataTypeException(msg);
 			} //end if
             int fractionOfSecInt = secMultRound - (second * 10000);
             fractionOfSec = fractionOfSecInt / 10000F;
             String fractString = "";
             //Now convert the fractionOfSec field to a string without the leading zero
             if (fractionOfSec != 0.0F) {
                 fractString = (Float.toString(fractionOfSec)).substring(1);
             } //end if
             //Now update the value field
             offSet = 0;
             //Here the offset is not defined, we should omit showing it in the
             //return value from the getValue() method
             omitOffsetFg = true;
             value = value + DataTypeUtil.preAppendZeroes(second, 2) + fractString;
         } //end try
 
         catch (DataTypeException e) {
             throw e;
         } //end catch
 
         catch (Exception e) {
             throw new DataTypeException(e);
         } //end catch
     } //end method
 
     /**
      * This method takes in the four digit (signed) GMT offset and sets the offset
      * field
      */
     public void setOffset(int signedOffset) throws DataTypeException {
         try {
             //When this function is called an offset is being created/updated
             //we should not omit displaying it in the return value from
             //the getValue() method
             omitOffsetFg = false;
             String offsetStr = Integer.toString(signedOffset);
             if ((signedOffset >= 0 && offsetStr.length() > 4) || (signedOffset < 0 && offsetStr.length() > 5)) {
                 //The length of the GMT offset must be no greater than 5 characters (including the sign)
                 String msg =
                     "The length of the GMT offset for the TM datatype value does"
                         + " not conform to the allowable format [+/-ZZZZ]. Value: " + signedOffset;
                 throw new DataTypeException(msg);
             } //end if
             //obtain the absolute value of the input
             int absOffset = Math.abs(signedOffset);
             //extract the hour data from the offset value.
             //first preappend zeros so we have a 4 char offset value (without sign)
             offsetStr = DataTypeUtil.preAppendZeroes(absOffset, 4);
             int hrOffsetInt = Integer.parseInt(offsetStr.substring(0, 2));
             //check to see if the hour value is valid
             if ((hrOffsetInt < 0) || (hrOffsetInt > 23)) {
                 String msg = "The GMT offset hour value of the TM datatype must be >=0 and <=23";
                 throw new DataTypeException(msg);
             } //end if
             //extract the minute data from the offset value.
             int minOffsetInt = Integer.parseInt(offsetStr.substring(2, 4));
             //check to see if the minute value is valid
             if ((minOffsetInt < 0) || (minOffsetInt > 59)) {
                 String msg = "The GMT offset minute value of the TM datatype must be >=0 and <=59";
                 throw new DataTypeException(msg);
             } //end if
             //The input value is valid, now store it in the offset field
             offSet = signedOffset;
         } //end try
 
         catch (DataTypeException e) {
             throw e;
         } //end catch
 
         catch (Exception e) {
             throw new DataTypeException(e);
         } //end catch
     } //end method
 
     /**
      * Returns the HL7 TM string value.
      */
     public String getValue() {
         //combine the value field with the offSet field and return it
         String returnVal = null;
         if (value != null && !value.equals("")) {
             if (!omitOffsetFg && !value.equals("\"\"")) {
                 int absOffset = Math.abs(offSet);
                 String sign;
                 if (offSet >= 0) {
                     sign = "+";
                 } //end if
                 else {
                     sign = "-";
                 } //end else
                 returnVal = value + sign + DataTypeUtil.preAppendZeroes(absOffset, 4);
             }
             else {
                 returnVal = value;
             } //end else
         } //end if
         return returnVal;
     } //end method
 
     /**
      * Convenience setter which sets the value using a {@link Calendar} object. Passing in <code>null</code> clears any existing value.
      * 
      * Note: Sets fields using precision up to the minute
      * 
      * @param theCalendar The calendar object from which to retrieve values 
      * @since 1.1 
      */
     public void setValueToMinute(Calendar theCalendar) throws DataTypeException {
 		if (theCalendar == null) {
 			setValue((String)null);
 			return;
 		}
 
         int hr = theCalendar.get(Calendar.HOUR_OF_DAY);
         int min = theCalendar.get(Calendar.MINUTE);
         setHourMinutePrecision(hr, min);
     }
 
     /**
      * Convenience setter which sets the value using a {@link Date} object. Passing in <code>null</code> clears any existing value.
      * 
      * Note: Sets fields using precision up to the minute
      * Note: Date is timezone-agnostic, representing always GMT time
      * 
      * @param theDate The date object from which to retrieve values
      * @since 1.1 
      */
     public void setValueToMinute(Date theDate) throws DataTypeException {
 		if (theDate == null) {
 			setValue((String)null);
 			return;
 		}
 
 		Calendar calendar = Calendar.getInstance();
         calendar.setTime(theDate);
         setValueToMinute(calendar);
     }
     
     /**
      * Convenience setter which sets the value using a {@link Calendar} object. Passing in <code>null</code> clears any existing value.
      * 
      * Note: Sets fields using precision up to the second
      * 
      * @param theCalendar The calendar object from which to retrieve values 
      * @since 1.1 
      */
     public void setValueToSecond(Calendar theCalendar) throws DataTypeException {
 		if (theCalendar == null) {
 			setValue((String)null);
 			return;
 		}
 
         int hr = theCalendar.get(Calendar.HOUR_OF_DAY);
         int min = theCalendar.get(Calendar.MINUTE);
         int sec = theCalendar.get(Calendar.SECOND);
         
         setHourMinSecondPrecision(hr, min, sec);
     }
 
     /**
      * Convenience setter which sets the value using a {@link Calendar} object. Passing in <code>null</code> clears any existing value.
      * 
      * Note: Sets fields using precision up to the millisecond, including timezone offset
      * 
      * @param theCalendar The calendar object from which to retrieve values 
      * @since 1.1 
      */
     public void setValue(Calendar theCalendar) throws DataTypeException {
 		if (theCalendar == null) {
 			setValue((String)null);
 			return;
 		}
 
         int hr = theCalendar.get(Calendar.HOUR_OF_DAY);
         int min = theCalendar.get(Calendar.MINUTE);
         float sec = theCalendar.get(Calendar.SECOND) + (theCalendar.get(Calendar.MILLISECOND) / 1000.0F);
         setHourMinSecondPrecision(hr, min, sec);
         
         // 3410095: care for integer overflow and timezones not at the full hour, e.g. India
         int hourOffset= theCalendar.get(Calendar.ZONE_OFFSET) / (1000 * 60 * 60);   
         int minuteOffset = (theCalendar.get(Calendar.ZONE_OFFSET) / (1000 * 60)) % 60;
         int zoneOffset = hourOffset * 100 + minuteOffset;
         setOffset(zoneOffset);
     }
    
     /**
      * Convenience setter which sets the value using a {@link Calendar} object. Passing in <code>null</code> clears any existing value.
      * 
      * Note: Sets fields using precision up to the millisecond, and sets the timezone offset to
      * the current system offset
      * Note: Date is timezone-agnostic, representing always GMT time
      * 
      * @param theDate The calendar object from which to retrieve values 
      * @since 1.1 
      */
 	public void setValue(Date theDate) throws DataTypeException {
 		if (theDate == null) {
 			setValue((String)null);
 			return;
 		}
 
 		GregorianCalendar cal = new GregorianCalendar();
 		cal.setTime(theDate);
 		setValue(cal);
 	}
     
     /**
      * Convenience setter which sets the value using a {@link Date} object. Passing in <code>null</code> clears any existing value.
      * 
      * Note: Sets fields using precision up to the second
      * Note: Date is timezone-agnostic, representing always GMT time
      * 
      * @param theDate The date object from which to retrieve values
      * @since 1.1 
      */
     public void setValueToSecond(Date theDate) throws DataTypeException {
 		if (theDate == null) {
 			setValue((String)null);
 			return;
 		}
 
         Calendar calendar = Calendar.getInstance();
         calendar.setTime(theDate);
         setValueToSecond(calendar);
     }
     
     /**
      * <p>Return the value as a calendar object.</p> 
      * 
      * <b>Note that only the time component of the return value is set to
      * the value from this object. Returned value will have today's date</b> 
      * @since 1.1 
      */
     public Calendar getValueAsCalendar() {
         int gmtOff = getGMTOffset();
         Calendar retVal;
         if (gmtOff != GMT_OFFSET_NOT_SET_VALUE && !omitOffsetFg) {
             int hrOffset = gmtOff / 100;
             int minOffset = Math.abs(gmtOff % 100);
             String timeZone = String.format("GMT%+d:%02d", hrOffset, minOffset);
             retVal = new GregorianCalendar(TimeZone.getTimeZone(timeZone));
         } else {
             retVal = Calendar.getInstance();
         }
 
         retVal.set(Calendar.HOUR_OF_DAY, getHour());
         retVal.set(Calendar.MINUTE, getMinute());
         retVal.set(Calendar.SECOND, getSecond());
         float fractSecond = getFractSecond();
         retVal.set(Calendar.MILLISECOND, (int) Math.round(fractSecond * 1000.0));
 
         return retVal;
     }
 
     
     /**
      * <p>Return the value as a date object</p>
      * 
      * <b>Note that only the time component of the return value is set to
      * the value from this object. Returned value will have today's date</b> 
      * Note: Date is timezone-agnostic, representing always GMT time
      * @since 1.1 
      */
     public Date getValueAsDate() {
         return getValueAsCalendar().getTime();
     }    
     
     /**
      * Returns the hour as an integer.
      */
     public int getHour() {
         return hour;
     } //end method
 
     /**
      * Returns the minute as an integer.
      */
     public int getMinute() {
         return minute;
     } //end method
 
     /**
      * Returns the second as an integer.
      */
     public int getSecond() {
         return second;
     } //end method
 
     /**
      * Returns the fractional second value as a float.
      */
     public float getFractSecond() {
         return fractionOfSec;
     } //end method
 
     /**
      * Returns the GMT offset value as an integer, {@link #GMT_OFFSET_NOT_SET_VALUE} if not set.  
      */
     public int getGMTOffset() {
         return offSet;
     } //end method
     
     /**
      * Returns a string value representing the input Gregorian Calendar object in
      * an Hl7 Time Format.
      */
     public static String toHl7TMFormat(GregorianCalendar cal) throws DataTypeException {
         String val;
         try {
             //set the input cal object so that it can report errors
             //on it's value
             cal.setLenient(false);
             int calHour = cal.get(GregorianCalendar.HOUR_OF_DAY);
             int calMin = cal.get(GregorianCalendar.MINUTE);
             int calSec = cal.get(GregorianCalendar.SECOND);
             int calMilli = cal.get(GregorianCalendar.MILLISECOND);
             //the inputs seconds and milli seconds should be combined into a float type
             float fractSec = calMilli / 1000F;
             float calSecFloat = calSec + fractSec;
             int calOffset = cal.get(GregorianCalendar.ZONE_OFFSET) + cal.get(GregorianCalendar.DST_OFFSET); 
             //Note the input's Offset value is in milliseconds, we must convert it to
             //a 4 digit integer in the HL7 Offset format.
             int offSetSignInt;
             if (calOffset < 0) {
                 offSetSignInt = -1;
             }
             else {
                 offSetSignInt = 1;
             }
             //get the absolute value of the gmtOffSet
             int absGmtOffSet = Math.abs(calOffset);
             int gmtOffSetHours = absGmtOffSet / (3600 * 1000);
             int gmtOffSetMin = (absGmtOffSet / 60000) % (60);
             //reset calOffset
             calOffset = ((gmtOffSetHours * 100) + gmtOffSetMin) * offSetSignInt;
             //Create an object of the TS class and populate it with the above values
             //then return the HL7 string value from the object
             CommonTMitive/CommonTM.html#CommonTM">CommonTM tm = new CommonTM();
             tm.setHourMinSecondPrecision(calHour, calMin, calSecFloat);
             tm.setOffset(calOffset);
             val = tm.getValue();
         } // end try
 
         catch (DataTypeException e) {
             throw e;
         } //end catch
 
         catch (Exception e) {
             throw new DataTypeException(e);
         } //end catch
         return val;
     } //end method
 
 } //end class