Interpreting the Command String that Visio Sends to Your Program | Developing Microsoft Visio Solutions (Pro-Documentation)

3 4

When an executable program ( exe ) is run, it receives a command string from the environment that launched the program. The command string that the Microsoft Visio engine sends identifies the Visio environment as the environment that launched the program. You can use some of the values contained in the command string to retrieve certain objects in addition to arguments for the program. The values in the string depend on how the program was run—from the Macros submenu or from a formula, with arguments or without.

Running the Program from the Macros Submenu

If the program is run from the Macros submenu—the user chooses it from either the Macros submenu (on the Tools menu, click Macros) or the Macros dialog box—the command string that the Visio engine passes to the program looks like this:

 "/visio=instanceHandle"

The significant portion of this command string is /visio, which you can use to confirm that the program was run from the Visio engine and not some inappropriate environment. The Windows handle instanceHandle is the handle of the Visio instance that the program was run from.

Running the Program when a Formula is Evaluated

When a formula that uses the RUNADDON function is evaluated, the command string that the Visio engine sends to your program depends on the object that contains the formula. Following are examples of the command string that your program receives when a formula belonging to a shape, master, or style object is evaluated.

A shape formula that uses RUNADDON

If a shape formula uses a runaddon function to run a program when it is evaluated, the Visio engine sends a command string to the program, such as the following:

 /visio=instanceHandle /doc=docIndex /page=pagIndex /shape=NameID

Various parts of the command string identify objects that contain the shape whose formula ran the program.

docIndex is the index of the Document object.
You can use this value to get the corresponding Document object from its collection. For example:
```
 Set docObj = appVisio.Documents.Item(docIndex) 
```
pagIndex is the index of the Page object.
You can use this value to get the corresponding Page object from its collection. For example:
```
 Set pagObj = appVisio.Documents.Item(docIndex).Pages(pagIndex) 
```
NameID is the NameID property of the shape whose formula was evaluated.
You can use this value to get the corresponding Shape object from its collection. For example:
```
 Set shpObj = appVisio.Documents(docIndex).Pages(pagIndex).Shapes(NameID) 
```

A master formula that uses RUNADDON

If the formula that was evaluated is in a master rather than in a shape on a drawing page, the command string looks like this:

 /visio=instanceHandle /doc=docIndex /master=masterIndex /shape=NameID

masterIndex is the index of the Master object.

In this case, you would get the Shape object as follows:

 Set shpObj = appVisio.Documents(docIndex).Masters(masterIndex).Shapes(NameID)

A style formula that uses RUNADDON

If the formula that was evaluated is in a style rather than a shape or a master, the command string looks like this:

 /visio=instanceHandle32 /doc=docIndex /style=NameID

In this case, you would get the Style object as follows:

 Set styleObj = appVisio.Documents(docIndex).Styles(NameID)

Running the Program with Arguments

If a cell formula uses a runaddonwargs function to run the program, the command string includes the specified arguments:

 /visio=instanceHandle /doc=docIndex /page=pagIndex      /shape=Sheet.ID arguments

If a custom menu command or toolbar button's AddOnArgs property contains arguments, the command string looks like this:

 /visio=instanceHandle arguments

The arguments string can be anything appropriate for your program. The entire command string is limited to 127 characters including flags (/visio=, /doc=, /page=, and /shape, for example), so in practice the arguments should not exceed 50 characters. If the entire command string exceeds 127 characters, an error occurs and Visio will not run the program.

Running the Program from the Startup Folder

If the program is run from the Visio Startup folder, the command string also includes the flag /launch.

 /visio=instanceHandle /launch

Parsing a Command String

Parsing is the process of separating statements into syntactic units—analyzing a character string and breaking it down into a group of more easily processed components.

To retrieve and parse a command string, use the functions provided by your development environment for that purpose. In Microsoft Visual Basic, for example, use Command to retrieve the command string and string functions, such as Mid and StrComp, to parse it.