cleanup and extend Message Classes.

6 files changed, 222 insertions, 180 deletions

diff --git a/manuals/en/developers/Makefile b/manuals/en/developers/Makefile
index 8a8d83a..04f5460 100644
--- a/manuals/en/developers/Makefile
+++ b/manuals/en/developers/Makefile
@@ -2,6 +2,7 @@
 PANDOC=pandoc
 
 FILES = generaldevel.md \
+      messages.md \
       pluginAPI.md \
       platformsupport.md \
       daemonprotocol.md \
diff --git a/manuals/en/developers/generaldevel.md b/manuals/en/developers/generaldevel.md
index f59a56e..9d0eb7b 100644
--- a/manuals/en/developers/generaldevel.md
+++ b/manuals/en/developers/generaldevel.md
@@ -43,6 +43,53 @@ your changes directly to the Git repository. To do so, you will need a
 userid on Source Forge.
 
 
+Bugs Database
+-------------
+
+We have a bugs database which is at <https://bugs.bareos.org>.
+
+The first thing is if you want to take over a bug, rather than just make
+a note, you should assign the bug to yourself. This helps other
+developers know that you are the principal person to deal with the bug.
+You can do so by going into the bug and clicking on the <span>**Update
+Issue**</span> button. Then you simply go to the <span>**Assigned
+To**</span> box and select your name from the drop down box. To actually
+update it you must click on the <span>**Update Information**</span>
+button a bit further down on the screen, but if you have other things to
+do such as add a Note, you might wait before clicking on the
+<span>**Update Information**</span> button.
+
+Generally, we set the <span>**Status**</span> field to either
+acknowledged, confirmed, or feedback when we first start working on the
+bug. Feedback is set when we expect that the user should give us more
+information.
+
+Normally, once you are reasonably sure that the bug is fixed, and a
+patch is made and attached to the bug report, and/or in the SVN, you can
+close the bug. If you want the user to test the patch, then leave the
+bug open, otherwise close it and set <span>**Resolution**</span> to
+<span>**Fixed**</span>. We generally close bug reports rather quickly,
+even without confirmation, especially if we have run tests and can see
+that for us the problem is fixed. However, in doing so, it avoids
+misunderstandings if you leave a note while you are closing the bug that
+says something to the following effect: We are closing this bug because
+... If for some reason, it does not fix your problem, please feel free
+to reopen it, or to open a new bug report describing the problem".
+
+We do not recommend that you attempt to edit any of the bug notes that
+have been submitted, nor to delete them or make them private. In fact,
+if someone accidentally makes a bug note private, you should ask the
+reason and if at all possible (with his agreement) make the bug note
+public.
+
+If the user has not properly filled in most of the important fields
+(platorm, OS, Product Version, ...) please do not hesitate to politely
+ask him. Also, if the bug report is a request for a new feature, please
+politely send the user to the Feature Request menu item on
+www.bareos.org. The same applies to a support request (we answer only
+bugs), you might give the user a tip, but please politely refer him to
+the manual and the Getting Support page of www.bareos.org.
+
 Developing Bareos
 -----------------
 
@@ -396,149 +443,3 @@ concatenation causes the appropriate string to be concatenated to the
 “%”.
 
 Also please don’t use the STL or Templates or any complicated C++ code.
