---
product: Chilkat
product_version: 11.7.0
language: sqlserver
language_label: SQL Server
class: Charset
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/sqlserver_CharsetRef.html
---
# Chilkat Charset — SQL Server — v11.7.0

> Chilkat 11.7.0 · language=sqlserver · class=Charset
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Charset.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/sqlserver/guide.md`.

## Purpose

Deprecated — scheduled for removal

**Legacy character-set conversion utilities. Migrate before Chilkat v12.0.0.**

**Do not use `Chilkat.Charset` in new development.** The entire class is deprecated and is scheduled to be removed in Chilkat v12.0.0. Existing applications should migrate now. Equivalent functionality is available in the free `Chilkat.BinData` and `Chilkat.StringBuilder` classes.

`Chilkat.Charset` is a legacy class for converting text between character encodings, reading and writing encoded text files, inspecting or rewriting HTML charset declarations, encoding and decoding HTML entities, validating byte sequences, and performing several older text utilities. It remains documented only to support maintenance and migration of existing applications.

**Use BinData for bytes**

Store raw bytes, load and save files, append byte-order marks, and move encoded data between files, memory, and other Chilkat objects.

**Use StringBuilder for text**

Hold Unicode text and perform charset encoding or decoding, URL processing, HTML entity conversion, case conversion, and related text operations.

**Prefer UTF-8**

For new text formats and interchange, use UTF-8 unless a protocol or legacy system explicitly requires another encoding.

**Keep bytes and characters distinct**

A charset defines how text characters map to bytes. Binary encodings such as Base64 or hexadecimal solve a different problem and are not character sets.

**Legacy HTML helpers**

The class can inspect and rewrite HTML charset metadata, but these helpers do not validate that declared metadata matches the actual bytes.

**Maintenance only**

Continue using this class only while maintaining older code, and plan a tested migration before adopting Chilkat v12.

**Migration pattern:** load encoded bytes into `BinData`, decode them into a `StringBuilder` using the known source charset, work with Unicode text, then encode back into `BinData` using the required destination charset. This makes the boundary between bytes and text explicit and replaces the stateful `FromCharset`/`ToCharset` workflow.

## Object creation, unlocking and error handling

**Object Creation**

```sql
DECLARE @hr int
DECLARE @charset int
EXEC @hr = sp_OACreate 'Chilkat.Charset', @charset OUT
IF @hr <> 0
BEGIN
    PRINT 'Failed to create ActiveX component'
    RETURN
END

-- ... use @charset ...

