return
Allows you to exit a command file or macro and return to the command file or macro that invoked it. Its effect is similar to BREAK when you use it to exit a loop, skipping all remaining commands in the command file or macro (including any cleanup commands you may have at the end of your macro).
If a RETURN is executed within loops (nested to any depth), it exits those loops and performs all required cleanup, just as multiple BREAKs would do. You can have as many RETURN commands in your command files or macros as you want.
Format:
RETURN
Example:
RETURN is often used as a means of recovering from an error condition or allowing a user to cancel an operation. Below, are two examples.
Example 1
In the example, the RETURN command lists information on the contents of the select list, but only if there are objects on the list. If it finds no objects, it returns and issues an error message.
if condition=(DB_COUNT(.SELECT_LIST, "objects_in_group")==0)
mdi gui_utl_alert_box_1 type="Error" text="Select List is empty. Select objects first."
return
end !if
!
info empty
!
list_info group &
group_name = .SELECT_LIST &
brief = on &
write_to_terminal = on
!
Example 2
This example macro determines if a particular file exists and asks the user if it should overwrite the existing file.
variable create variable=$_self.fileName string="file.dat"
if condition=(file_exists($_self.fileName))
if condition=(alert("warning", "Delete existing "//$_self.fileName//"?", "Ok", "Cancel", "", 2) == 2)
variable create variable=$_self.junk &
int=(alert("information", "File "//$_self.fileName//" not destroyed.", "Ok", "", "", 1))
variable delete variable=$_self.*
return
end
variable create variable=$_self.junk &
int=(alert("information", "File "//$_self.fileName//" was destroyed.", "Ok", "", "", 1))
end
! Write the new file.
file text open file=($_self.fileName) open_mode=overwrite
file text close
! Clean up.
variable delete variable=$_self.*