Connection string

NTiConnection is configured through a standard ADO.NET connection string, in key=value;key=value format. This page is the exhaustive reference for NTi 5 keywords and their corresponding NTiConnection properties.

General rules

Keywords are case-insensitive, and several synonyms are accepted for v4 compatibility.
An unknown keyword is ignored (v4 compatibility, a v4 connection string can be reused as is).
An invalid value for a known keyword throws immediately, as soon as the string is assigned. There is never a silent fallback to a default value.
Once the connection is open, the configuration is locked in, and the password is stripped from ConnectionString (unless persist security info=true). See the Connection article for the detail.

using Aumerial.Data.Nti;

await using var connection = new NTiConnection(
    "server=MYIBMI;user=MYUSER;password=MYPASSWORD;" +
    "ssl=true;pooling=true;max pool size=20;" +
    "default schema=MYLIB;naming=sql;application name=OrderApi");
await connection.OpenAsync();

Server and identity

Property	Keywords	Default	Description
`Server`	`server` `host` `system` `dsn` `datasource` `data source`	(required)	DNS name or IP address of the IBM i.
`Username`	`user` `user id` `userid` `uid`	(required)	IBM i user profile.
`Password`	`password` `pwd`	(required)	Password (every `QPWDLVL` level is supported).
`AdditionalFactor`	`additional factor` `additionalfactor` `mfa` `2fa`	none	Static additional authentication factor (TOTP, etc.).
`AdditionalFactorProvider`	(property only)	none	Synchronous callback invoked at signon for a physical session, which receives a context (host, user). Takes precedence over the async variant.
`AdditionalFactorAsyncProvider`	(property only)	none	Asynchronous variant (vaults, prompts). On `OpenAsync`, it's awaited natively with the caller's token, so it's cancellable. On synchronous `Open`, it starts outside any `SynchronizationContext` with an unbounded wait, so it's up to you to bound interactive prompts.
`LicenseLibrary`	`license library`	`KNTI`	Library holding the NTi license on the partition.
(none)	`isvid`	none	Vendor key (ISV integrations).
(none)	`persist security info` `persistsecurityinfo`	`false`	Keeps the password in `ConnectionString` after opening (default: stripped).
`ConnectionTimeout` (read-only)	`connect timeout` `connection timeout` `timeout`	0 (unlimited)	Connection establishment timeout, in seconds. 0 = infinite.

Network and transport

Property	Keywords	Default	Description
`UseSSL`	`ssl` `tls` `use ssl` `use tls`	`false`	Encrypts the connections to the host servers over TLS. The default ports then switch to their 94xx variants.
`Untrusted`	`untrusted`	`false`	Accepts any server certificate (test environments only).
`UsePortMapper`	`use mapper` `use port mapper`	`false`	Resolves ports through the port mapper (449) instead of the fixed ports.
`SignonPort`	`signon port`	8476 (9476 over TLS)	Port of the signon server.
`DatabasePort`	`database port`	8471 (9471 over TLS)	Port of the database server.
`CommandPort`	`command port`	8475 (9475 over TLS)	Port of the command/program server.
`MapperPort`	`mapper port`	449	Port of the port mapper.
`Compress`	`compress` `use compression`	`true`	RLE compression for large responses.

Connection pooling

Property	Keywords	Default	Description
`Pooling`	`pool` `pooling` `pooled` `connection pool` `connection pooling`	`false`	Turns on connection pooling. Off by default for v4 compatibility, it has to be turned on explicitly, which is strongly recommended for the web.
`PoolSize`	`pool size` `poolsize`	50	Target size of the pool.
`LimitPoolSize`	`limit pool size` `limitpoolsize` `pool limit` `poollimit`	`false`	Turns `PoolSize` into a hard cap.
`PoolSize` + `LimitPoolSize`	`maxpoolsize` `max pool size`	(not set)	Shortcut: sets the size AND turns on the cap.

Data and text

Property	Keywords	Default	Description
`DefaultCcsid`	`default ccsid` `defaultccsid`	none	Asserts that "untagged text is in this codepage." Without it, CHAR/VARCHAR CCSID 65535 = FOR BIT DATA (binary, never converted). Essential for reading text on systems with QCCSID=65535. Never overrides a real column CCSID.
`ForceTranslate`	`force translate`	none	Reinstates v4 semantics, decoding BINARY/VARBINARY/ROWID fields as text in this CCSID. Never touches FOR BIT DATA.
(none)	`text errors` `texterrors`	`lenient`	Error mode for conversions: `lenient` (tolerant decoding with U+FFFD, strict encoding), `strict`, `legacy` ("?" substitution, full v4 behavior).
`TrimCharFields`	`trim`	`true`	Strips trailing blanks from fixed-length CHAR/GRAPHIC values.
`LegacyNullSemantics`	`null semantics` `legacy nulls`	`false`	Reinstates v4 NULL semantics, with `GetValue` and `ExecuteScalar` returning `null` instead of `DBNull`.
(none)	`roundoption` `round option`	server default	DECFLOAT rounding mode (server register).
`LOBMaxSize`	`lob threshold`	15360	Threshold, in bytes, beyond which a LOB is read through a locator instead of inline.

Execution and fetching

Property	Keywords	Default	Description
`BlockingFactor`	`blocking` `blocking factor` `blockingfactor`	0 (adaptive)	Rows per fetch block. By default, the value is sized automatically from the row width to target `block size`, capped at 32767. A value greater than 0 forces a fixed count, as in v4.
`FetchBlockSize`	`block size` `blocksize`	512	Target fetch block size, in KiB, for automatic sizing.
`FetchAhead`	`fetch ahead` `fetchahead`	`false`	Overlaps network transfer and decoding, by requesting the next block while the current one is still being read.

SQL context

Property	Keywords	Default	Description
`DefaultDatabase`	`default schema` `default database` `default collection` `schema` `database` `deault schema` (v4 typo kept)	none	The session's current schema (`SET CURRENT SCHEMA`). Can be changed on the fly through `ChangeDatabase`.
`NamingConvention`	`naming` `naming convention`	`sql`	Naming convention: `sql` (`LIB.OBJ`) or `sys` (`LIB/OBJ`, library list). The EF Core layer requires `sql`.

Client identity (accounting)

Property	Keywords	Default	Description
`ApplicationName`	`application name` `applicationname`	`.NET Application`	Application name pushed to the server (auditing/accounting).
`ClientAccounting`	`client accounting` `clientaccounting`	none	Client accounting code.
`ClientUserIdentifier`	`client user identifier`	none	End-user identifier (traceability).
`ClientProgramIdentifier`	`client program identifier`	none	Client program identifier.

A note on the pool key

The connection pool is indexed by the full configuration, client identity included, with application name, client accounting, client user identifier, and client program identifier all part of the pool key. Two distinct identities therefore never share a pool. The password itself never enters the key in clear text.

What's next?

Connection: lifecycle, pooling, TLS, MFA, cancellation
Overview: the provider's architecture and features
Quickstart guide: first connection and first IBM i calls