Windows API Class -- Entisoft Tools 1.3 Object Library

Windows API Class

Entisoft Tools 1.3 Object Library
Version 1.3.18 Released 1998/10/19 2329
Index || Up to Contents || Topics
<-- (VBUtilities) Previous || Declarations || Next (EntisoftToolsPort) -->

Declarations Section, CharToOem Function, CoerceBooleanToInteger Function, CoerceCurrencyToDouble Function, CoerceDoubleToCurrency Function, CoerceIntegerToBoolean Function, CoerceLongToSingle Function, CoerceSingleToLong Function, CoerceTwoBytesToInteger Function, CoerceTwoIntegersToLong Function, CoerceTwoLongsToDouble Function, DRIVE_CDROM Property, DRIVE_FIXED Property, DRIVE_RAMDISK Property, DRIVE_REMOTE Property, DRIVE_REMOVABLE Property, DRIVEConstantToString Function, GetDriveType Function, GetDriveTypeSample Sub, GetModuleFileName Function, GetSystemDirectory Property, GetTempPath Property, GetTempFileName Function, GetWindowsDirectory Property, GetWindowsVersion Property, HIBYTE Function, HIDWORD Function, HIWORD Function, LOBYTE Function, LODWORD Function, LOWORD Function, OemToChar Function, ShellNoWait Function, ShellWait Function, ProfileFileName Property, ProfileSectionName Property, GetPrivateProfileInt Function, GetPrivateProfileSection Function, GetPrivateProfileSectionSample Sub, GetPrivateProfileString Function, GetProfileInt Function, GetProfileSection Function, GetProfileSectionSample Sub, GetProfileString Function, WritePrivateProfileString Function, WriteProfileString Function

Declarations Section
Char To Oem Function: "ANSI Characters To OEM Characters" Converts ANSI (Windows) characters to the OEM (DOS) character set. Used to be known as AnsiToOem.
Coerce Boolean To Integer Function: Coerce a Boolean value into an Integer value. Return the Integer value whose bytes have the same in-memory representation as the Boolean value vValue.
Coerce Currency To Double Function: Coerce a Currency value into a Double value. Return the Double value whose bytes have the same in-memory representation as the Currency value vcurValue. Inverse of the CoerceDoubleToCurrency Function.
Coerce Double To Currency Function: Coerce a Double value into a Currency value. Return the Currency value whose bytes have the same in-memory representation as the Double value vValue. Inverse of the CoerceCurrencyToDouble Function.
Coerce Integer To Boolean Function: Coerce an Integer value into a Boolean value. Return the Boolean value whose bytes have the same in-memory representation as the Integer value vValue.
Coerce Long To Single Function: Coerce a Long (Integer) value into a Single (precision floating-point) value. Return the Single value whose bytes have the same in-memory representation as the Long value vValue. Inverse of the CoerceSingleToLong Function.
Coerce Single To Long Function: Coerce a Single (precision floating-point) value into a Long (Integer) value. Return the Long value whose bytes have the same in-memory representation as the Single value vValue. Inverse of the CoerceLongToSingle Function.
Coerce Two Bytes To Integer Function: Coerce two Byte values into an Integer value. Return the Integer value whose low-order byte (first, least-significant-byte) is vLo and whose high-order byte (last, most-significant-byte) is vHi. Inverse/opposite of the HIBYTE and LOBYTE functions.
Coerce Two Integers To Long Function: Coerce two Integer values into a Long (Integer) value. Return the Long value whose low-order word (2 bytes) has the same representation as vLo, and whose high-order word has the same representation as vHi. Inverse/opposite of the HIWORD and LOWORD functions.
Coerce Two Longs To Double Function: Coerce two Long (Integer) values into a Double (precision floating-point) value. Return the Double value whose low-order double-word (4 bytes) has the same representation as vLo, and whose high-order double-word has the same representation as vHi. Inverse/opposite of the HIDWORD and LODWORD functions.
DRIVE_CDROM Property: "Drive Type Is CD-ROM" The GetDriveType Function returns this value to indicate that the specified drive is a CD-ROM.
DRIVE_FIXED Property: "Drive Type Is Fixed" The GetDriveType Function returns this value to indicate that the specified drive is a fixed disk, such as a hard disk.
DRIVE_RAMDISK Property: "Drive Type Is RAM Disk" The GetDriveType Function returns this value to indicate that the specified drive is a RAM disk.
DRIVE_REMOTE Property: "Drive Type Is Remote" The GetDriveType Function returns this value to indicate that the specified drive is a remote (network) drive.
DRIVE_REMOVABLE Property: "Drive Type Is Removable" The GetDriveType Function returns this value to indicate that the specified drive is a removable disk, such as a floppy disk, removable hard disk, or optical disk.
DRIVE Constant To String Function: Return a word that describes one of the DRIVE Constants.
Get Drive Type Function: Returns a number describing the type of drive (storage device) that is attached to a drive letter A..Z. The number returned should be one of the DRIVE Constants.
Get Drive Type Sample Sub: Sample of the GetDriveType function that prints the type of each of the drives A through Z.
Get Module File Name Function: Return the file name of the program associated with the Windows Module Handle vModuleHandle.
Get System Directory Property: "Get Windows System Directory Name" Returns the name of the Windows system directory, usually "C:\WINDOWS\SYSTEM"
Get Temp Path Property: "Get Temporary Path Name" Returns the name of the Windows temporary directory.
Get Temp File Name Function: "Get Temporary File Name" Creates an empty file (usually in the Windows temporary file directory) and returns the name of the file. File will be located in directory vSuggestPath and will have prefix vPrefix.
Get Windows Directory Property: "Get Windows Directory Name" Returns the name of the user's Windows directory, usually "C:\WINDOWS"
Get Windows Version Property: Get the version number of Microsoft Windows and return it in the form of a string.
HIBYTE Function: "High Byte" Return the high-order byte of an Integer value. Return the Byte value whose in-memory representation is the same as the left-most, most-significant-byte of Integer value vValue.
HIDWORD Function: "High Double Word" Return the high-order double-word (4 bytes) of a Double (precision floating-point) value. Return the Long (Integer) value whose in-memory representation is the same as the left-most, most-significant double-word of Double value vValue.
HIWORD Function: "High Word" Return the high-order word (2 bytes) of a Long (Integer) value. Return the Integer value whose in-memory representation is the same as the left-most, most-significant-word of Long value vValue.
LOBYTE Function: "Low Byte" Return the low-order byte of an Integer value. Return the Byte value whose in-memory representation is the same as the right-most, least-significant-byte of Integer value vValue.
LODWORD Function: "Low Double Word" Return the low-order double-word (4 bytes) of a Double (precision floating-point) value. Return the Long (Integer) value whose in-memory representation is the same as the right-most, least-significant double-word of Double value vValue.
LOWORD Function: "Low Word" Return the low-order word (2 bytes) of a Long (Integer) value. Return the Integer value whose in-memory representation is the same as the right-most, least-significant-word of Long value vValue.
Oem To Char Function: "OEM Characters To ANSI Characters" Converts OEM (DOS) characters to the ANSI (Windows) character set. Used to be known as OemToAnsi.
Shell No Wait Function: Executes a Windows or DOS program without waiting for it to complete. Its window gets the specified focus. Function optionally sends keystrokes to the program. Function returns either 0 (zero) upon success or the number of the error encountered.
Shell Wait Function: Executes a Windows or DOS program and wait for it to complete. Its window gets the specified focus. Function optionally sends keystrokes to the program. Function returns either 0 (zero) upon success or the number of the error encountered.
Profile File Name Property: Specifies the Private Profile (INI) file name that will be used by the Private Profile functions when their vFileName argument is missing or Null. Get the current value of the ProfileFileName Property. Set the current value of the ProfileFileName Property.
Profile Section Name Property: Specifies the Section Name that will be used by the Profile functions when their vSectionName argument is missing or Null. Get the current value of the ProfileSectionName Property. Set the current value of the ProfileSectionName Property.
Get Private Profile Int Function: "Get Private Profile Integer" Get the value of an Integer numeric setting from a Windows Private Profile (INI) file. Function returns a Long value.
Get Private Profile Section Function: Get all of the settings from a section of a Private Profile file and place them into a Variant array. Function returns True upon success and False upon failure.
Get Private Profile Section Sample Sub: Print a sample of the GetPrivateProfileSection function.
Get Private Profile String Function: Get the value of a String setting from a Windows Private Profile (INI) file.
Get Profile Int Function: "Get Profile Integer" Get the value of an (Integer) numeric setting from the Windows Registry. Function returns a Long value.
Get Profile Section Function: Get all of the settings from a section of the Windows Registry. Function returns True upon success and False upon failure.
Get Profile Section Sample Sub: Print a sample of the GetProfileSectionSample function.
Get Profile String Function: Get the value of a String setting from the Windows Registry.
Write Private Profile String Function: Writes a Key Name and Value pair into a Windows Private Profile (INI) file.
Write Profile String Function: Write a Key Name and Value pair into the Windows Registry.

