*nullif

`*nullif`

Library: fbudf

Added in: 1.0 (Win), 1.5 (Linux)

Better alternative: Internal function NULLIF()

Description: The four *nullif functions – for integers, bigints, doubles and strings, respectively – each return the first argument if it is not equal to the second. If the arguments are equal, the functions return NULL.

Return type: Varies, see declarations.

Syntax:

inullif   (int1, int2)
i64nullif (bigint1, bigint2)
dnullif   (double1, double2)
snullif   (string1, string2)

As from Firebird 1.5, use of the new internal function NULLIF is preferred.

Warnings

These functions return NULL when the second argument is NULL, even if the first argument is a proper value. This is a wrong result. The NULLIF internal function doesn't have this bug.
i64nullif and dnullif will return wrong and/or bizarre results if it is not 100% clear to the engine that each argument is of the intended type (NUMERIC(18,0) or DOUBLE PRECISION). If in doubt, cast them both explicitly to the declared type (see declarations below).

Declarations:

DECLARE EXTERNAL FUNCTION inullif
   INT BY DESCRIPTOR, INT BY DESCRIPTOR
   RETURNS INT BY DESCRIPTOR
   ENTRY_POINT 'iNullIf' MODULE_NAME 'fbudf'

DECLARE EXTERNAL FUNCTION i64nullif
   NUMERIC(18,4) BY DESCRIPTOR, NUMERIC(18,4) BY DESCRIPTOR
   RETURNS NUMERIC(18,4) BY DESCRIPTOR
   ENTRY_POINT 'iNullIf' MODULE_NAME 'fbudf'

DECLARE EXTERNAL FUNCTION dnullif
   DOUBLE PRECISION BY DESCRIPTOR, DOUBLE PRECISION BY DESCRIPTOR
   RETURNS DOUBLE PRECISION BY DESCRIPTOR
   ENTRY_POINT 'dNullIf' MODULE_NAME 'fbudf'

DECLARE EXTERNAL FUNCTION snullif
   VARCHAR(100) BY DESCRIPTOR, VARCHAR(100) BY DESCRIPTOR,
   VARCHAR(100) BY DESCRIPTOR RETURNS PARAMETER 3
   ENTRY_POINT 'sNullIf' MODULE_NAME 'fbudf'