---
product: Chilkat
product_version: 11.7.0
language: powerbuilder
language_label: PowerBuilder
class: Global
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/powerbuilder_GlobalRef.html
---
# Chilkat Global — PowerBuilder — v11.7.0

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

## Purpose

**Unlock Chilkat and configure library-wide defaults, diagnostics, and async behavior.**

`Chilkat.Global` is the Chilkat class for library-wide initialization, licensing, default behavior, diagnostics, and thread-pool control. Its most important method is `UnlockBundle`, which should be called once at application startup before using other Chilkat classes. It also provides settings for DNS caching, ANSI code page behavior, NTLM version, IPv6 preference, verbose TLS logging, async task execution, thread-pool limits, thread-pool logging, and special PKCS#7 encoding behavior.

**Library unlocking**

Call `UnlockBundle` once during application startup to unlock Chilkat components for use throughout the process.

**Global defaults**

Configure process-wide defaults such as ANSI code page handling, DNS caching behavior, IPv6 preference, and NTLM version selection.

**Diagnostics and logging**

Enable additional diagnostic behavior such as verbose TLS logging and thread-pool logging when troubleshooting difficult runtime issues.

**Async thread pool**

Control the limits and behavior of Chilkat's internal thread pool used by asynchronous task-based methods.

**Network-related behavior**

Adjust DNS and IP-version preferences that can affect how Chilkat classes resolve names and establish network connections.

**Compatibility options**

Set specialized process-wide options for interoperability scenarios, such as special PKCS#7 encoding behavior.

**Common pattern:** Create a `Chilkat.Global` object at application startup, call `UnlockBundle` once, then set any process-wide defaults before creating and using other Chilkat objects. Treat these settings as application-wide configuration, not per-object state.