Declarations Section
Windows API Class

Functions that wrap around various Windows API functions, making them easier to access.
Copyright 1998 Entisoft

Summary: The Windows API Class makes it easier to access certain frequently-used Windows API functions. These functions handle automatically handle the conversion of strings between Visual Basic and C where appropriate. This Class if organized into two parts. The first part includes everything but the profile/registry functions. The second part consists of the profile/registry functions. Within each section, the Objects are generally sorted by name.
Coerse: These functions provide alternate interpretations for the bytes that represent different types of values.
HIBYTE, et. al.: The HIBYTE and LOBYTE functions split values in half, returning the bytes in the form of some other value.
See also:

    CoerceMake Class
    ConvertValues Class
    BasicExtensions Class
    FileNames Class

Char To Oem Function
Windows API Class

Public Function CharToOem( _
    ByVal vANSIString As Variant _
    ) As Variant

"ANSI Characters To OEM Characters"
Converts ANSI (Windows) characters to the OEM (DOS) character set.
Used to be known as AnsiToOem.

Example:

    CharToOem("Hawaii") = "Hawaii"

See also:

    OemToChar Function
    CharToOem (Windows API)

vANSIString: String that contains characters from the ANSI Windows character set. Function returns Null if vANSIString is Null or cannot be fixed-up to a String.
Return value: The result string contains the corresponding characters from the OEM character set.
v1.3 Change: Removed 16-bit support from this function.

Coerce Boolean To Integer Function
Windows API Class

Public Function CoerceBooleanToInteger( _
    ByVal vValue As Boolean _
    ) As Integer

Coerce a Boolean value into an Integer value.
Return the Integer value whose bytes have the same in-memory representation as the Boolean value vValue.

Examples:

    CoerceBooleanToInteger(True) = -1
    CoerceBooleanToInteger(False) = 0

See also:

    CoerceIntegerToBoolean Function
    MakeBoolean Function
    CoerceToInteger Function

vValue: The Boolean value whose bytes are to be interpreted as an Integer.
Note: We are not sure if this function has any use, but we included it to be consistent and complete.

Coerce Currency To Double Function
Windows API Class

Public Function CoerceCurrencyToDouble( _
    ByVal vcurValue As Currency _
    ) As Double

Coerce a Currency value into a Double value.
Return the Double value whose bytes have the same in-memory representation as the Currency value vcurValue.
Inverse of the CoerceDoubleToCurrency Function.

Examples:

    CoerceCurrencyToDouble(1) = 4.94065645841247E-320
    CoerceCurrencyToDouble(2) = 9.88131291682493E-320
    CoerceCurrencyToDouble(461168601842738.7904) = 2.0000000000001
    CoerceCurrencyToDouble(460718241880001.7408) = 1.00000000000002

See also:

    CoerceDoubleToCurrency Function
    MakeCurrency Function
    CoerceToDouble Function

Note: Similar to but faster than using the MakeCurrency and CoerceToDouble functions.

Coerce Double To Currency Function
Windows API Class

