Reference manual di GALATEO. 

A RISISTEMARE E INTEGRARE IN GALATEO

INFORMAZIONI GENERALI

Con IMPOSTAZIONI/ IMPOSTAZIONI GENERALI è possibile accedere alla dialogbox nelle IMPOSTAZIONI GENERALI, dove vengono configurati gli aspetti principali del report, si scelgono le stampanti , si determinano le misure e i margini, eccetera.

Con DATABASE/CONFIGURAZIONE COLLEGAMENTO A DATABASE si può collegare il report ad un database; driver può essere un ALIAS del BDE, oppure un driver ODBC.

Se come driver viene indicato un database SQL, non è necessario indicare una tavola, altrimenti il campo Tavola può contenere direttamente il nome di un file fisico (ad esempio un file DBF).

La struttura fondamentale di un report è il comando SQL di selezione dei dati. Se fai due click su un punto vuoto della finestra, si apre la dialogbox di gestione della sezione. Sulla scheda OPZIONI è possibile impostare parecchie utili opzioni sul comportamento della sezione, ma soprattutto, sulla scheda SQL, è possibile scrivere il comando SQL. Deve essere un comando SELECT che fa riferimento ad una o più tavole che fanno parte del database associato al report.

Non ci sono particolari problemi ad utilizzare comandi del tipo

SELECT * FROM .....

come pure va benissimo elencare i campi da selezionare

SELECT str_nome,str_codice FROM .....

Una volta eseguita l'associazione ad un database e definita l'istruzione SELECT, attraverso il comando DATABASE/ COLONNE DATABASE è possibile importare nel report le colonne del database.

LE SEZIONI

Un report è formato da una o piu' sezioni gerarchicamente nidificate. La prima sezione si chiama PRINCIPALE, le altre sezioni hanno nomi liberamente definibili.

A titolo di esempio, per la stampa di una fattura avremo probabilmente la sezione principale che conterrà l'intestazione della fattura, e una sottosezione contenente le voci della fattura.

Per inserire una nuova sezione usare il comando IMPOSTAZIONI/ CREA NUOVA SOTTO-SEZIONE.

Ogni sezione ha una istruzione SQL (salvo la sezione principale, che può anche non averla).

L'istruzione SQL di una sotto-sezione viene eseguita uno volta per ogni record contenuto nella sezione gerarchicamente

superiore. Ogni sottosezione viene stampata una volta per ogni record identificato dal suo comando SQL.

REFERENZIAZIONE DEGLI OGGETTI

Quasi ovunque, ove ha senso, è possibile referenziare il contenuto di un oggetto del report.

Ad esempio, nell'istruzione SQL di una sottosezione è possibile (ovviamente) riferirsi ai campi dell'istruzione SQL delle sezioni gerarchicamente superiori utilizzando la notazione

NOMESEZIONE.CAMPO

In altri contesti, e piu’ in generale, è possibile riferirsi al contenuto di un oggetto attraverso la notazione $NOMEOGGETTO. Ad esempio, l'eseguibile può passare informazioni sulla stampa da eseguire attraverso l'utilizzo dei parametri; per ordinare la stampa di una certa fattura, si potrà usare nel report l'istruzione SQL

SELECT * FROM fatture WHERE lo_key_fattura = $PARM_LO_KEY_FATTURA