For an extended overview, see [Global Class Overview](https://www.chilkatsoft.com/global_class_overview.asp).

## Object creation, unlocking and error handling

**Object Creation**

```powerbuilder
oleobject loo_Global
integer li_rc

loo_Global = create oleobject
li_rc = loo_Global.ConnectToNewObject("Chilkat.Global")
if li_rc < 0 then
    destroy loo_Global
    MessageBox("Error","Connecting to COM object failed")
    return
end if

// ... use loo_Global ...

destroy loo_Global
```

PowerBuilder uses the Chilkat ActiveX through an `oleobject`: declare the variable, `create` it, connect it to the Chilkat class with `ConnectToNewObject`, and `destroy` it when finished. A negative return code from `ConnectToNewObject` means the ActiveX is not registered, or the registered ActiveX does not match the bitness (32-bit or 64-bit) of the PowerBuilder target.

Objects returned by methods (such as an `HttpResponse` or `JsonObject`) are also `oleobject` variables and must likewise be destroyed. A method that fails to return an object returns `null`; test with `IsNull()`. In the signatures on this page, the Chilkat class name identifies which object is expected or returned; the PowerBuilder variable type is always `oleobject`.

To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as `ConnectToNewObject("Chilkat.Global.11")` for Chilkat v11.\*.\*.

Members typed `blob` exchange binary data as a Variant byte array. The PowerBuilder examples instead use the `BinData`-based alternatives (methods ending in *Bd*), which keep binary data inside Chilkat objects.

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` | `string DebugLogFilePath` | 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` | `blob LastBinaryResult (read-only)` | 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` | `string LastErrorHtml (read-only)` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `string LastErrorText (read-only)` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `string LastErrorXml (read-only)` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `long LastMethodSuccess` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `string LastStringResult (read-only)` | 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` | `long LastStringResultLen (read-only)` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `long VerboseLogging` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `string Version (read-only)` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `AnsiCodePage` | property, read/write | `long AnsiCodePage` |
| `AutoQBDecode` | property, read/write | `long AutoQBDecode` |
| `DefaultNtlmVersion` | property, read/write | `long DefaultNtlmVersion` |
| `DnsTimeToLive` | property, read/write | `long DnsTimeToLive` |
| `EnableDnsCaching` | property, read/write | `long EnableDnsCaching` |
| `KeepBinaryResult` | property, read/write | `long KeepBinaryResult` |
| `KeepStringResult` | property, read/write | `long KeepStringResult` |
| `MaxThreads` | property, read/write | `long MaxThreads` |
| `PreferIpv6` | property, read/write | `long PreferIpv6` |
| `ThreadPoolLogPath` | property, read/write | `string ThreadPoolLogPath` |
| `UncommonOptions` | property, read/write | `string UncommonOptions` |
| `UnlockStatus` | property, read-only | `long UnlockStatus (read-only)` |
| `UsePkcsConstructedEncoding` | property, read/write | `long UsePkcsConstructedEncoding` |
| `VerboseTls` | property, read/write | `long VerboseTls` |
| `DnsClearCache` | method | `long DnsClearCache()` |
| `FinalizeThreadPool` | method | `long FinalizeThreadPool()` |
| `ThreadPoolLogLine` | method | `long ThreadPoolLogLine(string str)` |
| `UnlockBundle` | method | `long UnlockBundle(string bundleUnlockCode)` |

## Properties

### Global.AnsiCodePage

`Chilkat 11.7.0 · powerbuilder · Global · AnsiCodePage · property · read/write · since 9.5.0.49`

```powerbuilder
long AnsiCodePage
```

The default ANSI code page is determined at runtime based on the computer where the application happens to be running. For example, the ANSI code page for an application running on a Japanese computer is likely to be Shift_JIS (code page 932), whereas on a US-English computer it would be iso-8859-1 (or Windows-1252 which is essentially a superset of iso-8859-1).

If there is a desire for the Chilkat library to use a specific ANSI code page regardless of locale, then this property should be set to the desired code page. The default value of this property is the ANSI code page of the local computer.

### Global.AutoQBDecode

`Chilkat 11.7.0 · powerbuilder · Global · AutoQBDecode · property · read/write · since 10.0.0`

```powerbuilder
long AutoQBDecode
```

If set to `1`, then `Q` or `B` encoded strings can be passed in any string argument to any Chilkat method, and Chilkat will automatically decode the string before using it. This is meant to be a convenient way to use non-usascii literal strings in your source code. See the links below for an example and for a discussion about non-usascii literal strings.

See also:

- [Avoid Non-usascii Literal Strings in Source Code](https://cknotes.com/avoid-non-usascii-literal-strings-in-source-code/)

### Global.DefaultNtlmVersion

`Chilkat 11.7.0 · powerbuilder · Global · DefaultNtlmVersion · property · read/write · since 9.5.0.52`

```powerbuilder
long DefaultNtlmVersion
```

Selects the default NTLM protocol version to use for NTLM authentication for HTTP, POP3, IMAP, SMTP, and HTTP proxies. The default value is 2. This property may optionally be set to 1.

### Global.DnsTimeToLive

`Chilkat 11.7.0 · powerbuilder · Global · DnsTimeToLive · property · read/write · since 9.5.0.49`

```powerbuilder
long DnsTimeToLive
```

If DNS caching is enabled, this is the time-to-live (in seconds) for a cached DNS lookup. A DNS lookup result older than this expiration time is discarded, and causes a new DNS lookup to occur. A value of 0 indicates an infinite time-to-live. The default value of this property is 0.

### Global.EnableDnsCaching

`Chilkat 11.7.0 · powerbuilder · Global · EnableDnsCaching · property · read/write · since 9.5.0.49`

```powerbuilder
long EnableDnsCaching
```

Controls whether DNS domain lookups (to resolve to IP addresses) are cached in memory. The default value is `0`, meaning that DNS caching is disabled.

### Global.KeepBinaryResult

`Chilkat 11.7.0 · powerbuilder · Global · KeepBinaryResult · property · read/write · since 9.5.0.53`

```powerbuilder
long KeepBinaryResult
```

If set to `1`, then the binary data returned by any method will be persisted in memory in the LastBinaryResult property. This allows for an ActiveX running in the SQL Server environment to access large varbinary return values via temp tables. The method would be called, and then the LastBinaryResult property would be fetched to get the full contents of the returned string.

### Global.KeepStringResult

`Chilkat 11.7.0 · powerbuilder · Global · KeepStringResult · property · read/write · since 9.5.0.52`

```powerbuilder
long KeepStringResult
```

If set to `1`, then the string returned by any method will be persisted in memory in the LastStringResult property. This allows for an ActiveX running in the SQL Server environment to access large string return values via temp tables. The method would be called, and then the LastStringResult property would be fetched to get the full contents of the returned string.

**Important:** When this property = `1`, all Chilkat methods that return strings will return the empty string. The string return value is available in the LastStringResult property.

### Global.MaxThreads

`Chilkat 11.7.0 · powerbuilder · Global · MaxThreads · property · read/write · since 9.5.0.52`

```powerbuilder
long MaxThreads
```

The maximum number of thread pool threads. The default value is 100. The maximum value is 500. Note: Asynchronous worker threads are created on as needed up to the maximum.

### Global.PreferIpv6

`Chilkat 11.7.0 · powerbuilder · Global · PreferIpv6 · property · read/write · since 9.5.0.70`

```powerbuilder
long PreferIpv6
```

If `1`, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is `0`, which will choose IPv4 over IPv6.

Note: Setting this property has the effect of also setting the default value of the PreferIpv6 property for other classes.

### Global.ThreadPoolLogPath

`Chilkat 11.7.0 · powerbuilder · Global · ThreadPoolLogPath · property · read/write · since 9.5.0.52`

```powerbuilder
string ThreadPoolLogPath
```

If set, indicates the path of a log file to be used by the thread pool thread and each of the pool worker threads for logging async activity. Chilkat always appends to the log file. If the log file already exists, then new information will be appended.

### Global.UncommonOptions

`Chilkat 11.7.0 · powerbuilder · Global · UncommonOptions · property · read/write · since 9.5.0.90`

```powerbuilder
string UncommonOptions
```

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.

### Global.UnlockStatus

`Chilkat 11.7.0 · powerbuilder · Global · UnlockStatus · property · read-only · since 9.5.0.62`

```powerbuilder
long UnlockStatus (read-only)
```

Indicates the unlocked status for the last call to UnlockBundle. The possible values are:

0. Not unlocked. (Still in locked state.)
1. Unlocked with in fully-functional trial mode.
2. Unlocked using a valid purchased unlock code.

Note: If UnlockBundle is called with a purchased unlock code, the UnlockStatus is correctly set to the value 2. This value is intentionally sticky. If a subsequent and redundant call to UnlockBundle happens, it is effectively a `No-Op` because the library is already unlocked. The UnlockStatus will not change.

If however, if the 1st call resulted in UnlockStatus = 1, and THEN the unlock method is called again with a purchased unlock code, the UnlockStatus should change from 1 to 2.

### Global.UsePkcsConstructedEncoding

`Chilkat 11.7.0 · powerbuilder · Global · UsePkcsConstructedEncoding · property · read/write · since 9.5.0.70`

```powerbuilder
long UsePkcsConstructedEncoding
```

This property should typically be left at the default value of `0`. If set to `1`, then Chilkat will use a constructed ASN.1 encoding for PCKS7 data. (This is an internal implementation option that normally does not matter, and should not matter. Some PKCS7 receiving systems might be picky, and this option can be used to satisfy this requirement.)

### Global.VerboseTls

`Chilkat 11.7.0 · powerbuilder · Global · VerboseTls · property · read/write · since 9.5.0.78`

```powerbuilder
long VerboseTls
```

If set to `1`, then causes extremely verbose logging (in LastErrorText) all TLS connections in any Chilkat class. This property should only be used for troubleshooting TLS problems. The default value is `0`.

Note: This property only has effect on Chilkat objects not yet created. Set the property first, then instantiate the Chilkat object.

## Methods

### Global.DnsClearCache

`Chilkat 11.7.0 · powerbuilder · Global · DnsClearCache · method · since 9.5.0.49`

```powerbuilder
long DnsClearCache()
```

This function clears the Chilkat in-memory DNS cache, which stores hostname-to-IP address mappings to avoid repeated DNS lookups.

**Note:**

- The DNS cache is shared across all Chilkat objects, so clearing it will impact all such objects.
- Chilkat's DNS caching respects the TTL (time to live) of DNS records. If the TTL has expired since the initial lookup, Chilkat will perform a new DNS query and update the cache with the latest IP address.

Returns 1 for success, 0 for failure.

### Global.FinalizeThreadPool

`Chilkat 11.7.0 · powerbuilder · Global · FinalizeThreadPool · method · since 9.5.0.56`

```powerbuilder
long FinalizeThreadPool()
```

Called to stop and finalize all threads in the thread pool, and causes the thread pool thread to exit.

The following behaviors exist in **v9.5.0.64 and later**:

- All remaining asynchronous tasks are automatically canceled.
- Restores the thread pool to it's pristine state where no background threads are running.

It is a good idea to call this method at the very end of a program, just before it exits. This is especially true for programs written in VBScript, VB6, FoxPro, and PowerBuilder.

Returns 1 for success, 0 for failure.

### Global.ThreadPoolLogLine

`Chilkat 11.7.0 · powerbuilder · Global · ThreadPoolLogLine · method · since 9.5.0.77`

```powerbuilder
long ThreadPoolLogLine(string str)
```

Logs a line to the thread pool log file.

Returns 1 for success, 0 for failure.

### Global.UnlockBundle

`Chilkat 11.7.0 · powerbuilder · Global · UnlockBundle · method · since 9.5.0.49`

```powerbuilder
long UnlockBundle(string bundleUnlockCode)
```

Unlocks the entire Chilkat API for all classes. This should be called once at the beginning of a program. Once unlocked, objects of any Chilkat class may be instantiated and used. To unlock in fully-functional 30-day trial mode, pass any string, such as `Hello`, in `bundleUnlockCode`. If a license is purchased, then replace the `Hello` with the purchased unlock code.

After calling UnlockBundle once, the instance of the Global object may be discarded/deleted (assuming the programming language requires explicit deletes). Multiple calls to UnlockBundle are harmless. If the Chilkat API is already unlocked, the duplicate calls to UnlockBundle are no-ops.

**Important:** Unlocking sets a flag in memory to indicate the unlocked status. There are no licensing files, and there is no communication with any Chilkat servers. This means your application, script, etc. must call UnlockBundle once at the start each time it runs. The good thing is that your application can run on any computer -- there are no licensing files to worry about. Also: If an application forgets to call UnlockBundle, Chilkat will automatically unlock in trial mode, and this will eventually fail when the trial runs out. If you purchased a license, it is very important to make sure you call UnlockBundle with the purchased unlock code.

Returns 1 for success, 0 for failure.