Public Function CoerceDoubleToCurrency( _
    ByVal vValue As Double _
    ) As Currency

Coerce a Double value into a Currency value.
Return the Currency value whose bytes have the same in-memory representation as the Double value vValue.
Inverse of the CoerceCurrencyToDouble Function.

Examples:

    CoerceDoubleToCurrency(1) = 460718241880001.7408
    CoerceDoubleToCurrency(2) = 461168601842738.7904
    CoerceDoubleToCurrency(4.94065645841247E-320) = 1
    CoerceDoubleToCurrency(9.88131291682493E-320) = 2

See also:

    CoerceCurrencyToDouble Function
    MakeDouble Function
    CoerceToCurrency Function

Note: Similar to but faster than using the MakeDouble and CoerceToCurrency functions.

Coerce Integer To Boolean Function
Windows API Class

Public Function CoerceIntegerToBoolean( _
    ByVal vValue As Integer _
    ) As Boolean

Coerce an Integer value into a Boolean value.
Return the Boolean value whose bytes have the same in-memory representation as the Integer value vValue.

Examples:

    CoerceIntegerToBoolean(-1) = True
    CoerceIntegerToBoolean(0) = False
    CoerceIntegerToBoolean(1) = True
    CoerceIntegerToBoolean(56) = True

See also:

    CoerceBooleanToInteger Function
    MakeInteger Function
    CoerceToBoolean Function

Note: Since Boolean value are not capable of representing the same range of values as Integers, CoerceBooleanToInteger(CoerceIntegerToBoolean(X)) will likely not equal X.
Note: We are not sure if this function has any use, but we included it to be consistent and complete.

Coerce Long To Single Function
Windows API Class

Public Function CoerceLongToSingle( _
    ByVal vValue As Long _
    ) As Single

Coerce a Long (Integer) value into a Single (precision floating-point) value.
Return the Single value whose bytes have the same in-memory representation as the Long value vValue.
Inverse of the CoerceSingleToLong Function.

Examples:

    CoerceLongToSingle(1) = 1.401298E-45
    CoerceLongToSingle(2) = 2.802597E-45
    CoerceLongToSingle(1065353216) = 1
    CoerceLongToSingle(1073741824) = 2

See also:

    CoerceSingleToLong Function
    MakeLong Function
    CoerceToSingle Function

Note: Similar to but faster than using the MakeLong and CoerceToSingle functions.

Coerce Single To Long Function
Windows API Class

Public Function CoerceSingleToLong( _
    ByVal vValue As Single _
    ) As Long

Coerce a Single (precision floating-point) value into a Long (Integer) value.
Return the Long value whose bytes have the same in-memory representation as the Single value vValue.
Inverse of the CoerceLongToSingle Function.

Examples:

    CoerceSingleToLong(1) = 1065353216
    CoerceSingleToLong(2) = 1073741824
    CoerceSingleToLong(1.401298E-45) = 1
    CoerceSingleToLong(2.802597E-45) = 2

See also:

    CoerceLongToSingle Function
    MakeSingle Function
    CoerceToLong Function

Note: Similar to but faster than using the MakeSingle and CoerceToLong functions.

Coerce Two Bytes To Integer Function
Windows API Class

Public Function CoerceTwoBytesToInteger( _
      ByVal vLo As Byte _
    , ByVal vHi As Byte _
    ) As Integer

Coerce two Byte values into an Integer value.
Return the Integer value whose low-order byte (first, least-significant-byte) is vLo
and whose high-order byte (last, most-significant-byte) is vHi.
Inverse/opposite of the HIBYTE and LOBYTE functions.

Examples:

    CoerceTwoBytesToInteger(1, 2) = 513
    CoerceTwoBytesToInteger(2, 1) = 258
    CoerceTwoBytesToInteger(254, 255) = -2
    CoerceTwoBytesToInteger(255, 254) = -257

See also:

    HIBYTE Function
    LOBYTE Function
    MakeByte Function
    CoerceToInteger Function

Coerce Two Integers To Long Function
Windows API Class

Public Function CoerceTwoIntegersToLong( _
      ByVal vLo As Integer _
    , ByVal vHi As Integer _
    ) As Long

Coerce two Integer values into a Long (Integer) value.
Return the Long value whose low-order word (2 bytes) has the same representation as vLo,
and whose high-order word has the same representation as vHi.
Inverse/opposite of the HIWORD and LOWORD functions.

Examples:

    CoerceTwoIntegersToLong(1, 2) = 131073
    CoerceTwoIntegersToLong(2, 1) = 65538
    CoerceTwoIntegersToLong(0, 32767) = 2147418112
    CoerceTwoIntegersToLong(0, -32767) = -2147418112

See also:

    HIWORD Function
    LOWORD Function
    MakeInteger Function
    CoerceToLong Function

Coerce Two Longs To Double Function
Windows API Class

Public Function CoerceTwoLongsToDouble( _
      ByVal vLo As Long _
    , ByVal vHi As Long _
    ) As Double

Coerce two Long (Integer) values into a Double (precision floating-point) value.
Return the Double value whose low-order double-word (4 bytes) has the same representation as vLo,
and whose high-order double-word has the same representation as vHi.
Inverse/opposite of the HIDWORD and LODWORD functions.

Examples:

    CoerceTwoLongsToDouble(1, 2) = 4.24399158242461E-314
    CoerceTwoLongsToDouble(1, 3) = 6.36598737338988E-314
    CoerceTwoLongsToDouble(3, 1) = 2.12199579244747E-314
    CoerceTwoLongsToDouble(0, 1072693248) = 1
    CoerceTwoLongsToDouble(0, 1073741824) = 2

See also:

    HIDWORD Function
    LODWORD Function
    MakeLong Function
    CoerceToDouble Function

DRIVE_CDROM Property
Windows API Class

Public Property Get DRIVE_CDROM() As Long

"Drive Type Is CD-ROM"
The GetDriveType Function returns this value to indicate that the specified drive is a CD-ROM.

Example:

    Debug.Print "E is" & IIf(GetDriveType("E") = DRIVE_CDROM), "", " NOT") & " a CD-ROM."

