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	<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	<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	<h3>Function Prototype</h3>
39	<p/>
40	<code lang="nksp">
41	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
57	<h3>Return Value</h3>
58	<p>None.</p>
59
60	<h3>Remarks</h3>
61	<p>
62	This functions supports printing numbers (i.e. variables or literals) with standard units.
63	</p>
64
65	<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>