com.ibm.as400.access
Class AS400Date

java.lang.Object
  extended by com.ibm.as400.access.AS400AbstractTime
      extended by com.ibm.as400.access.AS400Date
All Implemented Interfaces:
AS400DataType, Serializable, Cloneable

public class AS400Date
extends AS400AbstractTime

Provides a converter between a java.sql.Date object and an IBM i date value such as "12/31/97". In the IBM i programming reference, this type is referred to as the "Date Data Type", or DDS data type L. Note: Only date fields that are stored on the IBM i system as EBCDIC characters are currently supported by this class. (Some IBM i "logical files" have date fields stored as zoned or packed decimal values.)

An IBM i date value simply indicates a year/month/day, and does not indicate a contextual time zone. Internally, this class interprets all date- and time-related strings as relative to the timezone of the server.

Suggestion: To avoid confusion and unexpected results when crossing time zones:
Whenever creating or interpreting instances of java.sql.Date, java.sql.Time, or java.sql.Timestamp, always assume that the reference time zone for the object is the same as the server, and avoid using any deprecated methods. If it is necessary to convert date/time values between the server time zone and other time zones, use methods of Calendar. Rather than using toString() to display the value of a date/time object, use DateFormat.format() after specifying the server TimeZone. For example: import java.text.SimpleDateFormat; java.sql.Date date1; // value to be generated by AS400Date SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd"); // Set the formatter's time zone to GMT. formatter.setTimeZone(as400.getTimeZone()); ... System.out.println("Date value: " + formatter.format(date1));

Suggestion: To avoid ambiguity and confusion between different kinds of "Date" objects, fully qualify all references to classes java.util.Date and java.sql.Date (especially if you import both java.util.* and java.sql.*).

Note: In the descriptions of the "format" constants, all example dates represent the date April 25, 1997.

See Also:
AS400Time, AS400Timestamp, Serialized Form

Field Summary
static int FORMAT_CDMY
          Date format CDMY (cdd/mm/yy).
static int FORMAT_CMDY
          Date format CMDY (cmm/dd/yy).
static int FORMAT_CYMD
          Date format CYMD (cyy/mm/dd).
static int FORMAT_DMY
          Date format DMY (dd/mm/yy).
static int FORMAT_EUR
          Date format EUR (dd.mm.yyyy).
static int FORMAT_ISO
          Date format ISO (yyyy-mm-dd).
static int FORMAT_JIS
          Date format JIS (yyyy-mm-dd).
static int FORMAT_JUL
          Date format JUL (yy/ddd).
static int FORMAT_LONGJUL
          Date format LONGJUL (yyyy/ddd).
static int FORMAT_MDY
          Date format MDY (mm/dd/yy).
static int FORMAT_MY
          Date format MY (mm/yy).
static int FORMAT_MYY
          Date format MYY (mm/yyyy).
static int FORMAT_USA
          Date format USA (mm/dd/yyyy).
static int FORMAT_YM
          Date format YM (yy/mm).
static int FORMAT_YMD
          Date format YMD (yy/mm/dd).
static int FORMAT_YYM
          Date format YYM (yyyy/mm).
 
Fields inherited from interface com.ibm.as400.access.AS400DataType
TYPE_ARRAY, TYPE_BIN1, TYPE_BIN2, TYPE_BIN4, TYPE_BIN8, TYPE_BYTE_ARRAY, TYPE_DATE, TYPE_DECFLOAT, TYPE_FLOAT4, TYPE_FLOAT8, TYPE_PACKED, TYPE_STRUCTURE, TYPE_TEXT, TYPE_TIME, TYPE_TIME_OF_DAY, TYPE_TIMESTAMP, TYPE_UBIN1, TYPE_UBIN2, TYPE_UBIN4, TYPE_UBIN8, TYPE_ZONED
 
Constructor Summary
AS400Date()
          Constructs an AS400Date object.
AS400Date(int format)
          Constructs an AS400Date object.
AS400Date(int format, Character separator)
          Constructs an AS400Date object.
AS400Date(TimeZone timeZone)
          Constructs an AS400Date object.
AS400Date(TimeZone timeZone, int format)
          Constructs an AS400Date object.
AS400Date(TimeZone timeZone, int format, Character separator)
          Constructs an AS400Date object.
 
