Overview of $Date functions: Difference between revisions
(→Usage) |
m (minor cleanup) |
||
(8 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
==Syntax== | |||
<p> | <p> | ||
The <var>$Date</var> functions — <var>[[$Date]]</var>, <var>[[$DateJ]]</var>, <var>[[$DateP]]</var> — accept two input arguments:</p> | |||
<p class="syntax">$Date(<span class="term">year-format</span>, <span class="term">fill-character</span>) | <p class="syntax">$Date(<span class="term">year-format</span>, <span class="term">fill-character</span>) | ||
</p> | </p> | ||
Where | Where: | ||
<ul> | <ul> | ||
<li>The <var class="term">year-format</var> argument controls the format of the year | <li>The <var class="term">year-format</var> argument controls the format of the returned year value; month and day formats depend on the individual $function. The following are the valid <var class="term">year-format</var> input values and their result:</li> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
Line 35: | Line 34: | ||
</table> | </table> | ||
<p> | <p> | ||
CYY represents the century-year format. The first digit represents the century since 1900. The CYY format can be manipulated using the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter. </p> | <var>CYY</var> represents the century-year format. The first digit represents the century since 1900. The <var>CYY</var> format can be manipulated using the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter. </p> | ||
</li> | </li> | ||
Line 48: | Line 47: | ||
<tr> | <tr> | ||
<td>$date(2,' ')</td> | <td>$date(2,' ')</td> | ||
<td> | <td>CYY MM DD</td> | ||
<td>113 07 11</td> | <td>113 07 11</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>$date(0,' | <td>$date(0,'z')</td> | ||
<td> | <td>YYzMMzDD</td> | ||
<td>13z07z11</td> | <td>13z07z11</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>$ | <td>$DateJ(1,'-')</td> | ||
<td> | <td>YYYY-DDD</td> | ||
<td>2013-192</td> | <td>2013-192</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>$ | <td>$DateJ(1,'')</td> | ||
<td> | <td>YYYYDDD</td> | ||
<td>2013192</td> | <td>2013192</td> | ||
</tr> | </tr> | ||
Line 73: | Line 72: | ||
</ul> | </ul> | ||
==Usage== | |||
<p> | <p> | ||
$DateChg, $ | <var>[[$DateChg]]</var>, <var>[[$DateChk]]</var>, <var>[[$DateCnv]]</var>, and <var>[[$DateDif]]</var> recognize a format of <var>CYY</var> as representing the century-year format as returned from the <var>$Date</var> function. Conversion to and from the <var>CYY</var> format is fully supported. </p> | ||
<p> | <p> | ||
In addition, if <code>CUSTOM=1</code> is added to the User 0 CCAIN stream or set later using the RESET command, the following occurs: If a CYY date format is specified for conversion and only a YY input is supplied, the conversion is successfully completed by using the <var>[[CENTSPLT parameter|CENTSPLT]]</var> and <var>[[ | In addition, if <code>CUSTOM=1</code> is added to the User 0 CCAIN stream or set later using the <var>RESET</var> command, the following occurs: If a <var>CYY</var> date format is specified for conversion and only a <var>YY</var> input is supplied, the conversion is successfully completed by using the <var>[[CENTSPLT parameter|CENTSPLT]]</var> and <var>[[BASECENT parameter|BASECENT]]</var> parameters. </p> | ||
==Examples== | |||
<ul> | <ul> | ||
<li> | <li>If <code>CUSTOM=1</code>, <code>BASECENT=19</code>, and <code>CENTSPLT=95</code>, then: | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
<th>Print | <th>Print statement</th> | ||
<th> | <th>Result</th> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','96001')</p></td> | ||
<td align="right">19960101</td> | <td align="right"><p>19960101</p></td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','196001')</p></td> | ||
<td align="right"><p>20960101</p></td> | |||
<td align="right">20960101</td> | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','95001')</p></td> | ||
<td align="right">19950101</td> | <td align="right"><p>19950101</p></td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','095001')</p></td> | ||
<td align="right">19950101</td> | <td align="right"><p>19950101</p></td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
</li> | </li> | ||
<li>If CUSTOM=1 is omitted, BASECENT=19, and CENTSPLT=95, then: | <li>If <code>CUSTOM=1</code> is omitted, <code>BASECENT=19</code>, and <code>CENTSPLT=95</code>, then: | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
<th>Print | <th>Print statement</th> | ||
<th> | <th>Result</th> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','96001')</p></td> | ||
<td><b></b>******</td> | <td><p><b></b>******</p></td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','196001')</p></td> | ||
<td align="right">20960101</td> | <td align="right"><p>20960101</p></td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','95001')</p></td> | ||
<td><b></b>******</td> | <td><p><b></b>******</p></td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><p class="codeInTable">Print $DateCnv('CYYDDD','YYYYMMDD','095001')</p></td> | ||
<td>19950101</td> | <td><p>19950101</p></td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
</li> | </li> | ||
<li>If <code>CUSTOM=2</code> is added to the User 0 CCAIN stream or set later using the <var>RESET</var> command, the following occurs: If a CYY-format is specified for output conversion and the C indicator is zero, then C is eliminated. This is true for all $Date function calls. For example: | <li>If <code>CUSTOM=2</code> is added to the User 0 CCAIN stream or set later using the <var>RESET</var> command, the following occurs: If a <var>CYY</var>-format is specified for output conversion and the <var>C</var> indicator is zero, then <var>C</var> is eliminated. This is true for all <var>$Date</var> function calls. For example: | ||
<p> | <p> | ||
If CUSTOM=2, then: <code> | If <code>CUSTOM=2</code>, then: <code>Print $Datej(2)</code> prints <code>97.001</code>.</p> | ||
<p>But if CUSTOM=2 is omitted, then <code> | <p> | ||
But if <code>CUSTOM=2</code> is omitted, then <code>Print $Datej(2)</code> prints <code>097.001</code>.</p> | |||
</li> | </li> | ||
</ul> | </ul> | ||
==Julian dates== | |||
<p>The Julian date is a 4-byte, packed decimal formatted as follows:</p> | <p> | ||
The Julian date is a 4-byte, packed decimal formatted as follows:</p> | |||
<p class="code">0CYYDDDF | <p class="code">0CYYDDDF | ||
</p> | </p> | ||
<p>Where:</p> | <p>Where:</p> | ||
<ul> | <ul> | ||
<li>0 is a reserved filler</li> | <li>0 is a reserved filler.</li> | ||
<li>C represents the century since 1900. For example: | <li><var>C</var> represents the century since 1900. For example: | ||
<p> | <p> | ||
C=0 represents years 1900-1999</p> | <code>C=0</code> represents years 1900-1999.</p> | ||
<p> | <p> | ||
C=1 represents years 2000-2099</p> | <code>C=1</code> represents years 2000-2099.</p> | ||
</li> | </li> | ||
<li>YY is 2-byte year</li> | <li><var>YY</var> is 2-byte year.</li> | ||
<li>DDD is 3-byte day</li> | <li><var>DDD</var> is 3-byte day.</li> | ||
<li>F is positive sign nibble for packed decimal | <li><var>F</var> is positive-sign nibble for packed decimal. </li> | ||
</li> | |||
</ul> | </ul> | ||
==Routines available for user-written date $functions== | |||
<p> | <p> | ||
CCALL entry points | CCALL entry points are added: <code>DATE</code>, <code>DATE3</code>, and <code>DATE4</code>. All routines must be called with T1 pointing to a 26-byte answer area. [[Contacting Rocket Software Technical Support|Technical Support]] recommends that you allocate the answer area using the <code>VARS=(name, len)</code> pushdown list variable of the ENTER macro. (See [[Customizing functions and translation tables]] for more information on the ENTER macro.) </p> | ||
<p> | <p> | ||
The current date and time are stored in the area with this format:</p> | The current date and time are stored in the area with this format:</p> | ||
Line 182: | Line 181: | ||
<tr> | <tr> | ||
<td>DATE</td> | <td>DATE</td> | ||
<td> | <td>YY.DDD MON DD HH.MM.SS</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>DATE3</td> | <td>DATE3</td> | ||
<td> | <td>CYY.DDD MON DD HH.MM.SS</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>DATE4</td> | <td>DATE4</td> | ||
<td> | <td>YYYY.DDD MON DD HH.MM.SS</td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
<p>All registers are returned intact with the exception of the DATE and DATE4 calls. The DATE and DATE4 calls change only the T4 register, returning a number representing the current month (1-12).</p> | <p> | ||
<p>DATE returns 24 bytes, DATE3 returns 25 bytes, and DATE4 returns 26 bytes.< | All registers are returned intact with the exception of the <code>DATE</code> and <code>DATE4</code> calls. The <code>DATE</code> and <code>DATE4</code> calls change only the T4 register, returning a number representing the current month (1-12).</p> | ||
<p> | |||
<code>DATE</code> returns 24 bytes, <code>DATE3</code> returns 25 bytes, and <code>DATE4</code> returns 26 bytes. </p> | |||
<p class="note"><b>Note:</b> There are two spaces before and after <code>MON DD</code>.</p> | |||
[[Category:SOUL]] | [[Category:SOUL]] |
Latest revision as of 20:26, 6 October 2015
Syntax
The $Date functions — $Date, $DateJ, $DateP — accept two input arguments:
$Date(year-format, fill-character)
Where:
- The year-format argument controls the format of the returned year value; month and day formats depend on the individual $function. The following are the valid year-format input values and their result:
- The fill-character argument indicates a 1-byte fill character to place between the date components, as in the following examples:
Code example Return format Example: July 11, 2013 $date(2,' ') CYY MM DD 113 07 11 $date(0,'z') YYzMMzDD 13z07z11 $DateJ(1,'-') YYYY-DDD 2013-192 $DateJ(1,'') YYYYDDD 2013192
year-format input | Return format | Example: Year 2013 displayed as... |
---|---|---|
0 | YY | 13 |
1 | YYYY | 2013 |
2 | CYY | 113 (The first digit represents the century since 1900) |
CYY represents the century-year format. The first digit represents the century since 1900. The CYY format can be manipulated using the CUSTOM parameter.
Usage
$DateChg, $DateChk, $DateCnv, and $DateDif recognize a format of CYY as representing the century-year format as returned from the $Date function. Conversion to and from the CYY format is fully supported.
In addition, if CUSTOM=1
is added to the User 0 CCAIN stream or set later using the RESET command, the following occurs: If a CYY date format is specified for conversion and only a YY input is supplied, the conversion is successfully completed by using the CENTSPLT and BASECENT parameters.
Examples
- If
CUSTOM=1
,BASECENT=19
, andCENTSPLT=95
, then:Print statement Result Print $DateCnv('CYYDDD','YYYYMMDD','96001')
19960101
Print $DateCnv('CYYDDD','YYYYMMDD','196001')
20960101
Print $DateCnv('CYYDDD','YYYYMMDD','95001')
19950101
Print $DateCnv('CYYDDD','YYYYMMDD','095001')
19950101
- If
CUSTOM=1
is omitted,BASECENT=19
, andCENTSPLT=95
, then:Print statement Result Print $DateCnv('CYYDDD','YYYYMMDD','96001')
******
Print $DateCnv('CYYDDD','YYYYMMDD','196001')
20960101
Print $DateCnv('CYYDDD','YYYYMMDD','95001')
******
Print $DateCnv('CYYDDD','YYYYMMDD','095001')
19950101
- If
CUSTOM=2
is added to the User 0 CCAIN stream or set later using the RESET command, the following occurs: If a CYY-format is specified for output conversion and the C indicator is zero, then C is eliminated. This is true for all $Date function calls. For example:If
CUSTOM=2
, then:Print $Datej(2)
prints97.001
.But if
CUSTOM=2
is omitted, thenPrint $Datej(2)
prints097.001
.
Julian dates
The Julian date is a 4-byte, packed decimal formatted as follows:
0CYYDDDF
Where:
- 0 is a reserved filler.
- C represents the century since 1900. For example:
C=0
represents years 1900-1999.C=1
represents years 2000-2099. - YY is 2-byte year.
- DDD is 3-byte day.
- F is positive-sign nibble for packed decimal.
Routines available for user-written date $functions
CCALL entry points are added: DATE
, DATE3
, and DATE4
. All routines must be called with T1 pointing to a 26-byte answer area. Technical Support recommends that you allocate the answer area using the VARS=(name, len)
pushdown list variable of the ENTER macro. (See Customizing functions and translation tables for more information on the ENTER macro.)
The current date and time are stored in the area with this format:
Code entry point | Format used for storing... |
---|---|
DATE | YY.DDD MON DD HH.MM.SS |
DATE3 | CYY.DDD MON DD HH.MM.SS |
DATE4 | YYYY.DDD MON DD HH.MM.SS |
All registers are returned intact with the exception of the DATE
and DATE4
calls. The DATE
and DATE4
calls change only the T4 register, returning a number representing the current month (1-12).
DATE
returns 24 bytes, DATE3
returns 25 bytes, and DATE4
returns 26 bytes.
Note: There are two spaces before and after MON DD
.