| MIL 10 Reference
| Customize Help
| Save Settings

MstrInquire


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
None.
MstrGetResult
MstrPreprocess
Synopsis
Inquire information about a specified String Reader context, string model, result buffer, font, or an error/warning code generated by MstrExpert().
Syntax
MIL_INT MstrInquire(
MIL_ID ContextOrResultId, //in
MIL_INT Index, //in
MIL_INT64 InquireType, //in
void *UserVarPtr //out
)
Description

This function inquires information about a String Reader context, the string models or fonts contained therein, or a result buffer. In addition, this function can inquire from the String Reader context the meaning of an error/warning code generated by MstrExpert() and retrieved using MstrGetResult() with M_REPORT_ERRORS or M_REPORT_WARNINGS.

Unless otherwise specified, the inquire type settings are applicable to both font-based and fontless contexts.

If the inquired setting is set to M_DEFAULT (for example, in MstrControl()), MstrInquire() 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 if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
ContextOrResultId

Specifies the String Reader context or result buffer about which to inquire information. The String Reader context must have been previously allocated on the required system using MstrAlloc(). The String Reader result buffer must have been previously allocated on the required system using MstrAllocResult().

Index

Specifies that information will be inquired about the String Reader context, a specific font, a specific string model, a specified error/warning code, or a result buffer. Set this parameter to one of the following values:

function map For a String Reader context, specific font, specific string model, result buffer, or a report generated by the last call to MstrExpert().
CollapseValue Description
Collapse M_DEFAULT

Specifies the default.

If a String Reader context is specified, same as M_CONTEXT.

If a String Reader result buffer is specified, same as M_GENERAL.

(summarize)
Collapse

Specifies the index of the font about which to inquire.

Note that this macro is only available for a font-based context.

(summarize)
Parameters

This parameter specifies the index of the font. You can set this parameter to the following:
Value >= 0

Specifies the index of the individual font about which to inquire.

To retrieve the index of a font from its user label, set the Index parameter of MstrInquire() to the user label and set the inquire type to M_FONT_INDEX_FROM_LABEL.
Collapse

Specifies the index of the string about which to inquire.

(summarize)
Parameters

This parameter specifies the index of the string. You can set this parameter to the following:
Value >= 0

Specifies the index of the individual string about which you want to inquire.

To retrieve the index of a string from its user label, set the Index parameter of MstrInquire() to the user label and set the inquire type to M_STRING_INDEX_FROM_LABEL.
Collapse M_CONTEXT

Specifies to inquire information about a general setting of a String Reader context.
Collapse M_GENERAL

Specifies to inquire information about a general setting of a String Reader result buffer.
Collapse Error or warning value

Specifies the error or warning code about which to inquire. Typically, these codes are generated by the last call to MstrExpert(), and retrieved using MstrGetResult() with either M_REPORT_ERRORS or M_REPORT_WARNINGS.

(summarize)
Collapse User label

Specifies the label of the font or string about which to inquire, assigned using MstrControl().

Set InquireType to either M_FONT_INDEX_FROM_LABEL or M_STRING_INDEX_FROM_LABEL to retrieve the font or string index associated with the user label, respectively.

(summarize)
InquireType

Specifies the type of setting about which to inquire.

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 char
  • array of type MIL_DOUBLE
  • array of type MIL_FLOAT
  • array of type MIL_ID
  • array of type MIL_INT
  • array of type MIL_INT16
  • array of type MIL_INT32
  • array of type MIL_INT64
  • array of type MIL_TEXT_CHAR
  • array of type short
  • char
  • MIL_DOUBLE
  • MIL_FLOAT
  • MIL_ID
  • MIL_INT
  • MIL_INT16
  • MIL_INT32
  • MIL_INT64
  • MIL_TEXT_CHAR

Specifies the address in which to write the requested information. Since the MstrInquire() function also returns the requested information, you can set this parameter to M_NULL (for non-array results only).

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 a String Reader context (M_CONTEXT), or a specific string in the String Reader context (M_STRING_INDEX()), the InquireType parameter can be set to the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a context or an individual string
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_STRING_NUMBER +

Inquires either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.
Collapse M_ALL

Specifies that all strings will be read. INFO
Collapse Value

Specifies the maximum number of strings that can be read. INFO

For a fontless context (M_CONTEXT), or font-based context (M_FONT_INDEX()), the InquireType parameter can be set to the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a context or a specific font
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_CHAR_VALUE +

Inquires the character value for each character. Unless a data type from the table For specifying the data type is explicitly added to M_CHAR_VALUE, the string array must be of the right type for the encoding scheme selected (MstrInquire() with M_ENCODING).

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: This array must be of size M_NUMBER_OF_CHARS.

Collapse Value

Specifies the value of the character.
Collapse M_NUMBER_OF_CHARS +

Inquires the number of characters in the font-based or fontless context.

