DMM Studio Online Help › DMM Studio › Language Structure › General Commands

General Commands

The following are the General commands used in CA DMM scripts:

Break

Jumps the flow of control to the end of the immediate loop and executes the first instruction following the loop. This is different from a return, which leaves all loops and the function scope. Break is only meaningful inside of a loop.

Example:

function Foo()
{
     while (true)
     {
          while (z < 5)
          {
               ...
               if (x == false)
               {
               break;     // jumps to line following while (z < 5) {}
               }
               if (y == true)
               {
          return 5;     // returns from Foo() immediately
               }
          }
          if (x == false)
          {
               break;     // jumps to line following while (true) {}
          }
     }
     ...
     return -1;	// returns from Foo() immediately

}

ConvertBinaryToString

Converts a binary string to an ASCII string. It has one required parameter that is the string that contains binary data to be converted. The second parameter is an optional one and is binary. If the Boolean value is true, then it is converted to UNICODE string. But, if it is false, then it is converted to an ASCII string.

First Parameter:

The binary string

Second Parameter:

The Boolean value

Usage:

ConvertBinaryToString(<value>,[Boolean]);

Example:

var result = ConvertBinaryToString("000FFFDCB709E")

ConvertStringToBinary

Converts an ASCII string to a binary string. It has one required parameter that is the ASCII string to be converted. The second parameter is an optional one. If this parameter is true, then it is converted to UNICODE Binary.

First Parameter:

The ASCII string

Second Parameter:

The Boolean value

Usage:

ConvertStringToBinary(<value>,[Boolean]);

Example:

var result = ConvertStringToBinary("convert this string to binary")

Detect

Specifies the application associated with the script. Only one application can be associated with a script. On the source computer it is called from the Detection function. On the destination computer, it can be called from anywhere to resolve the application path. The interpreter resolves the APPLICATIONPATH keyword, which is not valid and should not be used before this call is issued. The script should call Detect in the Detection function to avoid unnecessary processing.

The parameters for Detect are the executable name and an optional registry key value. Both parameters are string values. The registry value path parameter is the full path to the registry value that holds the path to the executable. If the registry value is the default parameter, the path should end with the key name and a slash (see example following). In the Detection function the script must check the return value of Detect to determine whether to continue processing the script or to terminate the script.

First parameter:

The Executable name (string value)

Second parameter:

The registry path (string value)

Usage:

Detect ( <Executable name>, [Registry path] );

Examples:

if( Detect( "MyApp.exe", "HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\MyApp.exe\\"  ) == false)
{
     return;
}
if (Detect ( <executable Name>) == false)
return;

Execute

Exceutes an executable or dll. If the execute is unable to find the file or dll to make the call, the function returns false.

First parameter:

The first parameter is the path to what is to be executed. If the path is to a dll, then the API function needs to be right after two colons. The format of the dll call is PATH::APIFunctionName. The Execute for dll only looks for calls in two types of functions:

    int FunctionName();

    int FunctionName( const char * );

Second parameter:

If the call takes command line arguments, enter the arguments or enter an empty string.

Third parameter:

A Boolean value that indicates whether the script will wait for an Executable to complete. This parameter is ignored for dll calls.

Examples:

/*executes notepad with the following file, myfile.txt and waits for the process to end.*/
Execute( "c:\\windows\\notepad.exe", "myfile.txt", true );

/*executes notepad without parameters and waiting.*/
Execute( "c:\\windows\\notepad.exe" );

/* makes a call into the dll with parameters*/
Execute( "c\\windows\\Somelib.dll::CheckNetwork", "000d1");

**Note the format for dll PATH::APIFunctionName

Exit

Exits a script. If a value follows this keyword, it is written to the Debug and Error Logs. Parentheses are optional.

Examples:

Exit ("Exiting because MS Word does not exist on machine.");

ExpandString

Expand all environments variables in the given string and returns the result.

First Parameter:

String containing the environment variables.

Usage:

ExpandString(<string>);

Example:

var result = ExpandString("%WinDir%")

GetEngineData

Returns engine-related data based on the CommandID. It returns the error during migration if wrong CommandID is passed. You can use this command at both sides - store and apply - of the migration.

Note: You cannot use this command with the previous versions of the product. This command will give syntax errors if you try to use it in the older versions of CA DMM.

First Parameter:

CommandID (for example, GET_CUR_SEL) to get current selected node name (application or system settings) for migration.

Usage:

GetEngineData(<CommandID>);

Example:

var strNewPath = GetEngineData(GET_CUR_SEL)

GetMappedPath

Returns the new File path mapped to the new machine. The command also has the ability to take paths which have different delimiters than the common \\ character.

First parameter:

The old File path (string value)

Second parameter:

The path delimiter (string value)

Usage:

GetMappedPath( <old File path>, [<path delimiter>] );

Example:

newPath = GetMappedPath("c:\\old path\\file.txt");
/* newPath will equal the new file path.*/		
oldPath = "c:_old path_file.txt";
newPath = GetMappedPath( oldPath, "_" );
/* newPath will equal the new file path with the delimiter*/

