* CICSVSAM DOC * ----------------------------------------------- 12/08/93

Documentazione della transazione VSAM per l'edit di files Vsam sotto CICS

---------------------------------------------------------------- Rel. 2.2




1)                      G E N E R A L I T A'


    La transazione 'VSAM' permette di visualizzare o aggiornare dei files
Vsam definiti in ambiente CICS, con un uso operativo simile a quello di un
semplice editor full screen, in cui ogni riga visualizzata corrisponde a
un record. Le operazioni che si possono compiere sono:
- visualizzazione normale o esadecimale
- ricerca di una stringa in Avanti/Indietro su tutto il file o solamente
  su un campo del file
- cancellazione di uno o piu' record (tranne che per files ESDS)
- aggiornamento di record in modo normale o esadecimale
- copia di uno o piu' record in un buffer
- aggiunta di uno o piu' record preventivamente salvati ed editati nel buffer
- inserimento (merge) di uno o piu' record preventivamente salvati nel buffer
  se il file e' un KSDS o un RRDS
- possibilita' di gestire files a lunghezza record variabile e in particolare
  cambiare la lunghezza record ad uno o piu' record esistenti (solo KSDS)
- visualizzare le caratteristiche del file come la posizione e l'offset
  della chiave o la chiave stessa per un KSDS, o come l'RBA per i files ESDS
  o KSDS, o come il numero relativo di record rispetto all'inizio del file
- posizionarsi direttamente su un record di cui si conosce la chiave
- aggiungere un record tappo ad un file vuoto

    Si puo' forzare l'accesso in read-only al file; si puo' infine tenere
un log di tutti gli aggiornamenti che vengono fatti sui files.




2)                         D E S C R I Z I O N E


    Si accede alla transazione come se fosse un comando, con la seguente
sintassi:

    VSAM nome-logico

dove per nome logico si intende il nome in FCT con il quale in CICS si
accede al file. Il nome logico e' quindi al massimo di 7 caratteri in VSE/SP
o di 8 caratteri in MVS. Se il file esiste, ha almeno un record ed e'
aperto, compare la schermata dell'editor con la quale si visualizzano i
primi 20 records. Schematizziamo tale schermata nel seguente modo:


    /------------------------------------------------------------------+
    ! Editor VSAM -  nomefile KSDS    12    32  Key: 10  2  VSAML0C1 A !
    !     0....+....!....+....!....+....!....+....!....+....!....+     !
    ! ---- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa              !
    ! ---- bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb              !
    ! ---- cccccccccccccccccccccccccccccccccccccccccccccc              !
    ! ---- dddddddddddddddddddddddddddddddddddddddddddddd              !
    ! ---- eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee              !
    ! ---- records ...................................                 !
    ! ---- records ...................................                 !
    ! ---- hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh              !
    ! ---- iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii              !
    ! ---- llllllllllllllllllllllllllllllllllllllllllllll              !
    ! ----                                                             !
    ! ==> _                                                            !
    ! 1=Help 2=Hex 3=Quit 4=Left 5=Right 6=Lrec 7=Ba 8=Fo 9=Top 10=Bot !
    +------------------------------------------------------------------/


    La schermata e' composta da:
- prima riga, con alcune caratteristiche del file in editing
- seconda riga, con il righello, in cui il numero a sinistra indica la
  posizione di partenza rispetto all'inizio record
- righe da 3 a 22 composte da 'prefix area' (la colonna di '----' sulla
  sinistra) su cui si possono dare comandi relativi al singolo record,
  e il record stesso, visualizzato a seconda dei casi in chiaro o in
  esadecimale
- riga 23, la 'command line' su cui si possono dare altri comandi
- riga 24, con un pro memoria dell'uso dei tasti funzione

    Spieghiamo in dettaglio il contenuto della prima linea:
- nome logico del file, che e' stato digitato all'innesco della transazione
- tipo di file: puo' essere ESDS, KSDS o RRDS
- numero relativo di record per il primo e l'ultimo record visualizzato
  nella attuale schermata; questi valori possono non essere presenti, il
  che indica che il programma e' stato impossibilitato a tenere il conto
  dei record che ci sono dall'inizio del file. Tipicamente questa perdita
  di posizionamento si ha quando e' stato dato un comando di accesso diretto
  ad un determinato record, come col comando KEY o BOTTOM. Per ripristinare
  il conto e' necessario ripartire da inizio file col comando TOP.
  Si noti che questo conteggio di record e' disponibile per tutti e tre
  i tipi di file Vsam e che in particolare per i file RRDS puo' non
  coincidere col Relative Record Number di ciascun record, in quanto la
  transazione conta solo i record effettivamente esistenti nel file mentre
  il Vsam salta il numero d'ordine di un record che e' stato cancellato.
