Automated masking and exit is controlled by providing the appropriate command line options when the application starts. The options required to automate the masking process are:
<DummyServerName>[DummyDatabase]=<RealServerName>[RealDatabase]
The Database Substitution Parameter section below contains more information and examples.
<DummyLogin>@<DummyServerName>[DummyDatabase]=<RealLogin>/<RealPassword>@<RealServerName>[RealDatabase]
The Login Substitution Parameter section below contains more information and examples.
Unlike the other command line options, the PARFILE option must be specified with an equals sign as in the example below:
PARFILE=C:\MaskingSets\SamplePARFILE.txt
The Parameter File section below contains more information and examples.
If the Masking Set filename is specified and the -R option is omitted then the Data Masker application will simply load the Masking Set and return to manual operating mode.
Exit Codes
The exit code value is returned using the Windows standard mechanisms and can be determined via any of the available Windows methods. The most common way to view the return code is by using the DOS echo %errorlevel% command. The script output below shows such an operation. The 301 exit code means the masking set execution failed with an error.
C:\Program Files\Data Masker (Sql Server)>start /wait "" Datamasker.exe C:\Net2000\DMS_TestSets\DMTest.DMSSet -R -X C:\Program Files\Data Masker (Sql Server)>echo %errorlevel% 301 C:\Program Files\Data Masker>
There is an important consideration which must be noted when launching Windows applications from a command line. The Command application will, by default, launch a Windows application as a separate process. Once started, the Command application will not monitor the running Windows application process. In effect, this behaviour means that immediately after launching the Windows application, the Command application will return to the DOS prompt and continue with the next command statement. It is not possible to retrieve the exit code in such circumstances and the next operation in the Command application will begin to process long before the masking set has completed.
If it is necessary for the Command line application to wait until the masking set has executed (and the Data Masker software has shutdown) before it executes the next operation, then the Data Masker software must be launched with the DOS start /wait command. The example below illustrates these concepts:
Note: For some reason, the first parameter of the Start /Wait Command needs to be the Title of the Window To Open. Nobody knows quite why such an optional parameter would be required let alone be specified first in the list - however that is just the way it is. In the examples below the window title is entered on the command line as two double quote characters "". You can use whatever title you wish but the title parameter does need to be present or the Start /Wait command will improperly interpret the remaining command line parameters.
C:\Program Files\Data Masker (Sql Server)>REM the errorlevel will be set and the next command will only C:\Program Files\Data Masker (Sql Server)>REM be performed once the masking set is complete C:\Program Files\Data Masker (Sql Server)>start /wait "" Datamasker.exe C:\Net2000\DMS_TestSets\DMTest.DMSSet -R -X C:\Program Files\Data Masker (Sql Server)>echo %errorlevel% C:\Program Files\Data Masker (Sql Server)> ... perform next commandC:\Program Files\Data Masker (Sql Server)>REM the errorlevel will always be zero and the next command will be C:\Program Files\Data Masker (Sql Server)>REM performed immediately without waiting for the Data Masker software C:\Program Files\Data Masker (Sql Server)>REM to complete C:\Program Files\Data Masker (Sql Server)>Datamasker.exe C:\Net2000\DMS_TestSets\DMTest.DMSSet -R -X C:\Program Files\Data Masker (Sql Server)>echo %errorlevel% C:\Program Files\Data Masker (Sql Server)> ... perform next command
<DummyServerName>[DummyDatabase]=<RealServerName>[RealDatabase]
For example, a Rule Controller might be configured with a server name of XXXX, and a database name of YYYY. In that case, a command line with the option -D XXXX[YYYY]=XANTHE\MSSDMTEST[DMTest] would check each Rule Controller in the masking set and substitute the real server and database information of XANTHE\MSSDMTEST in place of XXXX and the database name DMTest would be substituted in place of the dummy value YYYY . The dummy values of serve as place holders for the real information and allow the appropriate Rule Controller to be updated at run time. A masking set can have multiple Rule Controllers. In that circumstance, multiple substitution parameters can be configured as shown below:
-D XXXX[YYYY]=XANTHE\MSSDMTEST[DMTest] -D AAA[BBBB]=CHRYSE\SQLSERVERTEST[Pubs]
The Login Substitution Parameter
<DummyLogin>@<DummyServerName>[DummyDatabase]=<RealLogin>/<RealPassword>@<RealServerName>[RealDatabase]
For example, a Rule Controller might be configured with a login of FOO, a server name of BAR, and a database name of ABCDB. In that case, a command line with the option -S FOO@BAR[ABCDB]=DataMasker/ItIsSecret@XANTHE\MSSDMTEST[DMTest] would check each Rule Controller in the masking set and substitute the real login information of DataMasker/ItIsSecret@XANTHE\MSSDMTEST in place of FOO@BAR and the database name DMTest would be substituted in place of the dummy value ABCDB . The dummy values of serve as place holders for the real information and allow the appropriate Rule Controller to be updated at run time. A masking set can have multiple Rule Controllers. In that circumstance, multiple substitution parameters can be configured as shown below:
-S FOO@BAR[ABCDB]=DataMasker/ItIsSecret@XANTHE\MSSDMTEST[DMTest] -S AAA@BBB[ABCDB]=DataMasker/SecretPassWord@CHRYSE\SQLSERVERTEST[Pubs]
The Parameter File Contents
Each line of a parameter file specifies an option. Note that it is not necessary to enclose file names which contain space characters in double quotes inside the parameter file. The use of double quotes is only required (by Windows) when the file name is specified directly on the command line. Below is an example of a parameter file:
-- Sample Parameter file for Data Masker Command Line -- usage: start /wait Datamasker.exe PARFILE=C:\MaskingSets\SamplePARFILE.txt -- LOGINSUB=DummyLogin@DummyServer[DummyDatabase]||DataMasker/DataMasker@N2KBUILD-PC\N2KTEST1[DMTest] LOGINSUB=XXXLogin@XXXServer[XXXDatabase]||DBSSourceUser/DBSSourceUser@N2KBUILD-PC\N2KTEST1[DBSSource] MASKSET=C:\Net2000\DMS_TestSets\CmdTestWithSubParams.DMSSet AUTORUN=true AUTOEXIT=true DMSSUBVALUE00=DM_INVOICE_LINE_HISTORY DMSSUBVALUE05=TESTUSER
<DummyLogin>@<DummyServerName>[DummyDatabase]||<RealLogin>/<RealPassword>@<RealServerName>[RealDatabase]
The Login Substitution Parameter section above contains more information and examples. If more than one login substition is required by the masking set, use multiple LOGINSUB lines in the parameter file as illustrated in the example above.
Usage: The keywords for these replacement strings are DMSSUBVALUE00 to DMSSUBVALUE19. If the text %DMSSUBVALUExx% is used in a Command rule or in the Where Clause of a masking rule, the value associated with that keyword will be replaced at runtime before the rule is executed. For example, if a Command rule included a statement like Truncate table %DMSSUBVALUE05%_TEMP; and the parameter file contained a line stating DMSSUBVALUE05=TESTUSER then the actual statement that would be executed would be Truncate table TESTUSER_TEMP;. The value TESTUSER would be substituted for the %DMSSUBVALUE05% text in the SQL statement immediately before the statement was executed.
Use of Delimiters in Substitution Value Text
The Data Masker Command Line Processor uses delimiter characters ('@', '[', ']' and '=') to determine the various components of the login name, password, database and instance in the Login and Database substitution parameters. If the contents of the Login and Database substitution parameters require the use of any of these characters (for example a password is "myp@ss") the presence of the delimiters will disrupt the interpretation and processing of the command line.
Delimiter characters used in the text of a substitution value must be marked with a preceeding backslash character (escaped). For example, a Login Substitution value implementing a password of myp@ss=1 would have its password written as myp\@ss\=1. The full Login Substution value might look like...
FOO@BAR[ABCDB]=DataMasker/myp\@ss\=1@XANTHE\MSSDMTEST[DMTest]
The command line processor will see the "\@" and "\=" and will interpret them as part of the substitution value text and not as the '@' and '=' delimiters. Similarly, the '[' and ']' characters can be escaped as "\[" and "\]". A single backslash can be represented in the text as "\\" if necessary.
Examples