See also:

    GetDriveType Function
    DRIVEConstantToString Function
    DRIVE_CDROM Define (Windows API)

DRIVE_FIXED Property
Windows API Class

Public Property Get DRIVE_FIXED() As Long

"Drive Type Is Fixed"
The GetDriveType Function returns this value to indicate that the specified drive is a fixed disk, such as a hard disk.

Example:

    Debug.Print "C is" & IIf(GetDriveType("C") = DRIVE_FIXED), "", " NOT") & " a fixed disk."

See also:

    GetDriveType Function
    DRIVEConstantToString Function
    DRIVE_FIXED Define (Windows API)

DRIVE_RAMDISK Property
Windows API Class

Public Property Get DRIVE_RAMDISK() As Long

"Drive Type Is RAM Disk"
The GetDriveType Function returns this value to indicate that the specified drive is a RAM disk.

Example:

    Debug.Print "F is" & IIf(GetDriveType("F") = DRIVE_RAMDISK), "", " NOT") & " a RAM disk."

See also:

    GetDriveType Function
    DRIVEConstantToString Function
    DRIVE_RAMDISK Define (Windows API)

DRIVE_REMOTE Property
Windows API Class

Public Property Get DRIVE_REMOTE() As Long

"Drive Type Is Remote"
The GetDriveType Function returns this value to indicate that the specified drive is a remote (network) drive.

Example:

    Debug.Print "Z is" & IIf(GetDriveType("Z") = DRIVE_REMOTE), "", " NOT") & " a remote drive."

See also:

    GetDriveType Function
    DRIVEConstantToString Function
    DRIVE_REMOTE Define (Windows API)

DRIVE_REMOVABLE Property
Windows API Class

Public Property Get DRIVE_REMOVABLE() As Long

"Drive Type Is Removable"
The GetDriveType Function returns this value to indicate that the specified drive is a removable disk, such as a floppy disk, removable hard disk, or optical disk.

Example:

    Debug.Print "A is" & IIf(GetDriveType("A") = DRIVE_REMOVABLE), "", " NOT") & " a removable drive."

See also:

    GetDriveType Function
    DRIVEConstantToString Function
    DRIVE_REMOVABLE Define (Windows API)

DRIVE Constant To String Function
Windows API Class

Public Function DRIVEConstantToString( _
    ByVal vDriveType As Variant _
    ) As Variant

Return a word that describes one of the DRIVE Constants.

Examples:

    DRIVEConstantToString(DRIVE_CDROM) = "CDROM"
    DRIVEConstantToString(DRIVE_FIXED) = "FIXED"
    DRIVEConstantToString(2938923) = "UNKNOWN"
    IsNull(DRIVEConstantToString(Null)) = True

See also:

    DRIVE_CDROM Property
    DRIVE_FIXED Property
    DRIVE_RAMDISK Property
    DRIVE_REMOTE Property
    DRIVE_REMOVABLE Property
    GetDriveType Function

vDriveType: Numeric constant that describes a type of storage device. Function returns Null if vDriveType is Null or cannot be fixed-up to a number. Function returns the string "UNKNOWN" if vDriveType is not one of the valid drive type identifiers.

Get Drive Type Function
Windows API Class

Public Function GetDriveType( _
    ByVal vDrive As Variant _
    ) As Variant

Returns a number describing the type of drive (storage device) that is attached to a drive letter A..Z.
The number returned should be one of the DRIVE Constants.

Examples:

    GetDriveType("A") = DRIVE_REMOVABLE
    GetDriveType("C") = DRIVE_FIXED

See also:

    DRIVE_CDROM Property, et. al.
    DRIVEConstantToString Function
    GetDriveTypeSample Subroutine
    GetDriveType Function (Windows API)

vDrive: Letter of the drive whose type will be returned. Function returns Null if vDrive is Null or cannot be fixed-up to a String.
Return value: This function returns 1 (one) if the drive type cannot be determined.
v1.3 Change: Removed 16-bit support from this function.

Get Drive Type Sample Sub
Windows API Class

Private Sub GetDriveTypeSample()
    ' Sample of the GetDriveType function that
    ' prints the type of each of the drives A through Z.

    Dim intAsc As Integer
    For intAsc = Asc("A") To Asc("Z")
        Dim strDrive As String
        strDrive = Chr$(intAsc) + ":"

        Dim lngType As Integer
        lngType = GetDriveType(strDrive)

        Dim strType As String
        strType = DRIVEConstantToString(lngType)

        Debug.Print "Drive " & strDrive & " Type " & lngType & " " & strType
    Next intAsc
End Sub

Get Module File Name Function
Windows API Class

Public Function GetModuleFileName( _
    ByVal vModuleHandle As Variant _
    ) As Variant

Return the file name of the program associated with the Windows Module Handle vModuleHandle.

Example:

    GetModuleFileName(est.hInstance) = "C:\VB\VB32.EXE"

Note: You will likely get a different result when running this example.
See also:

    hInstance Application Class Property
    GetModuleFileName Function (Windows API)

vModuleHandle: Windows Module Handle for the program whose file name will be returned. Function returns Null if vModuleHandle is Null or cannot be fixed-up to a number.
v1.3 Change: Removed 16-bit support from this function.

Get System Directory Property
Windows API Class

Public Property Get GetSystemDirectory( _
    ) As String

"Get Windows System Directory Name"
Returns the name of the Windows system directory,
usually "C:\WINDOWS\SYSTEM"

Example:

    GetSystemDirectory = "C:\WINDOWS\SYSTEM"

See also:

    GetWindowsDirectory Property
    GetTempPath Function
    GetSystemDirectory Function (Windows API)

v1.3 Change: Removed 16-bit support from this function.

Get Temp Path Property
Windows API Class

Public Property Get GetTempPath( _
    ) As String

"Get Temporary Path Name"
Returns the name of the Windows temporary directory.

Example:

    GetTempPath = "C:\WINDOWS\TEMP"

