External Function Summary
Total Page:16
File Type:pdf, Size:1020Kb
APPENDIX I External Function Summary Conditional Logic Functions FBUDF INULLIF (VALUE1, VALUE2) Linux, Win32 Returns NULL for a sub-expression if it resolves to a non-null value; otherwise, returns the value of the sub-expression. Applicable to flxed numeric types only and should be used only with Firebird l.O.x. With Firebird 1.5 and higher, use internal function NULLIF( ). Arguments valuel: The column or expression that is tobe evaluated. value2: A constant or expression with which valuel is to be compared. Ifthere is a match, the iNulllf expressionwill return NULL. Return value Will be NULL if valuel and value2 resolve to a match; if there is no match, then value l is returned. Notes iNulllf( ) has an effect equivalent to using the internal SQL function NULLIF(), implemented in Firebird 1.5 and higher, with flxed numeric types. The iNulllf() external function comes in three implementations: two for 32-bit and 16-bit types (inullif and dnullif), the other for 64-bit types (i64nullif). Ifyou wanttobe able to use it with any flxed numeric type, declare all implementations. The declarations can be found in the script fbudf.sql, in the /UDF directory ofyour Firebird installation. Do not declare the i64nullif implementation in any database that does not support 64-bit numeries-in an unported InterBase 5 database, for example. Example This Statement will cause the STOCK value in the PRODUCTS table to be set to NULL on all rows where it is currently stored as 0: UPDATE PRODUCTS SET STOCK = iNULLIF(STOCK, o) Related or similar See also NULLIF( ), sNulllf( ). functions 881 Appendix! FBUDF INVL(VALUE1, VALUE2) Linux, Win32 This function attempts to mirnie the NVL( ) function of Oracle, for fiXed numerie types only. It will cause a specified non-null value tobe output if the column is actually storing a NULL. Arguments valuel: A column or expression involving a column. Floating-point typesarenot supported. Ifnecessary, use CAST() in your expression to transform the value to a numeric type. value2: An expression or constant that will resolve to the value which is to be output if value 1 resolves to NULL. Return value A non-null value. If valuel is not null, it is returned; otherwise, value2 is returned. Ifboth valuel and value2 resolve to NULL, then NULL is returned. Notes Logically, this function is equivalent to the simple form ofthe v.l.5 COALESCE( ) function when used with a column of a fixed numerie type, namely COALESCE(valuel, value2). It should be regarded as deprecated for versions of Firebird from 1.5 onward. The iNVL() external function comes in three implementations: two for 32-bit and 16-bit types (invl and dnvl), the other for 64-bit types (i64nvl). Ifyou wanttobe able to use itwith anyfixed numeric type, declare all implementations. The declarations can be found in the script tbudf.sql, in the /UDF directory ofyour Firebird installation. Do not declare the i64nvl implementation in any database that does not support 64-bit numeries-in an unported InterBase 5 database, for example. Example The following query outputs 0 if STOCK is NULL: SELECT PRODUCT_ID, PRODUCT_NAME, INVL(STOCK, o) FROM PRODUCTS; Related or similar See also sNVL( ), iNulllf( ), internal function COALESCE( ). functions FBUDF SNULLIF (VALUE1, VALUE2) Linux, Win32 Returns NULLfora sub-expression ifit resolves to a non-null value; otherwise, returns the value of the sub-expression. Applicable to character types only and should be used only with Firebird l.O.x. With Firebird 1.5 and higher, use NULLIF(). Arguments valuel: The column or expression that is tobe evaluated. value2: A constant or expression with which valuel is to be compared. If there is a match, the sNulllf expression will return NULL. 882 External Function Summary FBUDF SNULLIF (VALUE1, VALUE2) (continued) Return value Will be NULL if valuel and value2 resolve to a match. If there is no match, then valuel is returned. Notes sNullif() has an effect equivalent to using the internal SQL function NULLIF( ), implemented in Firebird 1.5 and higher, with character types. Example This query will set the column IS_REGISTERED to NULL in all rows where its value is 'T' and REGISTRATION_DATE is NULL: UPDATE ATABLE SET IS_REGISTERED = SNULLIF(IS_REGISTERED, 'T') WHERE REGISTRATION_DATE IS NULL; Related or similar See also iNulllf( ). For Firebird 1.5 and higher, see internal function functions NULLIF(). FBUDF SNVL(VALUE1, VALUE2) Linux, Win32 This function attempts to mirnie the NVL() function of Oracle, for character types only. It will cause a specified non-null value to be output if the column is actually storing a NULL. Arguments valuel: A column or expression involving a column. value2: An expression or constant that will resolve to the value that is to be output if valuel resolves to NULL. Return value A non-null value. If valuel is not null, it is returned; otherwise, value2 is returned. If both valuel and value2 resolve to NULL, then NULL is returned. Notes Logically, this function is equivalent to the simple form of the v.l.5 COALESCE() function when used with a column of a character type, namely COALESCE(valuel, value2). sNVL( ) should be regarded as deprecated for versions of Firebird from 1.5 onward. Example The following query calculates and outputs a runtime column, BIRTH_yEAR, for each student. Where this value resolves to NULL, the string "Not known" is output instead: SELECT FIRST_NAME, LAST_NAME, SNVL(CAST(EXTRACT(YEAR FROM BIRTH_DATE) AS VARCHAR(9)), 'Not known') AS BIRTH YEAR FROM STUDENT_REGISTER; Related or similar See also iNVL( ) , sNulllf(), internal function COALESCE( ) . functions 883 Appendix! Mathematical Functions IB_UDF ABS{VALUE) Linux, Win32 Returns the absolute value of a number. Arguments value is column or expression that is compatible with a signed or unsigned DOUBLE PRECISION NUMBER. Return value A DOUBLE PRECISION number. Example This statementwill calculate a total of values that are negative and return it as a positive value: SELECT ABS(SUM(ASSET_VALUE)) AS LIABILITY FROM ASSET REGISTER WHERE ASSET_VALUE < o; Similar function See f_DoubleAbs( )-another external function that performs the sametask. IB_UDF BIN_AND{VALUE1, VALUE2) Linux, Win32 Returns the result of a bitwise AND operation performed on the two input values. Arguments valuel and value2 are columns or expressions that evaluate to SMALLINT or INTEGER type. Return value An INTEGER number. Example SELECT BIN_AND(128,24) AS ANDED RESULT FROM RDB$DATABASE; IB_UDF BIN_OR{VALUE1, VALUE2) Linux, Win32 Returns the result of a binary (bitwise) OR operation performed on the two input values. Arguments valuel and value2 are columns or expressions that evaluate to SMALLINT or INTEGER type. Return value An INTEGER number. Example SELECT BIN_OR(128,24) AS ORED_RESULT FROM RDB$DATABASE; IB_UDF BIN_XOR{VALUE1, VALUE2) Linux, Win32 Returns the result of a binary (bitwise exclusive or) XOR operation performed on the two input values. Arguments valuel and value2 are columns or expressions that evaluate to SMALLINT or INTEGER type. 884 Externat Function Summary IB_UDF BIN_XOR(VALUE1, VALUE2) (continued) Return value An INTEGER number. Example SELECT BIN_XOR(128,24) AS EXORED_RESULT FROM RDB$DATABASE; IB_UDF CEILING(VALUE) Linux, Win32 Returns a DOUBLE PRECISION value representing the smallest integer that is greater than or equal to the input value. Arguments value is a column or expression that evaluates to a number of DOUBLE PRECISION type. Return value A DOUBLE PRECISION number with a zero decimal part. Example SELECT CEILING(LAST_TOTAL) AS ROUND_UP_NEAREST FROM SALES_HISTORY; IB_UDF DIV(VALUE1, VALUE2) Linux, Win32 Divides the two integer inputs and returns the quotient, discarding the decimal part. Arguments valuel and value2 are columns or expressions that evaluate to numbers of SMALLINT or INTEGER type. Return value A DOUBLE PRECISION number with a zero decimal part. Notes The function behaves almost like integer-by-integer division in databases created in dialect 3-the distinction being that the division returns a double. Example SELECT DIV(TERM, (CURRENT_DATE - START_DATE)/365) AS YEARS REMAINING FROM MORTGAGE ACCOUNT WHERE ACCOUNT_ID = 12345; FBUDF DPOWER(VALUE, EXPONENT) Linux, Win32 Takes a number and an exponent and returns to exponential value. Arguments value: A column or expression that evaluates to a number of type DOUBLE PRECISION. exponent A column or expression that evaluates to a number of type DOUBLE PRECISION. Return value Returns the exponential value as a DOUBLE PRECISION number. Example SELECT DPOWER(2.64575,2) AS NEARLY_7 FROM RDB$DATABASE; Related or similar See also SQRT( ). functions 885 Appendix! FREEUDFLIB F_DOUBLEABS(VALUE} Win32 Returns the absolute value of a floating-point number. Arguments value is a column or expression that evaluates to a nurober of type DOUBLE PRECISION or FLOAT. Return value A positive nurober oftype DOUBLE PRECISION. Example SELECT ABS(SUM(ASSET_VALUE)) AS LIABILITY FROM ASSET REGISTER WHERE ASSET_VALUE < 0; Related or similar See also ABS( ), another external function that performs the same functions task and is available on non-Windows platforms. FREEUDFLIB F_ISDVISIBLEBY(VALUE1, VALUE2} Win32 Determines whether a value is evenly divisibly by another value. Returns 1 if Numerator (valuel) is evenly divisible by Denominator (value2); otherwise, returns 0. Arguments valuel: A column or expression that evaluates to an integer type, the nurober that is be divided (the numerator). value2: Another integer, the nurober to use as the denominator. Return value Returns 1 ifTrue, 0 ifFalse. Example This function could be called in a CHECK constraint as follows: ALTER TABLE ORDER DETAIL ADD CONSTRAINT CHECK MULTIPLE CHECK (ISDIVISIBLEBY(ORDER_QTY, PACK_QTY) = 1); Such a check might be used for validation where multiple pre packaged units are priced on a per-unit basis, rather than per-pack. FREEUDFLIB F_MODULO(VALUE1, VALUE2) Win32 Modulo function-returns the remainder from a division between two integers. Arguments valuel and value2 are columns or expressions that evaluate to numbers of SMALLINT or INTEGER type.