(summarize)
Collapse Value

Specifies the number of characters.
Collapse M_SPACE_WIDTH +

Inquires the width of the space character of the font or fontless context. SET

(summarize)
Collapse M_DEFAULT

Same as M_MEAN_CHAR_WIDTH.
Collapse M_INFINITE

Specifies that the width of the space character is infinite. INFO
Collapse M_MAX_CHAR_WIDTH

Specifies that the width of the space character is equal to the maximum character X-size of the font.
Collapse M_MEAN_CHAR_WIDTH

Specifies that the width of the space character is equal to the average character X-size of the font.
Collapse M_MIN_CHAR_WIDTH

Specifies that the width of the space character is equal to the minimum character X-size of the font.
Collapse M_QUARTER_MAX_CHAR_WIDTH

Specifies that the width of the space character is equal to a quarter of the maximum character width of the font. INFO
Collapse Value >= 1

Specifies the width of the space character, in pixels.
Collapse M_SPACE_WIDTH_VALUE +

Inquires the actual width value of the space character of the font or fontless context.

(summarize)
Collapse Value >= 1

Specifies the actual width value of the space character, in pixels.

For a String Reader context (M_CONTEXT), the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a String reader context
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_CHAR_STATUS +

Inquires the status of each character in the context, where the status determines whether the String Reader module should search for the character in the image.

Note that this inquire type is only available for a fontless context. SET SET

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The size of the array must be large enough to contain the status for every character in the fontless context. This number can be retrieved with M_NUMBER_OF_CHARS.

Collapse M_DISABLE

Specifies not to search for the character when performing a read operation.
Collapse M_ENABLE

Specifies to search for the character when performing a read operation.
Collapse M_CONTEXT_TYPE +

Inquires the type of String Reader context.

(summarize)
Collapse M_FONT_BASED

Specifies a font-based context. Such contexts must be allocated, using MstrAlloc().

(summarize)
Collapse M_FONTLESS

Specifies a fontless context. Such contexts must be restored, using MstrRestore().

(summarize)
Collapse M_DRAW_LAST_SIZE_X +

Inquires the width of the image buffer needed by the last call to MstrDraw(). This allows you to allocate a buffer of optimal size, for the required drawing operation.

Note that when you call MstrDraw() for the first time, you can pass M_NULL as the destination image to get the size needed for the required drawing operation. For more information, see MstrDraw().

(summarize)
Collapse Value

Specifies the width of the image buffer.
Collapse M_DRAW_LAST_SIZE_Y +

Inquires the height of the image buffer needed by the last call to MstrDraw(). This allows you to allocate a buffer of optimal size, for the required drawing operation.

Note that when you call MstrDraw() for the first time, you can pass M_NULL as the destination image to get the size needed for the required drawing operation. For more information, see MstrDraw().

(summarize)
Collapse Value

Specifies the height of the image buffer.
Collapse M_ENCODING +

Inquires the type of character encoding used by the String Reader context. SET

(summarize)
Collapse M_DEFAULT

Same as M_ASCII.
Collapse M_ASCII

Specifies an 8-bit ASCII standard. INFO
Collapse M_UNICODE

Specifies a 16-bit Unicode standard. INFO
Collapse M_MAX_CHAR_SIZE_X +

Inquires the width (X-size) of the widest, enabled character in the fontless context when it has a height of M_REF_CHAR_SIZE_Y.

Note that this inquire type is only available for a fontless context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 65 pixels.
Collapse 0 <= Value <= 65536

Specifies the maximum character width, in pixels.
Collapse M_MIN_CHAR_SIZE_X +

Inquires the width (X-size) of the narrowest, enabled character in the fontless context when it has a height of M_REF_CHAR_SIZE_Y.

Note that this inquire type is only available for a fontless context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 6 pixels.
Collapse 0 <= Value <= 65536

Specifies the minimum character width, in pixels.
Collapse M_MINIMUM_CONTRAST +

Inquires the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead(). SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 15.
Collapse 1 <= Value <= 255

Specifies the minimum contrast.
Collapse M_MODIFICATION_COUNT +

Inquires the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified.

Although you cannot identify the modification counter's contents, you can compare them throughout your application to know if the context has been altered. If the modification counter has changed you can, for example, prompt the user to save before closing the application.

(summarize)
Collapse Value

Specifies the current value of the modification counter.
Collapse M_NUMBER_OF_FONTS +

Inquires the number of fonts in the context.

Note that this inquire type is only available for a font-based context.

(summarize)
Collapse Value

Specifies the number of fonts.
Collapse M_NUMBER_OF_STRING_MODELS +

Inquires the number of string models in the context.

(summarize)
Collapse Value

Specifies the number of string models.
Collapse M_PREPROCESSED +

Inquires whether the String Reader context is preprocessed. This will indicate whether preprocessing (using MstrPreprocess()) is needed to prepare the context for use.