See also:

    GetTempFileName Function
    EnvironToVariantVector Function
    GetSystemDirectory Property
    GetWindowsDirectory Property
    GetTempPath Function (Windows API)
    Environ Function (Visual Basic)

v1.3 Change: Removed 16-bit support from this function.

Get Temp File Name Function
Windows API Class

Public Function GetTempFileName( _
      Optional ByVal vSuggestPath As Variant _
    , Optional ByVal vPrefix As Variant _
    ) As String

"Get Temporary File Name"
Creates an empty file (usually in the Windows temporary file directory) and returns the name of the file.
File will be located in directory vSuggestPath and will have prefix vPrefix.

Examples:

    ? GetTempFileName(Null, Null)
    C:\TEMP\F185.TMP
    ? GetTempFileName("C:\WINDOWS", Null)
    C:\WINDOWS\34.TMP
    ? GetTempFileName("C:\WINDOWS", "ABCDEF")
    C:\WINDOWS\ABCC1.TMP
    ? GetTempFileName(Null, "ABCDEF")
    C:\TEMP\ABCF380.TMP

Note: You will likely get different results when you run these examples because the temporary file names are based partially upon the current time.
Note: These examples will create empty files with the specified names, so you may want to consider following each example with the Kill command to get rid of the file.
See also:

    GetTempPath Function
    GetTempFileName Function (Windows API)

vSuggestPath: A string that suggests the directory in where the temporary file should be created. vSuggestPath defaults to the Windows temporary directory (usually "C:\TEMP" or "C:\TEMP\WINDOWS") if it is missing or Null or cannot be fixed-up to a string. See the Microsoft Windows API documentation for the GetTempFileName function for more details about the suggested path argument.
vPrefix: A string that suggests the prefix of the temporary file name. All or part or none of the prefix may be used by the GetTempFileName (Microsoft Windows API) function. See the Microsoft Windows API documentation for the GetTempFileName function for more details about the prefix argument.
v1.3 Change: Removed 16-bit support from this function.

Get Windows Directory Property
Windows API Class

Public Property Get GetWindowsDirectory( _
    ) As String

"Get Windows Directory Name"
Returns the name of the user's Windows directory,
usually "C:\WINDOWS"

Example:

    GetWindowsDirectory = "C:\WINDOWS"

See also:

    GetSystemDirectory Property
    GetTempPath Function
    GetWindowsDirectory Function (Windows API)

v1.3 Change: Removed 16-bit support from this function.

Get Windows Version Property
Windows API Class

Public Property Get GetWindowsVersion( _
    ) As String

Get the version number of Microsoft Windows and return it in the form of a string.

Example:

    GetWindowsVersion = "4.0"

Note: Windows 95 is version "4.0".
See also:

    VersionNumberCompare Function
    GetVersion Function (Windows API)

v1.3 Change: Removed 16-bit support from this function.

HIBYTE Function
Windows API Class

Public Function HIBYTE( _
    ByVal vValue As Integer _
    ) As Byte

"High Byte"
Return the high-order byte of an Integer value.
Return the Byte value whose in-memory representation is the same as the left-most, most-significant-byte of Integer value vValue.

Examples:

    HIBYTE(513) = 2
    HIBYTE(258) = 1
    HIBYTE(-2) = 255
    HIBYTE(-257) = 254

See also:

    LOBYTE Function
    HIWORD Function
    CoerceTwoBytesToInteger Function
    MakeInteger Function
    CoerceToByte Function

Note: Use the CoerceTwoBytesToInteger function to reconstruct an Integer from two Byte values.
Note: Similar to but faster than using the MakeInteger and CoerceToByte functions.

HIDWORD Function
Windows API Class

Public Function HIDWORD( _
    ByVal vValue As Double _
    ) As Long

"High Double Word"
Return the high-order double-word (4 bytes) of a Double (precision floating-point) value.
Return the Long (Integer) value whose in-memory representation is the same as the left-most, most-significant double-word of Double value vValue.

Examples:

    HIDWORD(1) = 1072693248
    HIDWORD(2) = 1073741824

See also:

    LODWORD Function
    HIWORD Function
    CoerceTwoLongsToDouble Function
    MakeDouble Function
    CoerceToLong Function

Note: Use the CoerceTwoLongsToDouble function to reconstruct a Double from two Long values.
Note: Similar to but faster than using the MakeDouble and CoerceToLong functions.

HIWORD Function
Windows API Class

Public Function HIWORD( _
    ByVal vValue As Long _
    ) As Integer

"High Word"
Return the high-order word (2 bytes) of a Long (Integer) value.
Return the Integer value whose in-memory representation is the same as the left-most, most-significant-word of Long value vValue.

Examples:

    HIWORD(131073) = 2
    HIWORD(65538) = 1
    HIWORD(2147418112) = 32767
    HIWORD(-2147418112) = -32767

See also:

    LOWORD Function
    HIBYTE Function
    HIDWORD Function
    CoerceTwoIntegersToLong Function
    MakeLong Function
    CoerceToInteger Function

Note: Use the CoerceTwoIntegersToLong function to reconstruct a Long from two Integer values.
Note: Similar to but faster than using the MakeLong and CoerceToInteger functions.

LOBYTE Function
Windows API Class

Public Function LOBYTE( _
    ByVal vValue As Integer _
    ) As Byte

"Low Byte"
Return the low-order byte of an Integer value.
Return the Byte value whose in-memory representation is the same as the right-most, least-significant-byte of Integer value vValue.

Examples:

    LOBYTE(513) = 1
    LOBYTE(258) = 2
    LOBYTE(-2) = 254
    LOBYTE(-257) = 255

See also:

    HIBYTE Function
    LOWORD Function
    CoerceTwoBytesToInteger Function
    MakeInteger Function
    CoerceToByte Function

Note: Use the CoerceTwoBytesToInteger function to reconstruct an Integer from two Byte values.
Note: Similar to but faster than using the MakeInteger and CoerceToByte functions.

LODWORD Function
Windows API Class

Public Function LODWORD( _
    ByVal vValue As Double _
    ) As Long

