Information Retrieval

Transcript

1 I C A R O/400 Information Retrieval IBM Application System/400 Guida per il programmatore (ICARO, IcaroPc, IcaNet) Versione 4.0 Marzo 2004

2

3 Gaetano SAVONA Versione Marzo 2004 SAP sas Via dei Nebrodi, 55 Palermo (Italy)

4

5 Informazioni su questo manuale Questo manuale illustra come installare, avviare e lavorare con ICARO/400 per risolvere la indicizzazione totale di testi liberi non strutturati su IBM AS/400. Questo manuale è stato realizzato da SAP sas - Italy. Il copyright è della SAP sas e non ha alcun legame o obbligazione con la IBM company. I seguenti termini o logo, usati in questo manuale sono marchi registrati della IBM International Business Machine corporation: IBM ImagePlus AS/400 OS/2 PS/2 Personal System/2 SAA OfficeVision/ ICARO/400 è un prodotto della SAP sas. Dr. Gaetano Savona; Per ulteriori informazioni contattare TIS Text Information Systems, Svizzera - centro internazionale di supporto e distribuzione del prodotto ICARO: T.I.S SA, Kybourg 1, CH 1700, Fribourg Tel. (00 41 ) fax (00 32) oppure SAP sas., via dei Nebrodi 55, Palermo (Italy), Tel. (091) , Fax (091) [email protected] sito A CHI SI RIVOLGE QUESTO MANUALE Questo manuale è indirizzato all'amministratore delle banche dati, ai progettisti delle banche dati ed ai programmatori per lo sviluppo di procedure di backup e restore automatizzate, per la realizzazione di interfacce utente per facilitare l'interrogazione, per integrare banche dati ed applicazioni utente con banche dati ICARO, per realizzare interfacce web ed integrazioni con oggetti multimediali. I gestori di banche dati ed i programmatori ICARO devono avere una conoscenza di base dell'application System/400 (IBM AS/400) e delle procedure per la sicurezza dell'as/400. ICARO Guida Programmatore i

6 Informazioni collegate On Line e stampate Il Programmatore e l'amministratore troverà in questo manuale ed anche nella Guida 'on line' le istruzioni fondamentali per realizzare applicazioni di information retrieval personalizzate e per integrare applicazioni utente con ICARO utilizzando le A.P.I. (Application Programming Interface) qui descritte. Inoltre, il programmatore dovrebbe leggere il manuale "ICARO: Guida per l'utente" per sapere come installare l'applicazione ICARO, definire una banca dati, e gestire e ricercare documenti. Altre informazioni si trovano in una banca dati ICARO on line o sul nastro del prodotto in licenza ICARO. Altri manuali SAP/TIS ed IBM contengono informazioni correlate: TIS ICARO-ImagePlus Interface - administration TISDOCi04 TIS ICARO-ImagePlus Interface - User's guide TISDOCi05 SAA ImagePlus/400 System Administrator's Guide SC SAA ImagePlus/400 General information manual GC SAA ImagePlus/400 Planning and installation Guide GC SAA ImagePlus Workfolder application facility/400 Message and codes SC SAA ImagePlus Workfolder application facility/400 Programming interfaces SC PS/2 ImagePlus Workstation Program Operation Guide SC SAA ImagePlus/400 Workstation Program/2 Programmers Guide ICARO - Guida utente ii ICARO Guida Programmatore

7 I n d i c e Introduzione I-1 Capitolo 1. Richiamo delle applicazioni ICARO Iniziare una sessione ICARO, creazione ambiente di lavoro (CRTAUTUSE) e chiusura corretta della sessione Richiamo del video di logon Richiamo del Menu Principale Richiamo del Menu DEFICA (Definire ICARO) Richiamo del Menu Gestione tabelle Richiamo del Menu Gestione del Dizionario Richiamo del Menu Funzioni Operative Capitolo 2. Richiamo delle funzioni di ICARO Aprire la sessione ICARO Richiamo menu gestione documenti: TEXGES Richiamo funzione gestione di un documento: TEXGESDOC Richiamo funzione interrogazione documenti: TEXINQ Creazione procedure per l'amministrazione delle banche dati Richiamare la riorganizzazione della banca dati: TXTRIORGA. 2-5 Salvataggio di una banca dati: SAVEDBICA Salvataggio di tutte le banche dati: SAVEDB Salvataggio degli oggetti multimediali di una banca dati SAVDBIFS. 2-7 Salvataggio procedure.exe della directory IFS. SAVIFS Ripristinare una banca dati: RSTDBICA Ripristino degli oggetti multimediali di una banca dati RSTDBIFS. 2-9 Ripristino procedure.exe delle directory IFS. RSTIFS 2.9 Ricostruzione (totale) indici banca dati: SUBIDXTOT/IDXTOT Ricostruzione (parziale) indici banca dati: SUBIDXWOR/IDXWOR Aggiornamento indici: SUBAGDOC/TEXUPDOC Emissione su stampa o su file del dizionario TEXT08Px ICARO Guida Programmatore iii

8 Capitolo 3. Gestione documenti Struttura dei file di ICARO: File TEXRAAA e TEXDAAA File di lavoro TEWRAAA e TEWDAAA File assegnazione numero identificativo:texaret e TEXAGAN Selezione di un documento da revisionare: TEXT Assegna o proteggi il contenuto di un campo: EXTAUT Definire un help sui campi formattati: EXTHF Definire un help sui singoli paragrafi: EXTHP Routine controllo contenuto dei campi formattati: EXTCOF Routine controllo contenuto dei paragrafi: EXTCOP Routine controllo cancellazione documento: EXTDEL Routine di EXIT nella gestione di docum.: il tasto F20 EXTGES) 3-14 Routine dopo l'aggiornamento del documento: EXTCLDOC 3-15 Modifica videata/program di gestione campi formattati: TEZAAA 3-16 Importare docum.office (.doc,.html, rft, txt) EXTIMPO/EXTIMPO Esportare verso l office (.doc,.rft,.html,.txt) EXTEXPO 3-19 Tre metodi per esportare documenti ICARO a office Importare un membro di file sorgente: TEXT15T Importare un documento office in un file ICARO: TEXT16T Capitolo 4. Leggere un campo o paragrafo Lettura di un campo formattato: TEWSFFF Lettura campo variabile (2000 o 9999 car.): TEWSPPP/TEWSPP9 4-2 Lettura campo variabile (senza limite di lunghezza): TEWS Lettura delle righe di intestazione di un paragrafo RTVINPAR. 4-4 Invertire un campo arabo: ARAB iv ICARO Guida Programmatore

9 Capitolo 5. Altre routine Controllo termini di un campo o di righe di testo TEXT21R Accesso a tabelle di riferimento ICARO: TEXT Duplica una tabella di riferimento ICARO: DUPTAB Accesso alla lista di banche dati autorizzate: TEX05A Reperire il codice di lingua di un utente: RTVLANGU Allocare /bloccare una banca dati: LCKDB Verifica dei lavori attivi in una banca dati: TESTJOB Rilascia le librerie di lavoro utente WICA000xxx: INQDLTSP Visualizzazione di un membro di file sorgente: TEXMSGP Modifica righe membro source TXTTOPCX Testare l ambiente di lavoro (batch/interattivo) TYPEJOB Marginare un testo : TEXT13CB Capitolo 6. Caricare/scaricare una banca dati a) caricare documenti via batch ADDDOC/ADDDOCB. 6-1 Formato file di input (TEWLOG) b) Reperire documenti RTVDOC/RTVDOCB. 6-7 Formato di file di output (TEWLOG) Applicazioni Recupero/svuotamento/caricamento documenti Banche dati parallele Recuperare/unire informazioni esterne Creare una sotto banca dati Modificare globalmente campi/paragrafi specifici Capitolo 7. Programma guida: TEXBAT Il sorgente TEXBAT Routine SELOP Routine WRKDOC Routine GESDOC Routine di RESET Routine AGGDOC ICARO Guida Programmatore v

10 Capitolo 8. Autorizzazioni Assegnare ad un utente un profilo di riferimento: TXADUP Modifica, per un profilo, delle limitazioni di accesso a documenti (CHGQRYLMT) Capitolo 9. Interrogazione su banche dati Quadro generale Esempio dell'interfaccia di interrogazione. (TURBO INQDIR) Esempio di exit per banca dati (programma EXTINQ Descrizione delle routine API Apertura della sessione di interrogazione INQOPNSP. 9-3 Attivazione banca dati: INQSETDB. 9-3 Formulazione interattiva della domanda: INQR Programma per la formulazione della domanda: PGMxxx Formulazione di domanda in modo batch INQSNQRY. 9-7 Controllo domanda: INQCHK Attivazione formato visualizzazione/stampa TEXINQF/INQSETFO 9-10 Reperire il risultato della domanda - RTVRSL Visualizza lista delle ricorrenze dell'ultima domanda: INQDSPOC Selezione del tipo di output del risultato: INQDSPOP 9-12 Visualizzazione dei documenti estratti: INQDSPDO Visualizza lista abbreviata documenti: INQDSPLI/INQDSPLX Stampa dei documenti estratti: INQSNPRT Procedura di estrazione dei documenti: INQEXCES Routine di EXIT di visualizzazione documenti: EXTINQ Visualiz. documento con numero. di riferimento: DSPDOC Chiusura di una sessione di interrogazione INQDLT Esempi di navigazione ipertestuali Modifica una procedura di estrazione per aggiornare direttamente un data base utente vi ICARO Guida Programmatore

11 Altre routine Reperire le banche dati attive per l interrogazione e l ultimo numero di livello RTVOPNDB Reperire alcuni termini di una banca dati RTVTERM Capitolo 10. Ricorsività di programmi La routine CRTRCR Capitolo 11. Esempi di estrazione/trasferimento dati Istogramma di frequenza (TEXDIAALF TEXDIANUM) Trasferire su PC il file risultato di una procedura di estrazione. EXTEXPD Realizzare prospetti con totali o calcoli dopo l'interrogazione Converti un membro source/text Management in RTF, HTML o ASCII con output in un membro source e in un file system AS.....TXTTOPC Converti ed esporta un membro source/text Management in RTF, HTML o ASCII in un file system AS, server di rete o pc locale DOCTOPC Importa e converti un documento office.doc rtf htm in un membro di file source. DOCTOAS Trasferim. da server PC a IFS AS400 e viceversa PCTOPC 11-9 Convertire un documento ICARO, nel formato di visualizzazione, in un membro di file source. DOCTOMBR Leggere il contenuto di una DIR e trasferirla in un membro source RTVDIR Funzioni windows (.exe.bat) utilizzabili dall utente BROWSER.bat visualizzazione documenti e oggetti multimediali COPIA.exe copia oggetti documenti e multimediali EXEWORD.bat lancio del word di uno specifico docum TXTCONV.exe e LISTACONV. Exe conversione documenti SCAN2PDF.exe scansione documenti in formato pdf Capitolo 12. Paragrafi in modalità protetta (campi formatati) Introduzione Regole di codifica dei paragrafi Generazione dei programmi per la gestione in modalità protetta ) Compilazione dei paragrafi ) Assegnazione attributi di controllo ) Crea un testo di help per il paragrafo ) Personalizzazioni del display file e dei programmi generati Immissione dei dati e controlli nei paragrafi in modalità protetta Eliminare la gestione protetta per un paragrafo Routine di lettura o aggiornamento di un campo formattato di un ICARO Guida Programmatore vii

12 paragrafo a gestione protetta TEWSXXX viii ICARO Guida Programmatore

13 Capitolo 13. Immagini / Telex / Fax Esempi forniti con ICARO Metodo generale per lo scanner Metodo generale per la visualizzazione Prove di TEST con le banche dati dimostrative a) Visualizzazione immagini e file multimediali b) Acquisizione Immagini (scansione) L'integrazione ImagePlus Visualizza immagini di documenti ICARO in pagine Html Integrazione Telex Capitolo 14. Ottimizzazione: indicizzazione/spazio disco Per ottimizzare l'attività di indicizzazione Per ottimizzare lo spazio su disco Capitolo 15. ICAROPc/ICANET note tecniche Le API AS/400 per personalizzare box WINDOWS o pagine HTML Il Flusso dell applicazione ICAROPc/ICANET la procedura di Exit call ICALOGON Invio di una box o menu iniziale da host -MEXTINQ la funzione STRBOX Righe di intestazione box Righe di testo e campi di input Definizione dei bottoni Attributi campi di input Box in sovrapposizione o in sostituzione -Liste record Lista delle librerie la funzione STRQRY la funzione di navigazione il pgm PEXTINQ la procedura di Exit call ICALOGOF Esempi di interrogazione diretta con link da Pagine HTML ICARO Guida Programmatore ix

14 Capitolo 16 La libreria ICAWIN: API per Windows per l interfaccia grafica ICAROPc Informazioni sulla libreria ICAWin Descrizione dell'ambiente Le strutture dati di Icawin Le funzioni di ICAWin ICA_Init ICA_RMsg ICA_RTxt ICA_LDBA ICA_RtFdDB ICA_RtTbLT ICA_RtTbLD ICA_RtvDiz ICA_SndQry ICA_RtvOcc ICA_DSPLI ICA_DSPDO ICA_RtvNav ICA_Call ICA_End L interfaccia di accesso ai programmi esterni Capitolo 17 L interfaccia INTERNET Informazioni sui moduli IcaNET e IcaBWS Il modulo ICANET Descrizione dell'ambiente Le variabili di inizializzazione di IcaNet11 ed il file dei messaggi IcaNet11.str Il file di accounting Account.ica I programmi di IcaNet INLogon.exe INIProc.exe INLMsg.exe INSelDB.exe INNote.exe x ICARO Guida Programmatore

15 INQuery.exe INQryRes.exe INOcc.exe INOption.exe La libreria statica CGITools.obj La libreria statica ICAPage.obj Il modulo IcaBWS Descrizione dell'ambiente IcaBWS Le sezioni del file SessionF.ica General Logon InitProc UserMessage DBNote DBSelect TableList Table Dictionary Query QueryResult Occurence Navigation NavigationMenu Logoff ICARO Guida Programmatore xi

16

17 INTRODUZIONE. L Ambiente operativo Per una buona operatività del software è necessario quanto segue: che il sottosistema QICARO sia fatto partire preferibilmente alle IPL di sistema; aggiungere, a tal fine, nel programma di start il comando: STRSBS ICA$BAS/QICARO. RLSJOBQ ICA$BAS/QICAIMM RLSJOBQ ICA$BAS/ICARO RLSJOBQ ICA$BAS/ICARO1 All avvio del sottosistema QICARO viene lanciato automaticamente il lavoro RSTSPC che provvede a chiudere eventuali aree di lavoro WICA000xxx connessi a lavori chiusi in modo anomalo. Che non vengano rimosse dalla lista delle librerie, nelle funzioni di exit controllate dall utente, le librerie di lavoro che il software ICARO o le sue routine aggiungono nella lista delle librerie. Le librerie utilizzate dal software sono generalmente ICA$BAS (contenente programmi e files applicativi), WICA000xxx (libreria di lavoro assegnata alla sessione utente) e ICA$xxx (con xxx tra 001 e librerie contenenti I files delle banche dati). NOTE SULLE AREE DI LAVORO. Per ciascuna sessione di lavoro ICARO viene associato a ciascun terminale o lavoro una libreria contenete I files temporanei per l interrogazione di banche dati o per processi di gestione. Nel sistema verranno create un certo numero di librerie di lavoro denominate WICA000xxx (con xxx tra 001 e 330) come duplica della libreria modello WICA$W. Il numero di librerie precreate sono corrispondenti al numero che l utente ha impostato nel menu di definizione ICARO opzione 10 (livello medio di attività). Questo numero dovrebbe essere corrispondente al numero massimo di sessioni (utenti) CONTEMPORANEAMENTE attivi. ICARO Guida Programmatore I - 1 Introduzione

18 L associazione terminale - area di lavoro viene effettuata dalla procedura CRTAUTUSE che assegna la prima libreria WICA000xxx disponibile al terminale che ha iniziato la sessione. Il programmatore deve quindi curare: di immettere nei propri programmi o Menu che utilizzeranno Api o funzioni ICARO, il richiamo iniziale della procedura CALL ICA$BAS/CRTAUTUSE; di immettere nei propri programmi, prima del comando SIGNOFF, il richiamo della procedura di chiusura della sessione ICARO: CALL ICA$BAS/INQDLTSP ( ). Questa procedura renderà disponibile la libreria di lavoro WICA000xxx per altri utenti ATTENZIONE: La procedura INQDLTSP deve essere richiamata esclusivamente prima del comando SIGNOFF. Difatti, l esecuzione di tale procedura non produrrà alcuna disallocazione dell area WICA000xxx se il JOB risulterà attivo. Se il programmatore non provvederà a rilasciare le aree di lavoro per le sessioni di terminali che chiudono con SIGNOFF è probabile che in breve si esauriranno le librerie di lavoro WICA000xxx disponibili. In questo caso, automaticamente verrà avviato il lavoro INQRSTSP che provvederà a forzare la chiusura di quelle sessioni non più attive nel sistema. Viceversa, se il numero di sessioni ICARO contemporaneamente aperte supera il valore impostato dall utente, ICARO provvede a creare altre librerie di lavoro WICA000xxx (da 001 a massimo 330) e ad estendere il valore massimo impostato dall utente. Se le api o funzioni scritte dall utente sono eseguite all interno di uno dei menu ICARO (TEXMAN, TEXMAN2, DEFICA, RGZICA) non necessita avviare la procedura CRTAUTUSE essendo questa automaticamente avviata da questi menu. Se i menu ICARO (TEXMAN TEXMAN2 DEFICA o RGZICA) sono richiamati con lo switch U8 impostato a 0 non necessita eseguire alcuna procedura INQDLTSP in quanto i suddetti menu, prima del signoff, provvederanno ad eseguire la procedura di disallocazione dell area di lavoro. Al contrario, se da un menu utente si richiama uno dei menu ICARO con lo switch U8 impostato al valore 1 o una funzione di interrorrogazione, occorrerà, NEL PROGRAMMA O MENU UTENTE, prima del SIGNOFF (QUINDI COME ULTIMA ISTRUZIONE), immettere il comando CALL ICA$BAS/INQDLTSP ( ) (vedere la routine INQDLTSP).. Introduzione I - 2 ICARO Guida Utente

19 Capitolo 1. Richiamo delle applicazioni ICARO Iniziare una sessione ICARO (creazione ambiente di lavoro): CRTAUTUSE Per avviare una sessione ICARO prima del richiamo di una qualsiasi delle API ICARO o una delle funzioni ICARO, è necessario creare l ambiente di lavoro associata alla sessione di lavoro con il seguente comando: CALL ICA$BAS/CRTAUTUSE Con questo comando verrà eseguito: la creazione della libreria temporanea WICA000XXX (XXX tra ) associata al al lavoro. Questa libreria è una duplica della libreria modello WICA$W contenente I files di lavoro; il comando WRKLIB WICA* consente di visualizzare le librerie di lavoro WICA000xxx utilizzate. la creazione dell'user space SPICA in QTEMP relativa alle autorizzazioni concesse all utente; la creazione in QTEMP di una data area WRKICA contenente, nei primi 10 caratteri il nome della libreria di lavoro assegnata al job (WICA000xxx). L'ambiente di lavoro per una sessione utente rimarrà aperta, fino a che l'utente, prima del SIGNOFF del terminale o della fine del job non avvia il comando di chiusura e rilascio CALL ICA$BAS/INQDLTSP ( ). Eccezione: Se un utente inizia a lavorare con ICARO richiamando i menu di ICARO TEXMAN, TEXMAN2, DEFICA o RGZICA, il comando CRTAUTUSE è richiamato implicitamente dai menu. Chiudere una sessione / rimozione dell'ambiente di lavoro Un ambiente di lavoro è chiuso e rilasciato (disponibile così per un altro utente) dalla procedura INQDLTSP. Prima del rilascio della libreria temporanea WICA000XXX, i files relativi al giornale delle interrogazioni effettuate dall'utente (INQD e INQR) verranno aggiunti ai files del giornale generale delle interrogazioni (INQD$ e INQR$) in ICA$BAS. La procedura INQDLTSP è sottomessa nei seguenti casi: - Viene richiamata da un applicazione utente; - Dopo la chiusura di uno dei menu ICARO (TEXMAN, TEXMAN2, RGZICA, DEFICA) richiamato con il jobswitch impostato a Alla partenza del sottosistema QICARO per ciascun lavoro terminato. - Attraverso la procedura TXTRIORGA. ICARO Guida programmatore 1-1 Richiamo Applicazioni

20 Richiamo del video di logon di ICARO Per richiamare il menu iniziale eseguire: CHGJOB SWS(' ') CHGJOB SWS(' ') CALL ICA$BAS/TEXMAN oppure Nel richiamare TEXMAN, il valore SWS ' ' pone la sessione terminale in stato di SIGNOFF quando l'utente esce da ICARO. Con il valore ' ' l'utente ritornerà al programma o menu chiamante o alla videata da cui ICARO è stato richiamato. Se l utente utilizza delle interfacce grafiche e desidera non ricevere i messaggi di attesa (finestre senza risposta, ad esempio Attendere ) può mettere in ON anche lo SWS sette prima di chiamare il menu; in tal modo i messaggi del tipo Attendere, lavoro in esecuzione non verranno inviati. Exit utente - Exit1 - dal video di logon di ICARO Nome del programma: CAMERA Parametri: nessuno Dal video di logon di ICARO, si può richiamare l'exit1 (programma CAMERA) mediante l'opzione 3. La descrizione dell'opzione 3 sulla videata di Logon può essere modificata o personalizzata dal gestore del prodotto in ognuna delle lingue previste (menu DEFICA opzione 1, definizione prodotto ICARO --> opzione 4, modifica descrizione richiamo menu utente). Se la descrizione dell'opzione 3 è rimossa, non sarà mostrata l'opzione 3 nel video di Logon. L'opzione 3 è controllata dall'icaro security. Con l'exit1 (richiamo du un programma o menu di nome CAMERA scritto dall'utente) l'utente può accedere ad un suo programma per l'accesso a banche dati esterne, videate definite per l'utente o altre applicazioni. Richiamo Applicazioni 1-2 ICARO Guida Programmatore

21 Richiamo del menu principale ICARO Per richiamare il menu iniziale eseguire: CHGJOB SWS(' ') CHGJOB SWS(' ') CALL ICA$BAS/TEXMAN2 oppure Nel richiamare TEXMAN2, il valore SWS ' ' pone la sessione del terminale in stato di SIGNOFF quando l'utente esce da ICARO. Con il valore SWS ' ' l'utente ritornerà al programma o menu chiamante o alla videata da cui ICARO è stato richiamato. Exit utente - Exit2 - dal menu principale di ICARO Nome del programma: MENUUTE Parametri: nessuno Dal menu principale di ICARO, si può richiamare un Exit (programma MENUUTE) mediante l'opzione 9. La descrizione dell'opzione 9 del menu principale può essere modificata e personalizzata dal gestore del prodotto in tutte le lingue previste dal prodotto (menu DEFICA opzione 1, definizione prodotto ICARO --> opzione 4 modifica descrizione richiamo menu utente). Se la descrizione dell'opzione 9 è rimossa, non sarà visibile sul menu principale. L'opzione 9 è controllata dall'icaro security. Con l'exit2 (richiamo del programma MENUUTE scritto dall'utente) l'utente può accedere ad un suo programma o menu per l'accesso a banche dati esterne, videate definite per l'utente o altre applicazioni. Richiamare il menu ICARO DEFICA (Definire ICARO) Per richiamare il menu (corrispondente all'opzione 7 del menu Principale) eseguire: CHGJOB SWS(' ') CHGJOB SWS(' ') CALL ICA$BAS/DEFICA oppure Nel richiamare DEFICA, il valore SWS ' ' pone la sessione terminale in stato di SIGNOFF quando l'utente esce da ICARO. Con il valore SWS ' ' l'utente ritornerà al programma o menu chiamante o alla videata da cui il menu è stato richiamato. ICARO Guida programmatore 1-3 Richiamo Applicazioni

22 Richiamare il menu ICARO RGZICA (Gestione operativa delle banche dati) Per richiamare il menu (corrispondente all'opzione 8 del menu Principale) eseguire: CHGJOB SWS(' ') CHGJOB SWS(' ') CALL ICA$BAS/RGZICA oppure Nel richiamare RGZICA, il valore SWS ' ' pone la sessione terminale in stato di SIGNOFF quando si lascia ICARO. Con il valore ' ' l'utente ritornerà al programma o menu chiamante o alla videata da cui il menù è stato richiamato. Richiamare il menu ICARO "Gestione tabelle" Per richiamare il menu (corrispondente all'opzione 3 del menu Principale) eseguire, in ambiente interattivo: (l'esecuzione del comando CRTAUTUSE deve essere stato avviato almeno una volta nella sessione): CALL ICA$BAS/TEXTAB PARM(&CODDB) (se le tabelle di riferimento devono essere richiamate da un programma) oppure CALL ICA$BAS/TEXTAB PARM(X'yyyF') (dove yyy è 000 oppure un codice valido di banca dati) se le tabelle di riferimento devono essere richiamate dalla linea di comando)... CHGLIB CURLIB(*CRTDFT) parametri: &CODDB Tipo: *DEC Len: 3 è un parametro numerico di 3 cifre inizializzato a 0 (zero) se si vuole mostrare la lista delle banche dati autorizzate o con un codice esistente di banca dati per mostrare il menu per la specifica banca dati. Richiamo Applicazioni 1-4 ICARO Guida Programmatore

23 Richiamare il menu ICARO "Gestione del dizionario ICARO": Per richiamare il menu (corrispondente all'opzione 5 del menu Principale) eseguire, in ambiente interattivo: (l'esecuzione del comando CRTAUTUSE deve essere stato avviato almeno una volta nella sessione): CALL ICA$BAS/TEXVCB PARM(&CODDB) (se la gestione del dizionario deve essere richiamata da un programma) oppure CALL ICA$BAS/TEXVCB PARM(X'yyyF') (dove yyy è 000 oppure un codice valido di banca dati) se la gestione del dizionario deve essere richiamato da una linea di comando... CHGLIB CURLIB(*CRTDFT) parametri: &CODDB Tipo: *DEC Len: 3 è un parametro numerico di 3 cifre inizializzato a 0 (zero) se si vuole mostrare la lista delle banche dati autorizzate o con un codice esistente di banca dati per mostrare il menu per la specifica banca dati. Richiamo del menu ICARO "Funzioni operative" per il controllo delle stampe Per richiamare il menu (corrispondente all'opzione F6 del menu Principale) eseguire, in ambiente interattivo:... CALL ICA$BAS/TEXOPE RMVLIBLE ICA$BAS ICARO Guida programmatore 1-5 Richiamo Applicazioni

24 Pagina vuota Richiamo Applicazioni 1-6 ICARO Guida Programmatore

25 Capitolo 2. Richiamo delle funzioni di ICARO (Richiamo delle funzioni di ICARO da un'altra applicazione o da un interfaccia utente speciale) Aprire/chiudere una sessione di ICARO/Creare l'ambiente di lavoro Prima di richiamare una qualsiasi delle API ICARO o una delle funzioni esterne ad ICARO, per es. da un applicazione dell'utente, deve essere aperta una sessione di ICARO con il seguente comando: CALL ICA$BAS/CRTAUTUSE Vedi capitolo 1 per le note su questo comando. Richiamo del menu di gestione documenti (interattivo) : TEXGES Dopo aver aperto la sessione di ICARO con il comando CRTAUTUSE, per richiamare, da un proprio menu o da un programma utente, la funzione di gestione documenti (opzione 1 del menu) eseguire i seguenti comandi: CALL ICA$BAS/TEXGES PARM(&DBNBR) (se il programma deve essere richiamato da programma utente) oppure (CL o interattivamente): CALL ICA$BAS/TEXGES PARM(X'yyyF') (dove yyy è ØØØ o un codice valido di banca dati) per richiamare il programma da una linea di comando). Parametri: &DBNR Tipo: *DEC Lung: 3 è un parametro numerico di 3 cifre inizializzato a Ø (zero) per mostrare la lista delle banche dati autorizzate all'utente o con un codice esistente di banca dati di cui avviare la gestione dei documenti. esempio: CALL ICA$BAS/TEXGES PARM(X'ØØØF') (per visualizzare e selezionare dalla lista di banche dati autorizzate) CALL ICA$BAS/TEXGES PARM(X'ØØ5F') (per accedere direttamente alla 'gestione documenti' per la banca dati ØØ5.) ICARO Guida programmatore 2-1 Richiamo Funzioni

26 Richiamo della funzione di gestione di un documento: TEXGESDOC Per avviare l inserimento o revisione di un documento eseguire, dopo CRTAUTUSE: CALL ICA$BAS/TEXGESDOC (&DBNR &TOP &DOC &RTNCDE) Parametri: &DBNR Tipo: *DEC Lung: 3 codice della banca dati &TOP *CHAR 1 vale 1 per nuovo documento, 2 per revisone 3 per annullamento, 4 per visualizzare documenti in attesa di aggiornamento. &DOC *DEC 7 Riferimento ced del documento. &RTNCDE *CHAR 1 Codice di ritorno: V Vincolo su prodotto, banca dati o documento U La CURLIB è in conflitto con la banca dati selezionata M E' stato raggiunto il numero massimo di utenti ammessi per lavorare con documenti (vedi le definizioni generali della banca dati) C La banca dati deve essere compilata o ricompilata. T La precedente richiesta di gestione documenti è terminata in modo anomalo (è stata interrotta), i parametri correnti (&TOP &NDOC) sono diversi dai parametri del documento interrotto. O Parametro &TOP non valido (_ da 1, 2, 3) D Il numero di documento &NDOC non è corretto, non è disponibile o è già stato annullato E Il numero di documento &NDOC è già utilizzato da altro utente o è in aggiornamento K File TEXRAAA disallineato; banca dati danneggiata W Errore durante la creazione dell'area di lavoro (TEWRAAA/TEWDAAA); la procedura CRTAUTUSE non è stata completata con esito positivo. BLANK Operazione chiusa normalmente L Applicazione TEXGESDOC richiama la gestione di ogni singolo documento provvedendo, dopo il completamento, a chiudere tutti i files. E preferibile non richiamare questa funzione se si è già all interno della gestione documenti (attraverso una delle routine EXTAUT, EXTHF, EXTHP ecc.. richiamabili all interno della gestione di un documento ). Richiamo Funzioni 2-2 ICARO Guida Programmatore

27 Richiamo della funzione di interrogazione documenti: TEXINQ Per richiamare da un proprio menu o da un programma utente la funzione interattiva di interrogazione documenti, eseguire: CALL ICA$BAS/TEXINQ PARM(&MDB &LANG) Parametri: &MDB Tipo: *CHAR Lung: 27 è un parametro alfanumerico di 27 caratteri contenente al massimo 9 codici di tre cifre. Ciascun codice di banca dati (massimo 9) può essere passato al programma TEXINQ. Se il parametro è lasciato in bianco viene mostrata la lista delle banche dati autorizzate per consentirne la selezione. &LANG Tipo: *CHAR Lung: 1 è un parametro alfanumerico di 1 carattere contenente il codice lingua utile per passare al programma TEXINQ. Codici validi di linguaggio sono: 1=italiano, 2=inglese, 3=tedesco, 4=francese, 5=spagnolo, 6=portoghese, 7=arabo, 8=lingua addizionale, 9=lingua addizionale (nota: la relazione "numerolinguaggio" può essere modificata, ad esempio copiando i file relativi della lingua 2 nel codice 8 e traducendoli si potrebbe creare la lingua "8=greco"). esempio: CALL ICA$BAS/TEXINQ PARM('ØØ2ØØ5 ' '1') (per accedere all'editor standard della domanda per le banche dati ØØ2 e ØØ5, in italiano) CALL ICA$BAS/TEXINQ PARM(' ' '2') ('27 spazi' per accedere alla lista di banche dati autorizzate e per selezionare da 1 a 9 tra queste banche dati, '2' per ricevere l'editor standard della domanda in inglese) ICARO Guida programmatore 2-3 Richiamo Funzioni

28 Creazione di procedure per l'amministrazione delle banche dati (Supervisione del lavoro di journaling e di riorganizzazione) ICARO crea e usa due tipi di journal: - il journal di tutte le modifiche dei documenti di una banca dati; - il journal delle interrogazioni dell'utente nella ricerca di documenti. Entrambi possono essere attivati separatamente. Se uno o entrambi i journal sono attivati si dovrebbe fare il backup giornaliero dei file di journal per registrare o salvare i file su nastro e successivamente pulirli. Ciò fà aumentare la disponibilità di spazio su disco. Il journal delle modifiche contiene l'ultima immagine di ogni documento che è stato creato, modificato o prima di essere stato cancellato. Il Journal è un file fisico che si trova nella libreria di ogni banca dati ICA$nnn con il nome TEWLOG. Con l'api di ADDDOC il contenuto di un file di journal può essere ricaricato nella stessa o in una banca dati di copia in modalità ADD o REPLACE. Il formato TEWLOG e l'uso di ADDDOC API sono ampiamente descritti nel manuale utente di ICARO capitolo 10 pagina 29 e seguenti. Il journal delle domande INQD ed il journal dei risultati corrispondenti INQR, si trovano nella libreria di lavoro temporanea WICA000XXX (vedi capitolo 1). Se il journal è attivo, il contenuto dei file storici del journal INQD e INQR della libreria WICA000XXX sarà copiato nei file INQD$ e INQR$ della libreria ICA$BAS dopo che la sessione dell'utente è posizionata in stato SIGNOFF. Esempio di procedimento per il salvataggio dei file di journal Il membro source SAVEJRNL in ICA$BAS/EXAMPLE contiene un programma modello da adattare e inserire nella lista dei lavori quotidiani. I passi per il salvataggio dei file di journal sono i seguenti: - Richiamo del programma INQRSTSP. Se il journal delle domande è attivato, sarà eseguita la copia dei file journal delle domande dalle librerie WICA000XXX nei file storici dei journal nella libreria ICA$BAS. Dopo la copia, le librerie inutilizzate WICA000XXX sono rese disponibili per altri utenti. - Copia dei file del journal delle domande (INQD$ e INQR$ in ICA$BAS) in una libreria di backup e la successiva loro inizializzazione (CLRPFM). - Ricerca dei file del journal delle modifiche (TEWLOG) in tutte le librerie ICARO (da ICA$001 a ICA$999) presenti nel sistema. Se un file TEWLOG viene trovato, esso sarà copiato con il nome TEWLOGxxx nella libreria di backup. Il contenuto di ogni file TEWLOG delle librerie ICA$xxx a questo punto potrà essere cancellato. Se tutte le modifiche ai file di journal sono state copiate e cancellate, la libreria di backup deve essere salvata su nastro e successivamente cancellata. La creazione di un file di journal può essere attivata durante la definizione generale di banca dati (opzione 1 del menu 'Definizione banca dati'). Il journal registra in TEWLOG l'ultima immagine di ogni documento nuovo o revisionato o cancellato (per aggiornamento batch o interattivo). Richiamo Funzioni 2-4 ICARO Guida Programmatore

29 Per attivare il journal per le domande vedere l'opzione 9 del menu 'definizione del prodotto ICARO'. Se questa opzione è stata selezionata, tutte le domande formulate da ciascun utente saranno copiate, al momento della chiusura della sessione, nei file INQD$ e INQR$ (questi file sono descritti nel file d'origine ICA$BAS/EXAMPLE). Il file journal delle domande potrebbe essere utilizzato per fatturare l'uso delle banche dati o per scopi statistici ( per es. esaminare tutti i termini utilizzati dagli utenti nelle domande aiuterebbe a migliorare le performance di un thesaurus di ricerca o una lista di sinonimi). Attivando i journal, i relativi file (TEWLOG, INQD$ e INQR$) saranno incrementati ad ogni sessione di aggiornamento o recupero fatta dall'utente. E' quindi consigliabile salvare e svuotare questi file periodicamente (per es. ogni notte). Il membro source SAVEJRNL in ICA$BAS/EXAMPLE contiene un programma modello da adattare e inserire nella lista dei lavori quotidiani. Richiamare la riorganizzazione della banca dati: TXTRIORGA Nella definizione della banca dati, l'utente può assegnare un giorno specifico della settimana per indicare al programma TXTRIORGA se quel giorno la banca dati deve essere riorganizzata; se non si assegna un giorno e si lascia in bianco il valore della giornata, il programma TXTRIORGA non esaminerà la banca dati; in questo caso una eventuale riorganizzazione dovrà essere avviata manualmente dal menu RGZICA. La riorganizzazione consente di pulire i file journal di ogni banca dati ed eventualmente l'eliminazione fisica di tutti i documenti annullati. TXTRIORGA deve essere avviato giornalmente, possibilmente in una coda notturna. dove: CALL ICA$BAS/TXTRIORGA (&JRNL &DELET) &JRNL campo alfa di 1 carattere: '1' per pulire il file di journal TEWLOG nelle librerie ICA$nnn esaminate; TEWLOG contiene l'ultima immagine di tutti i documenti modificati/creati (se il journaling era stato attivato durante la definizione della banca dati generale). Se il parametro &JRNL è '1', il programma di Salvataggio dei journal deve essere avviato prima di TXTRIORGA altrimenti si rischia di perdere i dati del journal (vedi il sorgente SAVEJRNL in ICA$BAS/EXAMPLE). &DELET campo alfa di 1 carattere: '1' per eliminare fisicamente tutti i documenti cancellati. A seconda dell'opzione di riorganizzazione 'R=Reuse' o 'S=ADD Sequential' selezionata durante la definizione della banca dati, i numeri dei documenti cancellati saranno riutilizzati (opz. R) o mai utilizzati (opz. S). 'Ø' per lasciare in archivio i documenti annullati. ICARO Guida programmatore 2-5 Richiamo Funzioni

30 Salvataggio di una banca dati: SAVEDBICA Per richiamare da un proprio menu o da un programma utente la funzione interattiva di salvataggio banca dati (opzione 5 del menu RGZICA) eseguire il seguente comando: CALL ICA$BAS/SAVEDBICA PARM(&DBNR &DEVN &SAVFN &SAVLIB + &YN &YNF &RNT) dove: &DBNR 3 num. Campo numerico di tre cifre indicante il codice della banca dati da salvare. Se il valore impostato è Ø sarà fornita la lista delle banche dati autorizzate per selezionare interattivamente la banca dati. &DEVN 10 car. Campo alfabetico di dieci caratteri. E' il nome di device (dispositivo), per es. TAPxx DKTxx o *SAVF se la libreria della banca dati deve essere copiata su un file di salvataggio. Lasciare in bianco se il parametro &CODDB è Ø. &SAVFN 10 car. Campo alfabetico di dieci caratteri indicante il nome del file di salvataggio (se &DEVN=*SAVF).Questo file di salvataggio deve essere creato preventivamente a cura dell'utente con il comando CRTSAVF. &SAVLIB 10 car. Campo alfabetico di dieci caratteri. E' il nome della libreria dove si trova il file di salvataggio (se &DEVN=*SAVF). &YN 1 car. Indicare 'Y' se si desidera cancellare eventuali file presenti nell'unità di output prima della copia. &YNF 1 car. Indicare 'Y' se si desidera eseguire il salvataggio della banca dati anche in presenza di lavori interrotti/ sospesi/in corso. &RNT 1 car. Codice di ritorno se si è verificata una anomalia: U D A Utente non autorizzato/non definito in ICARO Parametro device errato. Se &DEVN equivale a *SAVF, il saved file non si trova nella libreria &SAVLIB oppure non è stato autorizzato o l'unità non è pronta o errata. Nel caso in cui vi sono lavori attivi. (Se il codice di ritorno è A l'utente potrebbe decidere di risottomettere il lavoro indicando 'Y' nel parametro &YFN). B Banca dati non trovata o precedentemente ripristinata in modo anomalo. E Salvataggio concluso in modo anomalo. I La password di licenza ICARO non corrisponde al sistema (ICARO non autorizzato). blank Operazione chiusa normalmente. N.B. SAVEDBICA prima di salvare la libreria ICA$xxx verifica se esiste nella stessa libreria il programma cl SAVDBIFS (vedi esempio nel file source example della libreria ICA$BAS) e se esiste lo esegue. Vedi funzione SAVDBIFS. Richiamo Funzioni 2-6 ICARO Guida Programmatore

31 Se tutti i parametri precedentemente descritti sono impostati a Ø o blank, l'utente potrà operare interattivamente immettendo i parametri necessari in un apposito schermo che verrà visualizzato. Se invece i valori dei parametri vengono immessi dal programma dell'utente, il salvataggio può essere sottomesso in batch: vedi il programma example SAVEDB nel file ICA$BAS/EXAMPLE. Salvataggio di tutte le banche dati: SAVEDB SAVEDB è un programma esemplificativo per salvare tutte le librerie ICA$nnn in un file di salvataggio nella libreria ICASAVLIB (vedi sorgente in ICA$BAS/EXAMPLE). Il programma example SAVEDB utilizza il comando SAVEDBICA. SAVEDB è stato realizzato per essere avviato in lavori notturni: prima di eseguire tale programma, accertarsi che il sottosistema QINTER non sia attivo. Salvataggio degli oggetti multimediali connessi ad una banca dati. (SAVDBIFS) Se per una banca dati ICA$xxx l utente ha creato una directory IFS sotto la root contenente oggetti multimediali (.doc,.jpeg,.asf,.tiff,.pdf ecc..) connessi ai documenti, sarà necessario in sede di backup salvare anche questi oggetti. SAVEDBICA quando è eseguito, in interattivo batch o da menù ICARO, esegue, se esiste nella libreria corrispondente ICA$xxx, il programma utente SAVDBIFS per creare un saved file ICA$xxx/IFSSAV Nella file source ICA$BAS/EXAMPLE vi è un esempio di CL, SAVDBIFS, eventualmente da modificare e compilare nella libreria ICA$xxx desiderata, che salva gli oggetti multimediali associati alla banca dati 025. Basta modificare il nome della libreria corrispondente alla banca dati (nell esempio è ICA$025) nonché la path contenente gli oggetti multimediali (nell esempio è \icaroimg\ica$025) e compilare il programma nella libreria ICA$xxx. Salvataggio degli oggetti e procedure.exe contenute nelle directory IFS \icaropgm. (SAVIFS) ICARO utilizza (per le funzioni import/export documenti) procedure ed eseguibili.exe contenuti nelle cartelle ifs \icaropgm, \icarowrk oltre ai folder, per compatibilità con precedenti versioni, \qdls\icaro e \qdls\icawin32 Il loro salvataggio in un saved file ICA$BAS\ifssav è eseguito dalla procedura: CALL ICA$BAS/SAVIFS ICARO Guida programmatore 2-7 Richiamo Funzioni

32 Ripristinare una banca dati: RSTDBICA Per richiamare da un proprio menu o da un programma utente la funzione interattiva di ripristino banca dati (opz. 6 menu RGZICA) eseguire il seguente comando: CALL ICA$BAS/RSTDBICA PARM(&DBNRI &DBNRO &DEVN &SAVFN + &SAVLIB &YF &YAU &RNT) dove i parametri RSTDBICA sono i seguenti: &DBNRI 3 num. Campo numerico di tre cifre indicante il codice della banca dati da ripristinare (Input). Ø per mostrare la videata standard di ripristino e per immettere i parametri in modo interattivo. &DBNRO 3 num. Campo numerico di tre cifre relativo al codice della banca dati da ripristinare (Output). Ø per mostrare la videata standard di ripristino e per immettere i parametri in modo interattivo. &DEVN 10 car. Campo alfabetico di dieci caratteri. E' il nome di device (dispositivo), per es. TAPxx DKTxx o *SAVF se la libreria della banca dati deve essere copiata su un file di salvataggio. Lasciare in bianco se il parametro &DBNRI è Ø. &SAVFN 10 car. campo alfabetico di dieci caratteri indicante il nome del file di salvataggio (se &DEVN=*SAVF). &SAVLIB 10 car. Campo alfabetico di dieci caratteri. E' il nome della libreria dove si trova il file di salvataggio (se &DEVN=*SAVF). Lasciare blank se è stato selezionato un device diverso da *SAVF &YF &YAU &RNT 1 car. Indicare 'Y' se si desidera cancellare e sostituire una eventuale banca dati esistente nel sistema con lo stesso codice. 1 car. Campo di un carattere alfa. Indicare Y se si desidera ripristinare le autorità utente per la banca dati. Se il parametro indicato è 'N' la banca dati appena ripristinata sarà autorizzata solo all'utente ICAROADM. 1 car. Campo di carattere alfa. E' un codice di ritorno in caso di anomalie. I codici anomalie sono i seguenti: U Utente non autorizzato/non definito in ICARO D Parametro device errato. Se &DEVN equivale a *SAVF non si trova il Saved file nella libreria SAVLIB oppure non è stato autorizzato o il dispositivo non è pronto. Richiamo Funzioni 2-8 ICARO Guida Programmatore

33 A B E I blank Nel caso in cui vi sono lavori attivi. (Se il codice di ritorno è A l'utente potrebbe decidere di risottomettere il lavoro con l'opzione 'Y' nel parametro &YFN). Banca dati non trovata nel sistema o non correttamente ripristinata in precedenza. Ripristino concluso in modo anomalo. La password di licenza ICARO non corrisponde al sistema (ICARO non autorizzato). Lavoro terminato normalmente. Se tutti i parametri precedentemente descritti sono impostati a Ø o blank, l'utente potrà immettere i valori ed operare interattivamente (verrà mostrata la schermata standard di ICARO). Se invece l'utente imposta i parametri di ripristino con un proprio programma, il lavoro potrà essere sottomesso in batch come lavoro notturno. Ripristino degli oggetti multimediali di una banca dati. (RSTDBIFS) Se per una banca dati ICA$xxx l utente ha creato la procedura (vedi paragrafo precedente) SAVDBIFS, dopo il ripristino di una banca dati, nella libreria ripristinata ICA$xxx vi sarà un saved file di nome IFSSAV contenente gli oggetti multimediali (.doc,.jpeg,.asf,.tiff,.pdf ecc..) connessi ai documenti; Sarà necessario in sede di restore, ripristinare anche questi oggetti. Nella file source ICA$BAS/EXAMPLE vi è un esempio di CL, RSTDBIFS, eventualmente da modificare e compilare nella libreria ICA$xxx desiderata, che salva gli oggetti multimediali associati alla banca dati 025. Basta modificare il nome della libreria corrispondente alla banca dati (nell esempio è ICA$025) nonché la path contenente gli oggetti multimediali (nell esempio è \icaroimg\ica$025) e compilare il programma nella libreria ICA$xxx. Il ripristino và eseguito da una riga comandi: CALL ICA$xxx/RSTDBIFS N.B. La modifica del CL e la ricompilazione và rieseguita se il ripristino è stato effettuato in una banca dati ICARO con codice diverso dall originale. Ripristino degli oggetti e procedure.exe contenute nelle directory IFS. (RSTIFS) Per ripristinare tutti gli oggetti salvati con SAVIFS eseguire da una riga comandi: CALL ICA$BAS/RSTIFS ICARO Guida programmatore 2-9 Richiamo Funzioni

34 Ricostruzione (totale) degli indici di una banca dati: SUBIDXTOT/IDXTOT E' necessario ricostruire gli indici (opz. 1 menu 'riorganizzazione banche dati' RGZICA) di una banca dati se sono state modificate le tabelle dei caratteri o nel caso in cui viene eliminato un campo o un paragrafo o se sono state aggiunte/modificate più di 200 stopword per la banca dati. Usare SUBIDXTOT per avviare il lavoro nella coda di lavoro di nome ICARO nella libreria ICA$nnn (con nnn equivalente al codice della banca dati). Usare IDXTOT per avviare il lavoro interattivamente o per sottometterlo in una qualunque altra coda desiderata (coda notturna o altro). Comandi: CALL ICA$BAS/SUBIDXTOT (&USER &DBNR) oppure CALL ICA$BAS/IDXTOT (&USER &DBNR) dove: &USER 10 caratteri nome utente &DBNR 3 numerico codice della banca dati Ricostruzione (parziale) indici di una banca dati: SUBIDXWOR / IDXWOR E' necessario ricostruire parzialmente gli indici di una banca dati ( opz. 2 menu 'riorganizzazione banche dati' RGZICA) se è stata modificata la stopword list della banca dati. Le stopword sono termini che non vengono indicizzati. Se i termini come 'IL, UNO, SE, UN, ecc.', ricorrono su un campo o paragrafo specifico possono essere definiti come stopword per il/i campo/i interessato/i. Se sono state aggiunte/modificate meno di 200 stopword e la banca dati contiene documenti, l'indice della banca dati deve essere ricostruito (parzialmente) per questi termini. Usare SUBIDXWOR per avviare il lavoro nella coda di lavoro di nome ICARO nella libreria ICA$nnn (con nnn equivalente al codice della banca dati). Usare IDXWOR per avviare il lavoro interattivamente o per sottometterlo in una qualunque altra coda desiderata (coda notturna o altro). Comandi: CALL ICA$BAS/SUBIDXWOR (&USER &DBNR) oppure CALL ICA$BAS/IDXWOR (&USER &DBNR) dove: &USER 10 caratteri nome utente &DBNR 3 numerico codice della banca dati Richiamo Funzioni 2-10 ICARO Guida Programmatore

35 Aggiornare l'indice di una banca dati per i documenti aggiunti/ revisionati: SUBAGDOC / TEXUPDOC Normalmente questo lavoro viene avviato automaticamente ad ogni chiusura del programma di gestione documenti (opz. 1 menu principale) e dopo l'esecuzione del comando ADDDOC. Ma per interruzioni di sistema si potrebbe rendere necessario riavviare tale funzione. L'aggiornamento dell'indice dei documenti (se non eseguito automaticamente quando si esce dal menu 'Gestione documenti') può essere eseguito selezionando l'opzione 4 del Menu Principale, scegliendo la banca dati, o con uno dei seguenti comandi: SUBAGDOC per avviare il lavoro nella coda di lavoro di nome ICARO nella libreria ICA$nnn (con nnn equivalente al codice della banca dati). TEXUPDOC per avviare il lavoro interattivamente o per sottometterlo in una qualunque altra coda desiderata (coda notturna o altro). Comandi: CALL ICA$BAS/SUBAGDOC (&USER &DBNR) oppure CALL ICA$BAS/TEXUPDOC (&USER &DBNR) dove: &USER 10 caratteri nome utente &DBNR 3 numerico codice della banca dati ICARO Guida programmatore 2-11 Richiamo Funzioni

36 Emissioni su stampa o su file del dizionario di una banca dati. Può necessitare avviare da un proprio Menu o sottomettere in un lavoro batch le 4 funzioni del menu di stampa del dizionario di una banca dati. Le 4 funzioni appresso descritte sono le stesse eseguibili dal Menu standard ICARO di dizionario raccolte nello schermo ICA005A (Opz. 5 Menu principale, opz. 2 Stampa dizionario) Per il richiamo o per l'avvio di una delle funzioni seguenti occorre premettere al richiamo di ogni programma le seguenti istruzioni: STRSBS QICARO MONMSG CPF0000 ADDLIBLE ICA$BAS MONMSG CPF0000 quindi in caso di sottomissione batch (SBMJOB) la lista librerie (*INLLIBL) dovrà essere *CURRENT o contenere comunque la ICA$BAS. 1. Stampa generale del dizionario o emissione su file (termini normalizzati e reali) in ordine di caricamento. CALL ICA$BAS/TEXT08P1 (&DB &LINGUA &NINIZ &NFINE + &OPTDK &OPTPRO &OPTDBA) descrizione dei parametri: &DB 3 *CHAR Contiene 3 caratteri alfanumerici contenente il codice della banca dati (es. 003) di cui elaborare il dizionario. &LINGUA 1 *CHAR Contiene 1 carattere identificativo della lingua (1=Italiano 2=Inglese..) &NINIZ 9 *CHAR Contiene 9 caratteri alfanumerici contenente il valore iniziale (di ingresso nel dizionario) da cui iniziare l'output dei termini del dizionario. Es. ' ' Nota: Allineare a destra ed estendere a 0 (zero) i caratteri di sinistra. &NFINE 9 *CHAR Contiene 9 caratteri alfanumerici contenente il valore finale (di ingresso nel dizionario) in cui terminare l'output dei termini del dizionario. Es. ' ' Nota: Allineare a destra ed estendere a 0 (zero) i caratteri di sinistra. &OPTDK 1 *CHAR Campo di un carattere contenente: '1' Output su stampa '2' Output nel file PRTDIZ nella QTEMP Il formato PRTDIZ è descritto in ICA$BAS/EXAMPLE. Richiamo Funzioni 2-12 ICARO Guida Programmatore

37 &OPTPRO 8 *CHAR &OPTDBA 3 *CHAR Nome della procedura o programma che elaborare il file QTEMP/PRTDIZ dopo la sua creazione (se &OPTDK=2). Vedi esempio source CPYPRTDZ in ICA$BAS/EXAMPLE. Lasciare blank questo parametro per non eseguire alcuna procedura Lasciare blank o immettere un codice alfa di tre cifre (es. '001') per indicare che vanno emessi tutti i termini della banca dati specificata in &DB tranne i termini esistenti nella banca dati specificata in &OPTDBA. 2. Stampa generale del dizionario o emissione su file (termini normalizzati e reali) in ordine alfabetico. CALL ICA$BAS/TEXT08P2 (&DB &LINGUA &AINIZ &AFINE &APOS &FIELD &OPTDK &OPTPRO &OPTDBA) descrizione dei parametri: &DB 3 *CHAR Contiene 3 caratteri alfanumerici contenente il codice della banca dati (es. 003) di cui elaborare il dizionario. &LINGUA 1 *CHAR Contiene 1 carattere identificativo della lingua (1=Italiano 2=Inglese..) &AINIZ 40 *CHAR Contiene 40 caratteri alfanumer. contenente il valore iniziale da cui iniziare l'output dei termini del dizionario. Es. 'aaaaa...' nel rispetto della codifica EBCDIC. (Il carattere z precede A). Questo campo deve essere blank se si utilizza il valore &APOS. &AFINE 40 *CHAR Contiene 40 caratteri alfanumer. contenente il valore finale in cui terminare l'output dei termini del dizionario. Es. 'ZZZZ... ' o ' ' Questo campo deve essere blank se si utilizza il valore &APOS. &APOS 40 *CHAR Questo campo deve essere blank se si sono utilizzati i valori &AINIZ e &AFINE. Immettere dei caratteri posizionali (Esempio A nel secondo byte e B nel terzo) per emettere solo i termini che contengono quei caratteri in quelle posizioni. (Es. GABBIA RABBIA..) &FIELD 56 *CHAR Immettere massimo 14 codici di campo formattato (Fxxx) e/o paragrafo (Pxxx) per selezionare solo i termini che ricorrono in uno dei campi indicati. Lasciare blank per accettare tutti i termini. (es. P001F002P012...) continua ICARO Guida programmatore 2-13 Richiamo Funzioni

38 &OPTDK 1 *CHAR Campo di un carattere contenente: '1' Output su stampa '2' Output nel file PRTDIZ nella QTEMP Il formato PRTDIZ è descritto in ICA$BAS/EXAMPLE. &OPTPRO 8 *CHAR Nome della procedura o programma che elabora il file QTEMP/PRTDIZ dopo la sua creazione (se &OPTDK=2). Vedi esempio source CPYPRTDZ in ICA$BAS/EXAMPLE. Lasciare blank questo parametro per non eseguire alcuna procedura &OPTDBA 3 *CHAR Lasciare blank o immettere un codice alfa di tre cifre (es. '001') per indicare che vanno emessi tutti i termini della banca dati specificata in &DB tranne i termini esistenti nella banca dati specificata in &OPTDBA. 3. Stampa o emissione su file dei termini nella forma normalizzata, con raggruppate le forme reali, in ordine di ingresso. CALL ICA$BAS/TEXT08P3 (&DB &LINGUA &NINIZ &NFINE &OPTDK &OPTPRO &OPTDBA) per la descrizione dei parametri fare riferimento ai parametri del punto Stampa o emissione su file dei termini nella forma normalizzata, con raggruppate le forme reali, in ordine alfabetico. CALL ICA$BAS/TEXT08P4 (&DB &LINGUA &AINIZ &AFINE &APOS &FIELD &OPTDK &OPTPRO &OPTDBA) per la descrizione dei parametri fare riferimento ai parametri del punto 2. Richiamo Funzioni 2-14 ICARO Guida Programmatore

39 Capitolo 3. Gestione documenti Struttura dei File di ICARO File TEXRAAA e TEXDAAA L'applicazione di ICARO gestisce 'documenti'. Un documento è una struttura logica di campi: fissi (detti anche formattati) e/o variabili (detti anche paragrafi). I campi formattati di un documento sono contenuti in un record nel file fisico TEXRAAA, indicizzato nel campo di riferimento C81 contenente il numero sequenziale di ingresso del documento nella banca dati: Label campi Contenuto C81 C81 -C85 C86 campo contenente il numero del documento campi utilizzati da ICARO status del documento: blank=attivo, 3=annullato CØØ1 campo formattato dell'utente di codice 001, se definito nella banca dati.... C255 campo formattato di codice 255 Il file logico TEXDAAA contiene un record per ogni riga di paragrafo del documento: TEXDAAA è il file logico singolo che unisce diversi file fisici corrispondenti alla lunghezza di righe di documenti. Ad esempio le righe di documento da 1 a 10 caratteri saranno memorizzate nel file TEXDØ1Ø, mentre le righe da 11 a 20 saranno memorizzate nel file TEXDØ2Ø ecc.. Il file logico TEXDAAA è organizzato secondo le seguenti chiavi: a) numero sequenziale di documento b) numero di campo c) numero di riga Per ciascun documento di ICARO, il file TEXRAAA contiene almeno un record (anche se la banca dati non contiene campi formattati) dove sono indicati ed utilizzati i campi C81 e C86. Al contrario, il file dei paragrafi TEXDAAA, può risultare privo di record se nessun paragrafo è stato definito nella banca dati. TEXRAAA e TEXDAAA contengono i record dei documenti 'effettivamente' memorizzati (ossia documenti indicizzati e interrogabili), mentre i documenti in fase di gestione (aggiunta revisione annullamento) o in attesa di aggiornamento sono memorizzati nei file 'work' (area di lavoro) TEWRAAA e TEWDAAA. Per le descrizioni dei file, consultare il file QDDSSRC nella libreria ICA$FIL. ICARO Guida Programmatore 3-1 Gestione documenti

40 File di lavoro TEWRAAA e TEWDAAA I documenti di nuova creazione o revisionati, non sono memorizzati immediatamente nei file appena descritti, bensì in file di aree di lavoro denominati TEWRAAA (per i campi formattati) e TEWDAAA (per le righe dei paragrafi). Se viene creato un documento nuovo: - la routine di preparazione area di lavoro creerà un record nel file TEWRAAA (con i campi inizzializzati a 0 o blank); - verranno creati nel file TEWDAAA 'n' record, uno per ogni riga, contenente per ciascun paragrafo le eventuali intestazioni (massimo tre righe protette per ogni campo) e le righe di default (massimo 10 righe definite dall'utente nella definizione dei paragrafi). Se un documento è esistente e viene revisionato, i suoi record in TEWRAAA e TEWDAAA conterranno i dati duplicati dai file del documento effettivo (TEXRAAA e TEXDAAA). Se viene revisionato un documento già esistente nell'area di lavoro, ma ancora in attesa di essere aggiornato, i suoi record saranno duplicati nella stessa area di lavoro con un livello di aggiornamento incrementato di 1. Il record di campo formattato del file TEWRAAA è indicizzato secondo le seguenti chiavi: - numero di documento (7 num.) (campo W81) - numero di livello (3 num.) (campo W82) i campi formattati Cxxx sono copiati in altrettanti campi del file di lavoro TEWRAAA identificati da Wxxx. Il file TEWDAAA è indicizzato secondo le seguenti chiavi: - numero di documento (7 num.) - numero di livello (3 num.) - numero di paragrafo - numero di riga Il numero di riga è incrementato di 1000 per consentire all'utente di inserire righe durante la revisione. Le prime tre righe di un paragrafo possono contenere le righe di intestazione (se sono state definite durante la definizione del paragrafo). Le righe di intestazione sono identificate dal carattere HEX FF in posizione 256 del campo testo. Le righe di intestazione sono protette in gestione e NON saranno trasferite nei file di documento TEXDAAA e quindi, le parole in esse contenute non saranno indicizzate. Gestione documenti 3-2 ICARO Guida Programmatore

41 File assegnazione numero identificativo: TEXARET e TEXAGAN Per ogni documento inserito in banca dati, viene assegnato un numero progressivo dato dall'incremento del campo TXADCU del file TEXARET (nella libreria ICA$nnn). Il file TEXARET contiene un solo record con le informazioni generali della banca dati: - nome della banca dati - totale documenti annullati - totale documenti attivi - ultimo numero di documento creato - numero massimo di utenti autorizzati - altri campi di uso interno - Se all'ultimo documento creato segue l'annullamento dell'operazione, il record creato nel file TEXRAAA verrà identificato con una 'X' nel campo C84. Questo identificativo fa sì che il numero di documento annullato sia immediatamente disponibile per nuovi documenti da inserire: un'apposita vista logica TEXAGAN costruita sul file TEXRAAA nel campo C84 consente ad ICARO di riutilizzare i numeri di documento non utilizzati. Il campo C84 ed il file logico TEXAGAN sono altresì utilizzati quando l'utente avvia la riorganizzazione della banca dati (opzione 3 menu RGZICA) con l'eliminazione fisica dei documenti annullati. In questo caso: se la riorganizzazione della banca dati è impostata nel campo 'tipo organizzazione' con il valore 'R' (recupero), nel file TEXRAAA ogni nuovo documento avrà come progressivo di caricamento quello più basso di un precedente documento annullato; se invece la riorganizzazione della banca dati è impostata nel campo 'tipo organizzazione' con il valore 'S', i numeri dei documenti annullati non saranno più utilizzati e ogni nuovo documento avrà come progressivo di caricamento quello immediatamente successivo al precedente numero di documento assegnato (vedi il menu di definizione generale della banca dati). ICARO Guida Programmatore 3-3 Gestione documenti

42 Selezione di un documento da revisionare: TEXT11 Con la funzione standard 'Gestione documenti' (opzione 1 del menu Principale), dopo la selezione della banca dati, compare la videata ICAØ11 che consente all'utente di scegliere l'opzione per inserire un nuovo documento (opz. 1), revisionare un documento (opz. 2), annullare un documento (opz.3) ed immettere l'eventuale numero di riferimento del documento da revisionare/annullare. Per revisionare (o annullare) un documento l'utente deve conoscere il numero di riferimento ICARO del documento e non, ad esempio, il codice del cliente. Se l'utente, con la procedura normale non ricorda il riferimento del documento corrispondente al cliente di codice 55 dovrebbe: - scegliere dalla videata ICAØ11 l'opzione 5 (interroga banca dati) - formulare la domanda: 55.codice (se codice è l'abbreviazione del campo formattato relativo al codice) - visualizzare la lista abbreviata dei documenti risultanti, - selezionare con il codice 2 (revisione) il documento interessato alla modifica o memorizzarne il numero di riferimento (xxx) - tornare con F3 alla videata di gestione dei documenti - immettere 2 (o 3) nel tipo operazione e xxx come numero del documento da revisionare (o annullare). Se uno o più campi formattati sono stati definiti per la banca dati e l'utente desidera eliminare questi passaggi - quindi desidera sostituire la videata ICAØ11 con un'altra videata - può realizzare un'interfaccia specifica: 1) definire una videata di Input, per es. Video xyz Video: DSPxxx Utente: ABC Immetti codice cliente: F3=Fine Gestione documenti 3-4 ICARO Guida Programmatore

43 2) creare un file logico, basato sul campo codice cliente per ognuno dei file del documento TEWRAAA e TEXRAAA Il programma utente cercherà il codice Cliente nelle viste logiche. Se il codice cliente non viene trovato, è possibile avviare la creazione di un nuovo documento richiamando la routine TEXT11 con il parametro &TOP impostato a 1=nuovo documento (si veda più avanti). Se invece il codice cliente viene trovato, l'utente può richiedere la immissione a video della operazione da effettuare: la modifica (che può essere l'opzione di default) o l'annullamento del documento. In questo caso la routine TEXT11 è richiamata con il tipo operazione (parametro &TOP) impostato a 2=Revisionare oppure 3=Annullare; viene altresì impostato in numero del documento nel parametro &NDOC con il valore dei campi W81 (se il codice cliente è trovato nel file TEWRAAA) o C81 (se il codice cliente è trovato nel file TEXRAAA). Come si crea un esempio? Occorre definire una vista logica per un campo formattato della banca dati Il contenuto di questo campo può essere impostato da input utente (non protetto) oppure generato a programma (per es. dal programma EXTAUT - si veda in seguito) rendendo quindi, se si vuole, non visibile il campo nella videata di Input: - Impostare con 1 (Yes) il parametro 'Ottimizza funzione SELECT'. In tal modo la compilazione della banca dati genererà uno specifico file logico sul file TEXRAAA: così se il codice del campo formattato è 2, la vista logica sarà TEXRLØØ2 sul file TEXRAAA per il campo CØØ2. - Dopo la compilazione della banca dati, creare un altro file logico sul file di lavoro TEWRAAA, per es. TEWRLØØ2 per il campo WØØ2 del file (sempre per il campo formattato 2). - Se l'accesso al file deve avvenire mediante più campi formattati, tra loro combinati, allora l'utente, dopo la compilazione, dovrà creare una apposita vista logica globale LOGIC1 per il file TEXRAAA e LOGIC2 per TEWRAAA ed entrambi useranno come chiave i 2 o più campi formattati.. 3) Creare un programma RPG, ad es. DOCGES, da compilare nella libreria ICA$nnn (con nnn=codice banca dati) per attivare la routine TEXT11 per la gestione della richiesta del tipo di operazione. Un esempio di programma DOCGES e di dspf DOCGESF si trova nel file ICA$021/QRPGSRC e ICA$021/QDDSSRC (si veda anche l'esempio EXTAUT). L'operatività del programma si può testare nella banca dati example di codice Ø21 dove l'utente potrà trovare i source dei file logici TEXRLØØ2 e TEWRLØØ2. Altro esempio è fornito nella banca dati example 031 (vedi source DOCGES e DOCGESF) e viste logiche TEXRL006 e TEWRL006. Collegandosi con il profilo utente ICARO si gestiranno le due banche dati con i programmi personalizzati DOCGES (vedi più avanti). Istruzione per richiamare la routine TEXT11: CHGCURLIB ICA$xxx (xxx = codice banca dati) CALL ICA$BAS/TEXT11 (&TOP &NDOC &RTN) ICARO Guida Programmatore 3-5 Gestione documenti

44 I parametri di TEXT11 sono: &TOP &NDOC &RTN 1 car. Campo alfa contenente il tipo di operazione: 1=nuovo documento 2=revisione documento 3=annullamento documento. 7 num. Campo numerico di 7 cifre; obbligatorio se &TOP è 2 o 3; può essere ØØØØØØØ se &TOP è 1; può essere il numero di un documento da 'duplicare' se &TOP è 1 1 car. Codice di ritorno: V Vincolo su prodotto, banca dati o documento U La CURLIB è in conflitto con la banca dati selezionata M E' stato raggiunto il numero massimo di utenti ammessi per lavorare con documenti (vedi le definizioni generali della banca dati) C La banca dati deve essere compilata o ricompilata. T La precedente richiesta di gestione documenti è terminata in modo anomalo (è stata interrotta), i parametri correnti (&TOP &NDOC) sono diversi dai parametri del documento interrotto. O Parametro &TOP non valido (_ da 1, 2, 3) D Il numero di documento &NDOC non è corretto, non è disponibile o è già stato annullato E Il numero di documento &NDOC è già utilizzato da altro utente o è in aggiornamento K File TEXRAAA disallineato; banca dati danneggiata W Errore durante la creazione dell'area di lavoro (TEWRAAA/TEWDAAA); la procedura CRTAUTUSE non è stata completata con esito positivo. BLANK Operazione chiusa normalmente. Prima di terminare il programma utente, la routine TEXT11 deve essere chiusa passando il valore 'F' nel parametro &RTN. Per esempio: CALL ICA$BAS/TEXT11 (&TOP &NDOC 'F') Questo comando chiude correttamente i file aperti e inizia automaticamente l'aggiornamento degli indici (i documenti creati/revisionati vengono trasferiti dai file di lavoro TEWRAAA e TEWDAAA ai file di documento della banca dati TEXRAAA e TEXDAAA). 4) Richiamare la gestione profili utente, e per gli utenti autorizzati, concedere l' autorità a gestire la banca dati immettendo il nome del programma generato nel valore 'Programma di input specifico' (per testare gli esempi delle banche dati fornite 021 e 031 assegnare il programma di input specifico DOCGES ad un utente autorizzato nelle banche dati 021 o 031 o usare il profilo utente ICARO). In tal modo quando si sceglierà dal menu principale l'opzione 1 per gestire documenti della banca dati, apparirà, per la richiesta del tipo operazione, lo schermo utente al posto dello schermo ICARO. Gestione documenti 3-6 ICARO Guida Programmatore

45 Assegna o proteggi il contenuto di un campo: EXTAUT Il richiamo della routine TEXT11 esegue subito, per il documento, la creazione dei record nei file TEWRAAA e TEWDAAA nell'area di lavoro - rispettivamente per i campi formattati e per i paragrafi - per poi gestirli con i relativi editori. Prima di una qualsiasi immissione/revisione nei record TEWRAAA e TEWDAAA, viene richiamata automaticamente, dalla routine TEXT11 la routine ICA$nnn/EXTAUT (se esiste per questa banca dati). EXTAUT può essere utilizzata per: - impostare un valore di default (per es. la data del sistema, un valore esterno della banca dati) ad uno o più campi formattati o paragrafi, anche in funzione del valore del parametro di operazione (&TOP): nuovo documento, revisione, annullamento ecc... La impostazione di valori di default dovrebbero essere sempre condizionati da TOP=1 per evitare valori indesiderati in caso di cadute di sistema durante una revisione e successivo recupero. - modificare dinamicamente gli attributi di protezioni di specifici campi, ad esempio, secondo il contenuto o valore degli altri campi: se il campo 1 contiene 'A' allora il campo 2 obbligatoriamente deve contenere 'B' ed il campo 'C' deve essere protetto da immissioni o modifiche... ecc... Un esempio di EXTAUT è dato nel file sorgente EXAMPLE della libreria ICA$BAS. Viceversa un esempio produttivo di EXTAUT è dato nella libreria ICA$021 per il test della banca dati 021: questo esempio assegna la data di sistema al campo W018 (campo formattato nel file di lavoro TEWRAAA), protegge anche questo campo dalla scrittura ed assegna un 'codice cliente' (letto da un'area dati predefinita) al campo W002. Il programma (RPG, CL,...) EXTAUT deve essere creato nella libreria della banca dati ICA$nnn. I parametri ricevuti dal programma EXTAUT sono i seguenti: NDOC 7 num. campo numerico di 7 cifre. Indica il numero del documento LEVEL 3 num. campo numerico di tre cifre. Indica il numero di livello aggiornato nell'area di lavoro (campo W82) TOP 1 car. tipo di operazione in esecuzione: 1=nuovo documento 2=revisione documento 3=annullamento documento. parametro ricevuto e modificabile dall'utente: AU 511 car. Codice di protezione per ciascun paragrafo (da 1 a 256) e per ogni campo formattato (da 257 a 511) Per ogni campo questo codice di protezione può contenere il seguente valore: Ø Il campo non è protetto: l'utente può leggere, scrivere, annullare, modificare il contenuto. 1 Il campo è visibile, ma protetto in scrittura. ICARO Guida Programmatore 3-7 Gestione documenti

46 2 L'intestazione del campo è visibile (per es. 'Cliente... '), ma il contenuto non è mostrato e quindi è protetto. 3 L'autorizzazione è Ø per nuovo documento; è 1 per documenti esistenti (revisionati): protetti. 4 L'intero campo (intestazione e contenuto) è completamente non visibile. Esempio: Per autorizzare (con il codice =Ø) il paragrafo 10 e per proteggere (con il codice =1) il campo formattato 10 ( = 266), trascrivere le seguenti istruzioni in un programma RPG:... MOVE 'Ø' MOVE '1'... AU,10 AU,266 con AU una schiera di 511 elementi. Gestione documenti 3-8 ICARO Guida Programmatore

47 Definire un help sui campi formattati: EXTHF Quando viene premuto il tasto F1 (Help o RICH AIUTO) nello schermo di gestione dei campi formattati ed il cursore è posizionato su uno specifico campo di input, viene automaticamente richiamato ed eseguito - se esiste - il programma ICA$XXX/EXTHF posto per l'appunto libreria della banca dati di codice XXX. Se invece non esiste nessun programma EXTHF nella libreria della banca dati, viene mostrata la videata di help generale per l'input dei campi formattati. Il programma EXTHF (per es. un programma CL, RPG, C) può mostrare l'help collegato al campo oppure una tabella che permette all'utente di selezionare il valore appropriato. Un esempio di programma EXTHF lo si può trovare nel membro EXTHF del file sorgente EXAMPLE nella libreria ICA$BAS. Una copia operativa del programma EXTHF la si può trovare nella libreria della banca dati 021 dove nel campo 'Settore economico' premendo F1 viene mostrata una tabella da cui l'utente potrà selezionare l'elemento che interessa. EXTHF deve essere creato nella libreria della banca dati ICA$nnn e deve avere i seguenti parametri: FIELD 3 num. numero di tre cifre contenente il codice del campo formattato in corrispondenza del quale è stato premuto F1 DBNR 3 num. numero di tre cifre contenente il codice della banca dati NDOC 7 num. numero di sette cifre indicante il riferimento del documento LEVEL 3 num. numero di tre cifre indicante il numero di livello del record in TEWRAAA. Dopo l'esecuzione di EXTHF, il programma riporta il controllo al programma di gestione dei campi formattati (TEZAAA). ICARO Guida Programmatore 3-9 Gestione documenti

48 Definire un help sui singoli paragrafi: EXTHP Quando viene premuto il tasto F1 (Help o RICH AIUTO) durante la gestione dei paragrafi di un documento o durante la visualizzazione di un documento in fase di interrogazione ed il cursore è posizionato su una riga di uno specifico paragrafo, viene automaticamente richiamato ed eseguito - se esiste - il programma ICA$XXX/EXTHP posto per l'appunto nella libreria della banca dati di codice XXX. Se invece non esiste il programma EXTHP nella libreria della banca dati, viene visualizzato l help generale. Il programma EXTHP (per es. un programma CL, RPG, C) può mostrare l'help collegato al campo oppure una tabella che permette all'utente di selezionare il valore appropriato. Un esempio di programma EXTHP lo si può trovare nel membro EXTHP del file sorgente EXAMPLE nella libreria ICA$BAS. Il richiamo della routine EXTHP avviene se l utente è autorizzato (profilo utente) alla gestione o interrogazione del paragrafo. Il richiamo di EXTHP (se l utente è autorizzato) avviene anche se il paragrafo è stato protetto dalla routine EXTAUT. Una copia operativa del programma EXTHP la si può trovare nella libreria della banca dati 021 dove nel primo paragrafo: premendo F1 viene mostrata una tabella da cui l'utente potrà selezionarne il testo e trasferirlo nella prima riga del paragrafo (premere F1 nella riga n.3 in quanto le prime 2 sono di intestazione). EXTHP, creato nella libreria ICA$nnn, deve avere i seguenti parametri: PARA 3 num. numero di tre cifre contenente il codice del paragrafo in corrispondenza del quale è stato premuto F1. In sede di gestione documenti il valore di questo campo viene passato in valore negativo (pertanto moltiplicare per -1 per ottenere il valore effettivo) Questo valore sarà passato in valore positivo se la routine è richiamata dalla visualizzazione di un documento. DBNR 3 num. numero di tre cifre contenente il codice della banca dati NDOC 7 num. numero di sette cifre indicante il riferimento del documento LEVEL 3 num. numero di tre cifre indicante il numero di livello del documento nell'area di lavoro. Dopo l'esecuzione di EXTHP, il programma riporta il controllo al programma di gestione dei paragrafi (editor di ICARO - videata ICA300). Gestione documenti 3-10 ICARO Guida Programmatore

49 Routine controllo contenuto dei campi formattati: EXTCOF Dopo il completamento della revisione/immissione dei campi formattati (esecuzione del programma ICARO TEZAAA), l'utente deve premere il tasto Invio per fare eseguire ad ICARO il controllo sui campi formattati, sui campi ad immissione obbligata, sui valori numerici, sulla validità della data, esistenza di termini ecc.. In apposita finestra, dal file QTEMP/ERRORI, si visualizzeranno i messaggi di errore identificati da 'W' (=warning, attenzione) oppure 'T' (=errori gravi che richiedono immediata correzione). Se l'utente lo desidera può, scrivendo l'opportuno programma EXTCOF, aggiungere propri controlli o addirittura calcolare un determinato valore da memorizzare in campi protetti ed eventuali errori possono essere registrati, dalla routine utente EXTCOF, nel file QTEMP/ERRORI per essere visualizzati insieme agli errori riscontrati da ICARO. EXTCOF sarà richiamato automaticamente se verrà creato un nuovo documento o se verrà revisionato un documento esistente, ma NON SARA' RICHIAMATO se il documento viene annullato. Un esempio di programma EXTCOF lo si può trovare nel membro EXTCOF del file sorgente EXAMPLE nella libreria ICA$BAS. Una copia operativa del programma EXTCOF la si può trovare nella libreria della banca dati 021 dove, dopo l'inserimento dei campi formattati, viene controllato che il campo 006 ('Settore economico') non sia blank. EXTCOF deve essere creato (da sorgenti RPG, CL, C, COBOL ecc.) nella libreria della banca dati ICA$nnn e deve avere i seguenti parametri: DBNR 3 num. tre cifre contenente il codice della banca dati NDOC 7 num. sette cifre indicante il riferimento del documento LEVEL 3 num. tre cifre indicante il numero di livello del documento nell'area di lavoro FIELDS 255 car. Serie di 255 caratteri alfa corrispondenti, ciascun elemento, ad un codice di campo formattato; l'utente si preoccupa di memorizzare in ciascun elemento il codice W o T se nel campo ha riscontrato un errore warning o grave. Il programma main (TEZAAA) visualizzerà in inversione di fondo i campi in errore. Per es. se la routine segnala nel campo 10 un errore di attenzione (W) o un errore grave (T), allora il decimo elemento di FIELDS conterrà W o T. Dopo l'esecuzione di EXTCOF, il programma ritorna al programma di gestione dei campi formattati (TEZAAA) per la visualizzazione, in apposita finestra, di eventuali errori e quindi passa all'editor ICARO (videata ICA300) per gestire i paragrafi (se non è stato trovato alcun errore nel file QTEMP/ERRORI). ICARO Guida Programmatore 3-11 Gestione documenti

50 Routine controllo contenuto dei paragrafi: EXTCOP Dopo il completamento della gestione dei paragrafi e dopo che l'utente ha premuto il tasto di aggiornamento F17, ICARO esegue il controllo sui paragrafi, sui paragrafi ad immissione obbligata, sulle authority list, ecc.. In apposita finestra, dal file QTEMP/ERRORI si visualizzeranno i messaggi di errore 'W' (=warning= attenzione) oppure 'T' (=errori gravi che richiedono immediata correzione). Se l'utente lo desidera può, scrivendo l'opportuno programma EXTCOP, aggiungere propri controlli o addirittura modificare/aggiungere righe di paragrafi protetti ed eventuali errori possono essere registrati nel file QTEMP/ERRORI per essere visualizzati con gli errori riscontrati da ICARO. EXTCOP sarà richiamato automaticamente se verrà creato un nuovo documento o se verrà revisionato un documento esistente, ma NON SARA' RICHIAMATO se il documento viene annullato. Un esempio di programma EXTCOP lo si può trovare nel membro EXTCOP del file sorgente EXAMPLE nella libreria ICA$BAS. Una copia operativa del programma EXTCOP la si può trovare nella libreria della banca dati 021 dove, dopo l'inserimento nel paragrafo 002 viene controllato che la prima riga di questo campo non venga lasciata blank (vuota). EXTCOP deve essere creato (da sorgenti RPG, CL, C, COBOL ecc.) nella libreria della banca dati ICA$nnn e deve avere i seguenti parametri: DBNR 3 num. numero di tre cifre contenente il codice della banca dati NDOC 7 num. numero di sette cifre indicante il riferimento del documento LEVEL 3 num. numero di tre cifre indicante il numero di livello del documento nell'area di lavoro. ERROR 1 car. campo alfabetico di 1 carattere. Se la routine riscontra in un paragrafo un errore segnala: 'W' se sono stati riscontrati errori warning registrati nel file QTEMP/ERRORI 'T' se è stato riscontrato almeno un errore grave registrati nel file QEMP/ERRORI (in questo modo è resa obbligatoria la correzione). BLANK Nessun errore Dopo l'esecuzione di EXTCOP, il programma ritorna all'editor ICARO (videata ICA300) per correggere gli errori, salvare o aggiornare il documento (se non è stato trovato alcun errore nel file QTEMP/ERRORI). Gestione documenti 3-12 ICARO Guida Programmatore

51 Routine controllo cancellazione documento: EXTDEL Può essere utile, per certe banche dati, che un programma di controllo verifichi, prima di accettare la cancellazione di un documento, l'esistenza di oggetti connessi al documento che si sta cancellando. Per esempio: un documento può essere unito ad altri documenti o ad oggetti esterni come immagini, suoni ecc.. Prima di accettare la cancellazione del documento, verrà automaticamente richiamato il programma EXTDEL, se esiste, che convaliderà la procedura di cancellazione secondo le specifiche indicate dall'utente. EXTDEL viene richiamato nei seguenti casi: - Dopo avere premuto il tasto F3 (uscire senza salvare) quando viene creato un nuovo documento o se si revisiona un documento già esistente. - Quando viene premuto il tasto F17 per l'annullamento di un documento già esistente. Il programma principale richiama, se esiste, il programma EXTDEL con i seguenti parametri: DBNR NDOC LEVEL DELET 3 num. numero di tre cifre contenente il codice della banca dati 7 num. numero di sette cifre indicante il riferimento del documento 3 num. numero di tre cifre indicante il numero di livello del documento nell'area di lavoro. 1 car. campo alfabetico di 1 carattere. L'utente può immettere: 'N' se si desidera che il programma principale NON accetti la cancellazione del documento richiesta utente. 'Y' se si desidera che il programma principale accetti la cancellazione del documento. Un esempio di programma EXTDEL lo si può trovare nel membro EXTDEL del file sorgente EXAMPLE nella libreria ICA$BAS. Questo esempio (sorgente CL) mostra all'utente un messaggio con cui si vieta e quindi annulla la richiesta di cancellazione. EXTDEL, per testarlo, deve essere creato nella corrispondente libreria di banca dati ICA$nnn. ICARO Guida Programmatore 3-13 Gestione documenti

52 Routine di EXIT da richiamare durante la gestione di documenti: con la pressione del tasto F20 (EXTGES) Durante la gestione dei campi formattati o dei paragrafi l'utente, se autorizzato e se esiste un programma di nome EXTGES, può richiamare la routine premendo il tasto F20. La routine EXTGES può attivare molte applicazioni esterne. Un esempio tipico è costituito dalla scansione di immagini e collegamento al documento in gestione di uno o più documenti associati al documento che si sta gestendo (l'interfaccia standard TIS IMAGE Plus usa la routine EXTGES). Il programma EXTGES deve avere i seguenti parametri: DBNR 3 num. numero di tre cifre contenente il codice della banca dati NDOC 7 num. numero di sette cifre indicante il riferimento del documento LEVEL 3 num. numero di tre cifre indicante il numero di livello del documento. Un esempio di programma EXTGES lo si può trovare nel file sorgente EXAMPLE nella libreria ICA$BAS. Questo esempio (sorgente CL) mostra all'utente un metodo per leggere il valore di un campo formattato e visualizzare (o scandire) un immagine. Un esempio produttivo di EXTGES è nella corrispondente libreria della banca dati ICA$nnn. Un esempio di codifica del programma è nella libreria ICA$Ø22: EXTGES legge il contenuto di un campo formattato contenente il nome di una immagine associata, quindi richiede al PC workstation (computer principale) di mostrare l'immagine (attraverso la sessione PCS-PCO). L'utente è invitato a stampare ed esaminare il sorgente. Gestione documenti 3-14 ICARO Guida Programmatore

53 Routine da eseguire dopo l'aggiornamento del documento: EXTCLDOC Il programma ICA$xxx/EXTCLDOC viene automaticamente richiamato dal programma TEXT11 dopo che la richiesta di aggiornamento è stata effettuata e definitivamente accettata con la pressione del tasto F17. Il programma EXTCLDOC non sarà richiamato se dopo aver richiesto l'aggiornamento vengono mostrati errori gravi o di attenzione oppure nel caso in cui le funzioni di editor vengono conclusi con la pressione del tasto F3 (uscita senza salvataggio). Il gestore di una banca dati può creare una particolare routine di EXTCLDOC nella libreria della banca dati ICA$xxx per applicazioni specifiche o per file esterni che devono essere aggiornati solo dopo una corretta convalidazione del documento e non se l'utente fa 'prove o errori'. Il programma EXTCLDOC deve avere i seguenti parametri: DBNR 3 num. numero di tre cifre contenente il codice della banca dati NDOC 7 num. numero di sette cifre indicante il riferimento del documento LEVEL 3 num. numero di tre cifre indicante il numero di livello del documento Un esempio di programma EXTCLDOC lo si può trovare nel file sorgente EXAMPLE nella libreria ICA$BAS. EXTCLDOC può essere utilizzato solo per aggiornare specifici file di controllo se e quando il documento è realmente valido ed è stato inviato nella coda di aggiornamento (F17). (Altre routine di convalida come EXTCOF/EXTCOP sono richiamate al fine di convalidare quando si sta lavorando con i documenti, anche se questi documenti possono essere successivamente cancellati dall'area di lavoro con F3). ICARO Guida Programmatore 3-15 Gestione documenti

54 Modifica videata del programma di gestione campi formattati: TEZAAA La compilazione di una banca dati crea nella libreria ICA$nnn i seguenti sorgenti: - un programma RPG per lavorare con i campi formattati (membro TEZAAA nel file QRPGSRC) - 9 file video uno per ognuna delle 9 lingue (membri TEZAAAFx -con x da 1 a 9- nel file ICA$xxx/QDDSSRC) Il programma RPG ed i file di visualizzazione possono essere modificati per specifiche esigenze, per es.: - modificare la disposizione dei campi (per es. due campi sulla stessa riga); - modificare gli attributi dei file video; - assegnare un valore iniziale ai campi formattati, ecc.. Un esempio di TEZAAA lo si trova nel file sorgente ICA$BAS/EXAMPLE. Punti interrogativi (?) nella colonna 4 indicano le modifiche al codice sorgente apportate dall'utente (diverse rispetto alla versione generata automaticamente). PRELIM routine La routine PRELIM è contenuta nel sorgente TEZAAA. Essa è utilizzata, per assegnare, a ciascun campo formattato dell'area di lavoro (W001 - W256), i valori di inizializzazione. PRELIM può essere modificato. Per es.: se il documento è nuovo, e quindi il contenuto del campo W83 è '1', la data di sistema può essere scritta nel campo formattato W002 (specificato come data durante la definizione del campo). CONTR routine La routine CONTR è contenuta nel sorgente TEZAAA. Essa indica, per ciascun campo formattato dell'area di lavoro (W001 - W256), il controllo da eseguire. CONTR può essere modificato. Per es.: il campo 'Titolo' - W005 può essere specificato come 'non blank' (non vuoto). Nota: E' consigliabile usare la routine EXTAUT per definire valori iniziali o la routine specifica EXTCOP per eseguire controlli piuttosto che modificare il programma TEZAAA. TEZAAA verrà automaticamente rigenerato e compilato ad ogni modifica strutturale della banca dati e quindi occorrerà riportare le modifiche dell'utente ad ogni nuova creazione del programma TEZAAA; ciò comporta quindi particolare attenzione: backup delle modifiche, controllo di livello, compilazioni specifiche, ecc.. Se il sorgente TEZAAA iniziale viene modificato, compilare il programma nella libreria della banca dati ICA$nnn dopo avere eseguito le istruzioni seguenti: OVRDSPF TEZAAAF ICA$nnn/TEZAAAFx OVRDBF TABLE ICA$BAS/TABLEx ADDLIBLE ICA$nnn (x=codice lingua) (x=codice lingua) Gestione documenti 3-16 ICARO Guida Programmatore

55 Importare/Esportare da e verso PC: EXTIMPO/EXTEXPO Nella gestione dei paragrafi di un documento i tasti F21 consente all'utente di importare (EXTIMPO o EXTIMPO2) documenti office, nei formati gestibili da word, in un documento ICARO (opzione 4 dal Menu di scelta dell'origine di importazione); il tasto F22 consente (EXTEXPO) di esportare un documento ICARO in formato.doc,.txt,.htm in un PC (opz. 4 di scelta della destinazione): Questi programmi (EXTIMPO,EXTEXPO EXTEXPO2) possono essere personalizzati per applicazioni specifiche o per personalizzare eventuali conversioni di testo o per adattamenti ad ambienti operativi particolari. L importazione utilizza il programma TXTCONV.exe (file system \\as400\icaropgm) che utilizzando il convertitore WORD trasferisce nella path IFS \icarowrk il documento selezionato qualunque supportabile dal word - con il nome della sessione di lavoro wicaxxxx dopo averlo convertito in formato Text With Layout (.ans) per testi ad 1 colonna (EXTIMPO) o Solo TESTO (.txt) per testi multicolonna (EXTIMPO2). Particolare esigenze di conversione possono essere assolte sostituendo TXTCONV.exe con un applicazione analoga modificando i pgm EXTIMPO. Importare da PC: EXTIMPO, EXTIMPO2 Il programma CL EXTIMPO (o EXTIMPO2) consente all'utente di importare nel documento ICARO un file testo ASCII,.DOC,.RFT,.HTM da un PC collegato all'as/400 via ClientAccess/400 o da un disco di rete. EXTIMPO provvede al trasferimento di documenti il cui testo è su una colonna, mentre EXTIMPO2 è da utilizzare per documenti multicolonna. Il programma CL EXTIMPO (o EXTIMPO2) esegue queste funzioni: - lancia, tramite strpccmd, l esecuzione dalla cartella \systemas400\icaropgm del programma windows TXTCONV.exe. Questo programma tramite finestre windows consente la scelta della directory e del documento da importare. Selezionato il documento, TXTCONV provvede a copiare nella cartella di lavoro \systemas400\icarowrk con il nome uguale all area di lavoro assegnata alla sessione (WICAxxxxx) il documento scelto dopo averlo convertito: 1) in formato TEXT LAYOUT (.ans) utilizzando il convertitore dell office installato nel caso di EXTIMPO (testo a 1 colonna), 2) in formato TEXT LAYOUT (.txt) utilizzando il convertitore dell office installato nel caso di EXTIMPO2 (testo a n colonne), - Copia in QTEMP dalla libreria ICA$BAS il file source di lavoro per l esecuzione batch dell FTP (RTFFILE) che serve per trasferire il documento dal file system ad un membro di file source. Nel membro FTPCMD1 del file RTFFILE vengono modificati : 1) il record n. 1 del membro source relativo all username e passord abilitato all'ftp (i cl forniti utilizzano come username ICAROFTP con password ICAROFTP). La modifica è effettuata con la routine TXTTOPCX. ICARO Guida Programmatore 3-17 Gestione documenti

56 2) Il record numero 3 inerente l istruzione PUT dell FTP. Viene inserito sia il nome dell oggetto trasferito nella cartella \icarowrk che il nome del file source (EXPORT) e del membro (EXPORT) della libreria di lavoro WICAxxxxx dove sarà trasferito il documento. - Lancio dell FTP per trasferire il documento dalla directory del file system \icarowrk al file source EXPORT residente nella libreria di lavoro dell utente WICAxxxxxx. L FTP usa come input il membro source FTPCMD1 e come output di log FTPOUT che si trovano entrambi in QTEMP nel file RTFFILE. In caso di errori o di trasferimento non eseguito l utente può analizzare il file di log per verificare i motivi delle anomalie. Poiché il file di log (FTPOUT è nella qtemp per visualizzarlo occorre non chiudere la sessione ma eseguire prima RICH SYS con codice 2 e dalla riga comandi eseguire DSPPFM QTEMP/RTFFILE MBR(FTPOUT). A questo punto correggere gli eventuali errori nel CL EXTIMPO ricompilare e lanciare. Per problemi nell esecuzione verificare: - che la cartella ICAROPGM e la cartella di lavoro ICAROWRK siano presenti nel sistema sotto la root IFS (Operation navigator) e con autorizzazione pubblica; le cartelle \Icaropgm e \icarowrk devono essere condivise (Operation navigator) con autorizzazione Lettura/Scrittura. - che sulla stazione di lavoro sia stato eseguito il setup contenuto nella cartella \icaropgm\txtconv2000, se si usa l office 2000 Microsoft, o \icaropgm\txtconv97 se si usa l office 97 Microsoft entrambi installati in ambiente WINDOWS NT o 2000 (vedi Guida utente capitolo 2) - Verificare di avere installato nell office (Microsoft word) le opzioni di filtro e conversione documenti usati dal programma TXTCONV per convertire i documenti. - Che sia stato definito nell as400 il profilo utente ICAROFTP con password ICAROFTP abilitato alle funzioni operative dell FTP (salvo modificare i programmi CL EXTIMPO/EXTIMPO2 contenuti nella libreria ICA$xxx e qui ricompilati. - Che da una riga comandi della stazione di lavoro venga accettato il comando STRPCO e successivamente STRPCCMD. - Che il TCP/IP sia attivo insieme al servizio FTP avviati nell as400 alle IPL - Il contenuto del membro source FTPOUT del file RTFFILE registrato dopo l errore nella libreria QTEMP della sessione di lavoro per verificare eventuali errori nella esecuzione dell FTP. - Se dopo l'importazione il documento dovesse apparire vuoto o danneggiato nel subfile di scelta righe da importare verificare che il documento originale non sia danneggiato (aprirlo con il word e salvarlo con un altro nome nel formato Text With Layout (.ans) e verificare con il NOTEPAD se il contenuto é vuoto o contiene anomalie. In questo caso il problema è nell Office. N.B. I programmi EXTIMPO ed EXTIMPO2 eventualmente modificati vanno compilati nella libreria della bancca dati di competenza (ICA$xxx) Gestione documenti 3-18 ICARO Guida Programmatore

57 Esportare a PC: EXTEXPO Il programma CL EXTEXPO consente all'utente di esportare un documento ICARO in un file.txt.doc.rft o HTML su un PC collegato via Client Access/400 o su un disco di rete. Il file verrà creato con il nome e nella directory scelta dall utente rispondendo a finestre windows. Il programma CL può essere adattato per particolari esigenze utente. Il source si trova nella libreria ICA$BAS nel file EXAMPLE. Questo source eventualmente modificato deve essere trasferito insieme al programma compilato nella libreria ICA$xxx della banca dati relativa. Il programma CL EXTEXPO esegue queste funzioni: - Pulisce il testo del membro source EXPORTW (file EXPORT della libreria WICAxxxx) da eventuali attributi colore e caratteri speciali e crea il membro EXPORT. Exportw al momento dell esecuzione di EXTEXPO contiene le righe selezionate del documento ICARO da esportare. - Il membro source EXPORT (libreria WICA$xxxx) viene convertito con la routine richiamata TXTTOPC1 (vedi capitolo 11) in un membro source nella qtemp con gli attributi e le marginature del documento in formato.txt o.doc o.html. - La routine TXTTOPC1 provvede anche ad eseguire l FTP per trasferire il membro source creato (.doc,.txt ecc..) dalla qtemp al file sistem \icarowrk dell AS400 con il nome wicaxxxxxx.doc o wicaxxxx.txt ecc.. corrispondente al nome univoco della sessione di lavoro. L FTP è eseguito con il profilo ICAROFTP e password ICAROFTP per cambiare utente o password modificare il nome del profilo in EXTEXPO e compilare il programma nella libreria della banca dati ICA$xxxx. Eventuali errori durante l FTP o anomalie sono registrate nella QTEMP nel file RTFFILE membro FTPOUT. - Viene eseguito dalla directory \sysas400\icaropgm il programma COPIA.exe che chiederà all utente, con finestre Windows, la path di destinazione ed il nome da assegnare al documento in esportazione. In caso di problemi nell esecuzione effettuare le stesse verifiche descritte per EXTIMPO/EXTIMPO2 I source ed il programma oggetto EXTEXPO devono risiedere nella libreria ICA$xxx della banca dati relativa. ICARO Guida Programmatore 3-19 Gestione documenti

58 Tre metodi di trasferimento documenti ICARO in documenti Pc Soluzione a) azione interattiva. Visualizzando un documento ICARO è possibile trasferire con l'opzione F22 direttamente il documento (le righe selezionate) nel PC utente in formato TXT word html con il mantenimento delle marginature Per tale funzione è necessario: a) Leggere le note Guida del Programmatore capitolo 3 pag. 17 o Guida utente capitolo 10 pag.18. b) Duplicare se necessario i pgm EXTIMPO, EXTIMPO2 ed EXTEXPO da ICA$FIL alla libreria ICARO interessata (ICA$xxx). Di questi pgm esistono i source nel file EXAMPLE di ICA$BAS per eventuali personalizzazioni. Soluzione b) azione interattiva. Visualizzando uno o più documenti ICARO è possibile trasferire (opzione F22) le parti o tutto il documento in vari membri source (ogni documento un nome di membro); con l'opzione Menù Office (nuova funzione): 1. Gestione documenti 2. Ricerca e stampa documenti 3. Gestione di tabelle 4. Aggiorna indici banca dati 5. Menu gestione dizionario 6. Richiamo OFFICE 7. Definizione ICARO e banche dati 8. Riorganizzazione banche dati 9. Menù gestione etichette Scegliere l'opzione 6 e quindi l'opzione 3 Esporta membro in formato ASCII, HTML, o RTF. Dalla maschera seguente un membro o tutti i membri (*ALL) di un file source possono essere trasferiti o in formato HTML, RFT, o ASCII in una directory di un sistema con l'ftp server ( ad esempio in una root dell'as/400) accessibile da un PC con il word ecc... Le marginature, i grassetti e le sottolineature di ICARO sono mantenute.: Gestione documenti 3-20 ICARO Guida Programmatore

59 Soluzione c) trasferimento batch di un documento ICARO mantenendo gli attributi Capitolo 11 pagina 5 e poi pagina 3 del manuale Guida per il programmatore. Con l'api DOCTOMBR è possibile prima trasferire un documento ICARO in un membro di file source e con l'api TXTTOPC1, successivamente, è possibile trasferire in HTML, RTF o ASCII il membro in un file PC. Leggere anche le note a pagina 4 del capitolo 11. Importare un membro di file sorgente: TEXT15T La routine TEXT15T converte un membro di file sorgente (per es. del Text Management o di qualsiasi file source) in un membro sorgente nella QTEMP (lunghezza massima del record 268) con gli attributi di HI (alta intensità) e UL (sottolineato) convertiti in formato ICARO. In questo modo può essere quindi trasferito in un campo variabile di ICARO. Per richiamare la routine e creare il file eseguire le istruzioni seguenti: - ovrdbf per il membro sorgente (per es. del Text Management) OVRDBF FILE(QTXTSRC) TOFILE(libreria nome/nome file) MBR(nome membro) LVLCHK(*NO) SECURE(*YES) - creare un file di lavoro vuoto CRTSRCPF FILE(QTEMP/ICASRCF) RCDLEN(268) MBR(*FILE) MONMSG MSGID(CPFØØØØ) EXEC(CLRPFM FILE(QTEMP/ICASRCF)) CALL PGM(ICA$BAS/TEXT15T) PARM(&MARGINMIN) MONMSG MSGID(CPFØØØØ) EXEC(GOTO CMDLBL(......)) I parametri di TEXT15T sono i seguenti: &MARGINMIN 3 num. valore minimo del margine sinistro. Questo valore viene restituito dalla routine ed indica la colonna iniziale di testo con il valore più basso nel documento originale. Dopo l'esecuzione il file QTEMP/ICASRCF contiene il file convertito. ICARO Guida Programmatore 3-21 Gestione documenti

60 Importare un documento office in un file ICARO: TEXT16T La routine TEXT16T converte un documento office in un membro sorgente nella libreria QTEMP (lunghezza massima del record 268) con gli attributi di HI (alta intensità) e UL (sottolineato) convertiti in formato ICARO. In questo modo può essere quindi trasferito in un paragrafo di ICARO (per es. usando un programma specifico). Per richiamare la routine e creare il file eseguire le istruzioni seguenti: - Stampare il documento in un file di output PRTDOC DOC(nome_documento) FLR(nome_folder) OPTIONS(*OUTFILE) OUTFILE(QTEMP/ICAROFILE) OUTMBR(*FIRST *REPLACE) OUTDTATYP(*ALL) MONMSG MSGID(CPFØØØØ) EXEC(segnale_errore) - ovrdbf del documento stampato su disco: OVRDBF FILE(ICAROFILE) TOFILE(QTEMP/ICAROFILE) LVLCHK(*NO) - creare un file di lavoro vuoto: CRTSRCPF FILE(QTEMP/ICASRCF) RCDLEN(268) MBR(*FILE) MONMSG MSGID(CPFØØØØ) EXEC(CLRPFM FILE(QTEMP/ICASRCF)) CALL PGM(ICA$BAS/TEXT16T) PARM(&MARGINMIN) MONMSG MSGID(CPFØØØØ) EXEC(GOTO CMDLBL(......)) I parametri di TEXT16T sono i seguenti: &MARGINMIN 3 num. valore minimo del margine sinistro. Questo valore viene restituito dalla routine ed indica la colonna iniziale di testo con il valore più basso nel documento originale. Dopo l'esecuzione il file QTEMP/ICASRCF contiene il documento office convertito. Gestione documenti 3-22 ICARO Guida Programmatore

61 Capitolo 4. Leggere un campo o paragrafo Applicazioni specifiche richiedono di avere la disponibilità del contenuto di un campo formattato o di un paragrafo di un documento della banca dati. Esistono diverse routine per la lettura dei campi. Lettura di un campo formattato: TEWSFFF La routine TEWSFFF consente di ricevere in una variabile il valore di un campo formattato letto dal file effettivo TEXRAAA o da un file di lavoro TEWRAAA (quando i documenti sono in revisione o aggiornamento). Comando: CALL ICA$BAS/TEWSFFF (&DBNR &HDR &FIELD &NDOC &LEVEL + &RTNVL1 &RTNVL2 &LAST) I parametri di TEWSFFF sono i seguenti: &DBNR 3 num. Campo numerico di tre cifre indicante il codice della banca dati. &HDR 1 car. Deve contenere il carattere '1' se si desidera ricevere nel campo RTNVL1 l'intestazione del campo; Deve contenere il carattere '2' se non si desidera ricevere l'intestazione del campo (&RTNVL1 è lasciato vuoto). Deve contenere 4 se il campo numerico (data o numero) venga editato con allineamento a destra nei primi 21 crt del campo RTNVL2 &FIELD 3 num. Campo numerico di tre cifre contenente il codice del campo formattato di cui si desidera ricevere il contenuto nel parametro &RTNVL2 &NDOC 7 num. &LEVEL 3 num. &RTNVL1 40 car. &RTNVL2 256 car. &LAST 3 num. Immettere il riferimento del documento. Immettere Ø se il contenuto del campo va letto nel file effettivo dei campi formattati TEXRAAA; 'un numero di livello' (>Ø) se bisogna leggere da TEWRAAA. Ritorna con l'intestazione del campo così come definitonei campi formattati. Ritorna con il contenuto del campo (giustificato a sinistra) Attenzione, i campi numerici sono riportati normalizzati a 15 cifre e la 16^ contiene il segno negativo (-) per i numeri negativi. Se &HDR = 4 il campo numerico editato si trova allineato a destra nei primi 20 crt ed il 21.mo crt conterrà l eventuale segno negativo (-). Ultima posizione non blank del campo RTNVL2. Nota: Il primo richiamo della routine TEWSFFF lascia aperti i file utilizzati. Quando l'utente non deve più leggere campi dalla banca dati, deve chiudere la routine richiamandola dopo avere impostato il valore del campo FIELD a 999 per chiudere tutti i file aperti. ICARO Guida Programmatore 4-1 Leggere un campo

62 Lettura campo variabile (2000 o 9999 caratteri): TEWSPPP/TEWSPP9 La routine TEWSPPP consente di ricevere in una stringa di 2000 caratteri i primi 2000 caratteri consecutivi e normalizzati di un paragrafo letto o dal file effettivo TEXDAAA o da un file di lavoro TEWDAAA (se il documento è in revisione o in aggiornamento). Per normalizzato si intende che i caratteri blank superflui sono eliminati e abbreviati in un solo blank. La routine TEWSPP9 opera in modo analogo, ma consente di trasferire sino a 9999 caratteri consecutivi normalizzati di un paragrafo. Comandi: CALL ICA$BAS/TEWSPPP (&...parametri...) oppure CALL ICA$BAS/TEWSPP9 (&...parametri...) I parametri sono identici in entrambe le routine: &DBNR 3 num. &PARA 3 num. &NDOC 7 num. &LEVEL 3 num. Campo numerico indicante il codice della banca dati. Campo numerico contenente il codice del paragrafo. Immettere il riferimento del documento. Immettere Ø se il contenuto del campo va letto nel file effettivo dei campi formattati TEXDAAA;'un numero di livello qualsiasi' (>Ø) se bisogna leggere da TEWDAAA. &TEXT 2000 Stringa di 2000 caratteri (per TEWSPPP) oppure 9999 Stringa di 9999 caratteri (per TEWSPP9). Riceve il contenuto del testo normalizzato per una lunghezza massima indicata nel parametro &MAXCHR. &MAXCHR 5 num. Numero massimo di caratteri da leggere e trasferire da questo campo: per es. 150, 500,.(il massimo è 2000 per TEWSPPP o 9999 per TEWSPP9). Dopo l'esecu-zione, &MAXCHR conterrà il numero massimo dei caratteri effettivamente trasferiti e che saranno riportati nel parametro &TEXT (per es. 123 se il valore è inferiore al massimo voluto). &CHR 1 car. Carattere speciale di contrassegno dopo il quale deve essere recuperata la stringa TEXT. Banche dati specifiche utilizzano costanti di input quali 'Titolo.:' come parte dell'informazione (e non come costanti di intestazione di campo protetto). Se il carattere &CHR è ':' la costante 'Titolo.:' non sarà inclusa nella stringa TEXT. &CHRSTR 3 num. Posizione massima, dall'inizio paragrafo, entro cui deve trovarsi lo speciale carattere di contrassegno &CHR. Se non viene trovato entro questo limite, allora il campo sarà recuperato dalla prima posizione del carattere. &SPLCHR 1 car. Indicare '1' se nella stringa di caratteri recuperati si intende includere gli speciali caratteri ICARO trovati nel testo: simboli di fine/inizio frase, inizio/fine termini da indicizzare, caratteri da non visualizzare... Blank per escludere questi caratteri speciali. Nota: Il primo richiamo della routine TEWSPPP o TEWSPP9 lascia aperti i file utilizzati. Quando l'utente termina di leggere paragrafi dalla banca dati, deve chiudere la routine TEWSPPP/TEWSPP9 richiamandola dopo avere impostato il valore del campo &PARAG a 999 per chiudere tutti i file aperti. Leggere un campo 4-2 ICARO Guida Programmatore

63 Lettura campo variabile (senza limite di lunghezza): TEWSOOO La routine TEWSOOO legge, una riga per volta, tutto il contenuto di un campo variabile o paragrafo, in una stringa di 256 caratteri per riga. TEWSOOO legge dal file effettivo TEXDAAA o da un file di lavoro TEWDAAA (se il documento è in revisione o in aggiornamento). Comandi: CALL ICA$BAS/TEWSOOO (&...parametri...) I parametri di TEWSOOO sono i seguenti: &DBNR 3 num. &PARA 3 num. &NDOC 7 num. &LEVEL 3 num. &TEXT 256 car &FLAG 1 car. &SPLCHR 1 car. Campo numerico indicante il codice della banca dati. Campo numerico contenente il codice del paragrafo. Immettere il riferimento del documento. Immettere Ø se il contenuto del campo va letto nel file effettivo del testo TEXDAAA; o un numero di livello qualsiasi' (>Ø) se il contenuto del campo va letto nel file dell'area di lavoro TEWDAAA. Al primo richiamo della routine la prima riga del paragrafo viene riportata nel parametro &TEXT. I richiami successivi (ripetendo gli stessi parametri &DBNR, &PARA, &NDOC, &LEVEL) trasferiranno ogni riga successiva del campo (vedi il campo FLAG). Quando viene richiamata la routine TEWSOOO, il parametro &FLAG deve essere impostato a: 1 per posizionare la lettura alla prima riga di paragrafo 2 per proseguire la lettura con le successive righe F per chiudere la routine TEWSOOO e i file aperti. Al ritorno dalla routine, TEWSOOO riporterà il parametro &FLAG con i seguenti valori: 3 fine del paragrafo, non ci sono altre righe E banca dati errata, documento non trovato o parametri, alla seconda chiamata '2', differenti dalla precedente. Indicare '1' se nella stringa di caratteri recuperati si intende includere gli speciali caratteri ICARO trovati nel testo: simboli di fine/inizio frase, inizio/fine termini da indicizzare, caratteri da non visualizzare... Nota: Il primo richiamo della routine TEWSOOO lascia aperti i file utilizzati. Quando l'utente non deve più leggere paragrafi dalla banca dati, deve chiudere la routine TEWSOOO richiamandola dopo avere impostato il valore del campo &FLAG a 'F' per chiudere tutti i file aperti. ICARO Guida Programmatore 4-3 Leggere un campo

64 Lettura delle righe di intestazione di un paragrafo: RTVINPAR La routine RTVINPAR consente di ricevere in tre campi distinti le tre righe di intestazione, nella lingua desiderata, definite per un paragrafo di una banca dati. Comando:CALL ICA$BAS/RTVINPAR (&...parametri...) I parametri sono : &DBNR 3 num. Campo numerico indicante il codice della banca dati. &PARA 3 num. Campo numerico contenente il codice del paragrafo di cui si desidera la lettura delle intestazioni. &LINGUA 1 alfa Codice lingua ( 1 Italiano 2 inglese...) &INT1 79 alfa Campo in cui, dopo l esecuzione si riceverà la prima riga di intestazione. &INT2 79 alfa Campo in cui, dopo l esecuzione si riceverà la seconda riga di intestazione. &INT3 79 alfa Campo in cui, dopo l esecuzione si riceverà la terza riga di intestazione. &FLAG 1 alfa lasciare blank al primo richiamo: Il programma sarà attivo finche non si fà una chiamata con FLAG impostato ad F Leggere un campo 4-4 ICARO Guida Programmatore

65 Invertire un campo arabo: ARAB I campi arabi sono memorrizzati su disco in forma invertita (speculare). La routine ARAB consente al programma utente di invertire un campo formattato o una riga del paragrafo ai fini della visualizzazione. Comandi: CALL ICA$BAS/ARAB (&LENGTH &STRING) I parametri di ARAB sono i seguenti: &LENGTH 3 num. numero dei caratteri da invertire. &STRING 256 car. STRING conterrà la stringa da invertire e dopo il richiamo della routine conterrà il contenuto della riga/campo in forma speculare. Nota: Il numero dei caratteri invertiti nel campo &STRING è assegnato dal parametro &LENG: si può invertire una substringa. Per esempio: valore &LENG: 10 &STRING: 'A BCDE' dopo l'esecuzione della routine: &STRING sarà: ' ABCD in quanto l'inversione ha riguardato i primi 10 caratteri. ICARO Guida Programmatore 4-5 Leggere un campo

66 Pagina vuota Leggere un campo 4-6 ICARO Guida Programmatore

67 Capitolo 5. Altre routine Controllo termini di un campo o di righe di testo TEXT21R La routine TEXT21R consente di assoggettare ad un controllo lessicale una o più righe di testo di un paragrafo o il contenuto alfabetico di un campo formattato. Prima di richiamare la routine, eseguire quanto segue: - CALL ICA$BAS/CRTAUTUSE (se non è stato eseguito) - CRTPF FILE(QTEMP/ERRORI) RCDLEN(67) (se il file non esiste) - OVRDBF TEWRAAA ICA$xxx/TEWRAAA (dove xxx è il codice di banca dati) - OVRDBF TABLE ICA$BAS/TABLEn (dove 'n' è il codice della lingua: 1=Italiano 2=Inglese,...il file 'TABLEn' contiene, nella lingua selezionata, la descrizione delle anomalie) - OVRDBF DIZAUT ICA$xxx/DIZAUT (dove xxx è il codice della banca dati su cui eseguire il controllo sull' authority list) - OVRDBF DIZBASEA ICA$xxx/DIZBASEA (dove xxx è il codice di banca dati) - OVRDBF DIZBASE ICA$xxx/DIZBASE (dove xxx è il codice di banca dati). Per ciascuna riga o per ciascun campo, la routine TEXT21R può essere richiamata con i seguenti parametri: &TEXT 257 car. Testo alfabetico di 257 caratteri. Questo campo è impostato dall'utente e deve contenere la riga o il testo del campo da controllare &QTERR 3 num. E' restituito con il numero di errori trovati &FIELD 3 num. Immettere di codice del paragrafo ( ) o il codice del campo formattato, incrementato di 256 (da 257 a 511), controllato. &ABBREV 6 car. In questo campo l'utente deve immettere una descrizione abbreviata del campo (AUTORE, TITOLO...) che sarà registrato come identificativonel file errori (QTEMP/ERRORI) &MAXLEN 3 num. Numero massimo di caratteri immessi dall'utente nel primo parametro TEXT: ultima posizione a destra non blank &LESSIC 1 car. Indicare 'Y' per controllare ciascun termine nel dizionario &AUTLIS 1 car. Indicare '1' per controllare se ciascun termine deve trovare riscontro nell'authority list (associato al codice campo &FIELD) &STATUS 1 car. blank è impostato dall'utente per default 'F' per completare la routine e chiudere i file aperti ICARO Guida Programmatore 5-1 Altre Routine

68 La routine restituisce il campo &STATUS con uno dei seguenti valori: 'W' se vengono incontrati errori di attenzione (warning) 'T' se viene incontrato un errore grave &NEWLIN 1 car. La routine lo restituisce al valore '1' se si verifica la seguente condizione: - il codice è relativo ad un paragrafo e la riga termina con un simbolo troncamento parola (-) come ultimo carattere a destra (o primo carattere a sinistra se arabo) e bisogna passare la riga successiva per completare l'intero termine. &BIDI 1 car. '1' se il campo è LTR standard Nota: la riga termina a sinistra per campi BIDI. '2' se il campo è BIDI (bidirezionale scrittura RTL) Se si assoggetta a controllo un paragrafo occorrerà chiamare n volte la routine TEXT21R per quante sono le righe di un paragrafo. Se l'ultima riga di un paragrafo termina con il simbolo '-' (il campo NEWLIN è restituito con '1'), bisogna richiamare la routine passando la successiva riga (campo &TEXT) a blank e il valore 999 per il parametro &FLDPAR ciò al fine di chiudere correttamente il controllo del campo/paragrafo. Fine di un documento Dopo aver convalidato tutti i campi e tutte le righe di un documento, l'utente può visualizzare, stampare o salvare gli errori memorizzati nel file QTEMP/ ERRORI. Il formato del file ERRORI (record lungo 67 bytes) è il seguente: *DS ERROR LINES *ERRORF = identificazione abbreviata di campo (&ABBREV) *ERRORT = tipo errore: W=warning (attenzione) T=terminal (grave) *ERRORD = descrizione errore IERROR DS I 1 6 ERRORF I 7 7 ERRORT I 8 67 ERRORD Inizio di un documento Ad ogni apertura di documento, il programma utente deve eseguire la pulizia del file ERRORI previa chiusura e apertura del file: CLOSE QTEMP/ERRORI CLRPFM QTEMP/ERRORI OPEN QTEMP/ERRORI Dopo questa operazione di pulizia del file, per ciascun campo o riga di paragrafo può essere richiamata la routine di controllo ed il file ERRORI conterrà le anomalie dei campi del nuovo documento. Altre Routine 5-2 ICARO Guida Programmatore

69 Accesso a tabelle di riferimento ICARO: TEXT17 Se da un programma utente (per es. EXTHF o EXTHP) si desidera visualizzare e scegliere elementi da una tabella, richiamare la routine TEXT17 con il comando: CALL ICA$BAS/TEXT17 (&DBNR &CODE &TEXT &LANG &FLAGA) I parametri di TEXT17 sono i seguenti: &DBNR 3 num. &CODE 8 car. Codice della banca dati Nome della tabella (2 caratteri) e nome iniziale di elemento (max 6 caratteri) Se il parametro &CODE è lasciato vuoto (blank), verrà mostrata prima la lista delle tabelle per la selezione. Il nome dell'elemento può essere dato per intero ocome sub stringa, es.: se esiste una tabella TS ed il parametro &CODE è fissato su 'TSLA', l'utente potrà selezionare dalla lista uno dei nomi di elementi che iniziano con 'LA...' nella tabella TS. L'intero codice dell'elemento sarà restituito a completamento della routine. &TEXT 79 car. Descrizione dell'elemento di tabella restituito a completamento della routine. &LANG 1 car. Numero di codice della lingua per la visualizzazione delle intestazioni (1=italiano, 2=inglese ecc.). &FLAGA 1 car. Indicare 'A' se si desidera effettuare il controllo dell'autorità utente nell'uso della tabella. Lasciare vuoto (blank) per permettere la visualizzazione di tutte le tabelle esistenti. Prima di richiamare la routine TEXT17, verificare che nella CURLIB vi sia già il nome della libreria della banca dati (ICA$nnn) e che sia attivo il comando OVRDSPF TEXDSPF ICA$BAS/TEXDSPFx (dove x indica il codice della lingua di dialogo). Duplica batch di una tabella di riferimento ICARO: DUPTAB Per duplicare una tabella da un applicativo utente eseguire: CALL ICA$BAS/DUPTAB (&DBI &DBO &TABI &TABO &REPLACE &FLAG) in cui : &DBI 3 *char Codice banca dati che contiene la tabella da duplicare &DBO 3 *char Codice banca dati di arrivo &TABI 2 *char Codice tabella da duplicare da &DBI &TABO 2 *char Codice da assegnare alla tabella in &DBO &REPLACE 1 *char Y Ammessa sostituzione N Non ammessa sostituzione se la tabella &TABO esiste in &DBO &FLAG 1 *char Codice ritorno: 1= Banca dati &DBI errata 2= tabella &DBI blank 3= Banca dati &DBO errata 4= tabella &DBO blank 5= &DBI &TABI = &DBO &TABO 6= tabella esiste in &DBO ICARO Guida Programmatore 5-3 Altre Routine

70 Accesso alla lista di banche dati autorizzate: TEX05A La routine TEX05A può essere richiamata se da un'applicazione utente si desidera visualizzare la lista delle banche dati autorizzate per effettuare una scelta di banca dati da gestire. Si richiama la routine TEX05A mediante il seguente comando: CALL ICA$BAS/TEX05A (&USER &LIST &DBNR) I parametri di TEX05A sono i seguenti: &USER 10 car. Nome utente &LIST 3 car. Indicare il codice '010' per richiedere la lista di banche dati AUTORIZZATE per l'attività di 'Gestione documenti'. Indicare '011' per richiedere la lista di banche dati AUTORIZZATE per l'attività di 'interrogazione e stampa dei documenti'. &DBNR 3 num. Ritorna il codice della banca dati selezionata. Prima di richiamare la routine TEX05A verificare che la libreria (ICA$BAS) sia stata aggiunta alla lista delle librerie (ADDLIBLE ) e che sia stato eseguito il comando OVRDSPF TEXDSPF ICA$BAS/TEXDSPFx (dove x indica il codice della lingua di dialogo). Reperire il codice di lingua di un utente: RTVLANGU La routine RTVLANGU permette di ritrovare il codice della lingua memorizzato nel profilo di un utente (si veda l'opzione 'Gestione profilo utente'). Comando: CALL ICA$BAS/RTVLANGU (&USER &LANG &ERROR) I parametri di RTVLANGU sono i seguenti: &USER 10 car. Nome utente &LANG 1 car. Conterrà il codice della lingua (da 1 a 9) dell'utente a completamento della routine. &ERROR 1 car. Ritorna 'N' se non esiste il profilo utente nella applicazione ICARO oppure ritorna 'blank' se il profilo è stato trovato. Altre Routine 5-4 ICARO Guida Programmatore

71 Allocare/bloccare una banca dati: LCKDB Se è necessario inibire l'accesso di utenti alla gestione interattiva di documenti, è necessario richiamare la routine LCKDB. Se lavori specifici richiedono che nessun utente lavori interattivamente con documenti (opzione 1 Menu Principale) eseguire il seguente comando: CALL ICA$BAS/LCKDB (&DBNR &ACTION &RTN) I parametri di LCKDB sono i seguenti: &DBNR 3 car. Codice della banca dati &ACTION 1 car. Codice azione : 1 bloccare la banca dati 2 sbloccare e rendere utilizzabile la banca dati. &RTN 1 car. Ritorna il codice 'E' se si riscontra un errore (es. banca dati inesistente). Verifica dei lavori attivi in una banca dati: TESTJOB Se prima di avviare un lavoro batch o interattivo per una banca dati, l'utente desidera conoscere se vi sono lavori attivi, la routine TESTJOB consente di ottenere l'informazione sullo stato della banca dati attraverso un codice di ritorno: CALL ICA$BAS/TESTJOB (&DBNR &RTN) I parametri di TESTJOB sono i seguenti: &DBNR 3 num. Codice della banca dati &RTN 1 car. Codice di ritorno: Blank nessun lavoro attivo 1 documenti in aggiornamento 2 o 3 re-indicizzazione in corso 4 pulizia area di lavoro 5 salvataggio in corso 6 ripristino in corso 7 riorganizzazione in corso 8 compilazione banca dati in corso 9 definizione o modifica della struttura della banca dati in corso D cancellazione banca dati in corso P Eliminazione documenti in corso, clear banca dati U utente collegato in gestione documenti T documenti in aggiornamento K documenti in attesa di aggiornamento nell'area di lavoro (nei file TEWDAAA e TEWRAAA) ICARO Guida Programmatore 5-5 Altre Routine

72 Rilasciare le librerie di lavoro utente WICA000xxx: INQDLTSP Se un utente avvia una sessione ICARO (CRTAUTUSE), viene creata la libreria lavoro WICA000xxx (dal modello WICA$W). Questa area di lavoro, associata al JOB, rimane attiva fino a che il job non viene chiuso con signoff. Per disallocare l area di lavoro necessita, IMMEDIATAMENTE prima del SIGNOFF eseguire la funzione CALL ICA$BAS/INQDLTSP ( ) viceversa l area resterà allocata al lavoro chiuso. La libreria di lavoro rimane attiva se l'utente, chiudendo una chiamata ad un lavoro ICARO, ritorna a un menu AS/400 o al programma chiamante. La libreria di lavoro utente WICA000xxx è disallocata e resa disponibile ad altri utenti se: - l'utente si scollega da ICARO (premendo F3) mentre lo switch di lavoro 8 è in posizione di off (comando CHGJOB ); il valore 0 di questo switch è quello di default se l'utente si è collegato al menu principale ICARO con il comando: CALL ICA$BAS/TEXMAN o TEXMAN2. Infatti con il valore SWITCH 8 a 0 il menu ICARO provvede ad eseguire la procedura INQDLTSP e SIGNOFF della sessione di lavoro. - Si avvia il sottosistema ICA$BAS/QICARO; All avvio del sottosistema viene avviato in automatico INQRSTSP che libera e rende disponibili le librerie di lavoro WICA000xxx rimaste aperte per chiusura anomala (relativi a JOB chiusi senza l esecuzione finale della procedura INQDLTSP). - E stato raggiunto il numero massimo di librerie di lavoro disponibili (opzione 10 menu definizione del prodotto ICARO). In questo caso viene eseguito INQDLTSP per quei lavori chiusi in modo anomalo. La routine INQDLTSP, prima di rilasciare la libreria, se il giornale delle interrogazioni è attivo, trasferisce i record dei files contenenti le domande formulate (durante la sessione di interrogazione (INQR e INQD)) in coda ai file storici delle domande INQR$ e INQD$ che si trovano nella libreria ICA$BAS. La routine INQDLTSP disalloca la libreria associata al terminale mentre la procedura INQRSTSP, avviata prima della procedura di salvataggio del giornale (vedi il sorgente SAVJRNL nel file ICA$BAS/EXAMPLE), provvede a disallocare tutte le librerie di lavoro di utenti non chiuse correttamente. Per verificare se l utente ha inserito il comando INQDLTSP in modo corretto in una sua applicazione che richiama funzioni ICARO (es. una funzione di interrogazione) occorre, durante l esecuzione del JOB, verificare qual è la libreria di lavoro WICA000xxx assegnata al lavoro (WRKLIB WICA* - il nome del lavoro e dell utente è visualizzato nella descrizione della libreria); Chiuso il lavoro, dopo pochi secondi, se la procedura INQDLTSP è stata avviata prima del SIGNOFF, la libreria deve essere disallocata (WRKLIB WICA* - la descrizione della libreria avrà valori blank) Altre Routine 5-6 ICARO Guida Programmatore

73 Visualizzazione di un membro di file sorgente: TEXMSGP Se una specifica applicazione richiede di mostrare l'help o un qualunque membro di file sorgente (per es. posto nel file help di ICARO -QMSGx- o in qualsiasi altro file), questo membro di file sorgente sarà mostrato utilizzando la routine TEXMSGP. Se si desidera visualizzare un membro eseguire: ADDLIBLE ICA$BAS CALL TEXMSGP (&FILE &MEMBER &LANG) I parametri di TEXMSGP sono i seguenti: (se non esiste nella lista delle librerie) &FILE 10 car. nome file sorgente &MEMBER 10 car. nome membro &LANG 1 car. codice lingua (1=italiano, 2=inglese, 3=tedesco, 4=francese ecc.). Il membro sarà dunque mostrato utilizzando la videata del file di visualizzazione prescelta. Nota: nel testo del membro il simbolo '?' è considerato attributo di alta luminosità; il simbolo '!' è considerato fine dell'attributo (quando il simbolo '!' è omesso, sarà evidenziata l'intera riga). Modifica righe di un Membro source: TXTTOPCX OVRDBF FILE(SOURCE) TOFILE(LIBR/FILESRC) MBR(MBR) (con il parametro TOFILE indicare il membro del file source da elaborare) CALL ICA$BAS/TXTTOPCX (&RECORD &DA &A &DATA) I parametri di TXTTOPCX sono i seguenti: &RECORD 5 0 num numero del record da elaborare &DA 3 0 num posizione iniziale del trasferimento nel record &A 3 0 num posizione finale del trasferimento nel record &DATA 256 caratt Stringa da trasferire da posiz. 1 Testare l ambiente di lavoro (Interattivo/Batch): TYPEJOB Richiamando la routine TYPEJOB è possibile sapere se l ambiente in cui si opera è batch o interattivo: ADDLIBLE ICA$BAS CALL TYPEJOB (&TYP) I parametri di TYPEJOB sono i seguenti: &TYP (se non esiste nella lista delle librerie) 1 car. Restituisce il carattere 1 se il job è interattivo 0 se batch. ICARO Guida Programmatore 5-7 Altre Routine

74 Marginare un testo : TEXT13CB Se si desidera utilizzare la routine di marginatura testo per marginare una stringa di caratteri (max 9 k) entro un margine destro, sinistro ed un rientro, richiamare la seguente routine: CALL ICA$BAS/TEXT13CB (&TEXT &MARSIN &MARDEX &RIENT &ALLIN &TIPCAL &NUMLIN &CLOSE) I parametri di TEXT13CB sono i seguenti: &TEXT 9999 car. una schiera contenente max 9999 caratteri da marginare. Su questa stessa schiera sarà restituito il testo marginato. &MARSIN 3 0 num campo numerico di 3 cifre che esprime il margine &MARDEX 3 0 num sinistro. campo numerico di 3 cifre che esprime il margine destro. &RIENT 3 0 num campo numerico di 3 cifre che esprime il rientro sinistro. &ALLIN 1 car. Y o N a seconda se si desidera marginare le parole a destra con inserimento di blank. &TIPCAL 1 car. valore blank. &NUMLIN 7 0 num campo numerico di 7 cifre in cui viene restituito il numero di righe finali calcolato dopo la marginatura. &CLOSE 1 car. passare il valore F per chiudere la routine. Nella schiera &TEXT verrà restituita la stringa dei caratteri marginati. La prima riga restituita avrà, in ampiezza, una dimensione in caratteri pari a : ((Marg.destro Margine sinis) - (+/- rientro paragr)) +1 e le successive righe avranno tutte un ampiezza in caratteri: (Marg.destro Margine sin ) + 1 Il campo &NUMLIN esprime il numero di righe di testo calcolate compreso la prima. Pertanto &TEXT restituirà, per ciascuna riga, i caratteri netti che la compongono (ovvero senza i blank a sinistra del margine sinistro); sarà cura del programmatore trasferire, nei suoi campi, le righe calcolate a partire dal margine sinistro desiderato. Altre Routine 5-8 ICARO Guida Programmatore

75 Capitolo 6. Caricare/scaricare una banca dati I documenti sono caricati/scaricati da/a file, usando il formato TEWLOG (vedi il file sorgente EXAMPLE della libreria ICA$BAS). a) Caricare documenti via batch La routine ADDDOC consente all'utente di caricare documenti. Prima di richiamare la routine, deve essere creato il file di input secondo la struttura TEWLOG appresso descritta: Se si desidera creare una struttura vuota per registrarvi i documenti da caricare in una banca dati, duplicare da ICA$FIL il file TEWLOG (es. FILEINP in QGPL) CRTDUPOBJ OBJ(TEWLOG) FROMLIB(ICA$FIL) OBJTYPE(*FILE) + TOLIB(QGPL) NEWOBJ(FILEINP) Procedura interattiva: Immettere il comando: CALL ICA$BAS/ADDDOC ICA400 Caricamento documenti File di input (formato TEWLOG) Libreria Banca dati di destinazione Codice di aggiornamento _ (F4=Lista) (A=Add R=Replace) Si consiglia di fare un backup prima di eseguire un caricamento batch. Usare l'opzione 5 del menu RGZICA. Il profilo utente deve essere autorizzato a lavorare con i documenti. A lavoro concluso, controllare gli errori nella coda di stampa. F3=Esci F4=Banche dati disponibili Appare la videata ICA400. Completare i campi: - File di input (formato TEWLOG) Nome del file (con formato TEWLOG o simile) contenente i documenti da caricare - Libreria Inserire il nome della libreria contenente il file (o la libreria della banca dati ICA$xxx se si fa riferimento al file di giornale collegato alla banca dati -TEWLOG) - Banca dati di destinazione Codice della banca dati ICARO di destinazione, per es. 001, 234,.in cui saranno aggiunti o sostituiti i documenti. - Codice di aggiornamento R Per sostituire i documenti della banca dati con quelli del file rispettando lo stesso valore di numero documento (la stessa posizione sequenziale nel file) espresso dal valore del campo JOUDOC. ICARO Guida Programmatore 6-1 Caricare/Scaricare una Banca dati

76 'R' consente all'utente, tramite il numero di documento, copiare documenti da altre banche dati mantenendo gli stessi numeri di documento. 'R' sarà usato per recuperare aggiornamenti di banche dati dal file di giornale (dove il numero di documento deve essere preservato per evitare versioni multiple). Se una banca dati è danneggiata, può essere recuperata partendo dall'ultimo backup valido e poi aggiornata (codice di aggiornamento 'R') con i successivi file di giornale. Usare 'R' se il file di giornale TEWLOG è utilizzato per aggiornare banche dati simili (localizzate su diversi sistemi): i numeri di documento saranno allora gli stessi nelle diverse banche dati. A Aggiungere. I documenti del file TEWLOG saranno aggiunti ai documenti della banca dati (il campo TEWLOG è trascurato) a partire dal primo numero disponibile. 'A' sarà normalmente usato quando nuovi documenti devono essere caricati nella banca dati tramite un file creato da uno specifico programma di input dell'utente. Se un numero di documento è indicato nel file di input, sarà ignorato. L'indicizzazione dei documenti sarà eseguito automaticamente alla fine della procedura ADDDOC per la modalità REPLACE. Per la modalità ADD l aggiornamento indici automatico avverrà se nella definizione della banca dati è stata scelta l opzione 1 nella voce Aggiornamento indici documenti. Al contrario l utente, per aggiornare i documenti, dovrà eseguire la procedura SUBAGDOC o TEXUPDOC o scegliere l opzione 4 dal menu pricipale. Dopo l ADDDOC ogni record di testa (Tipo 0) riporterà nelle col del campo JOUDES il numero documento ICARO modificato/caricato. Procedura batch Immettere: CALL ICA$BAS/ADDDOCB (&LIB &FILE &MODE &DBNR) I parametri di ADDDOC sono i seguenti: &LIB 10 car. Libreria del file di input &FILE 10 car Nome del file di input &MODE 1 car Modo caricamento (A=aggiungere; R=rimpiazzare) &DBNR 3 car. Codice banca dati es. '001' &Mode viene restituito, in caso di anomalia, con i seguenti valori: 1 Per utente non autorizzato 2 Per libreria o nome file di Input errati o non trovati 3 Valore &MODE errato; non è R o A 4 Codice banca dati errato o banca dati non disponibile 5 Lavori vincolanti nella banca dati di emissione; Riprovare dopo; (es. Aggiornamento indici in corso, utenti collegati in gestione documenti, documenti in attesa di aggiornamento) La procedura ADDDOCB in modalità ADD (aggiungere) puo essere eseguita anche se per la banca dati vi sono documenti in attesa di essere aggiornati o se è in corso un aggiornamento documenti. Caricare/Scaricare una Banca Dati 6-2 ICARO Guida Programmatore

77 Formato file di input (TEWLOG) Il formato del file di input, per la procedura ADDDOC deve avere esattamente la stessa struttura del file di giornale di ICARO (un file sequenziale, 7 campi per record). Il file di input ha 3 tipi di record: - Record di testa (tipo 0), all'inizio di ciascun documento - Record di campi formattati (tipo 1), da 0 a 'n' record, uno per ciascun campo formattato. - Record di paragrafi (tipo 2), da 0 a 'n' record, uno per ciascuna riga dei paragrafi. Record di testa 1 JOUREC 1 car. Tipo di record, valore=0 Indica l'inizio di un documento. I Record successivi (tipo 1/2) appartengono a questo documento. 2 JOUDOC 7 num. Numero di documento. Usato se il codice di aggiornamento è 'R' Ignorato, anche se esistente, quando il codice di aggiornamento è 'A' 3 JOUCOD 3 num. 0 (record iniziale) 4 JOUPRO 7 num. 0 (record iniziale) 5 JOUTYP 1 car. Vuoto (record iniziale) 6 JOULEN 3 num. 0 (record iniziale) 7 JOUDES 256 car. Campo contenente: 1 10 TERMINALE UTENTE DATA SISTEMA ORA ULTIMA MODIFICA/INPUT TIPO OPERAZIONE 1=DOC. NUOVO 2=DOC. REVISIONATO 3=DOC. ANNULLATO NUMERO LIVELLO AREA LAVORO Numero del documento ICARO aggiunto/modificato (campo riempito dopo l esecuzione di ADDDOC) riempito da blanks Record campi formattati Se la banca dati non contiene campi formattati questo tipo di record non sarà presente nel file di input. Se invece nella banca dati esistono campi formattati, dopo il record di testa (JOUREC=0) seguiranno tanti record di 'tipo 1' quanti sono i campi formattati della banca dati. La lunghezza/tipo campo è come il record di testa. La struttura del record è la seguente: 1 JOUREC 1 car. Tipo di record, valore=1 2 JOUDOC 7 num. Numero di documento. Usato se il codice di aggiornamento è 'R' Ignorato, anche se esistente, quando il codice di aggiornamento è 'A' ICARO Guida Programmatore 6-3 Caricare/Scaricare una Banca dati

78 3 JOUCOD 3 num. Deve contenere il codice del campo formattato (se nella banca dati di arrivo il codice di campo non esiste esso non viene considerato). 4 JOUPRO 7 num. 0 (fisso per tutti questi record ) 5 JOUTYP 1 car. 'N' campo numerico packed Z campo numerico zoned 'A' campo alfanumerico 'B' campo BIDI Se il tipo campo è 'B' il valore del campo JOUDES conterrà la riga di testo in forma speculare (ossia il primo carattere di destra trasferito nel primo carattere di sinistra ecc.). 6 JOULEN 3 num. Lunghezza del campo. 1-8 (campi numerici packed) 1-15 (campi numerici zoned) (campi alfanumerici) Se il campo è numerico packed la lunghezza deve essere relativa al formato PACKED: 8 per un numero di 15 digit (un numero più lungo di 15 digit può essere scritto come 'termine' in un campo alfanumerico), mentre per un campo alfa la lunghezza massima è di 255 caratteri. Num. digit. decimali Valore JOULEN JOUDES 256 num. Campo lungo 256 caratteri contenente: - una stringa giustificata a sinistra (campi alfanumerici) - un numero packed giustificato a sinistra (campi numerici). Per es. il numero è packed in: 053(zoned) 24F (digit) - Un numero zoned giustificato a sinistra con tante cifre quante indicate in JOULEN - un valore invertito giustificato a sinistra (per campi BIDI). N.b. I campi numerici con decimali sono trattati come interi Caricare/Scaricare una Banca Dati 6-4 ICARO Guida Programmatore

79 NOTA: Esempio di sorgente RPG, per impostare un valore packed di 3 byte (5 cifre) in un campo carattere 'STRING', per poi trasferirlo al campo JOUDES. IDATA DS I STRING I P 1 30PACKED I BLANCK C... C Z-ADD PACKED C CLEAR BLANCK C MOVELSTRING JOUDES Record paragrafi Se la banca dati non contiene paragrafi questo tipo di record non sarà presente nel file di input. Se invece nella banca dati esistono paragrafi, dopo il record di testa (JOUREC=0), e dopo i records dei campi formattati (JOUREC= 1) seguiranno tanti record di 'tipo 2' quante sono le righe nei paragrafi dei documenti. La lunghezza/tipo campo è come il record di testa. La struttura del record è la seguente: 1 JOUREC 1 car. Tipo di record, valore=2 2 JOUDOC 7 num. Numero di documento. Usato se il codice di aggiornamento è 'R'; Ignorato, anche se esistente, quando il codice di aggiornamento è 'A' 3 JOUCOD 3 num. Deve contenere il codice del paragrafo. (se nella banca dati di arrivo il codice di paragrafo non esiste esso non viene considerato). 4 JOUPRO 7 num. Contiene il numero di riga del paragrafo (ciascun record di tipo 2 contiene una riga di 'testo'; ciascuna riga deve avere il proprio numero sequenziale). Se i numeri di riga sono duplicati, le righe saranno caricate in sequenza. 5 JOUTYP 1 car. 'A' campo alfanumerico 'B' campo BIDI. Se il tipo campo è 'B' il valore del campo JOUDES conterrà la riga di testo in forma speculare (ossia il primo carattere di destra trasferito nel primo carattere di sinistra ecc.). 6 JOULEN 3 num. Non è utilizzato. La lunghezza della riga è quella specificata nella videata ' Definire/modificare la descrizione della banca data' ricevente. Se non è specificata viene assunta automaticamente la lunghezza massima. ICARO Guida Programmatore 6-5 Caricare/Scaricare una Banca dati

80 7 JOUDES 256 num. Campo lungo 256 caratteri contenente: - una riga giustificata a sinistra (banche dati RTL o campi) - una riga invertita giustificata a sinistra (per campi BIDI). Lista errori Dopo aver concluso la procedura ADDDOC, controllare gli errori. La lista degli errori viene stampata solo se presente almeno 1 errore. La stampa elenca le righe del file TEWLOG in errore che vengono omesse dall'elaborazione. Oltre ai dati identificativi, per le righe in errore viene indicato il codice di errore: Descrizione errori 1 Il primo record del file non è di tipo 0 (JOUREC) 2 Per ADDDOC in modalità 'REPLACE' (rimpiazzare) il numero documento è 0 o negativo 3 Per la modalità REPLACE, la COLONNA 33 del campo JOUDES è errata (le operazioni ammesse sono: 1 nuovo documento, 2 modificare un documento esistente, 3 cancellare un documento esistente) 4 Il campo numerico in JOUDES non è PACKED per la lunghezza specificata (JOULEN) o non contiene cifre per un campo Zoned. 5 Codice campo/paragrafo non trovato nella banca dati di arrivo 6 Tipo di campo formattato errato (i valori di JOUTYP ammessi sono A, B, N, Z) 7 Lunghezza (JOULEN) per campo numerico è zero o > 8 caratteri (packed) o >15 per campo numerico zoned 8 Lunghezza (joulen) per campo alfa 0 o > 255 caratteri 9 Tipo campo errato (JOUTYP): il campo di provenienza è tipo alfabetico mentre il campo di destinazione è tipo numerico 10 Contenuto campo errato (JOUDES): il campo contiene caratteri non validi (per es. PACKED, non definito nella tabella di caratteri validi) 11 Tipo paragrafo non valido (i valori JOUTYP sono A, B) 12 Paragrafo (JOUCOD) duplicato o fuori sequenza. Caricare/Scaricare una Banca Dati 6-6 ICARO Guida Programmatore

81 b) Reperire documenti Questa funzione esegue il prelievo di tutti o parte dei documenti di una banca dati di ICARO registrandoli in un file sequenziale utilizzando il formato TEWLOG. La funzione di prelievo è usata per estrarre documenti e successivamente e se necessario, dopo aver modificato o aggiunti record nel file creato (tipo TEWLOG) è possibile caricare o sostituire questi documenti nella banca dati di provenienza o in un'altra banca dati. Procedura interattiva: Immettere il comando: Call ICA$BAS/RTVDOC apparirà la seguente videata: Reperimento documenti da Banca Dati ICARO ICA401 File di output (formato TEWLOG).... Libreria Codice della banca dati (F4=Lista) Numero del primo documento Numero dell'ultimo documento..... Formato dei campi numerici in output.._ (Z=Zoned P=Packed) Prima di eseguire l estrazione si consiglia di pulire il file di arrivo in quanto i documenti vengono accodati. L utente deve possedere l autorità alla gestione documenti. F3=Fine F4=Lista banche dati esistenti Completare i campi come segue e premere Invio: - File di output Nome del file di output (in formato TEWLOG o simile) che conterrà i documenti ricercati - Libreria Libreria del file di output - Codice banca dati Il codice della banca dati di provenienza - Numero del primo documento Il primo documento da prelevare - Numero dell'ultimo documento L'ultimo documento da prelevare - Formato dei campi numerici in output Tipo emissione di campi numerici (Z Zoned P Packed) N.B. I campi numerici con decimali sono emessi come interi ICARO Guida Programmatore 6-7 Caricare/Scaricare una Banca dati

82 Procedura batch: Immettere il seguente comando: Call ICA$BAS/RTVDOCB (&LIB &FILE &DOCI &DOCF &AREAA &TYPNUM) I parametri di RTVDOCB sono i seguenti. &LIB 10 car Libreria del file di output &FILE 10 car Nome del file di output &DOCI 7 num Numero del primo documento &DOCF 7 num Numero dell'ultimo documento &AREAA 3 car Numero del codice della banca dati es. '001' &TYPNUM 1 car Tipo emissione campi numerici Z (Zoned) P (packed) Formato del file di output (TEWLOG) Il formato del file di output deve avere esattamente la stessa struttura del file di giornale di ICARO TEWLOG (un file sequenziale, 7 record di campi). Duplicare quindi dalla libreria ICA$FIL il file di output vuoto (es. FILEOUT in QGPL) CRTDUPOBJ OBJ(TEWLOG) FROMLIB(ICA$FIL) OBJTYPE(*FILE) + TOLIB(QGPL) NEWOBJ(FILEOUT) Il file di output ha 3 tipi di record: - Record di testa (tipo 0) all'inizio di ciascun documento - Record di campi formattati (tipo 1),da 0 a 'n' record, uno per ciascun campo formattato - Record di paragrafi (tipo 2), da 0 a 'n' record, uno per ciascuna riga di paragrafo Record di testa 1 JOUREC 1 car Tipo di record, valore=0 Indica l'inizio del documento I record successivi (tipo 1/2) appartengono a questo documento. 2 JOUDOC 7 num Numero di documento 3 JOUCOD 3 num 0 (per il record di testa) 4 JOUPRO 7 num 0 (per il record di testa) 5 JOUTYP 1 car blank (per il record di testa) 6 JOULEN 3 num 0 (per il record di testa) Caricare/Scaricare una Banca Dati 6-8 ICARO Guida Programmatore

83 7 JOUDES 256 car campo contenente: Record campi formattati 1 10 TERMINALE (blanks) UTENTE (blanks) DATA SISTEMA ORARIO TIPO OPERAZIONE 1=DOCUM. ATTIVO 2=Non usato da RTVDOC 3=DOCUM.ANNULLATO NUM. LIVELLO (ZERO) riempito da blanks Questo tipo di record è usato se la banca dati contiene campi formattati: per ciascun documento il numero di record di 'tipo 1' è uguale al numero di campi formattati definiti per la banca dati. La lunghezza/tipo di campo sono come per il record di testa. 1 JOUREC 1 car Tipo di record, valore=1 2 JOUDOC 7 num Numero di documento 3 JOUCOD 3 num Codice campo formattato 4 JOUPRO 7 num 0 (in tutti i record di campi formattati) 5 JOUTYP 1 car 'N' Campo numerico packed 'Z' Campo numerico Zoned 'A' Campo alfanumerico 'B' Campo BIDI (Il campo JOUDES sarà allora invertito come segue: il primo carattere a destra trasferito al primo carattere a sinistra; secondo carattere a destra trasferito al secondo carattere a sinistra; ecc.) 6 JOULEN 3 num Lunghezza di campo formattato; 1-8 (campi numerici packed) 1-15 (campi numerici zoned) (campi alfanumerici) 7 JOUDES 256 car contenente il valore del campo formattato ed avente: - una stringa giustificata a sinistra (campi alfanumerici) - un numero PACKED giustificato a sinistra (campi numerici). Per es. il numero packed occupa 3 bytes F - Un numero Zoned giustificato a sinistra: Es.: per un campo di 5 cifre zoned - Un valore invertito giustificato a sinistra (per campi BIDI) N.B. I campi numerici con decimali sono emessi come interi ICARO Guida Programmatore 6-9 Caricare/Scaricare una Banca dati

84 Record paragrafi Questo tipo di record è usato se la banca dati contiene dei campi variabili ('paragrafi'): per ciascun documento il numero di record di 'tipo 2' è uguale al numero di righe nei paragrafi del documento. 1 JOUREC 1 car Tipo di record, valore=2 2 JOUDOC 7 num Numero di documento Usato se il codice di aggiornamento è 'R' (rimpiazzare/sostituire); Ignorato, anche se esistente, quando il codice di aggiornamento è 'A' (Aggiungere) 3 JOUCOD 3 num Codice paragrafo 4 JOUPRO 7 num Numero di riga del paragrafo (ciascun record di tipo 2 contiene una riga di 'testo'; ciascuna riga è assegnata a un numero sequenziale di riga) 5 JOUTYP 1 car 'A' Campo alfanumerico' standard LTR 'B' Campo BIDI 6 JOULEN 3 num Non utilizzato 7 JOUDES 256 car Campo contenente: - una riga giustificata a sinistra (banche dati LTR o campi - una riga invertita giustificata a sinistra (per campi BIDI) Alla fine della procedura RTVDOC, il file prodotto può essere utilizzato come input per manipolazioni e successivamente caricato/ricaricato (procedura ADDDOC) in una banca dati di ICARO. Caricare/Scaricare una Banca Dati 6-10 ICARO Guida Programmatore

85 Applicazioni Recupero/svuotamento/caricamento documenti Se l'utente desidera recuperare documenti non per riferimento specifico, ma in funzione del valore di certi campi formattati (per esempio estrarre documenti da una banca dati prima di una determinata data indicata dall'utente oppure modificare documenti il cui campo 'Tipo' è uguale a '4' ecc.), eseguire la seguente procedura: - Creare una vista logica al file TEXRAAA (per es. 'TEXRWWW') con le necessarie istruzioni INCLUDE/OMIT - Eseguire: OVRDBF TEXRAAA ICA$xxx/TEXRWWW - Richiamare la procedura RTVDOCB: Call ICA$BAS/RTVDOCB (...) Indicare '0' come primo documento e ' ' come ultimo documento. Il file di output (in formato TEWLOG) conterrà solo i documenti selezionati. - Modificare, se necessario, il file TEWLOG - Ricaricare i documenti usando la procedura ADDDOC (con il codice di aggiornamento ADD per creare una nuova banca dati contenente solo i documenti selezionati, o con il codice di aggiornamento REPLACE per ricaricare i documenti nella stessa banca dati e nella stessa sequenza). Banche dati parallele Un'impresa possiede diversi AS/400 (in ciascuna filiale/nazione). La sede centrale gestisce una banca dati ICARO. Ciascuna filiale deve tenere localmente una copia della banca dati, senza per questo dover fare periodicamente il backup in SEDE e ricaricare l'intera banca dati in periferia. Come fare per allineare la medesima banca dati ICARO agli altri sistemi remoti senza trasferire l'intera banca dati? - La banca dati deve essere inizialmente copiata/caricata su ciascun computer della filiale, sarà così allo stesso livello dappertutto. - solo gli utenti della sede centrale (locale o remota) saranno autorizzati a creare/revisionare documenti nella banca dati della sede centrale. - L'opzione di journaling dovrebbe essere attivata con 'YES' nella banca dati centrale. - Ogni sera completare e chiudere l'attività 'Gestione documenti' nella banca dati (e bloccarla con LCKDB -vedi capitolo 5) e trasmettere il file TEWLOG a ciascuna filiale (SNDNETF), fare il backup del file di giornale (per consentire successivi recuperi), svuotare il file TEWLOG (CLRPFM) e aprire la banca dati (vedi LCKDB). ICARO Guida Programmatore 6-11 Caricare/Scaricare una Banca dati

86 SEDE CENTRALE Trasmissione TEWLOG Filiale di Houston Filiale di Londra Backup Svuotamento Filiale di Sidney - In tutte le filiali eseguire la procedura ADDDOC o ADDDOCB utilizzando il file TEWLOG ricevuto come input ed indicando 'R' (REPLACE) come codice di aggiornamento. Svuotare il file TEWLOG (CLRPFM) ricevuto. Recuperare/unire informazioni esterne Un utente desidera caricare diversi file in una banca dati ICARO. - Un file formato TEWLOG proveniente da altri sistemi; - Un file di output non di ICARO (proveniente da una banca dati di PC, da una banca dati STAIRS (architettura 370) o da altro sistema di gestione di file; - Un insieme di file differenti: campi estratti da un file cliente, da un file di fatturazione, da registrazioni di conti... - telex o posta elettronica ricevuti da parte di partner interni/esterni o agenzie di stampa. Come procedere: - Caricare il file corrispondente sull'as/400 (RSTOBJ, trasferimento di file da PC via PCS...). - Creare una struttura di banca dati ICARO sull'as/400 (se non è possibile usarne una già esistente). Progettare tutti i campi che l'utente desidera caricare (vedi il capitolo 'Progettare banche dati') nel manuale dell'utente di ICARO. - Creare un file TEWLOG vuoto (si può utilizzare anche un nome diverso da TEWLOG) in una libreria di servizio (per es. la libreria di banca dati ICA$nnn): CRTDUPOBJ OBJ(TEWLOG) FROMLIB(ICA$FIL) OBJTYPE(*FILE) + TOLIB(...) DATA(*NO) NEWOBJ(TEWLOG2) - Creare un programma (RPG, COBOL, C,...) per leggere il file di input e per trasferire l'informazione richiesta nei record TEWLOG. Creare un record principale 'Tipo 0' per ciascun documento, dei record 'Tipo 1' per ciascun campo formattato, dei record 'Tipo 2' per ciascuna riga di paragrafo. - Richiamare le procedure ADDDOC o ADDDOCB per aggiungere i documenti nella banca dati di ICARO da TEWLOG2. Caricare/Scaricare una Banca Dati 6-12 ICARO Guida Programmatore

87 Creare una sotto banca dati Un utente desidera creare una nuova banca dati ICARO contenente un set o parte dei documenti estratti da una banca dati già esistente, più grande. - Creare una nuova struttura di banca dati (campi specifici possono essere aggiunti o omessi) - Creare un file TEWLOG vuoto (si può utilizzare anche un nome diverso da TEWLOG) in una libreria conveniente (per es. la libreria di banca dati ICA$nnn): CRTDUPOBJ OBJ(TEWLOG) FROMLIB(ICA$FIL) OBJTYPE(*FILE) TOLIB(...) DATA(*NO) NEWOBJ(TEWLOG2) - Usare la procedura RTVDOC per svuotare i documenti richiesti nel file TEWLOG2 - Aggiungere il documento alla nuova banca dati richiamando la procedura ADDDOC. Modificare globalmente campi/paragrafi specifici (in tutti i documenti di banca dati) Un Utente desidera modificare campi specifici: - Creare un file TEWLOG vuoto (si può utilizzare anche un nome diverso da TEWLOG) in una libreria operativa (per es. la libreria di banca dati ICA$nnn): CRTDUPOBJ OBJ(TEWLOG) FROMLIB(ICA$FIL) OBJTYPE(*FILE) TOLIB(...) DATA(*NO) NEWOBJ(TEWLOG2) - Usare la procedura RTVDOC per reperire i documenti richiesti nel file TEWLOG2 - Modificare il contenuto del file sequenziale TEWLOG2 (cambia/cancella) - Rimpiazzare ('R') i documenti nella banca dati richiamando la procedura ADDDOC. ICARO Guida Programmatore 6-13 Caricare/Scaricare una Banca dati

88 Pagina vuota Caricare/Scaricare una Banca Dati 6-14 ICARO Guida Programmatore

89 Capitolo 7. Il programma guida: TEXBAT Potrebbe essere necessario, per motivi di analisi applicativa, sviluppare procedure per la gestione dei documenti ICARO mediante programmi interattivi e quindi superando il programma di gestione ICARO. E' necessario uno specifico programma per creare, revisionare o cancellare documenti all'interno di una banca dati ICARO: il programma di esempio TEXBAT è fornito a tal fine in formato di codice sorgente (vedi il membro TEXBAT nel file ICA$BAS/EXAMPLE). Ecco alcuni casi in cui è necessario personalizzare e utilizzare TEXBAT: a) Supponiamo che un utente desidera creare una banca dati riepilogativa o di sintesi di certi fenomeni aziendali mediante documenti ICARO. Supponiamo di creare una banca dati CLIENTI (o prodotti) ove ogni documento (Uno per Cliente o Prodotto) raccoglierà, in appositi paragrafi, tutti gli eventi di un CLIENTE (o prodotto). Un paragrafo potrebbe ad esempio raccogliere, per ogni riga, una fattura emessa; un'altro paragrafo potrebbe raccogliere i pagamenti (1 per riga); al momento della fatturazione o della registrazione dei pagamenti il programma utente (tipo TEXBAT) potrebbe aggiungere alla scheda CLIENTE (o prodotti), nei paragrafi relativi le informazioni o gli eventi accaduti : fatture emesse, note credito, visite dei rappresentanti ecc. Le informazioni circa le fatture ed i pagamenti provenienti dalle varie applicazioni utente, saranno raggruppate in unità logiche (per cliente, per fornitore) senza, in sede di ricerca, le normali restrizioni (codice o nome del cliente, ecc.).delle applicazioni tradizionali. In questo modo, un qualunque dato (numero di fattura, mese, ammontare) costituirà la via d'accesso all'informazione in modo discorsivo e con la potenza elaborativa di ricerca ICARO. Ciò comporta che ad ogni modifica o inserimento di un dato (ad esempio emissione fatture), un programma utente con la logica del TEXBAT vada ad aggiungere, all'unità documento ICARO relativo al cliente, una riga relativa alla fattura emessa, al fine di allineare i dati contabili con il riepilogativo. b) L'utente ha necessità di gestire documenti ICARO (campi formattati e paragrafi) attraverso videate di input a campi formattati o con un subfile. I dati di input immessi dall'utente saranno controllati dal programma personalizzato, il quale li memorizzerà nei paragrafi e nei campi formattati definiti nella banca dati per ottenere, dopo l'aggiornamento un documento disponibile per la ricerca. ICARO Guida Programmatore 7-1 Texbat

90 Il sorgente TEXBAT Stampare il sorgente TEXBAT (dal file source EXAMPLE della libreria ICA$BAS) e verificare i passaggi essenziali. Il simbolo '???' (in posizione 3-5 nel programma sorgente) indica le specifiche che l'utente può personalizzare. a) File di input: TEXBAT Prevede il file utente di input 'FILUTE' (riga 97.00); ovviamente secondo le esigenze dell'utente, le informazioni in input possono provenire contemporaneamente da più file utente, o da un file video, o da file disco utente contenenti aggiornamenti. 'FILUTE' può essere quindi sostituito dal nome del (o dei) file contenenti i dati di input. Gli altri file presenti nelle specifiche 'F' riguardano: - le aree di lavoro TEWRAAA e TEWDAAA nei quali sono registrati e gestiti i documenti - i file di supporto TEXAGAN, TEXARET e TEXJRNL, TEXRAAA; b) Specifiche 'E' ed 'I'. Le righe che non siano precedute da '?' (col 1-5) NON devono essere modificate o cancellate in quanto sono usate per le subroutine delle strutture di dati o tabelle. Alle righe precedute da '?' (col 1-5) il programmatore può aggiungere righe a secondo delle proprie necessità (ad es. per decodificare informazioni ecc.); fare riferimento alle righe di commento 2.00 e c) Specifiche di calcolo: Nella riga di commento del programma TEXBAT l'utente può inserire qualsiasi parametro da scambiare con il programma MAIN. Un campo RTN è previsto per chiudere il programma passando ad un eventuale MAIN il codice errore di ritorno (vedi righe di commento e ). Il programma TEXBAT è strutturato in modo da richiedere il minore intervento possibile da parte dell'utente. Il programma si presta ad essere utilizzato dall'utente in un programma batch o interattivo, ciò grazie alla sua struttura in routine ed al fatto che gli errori sono evidenziati da codici di ritorno. Il diagramma di flusso del programma è illustrato nella pagina seguente Programma Texbat 7-2 ICARO Guida Programmatore

91 Codice banca dati Inserire il codice di banca dati (istruzione ) EXSR PRELIM La routine esegue: a) controllo autorizzazioni; b) apertura files banca dati, lettura della struttura campi/paragrafi della b.d. c) controlla che la banca dati sia disponibile Errore Controllare anomalia precedente: salvare il documento interrotto o riinizzializzare le aree di lavoro A RESET Routine di SELOP Loop sul file di input di utente Istruzioni di utente per leggere il file di input. Potrebbe essere un file video (prooperazioni; immettere le grammi interattivi). Impostare il tipo informazioni Convalidare l'input e scegliere l'operazione Istruzioni di convalida, codificate secondo le necessità dell'utente. Scegliere il tipo di operazione: 1=nuovo documento, 2=revisione di documento, 3=annullamento. In caso di errore tornare ad (A) Routine WRKDOC EXSR WRKDOC Richiamare la routine ICARO per preparare il documento nelle aree di lavoro TEWRAAA e TEWDAAA. se il documento è utilizzato da un altro utente (in revisione), ritornare su A. Routine GESDOC Modifiche e controlli di documenti Istruzioni di utente per modificare e gestire campi formattati (in TEWRAAA) e paragrafi (in TEWDAAA). TEWDAAA contiene un record per riga di paragrafo. Routine AGGDOC Documento pronto Non modificare queste istruzioni ICARO che forniscono tutte le operazioni finali di aggiornamento per il documento in esame. Ripetizione LOOP L'utente condizionerà la condizione di ritorno al loop (non raggiunta la fine file o non premuto F3 ecc.) ICARO Guida Programmatore 7-3 Texbat

92 Descrizione dei passaggi I passaggi di EXSR PRELIM sono i seguenti: - Verifica l'autorità dell'utente alla gestione della banca dati; - Verifica se l'utente ha altre sessioni aperte sulla stessa banca dati - Registra lo stato dell'attività dell'utente sulla banca dati. - Verifica la disponibilità della banca dati (ovvero che non vi siano lavori ICARO che richiedono l'uso esclusivo della banca dati) - Verifica che non ci siano altre attività in corso, oltre a quelle consentite per la banca dati. - Legge la struttura della banca dati (campi formattati/paragrafi). - Registra l'attività in corso. - Controlla se una attività precedente si è conclusa correttamente (ad esempio qualche documento lasciato in 'sospeso' per spegnimento del terminale durante la sua gestione). In caso di errore, il campo RTN (istruz ) conterrà un codice di errore (vedi legenda righe ) che comporterà la chiusura del programma. Se il campo RTN è vuoto (nessun errore), ma i campi ST, SP sono uguali a 03 l'utente deve allora scegliere: o perdere le modifiche apportate al documento trovato in sospeso, o effettuarne l'aggiornamento immediatamente attraverso la routine GESDOC. LOOP di INPUT utente Vedi istruzioni (SELT TAG) e (GOTO SELT). Il loop di ciclo è composto dalle routine: - SELOP (leggere file utente, scegliere sul tipo di operazione - nuovo revisione annullamento documento- creare l'area di lavoro) - GESDOC (istruzioni proprie dell'utente di modifica campi/paragrafi) - AGGDOC (routine di aggiornamento e chiusura del documento). Routine SELOP Questa routine deve impostare il tipo di operazione da effettuare (valore di campo $TOP): 1=aggiungere, 2=aggiornare, 3=cancellare ed eventualmente (per i codici 2 e 3) il numero del documento interessato. I valori di codice 2 e 3 richiedono come riferimento il Numero Documento (campo $ADOCR). Vedi istruzioni e Il programma utente può stabilire di inserire l'istruzione di lettura file video (comando EXFMT) o file disco - vedi istruzione per determinare il tipo di operazione da eseguire. Si ricorda che si possono creare viste logiche per effettuare controlli specifici (sul numero di cliente, ecc.) operando sui file TEXRAAA e TEWRAAA. Non ci sono limitaizioni nell'uso del Numero di Documento. Programma Texbat 7-4 ICARO Guida Programmatore

93 Stabiliti i valori di $TOP e $ADOCR, viene richiamata la routine CHKOP, la quale in casi di anomalie (documenti non revisionabili), riporta il controllo alla richiesta tipo operazione (vedi istruzioni e ). Routine WRKDOC Dopo il controllo del tipo di operazione (1, 2 o 3) e l'eventuale riferimento del numero di documento in $ADOCR, la routine WRKDOC crea un area di lavoro per i file TEWRAAA (campi formattati) e TEWDAAA (paragrafi) contenente quest'ultimo un record per ciascuna riga di testo (vedi descrizione nella libreria ICA$xxx) L'area di lavoro contiene l'ultima versione del documento da aggiornare o il formato di default se trattasi di nuovo documento. Routine GESDOC Dopo la preparazione dell'area di lavoro (vedi istruzione e seguenti) il MAIN avvia la routine di gestione GESDOC per modificare il documento (campi formattati e paragrafi). Vedi le note nel programma sorgente. In questa routine, l'utente può inserire tutte le istruzioni necessarie a modificare i record del file TEWRAAA, per ciascun campo formattato; così come anche istruzioni per inserire, modificare o cancellare righe nel file TEWDAAA per ciascun paragrafo. Nella routine si possono inserire istruzioni per emettere videate o per leggere informazioni da files utente su disco e controllarne la validità. Routine di RESET Richiamando questa routine si annullano le operazioni in corso, così come le aree di lavoro create per il documento in gestione. Dopo aver richiamato la routine di RESET, l'utente deve ritornare all'inizio del ciclo SELOP. Routine AGGDOC Quando non sono stati riscontrati errori, si richiama la routine AGGDOC (istruzione ) per la registrazione del documento. Questa routine mette un flag di pronto per l'aggiornamento (per il documento) nel file TEXRAAA; registra nel file TEXJRNL il livello ultimo del documento gestito per indicare al registratore del journal quale versione registrare nel file di giornale TEWLOG. Quando l'aggiornamento è avvenuto, la routine MAIN ritorna sulla routine SELOP (istruzione ), per cominciare un nuovo ciclo o per concludere il programma se il campo RTN=F ICARO Guida Programmatore 7-5 Texbat

94 Pagina vuota Programma Texbat 7-6 ICARO Guida Programmatore

95 Capitolo 8. Autorizzazioni Assegnare ad un utente un profilo di riferimento: TXADUP Da programma, è possibile autorizzare un utente a realizzare compiti o funzioni specifici assegnandogli un profilo di riferimento ICARO già esistente. Eseguire il comando seguente: CALL TXADUP PARM(&USER &REFPRO &GROUP &LANG &RTN) I parametri di TXADUP sono: &USER 10 car. Nome utente da autorizzare. Tale utente non può essere creato se è già definito nell'applicazione di ICARO. &REFPRO 10 num. Campo numerico di 10 cifre indicante il nome del profilo di riferimento. Deve essere completamente definito utilizzando l'opzione 'Gestione profili utente' del menu 'Definizioni ICARO'. &GROUP 3 num. Campo numerico di 3 cifre. E' il codice contabile di gruppo (vedi guida dell'utente ICARO, capitolo 9 'Gestione profili utente'). &LANG 1 car. Codice della lingua utente (1=italiano, 2=inglese, ecc.). Gli schermi video saranno mostrati nella lingua immessa se è utilizzata l'interfaccia standard di ICARO. &RNT 1 car. Codice di ritorno. A completamento della routine, comparirà il carattere 'E' se è stato riscontrato un errore nel valore dei parametri (per es. - nel caso in cui l'utente era già stato definito - se il profilo di riferimento o la lingua non sono stati trovati). Nota: Dopo l'esecuzione di TXADUP, la libreria CURLIB è impostata al valore *CRTDFT. Se necessario, modificare la libreria corrente. ICARO Guida Programmatore 8-1 Autorizzazioni

96 Modifica delle limitazioni di accesso a documenti (CHGQRYLMT) Nella gestione delle autorizzazioni è possibile ad un certo utente e per una specifica banca dati nascondere una espressione di interrogazione (sia in relazione AND che NOT) per limitare l accesso a documenti. Se il programmatore desidera, in batch, aggiungere o eliminare espressioni in uno specifico profilo e per una specifica banca dati può utilizzare la seguente routine: CALL ICA$BAS/ CHGQRYLMT (&USRPRO &DB &AND &NOT &STS) NOTA BENE: La libreria ICA$BAS deve essere nella lista delle librerie prima dell esecuzione della routine. Parametri: &USRPRO 10 car. Nome del profilo di riferimento (che può coincidere con il nome utente se questi ha uno specifico profilo). Non è possibile utilizzare ICAROADM. &DB 3 num Campo numerico di tre cifre; deve contenere il codice della banca dati ( ) a cui l utente è stato autorizzato e per la quale sarà richiesta la modifica delle query AND / NOT. &AND 50 alfa Campo alfanumerico di 50 caratteri contenete la espressione di query nascosta che precederà in relazione AND la query dell utente. Lasciare blank questo campo se si desidera eliminare la query AND già esistente per il profilo (&USRPRO) e per la banca dati (&DB) &NOT &STS Nota bene: 50 alfa Campo alfanumerico di 50 caratteri contenete la espressione di query nascosta che seguirà in relazione NOT la query dell utente. Lasciare blank questo campo se si desidera eliminare la query NOT già esistente per il profilo (&USRPRO) e per la banca dati (&DB) 1 alfa Flag; dopo la elaborazione della routine se questo campo ritorna con il valore N significa che I valori impostati (&USRPRO e/o &DB ) non sono validi o che l utente (profilo) non esiste o che per il profilo non vi è alcuna autorizzazione a quella banca dati. La routine va richiamata con il valore &STS impostato a blank; ultimati gli aggiornamenti, per chiudere correttamente il file delle autorizzazioni, richiamare la routine con il valore &STS impostato ad F. Exit Routines 8-2 ICARO Guida Utente

97 Capitolo 9. Interrogazione su banche dati Quadro generale Per procedere allo sviluppo di interfacce per l'interrogazione di banche dati, occorre utilizzare il gruppo specifico delle routine API Per formulare una interrogazione da un programma utente (dopo che è stata eseguita la routine CRTAUTUSE) occorre seguire il processo logico seguente: A INQOPNSP INQSETDB Apertura area di lavoro OVRDBF,OVRDSPF Attivazione banca dati B INQR01 o INQSNQRY Immissione domanda interattiva/batch INQCHK Controllo e calcolo INQDSPDO INQDSPLI INQ... Procedure di output del risultato: visualizzazione, lista, estrazione... vai da A/B or FINE Sessione INQDLT Un esempio di programma che utilizza il flusso delle API's è PGMINQ che è contenuto nel file EXAMPLE nella libreria ICA$BAS. Questo programma richiama, combinando tra loro, diverse routine API simulando il comportamento dell'analogo programma standard di interrogazione ICARO e può essere adattato secondo le proprie necessità, ad esempio togliendo la funzione di lista delle ricorrenze (INQDSPOC). Altro esempio di formulazione di interrogazione, da parte dell'utente, sono forniti nel programma esempio 'TURBO' e in varie banche dati mediante programmi di exit (navigazione, passaggio da una banca dati all'altra). ICARO Guida Programmatore 9-1 Interrogazioni

98 Esempio dell'interfaccia di interrogazione Il programma esempio TURBO, associato con il file di visualizzazione TURBOF e con il programma esempio INQDIR (file ICA$BAS/EXAMPLE), permettono all'utente di immettere in un'unica maschera video una serie di criteri (parametri di ricerca, opzioni di risultato,..), e ottenere la visualizzazione immediata del risultato (senza eseguire passi intermedi). Per testare l'operatività di tali esempi immettere il comando: Call ICA$BAS/TURBO Il sorgente TURBO CL e l'inqdir PGM richiamano le API di interrogazione. Esempio di exit per banca dati (programma EXTINQ) Durante la visualizzazione di un documento (dopo un'interrogazione) è possibile attivare, con F20, una funzione di Exit (vedi più avanti EXTINQ) che consente di prelevare una parte del documento visualizzato ed utilizzare questo testo per eseguire una query sulla stessa o in un'altra banca dati (navigazione). Esempi di test di questa exit contengono l'utilizzo di opportune API di interrogazione. - La banca dati 024 contiene i sinonimi per la banca dati 023. Eseguire ad esempio nella banca dati 024 la domanda 'DELINQUENZA' e dopo aver visualizzato il documento (sinonimi di delinquenza) premere F20. La query contenuta nel secondo paragrafo del documento è utilizzata dall'exit EXTINQ per formulare in automatico una query nella banca dati 024 per cui appariranno i documenti dell'archivio bibliografico contenenti i termini sinonimi di delinquenza (terrorismo, mafia etc..). Il programma EXTINQ (vedi il sorgente CL nella libreria ICA$024) utilizza tra le routine API: INQSNQRY, INQCHK e INQDSPDO. Il programma EXTINQ è richiamato premendo il tasto funzione F20 quando compaiono i sinonimi. - I documenti della banca dati 030 (SENTENZE) sono legati con la banca dati 028 (LEGGI). Effettuare nella banca dati 030 la query: 'PARCHI E RISERVE' e premere F20 dopo aver visualizzato il documento. Il programma EXTINQ (vedi il sorgente CL nella libreria ICA$030) permette all'utente di navigare dalla banca dati delle sentenze alla banca dati delle leggi (e viceversa) premendo il tasto funzione F20. - I documenti della banca dati 022 (CATALOGO) sono legati con immagini esterne (ciò è possibile quando l'utente si è collegato con un PC mediante PCS/PCO - Organizer, e tutti i folder sono stati assegnati al disco logico J:. Effettuare la query esempio 'STATUA' e premere F20 dopo aver visualizzato il documento. Il programma EXTINQ (vedi il sorgente CL nella libreria ICA$022) permette all'utente di richiamare le immagini da un documento descrittivo (testuale) della banca dati 022 premendo il tasto funzione F20. Interrogazioni 9-2 ICARO Guida Programmatore

99 Descrizione delle routine API Apertura dell'area di lavoro Se si inizia da un programma 'non ICARO', necessita aprire una sessione ICARO; Nel programma MAIN, dopo CRTAUTUSE, eseguire anche la routine INQOPNSP (solo una volta ad inizio della sessione di interrogazione). Con CRTAUTUSE si assegnerà una libreria temporanea di lavoro WICA000xxx (vedi capitolo 1), mentre con INQOPNSP aprirà i files necessari all interrogazione. Il programma utente, di avvio di una sessione di interrogazione (MAIN), deve eseguire una sola volta ad inizio sessione due OVRDBF per indirizzare le successive routine ai files corretti: OVRDBF TABLE ICA$BAS/TABLEx (con x=codice lingua 1,2,...) OVRDSPF TEXDSPF ICA$BAS/TEXDSPFx (x=codice lingua). CALL ICA$BAS/INQOPNSP (&LANG) con : &LANG 1 car. Codice lingua (1=Italiano, 2=Inglese, ecc.). Se per l'immissione della domanda si utilizza l'interfaccia standard di ICARO le maschere video o i messaggi appariranno nella lingua indicata. Il richiamo ripetuto di tale routine, non comporta alcun problema ma è preferibile eseguirlo solo una volta o comunque dopo un richiamo di chiusura (INQDLT vedi più avanti). Nota: se una sessione di interrogazione chiama un'altra NUOVA sessione di interrogazione che utilizza INQDLT (per es. il pgm TURBO che richiama TEXINQ) al rientro nel pgm principale (TURBO) occorrerà rieseguire INQOPNSP per riattivare l'area di lavoro precedentemente chiusa. Attivazione banca dati: INQSETDB La routine INQSETDB apre una o più (massimo 9) banche dati per effettuare l'interrogazione. Per continuare con altre routine API, occorre che almeno una banca dati sia stata aperta. Per attivare la routine eseguire: CALL ICA$BAS/INQSETDB (&MDB &RTN) I parametri della routine INQSETDB sono i seguenti: &MDB 27 car. Campo contenente una o più (massimo 9) codici di banca dati (3 cifre per ogni banca dati, per esempio: ' ' per banche dati 002, 008, 022 e 351. ICARO Guida Programmatore 9-3 Interrogazioni

100 INQSETDB controlla la validità (se la banca dati esiste, se è disponibile) e se l'utente è autorizzato all'uso della o delle banche dati. Lasciando il parametro &MDB vuoto, verrà visualizzata la lista delle banche dati autorizzate dalla quale l'utente potrà selezionare le banche dati da aprire. &RTN 1 car. Codice di ritorno sull'esito del completamento delle API: A I H D U F O Blank Utente non autorizzato o non esiste il profilo utente o non è stato precedentemente eseguito CRTAUTUSE o non è stato precedentemente eseguito INQOPNSP La licenza ICARO non è abilitata (vedi licenza ICARO) o è stato superato il numero di banche dati gestibile La lista delle banche dati (se il parametro &MDB è vuoto) non può essere visualizzata se il job è stato sottomesso in modo batch La banca dati non esiste o non è autorizzata Il numero di utenti collegati supera il massimo consentito Durante la visualizzazione della lista banche dati è stato premuto il tasto funzione F3=Fine, o l'utente ha premuto il tasto Invio senza selezionare alcuna banca dati Non è stato eseguito il programma CRTAUTUSE o INQOPNSP (manca la libreria di lavoro WICAxxxxxx) L'operazione è stata completata con successo. Interrogazioni 9-4 ICARO Guida Programmatore

101 Formulazione interattiva della domanda: INQR01 Dopo l'apertura della banca dati con l'api INQSETDB, l'utente può richiamare la routine INQR01 per l'immissione interattiva della domanda con l'editore standard ICARO. La routine INQR01 determina il numero di livello assegnato alla domanda (numero sequenziale) e lo incrementa nell'uso successivo. Eseguire il seguente comando: Call ICA$BAS/INQR01 (&NJOB &QRYNUM &RTN) I parametri della routine INQR01 sono i seguenti: &NJOB 6 car. Campo alfa di 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. Campo numerico di 7 cifre contenente il numero sequenziale di livello della domanda. Questo valore viene passato al programma utente dopo che che è stata completata con successo la routine INQR01 &RTN 1 car. Codice di ritorno sull'esito del completamento delle API: blank Chiamando la routine con questo parametro impostato a blank vengono visualizzate le righe di immissione della domanda. 2 Chiamando la routine con il parametro &RTN impostato a '2' insieme alle righe per la domanda viene visualizzata la lista degli errori riscontrati da un precedente richiamo della routine INQCHK. 1 La routine dopo l'esecuzione passa il valore '1' se essa è stata chiusa con F8 (richiesta della lista delle banche dati) 3 La routine dopo l'esecuzione passa il valore '3' se essa è stata chiusa con F3 (Fine) E La routine dopo l'esecuzione passa il valore 'E' se essa è stata chiusa con un Errore (caduta terminale video o errore generico (es. non èstato eseguito INQOPNSP). ICARO Guida Programmatore 9-5 Interrogazioni

102 Programma specifico per la formulazione della domanda: PGMxxxx Durante l'esecuzione di INQR01 (formulazione di una domanda) può essere necessario attivare un programma specifico pre-definito tra gli operatori con il codice 'A3'. Esempio: Il gestore della banca dati crei un file di sinonimi (o una banca dati ICARO) in cui ogni termini esistente contiene dei campi contenenti dei sinonimi. Il gestore della banca dati definisca tra gli operatori booleani la funzione 'SYN' con codice interno 'A3'. Un programma corrispondente 'PGMSYN' deve essere creato a cura dell'utente (e deve essere disponibile nella lista della libreria corrente). Questo programma, ricevendo come parametro un termine, ricercherà i sinonimi e restituirà al programma chiamante (INQR01) la nuova stringa. Termine1 E SYN(termine2) E... La routine INQR01 cercherà il programma PGMSYN e passerà il valore TERM2 se l'operatore SYN è definito tra gli operatori con il codice 'A3': Call *LIB/PGMSYN (&PARM1 &PARM2) I parametri sono i seguenti: &PARM car. &PARM2 Struttura alfabetica di 7821 caratteri (99 righe x 79 caratteri) contenente la stringa passati da INQR01 al programma esterno PGMxxx. A conclusione della routine &PARM1 conterrà la nuova stringa o valore da sostituire. 1 car. Codice di ritorno impostato dal programma PGMxxx richiedendo al main (INQR01) le seguenti azioni: E Il programma utente PGMxxxxx ha trovato un errore nella stringa durante il processo. P Il programma utente PGMxxxxx richiede di eliminare l'intera stringa - PGMxxx(...) dallo schermo S/blank Il programma utente PGMxxxxx ha sostituito la stringa &PARM1 e la stringa (modificata) sostituirà la stringa originaria della domanda. Esempio: Domanda prima dell'esecuzione di 'PGMSYN' Veloce E SYN(auto) E Limite Domanda dopo l'esecuzione di 'PGMSYN' Veloce E (auto O automobile O veicolo) E Limite Interrogazioni 9-6 ICARO Guida Programmatore

103 Formulazione di domanda in modo batch: INQSNQRY La routine INQSNQRY è usata per formulare una domanda in ICARO. Questa domanda deve essere costruita e memorizzata da un programma utente o da una interfaccia. Con questa routine, l'utente non ha diretto accesso all'editor standard di ICARO usato invece dalla routine INQR01. La routine INQSNQRY memorizzerà le righe di domanda e determina il numero sequenziale di livello della domanda. Il comando è il seguente: Call ICA$BAS/INQSNQRY (&QRYTXT &QRYTYP &QRYNUM &RTN) I parametri di INQSNQRY sono: &QRYTXT 7900 car. (100 righe x 79 caratteri) immettere il testo della domanda. (La lunghezza della domanda da immettere è limitata se introdotta da INQSNQRY, mentre è illimitata se immessa direttamente nell'editor mediante INQR01). &QRYTYP 1 car. Immettere l'orientamento del testo: 1 Per una domanda con scrittura LTR (da sinistra a destra) 2 Per una domanda RTL (BIDI) da destra a sinistra &QRYNUM 7 num. Dopo l'esecuzione, la routine restituisce, di ritorno, il numero di livello assegnato alla domanda. &RTN 1 car. Codice di errore T Campo &QRYTYP (diverso da 1 o 2) J Non è stato eseguito INQOPNSP E Non è stata formulata alcuna domanda nel campo &QRYTXT ICARO Guida Programmatore 9-7 Interrogazioni

104 Controllo domanda: INQCHK Dopo la memorizzazione della domanda da elaborare (INQR01 o INQSNQRY), la routine INQCHK controlla la sintassi della domanda. Se c'è un errore, la domanda non sarà elaborata. Il comando è il seguente: CALL ICA$BAS/INQCHK (&JOBNUM &CODER &ERRTEX &RTN) I parametri di INQCHK sono: &JOBNUM 6 car. &CODER 2 car. Campo contenente il numero del job (ricerca questo job con il comando RTVJOBA) Codice di ritorno a completamento della routine 06 Nessuna domanda formulata 07 Manca parentesi aperta/chiusa 08 Espressione > di 200 caratteri 09 Funzione F(...) non definita 10 La funzione F(...) non è codificata con A6 A5 A4 A2 11 DOCNO/LVL/SEL, manca blank dopo ')' 12 Valore range non numerico 13 Range errato: minimo > massimo 14 Non eseguita in precedenza la procedura INQOPNSP/INQSETDB 15 Valore numerico negativo/errato/omesso 16 Livello domanda > = di quello corrente 18 Operatore mancante: assunto per default 19 Operatore errato: assunto per default 20 La domanda termina con un operatore 21 sequenza parentesi errata 22 SEL: abbreviazione campo formattato errata 23 SEL: operatore *XX errato 24 SEL:'valore' errato per il tipo campo 25 SEL: lunghezza valore immesso > lunghezza campo 26 SEL: valore confronto errato o mancante 27 Range: valore iniziale > valore finale 28 Valore > 40 caratteri / errore di sintassi 30 ID campo specificato errato/non esiste 31 Puntualizzati più di 20 campi 32 Abbreviazione campo errata Interrogazioni 9-8 ICARO Guida Programmatore

105 33 Più di un simbolo radice ($) 34 Più di un simbolo desinenza (%) 35 Più di un simbolo di range (/) 36 Simboli range e radice non possono essere usati insieme 37 Simboli inclusione (.) / esclusione (:) non possono essere usati insieme nello stesso operando 38 Troppi simboli di inclusione (.) 39 Troppi simboli di esclusione (:) 40 Simbolo troncamento/range segue inclusione/esclusione 41 Valore range non numerico 42 Caratteri errati o spazi nel termine 43 IMG(image): manca termine o parentesi 44 IMG: Carattere non ammesso dopo ')' 45 Abbreviazione campo mancante in tutte le b. dati 46 Valore troncamento ($ % ) : 1-9 non validi 47 File WICAxxxxxx/INWOR bloccato da altro lavoro 48 Troppi termini nella domanda (aumentare il limite nella definizione del profilo utente) &ERRTEX 40 car. Testo dell'errore secondo la lingua selezionata &RTN 1 car. Codice di ritorno a conclusione della routine 1 Il controllo della domanda si è concluso con successo (non ci sono errori o solo errori non gravi) 2 Errori gravi nel testo della domanda (vedi il codice nel campo &CODER e &ERRTEX. Nota: Se la routine viene chiamata con &RTN impostato ad F il programma INQCHK va a termine chiudendo tutti i file. Questa funzione è eseguita automaticamente dalla routine INQDLT (vedi più avanti). ICARO Guida Programmatore 9-9 Interrogazioni

106 Attivazione di un formato di visualizzazione/stampa Normalmente ICARO assume per la visualizzazione/lista/ordinamento dei documenti il formato di default di visualizzazione/stampa definito nel formato '00'. Per ogni banca dati è possibile definire fino a 99 formati differenti di visualizzazione e stampa. Il formato di visualizzazione/stampa può essere selezionato da una lista di formati esistenti o assegnata direttamente da uno specifico numero di formato. Selezionare un formato da una lista disponibile di formati: TEXINQF Se si desidera visualizzare la finestra-menu per la scelta interattiva dei formati o per selezionare un formato esistente da una lista autorizzata, immettere i seguenti comandi: OVRDSPF TEXDSPF ICA$BAS/TEXDSPFx (Dove x=codice lingua) CALL ICA$BAS/TEXINQF(&NJOB &LANG &QRYNUM) I parametri di TEXINQF sono i seguenti: &NJOB 6 car. Impostare 6 caratteri contenente il numero del job (per reperire tale valore l'utente usare il comando RTVJOBA) &LANG 1 car. Impostare il codice lingua (1=Italiano. 2=Inglese...) &QRYNUM 7 num. Impostare il numero sequenziale del livello della domanda, dopo il completamento con successo di INQR01 Assegnazione di un formato mediante il suo codice: INQSETFO Per assegnare un formato specifico per ogni banca dati, richiamare la routine INQSETFO: CALL ICA$BAS/INQSETFO (&NJOB &QRYNUM &MDB &FOR) I parametri di INQSETFO sono i seguenti: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. Immettere il numero sequenziale del livello della domanda, dopo il completamento con successo di INQR01 Interrogazioni 9-10 ICARO Guida Programmatore

107 &MDB 27 car. Immettere in questo campo 1 o più (massimo 9) codici di banche dati, per es.: ' ' per le banche dati 002, 008, 022 e 351 &FOR 18 car. Immettere i corrispondenti codici di formato (massimo 9): ogni formato è contrassegnato, nel campo, con 'due cifre. Quando il formato di visualizzazione/stampa è indicato con '00' viene mantenuto quello di default Reperire il risultato della domanda - RTVRSL Il risultato di una domanda contiene per ogni banca dati, il numero totale dei documenti ritrovati e delle ricorrenze. Se necessario, dopo l'esecuzione della routine INQCHK, viene richiamata la routine RTVRSL per visualizzare il totale delle ricorrenze e dei documenti (controlla se la query ha trovato dei documenti risultanti). Eseguire il comando: CALL ICA$BAS/RTVRSL (&NJOB &QRYNUM &MDB &SDOC &SOCC + &SBIDI &SFOR &QRYTYP &RTN) I parametri di RTVRSL sono i seguenti: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. Immettere il numero sequenziale del livello della domanda ottenuto dopo il completamento con successo delle API INQR01 o INQSNQRY dopo l'elaborazione si ricevono i campi: &MDB 27 car. Si ricevono da 1 a 9 codici di banche dati attivate per la query, per es.: ' ' per le banche dati 002, 008, 022 e 351 &SDOC 45 num (9 elementi x 5 packed) contenente per ogni banca dati del parametro &MDB il numero dei documenti estratti nell'elaborazione della domanda &SOCC 45 num (9 elementi x 5 packed) contenente per ogni banca dati del parametro &MDB il numero delle ricorrenze ritrovate nell'elaborazione della domanda &SBIDI 9 car. (9 elementi x 1 car.) contenente per ogni banca dati del parametro &MDB il tipo di banca dati: 1=LTR, 2=BIDI ICARO Guida Programmatore 9-11 Interrogazioni

108 &SFOR 18 car. (9 elementi x 2 car.) contenente per ogni banca dati del parametro &MDB il tipo di formato per la visualizzazione/stampa: '00-99' &QRYTYP 1 car. '1' se la domanda è formulata in formato LTR '2' se la domanda è formulata in formato BIDI &RTN 1 car. Codice di ritorno del risultato della routine RTVRSL: E Non trovato il numero della domanda (come indicato in QRYNUM) W Tempo scaduto, risultato ancora in elaborazione. Ripetere la routine RTVRSL Blank Routine conclusa normalmente. Visualizza lista delle ricorrenze dell'ultima domanda: INQDSPOC La routine INQDSPOC visualizza la lista delle ricorrenze relative all'elaborazione dell'ultimo risultato completato positivamente dalla routine INQCHK. Il comando è il seguente: CALL ICA$BAS/INQDSPOC (&NJOB &RETURN) I parametri della routine INQDSPOC sono: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &RTN 1 car. Codice di ritorno E L'ultima Query non è stata elaborata. o la routine INQOPNSP non è stata eseguita 3 L'utente ha premuto il tasto F3 per uscire dal programma 2 L'utente ha premuto il tasto F12 per annullare/ritornare Blank L'utente ha premuto il tasto Invio, completamento normale Selezione del tipo di output del risultato: INQDSPOP Se il modo di output del risultato della domanda non è stato preventivamente determinato dal programma (o dall'interfaccia di ricerca), richiamare la routine INQDSPOP per permettere all'utente di visualizzare in una finestra il menu con le possibili opzioni di output (visualizzazione, lista abbreviata, stampa dei documenti estratti). Il comando è il seguente: CALL ICA$BAS/INQDSPOP (&NJOB &QRYNUM &OPTION) Interrogazioni 9-12 ICARO Guida Programmatore

109 I parametri della routine INQDSPOP sono i seguenti: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. Immettere il numero sequenziale del livello della domanda, dopo il completamento con successo delle API INQR01 o INQSNQRY &OPTION 1 car. Dopo l'esecuzione conterrà l'opzione selezionata 1 Richiesta lista abbreviata 2 Richiesta visualizzazione documenti 3 Richiesta stampa R/Blanck Premuto F12=Annullamento/ritorno F Premuto F3=Fine Visualizzazione dei documenti estratti: INQDSPDO Dopo l'eleborazione della domanda (INQCHK) l'utente può richiedere la visualizzazione di tutti i documenti estratti. Eseguire il seguente comando: CALL ICA$BAS/INQDSPDO (&NJOB &QRYNUM &EXDOC &EXDBAS + &EXDSEQ &RTN) I parametri di INQDSPDO sono i seguenti: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. &EXDOC 7 num. &EXDBAS 3 num. &EXDSEQ 7 num. Immettere il numero sequenziale del livello della domanda, dopo il completamento con successo delle API INQR01 o INQSNQRY Riceve l'eventuale numero del documento su cui l'utente ha premuto il tasto per la routine di Exit (F20) durante la visualizzazione Riceve il codice della banca dati in cui l'utente ha premuto il tasto per la routine di Exit (F20) Contiene l'ordine/sequenza del documento su cui è stato premuto il tasto F20 durante la visualizzazione. Questo numero d'ordine indica la posizione occupata dal documento tra i documenti estratti: per es. il documento numero (EXDOC=100345) è il 7 (EXDSEQ=7) tra tutti i documenti estratti dalla banca dati di codice 111 (EXDBAS=111) come risulta dalla domanda numero 1 (QRYNUM=1) ICARO Guida Programmatore 9-13 Interrogazioni

110 &RTN 1 car. Codice di ritorno: E Numero livello domanda non trovato (l'ultima domanda è indicata in QRYNUM): la domanda non è stata immessa o la routine INQOPNSP non è stata eseguita o non ci sono documenti o la domanda è ancora in elaborazione X E' stato premuto il tasto di EXIT F20 durante la visualizzazione di un documento. Vedi i valori dei parametri EXDOC, EXDBAS e EXDSEQ 3 L'utente ha premuto il tasto F3 per uscire dal programma O L'utente ha premuto il tasto F12 per annullare/ritornare Nota: La routine INQDSPO utilizza quali parametri di visualizzazione/stampa quelli dei formati video e stampa di default (F00) o quelli dell'ultimo formato definito con l'ultimo richiamo della routine INQSETFO (l'ultimo che è stato storicizzato). Visualizza lista abbreviata documenti estratti: INQDSPLI/INQDSPLX Dopo l'elaborazione di una domanda avvenuta con successo (INQCHK) l'utente può richiedere la visualizzazione di una lista abbreviata di tutti i documenti estratti. La lista abbreviata permette all'utente di selezionare il documento da visualizzare o stampare o su cui eseguire l'exit (opzione 8) ad un programma EXTINQ (INQDSPLI e INQDSPLX sono differenti: vedi la nota successiva). Eseguire il seguente comando: CALL ICA$BAS/INQDSPLI (&NJOB &QRYNUM &EXDOC &EXDBAS + &EXDSEQ &RTN) Oppure: CALL ICA$BAS/INQDSPLX (...) I parametri di INQDSPLI/INQDSPLX sono i seguenti: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. Immettere il numero sequenziale del livello della domanda ottenuto dopo il completamento con successo delle API INQR01 o INQSNQRY &EXDOC 7 num. Riceve il numero del documento che l'utente ha selezionato con l'opzione 8 o F20 di EXIT o si trasmette il numero di documento da cui iniziare la visualizzazione. &EXDBAS 3 num. Riceve il codice della banca dati del documento selezionato con l'opzione 8 o F20 di Exit o si trasmette al programma il codice della banca dati del parametro EXDOC. Interrogazioni 9-14 ICARO Guida Programmatore

111 &EXDSEQ 7 num. Questo campo contiene l'ordine/sequenza del documento nel campo &EXDOC. Questo numero d'ordine indica la posizione occupata dal documento tra i documenti estratti: per es. il documento numero (EXDOC=100345) è il 7 (EXDSEQ=7) tra tutti i documenti estratti dalla banca dati numero 111 (EXDBAS=111) come risulta dalla domanda numero 1 (QRYNUM=1) &RTN 1 car. Codice di ritorno o di azione: E Numero livello domanda non trovato (l'ultima domanda è indicata in QRYNUM): la domanda non è stata immessa o la routine INQOPNSP non è stata eseguita o non ci sono documenti o la domanda è ancora in elaborazione X E' stata richiesta una routine di EXIT (opzione 8 durante la visualizzazione della lista abbreviata). I valori dei parametri EXDOC, EXDBAS e EXDSEQ sono restituiti da INQDSPLI, ma non da INQDSPLX Y E' stata richiesta una routine di EXIT (F20 nella visualizzazione del documento selezionato dalla lista abbreviata con l opzione 5). I valori dei parametri EXDOC, EXDBAS e EXDSEQ sono restituiti da INQDSPLI, ma non da INQDSPLX. Richiamando la routine con &RTN=Y si avvierà la visualizzazione del documento del parametro &EXDOC prima della lista abbreviata. A Non autorizzato alla lista abbreviata 3 L'utente ha premuto il tasto F3 per uscire dal programma O L'utente ha premuto il tasto F12 per annullare/ ritornare Nota: La routine INQDSPLI utilizza quali parametri di visualizzazione/stampa quelli dei formati video/stampa di default (F00) o quelli definiti con l'ultimo richiamo della routine INQSETFO (l'ultimo che è stato storicizzato). Differenza tra INQDSPLI e INQDSPLX: Se l'opzione 8 (Exit) viene selezionata durante la visualizzazione della lista abbreviata, la routine INQDSPLI termina l'esecuzione ritornando al programma chiamante con il codice di ritorno X. Il programma principale dovrà così eseguire il programma di exit EXTINQ per il (primo) documento selezionato (altre opzioni, se effettuate, vengono ignorate). Al contrario, la routine INQDSPLX non ritorna il codice X al programma principale, ma esegue al suo interno (una volta o più volte) il programma EXTINQ per tutte le opzioni 8 selezionate. (in questo caso può verificarsi un errore di ricorsività se EXTINQ richiama direttamente o indirettamente la routine INQDSPLX). ICARO Guida Programmatore 9-15 Interrogazioni

112 Stampa dei documenti estratti: INQSNPRT Dopo l'elaborazione con esito positivo di una domanda (INQCHK) l'utente può avviare la stampa di tutti i documenti estratti. Eseguire il seguente comando: CALL ICA$BAS/INQSNPRT (&NJOB &QRYNUM &DBNR &NDOC &FORM &RTN) I parametri di INQSNPRT sono i seguenti: &NJOB 6 car. Immettere 6 caratteri contenente il numero del job (per reperire tale valore l'utente userà il comando RTVJOBA) &QRYNUM 7 num. Immettere il numero sequenziale del livello della domanda, ottenuto al completamento con successo delle API INQR01 o INQSNQRY. Questo campo può essere zero se l'utente desidera stampare uno specifico documento e sarà sostituito dal parametro &NDOC &DBNR 3 num. Numero della banca dati da cui si intende stampare il documento o i documenti &NDOC 7 num. Numero del documento se QRYNUM è uguale a 0. Se QRYNUM contiene il numero della domanda, NDOC è diverso da 0 &FORM 2 car. Contiene il codice del formato di visualizzazione/stampa, se l'utente chiede la stampa di uno specifico documento (&NDOC>0) &RTN 1 car. Codice di ritorno A Utente non autorizzato per la stampa di documenti da questa banca dati R Manca domanda/risultato W Elaborazione non completata, attendere e riprovare dopo pochi secondi (2-3) P Parametri errati L Libreria WICAXXXX o ICA$nnn non trovata (INQOPNSP non è stato eseguito in precedenza) 1 Stampa avviata con successo 2 La richiesta di stampa è soggetta a specifiche limitazioni per il profilo utente (un numero massimo di documenti da stampare è stato specificato nella 'gestione profilo utente' da parte del gestore di ICARO). Nota: La routine INQSNPRT stamperà i documenti secondo i parametri del formato video/stampa di default (F00), o del formato attivato dall'utente con l'ultimo richiamo della routine INQSETFO (l'ultimo che è stato storicizzato). Interrogazioni 9-16 ICARO Guida Programmatore

113 Procedura di estrazione dei documenti: INQEXCES Dopo l'elaborazione con esito positivo di una domanda (INQCHK) l'utente può avviare la richiesta di estrazione di tutti i documenti. Eseguire il seguente comando: CALL ICA$BAS/INQEXCES (&QRYNUM &DBNR &PROC &RTN) I parametri di INQEXCES sono i seguenti: &QRYNUM 7 num. Immettere il numero sequenziale del livello della domanda ottenuto dal completamento con successo delle API INQR01 o INQSNQRY &DBNR 3 num. Numero della banca dati da cui si intende estrarre il documento o i documenti &PROC 2 car. Codice della procedura di estrazione dati; essa è specificata nell'opzione 'Definizione procedura di estrazione dati' del menu 'Definizione banche dati' &RTN 1 car. Codice di ritorno 3 L'utente ha premuto il tasto F3=Fine W L'elaborazione della domanda non è stata completata, attendere e ripetere. E Errore banca dati (non esiste, non autorizzata, questa estrazione dati non è autorizzata per questo profilo utente) B Job sottomesso a procedura batch in coda lavoro (se la procedura è stata specificata come 'B' - batch). La procedura di estrazione duplica il file TXFxx (xx codice della procedura) che si trova nella libreria ICA$ddd (ddd codice della banca dati) nella libreria QTEMP e vi scrive, i campi previsti dalla procedura di estrazione prelevanti da ciascun documento risultante dall interrogazione. Sul file TXFxx la procedura INQEXCES, esegue il programma di estrazione il cui nome è anche TXFxx; questo programma, dopo la creazione del file nella libreria QTEM, esegue la procedura od il programma previsto nella definizione della procedura. Se si desidera utilizzare i dati provenienti dall estrazione dei documenti ICARO per aggiornare direttamente un data base dell utente si legga il paragrafo Modifica una procedura di estrazione per aggiornare un data base utente in questo capitolo. ICARO Guida Programmatore 9-17 Interrogazioni

114 Routine di EXIT di visualizzazione documenti: EXTINQ La routine o programma utente EXTINQ può essere richiamato da un utente durante la visualizzazione del documento. Questa routine normalmente permette di prelevare specifiche informazioni dai campi/paragrafi del documento attivando altri programmi, per es. visualizzazione immagini collegate, navigare ad altra banca dati e visualizzare i documenti ad essa connessi (relazioni ipertestuali) ecc.. Dalla visualizzazione di un documento, EXTINQ è attivato con la pressione del tasto 'F20=...' (la descrizione di questo tasto funzione può essere modificata usando il menu 'Definizione/modifica banca dati') Dalla lista abbreviata, EXTINQ è attivato, per un documento, con la selezione dell'opzione 8. Il programma esterno EXTINQ, è richiamato con il seguente comando: CALL ICA$BAS/EXTINQ (&MDB &NJOB &DBNR &QRYNUM &NDOC) I parametri di EXTINQ sono: &MDB 27 car. Questo campo contiene 1 o più (massimo 9) codici di banche dati selezionate nell'interrogazione, per es.: ' ' per le banche dati 002, 008, 022 e 351 &NJOB 6 car. Campo alfa di 6 caratteri contenente il numero del job che richiama la routine &DBNR 3 num. Numero della banca dati del documento su cui è stato attivato la funzione di EXIT &QRYNUM 7 num. Numero sequenziale del livello della domanda &NDOC 7 num. Numero del documento da cui è stata attivata la funzione di EXIT (F20/8 nella lista abbreviata). Interrogazioni 9-18 ICARO Guida Programmatore

115 Visualizzazione di un documento di cui è noto il numero di riferimento: DSPDOC01 Può risultare particolarmente utile in un'applicazione utente visualizzare direttamente un documento di cui si conosce il numero sequenziale di ICARO, utilizzando nella costruzione della domanda l'operatore DOCNO(nnnnnnn). La visualizzazione diretta può essere richiesta da una qualunque applicazione, se è stata preventivamente avviata la routine INQOPNSP ed è stata aggiunta alla lista di librerie la libreria (ICA$nnn) della banca dati contenente il documento (dove nnn è il numero della banca dati). Eseguire il seguente comando: OVRDSPF TEXDSPF ICA$BAS/TEXDSPFx (x=lingua, per es. 2) CHGCURLIB ICA$nnn (nnn=banca dati) CALL ICA$BAS/DSPDOC01 (&DBNR &DBNAME &NUMDOM &NDOC + &SEQFLD &BIDI &DOCMIN &DOCMAX &EXTDES &LANG &SIF8 + &EXPOR &STAMP &SIOCC &FORMAT &RTN) I parametri di DSPDOC01 sono i seguenti: &DBNR 3 num. Numero banca dati &DBNAME 40 car. Nome/descrizione banca dati &NUMDOM 7 num. Livello domanda. Impostare a 0 &NDOC 7 num. Numero documento da visualizzare &SEQFLD 1536 car. Contiene 512 elementi di tre caratteri ZONED indicanti (a partire da sinistra) i codici dei paragrafi/campi da visualizzare. I codici dei campi formattati sono incrementati di 256. Esempio: visualizza il campo formattato 003 e i paragrafi 002, 004 e 012 &BIDI 1 car. Immettere il tipo banca dati '1' banca dati LTR '2' se la banca dati è BIDI DOCMIN 7 num. impostare a 1 &DOCMAX 7 num. impostare a 1 &EXTDES 15 car. Specificare la descrizione desiderata per 'F20=...' &LANG 1 car. Codice lingua: '2' per l'inglese, '1' Italiano ecc. &SIF8 1 car. Impostare a '0' &EXPOR 1 car. Autorizzazione esportazione documento. '0' (non attiva la esportazione) '1' (autorizza l'esportazione) &STAMP 1 car. Impostare a '0' &SIOCC 1 car. Impostare a '0' &FORMAT 2 car. Impostare a '00' per il formato di default o il codice di un formato esistente di cui utilizzare le opzioni di visualizzazione/stampa ICARO Guida Programmatore 9-19 Interrogazioni

116 &RTN 1 car. Impostare a 'Z'quando l'utente ha terminato di visualizzare il documento, ciò al fine di procedere alla corretta chiusura dei file. Un esempio della routine DSPDOC01 è nel file EXAMPLE della libreria ICA$BAS col nome TSTDSPDO. Questo esempio è compilato nella banca dati di test ICA$032. Per eseguire il test immettere: CALL ICA$032/TSTDSPDO (X' F') per visualizzare il documento numero 2. Chiusura di una sessione di interrogazione: INQDLT Da utilizzare nel programma MAIN alla fine del ciclo di interrogazioni Per ultimare correttamente un ciclo di interrogazione e chiudere tutte le routine ed i file lasciati aperti eseguire: CALL ICA$BAS/INQDLT (&LINGUA) I parametri di INQDLT sono i seguenti: &LINGUA 1 car. Codice lingua: '2' per l'inglese, '1' Italiano ecc. Dopo l esecuzione di questa routine il richiamo di una funzione di interrogazione deve iniziare con INQOPNSP. Se la sessione di interrogazione si chiude con SIGNOFF eseguire anche INQDLTSP. Esempi di navigazione ipertestuale Insieme al prodotto sono fornite delle banche dati di example per verificare un modo, alquanto semplice, per effettuare una navigazione ipertestuale ovvero, visualizzando un documento, di utilizzare parti di informazioni in esso contenute per effettuare una ricerca automatica su un altra banca dati o sulla stessa banca dati. Questo lo si effettua con un utilizzo delle API s di interrogazione. Effettuando un interrogazione nella banca dati di example 024 Sinonimi, immettere la domanda: DELINQUENTE e premere INVIO; visualizzare il documento risultante e premere il tasto di EXIT F20; saranno visualizzati i documenti della banca dati 023 Archivio bibliografico che contengono tutte le parole contenute nel precedente documento di sinonimi. Per la codifica verifica il programma source EXTINQ della libreria ICA$024. Analogamente, interrogare la banca dati 030 Giurisprudenza amministrativa ed immettere la domanda: Protezione del patrimonio naturale e premere INVIO; visualizzare il documento o la lista abbreviata e scegliere la funzione di EXIT F20; saranno visualizzate le leggi della banca dati 028 connesse con la giurisprudenza. Verifica il source EXTINQ nella libreria ICA$030. Un altro esempio è fornito dalla banca dati 035 Anamnesi. Effettuare la domanda: FUMATRICE e premere invio e visualizzato il documento premere F20; un menu utente dà la possibilità di accedere ai corrispondenti documenti o della banca dati Analisi paziente o diario clinico ed esami strumentali ; per visualizzare le immagini della banca dati Analisi strumentali si leggano le note nel manuale dell utente relative all installazione nel paragrafo Definizioni del PC support. Verifica il source EXTINQ nelle librerie ICA$035, ICA$036, ICA$037. Interrogazioni 9-20 ICARO Guida Programmatore

117 Modifica una procedura di estrazione per aggiornare direttamente un data base utente. Se si desidera che una procedura di estrazione aggiorni o aggiunga record direttamente in un data base utente, con dei parametri, operare come segue: Creare una procedura di estrazione contenente tutti i campi o paragrafi necessari ad aggiornare o ad aggiungere records nel data base utente; (sarà creata nella banca dati ICA$bbb il programma source ed il source del file di estrazione di nome TXFxx (xx nome della procedura); Duplicare il source del programma TXFxx ad esempio con il nome TXFxxNEW nella stessa libreria della banca dati ICA$bbb e produrne una stampa. Nel source noterete che nelle colonne 3-5 di alcune specifiche vi è un identificativo come Ix o Mx o Dx esse sono i punti in cui inserire istruzioni o da modificare o eliminare. Diamo un dettaglio dei singoli punti del source. Iden. Azione I1 In questo punto inserire la specifica di file per identificare il file utente da aggiornare o in cui accodare i record provenienti da ICARO. I2 Inserire, se necessario, le specifiche I di Input relative alla definizione della struttura dati DS della data area, creata dall utente, per passare al programma eventuali parametri necessari alla determinazione di costanti o variabili per l aggiornamento dei record del data base utente; I3 Inserire, se necessario, la lettura della data area di cui al punto I2 o in alternatica la call ad un programma utente per ricevere parametri per la determinazione di costanti o variabili per l aggiornamento dei record del data base utente; D1-D2 Cancellare tutte le specifiche comprese tra D1 e D2 esse stesse comprese; Infatti non sono più utili utilizzandosi un data base utente come output; lasciare invece l istruzione successiva a D2 relativa all open del file TXFxx. I4 Prima di questa istruzione, il programma ha determinato, per ciascun documento tutti i campi da estrarre; I campi estratti hanno la label Pxxx per i paragrafi (con xxx codice paragrafo) ed Fxxx (con xxx codice campo) per i campi formattati selezionati per l estrazione; Se il file utente è di tipo Update occorrerà, come prima istruzione aggiungere l istruzione di ricerca del record usando ad esempio uno dei campi formattati, per ciascun documento, proveniente da ICARO es: Fxxx CHAIN FILUSR XX Questa istruzione non è necessaria se il file utente è di solo Output. A questo punto, bisogna spostare nei singoli campi del record del file utente i campi provenienti dai documenti ICARO o calcolati o provenienti da data area utente (punto I2 e I3) es.: ICARO Guida Programmatore 9-21 Interrogazioni

118 C*Per campi alfabetici C MOVELP002 RAGSOC C MOVELP004 INDIR C MOVELF002 TITOLO C *Per campi numerici C MOVE F002 COART C MOVE F016 CODCLI C M1 M2 I5 Se è necessario utilizzare il numero documento ICARO in un campo del file utente sostituire il nome del campo del risultato C81 con il nome del campo utente; viceversa eliminare questa riga di istruzione. Aggiungere nelle colonne l indicatore LR per evitare che record vengano scritti nel file TXFAAA. Inserire in questo punto le istruzioni di scrittura record C XX WRITE FILUSR C NXX UPDAT FILUSR o semplicemente se il file è di solo output C WRITE FILUSER Il terzo elemento di tabella della schiera OVR contiene il comando della procedura da eseguire dopo la scrittura dei records nel file, se richiesto puo essere modifico. Compilare il programma TXFxxNEW con il nome dell oggetto TXFxx nella libreria della banca dati ICA$bbb sostituendo così il programma oggetto creato da ICARO. Aver cura prima di compilare il programma di aggiungere nella lista delle librerie sia la libreria della banca dati ICA$bbb sia la libreria dove risiede il file utente FILUSR. In sede di esecuzione accertarsi che il file utente sia disponibile nella library list. Un esempio di modifica di una procedura di estrazione è contenuta nella banca dati di example 023 Archivio bibliografico; si vedano le differenze tra il source TXFAA e TXFAANEW; eseguendo la procedura di estrazione dopo una query ICARO, viene visualizzato il file utente FILUSR aggiornato dalla procedura di estrazione. Nella libreria ICA$023 sono contenute le specifiche source del file utente index aggiornato dalla procedura; Le modifiche prevedono anche l uso di una data area che contiene un literal da scrivere su ogni record aggiornato nel data base utente. La data area potrebbe ad esempio contenere il nome della libreria che contiene la versione del file da aggiornare in modo tale che nel punto I3 l utente inserisca le istruzione per eseguire un OVRDBF e l OPEN del file. Interrogazioni 9-22 ICARO Guida Programmatore

119 Altre routine. Reperire le banche dati attive per l interrogazione e l ultimo numero di livello. RTVOPNDB Se si desidera, da una applicazione utente (esempio da una exit durante la funzione di interrogazione) conoscere le banche dati attive (max 9) eseguire CALL ICA$BAS/RTVOPNDB (&QRYNUM &CODDB &DESDB) con &QRYNUM *dec 7 0 Viene tornato in questa variabile il numero di livello dell ultima query. &CODDB *char 27 Schiera di 9 elementi di 3 caratteri *char; essa conterra i 9 codici massimo di banche dati selezionate per l inquiry. &DESDB *char 360 Schiera di 9 elementi di 40 caratteri *char; essa contiene le denominazioni delle 9 banche dati. Un esempio di utilizzo della routine il programmatore puo ritrovarlo nel source del programma RPG PGMWC utilizzato per la funzione di EXIT WC nella composizione della domanda (file EXAMPLE di ICA$BAS) Reperire alcuni termini di una banca dati (per formulare una query) RTVTERM Può essere necessario prelevare da una banca dati dei termini per comporre una specifica domanda. La routine RTVTERM consente di ricercare tutti i termini di una banca dati secondo le specifiche WILD CARD restituendo una schiera di 6000 caratteri contenente una struttura, preparata, contenente tra parentesi i termini estratti in relazione OR per la query, del tipo: ( termine1 OR termine2 OR... ) le specifiche sono: CALL ICA$BAS/RTVTERM (&TERM &DB &ARAB &TIPO &WORD) con &TERM *CHAR 40 Deve contenere il criterio WILD CARD di estrazione dei termini. Vedi appresso criterio WILD CARD ICARO Guida Programmatore 9-23 Interrogazioni

120 &DB *DEC 3 Deve contenere il codice della banca dati di cui utilizzare il dizionario per l estrazione dei termini. &ARAB *CHAR 1 Indicare 1 se si desidera ricevere la stringa &WORD in modalità LTR o 2 in forma inversa per elaborazioni arabe (RTL). &TIPO *CHAR 1 Indicare 1 per ricevere i termini nella forma normalizzata (termini base) o 2 se si desidera ricevere i termini nel formato reale cioè così come scritti nel documento nella loro forma maiuscola o minuscola e/o con caratteri speciali. &WORD *CHAR 6000 Struttura di 6000 caratteri che conterrà, tra parentesi i termini estratti separati dalla relazione OR: (term1 or term2 or term3...); se &TIPO è impostato a 2 la stringa sarà del tipo: (img(term1) or img(term2) or img(termx) ) Criteri WILD CARD Nel campo &TERM l utente deve immettere un set di caratteri secondo le specifiche wild card. La struttura Wild card è composta da un set di caratteri alfanumerici ove si possono trovare i caratteri speciali * o _ ; Il carattere asterisco (*) immesso indica che sono accettati un numero indefinito di caratteri, mentre ogni carattere sottolineato (_) indica che in quella posizione può trovarsi un solo carattere. Esempi: I_m* accetta termini quali IBM, IMMED, IMMEDIATO in quanto i termini devono iniziare per I, essere seguiti, come secondo carattere, da un carattere qualsiasi, nel terzo carattere vi deve essere una M e sono accettati tutti i termini che da quarto carattere hanno un blanc o un numero di caratteri diverso da blanc; altri esempi: *ZIONE STA* accettare tutti i termini che finiscono con AZIONE con un numero illimitato di caratteri precedenti. accettare tutti i termini che iniziano con STA con un numero illimitato di caratteri seguenti. ZIONE (LOZIONE, FAZIONE...) accettare tutti i termini che hanno due caratteri qualunque che precedono il set ZIONE. e così via: CA*F CA*S_M* CA*S M* ecc... Nota: non far seguire tra loro il simbolo asterischi (*) con sottolineato (_); tra questi simboli vi dovrebbe essere almeno un carattere. Ricerche con il simbolo * o _ a colonna 1, ovvero come primo carattere del criterio di ricerca richiedono alti tempi di elaborazione (es. *zione, ma*..), se possibile far precedere almeno un carattere valido iniziale per ridurre sensibilmente i tempi di ricerca. Interrogazioni 9-24 ICARO Guida Programmatore

121 Capitolo 10. Ricorsività dei programmi La routine CRTRCR Se in una banca dati l'utente crea un criterio di navigazione tra documenti della stessa o altra banca dati utilizzando la routine RPG 'EXTINQ', può verificarsi un errore di 'ricorsività' in quanto un programma RPG non può richiamare se stesso. Ciò accade quando 'EXTINQ' richiama la routine INQDSPDO con il parametro RETURN='X' (il programma di richiamo EXTINQ richiamerebbe se stesso). EXTINQ INQDSPDO EXTINQ Per risolvere tale problema, usare la routine CRTRCR prima dell'esecuzione del programma che necessita di ricorsività; la routine provvederà a memorizzare il pgm 'ricorsivo' in QTEMP con un nuovo nome e restituirà nel parametro NEWPGM il nuovo nome da utilizzare per un nuovo richiamo. CALL ICA$BAS/CRTRCR (&LIB &PGM &NEWPGM) NEWPGM conterrà il nuovo nome di richiamo. I parametri CRTRCR sono i seguenti: &LIB 10 car. Libreria contenente il programma 'ricorsivo' (per es. ICA$nnn, ICA$BAS...). &PGM 10 car. Nome del programma 'ricorsivo' (per es. EXTINQ). &NEWPGM 10 car. Nuovo nome del programma 'ricorsivo' calcolato dalla routine. Il programma dell'utente (es. INQDSPDO) eseguirà il comando: CALL QTEMP/&NEWPGM e non CALL ICA$xxx/EXTINQ ICARO Guida Programmatore 10-1 Ricorsività

122 Pagina vuota Gestione Documenti 10-2 ICARO Guida Utente

123 Capitolo 11. Esempi di estrazione ed esportazione dati Le procedure di estrazione di dati si possono definire utilizzando l'opzione 11 del menu 'Definire una banca dati'. Ciascuna procedura (identificata da due lettere da 'aa' a 'ZZ') specifica quali campi/paragrafi dei documenti recuperati dovranno essere registrati in un formato di file su disco e quale procedura (o programma) dovrà essere eseguito per elaborare il file creato. (Guida utente capitolo 5) Il file creato dalla definizione della procedura di estrazione si chiama 'TXFXX' dove 'XX' è il nome della procedura (es. TXFPD se il nome della procedura è 'PD'). Questo file viene creato nella libreria della banca dati ICA$nnn (es. ICA$005 se il numero della banca dati è '005'). In fase di esecuzione, il file TXFxx è copiato dalla libreria ICA$xxx nella libreria QTEMP con il nome di: TXFnnnXX, dove 'nnn' è il codice della banca dati e 'XX' è il nome della procedura (es. TXF005PD per la procedura 'PD' della banca dati '005'). I campi/paragrafi (o parti di campi) dei documenti reperiti in interrogazione saranno scritti nel file QTEMP/TXFnnnXX. Durante la definizione della procedura, l'utente può specificare quale funzione (es. COPY) o quale programma eseguire (interattivo o batch) sul file creato dalla stessa procedura di estrazione. ISTOGRAMMA di frequenza (TEXDIAALF / TEXDIANUM) Lo scopo di un istogramma di frequenza è quello di presentare graficamente il numero di ricorrenze di un termine trovato in un campo. Esempio: un gruppo di documenti recuperati contiene 100 record, un campo 'Città' è definito nella banca dati (questo campo contiene il nome di una città in ogni record). Una procedura di estrazione di dati carica il campo città ed esegue il programma di istogramma di frequenza: l'utente riceverà in visualizzazione un grafico con le differenti città trovate nel gruppo: Parigi 35 Londra 27 Roma 18 New York 10 Chicago 8 Bruxelles 2 L'esempio di programma TEXDIAALF crea un istogramma di frequenza utilizzando il file di output TXFxx composto solo da un campo di 20 caratteri alfanumerici. L'esempio di programma TEXDIANUM crea un istogramma di frequenza utilizzando il file di output TXFxx composto solo da un campo di 15 caratteri numerici. ICARO Guida Programmatore 11-1 Estrazione Dati

124 Per l'esecuzione di questi programmi: - Selezionare l'opzione 11 'Definire la procedura di estrazione' dal menu 'Definire una banca dati ICARO'. - Inserire il nome della procedura; nel video ICA128 si indicherà il nome del programma TEXDIA... che deve essere attivato dopo la creazione del file di output: CALL ICA$BAS/TEXDIAALF ('nnn' 'xx') CALL ICA$BAS/TEXDIANUM ('nnn' 'xx') dove: nnn è il codice della banca dati xx è il nome della procedura per un campo alfanumerico per un campo numerico - Selezionare solo 1 campo da caricare indicando la lunghezza (nel file di output dei campi formattati) di 20 se il campo da caricare è alfanumerico oppure di 15 se il campo è numerico. - Indicare '1' nella colonna K (KEY) per questo campo di output Un esempio di istogramma di frequenza l'utente lo può eseguire nella banca dati di test 030: dopo aver recuperato tutti i documenti (con la domanda 'ALLDOC'), eseguire la procedura di estrazione dati Trasferire su PC il risultato di una procedura di estrazione (EXTEXPD) Questa funzione, esegue il trasferimento del file TXFnnnxx, creato da una procedura di estrazione, dalla libreria QTEMP in un file su Personal Computer. Per l'esecuzione di questo programma immettere, nella definizione di una procedura di estrazione (video ICA128), la seguente procedura : CALL ICA$xxx/EXTEXPD ('TXFnnnyy') dove: nnn è il codice della banca dati yy xxx è il nome della procedura il codice della banca dati Eseguito questo comando, selezionare i campi desiderati in output indicando la loro lunghezza nel file di output TXFnnnxx. Il source CLP EXTEXPD si trova nel file example di ICA$BAS e dopo eventuali personalizzazioni và compilato nella libreria ICA$xxx. La procedura EXTEXPD esegue: - la copia del file fisico TXFyyynn dalla libreria Qtemp alla libreria di lavoro WICAxxxxx modificando il nome del membro uguale all area di lavoro wicaxxxxxx. Estrazione Dati 11-2 ICARO Guida Programmatore

125 - Crea nella libreria Qtemp nel membro FTPCMD1 del file RTFFILE i comandi FTP per copiare il file creato nel file System dell As400 \ICAROWRK l oggetto WICAxxxxxx.txt - Esegue dalla directory del file system \icaropgm il programma COPIA.exe che consente l invio di finestre windows per scegliere la path ed il nome da assegnare al file trasferito in un disco di rete. N.B. per eseguire questa funzione il programma CL, copiato ed eventualmente personalizzato nella libreria ICA$xxx (file qclsrc), deve essere compilato nella libreria ICA$xxx. La stazione di lavoro deve essere abilitata alle funzioni office setup per txtconv (vedi installazione guida utente 2-4). Realizzare prospetti o schemi con totali o calcoli dopo l'interrogazione Dopo aver estratto un gruppo di documenti da una banca dati ICARO, si possono realizzare prospetti numerici riepilogativi con totali o calcoli. Modificare il programma sorgente TXFxx sostituendo il comando WRITE (vedi sorgente) con: somma campi numerici, mostrare i risultati in una videata utente predefinita, stampa prospetti ecc.. Le indicazioni incluse possono quindi sostituire la creazione del file con altre attività quali l'emissione di una videata interattiva. ICARO Guida Programmatore 11-3 Estrazione Dati

126 Convertire e copiare un membro di file source o di testo Text Managem, in formato RTF (DOC) HTML o ASCII con output in un membro surce ed in un file system in un documento di tipo.doc o.html o.txt. Questa routine consente di convertire un membro source o un testo text management in un equivalente documento.doc (editabile con word) o HTML o ASCII. Il documento convertito mantiene gli attributi di marginatura e i caratteri sottolineati o grassetto se il documento è stato editato con il Text Management o se proviene da ICARO. Le funzioni svolte sono identiche alla funzione interattiva contenuta nel menu ICARO opzione 6 Office ed opzione 3 conversione. La routine permette al programmatore via batch di scaricare in un file system AS400 il documento proveniente da un file source AS/400 convertendolo in HTML TXT RTF utilizzabile sia dal WORD che da altri prodotti di office su pc. Il documento convertito si troverà anche in un file source della QTEMP di nome TOPC con lo stesso nome di membro. Il file PC con l'estensione.doc o.txt o.htm verrà trasferito con l'ftp all'indirizzo del file system AS specificato. Comando: CALL ICA$BAS/TXTTOPC1 (&LIB &FIL &MBR &MOD &SYSTEM &USER &PASSWOR &PATH) Dove: &LIB *char 10 Nome della libreria che contiene il file source &FIL *char 10 Nome del file source che contiene il membro &MBR *char 10 Nome del membro da convertire e trasferire &MOD *char 1 Codice conversione desiderata A=ASCII, R=RTF, H=HTML &SYSTEM *char 15 Indicare il nome del sistema server FTP in cui trasferire il documento PC convertito (può essere una path AS/400 creata nella route con il comando CRTDIR o un una path di un personal computer ove è installato l'ftp server). In sostituzione del nome (nel caso in cui non è usato un DNS per la risoluzione dei nomi in indirizzi IP) si può indicare direttamente l'indirizzo IP del sistema ricevente (es ) &USER *char 10 Indicare il nome utente riconosciuto ed autorizzato all'ftp. &PASSWORD *char 10 Indicare la password utente &PATH *char 75 Indicare la sola path di destinazione del documento (es. /ICARO/DOCUMENTI/ se nella route di destinazione esiste una directory di nome Icaro ed una sottodirectory DOCUMENTI). Estrazione Dati 11-4 ICARO Guida Programmatore

127 Nota bene. Il documeto verrà trasferito con lo stesso nome del membro da convertire con l'estensione.txt o.doc o.htm se è stato scelto rispettivamente il tipo di conversione A,R,H; Il trasferimento avverrà solo se i parametri &User &password &system e &Path risulteranno validi. Se il file nel Pc FTP di destinazione non dovesse essere presente consultare il log errori FTP (DSPPFM QTEMP/RTFFILE MBR(FTPOUT)). Il file di log si troverà nella libreria QTEMP della sessione. Indipendentemente dall'esito del trasferimento FTP del documento nel server verrà comunque creato nel file QTEMP/TOPC il documento convertito con lo stesso nome del membro di input che l'utente potrà utilizzare come vuole. (trasferirlo in un pc senza FTP con le funzioni del Client access o apportarvi eventuali modifiche come l'inserimento di comandi HTML in un membro convertito in HTML. ICARO Guida Programmatore 11-5 Estrazione Dati

128 Convertire e copiare un membro di file source o di testo Text Management in formato RTF (DOC) HTML o ASCII con output su sistema locale o un qualunque disco di rete. (DOCTOPC) Questa routine è una combinazione della routine TXTTOPC1 e della funzione di COPIA.exe (vedi più avanti). Mentre TXTTOPC1 effettua la conversione e la copia solo su un file system dell's/400, la routine DOCTOPC consente di trasferire il documento in una qualunque directory in rete anche quindi sul disco locale del PC inviando dopo la funzione di conversione una finestra WINDOWS per la scelta della path e del nome da assegnare al documento convertito. Comando: CALL ICA$BAS/DOCTOPC (&USER &PASSW &LIB &FIL &MBR &MOD &SYSTEM &PATH) Dove: &USER *char 10 Indicare il nome utente riconosciuto ed autorizzato all'ftp (esempio ICAROFTP). &PASSW *char 10 Indicare la password utente &LIB *char 10 Nome della libreria che contiene il file source &FIL *char 10 Nome del file source che contiene il membro &MBR *char 10 Nome del membro da convertire e trasferire. Viene restituito con il valore in presenza di errori di esecuzione. &MOD *char 1 Codice conversione desiderata A=ASCII, R=RTF, H=HTML &SYSTEM *char 15 Indicare il nome del sistema server FTP AS/400 o l indirizzo IP (es ) &PATH *char 75 Se lasciato blank l applicazione converte il documento e lo memorizza nella path di servizio \icarowrk ed immediatamente dopo invia la finestra windows di copia richiedendo all utente di immettere la path di destinazione ded il nome da assegnare al documento convertito (vedi COPIA.exe) Se viene immesso un valore di path esistente nel file system dell AS400 esempio /docum allora il documento verrà memorizzato col nome specificato nella variabile &MBR seguito dall estensione.doc o.htm o.txt.. Estrazione Dati 11-6 ICARO Guida Programmatore

129 Nota bene. Il documeto verrà trasferito con lo stesso nome del membro da convertire con l'estensione.txt o.doc o.htm se è stato scelto rispettivamente il tipo di conversione A,R,H; Il trasferimento avverrà solo se i parametri &User &password &system e &Path risulteranno validi. Se il file non dovesse essere presente nella path di destinazione consultare il log errori FTP (DSPPFM QTEMP/RTFFILE MBR(FTPOUT)). Il file di log si troverà nella libreria QTEMP della sessione. Indipendentemente dall'esito del trasferimento FTP del documento nel server verrà comunque creato nel file QTEMP/TOPC il documento convertito con lo stesso nome del membro di input che l'utente potrà utilizzare come vuole. (trasferirlo in un pc senza FTP con le funzioni del Client access o apportarvi eventuali modifiche come l'inserimento di comandi HTML in un membro convertito in HTML. Nella fiile source EXAMPLE di ICA$BAS è presente il sorgente di DOCTOPC ed un cl TDOCTOPC modificabile per testare, dopo la compilazione, le opzioni di richiamo della routine. Eventuali personalizzazioni dell utente alla routine DOCTOPC comporta la compilazione del programma nella libreria ICA$BAS. ICARO Guida Programmatore 11-7 Estrazione Dati

130 Importa e converti UN DOCUMENTO Office.doc, html txt in un membro di file source assegnato. DOCTOAS Questa routine utilizza la funzione di TXTCONV.exe e trasferisce un documento dalla rete, dopo averlo convertito in un membro source utente assegnato. Comando: CALL ICA$BAS/DOCTOAS (&USER &PASSW &FROM &MOD &LIB &FIL &MBR &NARSIN &MARDX &RIENT &ALLIN &RETUR) Dove: &USER *char 10 Indicare il nome utente riconosciuto ed autorizzato all'ftp (esempio ICAROFTP). &PASSW *char 10 Indicare la password utente &FROM *char 80 indicare la path ed il nome del documento es. \\sysas400\icarodoc\pluto.rtf o c:\pippo.doc Se lasciato blank l applicazione invia una finestra windows per la ricerca della path e del documento &MOD *char 1 Tipo documento in input (1= testo su una colonna 2= testo multicolonna) &LIB *char 10 Nome della libreria che riceverà il documento &FIL *char 10 Nome del file source che conterrà il documento &MBR *char 10 Nome da assegnare al documento convertito. &MARSIN *dec 3 0 Indicare il valore del margine sinistro in output es. 3. Questo valore è utilizzato per &mod = 2 &MARDX *dec 3 0 Indicare il valore del margine destro in output es. 3; Questo valore è utilizzato per &mod = 2 &RIENT *dec 3 0 Indicare il valore del rientro. Questo valore è utilizzato per &mod = 2 &ALLIN *char 1 Valore Y o N. Questo valore è utilizzato per &mod = 2 &RETURN *char 10 testo di eventuale codice di errore Estrazione Dati 11-8 ICARO Guida Programmatore

131 Nota bene. Il trasferimento avverrà solo se i parametri &User &password &system e &Path risulteranno validi. Se il file source specificato non dovesse contenere il documento consultare il log errori FTP (DSPPFM QTEMP/RTFFILE MBR(FTPOUT)). Il file di log si troverà nella libreria QTEMP della sessione. Nella fiile source EXAMPLE di ICA$BAS è presente il sorgente di DOCTOAS ed un cl TDOCTOAS modificabile per testare, dopo la compilazione, le opzioni di richiamo della routine. Eventuali personalizzazioni dell utente alla routine DOCTOAS comporta la compilazione del programma nella libreria ICA$BAS. Trasferimento documenti da file system PC a file fisico o IFS AS/400 e viceversa (PCTOPC). Il sorgente di questo programma CL è disponibile nel file example di ICA$BAS. Le note nel CL illustrano alcuni esempi applicativi. Comando: Call ICA$BAS/PCTOPC PARM(&PATI &PATO &SYST &USER &PWD &TIPO) Parametri: &PATI *char 10 Path di input &PATO *char 100 &SYST *char 15 &USER *char 10 &PWD *char 10 &TIPO *char 1 Path di output Nome AS400 per &TIPO =P O BLANK Server PC per &TIPO =Q Utente autorizzato all'ftp in &SYST Password utente =P Sistema di partenza PC -(l'ftp esegue GET) =Q come Opz. P ma con FTP ASCII =BLANK partenza da AS400 (l'ftp esegue GET) ICARO Guida Programmatore 11-9 Estrazione Dati

132 Convertire un documento ICARO, nel formato di visualizzazione, in un membro di file source. E' possibile trasferire un documento ICARO, nel formato di visualizzazione, in un membro di file source di nome dxxxxxxx (con x numero del riferimento Ced del documento) nel file source ICASRCF nella libreria Qtemp. Ottenuto il file source, richiamando la routine TXTTOPC1 il documento ICARO lo si può trasferire in formato doc,html o ascii in un pc. Comando: CALL DOCTOMBR (&BD &RIFCED &ARAB &LINGUA &FIELD &RETURN) Parametri: &BD *dec 3 Codice della banca dati ICARO &RIFCED *dec 7 Numero riferimento del documento Icaro &ARAB *char 1 codice tipo banca dati 1 = LTR 2= Araba &LINGUA *char 1 codice lingua (1=Italiano 2=Inglese ecc..) &FIELD *char codici di 3 caratteri numerici: questa schiera di 512 campi rappresenta la sequenza di output dei campi/paragrafi da emettere. I codici dei campi formattati vanno incrementati del valore 256. (così se si desidera emettere prima i campi formattati 2 e 4 e poi i paragrafi di codice 3 e 5 la serie sarà: &RETURN *char 1 return code. Viene restituito : B se banca dati errata T se documento inesisitente o bloccato in aggiornamento X documento annullato - riferimento disponibile per nuovo docum U documento usato in modifica K documento in attesa di aggiornamento. Dopo la creazione del documento Icaro in un membro di file source l'utente richiamando la routine TXTTOPC1 potrà trasferire questo membro in un Pc in formao HTML DOC o ASCII. Lettura di una DIR da file system o da un server (RTVDIR). CRTVDIR è CLP di esempio di source di utilizzo della routine (file example in ICA$BAS). Il risultato della dir sarà posto in un file QTEMP\DIROUT Comando: CALL ICA$BAS/RTVDIR (&SYSTEM &DIR &USER &PASSW) &SYSTEM Nome o IP del sistema server File system in rete. Es. SYSAS400 &DIR Path della dir es. /DIr1/dir2/*.pdf &USER &PASSW utente e password abilitati all'ftp sul sistema origine Estrazione Dati ICARO Guida Programmatore

133 Funzioni.exe.bat utilizzabili dall utente con STRPCCMD Nella directory del file system AS400 di nome \icaropgm sono forniti dei moduli.exe che, richiamabili dall utente in ambiente organizer (STRPCO) con il comando STRPCCMD, consentono di eseguire diverse funzioni. BROWSER.BAT (formato: path\browser.bat input.est) Eseguendo il comando o componendo in una variabile il valore di PCCMD: STRPCCMD PCCMD('\\sysas400\icaropgm\browser.bat c:\immagine.jpg') PAUSE(*NO) STRPCCMD PCCMD('\\sysas400\icaropgm\browser.bat \\sysas400\icaropgm\manuali\m_user.doc') PAUSE(*NO) In cui sysas400 è il nome in rete tcp dell AS400, viene lanciato il browser explorer e viene elaborato l oggetto indicato come parametro. In questo modo si visualizza un immagine (JPEG TIFF..) o un documento (file pdf o word) o l ascolto o la visualizzazione di un file multimediale (MPG ecc..) Questi comandi possono essere testati da una riga comando dopo aver lanciato STRPCO. COPIA.exe (formato: path\copia.exe input.exe) Consente di copiare un oggetto di cui si conosce la path\nome ed estensione in un disco di rete differente: STRPCCMD PCCMD('\\sysas400\icaropgm\copia.exe e:\immagine.jpg' ) PAUSE(*NO) Appare una finestra windows che consente di selezionare la path di arrivo e di immettere il nuovo nome dell oggetto copiato. EXEWORD.BAT (formato: path\exeword.bat docum.doc) Consente di lanciare con un cl l elaborazione di un documento con il word STRPCCMD PCCMD('\\sysas400\icaropgm\exeword.bat e:\docum.doc' ) PAUSE(*NO) ICARO Guida Programmatore Estrazione Dati

134 TXTCONV code_convers. (formato: path\txtconv.exe file_input.est,file_output, Esegue la conversione di un documento office (.doc, html, rft, txt) in un nuovo documento (file_output) nel formato specificato (code_convers). I formati sono specificati in coda. Prima di eseguire questa funzione è necessario che nella stazione di lavoro sia stato eseguito il setup contenuto nella path \\sysas400\icaropgm\txtconv97 o txtconv2000 a secondo che l utente abbia installato l office Microsoft 97 o 2000 (vedi Guida utente cap. 2 pag.4) Si presuppone che tutte le stazioni siano omogenee e che ogni stazione utilizzi l office97 o Eseguendo il setup non dimenticare di copiare dalla path locale di installazione c:\programmi\conversione nella path \\sysas400\icaropgm (solo una volta) il programma TXTCONV.exe, COPIA.exe e LISTConv.exe con quello dell office appropriato. TXTCONV può essere elaborato in tre modi Caso A TXTCONV richiamato senza parametri: STRPCCMD PCCMD('\\sysas400\icaropgm\txtconv') PAUSE(*NO) In questo caso appare la finestra Che consente con i tasti trova di selezionare i file origine, destinazione della conversione ed il formato in output. Così ad esempio un documento word può essere convertito in rft. Caso B TXTCONV richiamato con il solo nome del file output e codice di conversione. STRPCCMD PCCMD('\\sysas400\icaropgm\txtconv,c:\temp\docum, 6') pause(*no) In questo caso appare la finestra: Estrazione Dati ICARO Guida Programmatore

135 Che consente solo di selezionare la path ed il documento di input da convertire (nell esempio il documento è registrato nella path c:\temp col nome docum formato rtf.) I codici di conversione sono: WDFORMATDOCUMENT = (WORD.doc) 0 WDFORMATTEMPLATE = (Documento tipo.dot) 1 WDFORMATTEXT = (Documento solo testo.txt) 2 WDFORMATTEXTLINEBREAKS = (Testo con interruzione di linea.txt) 3 WDFORMATDOSTEXT = (Testo MSDOS) 4 WDFORMATDOSTEXTLINEBREAKS = (Testo MSDOS Interr linea) 5 WDFORMATRTF = (Testo RTF.rtf) 6 WDFORMATENCODEDTEXT = (Testo codificato) 7 WDFORMATHTML = (Testo HTML.htm) 8 Per le altre opzioni esempio Text With Layout Disponibili nel vostro office eseguire da \\sysas400\icaropgm\listaconv.exe Ove a sinistra è il nome del convertitore e, cliccandovi sopra, a destra apparirà il parametro da utilizzare Caso C TXTCONV richiamato con il nome del file di input,di output e codice di conversione. STRPCCMD PCCMD('\\sysas400\icaropgm\txtconv c:\temp\docum.rtf,c:\temp\docum,text With Layout') pause(*no) STRPCCMD PCCMD('\\sysas400\icaropgm\txtconv c:\temp\docum.rtf,\\nameas400\icarowrk\docum,0') pause(*no) In questo caso non appare alcuna finestra; il documento c:\tem\docum di tipo rtf viene convertito sempre nella temp come.doc (codice 0) o nel secondo caso nel file system AS400 directory \icarowrk n.b. un errore macro può avvenire se il documento selezionato in input contiene blank o caratteri speciali. ICARO Guida Programmatore Estrazione Dati

136 SCAN2PDF (formato: START path\scan2pdf path\nomeimmagine Costituisce un esempio per scandire (mediante una exit dalla gestione documenti EXTGES) delle immagini documento e convertirle in un documento.pdf da salvare nel file System \IcaroIMG\ICA$xxx associato ad una banca dati. Per utilizzare questa funzione eseguire prima il setup contenuto nel file zip che si trova in \\sysas400\icaropgm. e quindi eseguire l unzip del file Scan2WinNt.zip o del file ScanWin2000.zip (secondo il livello di Windows installato) nella directory c:\temp e leggere ed eseguire le istruzioni contenute nel file LEGGIMI.doc Disporre di uno scanner con interfaccia TWAIN e regolarmente installato. Questa routine richiede un nome immagine di lunghezza fissa di 15 crt. Pertanto il comado componibile, anche da un programma CL (es. EXTGES) è ad esempio: STRPCCMD PCCMD('START \sysas400\icaropgm\scan2pdf \\sysas400\icaroimg\ica$xxx\p_2003_000015_0 ) PAUSE(*NO) Verrà visualizzata una finestra windows per selezionare l interfaccia twain e per avviare la scansione di una o più immagini. Alla fine il tasto converti pdf creerà nella path di arrivo il documento.pdf Prima della scansione selezionare in "opzioni digitalizzazione" quella relativa a "ottima qualità di visualizzazione". Il programma CL nella libreria ICA$027 contiene un esempio di utilizzo di questa routine. Estrazione Dati ICARO Guida Programmatore

137 Capitolo 12. Gestione dei paragrafi con campi formattati Introduzione ICARO fornisce una funzione che permette, osservando alcune regole nella codifica delle righe di default dei paragrafi, di produrre in automatico un programma per ciascun paragrafo per la immissione dei dati in campi formattati nell ambito di uno o più righe dello stesso paragrafo. In questo modo i dati si troveranno, nell ambito del paragrafo, nelle stesse posizioni (riga colonna) e le eventuali costanti non potranno essere modificate. Fare riferimento, per gli esempi, alla banca dati di example fornita con il prodotto di codice 031 Status società. Video 1 B.D. 031 Status Società Revisione docum. N. 1 Liv. 1 Diagn. Y INIZIO DOCUM.! Ragione Sociale Rossetti e Figli SpA Identificativi temporali F.1 Data Cost. F.2 Data term. F.3 Status (?) F.4 Dal F.1 g 1 m 2 a 1980 F.2 g 0 m 0 a 0 F.3 Liquidazione F.4 g 0 m 0 a 0 Identificativi F.1 Tipo società F.2 Partita Iva F.3 N.soc /Vol /Fasc F.1 SAS F.2 _ F / 12 / a. Capitale sociale F.1 Data decorrenza F.2 N. Quote F.3 Valore unitario F.4 Totale Capitale "F.1 g 10 m 11 a 1990 F F.3 _ F.4 _ Settori operativi "F.1 EDILE Oggetto Sociale Elaborazione, Vendite apparecchiature elettroniche F3=Fine F17=Controlla/Aggiorna F24=Altri tasti Nel video 1 è visualizzato come appare lo schermo di gestione paragrafi per la banca dati 031. In questo esempio il paragrafo Ragione sociale è a testo libero nel senso che l utente puo utilizzare le funzioni di editing standard di ICARO (Inserimento righe, marginatura ecc.). Per i paragrafi che contengono campi sottolineati sono stati generati, con la funzione appreso indicata, i programmi di gestione a campi formattati. Ognuno di questi paragrafi viene automaticamente protetto per cui l utente non puo modificare i dati con l editore ICARO. Per modificare un paragrafo di questo tipo l utente puo premere il tasto F1 in corrispondenza di una qualunque riga del paragrafo da gestire. Premendo F1 con il cursore nel paragrafo Capitale sociale appare lo schermo 2 ICARO Guida Programmatore 12-1 Gestione Paragrafi

138 Video 2 Immissione Dati in Paragrafi I202 Data Base: Status Società Field : Capitale sociale Immetti i valori e premi INVIO Scelta: 4=Annulla + =Aggiungi blocco S Capitale sociale F.1 Data decorrenza F.2 N. Quote F.3 Valore unitario F.4 Totale Capitale + "F.1 g 10 m 11 a 1990 F.2 _ F.3 _ F.4 _ "F.1 g m a F.2 _ 0. F.3 _ 0. F.4 _ 0. F3=Fine F5=Aggiorna F12=Ritorno Fx= Poiché per il paragrafo, nella sua codifica, si è previsto il simbolo di frase ( ) a col. 1 della prima riga di default, il programma di gestione assume automaticamente che per il paragrafo è possibile la gestione a subfile ovvero che sarà possibile inserire più gruppi di record (immettendo il carattere+ nella colonna Sel). Il programma di gestione prevede, secondo le codifiche appresso indicate, di effettuare, per ciascun campo, il controllo data, o il richiamo e l acquisizione del codice o della descrizione di un elemento di tabella (in questo caso un carattere? immesso nel campo alfa richiamerà la lista degli elementi di tabella prevista per quel campo). Premuto ENTR i dati modificati e gli eventuali gruppi aggiunti saranno registrati nel paragrafo. Regole di codifica dei paragrafi. Fare riferimento alla banca dati di esempio 031 fornita con il prodotto. Per definire e generare un paragrafo per la gestione a campi formattati osservare le seguenti regole. Video 3 Gestione paragrafi ICA121 Codice della Banca Dati: 31 Status Società Codice paragrafo : 018 Tipo scrittura (1=LTR 2=BIDI) : 1 Descrizione del paragrafo : Soci Nro righe di immissione : 005 Paragrafo ad immissione obbligata: 0 (1=si 0=no) Paragrafo da indicizzare : 1 (1=si 0=no) Identificazione abbreviata : soci Authority List attiva : 0 (1=si 0=no) Video immissione paragrafo (da visualizzare x nuovi documenti) : "F.1 F.2 F.3 g 0 m 0 a _ 0.F.4 g 0 m 0 a _ F.5. F.6 _. F.7 _. Gestione Paragrafi 12-2 ICARO Guida Programmatore

139 3. ^Cogn.Nome o Rag.Soc.^ F.8 4. ^Comune Nasc. e Prov ^ F.9 F.A 5. ^Data Nasc. Cod. Fisc^ F.B g 0 m 0 a _ 0 F.C F3=Fine F10=Tabella caratteri F12=Ritorno F23=Annulla F6=Attributi colore F22=Importa definizione Paragrafo ICARO Guida Programmatore 12-3 Gestione Paragrafi

140 Video 4 Gestione paragrafi Righe di intestazione (max 3) per lingua: ICA121L Italiano Soci o Azionisti F.1 F/G F.2 T. Soc.(?) F.3 Dal F.4 Al F.5 N. quote F.6 Val Unitario F.7 Totale Capitale Inglese Soci o Azionisti F.1 F/G F.2 T. Soc. F.3 Dal F.4 Al F.5 N. quote F.6 Val Unitario F.7 Totale Capitale Tedesco Soci o Azionisti F.1 F/G F.2 T. Soc. F.3 Dal F.4 Al F.5 N. quote F.6 Val Unitario F.7 Totale Capitale Francese Soci o Azionisti F.1 F/G F.2 T. Soc. F.3 Dal F.4 Al F.5 N. quote F.6 Val Unitario F.7 Totale Capitale Spagnolo Soci o Azionisti F.1 F/G F.2 T. Soc. F.3 Dal F.4 Al F.5 N. quote F.6 Val Unitario F.7 Totale Capitale F3=Fine F5=Duplica prima intest. F6=Attributi colore F12=Ritorno Il Video 3 e 4 illustrano la codifica utilizzata per il paragrafo 018 SOCI; Attivare la gestione paragrafi (opz. 2 e poi 4 nel menu DEFICA); le regole per la codifica di un paragrafo da gestire in modalità protetta, sono: Indicare, nel campo NUMERO RIGHE DI IMMISSIONE, il numero esatto di righe che compongono ciascun gruppo di informazioni (da 1 a 10); nell esempio indicato è 5 (video 3) Se l utente desidera che nell ambito del paragrafo il gruppo di righe puo essere ripetuto (n records ognuno composto da n righe) immettere nel primo byte della prima riga di default il simbolo di inizio o fine FRASE (video 3); Per visualizzare il simbolo di frase corretto (nell esempio è ) premere F10. Se non dovrà essere possibile inserire più di un gruppo delle informazioni codificate lasciare blank la colonna 1 della prima riga del campo VIDEO IMMISSIONE PARAGRAFO. Immettere, nelle righe di default, le costanti che dovranno apparire nel paragrafo (eventualmente delimitate dal carattere di stop word - esempio ^ - F10 per visualizzare il carattere appropriato per la banca dati) nonché i campi formattati che dovranno apparire come campi di input/output. Per definire un campo posizionare il cursore nella posizione blank antecedente la posizione iniziale del campo e premere F6 (Attributi) selezionando il valore 2 (Sottolineato); Apparirà una linea di sottolineatura; Spostarsi di una posizione dopo l attributo di sottolineatura e premere tante volte il tasto spaziatura per quanti caratteri dovrà essere composto il campo. Spostarsi di una posizione a destra dall ultima posizione del campo e premere F6 selezionando il valore 0 (Fine attributo); Spostandosi adesso a destra dalla fine attributo sarà possibile Gestione Paragrafi 12-4 ICARO Guida Programmatore

141 definire ulteriori costanti o campi. Per definire un campo numerico con i suoi attributi immettere, allineati a destra nell ultima posizione utile del campo,:. (carattere punto) per numero >0 nessun decimale e punto per separazione delle migliaia (es );, (carattere virgola) per numero > 0 senza decimale e virgola come separazione delle migliaia (es. 1,555,999) ICARO Guida Programmatore 12-5 Gestione Paragrafi

142 0 (carattere zero) per numero >0 nessun decimale e nessuna separazione delle migliaia (es ).- (punto e trattino) per numero con segno, nessun decimale e punto per separazione delle migliaia (es );,- (virgola e trattino) per numero con segno, senza decimali e virgola come separazione delle migliaia (es. 1,555,999-) 0- (zero e trattino) per numero con segno, nessun decimale e nessuna separazione delle migliaia (es ),0 o,00 o,000 ecc.. (virgola zero o zeri) per numero positivo, con 1 o n decimali quanti sono gli zeri, virgola come separatore dei decimali, e punto come separatore delle migliaia (es ,9 ),0- o,00- o,000- ecc.. (virgola zero o zeri e trattino) per numero con segno, con 1 o n decimali quanti sono gli zeri, virgola come separatore dei decimali, e punto come separatore delle migliaia (es ,9- ).0 o.00 o.000 ecc.. (punto zero o zeri) per numero positivo, con 1 o n decimali quanti sono gli zeri, punto come separatore dei decimali, e virgola come separatore delle migliaia (es. 155,599.9 ).0- o.00- o.000- ecc.. (punto zero o zeri e trattino) per numero con segno, con 1 o n decimali quanti sono gli zeri, punto come separatore dei decimali, e virgola come separatore delle migliaia (es. 155, ) Nel definire la lunghezza di un campo numerico su tenga conto dei punti separatori e dell eventuale segno così, ad esempio, un campo numerico di 4 cifre con segno e separatore occuperà 6 posizioni: Si possono definire al massimo 40 campi per paragrafo ed un campo numerico non puo essere più ampio di 26 caratteri. Codificato il paragrafo premere Invio e definire, per ciascuna lingua, massimo tre righe di intestazioni (video 4). L utilizzo delle intestazioni evita di definire costanti nel corpo del paragrafo e quindi di occupare spazio su disco. Generazione dei programmi per la gestione protetta dei paragrafi. Dopo la codifica del paragrafo e delle intestazioni (Menu definizione b.d. opz. 4 paragrafo), premendo INVIO e se e stato definito almeno un campo formattato (Atrributo sottolineatura) verrà proposto il menu di definizione paragrafo protetto con le seguenti opzioni:. Gestione paragrafi ICA121M Righe di intestazione (max 3) per lingua: Portoghese Arabo : Definizione paragrafo protetto : : 1. Genera programma e schermo video :.... : 2. Definire controlli per campi : : 3. Definire help per schermo paragra- : : fo a campi formattati : : 4. Elimina gestione protetta del para- : : grafo. : : F3=Fine Opzione.. : :...: F3=Fine F6=Attributi colore F12=Ritorno Gestione Paragrafi 12-6 ICARO Guida Programmatore

143 L opzione 1 del menu Definizione paragrafo protetto provvede a: generare il source del display file XPARxxxF e e del programma RPG XPARxxx e compilarli nella libreria ICA$bbb con xxx =codice paragrafo e bbb=codice della banca dati. Creare la routine di exit di nome EXTAUT che protegge i paragrafi xxx se esistono i relativi PGM XPARxxx nella libreria della banca dati ICA$bbb. Il Pgm EXTAUT viene creato con duplica del pgm esistente nella libreria ICA$BAS di nome EXTAUTXXXX. Se nella libreria della banca dati l utente ha generato una propria routine EXTAUT, la procedura CRTPAR non sostituirà tale oggetto; in questo caso è cura dell utente aggiungere nella routine EXTAUT le istruzioni contenute nel source EXTAUTXXX (vedi file EXAMPLE della libreria ICA$BAS). Creare la routine di exit di nome EXTHP che provvede, alla pressione del tasto F1 in una riga di paragrafo di codice xxx, ad attivare il corrispondente pgm XPARxxx. Il Pgm EXTHP viene creato con duplica del pgm esistente nella libreria ICA$BAS di nome EXTHPXXXX. Se nella libreria della banca dati l utente ha generato una propria routine EXTHP, la procedura non sostituirà tale oggetto; in questo caso sarà cura dell utente aggiungere nella propria routine EXTHP le istruzioni contenute nel source EXTHPXXX (file EXAMPLE di ICA$BAS).Le liste di compilazione sono generate nella coda di default. 2) Assegna attributi di controllo per ciascun campo definito nel paragrafo. Dopo l esecuzione dell opzione 1 del menu Definizione paragrafo protetto l utente puo, per ciascun campo formattato definito nell ambito del paragrafo, immettere alcuni controlli di validità. Dal menu scegliere l opzione 2. Apparirà lo schermo VIDEO 5: Video 5 Tabella dei campi nel paragrafo Paragraph : 018 Data Base : 031 Header line : 03 Data Line : 05 CRTPARF Iden. Data Type Len Len Dec Start Sep Type Format Data Field Record Disp Disk Pos Field N D Control o Table A T FG A T SO N D DD N D MM N N D DD N D MM N N N F3=Fine F1=Help ICARO Guida Programmatore 12-7 Gestione Paragrafi

144 Nella prima colonna (video 5) è indicato il numero progressivo di campo a partire dalla prima riga da sinistra verso destra; la seconda colonna indica su quale riga dati si trova il campo; la terza colonna TYPE contiene il tipo campo (N numerico positivo, X numerico negativo, A Alfanumerico); lo schermo VIDEO 5 è relativo all esempio dello schermo VIDEO 3. L utente deve immettere nella colonna TYPE CONTROL il codice del tipo di controllo ed eventualmente, nella corrispondente colonna FORMAT, il parametro richiesto. I codici possibili sono: T Se il campo è di tipo A (Alfanumerico) il contenuto immesso dall utente in questo campo sarà controllato con la tabella specificata nella colonna FORMAT allineata a sinistra. L utente deve aver cura di creare la tabella per la banca dati (opz. 4 menu principale). In sede di immissione del campo la presenza di un? nel campo determina la visualizzazione della tabella e la possibilità di selezionarne un elemento. Il codice dell elemento di tabella selezionato (Max 6 crt) e trasferito nel campo allineato a sinistra; se il campo di ricezione, definito dall utente, è più corto del codice selezionato esso viene troncato. B Se il campo è di tipo A (Alfanumerico). il contenuto immesso dall utente in questo campo non sarà controllato con la tabella specificata nella colonna FORMAT allineata a sinistra. L utente deve aver cura di creare la tabella per la banca dati (opz. 4 menu principale). In sede di immissione del campo la presenza di un? nel campo determina la visualizzazione della tabella e la possibilità di selezionarne un elemento. La descrizione e non il codice dell elemento di tabella selezionato (Max 75 crt) e trasferito nel campo allineato a sinistra; se il campo di ricezione, definito dall utente, è più corto dell elemento selezio-nato esso viene troncato. D Se il campo è di tipo N (numerico positivo), senza Separatore Numerico, di lunghezza inferiore o uguale a 8 cifre, è accettato il controllo data. Nella colonna format allineato a sinistra indicare la maschera di controllo con DD per indicare la posizione delle cifre del giorno MM del mese YY o YYYY dell anno. Se il campo è di sole 2 cifre ed è presente DD il giorno è controllato nel range In un campo di 4 cifre, ad esempio, si può codificare D MMDD in questo caso l immissione è controllata tale che le prime due cifre devono essere un giorno valido e le 2 cifre seguenti un mese valido. F Se il campo è di tipo A alfanumerico con una lunghezza uguale a 16 caratteri, è accettato il controllo di validità del codice fiscale italiano (vengono controllati i 15 caratteri con il carattere di controllo della 16ma posizione). Se il campo è ampio 11 caratteri verrà controllata la validità del Codice Partita Iva italiano. La colonna Format deve essere blank. 3) Creare un testo di help per ciascun paragrafo a gestione protetta Note o consigli sulla compilazione dei campi formattati di un paragrafo possono essere memorizzati in un membro sorce col nome XPARxxxH (con xxx codice paragrafo) dl file QRPGSRC della libreria della banca dati ICA$bbb (bbb codice banca dati). Scegliere l opzione 3 del menu DEFINIZIONE paragrafo protetto: sarà richiamato il programma SEU per l immissione del testo di help. Alla pressione del tasto F1 (video 2) nella maschera di immissione campi apparirà il testo di aiuto. Gestione Paragrafi 12-8 ICARO Guida Programmatore

145 4) Casi di personalizzazione del display file e del programma di gestione di un paragrafo. Particolari esigenze del Cliente possono rendere utile intervenire nei source generati dall applicazione. (Salvare sempre i source originali e quelli modificati con altro nome poichè una eventuale ricompilazione del paragrafo -opz. 1- cancellerebbe i source modificati e quindi necessiterà riapportare le modifiche). Alcuni esempi. Quando modificare il source del display file XPARpppF con ppp codice del paragrafo nella libreria ICA$bbb con bbb codice della banca dati: Si desidera che un campo alfa ammetta solo caratteri maiuscoli: eliminare l attributo LOWER per il campo. Si desidera che un input numerico sia obbligatorio ed il valore ammesso sia compreso tra x ed y; Aggiungere dopo il campo interessato l attributo CHECK(ME) e RANGE(x y) Rendere protetto un campo dall immissione: Aggiungere dopo il campo l attributo DSPATR(PR). Quando modificare il source del programma RPG XPARppp (con ppp codice del paragrafo) nella libreria ICA$bbb (con bbb codice della banca dati). L utente desidera eseguire un operazione tra due campi ed il risultato registrarlo in un terzo campo. Esempio: il numero di quote sociali moltiplicarlo per il valore unitario immesso dall utente ed il risultato registrarlo nel campo totale capitale sociale (vedi lo schermo VIDEO 2). In questo caso occorrerà proteggere nel display file il campo V06 (sesto campo) che conterrà il risultato della moltiplicazione tra il campo V04 e V05. Nel source del pgm XPARxxx nella routine ERRCAM aggiungere l istruzione: V04 MULT V05 V06 l utente desidera trasferire il valore di un campo formattato in un campo definito nel paragrafo o viceversa. Nel programma source XPARxxx, nella routine ERRCAM l utente inserirà la specifica di file relativa al file di lavoro dei campi formattati (TEWRAAA) che contiene i campi formattati del documento. La chiave di accesso al file TEWRAAA è composta dai campi presenti nelle istruzioni di PARM presenti nel source: KRCE (riferimento del documento) e KRQS (numero di livello): C KEY KLIST C KFLD KRCE C KFLD KRQS C KEY CHAINTEWRAAA xx C*trasferisce il campo formattato 002 nel campo del paragrafo V04 C Nxx Z-ADDW002 V04 C... L utente desidera verificare (leggere o modificare) il contenuto di uno o più campi formattati di un altro paragrafo. Nell ambito di un paragrafo i campi formattati sono registrati in formato testo nel file TEWDAAA. I campi formattati possono risiedere su più record dati. Verificando la figura VIDEO 5, si vede, ad esempio, che il campo 01 (la cui label nel pgm XPARxxx sarà V01) indicato nella colonna PROGR FIELD risiede nella riga dati 01 (colonna DATA ICARO Guida Programmatore 12-9 Gestione Paragrafi

146 RECORD); sempre il campo 01, nell ambito del primo record dati, ha una lunghezza di 02 caratteri (LEN DISK) e, nel record dati, inizia da posizione 06 (START FIELD). Nell esempio citato un record logico presente in un paragrafo è composto da 5 record dati (5 record fisici); il paragrafo può contenere n record logici; in questo esempio 2 record logici richiederanno 10 record dati nel file TEWDAAA. La chiave di accesso nel file TEWDAAA è composta dal numero del documento in revisione (KRCE) dal livello (KRQS) dal codice paragrafo KPAR (3 cifre ) e da un numero riga di 9 cifre con un intervallo di 1000 numeri che bisogna calcolare. Ogni paragrafo inizia, se esistono, con n righe di intestazione (max 3). Se sono presenti tre righe di intestazioni (vedi campo Header line nella figura video 5) e i record dati sono 5 per ogni gruppo logico le chiavi presenti nel file TEWDAAA saranno, per il documento 15 di livello 2 e per il paragrafo 16: RIFCED KRQS KPAR KRIGA DATI primo record di intestazione) secondo record di intestazione) terzo record di intestazione) record dati 1 record logico record dati record dati record dati record dati record dati 2 record logico record dati record dati record dati record dati Quindi il calcolo del progressivo riga (KRIGA) per posizionarsi in un record dati (RD) di un record logico (RL) è: KRIGA = (RH + (((RL - 1) x BD) + RD)) x 1000 con RH righe header (di intestazione paragrafo) e BD numero righe che compongono un blocco dati (o record logico) A questo punto l utente, personalizzando il pgm XPARxxx, che ha già la specifica del file TEWDAAA potrà inserire delle strutture dati differenziate per ciascun paragrafo a cui vorrà accedere. Nell esempio sottoindicato la DS P006D1 potrebbe indicare l area dati che conterrà il record di dati 1 del paragrafo 6; mentre P006D2 indica la struttura dei dati sempre del paragrafo 6 per il secondo recod dati. Le posizioni dei campi per ciascun record dati sono visualizzabili nella figura VIDEO 5 (Colonna start e LEN DISK). Gestione Paragrafi ICARO Guida Programmatore

147 IP006D1 DS I xx yy Field1 I xx yy Field2 IP006D2 DS I xx yy Field3 I xx yy Field4 Per verificare fisicamente la struttura del file TEWDAAA e come i dati in esso sono memorizzati aprire una sessione di gestione interattiva documenti ed inserire un documento completando la sezione paragrafi; mentre la sessione di gestione è attiva da un altro video eseguire DSPPFM ICA$xxx/TEWDAAA con xxx codice della banca dati. Avvertenze. Dopo la creazione di una banca dati, con paragrafi gestiti in modo protetto (campi formattati) e, dopo l immissione di un certo numero di documenti, potrà risultare rischioso modificare la struttura di un paragrafo. Difatti se nella definizione di un campo formattato nell ambito di un paragrafo si sposta, dalla sua posizione originale, verso sinistra o verso destra un campo i dati dei documenti già esistenti possono venire troncati Lo stesso dicasi se si elimina una riga di dati. Per i documenti esistenti, in caso di revisione, i dati immessi potranno andar persi. Le regole da osservare, nel modificare paragrafi gestiti in modalità protetta, nel caso in cui la banca dati contiene già documenti, è di non alterare il tipo (Alfabetico numerico) dei dati e la loro posizione. Per i campi alfabetici è ammissibile ridurre o ampliare la dimensione del campo mantenendo inalterata la posizione iniziale; Per i campi numerici è ammissibile l ampliamento o la riduzione di un campo mantenendo inalterata la posizione finale del campo. Le costanti possono essere modificate in ogni caso e non alterano i dati. E possibile inserire in coda all ultima riga una nuova riga di campi formattati. Per i documenti già esistenti, in caso di revisione, i campi saranno assunti al valore 0 o blank. Effettuare sempre una copia di salvataggio della banca dati prima di effettuare una modifica nella struttura. Dopo aver eseguito la procedura (opz. 1 ) per generare la gestione protetta di un paragrafo, lo stesso paragrafo, in sede di gestione documenti, risulterà protetto da revisioni con l editore ICARO in quanto, pericolosamente, l utente potrebbe annullare righe o peggio spostare dati e/o costanti. Il programma di protezione dei paragrafi EXTAUT (per default assunto uguale allo standard EXTAUTXXX della ICA$BAS non protegge i paragrafi per l utente ICAROADM. Si consiglia quindi di non operare con il profilo ICAROADM se non strettamente necessario per effettuare dei test o delle correzioni sulle righe di paragrafi che normalmente sono protetti. ICARO Guida Programmatore Gestione Paragrafi

148 Immissione dei dati e controlli in un paragrafo a gestione protetta Definito un paragrafo a gestione protetta, un utente che richiama la gestione documenti (opz. 1 menu generale), troverà nello schermo di gestione paragrafi, che il paragrafo definito a gestione protetta sarà inibito alla immissione dati con l editore ICARO nel senso che non puo modificare inserire o eliminare righe. Per modificare i dati all interno del paragrafo dovrà, in qualunque riga del paragrafo premere il tasto F1 per abbandonare l editore ICARO e visualizzare la maschera per la gestione del paragrafo. Nei campi alfa, per i quali l utente ha definito il tipo di controllo T o B, l utente può immettere il simbolo? per ottenere la lista degli elementi di tabella relativi. La pressione del tasto INVIO, dopo aver immesso o modificato i dati procede al solo controllo degli stessi; la pressione del tasto F5, se non vi sono errori, provvede ad aggiornare i record nell ambito del paragrafo e a ritornare all editore ICARO. Quando nell editore ICARO si premerà il tasto F17 di aggiornamento documenti, verranno effettuati tutti i controlli (dizionario, autority list ecc.) previsti dall editore ICARO anche per i paragrafi gestiti in modalità protetta. Eliminare la gestione protetta di un paragrafo. Se l utente non desidera gestire in modo protetto un paragrafo utilizzare l opzione 4 del menu di Gestione paragrafo... : Definizione paragrafo protetto : : : : 1. Genera programma e schermo video : : 2. Definire controlli per campi : : 3. Definire help per schermo paragra- : : fo a campi formattati : : 4. Elimina gestione protetta del para- : : grafo. : : F3=Fine Opzione.. : :...: Gestione Paragrafi ICARO Guida Programmatore

149 Lettura o aggiornamento di un campo formattato di un paragrafo a gestione protetta. (TEWSXXX) Puo essere utile, in applicazioni utente o in personalizzazioni di programmi generati da ICARO, leggere il contenuto di un campo formattato di un paragrafo definito a gestione protetta. La routine consente anche, in funzione del parametro tipo operazione di modificare il contenuto di un campo formattato di un paragrafo quando il documento a cui si fa riferimento è contenuto nell area di lavoro. La routine TEWSXXX ha i seguenti parametri: CALL ICA$BAS/TEWSXXX (par1 par2...) Parametri: &DBNR 3 num. Campo numerico indicante il codice della banca dati. &NDOC 7 num Campo numerico indicante il numero del documento &LEVEL 3 num Immettere 0 (zero) se il contenuto del campo va letto dal file effettivo TEXDAAA (area dei documenti indicizzati) o un valore di livello qualsiasi (> 0) se bisogna leggere o aggiornare dal file contenente i documenti in sede di revisione (file TEWDAAA). La routine può eseguire la funzione di aggiornamento dati se LEVEL > 0. &PARA 3 num Immettere il codice del paragrafo dove è ubicato il campo formattato. &RECLO 5 num Indicare il record logico a cui accedere; un record logico può comprendere più righe del paragrafo ed è in genere preceduto dal simbolo di frase se è prevista la possibilità di immettere più record logici (subfile). Il &SUBF valore di questo campo può essere 1 o maggiore. 3 num Numero che identifica il campo formattato nel record logico (01-40). &TO 1 alfa Immettere R se necessita leggere il campo e restituirne il valore nei campi &VLA e/o &VLN. Immettere U se si desidera aggiornare il campo formattato specificato con i valori &VLA o &VLN. Il valore U è ammesso solo per &LEVEL > 0. Se è stato immesso il valore U con Level impostato a zero &TO è modificato in R. &VLA &VLN 80 alfa se il campo &TO contiene R i campi &VLA e &VLN 15 num conterranno il valore del campo letto; se il campo letto è numerico &VLN conterrà al massimo le 15 cifre che compongono il numero letto (con segno) e &VLA nelle posizioni 1-26 conterrà lo stesso numero secondo la maschera definita con la funzione CRTPARC (es ,50-) allineato alla 26ma posizione. Se il numero è stato definito con segno la posizione 26 di &VLA può contenere blank o - (trattino) a secondo se il numero è positivo o negativo. Se il campo letto è di tipo alfanumerico il suo valore è posizionato nel campo &VLA mentre VLN tornerà zero. ICARO Guida Programmatore Gestione Paragrafi

150 &RETUR 1 alfa Se il campo &TO ha il valore U (con &LEVEL > 0) l utente immetterà il valore del campo, che deve modificare il valore nel documento, in &VLN se il campo da aggiornare è stato definito numerico (VLN conterrà le cifre che compongono il numero - considerando le cifre decimali come interi); invece imposterà il valore in &VLA se il campo da aggiornare è alfanumerico. Return code. Il campo, dopo l esecuzione della routine potrà contenere un valore di errore: A Codice di campo errato (&SUBF) o paragrafo errato o non gestito con campi formattati (&PARA) B Codice banca dati non valido o non disponibile. C Record logico (&RECLO) non trovato Il primo richiamo della routine lascia attiva la routine ed i file aperti; per chiudere la sessione e chiudere i files aperti dalla routine, ripetere il richiamo della stessa impostando il valore del campo &PARA a 999 o 000. Gestione Paragrafi ICARO Guida Programmatore

151 Capitolo 13. Immagini / Telex / Fax... Introduzione ICARO fornisce un potente strumento di indicizzazione e di ricerca documenti e per l'archiviazione di oggetti correlati: tali oggetti possono essere immagini JPEG TIFF o fax, documenti RFT DOC PDF, dati esterni codificati o composti, ecc.. Gli 'oggetti esterni' non sono memorizzati da ICARO nei propri file delle banche dati, ma vengono memorizzati esternamente in folder, file system dell AS/400 o server di rete, DASD, librerie ottiche o altri apparati. ICARO non sostituisce le applicazioni esistenti (per es. WAF-Image Plus), ma integra ed indicizza le informazioni testuali relative agli oggetti di queste applicazioni. Si possono utilizzare diversi metodi per collegare 'documenti' di ICARO con oggetti esterni: 1 Il nome dell'oggetto, ed il programma da attivare, possono essere memorizzati direttamente dentro uno o più campi del documento ICARO; 2 Si può definire un archivio o file fisico contenente il legame tra il numero di documento ICARO e le informazioni specifiche dell'oggetto; 3 Il numero del documento di ICARO può essere memorizzato direttamente nell'ambiente dell'oggetto (per es. dentro la banca dati dell'applicazione WAF). Si possono utilizzare diversi metodi per attivare funzioni da un'applicazione all'altra: 1 ICARO può controllare un'altra applicazione (per es. attivare lo scanner, stampare, trasferire o mostrare oggetti) mediante i programmi di EXIT di ICARO (durante la gestione o la visualizzazione di documenti vedi EXTGES EXTINQ); 2 Altre applicazioni possono controllare ICARO (per es. caricare in ICARO ed indicizzare dati, recuperare, classificare, mostrare, estrarre, listare) mediante i programmi API ICARO (TEXBAT ADDDOC ecc..); 3 Entrambe le applicazioni possono essere controllate con un terzo programma o da un'applicazione cliente (concetto di cliente-servizio). ICARO Guida Programmatore 13-1 Immagini/telex/fax

152 Esempi forniti con ICARO Esempi di visualizzazione di immagini, così come descritto prima nel metodo 1, sono inclusi nei supporti del software ICARO. Questi esempi non forniscono un'intera applicazione di archiviazione di immagini, ma possono essere usati ai fini dimostrativi. Questi esempi sono contenuti nelle librerie delle banche dati ICA$021 ICA$025 ICA$027 ICA$033 (queste librerie sono disponibili presso il centro di distribuzione ICARO o contenute nel nastro di installazione versione 4.0). Nella banca dati ICARO sono stati definiti dei campi (formattati o paragrafi) per memorizzare : - Il nome dell'immagine associata al documento ICARO - o piu campi che composti insieme costituiscono il link dell immagine (esempio: anno_nro protocollo). Gli esempi fannno uso delle exit EXTGES ed EXTINQ Metodo generale per lo scanner Le immagini possono essere previamente digitalizzate (usando un qualsiasi PC e scanner o videocamera) e memorizzate in un comune file system AS/400 condivisibile in rete TCP o su un server NT. Se necessario, la procedura di digitalizzazione può essere attivata dalle funzioni 'Gestione documenti' : vedi la routine di EXIT EXTGES della banca dati 021, 027 (sorgente EXTGES del file QCLSRC nella libreria ICA$xxx). La routine deve contenere il comando STRPCCMD per avviare lo scanner e memorizzare l'immagine in una specifica path di un disco di rete associato alla banca dati. (vedi uso della routine SCAN2PDF.exe). Un esempio di installazione di una routine di scansione e salvataggio documenti in PDF è contenuto nella Guida utente cap.2-4 ed utilizzata nelle banche dati di esempio ICA$021 e ICA$027. Metodo generale per la visualizzazione Per visualizzare un qualunque tipo di immagine od oggetto multimediale si utilizza l explorer (vedi routine Browser.bat). Ma per specifiche esigenze (immagini di radiografie) di immagini elaborabili con specifici programmi si possono registrare questi programmi, forniti dal produttore, in un disco di rete e possono essere richiamati, sia per l acquisizione che visualizzazione dalle exit routine EXTGES o EXTINQ. Durante la visualizzazione dei documenti, dopo la ricerca, il tasto funzione di EXIT F20 attiva la routine EXTINQ di uscita dalla banca dati (si veda il membro sorgente EXTINQ nel file QCLSRC nella libreria ICA$021). Immagini/telex/fax 13-2 ICARO Guida Programmatore

153 Prove di TEST con le banche dati 025 e 027 a) Visualizzazione immagini (PDF) e file audio La postazione di lavoro deve essere un Personal in ambiente WINDOWS NT o 2000 con explorer installato insieme a plugin di adobe acrobat reader. la libreria originale ICA$025 di test deve essere ripristinata nel sistema (richiederla al centro di supporto). Dopo il ripristino della libreria occorrerà eseguire il comando call ICA$025/RSTDBIFS per trasferire nel file system AS/400 sotto la path \icaroimg la cartella \ica$025 contenente le immagini ed oggetti multimediali associati alla banca dati. - Richiamare ICARO dalla sessione 1 dell'emulazione 5250 mediante il comando: CALL ICA$BAS/TEXMAN - Scegliere l'opzione 'interrogazione e stampa documenti' e selezionare la banca dati Formulare la domanda: ALLDOC - Visualizzare il documento e premere il tasto funzione F20. - Selezionare il file pdf e successivamente il file audio. Sarà lanciato l explorer e la visualizzazione del file pdf e successivamente, scegliendo il file.asf il media player farà ascoltare l audio di una seduta. b) Acquisizione immagini La libreria originale ICA$027 (esempio protocollo) deve essere ripristinata nel sistema (vedi Guida utente ripristino librerie) (richiederla al centro di supporto). Dopo il ripristino della libreria occorrerà eseguire il comando call ICA$025/RSTDBIFS per trasferire nel file system AS/400 sotto la path \icaroimg la cartella \ica$027 contenente le immagini associate alla banca dati. - Verificare di avere effettuato il setup dall oggetto scanwinxx.zip secondo le istruzioni del file leggimi.doc che trovasi in \\sysas400\icaropgm (guida utente cap.2-4) - Verificare che il profilo ICAUSR abbia l autorizzazione alla banca dati e che abbia come programma personalizzato di gestione DOCGES e che abbia tutti i diritti per la gestione del documento. - Collegarsi all as con il profilo ICAUSER ed eseguire CALL ICA$BAS/TEXMAN - Sceglere l opzione gestione documenti e dalla maschera personalizzata immettere anno e numero protocollo (CL DOCGES) - Completare i dati dei campi formattati e paragrafi (premendo F1 sulle righe destinatari, mittente) - Premere F20 dopo la compilazione dei paragrafi. Partirà lo scanner dove l utente alimenterà una o più fogli. (esecuzione di EXTGES) - Effettuata la scansione e tornato al documento, aggiornare con F17, (L immagine è registrata nel disco \\sysas400\icaroimg\ica$027 in formato.pdf ICARO Guida Programmatore 13-3 Immagini/telex/fax

154 L'integrazione con ImagePlus La soluzione IBM SAA ImagePlus è stata associata ad ICARO in diverse occasioni. Possono essere utilizzati diversi metodi: 1 Le routine di EXIT dell'applicazione ICARO (EXTGES/EXTINQ) controllano l'applicazione ImagePlus utilizzando le API WAF: SCAN, STOROBJ, SENDOBJ, PRINTOBJ, ecc.. 2 L'applicazione ImagePlus del programma di Exit utente, controlla ICARO (caricare e indicizzare dati, salvare, ordinare, mostrare, estrarre, listare). Un'interfaccia standard ICARO-ImagePlus è stata sviluppata da T.I.S. utilizzando il metodo 1. Quest'interfaccia è un'opzione della licenza ICARO (che è possibile avere con una richiesta di ordine specifica ed un costo di licenza). L'interfaccia fornisce le seguenti funzioni: - Definizione dell'ambiente di WAF-ICARO (i nomi della libreria WAF possono essere assegnati secondo le richieste dell'utente, come l'immagine del LOGON) - Identificazione automatica del tipo di postazione di lavoro, dipendendo dalla tabella interna (EKDLIBFIL/WCT) - Generazione automatica di file fisici e logici necessari a collegare ImagePlus alla banca dati di ICARO - Gestione di un profilo specifico per autorizzare ciascun utente a: visualizzare stampare scannerizzare collegare immagini esistenti a un documento di ICARO eliminare collegamenti tra immagini e documenti di ICARO cancellare immagini di "proprietà dell'utente" durante 'nn' giorni cancellare tutte le immagini senza limiti di tempo usare una postazione di lavoro specifica per attività di immagine - Una specifica interfaccia, guidata da menu, permette di scannerizzare, memorizzare, visualizzare, stampare e collegare ad ogni documento ICARO da '1 a nnn' documenti-immagini con '1 a nnn' pagine ciascuno - Un'interfaccia di gestione per ordinare le immagini processate e per trasferire da DASD ad ottico (libreria ottica API). L'interfacci ICARO-ImagePlus è descritta nel manuale dell'utente Interfaccia TIS ICARO ImagePlus, referenza: TISDOCi04. Per altre applicazioni, che usano workflow o che interagiscono con ICARO dall'applicazione WAF o dalla postazione di lavoro di un cliente, è possibile richiedere al team di consulenza TIS (che da ottobre 1989 lavora con WAF- ImagePlus) una analisi/studio, progettazione, applicazioni o esempi di programmi. Immagini/telex/fax 13-4 ICARO Guida Programmatore

155 Visualizzazione di immagini di documenti ICARO in pagine Html Per consentire la visualizzazione di una immagine all'interno di un documento ICARO durante la visualizzazione via INTERNET (ICANET) inserire il seguente comando html in una riga di un paragrafo ICARO del documento interessato. Questo paragrafo, in sede di gestione, dovrà essere protetto dalla routine EXTAUT e registarto dalla routine EXTCOF (vedi esempi nei source cl e rpg nella banca dati di esempio ICA$027): <CENTER><IMG SRC= ></CENTER> dove: <CENTER> e </CENTER> indica al browser di centrare nella pagina l'immagine; xxx.xxx.xxx.xxx è l'indirizzo IP del web server. Può essere sostituito da un nome se il web server è asservito ad un DNS; IcaImage è la directory che contiene le immagini in formato JPG; Pippo.jpg è il nome dell'immagine da visualizzare. Nota: Il comando sopra indicato su un terminale alfanumerico 5250 non verrà interpretato e verrà visualizzato come testo. Integrazione Telex La banca dati di prova 032 è un esempio (basato sul telex dell'agenzia di stampa ANSA) di creazione automatica di banca dati usando linee telex come fonte di input. L'indicizzazione integrale del testo di un telex consente all'utente di estrarre informazioni aggiornate usando qualsiasi termine del testo del telex (ad eccezione dei termini definiti stopword). Altri campi formattati e paragrafi possono contenere la data, l'agenzia di stampa, i titoli ecc.. Gli elementi richiesti per sviluppare un'integrazione di telex sono i seguenti: - Disporre di un hardware collegato alla linea modem del telex, abilitato a ricevere e memorizzare telex (sono consigliabili una memoria buffer di 256 K o più, una fornitura di potenza con batteria di sicurezza ed una stampante di salvataggio). Questa configurazione hardware dovrebbe essere collegata (twinax o network) al server AS/400 (esempi di tale hardware sono forniti da PRB - Milano; Bytech - Svizzera ecc.). - Disporre di un software per leggere periodicamente (per es. ogni 5 minuti) se sono disponibili nuovi telex e per trasferirli in un TEWLOG e avviare la procedura ADDDOCB di ICARO. Esempi di tali applicazioni sono stati sviluppati dai centri di supporto ICARO (TIS o SAP). ICARO Guida Programmatore 13-5 Immagini/telex/fax

156 Pagina vuota Immagini/telex/fax 13-6 ICARO Guida Programmatore

157 Capitolo 14. Ottimizzazioni: indicizzazione/spazio disco In generale i tempi di aggiornamento documenti o di ricostruzione degli indici (opzione 1 menu RGZICA) dipendono essenzialmente dal numero di documenti e dalla quantità di termini (parole, numeri) da indicizzare. Esempio di lavoro di indicizzazione di banca dati con: documenti per complessive righe di testo distribuite in - 9 paragrafi e - 4 campi formattati con termini nel dizionario (reali e normlizzati) e ricorrenze di termini nei documenti In questo esempio di lavoro, il tempo di indicizzazione in un sistema AS/400 E80 non dedicato è stato di 30 minuti (senza richiesta di ottimizzazione). Il tempo di indicizzazione dipende inoltre dal numero di termini che esistono già nel dizionario: per aggiungere un altro gruppo di documenti nella stessa banca dati (quindi un totale di documenti) si impiegherebbe il 60-70% del tempo della prima indicizzazione. Per ottimizzare l'attività di indicizzazione Si raccomanda di eseguire le seguenti operazioni: - Definire una stop list Ogni ricorrenza di termine deve essere indicizzata (indirizzata) su uno spazio che occupa 12 byte. Tutti i termini privi di significato (lettere, avverbi, pronomi ecc.) vanno inseriti nella lista di stopword. Anche parole significative possono essere inserite nella lista di stopword se queste ricorrono in un campo specifico: per es. il termine 'Titolo' può assumere significato in tutto il documento tranne che per il paragrafo titolo 'TI' dove è presente in tutti i documenti ma non sarà mai cercato in quel paragrafo specifico. - Definire campi 'non indicizzati' Se un campo contiene informazioni che non saranno utilizzate ai fini della ricerca, definire il campo come 'non indicizzato' (vedi la definizione di campo nell'opzione 'Definire una banca dati'). ICARO Guida Programmatore 14-1 Immagini/telex/fax

158 Per ottimizzare lo spazio su disco - Se dei documenti vengono annullati frequentemente, l'opzione 3 'cancellazione documenti annullati' del menu RGZICA dovrebbe essere eseguita periodicamente. I documenti annullati, logicamente, verranno eliminati fisicamente dalla banca dati. - Salvare e svuotare periodicamente i file di giornale. Immagini/telex/fax 14-2 ICARO Guida Programmatore

159 Capitolo 15. ICAROPc/ICANET le API AS400 per personalizzare l interfaccia grafica in ambiente Windows o l accesso Via WEB Internet Questo capitolo fornisce le note tecniche per la realizzazione di personalizzazioni applicative al prodotto client ICAROPc o ICANET. La personalizzazione, oltre a riguardare la funzione di navigazione, consente la definizione di menu e di maschere, in box windows opagine HTML, con eventuali campi di input per realizzare funzioni di query personalizzate dall utente; è inoltre possibile controllare il LOGON ed il LOGOFF di una sessione ICAROPc. Il prodotto ICAROPc, composto da un applicativo sul server AS/400 e da un applicativo sul personal computer, assolve a tutte le funzioni di interrogazione a data bases ICARO in modalità grafica e in ambiente Windows; per le note di installazione e per una descrizione dettagliata del prodotto si può far riferimento al manuale ICAROPc Guida Utente. Nella pagina seguente è illustrato lo schema di flusso procedurale del prodotto. Nello schema di flusso sono illustrati i passi standard del prodotto ed i passi definibili dall utente mediante delle EXIT-CALL. Descrizione del flusso applicativo di ICAROPc/ICANET Passo 1 - Operazione di LOGON Questa fase, standard, è eseguita da ICAROPc per attivare una connessione verso l AS/400 secondo le modalità definite durante il SETUP di ICAROPc (connessione via TCP/IP, via router CA/400 ecc.). L operazione di LOGON, inoltre, provvede ad acquisire e verificare il nome utente e la password assegnata allo stesso utente; Prima di attivare la connessione, ICAROPc provvede a verificare se esiste nella libreria ICA$API il programma di nome ICALOGON, scritto dall utente, per effettuare ulteriori controlli alla connessione e per informare ICAROPc su quali moduli utilizzare nei passi successivi. (Vedi più avanti la descrizione della EXIT utente ICALOGON). Passo 2 - EXIT CALL ICALOGON. Se esiste (e scritto a cura dell utente) nella libreria ICA$API, viene eseguito il programma ICALOGON; Questo programma può comandare alla funzione ICAROPc del passo 1, dopo eventuali controlli sul profilo utente, di respingere la connessione. Così, ad esempio, è possibile respingere tutte le connessioni aperte con il profilo QSECOFR o ICAROADM. ICALOGON può essere utilizzato dall utente per realizzare dei log personalizzati di utilizzo del sistema (memorizzazione del nome utente, della data e orario di collegamento, ecc..). ICALOGON, può indirizzare l applicativo ICAROPc ad utilizzare un menu box iniziale di collegamento controllato dall AS/400 o scritto su Personal (Passo 3 o passo 4) o, può informare ICAROPc dell esistenza di un applicativo scritto su Personal che sostituisce la Lista banche dati (LEXTINQ) standard o la composizione standard della query (QEXTINQ) ICARO Guida Programmatore 15-1 ICAROPc

160 Schema di flusso dell applicazione ICAROPc 1) Operazione Lista di LOGON funzioni personalizzate funzioni standard 2) EXIT ICALOGON 3) EXIT - Menu Box da Applicativo utente PC (MEXTINQ.EXE) 5) Applicativo utente su PC (LEXTINQ.EXE) LISTA BANCHE 6) Lista banche Dati autorizzate 4) EXIT - Menu Box da Applicativo AS/400 (pgm MEXTINQ) 7) Applicativo utente su PC (QEXTINQ) per l EDIT della Query 8) EDIT QUERY 9) Elabora la QUERY ICARO 10) LISTA ABBREVIATA 11) VISUALIZZA DOCUMENTI 12) EXIT - NAVIGAZIONE (PGM AS/ PEXTINQ) per INVIO BOX MENU o 13) EXIT LOGOFF (Pgm AS/400 ICALOGOF) ICAROPc 15-2 ICARO Guida Programmatore

161 Passo 3 o 4 - EXIT CALL MEXTINQ. Se ICALOGON, scritto dall utente, avrà informato l applicazione ICAROPc dell esistenza di un menù iniziale, verrà ricercato ed eseguito il programma utente MEXTINQ. Secondo l opzione impostata in ICALOGON, il programma utente MEXTINQ sarà cercato nel personal (MEXTINQ.EXE) o nell AS/400 nella libreria ICA$API (Pgm ICA$API/MEXTINQ). Per le regole nella compilazione di un programma PC MEXTINQ.EXE si veda il manuale ICAWIN - Guida per il Programmatore. Per le regole di compilazione di un programma CL, RPG, o altro, su AS/400 si vedano più avanti i parametri necessari per la chiamata CALL MEXTINQ in AS/400. Nel caso di invio di un menù iniziale per il tramite di una chiamata su AS/400, il programma MEXTINQ invierà all applicazione client ICAROPc le righe, con i relativi attributi (colore, campi di input ecc.) che dovranno apparire in una box windows; per ciascuna riga che apparirà nel menù, se definita selezionabile, l utente deciderà, se la riga sarà selezionata, quale programma applicativo dovrà essere eseguito sull AS/400 (LIB/PGM) e quali parametri passare all applicativo (max 220 caratteri o quale comando o programma su PC eseguire; a sua volta, un applicativo utente, richiamato dopo la selezione di una riga del precedente menu, potrà inviare una nuova box di menu o di opzioni con campi di inpu/output. Per alcune righe di menù impostate dall utente, se selezionate, potrà essere richiesto l invio della finestra standard o personalizzata di lista banche dati o la finestra standard o personalizzata di query per una o più banche dati. Un esempio di box menu MEXTINQ l utente potrà trovarlo nel file QCLSRC nella libreria ICA$API. Passo 5 o 6 - Lista standard banche dati selezionabili (6) o programma utente sostitutivo su PC (LEXTINQ.exe) In questo passo, secondo l opzione impostata nel programma EXIT ICALOGON, verrà visualizzata la lista standard delle banche dati autorizzate (passo 6) o, in alternativa, verrà richiamato un programma PC scritto dall utente che avrà il compito di determinare su quali banche dati effettuare la ricerca. Questo programma, residente su PC, dovrà avere il nome LEXTINQ.EXE. Passo 7 o 8 - Video di input standard per la formulazione della Query (8) o programma utente sostitutivo (QEXTINQ.exe) In questo passo, secondo l opzione impostata nel programma EXIT ICALOGON, verrà visualizzata la box standard per l immissione della query sulle banche dati selezionate (passo 8) o, in alternativa, verrà richiamato un programma PC scritto dall utente che avrà il compito di determinare, con appositi campi di input, la query da effettuare, secondo la sintassi ICARO, sulle banche dati desiderate. Questo programma, residente su PC, dovrà avere il nome QEXTINQ.EXE. ICARO Guida Programmatore 15-3 ICAROPc

162 Passo 9 - Elaborazione della Query ICARO Questa funzione di ICAROPc provvede ad inviare all AS/400 la query da elaborare e riceverà il risultato della ricerca. Questa funzione consente all utente di selezionare il tipo di output desiderato (Lista abbreviata, Visualizzazione documento, download, ecc..) Passo 10 - Lista Abbreviata - stampa Se nel passo 9 è stata scelta l opzione di lista abbreviata o se nella personalizzazione dei menu è stato utilizzata la funzione STRQRY con l opzione Lista abbreviata, verrà visualizzata una lista abbreviata di tutti i documenti del risultato di ricerca con un massimo di 5 campi per ciascun documento. Passo 11 - Visualizzazione dei documenti - stampa - download Se nel passo 9 è stata scelta l opzione di Visualizzazione documento o se nella personalizzazione dei menu è stato utilizzata la funzione STRQRY con l opzione Visualizza documento, verrà visualizzato documento per documento il risultato di ricerca. Passo 12 - Navigazione. Se per la banca dati di cui è visualizzata la lista della banca dati (passo 10) o la visualizzazione del documento (passo 11) è stata definita la funzione di EXIT sarà attivato il bottone di scelta della Navigazione ipertestuale. La funzione di Navigazione è quella che permette, da un documento visualizzato, di utilizzare dei campi in esso contenuti per comporre una query da effettuare automaticamente sulla stessa o su altre banche dati. Selezionando il bottone di Navigazione sarà richiamato, se esiste nella libreria ICA$xxx (con xxx codice della banca dati) il programma di EXIT PEXTINQ. Questo programma, scritto dall utente, potrà inviare, analogamente al passo 4, un menu di opzioni (con utilizzo nel programma PEXTINQ della funzione STRBOX) o direttamente il testo di una query da elaborare su una o più banche dati (con utilizzo nel programma PEXTINQ della funzione STRQRY). Passo 13 - Exit CALL ICALOGOF Se l utente desidera controllare la chiusura di una sessione ICAROPc è possibile realizzare nell AS/400 nella libreria ICA$API un programma utente di nome ICALOGOF che ICAROPc richiamerà prima della chiusura della sessione. Un tale programma potrebbe essere utilizzato dall utente per memorizzare in un file di log i parametri di fine lavoro (nome utente, data e orario di chiusura ecc...) ICAROPc 15-4 ICARO Guida Programmatore

163 Descrizione delle procedure di exit CALL realizzabili dall utente. Qui appresso sono descritte le routines richiamabili dall utente per realizzare le funzioni di navigazione tra banche dati e per l invio di menu e box windows per personalizzare la sequenza operativa di una ricerca in banche dati ICARO mediante l interfaccia grafica. Il Programma utente ICALOGON Questo programma, se scritto dall utente e compilato nella libreria ICA$API, verrà richiamato ad ogni logon di ICAROPc e consentirà di: filtrare le connessioni di determinati profili utente respingendo ad esempio le chiamate effettuate con il profilo QSECOFR; Poichè questo programma, se esiste, viene eseguito all avvio della connessione, il programmatore può inserire in questo programma le istruzioni necessarie ad effettuare un LOG personalizzato delle connessioni avvenute (Nome utente data e orario di collegamento ecc..); Indirizzare il programma ICAROPc ad eseguire, dopo la connessione, un programma per l invio di un menù personalizzato residente sull HOST o sul Personal. L eventuale programma, che dovrà gestire l invio di un menu o più menu successivi o maschere di input, dovrà trovarsi o nell AS/400 nella libreria ICA$API con il nome MEXTINQ o nel personal con il nome MEXTINQ.EXE. Indirizzare il programma ICAROPc a utilizzare un programma personalizzato di lista banche dati, che sostituirà la lista standard, residente su Pc, con il nome LEXTINQ.EXE Indirizzare il programma ICAROPc a utilizzare un programma personalizzato, scritto dall utente, per la editazione della query che sostituirà la funzione standard di ICAROPc; Questo programma, realizzato dall utente risiederà nel Personal con il nome QEXTINQ.EXE. Il programmatore può consultare un esempio di programma ICALOGON il cui sorgente è nel file QCLSRC della libreria ICA$API. L Applicativo ICALOGON scritto dall utente dovrà ricevere come parametri di input/output i seguenti sette campi: Campo tipo len JOBUSER *CHAR 10 campo di input; in questo campo si riceverà il nome del profilo utente che ha aperto la sessione PC (nel caso di utilizzo del CA/400) o il nome del profilo utente che ha avviato l applicativo server AS/400 per il TCP/IP (STRICATCP). ICARO Guida Programmatore 15-5 ICAROPc

164 JOBNAME *CHAR 10 campo di input; in questo campo si riceverà il nome del job relativo al JOBUSER precedentemente descritto. JOBNUM *CHAR 6 campo di input; in questo campo si riceverà il numero del job relativo al JOBUSER precedentemente descritto. USERSIG *CHAR 10 campo di input; in questo campo si riceverà il nome utente utilizzato nella maschera del Signon di ICAROPc. INITPROC *CHAR 1 campo di output impostato dal programma ICALOGON. In questo campo il programmatore imposterà uno di questi valori: E se la connessione deve essere respinta. Questo è il valore da impostare se ad esempio, dopo un confronto del campo USERSIG con QSECOFR, non si desidera che venga proseguita l elaborazione. S se il menu di connessione deve essere quello standard. H se il menu di connessione è fornito da un programma su host AS/400 di nome MEXTINQ della libreria ICA$API. C se il menù di connessione è fornito da un programma sul client personal computer di nome MEXTINQ.EXE nella directory ICAROPC e sottodirectory del nome di sistema AS/400 di connessione (C:\ICAROPC\S44...\) SELDB *CHAR 1 campo di output impostato dal programma ICALOGON per informare l applicativo ICAROPc se la visualizzazione della lista delle banche dati deve essere quella standard del prodotto o una applicazione sul personal (nella directory C:\ICAROPC\S44...) di nome LEXTINQ. I valori possibili sono: S se la lista delle banche dati è quella standard del prodotto ICAROPc C se la lista delle banche dati ovvero la scelta delle banche dati da selezionare è determinata da un applicazione utente su PC di nome LEXTINQ.EXE (vedi manuale del programmatore su ICAROPC. ENTQRY *CHAR 1 campo di output impostato dal programma ICALOGON per informare l applicativo ICAROPc se la box di editazione della query deve essere quella standard del prodotto o una applicazione sul personal (nella directory C:\ICAROPC\S44...) di nome QEXTINQ. I valori possibili sono: S la box di editazione della query è quella standard del prodotto ICAROPc C la box per editare la query è determinata da un applicazione utente su PC di nome QEXTINQ.EXE (vedi manuale del programmatore su ICAROPC. ICAROPc 15-6 ICARO Guida Programmatore

165 Se il programma ICALOGON non esiste in ICA$API l applicativo ICAROPc utilizzerà i valori standard ovvero le schermate grafiche standard per la connessione, per la lista delle banche dati e per la editazione della query. Necessita osservare che se l utente, nel programma ICALOGON, esclude il profilo utente QSECOFR (impostando ad E il campo INITPROC se il campo JOBUSER è uguale a QSECOFR) nessun utente si potrà collegare nel caso in cui l avvio del server TCP/IP (STRICATCP) è stato fatto dal QSECOFR; difatti il campo JOBUSER, come detto, contiene il nome del profilo utente che ha avviato il server TCP/IP e non già il nome dell utente che ha fatto il Signon; ogni nuova sessione TCP avrà come JOBUSER quello del server che apre la nuova connessione. Pertanto il nome utente deve essere confrontato con il campo USERSIG. Comunque, inibire le connessioni JOBUSER=QSECOFR può evitare che le funzioni server del TCP/IP vengano erroneamente avviate con il profilo QSECOFR obbligando l operatore a terminare il TCP/IP (STPICATCP) e a riavviarlo con un profilo utente diverso ad esempio QPGMR (STRICATCP). INVIO DI UNA BOX O MENU INIZIALE DA HOST A ICAROPC (MEXTINQ) Se in ICALOGON il valore del campo INITPROC è stato impostato ad H l applicativo ICAROPc, dopo l avvenuta connessione, cercherà nella libreria dell AS/400, ICA$API, un programma applicativo, di nome MEXTINQ, che avrà lo scopo di inviare al programma client ICAROPc le righe necessarie per la composizione di una box di menù iniziale. Nel file source QCLSRC della libreria ICA$API è fornito un esempio di programma MEXTINQ. Il programma MEXTINQ scritto dall utente si farà cura di determinare : l intestazione da attribuire alla box e il colore di fondo della box; la descrizione di ogni riga che dovrà apparire nella box e l indicazione se la riga sarà selezionabile o meno con il mouse; la funzione o programma da eseguire (su PC o su host AS/400) se la riga del menù è selezionata con il mouse; gli attributi di colore e di sfondo di ciascuna riga ed il font ed il corpo da utilizzare; il posizionamento di eventuali campi di input la definizione di eventuali bottoni con relativa descrizione e programma da eseguire (su Pc o AS/400) se il bottone verrà selezionato con il mouse. la definizione delle caratteristiche degli eventuali singoli campi di input definiti nelle righe box (input numerico, input alfanumerico, output) ciascuna riga (di intestazione, di testo, di definizione bottoni o di definizione campi) determinata dal programmatore, utilizzando la funzione STRBOX, sarà inviata all applicazione ICAROPc. ICARO Guida Programmatore 15-7 ICAROPc

166 Il programma MEXTINQ scritto dall utente non ha parametri di input/output; se nell applicazione il programmatore desidera conoscere l utente che si è connesso ed altri parametri inerenti il JOB, può accedere alla data area WRKICA della libreria QTEMP. ICAROPc 15-8 ICARO Guida Programmatore

167 La data area WRKICA della QTEMP (accessibile con il comando RTVDTAARA), la cui ampiezza è di 1000 bytes, contiene i seguenti dati: 1-10 *CHAR NOME DELLA LIBRERIA WICAXXXXXX ASSEGNATA AL JOB *CHAR CODICE LINGUA UTENTE 1,2,3, *CHAR PROFILO UTENTE DELLA CONNESSIONE (STARTPCS, O PROFILO DEL SERVER TCP *CHAR PROFILO DI GRUPPO UTENTE ICARO *CHAR PROFILO UTENTE DEL SIGNON *CHAR NUMERO LAVORO *CHAR NOME DEL LAVORO (NOME DEL TERMINALE) *CHAR dati utente passati con INLOGON all apertura di una sessione ICARO nel campo String (Vedi ICAROPc/ICANET pagina 22). l utilizzo dei dati su descritti potrebbe essere utile al programmatore per condizionare la visualizzazione di una o più righe del menu, ad esempio, in funzione del profilo utente o di gruppo. Il programma MEXTINQ utilizzerà al suo interno la routine ICA$API/STRBOX per inviare all applicativo ICAROPc le informazioni, riga per riga, necessari alla composizione di una box di Menu o di una box di immissione dati. Qui appresso sono descritti i parametri necessari alla routine STRBOX per inviare i dati all applicativo ICAROPc. La routine STRBOX la routine STRBOX invia ad ICAROPc, record per record, ogni riga che dovrà comporre il menù o una maschera di input fino a ché l ultimo record trasmesso non riporterà l opportuno flag che comunica ad ICAROPc che trattasi dell ultima trasmissione. I record trasmessi, secondo il contenuto dei campi, possono raggrupparsi in: Record di intestazione (identificato dal numero di riga 0000) Records di riga (identificati dal range di riga ) Records di definizione dei bottoni (identificati dal range di riga ) Records di definizione degli attributi di campi di input/output (uno o più records con numero di riga 9999). Per ciascun records di riga o per ciascun bottone definito il programmatore indicherà il nome del programma (su Pc o su Host AS/400) che dovrà elaborare la richiesta (ad esempio per inviare un altro menu o elaborare una query). Il programma di esempio MEXTINQ in QCLSRC della libreria ICA$API e il programma esempio ANSA nello stesso file contengono un esempio di utilizzo della routine STRBOX. La chiamata alla routine è: CALL ICA$API/STRBOX (&TREC &NRIG &ATTRI &RIGA &SYS &CPGM &DPGM &RTN) in cui: ICARO Guida Programmatore 15-9 ICAROPc

168 &TREC *char 1 Contiene il carattere di tipo riga: S la riga è selezionabile con il mouse C la riga è una costante o contiene dei campi di input e non è selezionabile con il mouse. Per i record con il valore &TREC=S il programmatore indicherà nei successivi campi &SYS, &CPGM e &DPGM l ubicazione, il nome del programma ed i parametri necessari per elaborare la richiesta corrispondente alla selezione della riga. &NRIG *dec 4 Questo campo conterrà 4 cifre decimali il cui valore determinerà il tipo di record o la posizione della riga nell ambito della box Windows con questo valore si indica che trattasi di riga di intestazione. Il valore del campo &RIGA conterrà il testo di intestazione della box mentre il primo byte del campo &ATTRI conterrà il codice colore dello sfondo di default per le righe blank non definite nella box indica il valore posizionale del testo della riga (&RIGA) nella box; Per un record che conterrà un valore &NRIG compreso tra 0001 e 8999 il valore del campo &ATTRI specificherà gli attributi di sfondo, di colore ed il font della riga di testo contenuto nel campo &RIGA. Se alcuni valori di riga vengono omessi (in quanto si desidera lasciarli blank) le righe blank assumeranno come colore di sfondo (primo bytes del campo &ATTRIB) quello impostato nella riga di intestazione (&NRIG = 0) inviando uno o tutti i record ad ICAROPc (991, 992, 993, 9994) saranno attivati i relativi bottoni in calce alla box con un testo (esempio: ESEGUI, ELABORA, MENU A, MENU B ecc..) che sarà indicato nel campo &RIGA uno più record identificati tutti dal campo &NRIG=9999 conterranno le eventuali caratteristiche dei campi di input definiti nella box. &ATTRI *char 6 Attributo di colore. Se il campo &NRIG è 0000 gli attributi di colore non sono riferite alla riga di intestazione della box; per la riga di intestazione della box gli attributi sono quelli standard definiti da windows per il testo box; Per &NRIG 0000 viene assunto solo il primo byte come colore di sfondo per le righe blank ovvero per le righe box non definite. Se &NRIG è compreso tra gli attributi si riferiscono alla singola riga. I sei caratteri che compongono l attributo hanno la seguente composizione: 1 BYTE = COLORE SFONDO RIGA: 0 = NERO 4=VERDE 1 = BIANCO 5=BLU 2 = GRIGIO 6=VERDE SCURO 3 = ROSSO 7=VIOLETTO 8 =GIALLO 9=AZZURRO ICAROPc ICARO Guida Programmatore

169 2 BYTE = TIPO DI ICONA IN TESTA ALLA RIGA 0 = NESSUNA ICONA RIGA 1 = QUADRATINO 2 = CERCHIETTO 3 = TRIANGOLO 4 = CROCETTA 3 BYTE = COLORE CARATTERE RIGA 0 = NERO 4=VERDE 1 = BIANCO 5=BLU 2 = GRIGIO 6=VERDE SCURO 3 = ROSSO 7=VIOLETTO 8 =GIALLO 9=AZZURRO 4 BYTE = ATTRIBUTO TESTO (&RIGA) 0 = NORMALE 1 = BOLD 2 = ITALIC 3 = UNDERLINE 4 = BOLD + ITALIC 5 = BOLD + UNDERLINE 6 = ITALIC + UNDERLINE 7 = BOLD + UNDERLINE + ITALIC 8 = CENTRATO 9 = CENTRATO + BOLD 5 BYTE = TIPO CARATTERE 0 = COURIER NEW 1 = ARIAL 2 = TIMES NEW ROMAN 6 BYTE = CORPO CARATTERE 0 = CORPO 14 7= corpo 30 1 = 06 8= 35 2 = 08 9= 40 3 = 10 4 = 12 5 = 16 6 = 22 &RIGA *char 79 Testo della riga di intestazione della Box (per &NRIG = 0000) o della singola riga della box (&NRIG tra 0001 e 8999) o della descrizione del bottone (&NRIG tra 9991 e 9993) di cui saranno considerati i primi 15 caratteri. Attenzione: Nel caso di righe box (&NRIG tra 0001 e 8999) è possibile inserire dei campi di input o di output (numerici, alfanumerici) semplicemente indicando tra il simbolo minore e maggiore una lettera maiuscola o minuscola. Es.: Codice: <A> data:<a> tipo: <B> Osservare che ogni lettera (Minuscola o maiuscola) identifica univocamente un campo e pertanto non deve essere duplicata (lettere minuscole o maiuscole identificano campi differenti così a è diverso dal campo A). Quando si posiziona nella riga un campo occorre lasciare sufficiente spazio a contenere la lunghezza massima del campo. Gli attributi di ogni singolo campo sono definiti, alla fine, nei record di tipo 9999 (&NRIG 9999). ICARO Guida Programmatore ICAROPc

170 &SYS *char 1 Sistema che dovrà elaborare la richiesta. Nel caso di &TREC=S ovvero di riga selezionabile o nel caso di riga di definizione bottone (&NRIG tra 9991 e 9993) bisogna indicare la ubicazione del programma, scritto dall utente, che dovrà elaborare la richiesta, nel caso in cui la riga o bottone è selezionato: C il programma risiede nel client PC. In questo caso il campo &DPGM indicherà la directory ed il comando di chiamata es.: C:\ICAROPC\PGMA.EXE; il campo &CPGM sarà blank. H il programma risiede nell AS/400. In questo caso &CPGM conterrà il nome Libreria/programma da elaborare e nel campo &DPGM saranno immessi i valori desiderati da passare al programma (&CPGM) per l elaborazione. I Come il caso H. In questo caso il programma richiamato genererà lo stesso livello di chiamata del chiamante; ciò vuol dire che se il programma chiamato genererà una box questa ultima sostituirà la box precedente alla quale non potrà essere fatto ritorno se non con una specifica chiamata. W Con questa opzione si comanda di visualizzare la pagina HTML residente nella directory voluta. Il campo &DPGM conterrà il percorso completo e l identificativo della pagina HTML. L Procedere con la visualizzazione della lista delle banche dati standard o personalizzata (LEXTINQ); in questo caso &CPGM e &DPGM saranno lasciate blank. L opzione L non è ammessa se STRBOX è richiamata dalla funzione di navigazione (vedi Exit Call PEXTINQ). E Procedere con la maschera di editazione della query (standard o personalizzata - QEXTINQ) saltando la fase di selezione delle banche dati. I codici delle banche dati su cui effettuare la query saranno posti nel campo &DPGM mediante una sequenza di 27 cifre (3 cifre per banca dati x 9 codici al massimo); Il campo &CPGM sarà lasciato blank. L opzione E non è ammessa se STRBOX è richiamata dalla funzione di navigazione (vedi Exit Call PEXTINQ). Blank = se riga non selezionabile o se trattasi di record di intestazione (&NRIG = 0000) o records di definizione campi (&NRIG= 9999) &CPGM *char 21 Nome del programma residente su host AS/400 nel formato LIB/PGM. Questo campo va compilato se &SYS=H. &DPGM *char 220 Nel caso di &SYS=C in questo campo sarà indicato, completo di directory, il comando su PC da eseguire. Ad esempio: C:\immagini\DSPFOTO.EXE C:\immag\foto.gif Nel caso di &SYS=H,I l intero campo di 220 bytes sarà passato come unico parametro al programma su host AS/400, indicato nel campo &CPGM, per la lunghezza di 220 caratteri. ICAROPc ICARO Guida Programmatore

171 Nel caso di &SYS=E occorre immettere, allineato a sinistra 27 cifre indicanti il codice o i codici delle banche dati (massimo 9 x 3 cifre) su cui effettuare la query. Se la banca dati., ad esempio da interrogare è la 001 e 021 occorrerà immettere: Nel caso di record di definizione di campi di input in questo campo andranno definite le caratteristiche dei singoli campi (vedi più avanti definizione attributi di campo). &RTN *char 1 blank seguono altri record F questo è l ultimo record. ICAROPc può elaborare la box. Attenzione: Se nell ultimo record trasmesso il programmatore non valorizza il campo &RTN a F il programma ICAROPc rimarrà in attesa senza elaborare la Box e senza accettare alcun altro input. Descritti i campi necessari alla routine STRBOX si riepilogano i campi necessari per ogni tipo di informazione di riga per la composizione di una box. Riga di intestazione di una box: Costituisce in genere la prima riga ovvero il primo record che la routine STRBOX trasmette all applicazione ICAROPc per definire l intestazione della box e gli attributi di sfondo per le righe non definite per la finestra (righe che saranno assunte a blank). I campi da compilare sono: &TREC = C per indicare che trattasi di costante; &NRIG =0000 per indicare che trattasi di riga di intestazione; &ATTRI primo bytes con l attibuto di colore di fondo di default per le righe della box che non sranno definite e che dovranno assumersi a blank; I bytes dal secondo al sesto di &ATTRI resteranno a zero. Nel campo &RIGA indicare il testo di intestazione della box. Gli attributi di colore e di font della riga di intestazione box sono quelli standard di Windows; tutti i campi successivi &SYS, &CPGM, &DPGM e &RTN saranno impostati a blanks. Riga di testo menu o riga con campi di input. Indicare nel campo &TREC il carattere C se la riga di testo è una costante non selezionabile o un carattere S se l utente potrà selezionare con il mouse la riga avviando, automaticamente, l elaborazione del programma associato alla riga (vedi campi &SYS, &CPGM e &DPGM); nel caso in cui la riga contiene dei campi di immissione &TREC dovrebbe normalmente contenere il carattere C in quanto il valore dei campi immessi saranno trasmessi, per l elaborazione, al programma associato al bottone, che sarà definito dall utente (vedi definizione bottoni e definizione campi), bottone del tipo Elabora. Il campo &NRIG dovrà avere un valore diverso da 0 per indicare la posizione relativa, dall inizio della box, in cui la stessa riga deve essere visualizzata; se il numero di riga indicato in &NRIG supera il ICARO Guida Programmatore ICAROPc

172 numero di riga della box essa sarà visualizzata utilizzando i tasti di scorrimento che appariranno a fianco della finestra windows. Le posizioni di riga non definite, saranno assunte a blank con un colore di fondo definito nel primo bytes del campo &ATTRI per record con &NRIG = 0. Il campo &ATTRI conterrà gli attributi di colore e di font desiderati per il testo contenuto nel campo &RIGA. Per ottenere uno sfondo omogeneo di colore, Il primo byte del campo &ATTRI dovrebbe normalmente essere uguale a quello definito nel record di intestazione box (&NRIG=0); il campo &RIGA conterrà il testo della riga di menu o una riga di costanti e/o campi di input identificati ciascuno da una lettera dell alfabeto: campo di input: <a> secondo campo: <b> ecc... se saranno definiti dei campi (delimitati dal simbolo minore e maggiore) occorrerà specificare, per ciascun campo, i singoli attributi (vedi record &NRIG = 9999) ed almeno un bottone per l avvio della elaborazione dei campi (vedi record &NRIG ). Lasciare, dopo la definizione di un campo (es. <a>) uno spazio sufficiente a contenere il campo nella sua lunghezza. il campo &SYS conterrà l origine da cui elaborare il programma associato alla riga definita selezionabile (H host o C per client) o la funzione di ICAROPc a cui rinviare l applicazione; così, ad esempio, se una riga della box contiene il seguente testo (in &RIGA): * Visualizza lista delle banche dati autorizzate il valore &SYS = L indirizzerà l applicazione ICAROPc a proseguire dalla lista delle banche dati autorizzate, in questo caso &CPGM e &DPGM resteranno blank; viceversa, se &SYS conterrà il carattere E e la riga di testo (&RIGA) sarà ad esempio: * formula domanda nella banca dati leggi. l applicazione ICAROPc sarà instradata, se sarà selezionata questa riga, direttamente alla formulazione della query nella b.d. leggi ; se la banca dati leggi ha il codice 022, ad esempio, il programmatore dovrà indicare tale codice nella stringa di 27 cifre poste nel campo &DPGM, allineate a sinistra, per indicare che la query andrà formulata nella banca dati 027 ( ). Se l applicazione da richiamare (quando la riga verrà selezionata) è un programma nell AS/400 (&SYS = H) necessiterà indicare il nome del programma nel campo &CPGM nel formato libreria/programma e, in questo caso, nel campo &DPGM (lungo al massimo 220 caratteri) andranno memorizzati i parametri che il programmatore desidera che siano passati al programma nelle posizioni desiderate. Si osservi che &DPGM sarà passato come unico campo di 220 bytes alfa al programma chiamato (&CPGM); Nel determinare la corretta posizione dei parametri da passare al programma indicato in &CPGM si veda più avanti (definizione dei campi di input) in quanto eventuali campi di input saranno sempre trasferiti in posizioni predeterminate dal programmatore nel campo &DPGM. Invece, se l applicazione da richiamare è un programma su Personal (&SYS = C) il campo &CPGM sarà blank e la stringa comando e gli eventuali dati saranno immessi nel campo &DPGM. ICAROPc ICARO Guida Programmatore

173 Record di definizione dei bottoni. Normalmente una tale funzione potrà tornare utile se il programmatore ha definito delle righe con dei campi di input che, dopo la compilazione, dovranno essere elaborati alla pressione di un certo tasto che riporti una specifica descrizione definita dal programmatore ad esempio ESEGUI Per definire ad esempio un tasto con la descrizione ESEGUI scelto il quale dovrà essere elaborato il programma nell AS/400 PGM888 posto nella libreria ICA$API modificare i seguenti valori: &TREC = S per indicare che il tasto è selezionabile &NRIG = 9991 (o 9992 o 9993 o 9994), &RIGA = ESEGUI ovvero con un testo allineato a sinistra con massimo 15 caratteri; &SYS = H &CPGM = ICA$API/PGM888 se PGM888 è il programma da elaborare dalla libreria ICA$API se il tasto è selezionato. &DPGM = valori o costanti desiderate da passare al programma definito in &CPGM. E possibile definire sino a quattro bottoni richiamando la routine STRBOX passando rispettivamente il valore &NRIG impostato a 9991, 9992, 9993 o 9994 con gli altri campi compilati secondo le rispettive funzioni desiderate e associate ai bottoni con le stesse regole viste per le righe di menu (&SYS = H,C,L, o E). il valore e 9993 definiscono rispettivamente il bottone a sinistra, a centro o a destra nello spazio disponibile in basso alla box. Definizione degli attributi dei campi di input. Se nella definizione delle righe il programmatore ha previsto dei campi di input/output dovrà, per ciascuno, definire, in un record di tipo 9999 (&NRIG) gli attributi del campo e la posizione in cui l eventuale campo di input dovrà essere passato, nel campo &DPGM, come parametro al programma di elaborazione. In pratica, se ad esempio il programmatore ha definito 4 campi (<A> <B> <a> <b>) di input nella box, nella stessa riga o in righe diverse, dovrà, prima di chiudere la trasmissione dei record, con STRBOX, a ICAROPc (&FLAG = F), passare tanti record con &NRIG = 9999, quanti ne necessitano a trasmettere la stringa di definizione di tutti i campi usati nelle righe box. I campi da compilare, per STRBOX, per la trasmissione degli attributi di campo sono: ICARO Guida Programmatore ICAROPc

174 &TREC = C &NRIG = 9999 &ATTRI = &SYS = blank &RIGA = blanks &CPGM = blanks &DPGM = stringa definizione dei campi EC &FLAG = F nell ultimo record o blank se seguono altri record. La stringa di definizione dei campi ha il seguente formato: <A>XYYYZZ:D<B>XYYYZZ:D... In cui <A>, <B> sono l inizio è l identificazione del campo di cui segue la definizione. La definizione di un campo termina all inizio del successivo campo delimitato da < e >; Si ricordi che le lettere devono essere univoche e che una lettera maiuscola e la corrispondente minuscola identificano campi differenti (<a> è diverso da <A>); La definizione dei campi deve iniziare a colonna 1 del campo &DPGM proseguendo sullo stesso record con la definizione degli altri campi; Se &DPGM non è sufficiente a contenere la definizione dei campi si può proseguire con un successivo record continuando sempre a colonna 1 del campo &DPGM senza ripetere il codice campo; X Rappresenta una cifra di tipo campo; E il primo carattere obbligatorio dopo l identificativo di campo: 1= campo di input solo numerico; 2= campo di input alfanumerico; YYY ZZ tre cifre, dopo l identificativo di tipo campo, indicante a partire da quale posizione del campo &DPGM sarà registrato il valore immesso in tale campo per la lunghezza massima specificata nel successivo campo ZZ; Nota bene: Se una box contiene dei campi di input, qualunque sia la riga o il tasto selezionato dalla box, TUTTI i campi di input saranno trasmessi nel campo &DPGM al programma associato alla riga o tasto selezionato. In altri termini, tutti i campi di input dovranno, se desiderato, trovare una ubicazione nel campo &DPGM per ciascuna delle righe definite selezionabili. Indicare come valore di YYY 000 se non si desidera trasferire il valore di questo campo nel campo parametro &DPGM (ad esempio per i campi che si vogliono come output) Due cifre indicante la lunghezza massima accettata nell immissione del campo e trasferita nel campo &DPGM a partire dalla posizione YYY; Immettere il valore 00 se non si desidera trasferire il valore di questo campo nel campo parametro &DPGM (ad esempio campi di solo output) :D Preceduto dal carattere : indicare subito dopo l eventuale valore di default o il valore del campo di output che sarà visualizzato nel campo. ICAROPc ICARO Guida Programmatore

175 Un campo di output va dunque definito come un campo di input con impostato il valore di default con YYY e ZZ impostati a zero. Non dimenticare nell utilizzo della routine STRBOX: Di assumere nel campo &FLAG il valore F nella trasmissione dell ultimo record all applicazione ICAROPc; difatti solo quando ICAROPc riceverà un record con &FLAG=F inizierà l elaborazione e visualizzerà la BOX Windows; Di non utilizzare mai nel campo &CPGM i valori ICA$API/STRBOX o ICA$API/STRQRY; Se un programma utente, che invia una box (ad esempio MEXTINQ), deve inviare un altra box o avviare l elaborazione di una query (vedi utilizzo STRQRY) occorrerà definire in &CPGM un altro programma utente (CL, RPG, C, COBOL,...) che a sua volta utilizzerà le routine STRBOX e STRQRY. Se un programma utente (ad esempio un CL) ha iniziato la trasmissione di record componenti una box ad ICAROPc, con il richiamo della routine STRBOX, esso deve terminare con il richiamo della routine STRBOX con la trasmissione dell ultimo record componente la box (o la definizione dei bottoni o dei campi) con &FLAG = F ; Non è possibile richiamare, nello stesso programma, dopo una STRBOX, la routine STRQRY per l avvio dell elaborazione di una query in quanto l ultima trasmissione (&FLAG = F) passa il controllo a ICAROPc. Se l utente tra richiami di STRBOX inserisce istruzioni ed esegue il richiamo della routine STRQRY si potrebbero verificare errori imprevedibili. Per un esempio di utilizzo di STRBOX vedere il source MEXTINQ e ANSA nel file QCLSRC nella libreria ICA$API. ICARO Guida Programmatore ICAROPc

176 INVIO DI BOX IN SOVRAPPOSIZIONE ED IN SOSTITUZIONE. Liste di record e paginazione. Un programma (esempio MEXTINQ) che invia una box (tramite la routine STRBOX) è normalmente composta da righe alcune delle quali selezionabili. A fronte di una selezione riga è possibile richiamare un altro programma utente (esempio MEXTINQ2) che invia una seconda box. Se il programma MEXTINQ nella riga corrispondente al richiamo del pgm MEXTINQ2 ha usato l opzione &SYS = H la seconda box è generata in sovrapposizione (livello 2) infatti, selezionando il tasto annulla nella seconda box l utente vedrà riapparire la box iniziale generata dal programma MEXTINQ (a livello 1). Viceversa se da una box si richiama un programma utente, che dovrà generare una nuova box, con l opzione &SYS=I allora la seconda box verrà generata in sostituzione nel senso che quest ultima assumerà il numero di livello di chiamata identico al numero di livello della box chiamante; in tal modo la prima box sarà sostituita dalla seconda box ed il tasto annulla non riporterà alla visualizzazione della prima box a meno di non richiamare un programma utente che la generi. L utilizzo della box in sostituzione può tornare utile nella generazione di liste di record abbastanza ampie. Difatti, se l utente desidera emettere una box con 2000 righe dovrebbe attendere, prima della sua comparsa, che tutte le righe siano state trasmesse dall AS/400 al personal computer. Viceversa, l utente potrebbe emettere una prima box con sole 20 righe ed abilitare due bottoni per la gestione (a cura dell utente) di PAGINA AVANTI e PAGINA INDIETRO ; Ogni chiamata della paginazione sarà effettuata con l opzione &SYS = I ottenendo la visualizzazione di soli 20 record per volta e le pagine (con la tecnica della sostituzione) non rimaranno tutte a video. Aggiornamento della Lista delle Librerie. Se in un programma utente, che genera una box, il programmatore ha settato una lista delle librerie e se, successivamente ha richiamato un altro programma che emette una nuova box con un altra lista delle librerie, il ritorno alla box precedente non ripristina la lista delle librerie allo stato originale. Pertanto l utente abbia cura, tutte le volte che richiama programmi da una box di eseguire l aggiornamento della lista delle librerie nell ambito del programma chiamato e non già nella box. ICAROPc ICARO Guida Programmatore

177 La Routine STRQRY Avviare l elaborazione di una query automatica su una o più banche dati Un programma utente come MEXTINQ o PEXTINQ o un programma, scritto dall utente, richiamabile dalla selezione di una riga BOX (vedi STRBOX campi &SYS, &CPGM, &DPGM) potrebbe servire, con l utilizzo in esso della routine STRQRY, per avviare una query automatica su una o più banche dati ICARO. Nella libreria ICA$API, nel file source QCLSRC è fornito il programma esempio ANSA (a sua volta richiamato da una riga del menu MEXTINQ) che ricevendo alcuni campi di input dalla box WINDOWS innesca l elaborazione del programma ANSA2 (vedi source) che, utilizzando la routine STRQRY, avvia una interrogazione nella banca dati Notizie ANSA dopo aver composto la query con i campi di input trasmessi dal programma ANSA. I parametri per il richiamo e l uso della routine sono: CALL ICA$API/STRQRY (&DB &OPT &FLDL &FLDS &SORA &SORC &QRYT) con Campo tipo len descrizione &DB *char 27 massimo 9 codici di tre cifre di banche dati su cui effettuare la query. Estendere a zeri le posizioni non utilizzate &OPT *char 1 V per visualizzare i documenti dopo la ricerca L per listare (lista abbreviata) i documenti dopo la ricerca &FLDL *char 15 Nel caso in cui &OPT = L indicare un massimo di 5 codici (di 3 cifre) relativi ai campi o paragrafi da utilizzare per la lista abbreviata (i campi formattati vanno incrementati di 256); lasciando a zeri questo campo verranno assunti i valori di default per il profilo utente. Nel caso di &OPT uguale a V estendere questa stringa di 15 caratteri a zero. &FLDS *char 9 Indicare un massimo di 3 codici di 3 cifre relativi ai campi o paragrafi da utilizzare quale criterio di ordinamento dei documenti prima della Visualizzazione o lista abbreviata. Estendere a zeri la stringa se l ordinamento non è richiesto. &SORA *char 1 Se &FLDS è impostato ad un valore diverso da zero immettere nel campo &SORA il carattere A per ordinamento Ascendente o D per Discendente. &SORC *char 1 Se &FLDS è impostato ad un valore diverso da zero immettere nel campo &SORC il carattere Y se si desidera ordinare distinguendo Maiuscole e minuscole; utilizzare N per ordinare indifferentemente da maiuscole/minuscole. &QUERT *char 7900 Testo della query secondo la sintassi ICARO. ICARO Guida Programmatore ICAROPc

178 L applicativo Client ICAROPc riceverà, tramite STRQRY, i parametri della query da effettuare ed innescherà le chiamate al server necessarie a Visualizzare o listare i documenti risultanti nella query impostata. La funzione di Navigazione Come è noto, durante la visualizzazione di un documento o dalla lista abbreviata di documenti risultanti da una query è possibile attivare una funzione scritta dall utente per far si che si inneschi una query automatica ad una altra banca dati o, ad esempio, si avvii l elaborazione di un applicativo utente per visualizzare un immagine. Nell interfaccia grafica perché si attivi, per un documento, la visualizzazione della funzione di EXIT per il richiamo di un applicativo utente, deve esistere, nella libreria della banca dati in questione, il programma PEXTINQ scritto dall utente. Tra le banche dati dimostrative consegnate con il prodotto esistono degli esempi applicativi appresso specificati. Per una certa banca dati, la descrizione della funzione di EXIT (es. Immagine, Suono, Vis. Pratica, ecc...), che appare nel relativo bottone di selezione, viene impostato dal menu DEFICA (opz. 2) con l opzione 9 Intestazione della funzione di Exit. Il programma PEXTINQ Perché per una banca dati appaia la funzione di EXIT verso un applicativo utente è necessario che esista nella libreria della banca dati ICA$xxx (con xxx= codice della banca dati) un programma scritto dall utente (CL o RPG o COBOL ecc..) che esegua una delle funzioni appresso indicate. Il programma di nome PEXTINQ, posto nella libreria ICA$xxx, riceverà come parametri il codice della banca dati, il numero della query ICARO ed il riferimento ced del documento selezionato per la navigazione ovvero per la funzione di EXIT. Utilizzando questi valori, PEXTINQ può utilizzare una delle tante API ICARO per reperire informazioni dal documento visualizzato e per elaborale per una nuova query o per l invio, al PC, di una finestra di opzioni o di testo. I parametri ricevuti da PEXTINQ sono: Campo tipo len descrizione &DB *dec 3 Codice della banca dati del documento &QRYNBR* dec 7 Numero di livello della query formulata per il documento visualizzato. &DOCNUM *dec 7 Riferimento CED del documento su cui è stata richiesta la funzione di EXIT. ICAROPc ICARO Guida Programmatore

179 All interno di un programma PEXTINQ, attivato con la pressione del tasto di Navigazione, è possibile A) Visualizzare un Menu di scelte con righe di testo e righe di comando vedi STRBOX Analogamente a quanto visto per il Menu iniziale (MEXTINQ) l utente, alla pressione del tasto di NAVIGAZIONE può inviare un menu di scelte. Un esempio è contenuto nella banca dati 035. Il programma CL PEXTINQ contenuto nella libreria ICA$035 (vedi source) è un esempio di codifica per l invio di una box menu con l utilizzo della routine STRBOX. Difatti effettuando sulla banca dati di esempio la query: Fumat$ visualizzato il documento e premuta la funzione EXIT apparirà la seguente WINDOWS: In questo esempio la routine STRBOX contenuta nel pgm PEXTINQ nell esempio della banca dati 035 provvede a: - Inviare un riga di intestazione da visualizzare come titolo della BOX - Inviare una riga di testo a cui è associato un comando PC che sarà elaborato da ICAROPc se la riga di testo sarà selezionata con il mouse (Immagine paziente). - Inviare una riga di testo a cui è associato il nome di un programma da eseguire sul server AS/400 se la riga è selezionata (Analisi paziente, Diario Clinico, GUIDA). Per l invio di ogni riga da far apparire nella BOX WINDOWS, L utente, nel pgm PEXTINQ, richiamerà la routine STRBOX per inviare al client la riga con le relative opzioni (VEDI uso della routine STRBOX) NOTA BENE: Non dimenticare che l opzione L ed E nel campo &SYS della routine STRBOX non deve essere utilizzata se STRBOX è chiamata dalla funzione di navigazione (dall exit call PEXTINQ o suoi sotto programmi). ICARO Guida Programmatore ICAROPc

180 Con la funzione di richiamo programma su Host è possibile innescare il richiamo di programmi in cascata (PEXTINQ --> PEXTINQ2 ---> PEXTINQ3 ecc...) ognuno dei quali può inviare un ulteriore BOX o avviare al funzione STRQRY. Un altro esempio di utilizzo della funzione STRQRY è disponibile nella banca dati di codice 024 (Sinonimi per archivio bibliografico). Il programma CLP di nome PEXTINQ (vedi più avanti - funzione di navigazione), nella libreria ICA$024, contiene la codifica per attivare una query sulla banca dati 023 in funzione del contenuto di un paragrafo del documento della banca dati 024 (letti con una delle funzioni TEWSPPP, ecc...). EXIT CALL di Controllo della Chiusura dell applicazione ICAROPc (ICALOGOF) Come anticipato nella descrizione della funzione ICALOGON, se il programmatore desidera che alla chiusura dell applicazione ICAROPc (utente che si scollega o chiusura per caduta linea) venga passato il controllo ad un programma utente per gestire, ad esempio, la memorizzazione di dati di contabilizzazione (data e orario di sconnessione, nome utente, tipo chiusura...) può procedere, tenendo presente quanto segue. L applicativo ICAROPc, ricevuto il comando di chiusura ed effettuata la sconnessione fisica, cercherà ed eseguirà, se esiste, il programma scritto dall utente di nome ICALOGOF dalla libreria ICA$API. Il programma ICALOGOF, scritto dall utente, dovrà prevedere come parametri di input i seguenti campi: Campo tipo len JOBUSER *CHAR 10 JOBNAME *CHAR 10 campo di input; in questo campo si riceverà il nome del profilo utente che ha aperto la sessione PC (nel caso di utilizzo del CA/400) o il nome del profilo utente che ha avviato l applicativo server AS/400 per il TCP/IP (STRICATCP). campo di input; in questo campo si riceverà il nome del job relativo al JOBUSER precedentemente descritto. JOBNUM *CHAR 6 campo di input; in questo campo si riceverà il numero del job relativo al JOBUSER precedentemente descritto. USERSIG *CHAR 10 campo di input; in questo campo si riceverà il nome utente utilizzato nella maschera del Signon di ICAROPc. CLOSE *CHAR 1 campo di input; in questo campo si riceverà: 0 per chiusura regolare 1 per chiusura anomala Utilizzando i valori di input ricevuti, il programmatore può inserire nell eventuale programma ICALOGOF le istruzioni che ritiene più opportune per effettuare dei log o comunque operazioni di controllo che riterrà necessarie a chiusura del collegamento. ICAROPc ICARO Guida Programmatore

181 Esempi di interrogazione diretta con link da Pagine HTML Una delle esigenze dell utente può essere quella di realizzare, in una pagina HTML, un link per avviare una query diretta ad una banca dati ICARO. Così, ad esempio, in una pagina HTML, al testo Le notizie sui mercati valutari si vuol far corrispondere una ricerca automatica, nella banca dati Notiziario, dell espressione mercati adj valutari ottenendo o la lista abbreviata o la visualizzazione diretta dei documenti risultanti dalla ricerca.. Un esempio è dato dalla pagina example.htm che, dopo l installazione di ICANET, si trova nella sottodirectory ICANET11/WWWROOT. Da questa pagina è possibile con dei link: Richiamare la pagina standard di logon; Collegarsi senza la mappa di logon (assumere per default l utente Anonymous), Avviare una query alla banca dati NOTIZIARIO, con user ANONYMOUS, ottenendo la lista abbreviata dei documenti corrispondenti alla ricerca mercati adj valutari, Avviare una query alla banca dati NOTIZIARIO ottenendo la visualizzazione dei documenti, corrispondenti alla ricerca mercati adj valutari, L utente esperto può analizzare la pagina HTML di nome EXAMPLE, contenuta nella sottodirectory ICANET11/WWWROOT del prodotto ICANET. Cliccando nella pagina example appare: Analizzando il source di questa pagina e quindi la sintassi corretta, l utente potrà modificare i termini delle espressioni tenendo conto che nell esempio : ICARO Guida Programmatore ICAROPc

182 NOIRE deve essere sostituito dal nome del server WEB 032 deve essere sostituito dal codice banca dati utente (banca dati che deve essere autorizzata all utente ANONYMOUS) nella libreria ICA$API devono esistere i pgm ICALOGON MEXTINQ e QDIRECT ed in caso contrario vanno ricompilati dal file qclsrc di ICA$API. Per eseguire i link della pagina Example.html con la banca dati 032 Notiziario fornita come esempio con il prodotto ICARO, accertarsi che: a) il prodotto ICANET sia installato regolarmente secondo le note di installazione contenute nel manuale di installazione IcaroPc/Icaronet. In questo caso da un browser digitando dovrebbe far apparire la mappa di logon. b) l utente Anonymous, con password anonymous, sia definito come profilo utente sia nell AS/400 sia come utente ICARO abilitato alle banche dati pubbliche tra le quali la banca dati di esempio fornita con il prodotto ICARO di codice 032 Notiziaro. Se la banca dati non esiste ripristinarla dal supporto fornito con il prodotto ICARO. c) nella libreria ICA$API esistano i pgm ICALOGON, MEXTINQ, QDIRECT. Se non esistono compilarli in ICA$API (CRTCLPGM) dai source che si trovano nel file qclsrc della libreria ICA$API. Se ICALOGON ed MEXTINQ esistono perché creati dall utente accertarsi che in essi siano contenute le istruzioni dei source di esempio. d) Compilare in ICA$API i source CL:di esempio ANSA ed ANSA2. e) Nella pagina EXAMPLE.HTM, mediante NOTEPAD, sostituire il nome di sistema NOIRE con il nome del sistema web server. A questo punto visualizzando la pagina html example aggiornata e selezionando la voce mercati valutari per la visualizzazione apparirà direttamente il risultato della ricerca: ICAROPc ICARO Guida Programmatore

183 Pagina vuota ICARO Guida Programmatore ICAROPc

184

185 Capitolo 16 La libreria ICAWIN l interfaccia grafica per Windows (API) Informazioni sulla libreria ICAWin In questo manuale vengono illustrate le caratteristiche della libreria ICAWin dal punto di vista del programmatore Windows. La conoscenza delle funzioni descritte in questo manuale permette la realizzazione di interfacce client di accesso ai dati Icaro personalizzate. Relativamente all'ambiente client su personal computer, ICAWin è essenzialmente una libreria a collegamento dinamico (DLL) che permette di realizzare applicazioni in ambiente client/server utilizzando una tecnologia di tipo message and queuing in connessione con il prodotto di Information Retrival ICARO. Parallelamente all'ambiente client sul personal computer, sul sistema IBM AS/400 deve trovarsi installato il prodotto programma ICARO e la relativa interfaccia server dedicata al colloquio con l'ambiente ICAWin. La versione 1.1 di ICAWin si basa sugli ambienti di seguito descritti: - L'ambiente client è costituito dal personal computer con installato: l'ambiente operativo Microsoft Windows 3.x, Microsoft Windows 95, Microsoft Windows NT; la parte client del prodotto di connessione al sistema di elaborazione IBM AS/400 in ambiente SNA denominato IBM Client Access/400 configurato in modo che sia installato il modulo relativo alla gestione delle code dati oppure, in alternativa, l ambiente Microsoft TCP/IP v1.1 (Windows Socket); la componente client di ICAWin. - L'ambiente server, invece, è costituito da un sistema IBM AS/400 con installato: il sistema operativo IBM OS/400 ver 3.1; la parte server del prodotto programma IBM Client Access/400 ver 3.1 o in alternativa il protocollo TCP/IP (fornito con il sistema operativo IBM OS/400 ver 3.1); il prodotto di Information Retrival ICARO ver 3.2; la componente server di ICAWin. La libreria ICAWin.dll dispone di una serie di funzioni, richiamabili da programmi applicativi, che consentono l'accesso ad una serie di funzioni del prodotto ICARO. In particolare, le funzioni disponibili riguardano le seguenti aree: accesso, in lettura, alla lista delle banche dati ed alle note ad esse relative; accesso, in lettura, alla lista di campi/paragrafi per le banche dati; accesso, in lettura, alla lista delle tabelle per le banche dati; accesso, in lettura, al dizionario; esecuzione di una ricerca relativamente ad un massimo di nove banche dati; accesso, in lettura, alla lista delle ricorrenze relative ad una domanda; accesso, in lettura, alla lista abbreviata relativa ad una domanda; accesso, in lettura, ai documenti risultato di una ricerca; esecuzione delle funzioni di navigazione fra documenti e banche dati. ICARO Guida Programmatore 16-1 ICAWIN

186 La libreria ICAWin.dll, realizzata in linguaggio C, è stata compilata utilizzando il modello di memoria large; l header relativo contiene dichiarazioni FAR sia per le funzioni che per le variabili da queste utilizzate. Questo permette al programmatore di includere l header ICAWin.h ai propri programmi utilizzando un qualsiasi modello di memoria per le successive operazioni di compilazione. Unitamente all'ambiente ICAWin è disponibile il prodotto di accesso e consultazione delle banche dati ICARO basato su ICAWin denominato IcaroPC ver 1.1. Le versioni successive dei due prodotti ICAWin e IcaroPC includeranno la fase di gestione delle banche dati, permettendo funzioni quali il caricamento e la modifica di documenti. ICAWIN 16-2 ICARO Guida Programmatore

187 Descrizione dell'ambiente La libreria ICAWin permette di realizzare un legame applicativo fra l'ambiente client Microsoft Windows ed il prodotto software di Information Retrival ICARO in un ambiente server OS/400 ver In particolare, ICAWin mette a disposizione dei programmatori su personal computer in ambiente Windows una serie di funzioni che consentono l'accesso ai servizi applicativi ICARO. Il supporto trasmissivo utilizzato si basa sia sull'architettura SNA, utilizzando il protocollo LU 6.2 ed i servizi ad esso connessi e disponibili nel prodotto Client Access /400; sia sul protocollo TCP/IP così come implementato all interno dei sistemi operativi IBM OS/400 e Microsoft Windows. La soluzione utilizzata da ICAWin è allora rappresentata, nella sua versione completa che utilizza sia il protocollo LU 6.2 che TCP/IP, nel seguente schema: In essa si vede che la "Interfaccia Utente Grafica" del client è separata dal sistema operativo e dal software di rete da due strati software. Il primo strato ("Interfaccia verso i servizi di rete") si occupa di dialogare con il protocollo di rete, sia esso SNA che TCP/IP; il secondo strato ("Interfaccia applicativa verso ICARO"), viceversa, offre una serie di funzioni di accesso ad ICARO alla "Interfaccia Utente Grafica". Quest'ultima vede i servizi di rete e le API di accesso ad ICARO del tutto mascherate dai due strati software specializzati posti ai livelli inferiori. Questa particolare struttura permette di far sì che la "Interfaccia Utente Grafica" non si preoccupi di conoscere i dettagli dell'implementazione del colloquio, in ambito client/server, con le API di ICARO per accedere ai dati contenuti nelle banche dati, ma utilizzi, attraverso la DLL "Interfaccia applicativa verso ICARO", le funzioni di accesso ad ICARO. Tale interfaccia permette quindi l'accesso alle funzioni di ICARO ad applicazioni operanti su personal computer. Lo strato software denominato "Interfaccia verso i servizi di rete" consiste in una DLL che mette a disposizione dello strato superiore ("Interfaccia applicativa verso ICARO Guida Programmatore 16-3 ICAWIN

188 ICARO") i servizi di accesso e di trasporto dei dati offerti dalla rete e dal protocollo di comunicazione. Come esempio del meccanismo di funzionamento del sistema e degli strati software individuati si consideri il caso in cui la "Interfaccia Utente Grafica" richiede l'esecuzione d una ricerca in una data banca dati. Questa richiesta verrà passata attraverso una chiamata funzionale allo strato software sottostante. I dettagli implementativi della ricerca e la sua esecuzione attraverso le API di ICARO poste sul server AS/400 sono noti esclusivamente allo strato di "Interfaccia applicativa verso ICARO". L'esecuzione remota delle API e lo scambio di dati con il sistema AS/400 viene gestito dalla "Interfaccia verso i servizi di rete" che si occupa di tradurre le richieste della "Interfaccia applicativa verso ICARO" in richieste verso l'ambiente di trasmissione (sia esso CA/400 piuttosto che TCP/IP). ICAWIN 16-4 ICARO Guida Programmatore

189 Le strutture dati di ICAWin 1.0 La struttura dati ICA_Env Le funzioni della libreria ICAWin.dll utilizzano la struttura dati ICA_Env definita nell'header ICAWin.h per memorizzare le informazioni relative alla sessione di lavoro. Pertanto, una struttura dati ICA_Env deve essere definita all'interno del programma applicativo in modo che le funzioni di ICAWin.dll possano riferirsi ad essa per mantenere le informazioni relative alla sessione di lavoro. La struttura dati ICA_Env è così composta: struct ICA_Env { short short LONG struct c_message struct MSTCPIP311_Parm struct Function int unsigned char struct ICA_Table struct ICA_DBList char char char char char char char char char char char char char char c_type; c_debug; c_waittime; c_msg; TCP1; FP; ICA_Language; SpecialChar[34]; ICA_T; ICA_DBL; InitProcType; DBSelProcType; QueryProcType; IcaroPCDirectory[80]; ServerDirectory[80]; SessionPCDirectory[80]; MsgDataTime[13]; User[11]; Password[11]; ASSystem[16]; ASerialNumber[10]; RagSoc[31]; IDArea[11]; PgmArea[11]; } int NavLevel; Alcune delle variabili contenute in ICA_Env (ad esempio i messaggi della struttura c_message piuttosto che la variabile IcaroPCDirectory) vengono valorizzata dalle funzioni di ICAWin.dl man mano che queste vengono richiamate dal programma applicativo; una seconda serie (ad esempio le variabili c_type o ICA_Language) deve ICARO Guida Programmatore 16-5 ICAWIN

190 essere valorizzata dal programma applicativo prima che le funzioni di ICAWin.dll vengano richiamate da questo; altre variabili sono, invece, variabili riservate utilizzate all interno della libreria ICAWin.dll e che non devono essere modificate dal programma applicativo. La descrizione di dettaglio delle variabili contenute in ICA_Env è fornita di seguito. Nome della variabile short c_type Descrizione Questa variabile, definita dal programma applicativo, indica alle funzioni della libreria il tipo di protocollo da utilizzare nella connessione verso il server AS/400. Questo parametro può valere: 0: è utilizzato il protocollo SNA 6.2 e le funzioni applicative contenute nel prodotto IBM Client Access/400. 2: è utilizzato il protocollo TCP/IP (Microsoft Windows socket v1.1). Nome della variabile short c_debug Descrizione Questa variabile definita dal programma applicativo indica alle funzioni della libreria il tipo di debug da attivare. I messaggi ritornati dai moduli di debug vengono registrati nel file Debug.ica posto nella directory IcaroPCDirectory. Questo parametro può valere: 0: Nessun debug attivo, 1: Debug attivo in trasmissione/ricezione/comandi, 2: Debug attivo in trasmissione, 3: Debug attivo in ricezione, 4: Debug attivo in comandi. Nome della variabile LONG c_waittime Descrizione Questa variabile, definita dal programma applicativo, indica (in secondi) alle funzioni di ICAWin.dll il tempo di attesa da utilizzare nelle API CA/400 prima di considerare il colloquio con il server interroto ed intraprendere, laddove possibile, delle azioni di recupero. ICAWIN 16-6 ICARO Guida Programmatore

191 Nome della struttura struct c_message { short NMsg; char *MsgID[]; WORD SevCode[]; char *Message[]; } c_msg; Descrizione Questa struttura contiene gli eventuali messaggi di errore ritornati dalle funzioni di comunicazione del Client Access/400. Il parametro NMsg indica il numero di messaggi ritornati; il parametro MsgID contiene l'identificativo del messaggio; il parametro SevCode contiene il codice di gravità dei messaggi; il parametro Message contiene il testo del messaggio. Nome della struttura struct MSTCPIP311_Parm { WORD Version; unsigned short Port; WSADATA data; int Socket; }; struct sockaddr_in struct hostent Server; *HostName; Descrizione Questa struttura è riservata per un utilizzo interno delle funzioni di ICAWin.dll, tranne che per la variabile Port che deve contenere il numero di porta TCP/IP da utilizzare per il colloquio con il server AS/400. Il valore utilizzato per default è di Nome della struttura struct Function FP Descrizione Questa struttura è riservata per un utilizzo interno delle funzioni di ICAWin.dll. ICARO Guida Programmatore 16-7 ICAWIN

192 Nome della variabile int ICA_Language Descrizione Questa variabile, definita dal programma applicativo, indica la lingua che quest ultimo intende utilizzare. Questo parametro può valere: 1: Italiano, 2: Inglese, 3: Tedesco, 4: Francese, 5: Spagnolo, 6: Portoghese, 7: Arabo. Nome della variabile unsigned char SpecialChar[34]; Descrizione Questa variabile, ritornata dal server AS/400 a seguito della chiamata alla funzione ICA_INIT, contiene i caratteri speciali inseriti nei testi ritornati da Icaro. I primi due caratteri a posizione 0 ed 1 costituiscono I due delimitatori utilizzati nella funzione ICA_RtvDiz per separare le caratteristiche del termine individuato; mentre I simboli successivi indicano le combinazioni di grassetti, sottolineature, colori, etc utilizzate nel testo. L elenco di dettaglio di tale sequenza di caratteri è illustrata di seguito. Posizione Colore del testo Colore dello sfondo Attributi 2 Nero Bianco Normale 3 Bianco Nero Normale 4 Nero Bianco Grassetto 5 Nero Grigio Normale 6 Nero Bianco Sottolineato 7 Verde Bianco Normale 8 Verde Nero Grassetto 9 Rosso Bianco Normale 10 Rosso Nero Grassetto 11 Non usato Non usato Non usato 12 Rosso Bianco Italico 13 Bianco Rosso Normale 14 Non usato Non usato Non usato 15 Viola Bianco Normale 16 Viola Nero Grassetto 17 Giallo Nero Normale 18 Blu Bianco Grassetto 19 Ciano Nero Grassetto ICAWIN 16-8 ICARO Guida Programmatore

193 20 Azzurro Bianco Normale 21 Ciano Nero Grassetto 22 Giallo Bianco Sottolineato 23 Nero Ciano Grassetto 24 Grigio Bianco Normale 25 Grigio Nero Grassetto 26 Bianco Blu Normale 27 Non usato Non usato Non usato 28 Giallo Blu Normale 29 Nero Viola Normale 30 Giallo Viola Grassetto 31 Nero Giallo Normale 32 Non usato Non usato Non usato Nome della struttura struct ICA_Table { short NRec; char *Table[]; } ICA_T; Descrizione Questa struttura, valorizzata dalla funzione ICA_RMsg, contiene gli eventuali messaggi per l'utente disponibili sul server AS/400. La variabile NRec contiene il numero di record che costituiscono il messaggio; La tabella Table contiene il testo del messaggio. Nome della struttura struct ICA_DBList { short NSel; char *Code[]; char *Name[]; } ICA_DBL; Descrizione Questa struttura contiene la lista delle banche dati selezionata dall'utente ed utilizzata in funzioni quali ICA_LDBA. Il parametro NSel deve contenere il numero di banche dati selezionate; il parametro Code deve contenere i codici delle banche dati selezionate; il parametro Name deve contenere la descrizione della banca dati. Nome della variabile char InitProcType ICARO Guida Programmatore 16-9 ICAWIN

194 Descrizione Questa variabile contiene un carattere che indica l esistenza di una procedura personalizzata per la inizializzazione della sessione di lavoro Icaro. I valori permessi sono: S : Standard. Non vi sono procedure personalizzate di inizializzazione. L utente che ha iniziato la sessione di lavoro può operare utilizzando tutte le funzioni previste all interno di IcaroPC; H : Host. Esiste una procedura personalizzata definita sul server AS/400. Le modalità di esecuzione delle attività di ricerca e visualizzazione dei dati sono guidate da moduli definiti sul server AS/400. La tecnica di definizione di tali moduli e la loro interazione con la componente client IcaroPC sono descritti in dettaglio nel manuale del programmatore ICARO: Guida per il programmatore. C : Client. Esiste una procedura personalizzata definita sul client. Le modalità di esecuzione delle attività di ricerca e visualizzazione dei dati sono guidate da un programma di nome MExtInq.exe definito sul client. La modalità di lavoro di tale programma e le sue interazioni con IcaroPC sono descritti in dettaglio nel capitolo L interfaccia di accesso a programmi esterni. Questa variabile è ritornata dalla funzione ICA_Init. Nome della variabile char DBSelProcType Descrizione Questa variabile contiene un carattere che indica la esistenza di una procedura personalizzata per la selezione delle banche dati Icaro. I valori permessi sono: S : Standard. Non vi sono procedure personalizzate di selezione delle banche dati. L utente che ha iniziato la sessione di lavoro può operare utilizzando tutte le funzioni previste all interno di IcaroPC; C : Client. Esiste una procedura personalizzata definita sul client. Le modalità di esecuzione delle attività di selezione delle banche dati sono guidate da un programma di nome LExtInq.exe definito sul client. La modalità di lavoro di tale programma e le sue interazioni con IcaroPC sono descritti in dettaglio nel capitolo L interfaccia di accesso a programmi esterni. Questo parametro è ritornato dalla funzione ICA_Init. Nome della variabile char QueryProcType Descrizione Questa variabile contiene un carattere che indica la esistenza di una procedura personalizzata per la composizione della query Icaro. I valori permessi sono: S : Standard. Non vi sono procedure personalizzate di composizione della query. L utente che ha iniziato la sessione di lavoro può operare utilizzando tutte le funzioni previste all interno di IcaroPC; C : Client. Esiste una procedura personalizzata definita sul client. Le modalità di formulazione della query sono guidate da un programma di nome QExtInq.exe definito sul client. La modalità di lavoro di tale programma e le sue interazioni con IcaroPC sono descritti in dettaglio nel capitolo L interfaccia di accesso a programmi esterni. Questo parametro è ritornato dalla funzione ICA_Init. ICAWIN ICARO Guida Programmatore

195 Nome della variabile char *IcaroPCDirectory Descrizione Questa variabile, lunga 80 byte, e definita dal programma applicativo, deve contenere il nome della directory in cui è installato ICAWin. Nome della variabile char *ServerDirectory Descrizione Questa variabile, lunga 80 byte, e ritornata dalla funzione ICA_Init, contiene il nome della directory relativa al server AS/400. Nome della variabile char *SessionPCDirectory Descrizione Questa variabile, lunga 80 byte, contiene il nome della directory relativa alla sessione di lavoro corrente. Questo parametro viene valorizzato dalla funzione ICA_Init. Nome della variabile char *MsgDataTime Descrizione Questa variabile, valorizzata dalla funzione ICA_Init, contiene la data e l'ora dell'ultima modifica fatta al messaggio per gli utenti sul server AS/400. Questa informazione viene utilizzata successivamente dalle funzione di ICAWin per ottimizzare il trasferimento dei dati riducendo sia i tempi di elaborazione sul server AS/400 che la quantità di dati trasferiti tra il client ed il server. Nome della variabile char *User Descrizione Questa variabile contiene il nome dell'utente che richiede l'inizializzazione della sessione di lavoro (massimo 10 byte). La variabile deve contenere il nome di un profilo utente autorizzato all'uso di ICARO oppure il valore *JOB se si vuole assumere, come nome utente, il nome dell'utente che ha avviato il router nel caso di connessione SNA (CA/400). La variabile deve essere valorizzata dal programma utente. ICARO Guida Programmatore ICAWIN

196 Nome della variabile char *Password Descrizione Questa variabile contiene la password dell'utente User (massimo 10 byte). La variabile deve contenere la password del profilo utente indicato nel parametro User oppure il valore *NONE se si è utilizzato il valore *JOB nel parametro User. La variabile deve essere valorizzata dal programma utente. La password scambiata fra il client ed il server viene opportunamente cifrata dalle funzioni interne di ICAWin.dll in modo tale che non possa essere trafugata da eventuali intrusi. Nome della variabile char *ASSystem Descrizione Questa variabile contiene il nome del server AS/400 verso il quale si vuole aprire una sessione di lavoro. La variabile deve essere valorizzata dal programma utente. Il nome del server è, nel caso di una connessione SNA, il nome APPN del server; mentre, nel caso di una connessione TCP/IP, è l indirizzo IP del server cui ci si vuole connettere. Nome della variabile char *ASSerialNumber Descrizione Questa variabile, lunga 10 caratteri, contiene il numero di serie del server AS/400. Questo parametro viene utilizzato per creare la directory che conterrà tutte le directory di lavoro delle sessione aperte con quello specifico server AS/400. Questo parametro è ritornato dalla funzione ICA_Init. Nome della variabile char *RagSoc Descrizione Questa variabile, lunga 31 caratteri, contiene una stringa utilizzata per indicare la ragione sociale della società proprietaria della licenza d uso di ICARO. Questa variabile è ritornata dalla funzione ICA_Init. Nome della variabile char *IDArea Descrizione Questa variabile contiene il nome della libreria di lavoro sul server AS/400. Essa è composta da "WICA" ed un identificativo numerico univoco per il server. Questa variabile è ritornata dalla funzione ICA_Init. ICAWIN ICARO Guida Programmatore

197 Nome della variabile char *PgmArea Descrizione Questa variabile contiene il nome della coda dati (massimo 10 byte) assegnata dal programma server ed utilizzata per la sottomissione di comandi al server AS/400. Essa è composta da "WICA" ed un identificativo numerico univoco per il server AS/400 (in pratica il numero del lavoro assegnato dal sistema operativo OS/400). Questa variabile è ritornata dalla funzione ICA_Init. Nome della variabile char *NavLevel Descrizione Questa variabile contiene il livello di navigazione attuale. 2.0 La struttura dati ShortList La struttura dati ShortList contiene al sue interno tutte le informazioni necessarie alla definizione della lista abbreviata ottenuta come risultato di una interrogazione. Essa è costituita come segue: struct ShortList { char DBId[4]; char Level[8]; char TotDoc[10]; long From; long To; char Format[3]; char Modality; char Sort; char Mm; char ShListOption[25]; char NavigationName[16]; }; Il significato delle singole variabili è di seguito indicato: Nome della variabile char *DBId Descrizione costituisce il codice della banca dati selezionata. ICARO Guida Programmatore ICAWIN

198 Nome della variabile char *Level Descrizione E il livello della domanda. Questo parametro è ritornato dalla funzione ICA_SndQry all'interno del campo Result. Nome della variabile char *TotDoc Descrizione Rappresenta il numero totale dei documenti trovati nella ricerca. Questo parametro è ritornato dalla funzione ICA_SndQry all'interno del campo Result per ognuna delle 9 possibili banche dati selezionate. Nome della variabile long From Descrizione Rappresenta il numero di documento relativo dal quale si vuole iniziare la lettura. Nome della variabile long To Descrizione Rappresenta il numero di documento relativo fino al quale si vuole effettuare la lettura. Nome della variabile char *Format Descrizione E il formato di visualizzazione della lista abbreviata e il criterio di ordinamento definito per la banca dati. ICAWIN ICARO Guida Programmatore

199 Nome della variabile char *Modality Descrizione Questo parametro indica la modalità LTR o BIDI. Nome della variabile char *Sort Descrizione E il tipo di sort da utilizzare per l estrazione dei documenti della lista abbreviata. Questo parametro vale A per un sort di tipo ascendente oppure D per un sort di tipo discendente. Nome della variabile char *Mm Descrizione Rappresenta la differenza maiuscolo/minuscolo nel sort. Questo parametro vale Y per effettuare un sort differenziando i caratteri minuscoli dai maiuscoli oppure N per effettuare un sort non differenziando i caratteri minuscoli dai maiuscoli. Nome della variabile char *ShListOption Descrizione Questo parametro, definito dall'utente, contiene un record con definita la lista dei campi/paragrafi di default da utilizzare nella lista abbreviata e la lista dei campi/paragrafi da utilizzare per l'ordinamento definiti sulla banca dati di codice DBID. La struttura del record è la seguente: Posizione Descrizione 1-15 Codici dei campi/paragrafi usati nella lista abbreviata (massimo 5 campi) Descrizione dei campi/paragrafi Codici dei campi/paragrafi usati nell'ordinamento (massimo 3 campi) ICARO Guida Programmatore ICAWIN

200 3.0 La struttura dati Document La struttura dati Document contiene al suo interno tutte le informazioni necessarie alla definizione di un documento ottenuto come risultato di una interrogazione. Essa è costituita come segue: struct Document { char DBID[4]; char Level[8]; char TotDoc[10]; long From; long To; int FldParPos; int RowPos; int Offset; char RifCED[8]; char Format[3]; char Modality; char Sort; char Mm; char DocOption[1550]; char Paragraph[4]; int Row; char NavigationName[16]; }; Il significato delle singole variabili è di seguito indicato: Nome della variabile char *DBId Descrizione Costituisce il codice della banca dati selezionata. Nome della variabile char *Level Descrizione E il livello della domanda. Questo parametro è ritornato dalla funzione ICA_SndQry all'interno del campo Result. ICAWIN ICARO Guida Programmatore

201 Nome della variabile char *TotDoc Descrizione Rappresenta il numero totale dei documenti trovati nella ricerca. Questo parametro è ritornato dalla funzione ICA_SndQry all'interno del campo Result per ognuna delle 9 possibili banche dati selezionate. Nome della variabile long From Descrizione Rappresenta il numero di documento relativo dal quale si vuole iniziare la lettura. Nome della variabile long To Descrizione Rappresenta il numero di documento relativo fino al quale si vuole effettuare la lettura. Nome della variabile int FldParPos Descrizione E il campo/paragrafo di partenza per la lettura del documento. Nome della variabile int RowPos Descrizione E la riga di partenza nell'ambito del campo/paragrafo indicato nella variabile precedente. Nome della variabile int Offset Descrizione Rappresenta il numero di righe da leggere. ICARO Guida Programmatore ICAWIN

202 Nome della variabile char *RifCED Descrizione E il riferimento CED del documento letto. Nome della variabile char *Format Descrizione E il formato di visualizzazione del documento ed il criterio di ordinamento definito per la banca dati. Nome della variabile char *Modality Descrizione Questo parametro indica la modalità LTR o BIDI. Nome della variabile char Sort Descrizione E il tipo di sort da utilizzare per l estrazione dei documenti. Questo parametro vale A per un sort di tipo ascendente oppure D per un sort di tipo discendente. Nome della variabile char Mm Descrizione Rappresenta la differenza maiuscolo/minuscolo nel sort. Questo parametro vale Y per effettuare un sort differenziando i caratteri minuscoli dai maiuscoli oppure N per effettuare un sort non differenziando i caratteri minuscoli dai maiuscoli. Nome della variabile char *DocOption Descrizione Questo parametro, definito dall'utente, contiene un record con definita la lista dei campi/paragrafi di default da utilizzare nella estrazione del documento e la lista dei campi/paragrafi da utilizzare per l'ordinamento definiti sulla banca dati di codice DBID. La struttura del record è la seguente: ICAWIN ICARO Guida Programmatore

203 Posizione Descrizione 1-9 Codici dei campi/paragrafi usati nell ordinamento (massimo 3 campi) Descrizione dei campi/paragrafi da usare per la visualizzazione. Nome della variabile char *Paragraph Descrizione E l ultimo paragrafo letto (serve alla ripartenza). Nome della variabile int *Row Descrizione E l ultima riga letta nell'ambito del paragrafo (serve alla ripartenza). Nome della variabile char *NavigationName Descrizione Questa stringa contiene il testo definito in Icaro per l opzione di navigazione definita per qule documento. ICARO Guida Programmatore ICAWIN

204 Le funzione di ICAWin Nome funzione: ICA_Init Descrizione Questa funzione inizializza una sessione di colloquio applicativo tra l'interfaccia client del personal computer ed il prodotto programma ICARO sul server AS/400. La chiamata alla funzione ICA_Init è propedeutica a qualsiasi altra operazione effettuata attraverso le funzioni contenute nella libreria ICAWin.dll. La funzione provvede a creare un ambiente univoco (in pratica una libreria sul server AS/400 ed una directory sul client pc) che conterrà tutti i file di lavoro e le code dati per lo scambio di messaggi tra il client ed il server. Tale ambiente sul server AS/400 assume come nome il valore contenuto nel parametro IDArea. Il giornale delle interrogazioni ICARO su AS/400, se attivo, viene registrato nella libreria IDArea del server AS/400. All'interno della directory IcaroPCDirectory di installazione di ICAWin sul client, invece, viene creata, se non esiste, la directory ServerDirectory, il cui nome è costituito dal numero di serie del server AS/400 (per ulteriori dettagli sulla struttura delle directory si veda la parte introduttiva a ICAWin). Questa directory, che non sarà più cancellata da ICAWin, conterrà a sua volta le directory SessionPCDirectory relative alle singole sessioni di lavoro; il nome di tale directory è composto dalla lettera "W" seguita dalla sequenza numerica contenuta nel parametro IDArea e dalla estensione ".ICA". Anche tali directory di lavoro verranno create anche loro dalla funzione ICA_Init. ICA_Init provvede a valorizzare, inoltre, le variabili globali DBDataTime e MsgDataTime contenenti rispettivamente la data e l'ora dell'ultima modifica della lista delle banche dati disponibili sul server AS/400 e del messaggio di collegamento definito in ICARO per gli utenti. Una sessione di lavoro verso ICARO, iniziata con una chiamata alla funzione ICA_Init, deve concludersi con il richiamo della funzione ICA_End perché siano correttamente eliminate le aree di lavoro create per la sessione sia sul server AS/400 che sul client pc. Sintassi C int ICA_Init(HWND hdlg, struct ICA_Env *E); ICAWIN ICARO Guida Programmatore

205 Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. Return code Il valore ritornato da ICA_Init è dettagliato nella tabella seguente. Codice numerico Descrizione 1 La sessione applicativa verso ICARO è stata aperta con successo. E disponibile un messaggio per gli utenti. 0 La sessione applicativa verso ICARO è stata aperta con successo. Non è disponibile un messaggio per gli utenti. -1 Inizializzazione dell'ambiente di comunicazione fallita. Probabile errore nell'assegnazione della variabile globale c_type. -10 Inizializzazione della sessione di comunicazione fallita. -11 Errore generico nell'inizializzazione della sessione di comunicazione. Probabile errore nell'assegnazione della variabile globale c_type. -20 Inizializzazione della sessione ICARO fallita. -21 Errore generico nell'inizializzazione della sessione ICARO. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ricevuto dal server AS/400 non è stato riconosciuto come proveniente dal programma server di inizializzazione ICA_INIT. -31 L'utente ritornato dal programma server ICA_INIT non è stato riconosciuto come quello definito dall'api ICA_Init sul client. -32 Nome utente o password errata in ICARO. -33 Utente o profilo non autorizzato in ICARO. -34 Prodotto ICARO non autorizzato. -35 Programmi server di ICARO non autorizzati. -36 Il sottosistema QICARO sul server non è attivo. -37 Errore nella procedura di inizializzazione sul server AS/ La creazione della directory di lavoro sul client è fallita. -50 Errore nella ricezione dei messaggi dal server AS/ Errore generico nell'inizializzazione della sessione di lavoro Icaro. Probabile errore in c_type.. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICARO Guida Programmatore ICAWIN

206 Nome funzione: ICA_RMsg Descrizione La funzione ICA_RMsg accede in lettura ai messaggi per l'utente definiti in ICARO per la sessione di lavoro IDArea. Essa opera in modo tale da minimizzare i tempi di risposta e la quantità di dati trasmessi attraverso il supporto trasmissivo che collega il server AS/400 al client pc. In quest'ottica, la funzione ICA_RMsg si basa sul contenuto della variabile globale MsgDataTime valorizzata dalla precedente chiamata alla funzione ICA_Init. Il contenuto di MsgDataTime indica la data e l'ora dell'ultima modifica subita dal messaggio utente. La prima volta che viene chiamata la funzione ICA_RMsg essa provvede a memorizzare il contenuto della variabile MsgDataTime nel file MModify.ica contenuto nella directory ServerDirectory relativa al server AS/400. Quindi il messaggio viene memorizzato all'interno del file Message.ica posto nella stessa directory ServerDirectory al fine di crearne una copia locale. Nelle successive chiamate di ICA_RMsg essa provvede a confrontare il valore contenuto nel file MModify.ica con quello contenuto nella variabile MsgDataTime. Se da questo confronto emerge che il messaggio sul server AS/400 non è stato modificato dall'ultima volta che è stato scaricato sul client e il file Message.ica sul client non è stato cancellato, la funzione utilizza la copia locale del messaggio altrimenti provvede a scaricare dal server AS/400 la nuova versione del messaggio, aggiornando di conseguenza i due file MModify.ica e Message.ica per i successivi usi. ICA_RMsg ritorna poi il messaggio utente nella struttura globale ICA_T di tipo ICA_Table. In particolare in essa la variabile intera NRec conterrà il numero di record che compongono il messaggio mentre questi ultimi saranno posti nella matrice di char Table anch'essa contenuta nella struttura ICA_T. Sintassi C int ICA_RMsg(HWND hdlg, struct ICA_Env *E, char *Table); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *Table E il nome della tabella ICARO che si vuole ricevere dal server AS/400. ICAWIN ICARO Guida Programmatore

207 Return code Il valore ritornato dalla funzione ICA_RMsg è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo ma non vi sono messaggi. 1 La funzione è stata eseguita con successo e vi sono messaggi. -10 Esecuzione del programma server ICA_RMSG fallita. -11 Errore generico nella esecuzione del programma server ICA_RMSG. Probabile errore nell'assegnazione della variabile globale c_type. -20 Ricezione di messaggi dal server AS/400 fallita. -21 Errore generico nella ricezione di messaggi dal server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ricevuto dal server non è stato riconosciuto come proveniente dal programma server ICA_RMSG. -32 Errore generico verificatosi nel programma server ICA_RMSG. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICARO Guida Programmatore ICAWIN

208 Nome funzione: ICA_RTxt Descrizione La funzione ICA_RTxt accede in lettura ad un membro in un file di database sul server per la sessione di lavoro IDArea. Il membro, se trovato, viene memorizzato nella directory temporanea SessionPCDirectory relativa alla sessione di lavoro sul client nel file indicato nella variabile globale NoteFile. Il file NoteFile è strutturato in modo tale che ogni record del membro contenuto nel file di database del server AS/400 è separato dal successivo da un carattere di newline ("\n"). Sintassi C int ICA_RTxt(HWND hdlg, struct ICA_Env *E, char *Library, char *File, char *Member,short Type, char *NoteFile); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *Library E il nome della libreria del server AS/400 contenente il file. char *File E il nome del file del server AS/400. char *Member E il nome del membro. short Type E il tipo di conversione desiderata. Questo parametro vale: 1 nel caso ASCII; 2 nel caso di conversione dei caratteri di controllo ICARO. char *NoteFile E il path e nome del file sul pc client. ICAWIN ICARO Guida Programmatore

209 Return code Il valore ritornato dalla funzione ICA_RTxt è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -10 Esecuzione del programma server ICA_RTXT fallita. -11 Errore generico nella esecuzione del programma server ICA_RTXT. Probabile errore nell'assegnazione della variabile globale c_type. -20 Ricezione di messaggi dal server fallita. -21 Errore generico nella ricezione di messaggi dal server. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ricevuto dal server non è stato riconosciuto come proveniente dal programma server ICA_RTXT. -32 Errore generico verificatosi nel programma server ICA_RTXT relativamente al membro. -33 Errore generico verificatosi nel programma server ICA_RTXT nell'accesso alla coda dati. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICARO Guida Programmatore ICAWIN

210 Nome funzione: ICA_LDBA Descrizione La funzione ICA_LDBA accede in lettura alla lista delle banche dati ICARO disponibili sul server AS/400 per la sessione di lavoro IDArea. La modalità di accesso alla lista delle banche dati è indicata nel parametro *Modality nel modo sotto dettagliato. Il file DBList.ica è strutturato in modo tale che ogni record è separato dall'altro da un carattere di newline ("\n"). I record sono a loro volta suddivisi in campi la cui struttura è rappresentata nella seguente tabella: Posizione Descrizione 1-3 Codice banca dati 4-43 Nome della banca dati Numeri dei documenti della banca dati Flag di disponibilità per la banca dati: Y la banca dati non è disponibile poichè necessita di essere ricompilata a segiuto di una modifica della struttura; spazio la banca dati è disponibile Flag di necessità di ricostruzione degli indici: spazio non è necessaria alcuna attività di ricostruzione; P è necessaria una ricostruzione parziale degli indici; T è necessaria una ricostruzione totale degli indici : esistono note; : non esistono note. Sintassi C int ICA_LDBA(HWND hdlg, struct ICA_Env *E, char *Modality); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *Modality E la modalità di accesso richiesto. I valori permessi sono indicati nella seguente tabella. ICAWIN ICARO Guida Programmatore

211 Valore Descrizione 000 Interrogazione stampa documenti 001 Gestione documenti 002 Dizionario 003 Tabelle 004 Aggiornamento documenti 005 Ricostruzione indici 006 Pulizia area lavoro 007 Distruzione banca dati 008 Crea formati di output 009 Crea tipi di visualizzazione stampa 010 Gestione documenti (lista banca dati) 011 Interrogazione (lista banca dati) Non usati 999 Tutte Return code Il valore ritornato dalla funzione ICA_LDBA è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -10 Esecuzione del programma server ICA_LDBA fallita. -11 Errore generico nella esecuzione del programma server ICA_LDBA. Probabile errore nell'assegnazione della variabile globale c_type. -20 Ricezione di messaggi dal server AS/400 fallita. -21 Errore generico nella ricezione di messaggi dal server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ricevuto dal server non è stato riconosciuto come proveniente dal programma server ICA_LDBA. -33 Errore verificatosi nel programma server ICA_LDBA. La coda dati sul server AS/400 non è disponibile o il nome della libreria di lavoro è errata. -34 Errore verificatosi nel programma server ICA_LDBA. Non è stata eseguita la funzione di inizializzazione ICA_INIT. -35 Errore verificatosi nel programma server ICA_LDBA. L'utente non è autorizzato alla funzione richiesta nel parametro Modality. -36 Errore verificatosi nel programma server ICA_LDBA. Nessuna delle banche dati è autorizzata. -37 Errore verificatosi nel programma server ICA_LDBA. Riscontrato un vincolo di autorizzazione sul numero di banche dati presenti sul server AS/ Errore nella creazione del file DBList.ica. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICARO Guida Programmatore ICAWIN

212 Nome funzione: ICA_RtFdDB Descrizione La funzione ICA_RtFdDB accede, in lettura, ai campi ed ai paragrafi delle banche dati Icaro contenute nella struttura globale ICA_DBList per la sessione di lavoro IDArea. La lista dei campi/paragrafi per ogni singola banca dati selezionata viene memorizzata su di un file avente nome Struxxx.ica (dove xxx indica il codice della banca dati). Ogni record del file è separato dal successivo con un carattere di newline ('\n') ed avrà la seguente struttura: Posizione Descrizione 1-3 Codice banca dati 4-6 Codice campo/paragrafo 7-12 Codice abbreviato campo/paragrafo Tipo campo/paragrafo: 'N' Numerico 'A' Alfanumerico 'V' Variabile (paragrafo) 'B' BIDI (Arabo) Lunghezza campo (solo tipo campo/paragrafo V ) Descrizione campo/paragrafo Indicizzazione: '1' campo/paragrafo indicizzato '2' campo/paragr. non indicizzato Flag relativo alla possibilità di utilizzare il campo nella ricerca puntualizzata: '0' no '1' si Titolo del campo/paragrafo: '1' LTR '0' RTL (BIDI - Arabo) Inoltre, la funzione ICA_RtFdDB provvede a creare altri tre file aventi rispettivamente nome ShLOxxx.ica, SoLOxxx.ica e Doxxx.ica (dove xxx indica il codice della banca dati) e contenenti i campi/paragrafi utilizzati per la lista abbreviata, quelli da utilizzare per l ordinamento ed i campi/paragrafi da usare per la visualizzazione del documento. In tali file ogni record è costituito da tre byte che indicano il codice del campo/paragrafo da utilizzare rispettivamente per lista abbreviata, ordinamento e visualizzazione. Ogni record è separato dal successivo con un carattere di newline ('\n'). Tutti questi file vengono memorizzati nella directory di lavoro SessionPCDirectory. La funzione ICA_RtFdDB è progettata in modo da ottimizzare i tempi di risposta e la quantità di dati trasferiti sul supporto trasmissivo cercando, all'interno della directory di lavoro SessionPCDirectory, i file dati contenente le informazioni richieste ed eventualmente scaricate dal server in una richiesta precedente nell ambito della stessa sessione di lavoro. ICAWIN ICARO Guida Programmatore

213 Sintassi C int ICA_RtFdDB(HWND hdlg, struct ICA_Env *E, char Type, char Autorithy); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportunoconsultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *Type E il tipo di campi o paragrafi oggetto della ricerca. Il parametro vale:'c' per i campi formattati, 'P' per i paragrafi, 'B' per entrambi campi/paragrafi. char *Authority E il tipo di controllo di autorità richiesto. Il parametro vale:' ' tutti i campi/paragrafi senza controllo di autorità, 'I' campi/paragrafi autorizzati all'interrogazione, 'N' campi/paragrafi autorizzati in inserimento, 'R' campi/paragrafi autorizzati in revisione. Return code Il valore ritornato dalla funzione ICA_RtFdDB è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -1 Nessuna banca dati è contenuta nella struttura globale ICA_DBList. -10 Esecuzione del programma server ICA_RTFDDB fallita. -11 Errore generico nella esecuzione del programma server ICA_RTFDDB. Probabile errore nell'assegnazione della variabile globale c_type. -20 Errore nella ricezione di messaggi dal server AS/400 fallita. -21 Errore generico nella ricezione di messaggi dal server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. ICARO Guida Programmatore ICAWIN

214 -30 Il messaggio ricevuto dal server non è stato riconosciuto come proveniente dal programma server ICA_RTFDDB. -33 Errore verificatosi nel programma server ICA_RTFDDB. La coda dati sul server AS/400 non è disponibile o il nome della libreria di lavoro è errata o non è stata eseguita la funzione di inizializzazione ICA_INIT. -34 Errore verificatosi nel programma server ICA_RTFDDB. L'utente non è autorizzato. -35 Errore verificatosi nel programma server ICA_RTFDDB. Il codice della banca dati è errato. -36 Errore verificatosi nel programma server ICA_RTFDDB. La banca dati non esiste. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

215 Nome funzione: ICA_RtTbLT Descrizione La funzione ICA_RtTbLT ritorna la lista delle tabelle definite per le banche dati contenute nella struttura globale ICA_DBList per la sessione di lavoro IDArea. La lista delle tabelle per ogni singola banca dati selezionata viene memorizzata su di un file avente nome TblLxxx.Ica (dove xxx indica il codice della banca dati) contenuto nella directory di lavoro SessionPCDirectory. Ogni record del file è separato dal successivo con un caratteri di newline ('\n') ed avrà la seguente struttura: Posizione Descrizione 1-3 Codice banca dati 4-5 Nome tabella 6-11 Non usato Descrizione tabella La funzione ICA_RtTbLT ottimizza i tempi di risposta e la quantità di dati trasferiti sul supporto trasmissivo cercando, all'interno della directory di lavoro SessionPCDirectory, i file dati contenenti le informazioni richieste ed eventualmente scaricate dal server in una richiesta precedente nell ambito della stessa sessione di lavoro. Sintassi C int ICA_RtTbLT (HWND hdlg, struct ICA_Env *E, char Autorithy); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *Authority E il tipo di controllo di autorità richiesto. Il parametro vale: ' ' tutti i campi/paragrafi senza controllo di autorità, 'A' controlla i campi autorizzati. ICARO Guida Programmatore ICAWIN

216 Return code Il valore ritornato dalla funzione ICA_RtTbLT è dettagliato nella tabella seguente. Codice numerico Descrizione 0 Funzione eseguita con successo. -1 Non vi sono banche dati selezionate. -10 Esecuzione del programma server ICA_RTTBLT fallita. -11 Errore generico nella esecuzione del programma server ICA_RTTBLT. Probabile errore nell'assegnazione della variabile globale c_type. -20 Ricezione di messaggi dal server AS/400 fallita. -21 Errore generico nella ricezione di messaggi dal server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ricevuto dal server non è stato riconosciuto come proveniente dal programma server ICA_RTTBLT. -33 Errore verificatosi nel programma server ICA_RTTBLT. La coda dati sul server AS/400 non è disponibile o il nome della libreria di lavoro è errata o non è stata eseguita la funzione di inizializzazione ICA_INIT. -34 Errore verificatosi nel programma server ICA_RTTBLT. L'utente non è autorizzato. -35 Errore verificatosi nel programma server ICA_RTTBLT. Il codice della banca dati è errato. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

217 Nome funzione: ICA_RtTbLD Descrizione La funzione ICA_RtTbLD accede in lettura ai campi della tabella indicata nella variabile TableID per la banca dati di codice DBID dal server ASSystem per la sessione di lavoro associata a IDArea. La lista dei campi viene memorizzata su di un file avente nome TbRxxxyy.Ica (dove xxx indica il codice della banca dati e yy il codice della tabella) contenuto nella directory di lavoro SessionPCDirectory. Ogni record del file è separato dal successivo con un carattere di newline ('\n') ed avrà la seguente struttura: Posizione Descrizione 1-3 Codice banca dati 4-5 Nome tabella 6-11 Codice elemento Descrizione tabella La funzione ICA_RtFdDB ottimizza i tempi di risposta e la quantità di dati trasferiti sul supporto trasmissivo cercando, all'interno della directory di lavoro SessionPCDirectory, il file dati contenenti le informazioni richieste ed eventualmente scaricate dal server in una richiesta precedente. Sintassi C int ICA_RtTbLD (HWND hdlg, struct ICA_Env *E, char *DBID, char *TableID, char Autorithy); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *DBID E il codice della banca dati. char *TableID ICARO Guida Programmatore ICAWIN

218 E il codice della tabella. char *Authority E il tipo di controllo di autorità richiesto. Il parametro vale: ' ' tutti i campi senza controllo di autorità, 'A' controlla i campi autorizzati. Return code Il valore ritornato dalla funzione ICA_RtTbLD è dettagliato nella tabella seguente. Codice numerico Descrizione 0 Funzione eseguita con successo. -10 Esecuzione del programma server ICA_RTTBLD fallita. -11 Errore generico nella esecuzione del programma server ICA_RTTBLD. Probabile errore nell'assegnazione della variabile globale c_type. -20 Ricezione di messaggi dal server AS/400 fallita. -21 Errore generico nella ricezione di messaggi dal server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ricevuto dal server non è stato riconosciuto come proveniente dal programma server ICA_RTTBLD. -33 Errore verificatosi nel programma server ICA_RTTBLD. La coda dati sul server AS/400 non è disponibile o il nome della libreria di lavoro è errata o non è stata eseguita la funzione di inizializzazione ICA_INIT. -34 Errore verificatosi nel programma server ICA_RTTBLD. L'utente non è autorizzato. -35 Errore verificatosi nel programma server ICA_RTTBLD. Il codice della banca dati è errato. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

219 Nome funzione: ICA_RtvDiz Descrizione La funzione ICA_RtvDiz accede ai servizi di dizionario messi a disposizione da Icaro sul server ASSystem relativamente alla banca dati di codice DBID. Il comportamento della funzione ICA_RtvDiz dipende dal parametro op ed in funzione di questo ICA_RtvDiz esegue delle specifiche azioni. In particolare, se op vale 1 allora la funzione esegue, localmente senza accedere al server AS/400, un controllo sintattico del termine passato verificando che i simboli utilizzati per comporre il termine di ricerca siano corretti. Se op vale 2 viene effettuato il primo accesso al dizionario con la lettura del primo blocco di termini. In questo caso il flag status vale 1 se vi sono ancora termini da leggere altrimenti vale 0 se non ve ne sono altri. Se op vale 3 vengono effettuati gli accessi successivi al dizionario con la lettura dei blocchi di termini successivi. Anche in questo caso il flag status vale 1 se vi sono ancora termini da leggere altrimenti vale 0 se non ve ne sono altri. Se, infine, op vale 4 allora viene chiuso l'accesso al dizionario. Nella composizione del termine di ricerca è possibile utilizzare delle wildcard. In particolare il simbolo * indica un numero qualsiasi di caratteri mentre il simbolo? indica un solo carattere in analogia alle wildcard disponibili nei sistemi operativi per personal computer. L'output dei dati verrà memorizzato nel file Dizxxx.ica (dove xxx indica il codice della banca dati) contenuto nella directory SessionPCDirectory. Ogni record del file è separato dal successivo con un carattere di newline ('\n') ed avrà la seguente struttura: Posizione Descrizione 1 Non usato 2-41 Termine Tipo termine: 0 termine base LTR (normalizzato) 1 termine reale LTR 2 termine base BIDI (normalizzato) 3 termine reale BIDI Stop word: N il termine non è una stop word 2 il termine normalizzato è una stop word con i termini reali 1 il termine reale è una stop word Lista di autorità: N la parola non fa parte dell authority list 1 il termine reale è autorizzato in certi campi 2 il termine reale è autorizzato in certi campi paragrafo, anche i termini reali fanno parte dell authority list 3 il termine reale è in sostituzione di un altro termine 4 il termine reale è in sostituzione di un altro termine ICARO Guida Programmatore ICAWIN

220 44-44 Gestione: 0 il termine può essere cancellato dal dizionario se non ha ricorrenza nella banca dati, 1 il termine è permanente Numero totale di documenti in cui il termine è presente Numero totale di ricorrenze del termine. Sintassi C int ICA_RtvDiz (HWND hdlg, struct ICA_Env *E, char *DBID, char Modality, char *Term, int Service, int *status,int *Type); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char *DBID E il codice della banca dati. char *Modality Questo parametro indica la modalità di ricerca richiesta. Questo parametro può valere: '1' se si vuole ricercare il termine normalizzato; '2' se si vuole ricercare il termine in modalità reale. char *Term E il termine che si vuole ricercare nel dizionario. int Service E il tipo di operazione richiesta alla funzione. Questo parametro può valere: 1 - se si vuole effettuare un controllo sintattico sul termine da ricercare; 2 - Per effettuare l'apertura e la prima lettura di dati dal dizionario; 3 - Per effettuare le successive letture dal dizionario; 4 - per chiudere il dizionario. int *status E il flag di fine lettura. Esso vale: 1 - se vi sono altri record da leggere nel dizionario; 0 - se non vi sono più record da leggere nel dizionario. int *Type E un flag ritornato dalla funzione che identifica il tipo di termine. ICAWIN ICARO Guida Programmatore

221 Return code Il valore ritornato dalla funzione ICA_RtvDiz è dettagliato nella tabella seguente. Codice numerico Descrizione >0 Funzione eseguita con successo. Vi sono altri termini disponibili, in lettura, nel dizionario. Ritorna il numero di record letti. 0 Funzione eseguita con successo. Non vi sono più termini disponibili nel dizionario. -1 Errore di sintassi se il parametro op vale Errore nella apertura del file Diz%s.ica. -9 Errore generico nel parametro op. -10 Esecuzione del programma server ICA_RTVDIZ fallita. -11 Errore generico nella esecuzione del programma server ICA_RTVDIZ. Probabile errore nell'assegnazione della variabile globale c_type. -12 Errore nella pulizia della coda dati ICO_DTAQ. -20 Ricezione di messaggi dal server AS/400 fallita. -21 Errore generico nella ricezione di messaggi dal server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ritornato dalla coda dati non proviene dal programma server ICA_RTVDIZ. -33 Errore verificatosi nel programma server ICA_RTVDIZ. La coda dati sul server AS/400 non è disponibile o il nome della libreria di lavoro è errata o non è stata eseguita la funzione di inizializzazione ICA_INIT. -34 Errore verificatosi nel programma server ICA_RTVDIZ. L'utente non è autorizzato. -35 Errore verificatosi nel programma server ICA_RTVDIZ. Il codice della banca dati è errato. Informazioni di dettaglio sull'errore verificatosi sono contenute nella struttura dei messaggi c_msg. -36 Errore nell'esecuzione del programma server ICA_RTVDIZ. Codice tipo termine errato. -37 Errore nell'esecuzione del programma server ICA_RTVDIZ. Termine iniziale vuoto. -38 Errore nell'esecuzione del programma server ICA_RTVDIZ. Tipo ricerca errato. -39 Errore nell'esecuzione del programma server ICA_RTVDIZ. Sintassi wildcard errata. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICARO Guida Programmatore ICAWIN

222 Nome funzione: ICA_SndQry Descrizione La funzione ICA_SndQry sottomette al server AS/400 ASSystem una interrogazione (domanda) sulle banche dati selezionate nella struttura globale ICA_DBList per la sessione di lavoro associata ad IDArea. La domanda deve essere memorizzata all'interno del file CurQuery.ica contenuto nella directory SessionPCDirectory. Questo file contiene un solo record terminato dal carattere di newline ('\n') costituito dalla domanda da formulare. L'output della funzione è restituito nella variabile Result e consiste in un record terminato da un carattere nullo ('\0') la cui struttura è riportata nella seguente tabella: Posizione Descrizione 1-27 Codice Banca Dati Documenti trovato come risultato della domanda - 9 byte per ognuna delle nove banche dati permesse Ricorrenze - 9 byte per ognuna delle nove banche dati permesse Flag relativo alla notazione Europea o Araba - 1 byte per ognuna delle nove banche dati permesse: 1 LTR (europea) 2 RTL (BIDI - araba) Codice di formato per la visualizzazione di default del documento - 2 byte per ognuna delle nove banche dati permesse Flag di notazione della domanda: 1 LTR (europea) 2 RTL (BIDI - araba) Numero di livello della domanda In caso di errore o di warning nell'esecuzione del programma server ICA_INQCHK che effettua il controllo sintattico della domanda, la funzione ICA_SndQry provvede a generare un file contenente gli errori relativi alla domanda formulata. Tale file ha nome QryErr.ica ed è contenuto nella directory SessionPCDirectory. La sua struttura è costituita da tanti record quanti sono gli errori ritornati da ICA_INQCHK separati da un carattere di newline ('\n'). Sintassi C int ICA_SndQry (HWND hdlg, struct ICA_Env *E, char Type, char *Result); ICAWIN ICARO Guida Programmatore

223 Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char Type E il tipo di domanda. Questo parametro può valere: 1 - per una interrogazione LTR (Left To Right); 2 - per una interrogazione BIDI (BIDIrectional). char *Result E il risultato della ricerca. La struttura di questo record è stata definita nella descrizione precedente. Return code Il valore ritornato dalla funzione ICA_SndQry è dettagliato nella tabella seguente. Codice numerico Descrizione 1 Funzione eseguita con successo. Vi sono warning contenuti nel file QryErr.ica. 0 Funzione eseguita con successo. -1 Pulizia della coda dati ICO_DTAQ fallita. -2 Il file CurQuery.ica non è stato trovato nella directory SessionPCDirectory. -10 La spedizione del messaggio contenente la domanda al server AS/400 è fallita. -11 Errore generico nella spedizione del messaggi contenente la domanda al server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -20 Esecuzione del programma server ICA_SNDQRY fallita. -21 Errore generico nella esecuzione del programma server ICA_SNDQRY. Probabile errore nell'assegnazione della variabile globale c_type. -30 Ricezione di messaggi dal server AS/400 fallita durante la lettura del risultato della domanda. -31 Errore generico nella ricezione di messaggi dal server AS/400 durante la lettura del risultato della domanda. Probabile errore nell'assegnazione della variabile globale c_type. -41 Esecuzione del programma server ICA_SNDQRY fallita. Coda dati non disponibile, libreria di lavoro errata o mancata esecuzione di ICA_Init. ICARO Guida Programmatore ICAWIN

224 -42 Esecuzione del programma server ICA_SNDQRY fallita. Utente non autorizzato. -43 Esecuzione del programma server ICA_SNDQRY fallita. Non è stata formulata alcuna domanda. -44 Esecuzione del programma server ICA_SNDQRY fallita. Tipo domanda LTR/BIDI errata. -45 Esecuzione del programma server ICA_SNDQRY fallita. Errore nella chiamata al programma server ICA_INQCHK. -51 Esecuzione del programma server ICA_INQCHK fallita. Errore all avvio del programma server ICA_INQCHK. -52 Esecuzione del programma server ICA_INQCHK fallita. Errore di sintassi nella domanda. -53 Ricezione di messaggi dal server AS/400 fallita durante l'esecuzione del programma INQCHK. -54 Errore generico nella ricezione di messaggi dal server AS/400 durante l'esecuzione del programma INQCHK. Probabile errore nell'assegnazione della variabile globale c_type. -61 Errore durante l'esecuzione del programma server ICA_RTVRSL. Numero di domanda errata. -62 Errore durante l'esecuzione del programma server ICA_RTVRSL. Risultato non pronto. -71 Errore durante l'esecuzione del programma server ICA_INQSDB. Nessuna banca dati selezionata. -72 Errore durante l'esecuzione del programma server ICA_INQSDB. Utente non autorizzato o CRTAUTUSE non eseguito o superato limite utenti. -73 Errore durante l'esecuzione del programma server ICA_INQSDB. Prodotto non autorizzato o numero di banche dati richieste maggiore del limite previsto nella matricola di ICARO. -74 Errore durante l'esecuzione del programma server ICA_INQSDB. La banca dati non è in linea o non è autorizzata. -75 Errore durante l'esecuzione del programma server ICA_INQSDB. Libreria di lavoro vincolata. -79 Errore durante l'esecuzione del programma server ICA_INQSDB. Errore generico nel programma server ICA_INQSDB. -80 Errore generico nella funzione ICA_SndQry. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

225 Nome funzione: ICA_RtvOcc Descrizione La funzione ICA_RtvOcc ritorna le ricorrenze delle parole di una ricerca per le banche dati selezionate nella sessione di lavoro IDArea. L'output dei dati viene memorizzato nel file Occxxx.ica (dove xxx indica il codice della banca dati) contenuto nella directory SessionPCDirectory. La esecuzione di questa funzione è subordinata alla precedente esecuzione della funzione ICA_SndQry. Sintassi C int ICA_RtvOcc (HWND hdlg, struct ICA_Env *E, char *DBId); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env consultare il capitolo "La struttura dati ICA_Env" di questo manuale. char DBId E il codice della banca dati selezionata. Return code Il valore ritornato della funzione ICA_RtvOcc è dettagliato nella tabella seguente. Codice numerico Descrizione 0 Funzione eseguita con successo. -1 Pulizia della coda dati ICA_DTAQ fallita. -10 Esecuzione del programma server ICA_RTVOCC fallita. -11 Errore generico nella esecuzione del programma server ICA_RTVOCC. Probabile errore nell'assegnazione della variabile globale c_type. -20 Errore nella ricezione dei messaggi dalla coda dati AS/400. ICARO Guida Programmatore ICAWIN

226 -21 Errore generico nell'inizializzazione della sessione di lavoro ICARO. Probabile errore in c_type. -30 Il messaggio ritornato dalla coda dati non proviene dal programma server ICA_RTVOCC. -32 Coda dati non disponibile o libreria di lavoro errata o mancata esecuzione di ICA_Init. -33 Non esistono ricorrenze per precedenti errori di sintassi. -34 Superato limite dei termini autorizzati per l'utente. -51 Errore nella creazione del file Occxxx.ica. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

227 Nome funzione: ICA_DSPLI Descrizione La funzione ICA_DSPLI accede in lettura alla lista abbreviata dei documenti trovati come risultato di una ricerca effettuata sul server ASSystem durante la sessione di lavoro IDArea. Il comportamento della funzione ICA_DSPLI dipende dal parametro Service. In particolare: Service=1: la funzione esegue il primo accesso alla lista abbreviata disponibile sul server AS/400 estraendo il primo blocco di documenti trovati indicato dai parametri From e To; Service=2: vengono effettuati gli accessi successivi alla lista abbreviata con la lettura dei documenti successivi compresi fra ShL.From e ShL.To; Service=3: viene chiuso l'accesso alla lista abbreviata. L'output viene memorizzato nel file il cui puntatore è contenuto nella variabile *p. Ogni record del file è separato dal successivo con un carattere di newline ('\n') ed ha la seguente struttura: Posizione Descrizione 1-7 Riferimento CED del documento 8-75 Campi paragrafi da utilizzare per la lista abbreviata Numero relativo del documento La funzione ICA_DSPLI è subordinata all'esecuzione di una chiamata avvenuta con successo alla funzione ICA_SndQry per l'esecuzione della domanda e la preparazione, sul server, del risultato della stessa. Sintassi C int ICA_DSPLI(HWND hdlg,int Service,struct ICA_Env *E, struct ShortList *ShL,char Exec,FILE *p) Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. int Service Indica il tipo di operazione richiesta alla funzione ICA_DSPLI. Per ulteriori dettagli si rinvia alla precedente descrizione. struct ICA_Env *E ICARO Guida Programmatore ICAWIN

228 E Struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro la si ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env consultare il capitolo "La struttura dati ICA_Env" di questo manuale. struct ShortList *ShL E la struttura di tipo ShortList contenente le informazioni relative alla lista abbreviata per la sessione di lavoro di ICAWin. La struttura ShortList di definizione della lista abbreviata è costituita come segue: struct ShortList { char DBID[4]; // Codice della banca dati. (*) char Level[8]; // Livello della domanda. (*) char TotDoc[10]; // Totale documenti. (*) long From; // Documento di partenza. (*) long To; // Documento di arrivo. (*) char Format[3]; // Formato di visualizzazione. (*) char Modality; // Modalità LTR o BIDI. (*) char Sort; // Tipo di sort. (*) char Mm; // Differenza maiuscolo/minuscolo nel sort. (*) char ShListOption[25]; // Campi/paragrafi per lista/ordinamento. (*) char NavigationName[16]; // Titolo della navigazione. (+) }; Di questa struttura devono essere valorizzati, da parte del programma applicativo, le variabili contrassegnate da un simbolo (*) mentre verranno ritornate valorizzate dalla funzione ICA_DSPLI le variabili contrassegnate dal simbolo (+). char Exec Rappresenta la modalità di esecuzione del programma server. Il parametro vale: '1' per una esecuzione in modalità interattiva, '2' per una modalità in esecuzione batch. FILE *p E un puntatore al file che contiene I record relativi alla lista abbreviata ritornati dal server AS/400. Return code Il valore ritornato dalla funzione ICA_DSPLI è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -1 Pulizia della coda dati ICO_DTAQ fallita. -2 Creazione del file Lxxxxxx.ica in SessionPCDirectory fallita. -10 La spedizione del messaggio contenente la richiesta al server AS/400 è fallita. -11 Errore generico nella spedizione del messaggi contenente la richiesta al server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. ICAWIN ICARO Guida Programmatore

229 -20 Esecuzione del programma server ICA_DSPLI fallita. -21 Errore generico nella esecuzione del programma server ICA_DSPLI. Probabile errore nell'assegnazione della variabile globale c_type. -22 Ricezione di messaggi dal server AS/400 fallita durante la lettura del risultato della domanda. -23 Errore generico nella ricezione di messaggi dal server AS/400 durante la lettura del risultato della domanda. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ritornato dalla coda dati non proviene dal programma server ICA_DSPLI. -32 Coda dati non disponibile o libreria di lavoro errata o mancata esecuzione di ICA_Init. -33 Domanda non pronta o numero di domanda errato. -34 Utente non autorizzato. -35 Parametri errati nella coda dati ICO_DTAQ. -36 Il totale dei documenti è zero. -37 Il programma server è andato in time out. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICARO Guida Programmatore ICAWIN

230 Nome funzione: ICA_DSPDO Descrizione La funzione ICA_DSPDO accede, in lettura, ai documenti risultato di una ricerca sul server AS/400. Il comportamento della funzione ICA_DSPDO dipende dal parametro Service. In particolare: Service=1: la funzione esegue il primo accesso ai documenti disponibili sul server AS/400 estraendo il primo blocco di documenti trovati indicato dai parametri From e To; Service=2: vengono effettuati gli accessi successivi ai documenti con la lettura dei documenti successivi compresi fra From e To; Service=3: viene chiuso l'accesso ai documenti. L'output verrà memorizzato nel file il cui puntatore è contenuto nella variabile *p. Ogni record del file è separato dal successivo con un carattere di newline ('\n') ed ha la seguente struttura: Posizione Descrizione 1-3 Codice del campo/paragrafo 4-84 Dati La esecuzione di questa funzione è subordinata alla precedente esecuzione della funzione ICA_SndQry. Sintassi C int ICA_DSPDO(HWND hdlg,int Service,struct ICA_Env *E, struct Document *Doc,char Exec,FILE *p) Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. int Service Indica il tipo di operazione richiesta alla funzione ICA_DSPDO. Per ulteriori dettagli vedi la precedente descrizione. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. ICAWIN ICARO Guida Programmatore

231 Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. struct Document *Doc E la struttura di tipo Document contenente le informazioni relative ai documenti per la sessione di lavoro di ICAWin. La struttura Document di definizione dei documenti è costituita come segue: struct Document { char DBID[4]; // Codice della banca dati Icaro. (*) char Level[8]; // Livello della domanda. (*) char TotDoc[10]; // Totale documenti. (*) int From; // Documento di partenza. (*) int To; // Documento di arrivo. (*) int FldParPos; // Campo/paragrafo di partenza. (*) int RowPos; // Riga di partenza nell'ambito del (*) campo/paragrafo precedente. int Offset; // Numero di righe da leggere. (*) char RifCED[8]; // Riferimento CED. (+) char Format[3]; // Formato di visualizzazione. (*) char Modality; // Modalità LTR o BIDI. (*) char Sort; // Tipo di sort. (*) char Mm; // Differenza maiuscolo/minuscolo. (*) char DocOption[1550]; // Campi/paragrafi per (*) visualizzazione/ordinamento. char Paragraph[4]; // Ultimo paragrafo letto. (+) int Row; // Ultima riga letta. (+) char NavigationName[16]; // Titolo della navigazione. (+) }; Di questa struttura devono essere valorizzati, da parte del programma applicativo, le variabili contrassegnate da un simbolo (*); mentre vengono ritornate valorizzate dalla funzione ICA_DSPDO le variabili contrassegnate dal simbolo (+). char Exec Rappresenta la modalità di esecuzione del programma server. Il parametro vale: '1' per una esecuzione in modalità interattiva, '2' per una modalità in esecuzione batch. FILE *p E un puntatore al file che contiene I record relativi alla lista abbreviata ritornati dal server AS/400. Return code Il valore ritornato dalla funzione ICA_DSPDO è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -1 Pulizia della coda dati ICD_DTAQ fallita. -2 Creazione del file Doc.ica in SessionPCDirectory fallita. ICARO Guida Programmatore ICAWIN

232 -10 La spedizione del messaggio contenente la domanda al server AS/400 è fallita. -11 Errore generico nella spedizione del messaggi contenente la domanda al server AS/400. Probabile errore nell'assegnazione della variabile globale c_type. -12 Pulizia della coda dati ICE_DTAQ fallita. -20 Esecuzione del programma server ICA_DSPDO fallita. -21 Errore generico nella esecuzione del programma server ICA_DSPDO. Probabile errore nell'assegnazione della variabile globale c_type. -22 Ricezione di messaggi dal server AS/400 fallita durante la lettura del documento. -23 Errore generico nella ricezione di messaggi dal server AS/400 durante la lettura del documento. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ritornato dalla coda dati non proviene dal programma server ICA_DSPDO. -32 Coda dati non disponibile o libreria di lavoro errata o mancata esecuzione di ICA_Init. -33 Domanda non pronta o numero di domanda errato. -34 Utente non autorizzato. -35 Parametri errati nella coda dati ICD_DTAQ. -36 Il totale dei documenti è zero. -37 Il programma server è andato in errore. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

233 Nome funzione: ICA_RtvNav Descrizione La funzione ICA_RtvNav accede alle opzioni di navigazione definite per una banca dati. Per ognuna delle opzioni di navigazione viene fornito un record contenente un testo descrittivo dell opzione di navigazione e, se l opzione permette ulteriori passi di navigazione, il comando (server o client) da mandare in esecuzione per generare il nuovo passo di navigazione. La chiamata alla funzione ICA_RtvNav ritorna un file avente nome NavList.xxx (con xxx indicante il livello di navigazione) contenente tanti record quante sono le opzioni di navigazione ogni record separato dai successivi da un carattere di newline ( \n ). La struttura del record è la seguente: Posizione Descrizione 1-2 Non usati 3-3 Tipo: A - query B mappa video 4-4 Tipo di opzione di navigazione: C non selezionabile; S selezionabile. 5-8 Riga dell opzione di navigazione Attributi di visualizzazione Testo dell opzione di navigazione Ubicazione del programma: H Server, C client Nome del comando AS/400 (libreria e programma separati da /) Comando PC (nome del programma seguito dai parametri) da eseguire o parametri del comando AS/400 se l opzione di navigazione è selezionabile. Nel caso di comando client ( C ) a partire dalla posizione 116 si trova il comando da eseguire sul personal computer; invece, nel caso di comando host ( H ), a partire dalla posizione 95 si troverà il comando host da eseguire sul server AS/400, mentre a partire da posizione 116 si trovano I parametri eventuali da passare al comando host. Sintassi C int ICA_RtvNav(HWND hdlg,struct ICA_Env *E,int *Type,char *Program, char *DBId,char *Level,char *RifCED) Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E ICARO Guida Programmatore ICAWIN

234 E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. int *Type E il valore ritornato da ICA_RtvNav in funzione del tipo di navigazione determinata sull'as/400. char *Program E l eventuale programma AS/400 de eseguire per i livelli di navigazione superiori al primo. char *DBId Rappresenta il codice della banca dati per la quale effettuare la navigazione. char *Level E il livello della interrogazione. char *RifCED E il riferimento CED. Return code Il valore ritornato dalla funzione ICA_End è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -1 Fallita la pulizia della coda dati ICA_DTAQ. -10 Esecuzione del programma server fallita. -11 Errore generico nella esecuzione del programma server. -20 Ricezione dei messaggi dal server fallita. -21 Errore generico nella ricezione dei messaggi dal server. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ritornato dalla coda dati non proviene dal programma server. -32 Non esiste la query. -33 Non esiste il programma di exit. -40 Errore nella gestione del file NavList.xxx. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

235 Nome funzione: ICA_Call Descrizione La funzione ICA_Call fornisce i servizi di ricezione dati dall'as/400 per i programmi ed I menu di personalizzazione nella selezione delle banche dati e nella formulazione della domanda. Per ognuna delle opzioni viene fornito un record contenente un testo descrittivo dell opzione e, se l opzione permette ulteriori passi di menu, il comando (server o client) da mandare in esecuzione per generare il nuovo passo. La chiamata alla funzione ICA_Call ritorna un file avente nome IcaInit.xxx (con xxx indicante il livello di menu) contenente tanti record quante sono le opzioni ogni record separato dai successivi da un carattere di newline ( \n ). La struttura del record è la seguente: Posizione Descrizione 1-2 Non usati 3-3 Tipo: A - query B mappa video 4-4 Tipo di opzione di navigazione: C non selezionabile; S selezionabile. 5-8 Riga dell opzione Attributi di visualizzazione Testo dell opzione Tipo di comando: L lista abbreviata; E editazione della query; H comando host Nome del comando AS/400 (libreria e programma separati da /) Comando PC (nome del programma seguito dai parametri) da eseguire o parametri del comando AS/400 se l opzione di navigazione è selezionabile. Sintassi C int ICA_Call(HWND hdlg,struct ICA_Env *E,int *Type,char *Program, char *FileName) Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. ICARO Guida Programmatore ICAWIN

236 int *Type E il valore ritornato da ICA_Call in funzione del tipo di procedura iniziale determinato sull'as/400. char *Program E l eventuale programma AS/400 de eseguire per i livelli superiori al primo. char *FileName E il nome del file dati in cui memorizzare i messaggi ricevuti dal server. Return code Il valore ritornato dalla funzione ICA_End è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La funzione è stata eseguita con successo. -1 Fallita la pulizia della coda dati ICA_DTAQ. -10 Esecuzione del programma server fallita. -11 Errore generico nella esecuzione del programma server. -20 Ricezione dei messaggi dal server fallita. -21 Errore generico nella ricezione dei messaggi dal server. Probabile errore nell'assegnazione della variabile globale c_type. -30 Il messaggio ritornato dalla coda dati non proviene dal programma server. -33 Non esiste il programma di menu iniziale. -40 Errore nella gestione del file FileName. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

237 Nome funzione: ICA_End Descrizione La funzione ICA_End termina una sessione di colloquio applicativo con ICARO. Come conseguenza della chiamata alla funzione ICA_End viene cancellata la libreria IDArea creata sul server dalla funzione ICA_Init e sono memorizzate nel file del giornale generale delle interrogazioni le eventuali query effettuate dall'utente durante la sessione di lavoro. Sul client viene cancellata la directory relativa alla sessione di lavoro ICARO contenente tutti i file temporanei creati durante la sessione di lavoro. Sintassi C int ICA_End (HWND hdlg, struct ICA_Env *E); Descrizione dei parametri HWND hdlg E il puntatore alla finestra Windows. struct ICA_Env *E E la struttura di tipo ICA_Env contenente le informazioni relative alla sessione di lavoro di ICAWin. Per ulteriori dettagli sulla struttura dati ICA_Env è opportuno consultare il capitolo "La struttura dati ICA_Env" di questo manuale. Return code Il valore ritornato dalla funzione ICA_End è dettagliato nella tabella seguente. Codice numerico Descrizione 0 La sessione di lavoro è stata terminata con successo. -10 Esecuzione del programma server INQDLTSP fallita. -11 Errore generico nella esecuzione del programma server INQDLTSP. -20 Chiusura della sessione di lavoro con il server fallita. -21 Errore generico nella chiusura della sessione di lavoro. Probabile errore nell'assegnazione della variabile globale c_type. -30 Chiusura della sessione di comunicazione con il server fallita. -31 Errore generico nella chiusura della sessione di comunicazione. Probabile errore nell'assegnazione della variabile globale c_type. ICARO Guida Programmatore ICAWIN

238 -40 Errore nella rimozione della directory di lavoro sul client. La struttura dei messaggi c_msg, nel caso di connessione SNA, contiene gli eventuali messaggi relativi all'errore. ICAWIN ICARO Guida Programmatore

239 L interfaccia di accesso a programmi esterni IcaroPC mette a disposizione una serie di interfacce di accesso a programmi esterni che permettono delle personalizzazioni delle funzioni di inizializzazione, selezione banche dati e formulazione della query alternative a quelle standard di IcaroPC. Queste funzioni di personalizzazione possono essere pilotate dal server AS/400 (si veda a questo proposito per ulteriori dettagli il manuale "ICARO: Guida per il programmatore") oppure da procedure mandate in esecuzione sul client. Di seguito viene descritta la modalità di aggancio dei programmi esterni eseguiti sul client. La prima interfaccia verso programmi esterni è fornita al momento del logon. Il server AS/400 provvede a ritornare, opportunamente valorizzato, il flag InitProcType contenuto nella struttura dati ICA_Env. In funzione del valore di tale flag vengono intraprese le opportune azioni indicate nel seguente schema. Effettua il Logon al server AS/400 Se InitProcType vale H Attiva le opzioni di personalizzazione definite sul server Se InitProcType vale C Manda in esecuzione il programma MExtInq.exe Se InitProcType vale S Attiva le opzioni standard successive al Logon IcaroPC manda in esecuzione il programma MExtInq.exe e resta in attesa che questo completi la propria elaborazione creando in SessionPCDirectory il file-flag vuoto avente nome FI_OK.ica oppure FI_CANC.ica. Il primo file-flag indica ad IcaroPC di proseguire l elaborazione con la modalità sotto indicata mentre il secondo file-flag forza IcaroPC ad effettuare un logoff dalla sessione aperta sul server AS/400. Prima di segnalare la fine della sua elaborazione tramite i file-flag sopra descritti il programma MExtInq.exe deve creare il file IEnv.ica in SessionPCDirectory. Questo file deve essere costituito da un record indicante il numero di banche dati selezionate nella procedura MExtInq.exe e da tanti record successivi al primo contenenti ognuno alternativamente il codice di una banca dati e la sua descrizione. Un ulteriore record deve contenere un flag il cui valore deve essere Q se si vuole che IcaroPC prosegua la propria elaborazione, inviando la finestra di dialogo tramite la quale immettere la query per le banche dati selezionate; oppure G se si vuole andare direttamente alla esecuzione della domanda sul server AS/400. In questo caso il programma MExtInq.exe ICARO Guida Programmatore ICAWIN

240 deve avere creato anche il file contenente la domanda CurQuery.ica ed eventualmente aggiornato il file SesQuery.ica. L ultimo record, infine, deve contenere il tipo di query eventualmente da effettuare. Questo valore deve essere 1 per query di tipo LTR o 2 per query di tipo arabo. La seconda interfaccia verso programmi esterni è fornita al momento della selezione delle banche dati sulle quali operare le domande. Anche in questo caso il server AS/400 provvede a ritornare, opportunamente valorizzato, il flag DBSelProcType contenuto nella struttura dati ICA_Env. In funzione del valore di tale flag vengono intraprese le opportune azioni indicate nel seguente schema. Analizza la richiesta di selezione delle banche dati Se DBSelProcType vale C Manda in esecuzione il programma LExtInq.exe Se DBSelProcType vale S Attiva le opzioni standard di selezione banche dati IcaroPC manda in esecuzione il programma LExtInq.exe e resta in attesa che questo completi la propria elaborazione, creando in SessionPCDirectory il file-flag vuoto avente nome FDB_OK.ica oppure FDB_CANC.ica. Prima di eseguire LExtInq.exe deve essere creato il file DBEnv.ica contenuto in SessionPCDirectory e contenente un record indicante il numero di banche dati selezionate nella procedura QExtInq.exe e tanti record successivi al primo e contenenti ognuno alternativamente il codice di una banca dati e la sua descrizione. Prima di segnalare la fine della sua elaborazione tramite I file-flag sopra descritti il programma LExtInq.exe deve aggiornare il file DBEnv.ica in SessionPCDirectory mantenendone la struttura sopra descritta. La terza interfaccia verso programmi esterni è fornita al momento della formulazione di una query sulle banche dati selezionate. Anche in questo caso il server AS/400 provvede a ritornare, opportunamente valorizzato, il flag QueryProcType contenuto nella struttura dati ICA_Env. In funzione del valore di tale flag vengono intraprese le opportune azioni indicate nel seguente schema. ICAWIN ICARO Guida Programmatore

241 Analizza la richiesta di formulazione delle query Se QueryProcType vale C Manda in esecuzione il programma QExtInq.exe Se QueryProcType vale S Attiva le opzioni standard di selezione banche dati IcaroPC manda in esecuzione il programma QExtInq.exe e resta in attesa che questo completi la propria elaborazione, creando in SessionPCDirectory il file-flag vuoto avente nome FQ_OK.ica oppure FQ_CANC.ica. Prima di eseguire QExtInq.exe deve essere creato il file QEnv.ica contenuto in SessionPCDirectory e contenente un record indicante il numero di banche dati selezionate nella procedura QExtInq.exe e tanti record successivi al primo e contenenti ognuno alternativamente il codice di una banca dati e la sua descrizione. Prima di segnalare la fine della sua elaborazione tramite I file-flag sopra descritti il programma QExtInq.exe deve aggiornare il file QEnv.ica in SessionPCDirectory mantenendone la struttura sopra descritta e deve inoltre creare il file contenente la domanda CurQuery.ica ed eventualmente aggiornato il file SesQuery.ica. ICARO Guida Programmatore ICAWIN

242 Pagina vuota ICAWIN ICARO Guida Programmatore

243 Informazioni sui moduli IcaNet e IcaBWS In questo manuale vengono illustrate le caratteristiche dei prodotti IcaNet e IcaBWS dal punto di vista dei programmatori e dei sistemisti. L interfaccia IcaNet è un gestore di richieste di accesso alle banche dati Icaro che opera accettando richieste Icaro formulate da form HTML tramite l interfaccia CGI (Common Gateway Interface), sottoponendo tali richieste al servente di sessione IcaBWS e convertendo le risposte ritornate da questo in pagine HTML. Il modulo software IcaBWS, invece, costituisce un servente di richieste batch che opera tramite una tecnica di trasmissione di messaggi indirizzati alle singole funzioni Icaro. IcaBWS è in grado di assicurare la congruità della sessione di lavoro Icaro durante le varie fasi di accesso ai database Icaro. IcaBWS è stato utilizzato per realizzare l interfaccia di IcaNet verso Icaro e si basa a sua volta sulla libreria di funzioni IcaCli v1.1. Le funzioni presenti in questa libreria sono descritte nel manuale IcaWin: Guida per il programmatore (IcaWin è il nome della libreria utilizzata nella interfaccia grafica IcaroPC e si differenzia dalla libreria IcaCli perché quest ultima utilizza, come protocollo di rete, solo il TCP/IP e non usa anche l APPC. L uso di IcaNet, IcaBWS e IcaCli consente quindi di realizzare un gateway HTML di accesso ai database Icaro che opera come server per le richieste HTTP provenienti dai web browser operanti in rete internet/intranet e come client per le richieste inoltrate verso le componenti server di Icaro attive sul server IBM AS/400. I moduli coinvolti in questo processo sono schematizzati nel seguente disegno. Client Server NT verso la rete Internet/Intranet AS/400 Web Browser Web Server IcaNet IcaBWS Icaro In particolare, le versioni 1.1 di IcaNet e di IcaBWS si basano sugli ambienti di seguito descritti: - L'ambiente server è costituito da un sistema IBM AS/400 con installato: il sistema operativo IBM OS/400 ver 3.1 o successivi; il protocollo TCP/IP (fornito con il sistema operativo IBM OS/400 ver 3.1 o successivi); il prodotto di Information Retrival ICARO ver 3.3; la componente server di IcaCli (libreria ICA$API fornita unitamente al prodotto ICARO). ICARO Guida Programmatore 17-1 ICANet

244 - L'ambiente gateway (servente delle richieste HTML e gestore della sessione di lavoro Icaro) è costituito da un sistema personal computer o mini computer con installato: l'ambiente operativo Microsoft Windows NT; configurato in modo che sia definito l ambiente Internet Information Server (il Web Server Microsoft) ed il protocollo TCP/IP per l accesso al server IBM AS/400; il prodotto IcaNet v1.1 di interfaccia verso le richieste HTML; il prodotto IcaBWS v1.1 di gestione delle sessioni di lavoro Icaro; il prodotto IcaCli v1.1 di accesso alle risorse Icaro. Tale modulo software è descritto in dettaglio nel manuale "IcaWin: Guida per il programmatore ; L ambiente client è costituito da un qualsiasi sistema che utilizzi un web browser basato sul protocollo HTML v3.0. Le funzioni di Icaro accedute da IcaNet/IcaBWS riguardano le seguenti aree: accesso, in lettura, alla lista delle banche dati ed alle note ad esse relative; esecuzione di una ricerca relativamente ad un massimo di nove banche dati; accesso, in lettura, alla lista delle ricorrenze relative ad una domanda; accesso, in lettura, alla lista abbreviata relativa ad una domanda; accesso, in lettura, ai documenti risultato di una ricerca; esecuzione delle funzioni di navigazione fra documenti e banche dati. ICANET 17-2 ICARO Guida Programmatore

245 Descrizione dell ambiente IcaNet L ambiente IcaNet è costituito da una serie di programmi realizzati in linguaggio C++ (è stato utilizzato il compilatore Microsoft Visual C++ v4.1 a 32 bit ed il sistema operativo Microsoft Windows NT) che utilizzano l interfaccia CGI (Common Gateway Interface) e sono compilati in modalità di applicazione console per permettere di realizzare un dialogo fra delle pagine HTML e il servente delle richieste batch di Icaro IcaBWS. L elenco dei programmi che costituisce l ambiente IcaNet v1.1 è riportato di seguito. INLogon.exe; INIProc.exe; INLMsg.exe; INSelDB.exe; INNote.exe; INQuery.exe; INOcc.exe; INOption.exe; INQryRes.exe. Ognuno di questi programmi viene mandato in esecuzione da una apposita form Inserita nella pagina HTML. Le pagine HTML fornite con IcaNet sono elencate di seguito (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo): INLogonx.htm; InitProc.htx; LMessage.htx; DBList.htx; DBNote.htx; Query.htx; Result.htx; Occur.htx; Option.htx; ShList.htx; Document.htx; NavMap.htx; NavRPMap.htx. Tranne la pagina di logon (INLogonx.htm) tutte le altre pagine HTML vengono realizzate dai programmi di IcaNet fondendo lo scheletro di una pagina HTML statica presente all interno della directory in cui è installato il prodotto con i dati ritornati da IcaBWS. Lo schema seguente illustra questo meccanismo di creazione della pagina HTML visualizzata sul web browser. ICARO Guida Programmatore 17-3 ICANet

246 IcaBWS Pagina HTML statica Dati Icaro Componente di IcaNet Pagina HTML restituita al web browser I programmi che costituiscono l interfaccia IcaNet tra il web server e IcaBWS vengono forniti in sorgente per poter essere modificati o per fornire delle basi da utilizzare per sviluppare proprie versioni personalizzate delle modalità di accesso alle banche dati. Le possibilità di personalizzazione messe a disposizione da IcaNet si sommano a quelle permesse dall interfaccia IcaroPC e vengono riassunte di seguito: possibilità di modificare i programmi che costituiscono IcaNet; possibilità di realizzare procedure personalizzate che guidano l utente attraverso dei menu predefiniti da programmi attivi o sul server AS/400 o sul server NT. Nel seguito verrà fornita una descrizione dei programmi di IcaNet, delle pagine HTML che li mandano in esecuzione e dei vincoli posti alla modifica di tali pagine. Il seguente schema illustra il flusso di pagine HTML e di programmi eseguiti da IcaNet per lo svolgimento delle varie funzioni necessarie alla ricerca ed alla visualizzazione dei documenti Icaro. In tale schema: ICANET 17-4 ICARO Guida Programmatore

247 INLogon questo simbolo indica una pagina HTML; INLogon.exe questo simbolo indica un programma di IcaNet mandato in esecuzione da una FORM contenuta in una pagina HTML e che genera, in risposta, una nuova pagina HTML; questo simbolo indica il flusso dell applicazione. ICARO Guida Programmatore 17-5 ICANet

248 INLogon INLogon.exe LMessage InitProc INLMsg.exe INNote.exe DBList INIProc.exe DBNote INSelDB.exe Query INQuery.exe INOption.exe INOcc.exe Result Option Occur INQryRes.exe NavMap NavRPMap ShList Document ICANET 17-6

249 Le variabili di inizializzazione di IcaNet11 ed il file dei messaggi IcaNet11.str IcaNet utilizza una serie di variabili di inizializzazione. Tali variabili vengono registrate nel registry del sistema NT e sono costituite da una serie di informazioni relative alla directory utilizzate da IcaNet, al server AS/400, etc. Tali variabili sono organizzate secondo la seguente struttura gerarchica: HKEY_LOCAL_MACHINE SOFTWARE Icaro General RootDirectory CommType Debug ASSystem TCPPort TimerInterval WaitTime IcaBWS11 Account IcaNet11 HomePage IcaNEtActive TimeOut NavReturnMode Il loro significato è indicato di seguito: RootDirectory: è il path della directory di installazione di Icaro (per default vale C:\Icaro); CommType: è il tipo di protocollo di comunicazione utilizzato verso il server AS/400 (il suo valore fisso è 2); Debug: indica se attivare (utilizzare il valore 1) o disattivare (utilizzare il valore 0) le funzioni di debug interne di Icaro (per default vale 0); ASSystem: è l indirizzo IP del server AS/400; TCPPort: è il valore della porta TCP sulla quale è in ascolto il processo servente di Icaro (per default vale 1246); TimerInterval: è il timer utilizzato dal servente IcaBWS per determinare se dai moduli di IcaNet è giunta una richiesta da inoltrare al server AS/400; WaitTime: è il time out utilizzato dalle funzioni di comunicazione per decidere che il server AS/400 non è più in ascolto. Account: è un flag, che può assumere il valore di 1 o 0, e che indica se il sistema di account è o meno attivo (per default vale 0); HomePage: è l URL della pagina alla quale ritornare in caso di selezione del pulsante di ritorno alla home page; ICARO Guida Programmatore 17-7 IcaNET

250 IcaNetActive: è un flag, che può assumere il valore di 1 o 0, e che indica se IcaNet è disponibile ad accettare richieste di connessione o meno (per default vale 0); TimeOut: è il time out utilizzato dai programmi di IcaNet per terminare la fase di attesa di una risposta dal server AS/400; NavReturnMode: è un flag che se vale 1 abilita il ritorno dalla navigazione attraverso il menu di selezione del punto di rientro mentre se vale 0 disabilita questo menu in modo tale che ad ogni richiesta di ritorno si vada direttamente al passo di navigazione precedente. Il valore di default è 1. Il file dei messaggi IcaNet11.str è costituita dalla sezione Message che contiene i messaggi utilizzati nella costruzione delle pagine HTML nelle sette lingue previste per IcaNet. Di seguito si analizzano i record contenuti nella sezione Message e si discutono i valori ad essi assegnati. Sezione: Message Error: titolo generico da utilizzare in caso di errore; NoActive: messaggio utilizzato dal modulo IcaLogon per informare l utente che il servizio di accesso ai dati Icaro è temporaneamente disattivato (si verifica quando il record IcaNetActive è settato a 1); TimeOut: questo messaggio viene restituito dai moduli di IcaNet quando è stato superato uno dei time out contenuti nel file IcaNet11.ini senza che sia pervenuta alcuna richiesta dal server Icaro; ConnectionRefused: la connessione ad Icaro è stata respinta dal server AS/400 per l'utente che ha tentato il logon; NoUserName: messaggio inviato quando non è stato digitato il nome utente nella mappa di connessione; NoPassword: messaggio inviato quando non è stata digitata la password nella mappa di connessione; ConnectionFailed: messaggio utilizzato quando la connessione al server Icaro è fallita; ErrorOnWebCreation: messaggio generico utilizzato quando si è verificato un errore nella creazione della pagina web; NoDBSelected: messaggio inviato quando non è stata selezionata nessuna banca dati. NoWorkDirSelected: messaggio inviato quando la directory di lavoro non è stata definita. NoQueryInsert: messaggio inviato quando non è stata digitata alcuna query. TimeOut: questo messaggio viene inviato quando il servente IcaBWS ha terminato, per supero tempo, la propria sessione di lavoro e pertanto è necessario rieseguire la connessione. InitReturn: testo associato al pulsante di ritorno alla pagina precedente; NoSelect: selezione non effettuata; OccurrenceList: testo associato al pulsante di visualizzazione della lista delle ricorrenze; PrevDocument: testo associato al pulsante di ritorno al documento precedente; NextDocument: testo associato al pulsante di avanzamento al documento successivo; GoDocument: testo associato alla stringa di salto ad un documento; GoToDocument: testo associato al pulsante di salto ad un documento; ReturnShL: testo associato al pulsante di lista abbreviata; ReturnGes: testo associato al pulsante di ritorno alla pagina di gestione del risultato; ICANET 17-8 Guida Programmatore

251 ReturnInitProc: testo associato al pulsante di ritorno alla pagina iniziale precedente; NavigationReturn: testo associato al pulsante di ritorno alla pagina precedente della navigazione; NextShortList: testo associato al pulsante di visualizzazione della successiva pagina della lista abbreviata; PreviuosShortList: testo associato al pulsante di visualizzazione della precedente pagina della lista abbreviata; DspDoc: testo associato alla stringa di richiesta di visualizzazione del documento; DisplayDocument: testo associato al pulsante di visualizzazione del documento; Navigation: testo associato al pulsante di navigazione. ICARO Guida Programmatore 17-9 IcaNET

252 Il file di accounting Account.ica Se al flag Account: contenuto nel registry di NT è assegnato il valore 1 allora è attivo il sistema di account di IcaNet. Questo sistema genera, per ogni sessione di lavoro aperta da un utente una registrazione all interno del file Account.ica. Tale registrazione contiene i seguenti record: Record Descrizione Record di separazione della registrazione dalla precedente UserName=ANONYMOUS Nome dell utente che ha aperto la sessione di lavoro SourceIPAddress= Non attivo StartDate=Thu 13 Feb 1997 Data di inizio della sessione di lavoro StartTime=15:29:42 Ora di inizio della sessione di lavoro QueryNumber=2 Numero di query eseguite TotalDocumentFound=53 Numero totale di documenti trovati DBCounter=1 Numero di banche dati consultate DBId 201 -TotalDocumentView =1 Codice della banca dati e numero di documenti visualizzati (un record per ogni banca dati) TotalResourceTime =24 Numero di secondi di impegno delle risorse EndDate=Thu 13 Feb 1997 Data dell ultima richiesta per la sessione di lavoro EndTime=15:31:15 Ora dell ultima richiesta per la sessione di lavoro La disponibilità di tali registrazioni permette di costruire delle tecniche di controllo degli accessi e di fatturazione basati su parametri quali il numero dei documenti trovati/consultati, la loro tipologia oppure la durata della sessione di lavoro. ICANET Guida Programmatore

253 I programmi di IcaNet: INLogon.exe Il programma INLogon.exe (IcaNet Logon) cura la fase di logon ad Icaro. La pagina HTML (INLogonx.htm) utilizzata è l unica pagina interamente statica usata da IcaNet. I campi di input utilizzati sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Nome Utente User text Password Password password Lingua Language radio Lunghezza Variabile La variabile Language indica la lingua da utilizzare per le pagine HTML successive a quella di logon. Il programma INLogon.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a mandare in esecuzione il servente batch di richieste Icaro passando a questo i parametri nome utente, password e progressivo di inizializzazione della sessione di lavoro. Quest ultimo parametro è un valore numerico intero che viene letto e progressivamente incrementato dal file "Progressivo Sessioni di Lavoro" di nome Progr.ica. Tale progressivo viene usato per generare il nome del file P<Progressivo>.ica all interno del quale il servente batch IcaBWS provvederà a comunicare ad INLogon.exe e quindi all intera applicazione IcaNet il path della directory della sessione di lavoro ed il path della directory relativa al servente AS/400. Il servente IcaBWS effettua il logon applicativo ad Icaro ed analizza il flag InitProcType ritornato dal server Icaro su AS/400. In funzione del valore ritornato da tale flag il servente IcaBWS: genera una risposta per INLogon (il file DBList.ica contenente la lista delle banche dati o la stringa contenente il messaggio di collegamento per gli utenti inserita nel file SessionF.ica); oppure innesca una nuova transazione verso il server Icaro su AS/400 per ottenere una pagina iniziale da fornire a INLogon nel file IcaInit.000. In particolare i valori permessi per il flag InitProcType sono: S sequenza standard (selezione banche dati o messaggio per gli utenti); H sequenza di pagine iniziali pilotate da Icaro sul server AS/400; E connessione per l utente respinta. Non appena IcaBWS termina la propria elaborazione crea il file P<Progressivo>.ica. Questo indica ad INLogon che la fase di logon è terminata e che è disponibile nel file SessionF.ica contenuto nella directory relativa alla sessione di lavoro il tipo di risposta da creare verso il web server. ICARO Guida Programmatore IcaNET

254 Infatti la sezione Logon del file SessionF.ica contiene il record Message con l eventuale messaggio per gli utenti ed il record InitProc con un valore numerico che indica il tipo di risposta ritornata da IcaBWS. In particolare il valore di InitProc è: 0 - se l elaborazione deve continuare con la visualizzazione del messaggio oppure con la lista delle banche dati; 1 - se è richiesta la gestione del risultato a fronte di una selezione banche dati e di una sottomissione automatica della query (le informazioni relative a questa fase vengono prelevate dalla sezione Query di SessionF.ica); 2 - se è richiesta la visualizzazione del documento a fronte di una selezione banche dati, di una sottomissione della query e di una selezione della modalità di visualizzazione automatica (le informazioni relative a questa fase vengono prelevate dalla sezione Document di SessionF.ica); 3 - se è richiesta la visualizzazione della lista abbreviata a fronte di una selezione banche dati, di una sottomissione della query e di una selezione della modalità di visualizzazione automatica (le informazioni relative a questa fase vengono prelevate dalla sezione ShortList di SessionF.ica); 4 - se è richiesta la visualizzazione di una pagina di menu (i dati da visualizzare nella pagina sono contenuti nel file IcaInit.000); 7 - se la connessione per quell utente è respinta. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INLogon azzera il record TransactionStatus della sezione General del file SessionF.ica e termina la propria elaborazione. La personalizzazione della pagina HTML deve mantenere inalterati i seguenti parametri: la struttura della form ; il campo di input name= User ; il campo di input name= Password ; la lista di selezione name= Language avente valore value= x dove il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo; il pulsante Avvio. ICANET Guida Programmatore

255 I programmi di IcaNet: INIProc.exe Il programma INIProc.exe (IcaNet Init Procedure) cura la fase di gestione delle pagine di menu iniziali di Icaro. La componente statica della pagina HTML usata da INIProc.exe è contenuta nel file InitProc.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Pulsante utente n. 1 Botton1 submit Pulsante utente n. 2 Botton2 submit Pulsante utente n. 3 Botton3 submit Pulsante utente n. 4 Botton4 submit Esecuzione di un InitMenu submit collegamento Pagina precedente InitReturn submit Home page HomePageReturn submit Livello pagine iniziali InitLevel hidden intero Identificativo dei InitChoice anchor collegamenti Contatore Counter hidden intero Variabili utente La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. Le variabili Bottonx indicano che l utente ha selezionato il pulsante personalizzato associato. La variabile InitMenu indica che l utente ha selezionato uno dei collegamenti (anchor) contenuto nella pagina HTML. La variabile InitReturn indica che l utente ha selezionato il pulsante di ritorno alla pagina HTML precedente. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML visualizzate. La variabile InitChoice indica il collegamento (anchor) selezionato dall utente. La variabile Counter è riservata. ICARO Guida Programmatore IcaNET

256 Qualsiasi altra variabile ritornata da questa pagina HTML viene considerata una variabile definita dal programmatore e valorizzata nella pagina HTML stessa dall utente. Il programma INIProc.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a selezionare il tipo di richiesta effettuata dall utente analizzando il contenuto delle variabili ritornate. Il tipo di richiesta viene quindi memorizzato nella variabile RequestType. I valori possibili sono: 1 - selezione di uno dei pulsanti gestiti dall utente; 2 - selezione di uno dei collegamenti (anchor) contenuti nella pagina; 3 - selezione del pulsante di ritorno alla pagina precedente; 4 - selezione del pulsante di ritorno alla home pag. Riassumendo è quindi possibile mandare interagire con la pagina in quattro modi diversi: selezionando uno dei collegamenti contenuti nella pagina, selezionando uno dei pulsanti gestiti dal programmatore, selezionando il bottone di ritorno ad una delle pagine precedenti oppure selezionando il bottone di ritorno alla home page. Nel caso di RequestType uguale a tre INIProc visualizza: se il livello precedente è zero la mappa di connessione ad Icaro tramite una chiamata alla funzione di libreria ICA_LogonPage altrimenti la pagina HTML di livello precedente attraverso una chiamata alla funzione di libreria ICA_InitProcPage. Nel caso di RequestType uguale a quattro INIProc visualizza la home page attraverso una chiamata alla funzione di libreria ICA_HomePage. Negli altri casi INIProc effettuata una chiamata al servente ICcaWSB attivato dal programma INLogon.exe richiedendo il servizio 130 (accesso ai menu iniziali) e passando le variabili necessarie (per ulteriori dettagli consultare il capitolo relativo alla sezione InitProc del file SessionF.ica ed alla richiesta 130 nel capitolo relativo al servente IcaBWS). Inizia quindi un ciclo di attesa a tempo alla conclusione del quale viene generata la risposta sotto forma di pagina HTML per il servente web. Al termine del ciclo di attesa, se è stato superato il timeout fissato nel record TimeOut della sezione General del file di inizializzazione della procedura allora viene generata una risposta di supero tempo, altrimenti se è stata ritornato un errore dal servente IcaBWS allora viene generata una pagina di risposta contenente l errore altrimenti viene analizzata la variabile InitProc contenente il tipo di risposta riotrnata dal servente IcaBWS. In particolare il valore di InitProc è: 0 o 5 - se l elaborazione deve continuare con la visualizzazione della lista delle banche dati; 1 - se è richiesta la gestione del risultato a fronte di una selezione banche dati e di una sottomissione automatica della query (le informazioni relative a questa fase vengono prelevate dalla sezione Query di SessionF.ica); ICANET Guida Programmatore

257 2 - se è richiesta la visualizzazione del documento a fronte di una selezione banche dati, di una sottomissione della query e di una selezione della modalità di visualizzazione automatica (le informazioni relative a questa fase vengono prelevate dalle sezioni Document e Navigation di SessionF.ica); 3 - se è richiesta la visualizzazione della lista abbreviata a fronte di una selezione banche dati, di una sottomissione della query e di una selezione della modalità di visualizzazione automatica (le informazioni relative a questa fase vengono prelevate dalle sezioni ShortList e Navigation di SessionF.ica); 4 - se è richiesta la visualizzazione di una pagina di menu (i dati da visualizzare nella pagina sono contenuti nel file IcaInit.xxx con xxx progressivo delle pagine iniziali); 6 - se viene richiesta la visualizzazione della pagina HTML di editazione della query. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INIProc azzera il record TransactionStatus della sezione General del file SessionF.ica e termina la propria elaborazione. ICARO Guida Programmatore IcaNET

258 I programmi di IcaNet: INLMsg.exe Il programma INLmsg.exe (IcaNet Logon Message) cura il ritorno dalla pagina HTML di visualizzazione del messaggio di collegamento per gli utenti. La componente statica della pagina HTML usata da INLMsg.exe è contenuta nel file LMessage.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Directory di lavoro SessionPCDirectory hidden 260 Pagina successiva Exec submit Home page HomePageReturn submit Lunghezza Variabile La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile Exec indica che l utente ha selezionato il pulsante di prosecuzione dell elaborazione Icaro. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il programma INLMsg.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a generare una nuova pagina HTML contenente la lista delle banche dati selezionabili dall utente. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INLMsg termina la propria elaborazione. ICANET Guida Programmatore

259 I programmi di IcaNet: INSelDB.exe Il programma INSelDB.exe (IcaNet Selection DataBase) cura la selezione delle banche dati sulle quali effettuare le ricerche. La componente statica della pagina HTML usata da INSelDB.exe è contenuta nel file DBList.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Lista BD selezionate DataBase select Accetta le banche dati Select submit 28 selezionate Pagina precedente LogonReturn submit Home page HomePageReturn submit Visualizzazione delle note di una banca dati Note submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML visualizzate. La variabile DataBase contiene l elenco dei codici associati alle banche dati selezionate dall utente. La lista delle banche dati è contenuta in una lista a selezione multipla dalla quale è possibile selezionare un massimo di nove banche dati. La lista delle banche dati selezionate viene passata dall interfaccia CGI come una serie di variabili di nome DataBase e di valore pari alla banca dati selezionata. La variabile Select indica che l utente ha confermato la lista delle banche dati selezionate dall utente. La variabile LogonReturn indica ha selezionato il pulsante di ritorno alla pagina HTML precedente. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. La variabile Note indica ha richiesto la visualizzazione delle eventuali note associate all ultima banca dati selezionata. ICARO Guida Programmatore IcaNET

260 Il programma INSelDB.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a selezionare il tipo di richiesta effettuata dall utente analizzando il contenuto delle variabili ritornate. Il tipo di richiesta viene quindi memorizzato nella variabile RequestType. I valori possibili sono: 1 - conferma delle banche dati selezionate; 2 - eventuale visualizzazione delle note di una banca dati; 3 - selezione del pulsante di ritorno alla pagina precedente. 4 - selezione del pulsante di ritorno alla home page. Riassumendo è quindi possibile mandare interagire con la pagina in quattro modi diversi: confermando la lista delle banche dati selezionate, visualizzando le note eventuali sulla banca dati selezionata, selezionando il bottone di ritorno alla pagine precedenti oppure selezionando il bottone di ritorno alla home page. Nel caso di RequestType uguale a tre INSelDB visualizza: se non vi sono pagine iniziali la mappa di connessione ad Icaro tramite una chiamata alla funzione di libreria ICA_LogonPage altrimenti la pagina HTML di livello precedente attraverso una chiamata alla funzione di libreria ICA_InitProcPage (se InitLevel è maggiore di zero) o la pagina di connessione tramite una chiamata alla funzione di libreria ICA_LogonPage (se InitLevel è uguale a zero). Nel caso di RequestType uguale a quattro INIProc visualizza la home page attraverso una chiamata alla funzione di libreria ICA_HomePage. Negli altri casi INSelDB effettuata una chiamata al servente ICcaWSB richiedendo il servizio 15 (accesso alle note di una banca dati) oppure il servizio 20 (seleziona le banche dati) e passando le variabili necessarie (per ulteriori dettagli consultare il capitolo relativo alla sezione DBNote e DBSelect del file SessionF.ica ed alle richieste 15 e 20 nel capitolo relativo al servente IcaBWS). Inizia quindi un ciclo di attesa a tempo alla conclusione del quale viene generata la risposta sotto forma di pagina HTML per il servente web. Al termine del ciclo di attesa, se è stato superato il timeout fissato nel record TimeOut della sezione General del file di inizializzazione della procedura allora viene generata una risposta di supero tempo, altrimenti se è stata ritornato un errore dal servente IcaBWS allora viene generata una pagina di risposta contenente l errore altrimenti viene generata la pagina contenente le note dell ultima banca dati selezionata se la richiesta era stata la funzione 15 oppure la pagina di formulazione della query se la richiesta era stata la funzione 20. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INSelDB azzera il record TransactionStatus della sezione General del file SessionF.ica e termina la propria elaborazione. ICANET Guida Programmatore

261 I programmi di IcaNet: INNote.exe Il programma INNote.exe (IcaNet Note) cura il ritorno dalla pagina HTML di visualizzazione delle note associate ad una banca dati. La componente statica della pagina HTML usata da INNote.exe è contenuta nel file DBNote.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Pagina precedente NoteReturn submit Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML visualizzate. La variabile NoteReturn indica ha selezionato il pulsante di ritorno alla pagina HTML precedente di visualizzazione della lista banche dati. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il programma INNote.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a generare una nuova pagina HTML contenente la lista delle banche dati selezionabili dall utente se la funzione richiesta è la NoteReturn oppure ritorna alla home page se è stata selezionata la funzione HomePageReturn. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INNote termina la propria elaborazione. ICARO Guida Programmatore IcaNET

262 I programmi di IcaNet: INQuery.exe Il programma INQuery.exe (IcaNet Query) cura la formulazione delle query. La componente statica della pagina HTML usata da INQuery.exe è contenuta nel file Query.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Esegui la query Exec submit 28 Pagina precedente DBListReturn submit Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML visualizzate. La variabile Exec indica che l utente ha confermato l esecuzione della query. La variabile DBListReturn indica ha selezionato il pulsante di ritorno alla pagina HTML precedente. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il programma INQuery.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a selezionare il tipo di richiesta effettuata dall utente analizzando il contenuto delle variabili ritornate. Il tipo di richiesta viene quindi memorizzato nella variabile RequestType. I valori possibili sono: 1 - esegue la query; 2 - selezione del pulsante di ritorno alla pagina precedente di selezione delle banche dati. 3 - selezione del pulsante di ritorno alla home page. 4 accesso al menu principale delle funzioni di importazione. 5 accesso al menu di selezione della tabella da cui importare voci. 6 selezione di una tabella e richiesta di visualizzazione delle sue voci. 7 selezionata la funzione di composizione di una select. 8 confermata la composizione di una select. 9 - selezionata la funzione di importazione di una query precedente. 10 confermata la selezione di una query precedente. 11 selezionata l importazione dal dizionario confermata la selezione di un termine dal dizionario. 13 richiesta l importazione dal thesaurus (funzione non ancora attiva). ICANET Guida Programmatore

263 14 non usato. 15 annullamento della generica operazione di importazione. 16 richiesta l importazione dalla lista dei campi/paragrafi per le banche dati selezionate. 17 confermata l importazione dalla lista dei campi/paragrafi per le banche dati selezionate. 18 richiesta l importazione di un operatore di relazione. 19 confermata l importazione di un operatore di relazione. 20 richiesta l importazione di una voce da una tabella. 21 richiesto l accesso al blocco successivo di dizionario. 22 confermata l importazione dei termini di un dizionario. Riassumendo è quindi possibile mandare interagire con la pagina in tre modi diversi: eseguendo la query, selezionando il bottone di ritorno alla pagine precedenti oppure selezionando il bottone di ritorno alla home page. Nel caso di RequestType uguale a due INQuery visualizza: la pagina di selezione delle banche dati tramite una chiamata alla funzione di libreria ICA_SelectDBPage se non vi sono pagine iniziali altrimenti la pagina HTML di livello precedente attraverso una chiamata alla funzione di libreria ICA_InitProcPage (se InitLevel è maggiore di zero) o la pagina di connessione attraverso una chiamata alla funzione ICA_LogonPage (se InitLevel è uguale a zero). Nel caso di RequestType uguale a tre INQuery visualizza la home page attraverso una chiamata alla funzione di libreria ICA_HomePage. Nel caso di RequestType uguale ad uno INQuery effettuata una chiamata al servente IcaBWS richiedendo il servizio 25 (esecuzione della query) e passando le variabili necessarie (per ulteriori dettagli consultare il capitolo relativo alla sezione Query del file SessionF.ica ed alla richiesta 25 nel capitolo relativo al servente IcaBWS). Negli altri casi previsti con il parametro RequestType viene gestito l insieme delle possibilità offerte dalle opzioni di importazione. Al cune di queste funzioni vengono elaborate localmente al server NT mentre altre (vedi ad esempio l accesso al dizionario) richiedono una interazione con il server AS/400. Inizia quindi un ciclo di attesa a tempo alla conclusione del quale viene generata la risposta sotto forma di pagina HTML per il servente web. Al termine del ciclo di attesa, se è stato superato il timeout fissato nel record TimeOut della sezione General del file di inizializzazione della procedura allora viene generata una risposta di supero tempo, altrimenti se è stata ritornato un errore dal servente IcaBWS allora viene generata una pagina di risposta contenente l errore altrimenti viene generata la pagina contenente il risultato della query formulata richiesta tramite la funzione 25. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INQuery azzera il record TransactionStatus della sezione General del file SessionF.ica e termina la propria elaborazione. ICARO Guida Programmatore IcaNET

264 I programmi di IcaNet: INQryRes.exe Il programma INQryRes.exe (IcaNet Query Result) gestisce il risultato di una query e tutte le attività connesse alla visualizzazione della lista abbreviata, alla visualizzazione dei documenti ed alla navigazione dinamica. Le componenti statiche delle pagine HTML usate da INQryRes.exe sono contenute nei file (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo): Result.htx: visualizzazione dei risultati; Occur.htx: visualizzazione delle ricorrenze; Option.htx: personalizzazione delle opzioni di visualizzazione e sort; ShList.htx: visualizzazione della lista abbreviata; Document.htx: visualizzazione dei documenti; NavMap.htx: pagina associata alla funzione di selezione delle opzioni di navigazione; NavRPMap.htx: pagina associata alla funzione di selezione del punto di ritorno dalla navigazione. Le variabili utilizzate nella pagina HTML Result.htx sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Codice banca dati DBId select 4 Lista abbreviata FirstShortList submit Visualizza documento FirstDocument submit Opzioni di DisplayOption submit visualizzazione/sort Lista ricorrenze OccurrenceList submit Pagina precedente QueryReturn submit Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML personalizzate sul server AS/400 già visualizzate durante le fasi iniziali della sessione di lavoro. La variabile DBId contiene il codice della banca dati selezionata e per la quale è stata richiesta una delle funzioni previste nella pagina di gestione del risultato. La variabile FirstShortList indica che l utente ha richiesto la visualizzazione della lista abbreviata. La variabile FirstDocument indica che l utente ha richiesto la visualizzazione dei documenti. ICANET Guida Programmatore

265 La variabile DisplayOption indica che l utente ha richiesto l accesso alle funzioni di personalizzazione della visualizzazione e del sort di lista abbreviata e documenti. La variabile OccurrenceList indica che l utente ha richiesto la visualizzazione della lista delle ricorrenze (questo pulsante non è più disponibile quando si ritorna, dopo una navigazione, alla pagina di gestione del risultato di una query Result.htx). La variabile QueryReturn indica ha selezionato il pulsante di ritorno alla pagina HTML precedente. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il ritorno alla home page comporta la chiusura automatica della sessione di lavoro Icaro. Le variabili utilizzate nella pagina HTML ShList.htx sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Livello di navigazione NavLevel hidden intero Numero di documenti NDoc hidden 10 già visualizzati Punto di rientro ReturnPoint hidden 20 Pagina richiesta nella NextPageNumber hidden int lista abbreviata Pagine visualizzate MaxPageNumber hidden int nella lista abbreviata Posizione relativa LastPosition hidden int Ritorno alla pagina PreviousShortList submit di lista abbreviata precedente Avanzamento alla NextShortList submit pagina successiva di lista abbreviata Ritorno al livello NavigationReturn submit precedente dalla navigazione Ritorno alla pagina ReturnGes submit di gestione dei risultati Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML personalizzate sul server AS/400 già visualizzate durante le fasi iniziali della sessione di lavoro. ICARO Guida Programmatore IcaNET

266 La variabile NavLevel contiene un valore numerico che indica il progressivo dei livelli di navigazione effettuati durante le fase di consultazione dei risultati della query iniziale. La variabile NDoc contiene un valore numerico che indica il numero di documenti già visualizzati nelle precedenti pagine di lista abbreviata. La variabile ReturnPoint contiene una stringa che indica il punto di rientro. Essa vale ShortList e indica che, in caso di visualizzazione di uno o più dei documenti contenuti nella lista abbreviata, il punto di ritorno all indietro dalla pagina HTML di visualizzazione del documento non è la pagina HTML di gestione del risultato (nel qual caso il contenuto della variabile ReturnPoint sarà la stringa ResultManagement ) ma è la pagina HTML di visualizzazione della lista abbreviata. La variabile NextPageNumber contiene un valore numerico che indica il progressivo delle pagine HTML già visualizzate nella lista abbreviata. La variabile MaxPageNumber contiene un valore numerico che indica il numero di pagine HTML di lista abbreviata già scaricate dal server AS/400 durante questa fase di consultazione della lista abbreviata. La variabile LastPosition contiene un valore numerico che indica la posizione relativa all interno del file dati (è un parametro riservato utilizzato internamente da IcaNet). La variabile PreviousShortList indica che l utente ha richiesto il ritorno alla pagina HTML di lista abbreviata precedente (pulsante presente solo se si sta visualizzando una pagina successiva alla prima). La variabile NextShortList indica che l utente ha richiesto la visualizzazione della successiva pagina HTML di lista abbreviata (pulsante presente solo se vi sono altre pagine di lista abbreviata successiva a quella visualizzata nella pagina attuale). La variabile NavigationReturn indica che l utente ha selezionato il pulsante di ritorno al livello di navigazione precedente (pulsante presente solo se si è disponibile una funzione di navigazione dinamica). La variabile ReturnGes indica la richiesta di ritorno alla pagina HTML di gestione del risultato. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il ritorno alla home page comporta la chiusura automatica della sessione di lavoro Icaro. Le variabili utilizzate nella pagina HTML Document.htx sono: ICANET Guida Programmatore

267 Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Livello di navigazione NavLevel hidden intero Numero di documenti NDoc hidden 10 già visualizzati Documenti da From hidden 10 Documenti a To hidden 10 Numero di righe Row hidden 10 Visualizzate Punto di rientro ReturnPoint hidden 20 Pagina successivo PageDown hidden Ritorno al documento PreviousDocument submit precedente Avanzamento al NextDocument submit documento successiva Richiesta la Navigation submit navigazione Ritorno al livello NavigationReturn submit precedente dalla navigazione Vai al documento GoToDocument submit Numero documento GoToDoc input 10 Ritorno alla lista ReturnShL hidden abbreviata ReturnInitProc Ritorno alla pagina ReturnGes submit di gestione dei risultati Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML personalizzate sul server AS/400 già visualizzate durante le fasi iniziali della sessione di lavoro. La variabile NavLevel contiene un valore numerico che indica il progressivo dei livelli di navigazione effettuati durante le fase di consultazione dei risultati della query iniziale. La variabile NDoc contiene un valore numerico che indica il numero di documenti già visualizzati nelle precedenti pagine di lista abbreviata. La variabile From contiene un valore numerico che indica il numero di documenti da cui iniziare la visualizzazione. La variabile To contiene un valore numerico che indica il numero di documenti fino a cui effettuare la visualizzazione. In questo caso la variabile From e la variabile To conterranno lo stesso valore. ICARO Guida Programmatore IcaNET

268 La variabile Row contiene un valore numerico che indica il numero di righe del documento corrente già visualizzate nella pagina HTML. La variabile ReturnPoint contiene una stringa che indica il punto di rientro. Essa può valere ResultManagement o ShortList. Vale ShortList se la visualizzazione del documento è stata richiesta da una pagina HTML di lista abbreviata per cui la richiesta di ritorno alla pagina HTML precedente deve riportare alla pagina di visualizzazione della lista abbreviata; vale, invece, ResultManagement se la visualizzazione del documento è stata richiesta dalla pagina HTML di gestione del risultato e pertanto la richiesta di ritorno alla pagina precedente deve riportare alla pagina HTML di gestione del risultato. La variabile PageDown indica che l utente ha richiesto la visualizzazione della pagina successiva del documento. La variabile PreviousDocument indica che l utente ha richiesto la visualizzazione del documento precedente (pulsante presente solo se si sta visualizzando un documento successivo al primo). La variabile NextDocument indica che l utente ha richiesto la visualizzazione del documento successivo (pulsante presente solo se vi sono altri documenti disponibili oltre quello visualizzato nella pagina HTML attuale). La variabile Navigation indica la richiesta di esecuzione di un passo di navigazione (questo pulsante è presente solo se è prevista una funzione di navigazione associata alla banca dati). La variabile NavigationReturn indica che l utente ha selezionato il pulsante di ritorno al livello di navigazione precedente (pulsante presente solo se si è attivata una funzione di navigazione). La variabile GoToDocument indica la richiesta di salto ad un documento. La variabile GoToDoc indica il documento al quale saltare a seguito della richiesta associata alla variabile GoToDocument. La variabile ReturnShL indica la richiesta di ritorno alla pagina HTML di visualizzazione della lista abbreviata. La variabile ReturnGes indica la richiesta di ritorno alla pagina HTML di gestione del risultato. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il ritorno alla home page comporta la chiusura automatica della sessione di lavoro Icaro. Le variabili utilizzate nella pagina HTML NavMap.htx sono: ICANET Guida Programmatore

269 Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Livello di navigazione NavLevel hidden intero Contatore interno Counter hidden intero Opzione selezionata NavChoice input 10 Ritorno al livello NavigationReturn submit precedente Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML personalizzate sul server AS/400 già visualizzate durante le fasi iniziali della sessione di lavoro. La variabile NavLevel contiene un valore numerico che indica il progressivo dei livelli di navigazione effettuati durante le fase di consultazione dei risultati della query iniziale. La variabile Counter contiene un progressivo numerico riservato a funzioni interne ad IcaNet. La variabile NavigationReturn che l utente indica ha selezionato il pulsante di ritorno al livello di navigazione precedente (pulsante presente solo se si è attivata una funzione di navigazione). La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il ritorno alla home page comporta la chiusura automatica della sessione di lavoro Icaro. Le variabili utilizzate nella pagina HTML NavRPMap.htx sono: Descrizione Campo Nome Variabile CGI Tipo Dimensione Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Livello di navigazione NavLevel hidden intero Ritorno al livello NavReturnStep submit precedente Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. ICARO Guida Programmatore IcaNET

270 La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML personalizzate sul server AS/400 già visualizzate durante le fasi iniziali della sessione di lavoro. La variabile NavLevel contiene un valore numerico che indica il progressivo dei livelli di navigazione effettuati durante le fase di consultazione dei risultati della query iniziale. La variabile NavReturnStep indica ha selezionato il pulsante di ritorno al livello di navigazione precedente. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il ritorno alla home page comporta la chiusura automatica della sessione di lavoro Icaro. Per quanto concerne le pagine Occurr.htx e Option.htx si rimanda ai capitoli relativi ai programmi INOption.exe e INOcc.exe. Il programma INQryRes.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a selezionare il tipo di richiesta effettuata dall utente analizzando il contenuto delle variabili ritornate. Il tipo di richiesta viene quindi memorizzato nella variabile RequestType. I valori possibili sono: 1 Richiesta la visualizzazione del primo documento; 2 Richiesta la successiva pagina del documento visualizzato; 3 Richiesta la visualizzazione del documento successivo; 4 Richiesta la visualizzazione del primo blocco di lista abbreviata; 5 Richiesta il successivo blocco di lista abbreviata; 6 Richiesta la visualizzazione del documento precedente; 7 Richiesta la navigazione da un documento; 8 Gestione del menu di navigazione; 9 Richiesta la funzione di "Vai al Documento"; 10 Ritorno dalla navigazione (n passi); 11 Richiesta la navigazione dalla lista abbreviata; 12 Ritorno dalla visualizzazione documento; 13 Ritorno alla lista abbreviata; 14 Gestione del menu di ritorno dalla navigazione; 15 Richiesta la lista delle occurrence; 16 Ritorno alla mappa di formulazione della query; 17 Richiesta la personalizzazione della visualizzazione; 18 Richiesta il precedente blocco di lista abbreviata; 19 Richiesta di ritorno alla home page. Nel caso di RequestType uguale a uno, due, tre, sei o nove INQryRes visualizza un documento attraverso una chiamata alla funzione di libreria ICA_DocumentPage. Nel caso di RequestType uguale a quattro, cinque, tredici o diciotto INQryRes visualizza la lista abbreviata attraverso una chiamata alla funzione di libreria ICA_ShortListPage. ICANET Guida Programmatore

271 Nel caso di RequestType uguale a sette, otto o undici INQryRes gestisce le funzioni di navigazione attraverso una chiamata alla funzione di libreria ICA_NavMapPage. Nel caso di RequestType uguale a dieci o quattordici INQryRes visualizza la pagina di gestione del rientro dalla navigazione attraverso una chiamata alla funzione di libreria ICA_NavReturnPointSelPage. Nel caso di RequestType uguale a quindici INQryRes visualizza la lista delle ricorrenze attraverso una chiamata alla funzione di libreria ICA_OccurrencePage. Nel caso di RequestType uguale a dodici o sedici INQryRes visualizza: la pagina di gestione del risultato tramite una chiamata alla funzione di libreria ICA_QueryResultPage se non vi sono pagine iniziali altrimenti la pagina HTML di livello precedente attraverso una chiamata alla funzione di libreria ICA_InitProcPage (se InitLevel è maggiore di zero) o la pagina di connessione attraverso una chiamata alla funzione ICA_LogonPage (se InitLevel è uguale a zero). Nel caso di RequestType uguale a diciassette INQryRes visualizza la pagina di selezione delle opzioni di visualizzazione e sort della lista abbreviata e delle visualizzazione dei documento attraverso una chiamata alla funzione di libreria ICA_DisplayOptionPage. Nel caso di RequestType uguale a diciannove INQuery visualizza la home page attraverso una chiamata alla funzione di libreria ICA_HomePage. Per le funzioni che lo prevedono si ha un ciclo di attesa a tempo alla conclusione del quale viene generata la risposta sotto forma di pagina HTML per il servente web. Al termine del ciclo di attesa, se è stato superato il timeout fissato nel record TimeOut della sezione General del file di inizializzazione della procedura allora viene generata una risposta di supero tempo, altrimenti se è stata ritornato un errore dal servente IcaBWS allora viene generata una pagina di risposta contenente l errore altrimenti viene generata la pagina associata alla richiesta effettuata dall utente. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INQuery azzera il record TransactionStatus della sezione General del file SessionF.ica e termina la propria elaborazione. ICARO Guida Programmatore IcaNET

272 I programmi di IcaNet: INOcc.exe Il programma INOcc.exe (IcaNet Occurrence) cura il ritorno dalla pagina HTML di visualizzazione delle ricorrenze dei termini contenuti in una query. La componente statica della pagina HTML usata da INOcc.exe è contenuta nel file Occur.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile Tipo Dimensione Lunghezza CGI Campo Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Pagina di gestione Exec submit risultato Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML visualizzate. La variabile Exec indica che l utente ha selezionato il pulsante di prosecuzione dell elaborazione Icaro. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il programma INOcc.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a generare una nuova pagina HTML contenente la lista delle banche dati selezionabili dall utente. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INLMsg termina la propria elaborazione. ICANET Guida Programmatore

273 I programmi di IcaNet: INOption.exe Il programma INOption.exe (IcaNet display Option) cura il ritorno dalla pagina HTML di visualizzazione delle opzioni di visualizzazione. La componente statica della pagina HTML usata da INOcc.exe è contenuta nel file Option.htx (il parametro x identifica il codice di lingua: 1 - italiano, 2 - inglese, 3 - tedesco, 4 - francese, 5 - spagnolo, 6 - portoghese, 7 - arabo). Le variabili utilizzate nella pagina HTML sono: Descrizione Campo Nome Variabile CGI Tipo Dimension e Campo Lunghezza Variabile Directory di lavoro SessionPCDirectory hidden 260 Livello pagine iniziali InitLevel hidden intero Campi/paragrafi per la DspList select visualizzazione Campi/paragrafi per la ShLList select lista abbreviata Campi/paragrafi per il SortList select sort Sort ascendente SortOption radio /discendente Distinzione maiuscole MmOption checkbo /minuscole x Conferma le opzioni SelectOption submit Pagina di gestione ExitOption submit risultato Home page HomePageReturn submit La variabile SessionPCDirectory, gestita dai moduli dell applicazione, contiene il path della directory che ospita i file relativi alla singola sessione di lavoro. La variabile InitLevel contiene un valore numerico che indica il progressivo delle pagine HTML visualizzate. La variabile DspList contiene la lista dei campi/paragrafi da utilizzare per la visualizzazione dei documenti. La variabile ShLList contiene la lista dei campi/paragrafi da utilizzare per la visualizzazione della lista abbreviata. La variabile SortList contiene la lista dei campi/paragrafi da utilizzare per il sort della lista abbreviata. La variabile SortOption indica il tipo di sort (ascendente o discendente) da utilizzare per la lista abbreviata. La variabile MmOption indica se il sort deve distinguere tra caratteri maiuscoli e caratteri minuscoli. ICARO Guida Programmatore IcaNET

274 La variabile SelectOption indica che l utente ha selezionato il pulsante di prosecuzione dell elaborazione Icaro confermando le selezioni fatte. La variabile ExitOption indica che l utente ha selezionato il pulsante di prosecuzione dell elaborazione Icaro non confermando le selezioni fatte. La variabile HomePageReturn indica che l utente ha selezionato il pulsante di ritorno alla home page. La home page è definita nel record HomePage della sezione General del valore Icaro del registry di NT. Il programma INOption.exe riceve il contenuto di queste variabili (usando le funzioni di interfaccia verso l ambiente CGI contenute nella libreria statica CGITools.obj) e provvede a generare una nuova pagina HTML contenente il risultato della query. Dopo aver generato la pagina di risposta (usando le funzioni contenute nella libreria statica ICAPage.obj) il programma INOption termina la propria elaborazione. ICANET Guida Programmatore

275 La libreria statica CGITools.obj La libreria statica CGITools.obj è costituita sostanzialmente da una sola funzione che si occupa di ricevere le variabili CGI da una pagina HTML. La sintassi della funzione è descritta di seguito. Nome della funzione: ReadArguments int ReadArguments (PPARMLIST *phead,char *SourceIPAddress) La funzione ReadArguments legge gli argomenti passati ad un programma CGI tramite i metodi GET e POST. Gli argomenti sono composti nella coppia (variabile, valore) contenuti nella struttura PPARMLIST definita nell header CGITools.h. Inoltre vengono convertiti tutti i caratteri speciali usati dal protocollo HTTP. Parametri in input La funzione riceve in input: una struttura PPARMLIST che ritornerà le coppie (variabile, valore); una stringa che conterrà' l'indirizzo IP dell'host che sottomette la richiesta. La struttura PPARMLIST è composta come segue: typedef struct _argument { char *VariableName; char *Value; struct _argument *pnext; } dove VariableName costituisce il nome della variabile CGI, Value è il valore assunto dalla variabile, pnext è un puntatore alla successiva istanza della coppia variabile/valore. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. 1 Metodo non gestito. 2 Variabile d'ambiente CONTENT_LENGTH non assegnata. 3 Allocazione di un buffer di memoria fallita. 4 Variabile d'ambiente QUERY_STRING non assegnata. ICARO Guida Programmatore IcaNET

276 Un esempio di utilizzo della funzione ReadArguments è fornito nello stralcio di programma seguente ed è comunque presente in ognuno dei programmi sorgenti forniti come esempio di IcaNet.... PPARMLIST... pparm=null; ReadArguments(&pParm,SourceIPAddress); while(pparm) { if(stricmp(pparm->variablename,"user")==0) strcpy(user,pparm->value); else if(stricmp(pparm->variablename,"password")==0) strcpy(password,pparm->value); } pparm=pparm->pnext; ICANET Guida Programmatore

277 La libreria statica ICAPage.obj La libreria statica ICAPage.obj contiene una serie di funzioni che hanno il compito di generare le pagine HTML necessarie all applicazione IcaNet. Le funzioni sono strutturate in modo tale da appoggiarsi ad uno scheletro di riferimento che rappresenta la struttura di base della pagina HTML ed a una serie di file, generati dal servente batch IcaBWS, contenente i dati dinamici estratti da Icaro. La lista delle funzioni di ICAPage.obj è costituita da: ICA_ErrorMessagePage; ICA_HTMLPage; ICA_HomePage; ICA_LogonPage; ICA_InitProcPage; ICA_LMessagePage; ICA_NoteDBPage; ICA_SelectDBPage; ICA_QueryPage; ICA_QueryErrorPage; ICA_ImportPage; ICA_ImportTableListPage; ICA_ImportTablePage; ICA_ImportFldParPage; ICA_ImportOpRelPage; ICA_ImportSelectPage; ICA_ImportDictionaryAccessPage; ICA_ImportDictionaryPage; ICA_ImportPreviousQueryPage; ICA_ResultQueryPage; ICA_DisplayOptionPage; ICA_OccurrencePage; ICA_DocumentPage; ICA_ShortListPage; ICA_NavMapPage; ICA_NavReturnPointSelPage. Nel seguito sono descritte le funzioni, i parametri ricevuti in input, ed i parametri restituiti in output. Per una migliore comprensione dell uso delle funzioni di ICAPage.obj si consiglia di consultare i programmi sorgenti forniti con IcaNet. ICARO Guida Programmatore IcaNET

278 Nome della funzione: ICA_ErrorMessagePage int ICA_ErrorMessagePage char *Title, char *Message) (char *FormFile, La funzione ICA_ErrorMessagePage visualizza una pagina HTML contenente un titolo ed un messaggio di errore. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; una stringa contenente il titolo del messaggio; una stringa contenente il testo del messaggio. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_HTMLPage int ICA_HTMLPage (char *HTMLFile, char *SessionPCDirectory) La funzione ICA_HTMLPage visualizza una generica pagina HTML. Parametri in input La funzione riceve in input: l URL della pagina HTML da visualizzare; il path della sessione di lavoro Icaro Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. ICANET Guida Programmatore

279 Nome della funzione: ICA_HomePage int ICA_HomePage(char *HomePage) La funzione ICA_HomePage visualizza la home page a cui punta l applicazione. Parametri in input La funzione riceve in input: una stringa contenente il percorso della pagina HTML contenente la home page. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. Nome della funzione: ICA_LogonPage int ICA_LogonPage int Language) (char *SessionPCDirectory, La funzione ICA_HomePage visualizza la home page a cui punta l applicazione. Parametri in input La funzione riceve in input: il path della sessione di lavoro Icaro; un valore numerico che indica la lingua selezionata dall utente. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. ICARO Guida Programmatore IcaNET

280 Nome della funzione: ICA_InitProcPage int ICA_InitProcPage (char *FormFile, char *DataFile, char *SessionPCDirectory, int InitLevel, int Language, char *FileMsg, int Counter) La funzione ICA_InitProcPage visualizza una pagina HTML contenente una pagina iniziale composta da una apposita procedura disponibile sul server IBM AS/400. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path del file contenente la componente dinamica della pagina HTML; il path della sessione di lavoro Icaro un progressivo numerico che indica il numero di pagine iniziali visualizzate; un valore numerico che indica la lingua selezionata dall utente; il path del file IcaNet11.str; un progressivo numerico riservato alla procedura. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. Nome della funzione: ICA_LMessagePage int ICA_LmessagePage (char *FormFile, char *Message, char *SessionPCDirectory) La funzione ICA_LMessagePage visualizza una pagina HTML contenente un messaggio per gli utenti proveniente dal server IBM AS/400. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; ICANET Guida Programmatore

281 il messaggio da visualizzare per gli utenti; il path della sessione di lavoro Icaro; Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_NoteDBPage int ICA_NoteDBPage (char *FormFile, char *DataFile, char *SessionPCDirectory, int InitLevel) La funzione ICA_NoteDBPage visualizza una pagina HTML contenente le note relative ad una banca dati (se disponibili). Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path del file contenente la componente dinamica della pagina HTML; il path della sessione di lavoro Icaro un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. -3 File con i caratteri di controllo non trovato. ICARO Guida Programmatore IcaNET

282 Nome della funzione: ICA_SelectDBPage int ICA_SelectDBPage (char *FormFile, char *DataFile, char *SessionPCDirectory, char *DBListId, int InitLevel) La funzione ICA_SelectDBPage visualizza una pagina HTML contenente la lista delle banche dati autorizzate per l utente. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path del file contenente la componente dinamica della pagina HTML; il path della sessione di lavoro Icaro una stringa contenente la lista delle banche dati precedentemente selezionate e quindi da evidenziare; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. Nome della funzione: ICA_QueryPage int ICA_QueryPage (char *FormFile, char *SessionPCDirectory, int InitLevel, char *DBListId, int QueryLevel) La funzione ICA_QueryPage visualizza una pagina HTML da utilizzare per la composizione della query. Parametri in input La funzione riceve in input: ICANET Guida Programmatore

283 il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; i codici della lista delle banche dati selezionate; un progressivo numerico che indica il livello della query da visualizzare. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_QueryErrorPage int ICA_QueryErrorPage (char *FormFile, char *SessionPCDirectory, int InitLevel) La funzione ICA_QueryErrorPage visualizza una pagina HTML contenente gli errori verificatisi durante l esecuzione di una query. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con i messaggi di errore non trovato. ICARO Guida Programmatore IcaNET

284 Nome della funzione: ICA_ImportPage int ICA_ImportPage (char *FormFile, char *SessionPCDirectory, int InitLevel int Language) La funzione ICA_ImportPage visualizza una pagina HTML contenente le possibili modalità di importazione dei dati. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_ImportTableListPage int ICA_ImportTableListPage (char *FormFile, char *DBCode, char *SessionPCDirectory, int InitLevel int Language) La funzione ICA_ImportTableListPage visualizza una pagina HTML contenente la lista delle possibili tabelle per l importazione dei dati. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; la lista delle banche dati selezionate; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata. ICANET Guida Programmatore

285 Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con la lista delle tabelle non trovato. Nome della funzione: ICA_ImportTablePage int ICA_ImportTablePage (char *FormFile, char *TableCode, char *SessionPCDirectory, int InitLevel int Language) La funzione ICA_ImportTablePage visualizza una pagina HTML contenente le voci di una tabella. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il codice della tabella selezionata; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le voci per la tabella selezionata non trovato. ICARO Guida Programmatore IcaNET

286 Nome della funzione: ICA_ImportFldParPage int ICA_ImportFldParPage (char *FormFile, char *SessionPCDirectory, int InitLevel int Language, char *DBCode) La funzione ICA_ImportFldParPage visualizza una pagina HTML contenente la lista dei campi/paragrafi da utilizzare per l importazione. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata; la lista delle banche dati selezionate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_ImportOpRelPage int ICA_ImportOpRekPage (char *FormFile, char *SessionPCDirectory, int InitLevel int Language) La funzione ICA_ImportOpRelPage visualizza una pagina HTML contenente la lista degli operatori di relazione da utilizzare per l importazione. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata. Parametri in output ICANET Guida Programmatore

287 La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_ImportSelectPage int ICA_ImportSelectPage (char *FormFile, char *SessionPCDirectory, int InitLevel int Language, char *DBCode) La funzione ICA_ImportSelectPage visualizza una pagina HTML contenente una form da utilizzare per comporre una select. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata; la lista delle banche dati selezionate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con la lista delle banche dati non trovato. Nome della funzione: ICA_ImportDictionaryAccessPage int ICA_ImportDictionaryAccessPage char *SessionPCDirectory, int InitLevel int Language, char *DBList) (char *FormFile, La funzione ICA_ImportDictionaryAccessPage visualizza una pagina HTML contenente una form da utilizzare per comporre la richiesta di accesso al dizionario. ICARO Guida Programmatore IcaNET

288 Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata; la lista delle banche dati selezionate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con la lista delle banche dati non trovato. Nome della funzione: ICA_ImportDictionaryPage int ICA_ImportDictionaryPage (char *FormFile, char *SessionPCDirectory, int InitLevel int Language, char *DBList) La funzione ICA_ImportDictionaryPage visualizza una pagina HTML contenente i termini estratti dal dizionario e che possono essere importati nella query. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata; la lista delle banche dati selezionate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. ICANET Guida Programmatore

289 Nome della funzione: ICA_ImportPreviousQueryPage int ICA_ImportPreviousQueryPage (char *FormFile, char *SessionPCDirectory, int InitLevel int Language) La funzione ICA_ImportPreviousQueryPage visualizza una pagina HTML contenente la lista delle query precedenti e che possono essere importati nella query. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il codice della lingua selezionata. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con la lista delle banche dati non trovato. Nome della funzione: ICA_ResultQueryPage int ICA_ResultQueryPage (char *FormFile, char *Result, char *SessionPCDirectory, int Language, char *FileMSg, int InitLevel) La funzione ICA_ResultQueryPage visualizza una pagina HTML contenente il risultato di una query. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il risultato della query; il path della sessione di lavoro Icaro; il codice numerico della lingua selezionata; il path del file IcaNet11.str contente i messaggi; un progressivo numerico che indica il numero di pagine iniziali visualizzate. ICARO Guida Programmatore IcaNET

290 Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. Nome della funzione: ICA_DisplayOptionPage int ICA_DisplayOptionPage (char *FormFile, char *SessionPCDirectory, char *DBId, int InitLevel) La funzione ICA_DisplayOptionPage visualizza una pagina HTML che consente di selezionare le modalità di visualizzazione e sort della lista abbreviata e della visualizzazione dei documenti. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; il codice della banca dati selezionata; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le strutture della banchi dati non trovato. ICANET Guida Programmatore

291 Nome della funzione: ICA_DocumentPage int ICA_DocumentPage (char *FormFile, char *DataFile, char *SessionPCDirectory, int DocNo, char *From, char *To char *TotDoc, char *Row, char *NavigationName, int NavLevel, char *ReturnPoint, int Language, char *FileMsg, int InitLevel) La funzione ICA_DocumentPage visualizza una pagina HTML che consente di selezionare le modalità di visualizzazione e sort della lista abbreviata e della visualizzazione dei documenti. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path del file contenente la componente dinamica della pagina HTML; il path della sessione di lavoro Icaro; il riferimento del documento nell ambito della banca dati; il numero del primo documento relativo da estrarre; il numero dell ultimo documento relativo da estrarre; il numero di riga del documento da cui iniziare l estrazione; la descrizione dell eventuale passo di navigazione; un progressivo numerico che indica il passo di navigazione; il punto di ritorno (gestione del risultato oppure lista abbreviata); il codice lingua selezionato; il path del file IcaNet11.str; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Per ulteriori dettagli si veda il capitolo relativo al programma INQryRes.exe Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. -3 File con i caratteri di controllo non trovato. ICARO Guida Programmatore IcaNET

292 Nome della funzione: ICA_ShortListPage int ICA_ShortListPage (char *FormFile, char *DataFile, char *SessionPCDirectory, char *NDoc, char *TotDoc, char *NavigationName, int NavLevel, int Language, char *FileINI, int InitLevel, int NextPageNumber, int MaxPageNumber, long LastPosition, char versus) La funzione ICA_ShortListPage visualizza una pagina HTML contenente la lista abbreviata. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path del file contenente la componente dinamica della pagina HTML; il path della sessione di lavoro Icaro; il riferimento del documento nell ambito della banca dati; il numero totale di documenti risultati dalla query; un progressivo che indica il numero di documenti visualizzati; la descrizione dell eventuale passo di navigazione; un progressivo numerico che indica il passo di navigazione; il codice lingua selezionato; il path del file IcaNet11.str; un progressivo numerico che indica il numero di pagine iniziali visualizzate; il numero massimo di pagine già visualizzate; il numero di pagina attualmente visualizzata; la posizione relativa dell ultimo accesso sul file dati; un carattere che indica la modalità di rientro nella lista abbreviata. Per ulteriori dettagli si veda il capitolo relativo al programma INQryRes.exe Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. -3 File con i caratteri di controllo non trovato. -4 File con i puntamenti relativi al file dati non trovato. ICANET Guida Programmatore

293 Nome della funzione: ICA_OccurrencePage int ICA_OccurrencePage (char *FormFile, char *SessionPCDirectory, int InitLevel) La funzione ICA_OccurrencePage visualizza una pagina HTML contenente la lista delle ricorrenze risultato della query. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. Nome della funzione: ICA_NavMapPage int ICA_NavMapPage(char *FormFile, char *DataFile, char *SessionPCDirectory, int NavLevel, int Language, char *FileINI, char *ReturnPoint, int Counter, int InitLevel) La funzione ICA_NavMapPage visualizza una pagina HTML contenente le possibili opzioni di navigazione. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path del file contenente la componente dinamica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il passo di navigazione; il codice lingua selezionato; il path del file IcaNet11.str; ICARO Guida Programmatore IcaNET

294 il punto da cui è stata chiamata la funzione di navigazione; un progressivo numerico riservato ad IcaNet; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. -2 File con le componenti dinamiche della pagine HTML non trovato. Nome della funzione: ICA_NavReturnPointSelPage int ICA_NavReturnPointSelPage (char *FormFile, char *SessionPCDirectory, int NavLevel, int InitLevel) La funzione ICA_NavReturnPointSelPage visualizza una pagina HTML che contiene le possibili opzioni di navigazione. Parametri in input La funzione riceve in input: il path del file contenente la componente statica della pagina HTML; il path della sessione di lavoro Icaro; un progressivo numerico che indica il passo di navigazione; un progressivo numerico che indica il numero di pagine iniziali visualizzate. Parametri in output La funzione restituisce un valore intero con il risultato dell operazione la cui decodifica è indicata nella tabella seguente: Valore Descrizione 0 Funzione completata con successo. -1 File con le componenti statiche della pagine HTML non trovato. ICANET Guida Programmatore

295 Il modulo IcaBWS Descrizione dell ambiente IcaBWS Il modulo IcaBWS v1.1 è un servente batch di sessioni di lavoro Icaro verso il server IBM AS/400. Esso opera ricevendo delle richieste e le inoltra verso l AS/400 e, viceversa, ricevendo le risposte dal server AS/400 e restituendole al chiamante. Lo scambio di richieste e di risposte tra IcaBWS e i moduli esterni che lo utilizzano avviene attraverso il file SessionF.ica. Il file SessionF.ica è un file windows di tipo.ini che viene acceduto attraverso le funzioni di sistema messa a disposizione dall ambiente Microsoft Windows per gestire i file di tipo.ini da programmi applicativi realizzati in vari linguaggi di alto livello. La scelta di utilizzare un tale meccanismo di scambio consente di ottenere una grande facilità e semplicità nella sottomissione di richieste verso Icaro e nella ricezione delle relative risposte. Le risposte ritornate da IcaBWS vengono memorizzate o in SessionF.ica oppure in appositi file di dati. Ad ogni sessione di lavoro viene assegnato uno spazio su disco nel server NT destinato a contenere tutti i dati relativi alla sessione. In particolare, all interno della directory che contiene i programmi relativi ad IcaBWS viene creata una directory per ogni server IBM AS/400 ed una directory per ogni sessione di lavoro. Il seguente schema illustra il meccanismo di scambio di richieste e risposte tra i moduli di una applicazione (Modulo 1, Modulo 2,..., Modulo N) quale ad esempio IcaNet e IcaBWS. Modulo 1 Modulo 2... Modulo N SessionF.ica IcaBWS La struttura delle chiamate per i vari servizi offerti da IcaBWS e le relative risposte sono illustrate nei successivi paragrafi. Ad ogni servizio è associato un codice numerico e dei record inserite in sezioni dedicate al servizio contenenti le richieste e le relative risposte. ICARO Guida Programmatore IcaNET

296 Le sezioni del file SessionF.ica La sezione General La sezione General contiene i seguenti record: TransactionStatus; TransactionRequest; SourceIPAddress; Language; MessageHeader; MessageText. Il record TransactionStatus Il record TransactionStatus della sezione General indica lo stato della esecuzione della richiesta sottoposta a IcaBWS. Val Descrizione 0 Non vi sono transazioni sospese. (Il client ed il server non sono sincronizzati). 1 Il client ha effettuato una richiesta (indicata nella variabile TransactionRequest) e resta in attesa della elaborazione da parte del server. Quest'ultimo non ha ancora letto la richiesta. 2 Il server ha letto la richiesta e la sta elaborando. Il client resta in attesa. 3 Il server ha terminato la propria elaborazione ed il client può leggere i risultati. E' a carico del client resettare il flag TransactionStatus al valore 0. 4 Il server ha terminato la propria elaborazione ed è stato riscontrato un errore il cui dettaglio si trova nei record MessageHeader e MessageText. E' a carico del client resettare il flag TransactionStatus al valore 0. Il record TransactionRequest Il record TransactionRequest della sezione General contiene un codice numerico che identifica la richiesta sottoposta a IcaBWS. Le possibili richieste sono riportate nella seguente tabella: Richiesta Codice Descrizione LOGON 5 Apertura della sessione di lavoro INITPROGRAM 130 Gestione dei menu iniziali USERMESSAGE 10 Messaggio per gli utenti DBNOTE 15 Note su una banca dati DBSELECT 20 Selezione banche dati QUERY 25 Formulazione di una domanda QUERYRESULT 100 Gestione del risultato di una query OCCURRENCE 105 Lista delle ricorrenze ICANET Guida Programmatore

297 NAVIGATION 110 Funzione di navigazione NAVIGATIONMENU 120 Ritorno da un passo di navigazione TABLELIST 140 Lista delle tabelle TABLE 150 Voci di una tabella DICTIONARY 160 Accesso al dizionario LOGOFF 200 Chiusura della sessione di lavoro Il record SourceIPAddress Questo record contiene l indirizzo IP del client che ha sottoposto la richiesta. Il record Language Questo record contiene il codice lingua selezionato. I valori ammessi sono: 1 - italiano; 2 - inglese; 3 - tedesco; 4 - francese; 5 - spagnolo; 6 - portoghese; 7 - arabo. I record MessageHeader e MessageText Questi due record contengono il titolo ed il testo di eventuali messaggi di errore. In questo caso il record TransactionStatus vale 4. La sezione Counter La sezione Counter contiene due record Navigation e InitProc riservate a funzioni interne di IcaBWS. ICARO Guida Programmatore IcaNET

298 Nome del servizio: LOGON Codice operativo: 5 Parametri in input: Questa richiesta prevede l avvio del servente IcaBWS con il passaggio dei seguenti parametri sulla riga di comando: User: Nome utente; Password: Password dell utente; Language: Lingua selezionata; File: Progressivo numerico; IPAddr: Indirizzo IP dell host chiamante. Output della richiesta: Sezione Record Descrizione del valore General Message Eventuale messaggio per gli utenti Icaro. General InitProc Tipo di procedura iniziale: Inoltre a conclusione dell attività di connessione al server IBM AS/400 viene restituito un file avente il nome composta dalla lettera P seguita dal progressivo numerico passato sulla riga dei comandi nel parametro File e dall estensione.ica. All interno di tale file sono memorizzati due record (terminati da un carattere di newline) contenenti il primo il path della sessione di lavoro assegnata alla richiesta ed il secondo il path della directory di lavoro assegnata al server IBM AS/400. Note: La richiesta di logon inizia con la esecuzione del programma IcaBWS al quale vengono passati, sulla riga di comando, i parametri discussi nella sezione Parametri in input. ICANET Guida Programmatore

299 Nome del servizio: INITPROGRAM Codice operativo: 130 Parametri in input: Sezione Record Descrizione del valore InitProc InitLevel Numero di pagine iniziali InitProc InitProcChoice Eventuale opzione selezionata dall utente InitProc FieldsValue Sequenza dei capi di input organizzata secondo lo schema: Nome_Campo:Valore; InitProc InitHTMLPage URL di una pagina HTML esterna ad IcaNet a cui accedere. File Descrizione del file IcaInit.<Livello - 1> File dati restituito dalla richiesta 130 di livello precedente. Output della richiesta: File IcaInit.<Livello> Descrizione del file File dati contenente il risultato da visualizzare (per dettagli sulla struttura dei file IcaInit vedi il manuale IcaWin v1.1 - Funzione ICA_Call, pagina 60). Note: Questo servizio accede alle funzioni successive alla procedura di logon nel caso in cui vi siano delle pagine di personalizzazione realizzate sul server IBM AS/400. Il progressivo InitLevel contiene l indicazione del numero e quindi delle pagine iniziali già generate nel processo relativo alla sessione di lavoro. Questo progressivo viene, peraltro, utilizzato per identificare le estensioni dei vari file di tipo InitProc contenenti i dati da visualizzare nelle pagine HTML. Il dettaglio della struttura di tale file può essere trovato nel manuale IcaWin v1.1 - Funzione ICA_Call, pagina 60. Se una delle pagine contiene dei campi di input (ad esempio una pagina di composizione guidata della query) allora i valori immessi dall utente vengono intercettati dal programma di gestione INIProc.exe e composti nella variabile FIeldsValue come indicato nella sezione parametri in input. Infine se viene selezionata una delle opzioni presentate nella pagina di menu iniziali allora deve essere memorizzata nella variabile InitProcChoice il numero dell opzione selezionata. Per dettagli ulteriori sull utilizzo di questa funzione si analizzi il programma INIProc.cpp fornito come esempio di corredo alla procedura IcaNet. ICARO Guida Programmatore IcaNET

300 Nome del servizio: USERMESSAGE Codice operativo: 010 Parametri in input: Nessuno. Output della richiesta: Sezione Record Descrizione del valore Logon Message Testo del messaggio. Note: Questo servizio accede all eventuale messaggio disponibile per gli utenti Icaro. Il messaggio viene scaricato dal server IBM AS/400 e posto nel record Message della sezione Logon. Nome del servizio: DBNOTE Codice operativo: 015 Parametri in input: Sezione Record Descrizione del valore DBNote DBId Codice della banca dati Output della richiesta: File Note<DBId>.ica Descrizione del file File dati contenente il testo delle note relative alla banca dati di codice DBId da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_RTxt, pagina 30). Note: Questo servizio accede all eventuale testo di note relative ad una banca dati. Tale testo viene memorizzato in un file il cui nome viene composto dalla stringa Note seguita dal codice numerico della banca dati e dall estensione.ica. Questo progressivo viene, peraltro, utilizzato per identificare le estensioni dei vari file di tipo InitProc contenenti i dati da visualizzare nelle pagine HTML. ICANET Guida Programmatore

301 Nome del servizio: DBSELECT Codice operativo: 020 Parametri in input: Sezione Record Descrizione del valore DBSelect DBListId Lista dei codici numerici delle banche dati Output della richiesta: File SoLO<Codice_BD>.ica; ShLO<Codice_BD>.ica; Stru<Codice_BD>.ica Descrizione del file File dati contenente il risultato da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_Call, pagina 60). Note: Questo servizio provvede alla selezione delle banche dati i cui codici sono inseriti nella stringa DBListId. A completamento della selezione vengono creati i file: SoLO<Codice_BD>.ica; ShLO<Codice_BD>.ica; Stru<Codice_BD>.ica. Nome del servizio: TABLELIST Codice operativo: 140 Parametri in input: Sezione Record Descrizione del valore DBSelect DBListId Lista dei codici numerici delle banche dati Output della richiesta: File TblL<Codice_BD>.ica Descrizione del file File dati contenente il risultato da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_RtTbLT, pagina 38). Note: Questo servizio provvede alla estrazione delle tabelle i cui codici sono inseriti nella stringa DBListId. A completamento della estrazione viene creato il file: TblL<Codice_BD>.ica. ICARO Guida Programmatore IcaNET

302 Nome del servizio: TABLE Codice operativo: 150 Parametri in input: Sezione Record Descrizione del valore Table TableId Codice numerici della tabella Table DBId Codice numerici delle banche dati Output della richiesta: File Descrizione del file TbR<Codice_BD><Codice_Tabella>.ica File dati contenente il risultato da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 Funzione ICA_RtTbLD, pagina 40). Note: Questo servizio provvede alla estrazione delle voci della tabella di codice TableId relativa alla banca dati DBId. A completamento della estrazione viene creato il file: TbR<Codice_BD><Codice_Tabella>.ica Nome del servizio: DICTIONARY Codice operativo: 160 Parametri in input: Sezione Record Descrizione del valore Dictionary Check Flag di richiesta verifica della sintassi Dictionary DBId Codice numerici delle banche dati Dictionary Modality Modalità di ricerca: 1 si ricerca il termine normalizzato; 2 si ricerca il termine reale. Dictionary Term Termine da ricercare. Output della richiesta: File Diz<Codice_BD>.ica Descrizione del file File dati contenente il risultato da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 Funzione ICA_RtvDiz, pagina 42). Note: Questo servizio provvede alla estrazione dei termini dal un dizionario relativo alla banca dati DBId. A completamento della estrazione viene creato il file: Diz<Codice_BD>.ica ICANET Guida Programmatore

303 Nome del servizio: QUERY Codice operativo: 025 Parametri in input: Sezione Record Descrizione del valore Query BIDI Query di tipo LTR o RTL. Query QueryLevel Progressivo numerico del numeri di query eseguite nella sessione di lavoro Icaro. File CurQuery.000 Descrizione del file File dati contenente la query da formulare. L estensione.000 indica il passo di navigazione a livello 0. (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_SndQuery, pagina 46). Output della richiesta: Sezione Record Descrizione del valore Query QueryStatus Stato della query. Questo parametro può valere: Success: la query ha avuto successo; Warning: si è verificato un errore non grave; Error: si è verificato un errore grave. Query Result Risultato della query (Codice Banca Dati, Descrizione Banca Dati, Totale Documenti.). Note: Questo servizio provvede a sottomettere una query al server. La query viene memorizzata in un file avente nome CurQuery.000 e passata al servente IcaBWS. La stringa QueryStatus indica il risultato della query in termini di successo, errore o errore grave. Il dettaglio del risultato viene, invece, restituito nella stringa Result che contiene il codice banca dati (3 byte), la descrizione banca dati (40 byte) ed il totale documenti trovati per la banca dati (9 byte). ICARO Guida Programmatore IcaNET

304 Nome del servizio: QUERYRESULT Codice operativo: 100 Parametri in input: Sezione Record Descrizione del valore QueryResult DBId Codice della banca dati selezionata per la gestione del risultato. QueryResult Mode Modalità di gestione del risultato. Può valere: Document: se è richiesta la visualizzazione documento; ShortList: se è richiesta la lista abbreviata. In funzione della modalità Mode selezionata deve essere valorizzata opportunamente la sezione Document o la sezione ShortList. Sezione Record Descrizione del valore Document Operation Tipo di operazione richiesta: New: prima pagina del documento; PageDown: pagina successiva. Document From Estremo inferiore del documento da estrarre. Document To Estremo superiore del documento da estrarre. Document Row Numero di righe estratte dal documento corrente. Sezione Record Descrizione del valore ShortList Operation Tipo di operazione richiesta: New: prima pagina della lista abbreviata; PageDown: pagina successiva. ShortList NavName Descrizione della navigazione. ShortList NDoc Numero del documento. ShortList Resume Flag che indica di ripristinare la lista abbreviata. Opzionalmente può essere valorizzata anche la sezione Sort per richiedere modalità di ordinamento alternative a quelle di default. Sezione Record Descrizione del valore Sort SortType Modalità del sort: A: ascendente; D: discendente. Sort UpperLower Distinzione fra caratteri maiuscoli/ minuscoli: Y: effettua la distinzione; N: non effettua la distinzione. ICANET Guida Programmatore

305 Output della richiesta: In funzione della richiesta effettuata vengono valorizzati i seguenti record delle sezioni Document o ShortList. Sezione Record Descrizione del valore Document NavName Descrizione della navigazione. Document DocNo Numero del documento. Document TotDoc Totale dei documenti. Sezione Record Descrizione del valore ShortList NavName Descrizione della navigazione. ShortList TotDoc Totale dei documenti. In funzione della richiesta effettuata viene ritornato un file contenente il documento oppure un file contenente la lista abbreviata. File Doc.<NavLevel> ShList.<NavLevel> Descrizione del file File dati contenente il documento da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_DSPDO, pagina 54). File dati contenente la lista abbreviata da visualizzare (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_DSPLI, pagina 51). Note: Nome del servizio: OCCURRENCE Codice operativo: 105 Parametri in input: Nessuno. Output della richiesta: File OccTot.ica Descrizione del file File dati contenente le ricorrenze della query (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_RtvOcc, pagina 49). Note: ICARO Guida Programmatore IcaNET

306 Nome del servizio: NAVIGATION Codice operativo: 110 Parametri in input: Sezione Record Descrizione del valore Navigation NavLevel Livello di navigazione Navigation NavCalled Stringa che indica il punto di chiamata della navigazione. La richiesta può provenire: Document: da un documento; ShortList: da una lista abbreviata; Document(SL): da un documento visualizzato da una lista abbreviata. Navigation NavChoice Se la navigazione è stata richiesta da una pagina di navigazione intermedia questa variabile indica l opzione che è stata selezionata per richiedere il successivo passo di navigazione. Navigation DocumentNumber E il numero di documento da cui è stata richiesta la navigazione nel caso di NavCalled=ShortList. Navigation NavFlag E un flag che indica se la navigazione avviene in avanti oppure in indietro. Navigation NavHTMLPage URL di una pagina HTML etserna ad IcaNet da visualizzare. Output della richiesta: Sezione Record Descrizione del valore Navigation NavResult Valore numerico che indica il risultato del passo di navigazione richiesto. Può assumere i seguenti valori: 1: riservato per usi futuri; 2: pagina di opzioni di navigazione; 3: visualizzazione del documento; 4: visualizzazione della lista abbreviata; 5: riservato per usi futuri; 6: visualizza una pagina HTML. File NavList.<NavLevel> Descrizione del file File dati contenente il risultato della navigazione (per dettagli ulteriori vedi il manuale IcaWin v1.1 - Funzione ICA_RtvNav, pagina 57). Note: In funzione del risultato NavResult del passo di navigazione l output sarà costituito da un file. In particolare: 2: un file di tipo NavList.<NavLevel>; 3: un file di tipo Document.<NavLevel>; 4: un file di tipo ShList.<NavLevel>. ICANET Guida Programmatore

307 Nome del servizio: NAVIGATIONMENU Codice operativo: 120 Parametri in input: Sezione Record Descrizione del valore Navigation NavLevel Livello di navigazione Navigation NavFlag E un flag che indica se la navigazione avviene in avanti oppure in indietro. In questo caso vale sempre 0. Output della richiesta: Sezione Record Descrizione del valore Navigation NavResult Valore numerico che indica il risultato del passo di navigazione richiesto. Può assumere i seguenti valori: 1: ancora non attivo; 2: pagina di opzioni di navigazione; 3: visualizzazione del documento; 4: visualizzazione della lista abbreviata; 5: ancora non attivo. Note: In funzione del risultato NavResult del passo di navigazione l output sarà costituito da un file. In particolare: 2: un file di tipo NavList.<NavLevel>; 3: un file di tipo Document.<NavLevel>; 4: un file di tipo ShList.<NavLevel>. Nome del servizio: LOGOFF Codice operativo: 200 Parametri in input: Nessuno. Output della richiesta: Nessuno. Note: Questo servizio provvede alla chiusura della sessione di lavoro Icaro ed alla cancellazione delle aree di lavoro. Al termine di queste attività il programma IcaBWS termina la propria esecuzione. ICARO Guida Programmatore IcaNET

308 ICANET Guida Programmatore

309 ICARO Guida Programmatore IcaNET