Data Masker for Oracle 5

The Data Masker application can be run in batch mode from a DOS command line or Windows based scheduler in order to automate the masking of data in a target schema.

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:

<Masking Set Filename>

The name of the masking set to load. This must be a full path including the drive and directory information. The Data Masker software will not use default directories in command line mode. If the masking set filename contains spaces, remember to enclose it in double quotes when placing it on the command line otherwise the Windows operating system will present it to the Data Masker software as multiple command line options.

-R

The signal to Run the masking set and perform the masking operations. 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.

-X

The signal to eXit after the masking set has completed. In order to determine if the masking set completed successfully or failed with an error it is necessary to examine the application exit code (see the discussion below).

-S <param>

The login Substitution parameter. The masking set can be configured with dummy login information in the Rule Controllers and have that information substituted by the command line. This functionality enables the target of a masking set to be determined at runtime. The format of the login substitution parameter is one of two forms. For TNSNames connections the format is...

... and for TCP/IP style connections the format is...

<DummySchema>@[<DummyIPorHostName>:<DummyPortNumber>:<DummySIDName>]=<RealSchema>/<RealPassword>@[<RealIPorHostName>:<RealPortNumber>:<RealSIDName>]

The Login Substitution Parameter section below contains more information and examples.

PARFILE

The name of the parameter file to read. This should be a full path including the drive and directory information. The Data Masker software will not use default directories in command line mode. If the parameter file filename contains spaces, remember to enclose it in double quotes when placing it on the command line otherwise the Windows operating system will present it to the Data Masker software as multiple command line options.

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.

Exit Codes

When run from a command line, the Data Masker software will return an exit code via the standard DOS mechanism. If the last run of the masking rules was a success then this exit code will always be zero. Any non-zero exit code implies that an error occurred while opening the masking set or while running the masking rules. If a non-zero exit code is returned the log file should always be examined to determine the error that occurred. Some of the more common exit codes are:

-1

Data Masker failed to start up. See logs for more information.

101

The masking set was not found. See the log file for more information.

201

The masking set run was canceled by user request.

301

Errors occurred during the run of the masking set. See the log file for more information.

401

Errors were found during the processing of the command line parameters. See the log file for more information.

1000-1999

Errors occurred during the pre-run checks of the masking set. See the log file for more information.

2210

License not valid. Your trial license may have expired.

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 for Oracle>start /wait "" Datamasker.exe C:\Net2000\DMO_TestSets\DMTest.MaskSet -R -X
C:\Program Files\Data Masker for Oracle>echo %errorlevel%
301
C:\Program Files\Data Masker>

The Start /Wait Command

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 behavior 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 for Oracle>REM the errorlevel will be set and the next command will only
C:\Program Files\Data Masker for Oracle>REM be performed once the masking set is complete
C:\Program Files\Data Masker for Oracle>start /wait "" Datamasker.exe C:\Net2000\DMO_TestSets\DMTest.MaskSet -R -X
C:\Program Files\Data Masker for Oracle>echo %errorlevel%
C:\Program Files\Data Masker for Oracle> ... perform next command

C:\Program Files\Data Masker for Oracle>REM the errorlevel will always be zero and the next command will be
C:\Program Files\Data Masker for Oracle>REM performed immediately without waiting for the Data Masker software
C:\Program Files\Data Masker for Oracle>REM to complete
C:\Program Files\Data Masker for Oracle>Datamasker.exe "" C:\Net2000\DMO_TestSets\DMTest.MaskSet -R -X
C:\Program Files\Data Masker for Oracle>echo %errorlevel%
C:\Program Files\Data Masker for Oracle> ... perform next command

The Login Substitution Parameter

The Login Substitution Parameter always follows the -S command line option and is used to replace dummy values configured in the Rule Controller with values specified on the command line. The format of the login substitution parameter for TNSNames connections is...

For example, a Rule Controller might be configured with a schema of FOO and a TNSName of BAR. In that case, a command line with the option -S FOO@BAR=scott/tiger@testdb1 would check each Rule Controller in the masking set and substitute the real connection information of scott/tiger@testdb1 in place of FOO@BAR. The dummy values of FOO@BAR 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=scott/tiger@testdb1 -S ABC@TESTDB=dmtest/dmtestpass@Test10G