/* for example newPath could equal e:_new path_file.txt*/

GetPlatform

Returns the computer's platform. The return values are: WIN2000, WINXP, WINVI, or WIN7 (see the Definitions List). It takes one parameter that indicates whether to get the platform of the source computer or the destination computer. This parameter is optional and is a Boolean value. False is the default and indicates the destination; True indicates the current computer.

Note: The Boolean parameter can only be used during General and Apply functions. The parameter causes a syntax error or runtime error if used otherwise.

First parameter:

The machine (Boolean value)

Usage:

GetPlatform( [Boolean] );

Example:

if (GetPlatform(DESTINATION) == WINXP)
    ApplyWinXPWord();

IsLikeNT

Queries the operating system to determine whether it is Windows 2000, Windows XP, Windows Vista, or Windows 7. The parameter is optional. If it is True, CA DMM get the OS of the source machine, otherwise it gets the OS of the destination machine. The default is False.

Note: The parameter can only be set to True during General and Apply functions. The parameter causes a syntax error or runtime error if used in a Store function.

First parameter:

The machine (Boolean value)

Usage:

Value = IsLikeNT([Boolean]);

Example:

IsLikeNT(SOURCE);

MapPath

Maps one path to another for the duration of a script. This path-mapping applies to all Apply operations following the MapPath keyword in the current script. This keyword has the effect of replacing all paths that match <old path> with <new path> in the following operations ApplyDirectory, ApplyFile, and ApplyMappedValue.

First parameter:

The old path (string value)

Second parameter:

The new path (string value)

Usage:

MapPath(<old path>, <new path>);

Example:

MapPath("c:\\winword\\data", "c:\\winword\\Application Data");

Message

Displays a message to the user. This command takes one parameter and is a string value. The parentheses are optional.

First parameter:

The Message text (string value)

Usage:

Message ( <string> );

Examples:

Message ("help!");

Option

Creates an option for displaying on the settings pages. It also associates the Store and Apply functions for the option. If the user chooses an option, then the functions associated to the option are invoked by the interpreter. The statement to display can specify a hierarchy by using slashes. For example, the option Microsoft Word\\Toolbar displays Microsoft Word on one line and Toolbar appears indented on the next line in the tree view of options.

First parameter:

The Option path (string value)

Second parameter:

The Store function name (string value)

Third parameter:

The Apply function name (string value)

Fourth parameter:

See Example: Create Localized Settings Trees.

Usage:

Option( <option path>, [Store function name], [Apply function name], [LanguageIndependentPath]);

Examples:

Option ( "Microsoft Word\\Toolbar");

Option( "MicrosoftWord\\Toolbar\\Tooltips", "StoreTooltips", "ApplyTooltips", "msword\\toolbar\\tooltips");

If the item is selected by the user, then the Store and Apply functions are called by the interpreter. If an option is selected by the user, the option's parent functions are also invoked.

Print

Prints a message to the Activity Log and the Debug Log. The parentheses are optional. This command takes one parameter that is a string value. For the optional second parameter information, see Print Levels. If Print Levels is not specified, the parameter defaults to GENERAL.

First parameter:

string (string value)

Usage:

print  (<string>);

Examples:

Print ("Warning: file win.ini will be overwritten");

PrintException

Prints a string to the Exception Log. The Exception Log is used for viewing items CA DMM was unable to move or post migration instructions. For example, the Netscape Communicator script prints out detailed instructions describing upgrade procedures to the Exception Log. The MS Word script prints out settings that could not be upgraded. The PrintException command can only be used within the ApplyFunction. See Print Levels for the optional second parameter. If Print Levels is not specified, the parameter defaults to GENERAL.

First parameter:

string (string value)

Usage:

PrintException (<string>);

Examples:

PrintException ("Please remove the file c:\\windows\\netscapecommunication.ttt");

RetrieveValue

Retrieves a registry key value either from the source computer or from the destination computer. It can take three parameters: the key path, the value name, and a Boolean. The first two parameters are required and are string values. The third parameter is optional. If the third parameter is True, CA DMM looks on the source computer, otherwise it looks on the destination computer. The default is False. The command returns False if the value could not be retrieved.

Note: The third Boolean parameter can only be used during General and Apply functions. The third Boolean parameter will cause a syntax error or runtime error if used otherwise.

First parameter:

The Key Path (string value)

Second parameter:

The Value Name (string value)

Third parameter:

The machine (Boolean value)

Usage:

Value = RetrieveValue(<Key Path>, <Value Name>, [Boolean]);

Example:

RetrieveValue( "HKCU\\Software\\Microsoft\\Office\\8.0\\Common\\Toolbar", "Tooltips", SOURCE);

RetrieveValue( "HKCU\\Software\\Microsoft\\Office\\8.0\\Common\", "Tooltips", DESTINATION);

RestartRequired

Directs CA DMM to display the restart required dialog at the end of a migration. Use this function for scripts that require a restart to complete a successful migration. The only required parameter is a Boolean indicating whether the script requires a restart.

First parameter:

(Boolean value)

Usage:

RestartRequired(<Boolean>);

Example:

RestartRequired(true);