MEMO CYCO SOFTWARE

Subject : AutoManager Document Server API

To :
From : Marc
Date : July 24, 1995
File : G:\CSD\MEM\M60222MB.API
Printed : September 20, 2017, 17:54 hr.

Introduction
This document describes the design and specification of the AutoManager Document Server API (AMDSAPI).
The AutoManager API is meant to replace the current situation where ACADDSI inside AutoCAD is talking
directly to AutoManager WorkFlow and the AM-WorkFlow Document Server Interface. The goal of this API is
to enable other applications to access AM-WorkFlow functionality, and possibly to extend this functionality to
other Document Management Software, like AutoManager Organizer.

This document limits to describing the Windows interface.

History:

MB - December 15, 1995 Version 1 finished.

MB - February 2, 1996 Version 2: Updated definitions for DsiEditCard, DsiGetOpenFilename and
DsiGetSaveFilename
MB - July 11, 1996 Version 2a: Corrected description of DsiNewCard

- memo 60222 page 1 -

Contents

Introduction................................................................................................................................................................

Design Goals...............................................................................................................................................................
Functions to be defined
Functions to be redefined or captured

Database Functions.....................................................................................................................................................

Profile Functions.........................................................................................................................................................

Redline Functions.......................................................................................................................................................

General Functions.......................................................................................................................................................

Setting up a link..........................................................................................................................................................

Function Descriptions.................................................................................................................................................
Error values
DsiEditCard
DsiGetField
DsiGetOpenFilename
DsiGetSaveFilename
DsiLockCard
DsiNewCard
DsiPutField
DsiQueryFilenameFromID
DsiQueryIDFromFilename
DsiReadGlobalProfile
DsiReadUserProfile
DsiRedCloseRedline
DsiRedNormalizeArc
DsiRedOpenRedline
DsiRedQueryNumLayers
DsiRedQueryLayerName
DsiRedReadEntity
DsiRedReStartRedline
DsiRedSetCurrentLayer
DsiRegisterApp
DsiUnregisterApp
DsiViewDocument
DsiWriteGlobalProfile
DsiWriteUserProfile

- memo 60222 page 2 -

Design Goals
This API design aims at achieving two main goals:
Cleaning up the current methods and APIs used in AutoCAD to access AM-WorkFlow.
Improve support for a number of other CAD packages for which support until now was limited, like
CadKey and Microstation.

The second point can be specified more precisely with the following:
The CAD packages environment can be extended with functions to access document information that is
stored in the AutoManager database. This is similar to the getfield/putfield functions which are
available in the link with AutoCAD.
A titleblock link can be implemented. Information in the titleblock can be hot-linked with information in
the database, based on the getfield/putfield functions described above.
Redlines can be loaded or viewed in the current drawing, similar to the way this works in AutoCAD.
The CAD packages Open command can be extended in a way that the user can select a document with
help of AutoManager (using the Navigator, etc.). Other commands can also be extended in a similar
way.
If the development environment of the CAD package is powerful enough AutoManager could be notified
when a document is opened to synchronize document locking and to prevent locked documents to be
loaded (if possible).

Figure 1. The AutoManager Document Server API provides access to AutoManager WorkFlow functionality
from various applications.

In the desired situation the application (the CAD package) has little to do with AutoManager. All
communication should go through a clean API behind which the application specific calls are hidden. The
larger part of the locking and editing logic should be encapsulated in that API. Implementing this mechanism
as a separate DLL or executable has four advantages:
AM-WorkFlow needs little or no modification.
The actual AutoManager API is hidden from the application. AM-WorkFlow could be replaced by AM-
Organizer without the application being aware of it.
The application side of the link can be relatively thin compared to the current situation.
The application side needs only very basic calls to achieve the needed card locking and editing capabilities
currently available in ACADDSI.

To achieve this situation AMDSAPI should support a number of API groups:

- memo 60222 page 3 -

 Database functions.
Profile functions.
Redline functions.
General (bookkeeping) functions.

Functions to be defined

