What the Class Is Used For

Use Chilkat.Global at application startup to unlock the Chilkat library and establish global behavior that affects other Chilkat classes. It is also used for library-wide troubleshooting tasks, such as enabling verbose TLS logging, configuring DNS caching, writing thread-pool logs, clearing the DNS cache, and finalizing asynchronous worker threads before program exit.

Unlock the API Call UnlockBundle once at program startup to unlock all Chilkat classes.

Set Global Defaults Configure ANSI code page, NTLM version, IPv6 preference, DNS caching, TLS logging, and PKCS#7 encoding behavior.

Manage Async Infrastructure Control the Chilkat thread pool size, log async activity, and finalize thread pool threads before program exit.

Troubleshoot Library-Wide Behavior Use LastErrorText, VerboseTls, and thread-pool logging to diagnose difficult problems.

Typical Startup Workflow

Create a Global object at the beginning of the application.
Call UnlockBundle with the purchased unlock code, or any string for fully functional trial mode.
Check UnlockStatus to confirm whether Chilkat is unlocked in trial mode or purchased-license mode.
Set any global options that should affect subsequently created Chilkat objects, such as VerboseTls, PreferIpv6, or DNS caching settings.
Create and use other Chilkat objects normally.
At program shutdown, optionally call FinalizeThreadPool, especially in scripting or COM-based environments such as VBScript, VB6, FoxPro, and PowerBuilder.

Core Concepts

Concept	Meaning	Important Members
Library Unlocking	Unlocking enables the Chilkat API for all classes. It must be done once each time the application runs.	UnlockBundle, UnlockStatus
Global Defaults	Settings that influence default behavior across Chilkat objects, such as ANSI encoding, NTLM version, IPv6 preference, and DNS caching.	AnsiCodePage, DefaultNtlmVersion, PreferIpv6, EnableDnsCaching
DNS Cache	Optional in-memory hostname-to-IP cache shared by Chilkat objects.	EnableDnsCaching, DnsTimeToLive, DnsClearCache
Thread Pool	Chilkat’s asynchronous worker thread infrastructure. Worker threads are created as needed up to the configured maximum.	MaxThreads, ThreadPoolLogPath, ThreadPoolLogLine, FinalizeThreadPool
TLS Diagnostics	Extremely verbose TLS logging can be enabled for troubleshooting TLS connection problems.	VerboseTls
Special Compatibility Options	Rarely used settings for unusual encoding, PKCS#7, or other compatibility requirements.	AutoQBDecode, UsePkcsConstructedEncoding, UncommonOptions

Core Properties

Property	Purpose	Guidance
AnsiCodePage	Sets the default ANSI code page Chilkat uses when ANSI text must be interpreted or emitted.	Defaults to the local computer’s ANSI code page. Set explicitly when an application needs consistent ANSI behavior regardless of system locale.
AutoQBDecode	Allows Q-encoded or B-encoded strings to be passed in string arguments and automatically decoded before use.	Useful when source code needs to contain non-US-ASCII literal strings in an encoded form.
DefaultNtlmVersion	Selects the default NTLM protocol version for NTLM authentication.	Default is 2. Can optionally be set to 1. Applies to HTTP, POP3, IMAP, SMTP, and HTTP proxies.
EnableDnsCaching	Enables or disables in-memory DNS lookup caching.	Default is false. Enable when repeated DNS lookups should be avoided.
DnsTimeToLive	Time-to-live, in seconds, for cached DNS lookups.	Default is 0, meaning infinite TTL. A cached DNS result older than the configured TTL is discarded and refreshed.
MaxThreads	Maximum number of Chilkat thread-pool worker threads.	Default is 100. Maximum is 500. Async worker threads are created as needed.
PreferIpv6	Controls whether IPv6 is preferred over IPv4 when both are available.	Default is false, meaning IPv4 is preferred. Setting this also affects the default PreferIpv6 behavior for other Chilkat classes.
ThreadPoolLogPath	Path to a log file used by the thread pool and worker threads.	Chilkat appends to the file. Existing log files are not overwritten.
UnlockStatus	Indicates the result of the last meaningful UnlockBundle call.	0 = not unlocked, 1 = trial mode, 2 = purchased unlock code.
UsePkcsConstructedEncoding	Controls whether Chilkat uses constructed ASN.1 encoding for PKCS#7 data.	Default is false. Leave unchanged unless a PKCS#7 receiving system specifically requires this behavior.
VerboseTls	Enables extremely verbose TLS logging in LastErrorText for TLS connections.	Default is false. Use only for troubleshooting. Set before creating the Chilkat objects that should be affected.
UncommonOptions	Catch-all property for uncommon needs.	Defaults to the empty string and should typically remain empty.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Unlocking Chilkat