Method Summary
static int getByteLength(int format, Character separator)
          Returns the number of bytes occupied on the IBM i system by a field of this type.
 Object getDefaultValue()
          Returns a Java object representing the default value of the data type.
 int getFormat()
          Gets the format of this AS400Date object.
 int getInstanceType()
          Returns TYPE_DATE.
 Class getJavaType()
          Returns the Java class that corresponds with this data type.
 Character getSeparator()
          Gets the separator character of this AS400Date object.
 Date parse(String source)
          Converts a string representation of a date, to a Java object.
static Date parseXsdString(String source)
          Converts the specified ISO representation of a date, to a Java object.
static Date parseXsdString(String source, TimeZone timeZone)
          Converts the specified ISO representation of a date, to a Java object.
 void setFormat(int format)
          Sets the format of this AS400Date object.
 void setFormat(int format, char separator)
          Deprecated. Use setFormat(int,Character) instead.
 void setFormat(int format, Character separator)
          Sets the format of this AS400Date object.
 int toBytes(Object javaValue, byte[] as400Value, int offset)
          Converts the specified Java object into IBM i format in the specified byte array.
static int toFormat(String formatName)
          Returns the integer format value that corresponds to specified format name.
 Object toObject(byte[] as400Value, int offset)
          Converts the specified IBM i data type to a Java object.
 String toString(Object javaValue)
          Converts the specified Java object into a String representation that is consistent with the format of this data type.
static String toXsdString(Object javaValue)
          Converts the specified Java object into an XML Schema string representation.
static String toXsdString(Object javaValue, TimeZone timeZone)
          Converts the specified Java object into an XML Schema string representation.
static boolean validateFormat(int format)
          Validates the specified format value.
 
Methods inherited from class com.ibm.as400.access.AS400AbstractTime
clone, getByteLength, getTimeZone, toBytes, toBytes, toObject
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FORMAT_MDY

public static final int FORMAT_MDY
Date format MDY (mm/dd/yy).
Example: 04/25/97
Range of years: 1940-2039
Default separator: '/'

See Also:
Constant Field Values

FORMAT_DMY

public static final int FORMAT_DMY
Date format DMY (dd/mm/yy).
Example: 25/04/97
Range of years: 1940-2039
Default separator: '/'

See Also:
Constant Field Values

FORMAT_YMD

public static final int FORMAT_YMD
Date format YMD (yy/mm/dd).
Example: 97/04/25
Range of years: 1940-2039
Default separator: '/'

See Also:
Constant Field Values

FORMAT_JUL

public static final int FORMAT_JUL
Date format JUL (yy/ddd).
Example: 97/115
Range of years: 1940-2039
Default separator: '/'

See Also:
Constant Field Values

FORMAT_ISO

public static final int FORMAT_ISO
Date format ISO (yyyy-mm-dd).
Example: 1997-04-25
Range of years: 0001-9999
Default separator: '-'

See Also:
Constant Field Values

FORMAT_USA

public static final int FORMAT_USA
Date format USA (mm/dd/yyyy).
Example: 04/25/1997
Range of years: 0001-9999
Default separator: '/'

See Also:
Constant Field Values

FORMAT_EUR

public static final int FORMAT_EUR
Date format EUR (dd.mm.yyyy).
Example: 25.04.1997
Range of years: 0001-9999
Default separator: '.'

See Also:
Constant Field Values

FORMAT_JIS

public static final int FORMAT_JIS
Date format JIS (yyyy-mm-dd).
Example: 1997-04-25
Range of years: 0001-9999
Default separator: '-'

See Also:
Constant Field Values

FORMAT_CYMD

public static final int FORMAT_CYMD
Date format CYMD (cyy/mm/dd).
Example: 097/04/25
Range of years: 1900-2899
Default separator: '/'

See Also:
Constant Field Values

FORMAT_CMDY

public static final int FORMAT_CMDY
Date format CMDY (cmm/dd/yy).
Example: 004/25/97
Range of years: 1900-2899
Default separator: '/'

See Also:
Constant Field Values

FORMAT_CDMY

public static final int FORMAT_CDMY
Date format CDMY (cdd/mm/yy).
Example: 025/04/97
Range of years: 1900-2899
Default separator: '/'

See Also:
Constant Field Values

FORMAT_LONGJUL

public static final int FORMAT_LONGJUL
Date format LONGJUL (yyyy/ddd).
Example: 1997/115
Range of years: 0001-9999
Default separator: '/'

See Also:
Constant Field Values

FORMAT_MY

public static final int FORMAT_MY
Date format MY (mm/yy).
Example: 04/97
Range of years: 1940-2039
Default separator: '/'

See Also:
Constant Field Values

