Messaggi di errore e codici di uscita

Traduzione automatica provvisoria, non revisionata. In caso di dubbio, consultare la versione inglese, che fa fede.

I messaggi di errore di Kent sono un insieme breve e fisso. Ognuno indica il comando che lo ha prodotto, quindi un messaggio vi dice sia cosa è andato storto sia dove. Questa pagina li elenca tutti.

Kent scrive in inglese, quindi i messaggi qui sotto sono riportati esattamente come compaiono nel vostro terminale; è tradotta la spiegazione di ciascuno.

Codici di uscita

Non c'è un codice distinto per tipo di errore. In uno script, verificate il codice di uscita per decidere se il comando ha funzionato, e leggete il messaggio per scoprire perché non ha funzionato:

if ! kent info mydata.sqlite; then
    echo "could not report on the database" >&2
fi

Errori da riga di comando

Provengono dall'analisi della riga di comando, prima che venga aperto qualsiasi database. Ciascuno è seguito dall'elenco d'uso completo, lo stesso testo che stampa kent help.

$ kent
missing command
usage: kent help
usage: kent createdb <dbfilename>
...

$ kent merge mydata.sqlite
unknown command: merge
usage: kent help
usage: kent createdb <dbfilename>
...

$ kent info
wrong number of arguments
usage: kent info <dbfilename>

kent sqldump e kent archive sono le eccezioni: prendono opzioni anziché un database posizionale, quindi un database omesso viene segnalato come opzione mancante.

$ kent sqldump
missing required flag: --in
usage: kent sqldump --in <dbfilename> [--out <outfile>] [--schema-only]

$ kent archive --in mydata.sqlite
missing required flag: --out
usage: kent archive --in <dbfilename> --out <archive>

archive e restore richiedono entrambi --out, dove sqldump lo tratta come facoltativo. Uno zip non può essere scritto sullo standard output e un database non può esservi costruito, quindi nessuno dei due ha un valore predefinito su cui ripiegare.

Errori di file e di database

Ogni messaggio inizia con kent e il nome del comando.

Messaggio	Cosa significa
`kent createdb: NAME already exists`	Il file di destinazione è già lì. `createdb` non sovrascrive mai; rimuovete voi il file se intendevate sostituirlo.
`kent info: NAME does not exist`	Il percorso non c'è. Kent deliberatamente non lo crea. Lo stesso messaggio compare per `details`.
`kent info: failed to open database: …`	Il file esiste ma non è stato possibile aprirlo come database Cordelia: di solito perché non lo è, oppure perché il suo schema è più vecchio di quello che questa build accetta.
`kent info: failed to read schema version`	Il database si è aperto, ma non è stato possibile leggerne la versione dello schema.
`kent info: failed to list tables`	Il database si è aperto, ma non è stato possibile leggerne l'elenco delle tabelle.
`kent info: failed to count rows in NAME`	Non è stato possibile leggere il conteggio delle righe di una tabella specifica. La tabella indicata è quella che ha fallito.
`kent createdb: failed to create database`	Non è stato possibile creare il file: quasi sempre una directory mancante o un problema di permessi sul percorso di destinazione.
`kent createdb: failed to create tables`	Il file è stato creato ma non è stato possibile scrivervi dentro lo schema.
`kent sqldump: NAME does not exist`	Il percorso passato a `--in` non c'è. Come per gli altri comandi, Kent non lo crea.
`kent sqldump: refusing to write the export over its own source: NAME`	`--in` e `--out` indicano lo stesso file. Rifiutato prima che venga letto alcunché, anziché troncare il database che avevate chiesto di esportare.
`kent files: NAME does not exist`	Il percorso non c'è, e Kent non lo crea: si veda `files`.
`kent archive: NAME does not exist`	Il percorso passato a `--in` non c'è. Come per ogni altro comando, Kent non lo crea.
`kent archive: cannot create the archive NAME`	La destinazione passata a `--out` non è stato possibile aprirla in scrittura: quasi sempre una directory mancante o un problema di permessi.
`kent archive: cannot write NAME`	Non è stato possibile scrivere un file nella directory di preparazione accanto alla destinazione. Di solito un disco pieno: un archivio ha bisogno di spazio per sé e per il suo contenuto in preparazione allo stesso tempo, si veda `archive`.
`kent archive: cannot add NAME to the archive`	Non è stato possibile aggiungere allo zip un file in preparazione.
`kent archive: finalising the archive failed`	Non è stato possibile chiudere e completare lo zip. L'archivio parziale viene rimosso anziché lasciato lì.
`kent restore: NAME already exists`	Il database indicato da `--out` è già lì. `restore` non ne sovrascrive mai uno, la stessa regola che segue `createdb`.
`kent restore: NAME is not readable as a kent archive: …`	Il file non è uno zip, oppure non è stato possibile aprirlo. La ragione sottostante segue i due punti.
`kent restore: NAME is not a kent archive: it has no …`	È uno zip, ma gli manca il manifesto o lo schema che ogni archivio porta con sé.
`kent restore: this archive is format version N, but this build of kent understands version M at most`	L'archivio è stato scritto da un Kent più recente. Kent rifiuta anziché tirare a indovinare su un formato successivo a sé.
`kent restore: the archive's manifest lists table "NAME" but the archive has no …`	L'archivio è incompleto. Rifiutato anziché ripristinato in parte.
`kent restore: the archive's manifest claims N rows in "NAME" but it holds M`	L'archivio è in disaccordo con sé stesso, quindi è danneggiato o è stato costruito male.
`kent restore: the archive is inconsistent: its schema.sql stamps schema version N but its manifest says M`	Lo stesso, per la versione dello schema.

Dove un messaggio termina con i due punti, l'errore sottostante del database lo segue sulla stessa riga. Quel dettaglio finale proviene dal livello di accesso ai dati di Cordelia, quindi la stessa formulazione compare in Cordelia: si veda i messaggi di errore di Cordelia.

Il database precedente a questa build

Questo merita di essere segnalato perché la formulazione può sembrare corruzione quando non lo è:

$ kent info old.sqlite
kent info: failed to open database: This database uses an older schema and cannot be opened; version 2 is required. Create a new database and import your .FIT files again.
$ echo $?
1

Il file è integro. È stato semplicemente scritto da una Cordelia più vecchia di quella che questa build di Kent comprende, e viene rifiutato all'apertura anziché letto con uno schema che non gli corrisponde.

kent sqldump e kent archive sono i due comandi che non lo rifiutano. Leggere un database vecchio è esattamente ciò che si fa prima di migrarlo, quindi entrambi lo leggono comunque. sqldump lo dichiara sullo standard error; è un avviso, non un errore, e il codice di uscita è 0:

$ kent sqldump --in old.sqlite --out old.sql
kent sqldump: note: this database reports schema version 0, but this build of cordelia expects 2. Exporting it anyway.
$ echo $?
0

archive non stampa una nota del genere. Registra invece la versione di schema trovata nel manifest.json dell'archivio stesso, così l'informazione viaggia con l'archivio anziché scorrere via su un terminale.

Kent non ha alcun comando che migri sul posto un database vecchio. Leggerlo è l'input di una migrazione, non una migrazione in sé: si veda Esportare un database con sqldump e Archiviare un database con archive.

Errori interni non gestiti

Se qualcosa sfugge alla normale gestione degli errori di Kent, viene segnalato sullo standard error anziché sullo standard output, e il codice di uscita resta 1:

$ kent info /some/unreadable/path.sqlite
kent: filesystem error: ...

kent: unhandled exception of unknown type