UnlockBundle unlocks the entire Chilkat API for all classes. It should be called once near the beginning of the program, before creating and using other Chilkat objects.

UnlockStatus	Meaning	Typical Situation
0	Not unlocked.	Chilkat is still in the locked state.
1	Unlocked in fully functional trial mode.	UnlockBundle was called with a trial string, or the library unlocked in trial mode.
2	Unlocked using a valid purchased unlock code.	UnlockBundle was called with a purchased unlock code.

Important licensing behavior: Unlocking sets an in-memory flag. There are no license files and no communication with Chilkat servers. Therefore, the application must call UnlockBundle once each time it starts.

Duplicate calls are harmless: Multiple calls to UnlockBundle are safe. If Chilkat is already unlocked with a purchased unlock code, a redundant call is effectively a no-op and UnlockStatus remains 2.

DNS Caching

Chilkat can cache DNS hostname-to-IP lookups in memory. This cache is shared across Chilkat objects.

Member	Purpose	Behavior
EnableDnsCaching	Turns DNS caching on or off.	Default is false. When disabled, Chilkat does not use its in-memory DNS cache.
DnsTimeToLive	Controls expiration of cached lookups.	Value is in seconds. 0 means cached entries do not expire due to Chilkat’s TTL setting.
DnsClearCache	Clears the shared in-memory DNS cache.	Impacts all Chilkat objects because the cache is shared.

Use with care: Clearing the DNS cache affects all Chilkat objects in the application. Use DnsClearCache when stale cached hostname resolutions must be discarded.

Thread Pool and Async Activity

Task	Member	Details
Limit async worker threads	MaxThreads	Sets the maximum number of thread-pool threads. Default is 100; maximum is 500.
Enable async logging	ThreadPoolLogPath	Sets the file path used by the thread pool and worker threads for logging async activity. Chilkat appends to the log file.
Write custom log line	ThreadPoolLogLine	Writes a line to the configured thread-pool log file.
Stop and reset the thread pool	FinalizeThreadPool	Stops and finalizes thread-pool threads, cancels remaining async tasks, and restores the thread pool to a pristine state.

Shutdown recommendation: Calling FinalizeThreadPool at the very end of a program is recommended, especially for VBScript, VB6, FoxPro, and PowerBuilder applications.

Networking and Authentication Defaults

Area	Property	Effect
NTLM authentication	DefaultNtlmVersion	Selects the default NTLM protocol version for HTTP, POP3, IMAP, SMTP, and HTTP proxy authentication.
IPv4 / IPv6 preference	PreferIpv6	When true, Chilkat prefers IPv6 over IPv4 when both are supported for a domain. The default is to prefer IPv4.
DNS caching	EnableDnsCaching, DnsTimeToLive	Controls whether resolved IP addresses are cached and how long cached results remain valid.
TLS troubleshooting	VerboseTls	Enables extremely verbose TLS logging for Chilkat objects created after the property is set.

Encoding and Compatibility Settings

Setting	Use Case	Default / Guidance
AnsiCodePage	Control how ANSI text is interpreted independently of the computer’s locale.	Defaults to the local computer’s ANSI code page. Set explicitly for predictable behavior across machines.
AutoQBDecode	Automatically decode Q-encoded or B-encoded strings passed to Chilkat methods.	Useful for non-US-ASCII literals embedded in source code.
UsePkcsConstructedEncoding	Use constructed ASN.1 encoding for PKCS#7 data.	Default is false. Enable only for unusual receiving systems that require this encoding style.
UncommonOptions	Catch-all for uncommon or special behavior.	Typically left empty.

Method Summary

