#: 96 S0/EasyPlex 11-Dec-89 12:11 PST Sb: ADS Arcticle fr. C. Gauntlett, ADESK Fm: Jeffrey Pike [76702,531] To Whom It May Concern: The following is the article written by Cliff Gauntlett, Autodesk, discussing the use of ADS: The AutoCAD Development System (ADS) is being released as part of the OS/2 version of AutoCAD Release 10. A number of questions have been raised about how to write and ADS program. This tutorial is designed to give the reader a quick overview of how to do just that. In general, ADS programs which only communicate with AutoCAD should be portable across all platforms which support this new interface. There are some slight exceptions, however, but they are out of the scope of this article, and will be covered in much more detail in the ADS documentation. ADS consists of function libraries, header files, and documentation. The function libraries contain two types of utilities. The first category of functions is the interface facilities. These functions allow the program to communicate with AutoCAD and assist in the management of the communication buffer required to make the interface operate. The second category of functions is the general utility functions. These functions replicate, for the most part, functions which are currently available in AutoLISP. All of these functions are contained in a single library which is linked to the ADS program during the link process. The header files included with ADS are of the standard ".h" include file variety. These files include definitions for AutoCAD specific datatypes, function declarations, return and state codes, and other information which assists the user in writing the programs. These files should be included in all ADS programs to improve compatibility of the programs across AutoCAD releases. The actual contents of the files is better documented in ADS Programmer's Reference. Now, let's try and clairfy some of the above by using an example program. This program is a simple one which does nothing more than highlight an entity selected by the user. The reader should be warned that for simplicity in the example, no error checking was performed. The user should always check error returns to ensure integrity in the program. ---------------------------------------------------------------------------- 01 | #include 02 | #include "adslib.h" 03 | 04 | main(argc,argv) 05 | 06 | int *argc; /* argument count */ 07 | char *argv[]; /* argument vector */ 08 | { 09 | 10 | ads_name e; /* entity name */ 11 | ads_point p; /* selection point */ 12 | int scode = RSRSLT; /* ADS status code */ 13 | int stat; /* return status */ 14 | 15 | 16 | /* INITIALISE THE COMMUNICATION WITH ADS */ 17 | 18 | ads_init(argc,argv); 19 | 20 | 21 | /* EXECUTE COMMUNICATION LINK WITH ACAD */ 22 | 23 | for ( ;; ) { 24 | stat = ads_link(scode); 25 | 26 | if (stat != RQTERM) { /* must want us to do something */ 27 | switch (stat) { 28 | case RQXLOAD: /* register our function names */ 29 | ads_defun ("C:HIGHLIGHT",0); 30 | break; 31 | 32 | case RQXUNLD: /* unload our functions */ 33 | break; 34 | 35 | case RQSUBR: /* execute registered function */ 36 | ads_entsel("\nSelect object:",e,p); 37 | ads_redraw(e,3); 38 | break; 39 | 40 | default: 41 | break; 42 | } 43 | } 44 | else break; /* terminate the program (RQTERM) */ 45 | 46 | scode = RSRSLT; /* default return code */ 47 | } 48 | 49 | 50 | /* RQTERM RECEIVED, EXIT PROGRAM */ 51 | 52 | ads_exit(); 53 | 54 | 55 | /* END MAIN FUNCTION */ 56 | } ----------------------------------------------------------------------------- The first two lines of the program allow the user to include header files. The first is a standard "C" include files which provides delcarations, constants, and type definitions for communication with the console device. The second is a header file for ADS which in turn includes all the ADS header files. Throughout the explanation of this program reference will be made to items which are declared in these files. The actual declaration is not relevant to the discussion here, but the meaning of the declaration is relevant. Lines 4 through 7 of the example declare the main portion of the program and its arguments. Since AutoCAD executes this program, the meaning of these arguments is only relevant to AutoCAD and the ADS communications functions. "argc" is an integer which specifies the number of arguments given to the program. "argv" is an array of character pointers which are the actual arguments to the program. Under no circumstances should the user attempt to modify the contents of either of these variables. Line 8 is the opening brace of the program and line 56 is the closing brace. All of the program steps are included between these two braces. Lines 10 through 13 define the variables to used in the program. The first of these is a variable of type "ads_name" which has the label "e". "ads_name" is a data type defined in the ADS header files. It represents the name of an entity or of a selection set. The next variable is of type "ads_point" and has the label "p". It is an AutoCAD point which is an array of three real numbers (doubles in "C" talk!). The next two variables are both integers. One is "scode" which represents the ADS return status code. This is the status code which the ADS program returns to AutoCAD to inform it of the status of the operation performed in the program. The other is "stat" which is the status sent by AutoCAD to the program to tell it what to do. Line 18 performs a call to one of the ADS communication functions, "ads_init". This function is responsible for establishing the communications link between the ADS program and AutoCAD. This should always be the first function called from the program. The arguments passed to this function are the same as the arguments passed by AutoCAD to the program. The section of the program that begins at line 23 is the main part of the program. This is where everything REALLY takes place. The first line of this section, line 23, begin execution of a for loop which ends on line 46. This for loop is designed to run forever. It contains no conditional exit statement so that the main program loop will continually execute. There are many ways to accomplish this loop, but for simplicity, this example uses this loop. The first thing the main program section must do is "link up" with AutoCAD. This is accomplished in line 24 with the call to "ads_link" which is another ADS communications function. "ads_link" is responsible for managing the communications buffer between AutoCAD and the ADS program. It has a single argument which is the return state to pass to AutoCAD to tell it what happened in the ADS program. The value of this return state was initialised to "RSRSLT" which is a declaration from the ADS header file. This value specifies that the program is waiting for instructions from AutoCAD. "ads_link" returns control to AutoCAD and waits for AutoCAD to issue its next instruction. When AutoCAD wakes up the ADS program, it returns to control to the "ads_link" function and passes it a status which "ads_link" then returns to the ADS program. This returned state is stored in the "stat" variable. Currently, "stat" may have one of four values, all of which are used in this program. The first return status value is RQTERM (again a value declared in the ADS header files). This is AutoCAD's way of telling the ADS program to terminate. This is checked for in the "if" statement in line 26. If AutoCAD is requesting a termination of the program, then control in the program jumps to line 44 where the for loop is broken and then to line 51 where the program terminates. This is the only way that this program can terminate. The for loop will continue forever until an RQTERM is received. The switch statement which begins at line 27 and ends at line 42 provides a mechanism for dealing with multiple cases of a variable state. In this case, the switch statement handles the other three AutoCAD request states. RQXLOAD is the first of these. Every ADS program must register its functions with AutoCAD. This way AutoCAD knows which ADS program to call when the user executes an ADS function or command. RQXLOAD function is AutoCAD's request state which tells the user to register its functions. The call to "ads_defun" on line 29 of the example is the ADS library function which registers commands and functions with AutoCAD. The first argument is the name of the function, and the second argument is a positive integer which is a function code to be associated with the command. This function code allows an ADS program to register many commands with AutoCAD. When AutoCAD requests that the program execute one of its commands, it passes the function code of the command to the ADS program. The example program registers a single command called "HIGHLIGHT", so there are no checks for the function code. Notice that the "C:" prefix is used here to define the function as an AutoCAD command (this is the same as AutoLISP). If the user had wanted to define an AutoLISP function, the "C:" prefix would need to be eliminated. The next request code is RQXUNLD. This AutoCAD request is made to let the ADS program know that the user has requested that this program be unloaded from AutoCAD. This example does not use this feature, so its explanation is left for a future tutorial. The last request code is RQSUBR. This is the request AutoCAD makes when the user has executed on of the registered functions associated with this ADS program. It is at this point that the program should check to see which function was executed if more than one function was registered. Line 36 prompts the user for an entity selection. The name of the entity picked is stored in the variable "e" and the point used to select the entity is stored in the variable "p". For AutoLISP users, this is the same as performing an "entsel". The next line, performs the highlight of the entity. This is the same as the "redraw" function in AutoLISP. At line 45 the ADS return status code is set to RSRSLT, and the for loop begins its execution again with the call to "ads_link". The "default" case at line 40 is provided for portability between compilers. This program would need to be compiled with an appropriate compiler and linked with a linker to the ADS library. Under OS/2, Microsoft C version 5.1 or greater can be used to do this. Specifics on compiler and linker switches are documented in the ADS Programmer's Reference. On the AutoCAD side of things, the user would type the following to load and execute this program. Command: (xload "example") C:HIGHLIGHT Command: HIGHLIGHT Select object: Command: The "xload" function loads the program "example". This is similar to the AutoLISP (load) function. AutoCAD executes the ADS program which calls the "ads_init" and "ads_link" functions. "ads_link" returns an RQXLOAD request which the ADS program processes by defining the HIGHLIGHT command. The ADS program then returns control back to AutoCAD. When the user types HIGHLIGHT, AutoCAD sends an RQSUBR request to the ADS program which then processes the command and returns to AutoCAD to wait for the next RQSUBR. Of course, a program like this example would probably be better done in AutoLISP than with an ADS program. In future tutorials more in depth discussions of ADS and more complex examples will be used. In the meantime, good luck and good hunting. Action!