                         A L L O C A T E


      Questa routine si puo' richiamare con una CALL da un qualunque
programma Cobol o Assembler in ambiente MVS, e consente di allocare
dinamicamente un file; in questo modo si puo' evitare di specificare
le schede DD relative ai file usati dal programma nel Job relativo.
Puo' cioe' essere il programma stesso a impostare molti dei valori
di una scheda DD, generando come variabili interne al programma, ad
esempio il ddname, il dsname e la disposition. Naturalmente, e' cosigliabile
usare le schede DD direttamente nel job, dovunque possibile, evitando
l'uso di questa routine, in quanto piu' facilmente manutenibili;
puo' invece essere usata in tutti quei casi in cui, al momento della
scrittura del job, non e' possibile sapere quali file fisici usera'il
programma.


    Uso per il cobol:

  CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME DISPOS SPAZIO DCB UNITA VOL

    dove solo i primi tre argomenti sono obbligatori;
    i parametri devono essere cosi' definiti:

           NUMARG     PIC    S9(7)   COMP.
           DDNAME     PIC     X(8).
           DSNAME     PIC     X(54).
           DISPOS     PIC     X(20).
           SPAZIO     PIC     X(20).
           DCB        PIC     X(40).
           UNITA      PIC     X(8).
           VOL        PIC     X(6).


    Uso per l'assembler:

    CALL ALLOCATE,(NUMARG,DDNAME,DSNAME,DISPOS,SPAZIO,DCB,UNITA,VOL),VL

    dove anche qui solo i primi tre argomenti sono obbligatori;
    i parametri devono essere cosi' definiti:

          NUMARG     DS    F
          DDNAME     DS    CL8
          DSNAME     DS    CL54
          DISPOS     DS    CL20
          SPAZIO     DS    CL20
          DCB        DS    CL40
          UNITA      DS    CL8
          VOL        DS    CL6

    Il significato dei parametri e' il seguente:

    NUMARG:  numero di argomenti (NUMARG escluso) espresso come Fullword
             binaria; il valore puo' essere da 2 a 7;
             al ritorno al chiamante NUMARG contiene il return code della
             allocazione dinamica
    DDNAME:  nome logico del file
    DSNAME:  nome fisico del file (anche membro di partitioned, espresso
             nel solito modo tra parentesi, attaccato al nome fisico
             della libreria)
    DISPOS:  disposition, anche nella forma p.e.:'(NEW,CATLG,DELETE)'
             di default e' 'SHR'
    SPAZIO:  solo per DISP=NEW: nella forma '(TRK,(pri,sec[,dir]))'
             'TRK' e' fisso, ossia lo spazio si puo' allocare solo in
             tracce; se non c'e' spazio secondario, bisogna specificare
             comunque '0' come spazio secondario
    DCB   :  solo per DISP=NEW: nella forma: '(LRECL=l,RECFM=fb,BLKSIZE=nnn)'
             con i seguenti default, se qualcuno dei parametri non e'
             specificato: LRECL=80,RECFM=FB,BLKSIZE=6160
             I RECFM supportati sono: A, S, B, V, F, U.
    UNITA :  solo per DISP=NEW: default 'SYSALLDA'; e' il parametro
             UNIT= della DD
    VOL   :  solo per DISP=NEW; corrisponde a VOL=SER= della DD


      Normalmente, per un file gia' esistente si useranno solo NUMARG,
che sara' uguale a 2, DDNAME e DSNAME; solo se non va bene DISP=SHR si
specifichera' anche il parametro DISPOS.

      Per l'allocazione di un file nuovo invece e' bene specificare
DISPOS, SPAZIO e DCB; opzionalmente anche UNITA e VOL.



      Nel caso si voglia allocare un file di stampa, ossia un 'SYSOUT',