- lunghezza e posizione (offset) della chiave di un file KSDS; questi valori
  sono uguali a 0 per un ESDS o un RRDS.
- nome del buffer gestito dal programma; questo buffer e' materialmente una
  coda di Temporary Storage il cui nome (se non viene cambiato con l'apposito
  comando) e' composto per i primi quattro caratteri da 'VSAM' e per i secondi
  quattro dal nome del terminale su cui si sta lavorando.
- Direzione attuale di spostamento: puo' essere la lettera 'A' per indicare
  'Avanti' oppure 'I' per indicare 'Indietro'. La conoscenza di questa
  direzione e' importante per il comando di ricerca di stringa in quanto e'
  quella assunta dalla ricerca stessa. Per impostare la direzione voluta si
  tenga presente che 'PF8' e 'TOP' impostano 'Avanti' e 'PF7' e 'BOTTOM'
  impostano 'Indietro'.

    Al suo innesco, la transazione accede ai record in Read-Only, e quindi,
a differenza di un normale editor, i campi che rappresentano i record
visualizzati non sono digitabili; vedremo poi in che modo aggiornarli.


    I comandi che si possono scrivere in 'prefix area', accanto al record
su cui si vuole che agiscano, sono i seguenti:
'Q'  : visualizza la chiave di quel record, che puo' essere:
       il campo chiave vero e proprio per un KSDS
       l'RBA (Relative Byte Address) del record per un file ESDS
       l'RRN (Relative Record Number) del record per un file RRDS
'/'  : fa diventare quel record il primo record della schermata
'C'  : copia il record nel buffer di temporary storage attualmente definito
'D'  : cancella il record dal file, purche' non sia un ESDS
       di ogni record cancellato, viene tenuta traccia nel file di log
       della transazione, di nome VSAMLOG.
'.n' : mette una label corrispondente al record voluto; accanto al punto
       (.) si mettera' una cifra da 1 a 9 che contraddistingue la label;
       per riposizionarsi sul record voluto in un qualsiasi altro momento
       si digitera' ".n" in command line, con 'n' corrispondente alla
       cifra voluta.


    Si puo' dare il comando di copia in buffer per un intero blocco di
record, scrivendo 'CC' di fianco al record di inizio e 'CC' di fianco al
record di fine blocco. In ogni caso, comandi di copia successivi accodano
i record nel buffer a quelli precedente copiati, fino a che il buffer non
viene esplicitamente svuotato con l'apposito comando. Il buffer puo' a
sua volta venire editato col comando 'EDTS', come si vedra' piu' avanti.
Non e' disponibile il comando di blocco per la cancellazione di record:
ogni record deve percio' essere cancellato singolarmente con una 'D'.


    I comandi che si possono scrivere in 'command line' sono in parte una
