xml — `n_pbt_xml` #

← Referencia de componentes · Índice de la guía

Escribir un XML elemento por elemento — aperturas, atributos, texto, cierres — con el escapado hecho por usted, y luego leer uno con XPath real: of_load, of_get_value, of_get_attr, of_count. PowerBuilder 10 no tiene analizador XML; este se apoya en DOMParser y document.evaluate del motor WebView2, llamados de forma sincrónica.

▶ Verlo en vivo — Aplicación de demostración, mosaico XML: los resultados, el código que los produce y esta página, lado a lado.

En resumen #

El lado de construcción es PowerScript puro (armar una cadena no necesita motor). El lado de lectura abre una página oculta en la primera consulta. El XPath es la versión 1.0, tal como lo evalúa el navegador. Hay un documento a la vez: una lectura sobre un documento construido lo carga primero en la página, se convierte en el documento cargado, y el of_start_element siguiente empieza uno nuevo. Una lectura se rechaza mientras un elemento del documento construido siga abierto (-4, vacío o false, e is_last_error): cierre primero sus elementos — no se pierde nada. of_xml y of_pretty, que trabajan sobre una copia, siguen disponibles.

Inicio rápido #

// Local variables
n_pbt_xml  lnv_xml

// Create the object once, free it when done
lnv_xml = create n_pbt_xml

// Read : load, then query with XPath
lnv_xml.of_load(/*xml*/ '<order id="4152"><customer>Ada</customer></order>')
IF lnv_xml.of_is_valid() THEN
	MessageBox("Customer", lnv_xml.of_get_value(/*xpath*/ "/order/customer"))   // Ada
	MessageBox("Id", lnv_xml.of_get_attr(/*xpath*/ "/order", /*name*/ "id"))              // 4152
END IF

// Build : element by element, escaping done for you
lnv_xml.of_clear()
lnv_xml.of_start_element(/*name*/ "order")
lnv_xml.of_element_attr(/*name*/ "id", /*value*/ "4152")
lnv_xml.of_leaf(/*name*/ "customer", /*text*/ "Ada & Co")
lnv_xml.of_end_element()

// lnv_xml.of_xml() -><order id="4152"><customer>Ada &amp; Co</customer></order>

// Free the object
destroy lnv_xml

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`is_last_error`	string	`""`	Por qué la última lectura devolvió vacío, `false`, `0` o un código negativo: documento mal formado, XPath rechazado por el motor, XPath sin coincidencia, nada cargado, límite demo, página que no respondió. Vacío tras una lectura con éxito. El builder también escribe aquí cuando rechaza un nombre de elemento o de atributo no válido
`ipo_owner`	powerobject	`null`	El objeto visual para el que trabaja esta utilidad: la licencia se comprueba en su clase. Se asigna antes de la primera lectura; asignado más tarde, se transmite en la lectura siguiente. Necesario solo en la aplicación de demostración; una clave de desarrollo o de ejecución desbloquea la lectura sin él. Sin desbloquear, la lectura está en modo demo — documentos de 64 KB como máximo, modificaciones incluidas. La construcción no lo necesita: es PowerScript puro

Construir un documento #

Miembro	Función
`of_start_element (string as_name)`	Abre un elemento (los elementos se anidan: una etiqueta abierta se cierra primero). Un nombre no válido (vacío, con un espacio, un carácter prohibido, más de un `:`, un `:` al principio o al final) se rechaza: `is_last_error` dice por qué, y el elemento queda fuera del documento con todo lo que contiene
`of_element_attr (string as_name, string as_value)`	Añade un atributo al elemento abierto, valor escapado — saltos de línea y tabulaciones incluidos, para que se relean tal cual (antes de cualquier hijo o texto). Un nombre no válido se rechaza (`is_last_error`); el mismo nombre dado dos veces deja UN solo atributo, con el segundo valor
`of_element_text (string as_text)`	El contenido de texto del elemento actual, escapado; los caracteres de control que XML prohíbe se eliminan (uno solo dejaba todo el documento mal formado)
`of_end_element ( )`	Cierra el elemento actual (vacío, se auto-cierra `<name/>`)
`of_leaf (string as_name, string as_text)`	Un elemento hoja en una llamada — `<name>texto</name>`, escapado
`of_clear ( )` → `long`	Vacía el documento — construido o cargado — para empezar otro; un documento cargado sale también de la página. Devuelve `0`
`of_xml ( )` → `string`	El documento tal cual: lo que construyó o cargó (`of_load`), tras cualquier cambio — la salida única, para enviar, almacenar o reescribir. Un documento construido no necesita página (todo elemento abierto se cierra) ; uno cargado lo serializa el motor. `of_pretty` da la forma indentada