i parametri, pur rimanendo tutti dello stesso tipo e dimensioni, assumono
un significato diverso; in cobol:

  CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME SYSOUT COPIES OUTPUT FCB HOLD

    dove solo i primi tre argomenti sono obbligatori;
    i parametri devono essere cosi' definiti:

           NUMARG     PIC    S9(7)   COMP.
           DDNAME     PIC     X(8).
           DSNAME     PIC     X(54).
           SYSOUT     PIC     X(20).
           COPIES     PIC     X(20).
           OUTPUT     PIC     X(40).
           FCB        PIC     X(8).
           HOLD       PIC     X(6).

    (In maniera analoga andranno definiti in assembler).

    Il significato dei parametri e' il seguente:

    NUMARG:  numero di argomenti (NUMARG escluso) espresso come Fullword
    DDNAME:  nome logico del file di stampa
    DSNAME:  deve essere il nome fisso 'SYSOUT', per segnalare che si sta
             allocando un file di stampa che andra' in spool.
    SYSOUT:  classe di stampa, anche nella forma p.e.: '(c,program,fno)'
             dove "c" e' la classe, "program" puo' essere per esempio
             "INTRDR" e "fno" e' il nome del modulo di stampa (il form
             number, di 4 caratteri); se questo campo non e' specificato
             di default e' 'A'; non e' ammesso l'asterisco come classe
             di stampa.
             Nota: se si vuole omettere il "program" e specificare invece
             "fno", sostituirlo con un punto: (c,.,fno).
    COPIES:  numero di copie richieste, espresso come numero editato
             tra 1 e 255; di default e' 1
    OUTPUT:  riferimento alla scheda OUTPUT: puo' essere espresso nei
             seguenti modi:
                ddname
                stepname.ddname
                stepname.procstepname.ddname
             non e' ammesso l'asterisco come referback; questo campo
             puo' essere lasciato vuoto (ossia pieno di blank) se non
             e' richiesto riferimento alla scheda OUTPUT.
    FCB   :  nome dell'FCB richiesto, di 4 lettere; lasciarlo a blank
             se non e' richiesto FCB
    HOLD  :  se la stampa deve finire in coda di HOLD, si riempira'
             questo campo col valore fisso 'HOLD'



Note:
      In un programma Cobol la parametrizzazione del ddname e' limitata,
dal momento che la stessa ddname deve essere specificata esplicitamente
nella ASSIGN nella FILE-CONTROL.
      In un programma Cobol devono essere specificate obbligatoriamente
nel Job le DD SYSOUT e SYSIN, che quindi non possono essere allocate
dinamicamente.
      Se si alloca una libreria partitioned non esistente, ossia con
DISP=(NEW,CATLG), e' obbligatorio specificare tutti 7 i parametri,
VOLUME compreso.
      I files sono deallocati automaticamente alla chiusura del file.


      Non si puo' usare questa routine in un programma CICS.



      La routine fa un primo controllo di correttezza formale sui parametri
passati: i return code che restituisce in NUMARG sono i seguenti:
      10  - NUMARG errato: deve essere tra 2 e 7
      12x - DISPOSITION errata
      13x - SPAZIO errato
      14x - DCB errato
'x' e' il numero d'ordine del sottoparametro in errore; se 'x' = 0 e' un
errore generico (es. parentesi non chiusa).
Se l'errore e' diverso, allora NUMARG e' il return code chiamato S99ERROR
che la SVC 99 restituisce a fronte della richiesta di allocazione dinamica.



      Ecco un esempio di programma cobol che richiama ALLOCATE:

       IDENTIFICATION DIVISION.
       PROGRAM-ID.   ALLOCA.
       AUTHOR. PIERO.
      ****************************************************************
      * PROVA RICHIAMO DELLA ROUTINE 'ALLOCATE' PER ALLOCAZIONE      *
      *       DINAMICA DI UN FILE SEQUENZIALE GIA' ESISTENTE         *
      ****************************************************************
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           DECIMAL-POINT  IS  COMMA.
       INPUT-OUTPUT SECTION.
      ****************************************************************
      * IL FILE VA DEFINITO NEL SOLITO MODO NELLA 'SELECT':          *
      *    QUI IL NOME LOGICO USATO E' "ALLOCA"                      *
      ****************************************************************
       FILE-CONTROL.
           SELECT PROVA     ASSIGN TO   UT-S-ALLOCA
                            ORGANIZATION IS SEQUENTIAL
                            ACCESS MODE  IS SEQUENTIAL.
      ****************************************************************
       DATA DIVISION.
       FILE SECTION.
      ****************************************************************
      * IL FILE VA DEFINITO NEL SOLITO MODO NELLA 'FD'               *
      ****************************************************************
       FD  PROVA
           BLOCK CONTAINS    0  RECORDS
           LABEL RECORD IS STANDARD.
       01  RIGA.
           02  DATI           PIC X(100).
       WORKING-STORAGE SECTION.
       77  NUMARG     PIC    S9(7)   COMP.
       77  DDNAME     PIC     X(8).
       77  DSNAME     PIC     X(54).
       77  DISPOS     PIC     X(20).
       77  SPAZIO     PIC     X(20).
       77  DCB        PIC     X(40).
       77  UNITA      PIC     X(8).
       77  VOLUME     PIC     X(6).
      ****************************************************************
       PROCEDURE DIVISION.
       INIZIO.
           MOVE +2        TO NUMARG.
           MOVE 'ALLOCA'  TO DDNAME.
           MOVE 'TSOUSER.PIERO.ALLOCA' TO DSNAME.
           CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME.
           DISPLAY 'RC ALLOCATE = ' NUMARG.
           IF NUMARG NOT = 0 THEN STOP RUN.
      ****************************************************************
      * OVVIAMENTE IL FILE VA APERTO DOPO CHE E' STATO ALLOCATO      *
      *     CON SUCCESSO, E NON PRIMA.                               *
      ****************************************************************
           OPEN OUTPUT PROVA.
           MOVE ' RECORD SCRITTO IN OUTPUT ' TO RIGA.
           WRITE  RIGA.
           CLOSE PROVA.
       FINE.
           STOP RUN.
      ********************************************************* END *


      Ecco un altro esempio di programma cobol che richiama ALLOCATE