duplicazione dei tasti funzione:

    Help     (PF1) : richiama la schermata di Help, con un sunto di tutti
                     i comandi
    Hex On/Off(PF2): cambia il modo di visualizzazione in esadecimale (On)
                     e toglie l'esadecimale se presente (Off)
    Quit     (PF3) : termina il programma; questo comando (e il corrispon-
                     dente tasto funzione) si puo' usare in fase di Update
                     del file per abbandonare l'aggiornamento senza che
                     alcuna modifica venga scritta
    Forward  (PF8) : avanza di una pagina video nella visualizzazione
                     Si puo' indicare anche il numero di pagine di spostamento
    Backward (PF7) : va indietro di una pagina video nella visualizzazione
                     Si puo' indicare anche il numero di pagine di spostamento
    Right    (PF5) : sposta la visualizzazione a destra per i record di
                     lunghezza tale da non poter essere contenuti nello
                     schermo; lo spostamento e' di 40 caratteri normalmente,
                     di 20 caratteri se si e' in visualizzazione esadecimale;
                     in linea comandi si puo' specificare di fianco a 'Right'
                     il numero di colonne di cui ci si vuol spostare: questo
                     numero viene in ogni caso troncato dal programma ad un
                     multiplo di 10
    Left     (PF4) : sposta la visualizzazione a sinistra, con le stesse
                     modalita' del comando 'Right'
             (PF6) : visualizza in prefix area la lunghezza di ciascun record;
                     se si e' in Update cambiando le lunghezze visualizzate si
                     puo' cambiare la lunghezza di un record in un file defi-
                     nito a lunghezza variabile. Si tenga presente comunque
                     che in Vsam ci sono le seguenti limitazioni:
                     - un file RRDS non puo essere a lunghezza variabile
                     - non puo' essere modificata la lunghezza record di un
                       record gia' scritto in un ESDS, anche se l'ESDS e' a
                       record variabili
    Top      (PF9) : si posiziona a inizio file
    Bottom   (PF10): si posiziona a fine   file

    I comandi rimanenti sono anche i piu' importanti:

    Update : passa da modo Read-only a modo Update. I campi di visualizza-
             zione record diventano digitabili e ciascun record presente
             nella schermata e' modificabile liberamente. Finche' si rimane
             in modo Update sono disabilitati tutti i comandi che cambiano
             il posizionamento nel file, ossia non funzionano PF7, PF8, PF9
             PF10 e il comando di ricerca di stringa. Inoltre, non e'
             possibile usare il comando 'Zoom' per cambiare modo di visua-
             lizzazione.
             Funzionano invece il posizionamento a destra e a sinistra (PF4
             e PF5) e in particolare il cambio di visualizzazione in esa-
             decimale: in questo caso la modifica dei record dovra' essere
             scritta in cifre esadecimali. Si noti che in visualizzazione
             normale e' rappresentato come punto (.) qualunque carattere
             del record che abbia un valore non visualizzabile; tipicamente
             saranno modificati in esadecimale i campi numerici in
             rappresentazione packed o binaria.
             Qualunque modifica venga fatta ai record visualizzati viene
             fatta solo in memoria senza alcun aggiornamento del file;
             per abbandonare le modifiche fatte si fara' Quit (o PF3) mentre
             per scriverle permanentemente si dara' il comando 'File' (o
             ancora 'Update', che qui e' un sinonimo di 'File'); un
             messaggio indica quanti record sono stati riscritti con
             successo. All'uscita del modo Update si ritorna in modo Read
             Only e i comandi di posizionamento vengono riattivati.
             Non e' possibile editare record piu' lunghi di 2000 bytes
             in questo modo di visualizzazione; per farlo si dovra'
             passare in modo 'Zoom' e quindi aggiornare il record.
       Note: - anche i record di un ESDS possono essere aggiornati
             - se e' visualizzata la lunghezza record (PF6) e il file e' un
               KSDS a lunghezza variabile, anche la  lunghezza di ciascun
               record puo' essere modificata
             - la cancellazione di record e' disabilitata in modo Update
             - di ogni record aggiornato con successo viene tenuta traccia
               in VSAMLOG.

    Zoom   : cambia il modo di visualizzazione passando da 20 record per
             schermata a un solo record, con i seguenti vantaggi:
             . il record e' visualizzato contemporaneamente sia in
               esadecimale che in chiaro
             . in questo modo di visualizzazione il programma supporta
               record piu' lunghi di 2000 bytes

             Lo schermo si presenta nel seguente modo:


    /------------------------------------------------------------------+
    ! Editor VSAM -  nomefile KSDS    12    32  Key: 10  2  VSAML0C1 A !
    !                                                                  !
    ! ---- 1 . . .  + . . .  ! . . .  + . . .        ....+....!....+...!
    ! 0000 aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa     0 AAAAAAAAAAAAAAAAAA!
    ! 0014 bbbbbbbb bbbbbbbb bbbbbbbb bbbbbbbb    20 BBBBBBBBBBBBBBBBBB!
    ! 0028 cccccccc cccccccc cccccccc cccccccc    40 CCCCCCCCCCCCCCCCCC!
    ! 003C dddddddd dddddddd dddddddd dddddddd    60 DDDDDDDDDDDDDDDDDD!
    ! 0050 eeeeeeee eeeeeeee eeeeeeee eeeeeeee    80 EEEEEEEEEEEEEEEEEE!
    !                                                                  !
    !                                                                  !
    !                                                                  !
    !                                                                  !
    ! ==> _                                                            !
    ! 1=Help 2=Hex 3=Quit 4=Left 5=Right 6=LRec 7=Ba 8=Fo 9=Top 10=Bot !
    +------------------------------------------------------------------/


    Nella parte sinistra dello schermo il record e' mostrato in esadecimale,
    con a sinistra l'offset (sempre in esadecimale) rispetto all'inizio
    del record; nella parte destra il record e' in chiaro, con l'offset
    in decimale. Ogni riga mostra 20 caratteri del record: una schermata
    completa puo' contenere al massimo 360 caratteri visualizzati in
    questo modo.
    La prefix area continua ad esistere anche qui: e' il campo '----'
    digitabile immediatamente a sinistra del righello esadecimale: la
    sua funzione e' invariata e puo' essere usata per scrivere gli stessi
    comandi di prima, tranne il comando 'Q'.
    Nella command line si possono ancora dare gli stessi comandi di prima;
    lo stesso dicasi per i tasti funzione, che hanno queste varianti:
    PF7 / PF8 vanno indietro / avanti all'interno del record, se questo
              occupa piu' di una schermata; passano al record precedente
              / successivo se il record e' piccolo o se in ogni caso si
              e' alla fine della visualizzazione del record. (Lo stesso
              dicasi per i comandi corrispondenti 'Backward n' e
              'Forward n')
              Nota: se la direzione di PF7/PF8 e' diversa da quella
              attuale, la pressione del primo PF cambia la direzione
              mantenendo lo stesso record, la seconda cambia effettivamente
              il record
    PF2  non ha alcun effetto
    Anche qui il comando 'U' permette di passare in update del record,
    disabilitando le funzioni di posizionamento su altri record; si puo'
    editare indifferentemente sia l'esadecimale che lo scritto in chiaro;
    si scriva di nuovo 'U' (o 'File') per registrare le variazioni.

    Per ritornare alla visualizzazione normale si scrivera' di nuovo
    'Zoom' in command line.


    Get    : aggiunge al file i record attualmente presenti nel buffer.
             Il comportamento del programma e' diverso a seconda del
             tipo di file che si sta editando:
             ESDS : i record vengono accodati in fondo al file nell'ordine
                    che avevano nel buffer
             KSDS : i record vengono scritti nella posizione corrispondente
                    alla chiave di ciascuno di essi; se esistesse gia' un
                    record con quella chiave, il record viene scartato; in
                    questo caso si ha una spece di 'merge' tra il file
                    rappresentato dal buffer e il KSDS.
             RRDS : i record vengono accodati in fondo al file; e' anche
                    possibile per i RRDS specificare accanto al comando Get
                    il numero di record (il Relative Record Number) a partire
                    dal quale si vuole che vengano inseriti i record: in
                    questo caso i record vengono scartati se la posizione
                    che assumerebbero corrisponde a un record gia' presente.
                    In altre parole, si possono inserire record in mezzo ad
                    un RRDS purche' rimpiazzino dei record precedentemente
                    cancellati. Non si puo' inserire record a partire dal
                    record numero 1.
       Note: A conclusione del comando compare un messaggio che indica il
               numero di record inseriti e il numero di record scartati
             Per ogni tipo di file:
             - se il file permette record variabili, viene conservata la
               lunghezza che il record aveva nel buffer;
             - se il record nel buffer ha lunghezza maggiore del massimo
               consentito per quel file, viene troncato;
             - se il record nel buffer ha lunghezza minore del minimo
               consentito per quel file, viengono aggiunti zeri binari a
               fine record.
             Il comando Get lascia inalterato il buffer; quindi, se necessario,
               il buffer va cancellato in seguito col comando Purge.
             Ogni record aggiunto con successo viene registrato in VSAMLOG.


    Key    : Posizionamento diretto su un determinato record.
             La sintassi del comando e' diversa a seconda del tipo di
             file che si sta editando:
             ESDS : Key rba
                    si posiziona direttamente a partire dal record che
                    ha l'RBA specificato (l'RBA deve essere valido, cioe'
                    deve corrispondere effettivamente ad un inizio record)
             KSDS : Key /chiave/
                    si posiziona a partire dal record che ha la chiave
                    specificata. Si noti che:
                    - puo' essere specificata una chiave parziale
                    - se si e' in visualizzazione esadecimale, tra le due
                      barre il valore specificato deve essere esadecimale
             RRDS : Key rrn
                    si posiziona direttamente a partire dal record che
                    ha il Relative Record Number specificato
                    Se il record e' stato cancellato, si posiziona a
                    partire da quello immediatamente successivo

    EDTS   : richiama l'editor di code di Temporary Storage per visualizzare
             ed eventualmente cambiare i record accumulati nel buffer.
             Questo editor funziona in modo simile alla transazione 'VSAM',
             e' un poco piu' flessibile ed ha piu' comandi di editing veri e
             propri. Per il dettaglio rimandiamo alla documentazione di EDTS.
             Durante la cancellazione di linee nel buffer, puo' capitare che
             in fondo al buffer rimangano delle linee spurie non cancellabili
             composte da un byte di valore esadecimale '00': cio' e' dovuto
             alla natura stessa della Temporary Storage che non permette la
             cancellazione di singoli record; queste linee spurie saranno
             comunque ignorate dal comando Get.
             Se si da il comando EDTS e il buffer e' vuoto, viene inserito
             nel buffer un record lungo 80 pieno di spazi.
             Accanto al comando EDTS si puo' specificare il nome di una coda
             di Temporary Storage voluta se non si vuole editare la coda che
             rappresenta il buffer della transazione; comunque, finche' non
             verra' cambiato il nome del buffer stesso associandolo ad una
             altra coda di TS, i comandi come Get useranno solo la coda di
             default.
             Una volta terminato l'editing dei record nel buffer, dare PF3
             per uscire da EDTS e ritornare alla transazione VSAM.

    Purge  : cancella il contenuto della coda di Temporary Storage usata
             come buffer.

    Buffer nome-coda-TS : cambia nome alla coda di TS che rappresenta il
             buffer della transazione; comandi come 'Get' o il comando di
             copia in prefix area leggeranno e scriveranno in questa nuova
             coda di Temporary Storage.

    Zone col1 col2 : definisce un campo che inizia nella prima colonna
             specificata e che finisce alla seconda colonna specificata
             (vedi i caratteri '<' e '>' sul righello). Questa definizione
             restringe la ricerca quando si usa il comando '/.../'.
             Per default, la ricerca e' sempre su tutto il record.

    /stringa/ : ricerca la stringa specificata nella direzione indicata da
             'A' o 'I'. Se e' stato precedentemente specificato 'Zone' la
             ricerca avviene sul campo indicato, altrimenti avviene su tutto
             il record. I record in cui la stringa e' stata trovata sono
             evidenziati con '===>' in prefix area; se la stringa non viene
             trovata la ricerca finisce a fine file (o a inizio file se la
             ricerca era all'indietro). Se il comando viene digitato quando
             si e' in visione esadecimale, si intende che la stringa tra le
             due barre deve essere scritta in esadecimale.
             La seconda barra di chiusura della stringa non puo' essere
             omessa. Se tra i caratteri della stringa da ricercare vi e'
             proprio la barra (/), allora la stringa deve essere scritta
             in esadecimale per evitare ambiguita'. Usare questo comando
             con cautela per i file molto grossi, perche' puo' essere di
             lunga durata e nel contempo puo' penalizzare pesantemente le
             altre transazioni concorrenti.
             Per limitare la pesantezza del comando, esiste un limite al
             numero di records che puo' essere letto in una volta: se
             la stringa cercata non e' stata trovata entro questo numero,
             la ricerca viene interrotta mostrando un messaggio. A questo
             punto pero' la ricerca puo' essere comunque essere proseguita
             con 'FIND'. Il limite di default e' 5000 record: puo' essere
             variato col comando 'SCANLIM'.
             Si tenga presente che la ricerca fatta non e' indifferente
             al maiuscolo / minuscolo: cio' che si digita in minuscolo
             tra le barre che delimitano la stringa sara' esattamente
             cio' che viene cercato.

    Find   : prosegue la ricerca precedentemente impostata con /..../ nella
             zona e nella direzione presente attualmente.

    .n     : posiziona la visualizzazione a partire dal record corrispon-
             dente alla label precedentemente definita in 'prefix area';
             'n' puo' essere una cifra da 1 a 9.

    Reset  : cancella le label da 1 a 9 precedentemente memorizzate.

    VSAM nome-file : la transazione VSAM permette il richiamo di se stessa
             per editare contemporaneamente un secondo file.

    Scanlim  n  : definisce il numero massimo di record che puo' essere
             letto in una ricerca con /.../ o con 'FIND' prima della
             interruzione; 'n' puo' essere un numero tra 100 e 1000000.

    ABEND  : forza un abend della transazione; lo scopo puo' essere quello
             di controaggiornare un file che ci si e' accorti di avere
             modificato in maniera errata; ovviamente questo file dovra'
             essere definito controaggiornabile a livello di tabella FCT.
             Altrettanto ovviamente, una volta terminata la transazione
             (con PF3) il file non e' piu' controaggiornabile.
             Nel log della transazione (il file VSAMLOG, che non e'
             a sua volta controaggiornabile, dal momento che e' un ESDS)
             vengono registrate sia le modifiche che sono state contro-
             aggiornate, sia il fatto che e' stato richiesto un abend
             dall'utente. In VSAMLOG non si ha traccia di altri eventuali
             abend che dovessero capitare alla transazione.


    Note: ognuno dei comandi di command line puo' essere abbreviato fino
ad un'unica lettera purche' non sorgano ambiguita' con altri comandi;
esempi di abbreviazioni minime:
F  = Forward  ;   FI = Find   ;   FIL = File
Il comando 'ABEND' va invece scritto per intero.



    Descriviamo ora l'uso di alcuni parametri opzionali che possono
essere usati in determinate situazioni.

    - Files REMOTI.

    Supponiamo che si voglia usare VSAM con dei file che sono definiti
come remoti al CICS, ossia che sono effettivamente controllati da un CICS
diverso da quello su cui si sta lavorando.
    In questo caso, la transazione VSAM non e' in grado di stabilire il
tipo di file e le caratteristiche della chiave (nel caso che il file
sia un KSDS). Il comando andra' quindi scritto nel seguente modo:

                      +                       +
                      ! ESDS                  !
    VSAM nome-logico  ! KSDS  len-key  offset !
                      ! RRDS                  !
                      +                       +

Se il file remoto e' un KSDS e' obbligatorio specificare la lunghezza
in bytes della chiave (len-key) mentre se l'offset della chiave viene
omesso, si assume che sia uguale a 0 (ossia che la chiave parta da
inizio record).


    - Files vuoti.

NEW e ADD sono sinonimi; poiche' non e' possibile andare in edit di un
         file vuoto, col parametro ADD o NEW il programma prima scrive nel
         file un record tappo, poi va in edit di esso. Questo record potra'
         naturalmente essere cambiato o cancellato in seguito.
         Questo parametro e' ignorato se nel file esiste almeno un record.


    - Accesso in sola lettura.

RO       accede al file in Read Only e non permette aggiornamenti di sorta.





3)       E D I T     D I     F I L E S    V S A M     N O N    C I C S


    Qui intendiamo la possibilita' di andare in edit con la transazione
VSAM di un file che non e' stato preventivamente definito in FCT e che
percio' non e' usato da nessun programma applicativo CICS, decidendo sul
momento quale e' l'effettivo nome fisico di questo file.
    Questo e' possibile solo in ambiente MVS usando la allocazione dinamica
dei file a disposizione in tutte le versioni di CICS.
    Per usare l'allocazione dinamica si deve pero' comunque appoggiarsi
su una definizione di file in FCT preesistente, per cui si consiglia la
seguente implementazione:

- definire in FCT uno o piu' file fittizi di appoggio con nomi non esistenti
  e caratteristiche generiche valide per tutti i file Vsam o quasi;
  per esempio:

        DFHFCT  TYPE=DATASET,
                DATASET=DUMMY1,
                DSNAME=DUMMY1.DUMMY1,
                FILSTAT=(CLOSED,DISABLED)

- non mettere le DD corrispondenti nel job di partenza del CICS
- lanciare la transazione in questa forma:

        VSAM DUMMY1 nome.fisico.file

  in cui DUMMY1 e' il file fittizio di appoggio in FCT e 'nome.fisico.file'
  e' il nome del dataset Vsam che si vuole editare.
  La transazione VSAM in questo caso agisce come segue:
  . se il file DUMMY1 e' chiuso e disabilitato inserisce il nome fisico
    specificato come definizione CICS del dataset name associato; in altre
    parole viene dinamicamente cambiato il parametro DSNAME della FCT
    (cosa che si puo' comunque fare col CEMT)
  . abilita il file e lo apre
  . va in edit del file nel modo solito

    Il cambio di definizione del nome fisico puo' avvenire solo se il
file e' chiuso e disabilitato; se il CICS riscontra altri errori nella
allocazione dinamica del file, questi vengono riportati da VSAM.
Al termine dell'uso di VSAM, se e' stata usata la allocazione dinamica,
il file viene automaticamente chiuso e disabilitato, in modo che possa
essere di nuovo usato per l'allocazione e l'edit di un'altro file.
    Se quando si lancia VSAM si aggiunge anche il parametro 'RO' per
l'accesso in Read-Only, oltre che a impostare il nome fisico del file
la transazione cambia anche le possibilita' di accesso, togliendovi
'Del', 'Add' e 'Upd' in modo tale che il file e' in Read-Only non
solo dal punto di vista della transazione ma anche dal punto di vista
del CICS. Questo consente di accedere da un CICS ad un file che e'
correntemente aperto da un'altro CICS.
    Si puo' anche accedere dinamicamente a file che sono definiti nello
stesso CICS; cio' potrebbe servire per accedere a livello VSAM dei file
che in realta' sono data base DL1.

    Si e' detto che in VSE/SP non c'e' allocazione dinamica; in realta'
per editare estemporaneamente un file non appartenente al CICS si puo'
aggirare l'ostacolo in questo modo:

- definire in FCT un file fittizio di appoggio con nomi non esistenti
  cosi' come si e' detto per il CICS MVS
- non mettere la DLBL corrispondente nel job di partenza del CICS
- prima di andare nel CICS per editare con VSAM il file voluto, lanciare
  un job che aggiunge in standard label la DLBL che lega il file fittizio
  in FCT col nome fisico del file voluto; questa operazione si puo' fare
  tranquillamente a CICS su'.
- andare in CICS, aprire il file col CEMT: poiche' manca la DLBL nel job,
  il CICS usera' quella in standard label ed aprira' correttamente il file
- editare il file con VSAM
- a fine edit, lanciare un'altro job per cancellare la DLBL che e' stata
  aggiunta in standard label, per avere una situazione pulita.

    Come si vede, il procedimento e' piuttosto macchinoso; puo' essere
comunque usato quando l'unica alternativa sarebbe fare un print batch del
file o addirittura un programma ad hoc per intervenire in aggiornamento.






4)                           E S E M P I


    Oltre agli usi ovvi di VSAM per funzioni di controllo e manutenzione
dei files sotto CICS, il programma si presta bene alla creazione di casi di
prova utili in fase di sviluppo delle applicazioni sotto CICS.


  - Si vuole duplicare un record di un file KSDS, ovviamente cambiandogli
chiave ma mantenendo inalterati gli altri campi:
  . Copiare nel buffer il record da duplicare con 'C' in prefix area
  . Con il comando EDTS, cambiare opportunamente il campo chiave al record
salvato nel buffer, in modo tale che la chiave faccia assumere al record
la posizione voluta
  . Dopo che si e' modificato il record, uscire da EDTS con PF3
  . Dare 'GET' per scrivere il nuovo record nel file
  . Pulire eventualmente il buffer con 'PURGE' prima di fare altre
operazioni.
Note: se andiamo in update direttamente nel campo chiave di un record
      di un KSDS, quando salviamo le modifiche ci prendiamo un errore
      'ILLOGIC' (e con ragione!).
      in un ESDS un record non e' duplicabile perche' GET accoda sempre
      in un RRDS un record e' duplicabile se il record successivo e' stato
         cancellato: in questo caso dare 'GET n' per inserire il record,
         dove 'n' e' la posizione libera.


  - In un file KSDS appena definito e quindi vuoto si vogliono mettere dei
 record prendendoli da altri due file dello stesso CICS:
  . Accedere al file vuoto con 'NEW': qui verra' creato un record tappo.
  . Accedere al primo file e copiare nel buffer i record voluti con 'C' in
prefix area.
  . Accedere al secondo file e copiare anche qui i record voluti
  . Accedere al buffer con EDTS e modificare il campo chiave in modo
che i record assumano l'ordine voluto
  . Dare 'Get' per scrivere i record nel file
  . Cancellare il record tappo che in questo caso aveva solo la funzione
di rendere il file accessibile all'editor per le operazioni successive
  . Pulire eventualmente il buffer con PURGE.
Note: usando l'allocazione dinamica del CICS MVS questi files non sono
necessariamente definiti al CICS nel quale si lavora; usando la allocazione
dinamica in Read Only potrebbero addirittura essere contemporaneamente
aperti in un'altro CICS.


  - Il transfer file PC-Host IND$ in ambiente CICS MVS e' in grado di
trasferire solo da PC a coda di Temporary storage; si vuole fare il
trasferimento da coda di TS a file Vsam:
  . Accedere direttamente alla coda di TS col comando "EDTS nome-coda",
che si puo' dare anche in CICS indipendentemente dalla transazione VSAM;
qui cancellare il primo record, che e' una intestazione prodotta dal
transfer file
  . Entrare in edit del file Vsam
  . Cambiare il nome del buffer mettendogli il nome della coda di TS
voluta (comando "BUFFER nome-coda")
  . Dare il comando GET per importare la coda nel file
  . Cancellare eventualmente la coda col comando PURGE


  - Si vuole verificare l'integrita' fisica di un file Vsam, ossia che
ogni record del file sia fisicamente leggibile dal disco.
  . Andare in edit del file e ricercare una stringa che si sa che non
esiste: il programma leggera' il file dall'inizio alla fine senza trovarla;
se il programma conclude la lettura senza problemi ogni record e' leggibile
e quindi il file e' integro.
Attenzione: se il file e' grosso questa operazione e' di lunga durata e in
pratica pianta il CICS.


  - Si vuole sapere quanti record ha un file
  . Andare in edit del file e ricercare una stringa che si sa che non
esiste: il programma leggera' il file dall'inizio alla fine senza trovarla;
la prima riga della schermata indica il numero d'ordine dell'ultimo record.
Attenzione: questo non e' certamente il metodo piu' efficente per conoscere
il numero di record di un file.







5)                     I N S T A L L A Z I O N E


    La transazione si compone di un unico eseguibile di nome CICSVSAM.
