Weekend functions

functions for exploring weekend-conventions and incorporating into calendar and business date calculations. More...

Functions
int __stdcall	SFDB_ISVALIDWKND (LPCTSTR argCode)
	Assess whether the provided code adheres to the valid weekend convention (TRUE/FALSE).
int __stdcall	SFDB_WKNDCode (WORD argNumber, LPTSTR retVal, size_t *pLen)
	Create a seven-character string code for a specified weekend number (ranging from 1 to 7 or 11 to 17).
int __stdcall	SFDB_WKNDNo (LPCTSTR argCode, LPWORD retVal)
	Return the corresponding weekend-number (1-7 or 11-17) for a given weekend code.
int __stdcall	SFDB_ISWKND (LONG argDate, LPCTSTR holidays, LPLONG zDates, size_t nSize, WORD nWkndNo, WORD argOptions)
	Examine the given date whether it falls on a (short/long) weekend.
int __stdcall	SFDB_WKNDur (LONG argDate, LPCTSTR holidays, LPLONG zDates, size_t nSize, WORD nWkndNo, LPWORD retVal)
	Calculate the duration in calendar days of the long weekend that a given date falls on.
int __stdcall	SFDB_WKNDate (LONG argDate, LPCTSTR holidays, LPLONG zDates, size_t nSize, WORD nWkndNo, WORD argLWkndOption, WORD argDirection, LPLONG retVal)
	Calculate the serial date number for the first day of the next weekend (or the last day of the last weekend).

Detailed Description

As of Excel 2007, Microsoft supports different weekend occurrences in the international version of the date functions (e.g., WORKDAY.INTL). The weekend conventions are defined by either a number or a seven-character string (code).

Weekend conventions specify which days of the week are weekends. The weekend convention is defined by a weekend number (1-7 and 11-17) or a string. Weekend string values are seven characters long, and each character represents a day of the week, starting with Monday. 1 depicts a non-workday, and 0 represents a workday. Only the characters 1 and 0 are permitted in the string. 1111111 is an invalid string, for example.

The weekend number (and weekend string) values indicate the following weekend days:

Weekend-Number	Weekend Days	Weekend Code
1	Saturday, Sunday	0000011
2	Sunday, Monday	1000001
3	Monday, Tuesday	1100000
4	Tuesday, Wednesday	0110000
5	Wednesday, Thursday	0011000
6	Thursday, Friday	0001100
7	Friday, Saturday	0000110
11	Sunday only	0000001
12	Monday only	1000000
13	Tuesday only	0100000
14	Wednesday only	0010000
15	Thursday only	0001000
16	Friday only	0000100
17	Saturday only	0000010

Remarks

1. A weekend is said to be a long weekend if a holiday falls immediately before or after this weekend. NumXL has support for long and short weekends as of version 1.56 (Zebra).

References

• Hans-Peter Deutsch, Derivatives and Internal Models, Palgrave Macmillan (2002), ISBN 0333977068

Related Links

• Wikipedia - Workweek and weekend

• Wikipedia - Long weekend

Function Documentation

SFDB_ISVALIDWKND()

int __stdcall SFDB_ISVALIDWKND

(

LPCTSTR

argCode

)

Assess whether the provided code adheres to the valid weekend convention (TRUE/FALSE)

Parameters

[in]

argCode

(Required) is the given weekend code or number.

Returns

status code of the function call: NDK_TRUE, NDK_FALSE, and negative = error occurred.

Return values

NDK_TRUE	success (TRUE)
NDK_FALSE	success (FALSE)
NDK_INVALID_ARG	failed (see remarks)
NDK_INVALID_VALUE	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The weekend conventions and encodings are described here.
2. If the calendar module has not been initialized, the function will fail and return NDK_FAILED as the return code.
3. The function is available in the lite (free) version without any restrictions.
4. If the value of the argCode argument is NULL, the function will fails and return NDK_INVALID_ARG as error code.

Requirements

Requirement	Value
Target Platform	Windows
Header	SFDBM.h (include Windows.h)
Library	SFDBM.lib
DLL	SFDBM.dll SFLUC.dll SFLOG.dll

Since

v1.56

See also

• SFDB_WKNDCode
• SFDB_WKNDNo
• SFDB_ISWKND
• SFDB_WKNDur
• SFDB_WKNDate

SFDB_ISWKND()

int __stdcall SFDB_ISWKND	(	LONG	argDate,
		LPCTSTR	holidays,
		LPLONG	zDates,
		size_t	nSize,
		WORD	nWkndNo,
		WORD	argOptions )

Returns TRUE if the reference date falls on a (short/long) weekend.

Parameters

[in]	argDate	(Required) a serial date number that represents a given date.
[in]	holidays	(Optional) a (:_:) separated list of holiday codes.
[in]	zDates	(Optional) an array of holidays dates; each expressed as a serial number (i.e. number of days since 1.1.1970) .
[in]	nSize	(Required) the number of holiday dates in zDates.
[in]	nWkndNo	(Required) the weekend number (1-7, 11-17).
[in]	argOptions	(Required) is a switch to specify how to test for short or long weekends: Value Option 1 All (default) 2 Ignore holidays (same as (1), but treats long weekend as short) 3 Only short weekends 4 Only long weekends

