MdmrInquireStringModel

Table:	For inquiring about a global setting of a string model
Table:	For inquiring about constraints for the different positions in the string model
+ combination:	For inquiring about the size of a string
+ combination:	For explicitly inquiring about Unicode character name information (can be useful when working in ASCII)
+ combination:	For inquiring the default value
+ combination:	For inquiring if an inquire type is supported
+ combination:	For casting information to the required data type.

Return value

Compilation information

Synopsis

Inquire about a global setting of a SureDotOCR string model, or inquire about a position (constraint) in a string model.

Syntax

MIL_INT MdmrInquireStringModel(

MIL_ID ContextDmrId,	//in
MIL_INT64 StringModelLabelOrIndex,	//in
MIL_INT64 Position,	//in
MIL_INT64 PermittedCharEntry,	//in
MIL_INT64 InquireType,	//in
void *UserVarPtr	//out

)

Description

This function inquires about a global setting of a SureDotOCR string model, or inquires about the different positions (constraints) in a string model. String models are defined with MdmrControlStringModel().

To inquire about the default constraints for the positions in the string model, call this function and pass M_DEFAULT to the Position parameter; to inquire about explicit constraints for a position, pass M_POSITION_IN_STRING(n) instead, where n is the explicitly constrained position. Note that constraints typically refer to the characters that are permitted to be read, according to a character type and font.

If you want to loop through all explicitly constrained positions, you can set the Position parameter to M_POSITION_CONSTRAINED_ORDER(n), where n is the order in which the position was explicitly constrained. Note that the constrained order of a position changes if you reset previously constrained positions to be implicitly constrained, using MdmrControlStringModel() with M_RESET_POSITION_TO_IMPLICIT_CONSTRAINTS.

If the inquired setting is set to M_DEFAULT (for example, in MdmrControlStringModel()), MdmrInquireStringModel() will return M_DEFAULT. To inquire the actual default value, add M_DEFAULT to the InquireType parameter.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

ContextDmrId

Specifies the identifier of the SureDotOCR context that contains the string model about which to inquire. The context must have been previously allocated on the system using MdmrAlloc().

StringModelLabelOrIndex

Specifies the string model about which to inquire. Set this parameter to one of the values below:

For specifying the string model

Value

Description

M_STRING_INDEX(

MIL_INT IndexValue

)

Specifies to inquire about the string model by indicating its index.

(summarize)

Specifies to inquire about the string model by indicating its index.

(more details...)

Parameters

IndexValue

Specifies the index of the string model.

0 <= Value < M_NUMBER_OF_STRING_MODELS

Specifies the index of the string model about which to inquire.

M_STRING_LABEL(

MIL_INT LabelValue

)

Specifies to inquire about the string model by indicating its label.

(summarize)

Specifies to inquire about the string model by indicating its label.

(more details...)

Parameters

LabelValue

Specifies the label of the string model.

0 < Value < 2097152

Specifies the label of the string model about which to inquire.

Position

Specifies how to inquire about the string model. Set this parameter to one of the values below:

For specifying how to inquire about the string model

Value

Description

M_DEFAULT

Specifies to inquire about a global setting of a string model.

M_POSITION_CONSTRAINED_ORDER(

MIL_INT OrderValue

)

Specifies to inquire about an explicitly constrained position in the string model by indicating the order in which the position was explicitly constrained.

(summarize)

Specifies to inquire about an explicitly constrained position in the string model by indicating the order in which the position was explicitly constrained.

(more details...)

Parameters

OrderValue

Specifies the order in which the position was explicitly constrained.

0 <= Value <= 255

Specifies the order in which the position was explicitly constrained. For example, if you explicitly constrained positions 19, 5, and 24, their respective constrained order values are 0, 1, and 2.

M_POSITION_IN_STRING(

MIL_INT PositionValue

)

Specifies to inquire about an explicitly constrained position in the string model by indicating its position.

If you specify a position that is not explicitly constrained, you will get an error. To inquire about the default constraints for the positions in the string model, you must set this parameter to M_DEFAULT.

(summarize)

Specifies to inquire about an explicitly constrained position in the string model by indicating its position.

(more details...)

Parameters

PositionValue

Specifies the explicitly constrained position.

0 <= Value <= 255

Specifies the explicitly constrained position about which to inquire.

PermittedCharEntry

Specifies the permitted character about which to inquire. SureDotOCR keeps track of each permitted character that you specify as an entry (MdmrControlStringModel() with M_ADD_PERMITTED_CHARS_ENTRY). The PermittedCharEntry parameter allows you to inquire about a specific entry.

