4D Doc Center : TEXT TO BLOB

4D v13.4

BLOB

TEXT TO BLOB


TEXT TO BLOB ( text ; blob {; textFormat {; offset \| *}} )

Parameter	Type	Description
text	String	Text to write into the BLOB
blob	BLOB	BLOB to receive the text
textFormat	Longint	Format and character set of text
offset \| *	Variable, Operator	Offset within the BLOB (expressed in bytes) or * to append the value
		New offset after writing if not *

Description

The TEXT TO BLOB command writes the Text value text into the BLOB blob.

The textFormat parameter can be used to set the internal format and the character set of the text value to be written. To do this, pass one of the following constants (found in the “BLOB” theme) in the textFormat parameter:

Constant	Type	Value
Mac C string	Longint	0
Mac Pascal string	Longint	1
Mac Text with length	Longint	2
Mac Text without length	Longint	3
UTF8 C string	Longint	4
UTF8 Text with length	Longint	5
UTF8 Text without length	Longint	6

If you omit the textFormat parameter, by default 4D uses the Mac C string format. In databases created beginning with version 11, 4D works by default with the Unicode character set (UTF8) for managing text, so it is recommended to use this character set.

Notes:

The “UTF8” constants can only be used when the application runs in Unicode mode.
The “Mac” constants cannot work with texts greater than 32 KB.
If you want to work with character sets other than UTF8, use the CONVERT FROM TEXT command.

The following table describes each of these formats:

Text format	Description and Examples
C string	The text is ended by a NULL character (ASCII code $00).
	UTF8	"" --> $00
		"Café" --> $43 61 66 C3 A9 00
	Mac	"" --> $00
		"Café" --> $43 61 66 8E 00
Pascal string	The text is preceded by a 1-byte length.
	UTF8	-
		-
	Mac	"" --> $00
		"Café" --> $04 43 61 66 8E
Text with length	The text is preceded by a 4-byte (UTF8) or 2-byte (Mac) length.
	UTF8	"" --> $00 00 00 00
		"Café" --> $00 00 00 05 43 61 66 C3 A9
	Mac	"" --> $00 00
		"Café" --> $00 04 43 61 66 8E
Text without length	The text is composed only of its characters.
	UTF8	"" --> No data
		"Café" --> $43 61 66 C3 A9
	Mac	"" --> No data
		"Café" --> $43 61 66 8E

If you specify the * optional parameter, the Text value is appended to the BLOB; the size of the BLOB is extended accordingly. Using the * optional parameter, you can sequentially store any number of Integer, Long Integer, Real or Text values (see other BLOB commands) in a BLOB, as long as the BLOB fits into memory.

If you do not specify the * optional parameter nor the offset variable parameter, the Text value is stored at the beginning of the BLOB, overriding its previous contents; the size of the BLOB is adjusted accordingly.

If you pass the offset variable parameter, the Text value is written at the offset (starting from zero) within the BLOB. No matter where you write the Text value, the size of the BLOB is, increased according to the location you passed (plus up to the size of the text, if necessary). New allocated bytes, other than the ones you are writing, are initialized to zero.

After the call, the offset variable parameter is returned, incremented by the number of bytes that have been written. Therfore, you can reuse that same variable with another BLOB writing command to write another value.

Example

After executing this code:

 SET BLOB SIZE(vxBlob;0)

 C_TEXT(vtValue)

 vtValue:="Café" ` Length of vtValue is 4 bytes

 TEXT TO BLOB(vtValue;vxBlob;Mac C string) ` Size of BLOB becomes 5 bytes

 TEXT TO BLOB(vtValue;vxBlob;Mac Pascal string) ` Size of BLOB becomes 5 bytes

 TEXT TO BLOB(vtValue;vxBlob;Mac Text with length) ` Size of BLOB becomes 6 bytes

 TEXT TO BLOB(vtValue;vxBlob;Mac Text without length) ` Size of BLOB becomes 4 bytes

 TEXT TO BLOB(vtValue;vxBlob;UTF8 C string) ` Size of BLOB becomes 6 bytes

 TEXT TO BLOB(vtValue;vxBlob;UTF8 Text with length) ` Size of BLOB becomes 9 bytes

 TEXT TO BLOB(vtValue;vxBlob;UTF8 Text without length) ` Size of BLOB becomes 5 bytes