The JUMP* DQFs

The MCVX_BACKTRACK DQF should hopefully satisfy most of the shortcomings of the link stepping logic but, when even that fails, the ultimate solution is the jump DQFs. These are JUMP, JUMP_TRUE, JUMP_FALSE and JUMP_UNDEFINED. Except for JUMP, these DQFs are supplied with a test and if the test condition is satisfied, jump to another part of the n-tuple entry and continue to fill it from there. JUMP jumps unconditionally. They are used as follows:-

 
' _    dqf_name  relative_offset,                         '
'                test_value;                              '

where:-

_

is the name for the entry. The DQF returns the value of its second arguement (JUMP just returns 1.0). As this information is singularly uninteresting the ``unnamed'' name _ is recommended. It may be reused on all jump DQFs, so relieving the user of the chore of inventing names for junk!

dqf_name

is one of:-

• JUMP_TRUE which means the jump will happen if the test value is true. True is any value except 0. or the undefined value.

• JUMP_FALSE which means the jump will happen if the test value is false i.e. 0.

• JUMP_UNDEFINED which means the jump will happen if the test value is undefined.

• JUMP which is an unconditional jump, there is no second parameter in this case.

relative_offset

is the number of entries, relative to the current one, to jump. The offset can be:-

negative literal e.g. -2

to jump backwards. For example -2 jumps back two entries. Jumping back up the n-tuple runs a risk: if the test is always satisfied, the program goes into an endless loop. To avoid this, collection of the current n-tuple is aborted and an informational ZTELL warning is issued, if too many jumps are executed.

Attempting to jump back before the first entry discards the current n-tuple, see section 6.7.2.

an earlier entry name e.g. _my_vx

to jump backwards. In this case the entry name which acts like a label for the jump. This form is preferred as it will continue to work even if new new entries are inserted between the jump target and the jump DQF.

positive literal e.g. +1.

to jump forward, for example +1 which jumps on just one entry (which is quite pointless as that is what will be processed next if the test fails).

a later entry name

to jump forwards by referring to an entry name further down the n-tuple. As with jumping backwards, this form is preferred.

Forward jumps must be treated with caution, jumping over entries will leave them at their undefined entry, even if you have requested that partial entries are to be discarded.

Attempting to jump forward beyond the last entry signals that the current n-tuple is complete and is ready to be stored, see section 6.7.2

test_value

is the value to be tested. Most likely this will refer to a previous entry that holds the result of some DQF test. If this parameter is omitted, then the value stored in the preceeding word is used, which is useful if the test condition is only needed for the jump, eg.:-

 
' _    gt          ev, $KEV_NPM,60;        '
' -    jump_true   _big_event;             '

It is recommended that, when using entries as labels for jumps they be reserved just for the purpose i.e. not used to store data. The following construction:-

 
' _my_label:                   '

is treated as shorthand for:-

 
' _my_label    reserved;       '

and helps to make labels stand out.

The primary use of the JUMP DQFs is to allow fine tuning of MCVX_BACKTRACK. For example, suppose you wish to backtrack from a scanned point MCVX to the first upstream interaction vertex which has its creation bit (KMCVX_CRE) set. This could be done as follows:-

 
' _my_vx        get_link       MCVX;                     '
' _my_tk        mcvx_backtrack _my_vx, $KMCVX_INT;       '
' _is_creation  bits           _my_vx, $KMCVX_CRE, 1;    '
' _             jump_false     _my_tk, _is_creation;     '

The first two lines define the link _my_vx to be equal to the scan point MCVX and then passes it to MCVX_BACKTRACK requiring that it backtracks to the first interaction that it encounters. On return _my_vx now points to the MCVX it has found. Next the BITS DQF is used to pull out the creation bit setting from its status word. Finally the JUMP_FALSE DQF is called using the setting of this bit. If it is zero i.e. false, the test succeeds, and the jump back to the _my_tk entry occurs. So MCVX_BACKTRACK is now called again and starts by stepping back one vertex, before resuming backtracking.

The simple loop illustrated above, allows you to add extra tests and to continue backtracking until they are all satisfied or until backtracking failed. It is worth spelling out what happens in this case. The first thing that happens is the MCVX_BACKTRACK returns a link of 0 which is equivalent to saying the result is undefined. If the discard partial entry is set on, then collection terminates at this point. If not the code ploughs on to the BITS DQF. As the link is zero, the result _is_creation is given the undefined value. This value is not considered to be false so the subsequent jump does not occur and so the loop breaks and control passes to the next entry word in the n-tuple.