+----------------------------------------------------+
|CALL HGIVEN (ID,CHTITL*,*NVAR*,CHTAG*,RLOW*,RHIGH*) |
+----------------------------------------------------+
Action: Routine to provide information about an Ntuple.
+--------------------------------------+
|CALL HGN (ID,*IDN*,IDNEVT,X*,IERROR*) |
+--------------------------------------+
Action: Copy the contents of a RWN event into an array.
This routine returns in the vector X the contents of the row IDNEVT or Ntuple ID. The vector X must be of size NVAR, as specified in the call to HBOOKN. If more than one row of the Ntuple is to be processed, it is more efficient to call first HGNPAR and then HGNF.
+------------------------+
|CALL HGNPAR (ID,CHROUT) |
+------------------------+
Action: Obtains the address and parameters of Ntuple ID.
This routine sets some internal pointers and must be called before the first call to HGNF for a given RWN. When accessing more than one row of an Ntuple it is more efficient to call HGNPAR and then HGNF for each row that is required than to call HGN.
+----------------------------------+
| CALL HGNF (ID,IDNEVT,X*,IERROR*) |
+----------------------------------+
Action: Copy the contents of an Ntuple event into an array. The routine HGNPAR must have been called prior to the first call to HGNF for a given Ntuple.
This routine returns in the vector X the contents of the row IDNEVT or Ntuple ID. The vector X must have be of size NVAR, as specified in the call to HBOOKN.
Example of access to RWN information
PROGRAM TEST
INTEGER NWPAWC
PARAMETER (NWPAWC=15000, MTUPLE=5)
COMMON/PAWC/PAW(NWPAWC)
CHARACTER*80 CHTITL
CHARACTER*8 CHTAGS(MTUPLE),CHTAGZ(MTUPLE)
DIMENSION EVENT(MTUPLE),RLOW(MTUPLE),RHIGH(MTUPLE)
EQUIVALENCE (EVENT(1),X),(EVENT(2),Y),(EVENT(3),Z)
EQUIVALENCE (EVENT(4),ENERGY),(EVENT(5),ELOSS)
DATA CHTAGS/'X','Y','Z','Energy','Eloss'/
*-- Tell HBOOK how many words are in PAWC.
CALL HLIMIT(NWPAWC)
*-- Book Ntuple
CALL HBOOKN(10,'A Row-Wise-Ntuple',5,' ',5000,CHTAGS)
*-- Fill the Ntuple
DO 10 I=1,1000
CALL RANNOR(X,Y)
Z=SQRT(X*X+Y*Y)
ENERGY=50. + 10.*X
ELOSS=10.*ABS(Y)
CALL HFN(10,EVENT)
10 CONTINUE
*-- Obtain the definitions of the Ntuple
NVAR = MTUPLE
CALL HGIVEN(10,CHTITL,NVAR,CHTAGZ,RLOW,RHIGH)
PRINT *,'Definitions of Ntuple # ',10
PRINT *,' Title: ',CHTITL(1:LENOCC(CHTITL))
PRINT *,' Number of variables: ',NVAR
DO 20 I=1,NVAR
PRINT 9001,I,RLOW(I),RHIGH(I)
9001 FORMAT(' Min/Max values for column # ',I3,1X,F10.5,
+ 1X,F10.5)
20 CONTINUE
*-- Get the contents of 'event' # 333
CALL HGNPAR(10,'TEST')
CALL HGNF(10,333,EVENT,IERR)
PRINT *,IERR,EVENT
*-- Get the number of events in this Ntuple
CALL HNOENT(10,NEVENT)
PRINT *,NEVENT
99 CONTINUE
END
+----------------------------+
|CALL HGNT (ID,IDNEVT,IERR*) |
+----------------------------+
Action:
Retrieve information about a CWN row.
The information is restored at the addresses specified by HBNAME or HBNAMC (for CHARACTER data). If the information is being retrieved by a program other than the one that wrote the Ntuple then HBNAME or HBNAMC must be called as appropriate (see below).
CALL HBNAME(ID,' ',0,'$CLEAR')
CALL HBNAME(ID,CHBLOK,VARIABLE,'$SET')
These calls are required as HBOOK must obtain the location at
which the requested information is to be returned which is obviously not
valid between programs. The first call clears all the addresses stored by
HBOOK for the specified Ntuple and the second one sets the
addresses for the variables in block CHBLOK starting at variable
VARIABLE. The second call should be repeated for every block of
which data has to be retrieved. The routine HUWFUN will generate these
calls automatically in the skeleton user function.
+----------------------------------+
|CALL HGNTB (ID,CHBLOK,IROW,IERR*) |
+----------------------------------+
Action:
Retrieve information about a named block in an Ntuple row.
The information is restored at the addresses specified by HBNAME or HBNAMC (for CHARACTER data).
+--------------------------------------+
|CALL HGNTV (ID,CHVAR,NVAR,IROW,IERR*) |
+--------------------------------------+
Action:
Retrieve information about the named variables in an Ntuple row.
The information is restored at the addresses specified by HBNAME or HBNAMC (for CHARACTER data).
+----------------------------+
| CALL HGNTF (ID,IROW,IERR*) |
+----------------------------+
Action:
Retrieve information about all variables specified in a previous call to either HGNT, HGNTB or HGNTV, in an Ntuple row. This routine is much faster than either HGNT, HGNTB or HGNTV.
The information is restored at the addresses specified by HBNAME or HBNAMC (for CHARACTER data).
HBOOK can automatically produce a skeleton user selection function, which includes the Ntuple declaration via the calls HBNT, HBNAME and HBNAMC, and can be used in a later run to access the elements of the Ntuple. Two cases are available; one for use in batch and the other for use with PAW. In the first case the common block names will be those specifed by the user in the call to HBNAME or HBNAMC. For PAW, these common names are /PAWCR4/, /PAWCR8/ and /PAWCCH/ for storing the ``single precision'' (LOGICAL, INTEGER and REAL*4), ``double precision'' (REAL*8 and COMPLEX) and CHARACTER data respectively.
+----------------------------------------+
|CALL HUWFUN (LUN,ID,CHFUN,ITRUNC,CHOPT) |
+----------------------------------------+
Action:
Write an user function or subroutine to access an Ntuple.
A simple example of the two kinds of skeletons generated with routine HUWFUN is given below. Another more complex example can be found on page [more info], where the code of a fully worked out subroutine based on such a sketeton can also be studied.
In PAW, the command UWFUNC generates a skeleton for the RWN or CWN analysis function automatically.
Example of an Ntuple definition and HUWFUN usage
COMMON /CVECT/ V1, V2, V3, V4, V5, V6, V7, V8, V9, V10,
+ V11, V12, V13, V14, V15, V16, V17, V18, V19, V20
...
...
*
*-- book N-tuple 20
*
CALL HBNT(20,'1 block 20 variable N-tuple', ' ')
CALL HBNAME(20,'VECT',V1,'V1,V2,V3,V4,V5,V6,V7,V8,V9,V10,V11,
+ V12,V13,V14,V15,V16,V17,V18,V19,V20')
*
...
OPEN(11,FILE='nt20.f',STATUS='UNKNOWN')
OPEN(12,FILE='nt20p.f',STATUS='UNKNOWN')
CALL HUWFUN(11, 20, 'NT20', 0, 'B')
CALL HUWFUN(12, 20, 'NT20', 0, 'P')
...
The HUWFUN output files nt20.f and nt20p.f look like:
File nt20.f
SUBROUTINE NT20
*********************************************************
* *
* This file was generated by HUWFUN. *
* *
*********************************************************
*
* N-tuple Id: 20
* N-tuple Title: 1 block 20 variable N-tuple
* Creation: 11/06/92 18.46.10
*
*********************************************************
*
REAL V1,V2,V3,V4,V5,V6,V7,V8,V9,V10,V11,V12,V13,V14,V15,V16,V17
+ ,V18,V19,V20
COMMON /VECT/ V1,V2,V3,V4,V5,V6,V7,V8,V9,V10,V11,V12,V13,V14,V15
+ ,V16,V17,V18,V19,V20
*
CALL HBNAME(20,' ',0,'$CLEAR')
CALL HBNAME(20,'VECT',V1,'$SET')
*
*
*-- Enter user code here
*
*
END
File nt20p.f
REAL FUNCTION NT20()
*********************************************************
* *
* This file was generated by HUWFUN. *
* *
*********************************************************
*
* N-tuple Id: 20
* N-tuple Title: 1 block 20 variable N-tuple
* Creation: 11/06/92 18.46.10
*
*********************************************************
*
COMMON /PAWIDN/ IDNEVT,VIDN1,VIDN2,VIDN3,VIDN(10)
*
REAL V1,V2,V3,V4,V5,V6,V7,V8,V9,V10,V11,V12,V13,V14,V15,V16,V17
+ ,V18,V19,V20
COMMON /PAWCR4/ V1,V2,V3,V4,V5,V6,V7,V8,V9,V10,V11,V12,V13,V14
+ ,V15,V16,V17,V18,V19,V20
*
*
*-- Enter user code here
*
NT20 = 1.
*
END
PAWOptimizing event loops
If you analyse Ntuple data without PAW, it is your own responsibility to find out and specify which are the columns referenced via the routines HGNTV or HGNTB (if all variables in a block are needed).
This optimization can be very important. Assume, for instance, that a 100 Mbyte file contains an Ntuple consisting of 300 columns, and that 3 columns are referenced. Then without optimization the complete 100 Mbyte file will have to be read, while, by specifying the columns used, only 1 Mbyte will be input.