FORMAT_YM

public static final int FORMAT_YM
Date format YM (yy/mm).
Example: 97/04
Range of years: 1940-2039
Default separator: '/'

See Also:
Constant Field Values

FORMAT_MYY

public static final int FORMAT_MYY
Date format MYY (mm/yyyy).
Example: 04/1997
Range of years: 0001-9999
Default separator: '/'

See Also:
Constant Field Values

FORMAT_YYM

public static final int FORMAT_YYM
Date format YYM (yyyy/mm).
Example: 1997/04
Range of years: 0001-9999
Default separator: '/'

See Also:
Constant Field Values
Constructor Detail

AS400Date

public AS400Date()
Constructs an AS400Date object. Assumes the default GMT time zone. Format FORMAT_ISO and separator '-' are used.


AS400Date

public AS400Date(TimeZone timeZone)
Constructs an AS400Date object. Format FORMAT_ISO and separator '-' are used.


AS400Date

public AS400Date(int format)
Constructs an AS400Date object. The specified format's default separator is used. Assumes the default GMT timezone

Parameters:
format - The date format. For a list of valid values, refer to AS400Date(int,Character).

AS400Date

public AS400Date(TimeZone timeZone,
                 int format)
Constructs an AS400Date object. The specified format's default separator is used.

Parameters:
format - The date format. For a list of valid values, refer to AS400Date(int,Character).

AS400Date

public AS400Date(int format,
                 Character separator)
Constructs an AS400Date object. The specified format's default separator is used. Assumes the default GMT timezone is used.

Parameters:
format - The date format.
Valid values are:
separator - The separator character. Valid values are:
  • '&' (ampersand)
  • ' ' (blank)
  • ',' (comma)
  • '-' (hyphen)
  • '.' (period)
  • '/' (slash)
  • (null)
A null value indicates "no separator". Refer to the IBM i programming reference to determine which separator characters are valid with each format.

AS400Date

public AS400Date(TimeZone timeZone,
                 int format,
                 Character separator)
Constructs an AS400Date object. The specified format's default separator is used.

Parameters:
format - The date format.
Valid values are:
separator - The separator character. Valid values are:
  • '&' (ampersand)
  • ' ' (blank)
  • ',' (comma)
  • '-' (hyphen)
  • '.' (period)
  • '/' (slash)
  • (null)
A null value indicates "no separator". Refer to the IBM i programming reference to determine which separator characters are valid with each format.
Method Detail

getDefaultValue

public Object getDefaultValue()
Returns a Java object representing the default value of the data type.

Specified by:
getDefaultValue in interface AS400DataType
Specified by:
getDefaultValue in class AS400AbstractTime
Returns:
A java.sql.Date object with a value of January 1, 1970, 00:00:00 GMT.

getFormat

public int getFormat()
Gets the format of this AS400Date object.

Returns:
format The format for this object. For a list of possible values, refer to AS400Date(int,Character).

getSeparator

public Character getSeparator()
Gets the separator character of this AS400Date object.

Returns:
separator The separator character. For a list of possible values, refer to AS400Date(int,Character). If the format contains no separators, null is returned.
See Also:
setFormat(int,Character)

getInstanceType

public int getInstanceType()
Returns TYPE_DATE.

Specified by:
getInstanceType in interface AS400DataType
Specified by:
getInstanceType in class AS400AbstractTime
Returns:
AS400DataType.TYPE_DATE.

getJavaType

public Class getJavaType()
Returns the Java class that corresponds with this data type.

Specified by:
getJavaType in interface AS400DataType
Specified by:
getJavaType in class AS400AbstractTime
Returns:
java.sql.Date.class.

setFormat

public void setFormat(int format)
Sets the format of this AS400Date object. The specified format's default separator character is used.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Date(int,Character).

setFormat

public void setFormat(int format,
                      Character separator)
Sets the format of this AS400Date object.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Date(int,Character).
separator - The separator character. For a list of valid values, refer to AS400Date(int,Character). A null value indicates "no separator". Refer to the IBM i programming reference to determine which separator characters are valid with each format.

setFormat

public void setFormat(int format,
                      char separator)
Deprecated. Use setFormat(int,Character) instead.

Sets the format of this AS400Date object.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Date(int,Character).
separator - The separator character.

toFormat

public static int toFormat(String formatName)
Returns the integer format value that corresponds to specified format name. If null is specified, the default format (FORMAT_ISO) is returned. This method is provided for use by the PCML infrastructure.