Based on this API the application should provide a number of additional commands (if supported by the CAD
package):
AMWNEW Create a new drawing with a name provided by AM-WorkFlow. This will pop-up the
AM-WorkFlow user interface with a new card. AM-WorkFlow generates a filename.
AMWOPEN Open an existing drawing from the AM-WorkFlow database. This will pop-up AM-
WorkFlow and lets the user select a card.
AMWSAVE Save the current drawing.
AMWSAVEAS Save the current drawing under a new name.
AMWCLOSE Close the current drawing.
AMWXREF1 Attach another drawing from the AM-WorkFlow database as an external reference
to the current drawing. (AutoCAD specific)
AMWINSERT Insert another drawing from the AM-WorkFlow database in the current drawing as a
block. (AutoCAD specific)
AMWWBLOCK Save a block as a new document in the AM-WorkFlow database. (AutoCAD
specific)
AMWEDIT Let the user edit the titleblock. The dialog used in AutoCAD is shown in Figure 2.
Depending on the CAD packages capabilities this functionality can also be achieved
in a more user friendly manner by letting the user click the titleblock part he wants
to edit in the drawing and also let the editing be done in the drawing.
AMWOPTIONS Let the user set preferences. The configurable options depend on the application, but
in principle all of the options should be stored in the user profile (see Figure 4). The
most important option to the user is the option to redefine AutoCAD commands to
their AM-WorkFlow equivalent. For example, typing 'OPEN' would invoke
'AMWOPEN'. If the user selected 'Redefine using AM-WorkFlow', this would
directly go to AM-WorkFlow. If he selected 'Redefine using file browser', this would
first display a common Windows file browse dialog (see Figure 3).
AMWHELP Displays a simple dialog showing some help about the various commands. This is
the only help available, no help files are used (see Figure 5).
AMWVIEWRED Displays the redlines in the current drawing.
AMWHIDERED Hide the redlines again.
AMWUPDAT Transfers the information from the titleblock to AM-WorkFlow.

11
The XREF, INSERT and WBLOCK commands are specific to the AutoCAD environment. For other CAD packages similar
commands could be defined for their equivalents. These commands should display the same behavior to the user and perform the same function
as their original.

- memo 60222 page 4 -

Figure 2. The dialog box to edit the current titleblock contents (The AMWEDIT command).

Figure 3. Dialog box to open a file, including a button to pass through to AM-WorkFlow.

- memo 60222 page 5 -

 Figure 4. The options dialog as used in the AutoCAD ACADDSI. Other applications should use a similar
dialog for user preferences.

Figure 5. The dialog showing very basic help for the various commands.

Functions to be redefined or captured

The following functions should be redefined:

OPEN
SAVE
SAVEAS
CLOSE

- memo 60222 page 6 -

 NEW

Depending on the settings in AMWOPTIONS these should be:

a. not redefined at all
b. redefined to show a user interface similar to the one in use by the CAD package
c. redefined to use the AM-WorkFlow user interface where applicable (as in the AMW... commands)

Also, if possible, a number of events should be trapped (regardless of the settings in AMWOPTIONS):
Opening of a file (locks a drawing).
Saving of a file (does not unlock a drawing, but might set a flag that the drawing is changed so that the
applications side knows that the card should be edited when the drawing is unlocked).
Saving of a file under a new name (unlocks the old drawing and creates and locks a new drawing).
Creation of a new document (creates and locks a new drawing).
Closing of a file (unlocks a drawing).
On these events locking and unlocking of the appropriate cards should be performed.

- memo 60222 page 7 -

Database Functions
The AutoManager database is a dBase III compatible database with proprietary index files. Each document in
the database has its own unique ID. This ID is an alphanumeric value with a configurable length that is stored
in a required field in the database. Because it is not possible to have more than one card referring to the same
file, documents in the database can be found by either filename or document ID. In the AMDSAPI all functions
operate on card IDs.

When a file is opened the application should call DsiQueryIDFromFilename to get the corresponding card ID.
If this fails the document is not yet in the database and should be added with a call to DsiNewCard with the
source card ID set to NULL. This should only be done if the user confirms that he wants to add the file.
When the document can be found in the database, it should be locked with a call to DsiLockCard. If this fails
the document is probably locked by some other application, and the application should at least notify the user
of this problem, but, if possible, close the file.
When the user closes the current file, the application should call DsiUnlockCard, and let the user edit the card
with DsiEditCard. This call lets the user interface of AM-WorkFlow pop up and go in edit mode.

