   A L L O C A T E  -  Platform: MVS routine


   A routine to perform file dynamic allocations inside a user program.


   In this distribution file (ALLOCATE.ZIP) there is:

ALLOCATE.OBJ            executable for MVS mainframe, in obj form
ALLOCATE.HIL            Hilmas source of this file
README.TXT              this help file 
LINKEDIT.JCL            job example to install ALLOCATE
MAN_ENG.TXT             manual in English
MAN_ITA.TXT             manual in Italian
TESTALLC.OBJ            Demo of use of ALLOCATE in assembler
TESTALLC.HIL            Source Hilmas of demo



OBJ installation:

- Create in MVS a sequential file, for example 'MYUSER.PROGRAM.OBJ'
  with RECFM=FB and LRECL=80, for example of 1 cylinder.

- SEND obj module from PC to MVS in this file in BINARY form, with your 
  3270 emulation; the most important thing is a binary transfer (therefore 
  without ASCII CRLF) in a file with record length of 80 bytes.
  Use this PC command (in a PC with IBM/PCOMM 4.1 3270 emulation installed):

     SEND ALLOCATE.OBJ 'MYUSER.PROGRAM.OBJ'

- Prepare a Job to Linkedit transferred obj in a load library;
  use LINKEDIT.JCL as example: fit this JCL to your needs
  changing library names

- Submit linkedit job to create load module; output library must be a
  load library used in your compilation job.

- Recall this routine in your Cobol program as explained in manual;
  then linkedit your program with this routine, verifying that 
  this load library is included in your compilation procedure.


Program instruction:

    See the manual for examples in COBOL of the use of this routine.
Here we want explain the demo in Hilmas enclosed in distribution;
TestAllc is a very simple program that display use of ALLOCATE routine
from an assembler program. See source TESTALLC.HIL.

    To install executable (OBJ) of this demo you must do the same things 
you have done for ALLOCATE; pay attention that the linkedit library SYSLIB
(in the linkedit job) must already contains routines ALLOCATE that must
be linked together with TESTALLC.

    To run demo TESTALLC in your ISPF/TSO session write:
       TSO TESTALLC        (if library of this executable is in linklist)
or, from =3.4 menu option, enter 'M' of the load library containing
TestAllc and, left to executable, write CALL <Enter>.

    TestAllc show an interactive screen similar to this:

         --- TEST OF "ALLOCATE" ROUTINE. ---'


         WRITE DDNAME (LOGICAL NAME):'
        mytestdd
         WRITE PHYSICAL FILE NAME:'
        myuser.search.list               <-- this is an existent file
         WRITE DISPOSITION (SHR, OLD, MOD OR (NEW,CATLG,DELETE)):'

         RETURN CODE = 0


     If return code is 0, you can verify dynamic allocation in your
TSO session with this command:
     TSO LISTAL STAT
that display you all files allocated to your session; at the end of this list
you must see file you have chosen. Use FREE FI(ddname) command to deallocate.
If you answer 'NEW' to 'DISPOSITION' request, demo program ask you  
SPACE, DCB, UNIT and VOLSER; filling them appropriately, you can next verify
the correct creation of this new sequential file.

