Binary

Binary datatype

This datatype was introduced in TD 5.2

Binary <-> String casting

A new datatype is introduced starting from TD5.2 : Binary.

This datatype is used to hold binary data which could come from the database (blobs), files, TD resources and ActiveX methods.
The difference between binary and string is mainly that the binary buffer does not have the ending NULL characters.
But in fact, string and binary variables can hold the same data. It does not depend on the contents of the data.
So a binary variable can easily contain text (UNICODE or ANSI) and a string can contain image data or other non-text information.

There are several new Sal/Vis functions which specifically needs a binary variable as parameter.

But the older functions (and your own custom functions) which act on Strings will not accept passing a binary variable.
The main problem is that there is no out-of-the-box functionality to cast between string and binary.

Why would we need this?

Well, when you have a binary variable and you want to manipulate it or pass it to Sal/Vis or custom functions, you are in trouble.
For instance, to read/write bytes from a specific offset in the binary data, you can only use the cstruct functions, like CStructGetByte and CStructPutByte.
But these functions do not accept binary datatype. So passing a binary to those functions will give you a compile error.
And unfortunately, there are no cstruct functions which allow you to pass a binary variable!

What we would like is a way to cast (convert) or copy the data from the binary variable to a string variable, do the stuff you need on the string, and then
cast the string back to binary.

What about the new TD 62 functions SalStringToBinary and SalBinaryToString?

These functions SEEM to do what we need. But in fact they can only be used in specific situations.
When the binary variable contains text (UNICODE/ANSI), these two functions convert the buffer data using the supplied encoding.
So a blob from database which is UNICODE text and is fetched in a binary variable can be converted to a string variable.
But what if the data is NOT text, for instance an image or any other binary data, these functions will surely corrupt the data.
The functions interpret the data and converts from and to UNICODE/ANSI encoding. So when passing an image, the bytes will be distorted.
For our need, a 1:1 cast without changing the data, these functions can not be used.

With the following trick, we are able to cast without changing the data:

   Set hBinary = SalHBinaryToNumber( binBuffer )
   Set sBuffer = SalNumberToHString( hBinary )

The first line gives us the handle (a number) to the binary variable.
The second line uses the binary handle and creates a string buffer using the data from the binary handle.

After this we have a "copy" of the binary variable data in a String variable.

This is the reverse:

   Set hString = SalHStringToNumber( sBuffer )
   Set binBuffer = SalNumberToHBinary( hString )

The first line gives us the handle (a number) to the string variable.
The second line uses the string handle and creates a binary buffer using the data from the string handle.

To combine this, the sample provided here contains two custom functions to cast easily between String and Binary:

   String PALBinaryToStr( pbinBinary )
   Binary PALStrToBinary( psString )

The sample will create a Binary variable and casts it to a String variable.
The String is then filled with bytes (1..128) using the cstruct function CStructPutByte.
After the String variable is filled, it is casted back to Binary.
The results are shown in the two multi-line fields which show a HEX view of the data.

Here you can download the sample:
WIKI_StringBinaryCasting.zip