To access the contents of the current card in the database, two functions are defined: DsiGetField and
DsiPutField. These are to be used to query the field contents to update the titleblock and vice versa.

- memo 60222 page 8 -

Profile Functions
Profiles implement a mechanism to store settings much like the way MS Windows 3.1 .INI files do, with the
exception that binary data can also be stored. The same combination of Sections and Keys is used, also with a
similar notation. A common practice in the use of profiles is to subdivide sections into subsections by using the
following notation: Section.Subsection . The profiles are not ASCII text, but a special file format, with a
special API. Part of this API is published through AMDSAPI.

User profiles

User profiles contain settings for the current user. Any configuration variables should be stored in this profile.
It is suggested that the application creates and uses a subsection of the section AMDSAPI , for example:
AMDSAPI.AutoCAD , AMDSAPI.Microstation or AMDSAPI.CadKey . Within its subsection the
application can store whatever data it needs to store. There are two functions defined for accessing user
profiles: DsiReadUserProfile and DsiWriteUserProfile.

Global profiles

The system profile contains settings for AutoManager. This can include global variables, also used by
BaseLisp. This system profile should be used with care, because this system profile contains the settings for all
users. The system profile is stored in a file that has the same name as the environment but with the extension
'.var'. There are two functions defined for accessing global profiles: DsiReadGlobalProfile and
DsiWriteGlobalProfile.

Note that most values such as integer and floating point values are stored in profiles as their ASCII
representations, but it is also possible to store binary data.

- memo 60222 page 9 -

Redline Functions
Redlines consist of a number of different concepts, all common to CAD packages:
Layers
Roles
Entities

Entities

Entities are the basic building blocks of a redline. These entities can be grouped on different layers. Each entity
consists of a DSIENTITY structure which contains either a polyline or an arc. All coordinates that are passed
in this structure are in document coordinates.

Roles

A role is the part a user plays in the creation and maintenance of documents. The default roles include:
Supervisor, Manager, Editor, User and Viewer. These are the roles that are used in AMW. Each of these roles
has it's own access rights to the different layers. AMDSAPI handles all access rights with roles, so the
application side will not have to bother about them.

Layers

Layers group different entities belonging to a certain role, with specified access levels for other roles. The layer
name can be retrieved with the function DsiRedQueryLayerName and can be used to create a layer in the
drawing if needed..

Processing redlines

The way to process redlines is:

1. Open the redlines file (with a call to DsiRedOpenRedline).
2. Query the number of layers (with a call to DsiRedQueryNumLayers).
3. Set the current layer (with a call to DsiRedSetCurrentLayer).
4. Get the layer name (with a call to DsiRedQueryLayerName) if needed.
5. Create a layer (or level).
6. Reset the current layer (with a call to DsiRedReStartRedline).
7. Get the next entity (with a call to DsiRedReadEntity) and draw it.
8. Repeat step 7 until no more entities on the layer.
9. Repeat steps 3 through 8 until no more layers.
10. Close the redlines (with a call to DsiRedCloseRedlines).

- memo 60222 page 10 -

General Functions
Before an application can do anything through AMDSAPI, the application should register itself through
DsiRegisterApp. For redlines a separate call should be made to DsiRedOpenRedline. When the application
closes it should call DsiUnregisterApp, which also unlocks any document that is still locked by the application
and closes redlines (but the preferred way is that the application does this with DsiUnlockCard and
DsiRedCloseRedline).
When the user wants to open a file that application can call DsiGetOpenFilename. Depending on a flag (one of
the arguments) this call will either display a common Windows file browse dialog with a button to go to AM-
WorkFlow, or directly go to AM-WorkFlow. The result of this action should be a filename. For saving of a file
the function DsiGetSaveFilename can be called. This function always goes directly to AM-WorkFlow and
creates a new card. The difference with DsiNewCard is that DsiGetSaveFilename generates a filename, where
DsiNewCard works on an existing filename.

- memo 60222 page 11 -

