FIRST_OF_PERIOD

Use the FIRST_OF_PERIOD script function to return the first day of the period for a specified date.The period can be a year, quarter, month or week. The script function lets you specify the date format for the returned date. Optionally specify a Calendar Event to consider for the calculation.

Syntax

FIRST_OF_PERIOD ([DateFormat:]Date, PeriodFormat[, OutputFormat[, Calendar, Calendar Event]])

Parameters

FIRST_OF_PERIOD
Determines the first day of a period for a specified date
Date
Specifies the date
Format: script literal or script variable
Note: Specify the date format when you use a format other than YYMMDD or YYYYMMDD. Separate the date format and the date with a colon or semicolon. For more information, see Date, Time and Period Formats in Scripts.
PeriodFormat
Defines the type of period to use for the calculation
Format:script literal or script variable
Tip: Different weekly period formats are available depending on whether the week starts on Sunday or Monday. For more information, see Date, Time and Period Formats in Scripts.
OutputFormat
(Optional) Date format for the returned value
Format:script literal or script variable
Default: YYMMDD
Calendar, Calendar Event
(Optional) Name of the Calendar object and Calendar Event to take into account to calculate the beginning of the period
More Information: Calendars (CALE)
Format: AE name, script literal or script variable
Note: If you do not specify a Calendar object and Calendar Event, you can omit the commas.

Important! Include all commas when you specify a Calendar object and Calendar Event, even if you omit the OutputFormat parameter.

Return Codes

The script function has the following return values:

Date of the period start in the specified format
20327
Calendar object does not exist
20328
Calendar Event does not exist in the Calendar object
20456
Calendar Event does not include the start date of the period

Note: If you specify a Calendar object and Calendar Event, the script function returns the correct calendar day of the period. If there is no valid calendar day for this period, the result is a zero date in the specified date format (example: 0000-00-00).

Tip: Use the :ON_ERROR script statement to define action to take when an error occurs. For more information, see Script Elements for Error Handling.

Examples

These examples return the date of the first day of a period, given a particular date, and print the result in the activation report.

March 29, 2000 was a Wednesday. The following script specifies a period format (WW) that defines Monday as the first day of the week.

:SET &DATE# = FIRST_OF_PERIOD ("000329","WW","DD.MM.YY")
:PRINT &DATE#

Line in the activation report:

2019-03-28 13:38:28 - U00020408 27.03.00

The following script uses the WS period format to define that the week starts with Sunday. The example uses the same date as in the previous example. In this example, the script specifies the date format because the date is provided in a different format than the default.

:SET &DATE# = FIRST_OF_PERIOD ("DD.MM.YY:29.03.00","WS","DD.MM.YY")
:PRINT &DATE#

Line in the activation report:

2019-03-28 13:51:02 - U00020408 26.03.00

The following example assumes you have a Calendar object called READINESS that contains an Event (WEEKDAY) which includes only weekdays, not weekends. The script returns the first weekday of the quarter that the specified date lies in.

:SET &DATE# = FIRST_OF_PERIOD ("190329", "Q", , READINESS, WEEKDAY)
:PRINT &DATE#

Line in the activation report:

2019-03-28 13:51:02 - U00020408 01.01.19