MYRIAD Integration Methods
This document
gives a brief overview of how to integrate an application with MYRIAD. The following sections appear in this
document:
Integration Methods
Command Line Arguments
Document Stack File
Myrcom32
DLL Integrations
Native DDE Messaging
Using MYRCMD
MYRTEST
DDE Commands
DDE Notifications
Integration Methods
You can integrate
multiple applications with MYRIAD simultaneously. Each integrating application can have a unique notification
message and can send any execution command to MYRIAD, providing more freedom
when developing integrations since you are not limited to a single channel of
communication. This section describes
the available integration methods.
Command Line Arguments
You
can use simple command line arguments to control various MYRIAD features or
to pass files to MYRIAD. These
commands include disabling redlining, the Document Stack Manager, or
printing; launching MYRIAD with two specified files in Side-by-Side Compare
mode; and many others. For a complete
listing of these commands and how to use them, see the Command Line
Arguments section of the on-line Help system.
Document Stack File
The
document stack file (*.dsf) contains the files opened in MYRIAD, whether they
were opened using the File/Open command or through the Document Stack
Manager. You can manually create or
edit a document stack file to control what files are contained in the stack,
including redline files, and how they are displayed by using an ASCII text
editor, such as Windows' Notepad application.
MYRCOM32
MYRCOM32
is a simple, 32-bit application included with MYRIAD that you can use to send
commands to MYRIAD. The MYRCOM
directory is located in the INTGCLT directory within the main MYRIAD32 (or
equivalent) directory. You can use it
to send DDE commands to MYRIAD, to pass files to MYRIAD, or to perform
commands contained in a script file.
On a more complex level, you can use the -queue command, which
allows MYRCOM32 to scan a given directory at specified intervals for all
script files and perform the commands they contain (for more information on
using the -queue command, see Advanced MYRCOM32 later in this
document). Except when using the
-queue command, MYRCOM32 will launch MYRIAD, if necessary, establish the
connection, perform the command or commands, then terminate. The MYRIAD session will remain running.
You
launch MYRCOM32 from the command prompt.
Once at the command prompt, go to the MYRIAD32 (or equivalent)
directory and type MYRCOM32, followed by the appropriate command, as shown in
the examples below. To give more than
one command, simply separate the commands with a space.
For
DDE commands:
Format: MYRCOM32 -DDE [command] -DDE [command]
Example: MYRCOM32 -DDE
ff_load(c:\images\myimage.dwg)
-DDE window(EXECUTE_WINDOW_TILE)
For
commands contained in script files:
Format: MYRCOM32 -script [path\filename]
Example: MYRCOM32 -script c:\scripts\test.scr
For
user-defined macros:
Format: MYRCOM32 -macroname [arg1[arg2[argX...]]]
Example: MYRCOM32 -mymacro sample.dwg
Advanced
MYRCOM32
Use
the following steps to create a macro:
1. Set up a
section in the MYRCOM32.INI with the name of the macro you are creating
(i.e., [mymacro]).
2. Add a series
of commands under the new section with key names of "cmd#=", where # is replaced with a number (cmd1=,
cmd2= etc). For example:
[mymacro]
cmd1=
cmd2=
cmd3=
3. Assign each
command a dde command, as shown below.
[mymacro]
cmd1=ff_load("%1P")
cmd2=print(EXECUTE_PRINT_QUICK)
cmd3=delete_item("%1P")
4. During
execution of the macro, parts of the commands can be replaced with
command-line parameters. To indicate
this, insert %[number][P] into your commands. The number represents which space delimited command line
parameter MYRCOM32 will use. MYRCOM32
will use the current directory to figure out the full path and filename for a
command line parameter that contained only a filename.
To
execute a macro, type the following at the command prompt:
myrcom32 -mymacro
c:\files\dwg\sample.dwg
or
c:
cd \files\dwg
myrcom32 -mymacro sample.dwg
The
second example would work because the macro was using %1P instead of %1 and
MYRCOM32 used the current directory to determine the full path and filename.
You
can instruct MYRCOM32 to periodically scan for script files and perform the
commands they contain by using the -queue command. This can be particularly helpful for batch printing. This command will launch MYRIAD, if
necessary, and periodically scan a specified directory for script (*.SCR)
files. If it finds any, it will read
the oldest script file in the directory and execute all listed commands. After all commands are completed, MYRCOM
will erase the script file and resume scanning for more script files. MYRCOM will
remain running until someone closes it or the MYRIAD session. The directory searched, frequency of the
scans, and even the file extension searched for is determined in the
MYRCOM32.INI file (see MYRCOM32.INI below).
You
use this commands just as any other MYRCOM32 switch described above. At the command prompt, go to the MYRIAD32
(or equivalent) directory and type MYRCOM32 followed by the switch.
Example: MYRCOM32 -queue
When
using the -queue command to perform batch printing, you can override the
default printer specified in the MYRCOM32.INI file by placing the following
command in the script file.
Format: set_printer(printer name)
You
restore the default printer by adding the following command to the end of the
script file.
Format: restore_printer()
MYRCOM32.INI
MYRCOM32.INI
contains the following settings:
queuedirectory=c:\temp
Points
to the directory MYRCOM32 will scan for script files when in queue mode.
scriptfile_wildcard=*.scr
Specifies
the type of file MYRCOM32 will search for when looking for scripts in queue
mode.
queuetimer=10000
Frequency
(in units of 1/1000 of a second) at which MYRCOM32 will scan for scripts when
in queue mode.
timebuffer=1000
Length
of time (in units of 1/1000 of a second) to pause between script commands.
freespaceminimum=20000000
Minimum
amount of free disk space (in bytes) needed before sending a print job. If there is less disk space available than
specified here, MYRCOM32 will wait before sending another print command to
MYRIAD. This value should be based on
the largest print job expected.
The
[Printers] section is maintained by the application and should not be altered
by the user. To change printers, use
the printer script commands shown above.
DLL Integrations
You
can perform integrations using MYRCMD16.DLL, MYRCMD32.DLL, or MYRIO.DLL. All the files and libraries needed to
perform DLL integrations are located in the INTGCLT\MYRCMD directory in the
main MYRIAD32 (or equivalent) directory, and are listed below.
MYRCMD
MYRCMD16.DLL - 16-bit integration DLL
MYRCMD16.LIB - 16-bit import library
MYRCMD32.DLL - 32-bit integration DLL
MYRCMD32.LIB - 32-bit import library
IGCINC.H - All structure definitions
(included by MYRCMD.H)
VWDDE.H - Integration routine prototypes
(included by MYRCMD.H)
MYRDDEDF.H - DDE specific data definitions
(included by MYRCMD.H)
MYRCMD.H - Main integration header file
(you include this file in your code)
MYRIO.DLL
is used to control the image loading and display system, and allows you to
control image, markup, and document stack loading. API routines that are exported by this DLL are called at
various points during the file I/O operations within MYRIAD. You can replace this DLL with one containing
your own functions to control these events.
This allows you to seamlessly integrate applications, such as document
databases, which need to be able to determine the images to load instead of
using the standard open dialog boxes.
Each
of the MYRCMD files contain all the possible DDE commands and allow the most
powerful and versatile method of integrating with MYRIAD. The 16-bit MYRCMD16.DLL allows for
integrations with 16-bit applications while the 32-bit MYRCMD32.DLL is used
for 32-bit applications. For more
information on integrations using the MYRCMD files, see Using MYRCMD
later in this document.
The
API routines found in MYRCMD.DLL are shown below.
StartAndInitServer
This
routine is used in the event MYRIAD is not running when you need to
connect. It launches MYRIAD and
establishes a connection. If MYRIAD
is already running when this function is called, it has the same effect as
InitServer.
Parameters:
ServerName
- Pointer to the MYRIAD executable
filename
(MYRIAD_EXECUTABLE_NAME)
Returns:
BOOL indicating success or failure
InitServer
This
routine establishes a connection when MYRIAD is already running.
Parameters:
None
Returns:
BOOL indicating success or failure
IsServerUp
This
routine determines if a connection has been established with MYRIAD and is
used to determine if you need to establish a connection prior to making calls
to send data to MYRIAD.
Parameters:
None
Returns:
BOOL indicating success or failure
CloseConversation
This
routine closes the conversation with MYRIAD, but does not close the MYRIAD
application. To close MYRIAD and the
conversation from your integrating application, send the CLOSE_SESSION
execution command to MYRIAD.
Parameters:
None
Returns:
BOOL indicating success or failure
SetNotifyWindow
You
must call this routine to receive notification messages from MYRIAD. It allows you to specify the window handle
that will receive the INTG_NOTIFY_CALLBACK_MESSAGE when notification messages
are received from MYRIAD. This single
message is used to notify the integrating application of all notification
messages sent from MYRIAD to the integrating application.
The
LPARAM of the INTG_NOTIFY_CALLBACK_MESSAGE contains a pointer to a
NotifyCallbackRecord structure, which contains the message ID, data status,
and the data sent from
MYRIAD.
This architecture allows you to have
a single routine handle all the notification messages sent from MYRIAD.
Parameters:
hWnd - HWND of the window to
receive the INTG_NOTIFY_CALLBACK_MESSAGE
Returns:
BOOL indicating success or failure
ProcessExecutionString
This
routine takes the execution command to send to MYRIAD in string format and
sends it.
Parameters:
pString - Null terminated string containing the command to send
to MYRIAD
Returns:
BOOL indicating success or failure
ProcessExecutionCommand
This
routine takes the execution command to send to MYRIAD in structure format (a
pointer to a data structure that corresponds to the data to send for that
particular command) and sends it.
Parameters:
Command - ExecutionCommandType enumeration specifying the command being
sent
pData - Pointer to the record
structure for the command being sent
Returns:
BOOL indicating success or failure
ProcessOnetimeExecutionString
This
routine encapsulates the process of starting MYRIAD, if necessary,
establishing a connection with MYRIAD, sending the given string command to
MYRIAD, and then closing the conversation.
This routine is useful if you have only a single command to send
MYRIAD.
Parameters:
pString - Null terminated string containing the command to send to
MYRIAD
bStartMYRIAD - Boolean indicating that MYRIAD is to be
started prior to sending the command
ProcessOnetimeExecutionCommand
This
routine is identical to ProcessOnetimeExecutionString, except it takes the
command in structure form.
Parameters:
Command - ExecutionCommandType enumeration of the command being sent
to MYRIAD
pData - Pointer to the record structure for the command
bStartMYRIAD - Boolean indicating that MYRIAD is to be
started prior to sending the command
Returns:
BOOL indicating success or failure
CancelExec
This
routine is used to cancel an outstanding request made with the
ProcessExecutionString or ProcessExecutionCommand routines. All commands are sent to MYRIAD
asynchronously. If a command is not
processed within a given time frame, such as if the communications link is
dropped, you can cancel the outstanding request using this routine.
Parameters:
None
Returns:
BOOL indicating success or failure
Specific
DDE Commands
The
following commands are DDE specific, and will not exist for other
communications protocols.
SetServerName
This
routine is used to set the DDE server name for MYRIAD and is utilized only if
NETDDE is being used. If you are
using NETDDE, set up MYRIAD as a NETDDE share, which requires the last
character of the server name to be '$'.
This routine allows you to set the server name to whatever you
specified in your network configuration.
If you are not using NETDDE, a default server name will be used.
Parameters:
ServerName - Null terminated string specifying the server name to use for
DDE connection
Returns:
BOOL indicating success or failure
GetServerName
This
routine allows you to retrieve the name of the MYRIAD server.
Parameters:
ServerName - Buffer to be filled with the null terminated server name
string
MaxLength - The maximum number of bytes which can be stored in the
ServerName buffer
Returns:
DWORD returned from DdeQueryString used
to return the server name
GetTopicName
This
routine allows you to retrieve the name of the MYRIAD topic being used.
Parameters:
TopicName - Buffer to be filled with the null terminated topic name
string
MaxLength - The maximum number of bytes which can be stored in the
TopicName buffer
Returns:
DWORD returned from DdeQueryString used
to return the topic name
GetItemName
This
routine allows you to retrieve the name of the MYRIAD item being used.
Parameters:
ItemName - Buffer to be filled with the null terminated item name
string
MaxLength - The maximum number of bytes which can be stored in the
ItemName buffer
Returns:
DWORD returned from DdeQueryString used
to return the item name
You
can use either the structure or string form of these commands, but the
structure form is generally preferred.
The commands are specified using keywords when in string format, and
using enumerated type when in structure format. Each command has a structure associated with it that specifies
the data to be sent to MYRIAD to perform the command. The ProcessExecutionString and
ProcessExecutionCommand routines are the API routines used to send the
commands to MYRIAD, so are generally the most heavily used commands. Your single notification message handler
(see example below) handles all the notification messages sent from MYRIAD to
your integrated application.
The
following code segments show how to perform the FF_LOAD command using the
string format and the structure format.
The FF_LOAD command takes the filename of an image to load and
displays the file. The first example
simply uses the one-time execution API to perform the operation, so you do
not have to worry about managing the communications connection. The second example shows both the use of
the connection establishing routines and the use of the structure form of the
commands. It is assumed your application correctly loads the MYRCMD16.DLL (or
MYRCMD32.DLL) and includes the integration header files (by including the
MYRCMD.H). Note that these examples
are in "C" form and that the MYRTEST sample application can be used
as an example as well.
Sample
Code in String Format:
/*************************
This routine is called to "do" our integration
*****************************/
MyMYRIADIntegration(void)
{
ProcessExecutionString("ff_load(c:\images\myimage.dwg,FF
Load Demo,c:\images\myimage.mrk)", TRUE);
}
This
one-time command starts MYRIAD (The "TRUE" parameter indicates that
MYRIAD is to be started prior to establishing the communications link.
"FALSE" would indicate MYRIAD is already running and that the
communications link would simply be established.), establishes the
connection, sends the image load command to MYRIAD, and closes the
connection. Note that this is a
one-way communication from the integrating application to MYRIAD. The image filename is
c:\images\myimage.dwg, the description is "FF Load Demo," and the
redline file is c:\images\myimage\mrk.
Notice that the parameters are simply listed in order, separated by
commas. You must use the parameters
in the order listed in the documentation below. If you skip a parameter, you must still show the comma as a
placeholder. For example:
ff_load(c:\images\myimage.dwg,,c:\images\myimage.mrk)
Sample
Code in Structure Format:
/************************
Contains handle to the application's window *****************************/
HWND
hMyWindow;
/************************
This routine is called to do our integration *******************************/
MyMYRIADIntegration(void)
{
struct ExecuteSetNotifications
SetNotificationData;
struct ExecuteFFLoad LoadImageData;
/******** Initialize the server.
This call assumes MYRIAD is already running ********/
if(InitServer()){
/* Establish the callback window
to receive notification messages from MYRIAD */
SetNotifyWindow(hMyWindow);
/************************
Request desired notification **************************/
SetNotificationData.NotificationTypes
= INTG_NOTIFY_REQUEST_ALL;
ProcessExecutionCommand(INTG_EXECUTE_SET_NOTIFICATIONS,
&SetNotificationData);
/******************
Set up the command to load the image ********************/
strcpy(LoadImageData.Filename,
"c:\\images\myimage.dwg");
strcpy(LoadImageData.Description,
"FF Load Demo");
LoadImageData.bLoadAsExtension
= FALSE;
LoadImageData.RedlineFilename[0]
= 0;
ProcessExecutionCommand(INTG_EXECUTE_LOADFOLDERFILE,
&LoadImageData);
/*****************
Close the conversation with MYRIAD ***********************/
CloseConversation();
}
}
/************Main
window procedure; receives all messages for the application ****************/
long
FAR PASCAL WndProc(HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam)
{
switch (iMessage){
case WM_...:{
/*******************All
other window message stuff here***********************/
}
break;
case
IGC_NOTIFY_CALLBACK_MESSAGE:{
MyNotifyCallbackHandler((struct
NotifyCallbackRecord *)lParam);
}
break;
}
}
/***********
This routine handles all notification messages sent from MYRIAD ************/
void
MyNotifyCallbackHandler(NotifyCallbackRecord *pCallbackRecord)
{
switch(pCallbackRecord->Message)
{
case ...
/***********************
Commands for each notification message here ***********************/
/***
Data Status designates the status of the data packet - complete, incomplete,
etc. ****/
/***************
Data contains the data for the particular notification message
***************/
}
}
This
example is a little more involved than the first example, but is much more
robust. This code performs everything
you need to do to establish bi-directional communications with MYRIAD. To drop this code into your application,
include the header file MYRCMD.H, load MYRCMD16.DLL (or MYRCMD32.DLL), and
fill in the code to handle the execution commands and notification messages
you want to work with. Generally, you
would leave the conversation open as long as you need it (not just close
after setting it up as we do here), and close it when you are done
communicating with MYRIAD.
This
example could be made more compact if you used the string form of the
execution commands instead of the structure form (i.e., you would code
command strings like the first example instead of handling the
structures). In most situations, the
structure form of the commands is easier to deal with and maintain, but
either form can be used interchangeably.
Native DDE Messaging
If
your integrating application does not have the ability to call functions in a
DLL or if you do not require the complexity of the DLL integration, you can use native DDE messaging. This involves sending WM_DDE_EXECUTE
messages to MYRIAD to pass commands in string format. When using this integration method, you
cannot receive notification messages from MYRIAD.
Since
MYRIAD can accept integration commands in both structure and string format,
you can send DDE commands to MYRIAD using native DDE messages. The message WM_DDE_EXECUTE is used to pass
string information to MYRIAD, with the command string formatted exactly as
you format the string for the ProcessExecutionString API routine. For example, you can send the ff_load
command to load an image using the NULL terminated string:
Example:
ff_load(c:\images\myimage.dwg,FF Load
Demo,c:\images\myimage.mrk)
This
string would be sent using the WM_DDE_EXECUTE message and would load the
image file c:\images\myimage.dwg with the description "FF Load
Demo" and load the associated redline file c:\images\myimage.mrk. As noted in the Sample Code in String
Format heading under the Using DLL section, parameters are separated by
commas. If you skip a parameter, you
must use the comma placeholder.
Example:
ff_load(c:\images\myimage.dwg,,c:\images\myimage.mrk)
If
you are using DDEML.DLL to communicate with MYRIAD, all commands must be sent
with a XTYP_EXECUTE. The DDE Server
and Topic names you should use to connect with MYRIAD using Native DDE are:
Service: imageviewer
Topic: system
There
are a few drawbacks to using this form of integration. Although it is very easy to use native
DDE messages in many integrating
environments, the communication is unidirectional. You can send commands to MYRIAD, but you cannot receive
information from MYRIAD. Therefore,
commands such as get_iso_string, which generate notification messages to
return their information, have no value when using native DDE commands. In order to receive notification messages
(and therefore information) from MYRIAD, you must use MYRCMD.DLL which
establishes bi-directional communications.
Also,
since you have no way of receiving information from MYRIAD, you cannot
determine if the command executed successfully. If you use MYRCMD.DLL to integrate with MYRIAD, you can select
to receive notify_execution_return messages, which tell you the status of the
command's execution. With native DDE
messaging, you can only assume the command succeeded.
Using MYRCMD
MYRTEST
MYRTEST
is the MYRIAD integration test application, located in the INTGCLT\MYRTEST
directory within the main MYRIAD32 or equivalent directory. There is both a 16- and 32-bit
version. This application performs
every command that can be performed in the DDE integration and responds to
all the notification messages MYRIAD generates. The purpose of the integration test application is not only to
exercise every command in the integration, but to provide an example of how
to create the function calls necessary to execute each command and respond to
each notification message. You can
cut and paste the command(s) from the test application source code into your
code. The files contained in the
MYRTEST directory are listed below.
MYRTEST
MITEST16.MAK - 16-bit make file for the test
application
MITEST16.EXE - 16-bit executable for the test
application
MITEST16.DEF - 16-bit definition file for the test
application
MITEST32.MAK - 32-bit make file for the test
application
MITEST32.EXE - 32-bit executable for the test
application
MYREXEC.C - Module containing routines to
execute each integration command
MYRTEST.C - Main source module for the test
application
MYRTEST.RC - Resources for the test application
MYRTEST.H - Resource ID definitions
MYRDATA.H - Header file for the data
structures used by the test application
DDE Commands
This section
lists the commands and notification messages supported in the MYRIAD
release. These are found in the
integration header file, IGCINC.H.
All enumerated types this documentation refers to are also found in
IGCINC.H. Note that many of the File
and Window commands will close any open dialog boxes in MYRIAD. This behavior may change in the future.
To generate the
string form of the command, create a null-terminated string using the
command's string keyword (the name of the command in bold print) and each of
the fields found in the structure corresponding to that command enclosed in
parenthesis. Each of the parameter
fields must be separated by commas, and all fields must be filled. You can specify null fields (a comma as a
field place holder) for those fields which are optional. Refer to the
previous ff_load example for an illustration. Those commands which do not have a structure do not require
parameters, just open and close parenthesis.
Note: Those commands which take an enumerated type
as a parameter can have either the string name of the enumerated type element
or the ordinal value of the element coded in the string. For example:
zoom(EXECUTE_ZOOM_EXTENTS)
or
zoom(2)
Either form is
correct, but the string form of the enumeration element is more
readable. Note also that for 16-bit
compatibility, the enumerations for each of the commands is defined as an
IGENUM. Each of the enumerated types
which are used in the record structures appear immediately before the
definition of the record structure in IGCINC.H. In the documentation below, the enumerated type used for the
particular field is stated.
REFERENCE
LIST
This
section lists all DDE commands in this section. For more detailed information, lookup the command under the
appropriate subsection below.
FILE
LOADING/CLOSING COMMANDS
close_all Closes
all files
close_document Close
all currently open views of the given document
ff_clear Closes
all files and the document stack file
ff_init Loads
the specified document stack file
ff_load Loads
graphics file and markup, if desired
fileopen_tool Summons
the Open Image dialog box
new_docstack Creates
a new document stack
notify_return Responds
to notification message that requested a response
open_docstack Opens
an existing document stack
set_notifications Specifies
the notification messages the application receives
side_by_side Opens
the specified files in Side-by-Side Compare
GENERAL
SERVICE COMMANDS
add_ud_menu Adds
a user-defined menu item to MYRIADs menus
author_tool Invokes
the Author tool
birdseye_tool Invokes
the Bird's Eye tool
changemark_tool Invokes
the Changemark tool
clear_command_queue Clears
the command queue for the conversation
clear_ud_menu Clears
all user-defined menu items from MYRIAD's menus
clip Copies
to the Clipboard
delete_item Removes
the given file from the current document stack
docstack_tool Invokes
the Document Stack tool
enable_doc_modify Enables/disables
document stack modification
enable_menu_item Enables/disables
a menu item
enable_ud_menu Enables/disables
user-defined menu item in MYRIAD's menu
export_to_file Exports
the current image window image to a file
eyeglass_tool Invokes
the | 