Setting up a link...
When an application starts, the first step should be to call DsiRegisterApp. If this call succeeds, it makes sense
to continue. The next step for the application is to find out what document is opened by the application. It
should then call DsiQueryIDFromFilename and DsiLockCard 2. If the application can have multiple documents
open, it should do this for all opened documents.
When the application has successfully locked the current document, it should figure out if that document has a
titleblock in it. If so, it should update the contents of the titleblock from the current card. This requires
repetitive calls to DsiGetField.
When the titleblock is updated, the application can query the existence of redlines with a call to
DsiRedOpenRedline. If there are none, this call returns an error. If there are redlines, the application should
query all redlines, layer by layer and entity by entity. When the redlines are done, the redline profile should be
closed with a call to DsiRedCloseRedline (More about redlines in the chapter Redline Functions).

22
If the application was launched by AutoManager with the current document as an argument, AutoManager has not locked this
document yet. This is the responsibility of the application.

- memo 60222 page 12 -

Function Descriptions
On the following pages all functions are described.

Error values

The following error values are defined:

NO_ERROR No error occurred

ERROR_ACCESS_DENIED Access to the specified card or field in the card was denied. This
can also happen when the card was already locked by another
application. This error is also returned from the user interface of
AM-WorkFlow when a dialog box is active.
ERROR_APP_REFUSED AMDSAPI refused the application's name, code or flags.
ERROR_BAD_PATH_NAME An invalid filename was given.
ERROR_NOT_FOUND The card for the specified filename could not be found.
ERROR_INVALID_CARDID The specified card ID is not valid or was not found in the
database.
ERROR_INVALID_DATA One or more of the given parameters are invalid.
ERROR_INVALID_FIELD The specified fieldname could not be found in the database.
ERROR_INVALID_HANDLE The specified application handle was invalid.
ERROR_LOCKED The card was already locked by this application (not really an
error).
ERROR_NOT_ENOUGH_MEMORY Not enough memory is available to complete the requested
operation.
ERROR_NOT_LOCKED Some action was attempted on a card that was not locked by the
current application or not locked at all, when it should have been.
ERROR_NOT_LOGGED_IN During registration it was not possible to get the current user
name, probably because there was no user logged in.
ERROR_NOT_FOUND The specified file was not found in the database.
ERROR_PROFILE_ACCESS An error occurred accessing a profile file, possibly the file is
corrupted or locked.
ERROR_RED_UNKNOWN_APP An attempt was made to read redlines that were created for a
different file type than the application uses.
ERROR_RED_LOCKED The redlines are locked by another process: they might be edited
in AM-WorkFlow.
ERROR_RED_NO_REDLINES No redlines available (not an error).
ERROR_RED_NOT_OPENED An attempt was made to read redlines that were not opened.
ERROR_RED_ALL_READY All layers have been completed.
ERROR_RED_LAYER_READY The current layer has been completed.
ERROR_RED_BAD_LAYERNUM The specified layer number is out of range.
ERROR_RED_BAD_ENTITY A incorrectly specified or unknown entity was encountered.
ERROR_START_APPLICATION AMDSAPI could not start either AM-WorkFlow or AM-Organizer.
ERROR_GENERIC An unknown or undefined error.

- memo 60222 page 13 -

DsiEditCard

Syntax:

DsiEditCard(pszCardID, pszCaption, pszMessage)

Arguments:

PTCHAR pszCardID
ID of the card to edit.

PTCHAR pszCaption
Caption to show in message box while waiting for AM-WorkFlow to finish.

PTCHAR pszMessage
Message to show while waiting for AM-WorkFlow to finish.

Returns:

USHORT
ERROR_ACCESS_DENIED
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NOT_LOCKED
NO_ERROR

Description:

DsiEditCard notifies AM-WorkFlow to pop up and let the user edit the card. The card should be
locked by the current application. AM-WorkFlow pops up in edit mode, and when the user exits
edit mode, either by canceling or accepting changes, control is returned to the calling application
and AM-WorkFlow is pushed to the background. This behavior is achieved by using a BaseLisp
function (amdsapi-edit), defined in platf_w.lsp.

- memo 60222 page 14 -

DsiGetField

Syntax:

DsiGetField(pszCardID, pszField, pszValue, usCnt)

Arguments:

PTCHAR pszCardID
ID of the card to query.

PTCHAR pszField
Field to query.

PTCHAR pszValue
The buffer to receive the field contents.