For TCP/IP connections the format is slightly different

<DummySchema>@[<DummyIPorHostName>:<DummyPortNumber>:<DummySIDName>]=<RealSchema>/<RealPassword>@[<RealIPorHostName>:<RealPortNumber>:<RealSIDName>]

For example, a Rule Controller might be configured with a schema of FOO and a IPAddress of AAA, a port of BBB and a SID of CCC. In that case, a command line with the option

-S FOO@[AAA:BBB:CCC]=scott/tiger@[192.168.1.254:1521:TestDB]

would check each Rule Controller in the masking set and substitute the real connection information of scott/tiger at specified IPAddress, Port and SID in place of FOO@[AAA:BBB:CCC]. The dummy values of FOO@[AAA:BBB:CCC] serve as place holders for the real Schema, IPAddress, Port and SID information and allow the appropriate Rule Controller to be updated at run time.

The Parameter File Contents

The name of the parameter file always follows the PARFILE command line option. Each line of the parameter file specifies a command line option. Every option that can directly specified on the command line can also be specified in a parameter file. However, there are some options which can only be specified in a parameter file.

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
--
MASKSET=C:\Masking Sets\CmdTest_WithSubs.MaskSet
LOGINSUB=FOO@Bar||scott/tiger@testdb1
LOGINSUB=ABC@TESTDB||dmtest/dmtestpass@Test10G
AUTORUN=true
AUTOEXIT=true
DMOSUBVALUE00=Scott
DMOSUBVALUE05=TESTUSER

MASKSET

The name of the masking set to load. This must be a full path including the drive and directory information. The Data Masker software will not assume default directories in the parameter file.

AUTORUN

A flag which indicates if the opened masking set should be automatically executed and masking operations performed at startup. This value can be either of true or false.

AUTOEXIT

A flag which indicates if the Data Masker software should automatically exit after the masking set has completed operations. This value can be either of true or false.

LOGINSUB <param>

The login substitution parameter. The masking set can be configured with dummy login information in the Rule Controllers and have that information substituted by the command line. This functionality enables the target of a masking set to be determined at runtime. The format of the login substitution parameter is always

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.

DMOSUBVALUExx

Up to twenty replacement strings can be specified in the parameter file. The xx is a two digit numeric value. These runtime substitution values are designed to permit generic SQL statements to be dynamically adjusted at runtime for specific targets during batch operations.

Note: The keywords for these replacement strings are DMOSUBVALUE00 to DMOSUBVALUE19. If the text %DMOSUBVALUExx% 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 %DMOSUBVALUE05%_TEMP; and the parameter file contained a line stating DMOSUBVALUE05=TESTUSER then the actual statement that would be executed would be Truncate table TESTUSER_TEMP;. The value TESTUSER would be substituted for the %DMOSUBVALUE05% text in the SQL statement immediately before the statement was executed.

Note: It is possible to specify the same actions using both options on the command line and also in the parameter file. The arguments are processed in order from left to right on the command line and from top to bottom of the parameter file. The last value processed will be active setting.

Examples

Load a Masking Set file only

start /wait "" DataMasker.exe "C:\Program Files\Data Masker Oracle\Masking Sets\scott.maskset"

Load, Run and Exit

start /wait "" DataMasker.exe "C:\Program Files\Data Masker Oracle\Masking Sets\scott.maskset" -R -X

Load, Run and Exit and Substitute login TNSNames connection details

start /wait "" DataMasker.exe "C:\Program Files\Data Masker Oracle\Masking Sets\scott.maskset" -R -X -S FOO@BAR=scott/tiger@testdb1

Load, Run and Exit and Substitute login and TCP/IP connection details

start /wait "" DataMasker.exe "C:\Program Files\Data Masker Oracle\Masking Sets\scott.maskset" -R -X -S FOO@[AAA:BBB:CCC]=scott/tiger@[192.168.1.254:1521:TestDB]

Execute using a parameter file

start /wait "" DataMasker.exe PARFILE=C:\MaskingSets\SamplePARFILE.txt

Execute using a parameter file specified with other command line options

start /wait "" DataMasker.exe PARFILE=C:\MaskingSets\SamplePARFILE.txt -R -X