RmimDesDoc-CommandLine

Introduction

In 2008, the need to be able to "drive" selected RMIM Designer "batch" functions from the command line arose in order to allow the ANT-automation of these publishing processes. Limited documentation of this interface was embedded in the Visual Basic (VBA) code in the RMIM Designer stencils and has been distributed as part of the releases in a text file. This documentation is presented here with sparse embellishment and corrections.

Jump to top of page

Invocation of Command Line Processing

The Visio application hides its own command-line invocation and therefore makes it difficult to do anything other than pass it a particular file to open. Therefore the strategy followed for this implementation was to create two support files. The primary one is an intermediary widget HL7VisioRunner.exe. The second support file is an HL7 static model (RMIM2) design named CmdLineDummy.vsd. Both files are installed in the Visio solutions directory as part of the standard RMIM Designer installation.

With those files in place, one invokes the HL7 RMIM Designer from the command line by using the command line to send a string (using the syntax defined below) to HL7VisioRunner. This, then, initiates the following sequence:

1. "HL7VisioRunner.exe" opens an stashes the command line in the registry
2. "HL7VisioRunner.exe" starts Visio passing it the RMIM2 design "CmdLineDummy.vsd"
3. The RMIM Designer software recognizes the opening of "CmdLineDummy.vsd" (by name) and tests for the presence of a valid command line string in the registry
4. If the RMIM Designer software finds a command line string, it retrieves the entries from the registry, parses them and tests them
5. Next, the RMIM Designer software executes the command line processes.
6. On completion, the RMIM Designer software places a "FAILED" or "DONE" semaphore in the registry.
7. "HL7VisioRunner" widget remains active throughout looking for the semaphore to be set, or for Visio to close (in case the user has to intervene). Only then does HL7VisioRunner close.

Note: If Visio stops processing the command line functions without closing (perhaps due to a an unexpected error), the HL7VisioRunner window will be displayed. The "Cancel" button on this window will attempt (and usually succeed) to close Visio, and subsequently itself.

Note on VBA command line module - CmdLineProcessor

This module contains the entire Command Line Functionality of the Visio RMIM Designer. If appropriate, it is invoked by the "Startup" sub of ThisDocument (which is invoked whenever a new drawing is opened). It replaces the key initialization functions of that subroutine, and REPLICATES rather than using the batch functions defined in the code of the BatchTask form.

This replication risks divergence, but the BatchTask code is very complex because it handles about a dozen functions, whereas this code needed only the simplest three of these. It does use the same HTML overlay and PNG generation functions that BatchTask uses.

Jump to top of page

Command line Syntax and Structure

Elements

RMIM Visio Command Line is expressed as a set of space-delimited elements (with quotes surrounding text elements that include a space.)

Sections

These elements are grouped into sections, each of which starts with a "-" and a keyword, as "-<keyWord>". Within a section, the values are single in many cases and repeat in others. The order of the "sections" is not important, except that "-TASK" section must appear somewhere or the line will be rejected, and if it is used, the "-DEBUG" section must be first.

The section key words and certain of the values must bedrawn from the set of enumerations listed here. These constrained elements are indicated with angle brackets

Section <keywords> List

The following lists the section keywords. Notes:

1. a number of elements are listed in angle brackets, such as <taskName>. These elements too are fully enumerated in sections that follow this one.
2. Whenever a task is followed by a quote-delimited string, the contents of the string describe the element that should replace this string in the command line
3. The words single or repeat in parentheses indicate whether or not the element repeats in the section.
4. Descriptive notes are listed below each element.

Section <keyWords>:

• -TASK <taskName> (single)
• -SUB <option> <option> ... (repeat)
• -INTENDEDDT "R1" or "R2" - affects which RIM release will be loaded from the repository (single)
• -DBPATH "Full path to a MIF file or a Design Repository. If the file is a MIF it can be either a MIF 'package' that holds both the RIM and Vocabulary, or a RIM core mif for which the appropriate Vocabulary MIF is in the same directory." (single)

  [If blank, will use last repository saved (last used) by Visio RMIM Designer]

• -SPATH "SourcePath prefix for source files" (single)

  points to the "root" of the directory(s) from which the "-SRC" files are drawn. If the "-SRC" files have no sub-directory info, then this is the directory from which the source files were drawn.

• -TPATH "Target path" (single)

  Interpretation depends on value of "-TPRELATIVE". (NOTE: several of the "-TASKs" create an internal algorithm for determining the output path.)

• -TPRELATIVE "Boolean (default = false)"

  If true, and if "-TPATH" is valued then ALL generated files are placed "under" "-TPATH" in sub-directory(s) that are determined by the sub-directories (if any) in the -SRC file strings.

  If false, and if "-TPATH" is valued, then "-TPATH" is the absolute target directory for all output.