EXEC @hr = sp_OADestroy @charset
```

T-SQL uses the Chilkat ActiveX through the OLE Automation stored procedures. They must be enabled once on the server (`EXEC sp_configure 'Ole Automation Procedures', 1; RECONFIGURE;`), and the Chilkat ActiveX registered must match the bitness of the SQL Server instance (64-bit for a 64-bit SQL Server). To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as `sp_OACreate 'Chilkat.Charset.11'` for Chilkat v11.\*.\*.

`sp_OACreate` returns an object token (an `int`) that is passed as the first argument of every `sp_OAMethod`, `sp_OAGetProperty` and `sp_OASetProperty` call, and released with `sp_OADestroy`. Objects returned by methods (such as an `HttpResponse` or `JsonObject`) are also tokens received through an `int` OUT parameter; they must likewise be destroyed, and the OUT parameter is `NULL` when the method fails to return an object. Objects passed as arguments are passed by their token. When an OLE Automation procedure itself fails (non-zero `@hr`), `sp_OAGetErrorInfo` describes the error.

Data types: strings are `nvarchar(4000)`; integers, booleans (1 or 0) and object tokens are `int`; dates are `datetime`. In the signatures on this page, `@success`, `@iResult`, `@sResult` and the like are the OUT variables receiving a method's return value, `@iValue` / `@sValue` receive or supply a property value, and the remaining `@` variables are the method's arguments in order.

A string returned through an OUT parameter is limited to 4000 characters. For longer values, retrieve the result as a result set into a table variable instead of an OUT parameter, for example `DECLARE @tmp TABLE (outputLine ntext)` followed by `INSERT INTO @tmp EXEC sp_OAGetProperty @charset, 'LastErrorText'`. See [string length limitations for strings returned by sp_OAMethod calls](https://www.chilkatsoft.com/sql_server_nvarchar_max_limitation.asp).

Methods that pass or return raw byte arrays are not shown on this page, because `varbinary(max)` values cannot be exchanged through `sp_OAMethod` (see [varbinary(max) limitation](https://www.chilkatsoft.com/sql_server_varbinary_max_limitation.asp)). Use the `BinData`-based alternatives (methods ending in *Bd*) or the base64 / hex string-encoded variants instead. Binary *properties* (such as `LastBinaryResult`) can be retrieved as a result set into a table variable, as shown in their signatures. Asynchronous (*\*Async*) methods and event callbacks are not available from SQL Server.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in SQL Server.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `EXEC sp_OAGetProperty @charset, 'DebugLogFilePath', @sValue OUT EXEC sp_OASetProperty @charset, 'DebugLogFilePath', @sValue` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastBinaryResult` | `INSERT INTO @tmp EXEC sp_OAGetProperty @charset, 'LastBinaryResult'` | read-only | This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. |
| `LastErrorHtml` | `EXEC sp_OAGetProperty @charset, 'LastErrorHtml', @sValue OUT` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `EXEC sp_OAGetProperty @charset, 'LastErrorText', @sValue OUT` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `EXEC sp_OAGetProperty @charset, 'LastErrorXml', @sValue OUT` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `EXEC sp_OAGetProperty @charset, 'LastMethodSuccess', @iValue OUT EXEC sp_OASetProperty @charset, 'LastMethodSuccess', @iValue` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `EXEC sp_OAGetProperty @charset, 'LastStringResult', @sValue OUT` | read-only | In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. |
| `LastStringResultLen` | `EXEC sp_OAGetProperty @charset, 'LastStringResultLen', @iValue OUT` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `EXEC sp_OAGetProperty @charset, 'VerboseLogging', @iValue OUT EXEC sp_OASetProperty @charset, 'VerboseLogging', @iValue` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `EXEC sp_OAGetProperty @charset, 'Version', @sValue OUT` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `AltToCharset` | property, read/write | `EXEC sp_OAGetProperty @charset, 'AltToCharset', @sValue OUT EXEC sp_OASetProperty @charset, 'AltToCharset', @sValue` |
| `ErrorAction` | property, read/write | `EXEC sp_OAGetProperty @charset, 'ErrorAction', @iValue OUT EXEC sp_OASetProperty @charset, 'ErrorAction', @iValue` |
| `FromCharset` | property, read/write | `EXEC sp_OAGetProperty @charset, 'FromCharset', @sValue OUT EXEC sp_OASetProperty @charset, 'FromCharset', @sValue` |
| `LastInputAsHex` | property, read-only | `EXEC sp_OAGetProperty @charset, 'LastInputAsHex', @sValue OUT` |
| `LastInputAsQP` | property, read-only | `EXEC sp_OAGetProperty @charset, 'LastInputAsQP', @sValue OUT` |
| `LastOutputAsHex` | property, read-only | `EXEC sp_OAGetProperty @charset, 'LastOutputAsHex', @sValue OUT` |
| `LastOutputAsQP` | property, read-only | `EXEC sp_OAGetProperty @charset, 'LastOutputAsQP', @sValue OUT` |
| `SaveLast` | property, read/write | `EXEC sp_OAGetProperty @charset, 'SaveLast', @iValue OUT EXEC sp_OASetProperty @charset, 'SaveLast', @iValue` |
| `ToCharset` | property, read/write | `EXEC sp_OAGetProperty @charset, 'ToCharset', @sValue OUT EXEC sp_OASetProperty @charset, 'ToCharset', @sValue` |
| `CharsetToCodePage` | method | `EXEC sp_OAMethod @charset, 'CharsetToCodePage', @iResult OUT, @charsetName` |
| `CodePageToCharset` | method | `EXEC sp_OAMethod @charset, 'CodePageToCharset', @sResult OUT, @codePage` |
| `ConvertFile` | method | `EXEC sp_OAMethod @charset, 'ConvertFile', @success OUT, @inPath, @destPath` |
| `ConvertFileNoPreamble` | method | `EXEC sp_OAMethod @charset, 'ConvertFileNoPreamble', @success OUT, @inPath, @destPath` |
| `ConvertHtmlFile` | method | `EXEC sp_OAMethod @charset, 'ConvertHtmlFile', @success OUT, @inPath, @destPath` |
| `EntityEncodeDec` | method | `EXEC sp_OAMethod @charset, 'EntityEncodeDec', @sResult OUT, @str` |
| `EntityEncodeHex` | method | `EXEC sp_OAMethod @charset, 'EntityEncodeHex', @sResult OUT, @str` |
| `GetHtmlFileCharset` | method | `EXEC sp_OAMethod @charset, 'GetHtmlFileCharset', @sResult OUT, @htmlFilePath` |
| `HtmlDecodeToStr` | method | `EXEC sp_OAMethod @charset, 'HtmlDecodeToStr', @sResult OUT, @inStr` |
| `HtmlEntityDecodeFile` | method | `EXEC sp_OAMethod @charset, 'HtmlEntityDecodeFile', @success OUT, @inPath, @destPath` |
| `LowerCase` | method | `EXEC sp_OAMethod @charset, 'LowerCase', @sResult OUT, @inStr` |
| `ReadFileToString` | method | `EXEC sp_OAMethod @charset, 'ReadFileToString', @sResult OUT, @path, @charset` |
| `SetErrorString` | method | `EXEC sp_OAMethod @charset, 'SetErrorString', NULL, @str, @charset` |
| `UpperCase` | method | `EXEC sp_OAMethod @charset, 'UpperCase', @sResult OUT, @inStr` |
| `UrlDecodeStr` | method | `EXEC sp_OAMethod @charset, 'UrlDecodeStr', @sResult OUT, @inStr` |
| `VerifyFile` | method | `EXEC sp_OAMethod @charset, 'VerifyFile', @success OUT, @charset, @path` |
| `WriteStringToFile` | method | `EXEC sp_OAMethod @charset, 'WriteStringToFile', @success OUT, @textData, @path, @charset` |

