![[SLAC Controls Department]](/grp/cd/soft/images/logo_cd.gif){kind=logo}
![[SLAC Home Page]](/grp/cd/soft/images/logo_slac.gif){kind=logo}
8.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 8-1
8.2 ORIGINATING ROUTINE . . . . . . . . . . . . . . . 8-3
8.2.1 ERR_SEND . . . . . . . . . . . . . . . . . . . 8-4
8.2.2 ERRCHK . . . . . . . . . . . . . . . . . . . . . 8-5
8.2.3 ERR_TEXT . . . . . . . . . . . . . . . . . . . . 8-6
8.3 RECEIVING ROUTINE . . . . . . . . . . . . . . . . 8-7
8.4 SEVERITY . . . . . . . . . . . . . . . . . . . . . 8-7
8.5 FACILITIES . . . . . . . . . . . . . . . . . . . . 8-8 CHAPTER 8 ERROR MESSAGES
8.1 INTRODUCTION SLC control programs use a coherent set of routines to signal error messages that is based on the VMS Message facility. This facility is available to stand-alone VMS programs, components of the VMS SLC control system, and to the micros under iRMX. An (error) message is sent to a destination when a program detects a condition requiring notification of a user. The message codes and texts are defined precisely as documented in the VMS Message Utility manual. This means that each message is associated with a unique 32 bit word called the message code. The structure of this longword is documented in the VAX Architecture manual. The message code is associated with a unique message symbol that is generated by the message compiler, and with a message text and formatting directives for any parameters of the message text. The message compiler takes as input a file of type .MSG, containing the message text for a particular facility. The SLC error message scheme has two basic pieces; a message originator and a message receiver. The message originator sends the message code and any parameters to the message receiver using the SLC Message format and utilities. The message
ERROR MESSAGES Page 8-2 originator needs to "know" only the message code, and the message text and formatting is handled entirely by VMS. The user does not code message codes directly, but refers to them by their symbols. The symbols and associated codes are available as valid Fortran parameter statements in valid "Include" files and can be included in VMS or iRMX Fortran. These files are generated from the output of the Message compiler by the program MSGREAD, and are kept in the Include text library and in the SLCRMX account. The receiving routine takes the SLC MSG buffer, acquires the message text using the SYS$GETMSG service, formats the message using SLC rather than SYS$FAO format conventions, and outputs the formatted message. Error messages from micros or SCPs are sent first to PARANOIA (if the severity level is high enough), which obtains and formats the message text and puts it in the error log. By default, the message is relayed by PARANOIA to the remote destination for display. This default may be overridden in either of two ways, in which case the message is logged but not sent out for display, regardless of the severity. The first way is to set the high order bit in the message code, in the call to ERR_SEND, i.e.: ISS = ERR_SEND( MSG_CODE [+ NOSEND], ARG1, ARG2,...) where NOSEND='80000000'X. The second way is to put the character '@' as the first character of the message text in the .MSG file, i.e.: MSGSYMBOL <'@ ..........'>
ERROR MESSAGES Page 8-3 In the case of an error arising in a micro, the error message is relayed by PARANOIA to the source of the command that led to the error message (i.e., to a particular SCP). In the case of an error arising in a normal SCP, the error message is relayed by PARANOIA to that SCP. Errors arising in processes that are not necessarily attached to terminals (e.g. DBEX, FEEDBACK, PARANOIA itself) are broadcast by COWRITE to all logged-on SCPs. Fatal errors originating in the micros or errors directed to PARANOIA are also broadcast. Each job in the micro contains a message common block which stores the command messages received, so that the source is be available when it is time to send an error message back to the appropriate destination in the VAX (i.e., the source of the command message is the destination of the error message). The source of the command message is put in the data of the MSG_SEND (if the source was a micro) or MSG_ESEND (if the source was SCP) used internally by ERR_SEND to send the error message code to PARANOIA. Error messages from standalone VAX processes are simply displayed at the terminal using COWRITE and not logged. The source of the error message (e.g. micro LI31 or SCP V004) is formatted as part of the error message, appearing just after the message symbol. (For stand-alone VAX processes no such source is included in the error message.)8.2 ORIGINATING ROUTINE
ERROR MESSAGES Page 8-48.2.1 ERR_SEND The originating routine in VAX programs is: MSG_STAT = ERR_SEND( MSG_CODE, ARG1, ..., ARG10) and in iRMX micro programs is: MSG_STAT = ERR_SEND( MSG_CODE, ARG1, ..., ARG10, NUMARGS) o MSG_STAT is the MSG_CODE. (This apparently strange construction is convenient in many applications. It allows testing of a status in an IF, etc. Note that the severity levels Success and Informational are TRUE and all others are FALSE.) o MSG_CODE is the unique VMS longword associated with the message. It is expected that the MSG_CODE will be coded as a parameter using the message symbol. o ARGn are longwords to be passed to the message receiver. These arguments are parameters to be formatted for inclusion in the error message. A particular error message requires a particular number of arguments, between 0 and 10. It should be noted that the argument passing convention is a genuine limitation of the generality of the VMS system. First, there is a limit on the number of different arguments, and if the parameter is an ASCII string, the address of the actual string of up to four characters is passed, rather than the string or the descriptor for the string. Example:
ERROR MESSAGES Page 8-5 CHARACTER*8 ARG_STRING . . . MSG_STAT=ERR_SEND(CONFIG_ERROR,REF%(ARG_STRING(1:4)), REF%(ARG_STRING(5:8)) ) [See ERR_SEND_STRING for an alternative to ERR_SEND]. Nevertheless, it is considered that these constraints are acceptable. o NUMARGS, the number of arguments ARGn, must be included for the iRMX micro calls to ERR_SEND and must NOT be included for VAX calls to ERR_SEND. In the iRMX micro case, NUMARGS must be present in the call list even if it is equal to zero. ERR_SEND also includes a common block as follows COMMON/ERRCOUNT/ FATAL_CT,ERROR_CT,WARNING_CT, > INFO_CT,SUCCESS_CT,TOTAL_CT,ERRLAST which keeps track of the number of errors at each severity level that have been sent. The counters are only incremented if the error message is not suppressed by ERR_SET (see below). ERRLAST is the message code for the last error message sent.8.2.2 ERRCHK Messages arising from system service calls (i.e., corresponding to message codes having facility number=0) are handled more conveniently
ERROR MESSAGES Page 8-6 by a different error routine. After system service calls the user calls : MSG_STAT=ERRCHK('prefix',ISS) where ISS is the message code returned from the system service call and prefix will normally be the name of the system service (but can be any user-defined string of not more than 32 characters). The call to ERR_SEND is made inside ERRCHK. System service calls do not have arguments, so the ARGn will instead be used to format and write the prefix string to distinguish which system service call the message is coming from. MSG_STAT is set equal to ISS, the message code.8.2.3 ERR_TEXT An additional routine is provided for sending text messages to the error log. MSG_STAT = ERR_TEXT(MSG_CODE,MSG_STRING) where MSG_STAT is the MSG_CODE as for ERR_SEND and MSG_STRING is the message to be logged. ERR_TEXT constructs a standard SLC message with a special function code reserved to the Error service, TEXT_CODE, and data MSG_SYMBOL followed by an Ascii text string which is the process name concatenated with the argument MSG_STRING. The maximum length of the string, including process name, is 132 characters. MSG_SYMBOL is expected to be a valid VMS error code. The message is sent to Paranoia and logged along with errors.
ERROR MESSAGES Page 8-78.3 RECEIVING ROUTINE The message receiver uses Fortran rather than FAO format conventions. This means that the message text can be any valid Fortran format statement with the exception that the outer parentheses are replaced by angle brackets. It of course must be remembered that the data to be formatted is in longwords. Examples of valid message texts are: <'NO RESPONSE FROM SERIAL SYSTEM'> <'CAMAC CRATE ',I2,' CLUSTER ',A4,' IS POOCHED'> <'CLUSTER ',A4,' LGPS UNIT ',I5,' OVERCURRENT = ',F10.2,' AMPS'>
8.4 SEVERITY VMS allows a severity level to be associated with each message. There are five levels, represented by the following codes (in increasing order of severity): Code Function ---- ---------- 1 Success 3 Informational 0 Warning 2 Error 4 Fatal Occasionally it may be desirable to suppress some level of messages from a facility. The function ERR_SET may be used for this purpose: PREV_LEV=ERR_SET(FACILITY_CODE,SEV_LEV) o PREV_LEV is the previous level that was in effect. The default value for all facilities is 0 (Warning). o SEV_LEV is the level BELOW which messages will not be reported. Note that it is thus not possible to suppress fatal errors! Note also that this means that a level of 1
ERROR MESSAGES Page 8-8 means Successes are reported. o FACILITY_CODE is the longword code for each facility generated by the message compiler and available as a parameter in the facilty message include files previously described. Note that repeated calls may be made to ERR_SET for the same facility. Note also that since each job in a micro has its own copy of ERR_SEND and ERR_SET, it is possible to impose different severity level cutoffs for messages from the same facility, in different jobs.8.5 FACILITIES Existing facility codes are: Code (hex) Facility Name ---------- ----------------- ----- 801 Database DB 802 Camac CAM 803 Analog/Digital Status STAT 805 Operations OPS 810 Slcnet SLCNET 814 Micro MICR 81C Message service MSG 81E Poll POLL 820 Master Pattern Generator MPG 82E Beam Design Language BDL 830 Cable Video CAVM 840 Magnets MGNT 841 LGPS LGPS 842 PIOP PIOP 843 Klystrons KLYS 844 BPMO BPMO 847 Crate Watch CRAT 848 Timing TIME B84 Boot86 BOOT86