Benche' non necessario, e' consigliabile avere anche il programma
CICSEDTS per l'implementazione del comando EDTS.
Dovra' percio' essere creata una entrata in PCT per il Transid 'VSAM' e
una entrata in PPT per il programma CICSVSAM; opzionalmente una entrata
in FCT per il file di log 'VSAMLOG'.
    Il programma in PPT deve essere definito come programma assembler.
Il transid puo' essere scelto a piacere come anche il nome del programma,
purche' ovviamente in PCT il legame tra codice transazione e programma
corrispondente sia corretto. Si tenga pero' presente che se viene
cambiato il nome del programma la transazione non puo' piu' chiamare se
stessa col comando 'VSAM nome-file'.
Non si puo invece cambiare il nome logico del file di log 'VSAMLOG' a
meno che non si faccia una zap direttamente sull'eseguibile.
    Il file di log e' un ESDS con record lunghi 80; tutto il resto e'
a piacere. Il file non necessita di inizializzazione; verra' usato da VSAM
solo se esiste ed e' aperto; si consiglia di usarlo in ambiente di
produzione per tenere sotto controllo accessi indiscriminati.
In un record del log vengono registrati: giorno, ora, terminale, nome
utente (oppure nome del CICS, se l'utente non ha fatto SIgn-On), nome
file, tipo file, tipo di aggiornamento e chiave del record aggiornato.
Il log si puo' visualizzare con la stessa transazione VSAM; il suo
contenuto pero' non puo' essere variato.
    Il programma e' scritto in assembler Command Level in maniera
conversazionale; gira da partire dal CICS 1.7 fino al CICS Versione 3.
E' disponibile in ambiente VSE/SP e in MVS.


Esempi di codifica delle tabelle:

PCT :
         DFHPCT   TYPE=ENTRY,
               TRANSID=VSAM,
               RSL=PUBLIC,
               PROGRAM=CICSVSAM


PPT :
         DFHPPT   TYPE=ENTRY,PROGRAM=CICSVSAM,RSL=PUBLIC


    La sola cosa importante e' definire come linguaggio l'Assembler (che
e' il default nelle tabelle tradizionali ma non in CEDA).


FCT :
         DFHFCT TYPE=DATASET,RSL=PUBLIC,
               DATASET=VSAMLOG,
               ACCMETH=VSAM,
               SERVREQ=(UPDATE,BROWSE,ADD,READ,DELETE),
               FILSTAT=CLOSED,
               LSRPOOL=NONE,
               LOG=NO,
               RECFORM=(FIXED,BLOCKED),
               STRNO=1


Delete / Define del file VSAMLOG:

         DELETE (vsam.log) CLUSTER PURGE CATALOG(nome.catalogo)
         DEFINE CLUSTER (                                  -
                NAME(vsam.log)                             -
                NONINDEXED                                 -
                REUSE                                      -
                TRACKS(5 5)                                -
                RECORDSIZE(80 80)                          -
                SHAREOPTIONS(2)                            -
                VOLUMES(nomevol)                           -
                )                                          -
              DATA (                                       -
                NAME(vsam.log.data)                        -
                CISZ(1024)                                 -
                )                                          -
              CATALOG(nome.catalogo)



    Il programma potrebbe essere richiamato direttamente da un altro
programma con un EXEC CICS LINK, passandogli i parametri in COMMAREA,
invece che essere richiamato a video dall'operatore.
La COMMAREA puo' essere di lunghezza qualsiasi fino a un massimo di 100 bytes.
In pratica, se trascuriamo i paramerti opzionali, in COMMAREA verra'
passato solo il nome logico del file da editare, per cui una lunghezza di
8 e' piu' che sufficente.

    Il programma ha i seguenti limiti:
- il terminale CICS deve essere un 3270 standard 80x24
- non gestisce i files Linear, oltre che ai files Nonvsam, in MVS;
  in VSE/SP e' comunque in grado di gestire i file Sam-feature, poiche'
  vengono visti come ESDS.


    Program History:

- Versione 1.0 - Programma scritto in COBOL, senza la possibilita' di fare
                 aggiornamenti ai record. Bleah !!
- Versione 2.0 - Prima versione in assembler, con possibilita' di fare
                 aggiornamenti. E' obbligatorio specificare il tipo di file;
                 ha un algoritmo euristico (fallibile!) per determinare
                 l'offset della chiave di un KSDS; funziona anche con CICS
                 pre 1.7 e con files remoti. E' solo DOS/VSE.
- Versione 2.1 - Utilizza EXEC CICS INQUIRE per determinare le caratteris-
                 tiche del file ma non gestisce i files remoti.
                 Disponibili versioni DOS e MVS, con CICS da 1.7 a 3.3.
- Versione 2.2 - Gestisce i file remoti; aggiunte le label '.n'  e i comandi
                 SCANLIM, RESET; con il nuovo comando ZOOM gestisce un modo
                 di visualizzazione a record singolo e contemporaneamente
                 record piu' lunghi di 2000. Sono stati corretti alcuni bug.