## Properties

### Charset.AltToCharset

`Chilkat 11.7.0 · sqlserver · Charset · AltToCharset · property · read/write`

```sql
EXEC sp_OAGetProperty @charset, 'AltToCharset', @sValue OUT
EXEC sp_OASetProperty @charset, 'AltToCharset', @sValue
```

Specifies the alternate destination character encoding used only when `ErrorAction` is `6`.

If a decoded input character cannot be represented in `ToCharset`, Chilkat attempts to encode that character using this alternate charset. If the alternate conversion also fails, the character is omitted from the output.

**Mixed-encoding output:** The result can contain a mixture of byte encodings. Such output is usually unsuitable for interchange unless the receiving format explicitly supports this behavior.

### Charset.ErrorAction

`Chilkat 11.7.0 · sqlserver · Charset · ErrorAction · property · read/write`

```sql
EXEC sp_OAGetProperty @charset, 'ErrorAction', @iValue OUT
EXEC sp_OASetProperty @charset, 'ErrorAction', @iValue
```

Controls what happens when an input character has been decoded successfully but cannot be represented in the destination charset.

| Value | Action |
| :--- | :--- |
| `0` | Drop the unrepresentable character. |
| `1` | Insert the replacement configured by `SetErrorString`. |
| `2` | Emit a hexadecimal numeric character reference such as `&#x20AC;`. |
| `3`–`5` | Reserved. Do not use. |
| `6` | Encode the character using `AltToCharset`; drop it if that also fails. |
| `7` | Pass the nonconvertible data through unchanged. |

**Data-integrity warning:** Values `0`, `6`, and `7` can silently lose data or produce output that is not valid in the declared destination charset. For new code, prefer an explicit failure or replacement policy in the replacement API.

### Charset.FromCharset

`Chilkat 11.7.0 · sqlserver · Charset · FromCharset · property · read/write`

```sql
EXEC sp_OAGetProperty @charset, 'FromCharset', @sValue OUT
EXEC sp_OASetProperty @charset, 'FromCharset', @sValue
```

