VARBINARY scalar function

The VARBINARY function returns a VARBINARY (varying-length binary string) representation of a string of any data type.

The schema is SYSIBM.

string-expression

An expression that returns a value of a string data type.

integer

An integer constant value, which specifies the length attribute of the resulting VARBINARY data type. The value must be 1 - 32672. If integer is not specified, the length attribute of the result is the lower of the following values:

The maximum length for the VARBINARY data type
The length attribute for the data type of string-expression expressed in bytes:
- The length attribute, if string-expression is a binary string, a character string that is FOR BIT DATA, or a character string with string units of OCTETS
- The length attribute multiplied by 2, if string-expression is a graphic string with string units of CODEUNITS16 or double bytes
- The length attribute multiplied by 4, if string-expression is a character or graphic string with string units of CODEUNITS32

If the length attribute of string-expression is zero and the integer argument is not specified, the length attribute of the result is 1.

The result of the function is a VARBINARY. If the first argument can be null, the result can be null; if the first argument is null, the result is the null value.

The actual length of the result is the minimum of the length attribute of the result and the actual length in bytes of the string-expression. If the length of string-expression that is converted to a binary string is greater than the length attribute of the result, truncation occurs. A warning (SQLSTATE 01004) is returned in the following situations:

The first argument is a character or graphic string (other than a CLOB or DBCLOB) and non-blank characters are truncated.
The first argument is a binary string (other than BLOB) and non-hexadecimal zeros are truncated.

Examples

The following function returns a varying-length binary string with a length attribute 1, actual length 0, and a value of empty string.
```
   SELECT VARBINARY('',1) 
     FROM SYSIBM.SYSDUMMY1
```
The following function returns a varying-length binary string with a length attribute 5, actual length 3, and a value BX'4B4248'.
```
   SELECT VARBINARY('KBH',5) 
     FROM SYSIBM.SYSDUMMY1
```
The following function returns a varying-length binary string with a length attribute 3, actual length 3, and a value BX'4B4248'.
```
   SELECT VARBINARY('KBH') 
     FROM SYSIBM.SYSDUMMY1
```
The following function returns a varying-length binary string with a length attribute 3, actual length 3, and a value BX'4B4248'.
```
   SELECT VARBINARY('KBH ',3) 
     FROM SYSIBM.SYSDUMMY1
```
The following function returns a varying-length binary string with a length attribute 3, actual length 3, a value BX'4B4248', and a warning (SQLSTATE 01004).
```
   SELECT VARBINARY('KBH 93',3) 
     FROM SYSIBM.SYSDUMMY1
```