The package is designed as to make almost all features of the very
flexible EP format (see section 
)
available to the user. One can and
should however, use it in as simple a way as possible. In the following,
we give a series of applications ranging from the simplest use to the
most complex one. It should be stressed that for the user wanting to use
the package as a black box,
-- no knowledge of the actual format is required -- the only routines he has to use and understand are
EPINIT
EPREAD(EPFHDR,EPFRD)
EPOUTS
EPRWND
EPCLOS
EPEND
Obviously, the more advanced user will have to learn more.
After the examples, we give a description of all routines in the package, and of the utility routines going with it (which are, however, independent of the package and are intended to fulfil the most common user needs).
While it should not concern most users, the following overview of
the format might help to clarify some problems. The basic "units"
of information are 16-bit words. However, as of version 1.56, all
information including the physical header, maybe given in 32-bit words.
The header of each
physical record or block is usually 12 words. The user's logical
data (or events) can be specified by the user to be in ``units'' of 16 or
32-bit words. Each logical record has a header (normally 4 units long)
which specifies the record length and header length in ``units'' and other
general identifiers. However, irrespective of the value of "unit" the user
can treat the logical data part of the record as 16-bit, 32-bit
or packed quantities, by specifying different ``MODES'' to EPREAD and
EPOUTS, etc.
Packed quantities are applicable to other types of data,
for example CDC 60-bit words or 24-bit Camac, but the user has to
look after the unpacking himself. The complete description of the
format can be found in section .
It should be stressed that the package does not perform automatic number format conversion, but only packs and unpacks (16 and 32-bit words). However, there are conversion routines from and to IBM floating and integer formats and from and to ASCII. To simplify the portability of data between different computer types, 32-bit headers are written in IBM format.
Users are invited to study the examples carefully concerning initialisation, termination, and definition of buffer sizes.
The Unix version is restricted to fixed length blocks with full padding which is in any case the EPIO default. If a different blocksize than the EPIO default (1800 16-bit words) is required, it must be specified correctly in status word 1 by a call to EPSETW, e.g. for a blocksize of 1800 bytes on unit 11
CALL EPSETW(11,1,900,IERR).Unfortunately, this means that you can not give an arbitrarily large blocksize to allow your program to read files with different block sizes. Otherwise, existing applications should be portable to Unix workstations.
The choice of C or Fortran for the basic I/O
can be selected using the status word 33,
which is set by the user as detailed in the table below.
Value Type of I/O Default filename (lun=nn)
0 Fortran sequential for0nn
1 Fortran direct access epionn
2 C using CFIO epionn
By default, status word 33 is set to 2. Although it is the old default, Value 0 is not portable and seems to give more problems. Values 1 and 2 give identical formats on most systems and are portable.
The association with real filenames can be made in several ways:
CALL EPDEFU(LUN,'epdata/test1',IERR)
ln epdata/test epio01and follow it by:
CALL EPREAD(1,MODE,NW,IREC,IBUF,IERR)
EPIO files for use on or created on mainframes should have fixed length blocks. On VAX/VMS you can use the default settings. On CERNVM the user should issue a filedef specifying RECFM F or RECFM U and the correct blocksize, which most applications are doing already. If not, a correct filedef is
FILEDEF IOFILE11 DISK MYEPIO TESTDATA A1 ( RECFM F BLOCK 3600The files can then be transferred using FTP. The most convenient way is to use the ZFTP utility and a good
putb myepio.testdata test1 3600
If ZFTP is not available on your system then you must use ftp directly specifying the qualifier ``binary''.
For files created on a workstation for transfer to a mainframe it is essential to create them as a byte stream. Although it is clearly inefficient, conversion utilities between the two formats will be provided.
A typical CERNVM ftp session would be
tcpipibm ftp hostnm > hostname > password > cd wdir > binary fixed 3600 for a blocksize of 3600 bytes > put file.iofile epio11 or > get epio11 file.iofile > quit
On VAX, the session is similar except that the EPIO file names
are of the form FOR0nn.DAT.
The VM version uses IOPACK, and both packages are available from the standard CERN program library PACKLIB, by using the command
CERNLIB
The IOFILEnn data sets read and written by EPIO must have filemode 4 (i.e. OS simulation) with options "RECFM U" and an appropriate blocksize.
For example, to access a disk data set "RAWDATA DATA" on logical unit 10 for reading or writing an appropriate FILEDEF might be:
FILEDEF IOFILE10 DISK RAWDATA DATA A4 (RECFM U BLKSIZE 3600At present, concatenation of data sets is not supported under VM, but at CERN the FILEDEF option "APPEND" is available for disk files.
The usage of disk files does not require any particular action, they are connected to logical units in the standard VMS way. If the logical name FORnnn is defined then its translation will be used as file name to connect, otherwise the file FORnnn.DAT will be used. However, the file name may also be changed at run-time via a call to the routine EPDEFU.
The current version of EPIO will recognize when it reads or writes a tape instead of disk, provided the device name is of the standard form MTAn:
For example: Suppose you want to mount a tape with blocks of length 23040 bytes on unit 0, for the logical unit no. 1:
MOUNT /FOR/BLOC=23040/REC=23040 MTAn: LABEL FOR001
where LABEL is just a place holder. For unlabelled tapes, on the CENTRAL 8600 at CERN the command should read
SETUP/BLOC=23040/REC=23040/NOLABEL XUTnnn XUTnnn FOR001
for a non labelled tape, where the second XUTnnn is again a place holder. Should the tape be labelled the qualifier /LABEL=ASCII or /LABEL=EBCDIC is required. If the tape is to be written the qualifier /WRITE must be inserted before the /[NO]LABEL qualifier. Byte swapping to/from tape may be done automatically when using EPIO, if this is allowed by the drivers' firmware/hardware. Tapes with EBCDIC labels should be positioned correctly using e.g.:
SET MAGTAPE/SKIP=FILES:1 FOR001
Alternately label groups must be treated by the user by recovering
from EPIO error 5. The file name may be changed at run-time via a call
to the routine EPDEFU.
The Apollo version uses the stream I/O routines available in the system library. The files written by EPIO are of type REC (variable record length) but even UASC files can be handled provided the logical block length is fixed and the first status word is properly set.
The default file name is FORnnn.DAT like on the VAX where nnn is the logical unit number. This can be changed by calling EPDEFU.
Tapes are accessed via a magnetic tape descriptor file. The EPIO routines address the file which in turn redirect the I/O operation to the physical device. A magnetic tape descriptor file is created by the command:
edmtdesc for011.dat -c -s lab no reo no civ yes spos yes edmtdesc for011.dat -s f 1 rf u bl 3600 rl 3600 ascni no
This is the case for a standard EPIO unlabelled tape recorded with
a blocksize of 3600 bytes. In case of label or of different blocksize
the parameters should be changed accordingly.
Type Help EDMTDESC for
more details. The name of the Magnetic tape descriptor file can
be different from FORnnn.DAT provided the user calls EPDEFU.
The IBM version of EPIO uses the input/output package IOPACK (Z300 in the CERN Program Library). DD names for the EPIO units are of the form
IOFILEnn nn = 1 to 99with DCB=(RECFM=U,BLKSIZE=iiii)
The default version of EPIO does not allow concatenation of data sets but this can easily be changed by setting status word 25 to non-zero;
CALL EPSETW(LUN,25,1,IERR)
To access multiple logical units on the same physical unit
using "UNIT=AFF" requires a "CALL EPRWND"
in addition to EPDROP, so
that the unit is properly closed. The details for reading multifile
labelled tapes are in the description of EPREAD.
The EPIO routines are available from the standard CERN Program libraries, and use FORTRAN BUFFER IN/OUT to perform the I/O.
Magnetic tape files should be accessed specifying record type RT=U. EPIO disk file default format on NOSBE:
MFA,MFB RT=S,BT=C
For reasons of compatibility with different word lengths, the block size should be a multiple of 480 bits = 60 bytes. The default block size is 3600 bytes.
In addition, there are restrictions on the recommended physical record sizes for certain devices. In adition, the ``standard Fortran'' version, on which the UNIX version is based, is restricted to block sizes in multiples of machine words.
With the status word 27 set to 1 fully automatic byte swapping is the default. This works of course only with the EP format as it requires two special control words in the physical header.
To read EP files created in the "OLD" format (with a 6 word physical header) the user must call EPSETW to set status word 27 to 0. The user can force EPIO to read his data as new format by setting status word 27 to 2, avoiding peculiar side effects when there are parity errors for example.