Specifies the character encoding of the input bytes for conversion operations. Chilkat decodes the source bytes using this charset before encoding the resulting Unicode text using `ToCharset`.

| Family | Recognized names |
| :--- | :--- |
| Unicode and ASCII | `us-ascii`, `utf-7`, `utf-8`, `unicode` / `utf-16` / `utf-16le`, `unicodefffe` / `utf-16be`, `utf-32`, `utf-32be` |
| ISO and Windows | `iso-8859-1`, `-2`, `-3`, `-4`, `-5`, `-6`, `-7`, `-8`, `-9`, `-13`, `-15`; `windows-874`, `windows-1250` through `windows-1258` |
| East Asian | `shift_jis`, `gb2312`, `ks_c_5601-1987`, `big5`, `iso-2022-jp`, `iso-2022-kr`, `euc-jp`, `euc-kr` |
| Macintosh | `macintosh`, `x-mac-japanese`, `x-mac-chinesetrad`, `x-mac-korean`, `x-mac-arabic`, `x-mac-hebrew`, `x-mac-greek`, `x-mac-cyrillic`, `x-mac-chinesesimp`, `x-mac-romanian`, `x-mac-ukrainian`, `x-mac-thai`, `x-mac-ce`, `x-mac-icelandic`, `x-mac-turkish`, `x-mac-croatian` |
| DOS, IBM, and legacy | `ebcdic`, `asmo-708`, `dos-720`, `dos-862`, `ibm01140` through `ibm01149`, `ibm037`, `ibm437`, `ibm500`, `ibm737`, `ibm775`, `ibm850`, `ibm852`, `ibm855`, `ibm857`, `ibm00858`, `ibm860`, `ibm861`, `ibm863`, `ibm864`, `ibm865`, `cp866`, `ibm869`, `ibm870`, `cp875`, `koi8-r`, `koi8-u` |

**Source encoding:** `unicode`, `utf-16`, and `utf-16le` identify little-endian UTF-16. `unicodefffe` and `utf-16be` identify big-endian UTF-16. Except where a method explicitly documents HTML metadata detection, set the source charset explicitly rather than assuming automatic detection.

### Charset.LastInputAsHex

`Chilkat 11.7.0 · sqlserver · Charset · LastInputAsHex · property · read-only`

```sql
EXEC sp_OAGetProperty @charset, 'LastInputAsHex', @sValue OUT
```

Returns the input bytes captured for the most recent conversion performed while `SaveLast` was enabled, represented as hexadecimal text.

**Diagnostic snapshot:** This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

### Charset.LastInputAsQP

`Chilkat 11.7.0 · sqlserver · Charset · LastInputAsQP · property · read-only`

```sql
EXEC sp_OAGetProperty @charset, 'LastInputAsQP', @sValue OUT
```

Returns the input bytes captured for the most recent conversion performed while `SaveLast` was enabled, represented as quoted-printable text.

**Diagnostic snapshot:** This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

### Charset.LastOutputAsHex

`Chilkat 11.7.0 · sqlserver · Charset · LastOutputAsHex · property · read-only`

```sql
EXEC sp_OAGetProperty @charset, 'LastOutputAsHex', @sValue OUT
```

Returns the output bytes captured for the most recent conversion performed while `SaveLast` was enabled, represented as hexadecimal text.

**Diagnostic snapshot:** This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

### Charset.LastOutputAsQP

`Chilkat 11.7.0 · sqlserver · Charset · LastOutputAsQP · property · read-only`

```sql
EXEC sp_OAGetProperty @charset, 'LastOutputAsQP', @sValue OUT
```

Returns the output bytes captured for the most recent conversion performed while `SaveLast` was enabled, represented as quoted-printable text.

**Diagnostic snapshot:** This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

### Charset.SaveLast

`Chilkat 11.7.0 · sqlserver · Charset · SaveLast · property · read/write`

```sql
EXEC sp_OAGetProperty @charset, 'SaveLast', @iValue OUT
EXEC sp_OASetProperty @charset, 'SaveLast', @iValue
```

When `1`, retains the input and output byte sequences from each conversion so they can be inspected through `LastInputAsHex`, `LastInputAsQP`, `LastOutputAsHex`, and `LastOutputAsQP`.

