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

  <refnamediv>
    <refname>schedwhen</refname>

    <refpurpose>
      Adds a new score event.
      <indexterm id="IndexSchedwhen"><primary>schedwhen</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      Adds a new score event.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis><command>schedwhen</command> ktrigger, kinsnum, kwhen, kdur [, ip4] [, ip5] [...]</synopsis>
    <synopsis><command>schedwhen</command> ktrigger, &quot;insname&quot;, kwhen, kdur [, ip4] [, ip5] [...]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ip4, ip5, ...</emphasis> -- Equivalent to p4, p5, etc., in a score <link linkend="i"><citetitle>i statement</citetitle></link>.
    </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kinsnum</emphasis> -- instrument number. Equivalent to p1 in a score <link linkend="i"><citetitle>i statement</citetitle></link>.
    </para>

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

    <para>
      <emphasis>ktrigger</emphasis> -- trigger value for new event
    </para>

    <para>
      <emphasis>kwhen</emphasis> -- start time of the new event. Equivalent to p2 in a score <link linkend="i"><citetitle>i statement</citetitle></link>.
    </para>

    <para>
      <emphasis>kdur</emphasis> -- duration of event. Equivalent to p3 in a score <link linkend="i"><citetitle>i statement</citetitle></link>.
    </para>

    <para>
      <emphasis>schedwhen</emphasis> adds a new score event. The event is only scheduled when the k-rate value <emphasis>ktrigger</emphasis> is first non-zero. The arguments, including options, are the same as in a score. The <emphasis>iwhen</emphasis> time (p2) is measured from the time of this event.
    </para>

    <para>
      If the duration is zero or negative the new event is of MIDI type, and inherits the release sub-event from the scheduling instruction.
    </para>

    <warning>
      <title>Warning</title>
      <para>Support for named instruments is broken in version 4.23</para>
    </warning>
  </refsect1>

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

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="schedule"><citetitle>schedule</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &namejohn;</member>
        <member>University of Bath/Codemist Ltd.</member>
        <member>Bath, UK</member>
        <member>November 1998</member>
      </simplelist>
    </para>
    <para>Example written by &namekevin;.</para>

    <para>New in Csound version 3.491</para>
    <para>Based on work by &namegabriel;</para>
  </refsect1>
</refentry>
