The Sir2000 APPDATE command

Overview

The APPDATE 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 APPDATE 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 APPDATE clocks are preferred to the Model 204 SYSDATE 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 for a list of the values that are affected by the APPDATE command. See APPDATE command usage notes for descriptions of several common testing scenarios and how to use APPDATE to handle them, including testing the effect of changing the date into the future for any of the following:

A single user's session
All users' sessions
All users' sessions except selected ones
All users of a given APSY
All users of all APSYs, except selected APSYs

In most contexts when describing APPDATE, 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.

APPDATE addresses many of the needs to test a SOUL application at some date in the future, notably beyond the end of the 1900s. APPDATE 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. APPDATE 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 APPDATE 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.

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

A single invocation of the APPDATE command can set APPDATE values or display APPDATE values. If you want to examine the APPDATE values in effect, use the syntax described in Examining the APPDATE information. The detailed explanation of setting APPDATE 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 APPDATE command is shown in Complete syntax of the APPDATE command.

Setting clocks with the APPDATE command

The two APPDATE 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 SYSDATE parameter cannot be specified if the APPDATE 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:

The current time of the clock being set
The time that would be current when the internal clock is at some specific reference time

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 USER clock:

State	Meaning
INTERNAL	Applications use the `INTERNAL` clock.
ON	Applications use the `USER` clock.
OFF (the default)	Applications use the `INTERNAL` clock unless the `SYSTEM` clock is on (the default `SYSTEM` clock is off).

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 USER or SYSTEM clock may be set by the APPDATE 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 APPDATE command, without changing the time of the USER or SYSTEM clock:

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

Syntax terms

USER | SYSTEM Optional specification of which clock is being modified. Defaults to USER. The USER clock specifies the running user's APPDATE clock. The SYSTEM clock specifies the APPDATE clock used for any user with an APPDATE USER clock that is OFF.

ON | OFF | INTERNAL

Optional. APPDATE USER ON indicates that the user clock is used by the current user. APPDATE SYSTEM ON indicates that the system clock is used by all users whose user clock is OFF. OFF and INTERNAL both indicate that the specified clock is not visible.

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

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

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

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

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

targdate [targtime]
[AT refdate [reftime]]

targdate 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 targdate and the optional targtime, and the reference datetime. The reference datetime can be omitted, in which case the reference datetime is the datetime when the APPDATE command is issued.

If reftime is specified, targtime must also be. If targtime is specified, then either refdate must be omitted or reftime must be specified. If targtime is omitted, the clock is shifted the number of days between targdate and refdate.

A successful APPDATE SYSTEM 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 OFF state.

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

Error handling control with DATE_ERR

The APPDATE command with the DATE_ERR keyword and the $Sir_Date_Err 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.

APPDATE DATE_ERR and $Sir_Date_Err detect the following errors:

Invalid datetime format specification
Datetime string not matching format
Datetime out of range for the format
Invalid CENTSPAN value
Datetime out of range for CENTSPAN/SPANSIZE combination

You can set the default error handling for all $functions in the system with an APPDATE SYSTEM DATE_ERR command. You can override this setting for an individual user with an APPDATE USER DATE_ERR command. You can override both settings for the duration of a SOUL request with the $Sir_Date_Err 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 $Sir_Date_Err or APPDATE.

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

Setting default error handling with the APPDATE command

The APPDATE command may be used to set and change the default for processing performed when a datetime $function detects an error.

USER | SYSTEM

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.

OFF | CANCEL | REPORT | IGNORE

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.

DEBUG | NODEBUG

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:

CANCEL	DEBUG
REPORT	DEBUG
IGNORE	NODEBUG
OFF	There is no DEBUG/NODEBUG setting at the level.

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

Both the USER and SYSTEM level defaults can be overridden by the setting of the $Sir_Date_Err 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 $Sir_Date_Err error handling is initially OFF. If $Sir_Date_Err('OFF') 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 APPDATE command and $Sir_Date_Err 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

$Sir_Date_Err 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 $Sir_Date_Err invocation persists until the end of the SOUL request, at which time its setting is reset to OFF. Note that $Sir_Date_Err 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 APPDATE 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 APPDATE 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]

ALL | USER | SYSTEM

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 APPDATE 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.

APPDATE DISPLAY ALL is not suitable for placing in a global and re-invoking; you should use APPDATE DISPLAY {USER | SYSTEM} for that purpose. The display format of APPDATE DISPLAY ALL 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 APPDATE DISPLAY {USER | SYSTEM} forms of the command produce results in the form of a legal APPDATE command that would set the levels to their current values. For example, the following lines would result from invocations of the APPDATE DISPLAY USER and APPDATE DISPLAY SYSTEM 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 $Sir_Date_Err 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 $Sir_Date_Err 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:

'OFF'
'CANCEL'
'REPORT'
'IGNORE'

Privileges, disabling, and pre-User 0 APPDATE command

