/[svn]/linuxsampler/trunk/Documentation/lscp.xml

Diff of /linuxsampler/trunk/Documentation/lscp.xml

Parent Directory | Revision Log | View Patch Patch

-revision 1136 by iliev,
Thu Mar 29 10:01:50 2007 UTC
+revision 1250 by schoenebeck,
Fri Jun 22 14:21:03 2007 UTC
 Line 16
       to an annoying "missing Normative/Informative References" error message -->
  <?rfc strict="no" ?>
- <rfc category="std" ipr="full3978" docName="LSCP 1.2">
+ <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
      <front>
-         <title>LinuxSampler Control Protocol</title>
+         <title>LinuxSampler Control Protocol (draft)</title>
          <author initials='C.S.' surname="Schoenebeck" fullname='C.
  Schoenebeck'>
              <organization>
 Line 34 
 Schoenebeck'>
                  <email>schoenebeck at software minus engineering dot org</email>
              </address>
          </author>
-         <date month="March" year="2007"/>
+         <date month="June" year="2007"/>
          <workgroup>LinuxSampler Developers</workgroup>
          <keyword>LSCP</keyword>
          <abstract>
 Line 61 
 Schoenebeck'>
              (front-end) and server (LinuxSampler) respectively. Lines in
              examples must be interpreted as every line being CRLF
              terminated (carriage return character followed by line feed
-             character as defined in the ASCII standard), thus the following
+             character as defined in the ASCII standard <xref target="RFC20"/>),
-             example:</t>
+             thus the following example:</t>
              <t>
                  <list>
 Line 2113 
 Schoenebeck'>
                      number of the sampler channel the instrument should be assigned to.
                      Each sampler channel can only have one instrument.</t>
+                     <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
+                     escape characters for special characters (see chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>"
+                     for details) and accordingly backslash characters in the filename
+                     MUST now be escaped as well!</t>
                      <t>The difference between regular and NON_MODAL versions of the command
                      is that the regular command returns OK only after the instrument has been
                      fully loaded and the channel is ready to be used while NON_MODAL version
-Line 3959 
 Schoenebeck'>
+Line 3965 
 Schoenebeck'>
                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
                                          </list>
                                      </t>
+                                     <t>INSTRUMENTS_DB_SUPPORT -
+                                         <list>
+                                             <t>either yes or no, specifies whether the
+                                             sampler is build with instruments database support.</t>
+                                         </list>
+                                     </t>
                                  </list>
                              </t>
                          </list>
-Line 4319 
 Schoenebeck'>
+Line 4331 
 Schoenebeck'>
                      index, &lt;engine_name&gt; a sampler engine name as returned by
                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
