Goff: Remover spurious line feed

2022-11-14T20:42:33Z

Remover spurious line feed

← Older revision		Revision as of 20:42, 14 November 2022
Line 117:		Line 117:
	<tr><th nowrap><i>targdate</i> [<i>targtime</i>] <br>[AT <i>refdate</i> [<i>reftime</i>]]</th>		<tr><th nowrap><i>targdate</i> [<i>targtime</i>] <br>[AT <i>refdate</i> [<i>reftime</i>]]</th>
	<td><var class="term">targdate</var> is required;, the rest are optional. These phrases allow you to specify the date and time of the application clock. The dates are specified in YYYY/MM/DD format, and the times are specified in HH:MI:SS format. <p>		<td><var class="term">targdate</var> is required;, the rest are optional. These phrases allow you to specify the date and time of the application clock. The dates are specified in YYYY/MM/DD format, and the times are specified in HH:MI:SS format. <p>
	The application clocks continue to run so that they are a constant difference from		The application clocks continue to run so that they are a constant difference from the internal date and time. This difference is the difference between the target datetime, as specified by <var class="term">targdate</var> and the optional <var class="term">targtime</var>, and the reference datetime. The reference datetime can be omitted, in which case the reference datetime is the datetime when the <var>APPDATE</var> command is issued. </p>
	the internal date and time. This difference is the difference between the target datetime, as specified by <var class="term">targdate</var> and the optional <var class="term">targtime</var>, and the reference datetime. The reference datetime can be omitted, in which case the reference datetime is the datetime when the <var>APPDATE</var> command is issued. </p>
	<p>		<p>
	If <var class="term">reftime</var> is specified, <var class="term">targtime</var> must also be. If <var class="term">targtime</var> is specified, then either <var class="term">refdate</var> must be omitted or <var class="term">reftime</var> must be specified. If <var class="term">targtime</var> is omitted, the clock is shifted the number of days between <var class="term">targdate</var> and <var class="term">refdate</var>. </p></td></tr>		If <var class="term">reftime</var> is specified, <var class="term">targtime</var> must also be. If <var class="term">targtime</var> is specified, then either <var class="term">refdate</var> must be omitted or <var class="term">reftime</var> must be specified. If <var class="term">targtime</var> is omitted, the clock is shifted the number of days between <var class="term">targdate</var> and <var class="term">refdate</var>. </p></td></tr>

JAL: /* Error handling control with DATE_ERR */ add link

2018-02-08T21:19:10Z

Error handling control with DATE_ERR: add link

New page

==Overview==
The <var>APPDATE</var> command provides control over the operation of date and time oriented SOUL $functions. It supports a system-wide or user-level clock that is used to obtain date and time values. It can be used to control the default handling of errors detected by datetime $functions, allowing the logging of error messages and request cancellation. The <var>APPDATE</var> command allows you to control these defaults at a user and system level, significantly reducing your effort to detect some date errors.

For application testing, the <var>APPDATE</var> clocks are preferred to the Model 204 <var>[[SYSDATE parameter|SYSDATE]]</var> parameter, which is much less flexible and which greatly complicates the ability to do things such as share procedure files or read-only data files in the testing environment.

