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

  <refnamediv>
    <refname>pgmassign</refname>
    <refpurpose>
      Assigns an instrument number to a specified MIDI program.
      <indexterm id="IndexPgmassign"><primary>pgmassign</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      Assigns an instrument number to a specified (or all) MIDI program(s).
    </para>

    <para>
      By default, the instrument is the same as the program number. If the selected instrument is zero or negative or does not exist, the program change is ignored. This opcode is normally used in the orchestra header. Although, like <link linkend="massign"><citetitle>massign</citetitle></link>, it also works in instruments.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis><command>pgmassign</command> ipgm, inst</synopsis>
    <synopsis><command>pgmassign</command> ipgm, &quot;insname&quot;</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ipgm</emphasis> -- MIDI program number (1 to 128). A value of zero selects all programs.
    </para>

    <para>
      <emphasis>inst</emphasis> -- instrument number. If set to zero, or negative, MIDI program changes to <emphasis>ipgm</emphasis> are ignored. Currently, assignment to an instrument that does not exist has the same effect. This may be changed in a later release to print an error message.
    </para>

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

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

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

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

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

    <para>
      Here is an example of the pgmassign opcode that will ignore program change events. It uses the files <ulink url="examples/pgmassign_ignore.orc"><citetitle>pgmassign_ignore.orc</citetitle></ulink> and <ulink url="examples/pgmassign_ignore.sco"><citetitle>pgmassign_ignore.sco</citetitle></ulink>.

      <example>
        <title>Example of the pgmassign opcode that will ignore program change events.</title>

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

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

    <para>
      Here is an advanced example of the pgmassign opcode. It uses the files <ulink url="examples/pgmassign_advanced.mid"><citetitle>pgmassign_advanced.mid</citetitle></ulink>, <ulink url="examples/pgmassign_advanced.orc"><citetitle>pgmassign_advanced.orc</citetitle></ulink>, and <ulink url="examples/pgmassign_advanced.sco"><citetitle>pgmassign_advanced.sco</citetitle></ulink>.
    </para>

    <para>
      Don't forget that you must include the <link linkend="FlagsMinusUpperF"><citetitle>-F flag</citetitle></link> when using an external MIDI file like <quote>pgmassign_advanced.mid</quote>.
    </para>

    <para>
      <example>
        <title>An advanced example of the pgmassign opcode.</title>

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

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

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

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &nameistvan;</member>
        <member>May 2002</member>
      </simplelist>
    </para>

    <para>New in version 4.20</para>
  </refsect1>
</refentry>
