MsiFormatRecordA function (msiquery.h)

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

Syntax

UINT MsiFormatRecordA(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPSTR     szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

Parameters

[in] 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.

[in] hRecord

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

[out] szResultBuf

Pointer to the buffer that receives the null terminated formatted string. Do not attempt to determine the size of the buffer by passing in a null (value=0) for szResultBuf. You can get the size of the buffer by passing in an empty string (for example ""). The function then returns ERROR_MORE_DATA and pcchResultBuf contains the required buffer size in TCHARs, not including the terminating null character. On return of ERROR_SUCCESS, pcchResultBuf contains the number of TCHARs written to the buffer, not including the terminating null character.

[in, out] pcchResultBuf

Pointer to the variable that specifies the size, in TCHARs, of the buffer pointed to by the variable szResultBuf. When the function returns ERROR_SUCCESS, this variable contains the size of the data copied to szResultBuf, not including the terminating null character. If szResultBuf is not large enough, the function returns ERROR_MORE_DATA and stores the required size, not including the terminating null character, in the variable pointed to by pcchResultBuf.

Return value

The MsiFormatRecord function returns one of the following values:

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.

Note in the case of deferred execution custom actions, MsiFormatRecord only supports CustomActionData and ProductCode properties. For more information, see Obtaining Context Information for Deferred Execution Custom Actions.

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 nonrecord 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. The value of "[#filekey]" remains blank and is not replaced by a path until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of "[#filekey]" depends upon the installation state of the component to which the file belongs. If the component is being run from source, the value is the path to the source location of the file. If the component is being run locally, the value is the path to the target location of the file after installation. If the component is absent, the path is blank. For more information about checking the installation state of components, see Checking the Installation of Features, Components, Files.
   • If a substring of the form "[$componentkey]" is found, it is replaced by the install directory of the component, with the value componentkey used as a key into the Component table. The value of "[$componentkey]" remains blank and is not replaced by a directory until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of "[$componentkey]" depends upon the installation state of the component. If the component is being run from source, the value is the source directory of the file. If the component is being run locally, the value is the target directory after installation. If the component is absent, the value is left blank. For more information about checking the installation state of components, see Checking the Installation of Features, Components, Files.
   • Note that if a component is already installed, and is not being reinstalled, removed, or moved during the current installation, the action state of the component is null and therefore the string "[$componentkey]" evaluates to Null.
   • 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.

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Requirement	Value
Minimum supported client	Windows Installer 5.0 on Windows Server 2012, Windows 8, Windows Server 2008 R2 or Windows 7. Windows Installer 4.0 or Windows Installer 4.5 on Windows Server 2008 or Windows Vista.
Target Platform	Windows
Header	msiquery.h
Library	Msi.lib
DLL	Msi.dll

See also

Passing Null as the Argument of Windows Installer Functions