                         A L L O C A T E


      This routine can be recalled by a Cobol or Assembler program
in MVS environment, and allow a dynamic allocation of a file; in this
way in Job can be avoided specification of DD statement relating to 
the file. That is, the program itself can set many of the parameters
of a DD statement, deciding what of these parameters are more suitable.
However is recommended to use DD statement in the Job, without
the use of this routine, because maintenance is more simple. 
This routine can be used in all cases in which, when job is written,
is not possible to know what files the program will use.


    In Cobol:

  CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME DISPOS SPACE DCB UNIT VOL

    where only three parameters are mandatory;
    parameters definition is:

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


    In assembler:

    CALL ALLOCATE,(NUMARG,DDNAME,DSNAME,DISPOS,SPACE,DCB,UNIT,VOL),VL

    where also only first three parameters are mandatory;
    parameter definition is:

          NUMARG     DS    F
          DDNAME     DS    CL8
          DSNAME     DS    CL54
          DISPOS     DS    CL20
          SPACE      DS    CL20
          DCB        DS    CL40
          UNIT       DS    CL8
          VOL        DS    CL6

    Meaning of parameters is:

    NUMARG:  number of arguments (NUMARG excluded) as a binary Fullword;
             value can be from 2 to 7;
             at return to calling program, NUMARG contain return code 
             of dynamic allocation.
    DDNAME:  logical file name
    DSNAME:  phisical file name; also a member of partitioned library,
             written as  'phisical.library.name(member)'
    DISPOS:  disposition, also in form: '(NEW,CATLG,DELETE)'
             default is 'SHR'
    SPACE:   only for DISP=NEW: in the form '(TRK,(pri,sec[,dir]))'
             'TRK' is mandatory, that is space can be allocated only
             in tracks; if secondary space is not permitted, specify
             '0' as 'sec' 
    DCB   :  only for DISP=NEW: in the form: '(LRECL=l,RECFM=fb,BLKSIZE=nnn)'
             with this defaults if some parameters are not specified:
             LRECL=80,RECFM=FB,BLKSIZE=6160
             Supported RECFM are: A, S, B, V, F, U.
    UNIT  :  only for DISP=NEW: default is 'SYSALLDA'; is  UNIT= of JCL
             DD statement
    VOL   :  only for DISP=NEW; correspond to VOL=SER= of DD statement


      Usually, for an already existent file you can use only NUMARG
(equal to 2), DDNAME and DSNAME; only if DISP=SHR is not correct you
specify also DISPOS (equal to OLD or MOD).

      For an allocation of a new file (not VSAM!) is good specify
DISPOS, SPACE and DCB; optionally also UNIT and VOL.

      To use defaults, fill parameter with blanks.

      To allocate a printer file, i.e. a 'SYSOUT' to write something in
spool, parameters are of the same type and length, but have another mean;
in cobol:

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

    where only first three parameters are mandatory;
    parameters have this definition:

           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 the same manner are defined in Assembler).

    Parameters have this mean:

    NUMARG:  nummer of arguments (NUMARG excluded) expressed in Fullword
    DDNAME:  logical name of printer file
    DSNAME:  must be fixed name 'SYSOUT', is the name that indicate
             that a  spool file is required.
    SYSOUT:  print class, also in the form: '(c,program,fno)'
             where "c" is the class, "program" can be for example
             "INTRDR" and "fno" is the name of the printer module 
             (form number, of 4 chatacters); if this field is blank,
             default is 'A'; star '*' is not admitted as printer class.
             Note: if you want leave out "program" and specify instead
             "fno", substutute it with a point: (c,.,fno).
    COPIES:  number of copies, an edited number (type character) from
             1 and 255;  default is 1
    OUTPUT:  referback to OUTPUT statement: can be written in these ways
                ddname
                stepname.ddname
                stepname.procstepname.ddname
             '*' is not admitted as referback; this fiels can be leaved 
             empty  (that is filled of blanks) if a reference to OUTPUT
             statement is not required.
    FCB   :  FCB name, 4 characters; leave it blank if not required
    HOLD  :  if printer file must be HOLDed, fill this field with fixed
             value  'HOLD'



Note:
      In a Cobol program, freedom to use ddname as you like is restricted
by the duty of specify the same ddname explicitly in ASSIGN statement,
in FILE-CONTROL.
      Moreover in a Cobol program are mandatory in Job the DD SYSOUT 
and SYSIN, that so cannot be dynamically allocated.
      If you allocate a new partitioned library, that is with 
DISP=(NEW,CATLG), is mandatory specify all 7 parameters, VOLUME included.
      Files are automatically deallocated at file close.

      Is not possible to use this routine in a CICS program.



      Routine do a first formal control on passed parameters: 
return codes returned in NUMARG are the following:
      10  - NUMARG wrong: must be from 2 and 7
      12x - DISPOSITION wrong
      13x - SPACE error
      14x - DCB error
'x' is the position of wrong subparameter; if 'x' = 0 is a generic error
(for example brackets not closed).
If error is different, then NUMARG is return code called S99ERROR,
that SVC 99 return as regards to dynamic allocation request.



      Now, a Cobol example that recall  ALLOCATE:

       IDENTIFICATION DIVISION.
       PROGRAM-ID.   ALLOCA.
       AUTHOR. PIERO.
      ****************************************************************
      * Try of recall of  routine    'ALLOCATE' for dynamic          *
      *      allocation of an existing sequential file               *
      ****************************************************************
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           DECIMAL-POINT  IS  COMMA.
       INPUT-OUTPUT SECTION.
      ****************************************************************
      * FILE must be defined as usual in 'SELECT' statement:         *
      *    here logical name used is  "ALLOCA"                       *
      ****************************************************************
       FILE-CONTROL.
           SELECT PROVA     ASSIGN TO   UT-S-ALLOCA
                            ORGANIZATION IS SEQUENTIAL
                            ACCESS MODE  IS SEQUENTIAL.
      ****************************************************************
       DATA DIVISION.
       FILE SECTION.
      ****************************************************************
      * File must be defined as usual in '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.  <-- change !!
           CALL 'ALLOCATE' USING NUMARG DDNAME DSNAME.
           DISPLAY 'RC ALLOCATE = ' NUMARG.
           IF NUMARG NOT = 0 THEN STOP RUN.
      ****************************************************************
      * Obviously, file must be opened only AFTER a successful       *
      *     allocation, and not before                               *
      ****************************************************************
           OPEN OUTPUT PROVA.
           MOVE ' RECORD written IN OUTPUT ' TO RIGA.
           WRITE  RIGA.
           CLOSE PROVA.
       FINE.
           STOP RUN.
      ********************************************************* END *


      Another example to allocate a new file:

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



      At last two examples that allocate a printer file:

       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'                                        *
      ****************************************************************