**Debugging only:** Enable this only while troubleshooting. Retaining both sides of a large conversion increases memory use and may keep sensitive plaintext in memory longer than necessary.

### Charset.ToCharset

`Chilkat 11.7.0 · sqlserver · Charset · ToCharset · property · read/write`

```sql
EXEC sp_OAGetProperty @charset, 'ToCharset', @sValue OUT
EXEC sp_OASetProperty @charset, 'ToCharset', @sValue
```

Specifies the destination character encoding for conversion operations. After decoding the source bytes using `FromCharset`, Chilkat encodes the resulting Unicode text in this charset.

| Family | Recognized names |
| :--- | :--- |
| Unicode and ASCII | `us-ascii`, `utf-7`, `utf-8`, `unicode` / `utf-16` / `utf-16le`, `unicodefffe` / `utf-16be`, `utf-32`, `utf-32be` |
| ISO and Windows | `iso-8859-1`, `-2`, `-3`, `-4`, `-5`, `-6`, `-7`, `-8`, `-9`, `-13`, `-15`; `windows-874`, `windows-1250` through `windows-1258` |
| East Asian | `shift_jis`, `gb2312`, `ks_c_5601-1987`, `big5`, `iso-2022-jp`, `iso-2022-kr`, `euc-jp`, `euc-kr` |
| Macintosh | `macintosh`, `x-mac-japanese`, `x-mac-chinesetrad`, `x-mac-korean`, `x-mac-arabic`, `x-mac-hebrew`, `x-mac-greek`, `x-mac-cyrillic`, `x-mac-chinesesimp`, `x-mac-romanian`, `x-mac-ukrainian`, `x-mac-thai`, `x-mac-ce`, `x-mac-icelandic`, `x-mac-turkish`, `x-mac-croatian` |
| DOS, IBM, and legacy | `ebcdic`, `asmo-708`, `dos-720`, `dos-862`, `ibm01140` through `ibm01149`, `ibm037`, `ibm437`, `ibm500`, `ibm737`, `ibm775`, `ibm850`, `ibm852`, `ibm855`, `ibm857`, `ibm00858`, `ibm860`, `ibm861`, `ibm863`, `ibm864`, `ibm865`, `cp866`, `ibm869`, `ibm870`, `cp875`, `koi8-r`, `koi8-u` |

**Choosing an output encoding:** For new text interchange, `utf-8` is normally the preferred destination. Legacy single-byte encodings cannot represent every Unicode character; `ErrorAction` controls how such conversion failures are handled.

## Methods

### Charset.CharsetToCodePage

`Chilkat 11.7.0 · sqlserver · Charset · CharsetToCodePage · method`

```sql
EXEC sp_OAMethod @charset, 'CharsetToCodePage', @iResult OUT, @charsetName
```

Returns the numeric Windows code-page identifier corresponding to `charsetName`. For example, `iso-8859-1` maps to `28591`, and `utf-8` maps to `65001`.

**Code pages:** A code page number is a legacy Windows identifier for a character encoding. Internet protocols and modern APIs normally use charset names such as `utf-8` rather than numeric code pages.

### Charset.CodePageToCharset

`Chilkat 11.7.0 · sqlserver · Charset · CodePageToCharset · method`

```sql
EXEC sp_OAMethod @charset, 'CodePageToCharset', @sResult OUT, @codePage
```

Returns the charset name corresponding to the numeric code-page identifier in `codePage`. For example, `65001` maps to `utf-8`. The operation fails when the code page is not recognized.

**Name normalization:** Different aliases can identify the same encoding. The returned value is Chilkat’s canonical name for the recognized code page, not necessarily the alias originally used by another application.

Returns `NULL` on failure

### Charset.ConvertFile

`Chilkat 11.7.0 · sqlserver · Charset · ConvertFile · method`

```sql
EXEC sp_OAMethod @charset, 'ConvertFile', @success OUT, @inPath, @destPath
```

Reads the file at `inPath`, converts its text from `FromCharset` to `ToCharset`, and writes the converted bytes to the file at `destPath`.

When the destination charset is `utf-8` or `utf-16`, this method writes the corresponding byte-order mark (BOM) at the beginning of the output. Use `ConvertFileNoPreamble` when the output must not contain a BOM.