per allocare un file nuovo:

       PROCEDURE DIVISION.
       INIZIO.
           MOVE +6        TO NUMARG.
           MOVE 'ALLOCA'  TO DDNAME.
           MOVE 'TSOUSER.PIERO.ALLOCA' TO DSNAME.
           MOVE '(NEW,CATLG)'          TO DISPOS.
           MOVE '(TRK,(10,2))'         TO SPAZIO.
           MOVE '(LRECL=80,RECFM=FB,BLKSIZE=4000)' TO DCB.
           MOVE 'SYSDA'                TO UNITA.
           CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME
                DISPOS SPAZIO DCB UNITA.
           DISPLAY 'RC ALLOCATE = ' NUMARG.



      Infine due esempi di programma cobol che richiamano ALLOCATE
per allocare un file di stampa:

       WORKING-STORAGE SECTION.
       77  NUMARG     PIC    S9(7)   COMP.
       77  DDNAME     PIC     X(8).
       77  DSNAME     PIC     X(54).
       77  CLASS      PIC     X(20).
      ****************************************************************
       PROCEDURE DIVISION.
       INIZIO.
           MOVE +3        TO NUMARG.
           MOVE 'STAMPA1' TO DDNAME.
           MOVE 'SYSOUT'  TO DSNAME.
           MOVE 'L'       TO CLASS.
           CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME CLASS.
           DISPLAY 'RC ALLOCATE = ' NUMARG.



       WORKING-STORAGE SECTION.
       77  NUMARG     PIC    S9(7)   COMP.
       77  DDNAME     PIC     X(8).
       77  DSNAME     PIC     X(54).
       77  CLASS      PIC     X(20).
       77  COPIES     PIC     X(20).
       77  OUTPUT     PIC     X(40).
       77  FCB        PIC     X(8).
       77  HOLD       PIC     X(6).
      ****************************************************************
       PROCEDURE DIVISION.
       INIZIO.
           MOVE +7        TO NUMARG.
           MOVE 'STAMPA1' TO DDNAME.
           MOVE 'SYSOUT'  TO DSNAME.
           MOVE '(R,.,MOD1)' TO CLASS.
           MOVE '2'       TO COPIES.
           MOVE '       ' TO OUTPUT.
           MOVE 'FCB1'    TO FCB.
           MOVE 'HOLD'    TO HOLD.
           CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME CLASS COPIES
                OUTPUT FCB HOLD.
           DISPLAY 'RC ALLOCATE = ' NUMARG.
      ****************************************************************
      * NOTA: HO LASCIATO DEI BLANK NEL CAMPO 'OUTPUT' PERCHE' VOGLIO*
      *       IMPOSTARE L'FCB E METTERE HOLD=YES SENZA USARE LA      *
      *       SCHEDA 'OUTPUT'                                        *
      ****************************************************************