Leer un documento (XPath) #

Miembro	Función
`of_load (string as_xml)` → `long`	Carga un texto XML (analizado por el DOMParser del motor). Devuelve `0` si está bien formado, `-5` si está vacío, `-4` si no es XML válido (o, en modo demo, demasiado largo una vez desarrolladas sus entidades), `-2` si la página oculta no respondió. Con un código negativo NO queda nada: ni un documento cargado antes, ni uno construido a medias
`of_is_valid ( )` → `boolean`	Verdadero cuando se tiene un documento bien formado — cargado con `of_load`, o construido (se carga entonces en la página, como en toda lectura). Falso si no hay nada, o si el documento construido está mal formado o aún tiene un elemento abierto
`of_exists (string as_xpath)` → `boolean`	Verdadero cuando el XPath coincide con al menos un nodo. Una expresión que devuelve un VALOR (`count(//line)`) no es un nodo: léala con `of_get_value`
`of_get_value (string as_xpath)` → `string`	El contenido de texto del PRIMER nodo coincidente. Vacío si ninguno (`is_last_error` lo dice). Un XPath que devuelve un VALOR lo da como texto: `count(//line)` → `3`, `sum(//@qty)`, `boolean(//paid)` → `true`
`of_get_attr (string as_xpath, string as_name)` → `string`	El valor del atributo `as_name` del primer nodo coincidente. Vacío si ausente
`of_count (string as_xpath)` → `long`	Cuántos nodos selecciona el XPath. `0` si ninguno (un recuento XPath nunca es negativo); `is_last_error` dice cuándo el propio XPath fue rechazado
`of_name (string as_xpath)` → `string`	El nombre de etiqueta del primer nodo coincidente. Vacío si ninguno
`of_pretty ( )` → `string`	El documento tal cual — construido o cargado, lo que devuelve `of_xml` — reindentado para su lectura. No se pierde nada: CDATA, comentarios, instrucciones de procesamiento y la declaración XML se conservan, y un elemento que contiene texto se escribe en una línea, tal cual. Vacío si no hay nada, o si un documento construido no está bien formado

Varios nodos, y el documento #

Miembro	Función
`of_get_values (string as_xpath, ref string as_values[])` → `long`	El contenido de texto de CADA nodo coincidente, en `as_values`; devuelve el recuento. Donde `of_get_value` solo devuelve el primero
`of_get_attrs (string as_xpath, string as_name, ref string as_values[])` → `long`	El valor del atributo `as_name` en CADA nodo coincidente (el id de cada fila); devuelve el recuento
`of_get_attr_names (string as_xpath, ref string as_names[])` → `long`	Los nombres de todos los atributos del primer nodo coincidente (enumeración); devuelve el recuento

Modificar un documento #

El lado de escritura cambia el árbol cargado en el sitio; of_xml devuelve el resultado. Cada una apunta al PRIMER nodo coincidente (salvo of_remove, que los toma todos), devuelve 0 al tener éxito, -4 si nada coincide o si el cambio se rechaza (is_last_error dice por qué), -5 con un argumento vacío, -2 si la página no respondió.

Miembro	Función
`of_set_value (string as_xpath, string as_text)` → `long`	Fija el texto del primer nodo coincidente (sus hijos se reemplazan)
`of_set_attr (string as_xpath, string as_name, string as_value)` → `long`	Fija (o agrega) un atributo en el primer nodo coincidente. Un nombre con prefijo (`xsi:type`) va al espacio de nombres que su prefijo tiene en ese nodo (o ligado con `of_register_namespace`); un prefijo no ligado en ninguna parte se rechaza (`-4`, `is_last_error`)
`of_remove_attr (string as_xpath, string as_name)` → `long`	Quita un atributo del primer nodo coincidente
`of_add_child (string as_xpath, string as_tag, string as_text)` → `long`	Añade un elemento hijo `<as_tag>as_text</as_tag>` bajo el primer nodo coincidente (el hijo hereda el espacio de nombres y el prefijo del padre; una etiqueta con prefijo `p:item` toma el espacio de nombres de su prefijo, o `-4` si no está ligado en ninguna parte). `-4` también cuando el nodo no puede tener hijos (un atributo, un texto) o la etiqueta no es un nombre válido
`of_add_xml (string as_xpath, string as_fragment)` → `long`	Injerta un fragmento XML ya formado (uno o varios elementos hermanos) bajo el primer nodo coincidente — lo que `of_add_child` no puede hacer, tomando solo una etiqueta y un texto. El fragmento debe estar bien formado; hereda los espacios de nombres vigentes en su destino, como `of_add_child` (`<line>` bajo `<order xmlns='urn:acme'>` está en `urn:acme`, `<s:Item/>` bajo un `s:Body` SOAP no declara nada)
`of_remove (string as_xpath)` → `long`	Quita TODOS los nodos coincidentes (una fila, una rama obsoleta, un atributo). Devuelve cuántos se quitaron realmente (`>= 0`; con `0`, `is_last_error` dice por qué), `-4` si no hay nada cargado, `-5` con un XPath vacío, `-2` si la página no respondió. El elemento raíz se queda: `of_clear` vacía un documento