USHORT usCnt
The size of the buffer, including terminating zero.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_FIELD
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
NO_ERROR

PTCHAR pszValue
Contains the contents of the field.

Description:

DsiGetField requests the contents of one specified field from the specified card. This card should
be locked by the current application.

- memo 60222 page 15 -

DsiGetOpenFilename

Syntax:

DsiGetOpenFilename(pOfn, pszFunction, pszCap, pszMsg, fBrowse)

Arguments:

OPENFILENAME FAR * pOfn

Structure identical to the one used in the standard Windows GetOpenFilename call, with
identical purpose.

PTCHAR pszFunction
String specifying the operation that is going to be performed with the filename that is
obtained. This string is used in the user interface, and can be somthing like 'openm', 'insert' or
'xref'.

PTCHAR pszCap
Caption of message box displayed while waiting for AM-WorkFlow to finish.

PTCHAR pszMsg
Message to display while waiting for AM-WorkFlow to finish.

BOOL fBrowse
TRUE: first a common file open dialog is presented, with a button to go to AM-
WorkFlow.
FALSE: go directly to AM-WorkFlow.

Returns:

USHORT
ERROR_ACCESS_DENIED
ERROR_BUSY_USERINTERFACE
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_GENERIC
ERROR_NO_CFG_LOADED
ERROR_NOT_LOGGED_IN
ERROR_OTHER_WLL_OPEN
NO_ERROR

Description:

Notifies AM-WorkFlow to pop up and let the user select a filename to open in the application.
AM-WorkFlow does not perform any additional actions: the card should be locked by the
application using DsiLockCard. In AM-WorkFlow the user can browse through the database using
the normal methods (navigator, selections etc.), and can either select a drawing to be opened in
the application or cancel back to the application through two extra menu entries: Open drawing
in <application name> and Cancel back to application name. The application name used is
the one specified with the call to DsiRegisterApp. This behavior is achieved with a BaseLisp
function (amdsapi-open), defined in platf_w.lsp.

- memo 60222 page 16 -

DsiGetSaveFilename

Syntax:

DsiGetSaveFilename(pOfn, pszCap, pszMsg, fBrowse)

Arguments:

OPENFILENAME FAR * pOfn

Structure identical to the one used in the standard Windows GetSaveFilename call, with
identical purpose.

PTCHAR pszCap
Caption of message box displayed while waiting for AM-WorkFlow to finish.

PTCHAR pszMsg
Message to display while waiting for AM-WorkFlow to finish.

BOOL fBrowse
TRUE: first a common file open dialog is presented, with a button to go to AM-
WorkFlow.
FALSE: go directly to AM-WorkFlow.

Returns:

USHORT
ERROR_ACCESS_DENIED
ERROR_BUSY_USERINTERFACE
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NO_CFG_LOADED
ERROR_NOT_LOGGED_IN
ERROR_OTHER_WLL_OPEN
NO_ERROR

Description:

Pops up AM-WorkFlow or a file browser to get a new filename. AM-WorkFlow creates a new card
that the user can immediately edit, but does not perform any additional actions: the card should be
locked with the DsiLockCard call.

- memo 60222 page 17 -

DsiLockCard

Syntax:

DsiLockCard(pszCardID, fLock)

Arguments:

PTCHAR pszCardID
ID of the card that should be locked or unlocked.

BOOL fLock
TRUE: the card will be locked.
FALSE: the card will be unlocked.

Returns:

USHORT
ERROR_ACCESS_DENIED
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_LOCKED
ERROR_NOT_LOCKED
NO_ERROR

Description:

DsiLockCard attempts to lock the card for the given filename.

- memo 60222 page 18 -

DsiNewCard

Syntax:

DsiNewCard(pszCopyFrom, pszFilename, usMaxLen, pszResult, usCnt)

Arguments:

PTCHAR pszCopyFrom
ID of the source card. If NULL or an empty string is passed, a new card will be created, using
defaults depending on the configuration used by AM-WorkFlow.

PTCHAR pszFilename
Filename to attach to the new card. If this string is empty a filename will be generated by AM-
WorkFlow.

USHORT usMaxLen
Length of the buffer to receive the generated filename. If a filename is specified in the call to
this API, this argument is ignored.

