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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1135 by iliev, Thu Mar 29 09:40:45 2007 UTC revision 1353 by iliev, Mon Sep 17 23:15:25 2007 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol (draft)</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
23  Schoenebeck'>  Schoenebeck'>
24              <organization>              <organization>
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="March" year="2007"/>          <date month="September" year="2007"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 3959  Schoenebeck'> Line 3973  Schoenebeck'>
3973                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
3974                                          </list>                                          </list>
3975                                      </t>                                      </t>
3976                                        <t>INSTRUMENTS_DB_SUPPORT -
3977                                            <list>
3978                                                <t>either yes or no, specifies whether the
3979                                                sampler is build with instruments database support.</t>
3980                                            </list>
3981                                        </t>
3982                                  </list>                                  </list>
3983                              </t>                              </t>
3984                          </list>                          </list>
# Line 4256  Schoenebeck'> Line 4276  Schoenebeck'>
4276                          <list>                          <list>
4277                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4278                              <t>S: "NAME: Standard Map"</t>                              <t>S: "NAME: Standard Map"</t>
4279                                <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4280                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
4281                          </list>                          </list>
4282                      </t>                      </t>
# Line 4318  Schoenebeck'> Line 4339  Schoenebeck'>
4339                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4340                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4341                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4342                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4343                        supporting escape sequences as described in chapter
4344                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4345                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4346                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4347                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
# Line 4733  Schoenebeck'> Line 4756  Schoenebeck'>
4756                  </section>                  </section>
4757              </section>              </section>
4758    
4759    
4760                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4761                    <t>The following commands describe how to use and manage
4762                    the instruments database.</t>
4763                    <t>Notice:</t>
4764                        <t>
4765                            <list>
4766                                <t>All command arguments representing a path or
4767                                instrument/directory name support escape sequences as described in chapter
4768                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4769                                </t>
4770                                <t>All occurrences of a forward slash in instrument and directory
4771                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4772                                </t>
4773                            </list>
4774                        </t>
4775    
4776                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4777                        <t>The front-end can add a new instrument directory to the
4778                        instruments database by sending the following command:</t>
4779                        <t>
4780                            <list>
4781                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
4782                            </list>
4783                        </t>
4784                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4785                        to be created (encapsulated into apostrophes).</t>
4786    
4787                        <t>Possible Answers:</t>
4788                        <t>
4789                            <list>
4790                                <t>"OK" -
4791                                    <list>
4792                                        <t>on success</t>
4793                                    </list>
4794                                </t>
4795                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4796                                    <list>
4797                                        <t>when the directory could not be created, which
4798                                        can happen if the directory already exists or the
4799                                        name contains not allowed symbols</t>
4800                                    </list>
4801                                </t>
4802                            </list>
4803                        </t>
4804    
4805                        <t>Examples:</t>
4806                        <t>
4807                            <list>
4808                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
4809                                <t>S: "OK"</t>
4810                            </list>
4811                        </t>
4812                    </section>
4813    
4814                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
4815                        <t>The front-end can delete a particular instrument directory
4816                        from the instruments database by sending the following command:</t>
4817                        <t>
4818                            <list>
4819                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
4820                            </list>
4821                        </t>
4822                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4823                        to delete. The optional FORCE argument can be used to
4824                        force the deletion of a non-empty directory and all its content.</t>
4825    
4826                        <t>Possible Answers:</t>
4827                        <t>
4828                            <list>
4829                                <t>"OK" -
4830                                    <list>
4831                                        <t>if the directory is deleted successfully</t>
4832                                    </list>
4833                                </t>
4834                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4835                                    <list>
4836                                        <t>if the given directory does not exist, or
4837                                        if trying to delete a non-empty directory,
4838                                        without using the FORCE argument.</t>
4839                                    </list>
4840                                </t>
4841                            </list>
4842                        </t>
4843    
4844                        <t>Examples:</t>
4845                        <t>
4846                            <list>
4847                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
4848                                <t>S: "OK"</t>
4849                            </list>
4850                        </t>
4851                    </section>
4852    
4853                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
4854                        <t>The front-end can retrieve the current amount of
4855                        directories in a specific directory by sending the following command:</t>
4856                        <t>
4857                            <list>
4858                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4859                            </list>
4860                        </t>
4861                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4862                        name of the directory. If RECURSIVE is specified, the number of
4863                        all directories, including those located in subdirectories of the
4864                        specified directory, will be returned.</t>
4865    
4866                        <t>Possible Answers:</t>
4867                        <t>
4868                            <list>
4869                                <t>The current number of instrument directories
4870                                in the specified directory.</t>
4871                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4872                                    <list>
4873                                        <t>if the given directory does not exist.</t>
4874                                    </list>
4875                                </t>
4876                            </list>
4877                        </t>
4878    
4879                        <t>Example:</t>
4880                        <t>
4881                            <list>
4882                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
4883                                <t>S: "2"</t>
4884                            </list>
4885                        </t>
4886                    </section>
4887    
4888                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
4889                        <t>The front-end can retrieve the current list of directories
4890                        in specific directory by sending the following command:</t>
4891                        <t>
4892                            <list>
4893                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4894                            </list>
4895                        </t>
4896                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4897                        name of the directory. If RECURSIVE is specified, the absolute path names
4898                        of all directories, including those located in subdirectories of the
4899                        specified directory, will be returned.</t>
4900    
4901                        <t>Possible Answers:</t>
4902                        <t>
4903                            <list>
4904                                <t>A comma separated list of all instrument directories
4905                                (encapsulated into apostrophes) in the specified directory.</t>
4906                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4907                                    <list>
4908                                        <t>if the given directory does not exist.</t>
4909                                    </list>
4910                                </t>
4911                            </list>
4912                        </t>
4913                        <t>Example:</t>
4914                        <t>
4915                            <list>
4916                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
4917                                <t>S: "'Piano Collection','Percussion Collection'"</t>
4918                            </list>
4919                        </t>
4920                        <t>
4921                            <list>
4922                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
4923                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
4924                            </list>
4925                        </t>
4926                    </section>
4927    
4928                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
4929                        <t>The front-end can ask for the current settings of an
4930                        instrument directory by sending the following command:</t>
4931                        <t>
4932                            <list>
4933                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
4934                            </list>
4935                        </t>
4936                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4937                        name of the directory the front-end is interested in.</t>
4938    
4939                        <t>Possible Answers:</t>
4940                        <t>
4941                            <list>
4942                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4943                                Each answer line begins with the settings category name
4944                                followed by a colon and then a space character &lt;SP&gt; and finally
4945                                the info character string to that setting category. At the
4946                                moment the following categories are defined:</t>
4947    
4948                                <t>
4949                                    <list>
4950                                        <t>DESCRIPTION -
4951                                            <list>
4952                                                <t>A brief description of the directory content.
4953                                                Note that the character string may contain
4954                                                <xref target="character_set">escape sequences</xref>.</t>
4955                                            </list>
4956                                        </t>
4957                                        <t>CREATED -
4958                                            <list>
4959                                                <t>The creation date and time of the directory,
4960                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
4961                                            </list>
4962                                        </t>
4963                                        <t>MODIFIED -
4964                                            <list>
4965                                                <t>The date and time of the last modification of the
4966                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
4967                                            </list>
4968                                        </t>
4969                                    </list>
4970                                </t>
4971                            </list>
4972                        </t>
4973                        <t>The mentioned fields above don't have to be in particular order.</t>
4974    
4975                        <t>Example:</t>
4976                        <t>
4977                            <list>
4978                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
4979                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
4980                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
4981                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
4982                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4983                            </list>
4984                        </t>
4985                    </section>
4986    
4987                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
4988                        <t>The front-end can alter the name of a specific
4989                        instrument directory by sending the following command:</t>
4990                        <t>
4991                            <list>
4992                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
4993                            </list>
4994                        </t>
4995                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
4996                        &lt;name&gt; is the new name for that directory.</t>
4997    
4998                        <t>Possible Answers:</t>
4999                        <t>
5000                            <list>
5001                                <t>"OK" -
5002                                    <list>
5003                                        <t>on success</t>
5004                                    </list>
5005                                </t>
5006                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5007                                    <list>
5008                                        <t>in case the given directory does not exists,
5009                                        or if a directory with name equal to the new
5010                                        name already exists.</t>
5011                                    </list>
5012                                </t>
5013                            </list>
5014                        </t>
5015    
5016                        <t>Example:</t>
5017                        <t>
5018                            <list>
5019                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5020                                <t>S: "OK"</t>
5021                            </list>
5022                        </t>
5023                    </section>
5024    
5025                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5026                        <t>The front-end can move a specific
5027                        instrument directory by sending the following command:</t>
5028                        <t>
5029                            <list>
5030                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5031                            </list>
5032                        </t>
5033                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5034                        to move and &lt;dst&gt; is the location where the directory will
5035                        be moved to.</t>
5036    
5037                        <t>Possible Answers:</t>
5038                        <t>
5039                            <list>
5040                                <t>"OK" -
5041                                    <list>
5042                                        <t>on success</t>
5043                                    </list>
5044                                </t>
5045                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5046                                    <list>
5047                                        <t>in case a given directory does not exists,
5048                                        or if a directory with name equal to the name
5049                                        of the specified directory already exists in
5050                                        the destination directory. Error is also thrown
5051                                        when trying to move a directory to a subdirectory
5052                                        of itself.</t>
5053                                    </list>
5054                                </t>
5055                            </list>
5056                        </t>
5057    
5058                        <t>Example:</t>
5059                        <t>
5060                            <list>
5061                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5062                                <t>S: "OK"</t>
5063                            </list>
5064                        </t>
5065                    </section>
5066    
5067                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5068                        <t>The front-end can copy a specific
5069                        instrument directory by sending the following command:</t>
5070                        <t>
5071                            <list>
5072                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5073                            </list>
5074                        </t>
5075                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5076                        to copy and &lt;dst&gt; is the location where the directory will
5077                        be copied to.</t>
5078    
5079                        <t>Possible Answers:</t>
5080                        <t>
5081                            <list>
5082                                <t>"OK" -
5083                                    <list>
5084                                        <t>on success</t>
5085                                    </list>
5086                                </t>
5087                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5088                                    <list>
5089                                        <t>in case a given directory does not exists,
5090                                        or if a directory with name equal to the name
5091                                        of the specified directory already exists in
5092                                        the destination directory. Error is also thrown
5093                                        when trying to copy a directory to a subdirectory
5094                                        of itself.</t>
5095                                    </list>
5096                                </t>
5097                            </list>
5098                        </t>
5099    
5100                        <t>Example:</t>
5101                        <t>
5102                            <list>
5103                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5104                                <t>S: "OK"</t>
5105                            </list>
5106                        </t>
5107                    </section>
5108    
5109                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5110                        <t>The front-end can alter the description of a specific
5111                        instrument directory by sending the following command:</t>
5112                        <t>
5113                            <list>
5114                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5115                            </list>
5116                        </t>
5117                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5118                        &lt;desc&gt; is the new description for the directory
5119                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5120                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5121    
5122                        <t>Possible Answers:</t>
5123                        <t>
5124                            <list>
5125                                <t>"OK" -
5126                                    <list>
5127                                        <t>on success</t>
5128                                    </list>
5129                                </t>
5130                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5131                                    <list>
5132                                        <t>in case the given directory does not exists.</t>
5133                                    </list>
5134                                </t>
5135                            </list>
5136                        </t>
5137    
5138                        <t>Example:</t>
5139                        <t>
5140                            <list>
5141                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5142                                <t>S: "OK"</t>
5143                            </list>
5144                        </t>
5145                    </section>
5146    
5147                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5148                        <t>The front-end can search for directories
5149                        in specific directory by sending the following command:</t>
5150                        <t>
5151                            <list>
5152                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5153                            </list>
5154                        </t>
5155                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5156                        name of the directory to search in. If NON_RECURSIVE is specified, the
5157                        directories located in subdirectories of the specified directory will not
5158                        be searched. &lt;criteria-list&gt; is a list of search criterias
5159                        in form of "key1=val1 key2=val2 ...". The following criterias are
5160                        allowed:</t>
5161                        <t>
5162                          <t>NAME='&lt;search-string&gt;'
5163                              <list>
5164                                  <t>Restricts the search to directories, which names
5165                                  satisfy the supplied search string (encapsulated into apostrophes,
5166                                  supporting escape sequences as described in chapter
5167                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5168                              </list>
5169                          </t>
5170    
5171                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5172                              <list>
5173                                  <t>Restricts the search to directories, which creation
5174                                  date satisfies the specified period, where &lt;date-after&gt;
5175                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5176                                  If &lt;date-after&gt; is omitted the search is restricted to
5177                                  directories created before &lt;date-before&gt;. If
5178                                  &lt;date-before&gt; is omitted, the search is restricted
5179                                  to directories created after &lt;date-after&gt;.</t>
5180                              </list>
5181                          </t>
5182    
5183                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5184                              <list>
5185                                  <t>Restricts the search to directories, which
5186                                  date of last modification satisfies the specified period, where
5187                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5188                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5189                                  directories, which are last modified before &lt;date-before&gt;. If
5190                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5191                                  which are last modified after &lt;date-after&gt;.</t>
5192                              </list>
5193                          </t>
5194    
5195                          <t>DESCRIPTION='&lt;search-string&gt;'
5196                              <list>
5197                                  <t>Restricts the search to directories with description
5198                                  that satisfies the supplied search string
5199                                  (encapsulated into apostrophes, supporting escape
5200                                  sequences as described in chapter
5201                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5202                              </list>
5203                          </t>
5204                        </t>
5205    
5206                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5207                        word list separated with spaces for OR search and with '+' for AND search.</t>
5208    
5209                        <t>Possible Answers:</t>
5210                        <t>
5211                            <list>
5212                                <t>A comma separated list with the absolute path names (encapsulated into
5213                                apostrophes) of all directories in the specified directory that satisfy
5214                                the supplied search criterias.</t>
5215                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5216                                    <list>
5217                                        <t>if the given directory does not exist.</t>
5218                                    </list>
5219                                </t>
5220                            </list>
5221                        </t>
5222                        <t>Example:</t>
5223                        <t>
5224                            <list>
5225                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5226                                <t>S: "'/Piano Collection'"</t>
5227                            </list>
5228                        </t>
5229                        <t>
5230                            <list>
5231                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5232                                <t>S: "'/Piano Collection','/Percussions'"</t>
5233                            </list>
5234                        </t>
5235                    </section>
5236    
5237                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5238                        <t>The front-end can add one or more instruments
5239                        to the instruments database by sending the following command:</t>
5240                        <t>
5241                            <list>
5242                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5243                            </list>
5244                        </t>
5245                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5246                        (encapsulated into apostrophes) in the instruments database in which
5247                        only the new instruments (that are not already in the database) will
5248                        be added, &lt;file_path&gt; is the absolute path name of a file or
5249                        directory in the file system (encapsulated into apostrophes). In case
5250                        an instrument file is supplied, only the instruments in the specified
5251                        file will be added to the instruments database. If the optional
5252                        &lt;instr_index&gt; (the index of the instrument within the given file)
5253                        is supplied too, then only the specified instrument will be added.
5254                        In case a directory is supplied, the instruments in that directory
5255                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5256                        when a directory is provided as &lt;file_path&gt; and specifies how the
5257                        scanning will be done and has exactly the following possibilities:</t>
5258                        <t>
5259                            <list>
5260                                <t>"RECURSIVE" -
5261                                    <list>
5262                                        <t>All instruments will be processed, including those
5263                                        in the subdirectories, and the respective subdirectory
5264                                        tree structure will be recreated in the instruments
5265                                        database</t>
5266                                    </list>
5267                                </t>
5268                                <t>"NON_RECURSIVE" -
5269                                    <list>
5270                                        <t>Only the instruments in the specified directory
5271                                        will be added, the instruments in the subdirectories
5272                                        will not be processed.</t>
5273                                    </list>
5274                                </t>
5275                                <t>"FLAT" -
5276                                    <list>
5277                                        <t>All instruments will be processed, including those
5278                                        in the subdirectories, but the respective subdirectory
5279                                        structure will not be recreated in the instruments
5280                                        database. All instruments will be added directly in
5281                                        the specified database directory.</t>
5282                                    </list>
5283                                </t>
5284                            </list>
5285                        </t>
5286    
5287                     <t>The difference between regular and NON_MODAL versions of the command
5288                        is that the regular command returns when the scanning is finished
5289                        while NON_MODAL version returns immediately and a background process is launched.
5290                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5291                        command can be used to monitor the scanning progress.</t>
5292    
5293                        <t>Possible Answers:</t>
5294                        <t>
5295                            <list>
5296                                <t>"OK" -
5297                                    <list>
5298                                        <t>on success when NON_MODAL is not supplied</t>
5299                                    </list>
5300                                </t>
5301                                <t>"OK[&lt;job-id&gt;]" -
5302                                    <list>
5303                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5304                                        is a numerical ID used to obtain status information about the job progress.
5305                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5306                                        </t>
5307                                    </list>
5308                                </t>
5309                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5310                                    <list>
5311                                        <t>if an invalid path is specified.</t>
5312                                    </list>
5313                                </t>
5314                            </list>
5315                        </t>
5316    
5317                        <t>Examples:</t>
5318                        <t>
5319                            <list>
5320                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5321                                <t>S: "OK"</t>
5322                            </list>
5323                        </t>
5324                    </section>
5325    
5326                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5327                        <t>The front-end can remove a particular instrument
5328                        from the instruments database by sending the following command:</t>
5329                        <t>
5330                            <list>
5331                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5332                            </list>
5333                        </t>
5334                        <t>Where &lt;instr_path&gt; is the absolute path name
5335                        (in the instruments database) of the instrument to remove.</t>
5336    
5337                        <t>Possible Answers:</t>
5338                        <t>
5339                            <list>
5340                                <t>"OK" -
5341                                    <list>
5342                                        <t>if the instrument is removed successfully</t>
5343                                    </list>
5344                                </t>
5345                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5346                                    <list>
5347                                        <t>if the given path does not exist or
5348                                        is a directory.</t>
5349                                    </list>
5350                                </t>
5351                            </list>
5352                        </t>
5353    
5354                        <t>Examples:</t>
5355                        <t>
5356                            <list>
5357                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5358                                <t>S: "OK"</t>
5359                            </list>
5360                        </t>
5361                    </section>
5362    
5363                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5364                        <t>The front-end can retrieve the current amount of
5365                        instruments in a specific directory by sending the following command:</t>
5366                        <t>
5367                            <list>
5368                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5369                            </list>
5370                        </t>
5371                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5372                        of the directory. If RECURSIVE is specified, the number of all
5373                        instruments, including those located in subdirectories of the
5374                        specified directory, will be returned.</t>
5375    
5376                        <t>Possible Answers:</t>
5377                        <t>
5378                            <list>
5379                                <t>The current number of instruments
5380                                in the specified directory.</t>
5381                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5382                                    <list>
5383                                        <t>if the given directory does not exist.</t>
5384                                    </list>
5385                                </t>
5386                            </list>
5387                        </t>
5388    
5389                        <t>Example:</t>
5390                        <t>
5391                            <list>
5392                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5393                                <t>S: "2"</t>
5394                            </list>
5395                        </t>
5396                    </section>
5397    
5398                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5399                        <t>The front-end can retrieve the current list of instruments
5400                        in specific directory by sending the following command:</t>
5401                        <t>
5402                            <list>
5403                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5404                            </list>
5405                        </t>
5406                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5407                        name of the directory. If RECURSIVE is specified, the absolute path
5408                        names of all instruments, including those located in subdirectories
5409                        of the specified directory, will be returned.</t>
5410    
5411                        <t>Possible Answers:</t>
5412                        <t>
5413                            <list>
5414                                <t>A comma separated list of all instruments
5415                                (encapsulated into apostrophes) in the specified directory.</t>
5416                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5417                                    <list>
5418                                        <t>if the given directory does not exist.</t>
5419                                    </list>
5420                                </t>
5421                            </list>
5422                        </t>
5423                        <t>Example:</t>
5424                        <t>
5425                            <list>
5426                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5427                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5428                            </list>
5429                        </t>
5430                        <t>
5431                            <list>
5432                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5433                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5434                            </list>
5435                        </t>
5436                    </section>
5437    
5438                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5439                        <t>The front-end can ask for the current settings of an
5440                        instrument by sending the following command:</t>
5441                        <t>
5442                            <list>
5443                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5444                            </list>
5445                        </t>
5446                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5447                        name of the instrument the front-end is interested in.</t>
5448    
5449                        <t>Possible Answers:</t>
5450                        <t>
5451                            <list>
5452                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5453                                Each answer line begins with the settings category name
5454                                followed by a colon and then a space character &lt;SP&gt; and finally
5455                                the info character string to that setting category. At the
5456                                moment the following categories are defined:</t>
5457    
5458                                <t>
5459                                    <list>
5460                                        <t>INSTRUMENT_FILE -
5461                                            <list>
5462                                                <t>File name of the instrument.
5463                                                Note that the character string may contain
5464                                                <xref target="character_set">escape sequences</xref>.</t>
5465                                            </list>
5466                                        </t>
5467                                        <t>INSTRUMENT_NR -
5468                                            <list>
5469                                                <t>Index of the instrument within the file.</t>
5470                                            </list>
5471                                        </t>
5472                                        <t>FORMAT_FAMILY -
5473                                            <list>
5474                                                <t>The format family of the instrument.</t>
5475                                            </list>
5476                                        </t>
5477                                        <t>FORMAT_VERSION -
5478                                            <list>
5479                                                <t>The format version of the instrument.</t>
5480                                            </list>
5481                                        </t>
5482                                        <t>SIZE -
5483                                            <list>
5484                                                <t>The size of the instrument in bytes.</t>
5485                                            </list>
5486                                        </t>
5487                                        <t>CREATED -
5488                                            <list>
5489                                                <t>The date and time when the instrument is added
5490                                                in the instruments database, represented in
5491                                               "YYYY-MM-DD HH:MM:SS" format</t>
5492                                            </list>
5493                                        </t>
5494                                        <t>MODIFIED -
5495                                            <list>
5496                                                <t>The date and time of the last modification of the
5497                                                instrument's database settings, represented in
5498                                                "YYYY-MM-DD HH:MM:SS" format</t>
5499                                            </list>
5500                                        </t>
5501                                        <t>DESCRIPTION -
5502                                            <list>
5503                                                <t>A brief description of the instrument.
5504                                                Note that the character string may contain
5505                                                <xref target="character_set">escape sequences</xref>.</t>
5506                                            </list>
5507                                        </t>
5508                                        <t>IS_DRUM -
5509                                            <list>
5510                                                <t>either true or false, determines whether the
5511                                                instrument is a drumkit or a chromatic instrument</t>
5512                                            </list>
5513                                        </t>
5514                                        <t>PRODUCT -
5515                                            <list>
5516                                                <t>The product title of the instrument.
5517                                                Note that the character string may contain
5518                                                <xref target="character_set">escape sequences</xref>.</t>
5519                                            </list>
5520                                        </t>
5521                                        <t>ARTISTS -
5522                                            <list>
5523                                                <t>Lists the artist names.
5524                                                Note that the character string may contain
5525                                                <xref target="character_set">escape sequences</xref>.</t>
5526                                            </list>
5527                                        </t>
5528                                        <t>KEYWORDS -
5529                                            <list>
5530                                                <t>Provides a list of keywords that refer to the instrument.
5531                                                Keywords are separated with semicolon and blank.
5532                                                Note that the character string may contain
5533                                                <xref target="character_set">escape sequences</xref>.</t>
5534                                            </list>
5535                                        </t>
5536                                    </list>
5537                                </t>
5538                            </list>
5539                        </t>
5540                        <t>The mentioned fields above don't have to be in particular order.</t>
5541    
5542                        <t>Example:</t>
5543                        <t>
5544                            <list>
5545                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5546                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5547                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5548                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5549                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5550                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5551                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5552                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5553                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5554                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5555                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5556                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5557                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5558                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5559                            </list>
5560                        </t>
5561                    </section>
5562    
5563                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5564                        <t>The front-end can alter the name of a specific
5565                        instrument by sending the following command:</t>
5566                        <t>
5567                            <list>
5568                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5569                            </list>
5570                        </t>
5571                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5572                        &lt;name&gt; is the new name for that instrument.</t>
5573    
5574                        <t>Possible Answers:</t>
5575                        <t>
5576                            <list>
5577                                <t>"OK" -
5578                                    <list>
5579                                        <t>on success</t>
5580                                    </list>
5581                                </t>
5582                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5583                                    <list>
5584                                        <t>in case the given instrument does not exists,
5585                                        or if an instrument with name equal to the new
5586                                        name already exists.</t>
5587                                    </list>
5588                                </t>
5589                            </list>
5590                        </t>
5591    
5592                        <t>Example:</t>
5593                        <t>
5594                            <list>
5595                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5596                                <t>S: "OK"</t>
5597                            </list>
5598                        </t>
5599                    </section>
5600    
5601                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5602                        <t>The front-end can move a specific instrument to another directory by
5603                        sending the following command:</t>
5604                        <t>
5605                            <list>
5606                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5607                            </list>
5608                        </t>
5609                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5610                        to move and &lt;dst&gt; is the directory where the instrument will
5611                        be moved to.</t>
5612    
5613                        <t>Possible Answers:</t>
5614                        <t>
5615                            <list>
5616                                <t>"OK" -
5617                                    <list>
5618                                        <t>on success</t>
5619                                    </list>
5620                                </t>
5621                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5622                                    <list>
5623                                        <t>in case the given instrument does not exists,
5624                                        or if an instrument with name equal to the name of the
5625                                        specified instrument already exists in the destination
5626                                        directory.</t>
5627                                    </list>
5628                                </t>
5629                            </list>
5630                        </t>
5631    
5632                        <t>Example:</t>
5633                        <t>
5634                            <list>
5635                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
5636                                <t>S: "OK"</t>
5637                            </list>
5638                        </t>
5639                    </section>
5640    
5641                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5642                        <t>The front-end can copy a specific instrument to another directory by
5643                        sending the following command:</t>
5644                        <t>
5645                            <list>
5646                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5647                            </list>
5648                        </t>
5649                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5650                        to copy and &lt;dst&gt; is the directory where the instrument will
5651                        be copied to.</t>
5652    
5653                        <t>Possible Answers:</t>
5654                        <t>
5655                            <list>
5656                                <t>"OK" -
5657                                    <list>
5658                                        <t>on success</t>
5659                                    </list>
5660                                </t>
5661                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5662                                    <list>
5663                                        <t>in case the given instrument does not exists,
5664                                        or if an instrument with name equal to the name of the
5665                                        specified instrument already exists in the destination
5666                                        directory.</t>
5667                                    </list>
5668                                </t>
5669                            </list>
5670                        </t>
5671    
5672                        <t>Example:</t>
5673                        <t>
5674                            <list>
5675                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5676                                <t>S: "OK"</t>
5677                            </list>
5678                        </t>
5679                    </section>
5680    
5681                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5682                        <t>The front-end can alter the description of a specific
5683                        instrument by sending the following command:</t>
5684                        <t>
5685                            <list>
5686                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
5687                            </list>
5688                        </t>
5689                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5690                        &lt;desc&gt; is the new description for the instrument
5691                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5692                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5693    
5694                        <t>Possible Answers:</t>
5695                        <t>
5696                            <list>
5697                                <t>"OK" -
5698                                    <list>
5699                                        <t>on success</t>
5700                                    </list>
5701                                </t>
5702                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5703                                    <list>
5704                                        <t>in case the given instrument does not exists.</t>
5705                                    </list>
5706                                </t>
5707                            </list>
5708                        </t>
5709    
5710                        <t>Example:</t>
5711                        <t>
5712                            <list>
5713                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
5714                                <t>S: "OK"</t>
5715                            </list>
5716                        </t>
5717                    </section>
5718    
5719                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5720                        <t>The front-end can search for instruments
5721                        in specific directory by sending the following command:</t>
5722                        <t>
5723                            <list>
5724                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5725                            </list>
5726                        </t>
5727                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5728                        name of the directory to search in. If NON_RECURSIVE is specified, the
5729                        directories located in subdirectories of the specified directory will not
5730                        be searched. &lt;criteria-list&gt; is a list of search criterias
5731                        in form of "key1=val1 key2=val2 ...". The following criterias are
5732                        allowed:</t>
5733                        <t>
5734                          <t>NAME='&lt;search-string&gt;'
5735                              <list>
5736                                  <t>Restricts the search to instruments, which names
5737                                  satisfy the supplied search string (encapsulated into apostrophes,
5738                                  supporting escape sequences as described in chapter
5739                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5740                              </list>
5741                          </t>
5742    
5743                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5744                              <list>
5745                                  <t>Restricts the search to instruments, which
5746                                  size is in the specified range. If &lt;min&gt; is omitted,
5747                                  the search results are restricted to instruments with size less then
5748                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5749                                  search is restricted to instruments with size greater then
5750                                  or equal to &lt;min&gt;.</t>
5751                              </list>
5752                          </t>
5753    
5754                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5755                              <list>
5756                                  <t>Restricts the search to instruments, which creation
5757                                  date satisfies the specified period, where &lt;date-after&gt;
5758                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5759                                  If &lt;date-after&gt; is omitted the search is restricted to
5760                                  instruments created before &lt;date-before&gt;. If
5761                                  &lt;date-before&gt; is omitted, the search is restricted
5762                                  to instruments created after &lt;date-after&gt;.</t>
5763                              </list>
5764                          </t>
5765    
5766                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5767                              <list>
5768                                  <t>Restricts the search to instruments, which
5769                                  date of last modification satisfies the specified period, where
5770                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5771                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5772                                  instruments, which are last modified before &lt;date-before&gt;. If
5773                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5774                                  which are last modified after &lt;date-after&gt;.</t>
5775                              </list>
5776                          </t>
5777    
5778                          <t>DESCRIPTION='&lt;search-string&gt;'
5779                              <list>
5780                                  <t>Restricts the search to instruments with description
5781                                  that satisfies the supplied search string (encapsulated into apostrophes,
5782                                  supporting escape sequences as described in chapter
5783                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5784                              </list>
5785                          </t>
5786    
5787                          <t>PRODUCT='&lt;search-string&gt;'
5788                              <list>
5789                                  <t>Restricts the search to instruments with product info
5790                                  that satisfies the supplied search string (encapsulated into apostrophes,
5791                                  supporting escape sequences as described in chapter
5792                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5793                              </list>
5794                          </t>
5795    
5796                          <t>ARTISTS='&lt;search-string&gt;'
5797                              <list>
5798                                  <t>Restricts the search to instruments with artists info
5799                                  that satisfies the supplied search string (encapsulated into apostrophes,
5800                                  supporting escape sequences as described in chapter
5801                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5802                              </list>
5803                          </t>
5804    
5805                          <t>KEYWORDS='&lt;search-string&gt;'
5806                              <list>
5807                                  <t>Restricts the search to instruments with keyword list
5808                                  that satisfies the supplied search string (encapsulated into apostrophes,
5809                                  supporting escape sequences as described in chapter
5810                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5811                              </list>
5812                          </t>
5813    
5814                          <t>IS_DRUM=true | false
5815                              <list>
5816                                  <t>Either true or false. Restricts the search to
5817                                  drum kits or chromatic instruments.</t>
5818                              </list>
5819                          </t>
5820    
5821                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5822                              <list>
5823                                  <t>Restricts the search to instruments of the supplied format families,
5824                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5825                              </list>
5826                          </t>
5827                        </t>
5828    
5829                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5830                        word list separated with spaces for OR search and with '+' for AND search.</t>
5831    
5832                        <t>Possible Answers:</t>
5833                        <t>
5834                            <list>
5835                                <t>A comma separated list with the absolute path names (encapsulated into
5836                                apostrophes) of all instruments in the specified directory that satisfy
5837                                the supplied search criterias.</t>
5838                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5839                                    <list>
5840                                        <t>if the given directory does not exist.</t>
5841                                    </list>
5842                                </t>
5843                            </list>
5844                        </t>
5845                        <t>Example:</t>
5846                        <t>
5847                            <list>
5848                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5849                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5850                            </list>
5851                        </t>
5852                        <t>
5853                            <list>
5854                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5855                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5856                            </list>
5857                        </t>
5858                    </section>
5859    
5860                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5861                        <t>The front-end can ask for the current status of a
5862                        particular database instruments job by sending the following command:</t>
5863                        <t>
5864                            <list>
5865                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5866                            </list>
5867                        </t>
5868                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5869                        of the job the front-end is interested in.</t>
5870    
5871                        <t>Possible Answers:</t>
5872                        <t>
5873                            <list>
5874                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5875                                Each answer line begins with the settings category name
5876                                followed by a colon and then a space character &lt;SP&gt; and finally
5877                                the info character string to that setting category. At the
5878                                moment the following categories are defined:</t>
5879    
5880                                <t>
5881                                    <list>
5882                                        <t>FILES_TOTAL -
5883                                            <list>
5884                                                <t>The total number of files scheduled for scanning</t>
5885                                            </list>
5886                                        </t>
5887                                        <t>FILES_SCANNED -
5888                                            <list>
5889                                                <t>The current number of scanned files</t>
5890                                            </list>
5891                                        </t>
5892                                        <t>SCANNING -
5893                                            <list>
5894                                                <t>The absolute path name of the file which is currently
5895                                                being scanned</t>
5896                                            </list>
5897                                        </t>
5898                                        <t>STATUS -
5899                                            <list>
5900                                                <t>An integer value between 0 and 100 indicating the
5901                                                scanning progress percentage of the file which is
5902                                                currently being scanned</t>
5903                                            </list>
5904                                        </t>
5905                                    </list>
5906                                </t>
5907                            </list>
5908                        </t>
5909                        <t>The mentioned fields above don't have to be in particular order.</t>
5910    
5911                        <t>Example:</t>
5912                        <t>
5913                            <list>
5914                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5915                                <t>S: "FILES_TOTAL: 12"</t>
5916                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5917                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5918                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5919                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5920                            </list>
5921                        </t>
5922                    </section>
5923    
5924                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5925                        <t>The front-end can remove all instruments and directories and re-create
5926                        the instruments database structure (e.g., in case of a database corruption)
5927                        by sending the following command:</t>
5928                        <t>
5929                            <list>
5930                                <t>FORMAT INSTRUMENTS_DB</t>
5931                            </list>
5932                        </t>
5933                        
5934                        <t>Possible Answers:</t>
5935                        <t>
5936                            <list>
5937                                <t>"OK" -
5938                                    <list>
5939                                        <t>on success</t>
5940                                    </list>
5941                                </t>
5942                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5943                                    <list>
5944                                        <t>If the formatting of the instruments database
5945                                        failed.</t>
5946                                    </list>
5947                                </t>
5948                            </list>
5949                        </t>
5950                    </section>
5951    
5952                </section>
5953    
5954          </section>          </section>
5955    
5956    
# Line 4808  Schoenebeck'> Line 6026  Schoenebeck'>
6026                  </t>                  </t>
6027                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
6028                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
6029                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
6030                  </t>                  </t>
6031                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
6032                  </t>                  </t>
6033                    <t>/ FIND SP find_instruction
6034                    </t>
6035                    <t>/ MOVE SP move_instruction
6036                    </t>
6037                    <t>/ COPY SP copy_instruction
6038                    </t>
6039                    <t>/ EDIT SP edit_instruction
6040                    </t>
6041                  <t>/ RESET                  <t>/ RESET
6042                  </t>                  </t>
6043                  <t>/ QUIT                  <t>/ QUIT
# Line 4824  Schoenebeck'> Line 6048  Schoenebeck'>
6048          <list>          <list>
6049                  <t>CHANNEL                  <t>CHANNEL
6050                  </t>                  </t>
6051                    <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
6052                    </t>
6053                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
6054                    </t>
6055                    <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
6056                    </t>
6057                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
6058                    </t>
6059                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
6060                    </t>
6061                    <t>/ DB_INSTRUMENTS SP pathname SP pathname
6062                    </t>
6063                    <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
6064                    </t>
6065                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6066                  </t>                  </t>
6067                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
# Line 4862  Schoenebeck'> Line 6100  Schoenebeck'>
6100                  </t>                  </t>
6101                  <t>/ MIDI_INSTRUMENT_INFO                  <t>/ MIDI_INSTRUMENT_INFO
6102                  </t>                  </t>
6103                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6104                    </t>
6105                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6106                    </t>
6107                    <t>/ DB_INSTRUMENT_COUNT
6108                    </t>
6109                    <t>/ DB_INSTRUMENT_INFO
6110                    </t>
6111                    <t>/ DB_INSTRUMENTS_JOB_INFO
6112                    </t>
6113                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6114                  </t>                  </t>
6115                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
# Line 4902  Schoenebeck'> Line 6150  Schoenebeck'>
6150                  </t>                  </t>
6151                  <t>/ MIDI_INSTRUMENT_INFO                  <t>/ MIDI_INSTRUMENT_INFO
6152                  </t>                  </t>
6153                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6154                    </t>
6155                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6156                    </t>
6157                    <t>/ DB_INSTRUMENT_COUNT
6158                    </t>
6159                    <t>/ DB_INSTRUMENT_INFO
6160                    </t>
6161                    <t>/ DB_INSTRUMENTS_JOB_INFO
6162                    </t>
6163                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6164                  </t>                  </t>
6165                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
# Line 4936  Schoenebeck'> Line 6194  Schoenebeck'>
6194                  </t>                  </t>
6195                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6196                  </t>                  </t>
6197                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
6198                    </t>
6199                    <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
6200                    </t>
6201                    <t>/ DB_INSTRUMENT SP pathname
6202                    </t>
6203          </list>          </list>
6204  </t>  </t>
6205  <t>get_instruction =  <t>get_instruction =
# Line 5006  Schoenebeck'> Line 6270  Schoenebeck'>
6270                  </t>                  </t>
6271                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6272                  </t>                  </t>
6273                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
6274                    </t>
6275                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
6276                    </t>
6277                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
6278                    </t>
6279                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
6280                    </t>
6281                    <t>/ DB_INSTRUMENTS SP pathname
6282                    </t>
6283                    <t>/ DB_INSTRUMENT SP INFO SP pathname
6284                    </t>
6285                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6286                    </t>
6287                  <t>/ VOLUME                  <t>/ VOLUME
6288                  </t>                  </t>
6289          </list>          </list>
# Line 5018  Schoenebeck'> Line 6296  Schoenebeck'>
6296                  </t>                  </t>
6297                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6298                  </t>                  </t>
6299                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6300                    </t>
6301                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
6302                  </t>                  </t>
6303                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
# Line 5032  Schoenebeck'> Line 6312  Schoenebeck'>
6312                  </t>                  </t>
6313                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6314                  </t>                  </t>
6315                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname
6316                    </t>
6317                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
6318                    </t>
6319                    <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname
6320                    </t>
6321                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
6322                    </t>
6323                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6324                  </t>                  </t>
6325                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
# Line 5068  Schoenebeck'> Line 6356  Schoenebeck'>
6356                  </t>                  </t>
6357          </list>          </list>
6358  </t>  </t>
6359    <t>find_instruction =
6360            <list>
6361                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
6362                    </t>
6363                    <t>/ DB_INSTRUMENTS SP pathname SP query_val_list
6364                    </t>
6365                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
6366                    </t>
6367                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
6368                    </t>
6369            </list>
6370    </t>
6371    <t>move_instruction =
6372            <list>
6373                    <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
6374                    </t>
6375                    <t>/ DB_INSTRUMENT SP pathname SP pathname
6376                    </t>
6377            </list>
6378    </t>
6379    <t>copy_instruction =
6380            <list>
6381                    <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
6382                    </t>
6383                    <t>/ DB_INSTRUMENT SP pathname SP pathname
6384                    </t>
6385            </list>
6386    </t>
6387  <t>destroy_instruction =  <t>destroy_instruction =
6388          <list>          <list>
6389                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
# Line 5118  Schoenebeck'> Line 6434  Schoenebeck'>
6434                  </t>                  </t>
6435          </list>          </list>
6436  </t>  </t>
6437    <t>edit_instruction =
6438            <list>
6439                    <t>INSTRUMENT SP sampler_channel
6440                    </t>
6441            </list>
6442    </t>
6443  <t>modal_arg =  <t>modal_arg =
6444          <list>          <list>
6445                  <t>/* epsilon (empty argument) */                  <t>/* epsilon (empty argument) */
# Line 5164  Schoenebeck'> Line 6486  Schoenebeck'>
6486                  </t>                  </t>
6487                  <t>/ FX_SENDS SP sampler_channel                  <t>/ FX_SENDS SP sampler_channel
6488                  </t>                  </t>
6489                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
6490                    </t>
6491                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
6492                    </t>
6493                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
6494                    </t>
6495                    <t>/ DB_INSTRUMENTS SP pathname
6496                    </t>
6497          </list>          </list>
6498  </t>  </t>
6499  <t>load_instr_args =  <t>load_instr_args =
# Line 5284  Schoenebeck'> Line 6614  Schoenebeck'>
6614                  </t>                  </t>
6615          </list>          </list>
6616  </t>  </t>
6617  <t>filename =  <t>pathname =
6618            <list>
6619                    <t>stringval
6620                    </t>
6621            </list>
6622    </t>
6623    <t>dirname =
6624          <list>          <list>
6625                  <t>stringval                  <t>stringval
6626                  </t>                  </t>
6627          </list>          </list>
6628  </t>  </t>
6629    <t>filename =
6630            <list>
6631                    <t>stringval_escaped
6632                    </t>
6633            </list>
6634    </t>
6635  <t>map_name =  <t>map_name =
6636          <list>          <list>
6637                  <t>stringval                  <t>stringval
# Line 5328  Schoenebeck'> Line 6670  Schoenebeck'>
6670                  </t>                  </t>
6671          </list>          </list>
6672  </t>  </t>
6673    <t>query_val_list =
6674            <list>
6675                    <t>string '=' query_val
6676                    </t>
6677                    <t>/ query_val_list SP string '=' query_val
6678                    </t>
6679            </list>
6680    </t>
6681    <t>query_val =
6682            <list>
6683                    <t>string
6684                    </t>
6685                    <t>/ stringval
6686                    </t>
6687            </list>
6688    </t>
6689    <t>scan_mode =
6690            <list>
6691                    <t>RECURSIVE
6692                    </t>
6693                    <t>/ NON_RECURSIVE
6694                    </t>
6695                    <t>/ FLAT
6696                    </t>
6697            </list>
6698    </t>
6699    
6700              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6701    
6702                <section title="Character Set and Escape Sequences" anchor="character_set">
6703                    <t>Older versions of this protocol up to and including v1.1 only
6704                    supported the standard ASCII character set (ASCII code 0 - 127)
6705                    <xref target="RFC20"/>, all younger versions of this protocol
6706                    however support the Extended ASCII character set (ASCII code
6707                    0 - 255). The same group of younger protocols also support
6708                    escape sequences, but only for certain, explicitly declared
6709                    parts of the protocol. The supported escape sequences are
6710                    defined as follows:</t>
6711                    <texttable>
6712                        <ttcol>ASCII Character Sequence</ttcol>
6713                        <ttcol>Translated into (Name)</ttcol>
6714                        <c>\n</c> <c>new line</c>
6715                        <c>\r</c> <c>carriage return</c>
6716                        <c>\f</c> <c>form feed</c>
6717                        <c>\t</c> <c>horizontal tab</c>
6718                        <c>\v</c> <c>vertical tab</c>
6719                        <c>\'</c> <c>apostrophe</c>
6720                        <c>\"</c> <c>quotation mark</c>
6721                        <c>\\</c> <c>backslash</c>
6722                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6723                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6724                    </texttable>
6725                    <t>Notice: due to the transition of certain parts of the
6726                    protocol which now support escape sequences, a slight backward
6727                    incompatibility to protocols version v1.1 and younger has been
6728                    introduced. The only difference is that in parts of the protocol
6729                    where escape characters are now supported, a backslash characters
6730                    MUST be escaped as well (that is as double backslash), whereas
6731                    in the old versions a single backslash was sufficient.</t>
6732                </section>
6733          </section>          </section>
6734    
6735          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 5515  Schoenebeck'> Line 6915  Schoenebeck'>
6915              </section>              </section>
6916    
6917              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
6918                  <t>Client may want to be notified when the number of effect sends on                  <t>Client may want to be notified when the number of effect sends on
6919                  a particular sampler channel is changed by issuing the following command:</t>                  a particular sampler channel is changed by issuing the following command:</t>
6920                  <t>                  <t>
6921                      <list>                      <list>
# Line 5671  Schoenebeck'> Line 7071  Schoenebeck'>
7071                  </t>                  </t>
7072              </section>              </section>
7073    
7074                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
7075                    <t>Client may want to be notified when the number of instrument
7076                    directories in a particular directory in the instruments database
7077                    is changed by issuing the following command:</t>
7078                    <t>
7079                        <list>
7080                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
7081                        </list>
7082                    </t>
7083                    <t>Server will start sending the following notification messages:</t>
7084                    <t>
7085                        <list>
7086                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
7087                        </list>
7088                    </t>
7089                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7090                    name of the directory in the instruments database,
7091                    in which the number of directories is changed.</t>
7092                    <t>Note that when a non-empty directory is removed, this event
7093                    is not sent for the subdirectories in that directory.</t>
7094                </section>
7095    
7096                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
7097                    <t>Client may want to be notified when changes were made to directories
7098                    in the instruments database by issuing the following command:</t>
7099                    <t>
7100                        <list>
7101                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
7102                        </list>
7103                    </t>
7104                    <t>Server will start sending the following notification messages:</t>
7105                    <t>
7106                        <list>
7107                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
7108                        </list>
7109                    </t>
7110                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
7111                    of the directory, for which information changes occurred. The front-end will have to send
7112                    the respective command to actually get the updated directory info. Because these messages
7113                    will be triggered by LSCP commands issued by other clients rather than real
7114                    time events happening on the server, it is believed that an empty notification
7115                    message is sufficient here.</t>
7116                    <t>
7117                        <list>
7118                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
7119                        </list>
7120                    </t>
7121                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
7122                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7123                    the new name of the directory, encapsulated into apostrophes.</t>
7124                </section>
7125    
7126                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
7127                    <t>Client may want to be notified when the number of instruments
7128                    in a particular directory in the instruments database
7129                    is changed by issuing the following command:</t>
7130                    <t>
7131                        <list>
7132                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
7133                        </list>
7134                    </t>
7135                    <t>Server will start sending the following notification messages:</t>
7136                    <t>
7137                        <list>
7138                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
7139                        </list>
7140                    </t>
7141                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7142                    name of the directory in the instruments database,
7143                    in which the number of instruments is changed.</t>
7144                    <t>Note that when a non-empty directory is removed, this event
7145                    is not sent for the instruments in that directory.</t>
7146                </section>
7147    
7148                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
7149                    <t>Client may want to be notified when changes were made to instruments
7150                    in the instruments database by issuing the following command:</t>
7151                    <t>
7152                        <list>
7153                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
7154                        </list>
7155                    </t>
7156                    <t>Server will start sending the following notification messages:</t>
7157                    <t>
7158                        <list>
7159                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
7160                        </list>
7161                    </t>
7162                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
7163                    of the instrument, which settings are changed. The front-end will have to send
7164                    the respective command to actually get the updated directory info. Because these messages
7165                    will be triggered by LSCP commands issued by other clients rather than real
7166                    time events happening on the server, it is believed that an empty notification
7167                    message is sufficient here.</t>
7168                    <t>
7169                        <list>
7170                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
7171                        </list>
7172                    </t>
7173                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
7174                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7175                    the new name of the instrument, encapsulated into apostrophes.</t>
7176                </section>
7177    
7178                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7179                    <t>Client may want to be notified when the status of particular database
7180                    instruments job is changed by issuing the following command:</t>
7181                    <t>
7182                        <list>
7183                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7184                        </list>
7185                    </t>
7186                    <t>Server will start sending the following notification messages:</t>
7187                    <t>
7188                        <list>
7189                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7190                        </list>
7191                    </t>
7192                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7193                    which status is changed. The front-end will have to send the respective
7194                    command to actually get the status info. Because these messages
7195                    will be triggered by LSCP commands issued by other clients rather than real
7196                    time events happening on the server, it is believed that an empty notification
7197                    message is sufficient here.</t>
7198                </section>
7199    
7200              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7201                  <t>Client may want to be notified of miscellaneous and debugging events occurring at                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
7202                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
# Line 5749  Schoenebeck'> Line 7275  Schoenebeck'>
7275                  </front>                  </front>
7276                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7277              </reference>              </reference>
7278                <reference anchor="RFC20">
7279                    <front>
7280                        <title>ASCII format for Network Interchange</title>
7281                        <author>
7282                            <organization>UCLA</organization>
7283                        </author>
7284                        <date year="1969"></date>
7285                    </front>
7286                    <seriesInfo name="RFC" value="20" />
7287                </reference>
7288           </references>           </references>
7289      </back>      </back>
7290    
Legend:
Removed from v.1135  
changed lines
  Added in v.1353
  ViewVC Help
Powered by ViewVC