1
Copyright © 2000 Environmental Systems Research, Institute, Inc.
All Rights Reserved.
Printed in the United States of America.
The information contained in this document is the exclusive property of Environmental Systems Research Institute, Inc. This work is protected under United States copyright law and the copyright laws of the given countries of origin and applicable international laws, treaties, and/or conventions. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying or recording, or by any information storage or retrieval system, except as expressly permitted in writing by Environmental Systems Research Institute, Inc. All requests should be sent to Attention: Contracts Manager, Environmental Systems Research Institute, Inc., 380 New York Street, Redlands, CA 92373-8100 USA.
The information contained in this document is subject to change without notice.
U.S. GOVERNMENT RESTRICTED/LIMITED RIGHTS
Any software, documentation, and/or data delivered hereunder is subject to the terms of the License Agreement. In no event shall the U.S. Government acquire greater than RESTRICTED/LIMITED RIGHTS. At a minimum, use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR §52.227-14 Alternates I, II, and III (JUN 1987); FAR §52.227-19 (JUN 1987) and/or FAR §12.211/12.212 (Commercial Technical Data/Computer Software); and DFARS §252.227-7015 (NOV 1995) (Technical Data) and/or DFARS §227.7202 (Computer Software), as applicable. Contractor/Manufacturer is Environmental Systems Research Institute, Inc., 380 New York Street, Redlands, CA 92373-8100 USA.
ESRI, ArcView, MapObjects, and ARC/INFO are trademarks of Environmental Systems Research Institute, Inc., registered in the United States and certain other countries; registration is pending in the European Community. Spatial Database Engine, ArcSDE, GIS by ESRI, the ArcSDE CAD Client logo, and the ESRI globe logo are trademarks and www.esri.com is a service mark of Environmental Systems Research Institute, Inc. Other companies and products mentioned herein are trademarks or registered trademarks of their respective trademark owners.
2 Using SDE CAD Client Contents
ArcSDE CAD Client 3 What Is ArcSDE CAD Client? 3 Who Is ArcSDE CAD Client For? 4 What Tasks Can You Perform with ArcSDE CAD Client? 5
Installing ArcSDE CAD Client 7 System Requirements 7 Installing ArcSDE CAD Client 7
The ArcSDE Environment 13 ArcSDE Requirements 13 Creating SDE Tables and Layers 14 Testing the ArcSDE Connection 15
Storing and Retrieving Data 21 Connecting to ArcSDE 21 Storing CAD Data in ArcSDE 22 Retrieving Data from ArcSDE 33 Changing the Store and Retrieve Settings 39
Editing ArcSDE Layers 43 Accessing Data for Editing 43 Committing Edits to ArcSDE 46 Viewing and Modifying Tabular Data 47 Removing Data from ArcSDE 48
Customizing ArcSDE CAD Client 51 Overview of the ArcSDE CAD Client API 51
3
CHAPTER 1 ArcSDE CAD Client
Computer-aided design (CAD) systems create and edit much of an organization’s infrastructure and utility data such as road, parcel, survey, water, sewer, transmission, or construction data. To effectively manage and integrate this diverse data into an organization’s enterprise processes requires storing multiple data formats, centralized storage, easy access by multiple users, and a secure environment. ArcSDE™ CAD Client provides these capabilities. Spatial Database Engine™ (ArcSDE) software, from Environmental Systems Research Institute, Inc. (ESRI), provides a way to serve large amounts of spatial data quickly to many different users and incorporates a central data source into the various processes of an organization. ArcSDE CAD Client, the CAD component of ArcSDE, integrates your CAD data with ArcSDE spatial data to maintain your organization’s investment in CAD systems.
What Is ArcSDE CAD Client?
ArcSDE is a nontiled spatial data server designed for a multiuser environment. With ArcSDE you can perform high-speed searches and retrieval of spatial features stored within a relational database. Along with a flexible environment for application development, ArcSDE takes advantage of security options provided by the relational database to maintain the integrity of the data in the shared environment.
ArcSDE CAD Client is an add-on application to AutoCAD or MicroStation and provides tools to store, retrieve, and edit CAD and SDE format data from an ArcSDE server. The ArcSDE CAD Client functions are available both from pulldown menus and from an
4 Using ArcSDE CAD Client
application programming interface (API). The ArcSDE CAD Client API permits you to customize the software using scripting languages specific to the host CAD application such as AutoLISP® and ARX for AutoCAD, MicroStation® BASIC and MDL for MicroStation, and the ActiveX Automation API for both CAD hosts.
CAD data can be stored through ArcSDE CAD Client both geographically as SDE shapes and as the original CAD data in its native format. When native CAD data is stored, the entire CAD data, with its associated properties, attributes, and geometry, can be retrieved into its native CAD environment as the CAD editor originally created it.
You can also store the data properties as feature attribute information (such as color, layer name, line type) within ArcSDE software’s relational database. The spatial and attribute data stored by ArcSDE CAD Client can be read by any ArcSDE client application such as ArcView® GIS, ARC/INFO®, or MapObjects® software.
MicroStation AutoCAD
SDE CAD Client
Custom Enterprise Applications SDE Processes
MapObjects ARC/INFO ArcView GIS
When stored geographically, CAD data is converted by ArcSDE CAD Client into SDE features. ArcSDE CAD Client provides spatial operators and Structured Query Language (SQL) query tools that allow you to select data based on area, proximity, and attribute values.
Who Is ArcSDE CAD Client For?
ArcSDE CAD Client is designed for the organization whose processes rely on data from both CAD and geographic information system (GIS) software. By incorporating data from CAD and GIS into a seamless database, communication between disciplines is enhanced, and
Chapter 1 ArcSDE CAD Client 5
enterprisewide processes are made more efficient. Because ArcSDE CAD Client drawings store drawing data through ArcSDE, other ArcSDE clients such as ArcView GIS, ARC/INFO, or MapObjects can also view the data.
For example, those ArcSDE users in a GIS department can access drawing databases developed and maintained by an engineering department in the enterprise. Conversely, CAD users can use ArcSDE CAD Client to access GIS data stored in SDE layers.
Many types of users will use ArcSDE CAD Client to build, store, and maintain data including
• CAD operators wanting to access GIS data • GIS/ArcSDE users wanting to use the editing tools of a CAD application • Organizations with a large investment in CAD resources • GIS users who want to interoperate with CAD data • Large enterprise organizations using ESRI® software • People who want to create and edit ArcSDE databases from CAD data • ArcSDE application developers • CAD application developers What Tasks Can You Perform with ArcSDE CAD Client?
ArcSDE CAD Client can be used to create, view, and edit SDE layers. Through ArcSDE CAD Client, CAD data can be stored as SDE shapes and/or CAD drawing data and be accessed by any ArcSDE client application.
7
CHAPTER 2 Installing ArcSDE CAD Client
System Requirements
Before you install ArcSDE CAD Client, make sure your host CAD application is properly installed and configured. ArcSDE CAD Client will work with the following CAD applications:
• MicroStation 95 • MicroStation J • AutoCAD Release 14 • AutoCAD Release 14.01 • AutoCAD Release 2000 ArcSDE CAD Client also requires an ArcSDE-supported relational database management system (RDBMS) server running SDE Version 3.0 through ArcSDE 8. ArcSDE CAD Client will run with the following operating systems:
• Windows NT 3.51 • Windows NT 4.0 • Windows 95 • Windows 98 • Windows 2000 For general information on setting up ArcSDE, consult your ArcSDE documentation.
Installing ArcSDE CAD Client
To set up ArcSDE CAD Client, close all unnecessary applications, then run the program setup.exe located on the distribution media. The setup program will guide you through the installation process. You will be asked to select the host CAD application and a folder in which ArcSDE CAD Client will be installed.
8 Using ArcSDE CAD Client
When installing ArcSDE CAD Client, it is recommended that you install ArcSDE CAD Client to a folder whose name does not exceed eight characters.
If you choose to install ArcSDE CAD Client to a path that has a long folder name, you should modify the Start In folder of the CAD application’s Desktop Properties. To modify the Start In folder, right click on the desktop shortcut of the host CAD application and select Properties from the menu selections. Select the Shortcut tab, and then enter the path to ArcSDE CAD Client, for example, “C:\Program Files\AutoCAD R14\scclient”. After setting the Start In folder, you can start ArcSDE CAD Client from a location containing long folder names.
You must add the ArcSDE instance to the operating system services file. The services file on the Windows NT platform is located under the winnt\system32\drivers\etc folder. The ArcSDE Administration Guide contains detailed information about setting the ArcSDE instance.
Updating the System Path
The path to the folder containing ArcSDE CAD Client must be manually added to the system environment path for Windows NT or the autoexec.bat for Windows 95 or Windows 98.
Windows NT 3.51, Windows NT 4.0, or Windows 2000 1. Go to the Control Panel. 2. Double click the System icon to open the System Properties dialog box. 3. Select the Environment panel. 4. Add the ArcSDE CAD Client path to the system path variable (e.g., “C:\Program Files\AutoCAD R14\scclient”). Windows 95 or Windows 98 1. Open the autoexec.bat file in Notepad (or a similar text editor). 2. Add the ArcSDE CAD Client path to the Path environment variable (e.g., “PATH = C:\Program Files\AutoCAD R14\scclient”). To connect to an ArcSDE server, your Windows services file must contain an entry that identifies the TCP/IP port number that ArcSDE communicates on. This services file is located in “%windir%\system32\drivers\etc” folder and may be modified with a text editor. Check with your ArcSDE administrator for the correct ArcSDE service name and number.
Chapter 2 Installing ArcSDE CAD Client 9
MicroStation Setup
When installing ArcSDE CAD Client for MicroStation, you will need to modify your MicroStation configuration in order to run ArcSDE CAD Client successfully. First, you must add the ArcSDE CAD Client path to the Primary Search Path for MDL applications within the current MicroStation workspace.
Use the following steps to add the ArcSDE CAD Client path to MicroStation.
1. From the Workspace pulldown menu, choose Configuration. This will display a dialog box titled Configuration. 2. Highlight the Primary Search Path category and click on MDL Applications under Set default search paths for locating files. 3. Click Select and browse to the folder where the scclient.ma file is stored. 4. Be sure to click Add to add the folder path and then click Done. Next, you must add the ArcSDE CAD Client menu.
Use the following steps to add the ArcSDE CAD Client menu to the MicroStation interface.
1. Start MicroStation. 2. When opening a drawing from MicroStation, choose cadclient from the available MicroStation interfaces. 3. From the MicroStation Manager, select the SDE menu choice from the Interface pulldown list. The MicroStation Manager allows you to select a drawing to open as well as environment options like Workspace, Project, Interface, and Style. As part of the installation procedure, the ArcSDE CAD Client menu is integrated with the MicroStation menu selections available through the MicroStation Manager.
10 Using ArcSDE CAD Client
The following graphic displays the interface previously described.
For detailed information on configuring MicroStation, please consult your MicroStation documentation.
Chapter 2 Installing ArcSDE CAD Client 11
AutoCAD Setup
When installing ArcSDE CAD Client for AutoCAD, you will need to modify your AutoCAD configuration in order to run ArcSDE CAD Client successfully. First, add the ArcSDE CAD Client installation path to AutoCAD’s Support Files Search Path.
1. From the Tools pulldown menu, choose Preferences. 2. Within the Preferences dialog box, select Support File Search Path located in the Files panel. 3. Choose Add, then browse to the ArcSDE CAD Client folder. Use the following steps to add the ArcSDE CAD Client menu to AutoCAD.
1. From the command line, type Menuload or choose Customize Menus from the Tools pulldown menu. 2. Choose Browse and browse to the ArcSDE CAD Client folder. Select the file scclient.mnu. 3. Load scclient.mnu as a Menu Group. 4. Click on the Menu Bar tab and select EsriCadClient from the list of Menu Groups as shown below.
12 Using ArcSDE CAD Client
5. Select SDE from the Menus list and insert the menu into the Menu Bar list as shown below.
6. Choose Close and the SDE menu will display on the Menu Bar.
Loading ArcSDE CAD Client
To load ArcSDE CAD Client for both AutoCAD and MicroStation, follow these steps:
1. Launch your CAD host and open a new or existing drawing file. 2. From the SDE pulldown menu, choose CAD Client, then choose Load.
Note: Use the Unload command to unload ArcSDE CAD Client.
13
CHAPTER 3 The ArcSDE Environment
ArcSDE is managed by an ArcSDE administrator. The ArcSDE administrator uses the underlying relational database management system (RDBMS) to manage and configure ArcSDE for data storage and retrieval. The ArcSDE administrator also creates user accounts and defines security options that determine how you can use SDE data. This chapter contains basic information regarding the interaction of ArcSDE CAD Client with ArcSDE.
ArcSDE Requirements
ArcSDE CAD Client does not require any special installation or configuration of the SDE server. Layer creation, including table definition and indexes, follows the guidelines as described in the SDE Administrator’s Guide. The following information will be useful when configuring ArcSDE to efficiently store and maintain your CAD data.
• Data description. • The users of this data. • Permissions required by users. • Types of CAD data to be stored. • CAD properties and attributes to be stored. • Average graphical sizes of linear and polygonal CAD data. • Number of vertices for average linear and polygonal CAD entities. • The amount of CAD data to be loaded into ArcSDE. • Average area to be queried by users of the data. • The minimum and maximum extents of the CAD data. If any of the data has negative coordinates, a false x and y offset must be applied. The offset shifts the coordinate system of ArcSDE, allowing the storage of CAD data with negative coordinates.
14 Using ArcSDE CAD Client
• The accuracy of the CAD data. SDE can be adjusted to efficiently maintain the accuracy of CAD data stored as features. Once ArcSDE is configured and ready for use, the SDE tables and layers can be optimized to efficiently perform storage and retrieval tasks. Information on optimizing ArcSDE for storage and retrieval can be found in the ArcSDE Tuning Guide for your relational database.
Creating SDE Tables and Layers
To store data and related attribute information in ArcSDE, you first define business tables and layers. Layers should be created to use homogeneous feature classes. When defining the layer specify entity types so that distinct features classes are stored per layer, e.g., points, lines, simple lines, or areas. Combinations of sde entity types can still be used when defining the layer. The following table and layer definition examples show the possible ArcSDE entity types that can be used when defining a layer to store point features.
The following example script creates business tables and layers using the ArcSDE administration functions sdetable and sdelayer. While these examples show column names that are identical to the CAD properties that ArcSDE CAD Client can store to the business table, you can choose your own column names for the attributes. It is recommended that you use the data types and sizes for the associated CAD properties specified below. As attribute information varies between AutoCAD and MicroStation, examples are given for each. Examples for creating SDE business tables and layers for AutoCAD to store point features
sdetable -o create -t actest -i esri_sde -s sdeserver -u cad -p cad -d “angle double(12,5), color integer(8), drawingname string(255), elevation double(12,5), entityhandle string(16), entitytype string(64), layername string(32), linetype string(255), linewidth double(12,5), linethickness double(12,5), refname string(255), textstyle string(255), textvalue string(255)”
sdelayer -o add -l actest,ac -e np3+McA -g 1000,0,0 -x -100,-100,100 -z -100,100 -i esri_sde -s sdeserver -u cad -p cad
Examples for creating SDE business tables and layers for MicroStation to store points features
sdetable -o create -t mstest -i esri_sde -s sdeserver -u cad -p cad -d “angle double(12,5), cellname string(8), color integer(8), drawingname string(255), elevation double(12,5), entityhandle string(8), fillcolor integer(8), levelnumber integer(8), levelname string(255), linetype string(255), lineweight integer(8), textvalue string(255), entitytype integer(8), catent1 integer(8), mslink1 integer(8)”
sdelayer -o add -l mstest,ms -e nplsa3+McA -g 1000,0,0 -x -100,-100,100 -z -100,100 -i esri_sde -s sdeserver - u cad -p cad
Note: Details on the syntax and options of the sdetable and sdelayer administrative functions can be found in the ArcSDE Administrator’s Guide.
Chapter 3 The ArcSDE Environment 15
Testing the ArcSDE Connection
Before using ArcSDE CAD Client, you should test your connection with the ArcSDE server using the SDE Test utility program. SDE Test displays basic information about your SDE business tables and layers. You can access SDE Test from the SDE menu. From the SDE pulldown menu, choose Utilities, then choose SDE Test.
The SDE Test utility opens a dialog box where you enter the user name, password, ArcSDE server, ArcSDE instance, and data source. You can obtain these required connection parameters from your ArcSDE adminstrator.
If SDE Test does not connect to ArcSDE, verify that ArcSDE, the RDBMS, and the network are installed, running, and communicating with each other. You must have an account on the RDBMS server for ArcSDE CAD Client and SDE Test to connect and retrieve ArcSDE instance information.
16 Using ArcSDE CAD Client
Using SDE Test
Once SDE Test is connected to the server, the ArcSDE Instance Information dialog box provides you with a list of instance and database properties such as the instance name, ArcSDE version, and number of connections. Below that is a list of available layers. Select a layer, and layer-specific information is displayed in the Layer Properties list box. The next section explains the contents of each list box.
Chapter 3 The ArcSDE Environment 17
Instance and Database Information
The Instance/Database Properties list box describes how the instance was defined and includes ArcSDE version, maximum connections, and maximum number of layers. The following table describes information displayed in the Instance/Database Properties list box.
Instance/Database Properties
Data Set Property Property Description
Instance name Instance of ArcSDE
ArcSDE version Version of the ArcSDE instance
Host database Name of host RDBMS
ArcSDE server path Location of the ArcSDE home directory on the server
Database name (optional) Name of the open database connectivity (ODBC) data source required to connect to a database by some RDBMSs (for example, SQL Server)
Maximum connections Maximum number of concurrent connections allowed
Current connections Number of clients currently connected to the ArcSDE server. Double click to display a list of the currently connected users.
Maximum number of layers Maximum number of layers that can be defined
Actual number of layers Number of layers currently defined
Versions Description of available versions (ArcSDE 8 only) Note: When using ArcSDE CAD Client with ArcSDE 8, ArcSDE CAD Client always uses the default version.
Layers
The Layers list box displays the SDE layers that are defined in the current connection. Selecting a layer will prompt SDE Test to list detailed information about the layer in the Layer Properties list box.
Layer Properties
The Layer Properties list box describes how the selected layer is defined including security settings and available feature classes. The following table describes information displayed in the Layer Properties list box.
18 Using ArcSDE CAD Client
Layer Properties
Layer Property Property Description Layer name The layer name (displayed as User_name.businesstable.spatial_column) Description Description of the layer Layer ID Numeric value identifying the internal map layer Storage type Type of ArcSDE storage Permissions Access permissions available to the current user Creation date Date and time layer was created Projection Projection of layer
XY scale factor Number of system units for one unit of measure or degree of resolution in the x,y plane X offset The offset of the origin in the x direction Y offset The offset of the origin in the y direction Z scale factor Number of system units for one unit of measure or degree of resolution in the z plane Z offset The offset of the origin in the z direction M scale factor The data’s measure scale in system units M offset Measure offset Minimum X coord Minimum X coordinate of layer
Minimum Y coord Minimum Y coordinate of layer
Maximum X coord Maximum X coordinate of layer
Maximum Y coord Maximum Y coordinate of layer
Minimum Z coord Minimum Z coordinate of layer
Maximum Z coord Maximum Z coordinate of layer Multipart features Shows if multipart features are allowed in the layer Feature classes Feature classes allowed in layer Grid sizes Grid sizes of the layer’s spatial index
Columns Attribute columns defined in the business table
Chapter 3 The ArcSDE Environment 19
Statistics
Use the Statistics button to generate statistics about the currently selected layer. As the entire layer is processed to obtain these statistics, a layer with a large amount of data may take longer to process than a layer containing a small amount of data.
Statistics Displayed in SDE Test
Statistics Property Property Description Extent lower left Minimum x,y coordinate for bounding area of all feature data Extent upper right Maximum x,y coordinate for bounding area of all feature data Feature counts Number of features stored in each feature class
Copy
The Copy function copies the information in the Layer Properties list box to the Windows clipboard.
21
CHAPTER 4 Storing and Retrieving Data
ArcSDE CAD Client can be used to add and retrieve data to and from SDE layers. Through ArcSDE CAD Client, CAD data can be stored and retrieved as SDE features and/or CAD objects.
Connecting to ArcSDE
Before storing to or retrieving data from ArcSDE, you first need to connect to an ArcSDE server. To connect to ArcSDE, use the Login command and enter your ArcSDE account information. From the SDE menu, choose Login. Once you have filled in all the required fields, choose OK to connect to ArcSDE.
22 Using ArcSDE CAD Client
Fill in the SDE Login dialog box with the following information: Username: Name of ArcSDE user
Password: Password for username
Server: The machine name or the IP address of the server running ArcSDE
Instance: The instance of ArcSDE to connect to. The default instance is esri_sde.
Database: The name of the ODBC data source. This is only required for RDBMSs whose clients connect using ODBC drivers. This is optional for other ArcSDE servers.
Your ArcSDE account determines what operations you can perform. For example, if the permissions granted to your ArcSDE account are “read only,” you may only retrieve SDE features and cannot edit or update them. Check with your ArcSDE administrator for the permissions available to you.
When you log in to ArcSDE, the available layers and their metadata are cached. If a new SDE layer is added or an existing layer is deleted, ArcSDE CAD Client will not be able to recognize these changes until you refresh the connection with your server. To refresh your ArcSDE connection, choose the Login command and press the OK button while leaving all the input fields unchanged.
Storing CAD Data in ArcSDE
To store CAD data, select Store from the SDE menu. This opens the Store dialog box. From the Store Template drop-down list, choose a Store template or select the Open File button to browse to a folder containing the Store template you wish to use. Choose OK to begin storing data to ArcSDE.
ArcSDE CAD Client stores data from the drawing based on options set in a store template. CAD data can be stored as SDE features and optionally as native CAD data, complete with associated properties, symbology, and geometry.
Chapter 4 Storing and Retrieving Data 23
When you press OK, ArcSDE CAD Client selects the specified CAD data from the drawing and converts it to SDE shapes. The data is then stored in the specified SDE layer. The store template determines what additional data is stored.
Two-dimensional area entities are converted to SDE area features, linear entities are converted to SDE line features, and point entities are converted to SDE point features. If ArcSDE CAD Client is configured to store text as annotation, then text and dimension entities are converted to annotation. CAD splines and curves are automatically converted to segmented line using the current curve tolerance setting.
Maintaining Data Integrity
To maintain the integrity of the original CAD data, ArcSDE CAD Client allows you to store and retrieve CAD drawing data, called CAD objects.
A CAD Object may be either an AutoCAD entity or a MicroStation element. A CAD Object refers to the native CAD data as it was originally created in the host CAD application. The native CAD data is maintained including the exact geometry, symbology, CAD properties, and user attributes.
The CAD Object stored in ArcSDE is only available through ArcSDE CAD Client and can only be accessed through the originating host CAD application. CAD objects are stored as native CAD data and are linked directly to their associated SDE features. Limited data translation occurs when the CAD Object is stored in ArcSDE; the entity remains just as it existed in the host CAD application.
24 Using ArcSDE CAD Client
The following table lists the AutoCAD entities and MicroStation elements that are stored as SDE area features.
Areas
AutoCAD R14 MicroStation
3D face Shape 3D polyline, closed Conic Circle, 2D Complex shape (complex) Circle, 3D Ellipse Donut Ellipse, closed Hatch, nonassociative Hatch, associative LWPolyline, closed Mline, closed Solid Spline, closed Spline, 3D closed Group
The following table lists the AutoCAD entities and MicroStation elements that are stored as SDE line features.
Lines
AutoCAD R14 MicroStation
3D polyline, open Line Arc Line string Ellipse, open arc Curve Line, 2D Complex string (complex) Line, 3D arc B-spline curve (complex) LWPolyline, open Multiline element Mline, open Spline, open Spline, 3D open Trace Leader, spline Leader, arrow Leader, mtext Group
Chapter 4 Storing and Retrieving Data 25
The following table lists the AutoCAD entities and MicroStation elements that are stored as SDE point features.
Points
AutoCAD R14 MicroStation
3D polygon mesh, box Cell library header 3D polygon mesh, cone Text node (complex) 3D polygon mesh, dish Text 3D polygon mesh, dome Surface (complex) 3D polygon mesh, mesh Solid (complex) 3D polygon mesh, pyramid Point string 3D polygon mesh, sphere B-spline surface (complex) 3D polygon mesh, torus Dimension element 3D polygon mesh, wedge Shared cell element 3D solid, box Raster header 3D solid, cone Raster reference attachment 3D solid, cylinder 3D solid, sphere 3D solid, torus 3D solid, wedge Block, no attributes Block, attributes Dimension, aligned Dimension, rotated Dimension, radius Dimension, diameter Dimension, 2 line angular Dimension, ordinate Image Mtext Plain text Point, 2D Point, 3D Ray Region Shape Tolerance X-line Xref, attach Xref, overlay Leader, spline Leader, arrow Leader, mtext Group
26 Using ArcSDE CAD Client
The following table lists the AutoCAD entities and MicroStation elements that are stored as SDE annotation for point features.
Annotation
AutoCAD R14 MicroStation
Text Text Mtext Dimension Dimension
Understanding the Store Template
The store template is required to store CAD data in ArcSDE. A store template is a set of parameters that determine how data is stored to an SDE layer. Templates are stored as individual files with a file extension of .ccst.
The template specifies three important facets of the store operation.
• Destination - the SDE layer to which features will be stored • Selection - whether to store all entities in the drawing or only currently selected entities • Options - whether to store CAD objects, 3D objects, and attributes Some ArcSDE administrative settings for Store are specified in the CAD Client Settings dialog box. Generally, it should not be necessary to change these store settings.
Once you have saved your store settings in a template, you can easily perform the identical store operation as many times as you wish without redefining the template parameters. Before using the Store command, it may be helpful to review the store properties to ensure data is stored according to your requirements.
Chapter 4 Storing and Retrieving Data 27
Creating and Editing a Store Template
You can create and edit store templates using the buttons on the Store dialog box.
The Create New Template button creates a new template with default settings.
The View Information button displays information about the current template.
The Open a Selected Template button allows you to browse and select a template in a specific location.
The Edit Template Properties button allows you to modify the properties of the current template or create a new template from an existing set of properties using the Store Template Properties dialog box.
28 Using ArcSDE CAD Client
Specifying Data to Store
To specify the data storage method and the destination layer, select the Options panel from the Store Template Properties dialog.
To store CAD Objects, in addition to SDE features, check the Store CAD Objects check box. The CAD Objects may then be brought back to the CAD host (i.e., AutoCAD or MicroStation) exactly as they existed in the original drawing. By checking the Store 3D coordinates check box, ArcSDE CAD Client will store the z value of each vertex for each feature.
You may store all the drawing data or only the data currently selected in the drawing. When you choose Store All Drawing Data, each graphical object in the drawing file is stored to your layer. If you choose Store Currently Selected Drawing Data, only those objects you have selected will be stored to your layer. Use the tools provided in the host CAD application to select the data in the drawing.
Note: ArcSDE CAD Client will ignore AutoCAD entities that reside in paper space when storing selected entities. If you select only entities in paper space, ArcSDE CAD Client will display a message stating that zero entities were stored.
Chapter 4 Storing and Retrieving Data 29
Selecting Attributes to Store
To specify the drawing attributes to store in your SDE layer, select the Attributes panel from the Store Template Properties dialog box.
You may choose to store some or all of an object’s drawing properties in the SDE layer. Each drawing property can be matched to a specified SDE attribute column. The Attributes panel displays a list of all the drawing properties and all the available SDE attribute columns in the selected layer. To store a drawing attribute in a specific SDE column, select a drawing property and then select the column where you wish to store the property. Press Add to add the matched pair to the Property/Column List. For example, in the Store Template Properties dialog box, shown above, the drawing property Layer name will be stored in the column layername. The drawing property Color will not be stored because it has not been matched to a column.
Note: The SDE attribute columns must be created before the drawing attributes can be stored. Example scripts for creating a business table with properly defined attribute columns can be found in Chapter 3, in the section “Creating SDE Tables and Layers.”
30 Using ArcSDE CAD Client
If you mark the Match defaults check box, ArcSDE CAD Client automatically pairs drawing properties to available column names. The following list of the matched properties/columns for each host CAD application can be found in the sccspml.dat file. You can change your defaults by editing the [AutoMatch] section in this file.
MicroStation AutoCAD [AutoMatch] [AutoMatch] Drawing name = drawingname Drawing name = drawingname Element type = elementtype Entity type = entitytype Rotation angle = angle Rotation angle = angle Element file position = entityhandle Entity handle = entityhandle Color = color Color = color Line style = linestyle Linetype = linetype Level number = levelnumber Line width = linewidth Level name = levelname Elevation = elevation Line weight = lineweight Line thickness = linethickness Elevation = elevation Layer name = layername Element class = elementclass Reference name = refname Font name = fontname Text style = textstyle Cell name = cellname Text value = textvalue Fill color = fillcolor Text value = textvalue Catalog entity 1 = catent1 Catalog entity 2 = catent2 Catalog entity 3 = catent3 Catalog entity 4 = catent4 Catalog entity 5 = catent5 Catalog entity 6 = catent6 MSLink 1 = mslink1 MSLink 2 = mslink2 MSLink 3 = mslink3 MSLink 4 = mslink4 MSLink 5 = mslink5 MSLink 6 = mslink6
Chapter 4 Storing and Retrieving Data 31
The supported CAD attributes are described in the following lists:
MicroStation Element Properties
Angle The rotation angle of the element. This is the angle at which an element is drawn in relation to the defined location of 0 degrees within the design file.
Catalog Entity [1..6] A value referencing an Mslink to a database catalog.
Cell Name Symbol name of a cell.
Color The numeric value of the element’s color.
Drawing Name The full path name of the design file containing the element.
Element Type The type of the element. The element type value is stored as a number representing the MDL entity code.
Elevation Location of the element on the z-axis.
Entity Handle A unique code given to each element in the drawing. The file position for the current element.
Fill Color Color of fill used within an area element.
Level The design file level that contains the element.
Level Name The most recently used name of the element’s assigned level.
Line Style The line style of an element.
Line Weight The weight of an element.
Mslink [1..6] A database link from the element to an external attribute table. An element may have from zero to six Mslinks attached.
Text Value The text string, or strings, of text and text node elements (up to 16K).
32 Using ArcSDE CAD Client
AutoCAD Entity Properties Angle The rotation angle of the entity. Color The numeric value of the entity color. Drawing Name Full path name of the drawing containing the entity. Elevation Location of entity on the z-axis. Entity Handle The handle for the entity. Entity Type The entity type of the entity. Layer The drawing layer of the specified entity. Line Thickness Thickness or depth of the entity. Line Type The user-defined line style of the entity. Line Width Width of the entity. Reference Name The text name of blocks or other entities with reference names. Text Style The text style of a text entity. Text Value The text string (up to 16K).
Adding Comments
You may add comments, which are visible from the Open Store Template dialog (as shown below). Additional information, which can be viewed from the additional information button on the Open Store Template dialog, may also be added.
Chapter 4 Storing and Retrieving Data 33
Retrieving Data from ArcSDE
The Retrieve command allows you to query a set of features from an SDE layer and generate that data within the current CAD drawing.
When you use ArcSDE CAD Client to retrieve data from ArcSDE, you are creating new objects in your current CAD drawing. The rows you retrieve depend on how you configure the retrieve template. The retrieve template supports graphical and attribute queries so you can retrieve all or only part of the layer to your current drawing. Depending on how the data was stored, you may retrieve either SDE features or CAD objects.
Understanding the Retrieve Template
A retrieve template specifies which data to return to the CAD editor. The retrieve template works much like the store template. It saves important information about the retrieve process, and once configured, can be reused. The retrieve template handles two important functions related to the retrieval process. First, it stores information about the layer to retrieve from. Second, the template stores the Retrieve command options including the spatial operators and SQL expressions to be used and whether CAD objects or SDE features will be retrieved. Retrieve templates are stored as individual files with a file extension of .ccrt.
Attribute and spatial selection methods can be used independently or combined to return specific features from the SDE layer.
34 Using ArcSDE CAD Client
Creating and Editing a Retrieve Template
You can create and edit a retrieve template using the buttons available on the Retrieve dialog box.
The Create New Template button creates a new template with default settings.
The View Information button displays information about the current template.
The Open a Selected Template button allows you to browse and select a template in a specific location.
The Edit Template Properties button modifies the properties of the current template using the Retrieve Template Properties dialog box.
Some ArcSDE administrative settings for data retrieval are configured using the Settings command. Generally it should not be necessary to change these retrieve settings. Once the settings are defined, the retrieve template can be saved and reused to perform identical retrieve operations.
Chapter 4 Storing and Retrieving Data 35
Specifying Data to Retrieve
You may choose whether to retrieve the SDE feature or the CAD object into the drawing. If you retrieve the SDE feature, it is drawn on the current CAD layer or level using the current property settings (e.g., color, line type) of the host CAD application. If you retrieve the CAD object from ArcSDE, the original entity or element is rendered in the drawing using the original properties (e.g., layer, color, line type), just as it existed in the original CAD drawing. If you retrieve the CAD object from a layer that does not contain CAD objects, or if the CAD object was generated from a different host CAD application, then ArcSDE CAD Client will draw the SDE feature instead.
36 Using ArcSDE CAD Client
Using Spatial Selections
ArcSDE CAD Client provides nine different spatial selection methods. Spatial Selection Methods Polygon - Passthru Within and crossing a selected polygon Polygon - Inside Inside a selected polygon Intersecting Intersecting a selected point, line, or polygon Entire Layer All features in the SDE layer Current View Window Within the current CAD view window Buffer - Inside Inside a specified buffer of a selected point, line, or polygon Buffer - Passthru Within and crossing a specified buffer of a selected drawing object Common Point All features that share a common point
Common Line All features that share a common line
These spatial selection methods may be used alone or in combination with an attribute query to specify the data to be retrieved.
To create a spatial selection, select a method from the spatial selection list. If the selection method you choose requires a selected object in the drawing, the object may be selected before using the Retrieve command, or you may select the appropriate objects when prompted. In AutoCAD, entities must be selected using entity grips. In MicroStation, elements may be selected manually or by using fences.
Chapter 4 Storing and Retrieving Data 37
If you do not wish to perform a spatial selection, choose the [none] option from the spatial selection list to disable spatial selections and retrieve from the SDE layer based on an attribute query only.
If you select the entire layer query, the entire contents of the layer are returned (attribute queries will be disabled).
Using Attribute Queries
You can also use attribute queries to retrieve data from a layer. This type of query requires the use of an SQL expression on the layer’s business table. You may use attribute and spatial queries in conjunction with each other.
The retrieve template uses a standard SQL WHERE clause to query feature attributes. You can use all the standard SQL operators, such as =, <, >, <>, <=, and >=, and any additional operators that are supported by your RDBMS. Please consult the SQL documentation for your RDBMS for more information on specifying select statements.
An example of an attribute query might be “COLOR =7 or ENTITYTYPE = ‘AcDbBlock Reference’”. This expression returns features whose color column contains a value of 7 or features whose entitytype column contains the string ‘AcDbBlock Reference’.
38 Using ArcSDE CAD Client
Adding Comments
You may add comments, which are visible from the Open Retrieve Template dialog located in the Comment panel. Additional information may also be added that can be viewed with the Additional Information button on the Open Retrieve Template dialog box.
Retrieving AutoCAD Blocks, Xrefs, and Images
If you retrieve inserts or custom objects into an AutoCAD drawing that has that block already defined, a message will display to the text window that states, “Duplicate definition of block
If you retrieve an Xref into a new AutoCAD drawing, the following message will display to the text window: “Nested Xref
To retrieve images that are stored as CAD objects, you must load the AutoCAD image module before loading ArcSDE CAD Client. To do this, type (arxload “ism”) at AutoCAD’s command line. Attaching an image to your current drawing will also load the image module. If you have not loaded AutoCAD’s image module prior to retrieving an image from ArcSDE CAD Client, only an SDE feature will be retrieved.
Chapter 4 Storing and Retrieving Data 39
Retrieving MicroStation 3D Objects
When using the MicroStation version of ArcSDE CAD Client, you should always retrieve 3D CAD objects into a 3D design file.
Changing the Store and Retrieve Settings
ArcSDE CAD Client provides several settings that determine how data is stored and retrieved. To adjust these settings, use the Settings command located on the Utilities submenu.
Store Settings
Buffered Loading
Checking the Use buffered loading check box instructs the ArcSDE server to buffer stored features and attributes before they are inserted into the RDBMS. Generally, buffered loading speeds up the store process by five to ten times. By default, Buffered Loading is enabled.
40 Using ArcSDE CAD Client
Store Text as Annotation
Checking the Store text as annotation check box instructs ArcSDE CAD Client to store native CAD text objects as SDE annotation on point features. For AutoCAD, text, mtext, and dimensions can be stored as annotation. For MicroStation, text and dimensions can be stored as annotation. When storing text as annotation, ArcSDE CAD Client retains detailed information about the text such as its original height, width, justification, and gap. If Store text as annotation is not checked, ArcSDE CAD Client will store CAD text objects as SDE point features. By default, Store text as annotation is disabled.
Curve Tolerance
When a curved drawing element such as an arc or a spline is stored in ArcSDE, the curve is translated into a series of line segments. Curve tolerance determines the maximum deviation of any one line segment to the actual curve. Specifying a small tolerance generates more segments than specifying a larger tolerance and therefore requires more storage space per feature. If the tolerance you set generates more than 20,000 points, ArcSDE CAD Client adjusts the tolerance. The adjusted tolerance only affects the current feature. The default curve tolerance is 0.001.
Features per Transaction
Features per transaction controls how many features are stored before a transaction is committed by the ArcSDE server. A setting of zero disables transactions, committing each feature as it is added to the SDE layer. The default value is 500 features per transaction.
Write Errors and Warnings to Log File
The Write errors and warnings to log file option allows you to record warning information and errors that occur during the storage process. ArcSDE CAD Client records the date, time, and drawing file name for every store process. By default, the log file is called SccStorErr.txt and is located on the root of the C drive. You may edit the file name and file location in the associated edit box.
Chapter 4 Storing and Retrieving Data 41
Retrieve Settings
Allow Editing of Retrieved Objects
When the Allow editing of retrieved objects setting is enabled, ArcSDE CAD Client appends link information to the newly retrieved drawing data. This allows you to use ArcSDE CAD Client to edit and display attributes of the retrieved data. You can programmatically retrieve this information using the API.
Retrieve and Display Feature Annotation
When the Retrieve and display feature annotation setting is enabled, any SDE features that contain associated annotation are drawn as text. The text will be rendered using the annotation height, width, location, justification, and gap and is drawn using the current text style set in the CAD host.
When retrieving and displaying feature annotation, you can choose whether to display the annotation and its associated feature or to display only the annotation. In both cases, features without an associated annotation are always displayed. By default, Retrieve and display feature annotation is disabled.
If you wish to edit text, you must have stored and retrieved the text as CAD objects.
43
CHAPTER 5 Editing ArcSDE Layers
Accessing Data for Editing
After you have enabled the retrieve setting Allow editing of retrieved data, you can then retrieve data for editing.
Data to be edited is selected using any of the selection tools available within the CAD environment. If no data has been selected prior to invoking the Start Editing command, you are prompted to select features to edit.
Note: Only data retrieved during the current ArcSDE CAD Client session can be edited.
Starting an Editing Session
The following steps describe how to begin an edit session.
1. Retrieve CAD objects or SDE features into your drawing. Multiple SDE layers of data can be edited simultaneously per editing session. 2. Select the features you wish to edit.
44 Using ArcSDE CAD Client
3. Choose the Start Editing command on the SDE menu. ArcSDE CAD Client processes the selected entities to determine if they can be edited. The Start Editing dialog box displays the following information: • Number of entities found • Number of entities without links • Number of entities with outdated links • List of SDE layers to be checked out for editing • Number of selected features per SDE layer
4. Select a layer and choose the Properties button to display the Editing Properties dialog box. This dialog allows you to specify how the edits are committed. Detailed information about the editing properties is discussed in the next section “Setting Edit Properties.”
Chapter 5 Editing SDE Layers 45
5. When editing properties have been set for all layers to be edited, select OK. This starts an editing transaction on each selected layer and creates locks of all the features within the bounding area of the selected entities for each layer. Once the features are checked out, other users will not be able to edit or remove these features until your updates are committed to the layer. Entities can now be edited using the tools of the host CAD application.
Setting Edit Properties
Edits are committed to the originating SDE layers using information contained in a store template. The Editing Properties dialog box allows you to select a store template, edit template properties, or create a new store template. The edit properties must be set separately for each selected layer.
There are two ways to add new data during editing. The first is to add new objects from specified drawing layers or levels in which ArcSDE CAD Client will check each AutoCAD layer or MicroStation level you have selected for new objects. The second is to add by selection set in which ArcSDE CAD Client will prompt you to select new objects that you wish to add to your SDE layer.
46 Using ArcSDE CAD Client
You may also choose to retain the original attributes of the data by checking Update geometry only. This option is important for users who wish to change the geometric characteristics of features while preserving the original attribute data associated with them.
Committing Edits to ArcSDE
The Stop Editing command commits edits to checked out features and adds new data to these layers. The Stop Editing dialog box displays the list of SDE layers that were checked out for editing. When the Stop Editing command is chosen, ArcSDE CAD Client scans the features you have checked out and reports the number of features that have been deleted, modified, unchanged, and added during the edit session.
Adding New Data 1. When you are finished editing, choose Stop Editing from the SDE menu. ArcSDE CAD Client will examine the data and locate new data based on the SDE layer editing properties. If the edit property Add new objects by selection set is set for an SDE layer, ArcSDE CAD Client will prompt you to add to new features to each layer.
When adding new features from selected drawing layers, ArcSDE CAD Client will search the selected layers for new objects. When adding new features by selection, ArcSDE CAD Client will prompt you to select the new objects as shown above.
Chapter 5 Editing SDE Layers 47
2. From the layer list, select the layers whose edits you want to commit, then choose Commit Edits to update the changes to ArcSDE. If a layer is not selected, edits to that layer are abandoned. 3. If you decide that you do not want to commit edits to any of the layers, choose Abandon All. If you want to verify your updates, retrieve the updated features into your drawing and check your data.
Viewing and Modifying Tabular Data
The Identify command allows you to view and modify the associated attributes of individual features. To use the Identify command, you must have retrieved data into the drawing with the retrieve setting Allow editing of retrieved objects enabled.
An entity can be selected using any of the selection tools available within the host CAD application. If no object has been selected prior to choosing the Identify command, you are prompted to select one. The attributes of the feature are then displayed in the Identify window.
Double clicking on an attribute value activates an editor that allows you to enter a new value. You can also copy the attribute values from the editor to the Windows clipboard. Modifications to the attributes are not committed until the Update button is chosen. Attributes that do not have a value are displayed as
48 Using ArcSDE CAD Client
Removing Data from ArcSDE
The Remove commands allow you to remove data from an SDE layer. Data can either be removed by specifying a selected set or by using a query. To remove data by selected set, it must have been retrieved into the CAD drawing with the retrieve setting Allow editing of retrieved objects.
Chapter 5 Editing SDE Layers 49
Remove by Selection
The Remove by Selection command removes the selected set of features from an SDE layer. The features can be selected using any of the CAD selection tools available. If no features have been selected prior to choosing the Remove command, you will be prompted to select some. Select the appropriate layer(s) to confirm that you want to remove those features. Features removed from an SDE layer are automatically deleted from the CAD drawing if it is removed by selection.
50 Using ArcSDE CAD Client
Remove by Query
The Remove by Query command removes data from an SDE layer based on the query parameters of a retrieve template. The interface for the Remove by Query command is identical to the Retrieve command.
When the OK button is pressed, ArcSDE CAD Client searches for the features as determined by the spatial and/or attribute query and removes them.
You will be asked to confirm the delete operation. Selecting Yes will remove those features from your SDE layer.
51
CHAPTER 6 Customizing ArcSDE CAD Client
ArcSDE CAD Client includes a separate API for programmers. Using the ArcSDE CAD Client API allows programmers access to the program’s core functionality such as server connections, data storage and retrieval, feature and attribute editing, and the creation and modification of templates.
Samples for using the ArcSDE CAD Client API are included on the distribution CD. This release includes samples for accessing the ArcSDE CAD Client API via AutoLISP and ARX for AutoCAD, MicroStation BASIC or MDL for MicroStation, and the ActiveX Automation API for both AutoCAD and MicroStation.
Overview of the ArcSDE CAD Client API
There are twenty functions available for your use. Below is a list of these functions describing their usage:
Init_API initiates the ArcSDE CAD Client API. It must be called at least once before calling any other API function. When your application closes, call Term_API to clean up and free any used memory. Term_API does not disconnect the user from ArcSDE.
Login opens the ArcSDE connection. It must be called before calling any other functions. You may choose to hard-code the parameters or prompt users for information by way of a user interface.
Logout closes the ArcSDE connection and frees the ArcSDE license.
Store performs the same functions as the Store command using the ArcSDE CAD Client software user interface. You must provide the template name and path and have an active ArcSDE connection.
52 Using ArcSDE CAD Client
Retrieve performs the same functions as the Retrieve command using ArcSDE CAD Client software user interface. You must provide the template name and path and have an active ArcSDE connection.
EditStart starts the edit session and checks out selected entities.
EditConfig configures your current and future edit sessions for a specific SDE layer. EditConfig allows you to specify which template to use in storing your edited features and whether to update only the geometric feature or all of the associated properties. EditConfig may only be called after starting an edit session from either the API or the user interface.
Note: You do not need to call EditConfig for each edit session, only the first time. If you call EditConfig and the layer is already configured, your changes overwrite the existing configuration for this and future edit sessions. The SDE layer and template associations are persistent between sessions.
EditStop either commits or abandons the edits made to elements checked out with EditStart.
RemoveSel removes all the currently selected elements with a valid link from the database. You must have a current ArcSDE connection.
RemoveQry removes elements based upon a retrieve template. You must provide the template name and path and have a current ArcSDE connection.
GetLink returns the layer name and feature ID (fid) for an element that was retrieved from your current ArcSDE connection with ArcSDE CAD Client.
GetLayers returns a list of the SDE layers defined for your current ArcSDE connection.
GetColumns returns a list of the attribute columns defined for the specified layer on your current ArcSDE connection.
GetFeatureAttr returns a list of column attributes for the feature you specify. You must provide the layer name and the feature ID for a current connection to specify the feature. The layer name and feature ID can be obtained through the API function GetLink.
SetFeatureAttr allows you to update column attributes for a single feature or a group of features on a specified layer. To update a single feature, specify the feature ID. To update a group of features, specify an SQL-type where clause to update the columns of all the features that match the specified where clause.
SQLExec passes an SQL expression to your current database server. When called from the Automation API, this function allows you to send an SQL expression and return a record set
Chapter 6 Customizing ArcSDE CAD Client 53 or a cursor. When SQLExec is called from AutoLISP, ARX, or MDL, it can only send an SQL expression.
StoreTplate manages store templates. Allows you to create new templates or modify or get information about the current template. The operation (e.g., “new”, “set”, “setLayer”, “getComment”) is supplied in the ‘cmd’ argument. All operations occur on the current template.
RetrieveTplate manages retrieve templates. Allows you to create new templates or modify or get information about the current template. The operation (e.g., “new”, “set”, “setCadObjects”, “getRetParams”) is supplied in the ‘cmd’ argument. All operations occur on the current template.
Settings manages the CAD Client system preferences that are accessible from the Settings dialog box in the user interface. The operation (e.g., “getLogFile”, “setCurveTolerance”, “setAllowEditing”) is supplied in the ‘cmd’ argument.
Note: ArcSDE CAD Client must be running before calling any ArcSDE CAD Client API. See the User Guide’s instructions on how to load ArcSDE CAD Client from your host CAD application.
Using the ArcSDE CAD Client ActiveX Automation API
Creating the Automation Object
To use the server, you need to first create an automation object using the create automation object function in the appropriate programming language. Here is an example in Visual Basic. Dim scc As Object Dim r as Boolean Dim s as String Dim layerName as String Dim fid as long ‘ Create automation object Set scc = CreateObject(“cadclient.application”) and an example in Delphi: var scc: Variant; begin scc := CreateOleObject(“cadclient.application”); The name of the server is “cadclient.application”. ArcSDE CAD Client must be loaded into the CAD host for this to work. If ArcSDE CAD Client is not loaded, you will get an OLE exception and an error message box.
54 Using ArcSDE CAD Client
Removing the Automation Object
To close the server, just destroy the reference to the automation object. Depending on your development environment, this can happen when the object goes out of scope or when you destroy it explicitly.
In Visual Basic, to destroy it explicitly, simply set the object reference to nothing. Set scc = Nothing In Delphi, set the reference to the UnAssigned global variable. scc := UnAssigned;
Chapter 6 Customizing ArcSDE CAD Client 55
Login(server as String, instance as String, database as String, username as String, password as String) r = scc.Login(“server”, “instance”, “database”, “user”, “password”) Login opens the ArcSDE connection and prepares ArcSDE CAD Client for future calls. Returns true or false.
Logout() r = scc.Logout Logout closes the ArcSDE connection. Returns true or false.
Store(template_path as String, template_name as String) r = scc.Store(“d:\ustation\scclient\template”, “sample.ccst”) Stores data to the current connection. Returns true or false.
Retrieve(template_path as String, template_name as String) r = scc.Retrieve(“d:\ustation\scclient\template”, “sample.ccrt”) Retrieves data from the current connection. Returns true or false.
GetLink(entityhandle as String, layerName as String, fid as Integer) r = scc.GetLink(“13814”, layerName$, fid) Gets the layer and feature ID of a specified entity. Returns true or false.
GetFeatureAttributes(layername as String, fid as Integer, columnNames as String) s = Scc..GetFeatureAttributes(LayerName, FID, “entityhandle;color;drawingname”) Debug.Print FID & “: EntityHandle “ & s(0) Debug.Print FID & “: Color “ & s(1) Debug.Print FID & “: DrawingName “ & s(02
Returns a variant (zero based) array of the specified column values for a specified feature.
If a particular column value contains no data (i.e., null), then the special value “???” is returned as that column’s value.
56 Using ArcSDE CAD Client
SetFeatureAttributes(layername as String, whereClause as String, columnValues as String)
r = scc.SetFeatureAttributes(LayerName, Str$(fid), “color=9999”) r = scc.SetFeatureAttributes(LayerName, “entityhandle = 244”, “color=887”) Sets the specified column values for a specified feature or group of features. Returns true or false.
To set a particular column value to null, set its value to the special string “???”.
GetColumns(layername as String)
s = scc.GetColumns(“user.table.shapecolumn”) Returns a variant (zero based) array of the specified columns for a designated layer.
GetLayers() s = scc.GetLayers For index = Lbound(s) to Ubound(s) Debug.Print s(index) Next index Returns a variant (zero based) array of layers for the current connection.
SQLExec
The SQLExec object passes SQL statements to your current database server. dim se as Object set se = scc.SqlExec Below is a list describing the properties and methods available for the SQLExec object. Each property and method description is followed by an example.
Expression
The Expression property can be used to set any SQL statement considered valid by the host RDBMS. This includes statements to create and drop tables, add and drop columns, perform and update joins, create views, update, and delete or insert rows. se.Expression = “insert into cad.mytable values (1.233, ‘hello world’)”
se.Expression = “select distinct parcelid, zoning from cad.parcels where ownername = ‘jones’ order by zoning”
Chapter 6 Customizing ArcSDE CAD Client 57
Execute
The Execute method carries out the expression that is currently set. Execute will return false if it fails. if se.Execute then msgbox “one row inserted” se.Execute
NumColumns
If an SQL statement returns rows (e.g., a select statement), you are returned a cursor from which you can fetch the returned rows. The NumColumns property can be used to determine how many columns are available in the selected set. numCols = se.NumColumns for i = 1 to numCols do msgbox se.ColumnName(i)
ColumnName
The ColumnName(i) property can be used in conjunction with NumColumns to return the name of the ith column in the cursor. numCols = se.NumColumns for i = 1 to numCols do msgbox se.ColumnName(i)
GetValue
The GetValue(I) property can be used to get the column values and return a variant representation of the ith column value. if se.Execute then v = se.GetValue(2)
Next
The Next method can be used in conjunction to GetValue to retrieve the next row. Next will return false when there are no more rows. if se.Execute then v = se.GetValue(2) while se.Next v = se.GetValue(2) wend endif
58 Using ArcSDE CAD Client
Reset
Use the Reset method to close the cursor before reading all the available rows. Se.Reset
Close
When you are finished with the object, you must call its Close method. se.Close Set se = nothing
StoreTemplate
The StoreTemplate object can be used to manage store templates. This object allows you to create new templates and modify or get information about a current template.
Create the StoreTemplate object. dim st as object set st = scc.StoreTemplate Below is a list describing the properties available for the StoreTemplate object. Each property description includes an example of its usage.
Name as String
FullTemplateName$ = st.Name
st.Name = “d:\ustation\scclient\template\sewers_4in.ccst” Name returns or sets the current store template.
New as String
st.New (“d:\ustation\scclient\template\sewers_new.ccst”) New creates a new template and sets the new template as the current store template.
Layer as String
layerName$ = st.Layer
st.Layer = “cad.sewer_city.cad” Layer returns or sets the SDE layer to which the data will be stored.
Chapter 6 Customizing ArcSDE CAD Client 59
Comment as String
comment$ = st.Comment
st.Comment = “this template stores all sewer pipes” Comment returns or sets the comment of the current store template.
Info as String
TemplateInfo$ = st.Info
st.Info = “extensive information about the template” Info returns or sets the information section of the store template. This is the equivalent of viewing or adding information through the Show Template Information input box in the user interface.
CadObjects as Boolean
CadObjs = st.CadObjects
st.CadObjects = true CadObjects returns or sets the setting specifying whether or not to store CAD objects in addition to SDE features. Valid values are true or false.
ThreeD as Boolean
ThreeDim = st.ThreeD
st.ThreeD = false ThreeD returns or sets the setting specifying whether 3-D (the first z value) is stored in the elevation column. Valid values are true or false.
Scope as String
SelScope = st.Scope
st.Scope = “all” Scope returns or sets the storage method of the current store template. Valid values are “all” or “selected.” “All” stores all drawing objects; “selected” stores the currently selected drawing objects.
Attributes as String
AttribMatch = st.Attributes
st.Attributes = “_ehandle = entityhandle; _elev = elevation; _ltype = linetype”
60 Using ArcSDE CAD Client
Attributes returns or sets the attribute match list. A match list is a list of each drawing property matched to the appropriate SDE column in the business table. When setting attributes, the drawing properties and SDE column names should be separated by an equal sign, and each attribute should be separated by semicolons. The following is a list of the keywords to use when creating the attribList. The keywords are to the left of the equal sign; their descriptions are to the right. The columns names must already exist in order for them to match with the keywords. AutoCAD: _angle = angle _color = color _dwgname = drawing file name _ehandle = entity handle _elev = elevation _etype = entity type _ltype = line type _txtval = text value _layername = layer name _lwidth = line width _lthick = line thickness _refname = object reference name (e.g., block name) _txtstyle = text style
MicroStation: _angle = angle _color = color _dwgname = design file name _ehandle = element file position _elev = elevation (first z-coordinate of an element) _etype = element type _ltype = line type _txtval = text value _level = level number _levelname = level name _lweight = line weight _cellname = cell name _fillcolor = fill color _mslink1 = ms link #1 _mslink2 = ms link #2 _mslink3 = ms link #3 _mslink4 = ms link #4 _mslink5 = ms link #5 _mslink6 = ms link #6 _catalog_entity1 = catalog entity #1 _catalog_entity2 = catalog entity #2 _catalog_entity3 = catalog entity #3 _catalog_entity4 = catalog entity #4 _catalog_entity5 = catalog entity #5 _catalog_entity6 = catalog entity #6 _fontname = font name _class = element class
Chapter 6 Customizing ArcSDE CAD Client 61
RetrieveTemplate
The RetrieveTemplate object can be used to manage retrieve templates. This object allows you to create new templates and modify or get information about a current template.
Create the RetrieveTemplate object. dim rt as object set rt = scc.RetreiveTemplate
Name as String
FullTemplateName$ = rt.Name
rt.Name = “d:\ustation\scclient\template\sewers_east.ccrt” Name returns or sets the current retrieve template.
New as String
rt.New(“d:\ustation\scclient\template\sewers_north.ccrt”) New creates a new template and sets the new template as the current retrieve template.
Layer as String
layerName$ = rt.Layer
rt.Layer = “cad.sewer_city.cad” Layer returns or sets the SDE layer from which the data will be retrieved.
Comment as String
comment$ = rt.Comment
rt.Comment = “this template stores all sewer pipes” Comment returns or sets the comment of the current retrieve template.
Info as String
Info$ = rt.Info
rt.Info = “extensive information about the template” Info returns or sets the information section of the retrieve template. This is the equivalent of viewing or adding information through the Show Template Information input box in the user interface.
62 Using ArcSDE CAD Client
CadObjects as Boolean
cadObjs = rt.CadObjects
rt.CadObjects = true CadObjects returns or sets the setting whether CAD objects or SDE features are retrieved. Valid values are true or false.
RetrieveOption as String
Option$ = rt.RetrieveOption
rt.RetrieveOption = “polygonwc” RetrieveOption returns or sets the retrieval method. Valid values are “attronly”, “polygonins”, “polygonwc”, “bufferins”, bufferwc”, “layerall”, “viewwindow”, “intersect”, “commonpt”, and “commonline.”
SQLExpression as String
SQLQuery$ = rt.SQLExpression
rt.SQLExpression = “color=3” SQLExpression returns or sets the SQL query used to retrieve data.
RetrieveParameters as Variant
BufDistance = rt.RetrieveParameters
rt.RetrieveParameters = 45.5” RetrieveParameters returns or sets the additional retrieve options. Currently this is only used to store the buffer distance on buffer spatial queries.
Settings
The Settings object can be used to manage the ArcSDE CAD Client system preferences that are accessible from the Settings dialog box in the user interface. For a detailed description of each setting option, please consult the ArcSDE CAD Client User’s Guide.
Create the Settings object. dim seti as object set seti = scc.Settings logFile as String
log$ = set.logFile
Chapter 6 Customizing ArcSDE CAD Client 63
set.logFile = “c:\store\logfile.log” logFile returns or sets the file menu of the log file used to report errors when storing. Setting a zero length string (“”) will turn logging off. featuresPerTransaction as String
Transactions$ = set.featuresPerTransaction
set.featuresPerTransaction = “100” featuresPerTransaction returns or sets the number of features committed per transaction as a string. Must be greater than zero. textAsAnno as Boolean
storeAnno = set.textAsAnno
set.textAsAnno = true textAsAnno returns or sets the setting Store text as annotation. Valid values are true and false.
BufferLoading as String
buffLoad = set.bufferLoading
set.bufferLoading = false bufferLoading returns or sets the setting Current stream loading. Valid values are true and false. curveTolerance as Double
Tolerance# = set.curveTolerance
set.curveTolerance = .001 curveTolerance returns or sets the current curve tolerance. allowEditing as Boolean
editLinks = set.allowEditing
set.allowEditing = true allowEditing returns or sets the setting Allow editing of retrieved objects. Valid values are true and false. annoDisplay as Integer
Display% = set.annoDisplay
64 Using ArcSDE CAD Client
set.annoDisplay = 2 annoDisplay returns or sets the setting Annotation Display. A value of 0 instructs the program to “Not draw annotation and only features” when data is retrieved, a value of 1 instructs the program to “Draw both features and annotation” when data is retrieved, and a value of 2 instructs the program to “Draw annotation only” when data is retrieved.
Writing MicroStation BASIC Applications
ArcSDE CAD Client includes a command-line interface you can call using MicroStation key-ins. Simulating these key-ins using MicroStation BASIC allows you to customize applications for ArcSDE CAD Client.
For examples on using the ArcSDE CAD Client API from BASIC, see the sample source file titled sc_samp.bas. This file includes subroutines that demonstrate all API functions.
To use any of the following key-ins from MicroStation, the BASIC code should call
MbeSendCommand “mdl command” +
The key-in commands available and their required parameters are
Sc_InitAPI
Always call Sc_InitAPI before using any other ArcSDE CAD Client API function. You only need to call this function once at the beginning of your application.
Sc_TermAPI
You must call Sc_TermAPI at the end of your program. For each call to Sc_InitAPI, you need to call Sc_TermAPI.
Sc_Login login$
login$ The user’s connection information in the form as server\instance\database\username\password. Login opens the ArcSDE connection and prepares ArcSDE CAD Client for future calls. Each parameter must be separated by backslash characters.
Sc_Logout
Logout closes the ArcSDE connection, freeing the connection license.
Chapter 6 Customizing ArcSDE CAD Client 65
Sc_Store templateName$ templateName$ The full path of the store template including the file extension (e.g., c:\templates\filename.ccst). Store performs the same operation as the ArcSDE CAD Client Store command.
Sc_Retrieve templateName$ templateName$ The full path of the retrieve template including the file extension (e.g., c:\templates\filename.ccrt). Retrieve performs the same operation as the ArcSDE CAD Client Retrieve command.
Sc_EditStart
EditStart checks out selected elements and begins editing. You must have the edit properties set before calling the editing API. The selected elements must be retrieved in the current session with ArcSDE CAD Client configured to allow editing of retrieved objects; other elements will be ignored.
Sc_EditConfig layerName$ templateName$ geomOnly$ layerName$ The name of the SDE layer. templateName$ The fully qualified name of the store template to use for editing including the file extension (e.g., c:\templates\filename.ccst). geomOnly$ Specifies whether to update only the geometry or to update both the geometry and any properties specified in the template. A value of 0 means to update geometry and properties. Any other value updates geometry only. EditConfig configures your current and future edit sessions for a specific SDE layer.
Sc_EditStop commit
Commit A Boolean value where a value of 1 stops editing and updates the database with edits. A value of 0 cancels edits and ends the editing session. Unlike the ArcSDE CAD Client user interface, you cannot add new elements or entities using the editing API. You must store the new entities rather than adding them through the edit session.
Sc_RemoveSel
RemoveSel performs the same operation as ArcSDE CAD Client software’s Remove by selection set command; however, interactive selection of entities is not supported. You must select the entities prior to calling this command.
66 Using ArcSDE CAD Client
Sc_RemoveQry templateName$
templateName$ The full path of the retrieve template including the file extension (e.g., c:\templates\filename.ccrt). Performs the same operation as ArcSDE CAD Client software’s Remove by query command.
Sc_GetLink
GetLink retrieves the layer name and feature ID of the specified entity.
This function puts the values of the feature ID and layer name into public variables you must declare in your code. Below is a list of the public variables available for use with the Sc_GetLink function. elemSet elem setMember point filePos fileNum saveGGLk saveMsgs See the examples in the sc_samp.bas file for more information on using public variables.
Chapter 6 Customizing ArcSDE CAD Client 67
Writing MicroStation MDL Applications
ArcSDE CAD Client includes a DLM with functions you can call from your MDL application.
The files you need for writing MDL applications for ArcSDE CAD Client include scdlmapi.h: The include file declaring the ArcSDE CAD Client API functions. scdlmapi.dls: The dynamic link specification file for MicroStation. scdlmapi.dll: The ArcSDE CAD Client API DLM. For examples on using the ArcSDE CAD Client API, see the following files: sc_samp.mc: A sample MDL application using the ArcSDE CAD Client. scsamp.mke: A sample MDL make file—you will need to modify this file to match your directory structure. The functions you will need to use are as follows: int iSC_InitAPI(void)
Always call iSC_InitAPI before using any other ArcSDE CAD Client API function. You only need to call this function once at the beginning of your application.
Returns a value of 1 if successful. Returns 0 if unsuccessful. int iSC_TermAPI(void)
Always call iSC_TermAPI at the end of your program to unload the API dynamic link library (DLL) and free used memory.
Returns a value of 1 if successful. Returns 0 if unsuccessful. int iSC_Login(unsigned char *server, unsigned char *instance, unsigned char *database, unsigned char *user, unsigned char *pass) server: The ArcSDE server name. instance: The ArcSDE instance. database: The ArcSDE database (may be null). user: The user name for accessing the ArcSDE database. pass: The user’s password for accessing the ArcSDE database. Login opens the ArcSDE connection and prepares ArcSDE CAD Client for future calls.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
68 Using ArcSDE CAD Client
int iSC_Logout(void)
Closes the ArcSDE connection, freeing the license.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
int iSC_Store(unsigned char *templatePath, unsigned char *templateName)
templatePath: Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName: Template to use for this store operation including extension (e.g., “filename.ccst”). Performs the same operation as ArcSDE CAD Client’s Store command.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
int iSC_Retrieve(unsigned char *templatePath, unsigned char *templateName)
templatePath: Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName: Template to use for this retrieve operation including extension (e.g., “filename.ccrt”). Performs the same operation as ArcSDE CAD Client software’s Retrieve command.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
int iSC_EditStart(void)
Checks out selected elements and begins editing. You must have the edit properties set before calling the editing API.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
int iSC_EditConfig(unsigned char*layerName, unsigned char *templatePath, unsigned char *templateName, int geomOnly)
layerName The name of the SDE layer. templatePath Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName The store template to use for editing including the file extension (e.g., “filename.ccst”). geomOnly Specifies whether to update only the geometry or to update both the geometry and any properties specified in the template. A value of 0 updates geometry and properties. Any other value updates geometry only. Returns a value of 1 if successful. Returns 0 if ArcSDE CAD Client was unable to update the configuration file. Failure is usually caused when an edit session has not been initiated prior to using this function or when attempting to use a template file that does not exist.
Chapter 6 Customizing ArcSDE CAD Client 69 int iSC_EditStop(int commit) commit: Boolean value where a value of 1 stops editing and updates the database with edits. A value of 0 cancels edits and ends the editing session. Unlike the ArcSDE CAD Client user interface, you cannot add new elements or entities using the editing API. You must store the new entities rather than adding them through the edit session.
Returns a value of 1 if successful. Returns 0 if unsuccessful. int iSC_RemoveSel(void)
Performs the same operation as ArcSDE CAD Client software’s Remove by selection set command by removing currently selected elements. Elements must be selected prior to calling this function.
Returns a value of 1 if successful. Returns 0 if unsuccessful. int iSC_RemoveQry(unsigned char *templatePath, unsigned char *templateName) templatePath: Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName: The template to use for this remove operation including extension (e.g., “filename.ccrt”). Performs the same operation as ArcSDE CAD Client software’s Remove by query command.
Returns a value of 1 if successful. Returns 0 if unsuccessful. int iSc_GetLink(unsigned char *layerName, long *featureId, long filePos) layerName: Output buffer for the name of the SDE layer (at least 255 characters). featureId: Output buffer for the feature ID of the specified entity. filePos: The MicroStation file position for the element from which to extract link information. Retrieves the layer name and feature ID of the specified element. If element does not have a valid link, featureID is updated on return with a value of -1. int iSC_GetLayers(unsigned char *buf, long bufLen) buf: Output buffer for the list of layers. bufLen: Specify the maximum number of characters to return (maximum returned is 32K). Updates buf with a semicolon-delimited list of layers for the current connection.
Returns 1 if successful. Returns 0 if unable to access the current connection.
70 Using ArcSDE CAD Client
int iSC_GetColumns(unsigned char *layerName, unsigned char *buf, long bufLen)
layerName: The name of the layer from which to retrieve column definitions. buf: Output buffer for the list of columns. bufLen: Specify the maximum number of characters to return (maximum returned is 32K). Returns a list of the specified columns for a designated layer.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
int iSC_GetFeatureAttr(unsigned char *layerName, long fid, unsigned char *colNames, unsigned char *buf, long bufLen)
layerName: The name of the layer from which to retrieve column definitions. fid: The feature ID of the element from which to get values. colNames: A semicolon-delimited list of the columns from which to get values. buf: Output buffer for the list of values. bufLen: Specify the maximum number of characters to return (maximum returned is 32K). Given a layer name, a specific feature ID, and a list of columns, updates buf with a semicolon delimited list of the values for the specified columns.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
int iSC_SetFeatureAttr(unsigned char *layerName, unsigned char *whereClause, unsigned char *newValues)
layerName: The name of the layer to update. whereClause: An SQL-type clause that specifies which features to update. newValues: The columns to update and their new values. Each value pair is separated by a semicolon (i.e., “dwgname = c:\\parcels;color = 3”). Sets the specified column values for a specified feature or group of features.
There are two ways to use this function. The first is to update by fid. In this case, the where clause is simply a string containing the feature ID of the feature to update. The second way is to update a group of features using a where clause. In this second case, the where clause should be an SQL-type query string. Another way you might want to use a where clause is to identify a single feature when you do not know the feature ID yet. To do this, you could specify a where clause with the drawing name and the file position (assuming you stored the file position as an attribute in ArcSDE).
newValues can be a single column–value pair, or a series of column–value pairs, separated by a semicolon. A column–value pair is formatted as ColumnName = Value such as “angle = 45”.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
Chapter 6 Customizing ArcSDE CAD Client 71 int iSC_SQLExec(unsigned char *sqlExpr) sqlExpr: The string containing the SQL expression to be passed on to the server. Passes an SQL expression to your current database server.
Returns a value of 1 if successful. Returns 0 if unsuccessful. int iSc_StoreTplate(unsigned char *cmd, unsigned char *inData, unsigned char *outData, int outDataLen)
Manages store templates. Allows you to create new templates and modify or get information about the current template.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
Valid values of cmd with descriptions are listed below:
cmd: new Creates a new store template and sets it as the current template. inData: template Fully qualified path and template name including extension. outData: null outDataLen: 0 cmd: get Returns the current store template name. inData: null outData: template Fully qualified path and template name including extension as a string. outDataLen: Maximum length of the outData buffer is 32K. cmd: set Sets the current store template. inData: template Fully qualified path and template name including extension as a string. outData: null outDataLen: 0 cmd: getlayer Returns the layer of the current store template. inData: null outData: layerName The SDE layer name to which the data will be stored as a string. outDataLen: Maximum length of the outData buffer is 32K. cmd: setlayer Sets the layer name of the current store template. inData: layerName The SDE layer name to which the data will be stored as a string. outData: null outDataLen: 0
72 Using ArcSDE CAD Client
cmd: getcomment Returns the comment of the current store template. inData: null outData: comment Comment of the current store template as a string. outDataLen: Maximum length of the outData buffer is 32K. cmd: setcomment Sets the comment of the current store template. inData: comment Comment of the current store template as a string. outData: null outDataLen: 0 cmd: getinfo Returns detailed information describing the current store template. inData: null outData: information A string of detailed information about the current store template. outDataLen: Maximum length of the outData buffer is 32K. cmd: setinfo Sets detailed information describing the current store template. inData: information A string of detailed information about the current store template. outData: null outDataLen: 0 cmd: getcadobjects Returns information regarding the store CAD object setting of the current store template. inData: null outData: cadObjects The value of the CAD objects setting. Returns 1 if the current template is configured to store both CAD objects and SDE features; otherwise returns 0 if current template is configured to only store SDE features. outDataLen: Maximum length of the outData buffer is 32K. cmd: setcadobjects Sets the CAD objects setting of the current store template. inData: cadObjects: A value of 1 enables the storage of CAD objects; 0 disables this setting. outData: null outDataLen: 0 cmd: get3d Returns the 3D setting of the current store template. inData: null outData: 3d String that specifies if store template is configured to store 3-D (z value) of elements in the business table. A return value of 1 denotes true; a return value of 0 denotes false. outDataLen: Maximum length of the outData buffer is 32K.
Chapter 6 Customizing ArcSDE CAD Client 73
cmd: set3d Sets the 3D setting of the current store template. inData: 3d String that specifies whether to store 3D (z value) of elements in the business table. A value of 1 sets for true; a value of 0 sets for false. outData: null outDataLen: 0 cmd: getscope Returns the storage scope of the current store template. inData: null outData: storageScope String describing what elements will be stored. Valid values returned are “all” for storing all drawing data or “selected” for storing currently selected drawing data. outDataLen: Maximum length of the outData buffer is 32K. cmd: setscope Sets the storage scope of the current store template. inData: storageScope String describing what elements will be stored. Valid values are “all” for storing all drawing data or “selected” for storing currently selected drawing data. outData: null outDataLen: 0 cmd: getattrs Returns the property match list for the current store template. inData: null outData: attribList Property match list for the current template. Returned as a semicolon-delimited string (i.e., tag=value;tag2=value2;tag3=value3). See list below for valid tag names. outDataLen: Maximum length of the outData buffer is 32K.
74 Using ArcSDE CAD Client
Cmd: setattrs Sets the property match list for the current store template. A match list is a list of each drawing property matched to the appropriate SDE column in the business table. inData: attribList The property match list of the current store template. When setting attributes, the drawing properties and SDE column names should be separated by an equal sign, and attributes should be separated by semicolons (e.g., “tag=value;tag2=value2.”). The following is a list of the keywords to use when creating the attribList. The keywords are to the left of the equal sign; their descriptions are to the right. The column names must already exist in order for them to match with the keywords.
_angle = angle _color = color _dwgname = design file name _ehandle = element file position _elev = elevation (first z-coordinate of an element) _etype = element type _ltype = line type _txtval = text value _level = level number _levelname = level name _lweight = line weight _cellname = cell name _fillcolor = fill color _mslink1 = ms link #1 _mslink2 = ms link #2 _mslink3 = ms link #3 _mslink4 = ms link #4 _mslink5 = ms link #5 _mslink6 = ms link #6 _catalog_entity1 = catalog entity #1 _catalog_entity2 = catalog entity #2 _catalog_entity3 = catalog entity #3 _catalog_entity4 = catalog entity #4 _catalog_entity5 = catalog entity #5 _catalog_entity6 = catalog entity #6 _fontname = font name _class = element class outData: null outDataLen: 0
Chapter 6 Customizing ArcSDE CAD Client 75
int iSc_RetrieveTplate(unsigned char *cmd, unsigned char *inData, unsigned char *outData, int outDataLen)
Manages retrieve templates. Allows you to create new templates and modify or get information about the current template.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
Valid values of cmd with description are listed below.
cmd: new Creates a new retrieve template and sets it as the current template.
inData: template Fully qualified path and template name including extension as a string. outData: null outDataLen: 0 cmd: get Returns the current retrieve template name. inData: null outData: template Fully qualified path and template name including extension as a string. outDataLen: Maximum length of the outData buffer is 32K. cmd: set Sets the current retrieve template. inData: template Fully qualified path and template name including extension as a string. outData: null outDataLen: 0 cmd: getlayer Returns the SDE layer name of the current retrieve template. inData: null outData: layerName The SDE layer name from which the data will be retrieved as a string. outDataLen: Maximum length of the outData buffer is 32K. cmd: setlayer Sets the layer name of the current retrieve template. inData: layerName The SDE layer name from which the data will be retrieved as a string. outData: null outDataLen: 0 cmd: getcomment Returns the comment of the current retrieve template. inData: null outData: comment Comment of the current retrieve template as a string. outDataLen: Maximum length of the outData buffer is 32K.
76 Using ArcSDE CAD Client
cmd: setcomment Sets the comment of the current retrieve template. inData: comment Comment of the current retrieve template as a string. outData: null outDataLen: 0 cmd: getinfo Returns detailed information describing the current retrieve template. inData: null outData: info Detailed information about the current retrieve template as a string. outDataLen: Maximum length of the outData buffer is 32K. cmd: setinfo Sets detailed information describing the current retrieve template. inData: info Detailed information about the current retrieve template as a string. outData: null outDataLen: 0 cmd: getcadobjects Returns the CAD objects setting of the current retrieve template. inData: null outData: cadObjects The value of the CAD objects setting. Returns 1 if the current template is configured to retrieve CAD objects; otherwise returns 0 if current template is configured to retrieve SDE features. outDataLen: Maximum length of the outData buffer is 32K. cmd: setcadobjects Sets the CAD objects setting of the current retrieve template. inData: cadObjects A value of 1 enables the retrieval of CAD objects. A value of 0 disables this setting. outData: null outDataLen: 0 cmd: getRetOption Returns the retrieve option of the current retrieve template. inData: null outData: RetOption The retrieve option for the current retrieve template as a string. Valid values of outData include ‘attronly’, ‘polygonins’, ‘polygonwc’, ‘bufferins’, bufferwc’, ‘layerall’, ‘viewwindow’, ‘intersect’, ‘commonpt’, and ‘commonline’. outDataLen: Maximum length of the outData buffer is 32K. cmd: setRetOption Sets the retrieve option of the current retrieve template. inData: RetOption The retrieve option for the current retrieve template as a string. Valid values of inData include ‘attronly’, ‘polygonins’, ‘polygonwc’, ‘bufferins’, bufferwc’, ‘layerall’, ‘viewwindow’, ‘intersect’, ‘commonpt’, and ‘commonline’. outData: null outDataLen: 0 cmd: getSqlQuery
Chapter 6 Customizing ArcSDE CAD Client 77
Returns the SQL query of the current retrieve template. inData: null outData: sqlQuery The SQL query used to retrieve data as a string. OutDataLen: Maximum length of the outData buffer is 32K. cmd: setSqlQuery Sets the SQL query of the current retrieve template. InData: sqlQuery The SQL query used to retrieve data as a string. OutData: null OutDataLen: 0 cmd: getRetParams Returns the retrieve option parameters. InData: null OutData: retParams The buffer distance on buffer spatial queries. Currently this is only used to store the buffer distance on buffer spatial queries. OutDataLen: Maximum length of the outData buffer is 32K. cmd: setRetParams Sets the retrieve option parameters of the current retrieve template. InData: retParams The buffer distance on buffer spatial queries. Currently this is only used to store the buffer distance on buffer spatial queries. OutData: null OutDataLen: 0
int iSc_Settings(unsigned char *cmd, unsigned char *inData, unsigned char *outData, int outDataLen)
The function can be used to manage the ArcSDE CAD Client system preferences that are accessible from the Settings dialog box in the user interface. For a detailed description of each setting option, please consult the ArcSDE CAD Client User’s Guide.
Returns a value of 1 if successful. Returns 0 if unsuccessful.
Valid values of cmd with description are listed below:
cmd: getLogFile Returns a fully qualified path and logfile name including extension as a string. inData: null outData: logFile Fully qualified path and logfile name including extension. outDataLen: Maximum length of the outData buffer is 32K.
78 Using ArcSDE CAD Client
cmd: setLogFile Sets the logfile name. inData: logFile Fully qualified path and logfile name including extension as a string. Setting a zero length string (““) will turn logging off. outData: null outDataLen: 0 cmd: getFeaturesPerTransaction Returns the number of features committed per transaction. inData: null outData: featuresPerTransaction Number of features committed per transaction during store. outDataLen: Maximum length of the outData buffer is 32K. cmd: setFeaturesPerTransaction Sets the Number of features per transaction. inData: featuresPerTransaction Number of features committed per transaction. Must be greater than zero. outData: null outDataLen: 0 cmd: getTextAsAnno Returns the setting of Store text as annotation. inData: null outData: textAsAnno Value of Store text as annotation setting. Returns 1 for true and 0 for false. outDataLen: Maximum length of the outData buffer is 32K. cmd: setTextAsAnno Sets the Store text as annotation setting. inData: textAsAnno Value of the Store text as annotation setting. Valid values include 1 for true and 0 for false. outData: null outDataLen: 0 cmd: getBufferLoading Returns the Current stream loading setting. inData: null outData: bufferLoading Value of the Current stream loading setting as a string. Returns 1 for true and 0 for false. outDataLen: Maximum length of the outData buffer is 32K. cmd: setBufferLoading Sets the Current stream loading setting. inData: bufferLoading Value of the Current stream loading as a string setting. Valid values include 1 for true and 0 for false. outData: null outDataLen: 0
Chapter 6 Customizing ArcSDE CAD Client 79
cmd: getCurveTolerance Returns the setting Current curve tolerance. inData: null outData: curveTolerance Current curve tolerance value. outDataLen: Maximum length of the outData buffer is 32K. cmd: setCurveTolerance Sets the setting Current curve tolerance. inData: curveTolerance Current curve tolerance value. Values must be greater than 0.00001 and less than 500. outData: null outDataLen: 0 cmd: getAllowEditing Returns the Allow editing of retrieved objects setting. inData: null outData: allowEditing Value of the Allow editing of retrieved objects setting. Returns 1 for true and 0 for false. outDataLen: Maximum length of the outData buffer is 32K. cmd: setAllowEditing Sets the Allow editing of retrieved objects setting. inData: AllowEditing Value of the Allow editing of retrieved objects setting. Valid values include 1 for true and 0 for false. outData: null outDataLen: 0 cmd: getAnnoDisplay Returns the Annotation Display setting. inData: null outData: annoDisplay Returns the value of the Annotation Display setting. A value of 0 instructs the program to “not draw annotation and only features” when data is retrieved, a value of 1 instructs the program to “draw both features and annotation” when data is retrieved, and a value of 2 instructs the program to “draw annotation only” when data is retrieved. outDataLen: Maximum length of the outData buffer is 32K. cmd: setAnnoDisplay Sets the Allow editing of retrieved objects setting. inData: annoDisplay Value of the Annotation Display setting. A value of 0 instructs the program to “not draw annotation and only features” when data is retrieved, a value of 1 instructs the program to “draw both features and annotation” when data is retrieved, and a value of 2 instructs the program to “draw annotation only” when data is retrieved. outData: null outDataLen: 0
80 Using ArcSDE CAD Client
Writing AutoCAD AutoLISP Applications
You can access all ArcSDE CAD Client functionality from AutoLISP using twenty function calls.
A sample AutoLISP file shows you how to use ArcSDE CAD Client functionality from within your own AutoLISP application. This file is named ccsamp.lsp.
The functions you will need to use are as follows:
esriSC_InitAPI
Always call esriSC_InitAPI before using any other ArcSDE CAD Client API function. You only need to call this function once at the beginning of your application.
Returns T if successful. Returns nil if unsuccessful.
esriSC_TermAPI
Always call esriSC_TermAPI at the end of your program. For each call to esriSC_InitAPI, you need to call esriSC_TermAPI.
Returns T if successful. Returns nil if unsuccessful.
esriSC_Login server instance database userName password
server: The ArcSDE server name. instance: The ArcSDE server instance. database: The ArcSDE server database (may be empty). userName: The user name for accessing the ArcSDE database. password: The user’s password for accessing the ArcSDE database. Login opens the ArcSDE connection and prepares ArcSDE CAD Client for future calls.
Returns T if successful. Returns nil if unsuccessful.
esriSC_Logout
Closes the ArcSDE connection, freeing the connection license.
Returns T if successful. Returns nil if unsuccessful.
Chapter 6 Customizing ArcSDE CAD Client 81
esriSC_Store templatePath templateName templatePath: Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName: The template to use for this store operation including extension (e.g., “filename.ccst”). Performs the same operation as the ArcSDE CAD Client Store command. Stores data to the current connection.
Returns T if successful. Returns nil if unsuccessful. esriSC_Retrieve templatePath templateName templatePath: Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName: The template to use for this retrieve operation including extension (e.g., “filename.ccrt”). Performs the same operation as the ArcSDE CAD Client Retrieve command. Retrieves data from the current connection.
Returns T if successful. Returns nil if unsuccessful. esriSC_EditStart
Checks out selected elements and begins editing. You must have the edit properties set before calling the editing API.
Returns T if successful. Returns nil if unsuccessful. esriSC_EditConfig layerName templatePath templateName geomOnly layerName The name of the ArcSDE layer. templatePath Fully qualified path where the user’s templates are stored (e.g., “c:\\templates”). templateName The store template to use for editing including file extension (e.g., “filename.ccst”). geomOnly An integer that specifies whether to update only the geometry or to update both the geometry and any properties specified in the template. A value of 0 updates geometry and properties. Any other value updates geometry only. Returns T if successful. Returns nil if unable to update the configuration file. Failure is usually caused when an edit session has not been initiated prior to using this function or when attempting to use a template file that does not exist. esriSC_EditStop commit commit A Boolean value where a value of 1 stops editing and updates database with edits. A value of 0 cancels edits and ends the editing session. Stops editing and updates modified objects.
Returns T if successful. Returns nil if unsuccessful.
82 Using ArcSDE CAD Client
esriSC_RemoveSel
Performs the same operation as ArcSDE CAD Client software’s Remove by Selection command. Entities must be selected prior to calling this command.
Returns T if successful. Returns nil if unsuccessful.
esriSC_RemoveQry templatePath templateName
templatePath: Fully qualified path where the user’s templates are stored (e.g., “c:\\template.ccrt”). templateName: The template to use for this remove operation including extension (e.g., filename.ccrt”). Performs the same operation as the ArcSDE CAD Client software’s Remove by Query command.
Returns T if successful. Returns nil if unsuccessful.
esriSC_GetLink ename
ename: The entity name of the entity from which to extract link information. Retrieves the layer name and feature ID of the specified entity. Returns list with two elements consisting of a string and an integer. The string is the layer name associated with the specified entity, and the integer is the feature ID. A feature ID with a value of -1 means the specified entity is not linked to an active data source.
esriSC_GetLayers
Returns a list containing the layers defined for the current connection.
Returns nil if unable to determine the information about the current connection.
esriSC_GetColumns layerName
layerName: A string that specifies the name of the layer from which to get the column definitions Returns a list containing the names of the columns defined for the specified layer.
Returns nil if unable to get column names.
Chapter 6 Customizing ArcSDE CAD Client 83
esriSC_GetFeatureAttr layerName fid colNames layerName: A string that specifies the name of the layer from which to get column values. fid: The feature ID (long integer or string) of the feature from which to get column values. colNames: A semicolon-delimited string list or list of strings of the columns from which to get values. Given a layer name, a specific feature ID, and a list of columns, returns a list containing a string with a semicolon-delimited list of the values for the specified columns.
Returns a list if successful. Returns nil if unable to get values for the specified feature ID. esriSC_SetFeatureAttr layerName whereClause newValues layerName: A string that specifies the name of the layer to update. whereClause: A string that contains an SQL-type clause that specifies which features or fid to update. newValues: A string or list of dotted pairs that specifies the columns to update and their new values. Each value pair is separated by a semicolon. There are two ways to use this function. The first is to update by fid (may be a string or an integer). In this case, your where clause is simply a string containing the feature ID of the feature to update. The second way is to update a group of features using a where clause. In this second case, the where clause should be an SQL-type query string. Another way you might want to use a where clause is to identify a single feature when you do not know the feature ID yet. To do this, you could specify a where clause with the drawing name and the entity handle (assuming you stored the handle as an attribute in ArcSDE). newValues can be a single column–value pair, or a series of column–value pairs, separated by a semicolon. A column–value pair is formatted as ColumnName = Value such as “angle = 45”.
Returns T if successful. Returns nil if unable to update the specified features. esriSC_SQLExec sqlExpression sqlExpression: The SQL expression to be passed to the server. Passes an SQL expression to your current database server.
Returns T if successful. Returns nil if unable to execute the SQL expression.
84 Using ArcSDE CAD Client
esriSC_StoreTplate (cmd, inData)
Manages the creation and editing of store templates.
Below is a list describing the options available for the esriSC_StoreTplate function. For a detailed description of each store template setting, please consult the ArcSDE CAD Client User’s Guide.
cmd: new Creates a new template. Sets it as the current template if created successfully. inData: template Fully qualified path and template name including extension. Returns T if successful. Returns nil if unable to create new template and set as current template. cmd: get Returns the current template name if successful. Returns nil if unsuccessful. cmd: set Sets the current store template. InData: template Fully qualified path and template name including extension. Returns T if successful. Returns nil if unable to set as current template. cmd: getlayer Returns the SDE layer of the current store template if successful. Returns nil if unsuccessful. cmd: setlayer Sets the SDE layer name. inData: layerName The SDE layer name to which the data will be stored. Returns T if successful. Returns nil if unable to set the SDE layer for the current template. cmd: getcomment Returns the comment of the current store template if successful. Returns nil if unsuccessful. cmd: setcomment Sets the comment. inData: comment String of brief information describing the store template. Returns T if successful. Returns nil if unable to set the comment for the current template. cmd: getinfo Returns the detailed information describing the current store template if successful. Returns nil if unsuccessful. cmd: setinfo Sets the information. inData: information String of detailed information describing the store template. Returns T if successful. Returns nil if unable to set the information for the current template. cmd: getcadobjects Returns the CAD objects setting of the current store template. The value should be 1 for true or 0 for false. Returns the CAD objects setting of the current store template if successful. Returns nil if unsuccessful.
Chapter 6 Customizing ArcSDE CAD Client 85
cmd: setcadobjects Sets the CAD objects setting. inData: cadobjects String that specifies whether to store CAD objects or to store SDE features. The value should be 1 for true or 0 for false. Returns T if successful. Returns nil if unable to set the CAD objects setting for the current template. cmd: get3d Returns the 3D setting of the current store template. The value should be 1 for true or 0 for false. Returns the 3D setting of the current store template if successful. Returns nil if unsuccessful. cmd: set3d Sets the 3D setting. inData: 3d A string that specifies whether to store 3D (z-value) of entities. The value should be 1 for true or 0 for false. Returns T if successful. Returns nil if unable to set the 3D setting for the current template. cmd: getscope Returns the storage scope of the current store template. Valid values are “all” or “selected.” Returns nil if unsuccessful. cmd: setscope Sets the storage scope. inData: storageScope String describing what entities will be stored. Valid values are “all” or “selected.” Returns T if successful. Returns nil if unable to set the storage scope for the current template. cmd: getattrs Returns the property match list for the current store template. It is returned as a dotted pair list of the following form: “(tag . value) (tag2 . value2) (tag3 . value3).” Returns nil if unsuccessful.
86 Using ArcSDE CAD Client
cmd: setattrs Sets the property match list. inData: attribList Property match list for the current template. AttribList can be a semicolon-delimited list of the following form: “tag=value;tag2=value2;tag3=value3”, or it can be stored as a dotted pair list of the following form: “(tag . value) (tag2 . value2) (tag3 . value3).” The following is a list of the keywords to use to create the attribList. The keywords are to the left of the equal sign; their descriptions are to the right. The column names must already exist in order for them to match with the keywords. _angle = angle _color = color _dwgname = drawing name _ehandle = entity handle _elev = elevation _etype = entity type _ltype = line type _txtval = text value _layername = layer name _lwidth = line width _lthick = line thickness _refname = object reference name (e.g., block name) _txtstyle = text style
Returns T if successful. Returns nil if unable to set the property match list for the current template.
esriSC_RetrieveTplate (cmd, inData)
Manages the creation and editing of retrieve templates.
Below is a list describing the options available for the esriSC_RetrieveTplate function. For a detailed description of each retrieve template setting, please consult the ArcSDE CAD Client User’s Guide.
cmd: new Creates a new template. Sets it as the current template if created successfully. inData: template Fully qualified path and template name including extension. Returns T if successful. Returns nil if unable to create new template and set as current template. cmd: get Returns the current template name if successful. Returns nil if unsuccessful. cmd: set Sets the current retrieve template. inData: template Fully qualified path and template name including extension. Returns T if successful. Returns nil if unable to set as current template. cmd: getlayer Returns the SDE layer of the current retrieve template if successful. Returns nil if unsuccessful.
Chapter 6 Customizing ArcSDE CAD Client 87
cmd: setlayer Sets the SDE layer name. inData: layerName The SDE layer name to which the data will be retrieved. Returns T if successful. Returns nil if unable to set the SDE layer for the current template. cmd: getcomment Returns the comment of the current retrieve template if successful. Returns nil if unsuccessful. cmd: setcomment Sets the comment. inData: comment String of brief information describing the retrieve template. Returns T if successful. Returns nil if unable to set the comment for the current template. cmd: getinfo Returns the detailed information describing the current retrieve template if successful. Returns nil if unsuccessful. cmd: setinfo Sets the information. inData: information String of detailed information describing the retrieve template. Returns T if successful. Returns nil if unable to set the information for the current template. cmd: getcadobjects Returns the CAD objects setting of the current retrieve template. The value should be 1 for true or 0 for false. Returns the CAD objects setting of the current retrieve template if successful. Returns nil if unsuccessful. cmd: setcadobjects Sets the CAD objects setting. inData: cadobjects String that specifies whether to retrieve CAD objects or to retrieve SDE features. The value should be 1 for true or 0 for false. Returns T if successful. Returns nil if unable to set the CAD objects setting for the current template. cmd: getRetOption Returns the retrieve option for the current template. Valid values include ‘attronly’, ‘polygonins’, ‘polygonwc’, ‘bufferins’, bufferwc’, ‘layerall’, ‘viewwindow’, ‘intersect’, ‘commonpt’, and ‘commonline’. Returns the retrieve option as a string if successful. Returns nil if unsuccessful. cmd: setRetOption Sets the retrieve option for the current template. inData: retOption The retrieve option for the current retrieve. Valid values include ‘attronly’, ‘polygonins’, ‘polygonwc’, ‘bufferins’, bufferwc’, ‘layerall’, ‘viewwindow’, ‘intersect’, ‘commonpt’, and ‘commonline’. Returns T if successful. Returns nil if unable set the retrieve option of the current template. cmd: getSqlQuery Returns the SQL query of the current retrieve template as a string if successful. Returns nil if unsuccessful.
88 Using ArcSDE CAD Client
cmd: setSqlQuery Sets the SQL query of the current retrieve template. inData: sqlQuery The SQL query used to retrieve data as a string. Returns T if successful. Returns nil if unable to set the SQL query of the current retrieve template. cmd: getRetParams Returns the retrieve option parameters if successful. Returns nil if unsuccessful. Currently this is only used to store the buffer distance on buffer spatial queries. cmd: setRetParams Sets the retrieve option parameters of the current retrieve template. inData: retParams The buffer distance on buffer spatial queries. Currently this is only used to store the buffer distance on buffer spatial queries. Returns T if successful. Returns nil if unable to set the retrieve parameters of the current template.
EsriSC_Settings (cmd, inData)
This function can be used to manage the ArcSDE CAD Client system preferences that are accessible from the Settings dialog box in the user interface. For a detailed description of each setting option, please consult the ArcSDE CAD Client User’s Guide.
Below is a list describing the options available for the esriSC_Settings function.
cmd: getLogfile Returns a fully qualified path and logfile name including extension as a string if successful. Returns nil if unsuccessful. cmd: setLogfile Sets the logfile name. inData: logFile Fully qualified path and logfile name including extension. Setting a zero length string (““) will turn logging off. Returns T if successful. Returns nil if unable to set the retrieve parameters of the current template. cmd: getFeaturesPerTransaction Returns the number of features committed per transaction as a string if successful. Returns nil if unsuccessful. cmd: setFeaturesPerTransaction Sets the setting Number of features committed per transaction. inData: featuresPerTransaction The number of features committed per transaction as a string. Returns T if successful. Returns nil if unable to set number of features per transaction. cmd: getTextAsAnno Returns the Store text as annotation setting. The value should be 1 for true or 0 for false. Returns the setting Store text as annotation if successful. Returns nil if unsuccessful.
Chapter 6 Customizing ArcSDE CAD Client 89
cmd: setTextAsAnno Sets the Store text as annotation setting. inData: textAsAnno Value of the Store text as annotation setting as a string. Returns T if successful. Returns nil if unable to set the setting Store text as annotation. cmd: getBufferLoading Returns the Current stream loading setting. inData: The value should be 1 for true or 0 for false. Returns the setting Current stream loading if successful. Returns nil if unsuccessful. cmd: setBufferLoading Sets the value of the Current stream loading setting. inData: bufferLoading: Value of the setting Current stream loading as a string. Returns T if successful. Returns nil if unable to set the buffer loading. cmd: getCurveTolerance Returns the setting Current curve tolerance if successful. Returns nil if unsuccessful. cmd: setCurveTolerance Sets the setting Current curve tolerance value. inData: curveTolerance Current curve tolerance value as a string. Returns T if successful. Returns nil if unable to set the curve tolerance. cmd: getAllowEditing Returns the setting Allow editing of retrieved objects as a string (1 = true or 0 = false) if successful. Returns nil if unsuccessful. cmd: setAllowEditing Sets the value of the Allow editing of retrieved objects setting. inData: allowEditing The value of the Allow editing of retrieved objects setting as a string. Returns T if successful. Returns nil if unable to set the setting Allow editing of retrieved objects. cmd: getAnnoDisplay Returns the Annotation Display setting. A value of 0 means off and will only draw features, a value of 1 means draw both features and annotation, and a value of 2 means draw annotation only. Returns the setting Annotation Display as a string if successful. Returns nil if unsuccessful. cmd: setAnnoDisplay Set the value of the Annotation Display setting. inData: annoDisplay The value of the setting Annotation Display as a string. A value of 0 instructs the program to “not draw annotation and only features” when data is retrieved, a value of 1 instructs the program to “draw both features and annotation” when data is retrieved, and a value of 2 instructs the program to “draw annotation only” when data is retrieved. Returns T if successful. Returns nil if unable to set the setting Annotation Display.
90 Using ArcSDE CAD Client
Writing ARX AutoCAD Applications
There are two ways to create ARX applications for AutoCAD. One way is to access all the functions described in the section “Writing AutoCAD AutoLISP Applications” using ads_invoke. The second way is to bypass the ads subsystem and call directly into ArcSDE CAD Client software’s core API DLL, csapi.dll.
In your sample directory, there is a sample Visual C++ 5.0 example project called ccsamparx. The file ccsampads.cpp shows how to access ArcSDE CAD Client software’s API using ads_invoke. The file ccsamparx.cpp shows how to call into the ArcSDE CAD Client software’s API DLL directly by loading the DLL and using GetProcAddress to get the appropriate function pointers.