Single Port Communication

Examples:
launch client example
get data client example

This method of communication is useful for when there are a high number of reports and/or stimulus. Rather than opening a socket for each communication stream, all communications are carried out on one stream. This requires some conversation between the client and the server.

When the client connects to the server, it may begin by issuing a number of new commands.

setpath
Tell the server the directory path and job to use when looking for reports. The default path is the server's home directory and the default job is 'job'
setsort
Tell the server how reports should be arranged. This prevents the need for sending large headers to the client detailing the order of the reports. The default sort criteria is Report Name.
setpattern
Give the server some search patterns so that later commands can limit the number of reports used.
gettimecount
Find the minimum available time from a subset of reports
getdata
Using a previous pattern, find matching reports and forward a desired portion of the contents to the client.
launch
By specifying some parameters, the server will start a simulation using the Queue.

Details

setpath

Format: setpath\ndirectory name[ws]job name\n
Response: [1 byte code]

First, send the command with a newline ('\n') at the end. The server will prepare to receive the parameters. Next will come the directory name, followed by a white space character (either a space ' ' or a tab '\t') then the job name. A final newline ('\n') will end the command. If either the directory name or job name should be left the same, you can leave its place blank, but keep the separating white space (see examples).

After the server completes the request, it will respond with a single bytes code. 0 for success or greater if failure.

Example:

Change directory to '/home/king/latest_runs'
Change job to 'job2004_09_18-3'

Final command: setpath\n/home/king/latest_runs job2004_09_18-3\n

Example:

Keep same directory
Change job name to 'job2004_09_18-5'

Final command: setpath\n job2004_09_18-5\n
(Notice the space between the newline and 'job')

Example:

Change directory to '/home/king/older_runs'
Keep same job

Final command: setpath\n/home/king/older_runs \n
(Notice the space between 'runs' and the final newline)

setsort

gettimecount

Format: gettimecount\n[X]
Receive: [timesteps]

First send the command followed by a newline ('\n'). Next send a binary integer (4 bytes, little endian) specifying which pattern ID you want to use (patterns are explained under setpattern).
The server will check all reports that match the pattern to determine what is the minimum available time. For example, if two reports are matched, one with 100 timesteps, the other with 150 timesteps, then 100 is sent.

getdata

Format: getdata\n[X][Tstart][Tstop]
Receive: [N][M][value1value2...valueN][data1data2...dataM]

First send the command followed by a newline ('\n'). Next send a binary integer (4 bytes, little endian) specifying which pattern ID you want to use (patterns are explained under setpattern). Finally, two binary integers (each 4 bytes, little endian) specifying the starting report time and the ending report time.

Once the server has all the data, it will reply. It first sends two binary integers (each 4 bytes, little endian). The first (N) telling how many reports were found that matched the chosen pattern(s). The second (M) telling how many lines of data will be sent. Next is a list of N integers (each 4 bytes, little endian). Each value corresponds to a report and tells how many cells exist in that report. Finally, M lines of data are sent. A timestep integer (4 bytes) followed by all data values sent as binary floats (each value 4 bytes).

Example:

Request reports that match pattern with ID 2
Start time of timestep 200 and End time at timestep 202
[#] indicates "The binary representation of #"

Final Command: getdata\n[2][200][202]

Response:

        [2][3][4][5]
        [200][1.23][1.45][1.67][1.8][6.23][7.51][6.54][8.23][7.41]
        [201][1.13][1.52][1.64][1.92][6.05][6.97][6.88][7.96][7.64]
        [202][1.03][1.46][1.71][2.01][6.51][6.45][6.91][7.82][7.38]

setpattern

Format:setpattern\n[N]field1[WS]field2[WS]field3[WS]field4[WS]field5[WS]field6\n
Response:[patternID]

Patterns are used to select a subset of reports out of all reports in a given path with the active job name.
First the command is sent, followed by a newline ('\n'). Then an integer N (four byte, little endian) indicating the number of subpatterns. Each subpattern is made up of six fields, each field separated by white space ( the space character ' ' or tab '\t') with a newline ('\n') to separate the subpatteerns. See the examples for more clarification on formatting.

After the server receives a pattern, it will reply with an ID number so that the pattern can be accessed again more easily.

About fields: When looking for reports, there are six fields that the server looks at to determine if a given report should be included when using getdata. These fields are:

Report Name
Report On
Column Name
Layer Names
Cell Name
Compatment Name

A field can have either the desired name, or the wildcard '*'. Wildcard means that any name for that particular field is acceptable.

Examples
setpattern\n[1]Report1 * * * * *\n

This pattern looks for a report named 'Report1'. Since reports typically use a unique name, this pattern will probably return one report despite the fact that all other fields are set to wild.

setpattern\n[1]* * AI_2 * * soma_e1\n

This pattern looks for any Report so long as it has a column named 'AI_2' and a compartment named 'soma_e1'

setpattern\n[2]* VOLTAGE AI_1 Layer_A Excitatory *\n * VOLTAGE AI_2 * * *\n

Here, two subpatterns are sent. If a report matches either, it will be included. Even though there are two subpatterns, only one patternID value is sent.

setpattern\n[3]* VOLTAGE * Layer_A Excitatory soma\n * VOLTAGE * Layer_A Excitatory basal\n * VOLTAGE * Layer_A Excitatory apical\n

Here, three subpatterns are sent. Again, a report only has to match one of the patterns for it to be included, and only one patternID will be sent back to the client.

launch

The server will handle submitting a simulation to the cluster Queue. This will allow nodes to be used more efficiently.

Format: launch\n[Flags][N][App#]inputFileName\n[file contents (optional)]outputFileName\nerrorFileName\n
Response: [1 byte code]

launch: The command with a newline ('\n')
Flags: Options that may be activated by setting a bit within a 4 byte binary integer.

File contents will be sent: +1
Output and Error files should be merged: +2

N: binary integer (4 bytes) indicates the number of nodes that the simulation should use.
App#: The server has a list of NCS applications, starting at 0 (default). Sending an binary integer (4 byte) tells the server which list item to use.
inputFileName: Name of input file. If the file is on cortex, the server will navigate to it. If the file is being sent (+1 to Flags), the server will create the file in the setpath directory.
file contents: Binary integer (4 bytes) for file size. Then the ascii characters.
outputFileName: File where NCS screen output should go. End with newline ('\n')
errorFileName: File where NCS error messages should go. End with newline ('\n'). If +2 to flags, this option is not needed since error messages will go in the same file as regular screen output.

After the server receives all parameters, it will attempt to launch the simulator using the cluster queue. If the launch is successful, it will send the client a 0, otherwise a value greater than zero if there was an error.