**BOM behavior:** A BOM is a leading byte sequence that can identify a Unicode encoding or byte order. UTF-8 does not require a BOM, and many modern formats prefer UTF-8 without one.

Returns 1 for success, 0 for failure.

### Charset.ConvertFileNoPreamble

`Chilkat 11.7.0 · sqlserver · Charset · ConvertFileNoPreamble · method`

```sql
EXEC sp_OAMethod @charset, 'ConvertFileNoPreamble', @success OUT, @inPath, @destPath
```

Reads the file at `inPath`, converts its text from `FromCharset` to `ToCharset`, and writes the converted bytes to `destPath` without adding a byte-order mark or other encoding preamble.

**UTF-8 output:** This is generally the appropriate choice for UTF-8 files unless the consuming system specifically requires a UTF-8 BOM.

Returns 1 for success, 0 for failure.

### Charset.ConvertHtmlFile

`Chilkat 11.7.0 · sqlserver · Charset · ConvertHtmlFile · method`

```sql
EXEC sp_OAMethod @charset, 'ConvertHtmlFile', @success OUT, @inPath, @destPath
```

Converts the HTML file at `inPath` to `ToCharset` and writes the result to `destPath`. Chilkat also updates the HTML `<meta>` charset declaration to identify the destination encoding.

If `FromCharset` is empty, Chilkat attempts to obtain the source charset from an HTML `<meta>` declaration. Otherwise, the explicitly configured source charset is used.

**Detection limitation:** A declared charset is metadata, not proof of the file’s actual encoding. Incorrect or missing declarations can cause decoding errors; use an explicit source charset when it is known.

Returns 1 for success, 0 for failure.

### Charset.EntityEncodeDec

`Chilkat 11.7.0 · sqlserver · Charset · EntityEncodeDec · method`

```sql
EXEC sp_OAMethod @charset, 'EntityEncodeDec', @sResult OUT, @str
```

Returns `str` with each non-US-ASCII character replaced by a decimal HTML/XML numeric character reference. For example, `é` becomes `&#233;`.

**Entity encoding:** Numeric character references describe Unicode characters; they are not a character-set conversion and do not make arbitrary binary data safe for HTML.

Returns `NULL` on failure

### Charset.EntityEncodeHex

`Chilkat 11.7.0 · sqlserver · Charset · EntityEncodeHex · method`

```sql
EXEC sp_OAMethod @charset, 'EntityEncodeHex', @sResult OUT, @str
```

Returns `str` with each non-US-ASCII character replaced by a hexadecimal HTML/XML numeric character reference. For example, `é` becomes `&#xE9;`.

**Entity encoding:** Decimal and hexadecimal numeric references represent the same Unicode character; only the textual notation differs.

Returns `NULL` on failure

### Charset.GetHtmlFileCharset

`Chilkat 11.7.0 · sqlserver · Charset · GetHtmlFileCharset · method`

```sql
EXEC sp_OAMethod @charset, 'GetHtmlFileCharset', @sResult OUT, @htmlFilePath
```

Examines the HTML file at `htmlFilePath` and returns the charset name declared by an HTML `<meta>` element, when present.

**Metadata only:** The method reads document metadata only. A missing, stale, or incorrect declaration does not reveal the file’s true encoding.

Returns `NULL` on failure

### Charset.HtmlDecodeToStr

`Chilkat 11.7.0 · sqlserver · Charset · HtmlDecodeToStr · method`

```sql
EXEC sp_OAMethod @charset, 'HtmlDecodeToStr', @sResult OUT, @inStr
```

Decodes HTML named entities and numeric character references in `inStr` and returns the resulting Unicode string. Examples include `&lt;`, `&amp;`, `&#233;`, and `&#xE9;`.

**Security context:** Entity decoding is a text transformation, not HTML parsing or sanitization. Decoding untrusted text can reintroduce markup-significant characters such as `<`, `>`, and `&`.

Returns `NULL` on failure

### Charset.HtmlEntityDecodeFile

`Chilkat 11.7.0 · sqlserver · Charset · HtmlEntityDecodeFile · method`