"Low Double Word"
Return the low-order double-word (4 bytes) of a Double (precision floating-point) value.
Return the Long (Integer) value whose in-memory representation is the same as the right-most, least-significant double-word of Double value vValue.

Examples:

    LODWORD(1) = 0
    LODWORD(2) = 0

See also:

    HIDWORD Function
    LOWORD Function
    CoerceTwoLongsToDouble Function
    MakeDouble Function
    CoerceToLong Function

Note: Use the CoerceTwoLongsToDouble function to reconstruct a Double from two Long values.
Note: Similar to but faster than using the MakeDouble and CoerceToLong functions.

LOWORD Function
Windows API Class

Public Function LOWORD( _
    ByVal vValue As Long _
    ) As Integer

"Low Word"
Return the low-order word (2 bytes) of a Long (Integer) value.
Return the Integer value whose in-memory representation is the same as the right-most, least-significant-word of Long value vValue.

Examples:

    LOWORD(345) = 345
    LOWORD(65538) = 2
    LOWORD(131073) = 1

See also:

    HIWORD Function
    LOBYTE Function
    LODWORD Function
    CoerceTwoIntegersToLong Function
    MakeLong Function
    CoerceToInteger Function

Note: Use the CoerceTwoIntegersToLong function to reconstruct a Long from two Integer values.
Note: Similar to but faster than using the MakeLong and CoerceToInteger functions.

Oem To Char Function
Windows API Class

Public Function OemToChar( _
    ByVal vOEMString As Variant _
    ) As Variant

"OEM Characters To ANSI Characters"
Converts OEM (DOS) characters to the ANSI (Windows) character set.
Used to be known as OemToAnsi.

Example:

    OemToChar("Hawaii") = "Hawaii"

See also:

    CharToOem Function
    OemToChar (Windows API)

vOEMString: String that contains characters from the OEM DOS character set. Function returns Null if vOEMString is Null or cannot be fixed-up to a String.
Return value: The result string contains the corresponding characters from the Windows ANSI character set.
v1.3 Change: Removed 16-bit support from this function.

Shell No Wait Function
Windows API Class

Public Function ShellNoWait( _
      ByVal vCommand As String _
    , Optional ByVal vFocus As Variant _
    , Optional ByVal vSendKeys As Variant _
    ) As Long

Executes a Windows or DOS program without waiting for it to complete.
Its window gets the specified focus.
Function optionally sends keystrokes to the program.
Function returns either 0 (zero) upon success or the number of the error encountered.

Examples:

    ShellNoWait("CharMap.Exe", vbNormalNoFocus) = 0
    ShellNoWait("NotePad.Exe NewFile.Txt") = 0

See also:

    ShellWait Function
    vbNormalFocus Property, et. al.
    PrefixSendKeysMetaCharacters Function
    Shell Function (Visual Basic)
    SendKeys Statement (Visual Basic)

vCommand: The Windows or DOS command that is to be executed. This command line must include a program name, and it can optionally include one or more command line arguments.

vFocus: The focus given to program's window. Should be one of the Visual Basic focus Constants like vbNormalFocus, vbNormalNoFocus, etc. vFocus defaults to vbNormalFocus if it is missing or Null or cannot be fixed-up to a number.

vSendKeys: String that will be sent to the program as keystrokes after it is started. vSendKeys defaults to an empty string (no keystrokes will be sent) if it is missing or Null or cannot be fixed-up to a string.
Warning: vSendKeys is ignored if vFocus is vbHide, vbMinimizedNoFocus, or vbNormalNoFocus.

Shell Wait Function
Windows API Class

Public Function ShellWait( _
      ByVal vCommand As String _
    , Optional ByVal vFocus As Variant _
    , Optional ByVal vSendKeys As Variant _
    , Optional ByVal vAllowDoEvents As Variant _
    ) As Long

Executes a Windows or DOS program and wait for it to complete.
Its window gets the specified focus.
Function optionally sends keystrokes to the program.
Function returns either 0 (zero) upon success or the number of the error encountered.

Examples:

    ShellWait("CharMap.Exe", vbNormalNoFocus) = 0
    ShellWait("NotePad.Exe NewFile.Txt") = 0

See also:

    ShellNoWait Function
    vbNormalFocus Property, et. al.
    PrefixSendKeysMetaCharacters Function
    Shell Function (Visual Basic)
    SendKeys Statement (Visual Basic)
    DoEvents Statement (Visual Basic)

vCommand: The Windows or DOS command that is to be executed. This command line must include a program name, and it can optionally include one or more command line arguments.

vAllowDoEvents: True if the use of DoEvents is permitted within this function. False if DoEvents is not allowed. Read the warnings below carefully.
Warning: Uses DoEvents so that this function can detect the end of 16-bit Windows Programs within the 32-bit version of Entisoft Tools. This may possibly cause problems when this function is used within the 32-bit In-process version of Entisoft Tools, since there are restrictions on using DoEvents within In-process servers--see the Visual Basic documentation.
Note: When executing 16-bit Windows applications from the 32-bit version of Entisoft Tools, you must set vAllowDoEvents to True (its default) otherwise it cannot detect the end of the program. Unfortunately, the DoEvents statements are not recommended by Microsoft for use within in-process OLE Automation Servers (such as Entisoft Tools). See the Visual Basic 4.0 documentation and help file for more information.
v1.3 Change: Removed 16-bit support from this function.

Profile File Name Property
Windows API Class

Public Property Get ProfileFileName( _
    ) As String

Specifies the Private Profile (INI) file name that will be used by the Private Profile functions when their vFileName argument is missing or Null.
Get the current value of the ProfileFileName Property.

See also:

    ProfileSectionName Property

Public Property Let ProfileFileName( _
    ByVal vFileName As String _
    )

Set the current value of the ProfileFileName Property.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
    for example
       estWAPI.ProfileFileName = "ESUnits.Ini"
       estWAPI.ProfileSectionName = "Entisoft Units"
       estWAPI.WritePrivateProfileString("Convert From", "5 kilometers") = True

Warning: Be careful about using this Property if your program employs multi-tasking and the profile functions can possibly be called simultaneously from different parts of your program.