-                     of the instrument's file to be deployed (encapsulated into apostrophes),
+                     of the instrument's file to be deployed (encapsulated into apostrophes,
+                     supporting escape sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>"),
                      &lt;instrument_index&gt; the index (integer value) of the instrument
                      within the given file, &lt;volume_value&gt; reflects the master
                      volume of the instrument as optionally dotted number (where a
-Line 4734 
 Schoenebeck'>
+Line 4748 
 Schoenebeck'>
                  </section>
              </section>
+             <section title="Managing Instruments Database" anchor="Managing Instruments Database">
+                 <t>The following commands describe how to use and manage
+                 the instruments database.</t>
+                 <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
+                     <t>The front-end can add a new instrument directory to the
+                     instruments database by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory
+                     to be created (encapsulated into apostrophes).</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>when the directory could not be created, which
+                                     can happen if the directory already exists or the
+                                     name contains not allowed symbols</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
+                     <t>The front-end can delete a particular instrument directory
+                     from the instruments database by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory
+                     to delete. The optional FORCE argument can be used to
+                     force the deletion of a non-empty directory and all its content.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>if the directory is deleted successfully</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist, or
+                                     if trying to delete a non-empty directory,
+                                     without using the FORCE argument.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
+                     <t>The front-end can retrieve the current amount of
+                     directories in a specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path
+                     name of the directory. If RECURSIVE is specified, the number of
+                     all directories, including those located in subdirectories of the
+                     specified directory, will be returned.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>The current number of instrument directories
+                             in the specified directory.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
+                             <t>S: "2"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
+                     <t>The front-end can retrieve the current list of directories
+                     in specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path
+                     name of the directory. If RECURSIVE is specified, the absolute path names
+                     of all directories, including those located in subdirectories of the
+                     specified directory, will be returned.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>A comma separated list of all instrument directories
+                             (encapsulated into apostrophes) in the specified directory.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
+                             <t>S: "'Piano Collection','Percussion Collection'"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
+                             <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
+                     <t>The front-end can ask for the current settings of an
+                     instrument directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path
+                     name of the directory the front-end is interested in.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
+                             Each answer line begins with the settings category name
+                             followed by a colon and then a space character &lt;SP&gt; and finally
+                             the info character string to that setting category. At the
+                             moment the following categories are defined:</t>
+                             <t>
+                                 <list>
+                                     <t>DESCRIPTION -
+                                         <list>
+                                             <t>A brief description of the directory content</t>
+                                         </list>
+                                     </t>
+                                     <t>CREATED -
+                                         <list>
+                                             <t>The creation date and time of the directory,
+                                             represented in "YYYY-MM-DD HH:MM:SS" format</t>
+                                         </list>
+                                     </t>
+                                     <t>MODIFIED -
+                                         <list>
+                                             <t>The date and time of the last modification of the
+                                             directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
+                                         </list>
+                                     </t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>The mentioned fields above don't have to be in particular order.</t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
+                             <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
+                             <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"."</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
+                     <t>The front-end can alter the name of a specific
+                     instrument directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory and
+                     &lt;name&gt; is the new name for that directory.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case the given directory does not exists,
+                                     or if a directory with name equal to the new
+                                     name already exists.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
+                     <t>The front-end can move a specific
+                     instrument directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory
+                     to move and &lt;dst&gt; is the location where the directory will
+                     be moved to.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case a given directory does not exists,
+                                     or if a directory with name equal to the name
+                                     of the specified directory already exists in
+                                     the destination directory. Error is also thrown
+                                     when trying to move a directory to a subdirectory
+                                     of itself.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
+                     <t>The front-end can copy a specific
+                     instrument directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory
+                     to copy and &lt;dst&gt; is the location where the directory will
+                     be copied to.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case a given directory does not exists,
+                                     or if a directory with name equal to the name
+                                     of the specified directory already exists in
+                                     the destination directory. Error is also thrown
+                                     when trying to copy a directory to a subdirectory
+                                     of itself.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
+                     <t>The front-end can alter the description of a specific
+                     instrument directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory and
+                     &lt;desc&gt; is the new description for the directory.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case the given directory does not exists.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
+                     <t>The front-end can search for directories
+                     in specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path
+                     name of the directory to search in. If NON_RECURSIVE is specified, the
+                     directories located in subdirectories of the specified directory will not
+                     be searched. &lt;criteria-list&gt; is a list of search criterias
+                     in form of "key1=val1 key2=val2 ...". The following criterias are
+                     allowed:</t>
+                     <t>
+                       <t>NAME='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to directories, which names
+                               satisfy the supplied search string.</t>
+                           </list>
+                       </t>
+                       <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to directories, which creation
+                               date satisfies the specified period, where &lt;date-after&gt;
+                               and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
+                               If &lt;date-after&gt; is omitted the search is restricted to
+                               directories created before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted
+                               to directories created after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to directories, which
+                               date of last modification satisfies the specified period, where
+                               &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
+                               format. If &lt;date-after&gt; is omitted the search is restricted to
+                               directories, which are last modified before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted to directories,
+                               which are last modified after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>DESCRIPTION='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to directories with description
+                               that satisfies the supplied search string.</t>
+                           </list>
+                       </t>
+                     </t>
+                     <t>Where &lt;search-string&gt; is either a regular expression, or a
+                     word list separated with spaces for OR search and with '+' for AND search.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>A comma separated list with the absolute path names (encapsulated into
+                             apostrophes) of all directories in the specified directory that satisfy
+                             the supplied search criterias.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
+                             <t>S: "'/Piano Collection'"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
+                             <t>S: "'/Piano Collection','/Percussions'"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
+                     <t>The front-end can add one or more instruments
+                     to the instruments database by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;db_dir&gt; is the absolute path name of a directory
+                     (encapsulated into apostrophes) in the instruments database in which
+                     only the new instruments (that are not already in the database) will
+                     be added, &lt;file_path&gt; is the absolute path name of a file or
+                     directory in the file system (encapsulated into apostrophes). In case
+                     an instrument file is supplied, only the instruments in the specified
+                     file will be added to the instruments database. If the optional
+                     &lt;instr_index&gt; (the index of the instrument within the given file)
+                     is supplied too, then only the specified instrument will be added.
+                     In case a directory is supplied, the instruments in that directory
+                     will be added. The OPTIONAL &lt;mode&gt; argument is only applied
+                     when a directory is provided as &lt;file_path&gt; and specifies how the
+                     scanning will be done and has exactly the following possibilities:</t>
+                     <t>
+                         <list>
+                             <t>"RECURSIVE" -
+                                 <list>
+                                     <t>All instruments will be processed, including those
+                                     in the subdirectories, and the respective subdirectory
+                                     tree structure will be recreated in the instruments
+                                     database</t>
+                                 </list>
+                             </t>
+                             <t>"NON_RECURSIVE" -
+                                 <list>
+                                     <t>Only the instruments in the specified directory
+                                     will be added, the instruments in the subdirectories
+                                     will not be processed.</t>
+                                 </list>
+                             </t>
+                             <t>"FLAT" -
+                                 <list>
+                                     <t>All instruments will be processed, including those
+                                     in the subdirectories, but the respective subdirectory
+                                     structure will not be recreated in the instruments
+                                     database. All instruments will be added directly in
+                                     the specified database directory.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                  <t>The difference between regular and NON_MODAL versions of the command
+                     is that the regular command returns when the scanning is finished
+                     while NON_MODAL version returns immediately and a background process is launched.
+                     The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
+                     command can be used to monitor the scanning progress.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success when NON_MODAL is not supplied</t>
+                                 </list>
+                             </t>
+                             <t>"OK[&lt;job-id&gt;]" -
+                                 <list>
+                                     <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
+                                     is a numerical ID used to obtain status information about the job progress.
+                                     See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
+                                     </t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if an invalid path is specified.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
+                     <t>The front-end can remove a particular instrument
+                     from the instruments database by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr_path&gt; is the absolute path name
+                     (in the instruments database) of the instrument to remove.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>if the instrument is removed successfully</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given path does not exist or
+                                     is a directory.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
+                     <t>The front-end can retrieve the current amount of
+                     instruments in a specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path name
+                     of the directory. If RECURSIVE is specified, the number of all
+                     instruments, including those located in subdirectories of the
+                     specified directory, will be returned.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>The current number of instruments
+                             in the specified directory.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
+                             <t>S: "2"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
+                     <t>The front-end can retrieve the current list of instruments
+                     in specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path
+                     name of the directory. If RECURSIVE is specified, the absolute path
+                     names of all instruments, including those located in subdirectories
+                     of the specified directory, will be returned.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>A comma separated list of all instruments
+                             (encapsulated into apostrophes) in the specified directory.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
+                             <t>S: "'Bosendorfer 290','Steinway D'"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
+                             <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
+                     <t>The front-end can ask for the current settings of an
+                     instrument by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr_path&gt; should be replaced by the absolute path
+                     name of the instrument the front-end is interested in.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
+                             Each answer line begins with the settings category name
+                             followed by a colon and then a space character &lt;SP&gt; and finally
+                             the info character string to that setting category. At the
+                             moment the following categories are defined:</t>
+                             <t>
+                                 <list>
+                                     <t>INSTRUMENT_FILE -
+                                         <list>
+                                             <t>File name of the instrument.</t>
+                                         </list>
+                                     </t>
+                                     <t>INSTRUMENT_NR -
+                                         <list>
+                                             <t>Index of the instrument within the file.</t>
+                                         </list>
+                                     </t>
+                                     <t>FORMAT_FAMILY -
+                                         <list>
+                                             <t>The format family of the instrument.</t>
+                                         </list>
+                                     </t>
+                                     <t>FORMAT_VERSION -
+                                         <list>
+                                             <t>The format version of the instrument.</t>
+                                         </list>
+                                     </t>
+                                     <t>SIZE -
+                                         <list>
+                                             <t>The size of the instrument in bytes.</t>
+                                         </list>
+                                     </t>
+                                     <t>CREATED -
+                                         <list>
+                                             <t>The date and time when the instrument is added
+                                             in the instruments database, represented in
+                                            "YYYY-MM-DD HH:MM:SS" format</t>
+                                         </list>
+                                     </t>
+                                     <t>MODIFIED -
+                                         <list>
+                                             <t>The date and time of the last modification of the
+                                             instrument's database settings, represented in
+                                             "YYYY-MM-DD HH:MM:SS" format</t>
+                                         </list>
+                                     </t>
+                                     <t>DESCRIPTION -
+                                         <list>
+                                             <t>A brief description of the instrument</t>
+                                         </list>
+                                     </t>
+                                     <t>IS_DRUM -
+                                         <list>
+                                             <t>either true or false, determines whether the
+                                             instrument is a drumkit or a chromatic instrument</t>
+                                         </list>
+                                     </t>
+                                     <t>PRODUCT -
+                                         <list>
+                                             <t>The product title of the instrument</t>
+                                         </list>
+                                     </t>
+                                     <t>ARTISTS -
+                                         <list>
+                                             <t>Lists the artist names</t>
+                                         </list>
+                                     </t>
+                                     <t>KEYWORDS -
+                                         <list>
+                                             <t>Provides a list of keywords that refer to the instrument.
+                                             Keywords are separated with semicolon and blank.</t>
+                                         </list>
+                                     </t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>The mentioned fields above don't have to be in particular order.</t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
+                             <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
+                             <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"."</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
+                     <t>The front-end can alter the name of a specific
+                     instrument by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr&gt; is the absolute path name of the instrument and
+                     &lt;name&gt; is the new name for that instrument.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case the given instrument does not exists,
+                                     or if an instrument with name equal to the new
+                                     name already exists.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
+                     <t>The front-end can move a specific instrument to another directory by
+                     sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr&gt; is the absolute path name of the instrument
+                     to move and &lt;dst&gt; is the directory where the instrument will
+                     be moved to.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case the given instrument does not exists,
+                                     or if an instrument with name equal to the name of the
+                                     specified instrument already exists in the destination
+                                     directory.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
+                     <t>The front-end can copy a specific instrument to another directory by
+                     sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr&gt; is the absolute path name of the instrument
+                     to copy and &lt;dst&gt; is the directory where the instrument will
+                     be copied to.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case the given instrument does not exists,
+                                     or if an instrument with name equal to the name of the
+                                     specified instrument already exists in the destination
+                                     directory.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
+                     <t>The front-end can alter the description of a specific
+                     instrument by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr&gt; is the absolute path name of the instrument and
+                     &lt;desc&gt; is the new description for the instrument.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case the given instrument does not exists.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
+                     <t>The front-end can search for instruments
+                     in specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; should be replaced by the absolute path
+                     name of the directory to search in. If NON_RECURSIVE is specified, the
+                     directories located in subdirectories of the specified directory will not
+                     be searched. &lt;criteria-list&gt; is a list of search criterias
+                     in form of "key1=val1 key2=val2 ...". The following criterias are
+                     allowed:</t>
+                     <t>
+                       <t>NAME='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments, which names
+                               satisfy the supplied search string.</t>
+                           </list>
+                       </t>
+                       <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
+                           <list>
+                               <t>Restricts the search to instruments, which
+                               size is in the specified range. If &lt;min&gt; is omitted,
+                               the search results are restricted to instruments with size less then
+                               or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
+                               search is restricted to instruments with size greater then
+                               or equal to &lt;min&gt;.</t>
+                           </list>
+                       </t>
+                       <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to instruments, which creation
+                               date satisfies the specified period, where &lt;date-after&gt;
+                               and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
+                               If &lt;date-after&gt; is omitted the search is restricted to
+                               instruments created before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted
+                               to instruments created after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to instruments, which
+                               date of last modification satisfies the specified period, where
+                               &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
+                               format. If &lt;date-after&gt; is omitted the search is restricted to
+                               instruments, which are last modified before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted to instruments,
+                               which are last modified after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>DESCRIPTION='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments with description
+                               that satisfies the supplied search string.</t>
+                           </list>
+                       </t>
+                       <t>PRODUCT='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments with product info
+                               that satisfies the supplied search string.</t>
+                           </list>
+                       </t>
+                       <t>ARTISTS='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments with artists info
+                               that satisfies the supplied search string.</t>
+                           </list>
+                       </t>
+                       <t>KEYWORDS='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments with keyword list
+                               that satisfies the supplied search string.</t>
+                           </list>
+                       </t>
+                       <t>IS_DRUM=true | false
+                           <list>
+                               <t>Either true or false. Restricts the search to
+                               drum kits or chromatic instruments.</t>
+                           </list>
+                       </t>
+                       <t>FORMAT_FAMILIES='&lt;format-list&gt;'
+                           <list>
+                               <t>Restricts the search to instruments of the supplied format families,
+                               where &lt;format-list&gt; is a comma separated list of format families.</t>
+                           </list>
+                       </t>
+                     </t>
+                     <t>Where &lt;search-string&gt; is either a regular expression, or a
+                     word list separated with spaces for OR search and with '+' for AND search.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>A comma separated list with the absolute path names (encapsulated into
+                             apostrophes) of all instruments in the specified directory that satisfy
+                             the supplied search criterias.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
+                             <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
+                             <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
+                     <t>The front-end can ask for the current status of a
+                     particular database instruments job by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;job-id&gt; should be replaced by the numerical ID
+                     of the job the front-end is interested in.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
+                             Each answer line begins with the settings category name
+                             followed by a colon and then a space character &lt;SP&gt; and finally
+                             the info character string to that setting category. At the
+                             moment the following categories are defined:</t>
+                             <t>
+                                 <list>
+                                     <t>FILES_TOTAL -
+                                         <list>
+                                             <t>The total number of files scheduled for scanning</t>
+                                         </list>
+                                     </t>
+                                     <t>FILES_SCANNED -
+                                         <list>
+                                             <t>The current number of scanned files</t>
+                                         </list>
+                                     </t>
+                                     <t>SCANNING -
+                                         <list>
+                                             <t>The absolute path name of the file which is currently
+                                             being scanned</t>
+                                         </list>
+                                     </t>
+                                     <t>STATUS -
+                                         <list>
+                                             <t>An integer value between 0 and 100 indicating the
+                                             scanning progress percentage of the file which is
+                                             currently being scanned</t>
+                                         </list>
+                                     </t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>The mentioned fields above don't have to be in particular order.</t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
+                             <t>S: "FILES_TOTAL: 12"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"."</t>
+                         </list>
+                     </t>
+                 </section>
+             </section>
          </section>
-Line 4809 
 Schoenebeck'>
+Line 5947 
 Schoenebeck'>
                  </t>
                  <t>/ UNSUBSCRIBE SP unsubscribe_event
                  </t>
-                 <t>/ SELECT SP text
-                 </t>
                  <t>/ RESET SP reset_instruction
                  </t>
                  <t>/ CLEAR SP clear_instruction
                  </t>
+                 <t>/ FIND SP find_instruction
+                 </t>
+                 <t>/ MOVE SP move_instruction
+                 </t>
+                 <t>/ COPY SP copy_instruction
+                 </t>
+                 <t>/ EDIT SP edit_instruction
+                 </t>
                  <t>/ RESET
                  </t>
                  <t>/ QUIT
-Line 4825 
 Schoenebeck'>
+Line 5969 
 Schoenebeck'>
          <list>
                  <t>CHANNEL
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP pathname SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
+                 </t>
                  <t>/ MIDI_INSTRUMENT_MAP
                  </t>
                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
-Line 4863 
 Schoenebeck'>
+Line 6021 
 Schoenebeck'>
                  </t>
                  <t>/ MIDI_INSTRUMENT_INFO
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY_INFO
+                 </t>
+                 <t>/ DB_INSTRUMENT_COUNT
+                 </t>
+                 <t>/ DB_INSTRUMENT_INFO
+                 </t>
+                 <t>/ DB_INSTRUMENTS_JOB_INFO
+                 </t>
                  <t>/ MISCELLANEOUS
                  </t>
                  <t>/ TOTAL_VOICE_COUNT
-Line 4903 
 Schoenebeck'>
+Line 6071 
 Schoenebeck'>
                  </t>
                  <t>/ MIDI_INSTRUMENT_INFO
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY_INFO
+                 </t>
+                 <t>/ DB_INSTRUMENT_COUNT
+                 </t>
+                 <t>/ DB_INSTRUMENT_INFO
+                 </t>
+                 <t>/ DB_INSTRUMENTS_JOB_INFO
+                 </t>
                  <t>/ MISCELLANEOUS
                  </t>
                  <t>/ TOTAL_VOICE_COUNT
-Line 4937 
 Schoenebeck'>
+Line 6115 
 Schoenebeck'>
                  </t>
                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT SP pathname
+                 </t>
          </list>
  </t>
  <t>get_instruction =
-Line 5007 
 Schoenebeck'>
+Line 6191 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT SP INFO SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
+                 </t>
                  <t>/ VOLUME
                  </t>
          </list>
-Line 5033 
 Schoenebeck'>
+Line 6231 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
+                 </t>
+                 <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname
+                 </t>
+                 <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
+                 </t>
                  <t>/ ECHO SP boolean
                  </t>
                  <t>/ VOLUME SP volume_value
-Line 5069 
 Schoenebeck'>
+Line 6275 
 Schoenebeck'>
                  </t>
          </list>
  </t>
+ <t>find_instruction =
+         <list>
+                 <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP pathname SP query_val_list
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
+                 </t>
+         </list>
+ </t>
+ <t>move_instruction =
+         <list>
+                 <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT SP pathname SP pathname
+                 </t>
+         </list>
+ </t>
+ <t>copy_instruction =
+         <list>
+                 <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT SP pathname SP pathname
+                 </t>
+         </list>
+ </t>
  <t>destroy_instruction =
          <list>
                  <t>AUDIO_OUTPUT_DEVICE SP number
-Line 5119 
 Schoenebeck'>
+Line 6353 
 Schoenebeck'>
                  </t>
          </list>
  </t>
+ <t>edit_instruction =
+         <list>
+                 <t>INSTRUMENT SP sampler_channel
+                 </t>
+         </list>
+ </t>
  <t>modal_arg =
          <list>
                  <t>/* epsilon (empty argument) */
-Line 5165 
 Schoenebeck'>
+Line 6405 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SENDS SP sampler_channel
                  </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP pathname
+                 </t>
          </list>
  </t>
  <t>load_instr_args =
-Line 5285 
 Schoenebeck'>
+Line 6533 
 Schoenebeck'>
                  </t>
          </list>
  </t>
- <t>filename =
+ <t>pathname =
+         <list>
+                 <t>stringval
+                 </t>
+         </list>
+ </t>
+ <t>dirname =
          <list>
                  <t>stringval
                  </t>
          </list>
  </t>
+ <t>filename =
+         <list>
+                 <t>stringval_escaped
+                 </t>
+         </list>
+ </t>
  <t>map_name =
          <list>
                  <t>stringval
-Line 5329 
 Schoenebeck'>
+Line 6589 
 Schoenebeck'>
                  </t>
          </list>
  </t>
+ <t>query_val_list =
+         <list>
+                 <t>string '=' query_val
+                 </t>
+                 <t>/ query_val_list SP string '=' query_val
+                 </t>
+         </list>
+ </t>
+ <t>query_val =
+         <list>
+                 <t>string
+                 </t>
+                 <t>/ stringval
+                 </t>
+         </list>
+ </t>
+ <t>scan_mode =
+         <list>
+                 <t>RECURSIVE
+                 </t>
+                 <t>/ NON_RECURSIVE
+                 </t>
+                 <t>/ FLAT
+                 </t>
+         </list>
+ </t>
              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
+             <section title="Character Set and Escape Sequences" anchor="character_set">
+                 <t>Older versions of this protocol up to and including v1.1 only
+                 supported the standard ASCII character set (ASCII code 0 - 127)
+                 <xref target="RFC20"/>, all younger versions of this protocol
+                 however support the Extended ASCII character set (ASCII code
+- 255). The same group of younger protocols also support
+                 escape sequences, but only for certain, explicitly declared
+                 parts of the protocol. The supported escape sequences are
+                 defined as follows:</t>
+                 <texttable>
+                     <ttcol>ASCII Character Sequence</ttcol>
+                     <ttcol>Translated into (Name)</ttcol>
+                     <c>\n</c> <c>new line</c>
+                     <c>\r</c> <c>carriage return</c>
+                     <c>\f</c> <c>form feed</c>
+                     <c>\t</c> <c>horizontal tab</c>
+                     <c>\v</c> <c>vertical tab</c>
+                     <c>\'</c> <c>apostrophe</c>
+                     <c>\"</c> <c>quotation mark</c>
+                     <c>\\</c> <c>backslash</c>
+                     <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
+                     <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
+                 </texttable>
+                 <t>Notice: due to the transition of certain parts of the
+                 protocol which now support escape sequences, a slight backward
+                 incompatibility to protocols version v1.1 and younger has been
+                 introduced. The only difference is that in parts of the protocol
+                 where escape characters are now supported, a backslash characters
+                 MUST be escaped as well (that is as double backslash), whereas
+                 in the old versions a single backslash was sufficient.</t>
+             </section>
          </section>
          <section title="Events" anchor="events">
-Line 5516 
 Schoenebeck'>
+Line 6834 
 Schoenebeck'>
              </section>
              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
                  <t>Client may want to be notified when the number of effect sends on
                  a particular sampler channel is changed by issuing the following command:</t>
                  <t>
                      <list>
-Line 5672 
 Schoenebeck'>
+Line 6990 
 Schoenebeck'>
                  </t>
              </section>
+             <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
+                 <t>Client may want to be notified when the number of instrument
+                 directories in a particular directory in the instruments database
+                 is changed by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;dir-path&gt; will be replaced by the absolute path
+                 name of the directory in the instruments database,
+                 in which the number of directories is changed.</t>
+                 <t>Note that when a non-empty directory is removed, this event
+                 is not sent for the subdirectories in that directory.</t>
+             </section>
+             <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
+                 <t>Client may want to be notified when changes were made to directories
+                 in the instruments database by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;dir-path&gt; will be replaced by the absolute path name
+                 of the directory, for which information changes occurred. The front-end will have to send
+                 the respective command to actually get the updated directory info. Because these messages
+                 will be triggered by LSCP commands issued by other clients rather than real
+                 time events happening on the server, it is believed that an empty notification
+                 message is sufficient here.</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
+                 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
+                 the new name of the directory, encapsulated into apostrophes.</t>
+             </section>
+             <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
+                 <t>Client may want to be notified when the number of instruments
+                 in a particular directory in the instruments database
+                 is changed by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;dir-path&gt; will be replaced by the absolute path
+                 name of the directory in the instruments database,
+                 in which the number of instruments is changed.</t>
+                 <t>Note that when a non-empty directory is removed, this event
+                 is not sent for the instruments in that directory.</t>
+             </section>
+             <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
+                 <t>Client may want to be notified when changes were made to instruments
+                 in the instruments database by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;instr-path&gt; will be replaced by the absolute path name
+                 of the instrument, which settings are changed. The front-end will have to send
+                 the respective command to actually get the updated directory info. Because these messages
+                 will be triggered by LSCP commands issued by other clients rather than real
+                 time events happening on the server, it is believed that an empty notification
+                 message is sufficient here.</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
+                 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
+                 the new name of the instrument, encapsulated into apostrophes.</t>
+             </section>
+             <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
+                 <t>Client may want to be notified when the status of particular database
+                 instruments job is changed by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
+                 which status is changed. The front-end will have to send the respective
+                 command to actually get the status info. Because these messages
+                 will be triggered by LSCP commands issued by other clients rather than real
+                 time events happening on the server, it is believed that an empty notification
+                 message is sufficient here.</t>
+             </section>
              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
                  the server by issuing the following command:</t>
-Line 5750 
 Schoenebeck'>
+Line 7194 
 Schoenebeck'>
                  </front>
                  <seriesInfo name="RFC" value="2234" />
              </reference>
+             <reference anchor="RFC20">
+                 <front>
+                     <title>ASCII format for Network Interchange</title>
+                     <author>
+                         <organization>UCLA</organization>
+                     </author>
+                     <date year="1969"></date>
+                 </front>
+                 <seriesInfo name="RFC" value="20" />
+             </reference>
           </references>
      </back>

 Legend:



Removed from v.1136
 


changed lines


 
Added in v.1250
 Legend:



Removed from v.1136
 


changed lines


 
Added in v.1250
-Removed from v.1136
+Added in v.1250

	ViewVC Help
Powered by ViewVC