(summarize)
Collapse 0

Specifies that the context is not preprocessed; you should preprocess again.
Collapse Value != 0

Specifies that the context is preprocessed; you should not preprocess again.
Collapse M_REF_CHAR_SIZE_Y +

Inquires the reference height.

Note that this inquire type is only available for a fontless context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 46 pixels.
Collapse 0 <= Value <= 65536

Specifies the height, in pixels.
Collapse M_REF_CHAR_THICKNESS +

Inquires the stroke width of characters in the fontless context when they have a height of M_REF_CHAR_SIZE_Y.

Note that this inquire type is only available for a fontless context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 6 pixels.
Collapse 0 <= Value <= 65536

Specifies the thickness, in pixels.
Collapse M_SEARCH_CHAR_ANGLE +

Inquires whether strategies specific to angular-range will be calculated. SET

(summarize)
Collapse M_DEFAULT

Same as M_DISABLE.
Collapse M_DISABLE

Specifies not to perform calculations specific to angular-range search strategies.
Collapse M_ENABLE

Specifies to perform calculations specific to angular-range search strategies.
Collapse M_SEARCH_SKEW_ANGLE +

Inquires whether strategies specific to angular-range skew will be calculated. SET

(summarize)
Collapse M_DEFAULT

Same as M_DISABLE.
Collapse M_DISABLE

Specifies not to perform calculations specific to angular-range skew search strategies.
Collapse M_ENABLE

Specifies to perform calculations specific to angular-range skew search strategies.
Collapse M_SEARCH_STRING_ANGLE +

Inquires whether to search for the string angle. SET

(summarize)
Collapse M_DEFAULT

Same as M_ENABLE.
Collapse M_DISABLE

Specifies not to search for the string angle.
Collapse M_ENABLE

Specifies to search for the string angle.
Collapse M_SPACE_CHARACTER +

Inquires the character value to use as a space character within the formatted text that will be read. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is numerical ASCII code 32.
Collapse M_NONE

Specifies no space character.
Collapse Value

Specifies the space character, as its numerical code (ASCII or Unicode). INFO
Collapse M_SPEED +

Inquires the search/read speed. SET

(summarize)
Collapse M_DEFAULT

Same as M_MEDIUM.
Collapse M_HIGH

Specifies a high speed.
Collapse M_MEDIUM

Specifies a medium speed.
Collapse M_STRING_SEPARATOR +

Inquires the character value to use as a string separator within the formatted text that will be read. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is numerical ASCII code 10.
Collapse M_NONE

Specifies no separator character.
Collapse Value

Specifies the separator character, as its numerical code (ASCII or Unicode). INFO
Collapse M_THICKEN_CHAR +

Inquires the number of character thickening iterations. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.
Collapse 0 <= Value <= 100

Specifies the number of character thickening iterations.
Collapse M_THRESHOLD_MODE +

Inquires the threshold method of the character blob extraction. SET

(summarize)
Collapse M_DEFAULT

Same as M_LOCAL_WITH_RESEGMENTATION.
Collapse M_LOCAL

Specifies local thresholding that uses only one threshold step that is automatically computed by the module. INFO
Collapse M_LOCAL_WITH_RESEGMENTATION

Specifies local thresholding that uses multiple threshold steps and split and merge techniques. INFO
Collapse M_USER_DEFINED

Specifies global thresholding that uses the threshold value set with M_THRESHOLD_VALUE. INFO
Collapse M_THRESHOLD_VALUE +

Inquires the global threshold value when M_THRESHOLD_MODE is set to M_USER_DEFINED (otherwise it is ignored). SET

(summarize)
Collapse M_DEFAULT

Same as M_AUTO_COMPUTE.
Collapse M_AUTO_COMPUTE

Specifies to automatically compute the global threshold value.
Collapse 0 <= Value <= 255

Specifies the threshold value.
Collapse M_TIMEOUT +

Inquires the maximum read time for MstrRead(), in msec. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 2000.0 msec.
Collapse M_DISABLE

Specifies an infinite amount of read time.
Collapse Value >= 0

Specifies the maximum read time, in msec.

