Version Introduced: ODBC 3.0
SQLReadFileDSN reads information from a File DSN.
[Input] Pointer to the data buffer containing the name of the .dsn file. A .dsn extension is appended to all file names that do not already have a .dsn extension. The value in *lpszFileName must be a null-terminated string.
[Input] Pointer to the data buffer containing the name of the application. This is "ODBC" for the ODBC section. The value in *lpszAppName must be a null-terminated string.
[Input] Pointer to the data buffer containing the name of the key to be read. See "Comments" for reserved keywords. The value in *lpszAppName must be a null-terminated string.
[Output] Pointer to the data buffer containing the string associated with the key to be read.
If *lpszFileName is a valid .dsn file name but the lpszAppName argument is a null pointer and the lpszKeyName argument is a null pointer, then *lpszString contains a list of valid applications. If *lpszFileName is a valid .dsn file name and *lpszAppName is a valid application name, but the lpszKeyName argument is a null pointer, then *lpszString contains a list of valid reserved keywords in the appropriate section of the DSN file, delimited by semicolons. If *lpszFileName is a valid .dsn file name but *lpszAppName is a null pointer and the lpszKeyName argument is a null pointer, then *lpszString contains a list of the sections in the DSN file, delimited by semicolons.
[Input] Length of the *lpszString buffer.
[Output] Total number of bytes available to return in *lpszString. If the number of bytes available to return is greater than or equal to cbString, the output string in *lpszString is truncated to cbString minus the null-termination character. The pcbString argument can be a null pointer.
The function returns TRUE if it is successful, FALSE if it fails.
When SQLReadFileDSN returns FALSE, an associated *pfErrorCode value can be obtained by calling SQLInstallerError. The following table lists the *pfErrorCode values that can be returned by SQLInstallerError and explains each one in the context of this function.
General installer error
An error occurred for which there was no specific installer error.
Invalid buffer length
The lpszString argument was NULL.
The cbString argument was less than or equal to 0.
Invalid install path
The path of the file name specified in the lpszFileName argument was invalid.
Invalid type of request
The lpszAppName argument was NULL, while the lpszKeyName argument was valid.
Out of memory
The installer could not perform the function because of a lack of memory.
Output string truncated
The string returned in *lpszString was truncated because the value in cbString was less than or equal to the value in *pcbString.
The keyword did not exist in the file DSN.
ODBC reserves the section name [ODBC] in which to store the connection information. The reserved keywords for this section are the same as those reserved for a connect string in SQLDriverConnect. (For more information, see the SQLDriverConnect function description.)
Applications can use these reserved keywords to read the information in a File DSN. If an applications wants to find out the DSN-less connection string associated with a File DSN, it can call SQLReadFileDSN for any of the reserved connection string keywords in the [ODBC] section. The full connection string passed in a DSN-less connection is a combination of all of the keywords (reserved and driver-specific) in the [ODBC] section.