Set this parameter to one of the values below:

For specifying the permitted character
Value	Description
M_DEFAULT	Specifies that this parameter is not required.
Value >= 0	Specifies the permitted character about which to inquire.

InquireType

Specifies the type of inquire to perform.

See the Parameter associations section for possible values that can be specified.

UserVarPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_TEXT_CHAR [optionally, in C++: a reference to a MIL_STRING]
MIL_DOUBLE
MIL_INT
MIL_INT32
MIL_INT64

Specifies the address in which to write the requested information. Since the MdmrInquireStringModel() function also returns the requested information, you can set this parameter to M_NULL.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The tables below list possible values for the InquireType parameter and possible values returned to the UserVarPtr parameter.

For inquiring about a global setting of a string model
For inquiring about constraints for the different positions in the string model

To inquire about a global setting of a string model, set the InquireType parameter to one of the values below. Unless otherwise specified, set the StringModelLabelOrIndex parameter to the label or index of a string model, set the Position parameter to M_DEFAULT, and set the PermittedCharEntry parameter to M_DEFAULT.

For inquiring about a global setting of a string model
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_CHAR_ACCEPTANCE +		Inquires the acceptance level for the score of the string's characters. SET (summarize) Inquires the acceptance level for the score of the string's characters. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE
	M_DEFAULT	Specifies the default value; the default value is 50.0 %.
	0.0 <= Value <= 100.0	Specifies the acceptance level for the character score, as a percentage. INFO
M_NUMBER_OF_CONSTRAINED_POSITIONS +		Inquires the number of explicitly constrained positions. These are set with MdmrControlStringModel(). (summarize) Inquires the number of explicitly constrained positions. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	Value >= 0	Specifies the number of explicitly constrained positions.
M_STRING_ACCEPTANCE +		Inquires the acceptance level for the string's score. SET (summarize) Inquires the acceptance level for the string's score. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE
	M_DEFAULT	Specifies the default value; the default value is 50.0 %.
	0.0 <= Value <= 100.0	Specifies the acceptance level for the string's score, as a percentage. INFO
M_STRING_CERTAINTY +		Inquires the certainty level for the string's score. SET (summarize) Inquires the certainty level for the string's score. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE
	M_DEFAULT	Specifies the default value; the default value is 70.0 %.
	0.0 <= Value <= 100.0	Specifies the certainty level for the string score, as a percentage. INFO
M_STRING_INDEX_VALUE +		Inquires the index of the string model. Set the StringModelLabelOrIndex parameter to the string model's label. (summarize) Inquires the index of the string model. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_INVALID	Specifies that the string model you are referring to does not exist in the context.
	Value >= 0	Specifies the index.
M_STRING_LABEL_VALUE +		Inquires the label of the string model. Set the StringModelLabelOrIndex parameter to the string model's index. (summarize) Inquires the label of the string model. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	Value > 0	Specifies the label.
M_STRING_RANK +		Inquires the order in which to read a string, relative to the other strings to read. SET (summarize) Inquires the order in which to read a string, relative to the other strings to read. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_DEFAULT	Specifies the default value; the default value is 0.
	Value >= 0	Specifies the order in which to read a string. INFO
M_STRING_SIZE_MAX +		Inquires the maximum number of characters in the string. SET (summarize) Inquires the maximum number of characters in the string. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_DEFAULT	Same as M_INVALID.
	M_INVALID	Specifies an invalid maximum number of characters. Set the maximum number of characters to a valid value, using MdmrControlStringModel() with M_STRING_SIZE_MAX. (summarize) Specifies an invalid maximum number of characters. (more details...)
	1 <= Value <= 256	Specifies the maximum number of characters.
M_STRING_SIZE_MIN +		Inquires the minimum number of characters in the string. SET (summarize) Inquires the minimum number of characters in the string. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_DEFAULT	Specifies the default value; the default value is 1.
	1 <= Value <= 256	Specifies the minimum number of characters.

To inquire about constraints for the different positions in the string model, set the InquireType parameter to one of the values below. In this case, set the StringModelLabelOrIndex parameter to the label or index of a string model.

To inquire about the default constraints for the positions in the string model, set the Position parameter to M_DEFAULT, unless otherwise specified. To inquire about explicit constraints for a position, set the Position parameter to the required position, unless otherwise specified.