PTCHAR pszResult
Pointer to buffer to receive the ID for the created card.

USHORT usCnt
Length of the buffer to receive the new card ID.

Returns:

USHORT
ERROR_BAD_PATH_NAME
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
NO_ERROR

PTCHAR pszFilename
Contains the generated filename if there is no ID returned in pszResult.

PTCHAR pszResult
Contains the new card ID if there is no filename returned in pszFilename.

Description:

DsiNewCard lets AM-WorkFlow make a new card for the given filename and optionally copy the
contents of the specified card in it. If no filename is specified, a filename will be generated by
AM-WorkFlow and returned in the pszFilename argument 3. The original card does not need to be
locked, the new card will not be locked by this call.

3
AutoManager Organizer does not generate filenames automatically. In stead a file dialog will be shown.

- memo 60222 page 19 -

DsiPutField

Syntax:

DsiPutField(pszCardID, pszField, pszValue)

Arguments:

PTCHAR pszCardID
ID of the card to modify.

PTCHAR pszField
Name of the field to modify.

PTCHAR pszValue
New contents for the field.

Returns:

USHORT
ERROR_ACCESS_DENIED
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_FIELD
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
ERROR_NOT_LOCKED
NO_ERROR

Description:

DsiPutField attempts to modify the contents for the specified field in the specified card. This card should be
locked by the current application. Some fields are not writeable by external applications. This is application
defined.

- memo 60222 page 20 -

DsiQueryFilenameFromID

Syntax:

DsiQueryFilenameFromID(pszCardID, pszFileName, usCnt)

Arguments:

PTCHAR pszCardID
The ID of the card to get the filename for.

PTCHAR pszFileName
Buffer to receive the requested filename.

USHORT usCnt
Length of the buffer, including terminating zero.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
NO_ERROR

PTCHAR pszFileName
Contains the requested filename, if found.

Description:

This call queries the filename for the given card ID from AM-WorkFlow. It is not necessary to
lock the card before this call. The requested filename is returned in the pszFileName.

- memo 60222 page 21 -

DsiQueryIDFromFilename

Syntax:

DsiQueryIDFromFilename(pszFilename, pszCardID, usCnt)

Arguments:

PTCHAR pszFilename
Filename to get the ID for.

PTCHAR pszCardID
Buffer to receive the requested ID.

USHORT usCnt
Length of the buffer, including terminating zero.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
NO_ERROR

PTCHAR pszCardID
Contains the requested ID, if found.

Description:

This call queries the ID for the given filename from AM-WorkFlow. It is not necessary to lock the
card before this call. The requested ID is returned in the pszCardID.

- memo 60222 page 22 -

DsiReadGlobalProfile

Syntax:

DsiReadGlobalProfile(pszCardID, pszSection, pszKey, pszValue, usCnt)

Arguments:

PTCHAR pszCardID
ID of the card to operate on.

PTCHAR pszSection
Section where key should be located.

PTCHAR pszKey
Key to read.

PTCHAR pszValue
Buffer to receive the value.

USHORT usCnt
The size of the buffer, including terminating zero.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR

Description:

Reads the value for the given key in the given section from the user profile. The system profile
might be the same profile as the user profile, but for AM-WorkFlow this is the profile for the
current environment.

- memo 60222 page 23 -

DsiReadUserProfile

Syntax:

DsiReadUserProfile(pszSection, pszKey, pszValue, usCnt)

Arguments:

PTCHAR pszSection
Section where the key should be located.

PTCHAR pszKey
Key to read.

PTCHAR pszValue
Buffer to receive the value.

USHORT usCnt
Size of the buffer, including terminating zero.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR

PTCHAR pszValue
Contains the value of the key.

Description:

Reads the value for the given key in the given section from the user profile. The user profile is
typically called <username>.ABU.

- memo 60222 page 24 -

DsiRedCloseRedline

Syntax:

DsiRedCloseRedline()

Arguments:

Returns:

USHORT
NO_ERROR

Description:

Closes the redlines profile.

- memo 60222 page 25 -

DsiRedNormalizeArc

Syntax:

DsiRedNormalizeArc(pArcNormal, pDsiEntity)

Arguments:

PARC_NORMAL pArcNormal
Pointer to structure that receives the normalized information on the arc.

PDSIENTITY pDsiEntity
Pointer to redline entity. This entity should be an arc.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
NO_ERROR

Description:

This API takes an arc entity, and calculates a different (more common) representation for it. This
information is returned in the structure of type ARC_NORMAL:

typedef struct _ARC_NORMAL {

DSIPOINTdspCenter;
double dRadius;
double dStartAngle;
double dEndAngle;
double adRotMatrix[9];
} ARC_NORMAL, FAR * PARC_NORMAL;

- memo 60222 page 26 -

DsiRedOpenRedline

Syntax:

DsiRedOpenRedline(pszCardID)

Arguments:

PTCHAR pszCardID
ID of the card for which to open the redline profile.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
ERROR_RED_LOCKED
ERROR_RED_NO_REDLINES
ERROR_RED_UNKNOWN_USER
NO_ERROR

Description:

Checks if there are redlines for the specified card, and if so, opens the redline profile for this card
and reads the layer definitions. The profile should be closed with a call to DsiRedCloseProfile.

- memo 60222 page 27 -

DsiRedQueryNumLayers

Syntax:

DsiRedQueryNumLayers(lpusNumRedlines)

Arguments:

LPUSHORT lpusNumRedlines
Points to a variable to receive the number of redline layers.

Returns:

USHORT
ERROR_INVALID_HANDLE
ERROR_RED_NOT_OPENED
NO_ERROR

LPUSHORT lpusNumRedlines
Contains the number of redline layers.

Description:

Queries the number of redline layers. This includes all layers, also those that the current user has
no access to.

- memo 60222 page 28 -

DsiRedQueryLayerName

Syntax:

DsiRedQueryLayerName(pszLayerName, usCnt, usLayerNum)

Arguments:

PTCHAR pszLayerName
Pointer to buffer to receive the redline layer name.

USHORT usCnt
Size of buffer to receive the name of the layer, including terminating zero.

USHORT usLayerNum
Number of layer to get the name for.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_HANDLE
ERROR_RED_NOT_OPENED
NO_ERROR

PTCHAR pszLayerName
Buffer filled with the name for the specified layer.

Description:

This API queries the name for a layer. A layer name can include spaces and most all other
characters. The primary use for this function will be to provide a possible layer name to the CAD
package, if needed.

- memo 60222 page 29 -

DsiRedReadEntity
Syntax:

DsiRedReadEntity(ppDsiEnt)

Arguments:

PDSIENTITY FAR* ppDsiEnt

Pointer to receive the pointer to the entity data.

Returns:
USHORT
NO_ERROR
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_RED_ALL_READY
ERROR_RED_BAD_ENTITY
ERROR_RED_LAYER_READY
ERROR_RED_NOT_OPENED
ERROR_RED_WRONG_USER

ppDsiEnt
Contains a pointer to the data the entity consists of, or NULL on error.

Description:

Reads the data for an entity on the current layer. After return ppDsiEnt points to a structure with
the following contents:

typedef struct _DSIENTITY

{
USHORT usEntType;
DSICOLOR dcEntColor;
USHORT usPntNumb;
PDSIPOINT aPoints;
PVOID pUserData;
} DSIENTITY, FAR * PDSIENTITY;

usEntType defines the type of the entity. All AM-WorkFlow redline entities (including text) are
reduced to the following simple type:
DSITYPE_POLYLINE is followed by a list of points that are to be connected.
DSITYPE_ARC is followed by three points on the arc. A circle is represented by two half
arcs, with both having three points.

dcEntColor contains the color for the entity in RGB values, using the following structure:
typedef struct _DSICOLOR
{
BYTE bRed;
BYTE bGreen;
BYTE bBlue;
} DSICOLOR, FAR * PDSICOLOR;

usPntNumb contains the number of points that follow.

aPoints is an array of points that all use the following definition:

- memo 60222 page 30 -

typedef struct _DSIPOINT
{
double X;
double Y;
double Z;
} DSIPOINT, FAR * PDSIPOINT;

pUserData is not used at the moment.

- memo 60222 page 31 -

DsiRedReStartRedline
Syntax:

DsiRedReStartRedline()

