QSE_dgmEventSkip.h File Reference

Interface to the event skipping routine. More...

Typedefs
typedef struct _LSF_datagram	LSF_datagram
Functions
int	QSE_dgmEventSkip (const LSF_datagram *dgm, int nskip, int *nctb, int *nrec)
	Counts the skip count down by the number of events in this datagram, but stops if the number of events is greater than nskip.

---

Detailed Description

Interface to the event skipping routine.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: QSE_dgmEventSkip.h,v 1.1 2008/09/19 22:00:50 russell Exp $

---

Function Documentation

int QSE_dgmEventSkip	(	const LSF_datagram *	dgm,
		int	nskip,
		int *	nctb,
		int *	nrec
	)

Counts the skip count down by the number of events in this datagram, but stops if the number of events is greater than nskip.

Returns:

> 0 The number of events remaining to be skipped. This value should be passed to QSE_dgmEventSkip as nskip when processing the next datagram. nctb is returned as the count of event contributors and nrec the count of event records in this datagram < 0 The target event is the first event in the next datagram. While the user may call QSE_dgmEventSkip with this as a parameter, its only action will be to set nctb and nrec to 0. = 0 The target event is within this datagram. The user may chose to calculate the number of events to skip (simply by noting the value of nskip when it was passe in) or use the return value in nctb and nrec. These values give the number of contributions to skip and the number of events within that contribution to reach the target event.

Parameters:

	dgm	The datagram to examine
	nskip	The number of events to skip.
	nctb	A returned value (may be NULL) If the skip count has expired, this is returned as the event contribution (0 based) it expired in. If the skip count has not expired this is returned as the count of contributions.
	nrec	A returned value (may be NULL) If the skip count has expired, this is returned as then record number (0 based) within the above contribution it expired at. If the skip count has not expired this is returned as the count of event records.

This routine is used by many utilities when they wish to skip some number of events before starting their processing. The routine pages forward through the datagrams until reaching the desired event. When the datagram with the desired event is reached, 0 is returned. Typically this routine would be called for each datagram until 0 is reached.

Example

This piece of code might appear in LSF_scanDatagrams callback routine.

        int nskip = ctl->nskip;

        / * Check if there are events to skip * /
        if (nskip > 0)
        {
            / * 
              |  If there are no events left to skip, nskip will be
              |  returned as 0 and ctl->nctb and ctl->nevent will be
              |  set to the the number of event contributors and the
              |  number of events to skip within that contributor
              |  before the target event is reached.
 /
             
            nskip = QSE_eventsSkip (dgm, nskip, &ctl->nctb, &ctl->nevent);


            / * If have not reached the skip count yet...* /
            if (nskip)
            {
                / * Skip count not reached yet, update the skip count * /
                ctl->nskip   = nskip;

                / *
                  | No need to process the contributors in this datagram
                  | continue processing the next datagram
 /
                ctb.rtn      = NULL;
                ctb.ctx      = (unsigned int)0;

                return ctb;
            }
        }

        / / Start processing datagrams, one may have page to the
        / / correct event using the nctb and nrec return values

Since this procedure only takes one to the datagram containing the first event to be processed, the event record handling routine would do the mandatory updating of the datagram, contribution and record context for the remaining events to be skipped. Then, when the requisite number of events have been skipped, it would begin normal processing.

For example, this might be the first few lines of code in an event record processing routine might look like this...

    / * Always update the context * /
    status =  QSEP_updateAtRecord (qsep, rec);


    / * Do we need to skip * /
    nskip       = ctl->nleft;
    if (nskip) 
    {
        / * Yes, reduce the skip count and continue to the next event * /
        ctl->nleft = nskip - 1; 
        return 0; 
    }
    
    / * The right numbers of events have been skipped, start processing * /
    ...

Note:

The reason that this does not return a pointer to the given event or provide some other random access method to the event is that typically one must page through the datagram to update the event context. Giving a pointer to the event would not help in this case.

Warning:

It cannot be used to get a count of the number of events in a datagram since it stop when the contribution containing the desired event is reached. I toyed with the idea of placing the event count in the header, but this seemed to elevate the importance of event records over any other kind of records. Maybe that was poor reasoning. It sure would have made this routine easier to implement.

References dgm_skip().

Referenced by QSE_dgmDvrDatagram().