Command BLOB to text

BLOB to text

4th Dimension 2004, Command Alphabetical List

version 6.0

BLOB to text (blob; textFormat{; offset{; textLength}}) Text

Parameter Type Description

blob BLOB BLOB from which to get the Text value

textFormat Number 0  C String

1  Pascal String

2  Text with length

3  Text without length

offset Variable Offset within the BLOB (expressed in bytes)

New offset after reading

textLength Number Number of characters to be read

Function result Text Text value

Description

The BLOB to text command returns a Text value read from the BLOB blob.

The textFormat parameter fixes the internal format of the text value to be read. You pass one of the following predefined constants provided by 4th Dimension:

Constant Type Value

C string Long Integer 0

Pascal string Long Integer 1

Text with length Long Integer 2

Text without length Long Integer 3

The following table describes each of these formats:

Text format Description &amp; Examples

C string The text is ended by a NULL character (ASCII code $00)

"" $00

"Hello World!" $48 65 6C 6C 6F 20 57 6F 72 6C 64 21 00

Pascal string The text is preceded a 1-byte length

"" $00

"Hello World!" $0C 48 65 6C 6C 6F 20 57 6F 72 6C 64 21

Text with length The text is preceded by a 2-byte length

"" $00 00

"Hello World!" $00 0C 48 65 6C 6C 6F 20 57 6F 72 6C 64 21

Text without length The text is only composed of its characters.

"" No data

"Hello World!" $48 65 6C 6C 6F 20 57 6F 72 6C 64 21

WARNING: The number of characters to be read is determined by the textFormat parameter, EXCEPT for the format Text without length, for which you MUST specify the number of characters to be read in the parameter textLength. For the other formats, textLength is ignored and you can omit it.

Remember that a Text variable can contain up to 32,000 characters and a String variable can contain up to the number of characters in its declaration, with a maximum of 255 characters. If you try to read more data than a variable can hold, 4D will truncate the result of the command when placing it into the variable.

If you specify the optional offset variable parameter, the Text value is read at the offset (starting from zero) within the BLOB. If you do not specify the optional offset variable parameter, the beginning of the BLOB is read according to the value you pass in textFormat. Note that you must pass the offset variable parameter when you are reading text without length.

Note: You should pass an offset value between 0 (zero) and the size of the BLOB minus the size of the text to be read. If you do not do so, the function result is unpredictable.

After the call, the variable is incremented by the number of bytes read. Therefore, you can reuse that same variable with another BLOB reading command to read another value.

Example

The following example reads an hypothetical Mac OS-based resource whose internal format is identical to that of the 'STR#' resources:

   GET RESOURCE ("ABCD";viResID;vxResData;viMyResFile)
   vlSize:=BLOB Size(vxResData)
   If (vlSize>0)
         ` The resource starts with a 2-byte integer specifying the number of strings
      vlOffset:=0
      viNbEntries:=BLOB to integer(vxResData;Macintosh Byte Ordering;vlOffset)
         ` Then the resource contains concatenated, not padded, Pascal strings
      For (viEntry;1;viNbEntries)
         If (vlOffset<vlSize)
            vsEntry:=BLOB to text(vxResData;Pascal string;vlOffset)
               ` Do something with vsEntry
         Else
               ` Resource data is invalid, get out of the loop
            viEntry:=viNbEntries+1
         End if
      End for
   End if

Parameter	Type	Description
blob	BLOB	BLOB from which to get the Text value
textFormat	Number	0 C String
		1 Pascal String
		2 Text with length
		3 Text without length
offset	Variable	Offset within the BLOB (expressed in bytes)
		New offset after reading
textLength	Number	Number of characters to be read
Function result	Text	Text value

Constant	Type	Value
C string	Long Integer	0
Pascal string	Long Integer	1
Text with length	Long Integer	2
Text without length	Long Integer	3

Text format	Description &amp; Examples
C string	The text is ended by a NULL character (ASCII code $00)
	"" $00
	"Hello World!" $48 65 6C 6C 6F 20 57 6F 72 6C 64 21 00
Pascal string	The text is preceded a 1-byte length
	"" $00
	"Hello World!" $0C 48 65 6C 6C 6F 20 57 6F 72 6C 64 21
Text with length	The text is preceded by a 2-byte length
	"" $00 00
	"Hello World!" $00 0C 48 65 6C 6C 6F 20 57 6F 72 6C 64 21
Text without length	The text is only composed of its characters.
	"" No data
	"Hello World!" $48 65 6C 6C 6F 20 57 6F 72 6C 64 21
WARNING: The number of characters to be read is determined by the `textFormat` parameter, EXCEPT for the format `Text without length`, for which you MUST specify the number of characters to be read in the parameter `textLength`. For the other formats, `textLength` is ignored and you can omit it.