Handling error/warning/info messages in SKILL
Contents:
- Function - hiDisplayAppDBox()
- Display an error message
- Display a warning message
- Display an info message
- Display a dialog box
- Functions - error(), warn() and info()
- Conclusion
In programming, effective communication with users and robust error handling are essential for creating reliable and user-friendly applications.
Providing immediate feedback and guidance helps users understand what the script does and decide what to do next. By reporting errors and warnings, we can help users to diagnose and resolve issues.
This guide provides an overview of messaging and debugging functions in SKILL, including hiDisplayAppDBox(), error(), warn(), and info(). These functions are essential for communicating with users, handling errors, and providing informational messages within the Cadence Virtuoso environment.
1. Function - hiDisplayAppDBox()
This function displays a pop-up box with a custom message. It can be used to display error, warning, informational or dialog messages.
Use hiDisplayAppDBox() when you need to interact with the user through the GUI, such as confirming an action, displaying an error that requires user acknowledgment, or providing important information. We can customize the pop-up box with optional arguments like message text, box type, buttons, etc., to match our needs.
1hiDisplayAppDBox(
2 ?name 'errorAppDBox
3 ?dboxBanner "*ERROR* My App"
4 ?dboxText "Failed to open a file!"
5 ?dialogType hicErrorDialog
6 ?buttonLayout 'Close
7)
Example using hiDisplayAppDBox() function
2. Display an error message
Errors should prevent a user from continuing using a script if something went wrong. They should be clear, so the user understands why the script failed and what to do next.
For example, failing to write to a file or providing incorrect type of input:
1procedure( writeData(filePath data)
2 prog( (outPort message)
3
4 outPort = outfile(filePath "w")
5 unless( outPort
6 sprintf(message "Failed to open a \"%s\" file!\nPlease check that the provided path is correct and you have write permissions."
7 filePath)
8 hiDisplayAppDBox(
9 ?name 'errorAppDBox
10 ?dboxBanner "*ERROR* Writing Data"
11 ?dboxText message
12 ?dialogType hicErrorDialog
13 ?buttonLayout 'Close
14 )
15
16 return()
17 );unless
18
19 unless( stringp(data)
20 sprintf(message "The provided data type - %L.\nPlease provide data as a string!"
21 type(data))
22
23 hiDisplayAppDBox(
24 ?name 'errorAppDBox
25 ?dboxBanner "*ERROR* Writing Data"
26 ?dboxText message
27 ?dialogType hicErrorDialog
28 ?buttonLayout 'Close
29 )
30
31 return()
32 );unless
33
34 fprintf(outPort "%s\n" data)
35 close(outPort)
36
37 return(t)
38 );prog
39);procedure
Example of an error message
Note: The code after the hiDisplayAppDBox() function is executed, so make sure to exit/stop a function after showing an error message.
3. Display a warning message
Warnings inform users of conditions that might lead to problems but do not immediately prevent the script from continuing.
For example, when the netbatch/cloud settings are missing, but we can still run the script locally:
1procedure( runVerifications()
2 let( (message)
3
4 unless( getShellEnvVar("NETBATCH_POOL")
5 message = "Netbatch settings are missing!\nRunning the tasks locally."
6 hiDisplayAppDBox(
7 ?name 'warningAppDBox
8 ?dboxBanner "*WARNING* My App"
9 ?dboxText message
10 ?dialogType hicWarningDialog
11 ?buttonLayout 'Close
12 )
13 );unless
14
15 ; Rest of the code here
16 );let
17);procedure
Example of a warning message
4. Display an info message
Info messages also do not prevent the script from continuing and are best to communicate progress, confirm actions, and offer guidance and tips.
For example, we inform the user when the script is finished:
1procedure( runTask()
2 let( (message success)
3
4 ; Implement task logic here
5
6 if( success
7 then
8 message = "The task is finished successfully!"
9 else
10 message = "The task is finished with errors!\nPlease refer to a log file."
11 );if
12
13 hiDisplayAppDBox(
14 ?name 'infoAppDBox
15 ?dboxBanner "*INFO* My App"
16 ?dboxText message
17 ?dialogType hicMessageDialog
18 ?buttonLayout 'Close
19 )
20 );let
21);procedure
Example of an info message
5. Display a dialog box
Displaying a dialog box is required when you need to interact directly with the user. Dialog boxes are ideal for situations where you need to make selections from the user. This could include entering data, choosing options, or confirming settings.
Before executing actions that have significant consequences, such as deleting data or applying major changes, a dialog box can be used to confirm the user's intent. This helps prevent accidental actions and ensures that the user is aware of the impact.
For example, when we want the user to choose what to do when a file is missing:
1procedure( askUser()
2 let( (answer)
3
4 answer = hiDisplayAppDBox(
5 ?name 'questionAppDBox
6 ?dboxBanner "*QUESTION* My App"
7 ?dboxText "A file is missing!\nYou can either create a new one, continue or abort."
8 ?dialogType hicQuestionDialog
9 ?buttonLayout 'UserDefined
10 ?buttons list("Create New File" "Continue" "Abort")
11 )
12
13 case( answer
14 ( 1
15 printf("Creating a new file\n")
16 )
17 ( 2
18 printf("Continuing\n")
19 )
20 ( 3
21 printf("Aborting\n")
22 )
23 );case
24 );let
25);procedure
Example of a dialog message
Here, we use ?buttons option to define the buttons. hiDisplayAppDBox() returns the number of the button clicked (1-based), which helps us to determine which logic to run after.
You can also provide callbacks to each button directly via the ?callback option:
1procedure( askUser()
2 hiDisplayAppDBox(
3 ?name 'questionAppDBox
4 ?dboxBanner "*QUESTION* My App"
5 ?dboxText "A file is missing!\nYou can either create a new one, continue or abort."
6 ?dialogType hicQuestionDialog
7 ?buttonLayout 'UserDefined
8 ?buttons list("Create New File" "Continue" "Abort")
9 ?callback list("createNewFile()" nil "abort()")
10 )
11
12 printf("Code continues here\n")
13);procedure
14
15
16procedure( createNewFile()
17 printf("Creating a new file\n")
18);procedure
19
20
21procedure( abort()
22 printf("Aborting\n")
23);procedureNote: Though, the clicked button runs a dedicated function, the code after the hiDisplayAppDBox() continues to run after the click. Also, if the callback is set to "nil", the button does nothing.
6. Functions - error(), warn() and info()
There is another way to show error, warning and informational messages. These functions print colored messages into the CIW, providing information for debugging without popping a box.
Overview:
- error() - prints an error message and halts the execution of the current script.
Output of the error() function
Note: The error() function halts code execution and prevents any subsequent script code from running.
- warn() - prints a warning message without halting script execution.
Output of the warn() function
- info() - prints an informational message.
Output of the einfo() function
To try these functions, replace hiDisplayAppDBox() with error(), warn(), and info() in the earlier examples for error, warning, and informational messages, respectively.
7. Conclusion
Mastering the use of messaging and debugging functions such as hiDisplayAppDBox(), error(), warn(), and info() is crucial for developing robust and user-friendly applications. These functions provide effective communication with users by providing immediate feedback and guidance. They also enhance error handling, ensuring that scripts run smoothly and efficiently.
Author: Eugeny Khanchin