<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="subinstr">
  <refmeta>
    <refentrytitle>subinstr</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>subinstr</refname>
    <refpurpose>
      Creates and runs a numbered instrument instance.
      <indexterm id="IndexSubinstr"><primary>subinstr</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      Creates an instance of another instrument and is used as if it were an opcode.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>a1, [...] [, a8] <command>subinstr</command> instrnum [, p4] [, p5] [...]</synopsis>
    <synopsis>a1, [...] [, a8] <command>subinstr</command> &quot;insname&quot; [, p4] [, p5] [...]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>instrnum</emphasis> -- Number of the instrument to be called.
    </para>

    <para>
      <emphasis><quote>insname</quote></emphasis> -- A string (in double-quotes) representing a named instrument.
    </para>

    <para>
      For more information about specifying input and output interfaces, see <link linkend="InstrSubinstrument"><citetitle>Calling an Instrument within an Instrument</citetitle></link>.
    </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>a1, ..., a8</emphasis> --  The audio output from the called instrument. This is generated using the <link linkend="SigioOutput"><citetitle>signal output</citetitle></link> opcodes.
    </para>

    <para>
      <emphasis>p4, p5, ...</emphasis> -- Additional input values the are mapped to the called instrument p-fields, starting with p4.
    </para>

    <para>
      The called instrument's p2 and p3 values will be identical to the host instrument's values. While the host instrument can <link linkend="ControlDurctl"><citetitle>control its own duration</citetitle></link>, any such attempts inside the called instrument will most likely have no effect.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="InstrSubinstrument"><citetitle>Calling an Instrument within an Instrument</citetitle></link>,
      <link linkend="event"><citetitle>event</citetitle></link>, 
      <link linkend="schedule"><citetitle>schedule</citetitle></link>,
      <link linkend="subinstrinit"><citetitle>subinstrinit</citetitle></link>
     </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the subinstr opcode. It uses the files <ulink url="examples/subinstr.orc"><citetitle>subinstr.orc</citetitle></ulink> and <ulink url="examples/subinstr.sco"><citetitle>subinstr.sco</citetitle></ulink>.

      <example>
        <title>Example of the subinstr opcode.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/subinstr.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/subinstr.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>
    </para>

    <para>
      Here is an example of the subinstr opcode using a named instrument. It uses the files <ulink url="examples/subinstr_named.orc"><citetitle>subinstr_named.orc</citetitle></ulink> and <ulink url="examples/subinstr_named.sco"><citetitle>subinstr_named.sco</citetitle></ulink>.

      <example>
        <title>Example of the subinstr opcode using a named instrument.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/subinstr_named.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/subinstr_named.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>New in version 4.21</para>
  </refsect1>
</refentry>
