* EXECIOVS DOC * ----------------------------------------------- 20/02/93

  Documentazione del programma EXECIOVS di interfaccia tra VSAM e REXX

---------------------------------------------------------------- Rel. 1.0




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


    Il programma EXECIOVS permette di utilizzare files VSAM da programmi
scritti in linguaggio REXX in ambiente TSO/MVS.
Mentre il comando 'EXECIO' del linguaggio REXX standard, permette di
accedere a file sequenziali o a membri di librerie partitioned, il
comando EXECIOVS, pur avendo un uso simile ad EXECIO, consente ad un
programma scritto in REXX di leggere, scrivere e aggiornare uno o piu'
record di un file VSAM.




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


    La sintassi completa del programma EXECIOVS e' la seguente:

                  +        +
           +   +  ! DISKR  !
 EXECIOVS  ! n !  ! DISKW  ! ddname [ chiave ] [([V] STEM array. [FINIS]]
           ! * !  ! DISKU  !
           +   +  ! DISKD  !
                  + DISKWU +

 n   indica il numero di record da elaborare
 *   elabora tutti o una parte dei record del file, a seconda del tipo di
     accesso e del tipo di file Vsam, come si vedra' piu' avanti

 DISKR  accede al file in lettura
 DISKW  accede al file in scrittura, aggiungendo record al file
 DISKU  accede al file in aggiornamento di record gia' esistenti
 DISKD  accede al file in cancellazione di un record
 DISKWU accede al file in scrittura o indifferentemente in aggiornamento

 ddname e' il nome logico con il quale viene acceduto il file vsam; cio'
        implica che prima del comando EXECIOVS dovra' essere dato il
        comando ALLOC opportuno per legare il nome logico interno al
        programma REXX al nome fisico col quale il file e' catalogato;
        per esempio:
            ALLOC FILE(ddname) DATA('nome.fisico.file') SHR

 chiave  e' la chiave per l'accesso diretto ai record del file e assume
        un significato ed una scrittura diversa a seconda del tipo di file:

        KSDS: se e' racchiuso tra apici (') rappresenta il valore della
              chiave (anche parziale) con la quale accedere al file in
              lettura o in cancellazione; se non e' racchiuso tra apici
              deve essere un nome valido di una variabile REXX che a sua
              volta contiene la chiave di accesso al file;
        ESDS: se rappresenta un numero, questo deve essere un valido RBA
              per l'accesso diretto ad un record del file in lettura;
              se non e' un numero, deve essere il nome valido di una
              variabile REXX che a sua volta contiene l'RBA di accesso
              al file;
        RRDS: se rappresenta un numero, questo deve essere un RRN (Relative
              Record Number) per l'accesso diretto ad un record del file
              in lettura o in cancellazione; se non e' un numero, deve
              essere il nome valido di una variabile REXX che a sua volta
              contiene l'RBA di accesso al file;

        Questo parametro viene ignorato per l'accesso in scrittura o in
        aggiornamento (DISKW, DISU e DISKWU), e' invece obbligatorio per
        l'accesso in cancellazione (DISKD) per specificare il record da
        cancellare. Se per l'accesso in lettura il parametro 'chiave'
        viene omesso, il file viene letto a partire dall'inizio; se in
        lettura di un KSDS viene specificata una chiave parziale e se
        viene specificato '*' come numero di record da leggere, vengono
        letti tutti i record con quella chiave parziale (piu' quello
        immediatamente successivo). Se in lettura il parametro 'chiave'
        viene omesso ed e' specificato '*' come numero di record, viene
        letto l'intero file.





    I parametri seguenti, separati dai precedenti da una parentesi aperta,
indicano quali variabili REXX devono essere interfacciate e come.