For a specific string (M_STRING_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For an individual string
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_CHAR_ACCEPTANCE +

Inquires the acceptance level for the character score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0%.
Collapse 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Collapse M_CHAR_ASPECT_RATIO_MAX_FACTOR +

Inquires the factor used to determine the upper limit of the aspect ratio for the characters in the string.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.1.
Collapse 1.0 <= Value <= 2.0

Specifies the factor that determines the maximum aspect ratio of the characters in the string.
Collapse M_CHAR_ASPECT_RATIO_MIN_FACTOR +

Inquires the factor used to determine the lower limit of the aspect ratio for the characters in the string.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.9.
Collapse 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum aspect ratio of the characters in the string.
Collapse M_CHAR_HOMOGENEITY_ACCEPTANCE +

Inquires the acceptance level for the character's homogeneity score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0%.
Collapse 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Collapse M_CHAR_MAX_BASELINE_DEVIATION +

Inquires the maximum deviation that a character can have from the string's baseline. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 10.
Collapse 0 <= Value <= 100

Specifies the character's maximum baseline deviation within the string model.
Collapse M_CHAR_SCALE_MAX_FACTOR +

Inquires the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.1.
Collapse 1.0 <= Value <= 2.0

Specifies the factor that determines the maximum scale of the characters in the string.
Collapse M_CHAR_SCALE_MIN_FACTOR +

Inquires the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.9.
Collapse 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum scale of the characters in the string.
Collapse M_CHAR_SIMILARITY_ACCEPTANCE +

Inquires the acceptance level for the character's similarity score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0%.
Collapse 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Collapse M_DEFAULT_CONSTRAINT_FONT +

Inquires the font index for each default font constraint.

The default constraint is applied, by default, either for all positions of the string model, if no explicit constraint has been set, or for a specific position, if M_DEFAULT has been set for a specific position.

This information can also be inquired using MstrInquire() with M_DEFAULT_CONSTRAINT_TYPE; however, it is encoded with other constant values.

M_DEFAULT_CONSTRAINT_FONT always returns a single value.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse 0 <= Value <= 255

Specifies the index of the individual font from which the constraint is taken. INFO
Collapse M_DEFAULT_CONSTRAINT_TYPE +

Inquires the default constraint type.

The default constraint is applied, by default, either for all positions of the string model, if no explicit constraint has been set, or for a specific position, if M_DEFAULT has been set for a specific position.

M_DEFAULT_CONSTRAINT_TYPE always returns a single value.

(summarize)
Collapse Value

Specifies the default constraint type.
Collapse M_FOREGROUND_VALUE +

Inquires the foreground color of the string. SET

(summarize)
Collapse M_DEFAULT

Same as M_FOREGROUND_BLACK.
Collapse M_FOREGROUND_BLACK

Specifies that black is the foreground color of the string.
Collapse M_FOREGROUND_BLACK_OR_WHITE

Specifies that the foreground color of the string can be either black or white.
Collapse M_FOREGROUND_WHITE

Specifies that white is the foreground color of the string.
Collapse M_NUMBER_OF_CONSTRAINTS +

Inquires the number of positions in the string that have a non-default constraint. Non-default constraints are constraints that have been set to a value other than M_DEFAULT.

Constraints are added to a string using MstrSetConstraint().

(summarize)
Collapse Value

Specifies the number of positions that have a constraint.
Collapse M_SPACE_MAX_CONSECUTIVE +

Inquires the maximum number of consecutive space characters allowed in the string. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 3.
Collapse Value >= 0

Specifies the maximum number of consecutive space characters.
Collapse M_STRING_ACCEPTANCE +

Inquires the acceptance level for the string score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0%.
Collapse 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Collapse M_STRING_ANGLE +

Inquires the nominal angle of the string. SET

(summarize)
Collapse M_DEFAULT

Same as M_ACCORDING_TO_REGION.
Collapse M_ACCORDING_TO_REGION

Specifies to set the nominal angle to the angle of the rectangular ROI (set using MbufSetRegion()) in the image. INFO
Collapse M_STRING_ANGLE_DELTA_NEG +

Inquires the lower limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 10.0°.
Collapse 0.0 <= Value <= 10.0

Specifies the lower limit of the angular range, in degrees.
Collapse M_STRING_ANGLE_DELTA_POS +

Inquires the upper limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 10.0°.
Collapse 0.0 <= Value <= 10.0

Specifies the upper limit of the angular range, in degrees.
Collapse M_STRING_ASPECT_RATIO +

Inquires the nominal aspect ratio of the string.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.0.
Collapse 0.5 <= Value <= 2.0

Specifies the ratio of pixel width to pixel height of the target.
Collapse M_STRING_ASPECT_RATIO_MAX_FACTOR +

Inquires the factor used to determine the upper limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO).

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.25.
Collapse 1.0 <= Value <= 2.0

Specifies the factor that determines the maximum aspect ratio of the string.
Collapse M_STRING_ASPECT_RATIO_MIN_FACTOR +

Inquires the factor used to determine the lower limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO).

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.8.
Collapse 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum aspect ratio of the string.
Collapse M_STRING_CERTAINTY +

Inquires the certainty level for the string score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 70.0%.
Collapse 0.0 <= Value <= 100.0

Specifies the certainty level for the string score, as a percentage.
Collapse M_STRING_SCALE +

Inquires the nominal scale of the string. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.0.
Collapse 0.25 <= Value <= 4.0

Specifies the value of the scale.
Collapse M_STRING_SCALE_MAX_FACTOR +

