MsiFormatRecord

[This is preliminary documentation and subject to change.]

The MsiFormatRecord function formats record field data and properties using a format string.

UINT MsiFormatRecord(
  MSIHANDLE hInstall,    // installer handle
  MSIHANDLE hRecord,     // record to execute
  LPTSTR szResultBuf,    // buffer to return formatted string
  DWORD *pcchResultBuf   // in/out buffer character count
);
 

Parameters

hInstall

Handle to the installation. This may be omitted, in which case only the record field parameters are processed and properties are not available for substitution.

hRecord

Handle to the record to format. The template string must be stored in record field 0 followed by referenced data parameters.

szResultBuf

Specifies the buffer to return the formatted string to.

pcchResultBuf

Specifies the in/out character count.

Return Values

ERROR_INVALID_HANDLE

An invalid or inactive handle was supplied.

ERROR_INVALID_PARAMETER

An invalid parameter was passed to the function.

ERROR_MORE_DATA

A buffer was too small to hold the entire value.

ERROR_SUCCESS

The function succeeded.

Remarks

The MsiFormatRecord function uses the following format process.

Parameters that are to be formatted are enclosed in square brackets [...]. The square brackets can be iterated because the substitutions are resolved from the inside out.

If a part of the string is enclosed in curly braces { } and contains no square brackets, it is left unchanged, including the curly braces.

If a part of the string is enclosed in curly braces { } and contains one or more property names, and if all the properties are found, the text (with the resolved substitutions) is displayed without the curly braces. If any of the properties is not found, all the text in the braces and the braces themselves are removed.

The following steps describe how to format strings using the MsiFormatRecord function:

    To format strings using the MsiFormatRecord function

1. The numeric parameters are substituted by replacing the marker with the value of the corresponding record field, with missing or null values producing no text.
2. The resultant string is processed by replacing the non-record parameters with the corresponding values, described next.
   • If a substring of the form [propertyname] is encountered, it is replaced by the value of the property.
   • If a substring of the form [%environmentvariable] is found, the value of the environment variable is substituted.
   • If a substring of the form [#filekey] is found, it is replaced by the full path of the file, with the value filekey used as a key into the File table.
   • If a substring of the form [$componentkey] is found, it is replaced by the installation directory of the component, with the value componentkey used as a key into the Component table, taking into account the Component.Action column state. If the component is selected to be installed locally, it is replaced by the target directory. If the component is selected to run from source, it is replaced by the source directory. If the component is not selected or if the component is missing, it is replaced by a null string.
   • If a substring of the form [\c] is found, it is replaced by the character without any further processing. Only the first character after the backslash is kept; everything else is removed.

QuickInfo

  Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
  Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in msiquery.h.
  Import Library: Use msi.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.