Move VariableServerSession logs into subdirectory; make separate toggle for session logs

docs/documentation/simulation_capabilities/Status-Message-System.md

@@ -14,9 +14,9 @@ If there are no subscribers, then publishing a message has no effect.
 ## Message Subscriber
 
 There can be any number of Message Subscribers, whose job is to receive (and usually output) published messages. Trick automatically creates three Message Subscribers:
-- `Trick::MessageCout` - outputs messages to the standard output stream
-- `Trick::MessageFile` - outputs messages to a file named `send_hs` in the RUN directory
-- `Trick::MessageTCDevice` - outputs messages to a socket at port 7200, used by the Simulation Control Panel for its Status Messages display
+- `Trick::MessageCout` - outputs messages with level < 100 to the standard output stream
+- `Trick::MessageHSFile` - outputs messages with level < 100 to a file named `send_hs` in the RUN directory
+- `Trick::MessageTCDevice` - outputs messages with level < 100 to a socket at port 7200, used by the Simulation Control Panel for its Status Messages display
 
 When you publish a message, it will be output by the three subscribers above.
 A subscriber can be enabled / disabled at any time during simulation execution to output / ignore messages as desired.
@@ -33,16 +33,18 @@ trick_message.mtcout.init()
 trick.message_subscribe(trick_message.mtcout)
 ```
 
-## User accessible routines
+## Publish a message
 
 To publish a message:
 
 ```cpp
-int ::message_publish(int level, const char * format_msg, ...) ;
-int ::send_hs(FILE * fp, const char * format_msg, ...) ;
+#include "trick/message_proto.h"
+#include "trick/message_level.h"
+
+int message_publish(int level, const char * format_msg, ...) ;
 ```
 
-The level number can be any integer from 0 to 99. Trick has a few predefined levels (`Trick::MessagePublisher::MESSAGE_TYPE`) that it uses for publishing messages.
+The level number can be any number greater than or equal to 0. Levels 0-99 are captured by Trick's default message subscribers. Trick has a few predefined levels (`Trick::MessagePublisher::MESSAGE_TYPE`) that it uses for publishing messages.
 If the message subscriber's color is enabled (see below), then a particular colored message will be displayed for each of these levels:
 - 0 - normal message, default color
 - 1 - informational message, green
@@ -50,6 +52,31 @@ If the message subscriber's color is enabled (see below), then a particular colo
 - 3 - error message, red
 - 10 - debug message, cyan
 
+## Open a custom log file
+
+To open a custom message file:
+
+```cpp
+#include "trick/Message_proto.hh"
+
+int open_custom_message_file(std::string file_name, std::string subscriber_name, int level = -1);
+```
+
+This function opens a new file, adds it to the list of message subscribers, and returns the level that can be used to write to the file.
+
+A user can specify a level >= 0. If `open_custom_message_file` is called without a level argument, the function will assign a unique level to the file that is >= 100. If a user wants the messages written to this file to also be captured by default Trick message subscribers, they should specify a level from 0-99. 
+
+Example:
+```cpp
+// Open the logfile
+int my_level = open_custom_message_file("my_log_dir/logfile", "custom_log");
+
+// Write to it by publishing a message with the given level
+message_publish(my_level, "This message will be written to my custom logfile");
+```
+
+## User accessible routines
+
 To subscribe / unsubscribe Trick's default subscribers (these call `::message_subscribe` / `::message_unsubscribe` mentioned above):
 
 By default these are all subscribed. You can use subscribe/unsubscribe throughout a simulation to turn on/off messages at will.

docs/documentation/simulation_capabilities/Variable-Server.md

@@ -39,7 +39,7 @@ int set_var_server_info_msg_on();
 ```
 
 These commands are also for toggling information messages from the variable server (i.e., commands received from <i>ALL</i> clients).
-The messages only go to a dedicated "varserver_log" file in the RUN directory.
+The messages only go to a dedicated `varserver_log` file in the RUN directory.
 The variable server log capability is off by default.
 
 ```c
@@ -47,6 +47,16 @@ int set_var_server_log_off();
 int set_var_server_log_on();
 ```
 
+These commands are also for toggling individual variable server session logs.
+Each log records the IP and port number of the client that connected and every message received.
+These logs go into a subdirectory under the RUN direcory called `sesssion_logs`, and the files are named `VSSession<num>.log`
+The variable server session log capability is off by default.
+
+```c
+int set_var_server_session_log_off();
+int set_var_server_session_log_on();
+```
+
 ### Getting and Setting the Variable Server Port Information
 
 To set the variable server port to a fixed number in the input file use var_server_set_port()