Returns

status code of the function call: NDK_TRUE, NDK_FALSE, and negative = error occurred.

Return values

NDK_TRUE	success (TRUE)
NDK_FALSE	success (FALSE)
NDK_INVALID_ARG	failed (see remarks)
NDK_INVALID_VALUE	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The weekend conventions and encodings are described here.
2. If the calendar module has not been initialized, the function will fail and return NDK_FAILED as the return code.
3. The function is available in the lite (free) version without any restrictions.
4. If the value of the argDate argument does not correspond to a valid date serial number, the function will fails and return NDK_INVALID_ARG as error code.
5. If the value of the argOptions argument is greater than 4, the function will fails and return NDK_INVALID_VALUE as error code.

Requirements

Requirement	Value
Target Platform	Windows
Header	SFDBM.h (include Windows.h)
Library	SFDBM.lib
DLL	SFDBM.dll SFLUC.dll SFLOG.dll

Since

v1.56

See also

• SFDB_ISVALIDWKND
• SFDB_WKNDCode
• SFDB_WKNDNo
• SFDB_WKNDur
• SFDB_WKNDate

SFDB_WKNDate()

int __stdcall SFDB_WKNDate	(	LONG	argDate,
		LPCTSTR	holidays,
		LPLONG	zDates,
		size_t	nSize,
		WORD	nWkndNo,
		WORD	argLWkndOption,
		WORD	argDirection,
		LPLONG	retVal )

Calculate the serial date number for the first day of the next weekend (or the last day of the last weekend).

Parameters

[in]	argDate	(Required) a serial date number that represents a given date.
[in]	holidays	(Optional) a (:_:) separated list of holiday codes.
[in]	zDates	(Optional) an array of holidays dates; each expressed as a serial number (i.e. number of days since 1.1.1970) .
[in]	nSize	(Required) the number of holiday dates in zDates.
[in]	nWkndNo	(Required) the weekend number (1-7, 11-17).
[in]	argLWkndOption	(Required) a switch to specify how to test for short or long weekends: Value Option 1 All (default) 2 Ignore holidays (same as (1), but treats long weekend as short) 3 Only short weekends 4 Only long weekends
[in]	argDirection	(Required) a switch to select the return output (1 = next weekend (default), 2 = last weekend).
[out]	retVal	(Required) the serial date number of the next/previous weekend.

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success (TRUE)
NDK_INVALID_ARG	failed (see remarks)
NDK_INVALID_VALUE	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The weekend conventions and encodings are described here.
2. If the calendar module has not been initialized, the function will fail and return NDK_FAILED as the return code.
3. The function is available in the lite (free) version without any restrictions.
4. If the value of retVal is NULL, the function will fail and return NDK_INVALID_ARG as error code.
5. If the value of the argDate argument does not correspond to a valid date serial number, the function will fails and return NDK_INVALID_ARG as error code.

Demo

  long dt = 41030; // Tuesday May 1, 2012
  std::wstring szHolidays;
  WORD wkndNo = 1;    // (Saturday, Sunday) wkncode:  0000011
  WORD wkdOption = 1; // (1 = all (default), 2 = ignore holidays, 3 = only short weekends, 4 = only long weekends). 
  WORD direction = 1; // (1 = next weekend(default), 2 = last weekend).
  long lNextWknd = 0;
 
  // Next weekend
  int nRetCode = SFDB_WKNDate(dt, NULL, NULL, 0, wkndNo, wkdOption, direction, &lNextWknd);   //lNextWknd == 41034 (Saturday)
  if(nRetCode == NDK_SUCCESS){
    std::wcout << L" SUCCESS - SFDB_WKNDate for next weekend: " << lNextWknd << std::endl;
 
    // calculate duration of this weekend
    WORD wDur=0;
    nRetCode = SFDB_WKNDur (lNextWknd, NULL, NULL, 0, wkndNo, &wDur);  // wDur == 2
    if(nRetCode == NDK_SUCCESS){
      std::wcout << L" SUCCESS - the duration SFDB_WKNDur for a given weekend: " << wDur << std::endl;

    }
 
  }

Requirements

Requirement	Value
Target Platform	Windows
Header	SFDBM.h (include Windows.h)
Library	SFDBM.lib
DLL	SFDBM.dll SFLUC.dll SFLOG.dll

Since

v1.56

See also

• SFDB_ISVALIDWKND
• SFDB_WKNDCode
• SFDB_WKNDNo
• SFDB_ISWKND
• SFDB_WKNDur

Examples

wknd_date.cpp.

SFDB_WKNDCode()

int __stdcall SFDB_WKNDCode	(	WORD	argNumber,
		LPTSTR	retVal,
		size_t *	pLen )

Create a seven-character string code for a specified weekend number (ranging from 1 to 7 or 11 to 17).

Parameters