For inquiring about constraints for the different positions in the string model
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_CHAR_LIST +		Inquires the names of the characters that can be read. This is returned as a regular string. It consists of all characters including the terminating null character. Characters can come from one or any font (M_FONT_LABEL_VALUE). M_CHAR_LIST is set as a permitted character constraint (M_ADD_PERMITTED_CHARS_ENTRY). There can be many permitted character constraint entries for a single character position. To specify which to inquire about, use the PermittedCharEntry parameter. SET (summarize) Inquires the names of the characters that can be read. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] Required array size: MdmrInquireStringModel ( M_CHAR_LIST + M_STRING_SIZE ) Note: When using C++, you can pass a reference to a MIL_STRING instead. In this case, the function will automatically determine the correct string size. Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] Required array size: MdmrInquireStringModel ( M_CHAR_LIST + M_STRING_SIZE ) Note: When using C++, you can pass a reference to a MIL_STRING instead. In this case, the function will automatically determine the correct string size.
	CharName	Specifies the character names. Retrieving an empty string ("") indicates that any character can be read. (summarize) Specifies the character names. (more details...)
M_CONSTRAINED_ORDER +		Inquires the order in which the position was explicitly constrained. Set the Position parameter to M_POSITION_IN_STRING(). (summarize) Inquires the order in which the position was explicitly constrained. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	Value >= 0	Specifies the constrained order. This value will be less than M_NUMBER_OF_CONSTRAINED_POSITIONS. (summarize) Specifies the constrained order. (more details...)
M_FONT_LABEL_VALUE +		Inquires the label of the font from which the character to read must come. This is set as a permitted character constraint (M_ADD_PERMITTED_CHARS_ENTRY). There can be many such permitted character constraint entries (allowable fonts) for a single character position. To specify which to inquire about, use the PermittedCharEntry parameter. To inquire the corresponding font index, call MdmrInquireFont() with M_FONT_INDEX_VALUE and the label value returned by M_FONT_LABEL_VALUE. SET (summarize) Inquires the label of the font from which the character to read must come. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_ANY	Specifies that the character can come from any font in the context.
	Value > 0	Specifies the label of the font. If SureDotOCR cannot return the requested information (no such font exists in the context), you will get an error. (summarize) Specifies the label of the font. (more details...)
M_NUMBER_OF_PERMITTED_CHARS_ENTRIES +		Inquires the number of permitted character entries. This is the number of permitted characters specified with M_ADD_PERMITTED_CHARS_ENTRY. Having no permitted character entries indicates you are reading any character from any font (initial default behavior). (summarize) Inquires the number of permitted character entries. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	Value >= 0	Specifies the number of permitted character entries.
M_POSITION +		Inquires the position within the string model, corresponding to the order in which the position was explicitly constrained. Set the Position parameter to M_POSITION_CONSTRAINED_ORDER(). (summarize) Inquires the position within the string model, corresponding to the order in which the position was explicitly constrained. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	Value >= 0	Specifies the position.
M_TYPE +		Inquires the type of characters that can be read. This is set as a permitted character constraint (M_ADD_PERMITTED_CHARS_ENTRY). There can be many such allowable types of characters for a position. To specify the one about which to inquire, use the PermittedCharEntry parameter. If you are reading an explicitly defined list of characters, use M_CHAR_LIST to inquire the names of those characters. SET (summarize) Inquires the type of characters that can be read. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_ANY	Specifies to read all characters present in the font.
	M_CHAR_LIST	Specifies to read an explicit list of characters. INFO
	M_DIGITS	Specifies to read characters '0' to '9'.
	M_LETTERS	Specifies to read characters 'A' to 'Z' and 'a' to 'z'.
	M_LETTERS_LOWERCASE	Specifies to read characters 'a' to 'z'.
	M_LETTERS_UPPERCASE	Specifies to read characters 'A' to 'Z'.
	M_SPACE	Specifies to read a space. INFO

Combination value for M_CHAR_LIST.

You can add the following value to the above-mentioned value to get the size of a string.

For inquiring about the size of a string
InquireType combination value		Description
	UserVarPtr - Possible values returned	Description
M_STRING_SIZE +		Inquires the number of characters in the string. This number accounts for every character, including the terminating null character. All strings have the terminating null character, even though you need not explicitly list it when specifying the string. (summarize) Inquires the number of characters in the string. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT

Combination values for M_CHAR_LIST; M_STRING_SIZE.

You can add one of the following values to the above-mentioned values to determine the UTF-16 (Unicode) character name information, which can be useful when working in an ASCII environment.

