General Commands

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

General Commands

The general commands that are used in the CA DMM scripts are as follows:

Break

Jumps the flow of control to the end of the immediate loop and executes the first instruction following the loop. Break is different from a return, which leaves all loops and the function scope. Break is only meaningful inside 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 that is associated with the script.

Note: Only one application can be associated with a script. The Detection function invokes the application from the source computer. The application can be invoked from anywhere on the destination computer to resolve the application path.

Ensure that the following points are verified:

The interpreter resolves the APPLICATIONPATH keyword only after the application is invoked.
The script calls 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, ensure that the path ends with the key name and a slash. The script must verify the return value of Detect in the Detection function to either continue or 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 command is unable to find the file or the dll to call, the function returns false.

First parameter:

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

    int FunctionName();

    int FunctionName( const char * );

Second parameter:

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

Third parameter:

A Boolean value that indicates whether the script waits 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. If the wrong CommandID is passed, the command returns the error during migration. Use this command at both store and apply sides of the migration.

Note: You cannot use this command with the previous versions of the product. If you use the command in the older versions of CA DMM, the command gives syntax errors.

First Parameter:

CommandID (for example, GET_CUR_SEL) to get the node name that is selected currently (application or system settings) for migration.

Usage:

GetEngineData(<CommandID>);

Example:

var strNewPath = GetEngineData(GET_CUR_SEL)

GetMappedPath

Returns the new File path that is mapped to the new system. The command also can 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 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. If used otherwise, the parameter causes a syntax error or runtime error.

First parameter:

The system (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 system, otherwise it gets the OS of the destination system. 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 system(Boolean value)

Usage:

Value = IsLikeNT([Boolean]);

Example:

IsLikeNT(SOURCE);

MapPath

Maps one path to another during a script. This path-mapping applies to all Apply operations following the MapPath keyword in the current script. This keyword replaces 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, the interpreter invokes the associated functions. 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 options tree view.

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 user selects the item, then the interpreter calls the Store and Apply functions. If the user selects an option, the parent functions of the option 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 the detailed instructions describing upgrade procedures to the Exception Log. The Microsoft Word script prints the settings that could not be upgraded. The PrintException command can only be used within the ApplyFunction command. 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, the CA DMM looks on the source computer, otherwise it looks on the destination computer. The default value is False. The command returns False if the value could not be retrieved.

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

First parameter:

The Key Path (string value)

Second parameter:

The Value Name (string value)

Third parameter:

The system (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);