Profile Section Name Property
Windows API Class

Public Property Get ProfileSectionName( _
    ) As String

Specifies the Section Name that will be used by the Profile functions when their vSectionName argument is missing or Null.
Get the current value of the ProfileSectionName Property.

See also:

    ProfileFileName Property

Public Property Let ProfileSectionName( _
    ByVal vSectionName As String _
    )

Set the current value of the ProfileSectionName Property.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
    for example
       estWAPI.ProfileFileName = "Sample.Ini"
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WritePrivateProfileString("Convert From", "5 kilometers") = True

Warning: Be careful about using this Property if your program employs multi-tasking and the profile functions can possibly be called simultaneously from different parts of your program.

Get Private Profile Int Function
Windows API Class

Public Function GetPrivateProfileInt( _
      ByVal vKeyName As Variant _
    , Optional ByVal vDefault As Variant _
    , Optional ByVal vSectionName As Variant _
    , Optional ByVal vFileName As Variant _
    ) As Variant

"Get Private Profile Integer"
Get the value of an Integer numeric setting from a Windows Private Profile (INI) file.
Function returns a Long value.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileFileName = "Sample.Ini"
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WritePrivateProfileInt("Major Version", 5) = True
    for example
       estWAPI.GetPrivateProfileInt("Major Version") = 5

See also:

    GetPrivateProfileString Function
    GetPrivateProfileSection Function
    WritePrivateProfileString Function
    GetProfileInt Function
    ProfileFileName Property
    ProfileSectionName Property
    GetPrivateProfileInt Function (Windows API)
    GetSetting Function (Visual Basic 4.0+; not directly related)

vKeyName: Name of the numeric setting whose value is to be retrieved. Function returns Null if vKeyName is Null or cannot be fixed-up to a String.
vDefault: Default value that will be returned by this function where there is no setting with the specified Name. vDefault defaults to 0 (zero) if it is missing or Null or cannot be fixed-up to a number.
vSectionName: The Section within the Private Profile file that contains the Setting. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
vFileName: The name of the Private Profile (INI) File that contains the Setting. vFileName defaults to the current value of the ProfileFileName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Get Private Profile Section Function
Windows API Class

Public Function GetPrivateProfileSection( _
      ByRef rSection() As Variant _
    , Optional ByVal vSectionName As Variant _
    , Optional ByVal vFileName As Variant _
    ) As Boolean

Get all of the settings from a section of a Private Profile file and place them into a Variant array.
Function returns True upon success and False upon failure.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileFileName = "Sample.Ini"
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WritePrivateProfileString("Convert From", "5 kilometers") = True
       estWAPI.WritePrivateProfileString("Convert To", "miles") = True
       Dim avarSettings() As Variant
    for example
       estWAPI.GetPrivateProfileSection(avarSettings()) = True
    leaves
       LBound(avarSettings) = 0
       UBound(avarSettings) = 2
       ? avarSettings(1)
       Convert From="5 kilometers"
       ? avarSettings(2)
       Convert To="miles"

See also:

    ProfileSectionToVariantVector Function
    GetPrivateProfileSectionSample Subroutine
    GetPrivateProfileInt Function
    GetPrivateProfileString Function
    GetProfileSection Function
    ProfileFileName Property
    ProfileSectionName Property
    GetPrivateProfileSection Function (Windows API)
    GetAllSettings Function (Visual Basic 4.0+; not directly related)

rSection: Dynamic array of Variants that will receive the Settings. This array will be reinitialized with a lower-bound of 0 (zero) and an upper-bound of the number of Settings read. The settings will be copied into elements 1..N of the array.
vSectionName: The Section Name whose settings will be copied into the array. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
vFileName: The name of the Private Profile (INI) File that contains the Section to be read. vFileName defaults to the current value of the ProfileFileName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Get Private Profile Section Sample Sub
Windows API Class

Private Sub GetPrivateProfileSectionSample()
    ' Print a sample of the GetPrivateProfileSection function.

    Dim avarSection() As Variant
    If GetPrivateProfileSection(avarSection, "windows", "WIN.INI") Then
        Debug.Print IllustrateVariantVector(avarSection)
    Else
        Debug.Print "Function failed."
    End If
End Sub

Get Private Profile String Function
Windows API Class

Public Function GetPrivateProfileString( _
      ByVal vKeyName As Variant _
    , Optional ByVal vDefault As Variant _
    , Optional ByVal vSectionName As Variant _
    , Optional ByVal vFileName As Variant _
    ) As Variant

Get the value of a String setting from a Windows Private Profile (INI) file.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileFileName = "Sample.Ini"
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WritePrivateProfileString("Convert From", "5 kilometers") = True
    for example
       estWAPI.GetPrivateProfileString("Convert From") = "5 kilometers"

See also:

    WritePrivateProfileString Function
    GetPrivateProfileInt Function
    GetPrivateProfileSection Function
    GetProfileString Function
    ProfileFileName Property
    ProfileSectionName Property
    GetPrivateProfileString Function (Windows API)
    GetSetting Function (Visual Basic 4.0+; not directly related)

vKeyName: Name of the String setting whose value is to be retrieved. Function returns Null if vKeyName is Null or cannot be fixed-up to a String.
vDefault: Default value that will be returned by this function where there is no setting with the specified Name. vDefault defaults to an empty string ("") if it is missing or Null or cannot be fixed-up to a String.
vSectionName: The Section within the Private Profile file that contains the Setting. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
vFileName: The name of the Private Profile (INI) File that contains the Setting. vFileName defaults to the current value of the ProfileFileName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Get Profile Int Function
Windows API Class

Public Function GetProfileInt( _
      ByVal vKeyName As Variant _
    , Optional ByVal vDefault As Variant _
    , Optional ByVal vSectionName As Variant _
    ) As Variant

"Get Profile Integer"
Get the value of an (Integer) numeric setting from the Windows Registry.
Function returns a Long value.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WriteProfileInt("Major Version", 5) = True
    for example
       estWAPI.GetProfileInt("Major Version") = 5