Method	Purpose	When to Use
UnlockBundle	Unlocks the entire Chilkat API for all classes.	Call once at application startup with a purchased unlock code, or any string for trial mode.
DnsClearCache	Clears Chilkat’s shared in-memory DNS cache.	Use when cached hostname-to-IP mappings should be discarded.
FinalizeThreadPool	Stops and finalizes thread-pool threads.	Call near program exit to cancel remaining async tasks and restore the thread pool to a clean state.
ThreadPoolLogLine	Writes a line to the thread-pool log file.	Use after setting ThreadPoolLogPath when custom async diagnostic messages are needed.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Chilkat appears to be running in trial mode	UnlockBundle, UnlockStatus	Confirm the application calls UnlockBundle with the purchased unlock code each time it starts.
License status seems confusing after repeated unlock calls	UnlockStatus	Remember that purchased unlock status is sticky. A redundant unlock call after successful purchased unlocking does not downgrade the status.
TLS connection fails with insufficient diagnostic detail	VerboseTls	Set VerboseTls before creating the Chilkat object involved in the TLS connection.
DNS results appear stale	EnableDnsCaching, DnsTimeToLive, DnsClearCache	Review DNS cache settings and clear the shared cache if necessary.
Async activity is difficult to diagnose	ThreadPoolLogPath, ThreadPoolLogLine	Configure a thread-pool log path and write custom log lines around important async activity.
Program does not exit cleanly after async work	FinalizeThreadPool	Call FinalizeThreadPool at the end of the program, especially in scripting and COM-based environments.
Text encoding differs across computers	AnsiCodePage	Set a specific ANSI code page when behavior must be consistent across locales.

Common Pitfalls

Pitfall	Better Approach
Calling UnlockBundle only once during installation.	Call UnlockBundle once each time the application starts. Unlocking is an in-memory state, not a saved license file.
Assuming Chilkat contacts a licensing server during unlock.	Unlocking does not communicate with Chilkat servers and does not require license files.
Enabling VerboseTls after creating the object being debugged.	Set VerboseTls first, then instantiate the Chilkat object involved in the TLS connection.
Leaving DNS cache TTL infinite when DNS changes must be noticed.	Set DnsTimeToLive to a non-zero value or call DnsClearCache when necessary.
Increasing MaxThreads without reason.	Use the default unless the application has a clear need for more async worker capacity. The maximum allowed value is 500.
Changing UsePkcsConstructedEncoding unnecessarily.	Leave it at false unless a specific PKCS#7 receiving system requires constructed ASN.1 encoding.
Forgetting to finalize the thread pool in scripting or COM applications.	Call FinalizeThreadPool at program shutdown to stop worker threads and cancel remaining async tasks.

Best Practices

Recommendation	Reason
Unlock early in application startup.	Calling UnlockBundle before other Chilkat work avoids accidental trial-mode behavior.
Check UnlockStatus after unlocking.	It confirms whether Chilkat is locked, trial-unlocked, or unlocked with a purchased code.
Set global defaults before creating dependent Chilkat objects.	Some global options, such as VerboseTls, only affect objects created after the property is set.
Use DNS caching deliberately.	DNS caching can reduce repeated lookups, but stale results may need a TTL or explicit cache clearing.
Use thread-pool logging only when diagnosing async behavior.	ThreadPoolLogPath can be useful, but Chilkat appends to the log file and it may grow over time.
Use VerboseTls only for troubleshooting.	It causes extremely verbose TLS logging and should not normally be enabled in production.
Leave uncommon compatibility options empty unless needed.	UncommonOptions and UsePkcsConstructedEncoding are intended for special cases.
Call FinalizeThreadPool at the end of programs that use async tasks.	It cancels remaining async tasks and returns the thread pool to a clean state.

Summary

Chilkat.Global is the Chilkat class for library-wide initialization, licensing, defaults, diagnostics, and thread-pool control. Its most important method is UnlockBundle, which should be called once at application startup. The class also configures DNS caching, ANSI code page behavior, NTLM version, IPv6 preference, verbose TLS logging, async thread-pool limits, thread-pool logging, and special PKCS#7 encoding behavior.

The most important practical guidance is to unlock early, set global diagnostic and networking defaults before creating other Chilkat objects, avoid uncommon options unless required, and finalize the thread pool at program shutdown when async tasks or scripting environments are involved.

Chilkat.Global Class Overview