-
-### Message Classes
-
-Currently, there are five classes of messages: Debug, Error, Job,
-Memory, and Queued.
-
-### Debug Messages
-
-Debug messages are designed to be turned on at a specified debug level
-and are always sent to STDOUT. There are designed to only be used in the
-development debug process. They are coded as:
-
-DmsgN(level, message, arg1, ...) where the N is a number indicating how
-many arguments are to be substituted into the message (i.e. it is a
-count of the number arguments you have in your message – generally the
-number of percent signs (%)). <span>**level**</span> is the debug level
-at which you wish the message to be printed. message is the debug
-message to be printed, and arg1, ... are the arguments to be
-substituted. Since not all compilers support \#defines with varargs, you
-must explicitly specify how many arguments you have.
-
-When the debug message is printed, it will automatically be prefixed by
-the name of the daemon which is running, the filename where the Dmsg is,
-and the line number within the file.
-
-Some actual examples are:
-
-Dmsg2(20, “MD5len=%d MD5=%s\\n”, strlen(buf), buf);
-
-Dmsg1(9, “Created client %s record\\n”, client-\>hdr.name);
-
-### Error Messages
-
-Error messages are messages that are related to the daemon as a whole
-rather than a particular job. For example, an out of memory condition my
-generate an error message. They should be very rarely needed. In
-general, you should be using Job and Job Queued messages (Jmsg and
-Qmsg). They are coded as:
-
-EmsgN(error-code, level, message, arg1, ...) As with debug messages, you
-must explicitly code the of arguments to be substituted in the message.
-error-code indicates the severity or class of error, and it may be one
-of the following:
-
-ERROR_CODE   | Description
--------------|-------------------------------------------------------------------------------------------------------------------------------
-M_ABORT      | Causes the daemon to immediately abort. This should be used only in extrem e cases. It attempts to produce a traceback.
-M_ERROR_TERM | Causes the daemon to immediately terminate. This should be used only in extreme cases. It does not produce a traceback.
-M_FATAL      | Causes the daemon to terminate the current job, but the daemon keeps running
-M_ERROR      | Reports the error. The daemon and the job continue running
-M_WARNING    | Reports an warning message. The daemon and the job continue running
-M_INFO       | Reports an informational message
-
-There are other error message classes, but they are in a state of being
-redesigned or deprecated, so please do not use them. Some actual
-examples are:
-
-Emsg1(M\_ABORT, 0, “Cannot create message thread: %s\\n”,
-strerror(status));
-
-Emsg3(M\_WARNING, 0, “Connect to File daemon %s at %s:%d failed.
-Retrying ...\\n”, client-<span>\></span>hdr.name,
-client-<span>\></span>address, client-<span>\></span>port);
-
-Emsg3(M\_FATAL, 0, “bdird<span>\<</span>filed: bad response from Filed
-to %s command: %d %s\\n”, cmd, n, strerror(errno));
-
-### Job Messages
-
-Job messages are messages that pertain to a particular job such as a
-file that could not be saved, or the number of files and bytes that were
-saved. They Are coded as:
-
-    Jmsg(jcr, M\_FATAL, 0, "Text of message");
-
-A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
-have any number of arguments for substituted in a printf like format.
-Output from the Jmsg() will go to the Job report. \<br\> If the Jmsg is
-followed with a number such as Jmsg1(...), the number indicates the
-number of arguments to be substituted (varargs is not standard for
-\#defines), and what is more important is that the file and line number
-will be prefixed to the message. This permits a sort of debug from
-user’s output.
-
-### Queued Job Messages
-
-Queued Job messages are similar to Jmsg()s except that the message is
-Queued rather than immediately dispatched. This is necessary within the
-network subroutines and in the message editing routines. This is to
-prevent recursive loops, and to ensure that messages can be delivered
-even in the event of a network error.
-
-### Memory Messages
-
-Memory messages are messages that are edited into a memory buffer.
-Generally they are used in low level routines such as the low level
-device file dev.c in the Storage daemon or in the low level Catalog
-routines. These routines do not generally have access to the Job Control
-Record and so they return error essages reformatted in a memory buffer.
-Mmsg() is the way to do this.
-
-### Bugs Database
-
-We have a bugs database which is at https://bugs.bareos.org.
-
-The first thing is if you want to take over a bug, rather than just make
-a note, you should assign the bug to yourself. This helps other
-developers know that you are the principal person to deal with the bug.
-You can do so by going into the bug and clicking on the <span>**Update
-Issue**</span> button. Then you simply go to the <span>**Assigned
-To**</span> box and select your name from the drop down box. To actually
-update it you must click on the <span>**Update Information**</span>
-button a bit further down on the screen, but if you have other things to
-do such as add a Note, you might wait before clicking on the
-<span>**Update Information**</span> button.
-
-Generally, we set the <span>**Status**</span> field to either
-acknowledged, confirmed, or feedback when we first start working on the
-bug. Feedback is set when we expect that the user should give us more
-information.
-
-Normally, once you are reasonably sure that the bug is fixed, and a
-patch is made and attached to the bug report, and/or in the SVN, you can
-close the bug. If you want the user to test the patch, then leave the
-bug open, otherwise close it and set <span>**Resolution**</span> to
-<span>**Fixed**</span>. We generally close bug reports rather quickly,
-even without confirmation, especially if we have run tests and can see
-that for us the problem is fixed. However, in doing so, it avoids
-misunderstandings if you leave a note while you are closing the bug that
-says something to the following effect: We are closing this bug because
-... If for some reason, it does not fix your problem, please feel free
-to reopen it, or to open a new bug report describing the problem".
-
-We do not recommend that you attempt to edit any of the bug notes that
-have been submitted, nor to delete them or make them private. In fact,
-if someone accidentally makes a bug note private, you should ask the
-reason and if at all possible (with his agreement) make the bug note
-public.
-
-If the user has not properly filled in most of the important fields
-(platorm, OS, Product Version, ...) please do not hesitate to politely
-ask him. Also, if the bug report is a request for a new feature, please
-politely send the user to the Feature Request menu item on
-www.bareos.org. The same applies to a support request (we answer only
-bugs), you might give the user a tip, but please politely refer him to
-the manual and the Getting Support page of www.bareos.org.
diff --git a/manuals/en/developers/messages.md b/manuals/en/developers/messages.md
new file mode 100644
index 0000000..1ce93a6
--- /dev/null
+++ b/manuals/en/developers/messages.md
@@ -0,0 +1,142 @@
+Message Classes
+===============
+
+Currently, there are following classes of messages:
+
+   * Memory Messages
+   * Debug Messages
+   * Job Messages
+   * Queued Job Messages
+   * Error Messages
+
+
+### Memory Messages
+
+Memory messages are messages that are edited into a memory buffer.
+Generally they are used in low level routines.
+These routines do not generally have access to the Job Control
+Record and so they return messages reformatted in a memory buffer.
+
+    Mmsg(resultmessage, "3603 JobId=%u device %s is busy reading.\n", jobid);
+
+
+
+### Debug Messages
+
+Debug messages are designed to be turned on at a specified debug level
+and are always sent to STDOUT. There are designed to only be used in the
+development debug process. They are coded as:
+
+    DmsgN(level, message, arg1, ...)
+    
+where
+
+   * `N` is a number indicating how many arguments are to be substituted into the message (i.e. it is a
+count of the number arguments you have in your message – generally the
+number of percent signs (%)).
+   * `level` is the debug level at which you wish the message to be printed.
+   * `message` is the message to be printed, and 
+   * `arg1, ...` are the arguments to be substituted.
+    
+Since not all compilers support \#defines with varargs, you
+must explicitly specify how many arguments you have.
+
+When the debug message is printed, it will automatically be prefixed by
+the name of the daemon which is running, the filename where the Dmsg is,
+and the line number within the file.
+
+Some actual examples are:
+
+    Dmsg2(20, “MD5len=%d MD5=%s\n”, strlen(buf), buf);
+    Dmsg1(9, “Created client %s record\n”, client->hdr.name);
+
+
+
+### Job Messages
+
+Job messages are messages that pertain to a particular job such as a
+file that could not be saved, or the number of files and bytes that were
+saved. They are coded as:
+
+    Jmsg(JCR, ERROR_CODE, 0, message, arg1, ...);
+    
+where
+
+   * `JCR` is the **Job Control Record**. If `JCR == NULL` and the `JCR` can not be determined, the message is treated as Daemon message, with fallback to output to `STDOUT`.
+   * `ERROR_CODE` indicates the severity or class of error
+   * `0` might be a timestamp, but is generally 0 (timestamp will be set to current time)
+   * `message` is the message to be printed, and 
+   * `arg1, ...` are the arguments to be substituted.
+
+`ERROR_CODE` is one of the following:
+
+ERROR_CODE   | Description
+-------------|-------------------------------------------------------------------------------------------------------------------------------
+M_ABORT      | Causes the daemon to immediately abort. This should be used only in extrem e cases. It attempts to produce a traceback.
+M_ERROR_TERM | Causes the daemon to immediately terminate. This should be used only in extreme cases. It does not produce a traceback.
+M_FATAL      | Causes the daemon to terminate the current job, but the daemon keeps running.
+M_ERROR      | Reports the error. The daemon and the job continue running.
+M_WARNING    | Reports an warning message. The daemon and the job continue running.
+M_INFO       | Reports an informational message.
+
+The Jmsg() takes varargs so can
+have any number of arguments for substituted in a printf like format.
+Output from the Jmsg() will go to the Job report.
+
+If the Jmsg is followed with a number such as Jmsg1(...),
+the number indicates the number of arguments to be substituted
+(varargs is not standard for `#defines`),
+and what is more important is that the file and line number
+will be prefixed to the message. This permits a sort of debug from
+user’s output.
+
+    Jmsg1(jcr, M_WARNING, 0, "Plugin=%s not found.\n", cmd);
+    Jmsg1(jcr, M_ERROR, 0, "%s exists but is not a directory.\n", path);
+    Jmsg0(NULL, M_ERROR_TERM, 0, "Failed to find config filename.\n");
+
+
+The [Message Ressource](http://doc.bareos.org/master/html/bareos-manual-main-reference.html#MessagesChapter) configuration defines how and to what destinations will be sent.
+
+#### Special Cases
+
+  * `JCR == NULL`: in this case, it is tried to identify the `JCR` automatically. If no `JCR` is found, the message is treated as Daemon message, with fallback to output to `STDOUT`.
+  * `JCR.JobId == 0` and `JCR.dir_socket != NULL`: a socket connection to the Director exists (normally on the File or Storage Daemon). The message is send directly to the Director via this socket connection.
+
+
+
+### Queued Job Messages
+
+Queued Job messages are similar to Jmsg()s except that the message is
+Queued rather than immediately dispatched. This is necessary within the
+network subroutines and in the message editing routines. This is to
+prevent recursive loops, and to ensure that messages can be delivered
+even in the event of a network error.
+
+    Qmsg(jcr, M_INFO, 0, "File skipped. Not newer: %s\n", attr->ofname);
+
+
+
+### Error Messages
+
+Error messages are messages that are related to the daemon as a whole
+rather than a particular job. For example, an out of memory condition my
+generate an error message. They should be very rarely needed. In
+general, you should be using Job and Job Queued messages (Jmsg and
+Qmsg). They are coded as:
+
+    EmsgN(ERROR_CODE, 0, message, arg1, ...)
+    
+As with debug messages, you
+must explicitly code the of arguments to be substituted in the message.
+
+Some actual examples are:
+
+    Emsg1(M_ABORT, 0, “Cannot create message thread: %s\n”, strerror(status));
+    Emsg3(M_WARNING, 0, “Connect to File daemon %s at %s:%d failed. Retrying ...\n”, client->hdr.name, client->address, client->port);
+    Emsg3(M_FATAL, 0, “Bad response from File daemon to %s command: %d %s\n”, cmd, n, strerror(errno));
+
+In essence, a `EmsgN(ERROR_CODE, 0, message, arg1, ...)` call resolves to:
+
+    DmsgN(10, message, arg1, ...)
+    JmsgN(NULL, ERROR_CODE, 0, message, arg1, ...)
+    
\ No newline at end of file
diff --git a/manuals/en/developers/netprotocol.md b/manuals/en/developers/netprotocol.md
index 5f414e4..48af785 100644
--- a/manuals/en/developers/netprotocol.md
+++ b/manuals/en/developers/netprotocol.md
@@ -77,13 +77,18 @@ int bnet\_fsend(BSOCK \*sock, char \*format, ...) and it allows you to
 send a formatted messages somewhat like fprintf(). The return status is
 the same as bnet\_send.
 
-Additional Error information
-----------------------------
+is\_bnet\_error
+---------------
 
 Fro additional error information, you can call
 <span>**is\_bnet\_error(BSOCK \*bsock)**</span> which will return 0 if
 there is no error or non-zero if there is an error on the last
-transmission. The <span>**is\_bnet\_stop(BSOCK \*bsock)**</span>
+transmission.
+
+is\_bnet\_stop
+--------------
+
+The <span>**is\_bnet\_stop(BSOCK \*bsock)**</span>
 function will return 0 if there no errors and you can continue sending.
 It will return non-zero if there are errors or the line is closed (no
 more transmissions should be sent).
@@ -99,12 +104,14 @@ length that follows as four bytes in network byte order. The data is
 read into sock-<span>\></span>msg and is sock-<span>\></span>msglen
 bytes. If the sock-<span>\></span>msg is not large enough, bnet\_recv()
 realloc() the buffer. It will return an error (-2) if maxbytes is less
-than the record size sent. It returns:
+than the record size sent.
 
-     * Returns number of bytes read
-     * Returns 0 on end of file
-     * Returns -1 on hard end of file (i.e. network connection close)
-     * Returns -2 on error
+It returns:
+
+   * \>0: number of bytes read
+   * 0: on end of file
+   * -1: on hard end of file (i.e. network connection close)
+   * -2: on error
 
 It should be noted that bnet\_recv() is a blocking read.
 
@@ -116,23 +123,15 @@ To send a “signal” from one daemon to another, one uses the subroutine:
 int bnet\_sig(BSOCK \*sock, SIGNAL) where SIGNAL is one of the
 following:
 
-1.  BNET\_EOF - deprecated use BNET\_EOD
-
-2.  BNET\_EOD - End of data stream, new data may follow
-
-3.  BNET\_EOD\_POLL - End of data and poll all in one
-
-4.  BNET\_STATUS - Request full status
-
-5.  BNET\_TERMINATE - Conversation terminated, doing close()
-
-6.  BNET\_POLL - Poll request, I’m hanging on a read
-
-7.  BNET\_HEARTBEAT - Heartbeat Response requested
-
-8.  BNET\_HB\_RESPONSE - Only response permitted to HB
-
-9.  BNET\_PROMPT - Prompt for UA
+   * BNET\_EOF - deprecated use BNET\_EOD
+   * BNET\_EOD - End of data stream, new data may follow
+   * BNET\_EOD\_POLL - End of data and poll all in one
+   * BNET\_STATUS - Request full status
+   * BNET\_TERMINATE - Conversation terminated, doing close()
+   * BNET\_POLL - Poll request, I’m hanging on a read
+   * BNET\_HEARTBEAT - Heartbeat Response requested
+   * BNET\_HB\_RESPONSE - Only response permitted to HB
+   * BNET\_PROMPT - Prompt for UA
 
 bnet\_strerror
 --------------
diff --git a/manuals/en/main/messagesres.tex b/manuals/en/main/messagesres.tex
index 969bccd..c5637b5 100644
--- a/manuals/en/main/messagesres.tex
+++ b/manuals/en/main/messagesres.tex
@@ -1,7 +1,7 @@
 
 \chapter{Messages Resource}
+% used as link from developer guide
 \label{MessagesChapter}
-\label{MessagesResource}
 \label{ResourceMessages}
 \index[general]{Resource!Messages}
 \index[general]{Messages Resource}
@@ -9,9 +9,9 @@
 The Messages resource defines how messages are to be handled and destinations
 to which they should be sent.
 
-Even though each daemon has a full message handler, within the File daemon and
-the Storage daemon, you will normally choose to send all the appropriate
-messages back to the Director.  This permits all the messages associated with
+Even though each daemon has a full message handler, within the \bareosFd and
+the \bareosSd, you will normally choose to send all the appropriate
+messages back to the \bareosDir.  This permits all the messages associated with
 a single Job to be combined in the Director and sent as a single email message
 to the user, or logged together in a single file.
 
@@ -28,10 +28,7 @@ In general, messages are attached to a Job and are included in the Job report.
 There are some rare cases, where this is not possible, e.g. when no job is
 running, or if a communications error occurs between a daemon and the
 director. In those cases, the message may remain in the system, and should be
-flushed at the end of the next Job. However, since such messages are not
-attached to a Job, any that are mailed will be sent to {\bf
-/usr/lib/sendmail}. On some systems, such as FreeBSD, if your sendmail is in a
-different place, you may want to link it to the the above location.
+flushed at the end of the next Job.
 
 The records contained in a Messages resource consist of a {\bf destination}
 specification followed by a list of {\bf message-types} in the format:
diff --git a/manuals/en/main/resource-messages-definitions.tex b/manuals/en/main/resource-messages-definitions.tex
index e2eda13..b7b0a41 100644
--- a/manuals/en/main/resource-messages-definitions.tex
+++ b/manuals/en/main/resource-messages-definitions.tex
@@ -50,7 +50,9 @@ file this email based on the Job termination code (see \linkResourceDirective{Di
 In the absence of this resource,  Bareos will send all mail using the
 following command:
 
-{\bf mail -s "Bareos Message" {\textless}recipients{\textgreater}}
+{\bf /usr/lib/sendmail -F BAREOS {\textless}recipients{\textgreater}}
+
+%{\bf mail -s "Bareos Message" {\textless}recipients{\textgreater}}
 
 In many cases, depending on your machine, this command may not work.
 However, by using the \configdirective{Mail Command}, you can specify exactly how to