[in]	argNumber	(Required) The weekend number (1-7, 11-17).
[out]	retVal	(Optional) The buffer that will receive the string code.
[in,out]	pLen	(Required) The maximum number of characters to copy to the buffer.

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success (TRUE)
NDK_INVALID_ARG	failed (see remarks)
NDK_LENGTH_ERROR	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The weekend conventions and encodings are described here.
2. If the calendar module has not been initialized, the function will fail and return NDK_FAILED as the return code.
3. The function is available in the lite (free) version without any restrictions.
4. If the value of argNumber is not between 1 and 7 or 11 and 17, the function will fail and return NDK_INVALID_ARG as error code.
5. If the value of pLen is NULL, the function will fail and return NDK_INVALID_ARG as error code.
6. If the value of the retVal argument is NULL, the function returns NDK_SUCCESS and stores the required size of the data, in the variable pointed to by pLen. This enables an application to determine the best way to allocate a buffer for the value's data.
7. If the value of the retVal argument is not NULL, but the value in the variable pointed to by the pLen is zero(0), the function will fail and return NDK_INVALID_ARG as error code.
8. If the value of the retVal argument is not NULL, but the value in the variable pointed to by the pLen is less than 7, the function will fail and return NDK_LENGTH_ERROR as error code.

Requirements

Requirement	Value
Target Platform	Windows
Header	SFDBM.h (include Windows.h)
Library	SFDBM.lib
DLL	SFDBM.dll SFLUC.dll SFLOG.dll

Since

v1.56

See also

• SFDB_ISVALIDWKND
• SFDB_WKNDNo
• SFDB_ISWKND
• SFDB_WKNDur
• SFDB_WKNDate

SFDB_WKNDNo()

int __stdcall SFDB_WKNDNo	(	LPCTSTR	argCode,
		LPWORD	retVal )

Returns the weekend-number (1-7 or 11-17) for a given country or a weekend code.

Parameters

[in]	argCode	(Required) the weekend 7-character string code.
[out]	retVal	(Required) The weekend number (1-7, 11-17).

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success (TRUE)
NDK_INVALID_ARG	failed (see remarks)
NDK_INVALID_VALUE	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The weekend conventions and encodings are described here.
2. If the calendar module has not been initialized, the function will fail and return NDK_FAILED as the return code.
3. The function is available in the lite (free) version without any restrictions.
4. If the value of retVal is NULL, the function will fail and return NDK_INVALID_ARG as error code.
5. If the value of argCode is NULL, the function will fail and return NDK_INVALID_ARG as error code.

Requirements

Requirement	Value
Target Platform	Windows
Header	SFDBM.h (include Windows.h)
Library	SFDBM.lib
DLL	SFDBM.dll SFLUC.dll SFLOG.dll

Since

v1.56

See also

• SFDB_ISVALIDWKND
• SFDB_WKNDCode
• SFDB_ISWKND
• SFDB_WKNDur
• SFDB_WKNDate

SFDB_WKNDur()

int __stdcall SFDB_WKNDur	(	LONG	argDate,
		LPCTSTR	holidays,
		LPLONG	zDates,
		size_t	nSize,
		WORD	nWkndNo,
		LPWORD	retVal )

Calculate the duration in calendar days of the long weekend that a given date falls on.

Parameters

[in]	argDate	(Required) a serial date number that represents a given date.
[in]	holidays	(Optional) a (:_:) separated list of holiday codes.
[in]	zDates	(Optional) an array of holidays dates; each expressed as a serial number (i.e. number of days since 1.1.1970) .
[in]	nSize	(Required) the number of holiday dates in zDates.
[in]	nWkndNo	(Required) the weekend number (1-7, 11-17).
[out]	retVal	(Required) the number of calendar days in the given weekend.

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success (TRUE)
NDK_INVALID_ARG	failed (see remarks)
NDK_INVALID_VALUE	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The weekend conventions and encodings are described here.
2. If the calendar module has not been initialized, the function will fail and return NDK_FAILED as the return code.
3. The function is available in the lite (free) version without any restrictions.
4. If the value of retVal is NULL, the function will fail and return NDK_INVALID_ARG as error code.
5. If the value of the argDate argument does not correspond to a valid date serial number, the function will fails and return NDK_INVALID_ARG as error code.

Demo

    WORD wDur=0;
    nRetCode = SFDB_WKNDur (lNextWknd, NULL, NULL, 0, wkndNo, &wDur);  // wDur == 2
    if(nRetCode == NDK_SUCCESS){
      std::wcout << L" SUCCESS - the duration SFDB_WKNDur for a given weekend: " << wDur << std::endl;
 

Requirements

Requirement	Value
Target Platform	Windows
Header	SFDBM.h (include Windows.h)
Library	SFDBM.lib
DLL	SFDBM.dll SFLUC.dll SFLOG.dll

Since

v1.56

See also

• SFDB_ISVALIDWKND
• SFDB_WKNDCode
• SFDB_WKNDNo
• SFDB_ISWKND
• SFDB_WKNDate

Examples

wknd_date.cpp.