/[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 973 by schoenebeck, Fri Dec 15 21:40:27 2006 UTC revision 1296 by iliev, Wed Aug 15 17:43:34 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="December" year="2006"/>          <date month="June" 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 2555  Schoenebeck'> Line 2569  Schoenebeck'>
2569                                      <t>VOLUME -                                      <t>VOLUME -
2570                                          <list>                                          <list>
2571                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2572                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2573                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2574                                          </list>                                          </list>
2575                                      </t>                                      </t>
# Line 3227  Schoenebeck'> Line 3241  Schoenebeck'>
3241                      </t>                      </t>
3242                  </section>                  </section>
3243    
3244                    <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND">
3245                        <t>The front-end can create an additional effect send on a specific sampler channel
3246                        by sending the following command:</t>
3247                        <t>
3248                            <list>
3249                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3250                            </list>
3251                        </t>
3252                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3253                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3254                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3255                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3256                        is a number between 0..127 defining the MIDI controller which can alter the
3257                        effect send level and &lt;name&gt; is an optional argument defining a name
3258                        for the effect send entity. The name does not have to be unique.</t>
3259    
3260                        <t>By default, that is as initial routing, the effect send's audio channels
3261                        are automatically routed to the last audio channels of the sampler channel's
3262                        audio output device, that way you can i.e. first increase the amount of audio
3263                        channels on the audio output device for having dedicated effect send output
3264                        channels and when "CREATE FX_SEND" is called, those channels will automatically
3265                        be picked. You can alter the destination channels however with
3266                        <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3267                        </t>
3268    
3269                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3270                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3271                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3272                        the voices and route the audio signal afterwards to the master outputs and effect send
3273                        outputs (along with their respective effect send levels). A sampler channel without effect
3274                        sends however can mix its voices directly into the audio output devices's audio buffers
3275                        and is thus faster.
3276                        </t>
3277    
3278                        <t>Possible Answers:</t>
3279                        <t>
3280                            <list>
3281                                <t>"OK[&lt;fx-send-id&gt;]" -
3282                                    <list>
3283                                        <t>in case a new effect send could be added to the
3284                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3285                                        unique ID of the newly created effect send entity</t>
3286                                    </list>
3287                                </t>
3288                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3289                                    <list>
3290                                        <t>when a new effect send could not be added, i.e.
3291                                        due to invalid parameters</t>
3292                                    </list>
3293                                </t>
3294                            </list>
3295                        </t>
3296    
3297                        <t>Examples:</t>
3298                        <t>
3299                            <list>
3300                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3301                                <t>S: "OK[0]"</t>
3302                            </list>
3303                        </t>
3304                        <t>
3305                            <list>
3306                                <t>C: "CREATE FX_SEND 0 93"</t>
3307                                <t>S: "OK[1]"</t>
3308                            </list>
3309                        </t>
3310                    </section>
3311    
3312                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND">
3313                        <t>The front-end can remove an existing effect send on a specific sampler channel
3314                        by sending the following command:</t>
3315                        <t>
3316                            <list>
3317                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3318                            </list>
3319                        </t>
3320                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3321                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3322                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3323                        sampler channel from which the effect send should be removed from and
3324                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3325                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3326                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3327    
3328                        <t>Possible Answers:</t>
3329                        <t>
3330                            <list>
3331                                <t>"OK" -
3332                                    <list>
3333                                        <t>on success</t>
3334                                    </list>
3335                                </t>
3336                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3337                                    <list>
3338                                        <t>in case it failed, providing an appropriate error code and
3339                                        error message</t>
3340                                    </list>
3341                                </t>
3342                            </list>
3343                        </t>
3344    
3345                        <t>Example:</t>
3346                        <t>
3347                            <list>
3348                                <t>C: "DESTROY FX_SEND 0 0"</t>
3349                                <t>S: "OK"</t>
3350                            </list>
3351                        </t>
3352                    </section>
3353    
3354                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS">
3355                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3356                        by sending the following command:</t>
3357                        <t>
3358                            <list>
3359                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3360                            </list>
3361                        </t>
3362                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3363                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3364                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3365    
3366                        <t>Possible Answers:</t>
3367                        <t>
3368                            <list>
3369                                <t>The sampler will answer by returning the number of effect
3370                                sends on the given sampler channel.</t>
3371                            </list>
3372                        </t>
3373    
3374                        <t>Example:</t>
3375                        <t>
3376                            <list>
3377                                <t>C: "GET FX_SENDS 0"</t>
3378                                <t>S: "2"</t>
3379                            </list>
3380                        </t>
3381                    </section>
3382    
3383                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS">
3384                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3385                        by sending the following command:</t>
3386                        <t>
3387                            <list>
3388                                <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3389                            </list>
3390                        </t>
3391                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3392                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3393                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3394    
3395                        <t>Possible Answers:</t>
3396                        <t>
3397                            <list>
3398                                <t>The sampler will answer by returning a comma separated list
3399                                with all effect sends' numerical IDs on the given sampler
3400                                channel.</t>
3401                            </list>
3402                        </t>
3403    
3404                        <t>Examples:</t>
3405                        <t>
3406                            <list>
3407                                <t>C: "LIST FX_SENDS 0"</t>
3408                                <t>S: "0,1"</t>
3409                            </list>
3410                        </t>
3411                        <t>
3412                            <list>
3413                                <t>C: "LIST FX_SENDS 1"</t>
3414                                <t>S: ""</t>
3415                            </list>
3416                        </t>
3417                    </section>
3418    
3419                    <section title="Getting effect send information" anchor="GET FX_SEND INFO">
3420                        <t>The front-end can ask for the current settings of an effect send entity
3421                        by sending the following command:</t>
3422                        <t>
3423                            <list>
3424                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3425                            </list>
3426                        </t>
3427                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3428                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3429                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3430                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3431                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3432                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3433                       </t>
3434    
3435                        <t>Possible Answers:</t>
3436                        <t>
3437                            <list>
3438                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3439                                Each answer line begins with the settings category name
3440                                followed by a colon and then a space character &lt;SP&gt; and finally
3441                                the info character string to that setting category. At the
3442                                moment the following categories are defined:</t>
3443    
3444                                <t>
3445                                    <list>
3446                                        <t>NAME -
3447                                            <list>
3448                                                <t>name of the effect send entity</t>
3449                                            </list>
3450                                        </t>
3451                                        <t>MIDI_CONTROLLER -
3452                                            <list>
3453                                                <t>a value between 0 and 127 reflecting the MIDI controller
3454                                                which is able to modify the effect send's send level</t>
3455                                            </list>
3456                                        </t>
3457                                        <t>LEVEL -
3458                                            <list>
3459                                                <t>optionally dotted number reflecting the effect send's
3460                                                current send level (where a value &lt; 1.0 means attenuation
3461                                                and a value > 1.0 means amplification)</t>
3462                                            </list>
3463                                        </t>
3464                                        <t>AUDIO_OUTPUT_ROUTING -
3465                                            <list>
3466                                                <t>comma separated list which reflects to which audio
3467                                                channel of the selected audio output device each
3468                                                effect send output channel is routed to, e.g. "0,3" would
3469                                                mean the effect send's output channel 0 is routed to channel
3470                                                0 of the audio output device and the effect send's output
3471                                                channel 1 is routed to the channel 3 of the audio
3472                                                output device (see
3473                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3474                                                for details)</t>
3475                                            </list>
3476                                        </t>
3477                                    </list>
3478                                </t>
3479                            </list>
3480                        </t>
3481                        <t>The mentioned fields above don't have to be in particular order.</t>
3482    
3483                        <t>Example:</t>
3484                        <t>
3485                            <list>
3486                                <t>C: "GET FX_SEND INFO 0 0"</t>
3487                                <t>S: "NAME: Reverb Send"</t>
3488                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3489                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3490                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3491                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3492                            </list>
3493                        </t>
3494                    </section>
3495    
3496                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME">
3497                        <t>The front-end can alter the current name of an effect
3498                        send entity by sending the following command:</t>
3499                        <t>
3500                            <list>
3501                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3502                            </list>
3503                        </t>
3504                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3505                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3506                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3507                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3508                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3509                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3510                        &lt;name&gt; is the new name of the effect send entity, which
3511                        does not have to be unique.</t>
3512    
3513                        <t>Possible Answers:</t>
3514                        <t>
3515                            <list>
3516                                <t>"OK" -
3517                                    <list>
3518                                        <t>on success</t>
3519                                    </list>
3520                                </t>
3521                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3522                                    <list>
3523                                        <t>in case it failed, providing an appropriate error code and error message</t>
3524                                    </list>
3525                                </t>
3526                            </list>
3527                        </t>
3528                        <t>Example:</t>
3529                        <t>
3530                            <list>
3531                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3532                                <t>S: "OK"</t>
3533                            </list>
3534                        </t>
3535                    </section>
3536    
3537                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL">
3538                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3539                        sampler channel by sending the following command:</t>
3540                        <t>
3541                            <list>
3542                                <t>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;</t>
3543                            </list>
3544                        </t>
3545                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3546                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3547                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3548                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3549                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3550                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3551                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3552                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3553                        the audio channel of the selected audio output device where &lt;audio-src&gt;
3554                        should be routed to.</t>
3555    
3556                        <t>Note that effect sends can only route audio to the same audio output
3557                        device as assigned to the effect send's sampler channel. Also note that an
3558                        effect send entity does always have exactly as much audio channels as its
3559                        sampler channel. So if the sampler channel is stereo, the effect send does
3560                        have two audio channels as well. Also keep in mind that the amount of audio
3561                        channels on a sampler channel might be dependant not only to the deployed
3562                        sampler engine on the sampler channel, but also dependant to the instrument
3563                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3564                        send into a mono one by simply altering its audio routing appropriately.</t>
3565    
3566                        <t>Possible Answers:</t>
3567                        <t>
3568                            <list>
3569                                <t>"OK" -
3570                                    <list>
3571                                        <t>on success</t>
3572                                    </list>
3573                                </t>
3574                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3575                                    <list>
3576                                        <t>if audio output channel was set, but there are noteworthy
3577                                        issue(s) related, providing an appropriate warning code and
3578                                        warning message</t>
3579                                    </list>
3580                                </t>
3581                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3582                                    <list>
3583                                        <t>in case it failed, providing an appropriate error code and error message</t>
3584                                    </list>
3585                                </t>
3586                            </list>
3587                        </t>
3588                        <t>Example:</t>
3589                        <t>
3590                            <list>
3591                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3592                                <t>S: "OK"</t>
3593                            </list>
3594                        </t>
3595                    </section>
3596    
3597                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3598                        <t>The front-end can alter the MIDI controller of an effect
3599                        send entity by sending the following command:</t>
3600                        <t>
3601                            <list>
3602                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
3603                            </list>
3604                        </t>
3605                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3606                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3607                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3608                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3609                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3610                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3611                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
3612                        able to modify the effect send's send level.</t>
3613    
3614                        <t>Possible Answers:</t>
3615                        <t>
3616                            <list>
3617                                <t>"OK" -
3618                                    <list>
3619                                        <t>on success</t>
3620                                    </list>
3621                                </t>
3622                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3623                                    <list>
3624                                        <t>if MIDI controller was set, but there are noteworthy
3625                                        issue(s) related, providing an appropriate warning code and
3626                                        warning message</t>
3627                                    </list>
3628                                </t>
3629                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3630                                    <list>
3631                                        <t>in case it failed, providing an appropriate error code and error message</t>
3632                                    </list>
3633                                </t>
3634                            </list>
3635                        </t>
3636                        <t>Example:</t>
3637                        <t>
3638                            <list>
3639                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
3640                                <t>S: "OK"</t>
3641                            </list>
3642                        </t>
3643                    </section>
3644    
3645                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL">
3646                        <t>The front-end can alter the current send level of an effect
3647                        send entity by sending the following command:</t>
3648                        <t>
3649                            <list>
3650                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
3651                            </list>
3652                        </t>
3653                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3654                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3655                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3656                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3657                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3658                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3659                        &lt;volume&gt; is an optionally dotted positive number (a value
3660                        smaller than 1.0 means attenuation, whereas a value greater than
3661                        1.0 means amplification) reflecting the new send level.</t>
3662    
3663                        <t>Possible Answers:</t>
3664                        <t>
3665                            <list>
3666                                <t>"OK" -
3667                                    <list>
3668                                        <t>on success</t>
3669                                    </list>
3670                                </t>
3671                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3672                                    <list>
3673                                        <t>if new send level was set, but there are noteworthy
3674                                        issue(s) related, providing an appropriate warning code and
3675                                        warning message</t>
3676                                    </list>
3677                                </t>
3678                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3679                                    <list>
3680                                        <t>in case it failed, providing an appropriate error code and error message</t>
3681                                    </list>
3682                                </t>
3683                            </list>
3684                        </t>
3685                        <t>Example:</t>
3686                        <t>
3687                            <list>
3688                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
3689                                <t>S: "OK"</t>
3690                            </list>
3691                        </t>
3692                    </section>
3693    
3694                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3695                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>
3696                      <t>                      <t>
# Line 3509  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 3516  Schoenebeck'> Line 3986  Schoenebeck'>
3986                      <t>The mentioned fields above don't have to be in particular order.                      <t>The mentioned fields above don't have to be in particular order.
3987                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
3988                  </section>                  </section>
3989    
3990                    <section title="Getting global volume attenuation" anchor="GET VOLUME">
3991                        <t>The client can ask for the current global sampler-wide volume
3992                        attenuation by sending the following command:</t>
3993                        <t>
3994                            <list>
3995                                <t>GET VOLUME</t>
3996                            </list>
3997                        </t>
3998                        <t>Possible Answers:</t>
3999                        <t>
4000                            <list>
4001                                <t>The sampler will always answer by returning the optional
4002                                dotted floating point coefficient, reflecting the current
4003                                global volume attenuation.
4004                                </t>
4005                            </list>
4006                        </t>
4007                        <t>Note: it is up to the respective sampler engine whether to obey
4008                        that global volume parameter or not, but in general all engines SHOULD
4009                        use this parameter.</t>
4010                    </section>
4011    
4012                    <section title="Setting global volume attenuation" anchor="SET VOLUME">
4013                        <t>The client can alter the current global sampler-wide volume
4014                        attenuation by sending the following command:</t>
4015                        <t>
4016                            <list>
4017                                <t>SET VOLUME &lt;volume&gt;</t>
4018                            </list>
4019                        </t>
4020                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4021                       floating point value, reflecting the new global volume parameter.
4022                       This value might usually be in the range between 0.0 and 1.0, that
4023                       is for attenuating the overall volume.</t>
4024    
4025                        <t>Possible Answers:</t>
4026                        <t>
4027                            <list>
4028                                <t>"OK" -
4029                                    <list>
4030                                        <t>on success</t>
4031                                    </list>
4032                                </t>
4033                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4034                                    <list>
4035                                        <t>if the global volume was set, but there are noteworthy
4036                                        issue(s) related, providing an appropriate warning code and
4037                                        warning message</t>
4038                                    </list>
4039                                </t>
4040                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4041                                    <list>
4042                                        <t>in case it failed, providing an appropriate error code and error message</t>
4043                                    </list>
4044                                </t>
4045                            </list>
4046                        </t>
4047                    </section>
4048              </section>              </section>
4049    
4050    
# Line 3730  Schoenebeck'> Line 4259  Schoenebeck'>
4259                                              which does not have to be unique</t>                                              which does not have to be unique</t>
4260                                          </list>                                          </list>
4261                                      </t>                                      </t>
4262                                        <t>DEFAULT -
4263                                            <list>
4264                                                <t>either true or false,
4265                                                defines whether this map is the default map</t>
4266                                            </list>
4267                                        </t>
4268                                  </list>                                  </list>
4269                              </t>                              </t>
4270                          </list>                          </list>
# Line 3741  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 3789  Schoenebeck'> Line 4325  Schoenebeck'>
4325                      command:</t>                      command:</t>
4326                      <t>                      <t>
4327                          <list>                          <list>
4328                              <t>MAP MIDI_INSTRUMENT &lt;map&gt;                              <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
4329                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
4330                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
4331                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
# Line 3803  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
4348                      value < 1.0 means attenuation and a value > 1.0 means                      value &lt; 1.0 means attenuation and a value > 1.0 means
4349                      amplification). This parameter easily allows to adjust the                      amplification). This parameter easily allows to adjust the
4350                      volume of all intruments within a custom instrument map                      volume of all intruments within a custom instrument map
4351                      without having to adjust their instrument files. The                      without having to adjust their instrument files. The
# Line 3842  Schoenebeck'> Line 4380  Schoenebeck'>
4380                              <t>"PERSISTENT" -                              <t>"PERSISTENT" -
4381                                  <list>                                  <list>
4382                                      <t>The instrument will immediately be loaded                                      <t>The instrument will immediately be loaded
4383                                      into memory in the background when this mapping                                      into memory when this mapping
4384                                      command is sent and the instrument is kept all                                      command is sent and the instrument is kept all
4385                                      the time. Instruments with this mode are                                      the time. Instruments with this mode are
4386                                      only freed when the sampler is reset or all                                      only freed when the sampler is reset or all
# Line 3892  Schoenebeck'> Line 4430  Schoenebeck'>
4430                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4431                      </t>                      </t>
4432                      <t>                      <t>
4433                      The "MAP MIDI_INSTRUMENT" command                      By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4434                      will immediately return, thus it will not block when an                      completely established in the sampler. The OPTIONAL "NON_MODAL" argument
4435                      instrument is to be loaded due to a "PERSISTENT" type                      however causes the respective "MAP MIDI_INSTRUMENT" command to return
4436                      entry as instruments are loaded in the background. As a                      immediately, that is to let the sampler establish the mapping in the
4437                      consequence this command may not necessarily return an error                      background. So this argument might be especially useful for mappings with
4438                      i.e. when the given instrument file does not exist or may                      a "PERSISTENT" type, because these have to load the respective instruments
4439                      turn out to be corrupt.                      immediately and might thus block for a very long time. It is recommended
4440                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
4441                        because it has the following drawbacks: as "NON_MODAL" instructions return
4442                        immediately, they may not necessarily return an error i.e. when the given
4443                        instrument file turns out to be corrupt, beside that subsequent commands
4444                        in a LSCP instruction sequence might fail, because mandatory mappings are
4445                        not yet completed.
4446                      </t>                      </t>
4447    
4448                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3941  Schoenebeck'> Line 4485  Schoenebeck'>
4485                      </t>                      </t>
4486                      <t>                      <t>
4487                          <list>                          <list>
4488                              <t>C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>                              <t>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
4489                              <t>S: "OK"</t>                              <t>S: "OK"</t>
4490                          </list>                          </list>
4491                      </t>                      </t>
# Line 4140  Schoenebeck'> Line 4684  Schoenebeck'>
4684                              <t>"VOLUME" -                              <t>"VOLUME" -
4685                                  <list>                                  <list>
4686                                      <t>master volume of the instrument as optionally                                      <t>master volume of the instrument as optionally
4687                                      dotted number (where a value < 1.0 means attenuation                                      dotted number (where a value &lt; 1.0 means attenuation
4688                                      and a value > 1.0 means amplification)</t>                                      and a value > 1.0 means amplification)</t>
4689                                  </list>                                  </list>
4690                              </t>                              </t>
# Line 4212  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    
4764                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4765                        <t>The front-end can add a new instrument directory to the
4766                        instruments database by sending the following command:</t>
4767                        <t>
4768                            <list>
4769                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
4770                            </list>
4771                        </t>
4772                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4773                        to be created (encapsulated into apostrophes).</t>
4774    
4775                        <t>Possible Answers:</t>
4776                        <t>
4777                            <list>
4778                                <t>"OK" -
4779                                    <list>
4780                                        <t>on success</t>
4781                                    </list>
4782                                </t>
4783                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4784                                    <list>
4785                                        <t>when the directory could not be created, which
4786                                        can happen if the directory already exists or the
4787                                        name contains not allowed symbols</t>
4788                                    </list>
4789                                </t>
4790                            </list>
4791                        </t>
4792    
4793                        <t>Examples:</t>
4794                        <t>
4795                            <list>
4796                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
4797                                <t>S: "OK"</t>
4798                            </list>
4799                        </t>
4800                    </section>
4801    
4802                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
4803                        <t>The front-end can delete a particular instrument directory
4804                        from the instruments database by sending the following command:</t>
4805                        <t>
4806                            <list>
4807                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
4808                            </list>
4809                        </t>
4810                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4811                        to delete. The optional FORCE argument can be used to
4812                        force the deletion of a non-empty directory and all its content.</t>
4813    
4814                        <t>Possible Answers:</t>
4815                        <t>
4816                            <list>
4817                                <t>"OK" -
4818                                    <list>
4819                                        <t>if the directory is deleted successfully</t>
4820                                    </list>
4821                                </t>
4822                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4823                                    <list>
4824                                        <t>if the given directory does not exist, or
4825                                        if trying to delete a non-empty directory,
4826                                        without using the FORCE argument.</t>
4827                                    </list>
4828                                </t>
4829                            </list>
4830                        </t>
4831    
4832                        <t>Examples:</t>
4833                        <t>
4834                            <list>
4835                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
4836                                <t>S: "OK"</t>
4837                            </list>
4838                        </t>
4839                    </section>
4840    
4841                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
4842                        <t>The front-end can retrieve the current amount of
4843                        directories in a specific directory by sending the following command:</t>
4844                        <t>
4845                            <list>
4846                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4847                            </list>
4848                        </t>
4849                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4850                        name of the directory. If RECURSIVE is specified, the number of
4851                        all directories, including those located in subdirectories of the
4852                        specified directory, will be returned.</t>
4853    
4854                        <t>Possible Answers:</t>
4855                        <t>
4856                            <list>
4857                                <t>The current number of instrument directories
4858                                in the specified directory.</t>
4859                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4860                                    <list>
4861                                        <t>if the given directory does not exist.</t>
4862                                    </list>
4863                                </t>
4864                            </list>
4865                        </t>
4866    
4867                        <t>Example:</t>
4868                        <t>
4869                            <list>
4870                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
4871                                <t>S: "2"</t>
4872                            </list>
4873                        </t>
4874                    </section>
4875    
4876                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
4877                        <t>The front-end can retrieve the current list of directories
4878                        in specific directory by sending the following command:</t>
4879                        <t>
4880                            <list>
4881                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4882                            </list>
4883                        </t>
4884                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4885                        name of the directory. If RECURSIVE is specified, the absolute path names
4886                        of all directories, including those located in subdirectories of the
4887                        specified directory, will be returned.</t>
4888    
4889                        <t>Possible Answers:</t>
4890                        <t>
4891                            <list>
4892                                <t>A comma separated list of all instrument directories
4893                                (encapsulated into apostrophes) in the specified directory.</t>
4894                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4895                                    <list>
4896                                        <t>if the given directory does not exist.</t>
4897                                    </list>
4898                                </t>
4899                            </list>
4900                        </t>
4901                        <t>Example:</t>
4902                        <t>
4903                            <list>
4904                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
4905                                <t>S: "'Piano Collection','Percussion Collection'"</t>
4906                            </list>
4907                        </t>
4908                        <t>
4909                            <list>
4910                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
4911                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
4912                            </list>
4913                        </t>
4914                    </section>
4915    
4916                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
4917                        <t>The front-end can ask for the current settings of an
4918                        instrument directory by sending the following command:</t>
4919                        <t>
4920                            <list>
4921                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
4922                            </list>
4923                        </t>
4924                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4925                        name of the directory the front-end is interested in.</t>
4926    
4927                        <t>Possible Answers:</t>
4928                        <t>
4929                            <list>
4930                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4931                                Each answer line begins with the settings category name
4932                                followed by a colon and then a space character &lt;SP&gt; and finally
4933                                the info character string to that setting category. At the
4934                                moment the following categories are defined:</t>
4935    
4936                                <t>
4937                                    <list>
4938                                        <t>DESCRIPTION -
4939                                            <list>
4940                                                <t>A brief description of the directory content</t>
4941                                            </list>
4942                                        </t>
4943                                        <t>CREATED -
4944                                            <list>
4945                                                <t>The creation date and time of the directory,
4946                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
4947                                            </list>
4948                                        </t>
4949                                        <t>MODIFIED -
4950                                            <list>
4951                                                <t>The date and time of the last modification of the
4952                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
4953                                            </list>
4954                                        </t>
4955                                    </list>
4956                                </t>
4957                            </list>
4958                        </t>
4959                        <t>The mentioned fields above don't have to be in particular order.</t>
4960    
4961                        <t>Example:</t>
4962                        <t>
4963                            <list>
4964                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
4965                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
4966                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
4967                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
4968                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4969                            </list>
4970                        </t>
4971                    </section>
4972    
4973                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
4974                        <t>The front-end can alter the name of a specific
4975                        instrument directory by sending the following command:</t>
4976                        <t>
4977                            <list>
4978                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
4979                            </list>
4980                        </t>
4981                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
4982                        &lt;name&gt; is the new name for that directory.</t>
4983    
4984                        <t>Possible Answers:</t>
4985                        <t>
4986                            <list>
4987                                <t>"OK" -
4988                                    <list>
4989                                        <t>on success</t>
4990                                    </list>
4991                                </t>
4992                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4993                                    <list>
4994                                        <t>in case the given directory does not exists,
4995                                        or if a directory with name equal to the new
4996                                        name already exists.</t>
4997                                    </list>
4998                                </t>
4999                            </list>
5000                        </t>
5001    
5002                        <t>Example:</t>
5003                        <t>
5004                            <list>
5005                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5006                                <t>S: "OK"</t>
5007                            </list>
5008                        </t>
5009                    </section>
5010    
5011                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5012                        <t>The front-end can move a specific
5013                        instrument directory by sending the following command:</t>
5014                        <t>
5015                            <list>
5016                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5017                            </list>
5018                        </t>
5019                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5020                        to move and &lt;dst&gt; is the location where the directory will
5021                        be moved to.</t>
5022    
5023                        <t>Possible Answers:</t>
5024                        <t>
5025                            <list>
5026                                <t>"OK" -
5027                                    <list>
5028                                        <t>on success</t>
5029                                    </list>
5030                                </t>
5031                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5032                                    <list>
5033                                        <t>in case a given directory does not exists,
5034                                        or if a directory with name equal to the name
5035                                        of the specified directory already exists in
5036                                        the destination directory. Error is also thrown
5037                                        when trying to move a directory to a subdirectory
5038                                        of itself.</t>
5039                                    </list>
5040                                </t>
5041                            </list>
5042                        </t>
5043    
5044                        <t>Example:</t>
5045                        <t>
5046                            <list>
5047                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5048                                <t>S: "OK"</t>
5049                            </list>
5050                        </t>
5051                    </section>
5052    
5053                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5054                        <t>The front-end can copy a specific
5055                        instrument directory by sending the following command:</t>
5056                        <t>
5057                            <list>
5058                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5059                            </list>
5060                        </t>
5061                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5062                        to copy and &lt;dst&gt; is the location where the directory will
5063                        be copied to.</t>
5064    
5065                        <t>Possible Answers:</t>
5066                        <t>
5067                            <list>
5068                                <t>"OK" -
5069                                    <list>
5070                                        <t>on success</t>
5071                                    </list>
5072                                </t>
5073                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5074                                    <list>
5075                                        <t>in case a given directory does not exists,
5076                                        or if a directory with name equal to the name
5077                                        of the specified directory already exists in
5078                                        the destination directory. Error is also thrown
5079                                        when trying to copy a directory to a subdirectory
5080                                        of itself.</t>
5081                                    </list>
5082                                </t>
5083                            </list>
5084                        </t>
5085    
5086                        <t>Example:</t>
5087                        <t>
5088                            <list>
5089                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5090                                <t>S: "OK"</t>
5091                            </list>
5092                        </t>
5093                    </section>
5094    
5095                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5096                        <t>The front-end can alter the description of a specific
5097                        instrument directory by sending the following command:</t>
5098                        <t>
5099                            <list>
5100                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5101                            </list>
5102                        </t>
5103                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5104                        &lt;desc&gt; is the new description for the directory.</t>
5105    
5106                        <t>Possible Answers:</t>
5107                        <t>
5108                            <list>
5109                                <t>"OK" -
5110                                    <list>
5111                                        <t>on success</t>
5112                                    </list>
5113                                </t>
5114                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5115                                    <list>
5116                                        <t>in case the given directory does not exists.</t>
5117                                    </list>
5118                                </t>
5119                            </list>
5120                        </t>
5121    
5122                        <t>Example:</t>
5123                        <t>
5124                            <list>
5125                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5126                                <t>S: "OK"</t>
5127                            </list>
5128                        </t>
5129                    </section>
5130    
5131                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5132                        <t>The front-end can search for directories
5133                        in specific directory by sending the following command:</t>
5134                        <t>
5135                            <list>
5136                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5137                            </list>
5138                        </t>
5139                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5140                        name of the directory to search in. If NON_RECURSIVE is specified, the
5141                        directories located in subdirectories of the specified directory will not
5142                        be searched. &lt;criteria-list&gt; is a list of search criterias
5143                        in form of "key1=val1 key2=val2 ...". The following criterias are
5144                        allowed:</t>
5145                        <t>
5146                          <t>NAME='&lt;search-string&gt;'
5147                              <list>
5148                                  <t>Restricts the search to directories, which names
5149                                  satisfy the supplied search string.</t>
5150                              </list>
5151                          </t>
5152    
5153                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5154                              <list>
5155                                  <t>Restricts the search to directories, which creation
5156                                  date satisfies the specified period, where &lt;date-after&gt;
5157                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5158                                  If &lt;date-after&gt; is omitted the search is restricted to
5159                                  directories created before &lt;date-before&gt;. If
5160                                  &lt;date-before&gt; is omitted, the search is restricted
5161                                  to directories created after &lt;date-after&gt;.</t>
5162                              </list>
5163                          </t>
5164    
5165                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5166                              <list>
5167                                  <t>Restricts the search to directories, which
5168                                  date of last modification satisfies the specified period, where
5169                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5170                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5171                                  directories, which are last modified before &lt;date-before&gt;. If
5172                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5173                                  which are last modified after &lt;date-after&gt;.</t>
5174                              </list>
5175                          </t>
5176    
5177                          <t>DESCRIPTION='&lt;search-string&gt;'
5178                              <list>
5179                                  <t>Restricts the search to directories with description
5180                                  that satisfies the supplied search string.</t>
5181                              </list>
5182                          </t>
5183                        </t>
5184    
5185                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5186                        word list separated with spaces for OR search and with '+' for AND search.</t>
5187    
5188                        <t>Possible Answers:</t>
5189                        <t>
5190                            <list>
5191                                <t>A comma separated list with the absolute path names (encapsulated into
5192                                apostrophes) of all directories in the specified directory that satisfy
5193                                the supplied search criterias.</t>
5194                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5195                                    <list>
5196                                        <t>if the given directory does not exist.</t>
5197                                    </list>
5198                                </t>
5199                            </list>
5200                        </t>
5201                        <t>Example:</t>
5202                        <t>
5203                            <list>
5204                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5205                                <t>S: "'/Piano Collection'"</t>
5206                            </list>
5207                        </t>
5208                        <t>
5209                            <list>
5210                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5211                                <t>S: "'/Piano Collection','/Percussions'"</t>
5212                            </list>
5213                        </t>
5214                    </section>
5215    
5216                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5217                        <t>The front-end can add one or more instruments
5218                        to the instruments database by sending the following command:</t>
5219                        <t>
5220                            <list>
5221                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5222                            </list>
5223                        </t>
5224                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5225                        (encapsulated into apostrophes) in the instruments database in which
5226                        only the new instruments (that are not already in the database) will
5227                        be added, &lt;file_path&gt; is the absolute path name of a file or
5228                        directory in the file system (encapsulated into apostrophes). In case
5229                        an instrument file is supplied, only the instruments in the specified
5230                        file will be added to the instruments database. If the optional
5231                        &lt;instr_index&gt; (the index of the instrument within the given file)
5232                        is supplied too, then only the specified instrument will be added.
5233                        In case a directory is supplied, the instruments in that directory
5234                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5235                        when a directory is provided as &lt;file_path&gt; and specifies how the
5236                        scanning will be done and has exactly the following possibilities:</t>
5237                        <t>
5238                            <list>
5239                                <t>"RECURSIVE" -
5240                                    <list>
5241                                        <t>All instruments will be processed, including those
5242                                        in the subdirectories, and the respective subdirectory
5243                                        tree structure will be recreated in the instruments
5244                                        database</t>
5245                                    </list>
5246                                </t>
5247                                <t>"NON_RECURSIVE" -
5248                                    <list>
5249                                        <t>Only the instruments in the specified directory
5250                                        will be added, the instruments in the subdirectories
5251                                        will not be processed.</t>
5252                                    </list>
5253                                </t>
5254                                <t>"FLAT" -
5255                                    <list>
5256                                        <t>All instruments will be processed, including those
5257                                        in the subdirectories, but the respective subdirectory
5258                                        structure will not be recreated in the instruments
5259                                        database. All instruments will be added directly in
5260                                        the specified database directory.</t>
5261                                    </list>
5262                                </t>
5263                            </list>
5264                        </t>
5265    
5266                     <t>The difference between regular and NON_MODAL versions of the command
5267                        is that the regular command returns when the scanning is finished
5268                        while NON_MODAL version returns immediately and a background process is launched.
5269                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5270                        command can be used to monitor the scanning progress.</t>
5271    
5272                        <t>Possible Answers:</t>
5273                        <t>
5274                            <list>
5275                                <t>"OK" -
5276                                    <list>
5277                                        <t>on success when NON_MODAL is not supplied</t>
5278                                    </list>
5279                                </t>
5280                                <t>"OK[&lt;job-id&gt;]" -
5281                                    <list>
5282                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5283                                        is a numerical ID used to obtain status information about the job progress.
5284                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5285                                        </t>
5286                                    </list>
5287                                </t>
5288                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5289                                    <list>
5290                                        <t>if an invalid path is specified.</t>
5291                                    </list>
5292                                </t>
5293                            </list>
5294                        </t>
5295    
5296                        <t>Examples:</t>
5297                        <t>
5298                            <list>
5299                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5300                                <t>S: "OK"</t>
5301                            </list>
5302                        </t>
5303                    </section>
5304    
5305                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5306                        <t>The front-end can remove a particular instrument
5307                        from the instruments database by sending the following command:</t>
5308                        <t>
5309                            <list>
5310                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5311                            </list>
5312                        </t>
5313                        <t>Where &lt;instr_path&gt; is the absolute path name
5314                        (in the instruments database) of the instrument to remove.</t>
5315    
5316                        <t>Possible Answers:</t>
5317                        <t>
5318                            <list>
5319                                <t>"OK" -
5320                                    <list>
5321                                        <t>if the instrument is removed successfully</t>
5322                                    </list>
5323                                </t>
5324                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5325                                    <list>
5326                                        <t>if the given path does not exist or
5327                                        is a directory.</t>
5328                                    </list>
5329                                </t>
5330                            </list>
5331                        </t>
5332    
5333                        <t>Examples:</t>
5334                        <t>
5335                            <list>
5336                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5337                                <t>S: "OK"</t>
5338                            </list>
5339                        </t>
5340                    </section>
5341    
5342                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5343                        <t>The front-end can retrieve the current amount of
5344                        instruments in a specific directory by sending the following command:</t>
5345                        <t>
5346                            <list>
5347                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5348                            </list>
5349                        </t>
5350                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5351                        of the directory. If RECURSIVE is specified, the number of all
5352                        instruments, including those located in subdirectories of the
5353                        specified directory, will be returned.</t>
5354    
5355                        <t>Possible Answers:</t>
5356                        <t>
5357                            <list>
5358                                <t>The current number of instruments
5359                                in the specified directory.</t>
5360                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5361                                    <list>
5362                                        <t>if the given directory does not exist.</t>
5363                                    </list>
5364                                </t>
5365                            </list>
5366                        </t>
5367    
5368                        <t>Example:</t>
5369                        <t>
5370                            <list>
5371                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5372                                <t>S: "2"</t>
5373                            </list>
5374                        </t>
5375                    </section>
5376    
5377                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5378                        <t>The front-end can retrieve the current list of instruments
5379                        in specific directory by sending the following command:</t>
5380                        <t>
5381                            <list>
5382                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5383                            </list>
5384                        </t>
5385                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5386                        name of the directory. If RECURSIVE is specified, the absolute path
5387                        names of all instruments, including those located in subdirectories
5388                        of the specified directory, will be returned.</t>
5389    
5390                        <t>Possible Answers:</t>
5391                        <t>
5392                            <list>
5393                                <t>A comma separated list of all instruments
5394                                (encapsulated into apostrophes) in the specified directory.</t>
5395                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5396                                    <list>
5397                                        <t>if the given directory does not exist.</t>
5398                                    </list>
5399                                </t>
5400                            </list>
5401                        </t>
5402                        <t>Example:</t>
5403                        <t>
5404                            <list>
5405                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5406                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5407                            </list>
5408                        </t>
5409                        <t>
5410                            <list>
5411                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5412                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5413                            </list>
5414                        </t>
5415                    </section>
5416    
5417                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5418                        <t>The front-end can ask for the current settings of an
5419                        instrument by sending the following command:</t>
5420                        <t>
5421                            <list>
5422                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5423                            </list>
5424                        </t>
5425                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5426                        name of the instrument the front-end is interested in.</t>
5427    
5428                        <t>Possible Answers:</t>
5429                        <t>
5430                            <list>
5431                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5432                                Each answer line begins with the settings category name
5433                                followed by a colon and then a space character &lt;SP&gt; and finally
5434                                the info character string to that setting category. At the
5435                                moment the following categories are defined:</t>
5436    
5437                                <t>
5438                                    <list>
5439                                        <t>INSTRUMENT_FILE -
5440                                            <list>
5441                                                <t>File name of the instrument.</t>
5442                                            </list>
5443                                        </t>
5444                                        <t>INSTRUMENT_NR -
5445                                            <list>
5446                                                <t>Index of the instrument within the file.</t>
5447                                            </list>
5448                                        </t>
5449                                        <t>FORMAT_FAMILY -
5450                                            <list>
5451                                                <t>The format family of the instrument.</t>
5452                                            </list>
5453                                        </t>
5454                                        <t>FORMAT_VERSION -
5455                                            <list>
5456                                                <t>The format version of the instrument.</t>
5457                                            </list>
5458                                        </t>
5459                                        <t>SIZE -
5460                                            <list>
5461                                                <t>The size of the instrument in bytes.</t>
5462                                            </list>
5463                                        </t>
5464                                        <t>CREATED -
5465                                            <list>
5466                                                <t>The date and time when the instrument is added
5467                                                in the instruments database, represented in
5468                                               "YYYY-MM-DD HH:MM:SS" format</t>
5469                                            </list>
5470                                        </t>
5471                                        <t>MODIFIED -
5472                                            <list>
5473                                                <t>The date and time of the last modification of the
5474                                                instrument's database settings, represented in
5475                                                "YYYY-MM-DD HH:MM:SS" format</t>
5476                                            </list>
5477                                        </t>
5478                                        <t>DESCRIPTION -
5479                                            <list>
5480                                                <t>A brief description of the instrument</t>
5481                                            </list>
5482                                        </t>
5483                                        <t>IS_DRUM -
5484                                            <list>
5485                                                <t>either true or false, determines whether the
5486                                                instrument is a drumkit or a chromatic instrument</t>
5487                                            </list>
5488                                        </t>
5489                                        <t>PRODUCT -
5490                                            <list>
5491                                                <t>The product title of the instrument</t>
5492                                            </list>
5493                                        </t>
5494                                        <t>ARTISTS -
5495                                            <list>
5496                                                <t>Lists the artist names</t>
5497                                            </list>
5498                                        </t>
5499                                        <t>KEYWORDS -
5500                                            <list>
5501                                                <t>Provides a list of keywords that refer to the instrument.
5502                                                Keywords are separated with semicolon and blank.</t>
5503                                            </list>
5504                                        </t>
5505                                    </list>
5506                                </t>
5507                            </list>
5508                        </t>
5509                        <t>The mentioned fields above don't have to be in particular order.</t>
5510    
5511                        <t>Example:</t>
5512                        <t>
5513                            <list>
5514                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5515                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5516                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5517                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5518                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5519                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5520                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5521                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5522                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5523                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5524                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5525                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5526                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5527                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5528                            </list>
5529                        </t>
5530                    </section>
5531    
5532                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5533                        <t>The front-end can alter the name of a specific
5534                        instrument by sending the following command:</t>
5535                        <t>
5536                            <list>
5537                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5538                            </list>
5539                        </t>
5540                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5541                        &lt;name&gt; is the new name for that instrument.</t>
5542    
5543                        <t>Possible Answers:</t>
5544                        <t>
5545                            <list>
5546                                <t>"OK" -
5547                                    <list>
5548                                        <t>on success</t>
5549                                    </list>
5550                                </t>
5551                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5552                                    <list>
5553                                        <t>in case the given instrument does not exists,
5554                                        or if an instrument with name equal to the new
5555                                        name already exists.</t>
5556                                    </list>
5557                                </t>
5558                            </list>
5559                        </t>
5560    
5561                        <t>Example:</t>
5562                        <t>
5563                            <list>
5564                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5565                                <t>S: "OK"</t>
5566                            </list>
5567                        </t>
5568                    </section>
5569    
5570                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5571                        <t>The front-end can move a specific instrument to another directory by
5572                        sending the following command:</t>
5573                        <t>
5574                            <list>
5575                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5576                            </list>
5577                        </t>
5578                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5579                        to move and &lt;dst&gt; is the directory where the instrument will
5580                        be moved to.</t>
5581    
5582                        <t>Possible Answers:</t>
5583                        <t>
5584                            <list>
5585                                <t>"OK" -
5586                                    <list>
5587                                        <t>on success</t>
5588                                    </list>
5589                                </t>
5590                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5591                                    <list>
5592                                        <t>in case the given instrument does not exists,
5593                                        or if an instrument with name equal to the name of the
5594                                        specified instrument already exists in the destination
5595                                        directory.</t>
5596                                    </list>
5597                                </t>
5598                            </list>
5599                        </t>
5600    
5601                        <t>Example:</t>
5602                        <t>
5603                            <list>
5604                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
5605                                <t>S: "OK"</t>
5606                            </list>
5607                        </t>
5608                    </section>
5609    
5610                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5611                        <t>The front-end can copy a specific instrument to another directory by
5612                        sending the following command:</t>
5613                        <t>
5614                            <list>
5615                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5616                            </list>
5617                        </t>
5618                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5619                        to copy and &lt;dst&gt; is the directory where the instrument will
5620                        be copied to.</t>
5621    
5622                        <t>Possible Answers:</t>
5623                        <t>
5624                            <list>
5625                                <t>"OK" -
5626                                    <list>
5627                                        <t>on success</t>
5628                                    </list>
5629                                </t>
5630                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5631                                    <list>
5632                                        <t>in case the given instrument does not exists,
5633                                        or if an instrument with name equal to the name of the
5634                                        specified instrument already exists in the destination
5635                                        directory.</t>
5636                                    </list>
5637                                </t>
5638                            </list>
5639                        </t>
5640    
5641                        <t>Example:</t>
5642                        <t>
5643                            <list>
5644                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5645                                <t>S: "OK"</t>
5646                            </list>
5647                        </t>
5648                    </section>
5649    
5650                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5651                        <t>The front-end can alter the description of a specific
5652                        instrument by sending the following command:</t>
5653                        <t>
5654                            <list>
5655                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
5656                            </list>
5657                        </t>
5658                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5659                        &lt;desc&gt; is the new description for the instrument.</t>
5660    
5661                        <t>Possible Answers:</t>
5662                        <t>
5663                            <list>
5664                                <t>"OK" -
5665                                    <list>
5666                                        <t>on success</t>
5667                                    </list>
5668                                </t>
5669                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5670                                    <list>
5671                                        <t>in case the given instrument does not exists.</t>
5672                                    </list>
5673                                </t>
5674                            </list>
5675                        </t>
5676    
5677                        <t>Example:</t>
5678                        <t>
5679                            <list>
5680                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
5681                                <t>S: "OK"</t>
5682                            </list>
5683                        </t>
5684                    </section>
5685    
5686                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5687                        <t>The front-end can search for instruments
5688                        in specific directory by sending the following command:</t>
5689                        <t>
5690                            <list>
5691                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5692                            </list>
5693                        </t>
5694                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5695                        name of the directory to search in. If NON_RECURSIVE is specified, the
5696                        directories located in subdirectories of the specified directory will not
5697                        be searched. &lt;criteria-list&gt; is a list of search criterias
5698                        in form of "key1=val1 key2=val2 ...". The following criterias are
5699                        allowed:</t>
5700                        <t>
5701                          <t>NAME='&lt;search-string&gt;'
5702                              <list>
5703                                  <t>Restricts the search to instruments, which names
5704                                  satisfy the supplied search string.</t>
5705                              </list>
5706                          </t>
5707    
5708                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5709                              <list>
5710                                  <t>Restricts the search to instruments, which
5711                                  size is in the specified range. If &lt;min&gt; is omitted,
5712                                  the search results are restricted to instruments with size less then
5713                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5714                                  search is restricted to instruments with size greater then
5715                                  or equal to &lt;min&gt;.</t>
5716                              </list>
5717                          </t>
5718    
5719                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5720                              <list>
5721                                  <t>Restricts the search to instruments, which creation
5722                                  date satisfies the specified period, where &lt;date-after&gt;
5723                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5724                                  If &lt;date-after&gt; is omitted the search is restricted to
5725                                  instruments created before &lt;date-before&gt;. If
5726                                  &lt;date-before&gt; is omitted, the search is restricted
5727                                  to instruments created after &lt;date-after&gt;.</t>
5728                              </list>
5729                          </t>
5730    
5731                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5732                              <list>
5733                                  <t>Restricts the search to instruments, which
5734                                  date of last modification satisfies the specified period, where
5735                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5736                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5737                                  instruments, which are last modified before &lt;date-before&gt;. If
5738                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5739                                  which are last modified after &lt;date-after&gt;.</t>
5740                              </list>
5741                          </t>
5742    
5743                          <t>DESCRIPTION='&lt;search-string&gt;'
5744                              <list>
5745                                  <t>Restricts the search to instruments with description
5746                                  that satisfies the supplied search string.</t>
5747                              </list>
5748                          </t>
5749    
5750                          <t>PRODUCT='&lt;search-string&gt;'
5751                              <list>
5752                                  <t>Restricts the search to instruments with product info
5753                                  that satisfies the supplied search string.</t>
5754                              </list>
5755                          </t>
5756    
5757                          <t>ARTISTS='&lt;search-string&gt;'
5758                              <list>
5759                                  <t>Restricts the search to instruments with artists info
5760                                  that satisfies the supplied search string.</t>
5761                              </list>
5762                          </t>
5763    
5764                          <t>KEYWORDS='&lt;search-string&gt;'
5765                              <list>
5766                                  <t>Restricts the search to instruments with keyword list
5767                                  that satisfies the supplied search string.</t>
5768                              </list>
5769                          </t>
5770    
5771                          <t>IS_DRUM=true | false
5772                              <list>
5773                                  <t>Either true or false. Restricts the search to
5774                                  drum kits or chromatic instruments.</t>
5775                              </list>
5776                          </t>
5777    
5778                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5779                              <list>
5780                                  <t>Restricts the search to instruments of the supplied format families,
5781                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5782                              </list>
5783                          </t>
5784                        </t>
5785    
5786                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5787                        word list separated with spaces for OR search and with '+' for AND search.</t>
5788    
5789                        <t>Possible Answers:</t>
5790                        <t>
5791                            <list>
5792                                <t>A comma separated list with the absolute path names (encapsulated into
5793                                apostrophes) of all instruments in the specified directory that satisfy
5794                                the supplied search criterias.</t>
5795                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5796                                    <list>
5797                                        <t>if the given directory does not exist.</t>
5798                                    </list>
5799                                </t>
5800                            </list>
5801                        </t>
5802                        <t>Example:</t>
5803                        <t>
5804                            <list>
5805                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5806                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5807                            </list>
5808                        </t>
5809                        <t>
5810                            <list>
5811                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5812                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5813                            </list>
5814                        </t>
5815                    </section>
5816    
5817                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5818                        <t>The front-end can ask for the current status of a
5819                        particular database instruments job by sending the following command:</t>
5820                        <t>
5821                            <list>
5822                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5823                            </list>
5824                        </t>
5825                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5826                        of the job the front-end is interested in.</t>
5827    
5828                        <t>Possible Answers:</t>
5829                        <t>
5830                            <list>
5831                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5832                                Each answer line begins with the settings category name
5833                                followed by a colon and then a space character &lt;SP&gt; and finally
5834                                the info character string to that setting category. At the
5835                                moment the following categories are defined:</t>
5836    
5837                                <t>
5838                                    <list>
5839                                        <t>FILES_TOTAL -
5840                                            <list>
5841                                                <t>The total number of files scheduled for scanning</t>
5842                                            </list>
5843                                        </t>
5844                                        <t>FILES_SCANNED -
5845                                            <list>
5846                                                <t>The current number of scanned files</t>
5847                                            </list>
5848                                        </t>
5849                                        <t>SCANNING -
5850                                            <list>
5851                                                <t>The absolute path name of the file which is currently
5852                                                being scanned</t>
5853                                            </list>
5854                                        </t>
5855                                        <t>STATUS -
5856                                            <list>
5857                                                <t>An integer value between 0 and 100 indicating the
5858                                                scanning progress percentage of the file which is
5859                                                currently being scanned</t>
5860                                            </list>
5861                                        </t>
5862                                    </list>
5863                                </t>
5864                            </list>
5865                        </t>
5866                        <t>The mentioned fields above don't have to be in particular order.</t>
5867    
5868                        <t>Example:</t>
5869                        <t>
5870                            <list>
5871                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5872                                <t>S: "FILES_TOTAL: 12"</t>
5873                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5874                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5875                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5876                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5877                            </list>
5878                        </t>
5879                    </section>
5880    
5881                </section>
5882    
5883          </section>          </section>
5884    
5885    
# Line 4287  Schoenebeck'> Line 5955  Schoenebeck'>
5955                  </t>                  </t>
5956                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
5957                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
5958                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
5959                  </t>                  </t>
5960                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
5961                  </t>                  </t>
5962                    <t>/ FIND SP find_instruction
5963                    </t>
5964                    <t>/ MOVE SP move_instruction
5965                    </t>
5966                    <t>/ COPY SP copy_instruction
5967                    </t>
5968                    <t>/ EDIT SP edit_instruction
5969                    </t>
5970                  <t>/ RESET                  <t>/ RESET
5971                  </t>                  </t>
5972                  <t>/ QUIT                  <t>/ QUIT
# Line 4303  Schoenebeck'> Line 5977  Schoenebeck'>
5977          <list>          <list>
5978                  <t>CHANNEL                  <t>CHANNEL
5979                  </t>                  </t>
5980                    <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
5981                    </t>
5982                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
5983                    </t>
5984                    <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
5985                    </t>
5986                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
5987                    </t>
5988                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
5989                    </t>
5990                    <t>/ DB_INSTRUMENTS SP pathname SP pathname
5991                    </t>
5992                    <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
5993                    </t>
5994                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
5995                  </t>                  </t>
5996                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
# Line 4311  Schoenebeck'> Line 5999  Schoenebeck'>
5999  </t>  </t>
6000  <t>subscribe_event =  <t>subscribe_event =
6001          <list>          <list>
6002                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6003                    </t>
6004                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6005                    </t>
6006                    <t>/ MIDI_INPUT_DEVICE_COUNT
6007                    </t>
6008                    <t>/ MIDI_INPUT_DEVICE_INFO
6009                    </t>
6010                    <t>/ CHANNEL_COUNT
6011                  </t>                  </t>
6012                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6013                  </t>                  </t>
# Line 4321  Schoenebeck'> Line 6017  Schoenebeck'>
6017                  </t>                  </t>
6018                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6019                  </t>                  </t>
6020                    <t>/ FX_SEND_COUNT
6021                    </t>
6022                    <t>/ FX_SEND_INFO
6023                    </t>
6024                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6025                    </t>
6026                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6027                    </t>
6028                    <t>/ MIDI_INSTRUMENT_COUNT
6029                    </t>
6030                    <t>/ MIDI_INSTRUMENT_INFO
6031                    </t>
6032                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6033                    </t>
6034                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6035                    </t>
6036                    <t>/ DB_INSTRUMENT_COUNT
6037                    </t>
6038                    <t>/ DB_INSTRUMENT_INFO
6039                    </t>
6040                    <t>/ DB_INSTRUMENTS_JOB_INFO
6041                    </t>
6042                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6043                  </t>                  </t>
6044                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6045                  </t>                  </t>
6046                    <t>/ GLOBAL_INFO
6047                    </t>
6048          </list>          </list>
6049  </t>  </t>
6050  <t>unsubscribe_event =  <t>unsubscribe_event =
6051          <list>          <list>
6052                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6053                    </t>
6054                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6055                    </t>
6056                    <t>/ MIDI_INPUT_DEVICE_COUNT
6057                    </t>
6058                    <t>/ MIDI_INPUT_DEVICE_INFO
6059                    </t>
6060                    <t>/ CHANNEL_COUNT
6061                  </t>                  </t>
6062                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6063                  </t>                  </t>
# Line 4339  Schoenebeck'> Line 6067  Schoenebeck'>
6067                  </t>                  </t>
6068                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6069                  </t>                  </t>
6070                    <t>/ FX_SEND_COUNT
6071                    </t>
6072                    <t>/ FX_SEND_INFO
6073                    </t>
6074                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6075                    </t>
6076                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6077                    </t>
6078                    <t>/ MIDI_INSTRUMENT_COUNT
6079                    </t>
6080                    <t>/ MIDI_INSTRUMENT_INFO
6081                    </t>
6082                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6083                    </t>
6084                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6085                    </t>
6086                    <t>/ DB_INSTRUMENT_COUNT
6087                    </t>
6088                    <t>/ DB_INSTRUMENT_INFO
6089                    </t>
6090                    <t>/ DB_INSTRUMENTS_JOB_INFO
6091                    </t>
6092                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6093                  </t>                  </t>
6094                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6095                  </t>                  </t>
6096                    <t>/ GLOBAL_INFO
6097                    </t>
6098          </list>          </list>
6099  </t>  </t>
6100  <t>map_instruction =  <t>map_instruction =
6101          <list>          <list>
6102                  <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value                  <t>MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
6103                  </t>                  </t>
6104                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
6105                  </t>                  </t>
6106                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
6107                  </t>                  </t>
6108                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
6109                  </t>                  </t>
6110          </list>          </list>
6111  </t>  </t>
# Line 4371  Schoenebeck'> Line 6123  Schoenebeck'>
6123                  </t>                  </t>
6124                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6125                  </t>                  </t>
6126                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
6127                    </t>
6128                    <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
6129                    </t>
6130                    <t>/ DB_INSTRUMENT SP pathname
6131                    </t>
6132          </list>          </list>
6133  </t>  </t>
6134  <t>get_instruction =  <t>get_instruction =
# Line 4437  Schoenebeck'> Line 6195  Schoenebeck'>
6195                  </t>                  </t>
6196                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
6197                  </t>                  </t>
6198                    <t>/ FX_SENDS SP sampler_channel
6199                    </t>
6200                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6201                    </t>
6202                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
6203                    </t>
6204                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
6205                    </t>
6206                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
6207                    </t>
6208                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
6209                    </t>
6210                    <t>/ DB_INSTRUMENTS SP pathname
6211                    </t>
6212                    <t>/ DB_INSTRUMENT SP INFO SP pathname
6213                    </t>
6214                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6215                    </t>
6216                    <t>/ VOLUME
6217                    </t>
6218          </list>          </list>
6219  </t>  </t>
6220  <t>set_instruction =  <t>set_instruction =
# Line 4447  Schoenebeck'> Line 6225  Schoenebeck'>
6225                  </t>                  </t>
6226                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6227                  </t>                  </t>
6228                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6229                    </t>
6230                  <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
6231                  </t>                  </t>
6232                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
6233                  </t>                  </t>
6234                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
6235                  </t>                  </t>
6236                    <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
6237                    </t>
6238                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
6239                    </t>
6240                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
6241                    </t>
6242                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6243                    </t>
6244                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname
6245                    </t>
6246                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
6247                    </t>
6248                    <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname
6249                    </t>
6250                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
6251                    </t>
6252                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6253                  </t>                  </t>
6254                    <t>/ VOLUME SP volume_value
6255                    </t>
6256          </list>          </list>
6257  </t>  </t>
6258  <t>create_instruction =  <t>create_instruction =
# Line 4467  Schoenebeck'> Line 6265  Schoenebeck'>
6265                  </t>                  </t>
6266                  <t>/ MIDI_INPUT_DEVICE SP string                  <t>/ MIDI_INPUT_DEVICE SP string
6267                  </t>                  </t>
6268                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl
6269                    </t>
6270                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
6271                    </t>
6272          </list>          </list>
6273  </t>  </t>
6274  <t>reset_instruction =  <t>reset_instruction =
# Line 4483  Schoenebeck'> Line 6285  Schoenebeck'>
6285                  </t>                  </t>
6286          </list>          </list>
6287  </t>  </t>
6288    <t>find_instruction =
6289            <list>
6290                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
6291                    </t>
6292                    <t>/ DB_INSTRUMENTS SP pathname SP query_val_list
6293                    </t>
6294                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
6295                    </t>
6296                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
6297                    </t>
6298            </list>
6299    </t>
6300    <t>move_instruction =
6301            <list>
6302                    <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
6303                    </t>
6304                    <t>/ DB_INSTRUMENT SP pathname SP pathname
6305                    </t>
6306            </list>
6307    </t>
6308    <t>copy_instruction =
6309            <list>
6310                    <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
6311                    </t>
6312                    <t>/ DB_INSTRUMENT SP pathname SP pathname
6313                    </t>
6314            </list>
6315    </t>
6316  <t>destroy_instruction =  <t>destroy_instruction =
6317          <list>          <list>
6318                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
6319                  </t>                  </t>
6320                  <t>/ MIDI_INPUT_DEVICE SP number                  <t>/ MIDI_INPUT_DEVICE SP number
6321                  </t>                  </t>
6322                    <t>/ FX_SEND SP sampler_channel SP fx_send_id
6323                    </t>
6324          </list>          </list>
6325  </t>  </t>
6326  <t>load_instruction =  <t>load_instruction =
# Line 4531  Schoenebeck'> Line 6363  Schoenebeck'>
6363                  </t>                  </t>
6364          </list>          </list>
6365  </t>  </t>
6366    <t>edit_instruction =
6367            <list>
6368                    <t>INSTRUMENT SP sampler_channel
6369                    </t>
6370            </list>
6371    </t>
6372    <t>modal_arg =
6373            <list>
6374                    <t>/* epsilon (empty argument) */
6375                    </t>
6376                    <t>/ NON_MODAL SP
6377                    </t>
6378            </list>
6379    </t>
6380  <t>key_val_list =  <t>key_val_list =
6381          <list>          <list>
6382                  <t>string '=' param_val_list                  <t>string '=' param_val_list
# Line 4567  Schoenebeck'> Line 6413  Schoenebeck'>
6413                  </t>                  </t>
6414                  <t>/ MIDI_INSTRUMENT_MAPS                  <t>/ MIDI_INSTRUMENT_MAPS
6415                  </t>                  </t>
6416                    <t>/ FX_SENDS SP sampler_channel
6417                    </t>
6418                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
6419                    </t>
6420                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
6421                    </t>
6422                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
6423                    </t>
6424                    <t>/ DB_INSTRUMENTS SP pathname
6425                    </t>
6426          </list>          </list>
6427  </t>  </t>
6428  <t>load_instr_args =  <t>load_instr_args =
# Line 4649  Schoenebeck'> Line 6505  Schoenebeck'>
6505                  </t>                  </t>
6506          </list>          </list>
6507  </t>  </t>
6508    <t>midi_ctrl =
6509            <list>
6510                    <t>number
6511                    </t>
6512            </list>
6513    </t>
6514  <t>volume_value =  <t>volume_value =
6515          <list>          <list>
6516                  <t>dotnum                  <t>dotnum
# Line 4669  Schoenebeck'> Line 6531  Schoenebeck'>
6531                  </t>                  </t>
6532          </list>          </list>
6533  </t>  </t>
6534    <t>fx_send_id =
6535            <list>
6536                    <t>number
6537                    </t>
6538            </list>
6539    </t>
6540  <t>engine_name =  <t>engine_name =
6541          <list>          <list>
6542                  <t>string                  <t>string
6543                  </t>                  </t>
6544          </list>          </list>
6545  </t>  </t>
6546  <t>filename =  <t>pathname =
6547          <list>          <list>
6548                  <t>stringval                  <t>stringval
6549                  </t>                  </t>
6550          </list>          </list>
6551  </t>  </t>
6552    <t>dirname =
6553            <list>
6554                    <t>stringval
6555                    </t>
6556            </list>
6557    </t>
6558    <t>filename =
6559            <list>
6560                    <t>stringval_escaped
6561                    </t>
6562            </list>
6563    </t>
6564  <t>map_name =  <t>map_name =
6565          <list>          <list>
6566                  <t>stringval                  <t>stringval
# Line 4693  Schoenebeck'> Line 6573  Schoenebeck'>
6573                  </t>                  </t>
6574          </list>          </list>
6575  </t>  </t>
6576    <t>fx_send_name =
6577            <list>
6578                    <t>stringval
6579                    </t>
6580            </list>
6581    </t>
6582  <t>param_val_list =  <t>param_val_list =
6583          <list>          <list>
6584                  <t>param_val                  <t>param_val
# Line 4713  Schoenebeck'> Line 6599  Schoenebeck'>
6599                  </t>                  </t>
6600          </list>          </list>
6601  </t>  </t>
6602    <t>query_val_list =
6603            <list>
6604                    <t>string '=' query_val
6605                    </t>
6606                    <t>/ query_val_list SP string '=' query_val
6607                    </t>
6608            </list>
6609    </t>
6610    <t>query_val =
6611            <list>
6612                    <t>string
6613                    </t>
6614                    <t>/ stringval
6615                    </t>
6616            </list>
6617    </t>
6618    <t>scan_mode =
6619            <list>
6620                    <t>RECURSIVE
6621                    </t>
6622                    <t>/ NON_RECURSIVE
6623                    </t>
6624                    <t>/ FLAT
6625                    </t>
6626            </list>
6627    </t>
6628    
6629              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6630    
6631                <section title="Character Set and Escape Sequences" anchor="character_set">
6632                    <t>Older versions of this protocol up to and including v1.1 only
6633                    supported the standard ASCII character set (ASCII code 0 - 127)
6634                    <xref target="RFC20"/>, all younger versions of this protocol
6635                    however support the Extended ASCII character set (ASCII code
6636                    0 - 255). The same group of younger protocols also support
6637                    escape sequences, but only for certain, explicitly declared
6638                    parts of the protocol. The supported escape sequences are
6639                    defined as follows:</t>
6640                    <texttable>
6641                        <ttcol>ASCII Character Sequence</ttcol>
6642                        <ttcol>Translated into (Name)</ttcol>
6643                        <c>\n</c> <c>new line</c>
6644                        <c>\r</c> <c>carriage return</c>
6645                        <c>\f</c> <c>form feed</c>
6646                        <c>\t</c> <c>horizontal tab</c>
6647                        <c>\v</c> <c>vertical tab</c>
6648                        <c>\'</c> <c>apostrophe</c>
6649                        <c>\"</c> <c>quotation mark</c>
6650                        <c>\\</c> <c>backslash</c>
6651                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6652                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6653                    </texttable>
6654                    <t>Notice: due to the transition of certain parts of the
6655                    protocol which now support escape sequences, a slight backward
6656                    incompatibility to protocols version v1.1 and younger has been
6657                    introduced. The only difference is that in parts of the protocol
6658                    where escape characters are now supported, a backslash characters
6659                    MUST be escaped as well (that is as double backslash), whereas
6660                    in the old versions a single backslash was sufficient.</t>
6661                </section>
6662          </section>          </section>
6663    
6664          <section title="Events" anchor="events">          <section title="Events" anchor="events">
6665              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
6666    
6667              <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL">              <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">
6668                    <t>Client may want to be notified when the total number of audio output devices on the
6669                    back-end changes by issuing the following command:</t>
6670                    <t>
6671                        <list>
6672                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT</t>
6673                        </list>
6674                    </t>
6675                    <t>Server will start sending the following notification messages:</t>
6676                    <t>
6677                        <list>
6678                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
6679                        </list>
6680                    </t>
6681                    <t>where &lt;devices&gt; will be replaced by the new number
6682                    of audio output devices.</t>
6683                </section>
6684    
6685                <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">
6686                    <t>Client may want to be notified when changes were made to audio output devices on the
6687                    back-end by issuing the following command:</t>
6688                    <t>
6689                        <list>
6690                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO</t>
6691                        </list>
6692                    </t>
6693                    <t>Server will start sending the following notification messages:</t>
6694                    <t>
6695                        <list>
6696                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
6697                        </list>
6698                    </t>
6699                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
6700                    which settings has been changed. The front-end will have to send
6701                    the respective command to actually get the audio output device info. Because these messages
6702                    will be triggered by LSCP commands issued by other clients rather than real
6703                    time events happening on the server, it is believed that an empty notification
6704                    message is sufficient here.</t>
6705                </section>
6706    
6707                <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">
6708                    <t>Client may want to be notified when the total number of MIDI input devices on the
6709                    back-end changes by issuing the following command:</t>
6710                    <t>
6711                        <list>
6712                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT</t>
6713                        </list>
6714                    </t>
6715                    <t>Server will start sending the following notification messages:</t>
6716                    <t>
6717                        <list>
6718                            <t>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
6719                        </list>
6720                    </t>
6721                    <t>where &lt;devices&gt; will be replaced by the new number
6722                    of MIDI input devices.</t>
6723                </section>
6724    
6725                <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO">
6726                    <t>Client may want to be notified when changes were made to MIDI input devices on the
6727                    back-end by issuing the following command:</t>
6728                    <t>
6729                        <list>
6730                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_INFO</t>
6731                        </list>
6732                    </t>
6733                    <t>Server will start sending the following notification messages:</t>
6734                    <t>
6735                        <list>
6736                            <t>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
6737                        </list>
6738                    </t>
6739                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
6740                    which settings has been changed. The front-end will have to send
6741                    the respective command to actually get the MIDI input device info. Because these messages
6742                    will be triggered by LSCP commands issued by other clients rather than real
6743                    time events happening on the server, it is believed that an empty notification
6744                    message is sufficient here.</t>
6745                </section>
6746    
6747                <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT">
6748                  <t>Client may want to be notified when the total number of channels on the                  <t>Client may want to be notified when the total number of channels on the
6749                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
6750                  <t>                  <t>
# Line 4749  Schoenebeck'> Line 6773  Schoenebeck'>
6773                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
6774                  <t>                  <t>
6775                      <list>                      <list>
6776                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
6777                      </list>                      </list>
6778                  </t>                  </t>
6779                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
# Line 4797  Schoenebeck'> Line 6821  Schoenebeck'>
6821                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>
6822              </section>              </section>
6823    
6824              <section title="Channel information changed" anchor="SUBSCRIBE INFO">              <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO">
6825                  <t>Client may want to be notified when changes were made to sampler channels on the                  <t>Client may want to be notified when changes were made to sampler channels on the
6826                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
6827                  <t>                  <t>
# Line 4819  Schoenebeck'> Line 6843  Schoenebeck'>
6843                  message is sufficient here.</t>                  message is sufficient here.</t>
6844              </section>              </section>
6845    
6846                <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
6847                    <t>Client may want to be notified when the number of effect sends on
6848                    a particular sampler channel is changed by issuing the following command:</t>
6849                    <t>
6850                        <list>
6851                            <t>SUBSCRIBE FX_SEND_COUNT</t>
6852                        </list>
6853                    </t>
6854                    <t>Server will start sending the following notification messages:</t>
6855                    <t>
6856                        <list>
6857                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
6858                        </list>
6859                    </t>
6860                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
6861                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
6862                    be replaced by the new number of effect sends on that channel.</t>
6863                </section>
6864    
6865                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO">
6866                    <t>Client may want to be notified when changes were made to effect sends on a
6867                    a particular sampler channel by issuing the following command:</t>
6868                    <t>
6869                        <list>
6870                            <t>SUBSCRIBE FX_SEND_INFO</t>
6871                        </list>
6872                    </t>
6873                    <t>Server will start sending the following notification messages:</t>
6874                    <t>
6875                        <list>
6876                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
6877                        </list>
6878                    </t>
6879                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
6880                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
6881                    be replaced by the numerical ID of the changed effect send.</t>
6882                </section>
6883    
6884              <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">              <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">
6885                  <t>Client may want to be notified when the total number of voices on the                  <t>Client may want to be notified when the total number of voices on the
6886                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4830  Schoenebeck'> Line 6892  Schoenebeck'>
6892                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
6893                  <t>                  <t>
6894                      <list>                      <list>
6895                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
6896                      </list>                      </list>
6897                  </t>                  </t>
6898                  <t>where &lt;voices&gt; will be replaced by the new number of                  <t>where &lt;voices&gt; will be replaced by the new number of
6899                  all currently active voices.</t>                  all currently active voices.</t>
6900              </section>              </section>
6901    
6902                <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
6903                    <t>Client may want to be notified when the number of MIDI instrument maps on the
6904                    back-end changes by issuing the following command:</t>
6905                    <t>
6906                        <list>
6907                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT</t>
6908                        </list>
6909                    </t>
6910                    <t>Server will start sending the following notification messages:</t>
6911                    <t>
6912                        <list>
6913                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"</t>
6914                        </list>
6915                    </t>
6916                    <t>where &lt;maps&gt; will be replaced by the new number
6917                    of MIDI instrument maps.</t>
6918                </section>
6919    
6920                <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">
6921                    <t>Client may want to be notified when changes were made to MIDI instrument maps on the
6922                    back-end by issuing the following command:</t>
6923                    <t>
6924                        <list>
6925                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO</t>
6926                        </list>
6927                    </t>
6928                    <t>Server will start sending the following notification messages:</t>
6929                    <t>
6930                        <list>
6931                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"</t>
6932                        </list>
6933                    </t>
6934                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
6935                    for which information changes occurred. The front-end will have to send
6936                    the respective command to actually get the MIDI instrument map info. Because these messages
6937                    will be triggered by LSCP commands issued by other clients rather than real
6938                    time events happening on the server, it is believed that an empty notification
6939                    message is sufficient here.</t>
6940                </section>
6941    
6942                <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT">
6943                    <t>Client may want to be notified when the number of MIDI instrument maps on the
6944                    back-end changes by issuing the following command:</t>
6945                    <t>
6946                        <list>
6947                            <t>SUBSCRIBE MIDI_INSTRUMENT_COUNT</t>
6948                        </list>
6949                    </t>
6950                    <t>Server will start sending the following notification messages:</t>
6951                    <t>
6952                        <list>
6953                            <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
6954                        </list>
6955                    </t>
6956                    <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
6957                    the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
6958                    the new number of MIDI instruments in the specified map.</t>
6959                </section>
6960    
6961                <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO">
6962                    <t>Client may want to be notified when changes were made to MIDI instruments on the
6963                    back-end by issuing the following command:</t>
6964                    <t>
6965                        <list>
6966                            <t>SUBSCRIBE MIDI_INSTRUMENT_INFO</t>
6967                        </list>
6968                    </t>
6969                    <t>Server will start sending the following notification messages:</t>
6970                    <t>
6971                        <list>
6972                            <t>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"</t>
6973                        </list>
6974                    </t>
6975                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
6976                    in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
6977                    the location of the changed MIDI instrument in the map. The front-end will have to send
6978                    the respective command to actually get the MIDI instrument info. Because these messages
6979                    will be triggered by LSCP commands issued by other clients rather than real
6980                    time events happening on the server, it is believed that an empty notification
6981                    message is sufficient here.</t>
6982                </section>
6983    
6984                <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO">
6985                    <t>Client may want to be notified when changes to the global settings
6986                    of the sampler were made by issuing the following command:</t>
6987                    <t>
6988                        <list>
6989                            <t>SUBSCRIBE GLOBAL_INFO</t>
6990                        </list>
6991                    </t>
6992                    <t>Server will start sending the following types of notification messages:</t>
6993                    <t>
6994                        <list>
6995                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
6996                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
6997                            replaced by the optional dotted floating point value, reflecting the
6998                            new global volume parameter.</t>
6999                        </list>
7000                    </t>
7001                </section>
7002    
7003                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
7004                    <t>Client may want to be notified when the number of instrument
7005                    directories in a particular directory in the instruments database
7006                    is changed by issuing the following command:</t>
7007                    <t>
7008                        <list>
7009                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
7010                        </list>
7011                    </t>
7012                    <t>Server will start sending the following notification messages:</t>
7013                    <t>
7014                        <list>
7015                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
7016                        </list>
7017                    </t>
7018                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7019                    name of the directory in the instruments database,
7020                    in which the number of directories is changed.</t>
7021                    <t>Note that when a non-empty directory is removed, this event
7022                    is not sent for the subdirectories in that directory.</t>
7023                </section>
7024    
7025                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
7026                    <t>Client may want to be notified when changes were made to directories
7027                    in the instruments database by issuing the following command:</t>
7028                    <t>
7029                        <list>
7030                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
7031                        </list>
7032                    </t>
7033                    <t>Server will start sending the following notification messages:</t>
7034                    <t>
7035                        <list>
7036                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
7037                        </list>
7038                    </t>
7039                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
7040                    of the directory, for which information changes occurred. The front-end will have to send
7041                    the respective command to actually get the updated directory info. Because these messages
7042                    will be triggered by LSCP commands issued by other clients rather than real
7043                    time events happening on the server, it is believed that an empty notification
7044                    message is sufficient here.</t>
7045                    <t>
7046                        <list>
7047                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
7048                        </list>
7049                    </t>
7050                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
7051                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7052                    the new name of the directory, encapsulated into apostrophes.</t>
7053                </section>
7054    
7055                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
7056                    <t>Client may want to be notified when the number of instruments
7057                    in a particular directory in the instruments database
7058                    is changed by issuing the following command:</t>
7059                    <t>
7060                        <list>
7061                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
7062                        </list>
7063                    </t>
7064                    <t>Server will start sending the following notification messages:</t>
7065                    <t>
7066                        <list>
7067                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
7068                        </list>
7069                    </t>
7070                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7071                    name of the directory in the instruments database,
7072                    in which the number of instruments is changed.</t>
7073                    <t>Note that when a non-empty directory is removed, this event
7074                    is not sent for the instruments in that directory.</t>
7075                </section>
7076    
7077                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
7078                    <t>Client may want to be notified when changes were made to instruments
7079                    in the instruments database by issuing the following command:</t>
7080                    <t>
7081                        <list>
7082                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
7083                        </list>
7084                    </t>
7085                    <t>Server will start sending the following notification messages:</t>
7086                    <t>
7087                        <list>
7088                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
7089                        </list>
7090                    </t>
7091                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
7092                    of the instrument, which settings are changed. The front-end will have to send
7093                    the respective command to actually get the updated directory info. Because these messages
7094                    will be triggered by LSCP commands issued by other clients rather than real
7095                    time events happening on the server, it is believed that an empty notification
7096                    message is sufficient here.</t>
7097                    <t>
7098                        <list>
7099                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
7100                        </list>
7101                    </t>
7102                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
7103                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7104                    the new name of the instrument, encapsulated into apostrophes.</t>
7105                </section>
7106    
7107                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7108                    <t>Client may want to be notified when the status of particular database
7109                    instruments job is changed by issuing the following command:</t>
7110                    <t>
7111                        <list>
7112                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7113                        </list>
7114                    </t>
7115                    <t>Server will start sending the following notification messages:</t>
7116                    <t>
7117                        <list>
7118                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7119                        </list>
7120                    </t>
7121                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7122                    which status is changed. The front-end will have to send the respective
7123                    command to actually get the status info. Because these messages
7124                    will be triggered by LSCP commands issued by other clients rather than real
7125                    time events happening on the server, it is believed that an empty notification
7126                    message is sufficient here.</t>
7127                </section>
7128    
7129              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7130                  <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
7131                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
# Line 4915  Schoenebeck'> Line 7204  Schoenebeck'>
7204                  </front>                  </front>
7205                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7206              </reference>              </reference>
7207                <reference anchor="RFC20">
7208                    <front>
7209                        <title>ASCII format for Network Interchange</title>
7210                        <author>
7211                            <organization>UCLA</organization>
7212                        </author>
7213                        <date year="1969"></date>
7214                    </front>
7215                    <seriesInfo name="RFC" value="20" />
7216                </reference>
7217           </references>           </references>
7218      </back>      </back>
7219    
Legend:
Removed from v.973  
changed lines
  Added in v.1296
  ViewVC Help
Powered by ViewVC