See [[#Values affected by the APPDATE clocks|Values affected by the APPDATE clocks]] for a list of the values that are affected by the <var>APPDATE</var> command. See [[#APPDATE command usage notes|APPDATE command usage notes]] for descriptions of several common testing scenarios and how to use <var>APPDATE</var> to handle them, including testing the effect of changing the date into the future for any of the following:

<ul>
<li>A single user's session </li>
<li>All users' sessions </li>
<li>All users' sessions except selected ones </li>
<li>All users of a given [[APSY]] </li>
<li>All users of all APSYs, except selected APSYs </li>
</ul>

In most contexts when describing <var>APPDATE</var>, these Sir2000 User Language Tools pages speak of a "date and time" or simply of a "time" (which is the same thing). Generally, for Y2K testing, you are only concerned about setting a "date," that is, setting the clock to a particular day.

<var>APPDATE</var> addresses many of the needs to test a SOUL application at some
date in the future, notably beyond the end of the 1900s. <var>APPDATE</var> lets you make these tests with your current version of Model 204, and without modifying the Model 204 internal date-related data structures, such as the File Parameter List, page trailers, and the Procedure Dictionary. <var>APPDATE</var> does not affect any file level operations such as recovery or DUMP, or the ability to open a file with different application date settings.

The system-wide and user-level clocks specified by the <var>APPDATE</var> command are called APPDATE clocks. In order to use these clocks, you must set the date (and optionally the time) of the system level or the user level clock. The syntax associated with setting these APPDATE clocks is described in [[#Setting the clocks with the APPDATE command|Setting the clocks with the APPDATE command]].

Another important component in a testing environment, or indeed in a production
environment, is the ability to detect unanticipated errors. The <var>APPDATE</var> command with a <var>DATE_ERR</var> clause and the <var>$Sir_Date_Err</var> function allow you to change the default error handling of arguments to date and time oriented $functions. The syntax associated with <var>DATE_ERR</var> is described in [[#Error handling control with DATE_ERR|Error handling control with DATE_ERR]].

A single invocation of the <var>APPDATE</var> command can set <var>APPDATE</var> values or display <var>APPDATE</var> values. If you want to examine the <var>APPDATE</var> values in effect, use the syntax described in [[#Examining the APPDATE information|Examining the APPDATE information]]. The detailed explanation of setting <var>APPDATE</var> values is described separately for clock values
and datetime argument error handling, but for a single level you can specify both clock values and error handling, in that order, in a single command.

The complete syntax of the <var>APPDATE</var> command is shown in [[#Complete syntax of the APPDATE command|Complete syntax of the APPDATE command]].

==Setting clocks with the APPDATE command==

The two <var>APPDATE</var> clocks (user and system) effectively run in parallel with the internal clock, that is, the time that Model 204 obtains from the CPU.

Note: The <var>SYSDATE</var> parameter cannot be specified if the <var>APPDATE</var> command is used. 

When you set either of the clocks, you are actually setting the amount that the clock runs ahead of the internal clock. You do that by specifying either of these: 
<ul>
<li>The current time of the clock being set </li>

<li>The time that would be current when the internal clock is at some specific reference time </li>
</ul>

In addition to the time setting of the clocks, you control which clock an application uses. This is determined primarily by the "state" of the <var>USER</var> clock:

<table class="thJustBold">
<tr class="head"><th>State</th><th>Meaning</th></tr>

<tr><th>INTERNAL</th>
<td>Applications use the <var>INTERNAL</var> clock. </td></tr>

<tr><th>ON</th>
<td>Applications use the <var>USER</var> clock. </td></tr>

<tr><th nowrap>OFF (the default) </th>
<td>Applications use the <var>INTERNAL</var> clock unless the
<var>SYSTEM</var> clock is on (the default <var>SYSTEM</var> clock is off). </td></tr>
</table>

The clock used to satisfy an application request for date or time is determined as shown in the following figure:

Source of date returned to $function
 *----------------------------------------------------------*
* Application code requests date *
* (datetime $functions) *
*----------------------------------------------------------*
|
|-> Gets date/time from the USER clock if it is ON
| (example: APPDATE USER ON 2001/01/01)
|
|-> Else from SYSTEM clock if it is ON and USER clock is OFF
| example: APPDATE USER OFF (default)
| and APPDATE SYSTEM ON 1999/12/31
|
|-> Else from INTERNAL clock:
example: APPDATE USER INTERNAL
or
APPDATE USER OFF
and APPDATE SYSTEM OFF
or
APPDATE USER OFF
and APPDATE SYSTEM INTERNAL 

===APPDATE syntax to set USER or SYSTEM clock===

The time of the <var>USER</var> or <var>SYSTEM</var> clock may be set by the <var>APPDATE</var> command:

APPDATE [USER|SYSTEM] [ON|OFF|INTERNAL] -
targdate [targtime] -
[AT refdate [reftime]] 

===APPDATE syntax to change state of USER or SYSTEM clock===

Whether or not a particular clock is used can be controlled by the <var>APPDATE</var> command, without changing the time of the <var>USER</var> or <var>SYSTEM</var> clock:

APPDATE [USER|SYSTEM] { ON|OFF|INTERNAL } 

===Syntax terms===
<table class="thJustBold">
<tr><th>USER | SYSTEM</th>
<td>Optional specification of which clock is being modified. Defaults to <var>USER</var>. The <var>USER</var> clock specifies the running user's <var>APPDATE</var> clock. The <var>SYSTEM</var> clock specifies the <var>APPDATE</var> clock used for any user with an <var>APPDATE</var> <var>USER</var> clock that is <var>OFF</var>. </td></tr>

<tr><th>ON | OFF | INTERNAL</th>
<td>Optional. <code>APPDATE USER ON</code> indicates that the user clock is used by the current user. <code>APPDATE SYSTEM ON</code> indicates that the system clock is used by all users whose user clock is <var>OFF</var>. <var>OFF</var> and <var>INTERNAL</var> both indicate that the specified clock is not visible.

If the user-level clock is set to <var>ON</var>, SOUL $function values are obtained from the user-level clock. 

If the user-level clock is set to <var>INTERNAL</var>, SOUL $function values are obtained from the internal clock. 

If the user-level clock is set to <var>OFF</var>, SOUL $function values depend on the setting of the system-wide clock: if it is <var>ON</var>, they are obtained from the system-wide clock; otherwise (it is <var>OFF</var> or <var>INTERNAL</var>) they are obtained from the internal clock. 

If this phrase is omitted in an <var>APPDATE</var> command that sets the time of a
clock, the state of that clock is set to <var>ON</var>. 

You can specify <var>ON</var>, <var>OFF</var>, or <var>INTERNAL</var> without a date, in which case the date/time in a clock is not changed, but the visibility of the corresponding clock is affected. </td></tr>

<tr><th nowrap>targdate [targtime] [AT refdate [reftime]]</th>
<td><var class="term">targdate</var> is required;, the rest are optional. These phrases allow you to specify the date and time of the application clock. The dates are specified in YYYY/MM/DD format, and the times are specified in HH:MI:SS format. 
The application clocks continue to run so that they are a constant difference from
the internal date and time. This difference is the difference between the target datetime, as specified by <var class="term">targdate</var> and the optional <var class="term">targtime</var>, and the reference datetime. The reference datetime can be omitted, in which case the reference datetime is the datetime when the <var>APPDATE</var> command is issued. 

If <var class="term">reftime</var> is specified, <var class="term">targtime</var> must also be. If <var class="term">targtime</var> is specified, then either <var class="term">refdate</var> must be omitted or <var class="term">reftime</var> must be specified. If <var class="term">targtime</var> is omitted, the clock is shifted the number of days between <var class="term">targdate</var> and <var class="term">refdate</var>. </td></tr>
</table>

A successful <code>APPDATE SYSTEM</code> command has an immediate effect upon the date/time returned by SOUL $functions for all threads that have user-level clocks set or defaulted to the <var>OFF</var> state. 

The default value of the system-wide clock and all user-level clocks is <var>OFF</var>, with the same datetime as the internal clock. Hence, if the only command you issue is <code>APPDATE SYSTEM yyyy/mm/dd</code>, you will immediately shift the value returned as the current date by SOUL $functions. The <var>APPDATE</var> <var>USER</var> clock is reset to <var>OFF</var>, with the same time as the <var>INTERNAL</var> clock, when a user logs off. 

==Error handling control with DATE_ERR==
The <var>APPDATE</var> command with the <var>DATE_ERR</var> keyword and the <var>[[$Sir_Date_Err]]</var> function let you decide what default action the system takes if an error is detected by a datetime $function. This lets you control validation of dates in your applications, significantly reducing your effort to detect and correct date errors.

<var>APPDATE DATE_ERR</var> and <var>$Sir_Date_Err<var> detect the following errors:
<ul>
<li>Invalid datetime format specification </li>
<li>Datetime string not matching format </li>
<li>Datetime out of range for the format </li>
<li>Invalid CENTSPAN value </li>
<li>Datetime out of range for CENTSPAN/SPANSIZE combination </li>
</ul>

You can set the default error handling for all $functions in the system with an <code>APPDATE SYSTEM DATE_ERR</code> command. You can override this setting for an individual user with
an <code>APPDATE USER DATE_ERR</code> command. You can override both settings for the duration of a SOUL request with the <var>$Sir_Date_Err</var> function. If you are using the Sirius datetime $functions, you can also supply a parameter on the individual
function call to control error handling, overriding the default set by <var>$Sir_Date_Err</var> or <var>APPDATE</var>. 

The processing performed when a datetime function encounters an error is determined
using the precedence indicated in the following figure:

Datetime $function argument error handling 
 *----------------------------------------*
* Datetime $function argument error *
*----------------------------------------*
|
|-> IGNORE is error handling handling arg:
| return error value
|
|-> REPORT is error handling arg:
| issue message, return error value
|
|-> Error handling supplied, and not OFF:
| issue message, cancel request
|
++ Else OFF is error handling arg, or none:
|
|-> $SIR_DATE_ERR('REPORT') last invoked:
| issue message, return error value
|
|-> $SIR_DATE_ERR('IGNORE') last invoked:
| return error value
|
|-> $SIR_DATE_ERR('CANCEL') last invoked:
| issue message, cancel request
|
++ Else error handling controlled by APPDATE:
|
|-> USER DATE_ERR REPORT:
| issue message, return error value
|
|-> USER DATE_ERR IGNORE:
| return error value
|
|-> USER DATE_ERR CANCEL:
| issue message, cancel request
|
|-> USER DATE_ERR OFF (default) and
| SYSTEM DATE_ERR REPORT
| issue message, return error value
|
|-> USER DATE_ERR OFF (default) and
| SYSTEM DATE_ERR IGNORE
| return error value
|
|-> USER DATE_ERR OFF (default) and
| SYSTEM DATE_ERR CANCEL
| issue message, cancel request
|
++ Else error handling not affected
| by Sir2000 User Language Tools:
|
+---> return error value 

===Setting default error handling with the APPDATE command===
The <var>APPDATE</var> command may be used to set and change the default for processing performed when a datetime $function detects an error.
APPDATE [USER|SYSTEM] DATE_ERR -
[OFF | CANCEL | REPORT | IGNORE] -
[DEBUG | NODEBUG]

<table class="thJustBold">
<tr><th>USER | SYSTEM</th>
<td>Optional specification of the scope for the current command, defaults to USER. The USER error handling overrides the SYSTEM error handling. Both USER and SYSTEM error handling are initially OFF. </td></tr>

<tr><th>OFF | CANCEL | REPORT | IGNORE</th>
<td>This is optional. OFF indicates that there is no default error handling at the
given level. CANCEL indicates that the default error handling at the given level is issuing an error message describing the error and cancelling the User Language request. REPORT indicates that the default error handling at the given level is issuing an error message describing the error and returning an error indicator. IGNORE indicates that the default error handling at the given level is returning an error indicator. </td></tr>

<tr><th nowrap>DEBUG | NODEBUG</th>
<td>If DEBUG is specified, any datetime error message produced at the given level (user or system) will include the name of the procedure file, the procedure name, and the line number within the procedure for the affected $function invocation.

If neither DEBUG nor NODEBUG is specified, then OFF, CANCEL, REPORT, or IGNORE must be specified, in which case the default DEBUG/NODEBUG setting is determined from the following table: 
<table class="thJustBold">
<tr><th>CANCEL</th>
<td>DEBUG </td></tr>

<tr><th>REPORT</th>
<td>DEBUG</td></tr>

<tr><th>IGNORE</th>
<td>NODEBUG</td></tr>

<tr><th>OFF</th>
<td>There is no DEBUG/NODEBUG setting at the level.</td></tr>
</table>

Since the initial DATE_ERR setting is OFF, there is no DEBUG/NODEBUG
setting, at both SYSTEM and USER levels. </td></tr>
</table>

Both the USER and SYSTEM level defaults can be overridden by the setting of the
<var>$Sir_Date_Err</var> function, which in turn is overridden by supplying a non-default value
for the error handling argument, if a $Sir_Datexxx $function is in use. The
<var>$Sir_Date_Err</var> error handling is initially OFF. If <code>$Sir_Date_Err('OFF')</code> is in effect,
the USER level handling controls default error handling, unless it is OFF, in which case the SYSTEM level controls the default. 
Note: The <var>APPDATE</var> command and <var>$Sir_Date_Err</var> set only the default datetime argument error handling. This will affect the standard SOUL date $functions, and it will affect the $Sir_Datexxx and Sir2000 $functions if they are coded without the error handling argument. 

===Setting default error handling with the $Sir_Date_Err function===
<var>[[$Sir_Date_Err]]</var> provides the ability to set or override default datetime $function error handling at the request level:
%s string len 8
%s = $sir_date_er('REPORT') 

The effect of a <var>$Sir_Date_Err</var> invocation persists until the end of the SOUL request, at which time its setting is reset to <var>OFF</var>. Note that <var>$Sir_Date_Err</var> only sets
the default datetime argument error handling. It will affect the standard SOUL date $functions, and
it will affect the $Sir_Datexxx $functions if they are coded without the error handling argument. 

==Examining the APPDATE information==
The Sir2000 User Language Tools provide mechanisms for displaying and saving the
state of the <var>APPDATE</var> clocks and various DATE_ERR switches. Thus, it is possible for applications to retrieve the current states, temporarily change the states and then restore the previous states.

===APPDATE DISPLAY command===
The following form of the <var>APPDATE</var> command allows you to view the setting of either the USER or SYSTEM clock, and to view the error handling setting:
APPDATE DISPLAY [ALL|USER|SYSTEM]


<table class="thJustBold">
<tr><th nowrap>ALL | USER | SYSTEM</th>
<td>This is optional. It specifies to display the current time and error handling setting for all levels, or to display either the USER or SYSTEM level in a form that is equivalent to the <var>APPDATE</var> command which set it.

ALL is the default and prints the current internal time, the
clock ON|OFF|INTERNAL settings for both USER and
SYSTEM, the DATE_ERR settings of both USER and
SYSTEM, what the current times would be for the clocks if
they were in effect, and an indication of which clock and
which error handling setting is active for the current user.
Following this is the display of the USER and SYSTEM levels
in the "command setting" form, that is, the command that was
issued to set the level. </td></tr>
</table>

<code>APPDATE DISPLAY ALL</code> is not suitable for placing in a global and re-invoking; you should use <code>APPDATE DISPLAY {USER | SYSTEM}</code> for that purpose. The display
format of <code>APPDATE DISPLAY ALL</code> is shown in the following example:

 LEVEL CLOCK STATE/DATE_ERR CURRENT CLOCK
-------- ----------------------- ------------------------
INTERNAL 1997/05/14 11:27:51
SYSTEM ON/OFF 2000/01/02 11:27:51 (@)
USER OFF/CANCEL DEBUG 1997/05/14 11:27:51 (*)
SYSTEM CLOCK ACTIVE (@); USER LEVEL IS ERROR HANDLING DEFAULT (*)
COMMAND SETTINGS:
APPDATE SYSTEM ON 2000/01/01 AT 1997/05/13 DATE_ERR OFF
APPDATE USER OFF 1997/05/13 AT 1997/05/13 DATE_ERR CANCEL DEBUG 

The <code>APPDATE DISPLAY {USER | SYSTEM}</code> forms of the command produce results in the form of a legal <var>APPDATE</var> command that would set the levels to their current
values. For example, the following lines would result from invocations of the <code>APPDATE DISPLAY USER</code> and <code>APPDATE DISPLAY SYSTEM</code> commands in the same context as above:

APPDATE SYSTEM ON 2000/01/01 AT 1997/05/13 DATE_ERR OFF
APPDATE USER OFF 1997/05/13 AT 1997/05/13 DATE_ERR CANCEL DEBUG 

===Retrieving last non-null $Sir_Date_Err setting===

You can call <var>$Sir_Date_Err</var> with no argument or with the null string, and it will return a character string indicating the most recent valid and non-null value specified in a call to <var>$Sir_Date_Err</var> during the current request. 

For example:

%s string len 8
%s = $sir_date_err( <no argument> | '' ) 

Such a call will return one of the following strings: 
<ul>
<li>'OFF' </li>
<li>'CANCEL' </li>
<li>'REPORT' </li>
<li>'IGNORE' </li>
</ul>

==Privileges, disabling, and pre-User 0 APPDATE command==
The <code>APPDATE SYSTEM</code> form of the command can be issued only by User 0 (user zero, that is, in the CCAIN input stream) or by a user with system manager privileges;
<code>APPDATE USER</code> and <code>APPDATE DISPLAY</code> can be issued by any user. <code>APPDATE SYSTEM</code> can also be used in the CCAIN input stream before the User 0 parameter line,
so that the system-wide <var>APPDATE</var> clock and error handling can be set prior to any calculations performed by an IODEV 3 thread. Neither <code>APPDATE USER</code> nor <code>APPDATE DISPLAY</code> may be used before the User 0 parameter line.

An <code>APPDATE RESTRICT</code> command can be used to prohibit any issuance of the
<var>APPDATE</var> command except prior to the User 0 parameter line. This could be used if you do not want anyone to change the <var>APPDATE</var> settings after initialization of the Model 204 run. The <code>APPDATE RESTRICT</code> command itself can only be issued before the User 0 parameter line. 

You can also disable or restrict the <var>APPDATE</var> command by applying a customization zap. You might use a customization zap like the following if, for example, you wanted to disallow the use of the <var>APPDATE</var> command in a production load module: 
 * If you apply the following zap, any APPDATE
* command will cause an error message to be
* issued and the command otherwise is ignored.
*
* Note: this example assumes you have no other
* customization zaps; if you do, include those
* bits in the VER and REP data.
*
NAME ONLINE SIRK$
VER 070E 00
REP 070E 80
* ------------- End of zap -------------------- 

Or a zap like the following, if you want to only allow one system-wide <var>APPDATE</var> setting for the entire Model 204 run:

 * If you apply the following zap, the APPDATE
* command is only allowed prior to the user zero
* parameter line, and any other use of APPDATE
* will cause an error message to be issued and
* the command otherwise is ignored.
*
* Note: this example assumes you have no other
* customization zaps; if you do, include those
* bits in the VER and REP data.
*
NAME ONLINE SIRK$
VER 070E 00
REP 070E 40
* ------------- End of zap --------------------

Note: Lines are not sent to the Model 204 audit trail for commands (and subsequent error messages) issued prior to the User 0 parameter line. Output is sent to CCAPRINT for such commands, however. 

==Complete syntax of the APPDATE command==
The detailed explanation of setting <var>APPDATE</var> values is described separately for clock values (see [[#Setting clocks with the APPDATE command|Setting clocks with the APPDATE comman]]) and
datetime argument error handling (see [[#Error handling control with DATE_ERR|Error handling control with DATE_ERR]]). However, for the USER or SYSTEM level you can specify both clock values and error handling, in that order, in a single command.

===Syntax===

The complete syntax of the <var>APPDATE</var> command is shown below: 

APPDATE { Level Clock_set [Err_set] | Level Err_set | Display | RESTRICT } 

===Syntax terms===
<table>
<tr><th>Level</th>
<td>USER | SYSTEM </td></tr>

<tr><th>Clock_set</th>
<td><var class="term">Clock_state</var> | [<var class="term">Clock_state</var>] <var class="term">Date_times</var> </td></tr>

<tr><th>Clock_state</th>
<td>ON | OFF | INTERNAL </td></tr>

<tr><th>Date_times</th>
<td>{ <var class="term">targdate</var> [AT <var class="term">refdate</var>]
| <var class="term">targdate targtime</var> [AT <var class="term">refdate reftime</var>] } </td></tr>

<tr><th>Err_set </th>
<td>DATE_ERR { [OFF|CANCEL|REPORT|IGNORE] | [DEBUG|NODEBUG] } 
Note: {<var>OFF|CANCEL|REPORT|IGNORE</var>} or {<var>DEBUG|NODEBUG</var>} must be specified with <var>DATE_ERR</var>.</td></tr>

<tr><th>Display </th>
<td>DISPLAY [ALL | USER | SYSTEM] </td></tr>
</table>

As discussed in [[#Privileges, disabling, and pre-User 0 APPDATE command|Privileges, disabling, and pre-User 0 APPDATE command]]: 
<ul>
<li>An <code>APPDATE SYSTEM</code> command must be issued in the User 0 input stream or by a system manager; an error message is produced if <code>APPDATE SYSTEM</code> is processed in other contexts. </li>

<li>An <code>APPDATE RESTRICT</code> command must be issued in the User 0 input stream; an error message is produced if <code>APPDATE RESTRICT</code> is processed in other contexts. </li>

<li>The <var>APPDATE</var> command can also be completely disabled, or restricted to the User 0 input stream before the User 0 parameter line, by using a customization zap. </li>

<li>Issuing an <var>APPDATE</var> command in a disabled or restricted context produces an error message but does no checking or processing of the command. </li>
</ul>

==Values affected by the APPDATE clocks==
The active <var>APPDATE</var> clock affects the value returned by the following SOUL $functions:
<ul>
<li><var>$Date</var>, <var>$DateJ</var>, <var>$DateP</var> </li>

<li><var>$DateDif</var>, <var>$DateCnv</var>, and <var>$DayI</var> (when obtaining the year for handling the <var>CENTSPLT</var> argument) </li>

<li><var>$Time</var> </li>

<li><var>$Sir_Date</var>, <var>$Sir_DateN</var>, <var>$Sir_DateND</var>, <var>$Sir_DateNM</var>, <var>$Sir_DateS</var>, <var>$SirTime</var>, and <var>$Web_Date</var> </li>

<li><var>$Web_Last_Modified</var> (when ensuring last-modified date isn't future) </li>

<li><var>$Sir_DateChg</var>, <var>$Sir_DateChk</var>, <var>$Sir_DateCnv</var>, <var>$Sir_DateDif</var>, <var>$Sir_Date2N</var>, <var>$Sir_Date2ND</var>, <var>$Sir_Date2NM</var>, <var>$Sir_Date2NS</var>, <var>$Db_RpcParam</var>, <var>$Srv_Bind</var>, and <var>$Srv_Parmset</var> (when obtaining the year for relative <var>CENTSPAN</var> handling) </li>
</ul>

The only Model 204 command affected by the <var>APPDATE</var> clock is the <var>RESET</var> command for changing the <var>CENTSPLT</var> user parameter. In this case, the <var>BASECENT</var> parameter, which is calculated using the current time, obtains the current time from the active
<var>APPDATE</var> clock. The resulting value of <var>BASECENT</var> can be used to interpret 2-digit years passed to the following SOUL $functions: 
<ul>
<li><var>$DateDif</var>, <var>$DateCnv</var>, and <var>$DayI</var>, if neither the <var>CENTSPLT</var> nor <var>DEFCENT</var> arguments are provided </li>

<li><var>$DateChg</var> and <var>$DateChk</var> </li>
</ul>

Finally, the default value of <var>DEFCENT</var> is taken from the active <var>APPDATE</var> clock if the <var>APPDATE</var> command is issued before the User 0 parameter line.


==APPDATE command usage notes==
<ol>
<li>One kind of application testing is simply to see what happens when dates into the
21st century are returned by SOUL $functions. This can be done in
isolation by issuing a command such as the following:
APPDATE USER 2000/01/01 

This can be simply issued by the user before entering the application, or it can be
issued in the startup or logon proc of the application.</li>

<li>If your application stores results that are retrieved later by the application, you should probably put a command such as the following into the startup proc:
APPDATE USER 2000/01/01 AT 1997/05/01 

This indicates that the application clock will run ahead of the internal date and time so that on the 1st of May, 1997, the application clock will show the 1st of January, 2000. Your application can thus run as if it were "shifted" ahead in time, and the shift amount will be consistent, even if you bring down the online and bring it up again. It is recommended that you place it in the startup procedure in case any dates are referenced in it.</li>

<li>If you want all applications (except those "shielded" as in item 5, below) to use the same clock, you need not change any applications but simply code before the User 0 parameter line:
APPDATE SYSTEM 2000/01/01 AT 1997/05/01 

Note that this also changes the default <var>DEFCENT</var>; see item 6, below. </li>

<li>If you have an application that must use the internal date and time, even if the system-wide application clock is ON, you should enter a command such as the
following in the startup procedure:
APPDATE USER INTERNAL 

This could be needed by an application that examines internal datetime values,
such as those found in the audit trail. A robust application will preserve the
<var>APPDATE</var> value and can do this using the <var>[[$CommndL]]</var> function, since an [[Sdaemons|sdaemon]] thread initiated with $COMMxxx copies the application clock of its invoker. </li>

<li>A good date for <var>APPDATE</var> testing might be <code>2000/02/29</code>, since that is a valid date, but <code>1900/02/29</code> is not. </li>

<li>The use of the <var>APPDATE</var> command is to establish a clock for all application-level operations. It does not affect static values that had been established prior to the <var>APPDATE</var> command. This is relevant to the value of the <var>BASECENT</var> parameter and the default value of the <var>DEFCENT</var> user parameter, as follows:
<ul>
<li>If the <var>DEFCENT</var> parameter has not been set, its value is the first two digits of the year during Model 204 initialization. An <code>APPDATE SYSTEM ON ...</code> command issued before the User 0 parameter line affects the default value of <var>DEFCENT</var>. All other invocations of the <var>APPDATE</var> command leave <var>DEFCENT</var> unaffected. </li>

<li>The <var>BASECENT</var> parameter is calculated based on the current time whenever the <var>CENTSPLT</var> parameer is set. This current time is taken from the active <var>APPDATE</var> clock, but subsequent invocations of the <var>APPDATE</var> command do not affect the <var>BASECENT</var> parameter. </li>
</ul></li>

<li>The <var>APPDATE</var> command does not affect the date and time printed on header 0 of each output page. </li>

<li>The <var>APPDATE</var> command and the use of the Model 204 <var>SYSDATE</var> parameter are mutually exclusive. </li>

<li><var>$Command</var>, <var>$CommBg</var>, and <var>$CommndL</var> (see [[List_of_$functions]]) provide a mechanism for passing a unit of work to an sdaemon or background thread that is different from the thread that issues the request.

When the requested unit of work receives control, the <code>APPDATE USER</code> settings from the thread that invoked the $function will be in effect. If an <code>APPDATE USER</code> command is issued in the sdaemon thread, its effect is not reflected back to the invoking thread. </li>

<li>The current application date used by <var>#DATExxx</var> functions in [[FUEL]] is set to the active <var>APPDATE</var> clock when the <var>$FunLoad</var> function is used. </li>
</ol>

==See also==
{{Template:Sir2000 topic list}}

[[Category: Sir2000 User Language Tools]]

The Sir2000 APPDATE command - Revision history

Goff: Remover spurious line feed

Admin: 1 revision imported

JAL: /* Error handling control with DATE_ERR */ add link

← Older revision	Revision as of 22:00, 8 February 2018
(No difference)