1. Understanding the interfaces
2. Connection of the interfaces
   1. Theory
   2. Practical
   3. Hummingbird DM specific
3. Using DRS
   1. DRD checking and inspecting
4. Using DRD Processor
5. What to do in problem case
6. Contact Information

Understanding the interfaces

First of all to understand is the separation of DRD, DRS and HDMI.

Starting with DRS: The Document Related Script is a set of DMS related commands as a plugin/enhancement for the scripting language ACScript (Application Control Script) which is somewhere between batch files and VB script. As DRS is independent from DMS it is only a framework and an interface.

The HDMI (Hummingbird DM Interface) is the implementation of the DRS for Hummingbird DM. So specifying HUMMINGBIRD_DM as destination/addressed DMS results in the use of HDMI (wmHDMI.dll) when processing DRS. When using DOCSOPEN as destination/addressed DMS then the implementation of DRS is realized in the MAY Computer DOCS/DAI interface. Similar applies for MAY Computer eDAS.

DRD (Document Related Data) is the container to ship/generate/retrieve profile information and document file link. It attaches/combines the document file(s) with profile information. It's purpose is also to let you easily integrate business logic accessing and dealing with the profile information as text file or object. DRD is also DMS independent.

Connection of the interfaces

In the following is described how the interfaces are combined:

Theory

When performing a DRS usually the following actions are performed in the listed order:

1. A DRD object is created (for an existing document file) or loaded from a given DRD file.
2. Some defaults are added to the DRD object given in form of other DRD files.
3. Some other options or profile fields are set to predefined values.
4. Integration of business logic (based on specific conditions in the given DRD appropriate actions are performed).
5. The results of performed business logic may be additional DRD variables or profile field values which are added during step 4.
6. Processing of the ready prepared DRD against DMS system. The type of action (IMPORT, UPDATE, EXPORT, RETRIEVE etc.) performed against DMS is determined by the Action option property in the DRD. In this step the DMS system is contacted and DRS interface deals with the interface that implements the DRS module for the choosen DMS system.

Until step 6 you are DMS independent and as DRD is itself also DMS independent the profile field names you are using is up to you. You should choose names that are speaking (Title, Description, Author, Typist, DocType, Application, ...). The module that implements DRS for a specific DMS is responsible for mapping of DRD profile fields to DMS specific profile fields (and vice versa).

Practical

DRD interface is provided by the wmDRD.dll in the <Common Files>\MAYComputer folder. There is no general preconfiguration required for this interface.

DRS interface is provided by the wmDRS.dll in the <Common Files>\MAYComputer folder. There is no general preconfiguration required for this interface.

HDMI interface (DRS implementation for Hummingbird DM) is provided by the wmHDMI.dll in the <Common Files>\MAYComputer folder. This module implements DRS for Hummingbird DM and it requires some preconfiguration which is mainly done in the wmHDMI.ini (located in <Common Files>\MAYComputer folder). The main options to be set are:

[Global]
...
;Used forms
;Style: [<Library>.]<Form>=<FormName>

ProfileForm=<ProfileFormName>
SearchForm=<SearchFormName>
...
;DM Aliases for DRD profile items
;Used for conversion of DRD profiles to DM profiles
;(DRD -> DM)
;Style: Alias.DRD[.<Library>].<DRDFieldName>=<DMFieldName>|-
;To skip fields define "-" as alias
Alias.DRD.<DRDProfileFieldName>=<DMProfileFieldName>
...
;DRD Aliases for DM profile items
;Used for conversion of DM profiles to DRD profiles
;(DM -> DRD)
;Style: Alias.DM[.<Library>].<DMFieldName>=<DRDFieldName>|-
;To skip fields define "-" as alias

Alias.DM.<DMProfileFieldName>=<DRDProfileFieldName>

DOCS/DAI interface (DRS implemenation for DOCS Open) is provided by the wmDOCS1.dll in the <Common Files>\MAYComputer folder. Required preconfiguration must be done in the wmDOCS1.ini (same folder) and is similar to wmHDMI.ini (see above) - a wmDOCS1.ini sample can be obtained from MAY Computer on demand.

eDAS interface (DRS implementation for eDAS) is provided by eDAS.exe in the eDAS program folder. Required preconfiguration must be done in the appropriate eDAS OpenStore ini. But in eDAS case the default store ini can already be used with DRS.

There are some aliases set by default. You should enhance the aliases lists by adding aliases for profile fields you added to your Hummingbird DM database. Avoid to use dots (".") in your DRD aliases. You should try to keep profile names the same on the DM profile form and search form referenced by the wmHDMI.ini (or respectively in other forms used for imports by specifying FormName option in DRD). Do not change default DRD aliases Application, Title, Author and Typist!

As a recommendation write DMS names in upper case and DRD names in mixed case. (Names are case insensitive therefore this is only for better distinguishing and readability.)

Hummingbird DM specific

Important note: You may not use the field names as you were using for DOCS Open and DAI! Instead launch DM Designer as shown below:

PAINT32.EXE /XYZZY

Attention: When starting designer in this mode you should strictly avoid to make changes if you do not really know what you are doing! You should use this way only to lookup profile field names.

Another important note: All profile fields you want/need to set or retrieve for through DRD processing must be on the profile form that you are using for your DRD processing (which is determined by the ProfileForm and SearchForm setting in your wmHDMI.ini).