If you are in an ASCII environment and you are inquiring about character names (for example, with M_CHAR_LIST) that are within the Basic Latin range, SureDotOCR does not consider the Unicode name, by default. For example, if SureDotOCR reads the character 'A', which is a Basic Latin character, and you use M_CHAR_LIST to get the name of that character, SureDotOCR returns 'A', even if you explicitly named it "\x0041" in the font. To return information about the character's UTF-16 (Unicode) name (that is, "\x0041"), use the combination value M_HEX_UTF16_FOR_ALL.

If you are in an ASCII environment and you are inquiring about character names beyond the Basic Latin range, you can only retrieve information about the character name in hexadecimal format. For example, Basic Latin does not include the smiley face character; it is named in hexadecimal format ("\x263A") in the font.

Note that the string size information can change when these combination values are added. For example, in an ASCII environment, if the first four characters in the font are "abc☺", using M_CHAR_LIST + M_HEX_UTF16_FOR_NON_BASIC_LATIN returns "b" for the character at index 1, and "\x263A" for the character at index 3. Consequently, the string sizes are 2 and 7, respectively (inquired with M_CHAR_LIST + M_STRING_SIZE + M_HEX_UTF16_FOR_NON_BASIC_LATIN). If M_HEX_UTF16_FOR_ALL is specified, the preceding example returns "\x0062" and "\x263A" for the respective character names, and 7 for each string size. Recall that the null-terminating character is included in the string size.

In a Unicode environment, the character representations are returned (for example, the smiley face), unless you explicitly specify a combination value (for example, to obtain "\x263A" instead of the actual smiley face).

For explicitly inquiring about Unicode character name information (can be useful when working in ASCII)
Combination value	Description
M_HEX_UTF16_FOR_ALL	Retrieves results with the name of all characters in hexadecimal 16-bit Unicode (UTF-16) format.
M_HEX_UTF16_FOR_NON_BASIC_LATIN	Retrieves results with the names of characters that fall out of the Basic Latin range, in hexadecimal 16-bit Unicode (UTF-16) format. INFO

Combination value for the values listed in For inquiring about a global setting of a string model; the values listed in For inquiring about constraints for the different positions in the string model.

You can add the following value to the above-mentioned values to get the default value of an inquire type, regardless of the current value of the inquire type.

For inquiring the default value
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_DEFAULT		Inquires the default value of the specified inquire type. (summarize) Inquires the default value of the specified inquire type. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE

You can add the following value to the above-mentioned values to determine whether an inquire type is supported for the font currently being inquired.

For inquiring if an inquire type is supported
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_SUPPORTED		Inquires whether the specified inquire type is supported. (summarize) Inquires whether the specified inquire type is supported. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT Data type info: Data type: address of a MIL_DOUBLE MORE Data type: address of a MIL_DOUBLE Recommended casting type: MIL_INT
	M_FALSE	Specifies that the inquire type is not supported.
	M_TRUE	Specifies that the inquire type is supported.

Combination values for the values listed in For inquiring about a global setting of a string model; and for the following values: M_CONSTRAINED_ORDER; M_FONT_LABEL_VALUE; M_NUMBER_OF_PERMITTED_CHARS_ENTRIES; M_POSITION; M_STRING_SIZE; M_TYPE.

You can add one of the following values to the above-mentioned values to cast the requested information to the required data type.

For casting information to the required data type.
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_TYPE_MIL_DOUBLE		Casts the requested information to a MIL_DOUBLE. (summarize) Casts the requested information to a MIL_DOUBLE. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE Data type: address of a MIL_DOUBLE
M_TYPE_MIL_INT		Casts the requested information to a MIL_INT. (summarize) Casts the requested information to a MIL_INT. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT
M_TYPE_MIL_INT32		Casts the requested information to a MIL_INT32. (summarize) Casts the requested information to a MIL_INT32. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT32 Data type: address of a MIL_INT32 Data type info: Data type: address of a MIL_INT32 Data type: address of a MIL_INT32
M_TYPE_MIL_INT64		Casts the requested information to a MIL_INT64. (summarize) Casts the requested information to a MIL_INT64. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT64 Data type: address of a MIL_INT64 Data type info: Data type: address of a MIL_INT64 Data type: address of a MIL_INT64

Return value

The returned value is the requested information, cast to a MIL_INT. If the requested information does not fit into a MIL_INT, this function will return M_NULL or truncate the information.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mildmr.lib.
DLL	Requires mil.dll; mildmr.dll.