Arguments:

Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_HANDLE
ERROR_RED_NOT_OPENED
NO_ERROR

Description:

Resets the state of the current layer to the first entity.

- memo 60222 page 32 -

DsiRedSetCurrentLayer
Syntax:

DsiRedSetCurrentLayer(usLayerNum)

Arguments:

USHORT usLayerNum
Number of the layer to set as current.

Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_HANDLE
ERROR_RED_BAD_LAYERNUM
ERROR_RED_NOT_OPENED
NO_ERROR

Description:

Sets the current layer to usLayerNum. The layer numbers start at 1, and the number of layers can
be queried with a call to DsiRedQueryNumLayers.

- memo 60222 page 33 -

DsiRegisterApp

Syntax:

DsiRegisterApp(pszAppCode, pszAppName, ulFlags, hwndApp)

Arguments:

PTCHAR pszAppCode
Short code used by this application. This code is used internally in the AMDSAPI DLL.
Possible values: acad (AutoCAD), msdgn (Microstation), ckprt (CadKey) and gcgcd (Generic
CADD).

PTCHAR pszAppName
Descriptive name of the application, for example 'AutoCAD' or 'MicroStation'. For use in the
user interface, may not be NULL.

ULONG ulFlags
Flags describing capabilities or limitations of the applications. Currently defined:
DSIFLAG_MDI The application is capable of opening multiple files at the same
time.

HWND hwndApp
The handle for the main window of the application. This is used to move windows backward
and forward.

Returns:

USHORT
ERROR_APP_REFUSED
ERROR_INVALID_DATA
ERROR_NOT_ENOUGH_MEMORY
ERROR_NOT_LOGGED_IN
ERROR_START_APPLICATION
NO_ERROR

Description:

DsiRegisterApp registers it's name with the AMDSAPI DLL, which in turn checks with AM-
WorkFlow if this applications is allowed to use the AMDSAPI functions. This should be the first
action the application performs. Before termination of the application DsiUnregisterApp should be
called.

- memo 60222 page 34 -

DsiUnregisterApp

Syntax:

DsiUnregisterApp(VOID)

Arguments:

Returns:

USHORT
ERROR_INVALID_HANDLE
NO_ERROR

Description:

Removes the application from the list of registered applications. After this call no more AMDSAPI
calls are allowed. The supplied handle should be obtained with DsiRegisterApp. When cards are
locked by the application when this function is called, they are automatically unlocked. Although
the AMDSAPI DLL performs cleanup when it unloads - the DsiUnregisterApp function is called
for all registered applications - it is advised to call this function explicitly.

- memo 60222 page 35 -

DsiViewDocument

Syntax:

DsiViewDocument(pszFilename, pszCaption, pszMessage);

Arguments:

PTCHAR pszFilename
Name of document to view.

PTCHAR pszCaption
Caption of message to display while waiting for viewing to end.

PTCHAR pszMessage
Message to display while waiting for viewing to end.

Returns:

USHORT
ERROR_ACCESS_DENIED
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
NO_ERROR

Description:

If the AM-WorkFlow user interface is not already busy in a dialog box this will pop up a viewer
window to view the specified document.

- memo 60222 page 36 -

DsiWriteGlobalProfile

Syntax:

DsiWriteGlobalProfile(pszCardID, pszSection, pszKey, pszValue)

Arguments:

PTCHAR pszCardID
ID of the card to operate on.

PTCHAR pszSection
Section where the key should be located.

PTCHAR pszKey
The key to modify.

PTCHAR pszValue
Value to write to the key.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR

Description:

Modifies the given key in the specified section of the system profile. The system profile might be
the same profile as the user profile, but for AM-WorkFlow this will be the profile containing the
current environment.

- memo 60222 page 37 -

DsiWriteUserProfile

Syntax:

DsiWriteUserProfile(pszSection, pszKey, pszValue)

Arguments:

PTCHAR pszSection
Section in the user profile where the key should be changed/created.

PTCHAR pszKey
Key in the above section that should be changed.

PTCHAR pszValue
Value to change the key to.

Returns:

USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR

Description:

Changes the given key in the given section in the user profile to the specified value. If either
section or key or both do not exist, they are created. The user profile is typically called
<username>.ABU.

- memo 60222 page 38 -