The current version number is 0.5, from 4/22/97. Version 0.5 fixes a
bug having to do with messages with more than 100 arguments.The program "sendSC" is a text-based Open SynthControl client. User can enter messages via command line arguments or standard input; sendSC formats these messages according to the "SynthControl" protocol, then sends the SynthControl data to an htm synthesizer via UDP or Unix protocol.
The "sendSC" program is available in CAST releases in the bin subdirectory of the distribution directory. Also, complete source to sendSC is available in the src subdirectory.
The current version number is 0.5, from 4/22/97. Version 0.5 fixes a
bug having to do with messages with more than 100 arguments.
usage: sendSC [-h host] [-r] port_number [message...]
The "-h" flag indicates that the next argument is the name of the target host. The "-r" flag instructs sendSC to look at the environment variable REMOTE_ADDR to get the name of the target host. The host can be either an Internet host name (e.g., "les") or an Internet address in standard dot notation (e.g., "128.32.122.13")
If a target host is given, sendSC uses the UDP protocol. Otherwise, the program uses the Unix protocol to connect to an HTM server running on the same machine.
The next command argument must be the port number.
For example, this invocation of sendSC causes it to try to connect to host "rodet" on port 7009:
sendSC -h rodet 7009
This invocation asks sendSC to connect to port 7005 using the UNIX protocol:
sendSC 7005
This invocation asks sendSC to connect to port 7022 of host 128.32.122.14:
setenv REMOTE_ADDR 128.32.122.14
sendSC -r 7022
If there are any additional command-line arguments after the port number, they're taken to be messages to be sent to HTM. In this mode, sendSC reads all of the command line arguments, translates them into a SynthControl packet, and sends it in a single packet. sendSC does not print any error or warning messages in this mode, which makes it a useful helper program for, e.g., CGI scripts.
Each command-line argument after the port number corresponds to an entire SynthControl message, according to this format:
message_name,arg1,arg2,arg3,arg4,...
Each argument must be one of the following:
integer: [-]?[0-9]+
float: [-]?([0-9]+.[0-9]*|.[0-9]+)
string: any other sequence of non-comma characters
The messages are combined into a single UDP packet and sent atomically to the synth.
Example: The following Unix command sends the messages "Adataset 1.0", "Atime_scale 1.0", and "Astart 0.0" to an HTM server on port 7003 of the current machine:
sendSC 7003 Adataset,1.0 Atime_scale,1.0 Astart,0.0
Example: The following Unix command sends the messages "Bidataset 3" and "Cload_file /usr/local/near/data/foo.format":
sendSC 7003 Bidataset,3 Cload_file,/usr/local/near/data/foo.format
Example: The following Unix command sends the message "Ctonebank 200. -19. 300. -32. 400. -40.":
sendSC 7003 Ctonebank,200.,-19.,300.,-32.,400.,-40.
Remember that the Unix shell will interpret any whitespace characters (space, tab, etc.) as delimiting the arguments to sendhtm. So if you want your string arguments to include any space characters, you must quote them to the shell. For example, these equivalent commands send the message "Astring_message" with the argument string "this string has spaces":
sendSC 7003 "Astring_message,this string has spaces"
sendSC 7003 Astring_message,this\ string\ has\ spaces
There are other characters which are special to Unix shells: "!", "$", ";", "~", etc. Be careful.
If the port number is the last command-line argument, sendSC enters an interactive mode. In this mode, lines of stdin should look like this:
message_name arg1 arg2 arg3...
Each line of stdin is converted into a one-message SynthControl packet and
sent immediately to the synth.
Example:
sendSC 7003
Amessage1 2.0 3.14159
Bmessage2 100 200 300
_message3 string1 string_number_two /the/third/string
Amessage4 1 2.0 three
In this interactive mode, any whitespace character is interpreted as delimiting the arguments to a message. To include whitespace in a string, surround the entire string with double-quote characters. Example:
sendSC 7003
Astringmessage "This string has spaces in it"
To exit interactive mode and return to the shell, type an EOF (control-D) or interrupt (control-C).
To group multiple messages into the same packet while in interactive mode, begin by entering an open bracket character ("[") by itself on a line. Once you've done this, all of the lines you enter will be accumulated into a large SynthControl buffer until you enter a close bracket character ("]") by itself on a line, at which point the entire packet will be sent.
Example:
sendSC 7003
[
Adataset 7.0
Atime_scale 1.0
Anote_start 0.0
]
If you enter a blank line in the middle of constructing a message group with [ and ], it is ignored. Otherwise, if you enter a blank line, sendSC re-sends the previous packet, which may be a single message or a group of messages.
sendSC sets the Unix exit status to indicate whether or not it was successful. In interactive mode, sendSC also prints warning and error messages to the screen, so the exit status is not so crucial. In command line mode, however, the exit status is the only way to know if sendSC could do its job.
Here are the possible exit status codes:
0: Successful
1: Message(s) had to be broken into multiple packets because they couldn't fit into the internal buffer all at the same time.
2: Message(s) were dropped entirely because of buffer overflow. This only happens if a message is so big that it doesn't even fit into the internal buffer by itself.
3: Socket error
4: Usage error: incorrect command-line arguments, or a "-r" without REMOTE_ADDR defined.
5: Internal error: this should never occur.
Click here for an example of using sendSC to control the demosoftcast synthesizer.