[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]

Calling an Action Routine from within a User Command

Function Index Top of Page

SD-CALL-CMDS  [macro]

(sd-call-cmds form
              :success success-form
              :failure failure-form
Description:
This macro has to be used whenever you want to call an Action Routine (either an existing Creo Elements/Direct Modeling command or a User Action) from within a User Action.

There are several restrictions for nested action routine calls:

Parameters:
form {LISP form}
Any Lisp form which may contain any number of Action Routine calls (either existing Creo Elements/Direct Modeling commands or User Actions).
success-form {LISP form}
A Lisp form which is evaluated when the form does not cause an error.

During the evaluation of the success-form, the global variable *SD-ACTION-RESULT* is bound to the action result of the last action routine that was called within the form.

The default value for the success-form is

  *sd-action-result*
              
failure-form {LISP form}
A Lisp form which is evaluated when the form causes an error.

Information about the error can be inquired via the sd-inq-error-obj function. One of the following error codes will be returned by (sd-inq-error-obj :code):

"SD-CALL-ACTION-ILLEGAL-CALL"
An action routine was called from an illegal context. See above for restrictions on the calling context.
"SD-CALL-ACTION-INTERACTION-REQUIRED"
A called action routine tried to become interactive.
"SD-CALL-ACTION-THROW"
A non-local exit (e.g., via throw) occurred.
(sd-inq-error-obj :object) will return (tag . value), where tag and value describe the exit.
"SD-CALL-ACTION-ESCAPE"
A C++ exception occurred.
(sd-inq-error-obj :object) will return (module . error), where module and error are strings describing the exception.
"SD-CALL-ACTION-ERROR"
A generic error occurred.
(sd-inq-error-obj :message) will return the string that was passed to sd-display-error.

NOTE: The message may be localized, therefore it is not allowed to use string comparisons for determining the exact cause of the error. The only legal way to use the message is to display it.

The default value for the failure-form is

  (progn
    (sd-display-error (sd-inq-error-obj :message))
    nil)
              
Note: sd-call-cmds may not trap errors correctly if they occur outside an action call. The throw in the following code fragment will not be caught by the sd-call-cmds form:
  (sd-call-cmds
    (progn
      (my_action_1 ...)
      (throw 'foo 'bar)
      (my_action_2 ...)))
              
To handle the throw, an additional catch is needed:
  (catch 'foo
    (sd-call-cmds
      (progn
        (my_action_1 ...)
        (throw 'foo 'bar)
        (my_action_2 ...))))
              

Return value:
On success
sd-call-cmds returns the result of evaluating the success-form. The default if no success-form is given is to return the action result of the last action called within the form (NOTE: The action result may be undefined).
On failure
sd-call-cmds returns the result of evaluating the failure-form. The default if no failure-form is given is to display an error message and to return NIL.

Examples:
1. Call of a regular function which contains calls to Creo Elements/Direct Modeling commands:

   (defun create-slot (p1 p2 width)
     (let (p1p2
           normal
           offset-vec)
       
       ;;----- Calculation: -----
       (setq p1p2 (sd-vec-subtract p2 p1))
       
       ;; Calculate Normal of p1p2 vector:
       (setq normal (make-gpnt2d :x (- (gpnt2d_y p1p2)) y: (gpnt2d_x p1p2)))
       
       ;; Normalize Normal:
       (setq normal (sd-vec-normalize normal))
       
       ;; Calculate Offset Vector:
       (setq offset-vec (sd-vec-scale normal (/ width 2.0)))
       
       ;; Create infinite construction lines through the center points:
       (c_line_inf :two_points p1 p2)
       (c_line_inf :two_points p1 (sd-vec-add p1 offset-vec))
       (c_line_inf :two_points p2 (sd-vec-add p2 offset-vec))
       
       ;; Create Slot:
       (line :two_points (sd-vec-add p1 offset-vec) (sd-vec-add p2 offset-vec))
       (line :two_points (sd-vec-subtract p1 offset-vec)
             (sd-vec-subtract p2 offset-vec))
       (arc :center p1 (sd-vec-add p1 offset-vec)
            (sd-vec-subtract p1 offset-vec))
       (arc :center p2 (sd-vec-subtract p2 offset-vec)
            (sd-vec-add p2 offset-vec))))

   ;; in a User Action:
   (sd-call-cmds (create-slot point_1 point_2 width))

;;-----------------------------------------------------------------------------

2. Call of a command which is built at run-time:

   (let* ((point_1 10,10)
          (point_2 100,100)
          (cmd `(rectangle ,point_1 ,point_2)))
     (eval `(sd-call-cmds ,cmd)))
   
;;----------------------------------------------------------------------

3. Call of a list of commands built at run-time:

   (let ((point_1 10,10)
         (point_2 100,100)
         (cmd nil))
     (setq cmd `((line :two_points ,point_1 ,point_2)))
     (setq cmd (nconc cmd `((rectangle ,point_1 ,point_2))))
     (eval `(sd-call-cmds (progn ,@cmd))))

Function Index Top of Page

SD-CALL-ACTION-ACTIVE-P  [function]

(sd-call-action-active-p)
Description:
This predicate can be used in User Actions to check whether the action was called in the context of sd-call-cmds.

Return value:
t
If this function is called within an Action Routine that was called via sd-call-cmds.
nil - otherwise

[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]
© 2023 Parametric Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved