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

Parameter	Description	Format	Default Value
Date	Specifies the date. 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.	Script literal or script variable	n.a.
PeriodFormat	Defines the type of period to use for the calculation. 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.	Script literal or script variable	n.a.
OutputFormat	(Optional) Date format for the returned value.	Script literal or script variable	YYMMDD
Calendar, Calendar Event	(Optional) Name of the Calendar object and Calendar Event to take into account to calculate the beginning of the period. For more information, see Calendars (CALE). Note: If you do not specify a Calendar object and Calendar Event, you can omit the commas.	AE name, script literal, or script variable	n.a.

Important Considerations

Key considerations include:

Important: Include all commas when you specify a Calendar object and Calendar Event, even if you omit the OutputFormat parameter.
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).

Return Codes

The FIRST_OF_PERIOD function returns the date of the period start in the specified format, or one of the following error codes:

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.

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

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

: 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