1142 lines
35 KiB
HTML
1142 lines
35 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Convert Date and Time Format (QWCCVTDT) API</title>
|
|
<!-- Begin Header Records ========================================= -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- QWCCVTDT SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
|
|
<!-- at RCHVMW2 on 6 Oct 1998 at 19:41:58 -->
|
|
<!-- Change history: -->
|
|
<!-- 021105 GFIX:(Added Time Modernization changes, P9A19763 ...)-->
|
|
<!-- File cleanup completed 06/28/01 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>Convert Date and Time Format (QWCCVTDT) API</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="45%">Input format</td>
|
|
<td align="left" valign="top" width="25%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Input variable</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Output format</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Output variable</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">Error code</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Optional Parameter Group 1:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">6</td>
|
|
<td align="left" valign="top" width="45%">Input time zone</td>
|
|
<td align="left" valign="top" width="25%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">7</td>
|
|
<td align="left" valign="top">Output time zone</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">Time zone information</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">9</td>
|
|
<td align="left" valign="top">Length of time zone information</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Bin(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">Precision indicator</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(1)</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<br>
|
|
Optional Parameter Group 2:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">11</td>
|
|
<td align="left" valign="top" width="45%">Input time indicator</td>
|
|
<td align="left" valign="top" width="25%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(1)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Convert Date and Time Format (QWCCVTDT) API converts date and time
|
|
values from one format to another format. The QWCCVTDT API lets you:</p>
|
|
|
|
<ul>
|
|
<li>Convert a time-stamp (*DTS, for system time-stamp) value to character
|
|
format</li>
|
|
|
|
<li>Convert a character date and time value to time-stamp format</li>
|
|
|
|
<li>Convert a date from one character format to another</li>
|
|
|
|
|
|
<li>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</li>
|
|
<li>Specify a precision of milliseconds or microseconds for your
|
|
input and output variables</li>
|
|
<li>Retrieve a current clock time based on the output time zone and return it
|
|
based on the output format you specify</li>
|
|
</ul>
|
|
|
|
<p>For additional information on converting dates and times,
|
|
see <a href="#HDRUSAGE">Usage Notes</a>.</p>
|
|
|
|
<br>
|
|
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<!-- Use this if there are no authorities and locks. -->
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Input format</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>The format of the data you give QWCCVTDT to convert. Valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CURRENT</em></td>
|
|
<td align="left" valign="top">The current system time.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DTS</em></td>
|
|
<td align="left" valign="top">System time-stamp. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*JOB</em></td>
|
|
<td align="left" valign="top">The format given in the DATFMT job
|
|
attribute.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYSVAL</em></td>
|
|
<td align="left" valign="top">The format given in the QDATFMT system
|
|
value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*YMD</em></td>
|
|
<td align="left" valign="top">YYMMDD (year, month, day) format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*YYMD</em></td>
|
|
<td align="left" valign="top">YYYYMMDD (4-digit year, month, day) format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*MDY</em></td>
|
|
<td align="left" valign="top">MMDDYY (month, day, year) format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*MDYY</em></td>
|
|
<td align="left" valign="top">MMDDYYYY (month, day, 4-digit year) format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DMY</em></td>
|
|
<td align="left" valign="top">DDMMYY (day, month, year) format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DMYY</em></td>
|
|
<td align="left" valign="top">DDMMYYYY (day, month, 4-digit year) format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*JUL</em></td>
|
|
<td align="left" valign="top">Julian format (YYDDD (year, day of year)).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*LONGJUL</em></td>
|
|
<td align="left" valign="top">Long Julian format (YYYYDDD (4-digit year, day of
|
|
year)).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
</dd>
|
|
|
|
<dt><strong>Input variable</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The data to be converted. If the input format is *CURRENT, then this
|
|
parameter is not used. See <a href="#HDRINOUTFMT">Input and Output Variable Formats</a>
|
|
to determine the structure of the input variable for all other input formats.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Output format</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>The format to convert the data to. Valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DTS</em></td>
|
|
<td align="left" valign="top">System time-stamp.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*JOB</em></td>
|
|
<td align="left" valign="top">The format given in the DATFMT job attribute</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYSVAL</em></td>
|
|
<td align="left" valign="top">The format given in the QDATFMT system value</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*YMD</em></td>
|
|
<td align="left" valign="top">YYMMDD format</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*YYMD</em></td>
|
|
<td align="left" valign="top">YYYYMMDD format</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*MDY</em></td>
|
|
<td align="left" valign="top">MMDDYY format</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*MDYY</em></td>
|
|
<td align="left" valign="top">MMDDYYYY format</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DMY</em></td>
|
|
<td align="left" valign="top">DDMMYY format</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DMYY</em></td>
|
|
<td align="left" valign="top">DDMMYYYY format</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*JUL</em></td>
|
|
<td align="left" valign="top">Julian format (YYDDD)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*LONGJUL</em></td>
|
|
<td align="left" valign="top">Long Julian format (YYYYDDD)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DOS</em></td>
|
|
<td align="left" valign="top">DOSGetDateTime format. The *DOS value can be
|
|
specified only when *CURRENT or *DTS is specified for the input format
|
|
parameter.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Output variable</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>The converted data. If the output format is *DOS, the first 11 characters
|
|
of this parameter are used. For details, see <a href="#HDRDOSVAL">
|
|
DOSGetDateTime Value Structure</a>. See <a href="#HDRINOUTFMT">Input and Output Variable Formats</a>
|
|
to determine the structure of the output variable for all other output formats.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Optional Parameter Group 1</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Input time zone</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>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:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYS</em></td>
|
|
<td align="left" valign="top">The input variable is a local system time value
|
|
and the associated time zone is specified by the time zone system value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*UTC</em></td>
|
|
<td align="left" valign="top">The input variable is a Coordinated Universal
|
|
Time (UTC) value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*JOB</em></td>
|
|
<td align="left" valign="top">The input variable is a local job time value
|
|
and the associated time zone is specified by the time zone job attribute.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>Time zone name</em></td>
|
|
<td align="left" valign="top">Specifies the name of a time zone description
|
|
(*TIMZON) object.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><strong>Output time zone</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>Specifies the time zone associated with the output variable. The default value
|
|
is *SYS. Valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYS</em></td>
|
|
<td align="left" valign="top">The output variable is a local system time value
|
|
and the associated time zone is specified by the time zone system value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*UTC</em></td>
|
|
<td align="left" valign="top">The output variable is a Coordinated Universal
|
|
Time (UTC) value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*JOB</em></td>
|
|
<td align="left" valign="top">The output variable is a local job time value
|
|
and the associated time zone is specified by the time zone job attribute.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>Time zone name</em></td>
|
|
<td align="left" valign="top">Specifies the name of a time zone description
|
|
(*TIMZON) object.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><strong>Time zone information</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>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 <a href="#hdrtmzninfo">Time Zone Information Value Structure</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Length of time zone information</strong></dt>
|
|
|
|
<dd>INPUT; BIN(4)
|
|
|
|
<p>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.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Precision indicator</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p>Specifies the precision of the input and output variables.
|
|
The default value is 0 or milliseconds. Valid values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">The input and output variables will have a
|
|
precision in milliseconds.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The input and output variables will have a
|
|
precision in microseconds.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Optional Parameter Group 2</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Input time indicator</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p>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 <a href="#HDRUSAGE">Usage Notes</a>.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">The input variable contains a date and time value that is
|
|
contained in the second or Standard Time segment.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The input variable contains a date and time value that is
|
|
contained in the first or Daylight Saving Time segment.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<h3><a name="HDRINOUTFMT">Input and Output Variable Formats</a></h3>
|
|
|
|
<p>This table shows the format used for the input or output variable parameters.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Input or Output Format</th>
|
|
<th align="left" valign="top">Input or Output Variable</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">*DTS</td>
|
|
<td align="left" valign="top">System time-stamp. The first 8 characters are
|
|
used.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">*YYMD, *MDYY, *DMYY, *LONGJUL in milliseconds</td>
|
|
<td align="left" valign="top">The first 17 characters are used. See <a href=
|
|
"#HDRVALSTR17">17-Byte Character Date and Time Value Structure</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">All other character formats in milliseconds</td>
|
|
<td align="left" valign="top">The first 16 characters are used. See <a href=
|
|
"#HDRVALSTR16">16-Byte Character Date and Time Value Structure</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">*YYMD, *MDYY, *DMYY, *LONGJUL in microseconds</td>
|
|
<td align="left" valign="top">The first 20 characters are used. See <a href=
|
|
"#HDRVALSTR20">20-Byte Character Date and Time Value Structure</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">All other character formats in microseconds</td>
|
|
<td align="left" valign="top">The first 19 characters are used. See <a href=
|
|
"#HDRVALSTR19">19-Byte Character Date and Time Value Structure</a>.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRVALSTR16">16-Byte Character Date and Time Value
|
|
Structure</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Offset</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="90%">Century. Possible values are 0, which
|
|
indicates years 19<em>xx</em>, 1, which indicates years 20<em>xx</em>
|
|
and so forth through 9, which indicates years 28<em>xx</em>.
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">1-6</td>
|
|
<td align="left" valign="top">Date, left-justified. This value cannot be all
|
|
blanks or all zeros. Left-justify Julian dates, using blanks to fill the
|
|
space.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">7-12</td>
|
|
<td align="left" valign="top">Time, in HHMMSS (hours, minutes, seconds)
|
|
format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">13-15</td>
|
|
<td align="left" valign="top">Milliseconds. This value cannot be blanks.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRVALSTR17">17-Byte Character Date and Time Value
|
|
Structure</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Offset</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="10%">0-7</td>
|
|
<td align="left" valign="top" width="90%">Date, left-justified. This value
|
|
cannot be all blanks or all zeros. Left-justify Julian dates, using blanks to
|
|
fill the space.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">8-13</td>
|
|
<td align="left" valign="top">Time, in HHMMSS (hours, minutes, seconds)
|
|
format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">14-16</td>
|
|
<td align="left" valign="top">Milliseconds. This value cannot be blanks.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<h3><a name="HDRVALSTR19">19-Byte Character Date and Time Value
|
|
Structure</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Offset</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="90%">Century. Possible values are 0, which
|
|
indicates years 19<em>xx</em>, 1, which indicates years 20<em>xx</em>
|
|
and so forth through 9, which indicates years 28<em>xx</em>.
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">1-6</td>
|
|
<td align="left" valign="top">Date, left-justified. This value cannot be all
|
|
blanks or all zeros. Left-justify Julian dates, using blanks to fill the
|
|
space.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">7-12</td>
|
|
<td align="left" valign="top">Time, in HHMMSS (hours, minutes, seconds)
|
|
format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">13-18</td>
|
|
<td align="left" valign="top">Microseconds. This value cannot be blanks.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRVALSTR20">20-Byte Character Date and Time Value
|
|
Structure</a></h3>
|
|
|
|
<p>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..</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Offset</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="10%">0-7</td>
|
|
<td align="left" valign="top" width="90%">Date, left-justified. This value
|
|
cannot be all blanks or all zeros. Left-justify Julian dates, using blanks to
|
|
fill the space.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">8-13</td>
|
|
<td align="left" valign="top">Time, in HHMMSS (hours, minutes, seconds)
|
|
format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">14-19</td>
|
|
<td align="left" valign="top">Microseconds. This value cannot be blanks.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDOSVAL">DOSGetDateTime Value Structure</a></h3>
|
|
|
|
<p>This table shows the structure used for the output variable.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Offset</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="90%">Hours (0-23)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">1</td>
|
|
<td align="left" valign="top">Minutes (0-59)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">2</td>
|
|
<td align="left" valign="top">Seconds (0-59)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">3</td>
|
|
<td align="left" valign="top">Hundredths of seconds (0-99)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">4</td>
|
|
<td align="left" valign="top">Day (1-31)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">5</td>
|
|
<td align="left" valign="top">Month (1-12)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">6-7</td>
|
|
<td align="left" valign="top">Year (for example, 1995)<sup>2</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">8-9</td>
|
|
<td align="left" valign="top">Time zone offset (in minutes)<sup>2, 3</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">10</td>
|
|
<td align="left" valign="top">Day of the week, where 0 is Sunday (0-6)<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><strong>Notes:</strong>
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="left" valign="top"><sup>1</sup></td>
|
|
<td align="left" valign="top">A 1-byte integer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><sup>2</sup></td>
|
|
<td align="left" valign="top">A 2-byte integer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><sup>3</sup></td>
|
|
<td align="left" valign="top">This is the negative value of the
|
|
offset associated with the specified output time zone. If *UTC is
|
|
specified for the output time zone, then this value will be 0. If an output
|
|
time zone is not specified, then this is the negative value of the
|
|
system value QUTCOFFSET.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3><a name="hdrtmzninfo">Time Zone Information Value Structure</a></h3>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Bytes returned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Bytes available</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Time zone description name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">19</td>
|
|
<td align="center" valign="top">13</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Current Daylight Saving Time indicator</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Current offset</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">CHAR(50)</td>
|
|
<td align="left" valign="top">Current full name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">74</td>
|
|
<td align="center" valign="top">4A</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Current abbreviated name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">84</td>
|
|
<td align="center" valign="top">54</td>
|
|
<td align="left" valign="top">CHAR(7)</td>
|
|
<td align="left" valign="top">Current message identifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">91</td>
|
|
<td align="center" valign="top">5B</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Message file name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">101</td>
|
|
<td align="center" valign="top">65</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Message file library</td>
|
|
</tr>
|
|
|
|
</table>
|
|
<br>
|
|
|
|
<h3>Field Descriptions</h3>
|
|
|
|
<p><strong>Bytes available.</strong> The number of bytes of data available to be
|
|
returned. All available data is returned if enough space is provided.</p>
|
|
|
|
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
|
|
|
|
<p><strong>Current abbreviated name.</strong> 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.</p>
|
|
|
|
<p><strong>Current Daylight Saving Time indicator.</strong> 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:</p>
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Daylight Saving Time is not being observed (Standard Time).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Daylight Saving Time is being observed.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Current full name.</strong> 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.</p>
|
|
|
|
<p><strong>Current message identifier.</strong> 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.</p>
|
|
|
|
<p><strong>Current offset.</strong> 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.
|
|
</p>
|
|
|
|
<p><strong>Message file library.</strong> The name of the library that contains
|
|
the message file. The field will contain all blanks if the current message identifier
|
|
is *NONE.</p>
|
|
|
|
<p><strong>Message file name.</strong> The name of the file that contains
|
|
the current message. The field will contain *NONE if the current message identifier
|
|
is *NONE.</p>
|
|
|
|
<p><strong>Reserved.</strong> An unused field.</p>
|
|
|
|
<p><strong>Time zone description name.</strong> 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.</p>
|
|
<br>
|
|
|
|
<h3><a name="HDRUSAGE">Usage Notes</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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).
|
|
</p>
|
|
|
|
<p>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).</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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. </p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
|
|
<br>
|
|
<br>
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1060 E</td>
|
|
<td align="left" valign="top">Date not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1061 E</td>
|
|
<td align="left" valign="top">Time not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1848 E</td>
|
|
<td align="left" valign="top">Century digit &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1849 E</td>
|
|
<td align="left" valign="top">
|
|
Millisecond or microsecond
|
|
value not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1850 E</td>
|
|
<td align="left" valign="top">Format &1 not valid</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24B4 E</td>
|
|
<td align="left" valign="top">Severe error while addressing parameter
|
|
list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C36 E</td>
|
|
<td align="left" valign="top">
|
|
Number of parameters, &1, for API not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C3C E</td>
|
|
<td align="left" valign="top">Value for parameter &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
|
<td align="left" valign="top">Literal value cannot be changed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9872 E</td>
|
|
<td align="left" valign="top">Program or service program &1 in library
|
|
&2 ended. Reason code &3.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
API introduced: V2R1
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
|
<a href="misc1.htm">Miscellaneous APIs</a> |
|
|
<a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|