V       e' opzionale ed e' da usare solo per i file a record di lunghezza
        variabile ESDS o KSDS e indica che deve essere scritto un
        record con lunghezza pari alla lunghezza della variabile REXX
        da cui il record viene preso; viceversa in lettura la variabile
        REXX avra' lunghezza pari alla lunghezza del record.
        Se il file e' a record variabili e viene omesso il parametro 'V',
        viene scritto un record pari alla lunghezza massima.
        Normalmente in scrittura di file a lunghezza fissa, se la variabile
        REXX e' piu' lunga della lunghezza record, questa viene troncata,
        mentre se e' piu' corta, vengono aggiunti degli zeri binari.


STEM array.  indica in quali variabili REXX devono essere letti o scritti
        i record rispettivamente da scrivere o leggere dal file Vsam.
        Il vettore (variabile Stem, nella terminologia REXX) acceduto dal
        programma e' dato da 'array.1', 'array.2', 'array.3' ecc., dove
        'array' indica il nome di fantasia della variabile.
        Il punto (.) deve essere esplicitamente specificato.
        L'indice di questo vettore parte da 1 fino al numero specificato
        dal parametro 'n' o e' variabile se vi e' '*'.
        STEM puo' essere omesso solo in cancellazione (DISKD).
        Se il file viene acceduto in lettura, nella variabile 'array.0'
        verra' scritto da EXECIOVS il numero di record effettivamente
        letti.
        Se in scrittura viene specificato '*' come numero di record,
        allora nella variabile 'array.0' ci deve essere il numero di
        elementi del vettore 'array' (a partire da 1) che contengono
        i record che devono essere scritti.


FINIS   e' un parametro opzionale che e' sempre ignorato; infatti il file
        viene sempre aperto ad inizio programma e sempre chiuso in uscita
        del programma; in altre parole e' come se 'FINIS' fosse sempre
        presente: viene ammesso per compatibilita' col comando 'EXECIO'.










4)                           E S E M P I

- Lettura di un record di un file KSDS (le virgolette sono per l'uso
  in un programma REXX); FILEVSAM e' il ddname del file, precedentemente
  allocato

         NREC = 1
         KEY = '123456'
         "EXECIOVS "NREC" DISKR FILEVSAM KEY (STEM REC."




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


    Il programma si compone di un unico eseguibile di nome appunto EXECIOVS.
Deve essere caricato in una libreria MVS di eseguibili puntata in Linklist
o per lo meno nella JOBLIB (o STEPLIB) dei Job di partenza delle utenze TSO.
Il programma, come si e' detto, necessita di un ALLOC al file Vsam che deve
accedere mentre si preoccupa autonomamente di leggere o scrivere le variabili
REXX del programma che lo usa.


    Note:
- Normalmente il file acceduto da EXECIOVS sara' allocato in SHR, per
  renderlo accessibile ad altri utenti
- Se il file viene aperto in aggiornamento (ossia con DISKW, DISKWU, DISKD
  e DISKU) ovviamente il file non e' condivisibile con un'altro utente che
  contemporaneamente lo apra in OUTPUT (il secondo arrivato va in errore);
  per evitare cio' il programma da un ENQ EXCLUSIVE sul nome del file
  tutte le volte che deve essere aperto in OUTPUT: in questo modo,
  EXECIOVS lanciato da un'altro utente TSO in aggiornamento sullo stesso
  file va in WAIT finche' l'EXECIOVS del primo utente non termina l'aggior-
  namento.
  Per chi volesse scrivere una applicazione che deve condividere il file
  in aggiornamento con EXECIOVS diamo i parametri dell'ENQ in modo che
  possa essere usato lo stesso meccanismo per la serializzazione:

    Nome coda:     EXECIOVS
    Nome risorsa:  il ddname del file
    in modo esclusivo su una CPU, ossia:  E,SYSTEM


    Limitazioni:
- Non vengono supportati i files Vsam di tipo Linear
- La lunghezza massima dei record e' 16K bytes.
- In questa release i record letti non possono essere messi direttamente
  nello stack, omettendo il parametro STEM, come per l'EXECIO.

