Convert Date and Time Format (QWCCVTDT) API
Required Parameter Group:
| 1 | Input format | Input | Char(10) |
| 2 | Input variable | Input | Char(*) |
| 3 | Output format | Input | Char(10) |
| 4 | Output variable | Output | Char(*) |
| 5 | Error code | I/O | Char(*) |
Optional Parameter Group 1:
| 6 | Input time zone | Input | Char(10) |
| 7 | Output time zone | Input | Char(10) |
| 8 | Time zone information | Output | Char(*) |
| 9 | Length of time zone information | Input | Bin(4) |
| 10 | Precision indicator | Input | Char(1) |
Optional Parameter Group 2:
| 11 | Input time indicator | Input | Char(1) |
Default Public Authority: *USE
Threadsafe: Yes
The Convert Date and Time Format (QWCCVTDT) API converts date and time values from one format to another format. The QWCCVTDT API lets you:
- Convert a time-stamp (*DTS, for system time-stamp) value to character format
- Convert a character date and time value to time-stamp format
- Convert a date from one character format to another
- Convert a date and time based on input and output time zone values and return the time zone information that is associated with the converted output
- Specify a precision of milliseconds or microseconds for your input and output variables
- Retrieve a current clock time based on the output time zone and return it based on the output format you specify
For additional information on converting dates and times, see Usage Notes.
Authorities and Locks
None.
Required Parameter Group
- Input format
- INPUT; CHAR(10)
The format of the data you give QWCCVTDT to convert. Valid values are:
*CURRENT The current system time. *DTS System time-stamp. *JOB The format given in the DATFMT job attribute. *SYSVAL The format given in the QDATFMT system value. *YMD YYMMDD (year, month, day) format. *YYMD YYYYMMDD (4-digit year, month, day) format. *MDY MMDDYY (month, day, year) format. *MDYY MMDDYYYY (month, day, 4-digit year) format. *DMY DDMMYY (day, month, year) format. *DMYY DDMMYYYY (day, month, 4-digit year) format. *JUL Julian format (YYDDD (year, day of year)). *LONGJUL Long Julian format (YYYYDDD (4-digit year, day of year)). - Input variable
- INPUT; CHAR(*)
The data to be converted. If the input format is *CURRENT, then this parameter is not used. See Input and Output Variable Formats to determine the structure of the input variable for all other input formats.
- Output format
- INPUT; CHAR(10)
The format to convert the data to. Valid values are:
*DTS System time-stamp. *JOB The format given in the DATFMT job attribute *SYSVAL The format given in the QDATFMT system value *YMD YYMMDD format *YYMD YYYYMMDD format *MDY MMDDYY format *MDYY MMDDYYYY format *DMY DDMMYY format *DMYY DDMMYYYY format *JUL Julian format (YYDDD) *LONGJUL Long Julian format (YYYYDDD) *DOS DOSGetDateTime format. The *DOS value can be specified only when *CURRENT or *DTS is specified for the input format parameter.
- Output variable
- OUTPUT; CHAR(*)
The converted data. If the output format is *DOS, the first 11 characters of this parameter are used. For details, see DOSGetDateTime Value Structure. See Input and Output Variable Formats to determine the structure of the output variable for all other output formats.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group 1
- Input time zone
- INPUT; CHAR(10)
Specifies the time zone associated with the input variable. If the input format is *CURRENT, then this parameter is not used. The default value is *SYS. Valid values are:
*SYS The input variable is a local system time value and the associated time zone is specified by the time zone system value. *UTC The input variable is a Gregorian Coordinated Universal Time (UTC) value. *JOB The input variable is a local job time value and the associated time zone is specified by the time zone job attribute. Time zone name Specifies the name of a time zone description (*TIMZON) object. - Output time zone
- INPUT; CHAR(10)
Specifies the time zone associated with the output variable. The default value is *SYS. Valid values are:
*SYS The output variable is a local system time value and the associated time zone is specified by the time zone system value. *UTC The output variable is a Gregorian Coordinated Universal Time (UTC) value. *JOB The output variable is a local job time value and the associated time zone is specified by the time zone job attribute. Time zone name Specifies the name of a time zone description (*TIMZON) object. - Time zone information
- OUTPUT; CHAR(*)
Specifies the time zone information associated with the output time zone. If 0 is specified for the length of time zone information, then this parameter is not used. For the format of the structure, see Time Zone Information Value Structure.
- Length of time zone information
- INPUT; BIN(4)
Specifies the length of the time zone information to be returned. The minimum length is 0 which indicates to not return any time zone information.
- Precision indicator
- INPUT; CHAR(1)
Specifies the precision of the input and output variables. The default value is 0 or milliseconds. Valid values are:
0 The input and output variables will have a precision in milliseconds. 1 The input and output variables will have a precision in microseconds.
Optional Parameter Group 2
- Input time indicator
- INPUT; CHAR(1)
Specifies which segment of time to use when the input variable has a date and time value that matches a repeated time. Otherwise, this parameter is not used. Repeated times occur when time changes from Daylight Saving Time (DST) to Standard Time (ST). For example, if DST ends on a given day at 02:00AM, then the segment of time from 01:00:00.000000 to 01:59:59.999999 on that day repeats. The first segment of time is considered in DST and the second segment is considered in ST. The default value is 1 or use the DST segment. For additional information on this parameter, see Usage Notes.
0 The input variable contains a date and time value that is contained in the second or Standard Time segment. 1 The input variable contains a date and time value that is contained in the first or Daylight Saving Time segment.
Input and Output Variable Formats
This table shows the format used for the input or output variable parameters.
| Input or Output Format | Input or Output Variable |
|---|---|
| *DTS | System time-stamp. The first 8 characters are used. |
| *YYMD, *MDYY, *DMYY, *LONGJUL in milliseconds | The first 17 characters are used. See 17-Byte Character Date and Time Value Structure. |
| All other character formats in milliseconds | The first 16 characters are used. See 16-Byte Character Date and Time Value Structure. |
| *YYMD, *MDYY, *DMYY, *LONGJUL in microseconds | The first 20 characters are used. See 20-Byte Character Date and Time Value Structure. |
| All other character formats in microseconds | The first 19 characters are used. See 19-Byte Character Date and Time Value Structure. |
16-Byte Character Date and Time Value Structure
This table shows the structure used for the input and output variables when the format is *JOB, *SYSVAL, *YMD, *MDY, *DMY, and *JUL and the precision indicator specifies milliseconds.
| Offset | Description |
|---|---|
| 0 | Century. Possible values are 0, which
indicates years 19xx, 1, which indicates years 20xx
and so forth through 9, which indicates years 28xx.
|
| 1-6 | Date, left-justified. This value cannot be all blanks or all zeros. Left-justify Julian dates, using blanks to fill the space. |
| 7-12 | Time, in HHMMSS (hours, minutes, seconds) format. |
| 13-15 | Milliseconds. This value cannot be blanks. |
17-Byte Character Date and Time Value Structure
This table shows the structure used for the input and output variables when the format is *YYMD, *MDYY, *DMYY, and *LONGJUL and the precision indicator specifies milliseconds.
| Offset | Description |
|---|---|
| 0-7 | Date, left-justified. This value cannot be all blanks or all zeros. Left-justify Julian dates, using blanks to fill the space. |
| 8-13 | Time, in HHMMSS (hours, minutes, seconds) format. |
| 14-16 | Milliseconds. This value cannot be blanks. |
19-Byte Character Date and Time Value Structure
This table shows the structure used for the input and output variables when the format is *JOB, *SYSVAL, *YMD, *MDY, *DMY, and *JUL and the precision indicator specifies microseconds.
| Offset | Description |
|---|---|
| 0 | Century. Possible values are 0, which
indicates years 19xx, 1, which indicates years 20xx
and so forth through 9, which indicates years 28xx.
|
| 1-6 | Date, left-justified. This value cannot be all blanks or all zeros. Left-justify Julian dates, using blanks to fill the space. |
| 7-12 | Time, in HHMMSS (hours, minutes, seconds) format. |
| 13-18 | Microseconds. This value cannot be blanks. |
20-Byte Character Date and Time Value Structure
This table shows the structure used for the input and output variables when the format is *YYMD, *MDYY, *DMYY, and *LONGJUL and the precision indicator specifies microseconds..
| Offset | Description |
|---|---|
| 0-7 | Date, left-justified. This value cannot be all blanks or all zeros. Left-justify Julian dates, using blanks to fill the space. |
| 8-13 | Time, in HHMMSS (hours, minutes, seconds) format. |
| 14-19 | Microseconds. This value cannot be blanks. |
DOSGetDateTime Value Structure
This table shows the structure used for the output variable.
| Offset | Description | ||||||
|---|---|---|---|---|---|---|---|
| 0 | Hours (0-23)1 | ||||||
| 1 | Minutes (0-59)1 | ||||||
| 2 | Seconds (0-59)1 | ||||||
| 3 | Hundredths of seconds (0-99)1 | ||||||
| 4 | Day (1-31)1 | ||||||
| 5 | Month (1-12)1 | ||||||
| 6-7 | Year (for example, 1995)2 | ||||||
| 8-9 | Time zone offset (in minutes)2, 3 | ||||||
| 10 | Day of the week, where 0 is Sunday (0-6)1 | ||||||
Notes:
|
|||||||
Time Zone Information Value Structure
This table shows the structure used for the time zone information output parameter. If *UTC is specified for the output time zone, or if the input and output time zone parameter values are the same and the input variable contains a date that is outside the supported date range (from August 25, 1928, 00:00:00.000000 to May 09, 2071, 00:00:00.000000), then all binary fields will be set to 0 and all character fields will be set to blanks.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Time zone description name |
| 18 | 12 | CHAR(1) | Reserved |
| 19 | 13 | CHAR(1) | Current Daylight Saving Time indicator |
| 20 | 14 | BINARY(4) | Current offset |
| 24 | 18 | CHAR(50) | Current full name |
| 74 | 4A | CHAR(10) | Current abbreviated name |
| 84 | 54 | CHAR(7) | Current message identifier |
| 91 | 5B | CHAR(10) | Message file name |
| 101 | 65 | CHAR(10) | Message file library |
| 111 | 6F | CHAR(1) | Reserved |
| 112 | 70 | BINARY(4) | Year offset |
Field Descriptions
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Current abbreviated name. The abbreviated, or short, name for the time zone. This field will contain either the Standard Time or Daylight Saving Time abbreviated name depending on whether or not Daylight Saving Time is in effect. If the time zone description uses a message to specify the current abbreviated name and the message cannot be retrieved, this field returns *N. This can occur when the caller of the API is not authorized to the message file or its library, the message file cannot be found or the message does not exist in the message file.
Current Daylight Saving Time indicator. Indicates whether or not the output date and time (output variable converted based on the output time zone) is observing Daylight Saving Time or not. Valid values that are returned are:
| 0 | Daylight Saving Time is not being observed (Standard Time). |
| 1 | Daylight Saving Time is being observed. |
Current full name. The full, or long, name for the time zone. This field will contain either the Standard Time or Daylight Saving Time full name depending on whether or not Daylight Saving Time is in effect. If the time zone description uses a message to specify the current full name and the message cannot be retrieved, this field returns *N. This can occur when the caller of the API is not authorized to the message file or its library, the message file cannot be found or the message does not exist in the message file.
Current message identifier. The identifier of the message that contains the current full and abbreviated names. This field will be *NONE if a message was not specified when the time zone description was created.
Current offset. The time difference, in minutes, between the output time zone and Coordinated Universal Time (UTC). This value has been adjusted for Daylight Saving Time, if necessary.
Message file library. The name of the library that contains the message file. The field will contain all blanks if the current message identifier is *NONE.
Message file name. The name of the file that contains the current message. The field will contain *NONE if the current message identifier is *NONE.
Reserved. An unused field.
Time zone description name. The name of the time zone description that is associated with the output time zone. If *SYS or *JOB was specified for the output time zone and a time zone has not been set for the Time zone (QTIMZON) system value, this field returns *N.
Year offset. The number of years that the current year in the calendar system used with this time zone differs from the current Gregorian year. The range is -140 to 140.
Usage Notes
When converting an input date from a 2-digit year format to a *DTS time-stamp format without time zone conversion, the supported date range is from August 23, 1928, 12:03:06.314752 (.315 for milliseconds) to May 10, 2071, 11:56:53.685240 (.685 for milliseconds). Converting an input date that is outside this range will result in an output date within this range.
When converting an input date from a 4-digit year format to a *DTS time-stamp format without time zone conversion, the supported date range is from August 24, 1928, 00:00:00.000000 to May 09, 2071, 23:59:59.999999 (.999 for milliseconds). Converting an input date that is outside this range will result in error message CPF1060.
When converting an input date from a 4-digit year format to a 2-digit year format without time zone conversion, the supported date range is from January 1, 1900, 00:00:00.000000 to December 31, 2899, 23:59:59.999999 (.999 for milliseconds). Converting an input date that is outside this range will result in error message CPF1060.
When converting an input date from a 4-digit year format to a 4-digit year format without time zone conversion, the supported date range is from January 1, 0001, 00:00:00.000000 to December 31, 9999, 23:59:59.999999 (.999 for milliseconds). Converting an input date that is outside this range will result in error message CPF1060.
When converting an input date from 2-digit year format to a 2-digit year format without time zone conversion, the supported date range is from January 1, 1900, 00:00:00.000000 to December 31, 2899, 23:59:59.999999 (.999 for milliseconds). The century digit of the input variable is copied into the output variable without validation.
When converting an input date from 2-digit year format to a 4-digit year format without time zone conversion, the supported date range is from January 1, 1900, 00:00:00.000000 to December 31, 2899, 23:59:59.999999 (.999 for milliseconds).
When converting an input date from a *DTS time-stamp format to an output date of any format without time zone conversion, the supported date range is from August 23, 1928, 12:03:06.314752 (.315 for milliseconds) to May 10, 2071, 11:56:53.685240 (.685 for milliseconds).
When converting an input date of any format to an output date of any format that involves time zone conversion as well, the supported date range is from August 25, 1928, 00:00:00.000000 to May 08, 2071, 23:59:59.999999 (.999 for milliseconds). Converting an input date that is outside this range will result in error message CPF1060.
When moving from Standard Time (ST) to Daylight Saving Time (DST) there is a window of time (1 hour) that does not occur. Any time zone conversion where the input variable date and time value is within this window will result in error message CPF1060.
When moving from Daylight Saving Time (DST) to Standard Time there is a window of time (1 hour) that repeats. For example, if DST ends on a given day at 02:00AM, then the segment of time from 01:00:00.000000 to 01:59:59.999999 on that day repeats. The first segment of repeated time is the DST segment. The second segment of repeated time is the Standard Time segment. It is possible using time zone conversion to have the output variable date and time value end up in either segment. If you are retrieving time zone information, the current Daylight Saving Time indicator will be set accordingly. By default, for any time zone conversion the input variable that is within this window of time that repeats is considered part of the DST segment. However, you can use the optional Input time indicator parameter to cause the input variable to be considered within the Standard Time segment. You can copy the resultant current DST indicator into the Input time indicator parameter when converting back and forth between time zones. For example, when converting a date and time value from *UTC to time zone A, the resultant time is 01:15:00 AM and the current DST indicator returned is 0, which means the resultant time is Standard Time. In order to obtain the original *UTC value when converting back to *UTC from time zone A, the current DST indicator value should be copied to the Input time indicator parameter. This will cause the date and time value to be treated as Standard Time rather than as the default, Daylight Saving Time.
You can convert any input format except *CURRENT to the same output format without receiving an error (time zone conversion is not specified, or if specified, the input and output time zone parameter values must be the same and the time zone information length must be 0 as well). For these cases, the input variable is copied into the output variable without validation.
When converting one character date format (that is, anything other than *CURRENT, the current machine-clock time, *DTS, the system time-stamp, or any specified time zone conversion) to another character date format, the date information is validated and converted. However, the time portion of the input variable is copied into the output variable without validation.
When requesting time zone conversion with different input and output time zone values, or when requesting time zone information, the time portion is validated and converted as well as the date portion.
When converting a character date and time value to *DTS and back to character format using microseconds precision, there is a rounding error of minus 1 to minus 7 microseconds. If you specify a precision of microseconds, it is recommended that you use a microsecond value that is evenly divisible by 8.
The system has the ability to manage a year offset that specifies the number of years that the current year in the calendar system used with this time zone differs from the current Gregorian year. When the input time format is *CURRENT, the date returned will be in the non-Gregorian year which takes the year offset into account. When specifying an input time zone value that is not *UTC and an output time zone value of *UTC, the year offset is removed along with the time zone offset. The converted output will be in the UTC time zone (based on the Greenwich meridian) and will be in the Gregorian year. To get a result that includes the year offset, specify an output time zone that defines Greenwich Mean Time such as the IBM-supplied Q0000GMT and that also contains the desired year offset. The converted output will be in the GMT time zone (same as UTC time zone) and will also be in the non-Gregorian year.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1060 E | Date not valid. |
| CPF1061 E | Time not valid. |
| CPF1848 E | Century digit &1 not valid. |
| CPF1849 E | Millisecond or microsecond value not valid. |
| CPF1850 E | Format &1 not valid |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C36 E | Number of parameters, &1, for API not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1
[ Back to top | Date and Time APIs | Miscellaneous APIs | APIs by category ]