reference/functions/nksp_message_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>message() function</title>
    <meta name="description" content="Prints text to the sampler's terminal.">
  </head>
  <body>
    <h1>message()</h1>
    <p>
      Prints the provided text to the sampler's terminal. This function is
      merely for script development and debugging purposes.
    </p>
    <note class="important">
      The message() function is not appropriate for being used with your final
      production sounds, since it can lead to audio dropouts.
      You should only use the message() function to try out things, and to spot
      and debug problems with your scripts. Same applies to all text string
      variables in general. Don't use any
      <a href="nksp.html#string_variables">string variables</a> in your final
      production sounds.
      You may use <a href="nksp.html#preprocessor_statements">preprocessor statements</a>
      to handle this effectively.
    </note>
    <p>
      Since it is a common requirement to switch a script between a development
      version and a production version, with either debug messages turned on or
      off, there is a dedicated built-in preprocessor condition to handle this
      conveniently for all <code>message()</code> calls: By simply adding
      <code>SET_CONDITION(NKSP_NO_MESSAGE)</code> to your script, all subsequent
      <code>message()</code> calls will be filtered out by the parser on
      preprocessor level. You can also revert that behavior at a subsequent
      section in your script by adding <code>RESET_CONDITION(NKSP_NO_MESSAGE)</code>,
      so all subsequent calls to <code>message()</code> will be processed again.
      This way you can easily also just disable <code>message()</code> calls in
      certain sections of your script.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
message(??text??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??text??</code></td>
        <td>String</td>
        <td>The text to be printed to the terminal.<br>
            [required]</td>
      </tr>
    </table>

    <h3>Return Value</h3>
    <p>None.</p>

    <h3>Remarks</h3>
    <p>
      This functions supports printing numbers (i.e. variables or literals) with standard units.
    </p>

    <h3>Examples</h3>
    <p/>
    <code>
on note
  message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
end on

on release
  message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
end on

on controller
  message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
end on
    </code>

  </body>
</html>
1	schoenebeck	2732	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>message() function</title>
5			<meta name="description" content="Prints text to the sampler's terminal.">
6			</head>
7			<body>
8			<h1>message()</h1>
9			<p>
10			Prints the provided text to the sampler's terminal. This function is
11			merely for script development and debugging purposes.
12			</p>
13	schoenebeck	3312	<note class="important">
14			The message() function is not appropriate for being used with your final
15			production sounds, since it can lead to audio dropouts.
16			You should only use the message() function to try out things, and to spot
17			and debug problems with your scripts. Same applies to all text string
18			variables in general. Don't use any
19			<a href="nksp.html#string_variables">string variables</a> in your final
20			production sounds.
21			You may use <a href="nksp.html#preprocessor_statements">preprocessor statements</a>
22			to handle this effectively.
23			</note>
24			<p>
25			Since it is a common requirement to switch a script between a development
26			version and a production version, with either debug messages turned on or
27			off, there is a dedicated built-in preprocessor condition to handle this
28			conveniently for all <code>message()</code> calls: By simply adding
29			<code>SET_CONDITION(NKSP_NO_MESSAGE)</code> to your script, all subsequent
30			<code>message()</code> calls will be filtered out by the parser on
31			preprocessor level. You can also revert that behavior at a subsequent
32			section in your script by adding <code>RESET_CONDITION(NKSP_NO_MESSAGE)</code>,
33			so all subsequent calls to <code>message()</code> will be processed again.
34			This way you can easily also just disable <code>message()</code> calls in
35			certain sections of your script.
36			</p>
37
38	schoenebeck	2732	<h3>Function Prototype</h3>
39			<p/>
40	schoenebeck	2742	<code lang="nksp">
41	schoenebeck	2732	message(??text??)
42			</code>
43
44			<h3>Arguments</h3>
45			<table>
46			<tr>
47			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
48			</tr>
49			<tr>
50			<td><code>??text??</code></td>
51			<td>String</td>
52			<td>The text to be printed to the terminal.<br>
53			[required]</td>
54			</tr>
55			</table>
56	schoenebeck	3601
57	schoenebeck	2732	<h3>Return Value</h3>
58			<p>None.</p>
59	schoenebeck	3601
60			<h3>Remarks</h3>
61			<p>
62			This functions supports printing numbers (i.e. variables or literals) with standard units.
63			</p>
64
65	schoenebeck	2732	<h3>Examples</h3>
66			<p/>
67			<code>
68			on note
69			message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
70			end on
71
72			on release
73			message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
74			end on
75
76			on controller
77			message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
78			end on
79			</code>
80
81			</body>
82			</html>