Controllo versione dei documenti XML

Per supportare l'estendibilità nelle release future, le procedure memorizzate comuni dell'API SQL restituiscono documenti di output XML che includono informazioni sulla versione.

Ogni volta che la struttura di un documento di output XML cambia (ad esempio, quando un elemento viene aggiunto o rimosso), i livelli di versione vengono incrementati. Pertanto, una procedura potrebbe supportare diverse versioni del documento di output XML.

Le informazioni sulla versione nel documento XML sono espresse come coppie chiave - valore per la versione principale del tipo di documento e per la versione secondaria del tipo di documento. Ad esempio, un documento di output XML potrebbe definire le seguenti chiavi e valori in un elemento del dizionario:

   <key>Document Type Name</key><string>Data Server Configuration Output</string>
   <key>Document Type Major Version</key><integer>2</integer>
   <key>Document Type Minor Version</key><integer>0</integer>

Quando si richiama la procedura, specificare la versione principale e la versione secondaria del documento XML che si desidera restituire. Il contenuto del documento di output XML varia in base al valore specificato.

Ad esempio, la procedura GET_CONFIG richiama i parametri di configurazione del database e del gestore database impostati per una particolare istanza. Quando questa procedura viene richiamata con major_version 2 e minor_version 0, restituisce un documento XML contenente parametri di configurazione raggruppati in categorie. Tuttavia, quando la stessa procedura viene richiamata con major_version 1 e minor_version 0, restituisce un documento XML che contiene parametri di configurazione, ma non sono raggruppati in categorie.

Allo stesso modo, la procedura GET_MESSAGE richiama il testo del messaggio e SQLSTATE per un SQLCODE specificato. Quando questa procedura viene richiamata con major_version 2 e minor_version 0, restituisce un documento XML che contiene il messaggio di testo breve, il messaggio di testo lungo e SQLSTATE per l'SQLCODE corrispondente. Tuttavia, quando la stessa procedura viene richiamata con major_version 1 e minor_version 0, restituisce un documento XML che contiene solo il messaggio di testo breve e SQLSTATE. Il messaggio di testo lungo non è disponibile nella versione 1 del documento.

Per determinare le versioni dei documenti più elevate supportate per una procedura, specificare NULL per versione_maggiore, versione_minoree tutti gli altri parametri di input. La procedura restituisce le versioni del documento supportate più elevate come valori nei parametri di output versione_maggiore e versione_minore e imposta i parametri di output xml_output e xml_message su NULL.

Se si specificano valori non null per versione_maggiore e versione_minore, è necessario specificare le versioni del documento supportate oppure la procedura genera un errore (-20457) per indicare che la procedura ha rilevato una versione non supportata.

I documenti di input XML possono facoltativamente includere valori per la versione principale del tipo di documento e per la versione secondaria del tipo di documento. Se questi valori vengono specificati nel documento di input XML, i valori passati per versione_principale e versione_minore nella chiamata della procedura devono corrispondere esattamente ai valori specificati nel documento XML, altrimenti la procedura genera un errore (+ 20458). Questo comportamento garantisce che il chiamante non specifichi una versione non supportata del documento di input XML.