Your SlideShare is downloading. ×
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Using DB2 Functions
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Using DB2 Functions

558

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
558
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
9
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. IN THIS CHAPTER CHAPTER 3 • Column Functions • Scalar Functions Using DB2 Functions • The RAISE_ERROR Function • MQSeries Built-in Functions • XML Publishing Built-in Functions Two types of built-in functions can be applied to data in a DB2 table using SQL: column functions and scalar functions. • Built-in Function Guidelines You can use these functions to further simplify the require- ments of complex data access. NOTE DB2 also provides the capability for users to create their own functions. This capability, called user-defined functions, is discussed in-depth in Chapter 4, “Using DB2 User-Defined Functions and Data Types.” Functions are called by specifying the function name and any required operands. A built-in function can be used any place an expression can be used (with some exceptions). Column Functions Column functions compute, from a group of rows, a single value for a designated column or expression. This provides the capability to aggregate data, thereby enabling you to perform statistical calculations across many rows with one SQL statement. To fully appreciate the column functions, you must understand SQL’s set-level processing capabilities. This list shows some rules for the column functions: • Column functions can be executed only in SELECT state- ments. • A column function must be specified for an explicitly named column or expression. • Each column function returns only one value for the set of selected rows. • If you apply a column function to one column in a SELECT statement, you must apply column functions to
  • 2. Column Functions 111 any other columns specified in the same SELECT statement, unless you also use the GROUP BY clause. • Use GROUP BY to apply a column function to a group of named columns. Any other column named in the SELECT statement must be operated on by a column function. • The result of any column function (except the COUNT and COUNT_BIG functions) will have the same data type as the column to which it was applied. The COUNT function returns an integer number; COUNT_BIG returns a decimal number. • The result of any column function (except the COUNT and COUNT_BIG functions) can be null. COUNT and COUNT_BIG always return a numeric result. 3 • Columns functions will not return a SQLCODE of +100 if the predicate specified in the WHERE clause finds no data. Instead, a null is returned. For example, consider the following SQL statement: SELECT MAX(SALARY) FROM DSN8810.EMP WHERE EMPNO = ‘999999’; There is no employee with an EMPNO of ‘999999’ in the DSN8810.EMP table. This statement therefore returns a null for the MAX(SALARY). Of course, this does not apply to COUNT and COUNT_BIG, both of which always return a value, never a null. • When using the AVG, MAX, MIN, STDDEV, SUM, and VARIANCE functions on nullable columns, all occurrences of null are eliminated before applying the function. • You can use the DISTINCT keyword with all column functions to eliminate duplicates before applying the given function. DISTINCT has no effect, however, on the MAX and MIN functions. • You can use the ALL keyword to indicate that duplicates should not be eliminated. ALL is the default. A column function can be specified in a WHERE clause only if that clause is part of a subquery of a HAVING clause. Additionally, every column name specified in the expression of the column function must be a correlated reference to the same group. The column functions are AVG, COUNT, COUNT_BIG, MAX, MIN, STDDEV, SUM, and VARIANCE. The AVG Function The AVG function computes the average of the values for the column or expression speci- fied as an argument. This function operates only on numeric arguments. The following example calculates the average salary of each department: SELECT WORKDEPT, AVG(SALARY) FROM DSN8810.EMP GROUP BY WORKDEPT;
  • 3. 112 CHAPTER 3 Using DB2 Functions The AVG function is the preferred method of calculating the average of a group of values. Although an average, in theory, is nothing more than a sum divided by a count, DB2 may not return equivalent values for AVG(COL_NAME) and SUM(COL_NAME)/COUNT(*). The reason is that the COUNT function will count all rows regardless of value, whereas SUM ignores nulls. The COUNT Function The COUNT function counts the number of rows in a table, or the number of distinct values for a given column. It can operate, therefore, at the column or row level. The syntax differs for each. To count the number of rows in the EMP table, issue this SQL statement: SELECT COUNT(*) FROM DSN8810.EMP; It does not matter what values are stored in the rows being counted. DB2 will simply count the number of rows and return the result. To count the number of distinct depart- ments represented in the EMP table, issue the following SELECT COUNT(DISTINCT WORKDEPT) FROM DSN8810.EMP; The keyword DISTINCT is not considered an argument of the function. It simply specifies an operation to be performed before the function is applied. When DISTINCT is coded, duplicate values are eliminated. If DISTINCT is not specified, then ALL is implicitly specified. ALL also can be explicitly spec- ified in the COUNT function. When ALL is specified, duplicate values are not eliminated. NOTE The argument of the COUNT function can be of any built-in data type other than a large object: CLOB, DBCLOB, or BLOB. Character string arguments can be no longer 255 bytes and graphic string arguments can be no longer than 127 bytes. The result of the COUNT function cannot be null. COUNT always returns an INTEGER value greater than or equal to zero. The COUNT_BIG Function The COUNT_BIG function is similar to the COUNT function. It counts the number of rows in a table, or the number of distinct values for a given column. However, the COUNT_BIG func- tion returns a result of data type DECIMAL(31,0), whereas COUNT can return a result only as large as the largest DB2 integer value, namely +2,147,483,647. The COUNT_BIG function works the same as the COUNT function, except it returns a decimal value. Therefore, the example SQL for COUNT is applicable to COUNT_BIG. Simply substitute COUNT_BIG for COUNT. For example, the following statement counts the number of rows in the EMP table (returning a decimal value, instead of an integer): SELECT COUNT_BIG(*) FROM DSN8810.EMP;
  • 4. Column Functions 113 NOTE The COUNT_BIG function has the same restrictions as the COUNT function. The argument of the COUNT_BIG function can be of any built-in data type other than a large object: CLOB, DBCLOB, or BLOB. Character string arguments can be no longer than 255 bytes and graphic string arguments can be no longer than 127 bytes. The result of the COUNT_BIG function cannot be null. COUNT_BIG returns a decimal value greater than or equal to zero. The MAX Function The MAX function returns the largest value in the specified column or expression. The 3 following SQL statement determines the project with the latest end date: SELECT MAX(ACENDATE) FROM DSN8810.PROJACT; NOTE The result of the MAX function is of the same data type as the column or expression on which it operates. The argument of the MAX function can be of any built-in data type other than a large object: CLOB, DBCLOB, or BLOB. Character string arguments can be no longer than 255 bytes and graphic string arguments can be no longer than 127 bytes. A somewhat more complicated example using MAX is shown below. It returns the largest salary paid to a man in department D01: SELECT MAX(SALARY) FROM DSN8810.EMP WHERE WORKDEPT = ‘D01’ AND SEX = ‘M’; The MIN Function The MIN function returns the smallest value in the specified column or expression. To retrieve the smallest bonus given to any employee, issue this SQL statement: SELECT MIN(BONUS) FROM DSN8810.EMP; NOTE The result of the MIN function is of the same data type as the column or expression on which it operates. The argument of the MIN function can be of any built-in data type other than a large object: CLOB, DBCLOB, or BLOB. Character string arguments can be no longer than 255 bytes and graphic string arguments can be no longer than 127 bytes.
  • 5. 114 CHAPTER 3 Using DB2 Functions The STDDEV Function The STDDEV function returns the standard deviation of a set of numbers. The standard deviation is calculated at the square root of the variance. For example SELECT STDDEV(SALARY) FROM DSN8810.EMP WHERE WORKDEPT = ‘D01’; NOTE The argument of the STDDEV function can be any built-in numeric data type. The resulting stan- dard deviation is a double precision floating-point number. The SUM Function The accumulated total of all values in the specified column or expression are returned by the SUM column function. For example, the following SQL statement calculates the total yearly monetary output for the corporation: SELECT SUM(SALARY+COMM+BONUS) FROM DSN8810.EMP; This SQL statement adds each employee’s salary, commission, and bonus. It then aggre- gates these results into a single value representing the total amount of compensation paid to all employees. NOTE The argument of the SUM function can be any built-in numeric data type. The resulting sum must be within the range of acceptable values for the data type. For example, the sum of an INTEGER column must be within the range –2,147,483,648 to +2,147,483,647. This is because the data type of the result is the same as the data type of the argument values, except: • The sum of SMALLINT values returns an INTEGER result. • The sum of single precision floating point values returns a double precision floating-point result. The VARIANCE Function The VARIANCE function returns the variance of a set of numbers. The result is the biased variance of the set of numbers. The variance is calculated as follows: VARIANCE = SUM(X**2)/COUNT(X) - (SUM(X)/COUNT(X))**2 NOTE The argument of the VARIANCE function can be any built-in numeric data type. The resulting vari- ance is a double precision floating-point number. For brevity and ease of coding, VARIANCE can be shortened to VAR.
  • 6. Scalar Functions 115 Scalar Functions Scalar functions are applied to a column or expression and operate on a single value. Contrast this with the column functions, which are applied to a set of data and return only a single result. There are more than 110 scalar functions, each of which can be applied to a column value or expression. NOTE DB2 V6 significantly improved IBM’s support for built-in scalar functions. Prior to DB2 V6 there 3 were only 22 built-in scalar functions. Additional built-in functions were added for DB2 V7 and V8, as well. The result of a scalar function is a transformed version of the column or expression being operated on. The transformation of the value is based on the scalar function being applied and the value itself. Consult the following descriptions of the DB2 scalar functions: ABSVAL or ABS Converts a value of any numeric data type to its absolute value. ACOS Returns the arc-cosine of the argument as an angle expressed in radians. ADD_MONTHS Returns a date value that is the result of adding the second expression (which V7 is a duration) to the first expression (which is a date). ASIN Returns the arc-sine of the argument as an angle expressed in radians. ATAN Returns the arc-tangent of the argument as an angle expressed in radians. ATANH Returns the hyperbolic arc-tangent of the argument as an angle expressed in radians. ATAN2 Returns the arc-tangent of the specified x and y coordinates as an angle expressed in radians. BLOB Converts a string or ROWID data type into a value of data type BLOB. CCSID_ENCODING Returns the encoding scheme of the specified CCSID. The result will be one of V7 the following: ASCII, EBCDIC, UNICODE, or UNKNOWN. CEILING or CEIL Converts the argument, represented as any numeric data type, to the small- est integer value greater than or equal to the argument value. CHAR Converts a DB2 date, time, timestamp, ROWID, floating point, integer, or decimal value to a character value. For example SELECT CHAR(HIREDATE, USA) FROM DSN8810.EMP WHERE EMPNO = ‘000140’; This SQL statement returns the value for HIREDATE, in USA date format, of the employee with the EMPNO of ‘000140’. CLOB Converts a string or ROWID data type into a value of data type CLOB.
  • 7. 116 CHAPTER 3 Using DB2 Functions COALESCE For nullable columns, returns a value instead of a null (equivalent to VALUE function). CONCAT Converts two strings into the concatenation of the two strings. COS Returns the cosine of the argument as an angle expressed in radians. COSH Returns the hyperbolic cosine of the argument as an angle expressed in radians. DATE Converts a value representing a date to a DB2 date. The value to be converted can be a DB2 timestamp, a DB2 date, a positive integer, or a char- acter string. DAY Returns the day portion of a DB2 date or timestamp. DAYOFMONTH Similar to DAY except DAYOFMONTH cannot accept a date duration or time duration as an argument. DAYOFWEEK Converts a date, timestamp, or string representation of a date or timestamp into an integer that represents the day of the week. The value 1 represents Sunday, 2 Monday, 3 Tuesday, 4 Wednesday, 5 Thursday, 6 Friday, and 7 Saturday. DAYOFWEEK_ISO Similar to the DAYOFWEEK function, but results in different numbers to repre- V7 sent the day of the week. Converts a date, timestamp, or string representa- tion of a date or timestamp into an integer that represents the day of the week. The value 1 represents Monday, 2 Tuesday, 3 Wednesday, 4 Thursday, 5 Friday, 6 Saturday, and 7 Sunday. DAYOFYEAR Converts a date, timestamp, or string representation of a date or timestamp into an integer that represents the day within the year. The value 1 repre- sents January 1st, 2 January 2nd, and so on. DAYS Converts a DB2 date or timestamp into an integer value representing one more than the number of days since January 1, 0001. DBCLOB Converts a string or ROWID data type into a value of data type DBCLOB. DECIMAL or DEC Converts any numeric value, or character representation of a numeric value, to a decimal value. V8 DECRYPT_BIT Decrypts an encrypted column into a binary value using a user-provided encryption password. V8 DECRYPT_CHAR Decrypts an encrypted column into a character value using a user-provided encryption password. V8 DECRYPT_DB Decrypts an encrypted column into a variable graphic value using a user- provided encryption password. DEGREES Returns the number of degrees for the number of radians supplied as an argument.
  • 8. Scalar Functions 117 DIGITS Converts a number to a character string of digits. Be aware that the DIGITS function will truncate the negative sign for negative numbers. DOUBLE or FLOAT Converts any numeric value, or character representation of a numeric value, into a double precision floating point value. Another synonym for this func- tion is DOUBLE-PRECISION. ENCRYPT_TDES Uses the Triple DES encryption algorithm to encrypt a column in a table V8 using a user-provided encryption password. EXP Returns the exponential function of the numeric argument. The EXP and LOG functions are inverse operations. 3 FLOOR Converts the argument, represented as any numeric data type, to the largest integer value less than or equal to the argument value. GENERATE_UNIQUE Generates a CHAR(13) FOR BIT DATA value that is unique across the Sysplex. V8 GETHINT Obtains a hint to help remember the encryption password. V8 V8 GETVARIABLE Retrieves session variable values. Details on this function’s operation can be found in Chapter 10, “DB2 Security and Authorization.” GRAPHIC Converts a string data type into a value of data type GRAPHIC. V7 GREATEST Returns the maximum value in a supplied set of values. The argument values can be of any built-in data type other than CLOB, DBCLOB, BLOB, or ROWID. HEX Converts any value other than a long string to hexadecimal. HOUR Returns the hour portion of a time, a timestamp, or a duration. IDENTITY_VAL_ Returns the most recently assigned value for an identity column. (No input V7 LOCAL() parameters are used by this function.) IFNULL Returns the first argument in a set of two arguments that is not null. For example SELECT EMPNO, IFNULL(WORKDEPT, ‘N/A’) FROM DSN8810.EMP; This SQL statement returns the value for WORKDEPT for all employees, unless WORKDEPT is null, in which case it returns the string ‘N/A’. INSERT Accepts four arguments. Returns a string with the first argument value inserted into the fourth argument value at the position specified by the second argument value. The third argument value indicates the number of bytes to delete (starting at the position indicated by the third argument value). For example SELECT INSERT(‘FLAMING’, 2, 1, ‘R’) FROM SYSIBM.SYSDUMMY1;
  • 9. 118 CHAPTER 3 Using DB2 Functions This SQL statement returns the value ‘FLAMING’. Here is another example SELECT INSERT(‘BOSTON CHOWDER’, 8, 0, ‘CLAM ‘) FROM SYSIBM.SYSDUMMY1; This SQL statement returns the value ‘BOSTON CLAM CHOWDER’. CAUTION Both the value of the argument being inserted into, and the value of the argument that is being inserted, must have the same string data type. That is, both expressions must be charac- ter strings, or both expressions must be graphic strings. If the expressions are character strings, neither can be a CLOB. If the expressions are graphic strings, neither can be a DBCLOB. INTEGER or INT Converts any number, or character representation of a number, to an integer by truncating the portion of the number to the right of the decimal point. If the whole number portion of the number is not a valid integer (for example, the value is out of range), an error results. JULIAN_DAY Converts a DB2 date or timestamp, or character representation of a date or timestamp, into an integer value representing the number of days from January 1, 4712 B.C. to the date specified in the argument. NOTE January 1, 4712 B.C. is the start date of the Julian calendar. V7 LAST_DAY Returns the last day of the month for the specified DB2 date or timestamp, or character representation of a date or timestamp. V7 LEAST Returns the minimum value in a supplied set of values. The argument values can be of any built-in data type other than CLOB, DBCLOB, BLOB, or ROWID. LEFT Returns a string containing only the leftmost characters of the string in the first argument, starting at the position indicated by the second argument. For example SELECT LEFT(‘THIS IS RETURNED’, 4) FROM SYSIBM.SYSDUMMY1; This SQL statement returns ‘THIS’, which is the four leftmost characters of the first argument. LENGTH Returns the length of any column, which may be null. Does not include the length of null indicators or variable character-length control values, but does include trailing blanks for character columns. LOCATE Returns the position of the first occurrence of the first string the second string. For example SELECT LOCATE(‘I’, ‘CRAIG MULLINS’) FROM SYSIBM.SYSDUMMY1;
  • 10. Scalar Functions 119 This SQL statement returns the value 4, because the value ‘I’ first appears in position four within the searched string. It also appears in the 11th position, but that is of no concern to the LOCATE function. Optionally, a third argu- ment can be supplied indicating where the search should start. For example SELECT LOCATE(‘I’, ‘CRAIG MULLINS’, 7) FROM SYSIBM.SYSDUMMY1; This SQL statement returns the value 11, because after position 7, the value ‘I’ first appears in the 11th position. When the third argument is not speci- fied, LOCATE defaults to the beginning of the second string. 3 LOG or LN Returns the natural logarithm of the numeric argument. The EXP and LOG functions are inverse operations. LOG10 Returns the base 10 logarithm of the numeric argument. LOWER or LCASE Converts a character string into all lowercase characters. LTRIM Removes the leading blanks from a character string. V7 MAX Returns the maximum value in a supplied set of values. The argument values can be of any built-in data type other than CLOB, DBCLOB, BLOB, or ROWID. (This scalar function is not the same as the MAX column function discussed earlier.) GREATEST is a synonym for the MAX scalar function. MICROSECOND Returns the microsecond component of a timestamp or the character repre- sentation of a timestamp. MIDNIGHT_SECONDS Returns the number of seconds since midnight for the specified argument, which must be a time, timestamp, or character representation of a time or timestamp. V7 MIN Returns the minimum value in a supplied set of values. The argument values can be of any built-in data type other than CLOB, DBCLOB, BLOB, or ROWID. (This scalar function is not the same as the MIN column function discussed earlier.) LEAST is a synonym for MIN. MINUTE Returns the minute portion of a time, a timestamp, a character representation of a time or timestamp, or a duration. MOD Returns the remainder of the division of the first argument by the second argument. Both arguments must be numeric. MONTH Returns the month portion of a date, a timestamp, a character representation of a date or timestamp, or a duration. V7 MULTIPLY_ALT Can be used as an alternative to the multiplication operator. This function returns a decimal value that is the product of multiplying the two arguments together.
  • 11. 120 CHAPTER 3 Using DB2 Functions V7 NEXT_DAY Returns a timestamp indicating the first day of the week as specified in the second argument that is later than the date expression specified in the first argument. Valid values for the second argument are text representations of the days of the week; that is, MONDAY, TUESDAY, and so on. For example SELECT NEXT_DAY(CURRENT DATE, ‘FRIDAY’) FROM SYSIBM.SYSDUMMY1; This SQL statement returns a timestamp specifying the first Friday after today. NULLIF Returns a null when two specified expressions are equal; if not equal, the first expression is returned. POSSTR Similar to the LOCATE function, but with the arguments reversed. POSSTR returns the position of the first occurrence of the second argument within the first argument. For example SELECT POSSTR(‘DATABASE ADMINISTRATION’, ‘ADMIN’) FROM SYSIBM.SYSDUMMY1; This SQL statement returns the value 10; the value ‘ADMIN’ first appears in the 10th position. POWER Returns the value of the first argument raised to the power of the second argument. QUARTER Converts a date, timestamp, or string representation of a date or timestamp into an integer that represents the quarter within the year. The value 1 repre- sents first quarter, 2 second quarter, 3 third quarter, and 4 fourth quarter. RADIANS Returns the number of radians for the numeric argument expressed in degrees. RAND Returns a random floating-point number between 0 and 1. Optionally, an integer value can be supplied as a seed value for the random value genera- tor. For example SELECT (RAND() * 100) FROM SYSIBM.SYSDUMMY1; This SQL statement returns a random number between 0 and 100. REAL Converts any numeric value, or character representation of a numeric value, into a single precision floating point value. REPEAT Returns a character string that consists of the first argument repeated the number of times specified in the second argument. For example SELECT REPEAT(‘HO ‘, 3) FROM SYSIBM.SYSDUMMY1; This SQL statement returns the character string ‘HO HO HO ‘.
  • 12. Scalar Functions 121 REPLACE Returns a character string with the value of the second argument replaced by each instance of the third argument in the first argument. For example SELECT REPLACE(‘BATATA’, ‘TA’, ‘NA’) FROM SYSIBM.SYSDUMMY1; This SQL statement replaces all instances of ‘TA’ with ‘NA’ changing the character string ‘BATATA’ into ‘BANANA’. CAUTION Neither the first nor the second argument may be empty strings. The third argument, however, can be an empty string. If the third argument is an empty string, the REPLACE function will 3 simply replace each instance of the second argument with an empty string. RIGHT Returns a string containing only the rightmost characters of the string in the first argument, starting at the position indicated by the second argument. For example SELECT RIGHT(‘RETURN ONLY THIS’, 4) FROM SYSIBM.SYSDUMMY1; This SQL statement returns ‘THIS’, which is the four rightmost characters of the first argument. ROUND Rounds the first numeric argument to the number of places specified in the second argument. V7 ROUND_TIMESTAMP Rounds the timestamp value specified in the first argument based on the unit specified in the second argument. The timestamp can be rounded to the nearest year, quarter, month, week, day, hour, minute, or second. NOTE Table 3.1 highlights the valid unit arguments for both the ROUND_TIMESTAMP and TRUNC_ TIMESTAMP function. ROWID Casts the specified argument to a ROWID data type. Although the argument can be any character string, it should be a row ID value that was previously generated by DB2. Otherwise, the value may not be an accurate DB2 ROWID. RTRIM Removes the trailing blanks from a character string. SECOND Returns the seconds portion of a time, a timestamp, a character representa- tion of a time or timestamp, or a duration. SIGN Returns a value that indicates the sign of the numeric argument. The returned value will be –1 if the argument is less than zero, +1 if the argument is greater than zero, and 0 if the argument equals zero. SIN Returns the sine of the argument as an angle expressed in radians. SINH Returns the hyperbolic sine of the argument as an angle expressed in radians.
  • 13. 122 CHAPTER 3 Using DB2 Functions SMALLINT Converts any number, or character representation of a number, to an integer by truncating the portion of the number to the right of the decimal point. If the whole number portion of the number is not a valid integer (for example, the value is out of range), an error results. SPACE Returns a string of blanks whose length is specified by the numeric argu- ment. The string of blanks is an SBCS character string. SQRT Returns the square root of the numeric argument. STRIP Removes leading, trailing, or both leading and trailing blanks (or any specific character) from a string expression. SUBSTR Returns the specified portion of a character column from any starting point to any ending point. TAN Returns the tangent of the argument as an angle expressed in radians. TANH Returns the hyperbolic tangent of the argument as an angle expressed in radians. TIME Converts a value representing a valid time to a DB2 time. The value to be converted can be a DB2 timestamp, a DB2 time, or a character string. TIMESTAMP Obtains a timestamp from another timestamp, a valid character-string repre- sentation of a timestamp, or a combination of date and time values. V7 TIMESTAMP_FORMAT Returns a DB2 timestamp for the data in the first argument (which must be a character expression) based on the formatting specified in the second argu- ment. For example SELECT TIMESTAMP_FORMAT(‘2004-12-15 23:59:59’, ‘YYYY-MM-DD HH24:MI:SS’) FROM SYSIBM.SYSDUMMY1; This SQL statement converts the non-standard timestamp representation into a standard DB2 timestamp. TRANSLATE Translates characters from one expression to another. There are two forms of the TRANSLATE function. If only one argument is specified, the character string is translated to uppercase. Alternately, three arguments can be supplied. In this case, the first argument is transformed by replacing the character string specified in the third argument with the character string specified in the second argument. For example SELECT TRANSLATE(‘BACK’, ‘R’, ‘C’) FROM SYSIBM.SYSDUMMY1; This SQL statement returns ‘BARK’, because the character string ‘C’ is replaced with the character string ‘R’.
  • 14. Scalar Functions 123 Optionally, a fourth argument can be specified. This is the pad character. If the length of the second argument is less than the length of the third argu- ment, the second argument will be padded with the pad character (or blanks) to make up the difference in size. For example SELECT TRANSLATE(‘BACK’, ‘Y’, ‘ACK’, ‘.’) FROM SYSIBM.SYSDUMMY1; This SQL statement returns ‘BY..’, because the character string ‘ACK’ is replaced with the character string ‘Y’, and is padded with ‘.’ characters to make up the difference in size. 3 The string to be translated must be a character string not exceeding 255 bytes or a graphic string of no more than 127 bytes. The string cannot be a CLOB or DBCLOB. TRUNCATE or TRUNC Converts the first numeric argument by truncating it to the right of the decimal place by the integer number specified in the second numeric argu- ment. For example SELECT TRUNC(3.014015,2) FROM SYSIBM.SYSDUMMY1; This SQL statement returns the number 3.010000, because the second argu- ment specified that only 2 significant digits are required. The rest was trun- cated. V7 TRUNC_TIMESTAMP Truncates the timestamp value specified in the first argument based on the unit specified in the second argument. The timestamp can be truncated by year, quarter, month, week, day, hour, minute, or second. NOTE Table 3.1 highlights the valid unit arguments for both the ROUND_TIMESTAMP and TRUNC_ TIMESTAMP function. UPPER or UCASE Converts a character string into all uppercase characters. VALUE For nullable columns, returns a value instead of a null (equivalent to the COALESCE function). VARCHAR Converts a character string, date, time, timestamp, integer, decimal, floating point, or ROWID value into a corresponding variable character string represen- tation. V7 VARCHAR_FORMAT Returns the character representation for the timestamp expression specified in the first argument based on the formatting specified in the second argu- ment. For example SELECT VARCHAR_FORMAT(CURRENT TIMESTAMP,’YYYY-MM-DD HH24:MI:SS’) FROM SYSIBM.SYSDUMMY1;
  • 15. 124 CHAPTER 3 Using DB2 Functions This SQL statement converts a standard timestamp into a non-standard char- acter representation of that timestamp. VARGRAPHIC Converts a character string to a graphic string. WEEK Returns an integer between 1 and 54 based on the week of the year in which a date, timestamp, or string representation of a date or timestamp falls. The assumption is that a week begins on Sunday and ends on Saturday. The value 1 represents the first week, 2 the second week, and so on. V7 WEEK_ISO Returns an integer between 1 and 53 based on the week of the year in which a date, timestamp, or string representation of a date or timestamp falls. The assumption is that a week begins on Monday and ends on Sunday. Week 1 is the first week of the year to contain a Thursday. So, it is possible to have up to three days at the beginning of the year appear as the last week of the previous year, or to have up to three days at the end of a year appear as the first week of the next year. YEAR Returns the year portion of a date, a timestamp, or a duration. TABLE 3.1 Units for Rounding and Truncating TIMESTAMPs Unit Definition Explanation CC Century Rounds up to the next century starting in the 50th year of the century or truncates to the first day of the current century. SCC can be used as a synonym for CC. YYYY Year Rounds up to the next year starting on July 1st or truncates to the first day of the current year. The following can be used as synonyms in place of YYYY: SYYY, YEAR, SYEAR, YYY, YY, and Y. IYYY ISO Year Provides the same functionality as YYYY. The following can be used as synonyms in place of IYYY: IYY, IY, and I. Q Quarter Rounds up to the next quarter starting on the sixteenth day of the second month of the quarter or truncates to the first day of the current quarter. MM Month Rounds up to the next month on the sixteenth day of the month or truncates to the first day of the current month. The following can be used as synonyms in place of MM: MONTH, MON, and RM. WW Week Rounds up to the next week on the twelfth hour of the third day of the week (with respect to the first day of the year) or truncates to the first day of the current week. IW ISO Week Rounds up to the next week on the twelfth hour of the third day of the week (with respect to the first day of the ISO year) or trun- cates to the first day of the current ISO week. W Week Rounds up to the next week on the twelfth hour of the third day of the week (with respect to the first day of the month) or trun- cates to the first day of the current week (also with respect to the first day of the month).
  • 16. The RAISE_ERROR Function 125 TABLE 3.1 Continued Unit Definition Explanation DDD Day Rounds up to the next day on the twelfth hour of the day or trun- cates to the beginning of the current day. DD and J can be used as synonyms in place of DDD. DAY Start Day Differs from DDD by rounding to the starting day of a week. Rounds up to the next week on the twelfth hour of the third day of the week, otherwise it truncates to the starting day of the current week. DY and D can be used as synonyms in place of DAY. HH Hour Rounds up to the next hour at 30 minutes or truncates to the 3 beginning of the current hour. HH12 and HH24 can be used as synonyms in place of HH. MI Minute Rounds up to the next minute at 30 seconds or truncates to the beginning of the current minute. SS Second Rounds up to the next second at 500000 microseconds or trun- cates to the beginning of the current second. Some rules for the scalar functions follow: • Scalar functions can be executed in the select-list of the SQL SELECT statement or as part of a WHERE or HAVING clause. • A scalar function can be used wherever an expression can be used. • The argument for a scalar function can be a column function. The RAISE_ERROR Function The RAISE_ERROR function is a different type of function than we have discussed so far. It is not a column function because it does not take a group of rows and return a single value. Nor is RAISE_ERROR truly a scalar function because it does not transform column data from one state to another. Instead, the RAISE_ERROR function is used to raise an error condition in the SQLCA. The user supplies the SQLSTATE and error description for the error to be raised. The error will be raised with the specified SQLSTATE and a SQLCODE of –438. The RAISE_ERROR function can be used to signal application program and data problems. One situation where RAISE_ERROR may prove useful is in a CASE statement such as SELECT EMPNO, CASE WHEN SEX = ‘M’ THEN ‘MALE ‘ WHEN SEX = ‘F’ THEN ‘FEMALE’ ELSE RAISE_ERROR(‘70SX1’, ‘INVALID DATA, SEX IS NEITHER F NOR M.’) END FROM DSN8810.EMP;
  • 17. 126 CHAPTER 3 Using DB2 Functions The value specified for SQLSTATE must conform to the following rules: • The value must be a character string of exactly five characters in length. • Only the characters ‘0’ through ‘9’ and uppercase ‘A’ through ‘Z’ may be used. • The first two characters cannot be ‘00’, ‘01’, or ‘02’. • If the first character is ‘0’ through ‘6’ or ‘A’ through ‘H’, the last three characters must start with a letter from ‘I’ through ‘Z’. • If the first character is ‘7’, ‘8’, ‘9’, or ‘I’ though ‘Z’, the last three characters can be any valid character. NOTE Technically, the RAISE_ERROR function does return a value. It always returns NULL with an unde- fined data type. You must use the CAST function to cast it to a defined data type to return the value to a program. MQSeries Built-in Functions V7 DB2 Version 7 adds a number of new built-in scalar and table functions for use with IBM’s message queuing software, MQSeries. These functions enable MQSeries messages to be received and sent. The MQSeries scalar functions are MQREAD Accepts two parameters; returns a message (as VARCHAR(4000)) from the MQSeries location specified in the first expression, using the quality of service policy defined in the second expression. MQREADCLOB Accepts two parameters; returns a message (as a CLOB) from the MQSeries location specified in the first expression, using the quality of service policy defined in the second expression. NOTE When performing either the MQREAD or MQREADCLOB function the operation does not remove the message from the queue specified in the first expression. Additionally, for both functions, if no messages are available a NULL is returned. MQRECEIVE Same as MQREAD, except the operation will remove the messages from the queue. MQRECEIVECLOB Same as MQREADCLOB, except the operation will remove the messages from the queue. NOTE When performing either the MQRECEIVE or MQRECEIVECLOB function, the operation will remove the message from the queue specified in the first expression. Additionally, for both functions, if no messages are available a NULL is returned.
  • 18. XML Publishing Built-in Functions 127 MQSEND This function is used to send messages to an MQSeries queue. It returns a value of 1 if successful; 0 if unsuccessful. It accepts three (possibly, four) para- meters. The data contained in the first expression will be sent to the MQSeries location specified in the second expression, using the quality of service policy defined in the third expression. A user defined by the message correlation identifier may be specified as an optional fourth expression. Using these scalar functions you can easily read, retrieve, and send information from and to MQSeries message queues. The scalar functions operate one message at a time. At times, though, you might want to operate on multiple MQSeries messages. This requires table 3 functions, and DB2 Version 7 supplies several of these as well. The MQSeries table func- tions are MQREADALL Returns all of the messages (as VARCHAR) from the MQSeries location speci- fied in the first expression, using the quality of service policy defined in the second expression. An optional third parameter can be used to limit the number of rows to return. MQREADALLCLOB Returns all of the messages (as CLOB) from the MQSeries location specified in the first expression, using the quality of service policy defined in the second expression. An optional third parameter can be used to limit the number of rows to return. MQRECEIVEALL Same as MQREADALL except the operation will remove the messages from the queue. MQRECEIVECLOBALL Same as MQREADALLCLOB except the operation will remove the messages from the queue. NOTE When performing any of the MQSeries functions that read or receive data, an operation returns a table with the following columns: • MSG—Contains the contents of the MQSeries message, either a VARCHAR(4000) or CLOB based on which function was used. • CORRELID—Correlation ID used to relate messages—VARCHAR(24). • TOPIC—The topic that the message was published with, if available—VARCHAR(40). • QNAME—The queue name where the message was received—VARCHAR(48). • MSGID—The assigned MQSeries unique identifier for this message—CHAR(24). • MSGFORMAT—The format (typically MQSTR) of the message, as defined by MQSeries— VARCHAR(8). XML Publishing Built-in Functions V8 DB2 Version 8 adds a number of new built-in scalar functions to allow applications to effi- ciently generate XML data from DB2 data. The XML publishing functions are
  • 19. 128 CHAPTER 3 Using DB2 Functions XMLELEMENT Returns an XML element given an element name, an optional collection of attributes, and zero or more arguments that make up the contents of the element. XMLATTRIBUTES Used within the XMLELEMENT function to specify attributes of the XML element. XMLFOREST Returns a forest of XML elements that share a pattern from a list of expres- sions. XMLCONCAT Returns a forest of XML elements generated from a concatenation of two or more elements. XMLAGG Returns a concatenation of XML elements generated from a collection of XML elements. XML2CLOB Returns a CLOB representation of an XML expression. Built-in Function Guidelines Use the following guidelines to implement an effective strategy for deploying built-in functions in your DB2 applications. Use Functions Instead of Program Logic Use the built-in functions provided by DB2 instead of coding your own application logic to perform the same tasks. You can be sure the DB2 built-in functions will perform the correct tasks with no bugs. But you will have to take the time to code, debug, and test your application code. This is time you can better spend on developing application- specific functionality. Avoid Function Synonyms Several of the built-in functions have synonymous names that perform the same function. For example, VALUES and COALESCE perform the same exact function. You should standard- ize on one of the forms in your applications. By using only one of the forms your SQL will be easier to understand and maintain. Of course, your purchased applications may use any of the forms. The following are my recommendations, but of course, yours may differ: Use This Instead of This CEILING CEIL COALESCE VALUES DAY DAYOFMONTH DECIMAL DEC DOUBLE FLOAT GREATEST MAX (scalar) INTEGER INT
  • 20. Built-in Function Guidelines 129 Use This Instead of This LEAST MIN (scalar) LOG LN LOWER LCASE TIMESTAMP_FORMAT TO_DATE TRUNCATE TRUNC UPPER UCASE VARIANCE VAR 3 VARIANCE_SAMP VAR_SAMP In general, it is better to use the long form of the function instead of the abbreviated form because it is easier to quickly understand the purpose of the function. For example, one might easily assume that VAR is short for the VARCHAR function, instead of the VARIANCE function. I suggest using DAY instead of DAYOFMONTH because DAYOFMONTH does not support using a date duration or a timestamp duration as an argument. However, if you do not use dura- tions in your applications you might want to standardize on DAYOFMONTH instead of DAY because it is similar in name to other related functions such as DAYOFWEEK and DAYOFYEAR. I suggest using DOUBLE instead of FLOAT because one might confuse FLOAT with REAL. If there were a synonym for REAL, such as SINGLE, I would suggest using SINGLE. But there is not. V7 I suggest using the scalar functions LEAST and GREATEST instead of the scalar functions MIN and MAX to avoid possible confusion with the column functions MIN and MAX. Use UPPER instead of TRANSLATE Using the TRANSLATE function with a single argument serves the same purpose as the UPPER function—to convert a character string into uppercase. However, the UPPER function should be used for this purpose instead of TRANSLATE because • The UPPER function can be used only for the purpose of converting character strings to uppercase. • The TRANSLATE function is not as easily identified by developers as converting text to uppercase and is therefore more difficult to debug, maintain, and test SQL changes. Use HAVING to Search Column Function Results When using column functions, remember that the WHERE clause applies to the data prior to modification. To remove results after the data has been modified by the function, you must use the HAVING clause in conjunction with a GROUP BY clause.
  • 21. 130 CHAPTER 3 Using DB2 Functions The GROUP BY clause collates the resultant rows after the column function(s) have been applied. When the data is grouped, users can eliminate non-pertinent groups of data with the HAVING clause. For example, the following query groups employee data by department, returning the aggregate salary for each department, unless the average salary is $10,000 or less: SELECT WORKDEPT, SUM(SALARY) FROM DSN8810.EMP GROUP BY WORKDEPT HAVING AVG(SALARY) > 10000 ; The HAVING clause eliminates groups of non-required data after the data is summarized. Be Aware of NULLs When Using Column Functions Nulls can be one of the more difficult features of DB2 to understand and master. This is especially so when using certain built-in DB2 column functions. In some cases, you can write a query against a column using a built-in function and have the result be NULL— even if the column itself is defined as NOT NULL. Don’t believe it? Run this query: SELECT SUM(ACTNO) FROM DSN8810.EMPPROJACT WHERE PROJNO = ‘QRSTUV’; ACTNO is defined as NOT NULL, yet this query returns a NULL (unless someone inserted a row with the value of ‘QRSTUV’ for PROJNO). Why? The sum of all ACTNO values for project ‘QRSTUV’ is not zero, but is not applicable—at least as defined by DB2. Basically, if there are no results that apply to the predicate, the result of using a function such as SUM or AVG is NULL because the sum or average of no rows is not zero, but unde- fined.

×