Parameters:
formatName - The date format name.
Valid values are:
  • MDY
  • DMY
  • YMD
  • JUL
  • ISO
  • USA
  • EUR
  • JIS
  • CYMD
  • CMDY
  • CDMY
  • LONGJUL
  • MY
  • YM
  • MYY
  • YYM
Returns:
the format value. For example, if formatName is "ISO", then FORMAT_ISO is returned.

toBytes

public int toBytes(Object javaValue,
                   byte[] as400Value,
                   int offset)
Converts the specified Java object into IBM i format in the specified byte array.

Specified by:
toBytes in interface AS400DataType
Overrides:
toBytes in class AS400AbstractTime
Parameters:
javaValue - The object corresponding to the data type. It must be an instance of java.sql.Date. Hours, minutes, seconds, and milliseconds are disregarded.
as400Value - The array to receive the data type in IBM i format. There must be enough space to hold the IBM i value.
offset - The offset into the byte array for the start of the IBM i value. It must be greater than or equal to zero.
Returns:
The number of bytes in the IBM i representation of the data type.

toObject

public Object toObject(byte[] as400Value,
                       int offset)
Converts the specified IBM i data type to a Java object.

Specified by:
toObject in interface AS400DataType
Specified by:
toObject in class AS400AbstractTime
Parameters:
as400Value - The array containing the data type in IBM i format. The entire data type must be represented.
offset - The offset into the byte array for the start of the IBM i value. It must be greater than or equal to zero.
Returns:
A java.sql.Date object corresponding to the data type. The reference time zone for the object is GMT.

toString

public String toString(Object javaValue)
Converts the specified Java object into a String representation that is consistent with the format of this data type.

Specified by:
toString in class AS400AbstractTime
Parameters:
javaValue - The object corresponding to the data type. This must be an instance of java.sql.Date, and must be within the range specifiable by this data type.
Returns:
A String representation of the specified value, formatted appropriately for this data type.

parse

public Date parse(String source)
Converts a string representation of a date, to a Java object.

Parameters:
source - A date value expressed as a string in the format specified for this AS400Date object.
Returns:
A java.sql.Date object representing the specified date. The reference time zone for the object is GMT.

parseXsdString

public static Date parseXsdString(String source)
Converts the specified ISO representation of a date, to a Java object. This method is provided for use by the PCML infrastructure; in particular, when parsing 'init=' values for 'date' data elements. This assumes the reference timezone to be GMT

Parameters:
source - A date value expressed as a string in format yyyy-MM-dd.
Returns:
A java.sql.Date object representing the specified date.

parseXsdString

public static Date parseXsdString(String source,
                                  TimeZone timeZone)
Converts the specified ISO representation of a date, to a Java object. This method is provided for use by the PCML infrastructure; in particular, when parsing 'init=' values for 'date' data elements.

Parameters:
source - A date value expressed as a string in format yyyy-MM-dd.
Returns:
A java.sql.Date object representing the specified date. The reference time zone must be passed as a parameter.

toXsdString

public static String toXsdString(Object javaValue)
Converts the specified Java object into an XML Schema string representation. This method is provided for use by the PCML infrastructure. This method assumes the use of the GMT timezone.

Parameters:
javaValue - The object corresponding to the data type. This must be an instance of java.sql.Date, and must be within the range specifiable by this data type.
Returns:
The date expressed as a string in format yyyy-MM-dd.

toXsdString

public static String toXsdString(Object javaValue,
                                 TimeZone timeZone)
Converts the specified Java object into an XML Schema string representation. This method is provided for use by the PCML infrastructure.

Parameters:
javaValue - The object corresponding to the data type. This must be an instance of java.sql.Date, and must be within the range specifiable by this data type.
timeZone - The timezone used to evaluate the string.
Returns:
The date expressed as a string in format yyyy-MM-dd.

validateFormat

public static boolean validateFormat(int format)
Validates the specified format value. This method is provided for use by the PCML infrastructure.

Parameters:
format - The format. For a list of valid values, refer to AS400Date(int,Character).
Returns:
true if the format is valid; false otherwise.

getByteLength

public static int getByteLength(int format,
                                Character separator)
Returns the number of bytes occupied on the IBM i system by a field of this type. This method is provided for use by the PCML infrastructure.

Parameters:
format - The format. For a list of valid values, refer to AS400Date(int,Character).
separator - The separator character. For a list of valid values, refer to AS400Date(int,Character).
Returns:
the number of bytes occupied.