Merge lp:~jlmuir/epics-appdev/typo-fixes-3.14 into lp:~epics-documenters/epics-appdev/3.16
- typo-fixes-3.14
- Merge into 3.16
Proposed by
J. Lewis Muir
Status: | Merged |
---|---|
Merged at revision: | 37 |
Proposed branch: | lp:~jlmuir/epics-appdev/typo-fixes-3.14 |
Merge into: | lp:~epics-documenters/epics-appdev/3.16 |
Diff against target: |
1203 lines (+362/-324) (has conflicts) 3 files modified
tex/errorLogging.tex (+141/-133) tex/libCom.tex (+1/-1) tex/recordSupport.tex (+220/-190) Text conflict in tex/errorLogging.tex |
To merge this branch: | bzr merge lp:~jlmuir/epics-appdev/typo-fixes-3.14 |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Ralph Lange | Needs Fixing | ||
Review via email:
|
Commit message
Description of the change
Typo fix.
To post a comment you must log in.
- 38. By Andrew Johnson
-
Merged Lewis' typo fix.
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'tex/errorLogging.tex' | |||
2 | --- tex/errorLogging.tex 2011-10-28 20:44:28 +0000 | |||
3 | +++ tex/errorLogging.tex 2012-01-06 20:56:29 +0000 | |||
4 | @@ -3,26 +3,25 @@ | |||
5 | 3 | 3 | ||
6 | 4 | \section{Overview } | 4 | \section{Overview } |
7 | 5 | 5 | ||
12 | 6 | Errors detected by an IOC can be divided into classes: Errors related to a particular client and errors not attributable to a | 6 | Errors detected by an IOC can be divided into classes: |
13 | 7 | particular client. An example of the first type of error is an illegal Channel Access request. For this type of error, a status | 7 | Errors related to a particular client and errors not attributable to a particular client. |
14 | 8 | value should be passed back to the client. An example of the second type of error is a device driver detecting a hardware | 8 | An example of the first type of error is an illegal Channel Access request. |
15 | 9 | error. This type of error should be reported to a system wide error handler. | 9 | For this type of error, a status value should be passed back to the client. |
16 | 10 | An example of the second type of error is a device driver detecting a hardware error. | ||
17 | 11 | This type of error should be reported to a system wide error handler. | ||
18 | 10 | 12 | ||
19 | 11 | Dividing errors into these two classes is complicated by a number of factors. | 13 | Dividing errors into these two classes is complicated by a number of factors. |
20 | 12 | 14 | ||
21 | 13 | \begin{itemize} | 15 | \begin{itemize} |
34 | 14 | \item In many cases it is not possible for the routine detecting an error to decide which type of error occurred. | 16 | \item In many cases it is not possible for the routine detecting an error to decide which type of error occurred. |
35 | 15 | 17 | ||
36 | 16 | \item Normally, only the routine detecting the error knows how to generate a fully descriptive error message. Thus, if a | 18 | \item Normally, only the routine detecting the error knows how to generate a fully descriptive error message. |
37 | 17 | routine decides that the error belongs to a particular client and merely returns an error status value, the ability to | 19 | Thus, if a routine decides that the error belongs to a particular client and merely returns an error status value, the ability to generate a fully descriptive error message is lost. |
38 | 18 | generate a fully descriptive error message is lost. | 20 | |
39 | 19 | 21 | \item If a routine always generates fully descriptive error messages then a particular client could cause error message storms. | |
40 | 20 | \item If a routine always generates fully descriptive error messages then a particular client could cause error message | 22 | |
41 | 21 | storms. | 23 | \item While developing a new application the programmer normally prefers fully descriptive error messages. |
42 | 22 | 24 | For a production system, however, the system wide error handler should not normally receive error messages cause by a particular client. | |
31 | 23 | \item While developing a new application the programmer normally prefers fully descriptive error messages. For a | ||
32 | 24 | production system, however, the system wide error handler should not normally receive error messages cause by a | ||
33 | 25 | particular client. | ||
43 | 26 | 25 | ||
44 | 27 | \end{itemize} | 26 | \end{itemize} |
45 | 28 | 27 | ||
46 | @@ -37,18 +36,20 @@ | |||
47 | 37 | 36 | ||
48 | 38 | \item errlogThread - A thread that passes the messages to all registered listeners. | 37 | \item errlogThread - A thread that passes the messages to all registered listeners. |
49 | 39 | 38 | ||
52 | 40 | \item console output and message buffer size - Messages can also be written to the console. The storage for the message | 39 | \item console output and message buffer size - Messages can also be written to the console. |
53 | 41 | queue can be specified by the user. | 40 | The storage for the message queue can be specified by the user. |
54 | 42 | 41 | ||
55 | 43 | \item status codes - EPICS status codes. | 42 | \item status codes - EPICS status codes. |
56 | 44 | 43 | ||
58 | 45 | \item iocLog- A system wide error logger supplied with base. It writes all messages to a system wide file. | 44 | \item iocLog- A system wide error logger supplied with base. |
59 | 45 | It writes all messages to a system wide file. | ||
60 | 46 | 46 | ||
61 | 47 | NOTE: Many sites use CMLOG instead of iocLog. | 47 | NOTE: Many sites use CMLOG instead of iocLog. |
62 | 48 | 48 | ||
63 | 49 | \end{itemize} | 49 | \end{itemize} |
64 | 50 | 50 | ||
66 | 51 | NOTE: \verb|recGbl| error routines are also provided. They in turn call one of the error message routines. | 51 | NOTE: \verb|recGbl| error routines are also provided. |
67 | 52 | They in turn call one of the error message routines. | ||
68 | 52 | 53 | ||
69 | 53 | \section{Error Message Routines} | 54 | \section{Error Message Routines} |
70 | 54 | 55 | ||
71 | @@ -64,10 +65,8 @@ | |||
72 | 64 | \index{errlogVprintf} | 65 | \index{errlogVprintf} |
73 | 65 | \index{errlogMessage} | 66 | \index{errlogMessage} |
74 | 66 | \index{errlogFlush} | 67 | \index{errlogFlush} |
79 | 67 | \verb|errlogPrintf| and \verb|errlogVprintf| are like \verb|printf| and \verb|vprintf| provided by the standard C library, except | 68 | \verb|errlogPrintf| and \verb|errlogVprintf| are like \verb|printf| and \verb|vprintf| provided by the standard C library, except that their output is sent to the errlog task; unless configured not to, the output will appear on the console as well. |
80 | 68 | that their output is sent to the errlog task; unless configured not to, the output will appear on the console as well. Consult | 69 | Consult any book that describes the standard C library such as ``The C Programming Language ANSI C Edition" by Kernighan and Ritchie. |
77 | 69 | any book that describes the standard C library such as ``The C Programming Language ANSI C Edition" by Kernighan | ||
78 | 70 | and Ritchie. | ||
81 | 71 | 70 | ||
82 | 72 | \verb|errlogMessage| sends message to the errlog task. | 71 | \verb|errlogMessage| sends message to the errlog task. |
83 | 73 | 72 | ||
84 | @@ -101,14 +100,14 @@ | |||
85 | 101 | \index{errlogGetSevEnumString} | 100 | \index{errlogGetSevEnumString} |
86 | 102 | \index{errlogSetSevToLog} | 101 | \index{errlogSetSevToLog} |
87 | 103 | \index{errlogGetSevToLog} | 102 | \index{errlogGetSevToLog} |
96 | 104 | \verb|errlogSevPrintf| and \verb|errlogSevVprintf| are like \verb|errlogPrintf| and \verb|errlogVprintf| except that they | 103 | \verb|errlogSevPrintf| and \verb|errlogSevVprintf| are like \verb|errlogPrintf| and \verb|errlogVprintf| except that they add the severity to the beginning of the message in the form ``sevr=\textless{}value\textgreater{}" where value is one of ``info, minor, major, fatal". |
97 | 105 | add the severity to the beginning of the message in the form ``sevr=\textless{}value\textgreater{}" where value is one of ``info, minor, major, | 104 | Also the message is suppressed if severity is less than the current severity to suppress. |
98 | 106 | fatal". Also the message is suppressed if severity is less than the current severity to suppress. If epicsThreadIsOkToBlock | 105 | If \verb|epicsThreadIsOkToBlock| is true, which is true during iocInit, errlogSevVprintf does NOT send output to the errlog task. |
99 | 107 | is true, which is true during iocInit, errlogSevVprintf does NOT send output to the errlog task. | 106 | |
100 | 108 | 107 | \verb|errlogGetSevEnumString| gets the string value of severity. | |
101 | 109 | \verb|errlogGetSevEnumString| gets the string value of severity. | 108 | |
102 | 110 | 109 | \verb|errlogSetSevToLog| sets the severity to log. | |
103 | 111 | \verb|errlogSetSevToLog| sets the severity to log. \verb|errlogGetSevToLog| gets the current severity to log. | 110 | \verb|errlogGetSevToLog| gets the current severity to log. |
104 | 112 | 111 | ||
105 | 113 | \subsection{Status Routines } | 112 | \subsection{Status Routines } |
106 | 114 | 113 | ||
107 | @@ -131,25 +130,23 @@ | |||
108 | 131 | Where status is defined as: | 130 | Where status is defined as: |
109 | 132 | 131 | ||
110 | 133 | \begin{itemize} | 132 | \begin{itemize} |
116 | 134 | \item 0: Find latest vxWorks or Unix error. | 133 | \item 0: Find latest vxWorks or Unix error. |
117 | 135 | 134 | ||
118 | 136 | \item -1: Don't report status. | 135 | \item -1: Don't report status. |
119 | 137 | 136 | ||
120 | 138 | \item Other: See ``Return Status Values" above. | 137 | \item Other: See ``Return Status Values" above. |
121 | 139 | 138 | ||
122 | 140 | \end{itemize} | 139 | \end{itemize} |
123 | 141 | 140 | ||
135 | 142 | \verb|errMessage|, via a call to \verb|errPrintf|, prints the message, the status symbol and string values, and the name of the task | 141 | \verb|errMessage|, via a call to \verb|errPrintf|, prints the message, the status symbol and string values, and the name of the task which invoked \verb|errMessage|. |
136 | 143 | which invoked \verb|errMessage|. It also prints the name of the source file and the line number from which the call was | 142 | It also prints the name of the source file and the line number from which the call was issued. |
137 | 144 | issued. | 143 | |
138 | 145 | 144 | The calling routine is expected to pass a descriptive message to this routine. | |
139 | 146 | The calling routine is expected to pass a descriptive message to this routine. Many subsystems provide routines built on | 145 | Many subsystems provide routines built on top of \verb|errMessage| which generate descriptive messages. |
140 | 147 | top of \verb|errMessage| which generate descriptive messages. | 146 | |
141 | 148 | 147 | An IOC global variable \verb|errVerbose|, defined as an \verb|external| in \verb|errMdef.h|, specifies verbose messages. | |
142 | 149 | An IOC global variable \verb|errVerbose|, defined as an \verb|external| in \verb|errMdef.h|, specifies verbose messages. If | 148 | If \verb|errVerbose| is \verb|TRUE| then \verb|errMessage| should be called whenever an error is detected even if it is known that the error belongs to a specific client. |
143 | 150 | \verb|errVerbose| is \verb|TRUE| then \verb|errMessage| should be called whenever an error is detected even if it is known that the | 149 | If \verb|errVerbose| is \verb|FALSE| then \verb|errMessage| should be called only for errors that are not caused by a specific client. |
133 | 151 | error belongs to a specific client. If \verb|errVerbose| is \verb|FALSE| then \verb|errMessage| should be called only for errors that are | ||
134 | 152 | not caused by a specific client. | ||
144 | 153 | 150 | ||
145 | 154 | Routine \verb|errPrintf| is normally called as follows: | 151 | Routine \verb|errPrintf| is normally called as follows: |
146 | 155 | 152 | ||
147 | @@ -161,28 +158,28 @@ | |||
148 | 161 | Where status is defined as: | 158 | Where status is defined as: |
149 | 162 | 159 | ||
150 | 163 | \begin{itemize} | 160 | \begin{itemize} |
156 | 164 | \item 0: Find latest vxWorks or Unix error. | 161 | \item 0: Find latest vxWorks or Unix error. |
157 | 165 | 162 | ||
158 | 166 | \item -1: Don't report status. | 163 | \item -1: Don't report status. |
159 | 167 | 164 | ||
160 | 168 | \item Other: See ``Return Status Values", above. | 165 | \item Other: See ``Return Status Values", above. |
161 | 169 | 166 | ||
162 | 170 | \end{itemize} | 167 | \end{itemize} |
163 | 171 | 168 | ||
164 | 172 | FILE and LINE are defined as: | 169 | FILE and LINE are defined as: |
165 | 173 | 170 | ||
166 | 174 | \begin{itemize} | 171 | \begin{itemize} |
168 | 175 | \item \_\_FILE\_\_ As shown or \verb|NULL| if the file name and line number should not be printed. | 172 | \item \_\_FILE\_\_ As shown or \verb|NULL| if the file name and line number should not be printed. |
169 | 176 | 173 | ||
170 | 177 | \item \_\_LINE\_\_ As shown | 174 | \item \_\_LINE\_\_ As shown |
171 | 178 | 175 | ||
172 | 179 | \end{itemize} | 176 | \end{itemize} |
173 | 180 | 177 | ||
176 | 181 | The remaining arguments are just like the arguments to the C \verb|printf| routine. \verb|errVerbose| determines if the filename | 178 | The remaining arguments are just like the arguments to the C \verb|printf| routine. |
177 | 182 | and line number are shown. | 179 | \verb|errVerbose| determines if the filename and line number are shown. |
178 | 183 | 180 | ||
181 | 184 | An EPICS status code can also be converted to a string. If the supplied status code isn't registered in the status code | 181 | An EPICS status code can also be converted to a string. |
182 | 185 | database then the raw status code number is converted into a string in the destination buffer. | 182 | If the supplied status code isn't registered in the status code database then the raw status code number is converted into a string in the destination buffer. |
183 | 186 | 183 | ||
184 | 187 | \begin{verbatim} | 184 | \begin{verbatim} |
185 | 188 | #include "errMdef.h" | 185 | #include "errMdef.h" |
186 | @@ -198,12 +195,14 @@ | |||
187 | 198 | 195 | ||
188 | 199 | \index{epicsPrintf} | 196 | \index{epicsPrintf} |
189 | 200 | \index{epicsVprintf} | 197 | \index{epicsVprintf} |
191 | 201 | These are macros that call errlogPrintf and errlogVprintf. They are provided for compatibility. | 198 | These are macros that call errlogPrintf and errlogVprintf. |
192 | 199 | They are provided for compatibility. | ||
193 | 202 | 200 | ||
194 | 203 | \section{errlog Listeners} | 201 | \section{errlog Listeners} |
195 | 204 | 202 | ||
196 | 205 | \index{errlog Listeners} | 203 | \index{errlog Listeners} |
198 | 206 | Any code can receive errlog message. The following are the calls to add and remove a listener. | 204 | Any code can receive errlog message. |
199 | 205 | The following are the calls to add and remove a listener. | ||
200 | 207 | 206 | ||
201 | 208 | \begin{verbatim} | 207 | \begin{verbatim} |
202 | 209 | typedef void(*errlogListener) (void *pvt,const char *message); | 208 | typedef void(*errlogListener) (void *pvt,const char *message); |
203 | @@ -214,34 +213,39 @@ | |||
204 | 214 | \index{errlogListener} | 213 | \index{errlogListener} |
205 | 215 | \index{errlogAddListener} | 214 | \index{errlogAddListener} |
206 | 216 | \index{errlogRemoveListener} | 215 | \index{errlogRemoveListener} |
209 | 217 | These routines add/remove a callback that receives each error message. These routines are the interface to the actual | 216 | These routines add/remove a callback that receives each error message. |
210 | 218 | system wide error handlers. | 217 | These routines are the interface to the actual system wide error handlers. |
211 | 219 | 218 | ||
212 | 220 | \section{errlogThread} | 219 | \section{errlogThread} |
213 | 221 | 220 | ||
214 | 222 | \index{errlogThread} | 221 | \index{errlogThread} |
227 | 223 | The error message routines can be called by any non-interrupt level code. These routines pass the message to the errlog | 222 | The error message routines can be called by any non-interrupt level code. |
228 | 224 | Thread. If any of the error message routines are called at interrupt level, \verb|epicsInterruptContextMessage| is | 223 | These routines pass the message to the errlog Thread. |
229 | 225 | called with the message ``errlogPrintf called from interrupt level". | 224 | If any of the error message routines are called at interrupt level, \verb|epicsInterruptContextMessage| is called with the message ``errlogPrintf called from interrupt level". |
230 | 226 | 225 | ||
231 | 227 | errlogThread manages the messages. Messages are placed in a message queue, which is read by errlogThread. The | 226 | \verb|errlogThread| manages the messages. |
232 | 228 | message queue uses a fixed block of memory to hold all messages. When the message queue is full additional messages | 227 | Messages are placed in a message queue, which is read by errlogThread. |
233 | 229 | are rejected but a count of missed messages is kept. The next time the message queue empties an extra message about the | 228 | The message queue uses a fixed block of memory to hold all messages. |
234 | 230 | missed messages is generated. | 229 | When the message queue is full additional messages are rejected but a count of missed messages is kept. |
235 | 231 | 230 | The next time the message queue empties an extra message about the missed messages is generated. | |
236 | 232 | The maximum message size is by default 256 characters. If a message is longer, the message is truncated and a message | 231 | |
237 | 233 | explaining that it was truncated is appended. There is a chance that long messages corrupt memory. This only happens if | 232 | The maximum message size is by default 256 characters. |
238 | 234 | client code is defective. Long messages most likely result from ``\%s" formats with a bad string argument. | 233 | If a message is longer, the message is truncated and a message explaining that it was truncated is appended. |
239 | 234 | There is a chance that long messages corrupt memory. | ||
240 | 235 | This only happens if client code is defective. | ||
241 | 236 | Long messages most likely result from ``\%s" formats with a bad string argument. | ||
242 | 235 | 237 | ||
243 | 236 | errlogThread passes each message to any registered listener. | 238 | errlogThread passes each message to any registered listener. |
244 | 237 | 239 | ||
245 | 238 | \section{console output and message queue size} | 240 | \section{console output and message queue size} |
246 | 239 | 241 | ||
250 | 240 | The errlog system can also display messages on the ioc console. It calls \verb|epicsThreadIsOkToBlock| to decide when | 242 | The errlog system can also display messages on the ioc console. |
251 | 241 | to display the message. If it is OK to block, the message is displayed by the same thread that calls one of the errlog print | 243 | It calls \verb|epicsThreadIsOkToBlock| to decide when to display the message. |
252 | 242 | routines. If it is not OK to block, errlorThread displays the messages. | 244 | If it is OK to block, the message is displayed by the same thread that calls one of the errlog print routines. |
253 | 245 | If it is not OK to block, errlogThread displays the messages. | ||
254 | 243 | 246 | ||
256 | 244 | Normally the errlog system displays all messages on the console. \verb|eltc| can be used to suppress these messages. | 247 | Normally the errlog system displays all messages on the console. |
257 | 248 | \verb|eltc| can be used to suppress these messages. | ||
258 | 245 | 249 | ||
259 | 246 | \begin{verbatim} | 250 | \begin{verbatim} |
260 | 247 | int eltc(int yesno); /* error log to console (0 or 1) */ | 251 | int eltc(int yesno); /* error log to console (0 or 1) */ |
261 | @@ -252,11 +256,11 @@ | |||
262 | 252 | \index{eltc} | 256 | \index{eltc} |
263 | 253 | \index{errlogInit} | 257 | \index{errlogInit} |
264 | 254 | \index{errlogInit2} | 258 | \index{errlogInit2} |
268 | 255 | eltc determines if errlog task writes message to the console. During error messages storms this command can be used to | 259 | eltc determines if errlog task writes message to the console. |
269 | 256 | suppress console messages. A argument of 0 suppresses the messages and any other value lets the message go to the | 260 | During error message storms this command can be used to suppress console messages. |
270 | 257 | console. | 261 | A argument of 0 suppresses the messages, any other value lets messages go to the console. |
271 | 258 | 262 | ||
273 | 259 | errlogInit or errlogInit2 can be used to initialize the error logging system with a larger buffer and maximum message size. | 263 | \verb|errlogInit| or \verb|errlogInit2| can be used to initialize the error logging system with a larger buffer and maximum message size. |
274 | 260 | The default buffer size is 1280 bytes, and the default maximum message size is 256. | 264 | The default buffer size is 1280 bytes, and the default maximum message size is 256. |
275 | 261 | 265 | ||
276 | 262 | \section{Status Codes} | 266 | \section{Status Codes} |
277 | @@ -265,34 +269,34 @@ | |||
278 | 265 | EPICS defined status values provide the following features: | 269 | EPICS defined status values provide the following features: |
279 | 266 | 270 | ||
280 | 267 | \begin{itemize} | 271 | \begin{itemize} |
282 | 268 | \item Whenever possible, IOC routines return a status value: (0, non-0) means (\verb|OK|, \verb|ERROR|). | 272 | \item Whenever possible, IOC routines return a status value: |
283 | 273 | 0 means OK, non-0 means an error. | ||
284 | 269 | 274 | ||
286 | 270 | \item The include files for each IOC subsystem contain macros defining error status symbols and strings. | 275 | \item The header files for most IOC subsystems contain macros defining error status symbols and strings. |
287 | 271 | 276 | ||
288 | 272 | \item Routines are provided for run time access of the error status symbols and strings. | 277 | \item Routines are provided for run time access of the error status symbols and strings. |
289 | 273 | 278 | ||
290 | 279 | \index{errVerbose} | ||
291 | 274 | \item A global variable \verb|errVerbose| helps code decide if error messages should be generated. | 280 | \item A global variable \verb|errVerbose| helps code decide if error messages should be generated. |
292 | 275 | 281 | ||
293 | 276 | \end{itemize} | 282 | \end{itemize} |
294 | 277 | 283 | ||
305 | 278 | WARNING: During the fall of 1995 a series of tech-talk messages were generated concerning EPICS status values. No | 284 | IOC routines often return a long integer status value, encoded similar to the vxWorks error status encoding. |
306 | 279 | consensus was reached. | 285 | On some modern architectures a long integer is more than 32 bits wide, but in order to keep the API compatible the status values are still passed as long integers, even though only 32 bits are ever used. |
307 | 280 | 286 | The most significant 16 bits indicate the subsystem or module where the error occurred. | |
308 | 281 | Whenever it makes sense, IOC routines return a status value encoded similar to the vxWorks error status encoding. The | 287 | The least significant 16 bits contain a subsystem-specific status value. |
309 | 282 | most significant short word indicates the subsystem module within which the error occurred. The low order short word is | 288 | In order that status values do not conflict with the vxWorks error status values, all subsystem numbers are greater than 500. |
310 | 283 | a subsystem status value. In order that status values do not conflict with the vxWorks error status values all subsystem | 289 | |
311 | 284 | numbers are greater than 500. | 290 | \index{errMdef.h} |
312 | 285 | 291 | A header file \verb|errMdef.h| defines macros for all the subsystem numbers. | |
313 | 286 | A file \verb|epics/share/epicsH/errMdef.h| defines each subsystem number. For example the \verb|define| for the | 292 | For example the database access routines use this module number: |
304 | 287 | database access routines is: | ||
314 | 288 | 293 | ||
315 | 289 | \begin{verbatim} | 294 | \begin{verbatim} |
318 | 290 | #define M_dbAccess (501 << 16) \ | 295 | #define M_dbAccess (501 << 16) /*Database Access Routines*/ |
317 | 291 | /*Database Access Routines*/ | ||
319 | 292 | \end{verbatim} | 296 | \end{verbatim} |
320 | 293 | 297 | ||
323 | 294 | Directory ``\verb|epics/share/epicsH|" contains an \verb|include| library for every IOC subsystem that returns standard status | 298 | There are header files for every IOC subsystem that returns standard status values. |
324 | 295 | values. The status values are encoded with lines of the following format: | 299 | The status values are encoded with lines of the following format: |
325 | 296 | 300 | ||
326 | 297 | \begin{verbatim} | 301 | \begin{verbatim} |
327 | 298 | #define S_xxxxxxx value /*string value*/ | 302 | #define S_xxxxxxx value /*string value*/ |
328 | @@ -301,8 +305,7 @@ | |||
329 | 301 | For example: | 305 | For example: |
330 | 302 | 306 | ||
331 | 303 | \begin{verbatim} | 307 | \begin{verbatim} |
334 | 304 | #define S_dbAccessBadDBR (M_dbAccess|3) \ | 308 | #define S_dbAccessBadDBR (M_dbAccess|3) /*Invalid Database Request*/ |
333 | 305 | /*Invalid Database Request*/ | ||
335 | 306 | \end{verbatim} | 309 | \end{verbatim} |
336 | 307 | 310 | ||
337 | 308 | For example, when \verb|dbGetField| detects a bad database request type, it executes the statement: | 311 | For example, when \verb|dbGetField| detects a bad database request type, it executes the statement: |
338 | @@ -314,53 +317,58 @@ | |||
339 | 314 | The calling routine checks the return status as follows: | 317 | The calling routine checks the return status as follows: |
340 | 315 | 318 | ||
341 | 316 | \begin{verbatim} | 319 | \begin{verbatim} |
343 | 317 | status = dbGetField( ...); | 320 | status = dbGetField(...); |
344 | 318 | if(status) {/* Call was not successful */ } | 321 | if(status) {/* Call was not successful */ } |
345 | 319 | \end{verbatim} | 322 | \end{verbatim} |
346 | 320 | 323 | ||
347 | 321 | \section{iocLog} | 324 | \section{iocLog} |
348 | 322 | 325 | ||
349 | 323 | \index{iocLog} | 326 | \index{iocLog} |
351 | 324 | NOTE: Many sites use CMLOG instead of iocLog. See the CMLOG documentation for details. | 327 | NOTE: Many sites use CMLOG instead of iocLog. |
352 | 328 | See the CMLOG documentation for details. | ||
353 | 325 | 329 | ||
356 | 326 | This consists of two modules: iocLogServer and iocLogClient. The client code runs on each ioc and listens for the | 330 | This consists of two modules: |
357 | 327 | messages generated locally by the errlog system. It also reports the messages from the vxWorks logMsg facility. | 331 | iocLogServer and iocLogClient. |
358 | 332 | The client code runs on each ioc and listens for the messages generated locally by the errlog system. | ||
359 | 333 | It also reports the messages from the vxWorks logMsg facility. | ||
360 | 328 | 334 | ||
361 | 329 | \subsection{iocLogServer} | 335 | \subsection{iocLogServer} |
362 | 330 | 336 | ||
363 | 331 | \index{iocLogServer} | 337 | \index{iocLogServer} |
364 | 338 | <<<<<<< TREE | ||
365 | 332 | This runs on a host. It receives messages for all enabled iocLogClients in the local area network. The messages are written | 339 | This runs on a host. It receives messages for all enabled iocLogClients in the local area network. The messages are written |
366 | 333 | to a file. Epics base provides a startup file ``base/src/libCom/log/rc2.logServer", which is a SystemV init script to start the server. | 340 | to a file. Epics base provides a startup file ``base/src/libCom/log/rc2.logServer", which is a SystemV init script to start the server. |
367 | 341 | ======= | ||
368 | 342 | This runs on a host. | ||
369 | 343 | It receives messages for all enabled iocLogClients in the local area network. | ||
370 | 344 | The messages are written to a file. | ||
371 | 345 | Epics base provides a startup file ``base/src/util/rc2.logServer", which is a SystemV init script to start the server. | ||
372 | 346 | >>>>>>> MERGE-SOURCE | ||
373 | 334 | Consult this script for details. | 347 | Consult this script for details. |
374 | 335 | 348 | ||
377 | 336 | To start a log server on a UNIX or PC workstation you must first set the following environment variables and then run the | 349 | To start a log server on a UNIX or PC workstation you must first set the following environment variables and then run the executable ``iocLogServer" on your PC or UNIX workstation. |
376 | 337 | executable ``iocLogServer" on your PC or UNIX workstation. | ||
378 | 338 | 350 | ||
379 | 339 | \begin{description} | 351 | \begin{description} |
380 | 340 | 352 | ||
382 | 341 | \item \index{EPICS\_IOC\_LOG\_FILE\_NAME}EPICS\_IOC\_LOG\_FILE\_NAME | 353 | \item \index{EPICS\_IOC\_LOG\_FILE\_NAME}EPICS\_IOC\_LOG\_FILE\_NAME |
383 | 342 | 354 | ||
384 | 343 | The name and path to the log file. | 355 | The name and path to the log file. |
385 | 344 | 356 | ||
386 | 345 | \item \index{EPICS\_IOC\_LOG\_FILE\_LIMIT}EPICS\_IOC\_LOG\_FILE\_LIMIT | 357 | \item \index{EPICS\_IOC\_LOG\_FILE\_LIMIT}EPICS\_IOC\_LOG\_FILE\_LIMIT |
387 | 346 | 358 | ||
391 | 347 | The maximum size in characters for the log file (after which it becomes a circular file and writes new | 359 | The maximum size in characters for the log file (after which it becomes a circular file and writes new messages over old messages at the beginning of the file). |
392 | 348 | messages over old messages at the beginning of the file). If the value is zero then there is no limit on the | 360 | If the value is zero then there is no limit on the size of the log file. |
390 | 349 | size of the log file. | ||
393 | 350 | 361 | ||
394 | 351 | \item \index{EPICS\_IOC\_LOG\_FILE\_COMMAND}EPICS\_IOC\_LOG\_FILE\_COMMAND | 362 | \item \index{EPICS\_IOC\_LOG\_FILE\_COMMAND}EPICS\_IOC\_LOG\_FILE\_COMMAND |
395 | 352 | 363 | ||
407 | 353 | A shell command string used to obtain the log file path name during initialization and in response to | 364 | A shell command string used to obtain the log file path name during initialization and in response to SIGHUP. |
408 | 354 | SIGHUP. The new path name will replace any path name supplied in EPICS\_IOC\_LOG\_FILE\_NAME. | 365 | The new path name will replace any path name supplied in EPICS\_IOC\_LOG\_FILE\_NAME. |
409 | 355 | 366 | ||
410 | 356 | Thus, if EPICS\_IOC\_LOG\_FILE\_NAME is | 367 | Thus, if EPICS\_IOC\_LOG\_FILE\_NAME is ``a/b/c.log" and EPICS\_IOC\_LOG\_FILE\_COMMAND returns ``A/B" or ``A/B/" the log server will be stored at ``A/B/c.log" |
411 | 357 | 368 | ||
412 | 358 | "a/b/c.log" and EPICS\_IOC\_LOG\_FILE\_COMMAND returns ``A/B" or ``A/B/" the log server will be stored | 369 | If EPICS\_IOC\_LOG\_FILE\_COMMAND is empty then this behavior is disabled. |
413 | 359 | at ``A/B/c.log" | 370 | This feature is used at some sites for switching the server to a new directory at a fixed time each day. |
414 | 360 | 371 | This variable is currently used only by the UNIX version of the log server. | |
404 | 361 | If EPICS\_IOC\_LOG\_FILE\_COMMAND is empty then this behavior is disabled. This feature is used at | ||
405 | 362 | some sites for switching the server to a new directory at a fixed time each day. This variable is currently | ||
406 | 363 | used only by the UNIX version of the log server. | ||
415 | 364 | 372 | ||
416 | 365 | \item \index{EPICS\_IOC\_LOG\_PORT}EPICS\_IOC\_LOG\_PORT | 373 | \item \index{EPICS\_IOC\_LOG\_PORT}EPICS\_IOC\_LOG\_PORT |
417 | 366 | 374 | ||
418 | @@ -368,37 +376,37 @@ | |||
419 | 368 | 376 | ||
420 | 369 | \end{description} | 377 | \end{description} |
421 | 370 | 378 | ||
425 | 371 | To configure an IOC so that its messages are placed in the log you must set the environment variable | 379 | To configure an IOC so that its messages are placed in the log you must set the environment variable EPICS\_IOC\_LOG\_INET to the IP address of the host that is running the log server, and EPICS\_IOC\_LOG\_PORT to the TCP/IP port used by the log server. |
423 | 372 | EPICS\_IOC\_LOG\_INET to the IP address of the host that is running the log server, and EPICS\_IOC\_LOG\_PORT to the | ||
424 | 373 | TCP/IP port used by the log server. | ||
426 | 374 | 380 | ||
429 | 375 | Defaults for all of the above parameters are specified in the files \$(EPICS\_BASE)/config/CONFIG\_SITE\_ENV and | 381 | Defaults for all of the above parameters are specified in the files \$(EPICS\_BASE)/config/CONFIG\_SITE\_ENV and \$(EPICS\_BASE)/config/CONFIG\_ENV. |
428 | 376 | \$(EPICS\_BASE)/config/CONFIG\_ENV. | ||
430 | 377 | 382 | ||
431 | 378 | \subsection{iocLogClient} | 383 | \subsection{iocLogClient} |
432 | 379 | \label{iocLogClient} | 384 | \label{iocLogClient} |
433 | 380 | 385 | ||
434 | 381 | \index{iocLogClient} | 386 | \index{iocLogClient} |
436 | 382 | This runs on each ioc. It is started by calling: | 387 | This runs on each ioc. |
437 | 388 | It is started by calling: | ||
438 | 383 | 389 | ||
439 | 384 | \begin{verbatim} | 390 | \begin{verbatim} |
440 | 385 | iocLogInit(); | 391 | iocLogInit(); |
441 | 386 | \end{verbatim} | 392 | \end{verbatim} |
442 | 387 | 393 | ||
447 | 388 | The global variable \verb|iocLogDisable| can be used to enable/disable the messages from being sent to the server. Setting | 394 | The global variable \verb|iocLogDisable| can be used to enable/disable the messages from being sent to the server. |
448 | 389 | this variable to (0,1) (enables,disables) the messages generation. If \verb|iocLogDisable| is set to 1 before calling | 395 | Setting this variable to (0,1) (enables, disables) the messages generation. |
449 | 390 | \verb|iocLogInit| then \verb|iocLogClient| will not even initialize itself. \verb|iocLogDisable| can also be changed to turn | 396 | If \verb|iocLogDisable| is set to 1 before calling \verb|iocLogInit| then \verb|iocLogClient| will not even initialize itself. |
450 | 391 | logging on or off. | 397 | \verb|iocLogDisable| can also be changed to turn logging on or off. |
451 | 392 | 398 | ||
452 | 393 | \verb|iocLogClient| calls \verb|errlogAddListener| and sends each message to the \verb|iocLogServer|. | 399 | \verb|iocLogClient| calls \verb|errlogAddListener| and sends each message to the \verb|iocLogServer|. |
453 | 394 | 400 | ||
454 | 395 | \subsection{Configuring a Private Log Server} | 401 | \subsection{Configuring a Private Log Server} |
455 | 396 | 402 | ||
457 | 397 | In a testing environment it is desirable to use a private log server. This can be done as follows: | 403 | In a testing environment it is desirable to use a private log server. |
458 | 404 | This can be done as follows: | ||
459 | 398 | 405 | ||
460 | 399 | \begin{itemize} | 406 | \begin{itemize} |
461 | 400 | 407 | ||
463 | 401 | \item Add a epicsEnvSet command to your IOC startup file. For example | 408 | \item Add a epicsEnvSet command to your IOC startup file. |
464 | 409 | For example | ||
465 | 402 | 410 | ||
466 | 403 | \begin{verbatim} | 411 | \begin{verbatim} |
467 | 404 | ld < iocCore | 412 | ld < iocCore |
468 | 405 | 413 | ||
469 | === modified file 'tex/libCom.tex' | |||
470 | --- tex/libCom.tex 2010-11-15 18:16:16 +0000 | |||
471 | +++ tex/libCom.tex 2012-01-06 20:56:29 +0000 | |||
472 | @@ -1561,7 +1561,7 @@ | |||
473 | 1561 | program's main() routine. | 1561 | program's main() routine. |
474 | 1562 | 1562 | ||
475 | 1563 | On vxWorks and RTEMS, an alternative test harness can be used to run a series of tests in order and summarize the results | 1563 | On vxWorks and RTEMS, an alternative test harness can be used to run a series of tests in order and summarize the results |
477 | 1564 | from them all at the end just like the Perl harness does. The routine testHarness() is called once a the beginning of the test | 1564 | from them all at the end just like the Perl harness does. The routine testHarness() is called once at the beginning of the test |
478 | 1565 | harness program. Each test program is run by passing its main routine name to the runTest() macro which expands into a | 1565 | harness program. Each test program is run by passing its main routine name to the runTest() macro which expands into a |
479 | 1566 | call to the runTestFunc() routine. The last test program or the harness program itself must finish by calling epicsExit() | 1566 | call to the runTestFunc() routine. The last test program or the harness program itself must finish by calling epicsExit() |
480 | 1567 | which triggers the test summary mechanism to generate its result outputs (from an epicsAtExit callback routine). | 1567 | which triggers the test summary mechanism to generate its result outputs (from an epicsAtExit callback routine). |
481 | 1568 | 1568 | ||
482 | === modified file 'tex/recordSupport.tex' | |||
483 | --- tex/recordSupport.tex 2010-11-15 18:16:16 +0000 | |||
484 | +++ tex/recordSupport.tex 2012-01-06 20:56:29 +0000 | |||
485 | @@ -3,35 +3,37 @@ | |||
486 | 3 | 3 | ||
487 | 4 | \section{Overview} | 4 | \section{Overview} |
488 | 5 | 5 | ||
512 | 6 | The purpose of this chapter is to describe record support in sufficient detail such that a C programmer can write new | 6 | The purpose of this chapter is to describe record support in sufficient detail such that a C programmer can write new record support modules. |
513 | 7 | record support modules. Before attempting to write new support modules, you should carefully study a few of the existing | 7 | Before attempting to write new support modules, you should carefully study a few of the existing support modules. |
514 | 8 | support modules. If an existing support module is similar to the desired module most of the work will already be done. | 8 | If an existing support module is similar to the desired module most of the work will already be done. |
515 | 9 | 9 | ||
516 | 10 | From previous chapters, it should be clear that many things happen as a result of record processing. The details of what | 10 | From previous chapters, it should be clear that many things happen as a result of record processing. |
517 | 11 | happens are dependent on the record type. In order to allow new record types and new device types without impacting the | 11 | The details of what happens are dependent on the record type. |
518 | 12 | core IOC system, the concept of record support and device support has been created. For each record type, a record | 12 | In order to allow new record types and new device types without impacting the core IOC system, the concept of record support and device support is used. |
519 | 13 | support module exists. It is responsible for all record specific details. In order to allow a record support module to be | 13 | For each record type, a record support module exists. |
520 | 14 | independent of device specific details, the concept of device support has been created. | 14 | It is responsible for all record specific details. |
521 | 15 | 15 | In order to allow a record support module to be independent of device specific details, the concept of device support has been created. | |
522 | 16 | A record support module consists of a standard set of routines which are called by database access routines. These | 16 | |
523 | 17 | routines implement record specific code. Each record type can define a standard set of device support routines specific to | 17 | A record support module consists of a standard set of routines which are called by database access routines. |
524 | 18 | that record type. | 18 | These routines implement record specific code. |
525 | 19 | 19 | Each record type can define a standard set of device support routines specific to that record type. | |
526 | 20 | By far the most important record support routine is \verb|process|, which \verb|dbProcess| calls when it wants to process a record. | 20 | |
527 | 21 | This routine is responsible for the details of record processing. In many cases it calls a device support I/O routine. The | 21 | By far the most important record support routine is \verb|process|, which \verb|dbProcess| calls when it wants to process a record. |
528 | 22 | next section gives an overview of what must be done in order to process a record. Next is a description of the entry tables | 22 | This routine is responsible for the details of record processing. |
529 | 23 | that must be provided by record and device support modules. The remaining sections give example record and device | 23 | In many cases it calls a device support I/O routine. |
530 | 24 | support modules and describe some global routines useful to record support modules. | 24 | The next section gives an overview of what must be done in order to process a record. |
531 | 25 | 25 | Next is a description of the entry tables that must be provided by record and device support modules. | |
532 | 26 | The record and device support modules are the only modules that are allowed to include the record specific include files | 26 | The remaining sections give example record and device support modules and describe some global routines useful to record support modules. |
533 | 27 | as defined in \verb|base/rec|. Thus they are the only routines that access record specific fields without going through database | 27 | |
534 | 28 | access. | 28 | The record and its device support modules are the only source files that should include the record specific header files. |
535 | 29 | Thus they will be the only routines that access record specific fields without going through database access. | ||
536 | 29 | 30 | ||
537 | 30 | \section{Overview of Record Processing} | 31 | \section{Overview of Record Processing} |
538 | 31 | 32 | ||
539 | 32 | \index{Overview of Record Processing} | 33 | \index{Overview of Record Processing} |
542 | 33 | The most important record support routine is \verb|process|. This routine determines what record processing means. Before | 34 | The most important record support routine is \verb|process|. |
543 | 34 | the record specific ``\verb|process|" routine is called, the following has already been done: | 35 | This routine determines what record processing means. |
544 | 36 | Before the record specific ``\verb|process|" routine is called, the following has already been done: | ||
545 | 35 | 37 | ||
546 | 36 | \begin{itemize} | 38 | \begin{itemize} |
547 | 37 | \item Decision to process a record. | 39 | \item Decision to process a record. |
548 | @@ -57,11 +59,12 @@ | |||
549 | 57 | 59 | ||
550 | 58 | \end{itemize} | 60 | \end{itemize} |
551 | 59 | 61 | ||
554 | 60 | A complication of record processing is that some devices are intrinsically asynchronous. It is NEVER permissible to wait | 62 | A complication of record processing is that some devices are intrinsically asynchronous. |
555 | 61 | for a slow device to complete. Asynchronous records perform the following steps: | 63 | It is NEVER permissible to wait for a slow device to complete. |
556 | 64 | Asynchronous records perform the following steps: | ||
557 | 62 | 65 | ||
558 | 63 | \begin{enumerate} | 66 | \begin{enumerate} |
560 | 64 | \item Initiate the I/O operation and set \verb|pact| \verb|TRUE| | 67 | \item Initiate the I/O operation and set \verb|pact = TRUE| |
561 | 65 | 68 | ||
562 | 66 | \item Determine a method for again calling process when the operation completes | 69 | \item Determine a method for again calling process when the operation completes |
563 | 67 | 70 | ||
564 | @@ -69,7 +72,7 @@ | |||
565 | 69 | 72 | ||
566 | 70 | \item When process is called after the I/O operation complete record processing | 73 | \item When process is called after the I/O operation complete record processing |
567 | 71 | 74 | ||
569 | 72 | \item Set \verb|pact| \verb|FALSE| and return | 75 | \item Set \verb|pact = FALSE| and return |
570 | 73 | 76 | ||
571 | 74 | \end{enumerate} | 77 | \end{enumerate} |
572 | 75 | 78 | ||
573 | @@ -77,35 +80,36 @@ | |||
574 | 77 | 80 | ||
575 | 78 | \section{Record Support and Device Support Entry Tables} | 81 | \section{Record Support and Device Support Entry Tables} |
576 | 79 | 82 | ||
589 | 80 | Each record type has an associated set of record support routines. These routines are located via the data structures | 83 | Each record type has an associated set of record support routines. |
590 | 81 | defined in \verb|epics/share/epicsH/recSup.h|. The concept of record support routines isolates the \verb|iocCore| software | 84 | These routines are located via the \verb|struct rset| data structure declared in \verb|recSup.h| and defined by the specific record type. |
591 | 82 | from the details of each record type. Thus new records can be defined and supported without affecting the IOC core | 85 | This use of a record support vector table isolates the \verb|iocCore| software from the implementation details of each record type. |
592 | 83 | software. | 86 | Thus new record types can be defined without having to modify the IOC core software. |
593 | 84 | 87 | ||
594 | 85 | Each record type also has zero or more sets of device support routines. Record types without associated hardware, e.g. | 88 | Each record type also has zero or more sets of device support routines. |
595 | 86 | calculation records, normally do not have any associated device support. Record types with associated hardware normally | 89 | Record types without associated hardware, e.g. calculation records, normally do not have any associated device support. |
596 | 87 | have a device support module for each device type. The concept of device support isolates IOC core software and even | 90 | Record types with associated hardware normally have a device support module for each device type. |
597 | 88 | record support from device specific details. | 91 | The concept of device support isolates IOC core software and even record support from device specific details. |
598 | 89 | 92 | ||
599 | 90 | Corresponding to each record type is a set of record support routines. The set of routines is the same for every record type. | 93 | Corresponding to each record type is a set of record support routines. |
600 | 91 | These routines are located via a Record Support Entry Table (\index{RSET}\index{Record Support Entry Table}RSET), which has the following structure | 94 | The set of routines is the same for every record type. |
601 | 95 | These routines are located via a Record Support Entry Table (\index{RSET}\index{Record Support Entry Table}RSET), which has the following structure: | ||
602 | 92 | 96 | ||
603 | 93 | \begin{verbatim} | 97 | \begin{verbatim} |
613 | 94 | rset { /* record support entry table */ | 98 | struct rset { /* record support entry table */ |
614 | 95 | long number; /* number of support routine */ | 99 | long number; /* number of support routine */ |
615 | 96 | RECSUPFUN report; /* print report */ | 100 | RECSUPFUN report; /* print report */ |
616 | 97 | RECSUPFUN init; /* init support */ | 101 | RECSUPFUN init; /* init support */ |
617 | 98 | RECSUPFUN init_record; /* init record */ | 102 | RECSUPFUN init_record; /* init record */ |
618 | 99 | RECSUPFUN process; /* process record */ | 103 | RECSUPFUN process; /* process record */ |
619 | 100 | RECSUPFUN special; /* special processing */ | 104 | RECSUPFUN special; /* special processing */ |
620 | 101 | RECSUPFUN get_value; /* OBSOLETE: Just leave NULL */ | 105 | RECSUPFUN get_value; /* OBSOLETE: Just leave NULL */ |
621 | 102 | RECSUPFUN cvt_dbaddr; /* cvt dbAddr */ | 106 | RECSUPFUN cvt_dbaddr; /* cvt dbAddr */ |
622 | 103 | RECSUPFUN get_array_info; | 107 | RECSUPFUN get_array_info; |
623 | 104 | RECSUPFUN put_array_info; | 108 | RECSUPFUN put_array_info; |
624 | 105 | RECSUPFUN get_units; | 109 | RECSUPFUN get_units; |
625 | 106 | RECSUPFUN get_precision; | 110 | RECSUPFUN get_precision; |
626 | 107 | RECSUPFUN get_enum_str; /* get string from enum */ | 111 | RECSUPFUN get_enum_str; /* get string from enum */ |
628 | 108 | RECSUPFUN get_enum_strs; /* get all enum strings */ | 112 | RECSUPFUN get_enum_strs; /* get all enum strings */ |
629 | 109 | RECSUPFUN put_enum_str; /* put enum from string */ | 113 | RECSUPFUN put_enum_str; /* put enum from string */ |
630 | 110 | RECSUPFUN get_graphic_double; | 114 | RECSUPFUN get_graphic_double; |
631 | 111 | RECSUPFUN get_control_double; | 115 | RECSUPFUN get_control_double; |
632 | @@ -119,35 +123,36 @@ | |||
633 | 119 | <record_type>RSET | 123 | <record_type>RSET |
634 | 120 | \end{verbatim} | 124 | \end{verbatim} |
635 | 121 | 125 | ||
638 | 122 | Any routines not needed for the particular record type should be initialized to the value \verb|NULL|. Look at the example below | 126 | Any routines not needed for the particular record type should be initialized to the value \verb|NULL|. |
639 | 123 | for details. | 127 | Look at the example below for details. |
640 | 124 | 128 | ||
641 | 125 | Device support routines are located via a Device Support Entry Table (\index{DSET}\index{Device Support Entry Table}DSET), which has the following structure: | 129 | Device support routines are located via a Device Support Entry Table (\index{DSET}\index{Device Support Entry Table}DSET), which has the following structure: |
642 | 126 | 130 | ||
643 | 127 | \begin{verbatim} | 131 | \begin{verbatim} |
644 | 128 | struct dset { /* device support entry table */ | 132 | struct dset { /* device support entry table */ |
648 | 129 | long number; /* number of support routines */ | 133 | long number; /* number of support routines */ |
649 | 130 | DEVSUPFUN report; /* print report */ | 134 | DEVSUPFUN report; /* print report */ |
650 | 131 | DEVSUPFUN init; /* init support */ | 135 | DEVSUPFUN init; /* init support */ |
651 | 132 | DEVSUPFUN init_record;/* init record instance*/ | 136 | DEVSUPFUN init_record;/* init record instance*/ |
652 | 133 | DEVSUPFUN get_ioint_info; /* get io interrupt info*/ | 137 | DEVSUPFUN get_ioint_info; /* get io interrupt info*/ |
653 | 134 | /* other functions are record dependent*/ | 138 | /* other functions are record dependent*/ |
654 | 135 | }; | 139 | }; |
655 | 136 | \end{verbatim} | 140 | \end{verbatim} |
656 | 137 | 141 | ||
659 | 138 | Each device support module must define its associated DSET. The external name must be the same as the name which | 142 | Each device support module must define its associated DSET. |
660 | 139 | appears in \verb|devSup.ascii|. | 143 | The external name must be the same as the name which appears in \verb|devSup.ascii|. |
661 | 140 | 144 | ||
665 | 141 | Any record support module which has associated device support must also include definitions for accessing its associated | 145 | Any record support module which has associated device support must also include definitions for accessing its associated device support modules. |
666 | 142 | device support modules. The field"\verb|dset|", which is located in \verb|dbCommon|, contains the address of the DSET. It is given a | 146 | The field \verb|dset|, which is declared in \verb|dbCommon|, contains the address of the DSET. |
667 | 143 | value by \verb|iocInit|. | 147 | It is given a value by \verb|iocInit|. |
668 | 144 | 148 | ||
669 | 145 | \section{Example Record Support Module} | 149 | \section{Example Record Support Module} |
670 | 146 | 150 | ||
675 | 147 | This section contains the skeleton of a record support package. The record type is \verb|xxx| and the record has the following | 151 | This section contains the skeleton of a record support package. |
676 | 148 | fields in addition to the \verb|dbCommon| fields: \verb|VAL|, \verb|PREC|, \verb|EGU|, \verb|HOPR|, \verb|LOPR|, \verb|HIHI|, \verb|LOLO|, \verb|HIGH|, \verb|LOW|, \verb|HHSV|, \verb|LLSV|, \verb|HSV|, | 152 | The record type is \verb|xxx| and the record has the following fields in addition to the \verb|dbCommon| fields: |
677 | 149 | \verb|LSV|, \verb|HYST|, \verb|ADEL|, \verb|MDEL|, \verb|LALM|, \verb|ALST|, \verb|MLST|. These fields will have the same meaning as they have for the \verb|ai| record. | 153 | \verb|VAL|, \verb|PREC|, \verb|EGU|, \verb|HOPR|, \verb|LOPR|, \verb|HIHI|, \verb|LOLO|, \verb|HIGH|, \verb|LOW|, \verb|HHSV|, \verb|LLSV|, \verb|HSV|, \verb|LSV|, \verb|HYST|, \verb|ADEL|, \verb|MDEL|, \verb|LALM|, \verb|ALST|, \verb|MLST|. |
678 | 150 | Consult the Record Reference manual for a description. | 154 | These fields will have the same meaning as they have for the \verb|ai| record. |
679 | 155 | Consult the Record Reference manual for a description. | ||
680 | 151 | 156 | ||
681 | 152 | \subsection{Declarations} | 157 | \subsection{Declarations} |
682 | 153 | 158 | ||
683 | @@ -208,14 +213,12 @@ | |||
684 | 208 | static void monitor(xxxRecord *pxxx); | 213 | static void monitor(xxxRecord *pxxx); |
685 | 209 | \end{verbatim} | 214 | \end{verbatim} |
686 | 210 | 215 | ||
695 | 211 | \index{RSET - example}The above declarations define the Record Support Entry Table (RSET), a template for the associated Device Support | 216 | \index{RSET - example}The above declarations define the Record Support Entry Table (RSET), a template for the associated Device Support Entry Table (DSET), and forward declarations to private routines. |
696 | 212 | Entry Table (DSET), and forward declarations to private routines. | 217 | |
697 | 213 | 218 | The RSET must be declared with an external name of \verb|xxxRSET|. It defines the record support routines supplied for this record type. | |
698 | 214 | The RSET must be declared with an external name of \verb|xxxRSET|. It defines the record support routines supplied for this | 219 | Note that forward declarations are given for all routines supported and a \verb|NULL| declaration for any routine not supported. |
699 | 215 | record type. Note that forward declarations are given for all routines supported and a \verb|NULL| declaration for any routine not | 220 | |
700 | 216 | supported. | 221 | The template for the DSET is declared for use by this module. |
693 | 217 | |||
694 | 218 | The template for the DSET is declared for use by this module. | ||
701 | 219 | 222 | ||
702 | 220 | \subsection{init\_record} | 223 | \subsection{init\_record} |
703 | 221 | 224 | ||
704 | @@ -246,16 +249,16 @@ | |||
705 | 246 | } | 249 | } |
706 | 247 | \end{verbatim} | 250 | \end{verbatim} |
707 | 248 | 251 | ||
710 | 249 | This routine, which is called by \verb|iocInit| twice for each record of type \verb|xxx|, checks to see if it has a proper set of device | 252 | This routine, which is called by \verb|iocInit| twice for each record of type \verb|xxx|, checks to see if it has a proper set of device support routines and, if present, calls the \verb|init_record| entry of the DSET. |
709 | 250 | support routines and, if present, calls the \verb|init_record| entry of the DSET. | ||
711 | 251 | 253 | ||
719 | 252 | During the first call to \verb|init_record| (pass=0) only initializations relating to this record can be performed. During the | 254 | During the first call to \verb|init_record| (pass=0) only initializations relating to this record can be performed. |
720 | 253 | second call (pass=1) initializations that may refer to other records can be performed. Note also that during the second | 255 | During the second call (pass=1) initializations that may refer to other records can be performed. |
721 | 254 | pass, other records may refer to fields within this record. A good example of where these rules are important is a | 256 | Note also that during the second pass, other records may refer to fields within this record. |
722 | 255 | waveform record. The \verb|VAL| field of a waveform record actually refers to an array. The waveform record support module | 257 | A good example of where these rules are important is a waveform record. |
723 | 256 | must allocate storage for the array. If another record has a database link referring to the waveform \verb|VAL| field then the | 258 | The \verb|VAL| field of a waveform record actually refers to an array. |
724 | 257 | storage must be allocated before the link is resolved. This is accomplished by having the waveform record support | 259 | The waveform record support module must allocate storage for the array. |
725 | 258 | allocate the array during the first pass (pass=0) and having the link reference resolved during the second pass (pass=1). | 260 | If another record has a database link referring to the waveform \verb|VAL| field then the storage must be allocated before the link is resolved. |
726 | 261 | This is accomplished by having the waveform record support allocate the array during the first pass (pass=0) and having the link reference resolved during the second pass (pass=1). | ||
727 | 259 | 262 | ||
728 | 260 | \subsection{process} | 263 | \subsection{process} |
729 | 261 | 264 | ||
730 | @@ -294,18 +297,20 @@ | |||
731 | 294 | } | 297 | } |
732 | 295 | \end{verbatim} | 298 | \end{verbatim} |
733 | 296 | 299 | ||
738 | 297 | The record processing routines are the heart of the IOC software. The record specific process routine is called by | 300 | The record processing routines are the heart of the IOC software. |
739 | 298 | \verb|dbProcess| whenever it decides that a record should be processed. Process decides what record processing really means. | 301 | The record specific process routine is called by \verb|dbProcess| whenever it decides that a record should be processed. |
740 | 299 | The above is a good example of what should be done. In addition to being called by \verb|dbProcess| the process routine may | 302 | Process decides what record processing really means. |
741 | 300 | also be called by asynchronous record completion routines. | 303 | The above is a good example of what should be done. |
742 | 304 | In addition to being called by \verb|dbProcess| the process routine may also be called by asynchronous record completion routines. | ||
743 | 301 | 305 | ||
746 | 302 | The above model supports both synchronous and asynchronous device support routines. For example, if \verb|read_xxx| is an | 306 | The above model supports both synchronous and asynchronous device support routines. |
747 | 303 | asynchronous routine, the following sequence of events will occur: | 307 | For example, if \verb|read_xxx| is an asynchronous routine, the following sequence of events will occur: |
748 | 304 | 308 | ||
749 | 305 | \begin{itemize} | 309 | \begin{itemize} |
750 | 306 | \item \verb|process| is called with \verb|pact| \verb|FALSE| | 310 | \item \verb|process| is called with \verb|pact| \verb|FALSE| |
751 | 307 | 311 | ||
753 | 308 | \item \verb|read_xxx| is called. Since \verb|pact| is \verb|FALSE| it starts I/O, arranges callback, and sets \verb|pact| \verb|TRUE| | 312 | \item \verb|read_xxx| is called. |
754 | 313 | Since \verb|pact| is \verb|FALSE| it starts I/O, arranges callback, and sets \verb|pact| \verb|TRUE| | ||
755 | 309 | 314 | ||
756 | 310 | \item \verb|read_xxx| returns | 315 | \item \verb|read_xxx| returns |
757 | 311 | 316 | ||
758 | @@ -315,7 +320,8 @@ | |||
759 | 315 | 320 | ||
760 | 316 | \item Sometime later the callback occurs and \verb|process| is called again. | 321 | \item Sometime later the callback occurs and \verb|process| is called again. |
761 | 317 | 322 | ||
763 | 318 | \item \verb|read_xxx| is called. Since \verb|pact| is \verb|TRUE| it knows that it is a completion request. | 323 | \item \verb|read_xxx| is called. |
764 | 324 | Since \verb|pact| is \verb|TRUE| it knows that it is a completion request. | ||
765 | 319 | 325 | ||
766 | 320 | \item \verb|read_xxx| returns | 326 | \item \verb|read_xxx| returns |
767 | 321 | 327 | ||
768 | @@ -327,8 +333,8 @@ | |||
769 | 327 | 333 | ||
770 | 328 | \end{itemize} | 334 | \end{itemize} |
771 | 329 | 335 | ||
774 | 330 | At this point the record has been completely processed. The next time \verb|process| is called everything starts all over from | 336 | At this point the record has been completely processed. |
775 | 331 | the beginning. | 337 | The next time \verb|process| is called everything starts all over from the beginning. |
776 | 332 | 338 | ||
777 | 333 | \subsection{Miscellaneous Utility Routines} | 339 | \subsection{Miscellaneous Utility Routines} |
778 | 334 | 340 | ||
779 | @@ -359,8 +365,8 @@ | |||
780 | 359 | 365 | ||
781 | 360 | \index{get\_units - .example} | 366 | \index{get\_units - .example} |
782 | 361 | \index{get\_graphic\_double - example} | 367 | \index{get\_graphic\_double - example} |
785 | 362 | These are a few examples of various routines supplied by a typical record support package. The functions that must be | 368 | These are a few examples of various routines supplied by a typical record support package. |
786 | 363 | performed by the remaining routines are described in the next section. | 369 | The functions that must be performed by the remaining routines are described in the next section. |
787 | 364 | 370 | ||
788 | 365 | \subsection{Alarm Processing} | 371 | \subsection{Alarm Processing} |
789 | 366 | 372 | ||
790 | @@ -416,13 +422,14 @@ | |||
791 | 416 | } | 422 | } |
792 | 417 | \end{verbatim} | 423 | \end{verbatim} |
793 | 418 | 424 | ||
797 | 419 | \index{checkAlarms}This is a typical set of code for checking alarms conditions for an analog type record. The actual set of code can be very | 425 | \index{checkAlarms}This is a typical set of code for checking alarms conditions for an analog type record. |
798 | 420 | record specific. Note also that other parts of the system can raise alarms. The algorithm is to always maximize alarm | 426 | The actual set of code can be very record specific. |
799 | 421 | severity, i.e. the highest severity outstanding alarm will be reported. | 427 | Note also that other parts of the system can raise alarms. |
800 | 428 | The algorithm is to always maximize alarm severity, i.e. the highest severity outstanding alarm will be reported. | ||
801 | 422 | 429 | ||
805 | 423 | The above algorithm also honors a hysteresis factor for the alarm. This is to prevent alarm storms from occurring in the | 430 | The above algorithm also honors a hysteresis factor for the alarm. |
806 | 424 | event that the current value is very near an alarm limit and noise makes it continually cross the limit. It honors the | 431 | This is to prevent alarm storms from occurring in the event that the current value is very near an alarm limit and noise makes it continually cross the limit. |
807 | 425 | hysteresis only when the value is going to a lower alarm severity. | 432 | It honors the hysteresis only when the value is going to a lower alarm severity. |
808 | 426 | 433 | ||
809 | 427 | Note the test: | 434 | Note the test: |
810 | 428 | 435 | ||
811 | @@ -433,30 +440,32 @@ | |||
812 | 433 | } | 440 | } |
813 | 434 | \end{verbatim} | 441 | \end{verbatim} |
814 | 435 | 442 | ||
834 | 436 | \index{udf}Database common defines the field \index{UDF}UDF, which means that field VAL is undefined. The STAT and SEVR fields are | 443 | \index{udf}Database common defines the field \index{UDF}UDF, which means that field VAL is undefined. |
835 | 437 | initialized as though \verb|recGblSetSevr(pxxx,UDF_ALARM,VALID_ALARM)|was called. Thus if the record is never | 444 | The STAT and SEVR fields are initialized as though \verb|recGblSetSevr(pxxx,UDF_ALARM,VALID_ALARM)|was called. |
836 | 438 | processed the record will be in an INVALID UNDEFINED alarm state. Field UDF is initialized to the value 1, i.e. TRUE. | 445 | Thus if the record is never processed the record will be in an INVALID UNDEFINED alarm state. |
837 | 439 | Thus the above code will keep the record in the INVALID UNDEFINED alarm state as long as UDF is not given the | 446 | Field UDF is initialized to the value 1, i.e. TRUE. |
838 | 440 | value 0. | 447 | Thus the above code will keep the record in the INVALID UNDEFINED alarm state as long as UDF is not given the value 0. |
839 | 441 | 448 | ||
840 | 442 | The UDF field means Undefined, i.e. the VAL field has never been given a value. When records are loaded into an ioc this | 449 | The UDF field means Undefined, i.e. the VAL field has never been given a value. |
841 | 443 | is the initial state of records. Whevever code gives a value to the VAL field it is also supposed to set UDF false. Unless a | 450 | When records are loaded into an ioc this is the initial state of records. |
842 | 444 | particular record type has unusual semantics no code should set UDF true. UDF normally means that the field was never | 451 | Whevever code gives a value to the VAL field it is also supposed to set UDF false. |
843 | 445 | given a value. | 452 | Unless a particular record type has unusual semantics no code should set UDF true. |
844 | 446 | 453 | UDF normally means that the field was never given a value. | |
845 | 447 | For input records device support is responsible for obtaining an input value. If no input value can be obtained neither | 454 | |
846 | 448 | record support nor device support sets UDF false. If device support reads a raw value it returns a value telling record | 455 | For input records device support is responsible for obtaining an input value. |
847 | 449 | support to perform a conversion. After the record support sets VAL equal to the converted value, it sets UDF false. If | 456 | If no input value can be obtained neither record support nor device support sets UDF false. |
848 | 450 | device support obtains a converted value that it writes to VAL, it sets UDF false. | 457 | If device support reads a raw value it returns a value telling record support to perform a conversion. |
849 | 451 | 458 | After the record support sets VAL equal to the converted value, it sets UDF false. | |
850 | 452 | For output records either something outside record/device support writes to the VAL field or else VAL is given a value | 459 | If device support obtains a converted value that it writes to VAL, it sets UDF false. |
851 | 453 | because record support obtains a value via the OMSL field. In either case the code that writes to the VAL field sets UDF | 460 | |
852 | 454 | false. | 461 | For output records either something outside record/device support writes to the VAL field or else VAL is given a value because record support obtains a value via the OMSL field. |
853 | 462 | In either case the code that writes to the VAL field sets UDF false. | ||
854 | 455 | 463 | ||
855 | 456 | Whenever database access writes to the VAL field it sets UDF false. | 464 | Whenever database access writes to the VAL field it sets UDF false. |
856 | 457 | 465 | ||
859 | 458 | Routine recGblSetSevr is called to raise alarms. It can be called by iocCore, record support, or device support. The code | 466 | Routine recGblSetSevr is called to raise alarms. |
860 | 459 | that detects an alarm is responsible for raising the alarm. | 467 | It can be called by iocCore, record support, or device support. |
861 | 468 | The code that detects an alarm is responsible for raising the alarm. | ||
862 | 460 | 469 | ||
863 | 461 | \subsection{Raising Monitors} | 470 | \subsection{Raising Monitors} |
864 | 462 | 471 | ||
865 | @@ -493,14 +502,16 @@ | |||
866 | 493 | } | 502 | } |
867 | 494 | \end{verbatim} | 503 | \end{verbatim} |
868 | 495 | 504 | ||
873 | 496 | \index{monitor - example}All record types should call \verb|recGblResetAlarms| as shown. Note that \verb|nsta| and \verb|nsev| will have the value 0 after this | 505 | \index{monitor - example}All record types should call \verb|recGblResetAlarms| as shown. |
874 | 497 | routine completes. This is necessary to ensure that alarm checking starts fresh after processing completes. The code also | 506 | Note that \verb|nsta| and \verb|nsev| will have the value 0 after this routine completes. |
875 | 498 | takes care of raising alarm monitors when a record changes from an alarm state to the no alarm state. It is essential that | 507 | This is necessary to ensure that alarm checking starts fresh after processing completes. |
876 | 499 | record support routines follow the above model or else alarm processing will not follow the rules. | 508 | The code also takes care of raising alarm monitors when a record changes from an alarm state to the no alarm state. |
877 | 509 | It is essential that record support routines follow the above model or else alarm processing will not follow the rules. | ||
878 | 500 | 510 | ||
879 | 501 | Analog type records should also provide monitor and archive hysteresis fields as shown by this example. | 511 | Analog type records should also provide monitor and archive hysteresis fields as shown by this example. |
880 | 502 | 512 | ||
882 | 503 | \verb|db_post_events| results in channel access issuing monitors for clients attached to the record and field. The call is | 513 | \verb|db_post_events| results in channel access issuing monitors for clients attached to the record and field. |
883 | 514 | The call is | ||
884 | 504 | 515 | ||
885 | 505 | \begin{verbatim} | 516 | \begin{verbatim} |
886 | 506 | int db_post_events(void *precord, void *pfield, | 517 | int db_post_events(void *precord, void *pfield, |
887 | @@ -517,7 +528,8 @@ | |||
888 | 517 | 528 | ||
889 | 518 | \begin{description} | 529 | \begin{description} |
890 | 519 | 530 | ||
892 | 520 | \item \index{DBE\_ALARM}DBE\_ALARM - A change of alarm state has occured. This is set by \verb|recGblResetAlarms|. | 531 | \item \index{DBE\_ALARM}DBE\_ALARM - A change of alarm state has occured. |
893 | 532 | This is set by \verb|recGblResetAlarms|. | ||
894 | 521 | 533 | ||
895 | 522 | \item \index{DBE\_LOG}DBE\_LOG - Archive change of state. | 534 | \item \index{DBE\_LOG}DBE\_LOG - Archive change of state. |
896 | 523 | 535 | ||
897 | @@ -526,13 +538,14 @@ | |||
898 | 526 | \end{description} | 538 | \end{description} |
899 | 527 | 539 | ||
900 | 528 | \end{description} | 540 | \end{description} |
903 | 529 | IMPORTANT: The record support module is responsible for calling \verb|db_post_event| for any fields that change as a | 541 | IMPORTANT: |
904 | 530 | result of record processing. Also it should NOT call \verb|db_post_event| for fields that do not change. | 542 | The record support module is responsible for calling \verb|db_post_event| for any fields that change as a result of record processing. |
905 | 543 | Also it should NOT call \verb|db_post_event| for fields that do not change. | ||
906 | 531 | 544 | ||
907 | 532 | \section{Record Support Routines} | 545 | \section{Record Support Routines} |
908 | 533 | 546 | ||
911 | 534 | This section describes the routines defined in the RSET. Any routine that does not apply to a specific record type must be | 547 | This section describes the routines defined in the RSET. |
912 | 535 | declared \verb|NULL|. | 548 | Any routine that does not apply to a specific record type must be declared \verb|NULL|. |
913 | 536 | 549 | ||
914 | 537 | \subsection{Generate Report of Each Field in Record} | 550 | \subsection{Generate Report of Each Field in Record} |
915 | 538 | 551 | ||
916 | @@ -540,7 +553,8 @@ | |||
917 | 540 | report(void *precord); /* addr of record*/ | 553 | report(void *precord); /* addr of record*/ |
918 | 541 | \end{verbatim} | 554 | \end{verbatim} |
919 | 542 | 555 | ||
921 | 543 | \index{report - Record Support Routine}This routine is not used by most record types. Any action is record type specific. | 556 | \index{report - Record Support Routine}This routine is not used by most record types. |
922 | 557 | Any action is record type specific. | ||
923 | 544 | 558 | ||
924 | 545 | \subsection{Initialize Record Processing} | 559 | \subsection{Initialize Record Processing} |
925 | 546 | 560 | ||
926 | @@ -548,8 +562,9 @@ | |||
927 | 548 | initialize(void); | 562 | initialize(void); |
928 | 549 | \end{verbatim} | 563 | \end{verbatim} |
929 | 550 | 564 | ||
932 | 551 | \index{init - Record Support Routine}This routine is called once at IOC initialization time. Any action is record type specific. Most record types do not need | 565 | \index{init - Record Support Routine}This routine is called once at IOC initialization time. |
933 | 552 | this routine. | 566 | Any action is record type specific. |
934 | 567 | Most record types do not need this routine. | ||
935 | 553 | 568 | ||
936 | 554 | \subsection{Initialize Specific Record} | 569 | \subsection{Initialize Specific Record} |
937 | 555 | 570 | ||
938 | @@ -559,15 +574,15 @@ | |||
939 | 559 | int pass); | 574 | int pass); |
940 | 560 | \end{verbatim} | 575 | \end{verbatim} |
941 | 561 | 576 | ||
944 | 562 | \index{init\_record - record support routine}\verb|iocInit| calls this routine twice (pass=0 and pass=1) for each database record of the type handled by this routine. It must | 577 | \index{init\_record - record support routine}\verb|iocInit| calls this routine twice (pass=0 and pass=1) for each database record of the type handled by this routine. |
945 | 563 | perform the following functions: | 578 | It must perform the following functions: |
946 | 564 | 579 | ||
947 | 565 | \begin{itemize} | 580 | \begin{itemize} |
948 | 566 | \item Check and/or issue initialization calls for the associated device support routines. | 581 | \item Check and/or issue initialization calls for the associated device support routines. |
949 | 567 | 582 | ||
950 | 568 | \item Perform any record type specific initialization. | 583 | \item Perform any record type specific initialization. |
951 | 569 | 584 | ||
953 | 570 | \item During the first pass it can only perform initializations that affect the record referenced by precord. | 585 | \item During the first pass it can only perform initializations that affect the record referenced by precord. |
954 | 571 | 586 | ||
955 | 572 | \item During the second pass it can perform initializations that affect other records. | 587 | \item During the second pass it can perform initializations that affect other records. |
956 | 573 | 588 | ||
957 | @@ -589,16 +604,20 @@ | |||
958 | 589 | int after);/*(FALSE,TRUE)=>(Before,After)Processing*/ | 604 | int after);/*(FALSE,TRUE)=>(Before,After)Processing*/ |
959 | 590 | \end{verbatim} | 605 | \end{verbatim} |
960 | 591 | 606 | ||
965 | 592 | \index{special - Record Support Routine}This routine implements the record type specific special processing for the field referred to by \verb|dbAddr|. Note that it is | 607 | \index{special - Record Support Routine}This routine implements the record type specific special processing for the field referred to by \verb|dbAddr|. |
966 | 593 | called twice. Once before any changes are made to the associated field and once after. File \verb|special.h| defines special | 608 | Note that it is called twice. |
967 | 594 | types. This routine is only called for user special fields, i.e. fields with \verb|SPC_xxx| \textgreater{}= 100. A field is declared special in the | 609 | Once before any changes are made to the associated field and once after. |
968 | 595 | ASCII record definition file. New values should not by added to \verb|special.h|, instead use \verb|SPC_MOD|. | 610 | File \verb|special.h| defines special types. |
969 | 611 | This routine is only called for user special fields, i.e. fields with \verb|SPC_xxx| \textgreater{}= 100. | ||
970 | 612 | A field is declared special in the ASCII record definition file. | ||
971 | 613 | New values should not by added to \verb|special.h|, instead use \verb|SPC_MOD|. | ||
972 | 596 | 614 | ||
973 | 597 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. | 615 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. |
974 | 598 | 616 | ||
975 | 599 | \subsection{Get Value} | 617 | \subsection{Get Value} |
976 | 600 | 618 | ||
978 | 601 | This routine is no longer used. It should be left as a NULL procedure in the record support entry table. | 619 | This routine is no longer used. |
979 | 620 | It should be left as a NULL procedure in the record support entry table. | ||
980 | 602 | 621 | ||
981 | 603 | \subsection{Convert dbAddr Definitions} | 622 | \subsection{Convert dbAddr Definitions} |
982 | 604 | 623 | ||
983 | @@ -606,18 +625,20 @@ | |||
984 | 606 | cvt_dbaddr(struct dbAddr *paddr); | 625 | cvt_dbaddr(struct dbAddr *paddr); |
985 | 607 | \end{verbatim} | 626 | \end{verbatim} |
986 | 608 | 627 | ||
991 | 609 | \index{cvt\_dbaddr - Record Support Routine}This routine is called by \verb|dbNameToAddr| if the field has special set equal to \verb|SPC_DBADDR|. A typical use is when a field | 628 | \index{cvt\_dbaddr - Record Support Routine}This routine is called by \verb|dbNameToAddr| if the field has special set equal to \verb|SPC_DBADDR|. |
992 | 610 | refers to an array. This routine can change any combination of the \verb|dbAddr| fields: \verb|no_elements|, \verb|field_type|, | 629 | A typical use is when a field refers to an array. |
993 | 611 | \verb|field_size|, \verb|special,pfield, |and\verb| dbr_type|. For example if the \verb|VAL| field of a waveform record is passed to | 630 | This routine can change any combination of the \verb|dbAddr| fields: |
994 | 612 | \verb|dbNameToAddr|, \verb|cvt_dbaddr| would change \verb|dbAddr| so that it refers to the actual array rather then \verb|VAL|. | 631 | \verb|no_elements|, \verb|field_type|, \verb|field_size|, \verb|special,pfield, |and\verb| dbr_type|. |
995 | 632 | For example if the \verb|VAL| field of a waveform record is passed to \verb|dbNameToAddr|, \verb|cvt_dbaddr| would change \verb|dbAddr| so that it refers to the actual array rather then \verb|VAL|. | ||
996 | 613 | 633 | ||
997 | 614 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. | 634 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. |
998 | 615 | 635 | ||
999 | 616 | NOTES: | 636 | NOTES: |
1000 | 617 | 637 | ||
1001 | 618 | \begin{itemize} | 638 | \begin{itemize} |
1004 | 619 | \item Channel access calls db\_name\_to\_addr, which is part of old database access. Db\_name\_to\_addr calls | 639 | \item Channel access calls \verb|db_name_to_addr|, which is part of old database access. |
1005 | 620 | dbNameToAddr. This is done when a client connects to the record. | 640 | \verb|db_name_to_addr| calls \verb|dbNameToAddr|. |
1006 | 641 | This is done when a client connects to the record. | ||
1007 | 621 | 642 | ||
1008 | 622 | \item no\_elements must be set to the maximum number of elements that will ever be stored in the array. | 643 | \item no\_elements must be set to the maximum number of elements that will ever be stored in the array. |
1009 | 623 | 644 | ||
1010 | @@ -632,11 +653,12 @@ | |||
1011 | 632 | long *offset); | 653 | long *offset); |
1012 | 633 | \end{verbatim} | 654 | \end{verbatim} |
1013 | 634 | 655 | ||
1016 | 635 | \index{get\_array\_info - Record Support Routine}This routine returns the current number of elements and the offset of the first value of the specified array. The offset field | 656 | \index{get\_array\_info - Record Support Routine}This routine returns the current number of elements and the offset of the first value of the specified array. |
1017 | 636 | is meaningful if the array is actually a circular buffer. | 657 | The offset field is meaningful if the array is actually a circular buffer. |
1018 | 637 | 658 | ||
1021 | 638 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. It is | 659 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. |
1022 | 639 | permissible for \verb|get_array_info| to change \verb|pfield|. This feature can be used to implement double buffering. | 660 | It is permissible for \verb|get_array_info| to change \verb|pfield|. |
1023 | 661 | This feature can be used to implement double buffering. | ||
1024 | 640 | 662 | ||
1025 | 641 | \index{get\_array\_info - Record Support Routine} | 663 | \index{get\_array\_info - Record Support Routine} |
1026 | 642 | When an array field is being written \verb|get_array_info| is called before the field values are changed. | 664 | When an array field is being written \verb|get_array_info| is called before the field values are changed. |
1027 | @@ -673,8 +695,9 @@ | |||
1028 | 673 | long *precision); | 695 | long *precision); |
1029 | 674 | \end{verbatim} | 696 | \end{verbatim} |
1030 | 675 | 697 | ||
1033 | 676 | \index{get\_precision - Record Support Routine}This routine gets the precision, i.e. number of decimal places, which should be used to convert the field value to an ASCII | 698 | \index{get\_precision - Record Support Routine}This routine gets the precision, i.e. |
1034 | 677 | string. \verb|recGblGetPrec| should be called for fields not directly related to the value field. | 699 | number of decimal places, which should be used to convert the field value to an ASCII string. |
1035 | 700 | \verb|recGblGetPrec| should be called for fields not directly related to the value field. | ||
1036 | 678 | 701 | ||
1037 | 679 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. | 702 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. |
1038 | 680 | 703 | ||
1039 | @@ -686,7 +709,8 @@ | |||
1040 | 686 | char *p); | 709 | char *p); |
1041 | 687 | \end{verbatim} | 710 | \end{verbatim} |
1042 | 688 | 711 | ||
1044 | 689 | \index{get\_enum\_str - record Support Routine}This routine sets \verb|*p| equal to the ASCII string for the field value. The field must have type \verb|DBF_ENUM|. | 712 | \index{get\_enum\_str - record Support Routine}This routine sets \verb|*p| equal to the ASCII string for the field value. |
1045 | 713 | The field must have type \verb|DBF_ENUM|. | ||
1046 | 690 | 714 | ||
1047 | 691 | Look at the code for the \verb|bi| or \verb|mbbi| records for examples. | 715 | Look at the code for the \verb|bi| or \verb|mbbi| records for examples. |
1048 | 692 | 716 | ||
1049 | @@ -714,8 +738,8 @@ | |||
1050 | 714 | char *p); | 738 | char *p); |
1051 | 715 | \end{verbatim} | 739 | \end{verbatim} |
1052 | 716 | 740 | ||
1055 | 717 | \index{put\_enum\_str - Record Support Routine}Given an ASCII string, this routine updates the database field. It compares the string with the string values associated with | 741 | \index{put\_enum\_str - Record Support Routine}Given an ASCII string, this routine updates the database field. |
1056 | 718 | each enumerated value and if it finds a match sets the database field equal to the index of the string which matched. | 742 | It compares the string with the string values associated with each enumerated value and if it finds a match sets the database field equal to the index of the string which matched. |
1057 | 719 | 743 | ||
1058 | 720 | Look at the code for the \verb|bi| or \verb|mbbi| records for examples. | 744 | Look at the code for the \verb|bi| or \verb|mbbi| records for examples. |
1059 | 721 | 745 | ||
1060 | @@ -729,8 +753,8 @@ | |||
1061 | 729 | struct dbr_grDouble *p); /* addr of return info*/ | 753 | struct dbr_grDouble *p); /* addr of return info*/ |
1062 | 730 | \end{verbatim} | 754 | \end{verbatim} |
1063 | 731 | 755 | ||
1066 | 732 | \index{get\_graphic\_double - Record Support Routine}This routine fills in the graphics related fields of structure \verb|dbr_grDouble|. \verb|recGblGetGraphicDouble| should be | 756 | \index{get\_graphic\_double - Record Support Routine}This routine fills in the graphics related fields of structure \verb|dbr_grDouble|. |
1067 | 733 | called for fields not directly related to the value field. | 757 | \verb|recGblGetGraphicDouble| should be called for fields not directly related to the value field. |
1068 | 734 | 758 | ||
1069 | 735 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. | 759 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. |
1070 | 736 | 760 | ||
1071 | @@ -742,8 +766,8 @@ | |||
1072 | 742 | struct dbr_ctrlDouble *p); /* addr of return info*/ | 766 | struct dbr_ctrlDouble *p); /* addr of return info*/ |
1073 | 743 | \end{verbatim} | 767 | \end{verbatim} |
1074 | 744 | 768 | ||
1077 | 745 | \index{get\_control\_double - Record Support Routine}This routine gives values to all fields of structure \verb|dbr_ctrlDouble|. \verb|recGblGetControlDouble| should be called | 769 | \index{get\_control\_double - Record Support Routine}This routine gives values to all fields of structure \verb|dbr_ctrlDouble|. |
1078 | 746 | for fields not directly related to the value field. | 770 | \verb|recGblGetControlDouble| should be called for fields not directly related to the value field. |
1079 | 747 | 771 | ||
1080 | 748 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. | 772 | The database access routine, \verb|dbGetFieldIndex| can be used to determine which field is being modified. |
1081 | 749 | 773 | ||
1082 | @@ -762,26 +786,30 @@ | |||
1083 | 762 | \section{Global Record Support Routines} | 786 | \section{Global Record Support Routines} |
1084 | 763 | 787 | ||
1085 | 764 | \index{Global Record Support Routines} | 788 | \index{Global Record Support Routines} |
1088 | 765 | A number of global record support routines are available. These routines are intended for use by the record specific | 789 | A number of global record support routines are available. |
1089 | 766 | processing routines but can be called by any routine that wishes to use their services. | 790 | These routines are intended for use by the record specific processing routines but can be called by any routine that wishes to use their services. |
1090 | 767 | 791 | ||
1091 | 768 | The name of each of these routines begins with ``\verb|recGbl|". | 792 | The name of each of these routines begins with ``\verb|recGbl|". |
1092 | 769 | 793 | ||
1093 | 770 | \subsection{Alarm Status and Severity} | 794 | \subsection{Alarm Status and Severity} |
1094 | 771 | 795 | ||
1108 | 772 | Alarms may be raised in many different places during the course of record processing. The algorithm is to maximize the | 796 | Alarms may be raised in many different places during the course of record processing. |
1109 | 773 | alarm severity, i.e. the highest severity outstanding alarm is raised. If more than one alarm of the same severity is found | 797 | The algorithm is to maximize the alarm severity, i.e. the highest severity outstanding alarm is raised. |
1110 | 774 | then the first one is reported. This means that whenever a code fragment wants to raise an alarm, it does so only if the | 798 | If more than one alarm of the same severity is found then the first one is reported. |
1111 | 775 | alarm severity it will declare is greater then that already existing. Four fields (in database common) are used to implement | 799 | This means that whenever a code fragment wants to raise an alarm, it does so only if the alarm severity it will declare is greater then that already existing. |
1112 | 776 | alarms: \verb|sevr|, \verb|stat|, \verb|nsev|, and \verb|nsta|. The first two are the status and severity after the record is completely processed. | 800 | Four fields (in database common) are used to implement alarms: |
1113 | 777 | The last two fields (\verb|nsta| and \verb|nsev|) are the status and severity values to set during record processing. Two routines are | 801 | \verb|sevr|, \verb|stat|, \verb|nsev|, and \verb|nsta|. |
1114 | 778 | used for handling alarms. Whenever a routine wants to raise an alarm it calls \verb|recGblSetSevr|. This routine will only | 802 | The first two are the status and severity after the record is completely processed. |
1115 | 779 | change \verb|nsta| and \verb|nsev| if it will result in the alarm severity being increased. At the end of processing, the record support | 803 | The last two fields (\verb|nsta| and \verb|nsev|) are the status and severity values to set during record processing. |
1116 | 780 | module must call \verb|recGblResetAlarms|. This routine sets \verb|stat = nsta|, \verb|sevr = nsev|, \verb|nsta= 0|, and \verb|nsev = 0|. If \verb|stat| | 804 | Two routines are used for handling alarms. |
1117 | 781 | or \verb|sevr| has changed value since the last call it calls \verb|db_post_event| for \verb|stat| and \verb|sevr| and returns a value of | 805 | Whenever a routine wants to raise an alarm it calls \verb|recGblSetSevr|. |
1118 | 782 | \verb|DBE_ALARM|. If no change occured it returns 0. Thus after calling \verb|recGblResetAlarms| everything is ready for raising | 806 | This routine will only change \verb|nsta| and \verb|nsev| if it will result in the alarm severity being increased. |
1119 | 783 | alarms the next time the record is processed. The example record support module presented above shows how these | 807 | At the end of processing, the record support module must call \verb|recGblResetAlarms|. |
1120 | 784 | macros are used. | 808 | This routine sets \verb|stat = nsta|, \verb|sevr = nsev|, \verb|nsta= 0|, and \verb|nsev = 0|. |
1121 | 809 | If \verb|stat| or \verb|sevr| has changed value since the last call it calls \verb|db_post_event| for \verb|stat| and \verb|sevr| and returns a value of \verb|DBE_ALARM|. | ||
1122 | 810 | If no change occured it returns 0. | ||
1123 | 811 | Thus after calling \verb|recGblResetAlarms| everything is ready for raising alarms the next time the record is processed. | ||
1124 | 812 | The example record support module presented above shows how these macros are used. | ||
1125 | 785 | 813 | ||
1126 | 786 | \begin{verbatim} | 814 | \begin{verbatim} |
1127 | 787 | recGblSetSevr( | 815 | recGblSetSevr( |
1128 | @@ -790,7 +818,7 @@ | |||
1129 | 790 | short nsevr); | 818 | short nsevr); |
1130 | 791 | \end{verbatim} | 819 | \end{verbatim} |
1131 | 792 | 820 | ||
1133 | 793 | \index{recGblSetSevr}Returns: (\verb|TRUE|, \verb|FALSE|) if (did, did not) change \verb|nsta| and \verb|nsev|. | 821 | \index{recGblSetSevr}Returns \verb|TRUE| if it changed \verb|nsta| and/or \verb|nsev|, \verb|FALSE| if it did not change them. |
1134 | 794 | 822 | ||
1135 | 795 | \begin{verbatim} | 823 | \begin{verbatim} |
1136 | 796 | unsigned short recGblResetAlarms(void *precord); | 824 | unsigned short recGblResetAlarms(void *precord); |
1137 | @@ -800,9 +828,10 @@ | |||
1138 | 800 | 828 | ||
1139 | 801 | \subsection{Alarm Acknowledgment} | 829 | \subsection{Alarm Acknowledgment} |
1140 | 802 | 830 | ||
1144 | 803 | Database common contains two additional alarm related fields: \verb|acks| (Highest severity unacknowledged alarm) and | 831 | Database common contains two additional alarm related fields: |
1145 | 804 | \verb|ackt| (does transient alarm need to be acknowledged). These field are handled by \verb|iocCore| and \verb|recGblResetAlarms| | 832 | \verb|acks| (Highest severity unacknowledged alarm) and \verb|ackt| (does transient alarm need to be acknowledged). |
1146 | 805 | and are not the responsibility of record support. These fields are intended for use by the alarm handler. | 833 | These field are handled by \verb|iocCore| and \verb|recGblResetAlarms| and are not the responsibility of record support. |
1147 | 834 | These fields are intended for use by the alarm handler. | ||
1148 | 806 | 835 | ||
1149 | 807 | \subsection{Generate Error: Process Variable Name, Caller, Message} | 836 | \subsection{Generate Error: Process Variable Name, Caller, Message} |
1150 | 808 | 837 | ||
1151 | @@ -815,8 +844,8 @@ | |||
1152 | 815 | char *pcaller_name); /* calling routine name */ | 844 | char *pcaller_name); /* calling routine name */ |
1153 | 816 | \end{verbatim} | 845 | \end{verbatim} |
1154 | 817 | 846 | ||
1157 | 818 | \index{recGblDbaddrError}This routine interfaces with the system wide error handling system to display the following information: Status | 847 | \index{recGblDbaddrError}This routine interfaces with the system wide error handling system to display the following information: |
1158 | 819 | information, process variable name, calling routine. | 848 | Status information, process variable name, calling routine. |
1159 | 820 | 849 | ||
1160 | 821 | \subsection{Generate Error: Status String, Record Name, Caller} | 850 | \subsection{Generate Error: Status String, Record Name, Caller} |
1161 | 822 | SUGGESTION: use errlogPrintf instead of this for new code. | 851 | SUGGESTION: use errlogPrintf instead of this for new code. |
1162 | @@ -829,8 +858,8 @@ | |||
1163 | 829 | 858 | ||
1164 | 830 | \index{errlogPrintf} | 859 | \index{errlogPrintf} |
1165 | 831 | \index{recGblRecordError} | 860 | \index{recGblRecordError} |
1168 | 832 | This routine interfaces with the system wide error handling system to display the following information: Status | 861 | This routine interfaces with the system wide error handling system to display the following information: |
1169 | 833 | information, record name, calling routine. | 862 | Status information, record name, calling routine. |
1170 | 834 | 863 | ||
1171 | 835 | \subsection{Generate Error: Record Name, Caller, Record Support Message} | 864 | \subsection{Generate Error: Record Name, Caller, Record Support Message} |
1172 | 836 | SUGGESTION: use errlogPrintf instead of this for new code. | 865 | SUGGESTION: use errlogPrintf instead of this for new code. |
1173 | @@ -844,8 +873,8 @@ | |||
1174 | 844 | 873 | ||
1175 | 845 | \index{errlogPrintf} | 874 | \index{errlogPrintf} |
1176 | 846 | \index{recGblRecsupError} | 875 | \index{recGblRecsupError} |
1179 | 847 | This routine interfaces with the system wide error handling system to display the following information: Status | 876 | This routine interfaces with the system wide error handling system to display the following information: |
1180 | 848 | information, record name, calling routine, record support entry name. | 877 | Status information, record name, calling routine, record support entry name. |
1181 | 849 | 878 | ||
1182 | 850 | \subsection{Get Graphics Double} | 879 | \subsection{Get Graphics Double} |
1183 | 851 | 880 | ||
1184 | @@ -900,8 +929,8 @@ | |||
1185 | 900 | \index{recGblGetTimeStamp}This routine gets the current time stamp and puts it in the record It does the following: | 929 | \index{recGblGetTimeStamp}This routine gets the current time stamp and puts it in the record It does the following: |
1186 | 901 | 930 | ||
1187 | 902 | \begin{itemize} | 931 | \begin{itemize} |
1190 | 903 | \item If TSEL is not a constant link and TSEL refers to the TIME field of a record, the time is obtained from the record | 932 | \item If TSEL is not a constant link and TSEL refers to the TIME field of a record, the time is obtained from the record reference by TSEL and this put in field TIME. |
1191 | 904 | reference by TSEL and this put in field TIME. The routine then returns. | 933 | The routine then returns. |
1192 | 905 | 934 | ||
1193 | 906 | \item If TSEL is not a constant link dbGetLink is called and the value put in field TSE. | 935 | \item If TSEL is not a constant link dbGetLink is called and the value put in field TSE. |
1194 | 907 | 936 | ||
1195 | @@ -929,5 +958,6 @@ | |||
1196 | 929 | void *pdest); | 958 | void *pdest); |
1197 | 930 | \end{verbatim} | 959 | \end{verbatim} |
1198 | 931 | 960 | ||
1201 | 932 | \index{recGblInitConstantLink}Initialize a constant link. This routine is usually called by \verb|init_record| (or by associated device support) to initialize | 961 | \index{recGblInitConstantLink}Initialize a constant link. |
1202 | 933 | the field associated with a constant link. It returns(FALSE, TRUE) if it (did not, did) modify the destination. | 962 | This routine is usually called by \verb|init_record| (or by associated device support) to initialize the field associated with a constant link. |
1203 | 963 | It returns(FALSE, TRUE) if it (did not, did) modify the destination. |
Could you fix the conflict and re-propose?