VerifyUtf Method (RUNTIME)

10.4

The VerifyUtf method ensures that PL/B character data is a valid UTF-8 string. The method uses the following format:

[label]	{object}.VerifyUtf	[GIVING {return}] USING [String=]{string*}[:
		[Flags=]{flags}][,[Length=]{length}]]

Where:

label

Optional. A Program Execution Label.

object

Required. A RUNTIME object that has been previously declared.

return

Optional. A Numeric Variable that returns the result for this method.

String

Required. A Character String Variable or literal that contains data to be verified.

Flags

Optional. A Numeric variable or decimal number that identifies the result type to be returned.

Length

Optional. A Numeric variable or decimal number that specifies the number of characters in the string data to be verified. When the length parameter is not used, the method determines the number of characters in the string to be tested.

Flags Affected: EOS, OVER, ZERO

Note the following:

The ZERO flag state is set to be TRUE if the {return} value is zero.
The OVER flag is set if the {return} numeric variable is too small to receive the full numeric result value.
The EOS flag is always cleared.
The {flags} bit mask values are described as follows:

Value	Description
0	This is the default value if the flags parameter is not specified for the method. When the flags value is zero, this method verifies that the data character string is a valid UTF-8 string. In this case, the return value of zero indicates that the character string is a valid UTF-8. A return of a non-zero value indicates an invalid UTF-8 string is found.
1	When this bit value is specified, this method evaluates the logical length of the string data. In the case, the return value is the evaluated logical length of the string data.
2	When this bit value is specified, this method evaluates the physical length of the string data. In this case, the return value is evaluated physical length of the string data. The physical length is calculated as the number of UTF-8 characters times 4.

Examples:

R	RUNTIME
nRes	FORM	5
nOpt1	INTEGER	1,"1" //Get Logical Length
nOpt2	INTEGER	1,"2" //Get Physical Length
Test1	INIT	"abc" //Valid UTF-8
Test2	INIT	"abc",0xE9 //Invalid UTF-8
Test3	INIT	"abc",0xC3,0xA9 //Valid UTF-8
.
Test1 ( Valid UTF-8 )
.
	R.VerifyUTF	GIVING nRes USING Test1 //nRes returns 0
	R.VerifyUTF	GIVING nRes USING Test1: //nRes returns 3
		nOpt1 //Logical Length
	R.VerifyUTF	GIVING nRes USING Test1: //nRes returns 12
		nOpt2 //Physical Length
.
.Test2 ( Invalid UTF-8 )
.
	R.VerifyUTF	GIVING nRes USING Test2 //nRes returns 1
	R.VerifyUTF	GIVING nRes USING Test2: //nRes returns 4
		nOpt1 //Logical Length
	R.VerifyUTF	GIVING nRes USING Test2: //nRes returns 16
		nOpt2 //Physical Length
.
. Test3 ( Valid UTF-8 )
.
	R.VerifyUTF	GIVING nRes USING Test3 //nRes returns 0
	R.VerifyUTF	GIVING nRes USING Test3: //nRes returns 4
		nOpt1 //Logical Length
	R.VerifyUTF	GIVING nRes USING Test3: //nRes returns 16
		nOpt2 //Physical Length

See Also: RUNTIME, RUNTIME Methods, Method Syntax