Generazione e Gestione della documentazione del software applicativo iSeries/AS400
La Missione del programma e' quella di fornire valide funzioni per realizzare e mantenere in automatico la :
- Documentazione Tecnica e di Struttura (con inserti funzionali)
- Documentazione Utente (manuale Utente) con indotte le seguenti funzioni aggiunte
- Impact Analisys ( mediante Where Used ) (determinazione degli impatti sul database e sui programmi a seguito di modifiche strutturali)
- On Line Facilities (per il programmatore che interattivamente puo' interrogare il repository per visionare e comprendere strutture, attributi, caratteristiche e modalita' del sistema)
- Valutazione di Programmi e Packages (mediante indici di complessita' semplice, di struttura e ciclomatica McCabe - Mills
Per mezzo di un processo di “reverse engineering”, abbiamo a disposizione un insieme strutturato di informazioni riferite ad oggetti (programmi e files) del sistema applicativo AS/400 da documentare; sono forniti su PC Windows strumenti per interrogare, completare e stampare in modo organizzato e grafico la struttura fisica e logica delle componenti. Sono evidenziate le strutture gerarchiche e relazionali tra i vari oggetti. Sono altresì fornite funzioni di supporto per il Programmatore e per l’Analista per la valutazione del livello qualitativo del software secondo criteri ufficiali (complessità lineare e ciclomatica), il tutto finalizzato alla produzione di documentazione (elettronica, ma anche cartacea), alla consultazione (visibilità su l’intero sistema) e all’apprendimento rapido dell’applicativo mediante presentazioni sia grafiche, sia testuali. Il recupero delle informazioni sulle strutture dell’applicativo (import nel repository) avviene in modo automatico mediante apposite funzioni di analisi dei dati.
I programmi (packages) sono sempre più frequentemente acquistati da terze parti, la loro documentazione si limita troppo spesso a una descrizione sommaria dei moduli e, talvolta, del solo data base fisico; la loro conoscenza tecnico-funzionale da parte del Personale acquirente è molto limitata; l’acquisizione del know-how richiede molto tempo con costi elevati, anche se non evidenti.
I sistemi sviluppati “in casa” sono stati realizzati su analisi funzionali “essenziali”, tramite specifiche tecniche e di struttura molto spesso inesistenti in quanto demandate alla buona (ottima) volontà e al buon senso del Personale (ovvero realizzate senza supporto di sistemi automatizzati).
A causa di problemi quali il contenimento dei costi di realizzazione e dei consueti e fisiologici ritardi nella consegna del progetto, raramente si assiste al completamento della documentazione, sia tecnica, sia Utente o funzionale.
Il turn-over del personale tecnico depositario di “segreti” informatici (racchiusi in procedure e programmi) pone l’Azienda in condizione critica in quanto il Soggetto dimissionario risulta essere, nella quasi totalità dei casi, l’unico conoscitore del sistema; questo accade spesso quando il tecnico è contemporaneamente realizzatore e manutentore.
La documentazione, se mai esistente, è raramente aggiornata a fronte di revisioni o modifiche dei sistemi (data base, procedure e programmi).
In ogni caso, il problema principale è come produrre e aggiornare in modo efficiente la documentazione di un nuovo progetto o di quanto già in essere purché questa risulti essere essenzialmente economica nella produzione e immediata nella consultazione e visione.
DocMaster è lo strumento adeguato per poter affrontare e risolvere il problema della documentazione di sistemi software AS/400 in modo semplice ed economico.
Il prodotto si pone come sistema di supporto alle figure di Capo Progetto, Analista e Programmatore, con una serie di funzioni che permettono di risolvere in modo affidabile e celere i relativi problemi di documentazione e di visibilità su programmi e procedure AS/400.
Il prodotto DocMaster è ispirato ai principi di “Reverse Engineering”.
Applicabilità
DocMaster trova applicazione nelle seguenti circostanze:
· accentramento e distribuzione di informazioni in merito alle strutture tecniche (software e database) e funzionali (software)
· ricerca e consultazione rapida di informazioni riferite al software e ai database
· mantenimento delle informazioni riferite al software (documentazione) a seguito di upgrade evolutivi apportati ai programmi applicativi
· valutazione sulla qualità del software
· valutazione e determinazione degli impatti sui programmi e sui database a seguito di revisioni strutturali e funzionali.
· produzione automatica di manuali tecnici direttamente su carta oppure su documenti ipertestuali
· gestione delle versioni evolutive dei programmi sorgenti, con evidenza delle variazioni apportate nel tempo
Macro funzioni
Le macro funzioni sono:
· documentazione tecnica/funzionale
· on line facilities
· valutazione software
Questi servizi si ottengono mediante le seguenti attività:
- Documentazione
- Matrice di Relazione
- Stampa Manuali
- Consultazione Video
Esistono funzioni comuni a ogni attività che permettono di risolvere problemi quali la quantificazione e la qualificazione delle informazioni. Tra di esse si può notare la funzione di “Where Used” che consente di effettuare valutazioni di tipo “Impact Analisys”, anche grazie all’assegnazione dell’indice di gravità (utilizzo: input, alias, write in, struttura dati).
Un esempio: mediante la funzione “Where Used” è possibile compiere un’analisi istantanea per rilevare quali e quanti oggetti (programmi, campi e database file) devono essere modificati per estendere il formato campo delle date da 6 posizioni a 8 posizioni.
Una sotto-funzione al “Where Used” , importantissima, è costituita dalla possibilità di “marcare” i programmi ed i record-source con degli appositi flag al fine di consentirne la successiva rapida identificazione e relativa gestione.Il caso di maggior applicabilità è rappresentato dai temi “anno 2000” , “euro-moneta” e similari, in quanto, grazie all’azione di marcatura, sarà possibile conoscere immediatamente quali statement di programma modificare per aggiornare il software applicativo soggetto alla revisione.
Standard
Lo standard adottato per la produzione della documentazione, l’utilizzo di criteri per la valutazione del software e i servizi offerti per la consultazione delle informazioni, permettono di adottare un unico “linguaggio e metodo” diffuso a livello sia di analisi sia di sviluppo, con evidenti benefici economici.
DocMaster consente la presentazione delle strutture dell’applicativo mediante il criterio della “decomposizione funzionale”, strutturata in Top-Down.
Gli inserti documentativi (inserimenti manuali di note funzionali) applicabili a ogni programma o sub routine consentono di completare il quadro documentativo.
Espandere la documentazione
DocMaster consente di relazione la documentazione propria con quanto di già esistente (files TXT e Word), oppure di inglobare nelle proprie strutture i corpi di testo documentativo sia già esistenti al momento della generazione della documentazione, sia manoscritti successivamente.
Questa possibilità è offerta dei servizi di “Link”.
Ambienti elaborativi
DocMaster opera su PC modello Pentium 166 o superiore, con almeno 16 MB RAM, dotati di Win 95/98/NT, in modalità stand alone oppure client server.
Il costo di acquisto del programma DocMaster è ammortizzabile in un periodo d’uso variabile da 1 a 4 mesi, in funzione dell’utilizzo.
La tabella seguente confronta i tempi/costi sostenuti per la produzione manuale della documentazione con i relativi tempi/costi sostenuti con procedimento automatico mediante DocMaster.
Il software applicativo portato come esempio è composto da 500 programmi (300 interattivi - 200 batch).Applicativi di dimensioni minori o maggiori daranno luogo a risparmi di diversa consistenza.
La complessità dei programmi è evidenziata da sigle: A (alta) B (bassa) M (media).
| Complessità | tipo | N. prog. | tempo per la documentaz. manuale di un programma | costo totale* | tempo di docum. di 1 prog. di by DocMaster | costo totale* | vantaggioA totale |
|---|---|---|---|---|---|---|---|
| A | Int. | 50 | 8 h | 10.000 | 0.5 h | 625 | |
| B | Int. | 100 | 4 h | 10.000 | 0.25 h | 312 | |
| M | Int. | 150 | 6 h | 22.500 | 0.25 h | 700 | |
| A | Batch | 50 | 8 h | 10.000 | 0.5 h | 625 | |
| B | Batch | 100 | 4 h | 10.000 | 0.25 h | 312 | |
| M | Batch | 50 | 6 h | 7.500 | 0.5 h | 468 | |
| totale | 70.000 | 3.042 | 66.958 |
* costo in euro stimato per documentare i programmi di cui alla colonna “N.prog.”.
Il costo giornaliero medio di un Programmatore/Analista è stimato in € 200,00
Ne consegue un risparmio pari a € 67.000 !! (o poco meno)
Inoltre non è qui stimato, poiché non quantificabile, il vantaggio economico derivante dall’utilizzo di DocMaster per attività di analisi, ricerca, valutazione !
Il presente modulo costituisce il nodo cruciale del sistema di documentazione.
Esso permette di visionare interattivamente la struttura del sistema applicativo documentato e dei suoi componenti.Permette quindi, navigando nei vari percorsi del documentatore, di visionare in dettaglio l’intero sistema applicativo e i sui componenti.
L’utilizzo dei parametri di selezione (riferim. capitolo “Modulo Parametri”) permette di ottenere una lista parziale di oggetti che costituiscono un sub set omogeneo. Da tale elenco è possibile ottenere, per ogni programma, le informazioni tecnico-funzionali in modo sia interattivo, sia su report, sia su documento Microsoft-Word 6.0. oppure su file in formato RTF (Rich Text Formatted), elaborabile da tutti i principali programmi di video scrittura.
Il modulo permette al Programmatore (e all’Analista) di visionare l’applicativo in tutte le sue componenti strutturali ed essenziali, fornendo la possibilità di apprenderne il significato mediante consultazioni delle strutture (grafiche e testuali). E’ possibile “navigare” nell’applicativo mediante funzioni di “jumping” tra programmi chiamanti e chiamati, nonché eseguire “zoom” sulle singole sub-routines, analizzandone i commenti (remarks) e le note funzionali.
Il documentatore di programmi non “scende” a un livello di struttura più analitico in quanto significherebbe duplicare, anche se forse in chiave più comprensibile in quanto grafica, il sorgente del programma stesso: per questo tipo di visibilità già il sistema operativo OS/400 fornisce gli strumenti di visione (PDM e SEU).
(mappa di presentazione della struttura fisica di un programma)
Modulo Parametri di ricerca
Rappresenta la funzione cardine del documentatore.
L’essenza della presente funzione è costituita da una serie di “filtri” che permettono di selezionare gli oggetti presenti nel repository sulla base di parametri immessi dall’utilizzatore.Le funzioni di selezione sono:
- per nome di libreria (corrispondente alla libreria AS/400 contenente i programmi oggetto)
- per sottosistema *
- per nome di programma
- per codice Azione Modulo Base (ex GDBA-ACG)
- per livello di chiamata
- per tipo di programma (RPG, COBOL, CLP)
- per descrizione (TEXT) del programma oggetto
- per nome di file contenuto nei programmi
- per nome di campo usato nei programmi oppure per attributi campo quali la lunghezza, i decimali e il tipo (funzione di “Where Used” **
* fare riferimento alla funzione di “Sottosistema”
** fare riferimento alla funzione di “Where Used (Impact Analisys)”
NB: tutti gli oggetti sono selezionabili per “nome parziale” o per “descrizione/text parziale”
Modulo Stampa Manuali
Il presente modulo consente la stampa dei dati presenti nel repository.
Si combina con i parametri di selezione (capitolo apposito) permettendo quindi di estrarre i soli oggetti (programmi, files e altro) che interessano realmente.E’ possibile produrre la documentazione su carta, su documento Microsoft Word oppure su file formattato RTF (Rich Text Formatted).E’ possibile ottenere la produzione della seguenti tipologie di documentazione (o una combinazione delle stesse):
- flussi I/O
- note e commenti funzionali ai pgm/sub routine
- report (ricostruzione tracciati)
- mappe (ricostruzione tracciati)
- relativi error message e note funzionali ai formati e mappe
- struttura del programma
- struttura dell’applicazione
- relazioni incrocio file/programmi
- relazioni incrocio programmi/programmi
- tracciati records data base files
- note e commenti funzionali applicati ai campi o alle tabelle d.b.
- tabella indici di valutazione dei programmi
(mappa per l’esecuzione della stampa manuali)
Modulo Matrici di Relazione
L’obiettivo della presente funzione è di consentire una visibilità sull’intero applicativo fornendo, in modo tabellare, informazioni di tipo “cross reference” scaturenti dagli oggetti files / programmi disponibili sul repository.
Anche per questa funzione si applica la selezione parametrica degli oggetti; solo gli oggetti che soddisfano le regole di selezione sono inclusi nell’elaborazione.
Il risultato è costituito dalla presentazione di una matrice bi-dimensionale (2500 x 2500 elementi) contenente il “cross-reference” di :
- files / programmi (da quali/quanti programmi i files sono utilizzati)
- programmi / programmi (da quali programmi altri programmi sono chiamati e il numero di chiamate totale).
- L’output è presentabile, così come ogni informazione gestita dalle altre funzioni, anche su report sia mediante una funzione topica (bottone “stampa”), sia tramite la funzione di “Stampa Moduli”.
(mappa cross reference programmi chiamati/chiamanti)
Modulo Analisi Attributi Files DB
L’obiettivo della presente funzione è di consentire la visibilità sugli attributi dei files appartenenti a una libreria per il tramite di una selezione da effettuare dalla lista dei files. Tale lista è creata dinamicamente sulla base dei parametri di selezione standard.
sull’intero applicativo fornendo, in modo tabellare, informazioni di tipo “cross reference” scaturenti dagli oggetti files / programmi disponibili sul repository.
Modulo Versioning: gestione storico sorgenti
Questo modulo accessorio (non fornito nella versione base) consente la storicizzazione delle versioni dei sorgenti al fine di permettere l’analisi e la visione dell’evoluzione.
Consente inoltre il confronto tra due o più versioni per mettere in evidenza le differenze prodotte da modifiche apportate nel tempo.
La presente funzione permette di identificare un gruppo di programmi, selezionabili dalla griglia parametri, ed assegnare ad essi un valore comune.
Questo consente di ottenere un criterio di aggregazione di programmi che, diversamente, non sarebbero immediatamente identificabili in quanto appartenenti tutti alla medesima area applicativa.
Il caso tipico consiste in lotti di programmi appartenenti a sotto sistemi applicativi distinti, tutti dislocati nella stessa libreria oggetti.
Where Used - Impact Analisys
Questa funzione è attiva a livello di:
- nomi di file
- nomi di campo
A livello di file: sono considerati solo i programmi che, utilizzando il file impostato come parametro (anche nome parziale), soddisfano la regola di estrazione
A livello di campo: l’apposita funzione permette di ricercare nel repository (anche congiuntamente ad altri parametri di selezione), tutti gli oggetti che utilizzano i campi impostati come parametri di selezione. I parametri possono essere:
- attributi di campo (lunghezza, decimali, tipo)
- nomi di campo (parziali o completi)
E’ inoltre evidenziato come il programma utilizza il campo; le condizioni sono:
- input
- input/alias
- output
- data structure
La funzione si applica anche ai campi di riferimento (Reference Field).
Sono elaborati i campi descritti sia esternamente, sia internamente al programma.
Marcatura programmi e statements
Questa sotto-funzione (componente di Where-Used) consente di marcare mediante appositi flag gli statements di programma (e i relativi programmi) affinché, successivamente alla ricerca, sia possibile ottenere visibilità (su video e su carta) di quali programmi modificare per eseguire l’aggiornamento richiesto.
Il criterio adottato consente inoltre di esprimere l’analisi di impatto mediante quantificazione (precisa) del numero di programmi e di statement da modificare.
Ricostruzione schermi e report (tracciati)
Il documentatore è fornito di una potente funzione di ricostruzione delle mappe video e dei printer layout definiti esternamente (DSPF e PRTF).
Ogni oggetto di natura “carattere” (quindi non GUI,GDDM,Barr Code) è ricostruito sulla base delle proprie specifiche origine. Tecniche speciali di programmazione quali:
- gestione di campi testo variabili con mess.file esterni (gestione multilingua)
- error message interni
- error message mediante message file sono risolte in automatico.
A carico del programmatore rimane solo il compito di combinare i vari “record” al fine di ricostruire mappe e report complessi (ovviamente solo se l’applicativo prevede l’uso di più record in sovrapposizione per ottenere mappe e report compositi).
Tracciati record data base file
Consente la presentazione dei tracciati record dei files usati dall’applicativo.
E’ di grande utilità nella gestione interattiva delle informazioni e nella preparazione del manuale in quanto permette di ricostruire gli effettivi tracciati record di files fisici, logici, join, le relative chiavi di ordinamento e le regole di Select/Omit.
Per ogni campo è inoltre evidenziato l’eventuale campo di riferimento (REFFLD).
Attributi dei DB Files
Consente la visione degli attributi operativi delle varie tabelle DB esistenti nelle librerie di data base selezionate per la documentazione.Tali attributi sono:
- tipologia tabella
- numero records
- dimensione in mega byte
- data creazione e utente
- data ultimo aggiornamento
- ecc.
E’ possibile inoltre conoscere le viste logiche di un Phisical File oppure il PF a cui la vista si riferisce (Display dei Referenced Files).
Import automatico informazioni
Successiva alla fase di Elaborazione, consente di importare automaticamente nel repository del PC le informazioni elaborate su AS/400.
In caso di riesecuzione dell’import, la funzione permette di sostituire le vecchie strutture con le nuove; eventuali inserti descrittivi delle funzioni (note funzionali aggiunte manualmente) sono salvaguardati e riagganciati alle nuove strutture.
Tramite Client Access è possibile effettuare l’import automaticamente leggendo le informazioni dal disco virtuale AS/400 (cartelle condivise).
Save & Load
La funzione SAVE consente di esportare dal data base in archivi ASCII le informazioni riferite alle applicazioni documentate e, con la funzione LOAD, di importare tali dati in un altro data base.
In pratica consente la replica automatica di un data base per motivi di allineamento qualora non sia attivata la modalità client-server.
Questa funzione non si applica ai Sorgenti.
Sorgenti
E’ possibile caricare sul repository del PC anche i sorgenti dell’applicativo da documentare.Questo consente di visionare i sorgenti in modalità off-line, senza cioè aver necessità di connessione con l’host.
Per motivi di sicurezza, non è possibile attivare le funzioni di SAVE e LOAD o altre di esportazione dati da PC.
Valutazione del software
Mediante gli indici di McCabe e Mills (complessità ciclomatica) e gli indici riferiti alla qualificazione delle istruzioni (complessità lineare), è possibile analizzare il codice sorgente dei programmi (packages) al fine di valutarne la qualità.
Link con documenti Office
E’ disponibile la funzione di link la quale consente di inserire dei riferimenti (percorsi) a documenti esterni scritti in Word.L’esecuzione del link consente di aprire contestualmente il documento esterno, completando quindi il problema della raccolta e gestione della documentazione esistente.
Siamo disponibili a fornire ogni informazione dettagliata sul servizio e sui relativi costi. La nostra sede di Milano è raggiungibile ai seguenti riferimenti:
tel 02 27001612 fax 02 2570081 oppure compilando il form nella pagina dei contatti
Informazioni Generali prodotto DocMaster - Documentatore Software AS/400
(i diritti di proprietà sul prodotto e sul presente documento sono riservati a Edoss Consulenze)