See also:

    GetProfileString Function
    GetProfileSection Function
    WriteProfileString Function
    GetPrivateProfileInt Function
    ProfileSectionName Property
    GetProfileInt Function (Windows API)

vKeyName: Name of the numeric setting whose value is to be retrieved. Function returns Null if vKeyName is Null or cannot be fixed-up to a String.
vDefault: Default value that will be returned by this function where there is no setting with the specified Name. vDefault defaults to 0 (zero) if it is missing or Null or cannot be fixed-up to a number.
vSectionName: The Section within the Profile file or Windows Registry that contains the Setting. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Get Profile Section Function
Windows API Class

Public Function GetProfileSection( _
      ByRef rSection() As Variant _
    , Optional ByVal vSectionName As Variant _
    ) As Boolean

Get all of the settings from a section of the Windows Registry.
Function returns True upon success and False upon failure.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WriteProfileString("Convert From", "5 kilometers") = True
       estWAPI.WriteProfileString("Convert To", "miles") = True
       Dim avarSettings() As Variant
    for example
       estWAPI.GetProfileSection(avarSettings()) = True
    leaves
       LBound(avarSettings) = 0
       UBound(avarSettings) = 2
       ? avarSettings(1)
       Convert From="5 kilometers"
       ? avarSettings(2)
       Convert To="miles"

See also:

    ProfileSectionToVariantVector Function
    GetProfileSectionSample Subroutine
    GetProfileInt Function
    GetProfileString Function
    GetPrivateProfileSection Function
    ProfileSectionName Property
    GetProfileSection Function (Windows API)

rSection: Dynamic array of Variants that will receive the Settings. This array will be reinitialized with a lower-bound of 0 (zero) and an upper-bound of the number of Settings read. The settings will be copied into elements 1..N of the array.
vSectionName: The Section within the Profile file or Windows Registry whose settings will be copied into the array. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Get Profile Section Sample Sub
Windows API Class

Private Sub GetProfileSectionSample()
    ' Print a sample of the GetProfileSectionSample function.

    Dim avarSection() As Variant
    If GetProfileSection(avarSection, "windows") Then
        Debug.Print IllustrateVariantVector(avarSection)
    Else
        Debug.Print "Function failed."
    End If
End Sub

Get Profile String Function
Windows API Class

Public Function GetProfileString( _
      ByVal vKeyName As Variant _
    , Optional ByVal vDefault As Variant _
    , Optional ByVal vSectionName As Variant _
    ) As Variant

Get the value of a String setting from the Windows Registry.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileSectionName = "Sample Section"
       estWAPI.WriteProfileString("Convert From", "5 kilometers") = True
    for example
       estWAPI.GetProfileString("Convert From") = "5 kilometers"

See also:

    WriteProfileString Function
    GetProfileInt Function
    GetProfileSection Function
    GetPrivateProfileString Function
    ProfileSectionName Property
    GetProfileString Function (Windows API)

vKeyName: Name of the String setting whose value is to be retrieved. Function returns Null if vKeyName is Null or cannot be fixed-up to a String.
vDefault: Default value that will be returned by this function where there is no setting with the specified Name. vDefault defaults to an empty string ("") if it is missing or Null or cannot be fixed-up to a String.
vSectionName: The Section within the Profile file or Windows Registry that contains the Setting. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Write Private Profile String Function
Windows API Class

Public Function WritePrivateProfileString( _
      Optional ByVal vKeyName As Variant _
    , Optional ByVal vValue As Variant _
    , Optional ByVal vSectionName As Variant _
    , Optional ByVal vFileName As Variant _
    ) As Boolean

Writes a Key Name and Value pair into a Windows Private Profile (INI) file.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileFileName = "Sample.Ini"
       estWAPI.ProfileSectionName = "Sample Section"
    for example
       estWAPI.WritePrivateProfileString("Convert From", "5 kilometers") = True

See also:

    GetPrivateProfileString Function
    GetPrivateProfileInt Function
    WriteProfileString Function
    ProfileFileName Property
    ProfileSectionName Property
    WritePrivateProfileString Function (Windows API)
    SaveSetting Function (Visual Basic 4.0+; not directly related)
    DeleteSetting Function (Visual Basic 4.0+; not directly related)

vKeyName: Name of the String setting whose value is to be written. Function returns Null if vKeyName is Null or cannot be fixed-up to a String.
vValue: The string Value that will be associated with the Name vKeyName. If vValue is Null, the Setting (Name and Value pair) with Name vKeyName will be removed. vValue defaults to Null if it is missing or Null or cannot be fixed-up to a string.
vSectionName: The Section Name into which the Setting will be written. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
vFileName: The name of the Private Profile (INI) File into which the Setting will be written. vFileName defaults to the current value of the ProfileFileName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.

Write Profile String Function
Windows API Class

Public Function WriteProfileString( _
      Optional ByVal vKeyName As Variant _
    , Optional ByVal vValue As Variant _
    , Optional ByVal vSectionName As Variant _
    ) As Boolean

Write a Key Name and Value pair into the Windows Registry.

Example:

    Assuming
       Dim estWAPI As New EntisoftTools1_3.WindowsAPI
       estWAPI.ProfileSectionName = "Sample Section"
    for example
       estWAPI.WriteProfileString("Convert From", "5 kilometers") = True

See also:

    GetProfileString Function
    GetProfileInt Function
    WritePrivateProfileString Function
    ProfileSectionName Property
    WriteProfileString Function (Windows API)

vKeyName: Name of the String setting whose value is to be written. Function returns Null if vKeyName is Null or cannot be fixed-up to a String.
vValue: The string Value that will be associated with the Name vKeyName. If vValue is Null, the Setting (Name and Value pair) with Name vKeyName will be removed. vValue defaults to Null if it is missing or Null or cannot be fixed-up to a string.
vSectionName: The Section within the Profile file or Windows Registry into which the Setting will be written. vSectionName defaults to the current value of the ProfileSectionName Property if it is missing or Null or cannot be fixed-up to a String.
v1.3 Change: Removed 16-bit support from this function.