• -IGNOREDTS "Boolean (default = false)"

  The output files for these processes do not have the same base name as the source files, and frequently, a single source produces multiple outputs. Therefore, the simple ANT date-time stamp (DTS) is not sufficient to test for result currency. Thus each TASK includes a check on the result and will only regenerate if the source (and/or the algorithm) is newer than the previous result.

  If -IGNOREDTS is true, the internal DTS check will be ignored and all results will be (re)generated.

• -SRC "Filename1 (perhaps with partial path at beginning)" "Filename2" "Filename3" ... (repeat)

<taskNames> Used By RMIM VISIO

The following is a list of allowed task names that can follow the "-TASK" section listed above:

• VSD2PNG

  Convert -SRC VSD files to PNG and create the HTML overlay.

  Saves results to an"edtiable" directory (for the html) and an "editable/images" for the PNG files, the location for the editable directory is determined as follows:

  • If -TPATH is not set, then the "target path" becomes the "source path" (-SRC) that was provided
  • If -TPRELATIVE is TRUE, then the "editable" directory is created by finding the source directory for the file, expressing it relative to the "target" path, and then the "editable" is SIBLING of the "resulting" dirsctory. (See example below)
    • If the source file is C:\test\input\domains\uvpa\sourcegraphics\abc.vsd, and"
      • If -SRC is C:\test\input\domains and -TPATH = C:\test\output\domains, and -TPRELATIVE is true, then the "editable" will be at C:\test\output\domains\uvpa\editable
      • If -TPATH=C:\test\output\processable\hmdvsd\editable, and -TPRELATIVE is false then the "editable" will be at c:\test\output\processable\hmdvsd\editable
    • NOTE: This behavior is dictated by logic internal to the Visio RMIM designer. The "sibling" directory decision is maintained because that is the logic used in the original HTML mapping batch task that is activated inside of Visio.

  [DTS NOTE: File currency is not tested. The process runs every time.]

• ALIGNDT

  Convert the data types used in the -SRC VSD models to align with whichever data type release is bound to the RIM (specified in -DBPATH) that is to be loaded when the RMIM Designer opens.

  (RIM releases 0.4 through 2.26 are bound to data types R1. RIM Releases 2.27 and beyond are bound to data types R2.)

  [DTS NOTE: File currency is not tested. The files are reviewed every time, but conversion will only be necessary for those whose data types are not bound to the correct release.]

• UPGRADE

  Upgrade -SRC VSD files from Visio 2000/2002 to Visio 2007/7 [ONLY available in Visio 2003/7]

  [DTS NOTE: File currency is not tested. The process runs every time.]

• REVERT

  Revert -SRC VSD files from Visio 2003/7 to Visio 2002 [ONLY available in Visio 2003/7]

  [DTS NOTE: File currency is not tested. The process runs every time.]

• CONVERT

  Converts the file format of the drawings between the VSD (normal Visio binary) format and the VDX (Microft's Visio xml format) This is used to support the correction of the GUIDS for Master shapes in the Visio 2002 files.. The direction depends upn the presence of one of two possible sub-tasks:

  • V2X Converts from VSD to VDX.
  • X2V Converts from VDX to VSD.

  [DTS NOTE: File currency is not tested. The process runs every time. and the result will over-wrtie any foile of the same extension in the target directory.]

• QUICKUPDATE

  Performs a quick update of the vocabulary constraints of coded attributes to make tem align to the current HL7 Static Model BNF, and then re-saves the file over itself. (Destructive.)

  [DTS NOTE: File currency is not tested. The process runs every time.]

• VALIDATE

  Performs an indepth validation of each model and class, and produces a text display that may be saved to document the results.

  [DTS NOTE: File currency is not tested. The process runs every time.]

NOTE: The "-SRC" files for all of these tasks listed above must be Visio "vsd" files. The sole exception is the CONVERT task with the X@V sub-task which convrts *.vds files to *.vsd.

<option> Names for VSD2PNG Task

The following lists the sub-task options (to be listed in "-SUB") for the VSD2PNG task:

• FIXVOC

  Scan/fix Domain specs before VSD2PNG

• RENAME

  Run "Rename" process before VSD2PNG

• RESAVE

  Resave the VSD in situ after either of above two options

Command Line Parsing Note

In keeping with convention, the command line will be parsed left to right, as a space-delimited string, in which double quotes are used to group a single value (ignore space delimiters within quotes). Both the -SUB and -SRC sections are repeating elements, and each new element is added to the set until a new section designator is reached.

Jump to top of page