| Last Revised: 02/13/17 |
Purpose: To process any error encountered by a program as well as interrupt key processing. This routine is called by all Dynamo Tools, and should be called by all application software to consistently process errors and interrupt keys.
CDS063 provides the following functions:
- Prints a window equal to the physical size of the screen to preserve the display in the state when the error occurred.
- Logs the details about the error as well as the error resolution option selected by the operator to the error log. The error log is printed using the System Error Log option on the SMC menu.
- Sends a comprehensive Program Error Report by email. Example.
- Display options for the operator including:
- Continue Program Execution - retry, appropriate response after error 0, error 5, etc.
- Display Additional Information about the error such as display of line of code, last host error code, etc.
- Display possible causes of the error and corrective action
- Display variables
- Enter console (programming) mode to alter the program (after entry of daily password)
- Abort the job and return to the menu
- Set a program trace and continue program execution
- Turn off escape handling and continue program execution so that next interrupt will not invoke error routine.
- Display information about opened files.
The lines of code necessary to call the error routine are created
automatically if you define a program using the File Utility (SMU menu).
These lines can also be added to
a program by using the ERROR command within the program editor. They can also
be updated using the Program Utility. The calling procedure is the same
whether the application program is RUN or CALLed.
Calling format for programs with line numbers:
First line of code after Remark typically at line 0100 (Line 0110 in this example)
0110 SETERR DT_ERR; SETESC DT_ERR
Near bottom of program:
8000 DT_ERR:
8010 CALL "CDS063",STR(TCB(5+3*(ERR=127))),Y$,PGM(-2)
8020 IF Y.ERRSTS=0 THEN SETERR 0 ELSE IF Y.ERRSTS=2 RETURN
8030 RETRY
Traditional format when not using a line label:
0110 SETESC 8000; SETERR 8000
8000 REM "Call Error/Escape Routine
8010 CALL "CDS063",STR(TCB(5+3*(ERR=127))),Y$,PGM(-2)
8020 ON Y.ERRSTS GOTO 8030,8040,8050,8060
8030 SETERR 0
8040 RETRY
8050 RETURN
8060 RETRY
Calling Format for bbj programs without line numbers:
First line of code after Remark
SETERR DT_ERR; SETESC DT_ERR
Near bottom of program:
DT_ERR:
CALL "CDS063",STR(TCB(5+3*(ERR=127))),Y$,PGM(-2)
IF Y.ERRSTS=0 THEN SETERR 0 ELSE IF Y.ERRSTS=2 RETURN
RETRY
Lower case version:
DT_ERR:
call "CDS063", str(tcb(5+3*(err=127))), Y$, pgm(-2)
if Y.ERRSTS=0 then seterr 0 else if Y.ERRSTS=2 return
retry
When using BBj Custom Objects, you do not need the SETERR, nor the DT_ERR lines within each method.
When using BBj, whether using Custom Objects or not, Dynamo Tools uses the global error routine option, which will still call CDS063 for un-trapped errors, even when the SETERR and DT_ERR section is not included in each program.
| CDS063 | |
|---|---|
STR(TCB(5+3*(ERR=127)))
|
the line number of the last error or line being executed when program execution was interrupted |
Y$
|
the Dynamo Tools session control variable. If passed to the error routine as null,
which might be done in the case of a called routine, the error routine will
retrieve For programs that do not use |
PGM(-2)
|
the name of the calling program |
CDS063 sets the Y.ERRSTS variable to control execution of the selected action
once control is returned to the calling program.
| Y.ERRSTS Resultant action | |
|---|---|
| 0 | Used to shut off error routine and retry in order to enter console (program) mode to manually alter program. |
| 1 | Used to retry and continue program execution. |
| 2 | Used to continue program execution after an interrupt. |
| 3 | Used to continue program execution after a printer error. Special forms alignment logic or other restart logic might be required before executing the RETRY statement. Note that line 8060 would be altered in that case. |
| Global Variables | |
|---|---|
SMS_CDS063.CCEMAIL
|
Set this global variable to an email address that should be copied on the error email. This is useful for software developers whose address is not included in the Software Support Email broadcast. Multiple email addresses can be included if separated by commas. |
WMS_DUMPLINK
|
Set this global variable to any value to enable a link to the DUMP report to appear on the Dynaweb error page should the application encounter an error. |
SMS_CDS063.DF
|
This global variable can be used to specify an alternative
dump file, and to cause CDS063 to exit to calling application instead of
terminating background tasks. The global should be set to the path
where the dump files should be stored. It is recommended that the
global end with CDS063 will pass the unique dump file name back to the calling program using the same global. If running as a background task, whether bbx or bbj, including stored
procedures and triggers, CDS063 will |
| SMS_CDS063.STATUS | Set this global to a program name that CDS063 will call to log error status information within your application. This is useful for dashboards that monitor background task status. The ENTER list should be Y$,STATUS$. STATUS$ will be set by CDS063 and passed to this called program with information such as "Error NNN, program XXXXXX, line NNN" or "Background Task Prompt: XXXXXXXXXXXXXXXXXXX". Note that you can also include a line label after the program name in the standard format: BKGTASK::LOG. |
Note
When the operator selects the option to abort and return to the selector, control is not passed to the calling routine. This permits aborting a job multiple levels deep within called routines without all of the logic necessary to back out of each program.
Background Tasks
Background tasks including Dynaweb applications, bbj stored procedures and
triggers, should also use CDS063. CDS063 will log the error and send the
email error report. In most cases, the error cannot be recovered, so CDS063 will call CDS081 to terminate the process. See Global
Variable SMS_CDS063.DF above to cause CDS063 to EXIT
to calling program for background tasks.
However, if the background task encounters an error 0 when reading (or EXTRACTing) a record in a disk file, instead of aborting the application, CDS063 waits one minute, then returns to the calling application so that the application can RETRY. Note that this process will repeat until the record becomes available. The log file will include an entry each time CDS063 is called.
Background Task Log File
When CDS063 is called from a background task, it will print (to the standard
out channel), a text message. If the background task was started by the
Dynamo Tool background script using the default log file name, then the log file is named log/bkg.
When running bbj, CDS063 sends the text message to the bbj standard error file
which can be easily viewed using the Basis Enterprise Manager.
CDS186 is used to deliver the message. Note that
the System Error Log (SMC) also includes summary information about the error.
Dynaweb
When using CDS063 with web applications such as Dynaweb, the error routine
will send a descriptive message to the browser. If the BBx global variable
"WMS_DUMPLINK" file is set (to any value), the browser message will
include "Dynamo Tools - Program Error Report" with a hyperlink to the report file created
to assist resolving the error. The error report file is created regardless of this
global, but the link can be removed for security purposes. The error
report file
is created in the $SMSDIR/tmp directory with a unique name. Use cron to
schedule the cleartmp script to run each evening to remove all files in the tmp
directory that are more than 1 day old.
Emailed Program Error Report
In order to email the Dynamo Tool - Program Error Report, the server, or data server, must first be configured to send email.
Email will be sent to the Software Support Email address as specified using Dynamo Configuration Maintenance on SMC menu. This address can be a 'role' address which forwards the email to multiple addresses.
Email can also be sent to the user logged in. To enable this option, use Operator Information Maintenance (SMC) and specify the email address and set the Email Program Errors option to Y.
Email will also be copied to an email address specified using global variable as described above.
If a Dynamo Tool program encounters an error, the Program Error Report will include:
- The date and time of the installed version of the program
- The date and time of the current version of the program, after a Dynamo Tools upgrade.
- Any program revision notes made since the installed version date.
- A hyperlink to the Dynamo Tools documentation for any called program
- The line of code (from the current program version) that encountered the error, or that was being executed when the program was interrupted
To minimize the time the operator has to wait for the Program Error Report to be created, portions of the report, including the email delivery is run as either a separate process. In the case of Windows using a data server, the separate process will be run on the data server.
Note that for Background Tasks including Dynaweb, running on Unix, (linux, AIX, SCO Unix, etc.), you can send a kill -4 signal to the running pro5 process to generate the Program Error Report. This is helpful when diagnosing a long running process, or one that might be caught in an infinite loop. You will need to issue the kill signal as root or the user that is running Dynaweb, i.e.,
sudo kill -4 <pro5 process id>
Example emailed Program Error Report.