json — `n_pbt_json` #

← Component reference · Guide contents

Build a JSON type by type — string, number, boolean, array, nested object — with the escaping done for you, then read one back along a path: of_load, of_get_string, of_type, of_count. A single object builds your requests and reads your responses. All in pure PowerScript: no page, no engine, PowerBuilder 10 included.

▶ See it live — Demo application, JSON tile: the results, the code behind them and this page, side by side.

At a glance #

n_pbt_json is autoinstantiate: declare it as a local variable, no create or destroy. It is the very object that internally builds the payloads sent to the engine — now offered to your code, on the build and the read side.

Quick start #

Build a payload, then read a response back — it all fits in one local variable:

n_pbt_json  lnv_json
string      ls_customer
double      ld_total

// Write : each member is typed and escaped for you - a path may have levels
lnv_json.of_set_string("customer", "Ada")
lnv_json.of_set_number("total", 690.50)
lnv_json.of_set_boolean("paid", true)
// lnv_json.of_text() -> {"customer":"Ada","total":690.5,"paid":true}

// Read : load a response, reach values by path
lnv_json.of_load('{"order":{"customer":"Ada","total":690.50}}')
IF lnv_json.of_is_valid() THEN
	ls_customer = lnv_json.of_get_string("order/customer")   // Ada
	ld_total    = lnv_json.of_get_number("order/total")     // 690.5
END IF

A path is the keys from the root joined by /; an array index is its position, counted from 0: order/lines/0.

Build a payload #

Method	Role
`of_add_string (string as_path, string as_value) → long`	Appends a STRING, escaped for you, to the ARRAY at `as_path`. The array must already be there: open it first with `of_set_raw` and an empty array. Returns `0`, `-4` when `as_path` is missing or is not an array
`of_add_boolean (string as_path, boolean ab_value) → long`	Appends a BOOLEAN (`true` or `false`, never quoted) to the ARRAY at `as_path`. The array must already be there: open it first with `of_set_raw` and an empty array. Returns `0`, `-4` when `as_path` is missing or is not an array
`of_add_number (string as_path, long al_value) → long`	Appends a NUMBER (three overloads: `integer`, `long`, `double`) to the ARRAY at `as_path`. The array must already be there: open it first with `of_set_raw` and an empty array. Returns `0`, `-4` when `as_path` is missing or is not an array
`of_add_raw (string as_path, string as_json) → long`	Appends a value ALREADY in JSON (an object, an array) you vouch for to the ARRAY at `as_path`. The array must already be there: open it first with `of_set_raw` and an empty array. Returns `0`, `-4` when `as_path` is missing or is not an array
`of_set_array (string as_path, string as_values[]) → long`	WRITES a whole ARRAY of strings at `as_path` from a PowerBuilder array, each element escaped. An empty array writes an empty one. Same path rule and same codes as `of_set_string`
`of_set_members (string as_fragment) → long`	Merges members already formed elsewhere at the ROOT, comma-joined. An empty fragment writes nothing. Returns `0`
`of_clear ( )` → `long`	Empties the document to start another object with the same variable. Returns `0`
`of_text ( )` → `string`	The document as it stands (compact): what you built (`of_add_string`, `of_add_number`...) or loaded (`of_load`), after any change — the single output, ready to send, store or save back. `of_pretty` is the indented form. `{}` when empty; calling it empties nothing

Read a document #

Method	Role
`of_load (string as_json)` → `long`	Loads a JSON text for reading. Returns `0` when well-formed, `-5` when the argument is empty, `-4` when it is not valid JSON (the document is then dropped). Parses in pure PowerScript
`of_is_valid ( )` → `boolean`	True when the last `of_load` succeeded
`of_exists (string as_path)` → `boolean`	True when a value lives at the given path — tells a present-but-empty value from an absent one
`of_type (string as_path)` → `string`	The JSON type at the path: `object`, `array`, `string`, `number`, `boolean`, `null`; empty if absent
`of_get_string (string as_path)` → `string`	The value at the path, as text: a string comes back decoded, a number/boolean/null as text, an object or array as raw JSON (reloadable by `of_load`)
`of_get_number (string as_path)` → `double`	The number at the path, as a `double` — the decimal dot is honoured on any machine (2.5 is 2.5, not 2). `0` if absent
`of_get_boolean (string as_path)` → `boolean`	The boolean at the path: true only for the JSON literal `true`
`of_count (string as_path)` → `long`	The number of members of the object, or elements of the array, at the path. Returns `-1` when the value is scalar or absent (tells an empty array, `0`, from a missing one, `-1`)
`of_name (string as_path, long al_index)` → `string`	The name of the `al_index`-th member (1-based) of the object at the path — to read the keys of an object whose shape is unknown. With `of_count`, it walks the object
`of_pretty ( )` → `string`	The loaded document, re-indented for reading (several lines, tabs) — a log, a text box. Empty when nothing valid is loaded

Modify a document #

The write side changes the loaded document in place, then of_text returns the result (compact) — what to save back. The setters replace the value at the path, or add the last key when it is missing from a parent object. Each returns 0, -4 when the parent is missing or of the wrong type, -5 on an empty path.

Member	Role
`of_set_string (string as_path, string as_value) → long` → `long`	WRITES a string at `as_path`, escaped for you. The path may have SEVERAL levels (`a/b/c`): the missing ones are created as OBJECTS, and an EMPTY document becomes one — writing IS building. A value already there is replaced, wherever it sits. Returns `0`, `-4` when a level on the way is a scalar or an array, `-5` on an empty path
`of_set_number (string as_path, long al_value) → long` → `long`	WRITES a NUMBER at `as_path`, the decimal point forced whatever the region. Three overloads: `integer`, `long`, `double`. Same path rule and same codes as `of_set_string`
`of_set_boolean (string as_path, boolean ab_value) → long` → `long`	WRITES a BOOLEAN at `as_path`: `true` or `false`, never quoted. Same path rule and same codes as `of_set_string`
`of_set_raw (string as_path, string as_json) → long` → `long`	WRITES at `as_path` a value ALREADY in JSON — a nested object, an array, `null` — as it is: you vouch for it. This is also how an array is OPENED before `of_add_*`. Same path rule and same codes as `of_set_string`
`of_remove (string as_path)` → `long`	Removes the value at the path — an object member (its key and one comma go with it) or an array element; the result stays valid

n_pbt_json  lnv_json

// Load, edit in place, then read back the ONE document with of_text
lnv_json.of_load('{"name":"Ada","active":false}')
lnv_json.of_set_string("name", "Grace")   // replace
lnv_json.of_set_boolean("active", true)
lnv_json.of_set_number("count", 3)        // added : the key was absent
// lnv_json.of_text() -> {"name":"Grace","active":true,"count":3}

Scope. JSON parses in pure PowerScript, no page or engine: n_pbt_json stays autoinstantiate and works everywhere, PowerBuilder 10 included. For XML, see xml (which relies on the engine); to display a JSON as a collapsible tree, see jsontree.