Espacios de nombres #

Un XPath con prefijo (SOAP, una API empresarial) resuelve por sí solo un prefijo que el documento declara (xmlns:s="…", en cualquier elemento). ⚠️ La trampa más frecuente: el espacio de nombres POR DEFECTO. <order xmlns="urn:acme"><customer>… no tiene prefijo, y sin embargo /order/customer no coincide con NADA: XPath 1.0 no tiene espacio de nombres por defecto. Ligue un prefijo de su elección con of_register_namespace("a", "urn:acme") y escriba /a:order/a:customer. of_clear_namespaces olvida las ligaduras. No hay XSLT: Chromium lo retira del motor (transforme en el servidor o en PowerScript). No hay validación por esquema XSD: el motor no la tiene.

Miembro	Función
`of_register_namespace (string as_prefix, string as_uri)` → `long`	Liga un prefijo al URI de su espacio de nombres, para que un XPath con prefijo se resuelva. Devuelve `0`, `-5` con un prefijo o un URI vacío, `-2` si la página no respondió. Las ligaduras duran hasta `of_clear_namespaces` u `of_reset`
`of_clear_namespaces ( )` → `long`	Olvida todos los prefijos registrados: un prefijo que el documento no declara ya no coincide con nada mientras no se ligue. Devuelve `0`, `-2` si la página no respondió

// A SOAP response : the prefix declared by the document resolves on its own
lnv_xml.of_load(/*xml*/ ls_soap)
ls_ok = lnv_xml.of_get_value(/*xpath*/ "//s:Body/result/status")

// A DEFAULT namespace (xmlns="urn:acme") : bind a prefix of your choice
lnv_xml.of_load(/*xml*/ '<order xmlns="urn:acme"><customer>Ada</customer></order>')
lnv_xml.of_register_namespace(/*prefix*/ "a", /*uri*/ "urn:acme")
ls_name = lnv_xml.of_get_value(/*xpath*/ "/a:order/a:customer")   // Ada

// Mutate, then read the result back
lnv_xml.of_set_value(/*xpath*/ "/a:order/a:customer", /*text*/ "Grace")
lnv_xml.of_add_child(/*xpath*/ "/a:order", /*tag*/ "total", /*text*/ "690.50")

// Graft a whole fragment at once (of_add_child adds only one tag)
lnv_xml.of_add_xml(/*xpath*/ "/a:order", /*fragment*/ '<lines xmlns="urn:acme"><line sku="1">A</line><line sku="2">B</line></lines>')
ls_out = lnv_xml.of_xml()

La página oculta #

Miembro	Función
`of_open ( )` → `long`	Crea la página oculta (lado lectura). Opcional — la primera lectura lo hace. Devuelve el handle (`> 0`) o `-2` si no se pudo crear (`is_last_error` dice por qué)
`of_is_open ( )` → `boolean`	Verdadero en cuanto existe la página oculta
`of_close ( )`	Libera la página oculta. La construcción sigue sin ella, y un documento cargado no se pierde: se guarda como texto, y la lectura siguiente lo vuelve a cargar. Se hace por usted al destruir
`of_reset ( )`	Vuelta a los valores por defecto: el builder vaciado, el estado de lectura borrado

Alcance. El XML se lee mediante el motor (DOMParser, XPath): n_pbt_xml abre una página oculta en la primera lectura, a diferencia de json, que analiza en PowerScript puro. Para mostrar un XML como árbol plegable, vea xmltree.