The repeat, loop, and subroutine opcodes are used to iterate over vectors, manage loop counts and early exits, and call and return from subroutines. These opcodes help in structuring reusable pattern blocks.

Conceptual Overview

In a pattern, repeat and loop opcodes control iteration, and call and return control subroutine execution. Use them to repeat vectors, define loops, exit loops early, and execute reusable subroutines. Subroutines are analogous to function calls.

The optional ! character inverts conditions.

Syntax Reference

Table 2. Syntax Descriptions for Repeat, Loop, and Subroutine Opcodes
Syntax Description
repeat(numeric) Executes the current vector the specified number of times.
repeat(register) Reads the repeat count from the specified pattern sequencer register and executes the current vector that many times. Pattern sequencer registers pass numeric values between the pattern sequencer and a run‑time test program.
set_loop(numeric) Sets the number of loop iterations for the next loop block.

After calling set_loop, label the first and last vectors of the loop and use end_loop(label).
set_loop(register) Reads the loop count from the specified register. Allows runtime control of loop iterations.

After calling set_loop, label the first and last vectors of the loop and use end_loop(label).
end_loop(label) Marks the last vector in the loop. Executes the vector and compares completed iteration to the count set by set_loop. If iterations remain, jumps to the label and repeats. Otherwise, the opcode pops the loop stack and continues.
exit_loop(label) Exits the loop immediately, pops the loop stack, and jumps to the specified label.
exit_loop_if([!]failed, label) Executes the current vector and conditionally exits the loop if any comparison failed.
exit_loop_if([!]seqflag, label) Exit the loop if you set the specified sequencer flag.
exit_loop_if([!]matched, label) Exits the loop if the vector executed exactly 80 cycles prior matched.
exit_loop_if([!]trigger, label) Exit the loop if the system asserts the specified trigger.
call(label) Jumps to the subroutine specified by the label. Executes until a return opcode, then resumes after the call. Subroutine calls can nest up to eight levels deep.
return Executes the current vector and then jumps to the vector that follows the vector with the corresponding call opcode.

Parameter Descriptions

The following parameters describe how repeat, loop, and subroutine opcodes control iteration and branching in pattern execution. Each parameter sets conditions or values. These conditions or values influence loop counts, exits, and subroutine calls.
  • failed—Exits the loop if any comparison failed in the current pattern burst. Otherwise, continue to the next vector.
    Note This condition does not include the vectors that executed within the last 80 cycles or vectors that contain the match opcode. You can use the repeat opcode to implement an 80 cycle delay.
  • label—Any local label within the pattern file or any label exported from another pattern file.
  • matched—Exits the loop if the vector executed exactly 80 cycles prior matched. Otherwise, continue to the next vector.
  • numeric—Repeat or loop count.

    Valid range: 1–65535.

  • register—Register name. Used to read repeat or loop count dynamically.

    Valid range: reg0–reg15.

  • seqflag—Exits the loop if you set the specified sequencer flag. Otherwise, continue to the next vector.
  • trigger—Exits the loop if the system asserts the specified trigger. Otherwise, continue to the next vector.
    • Note See Pattern Responses to Comparisons for more information about synchronizing multiple instruments and about parameters on vectors that span more than one instrument or more than one site.

    Evaluation Differences

    The system evaluates the matched parameter and the !failed parameter differently. Similarly, !matched parameter and the failed parameter have distinct evaluations. For more details, see the descriptions of the matched parameter and failed parameter.

    Special Considerations

    Additional steps are necessary when using the following opcodes or the following parameters.
    • match opcode
    • matched parameter of the jump_if opcode or the exit_loop_if opcode in burst patterns
    • failed parameter of the jump_if opcode or the exit_loop_if opcode in burst patterns

    Synchronization Requirements for Comparison Results

    If a pattern bursts across multiple synchronized digital pattern instruments, enable each instrument to process comparison results. Use Enable Match… for each synchronized instrument to process comparison results. Use one of the following options to enable comparison result processing for synchronized instruments.
    • niDigital Enable Match Fail Combination VI
    • EnableMatchFailCombination .NET method
    • niDigital_EnableMatchFailCombination C function
    You must also use the NI-Sync driver and a PXIe-6674T timing and synchronization instrument. These tools combine comparison results across instruments that are synchronized with NI-TClk.
    Note The vector before a call can use only call or match opcodes. You can use call on the first vector but not on the last vector in a pattern.
    Note The NI-Digital Pattern does not check nested loops or subroutine calls against instrument limits during compilation or editing.

    Early Loop Exit Using exit_loop_if(seqflag0, ...)

    // Set the number of loop iterations for the looping operation.
set_loop(100)                sample_timeset X;

// Set the label for the looping operation.
loop:                        sample_timeset X;

// Exit the loop prematurely if seqflag0 is set to true.
exit_loop_if(seqflag0, exit) sample_timeset X;

end_loop(loop)               sample_timeset X;

exit: halt                   sample_timeset X;

    Calling a Subroutine and Returning to the Next Vector

    // This vector executes first.
call(sub1) sample_timeset 0 L;

// This vector executes after the subroutine returns.
halt       sample_timeset 1 H;

...

sub1:      sample_timeset 0 L;

// Return to the vector following the call.
return     sample_timeset 0 L;