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

Modeling/Annotator Communication: General Information

Table of Contents

General overview

Situation

The Annotation module of Creo Elements/Direct Modeling is a two process solution.

While activation the module a special version of Creo Elements/Direct Drafting is used as a client to execute commands given by Creo Elements/Direct Modeling.

All the interactive input capabilities of this Creo Elements/Direct Drafting are cut off. It does not output error messages or warnings to it's screen, either.

This Creo Elements/Direct Drafting will be totally controlled from Creo Elements/Direct Modeling. Inside this document this Creo Elements/Direct Drafting process is called Annotator.

The following document describes an interface enabling it's users to execute commands inside the Annotator described above. They also describe how to receive data in Creo Elements/Direct Modeling from Annotator .

The interface is delivered "as is" and will be subject to change in the future.

What the commands do is in your responsibility. Because it's easily possible to modify a drawing in a way it cannot be updated any more by the standard Annotation module functionality we recommend to read the documentation about what operations you should avoid.

First of all the Annotation module must have been activated in order to execute commands in Annotator .
Having done so a procedural interface to Annotator is established in order to

Target customer

The synergy of Creo Elements/Direct Modeling and Annotator requires extended knowledge and advanced programming skills in

So, the interface described in these documents should be used carefully with a good understanding of what is going on in Annotator and Creo Elements/Direct Modeling when executing commands.

Target customers of the interface are VARs, Application Engineers and experienced Creo Elements/Direct Modeling and Annotator customers.

Hints and Tips

Since the Annotator used in this solution is "blind" it is of no use trying to create Annotator User Interface (menus, tables, filebrowser, etc).
The commands to do so are not cut off but will not behave as expected. Any kind of textual output like the command line, prompt line, status line, Annotator viewport number and much more are not visible.
All this does not make it easier to develop Annotator macro code.

Avoid these commands

We recommend to write Annotator macros inside a pure and complete Annotator enviroment. You should avoid commands related to these areas:

In fact it does not make much sense to use the areas described above at all since there is an equivalend Creo Elements/Direct Modeling functioanlity for each single one.

Take good care on Annotator settings

There is one group of functionality that should be taken care of especially

Changing Annotator settings does work in any way you do it but you need to know that many settings are required to be known by Creo Elements/Direct Modeling.
A good example are the CATCH and SHOW settings. To keep MODELING_NAMEs as well as Annotator s settings in sync it is required to make Creo Elements/Direct Modeling to inform Annotator about settings changed since he always is the master in this master/slave situation.

... using tables

You can use commands related to these areas but you do need to totally control them from Creo Elements/Direct Modeling:

This exception is intended to be applicable when programming Drawing Frames containing text fields to be filled up by a PDM system like WorkManager.

Software and hardware exceptions

In addition certain hardware and software exceptions are transferred to Creo Elements/Direct Modeling.
The most important ones are

You don't have control over these kinds of events.

They can occur at any time whenever Annotator raised the exception. Since this indicates a severe programming error Annotator will be in an undefined state.

The error box describing the type of exception will pop up inside Creo Elements/Direct Modeling's graphical user interface immediately.

How to execute a Annotator command using Creo Elements/Direct Modeling LISP functions?

We provide a LISP function to send a command to Annotator .

How to return a valid LISP form to Creo Elements/Direct Modeling ?

We provide a LISP function to send a command to Annotator and receive it's result. This result must be a valid LISP form.

The command to be executed by Annotator must return LISP data to Creo Elements/Direct Modeling using the macros described below.
NOTE: these Annotator functions return a value that should be checked.

Opening the connection from Annotator to Creo Elements/Direct Modeling

let isopen (DOCU_OPEN_CONNECTION_TO_SD)
This function establishes the connection to Creo Elements/Direct Modeling. It has to be called before calling any of the functions below. It must not be called twice!

Adding lines to the stream buffer

let done (DOCU_ADD_LINE_TO_SD)
This function adds one line to the output stream connected to Creo Elements/Direct Modeling.
This line must be a Annotator string token.
This function may be called after having called (DOCU_OPEN_CONNECTION_TO_SD) only.
It may be called multiple times if required.

This function will just add the line given to the output stream buffer but not send the line. This must be done by calling:

Sending the buffer to Creo Elements/Direct Modeling

let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)
This function closes the connection to Creo Elements/Direct Modeling and notifies Creo Elements/Direct Modeling about it.
It must be called once after having called (DOCU_OPEN_CONNECTION_TO_SD) only.
It must not be called twice.

Actually, this command will flush all lines sent to SD.

Sending a string to Creo Elements/Direct Modeling

let lispstring (DOCU_CSTRING_TO_LSTRING 'c_string')
This function must be used to transfer string data to Creo Elements/Direct Modeling.
It may be called as many times as required.

The programmer must take special care on sending strings to Creo Elements/Direct Modeling. A Annotator function to transform a Annotator string into a LISP string has been provided:
In case the programmer wants to transfer a string inside a LISP form or another string to Creo Elements/Direct Modeling it is required to "escape" the double quote characters.
For example:

Example

These four functions can be used to solve e.g. the following task:
Task: "Inquire the unique part id of the current Annotator part from MODELING_NAME"

Solution 1: The straight forward approach

    ;; This is Creo Elements/Direct Modeling LISP code
    (setq Annotator -function (format nil "~A ~A ~A ~A ~A ~A"
                          "inq_part '.'"
                          "let pid (inq 302)"
                          "let pid_s    (DOCU_CSTRING_TO_LSTRING pid)"
                          "let isopen   (DOCU_OPEN_CONNECTION_TO_SD)"
                          "let done     (DOCU_ADD_LINE_TO_SD pid_s)"
                          "let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)"
              ) ;; end format
    ) ;; end setq
    (setq current-part (sd-execute-annotator-function :fnc Annotator -function))

will do the job.

Solution 2: As described here it is recommended to write a Annotator macro file and to call it:

{ This is Annotator  macro code }
DEFINE Am_send_unique_part_id
  inq_part '.'
  let pid (inq 302)
  let pid_s (DOCU_CSTRING_TO_LSTRING pid)
  (DOCU_OPEN_CONNECTION_TO_SD)
  (DOCU_ADD_LINE_TO_SD pid_s)
  (DOCU_CLOSE_CONNECTION_TO_SD)
END_DEFINE

After having loaded this macro into Annotator it can be called this way:

   ;; This is Creo Elements/Direct Modeling LISP code
   (setq current-part (sd-execute-annotator-function
                        :fnc "Am_send_unique_part_id")

Debugging data sent to Creo Elements/Direct Modeling

Developing Annotator macros becomes more difficult then in Annotator because there is no way to view the macro inside Annotator .

So, it's probably a good idea to use a real Annotator if available to develop the macro itself.
In this case the macros introduced to send LISP-data to Creo Elements/Direct Modeling cannot be used.

The macro must be loaded into the Annotator running as Annotation module.
You load the macro by adding an "INPUT" statement to Annotator 's startup file.
For prototyping it's probably more convenient to simply execute the "INPUT" command from within Creo Elements/Direct Modeling:

  ;; this is Creo Elements/Direct Modeling LISP code
  (sd-execute-annotator-command :cmd "INPUT 'yourfile.mac'")

Having loaded the macro you can call it by it's name:

  ;; this is Creo Elements/Direct Modeling LISP code
  (sd-execute-annotator-command :cmd "Am_your_macro")

In case your macro is supposed to return data to Creo Elements/Direct Modeling you need to call it using (sd-execute-annotator-function)

  ;; this is Creo Elements/Direct Modeling LISP code
  (sd-execute-annotator-function :fnc "Am_your_macro")

If your macro did not return what you expected it to return you can have a look on the data send by Annotator most recently:

  ;; this is Creo Elements/Direct Modeling LISP code
  (symbol-function 'docu::eval-result)

It's important to know that this statement must be executed right after having called your macro. Otherwise this information has potentially been overwritten by an other call to Annotator .

This is an example for what you could get.

(LISP::LAMBDA-BLOCK DOCU::EVAL-RESULT ()
  (LISP::LIST :DOCU-DRAWING "SD_drawing" "~1" ""
      (LISP::LIST
          (LISP::LIST :DOCU-SHEET "1" "~2" ""
              (LISP::LIST
                  (LISP::LIST :DOCU-FRAME ".tb_frame_A1" "~3" ""
                      (LISP::LIST)))))))

This is identical to this LISP list:

'(:DOCU-DRAWING "SD_drawing" "~1" ""
    ((:DOCU-SHEET "1" "~2" ""
         ((:DOCU-FRAME ".tb_frame_A1" "~3" "" LISP::NIL)))))

Limitations

There are a couple of limitations applicable.

  1. The maximum length of an Annotator command is limited to about 1000 Byte. This value is subject to change and can be inquired using 
           (sd-get-max-cmd-length)

  2. The maximum length of an Annotator function is limited to about 950 Byte. This value is subject to change and can be inquired using 
           (sd-get-max-fnc-length)

  3. The maximum amount of data that can be received by Creo Elements/Direct Modeling is limited to about 5MB. This value is subject to change and can be inquired using 
           (sd-get-max-return-data-size)

    It cannot be changed.
    In case you need to transfer more data write a file to the filesystem and return the command to load the file to Creo Elements/Direct Modeling.

  4. At the moment you must not call Annotator InterLink commands.
    These are

    This might change in the future.

  5. You must not use these general Annotator commands

Limitations 1. and 2. are not really new limitations since Annotator itself cannot handle input lines longer then 1024 Byte. In addition it is always possible to simply send two shorter commands to Annotator instead of one long command.

Almost no user will ever find limitation 3. applicable.

Limitation 4. is an important one and must not be violated.

Please note that none of these limitations will be checked.
It is your responsibility to follow the rules.

[Previous Page] [Next Page] [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