Inquires the factor used to determine the upper limit (maximum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 2.0.
Collapse 1.0 <= Value <= 2.0

Specifies the factor that determines the minimum scale of the string.
Collapse M_STRING_SCALE_MIN_FACTOR +

Inquires the factor used to determine the lower limit (minimum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.5.
Collapse 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum scale of the string.
Collapse M_STRING_SIZE_MAX +

Inquires the maximum string size (number of characters) of the string model. SET

(summarize)
Collapse M_DEFAULT

Same as M_INFINITE.
Collapse M_INFINITE

Specifies no maximum string size.
Collapse Value >= 1

Specifies the maximum string size.
Collapse M_STRING_SIZE_MIN +

Inquires the minimum string size (number of characters) of the string model. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1.
Collapse Value >= 1

Specifies the minimum string size.
Collapse M_STRING_TARGET_ACCEPTANCE +

Inquires the acceptance level for the string target score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0%.
Collapse 0.0 <= Value <= 100.0

Specifies an acceptable string target score, as a percentage.
Collapse M_STRING_TARGET_CERTAINTY +

Inquires the certainty level for the string target score. SET

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 70.0%.
Collapse 0.0 <= Value <= 100.0

Specifies the certainty level for the string target score, as a percentage.
Collapse M_STRING_TYPE +

Inquires the type of the string model added to the String Reader context. SET

(summarize)
Collapse M_DEFAULT

Same as M_USER_DEFINED.
Collapse M_USER_DEFINED

Specifies a user-defined type of string model. INFO
Collapse M_STRING_USER_LABEL +

Inquires the string model's user-defined label. SET

(summarize)
Collapse M_DEFAULT

Same as M_NO_LABEL.
Collapse M_NO_LABEL

Specifies that no user label is associated with the string model.
Collapse Value

Specifies the user label of the string model. INFO

For a specific string (M_STRING_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of an array of type MIL_DOUBLE with a size equal to M_NUMBER_OF_CONSTRAINTS results .

function map For an individual string when specifying constraints
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_CONSTRAINT +

Inquires the constraint string at the specified index.

Unless a data type from the table For specifying the data type is explicitly added to M_CONSTRAINT, the string array type corresponds to the encoding scheme selected with M_ENCODING. The string returned is null-terminated. SET


You must specify a combination value from the following table:
(summarize)
Collapse UserVarPtr data type info
Collapse Value

Specifies the constraint string.
Collapse M_CONSTRAINT_ALLOC_SIZE +

Inquires the allocation size needed for each non-default constraint string. The allocation size of the constraint string includes the terminating 0 of the string.

(summarize)
Collapse Value

Specifies the size needed when retrieving the specified constraint string.
Collapse M_CONSTRAINT_FONT +

Inquires the font index for each non-default constraint of the string model. This information can also be inquired using MstrInquire() with M_CONSTRAINT_TYPE; however, it is encoded with other constant values.

You can inquire the position in the string model to which the constraint applies using MstrInquire() with M_CONSTRAINT_POSITION.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse 0 <= Value <= 255

Specifies the index of the individual font from which the constraint is taken. INFO
Collapse M_CONSTRAINT_POSITION +

Inquires the position of each non-default constraint in the string model (0, 255). The default constraint is therefore applied to all positions not returned in this array.

(summarize)
Collapse Value

Specifies the position of the constraint.
Collapse M_CONSTRAINT_TYPE +

Inquires the type of each non-default constraint of the string model (for example, M_LETTER, M_DIGIT). You can inquire the position in the string model to which this constraint applies using MstrInquire() with M_CONSTRAINT_POSITION. SET

(summarize)
Collapse Value

Specifies the constraint's type.
Collapse M_DEFAULT_CONSTRAINT +

Inquires a string of characters to which the default constraint was applied.

The default constraint is applied, by default, either for all positions of the string model, if no explicit constraint has been set, or for a specific position, if M_DEFAULT has been set for a specific position.

The string array must be large enough to contain M_DEFAULT_CONSTRAINT_ALLOC_SIZE characters.

Unless a data type from the table For specifying the data type is explicitly added to M_DEFAULT_CONSTRAINT, the string array type corresponds to the encoding scheme selected with M_ENCODING. The string returned is null-terminated.

(summarize)
Collapse UserVarPtr data type info
Collapse Value

Specifies the default constraint string.
Collapse M_DEFAULT_CONSTRAINT_ALLOC_SIZE +

Inquires the allocation size needed to get the default constraint string. The allocation size includes the terminating null character ("\0") of the default string. M_DEFAULT_CONSTRAINT_ALLOC_SIZE always returns a single value.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse Value

Specifies the size needed when retrieving the default constraint string.
Combination constant for M_CONSTRAINT.

You must add the following value to the above-mentioned value to get the constraint string at the specified index.

function map For M_CONSTRAINT to specify the index
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse 0 to (M_NUMBER_OF_CONSTRAINTS - 1)

Inquires the constraint string at the specified index.

The index you provide is the index of the constraint in the list of non-default constraints, and not its actual position in the string model. You can inquire the position in the string model that this constraint string applies to using MstrInquire() with M_CONSTRAINT_POSITION.

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: M_CONSTRAINT_ALLOC_SIZE characters.

For a specific font (M_FONT_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of an array of type MIL_DOUBLE with a size equal to M_NUMBER_OF_CHARS .

function map For an individual font
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_CHAR_BASELINE +

Inquires the setting for the baseline value for each character. To return the automatcially calculated character baseline (when M_CHAR_BASELINE is set to M_AUTO_COMPUTE), use M_CHAR_BASELINE_VALUE.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_AUTO_COMPUTE

Specifies that the baseline was automatically computed to an appropriate value.
Collapse M_NONE

Specifies no baseline.
Collapse -1000 <= Value <= 1000

Specifies the baseline value, as a percentage of the character's height. INFO
Collapse M_CHAR_BASELINE_VALUE +

Inquires the baseline value for each character. Note that when M_CHAR_BASELINE is set to M_AUTO_COMPUTE, this value will return the calculated character baseline.

Note that this inquire type is only available for a font-based context. SET

(summarize)
Collapse M_NONE

Specifies no baseline.
Collapse -1000 <= Value <= 1000

Specifies the baseline value, as a percentage of the character's height. INFO
Collapse M_CHAR_SIZE_X +

Inquires the X-size of each character in the font. SET SET

(summarize)
Collapse Value

Specifies the X-size of the character, in pixels.
Collapse M_CHAR_SIZE_Y +

Inquires the Y-size of each character in the font. SET SET

(summarize)
Collapse Value

Specifies the Y-size of the character, in pixels.
Collapse M_CHAR_THICKNESS +

Inquires the average thickness of each character in the font. SET

(summarize)
Collapse Value

Specifies the thickness of the character, in pixels.
Collapse M_CHAR_TYPE +

Inquires the type of each character in the font. SET

(summarize)
Collapse M_AUTO_COMPUTE

Specifies that the characters' type was computed automatically. INFO
Collapse M_PUNCTUATION

Specifies punctuation type characters. INFO
Collapse M_REGULAR

Specifies regular type characters. INFO
Collapse M_CHAR_TYPE_VALUE +

Inquires the type value of each character in the font. When the value of M_CHAR_TYPE is M_AUTO_COMPUTE, M_CHAR_TYPE_VALUE contains the auto-computed value (M_REGULAR or M_PUNCTUATION). For more information, see MstrEditFont() with M_CHAR_TYPE.

(summarize)
Collapse M_PUNCTUATION

Specifies punctuation type characters. INFO
Collapse M_REGULAR

Specifies regular type characters. INFO
Collapse M_DEFINITION_OFFSET_X +

Inquires the X-offset for each character in the font. The X- and Y-offsets define where the character is found in the definition image. This inquire type is only valid for user-defined characters (MstrEditFont() with M_USER_DEFINED).

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The array must be large enough to contain the offset for every character in the font. This number can be retrieved using MstrInquire() with M_NUMBER_OF_CHARS.

Collapse M_NONE

Specifies that the font in the String Reader context is a system font (MstrEditFont() with M_SYSTEM_FONT).
Collapse X-offset value

Specifies the X-offset of the character, in pixels.
Collapse M_DEFINITION_OFFSET_Y +

Inquires the Y-offset for each character in the font. The X- and Y-offsets define where the character is found in the definition image. This inquire type is only valid for user-defined characters (MstrEditFont() with M_USER_DEFINED).

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The array must be large enough to contain the offset for every character in the font. This number can be retrieved using MstrInquire() with M_NUMBER_OF_CHARS.

Collapse M_NONE

Specifies that the font in the String Reader context is a system font (MstrEditFont() with M_SYSTEM_FONT).
Collapse Y-offset value

Specifies the Y-offset of the character, in pixels.
Collapse M_DRAW_BOX_MARGIN_X +

Inquires the margin in the X-direction, between the character box and the drawing box. SET

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_DEFAULT

Specifies the default value; the default value is 3.
Collapse Value >= 0

Specifies the horizontal margin, in pixels.
Collapse M_DRAW_BOX_MARGIN_Y +

Inquires the margin in the Y-direction, between the character box and the drawing box. SET

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_DEFAULT

Specifies the default value; the default value is 3.
Collapse Value >= 0

Specifies the vertical margin, in pixels.
Collapse M_FONT_TYPE +

Inquires the type of font added. SET

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_DEFAULT

Same as M_USER_DEFINED.
Collapse M_USER_DEFINED

Specifies a user-defined type of font. INFO
Collapse M_FONT_USER_LABEL +

Inquires the font's user-defined label. SET

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_DEFAULT

Same as M_NO_LABEL.
Collapse M_NO_LABEL

Specifies that no user label is associated with the font.
Collapse Value

Specifies the user label of the font. INFO
Combination constant for the values listed in all the parameter association tables except For specifying the result for MstrGetResult, For inquiring about the system, For retrieving the meaning of an error or warning report value generated by MstrExpert(), For user label inquiries.

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

function map For the default value of an inquire type
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_DEFAULT

Inquires the actual default value of the specified inquire type.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

For a string result buffer (M_GENERAL), the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For specifying the result for MstrGetResult()
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_RESULT_OUTPUT_UNITS +

Inquires whether results are returned in pixel or world units. SET

(summarize)
Collapse M_ACCORDING_TO_CALIBRATION

Specifies that results are returned in world units if the result was calculated on an image associated with a calibration context; otherwise, specifies that results are returned in pixel units.
Collapse M_PIXEL

Specifies that results are returned in pixel units, with respect to the pixel coordinate system.
Collapse M_WORLD

Specifies that results are returned in world units, with respect to the relative coordinate system. INFO

To inquire about the system on which the String Reader context or result buffer has been allocated, set the InquireType parameter to the value below.

Note that the Index parameter must be set to M_CONTEXT for a String Reader context or to M_GENERAL for a result buffer.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For inquiring about the system
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_OWNER_SYSTEM +

Inquires the identifier of the system on which the String Reader context or result buffer was allocated. SET SET

(summarize)
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().

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

function map For specifying the data type
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_TYPE_CHAR

Casts the requested results to a char.

(summarize)
Collapse UserVarPtr data type info

  • Data type: char
    Note: When a single inquire.

  • Data type: array of type char
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_DOUBLE

Casts the requested results to a MIL_DOUBLE.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_DOUBLE
    Note: When a single inquire.

  • Data type: array of type MIL_DOUBLE
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_FLOAT

Casts the requested results to a MIL_FLOAT.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_FLOAT
    Note: When a single inquire.

  • Data type: array of type MIL_FLOAT
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_ID

Casts the requested results to a MIL_ID.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_ID
    Note: When a single inquire.

  • Data type: array of type MIL_ID
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_INT

Casts the requested results to a MIL_INT.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_INT
    Note: When a single inquire.

  • Data type: array of type MIL_INT
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_INT16

Casts the requested results to a MIL_INT16.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_INT16
    Note: When a single inquire.

  • Data type: array of type MIL_INT16
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_INT32

Casts the requested results to a MIL_INT32.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_INT32
    Note: When a single inquire.

  • Data type: array of type MIL_INT32
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_MIL_INT64

Casts the requested results to a MIL_INT64.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_INT64
    Note: When a single inquire.

  • Data type: array of type MIL_INT64
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.
Collapse M_TYPE_TEXT_CHAR

Casts the requested results to a MIL_TEXT_CHAR.

(summarize)
Collapse UserVarPtr data type info

  • Data type: MIL_TEXT_CHAR
    Note: When a single inquire.

  • Data type: array of type MIL_TEXT_CHAR
    Array size: Size depends on the contents of the array.
    Note: When multiple inquires.

For retrieving the meaning of an error or warning code generated by MstrExpert(), and retrieved using MstrGetResult() with M_REPORT_..., the InquireType parameter can be set to the following value.

function map For retrieving the meaning of an error or warning report value generated by MstrExpert()
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_REPORT_STRING +

Inquires the error message associated with an error or warning code generated by MstrExpert().

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: M_MAX_REPORT_STRING_LENGTH

You can add the following value to the above-mentioned values to determine whether an inquire type is supported.

function map For inquiring whether an inquire type is supported
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_SUPPORTED

Inquires whether the specified inquire type is supported for the String Reader context.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_NULL

Specifies that the inquire type is not supported.
Collapse Value != 0

Specifies that the inquire type is supported.

For user label inquiries, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For user label inquiries
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_FONT_INDEX_FROM_LABEL

Inquires the font index associated with a font user label if the user label is used.

Note that this inquire type is only available for a font-based context.

(summarize)
Collapse M_INVALID

Specifies that the user label is invalid. This is returned if the specified user label is not associated with a font.

(summarize)
Collapse Value

Specifies the font index associated with the specified user label.
Collapse M_STRING_INDEX_FROM_LABEL

Inquires the string model index associated with a string model user label if the user label is used.

(summarize)
Collapse M_INVALID

Specifies that the user label is invalid. This is returned if the specified user label is not associated with a string model.

(summarize)
Collapse Value

Specifies the string model index associated with the specified user label.
Return value
The returned value is the requested information, cast to a MIL_INT. If the requested information is not a single value, this function will return M_NULL.
Compilation information
Header Include mil.h.
Library Use mil.lib; milstr.lib.
DLL Requires mil.dll; milstr.dll.
DEFAULT CONTEXT GENERAL STRING NUMBER DEFAULT ALL CHAR VALUE NUMBER OF CHARS SPACE WIDTH DEFAULT INFINITE MAX CHAR WIDTH MEAN CHAR WIDTH MIN CHAR WIDTH QUARTER MAX CHAR WIDTH SPACE WIDTH VALUE CHAR STATUS DISABLE ENABLE CONTEXT TYPE FONT BASED FONTLESS DRAW LAST SIZE X DRAW LAST SIZE Y ENCODING DEFAULT ASCII UNICODE MAX CHAR SIZE X DEFAULT MIN CHAR SIZE X DEFAULT MINIMUM CONTRAST DEFAULT MODIFICATION COUNT NUMBER OF FONTS NUMBER OF STRING MODELS PREPROCESSED REF CHAR SIZE Y DEFAULT REF CHAR THICKNESS DEFAULT SEARCH CHAR ANGLE DEFAULT DISABLE ENABLE SEARCH SKEW ANGLE DEFAULT DISABLE ENABLE SEARCH STRING ANGLE DEFAULT DISABLE ENABLE SPACE CHARACTER DEFAULT NONE SPEED DEFAULT HIGH MEDIUM STRING SEPARATOR DEFAULT NONE THICKEN CHAR DEFAULT THRESHOLD MODE DEFAULT LOCAL LOCAL WITH RESEGMENTATION USER DEFINED THRESHOLD VALUE DEFAULT AUTO COMPUTE TIMEOUT DEFAULT DISABLE CHAR ACCEPTANCE DEFAULT CHAR ASPECT RATIO MAX FACTOR DEFAULT CHAR ASPECT RATIO MIN FACTOR DEFAULT CHAR HOMOGENEITY ACCEPTANCE DEFAULT CHAR MAX BASELINE DEVIATION DEFAULT CHAR SCALE MAX FACTOR DEFAULT CHAR SCALE MIN FACTOR DEFAULT CHAR SIMILARITY ACCEPTANCE DEFAULT DEFAULT CONSTRAINT FONT DEFAULT CONSTRAINT TYPE FOREGROUND VALUE DEFAULT FOREGROUND BLACK FOREGROUND BLACK OR WHITE FOREGROUND WHITE NUMBER OF CONSTRAINTS SPACE MAX CONSECUTIVE DEFAULT STRING ACCEPTANCE DEFAULT STRING ANGLE DEFAULT ACCORDING TO REGION STRING ANGLE DELTA NEG DEFAULT STRING ANGLE DELTA POS DEFAULT STRING ASPECT RATIO DEFAULT STRING ASPECT RATIO MAX FACTOR DEFAULT STRING ASPECT RATIO MIN FACTOR DEFAULT STRING CERTAINTY DEFAULT STRING SCALE DEFAULT STRING SCALE MAX FACTOR DEFAULT STRING SCALE MIN FACTOR DEFAULT STRING SIZE MAX DEFAULT INFINITE STRING SIZE MIN DEFAULT STRING TARGET ACCEPTANCE DEFAULT STRING TARGET CERTAINTY DEFAULT STRING TYPE DEFAULT USER DEFINED STRING USER LABEL DEFAULT NO LABEL CONSTRAINT CONSTRAINT ALLOC SIZE CONSTRAINT FONT CONSTRAINT POSITION CONSTRAINT TYPE DEFAULT CONSTRAINT DEFAULT CONSTRAINT ALLOC SIZE NUMBER OF CONSTRAINTS - 1) CHAR BASELINE AUTO COMPUTE NONE CHAR BASELINE VALUE NONE CHAR SIZE X CHAR SIZE Y CHAR THICKNESS CHAR TYPE AUTO COMPUTE PUNCTUATION REGULAR CHAR TYPE VALUE PUNCTUATION REGULAR DEFINITION OFFSET X NONE DEFINITION OFFSET Y NONE DRAW BOX MARGIN X DEFAULT DRAW BOX MARGIN Y DEFAULT FONT TYPE DEFAULT USER DEFINED FONT USER LABEL DEFAULT NO LABEL DEFAULT RESULT OUTPUT UNITS ACCORDING TO CALIBRATION PIXEL WORLD OWNER SYSTEM DEFAULT HOST TYPE CHAR TYPE MIL DOUBLE TYPE MIL FLOAT TYPE MIL ID TYPE MIL INT TYPE MIL INT16 TYPE MIL INT32 TYPE MIL INT64 TYPE TEXT CHAR REPORT STRING SUPPORTED NULL FONT INDEX FROM LABEL INVALID STRING INDEX FROM LABEL INVALID DEFAULT CONTEXT STRING INDEX FONT INDEX DEFAULT GENERAL ASCII UNICODE