1Message Classes
2===============
3
4Currently, there are following classes of messages:
5
6-  Memory Messages
7-  Debug Messages
8-  Job Messages
9-  Queued Job Messages
10-  Error Messages
11
12Memory Messages
13~~~~~~~~~~~~~~~
14
15Memory messages are messages that are edited into a memory buffer.
16Generally they are used in low level routines. These routines do not
17generally have access to the Job Control Record and so they return
18messages reformatted in a memory buffer.
19
20::
21
22    Mmsg(resultmessage, "3603 JobId=%u device %s is busy reading.\n", jobid);
23
24Debug Messages
25~~~~~~~~~~~~~~
26
27Debug messages are designed to be turned on at a specified debug level
28and are always sent to STDOUT. There are designed to only be used in the
29development debug process. They are coded as:
30
31::
32
33    DmsgN(level, message, arg1, ...)
34
35where
36
37-  ``N`` is a number indicating how many arguments are to be substituted
38   into the message (i.e. it is a count of the number arguments you have
39   in your message – generally the number of percent signs (%)).
40-  ``level`` is the debug level at which you wish the message to be
41   printed.
42-  ``message`` is the message to be printed, and
43-  ``arg1, ...`` are the arguments to be substituted.
44
45Since not all compilers support #defines with varargs, you must
46explicitly specify how many arguments you have.
47
48When the debug message is printed, it will automatically be prefixed by
49the name of the daemon which is running, the filename where the Dmsg is,
50and the line number within the file.
51
52Some actual examples are:
53
54::
55
56    Dmsg2(20, “MD5len=%d MD5=%s\n”, strlen(buf), buf);
57    Dmsg1(9, “Created client %s record\n”, client->hdr.name);
58
59Job Messages
60~~~~~~~~~~~~
61
62Job messages are messages that pertain to a particular job such as a
63file that could not be saved, or the number of files and bytes that were
64saved. They are coded as:
65
66::
67
68    Jmsg(JCR, ERROR_CODE, 0, message, arg1, ...);
69
70where
71
72-  ``JCR`` is the **Job Control Record**. If ``JCR == NULL`` and the
73   ``JCR`` can not be determined, the message is treated as Daemon
74   message, with fallback to output to ``STDOUT``.
75-  ``ERROR_CODE`` indicates the severity or class of error
76-  ``0`` might be a timestamp, but is generally 0 (timestamp will be set
77   to current time)
78-  ``message`` is the message to be printed, and
79-  ``arg1, ...`` are the arguments to be substituted.
80
81``ERROR_CODE`` is one of the following:
82
83+---------------+----------------------------------------------------------------+
84| ERROR OR CODE | Description                                                    |
85+===============+================================================================+
86| M_ABORT       | Causes the daemon to immediately abort. This should be used    |
87|               | only in extrem e cases. It attempts to produce a traceback.    |
88+---------------+----------------------------------------------------------------+
89| M_ERROR_TERM  | Causes the daemon to immediately terminate. This should be     |
90|               | used only in extreme cases. It does not produce a traceback.   |
91+---------------+----------------------------------------------------------------+
92| M_FATAL       | Causes the daemon to terminate the current job, but the daemon |
93|               | keeps running.                                                 |
94|               |                                                                |
95+---------------+----------------------------------------------------------------+
96| M_ERROR       | Reports the error. The daemon and the job continue running.    |
97+---------------+----------------------------------------------------------------+
98| M_WARNING     | Reports an warning message. The daemon and the job continue    |
99|               | running.                                                       |
100+---------------+----------------------------------------------------------------+
101| M_INFO        | Reports an informational message.                              |
102+---------------+----------------------------------------------------------------+
103
104The Jmsg() takes varargs so can have any number of arguments for
105substituted in a printf like format. Output from the Jmsg() will go to
106the Job report.
107
108If the Jmsg is followed with a number such as Jmsg1(…), the number
109indicates the number of arguments to be substituted (varargs is not
110standard for ``#defines``), and what is more important is that the file
111and line number will be prefixed to the message. This permits a sort of
112debug from user’s output.
113
114::
115
116    Jmsg1(jcr, M_WARNING, 0, "Plugin=%s not found.\n", cmd);
117    Jmsg1(jcr, M_ERROR, 0, "%s exists but is not a directory.\n", path);
118    Jmsg0(NULL, M_ERROR_TERM, 0, "Failed to find config filename.\n");
119
120The `Message Resource <../Configuration/Messages.html>`__ configuration defines how and to what destinations will be sent.
121
122Special Cases
123^^^^^^^^^^^^^
124
125-  ``JCR == NULL``: in this case, it is tried to identify the ``JCR``
126   automatically. If no ``JCR`` is found, the message is treated as
127   Daemon message, with fallback to output to ``STDOUT``.
128-  ``JCR.JobId == 0`` and ``JCR.dir_socket != NULL``: a socket
129   connection to the Director exists (normally on the File or Storage
130   Daemon). The message is send directly to the Director via this socket
131   connection.
132
133Queued Job Messages
134~~~~~~~~~~~~~~~~~~~
135
136Queued Job messages are similar to Jmsg()s except that the message is
137Queued rather than immediately dispatched. This is necessary within the
138network subroutines and in the message editing routines. This is to
139prevent recursive loops, and to ensure that messages can be delivered
140even in the event of a network error.
141
142::
143
144    Qmsg(jcr, M_INFO, 0, "File skipped. Not newer: %s\n", attr->ofname);
145
146Error Messages
147~~~~~~~~~~~~~~
148
149Error messages are messages that are related to the daemon as a whole
150rather than a particular job. For example, an out of memory condition my
151generate an error message. They should be very rarely needed. In
152general, you should be using Job and Job Queued messages (Jmsg and
153Qmsg). They are coded as:
154
155::
156
157    EmsgN(ERROR_CODE, 0, message, arg1, ...)
158
159As with debug messages, you must explicitly code the of arguments to be
160substituted in the message.
161
162Some actual examples are:
163
164::
165
166    Emsg1(M_ABORT, 0, “Cannot create message thread: %s\n”, strerror(status));
167    Emsg3(M_WARNING, 0, “Connect to File daemon %s at %s:%d failed. Retrying ...\n”, client->hdr.name, client->address, client->port);
168    Emsg3(M_FATAL, 0, “Bad response from File daemon to %s command: %d %s\n”, cmd, n, strerror(errno));
169
170In essence, a ``EmsgN(ERROR_CODE, 0, message, arg1, ...)`` call resolves
171to:
172
173::
174
175    DmsgN(10, message, arg1, ...)
176    JmsgN(NULL, ERROR_CODE, 0, message, arg1, ...)
177