After login go to File -> Open from Database. Then choose the profile form that you have specified within wmHDMI.ini. Double clicking on a profile field shows you a dialog box with the field name on top that applies for use with Hummingbird DM API.

When the wmHDMI.ini has been applied to match your environment you must set the user name and password that HDMI interface uses to log on to Hummingbird DM. This login information is saved encrypted at:

HKEY_CURRENT_USER\Software\MAY Computer\wmHDMI

The information can be set by using the HDMI Set Login tool (HDMISetLogin.exe) at Start -> <Programs> -> DRS -> HDMI Set Login or Start -> <Programs> -> DRD Processor -> HDMI Set Login.

For IMPORT actions it is extremely important that you set all required fields to valid values. To check which fields are required have a look at Designer within database and on your profile forms as in both places a field can be set to be a required one. An error message like "Error 5011: Error saving profile." is the best sign that some required field is missing or an invalid value has been set.

Short summary: Apply wmHDMI.ini, wmDOCS1.ini, eDAS store ini or appropriate DMS configuration file to match your environment (used forms, profile field aliases). Make sure that you set all required fields to valid values. There maybe additional configuration required depending on used DMS system. For Hummingbird DM set the login information with "HDMI Set Login".

Using DRS

DRS.exe is the script interpreter for the DRS language which can deal with DRD and the supported DMS systems. The interpreter runs a DRS starting at SUB MAIN (if exists) or at first line (if no SUB MAIN exists).

To edit a DRS you can simple use Notepad or any other text editor. To run a script use the following command:

DRS.exe script="<MyDRSFile>"

On DRD Processor/DRS installation DRS files are usually assigned to be run on doubleclick with DRS interpreter and in context menu an edit method is added opening the script with notepad.

For first tests and to get familiar with DRD and DRS try the samples.

DRS interpreter simply runs a document related script (DRS file) as it is.

DRD checking and inspecting

If you get errors or simply want to examine what's happening then the first proposal is to turn on the debugger which can be done by adding the DEBUGMODE ON command at the begin of your DRS. If you get errors of missing or invalid aliases, check the following for missing or invalid values: Default DRD files loaded, Values set in your DRS script. If you are not sure about your resulting DRD that gets processed against DMS then you have two possibilities:

• Use the command DEBUGMODE ON and type SHOWDRD or EDITDRD in intermediate window right before the DRD is processed. You have also the possibility to switch to module specific variables tab. After processing the first command addressing a DRD you can view end even edit the DRD by double clicking the appropriate item.
  
• Use one of the following commands right before processing it to see the actual processed DRD:
  • SHOWDRD
  • WRITEDRDTOFILE <VariableName>, <DRDFile>[, <RebuildString>][, <IsCopy>][, <DRDName>]

Using DRD Processor

What is the difference between DRS and DRD Processor?

The answer is: DRS is "only" the script interpreter that runs a DRS starting at SUB MAIN (if exists) or at first line (if no SUB MAIN exists). DRD Processor does a little bit more. It runs a DRS (using DRS interpreter activex interface) for all files in a configured folder and provides some more features around the process like error handling and logging. It can also be used to watch the configured folder for new files arriving and then start the processing automatically.

It is maybe a good way to start testing some DRS files before using DRD Processor to get familiar with DRD and DRS. The DMSDONE method should be commented out in DRS scripts used in DRD Processor because done automatically only if complete work is finished.

A set of configuration options and flags are combined to a job within a DRC file. DRD Processor can be launched with such a file in commandline to edit the settings or to run the job as shown below:

To edit configuration:
DRDProc.exe file="<MyConfigFile>" /edit

To run job:
DRDProc.exe file="<MyConfigFile>" /run

DRD Processor provides some "environment" to help in batch DRD/DRS processing. Minimum configuration required is a folder and a DRS to process the files with. You should also set a valid logfile name. This logfile should always be investigated if something goes wrong.

What to do in problem case

First examine the following logfiles:

• Expecially when trying the first time try to run the Sample_Retrieve.drs DRS and choose a document to be retrieved. The displayed errors/warnings can be a good help to find out about missing aliases in wmHDMI.ini, wmDOCS1.ini, eDAS store ini or other DMS configuration file.
• DRS logfile (<Program Files>\DRDProc\DRS.log or <Program Files>\DRS\DRS.log)
• DRD Processor job logfile (as configured in used DRC file) when using DRD Processor
• DRD Processor main logfile (<Program Files>\DRDProc\DRDProc.log) when using DRD Processor
• HDMI Debug logfile (as configured in wmHDMI.ini but debug logging should be turned on only if necessary) when using Hummingbird DM
• Optionally additional logfiles you may write during processing of your DRS

Examine (default) DRD files loaded during DRS processing.

Debug your DRS using the DEBUGMODE ON command somewhere at the beginning of your DRS which causes DRS Debugger to show up when processing the DRS. You can then go through your script step by step having a look at what exactly happens.

Do not hesitate to contact us if you experience problems. Please send us the

• DRS you are processing,
• (default) DRD files you are using and
• Logfiles (see above)

Contact Information

Technical support and latest information on our products are available at http://support.may.co.at

E-Mail support: mailto:support@may.co.at

MAY Computer GmbH & Co KG
Microsoft Solution Provider
Galvanigasse 2
A-1210 Vienna / Austria
Tel.: +43/1/278 20 80 Fax: +43/1/278 20 80 /22
http://www.may.co.at
mailto:may@may.co.at