```sql
EXEC sp_OAMethod @charset, 'HtmlEntityDecodeFile', @success OUT, @inPath, @destPath
```

Reads the file at `inPath`, decodes HTML named entities and numeric character references, and writes the transformed content to `destPath`.

**Content transformation:** The output may contain literal markup-significant characters that were previously escaped. This operation does not parse, validate, or sanitize HTML.

Returns 1 for success, 0 for failure.

### Charset.LowerCase

`Chilkat 11.7.0 · sqlserver · Charset · LowerCase · method`

```sql
EXEC sp_OAMethod @charset, 'LowerCase', @sResult OUT, @inStr
```

Returns the lowercase form of `inStr` using Chilkat’s Unicode case conversion.

**Unicode casing:** Case conversion can change string length and is not the same operation as locale-aware collation or case-insensitive comparison.

Returns `NULL` on failure

### Charset.ReadFileToString

`Chilkat 11.7.0 · sqlserver · Charset · ReadFileToString · method`

```sql
EXEC sp_OAMethod @charset, 'ReadFileToString', @sResult OUT, @path, @charset
```

Reads the text file at `path`, decodes its bytes using the charset named by `charset`, and returns the resulting Unicode string.

**Charset must match the file:** The caller must supply the actual source encoding. Choosing the wrong charset can produce replacement characters or silently incorrect text even when the file can be decoded.

Returns `NULL` on failure

### Charset.SetErrorString

`Chilkat 11.7.0 · sqlserver · Charset · SetErrorString · method`

```sql
EXEC sp_OAMethod @charset, 'SetErrorString', NULL, @str, @charset
```

Configures the replacement used when `ErrorAction` is `1`. `str` is the replacement text, and `charset` identifies the charset used to encode that replacement into the conversion output.

**Replacement behavior:** Choose replacement text that is representable in the specified charset. A common replacement is `?`, but explicit error handling is safer when data loss is unacceptable.

### Charset.UpperCase

`Chilkat 11.7.0 · sqlserver · Charset · UpperCase · method`

```sql
EXEC sp_OAMethod @charset, 'UpperCase', @sResult OUT, @inStr
```

Returns the uppercase form of `inStr` using Chilkat’s Unicode case conversion.

**Unicode casing:** Case conversion can change string length and is not the same operation as locale-aware collation or case-insensitive comparison.

Returns `NULL` on failure

### Charset.UrlDecodeStr

`Chilkat 11.7.0 · sqlserver · Charset · UrlDecodeStr · method`

```sql
EXEC sp_OAMethod @charset, 'UrlDecodeStr', @sResult OUT, @inStr
```

Percent-decodes `inStr` and interprets the resulting bytes using the platform’s legacy ANSI character encoding.

For example, in a Western Windows code page, `%C9` may decode as `É`. UTF-8 input would encode the same character as `%C3%89` and is therefore not handled correctly by this legacy assumption.

**Legacy ANSI behavior:** Do not use this method for modern URLs or form data unless the data is known to use the applicable ANSI code page. Use `StringBuilder` URL decoding with an explicit charset, normally `utf-8`.

Returns `NULL` on failure

### Charset.VerifyFile

`Chilkat 11.7.0 · sqlserver · Charset · VerifyFile · method`

```sql
EXEC sp_OAMethod @charset, 'VerifyFile', @success OUT, @charset, @path
```

Returns `1` when the contents of the file at `path` form a valid byte sequence for the charset named by `charset`; otherwise returns `0`.

**Validation limitation:** A successful result means only that the bytes are structurally valid for that encoding. It does not identify the encoding or confirm that the decoded text is semantically correct.

### Charset.WriteStringToFile

`Chilkat 11.7.0 · sqlserver · Charset · WriteStringToFile · method`

```sql
EXEC sp_OAMethod @charset, 'WriteStringToFile', @success OUT, @textData, @path, @charset
```

Encodes the Unicode text in `textData` using the charset named by `charset` and writes the resulting bytes to the file at `path`.

**Destination encoding:** The charset argument is the third parameter. Select `utf-8` for modern interchange unless a receiving system requires a specific legacy encoding.

Returns 1 for success, 0 for failure.