e impostare a run-time (attraverso l'appropriata funzione) il valore del parametro PARM_LO_KEY_FATTURA al valore desiderato.

GLI OGGETTI DI GALATEO

Gli oggetti che è possibile utilizzare in Galateo sono: TESTI, BMP, LINEE e RETTANGOLI.

Per modificare le impostazioni di un oggetto è sufficiente fare un doppio click sull’oggetto stesso. E’ possibile passare da un oggetto all’altro con il tasto TAB.

Per spostare un oggetto selezionarlo e agire con le frecce. Per ridimensionare un oggetto selezionarlo, schiacciare il tasto shift ed agire sulle frecce. La pressione del tasto ctrl aumenta la velocità di spostamento/ ridimensionamento.

Per allineare più oggetti selezionarli tutti (tenendo premuto il tasto ctrl) e utilizzare gli appositi bottoni presenti sulla barra degli strumenti.

Gli oggetti di testo e le bitmap possiedono una modalità di visualizzazione che consente loro di essere visualizzati solo al momento desiderato. Attraverso il comando OGGETTI/ NON MOSTRARE OGGETTI NASCOSTI è possibile non far comparire, neppure a design time, gli oggetti marcati come nascosti. Per avere un elenco di tutti gli oggetti disponibili nella sezione selezionata è possibile utilizzare il comando OGGETTI/ ELENCO OGGETTI DELLA SEZIONE.

BMP, LINEE, RETTANGOLI

BMP, linee e rettangoli sono oggetti grafici su cui non molto vi è da dire.

GLI OGGETTI DI TESTO

I testi si dividono ulteriormente in tre TIPI DI OGGETTO (vedi dialog box che si apre un un doppioclick su un oggetto).

OGGETTI DI TESTO: TESTI (STRINGHE)

Gli oggetti di tipo TESTO contengono una qualunque stringa di testo.

OGGETTI DI TESTO: LE FORMULE

Gli oggetti di tipo FORMULA vengono calcolati in funzione di altri oggetti. Possono essere formule di tipo numerico oppure di tipo testo.

Per le formule numeriche valgono le normali regole di composizione delle principali operazioni: +, *, -, /, raggruppamento in parentesi. Esempio:

3 * (fl_importo_iva + 2500)

dove fl_importo_iva deve essere un oggetto del report.

Per le formule di tipo testo è possibile la sola operazione di concatenazione (operatore +); è possibile indicare testi costanti racchiusi tra coppie di virgolette (non apici!). Esempio:

"NOME: " + str_nome + ", COGNOME: " + str_cognome

dove str_nome e str_cognome sono oggetti del report.

Sia nelle formule di testo che in quelle numeriche è possibile referenziare liberamente gli altri oggetti contenuti nel report, a patto che siano di tipo compatibile con la formula. Eventuali indicazioni di arrotondamento di un oggetto contenuto in una formula vengono applicate prima di utilizzare il suo valore nella formula.

Nelle formule è possibile utilizzare le seguenti funzioni:

·         PAGINA() indica il numero di pagina in stampa

·         TOT_PAGINE() indica il numero totale di pagine del report

·         ORA() ora di stampa

·         DATA() data di stampa

·         ACAPO() interrompe il paragrafo corrente e obbliga ad andare a capo

·         LEN(stringa) rende la lunghezza dell'oggetto di testo passato come parametro

·         COPY(stringa,i_start,i_len) rende una stringa contenente al massimo I_LEN caratteri a partire dal carattere I_START; il primo carattere ha indice 1

·         MAIUSCOLO(stringa) rende il parametro tutto maiuscolo

·         MINUSCOLO(stringa) rende il parametro tutto minuscolo

·         TOGLIBLANKS(stringa) toglie dal parametro gli spazi iniziali e finali (non toglie gli eventuali spazi contenuti all'interno della stringa)

·         QUOTEDSTR() racchiude tra apici il parametro

·         STR2SQL() equivalente a QUOTEDSTR()

·         PUNTATO(numero) rende il numero con i punti di separazione delle migliaia

·         NUMERO(string)  converte la stringa in numero (se possibile)

·         STRING(numero) converte il numero in una stringa

·         MIN_2_HOURS(minuti) trasforma un valore espresso in minuti nel corrispondente valore espresso in ore; esempio: 255 diventa 4h 15’

·         ROUND(numero,precisione) arrotonda NUMERO a 10^-precisione. PRECISIONE può essere un numero positivo o negativo.

OGGETTI DI TESTO: LE VARIABILI

Gli oggetti di tipo VARIABILE sono destinati ad ospitare valori che derivano ‘dal mondo esterno’; a loro volta, possono essere di quattro tipi differenti.

·         COLONNA DATABASE: un campo del database; il campo deve esistere;

·         PARAMETRO: un valore impostabile runtime dall’eseguibile. Durante la preparazione del report, per effettuare prove di stampa dall’interno di Galateo, è possibile indicare il valore che il parametro deve assumere nella casella ‘valore di esempio’;

·         SQL GROUP FUNCTION: può contenere una funzione di SQL raggruppamento da applicarsi alla sezione gerarchicamente inferiore

·         SQL SYNTAX: può contenere una qualunque istruzione SQL; è necessario che l’istruzione restituisca una sola riga

I LEGAMI COMUNITARI

Attraverso la gestione dei LEGAMI COMUNITARI è possibile effettuare lo spostamento e il ridimensionamento collettivo di gruppi di campi che sono in relazione tra di loro.

PAGINE LOGICHE

Galateo è in grado di gestire reports costituiti da più pagine logiche differenti. Un report può essere costituito, ad esempio, dalla copertina, da una serie di documenti e da una pagina riassuntiva finale, ovvero da tre differenti tipi di pagina.

Per aggiungere pagine logiche aprire impostazioni/impostazioni generali, selezionare la scheda pagine logiche e indicare il numero totale di pagine logiche desiderato. Per passare da una pagina logica all’altra utilizzare l’apposito comando presente sulla barra degli strumenti.

CONDIVISIONE DI PAGINE LOGICHE FRA PIU’ REPORTS

Capita spesso di avere una serie di reports che hanno in comune alcune pagine logiche. Tipicamente, ad esempio, capita di avere diversi reports che utilizzano la stessa copertina, oppure la stessa pagina riassuntiva finale.

Galateo consente di condividere fra più reports una o più pagine logiche. In questo modo è possibile avere una sola copia della copertina, ad esempio, ed effettuare le eventuali modifiche una sola volta per tutti i reports.

Il comando impostazioni/pagina logica/esporta pagina logica consente di esportare la pagina logica corrente su un file esterno (con estensione GPL – Galateo Pagina Logica). Il comando impostazioni/pagina logica/imposta pagina logica corrente consente di indicare se la pagina logica corrente è residente (ovvero: è interna, di proprietà del report) o importata da un file esterno.

STAMPA/ANTEPRIMA DI STAMPA

Attraverso il comando stampa/stampa è possibile eseguire una stampa di prova direttamente da Galateo. Il report viene stampato utilizzando, ove possibile e necessario, i valori specificato nelle caselle ‘valore di esempio’ dei singoli oggetti. 

SCRIPTS PRE e POST ESECUZIONE STAMPA

Galateo ha la capacità di eseguire delle istruzioni SQL prima e/o dopo l’esecuzione della stampa. Vedi impostazioni/sql scripts. Ogni istruzione può contenere qualunque comando SQL o una chiamata ad una stored procedure. Per referenziare variabili o parametri in uno script scriverlo preceduto da un $ nel caso di script standard, oppure senza sintassi aggiuntiva se indicato come parametro di una stored procedure. 

FUNZIONI RUNTIME

Galateo mette a disposizione una serie di funzioni attraverso le quali l’eseguibile può governare la stampa. Per programmi scritti in Delphi vedere la unit PRINT_LINK fornita insieme al programma.

Segue un elenco delle funzioni disponibili.

function GAL_open_and_print_proc(father : TForm;str_db_alias : shortstring; str_caption,str_default_path,str_filename : shortstring;setup_proc : setup_procedure_type) : boolean;

apre ed esegue il report indicato;

STR_DB_ALIAS indica l’alias BDE da utilizzare nel collegamento a database;

STR_CAPTION è il titolo che compare nella finestra di anteprima del report;

STR_DEFAULT_PATH è il percorso default (if any) in cui GALATEO deve cercare il report se non lo trova nella directory corrente;

STR_FILENAME: nome del file contenente il report

SETUP_PROC: callback procedure richiamata per effettuare il setup del report

function GAL_open_and_print_method(father : TForm;             str_db_alias : shortstring; str_caption, str_default_path, str_filename : shortstring; setup_method : setup_method_type) : boolean;

funziona come la precedente OPEN_AND_PRINT_PROC, ma utilizza un method come callback, anziché una procedure

SETUP_METHOD: callback method richiamato per effettuare il setup del report

le funzioni sotto elencate possono essere richiamate solamente da SETUP_PROC oppure da SETUP_METHOD, e devono passare come parametro il valore I_JOB ricevuto

function GAL_get_last_error(i_job : longint) : shortstring;

rende una descrizione dell’ultimo errore rilevato;

function GAL_set_textvar_value(i_job : longint; str_name, str_value : shortstring; bo_must_exist : boolean) : boolean;

function GAL_set_string_value(i_job : longint;str_name,str_value : ansistring;bo_must_exist : boolean) : boolean;

function GAL_set_asciizvar_value(i_job : longint;str_name : shortstring;lp_value : pchar;bo_must_exist : boolean) : boolean;

function GAL_set_textvar_listvalue(i_job : longint; str_name : shortstring; tstr_list : TStrings; str_if_void : str_default_parm_type; bo_must_exist : boolean) : boolean;

function GAL_set_longint_value(i_job : longint;str_name : ansistring;lo_value : longint; bo_must_exist : boolean) : boolean;

function GAL_set_double_value(i_job : longint;str_name : ansistring;do_value : double; bo_must_exist : boolean) : boolean;

le funzioni sopra descritte servono per effettuare l’impostazione dei parametri del report; le funzioni rendono TRUE se hanno successo, ovvero se effettuano l’impostazione del parametro; se BO_MUST_EXISTS è TRUE, la funzione rende TRUE solo se il parametro esiste nel report, altrimenti rende TRUE anche se il parametro non esiste.

function GAL_genera_parm_protetto(str_parm : string) : string;  

funziona come le altre; il parametro non avrà problemi anche se contiene virgole o altri caratteri speciali

function GAL_set_option(i_job,i_page : longint;str_section : shortstring;i_option,i_value : longint) : boolean;

function GAL_set_obj_option(i_job : longint;str_obj_name : shortstring; i_option : longint;lo_value : longint;bo_must_exist : boolean) : boolean;

imposta l’opzione indicata al valore indicato; vedi print_link.pas; rendono TRUE in caso di successo, FALSE altrimenti.

procedure GAL_get_option(i_job,i_page : longint;str_section : shortstring;i_option) : longint;

Come GAL_SET_OPTION(), ma legge invece di scrivere; vedi print_link.pas.

I_PAGE e STR_SECTION devono essere valori validi ed esistenti. Il valore viene caricato su LO_VALUE; la funzione rende TRUE in caso di successo, FALSE in caso di errore.

function GAL_get_obj_option(i_job : longint;str_obj_name : shortstring;i_option,lo_value : longint; bo_must_exist : boolean) : longint;

Come GAL_SET_OBJ:OPTION(), ma legge invece di scrivere; vedi print_link.pas. L’oggetto STR_OBJ_NAME deve esistere a meno che BO_MUST_EXISTS non sia FALSE. Il valore viene caricato su LO_VALUE; la funzione rende TRUE in caso di successo, FALSE in caso di errore.

function GAL_exists_parm(i_job : longint;str_name : shortstring) : boolean;

rende TRUE se il parametro specificato esiste

function GAL_exists_section(i_job : longint;str_name : shortstring) : boolean;

rende TRUE se la sezione specificata esiste

function GAL_find_full_filename(str_default_path : string;var str_filename : string) : boolean;

carica su str_filename il nome completo di path del report; rende TRUE se il report esiste, FALSE altrimenti;

function GAL_edit_report(father : TForm;str_default_print_path,str_report : string) : boolean;

lancia GALATEO ed apre il report indicato; rende FALSE se non trova GALATEO o se non trova il report;

function GAL_browse_files(father : TForm;str_initial_dir : shortstring;var str_filename : shortstring) : boolean;

function GAL_browse_files_TField(father : TForm;str_initial_dir : shortstring;ff : TField) : boolean;

apre una finestra di selezione di un report; funzione utile, non necessaria

function set_universal_callback(setup_proc : setup_procedure_type) : boolean;

imposta una callback function che viene richiamata in occasione di tutte le stampe; è del tutto analoga  alla callback function specifica per ogni stampa, ma consente di indicare valori e comportamenti comuni a tutto il programma

function GAL_get_version : longint;

restituisce la versione di Galateo; prime due cifre esadecimali: major versione, ultime 2: minor version; 4 cifre piu’ significative: non utilizzate

function GAL_get_version_signature : string;

rende una stringa che identifica la versione di Galateo; da utilizzare nella about-box del programma per referenziare la versione di Galateo utilizzata; se Galateo viene utilizzato come programma free-ware è obbligatoria la presenza di una icona di Galateo.

ALTRE FUNZIONALITA’ DI GALATEO

Altre funzionalità supportate da GALATEO, ma non spiegate da questa guida di riferimento, sono:

Gestione Stored Procedures

Stampa di etichette (non supportata da tutte le versioni di Galateo)