The APPDATE SYSTEM 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; APPDATE USER and APPDATE DISPLAY can be issued by any user. APPDATE SYSTEM can also be used in the CCAIN input stream before the User 0 parameter line, so that the system-wide APPDATE clock and error handling can be set prior to any calculations performed by an IODEV 3 thread. Neither APPDATE USER nor APPDATE DISPLAY may be used before the User 0 parameter line.

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

You can also disable or restrict the APPDATE 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 APPDATE 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 APPDATE 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 APPDATE values is described separately for clock values (see Setting clocks with the APPDATE comman) and datetime argument error handling (see 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 APPDATE command is shown below:

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

Syntax terms

Level	USER \| SYSTEM
Clock_set	`Clock_state` \| [`Clock_state`] `Date_times`
Clock_state	ON \| OFF \| INTERNAL
Date_times	{ `targdate` [AT `refdate`] \| `targdate targtime` [AT `refdate reftime`] }
Err_set	DATE_ERR { [OFF\|CANCEL\|REPORT\|IGNORE] \| [DEBUG\|NODEBUG] } Note: {`OFF\|CANCEL\|REPORT\|IGNORE`} or {`DEBUG\|NODEBUG`} must be specified with `DATE_ERR`.
Display	DISPLAY [ALL \| USER \| SYSTEM]

As discussed in Privileges, disabling, and pre-User 0 APPDATE command:

An APPDATE SYSTEM command must be issued in the User 0 input stream or by a system manager; an error message is produced if APPDATE SYSTEM is processed in other contexts.
An APPDATE RESTRICT command must be issued in the User 0 input stream; an error message is produced if APPDATE RESTRICT is processed in other contexts.
The APPDATE 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.
Issuing an APPDATE command in a disabled or restricted context produces an error message but does no checking or processing of the command.

Values affected by the APPDATE clocks

The active APPDATE clock affects the value returned by the following SOUL $functions:

$Date, $DateJ, $DateP
$DateDif, $DateCnv, and $DayI (when obtaining the year for handling the CENTSPLT argument)
$Time
$Sir_Date, $Sir_DateN, $Sir_DateND, $Sir_DateNM, $Sir_DateS, $SirTime, and $Web_Date
$Web_Last_Modified (when ensuring last-modified date isn't future)
$Sir_DateChg, $Sir_DateChk, $Sir_DateCnv, $Sir_DateDif, $Sir_Date2N, $Sir_Date2ND, $Sir_Date2NM, $Sir_Date2NS, $Db_RpcParam, $Srv_Bind, and $Srv_Parmset (when obtaining the year for relative CENTSPAN handling)

The only Model 204 command affected by the APPDATE clock is the RESET command for changing the CENTSPLT user parameter. In this case, the BASECENT parameter, which is calculated using the current time, obtains the current time from the active APPDATE clock. The resulting value of BASECENT can be used to interpret 2-digit years passed to the following SOUL $functions:

$DateDif, $DateCnv, and $DayI, if neither the CENTSPLT nor DEFCENT arguments are provided
$DateChg and $DateChk

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

APPDATE command usage notes

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.
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.
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 DEFCENT; see item 6, below.
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 APPDATE value and can do this using the $CommndL function, since an sdaemon thread initiated with $COMMxxx copies the application clock of its invoker.
A good date for APPDATE testing might be 2000/02/29, since that is a valid date, but 1900/02/29 is not.
The use of the APPDATE command is to establish a clock for all application-level operations. It does not affect static values that had been established prior to the APPDATE command. This is relevant to the value of the BASECENT parameter and the default value of the DEFCENT user parameter, as follows:
- If the DEFCENT parameter has not been set, its value is the first two digits of the year during Model 204 initialization. An APPDATE SYSTEM ON ... command issued before the User 0 parameter line affects the default value of DEFCENT. All other invocations of the APPDATE command leave DEFCENT unaffected.
- The BASECENT parameter is calculated based on the current time whenever the CENTSPLT parameer is set. This current time is taken from the active APPDATE clock, but subsequent invocations of the APPDATE command do not affect the BASECENT parameter.
The APPDATE command does not affect the date and time printed on header 0 of each output page.
The APPDATE command and the use of the Model 204 SYSDATE parameter are mutually exclusive.
$Command, $CommBg, and $CommndL (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 APPDATE USER settings from the thread that invoked the $function will be in effect. If an APPDATE USER command is issued in the sdaemon thread, its effect is not reflected back to the invoking thread.
The current application date used by #DATExxx functions in FUEL is set to the active APPDATE clock when the $FunLoad function is used.

The Sir2000 APPDATE command

Contents

Overview

Setting clocks with the APPDATE command

APPDATE syntax to set USER or SYSTEM clock

APPDATE syntax to change state of USER or SYSTEM clock

Syntax terms

Error handling control with DATE_ERR

Setting default error handling with the APPDATE command

Setting default error handling with the $Sir_Date_Err function

Examining the APPDATE information

APPDATE DISPLAY command

Retrieving last non-null $Sir_Date_Err setting

Privileges, disabling, and pre-User 0 APPDATE command

Complete syntax of the APPDATE command

Syntax

Syntax terms

Values affected by the APPDATE clocks

APPDATE command usage notes

See also

Navigation menu