json — n_pbt_json #

← Referência dos componentes · Índice do guia

Construir um JSON tipo a tipo — texto, número, booleano, array, objeto aninhado — com o escape feito por si, e depois ler um ao longo de um caminho: of_load, of_get_string, of_type, of_count. Um único objeto constrói os seus pedidos e lê as suas respostas. Tudo em PowerScript puro: sem página, sem motor, PowerBuilder 10 incluído.

▶ Ver ao vivo — Aplicação de demonstração, mosaico JSON: os resultados, o código que os produz e esta página, lado a lado.

Em resumo #

n_pbt_json é autoinstantiate: declara-se como variável local, sem create nem destroy. É o mesmo objeto que, internamente, constrói os payloads enviados ao motor — agora oferecido ao seu código, do lado da construção e da leitura.

Início rápido #

Construir um payload, depois reler uma resposta — tudo cabe numa variável local:

// Local variables
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(/*path*/ "customer", /*value*/ "Ada")
lnv_json.of_set_number(/*path*/ "total", /*value*/ 690.50)
lnv_json.of_set_boolean(/*path*/ "paid", /*value*/ true)

// lnv_json.of_text() -> {"customer":"Ada","total":690.5,"paid":true}

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

Um caminho são as chaves desde a raiz unidas por /; o índice de um array é a sua posição, contada a partir de 1, como toda a posição da biblioteca: order/lines/1 é a primeira linha, order/lines/0 não designa nada — uma escrita recusa-o com -5. Um nível escreve-se como o escreve o JSON Pointer (RFC 6901): ~1 é um / da chave e ~0 um ~ (paths/~1users lê a chave /users; of_escape_key converte uma chave), um nível vazio é a chave "" (a//b), e um caminho pode começar por / — a forma completa do ponteiro, a única maneira de nomear a chave "" da raiz (/). Se um objeto escrever a mesma chave duas vezes, é a sua PRIMEIRA ocorrência que é lida e escrita — um navegador guarda a última.

Construir um payload #

Ler um documento #

// Local variables
n_pbt_json  lnv_json
string      ls_tags[]
string      ls_compact
long        ll_count

// Read every element of an array at once, then store the document on one line
lnv_json.of_load(/*json*/ '{"customer":{"name":"Ada","tags":["vip","b2b"]}}')
ll_count = lnv_json.of_get_array(/*path*/ "customer/tags", /*values*/ ls_tags)   // 2 : vip, b2b

// The document on one line, without a space : the smallest text to store
ls_compact = lnv_json.of_pretty(/*indent*/ 0)

Modificar um documento #

O lado de escrita altera o documento carregado no lugar, depois of_text devolve o resultado (compacto) — o que se reescreve. Os setters substituem o valor no caminho, ou acrescentam a última chave quando falta a um objeto pai. Cada um devolve 0, -4 quando um nível do caminho é um escalar, ou um array sem esse índice, -5 num caminho vazio ou um índice 0 num array. Um array encontrado no caminho atravessa-se por um índice que EXISTE (items/1/qty acrescenta qty ao primeiro elemento); só uma chave de objeto é criada. Um valor null (número, booleano, JSON em bruto vazio) escreve-se null. Um ciclo de escritas, de chaves acrescentadas ou de remoções num documento grande (2 000 linhas) continua rápido: cada chamada só relê o que toca.

// Local variables
n_pbt_json  lnv_json

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

// lnv_json.of_text() -> {"name":"Grace","active":true,"count":3}

Datas #

Uma data escreve-se e lê-se em ISO 8601 — o que escrevem as API, os navegadores e o Python —, seja qual for o formato de data da máquina: uma data "2026-10-10", uma data-hora "2026-10-10T14:30:00" (a fração de segundo segue quando não é nula), uma hora "14:30:00". Um valor nulo escreve null.

// Local variables
n_pbt_json  lnv_json
date        ld_due
datetime    ldt_created

// Write : ISO 8601, whatever the date format of the machine
lnv_json.of_set_date(/*path*/ "due", /*value*/ Date(2026, 10, 31))
lnv_json.of_set_datetime(/*path*/ "created", /*value*/ DateTime(Date(2026, 10, 10), Time(14, 30, 0)))

// Read what an API writes : the Z is read, the hour stays the one written
lnv_json.of_load(/*json*/ '{"due":"2026-10-31","created":"2026-10-10T14:30:00Z"}')
ld_due      = lnv_json.of_get_date(/*path*/ "due")
ldt_created = lnv_json.of_get_datetime(/*path*/ "created")

Um DataStore em JSON, e volta #

O PowerBuilder só tem ExportJson e ImportJson a partir da 2017 R2. n_pbt_json fá-lo desde o PowerBuilder 10, tipado pelas colunas: uma cadeia, um número (um decimal mantém todos os algarismos), uma data yyyy-mm-dd, uma data-hora, uma hora, null para um NULL. Uma sobrecarga recebe um datawindow, outra um datawindowchild.

// Local variables
n_pbt_json  lnv_json
datastore   lds_orders
long        ll_rows
string      ls_body

// Send : every row of a retrieved DataStore as typed objects - the body of the call
lds_orders = create datastore
lds_orders.DataObject = "d_orders"
lds_orders.SetTransObject(SQLCA)
lds_orders.Retrieve()
ll_rows = lnv_json.of_from_datastore(/*path*/ "orders", /*source*/ lds_orders)
ls_body = lnv_json.of_text()

// Receive : the objects of a response inserted as NEW rows, ready for Update
lds_orders.Reset()
lnv_json.of_load(/*json*/ '{"data":[{"id":7,"customer":"Grace","amount":"19.99","due":"2026-12-24"}]}')
ll_rows = lnv_json.of_to_datastore(/*path*/ "data", /*target*/ lds_orders)
destroy lds_orders

Quando o texto não é JSON #

// Local variables
n_pbt_json  lnv_json
long        ll_rc
string      ls_why
long        ll_where

// A response with a colon missing on its second line
ll_rc = lnv_json.of_load(/*json*/ '{"id":4152,~r~n "paid" true}')
IF ll_rc < 0 THEN
	ls_why   = lnv_json.of_get_last_error()     // line 2, column 9 : ':' expected after a key
	ll_where = lnv_json.of_error_position()     // 22
END IF

Âmbito. O JSON analisa-se em PowerScript puro, sem página nem motor: n_pbt_json continua autoinstantiate e funciona em todo o lado, PowerBuilder 10 incluído. Para XML, veja xml (que assenta no motor); para mostrar um JSON como árvore recolhível, veja jsontree.

← Referência dos componentes · Índice do guia