DDDriverFileCommands

Last Updated:11/29/2016 06:58:13

Driver Commands for File Manipulations

It is important to note that file command usage cannot readily be mixed and matched across different SAFS engines. For example, Files opened by Robot(RC) are only known to RC. So attempting to use SDC or RJ commands on files opened by RC are not likely to work in this scenario. This will be fixed in future releases.

[How To Read This Reference]
CloseFile
RC RJ TID SDC SE2
Close the open file with the file number provided
CopyFile
RC RJ TID SDC SE2
Copy the specified filename to the target filename.
CopyMatchingFiles
RJ TID SDC SE2
Copy multiple files/sub-directories, based on matching the provided pattern, from one directory to another.
CreateDirectory
RC RJ TID SDC SE2
Create the directory for the provided directory pathname
CreateFile
RC RJ TID SDC SE2
Open a new file with the filename, mode and access provided.TID Note: Three ways to create a file: Mode=Input, Access=ReadMode=Output, Access=WriteMode=Append, Access=Write
DeleteDirectory
RC RJ TID SDC SE2
Delete the directory for the provided directory pathname
DeleteDirectoryContents
RJ TID SDC SE2
Delete the contents (files and sub-directories) of a provided directory and optionally, the directory itself.
DeleteFile
RC RJ TID SDC SE2
Delete the file for the file name provided
FilterImage
RJ TID SDC SE2
Filter out specific parts of an image.
FilterTextFile
RC RJ TID SDC SE2
Filter a text file based on the given parameters.
FindSqaFile
RC TID SDC
Find the file for the SQA relative path and file name provided. If a full file path is provided the file will be located using the full file path and name.
GetFileDateTime
RC RJ TID SDC SE2
Determine the date and time the file created/last changed/last accessed for file name provided and assign it to a DDV variable.
GetFileProtections
RJ TID SDC SE2
Save the file attributes for the file name to the variable provided.
GetFiles
RC RJ TID SDC SE2
Search the directory provided for files according to possible attribute and write the list of filenames found into the output file.
GetFileSize
RC RJ TID SDC SE2
Determine the file size for file name provided and assign it to a DDV variable.
GetINIFileValue
RJ TID SDC SE2
Get value from INI file.
GetStringCountInFile
RJ TID SDC SE2
Count the number of occurrences of a target string in a File.
GetSubstringsInFile
RJ TID SDC SE2
Extract dynamic substrings from a file using regular expressions.
GetTextFromImage
RJ SDC TID SE2
Incorporate OCR technology to detect the text in an image file and save the text to a variable.
IfExistDir
RJ TID SDC SE2
If the specified directory exists, then execute the following driver command.
IfExistFile
RJ TID SDC SE2
If the specified file exists, then execute the following driver command.
IsEndOfFile
RJ TID SDC SE2
If the specified file is at the end of file, a 'variable' gets true assigned, otherwise it gets false
OpenFile
RC RJ TID SDC SE2
Open an existing file with the filename, mode and access provided.TID Note: Multiple ways to open a file: Mode=Input, Access=ReadMode=Output, Access=WriteMode=Append, Access=WriteMode=AppendRaw, Access=Write
OpenUTF8File
RJ TID SDC SE2
Open an existing UTF-8 file with the filename, mode and access provided.TID Note: Multiple ways to open a file: Mode=Input, Access=ReadMode=Output, Access=WriteMode=Append, Access=WriteMode=AppendRaw, Access=Write
PrintToFile
RC RJ TID SDC SE2
Write output to a sequential file already opened for writing.
ReadFileChars
RC RJ TID SDC SE2
Read the number of characters from the file defined by file number and assign a string containing the characters read to a DDV variable.
ReadFileLine
RC RJ TID SDC SE2
Read a line from the file defined by file number and assign a string containing the line read to a DDV variable.
ReadFileString
RC
Read a comma-separated value from a file and store it in a DDVariable.
RenameFile
RC RJ TID SDC SE2
Rename the file from the old file name to the new filename
SaveTextFromImage
RJ SDC TID SE2
Incorporate OCR technology to detect the text in an image file and save the text to a text file.
SetFileProtections
RC RJ TID SDC SE2
Change the file attribute for the file name provided to the value of the new file protection provided.
WriteFileChars
RJ TID SDC SE2
Write the specified number of characters to a file already opened for writing.

DDDriverFileCommands::CloseFile
RC RJ TID SDC SE2

Close the open file with the file number provided


Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number for the file to be closed.


Examples:
  • C, CloseFile, 8
    Close the open file with the file number 8


  • C, CloseFile, ^file_number
    Close the open file with the file number contained in DDE variable file_number


[How To Read This Reference]

DDDriverFileCommands::CopyFile
RC RJ TID SDC SE2

Copy the specified filename to the target filename.

For the Java-based engines--RJ, TID, and SDC:

If the filenames provided are not full absolute paths then we will attempt to deduce a full Project-relative or Datapool\Test-relative path from the relative path provided. If the relative path already contains path separators (ex: "\subpath\filename.ext") then we attempt to deduce a fullpath relative to the SAFS Project. If no path separators exist (ex: "filename.txt") then we attempt to deduce a fullpath relative to the project's Datapool\Test directory. We do not actually attempt to see if the directories or files exists before executing the command.



Fields: [ ]=Optional with Default Value
  1. FromFileName
    The file path and file name for the file to be copied.


  2. ToFileName
    The file path and file name to copy the file to.


Examples:
  • C, CopyFile, "C:/Test/Test1.txt" , "C:/Test/Test2.txt"
    Copy the file C:/Test/Test1.txt to C:/Test/Test2.txt

    Fullpath filename specs should be supported by all engines.

  • C, CopyFile, "C:/Test/Test1.txt" , "Test2.txt"
    Copy the file C:/Test/Test1.txt to C:/MyProject/Datapool/Test/Test2.txt

    Supported only by the Java-based engines (RJ, SDC, TID) at this time.

  • C, CopyFile, "Test1.txt" , "Test2.txt"
    Copy the file C:/MyProject/Datapool/Test/Test1.txt to C:/MyProject/Datapool/Test/Test2.txt

    Supported only by the Java-based engines (RJ, SDC, TID) at this time.

  • C, CopyFile, "Test1.txt" , "/w32/Results/Test1.txt"
    Copy the file C:/MyProject/Datapool/Test/Test1.txt to C:/MyProject/w32/Results/Test1.txt

    Supported only by the Java-based engines (RJ, SDC, TID) at this time.

[How To Read This Reference]

DDDriverFileCommands::CopyMatchingFiles
RJ TID SDC SE2

Copy multiple files/sub-directories, based on matching the provided pattern, from one directory to another.

Note: This is a very powerful DriverCommand, please use with caution!

Fields: [ ]=Optional with Default Value
  1. FromDirectoryName
    The directory name where the files are located.

    The directory name where the files are located. The directory can be a fully-qualified path or a path that is relative to the SAFS Automation Project Directory.

  2. ToDirectoryName
    The directory name where the files are copied.

    The directory name where the files are copied. The directory can be a fully-qualified path or a path that is relative to the SAFS Automation Project Directory. This directory must already exist prior to execution.

  3. Pattern
    The pattern used to distinguish the files/sub-directories to be copied.


  4. [ FilterMode = ]
    The filter mode used for matching the files/sub-directories to be copied. Default is WILDCARD.

    Supported filter modes include:
    FilterMode Comments
    WILDCARD Default. Includes support for * and ? wildcard characters
    REGEXP Includes support for Regular Expression pattern matching


Examples:
  • C, CopyMatchingFiles, "C:\Test", "C\Test2", "file?.*"
    Copy all of the files and sub-directories that match the file?.* pattern. By default, the WILDCARD FilterMode is used. As a result, all files/subdirectories in C:\Test that begin with "file" followed by exactly one character before a "." followed by zero or more characters are copied to C:\Test2.


  • C, CopyMatchingFiles, "Datapool\Test\MyTestOutput", "C:\MyTestOutput", "file.*\.java", REGEXP
    Copy all of the files and sub-directories that match the file.*\.java pattern. Since the REGEXP FilterMode is used, all files/subdirectories in <SAFS_Automation_Project_Dir>\Datapool\Test\MyTestOutput that begin with "file" followed by zero or more characters before a "." followed by "java" are copied to C:\MyTestOutput.


[How To Read This Reference]

DDDriverFileCommands::CreateDirectory
RC RJ TID SDC SE2

Create the directory for the provided directory pathname


Fields: [ ]=Optional with Default Value
  1. DirectoryName
    The full directory path name for the directory to be created.


Examples:
  • C, CreateDirectory, "C:/Test/SubTest"
    Create the sub folder SubTest in the C:Test directory


[How To Read This Reference]

DDDriverFileCommands::CreateFile
RC RJ TID SDC SE2

Open a new file with the filename, mode and access provided.
TID Note: Three ways to create a file:
  1. Mode=Input, Access=Read
  2. Mode=Output, Access=Write
  3. Mode=Append, Access=Write


Fields: [ ]=Optional with Default Value
  1. FileName
    The full path file name of the file to be opened.


  2. Mode
    Mode to be used to create and open the file, Input, Output or Append. Random and Binary not supported


  3. Access
    Access to be used to create and open the file. Read, Write or Read Write.


  4. FileNumberVariable
    DDE Variable name of the variable to store the file number.


  5. [ FileNumber = ]
    Optional File number to be used to open the file Otherwise next available file number is used


Examples:
  • C, CreateFile, "C:\Test\FileTest.txt", "Output", "Write","^test_filenum"
    CreateFile a new file FileTest.txt for Output and writing and store the file number in DDE variable ^test_filenum


  • C, CreateFile, "C:\Test\FileTest.txt", "Output", "Write","^test_filenum", 8
    CreateFile a new file FileTest.txt for Output and Writing with the file number 8 and store the file number 8 in DDE variable ^test_filenum


[How To Read This Reference]

DDDriverFileCommands::DeleteDirectory
RC RJ TID SDC SE2

Delete the directory for the provided directory pathname


Fields: [ ]=Optional with Default Value
  1. DirectoryName
    The full directory path name for the directory to be deleted.


Examples:
  • C, DeleteDirectory, "C:/Test/SubTest"
    Delete the sub folder SubTest in the C:Test directory


[How To Read This Reference]

DDDriverFileCommands::DeleteDirectoryContents
RJ TID SDC SE2

Delete the contents (files and sub-directories) of a provided directory and optionally, the directory itself.

Note: This is a very powerful DriverCommand, please use with caution!

Fields: [ ]=Optional with Default Value
  1. DirectoryName
    The directory name in which the contents will be deleted.

    The directory name in which the contents will be deleted. The directory can be a fully-qualified path or a path that is relative to the SAFS Automation Project Directory.

  2. [ DeleteDir = ]
    Indicate whether you want to also delete the directory with true or false. Default is false.


Examples:
  • C, DeleteDirectoryContents, "Datapool\Test"
    Delete all of the files and sub-directories under directory <SAFS_Automation_Project_Dir>\Datapool\Test. By default, do not also delete <SAFS_Automation_Project_Dir>\Datapool\Test.


  • C, DeleteDirectoryContents, "C:\Test\SubTest", true
    Delete all of the files and sub-directories under directory C:\Test\SubTest. Also delete C:\Test\SubTest.


[How To Read This Reference]

DDDriverFileCommands::DeleteFile
RC RJ TID SDC SE2

Delete the file for the file name provided


Fields: [ ]=Optional with Default Value
  1. FileName
    The file name for the file to be deleted. Normally, the full file path is specified. If a relative path is specified, it is relative to the project directory.


  2. [ NoVerify = ]
    String Equal to "NOVERIFY" if file is not verified prior to deleting.


Examples:
  • C, DeleteFile, "Test1.txt"
    Delete the file /Datapool/Test/Test1.txt


  • C, DeleteFile, "C:/test/Test1.tst"
    Delete the file Test1.txt in directory C:/test


  • C, DeleteFile, "C:/test/Test1.tst", "NoVerify"
    Delete the file Test1.txt in directory C:/test no file existence verification


[How To Read This Reference]

DDDriverFileCommands::FilterImage
RJ TID SDC SE2

Filter out specific parts of an image.

Filter out specific parts of an image and save to a new or existing image file. The filtered portions of the image are blacked out so as to remove dynamic visible content from the image. The available formats for the input and output files are BITMAP (*.bmp) and JPEG (*.jpg).

Specific Notes:
This command requires that Java Advanced Imaging (JAI) be installed on the test machine.



Fields: [ ]=Optional with Default Value
  1. InputFilename
    The input image file (FULL PATH)


  2. OutputFilename
    The output image file after filtering (FULL PATH)

    The output image file after filtering (FULL PATH). The output image may overwrite the input image.

  3. FilterMode
    Mode by which the image is filtered

    Mode by which the image is filtered. Currently, the only supported FilterMode is COORD.

  4. Coords
    Required parameter for the COORD FilterMode that defines the rectangle(s) of the input image that are to be filtered out.

    Required parameter for the COORD FilterMode that defines the rectangles of the input image that are to be filtered out. Value of this app map reference must be in the format of a top-left and bottom-right pair, and can be either absolute coordinates or percentages ("x1,y1,x2,y2" or "x1%,y1%,x2%,y2%"). Coordinates are relative to the image, i.e. (0,0) and (0%,0%) are the minimum, and (image width, image height) and (100%,100%) are the maximum. Values exceeding the minimum/ maximum are forced to the nearest limiting value. Absolute and percent values can be mixed, so "0,0,50%,50%" is valid.

    Note: Java-based engines like RFT should support using either a comma (,) or a semi-colon (;) as the Coords item separator. Also, there should be a space char separating each set of rectangle coordinates.



Examples:
  • C, FilterImage, "C:\in.jpg", "C:\out.jpg", COORD, 30;40;50;60 50%;30%;75%;50%
    Filter input image file "C:\in.jpg" by blacking out 2 rectangles: 1) 30,40 to 50,60 and; 2) from 50%,30% to 75%,50%. Write output image to C:\out.jpg.


  • C_ FilterImage_ "C:\in.jpg"_ "C:\out.jpg"_ COORD_ 30,40,50,60
    Filter input image file "C:\in.jpg" by blacking out 1 rectangles at 30,40 to 50,60. Write to output image file "C:\out.jpg".


[How To Read This Reference]

DDDriverFileCommands::FilterTextFile
RC RJ TID SDC SE2

Filter a text file based on the given parameters.

Filter a text file based on the given parameters.

This command can be used to process a text file based on the provided parameters, such as replacing text in a file that matches a specific pattern. This command is experimental. command name/parameters are subject to change without notice.



Fields: [ ]=Optional with Default Value
  1. File
    The file to be filtered.

    The file to be filtered. This can be a full path, a relative path, or a file name. For relative path, it is appended to the project's path to build the full path of the file. For file name, the file is saved under the project's Datapool\Test directory. In any case the parent folder of the file must exist.

  2. FilterMode
    The filter mode.

    The filter mode.
    "REGEXP" (Regular Expressions) is currently the only supported FILTERMODE that actually filters anything.

  3. [ FilterOptions = ]
    Additional filter options.

    Additional filter options. Depending on the filter mode, some filter options are required.
    FILTERMODEFIELDSCOMMENTS
    Default(empty) (None) Default filtering. File is unchanged.
    "RegExp" 5 - PATTERN (Required) REGEXP pattern to match for filtering. All occurrences of text in a file that match regular expression PATTERN will be removed and replaced with the REPLACE string (if any).
    6 - REPLACE (Optional) Default value for REPLACE is "" (empty string). This tells REGEXP to remove matching PATTERN text from the file. Specifying a REPLACE string will remove matching PATTERN text from the file and insert the REPLACE string in its place.
    7 - CASE (Optional) CASE specifies the case-sensitivity used when searching for matching text in the file. Use "CaseInsensitive" to ignore case when searching.
    If not specified the default implementation is a CaseSensitive compare.


  4. [ Encoding = ]
    The encoding to use to read and write file.

    If user doesn't provide this parameter, program will detect the encoding automatically. If no encoding is provided and detected, program will use system default encoding.
    If user provide this paramter, FilterOptions must be present (can be blank).

Examples:
  • C, FilterTextFile, C:\Temp\myfile.txt
    Performs the default filtering on C:\Temp\myfile.txt (does nothing).


  • C, FilterTextFile, C:\Temp\myfile.txt, RegExp, "19\d\d BC", "Last Centry"
    Performs a case-sensitive regular expression filtering on C:\Temp\myfile.txt.

    Performs a case-sensitive regular expression filtering on C:\Temp\myfile.txt. All occurrences of year "19xx BC" (case-sensitive) are replaced with "Last Centry".

  • C, FilterTextFile, myfile.txt, RegExp, "19\d\d BC", "Last Centry", CaseInsensitive
    Performs a case-insensitive regular expression filtering on Datapool\Test\myfile.txt.

    Performs a case-insensitive regular expression filtering on Datapool\Test\myfile.txt. All occurrences of year "19xx BC" (case-insensitive) are replaced with "Last Centry".

  • C, FilterTextFile, Datapool\myfile.txt, RegExp, "19\d\d BC"
    Performs a case-sensitive regular expression filtering on Datapool\myfile.txt.

    Performs a case-sensitive regular expression filtering on Datapool\myfile.txt. All occurrences of year "19xx BC" (case-sensitive) are removed.

  • C, FilterTextFile, Datapool\myfile.txt, RegExp, "19\d\d BC", , , "UTF-8"
    Performs a case-sensitive regular expression filtering on Datapool\myfile.txt. File will be read and wrote by encoding "UTF-8".

    Performs a case-sensitive regular expression filtering on Datapool\myfile.txt. All occurrences of year "19xx BC" (case-sensitive) are removed. File will be read and wrote by encoding "UTF-8".

[How To Read This Reference]

DDDriverFileCommands::FindSqaFile
RC TID SDC

Find the file for the SQA relative path and file name provided. If a full file path is provided the file will be located using the full file path and name.


Fields: [ ]=Optional with Default Value
  1. FileName
    The file path and file name of the file to be found.


  2. FilePathVariable
    Name of the DDV variable to be used to store the full file path of the found file. If file not found blank string is assigned to variable


Examples:
  • C, FindSqaFile, "Test1.txt" , "^filepath"
    Test1.txt file is looked for at Project/Datapool/Test1.txt and if found the full file path is assigned to the DDV variable filepath


  • C, FindSqaFile, "C:Test1.txt" , "^filepath"
    Test1.txt file is looked for at C:Test1.txt and if found the full file path is assigned the DDV variable filepath


[How To Read This Reference]

DDDriverFileCommands::GetFileDateTime
RC RJ TID SDC SE2

Determine the date and time the file created/last changed/last accessed for file name provided and assign it to a DDV variable.

Determine the date and time the file created/last changed/last accessed for file name provided and assign it to a DDV variable. This date is in the format MM-DD-YYYY HH:MM:SS, it is in AM-PM 12-hours format (1-12) be default; If you set the third parameter 'GetMilitaryTime' to True, the time will be 24-hours military format (0-23). Use military time is recommanded, as am-pm time has confusion without AM or PM (example: 18:00 and 06:00 will be both 06:00) You can get different date and time by providing a different value to the fourth optional parameter DateTimeType.
NOTE:
For Operating System other than Windows, only "lastModified" time is supported.

Fields: [ ]=Optional with Default Value
  1. FileName
    The file path and file name of the file to get the file date and time.


  2. FileDateVariable
    Name of the DDV variable to be used to store the file date and time


  3. [ GetMilitaryTime = ]
    If true, the converted time is in 24-hours military time format

    If this is true, the converted time will be in 24-hours military time format (0-23). If this parameter is omitted, it is false be default, the converted time will be in AM-PM 12-hours format (1-12). If not provided, by default it is false.

  4. [ DateTimeType = ]
    You can get different date and time by providing a different value.

    You have 3 options:
    1. Created: get the created date and time for the file
    2. LastModified: get the last modified date and time for the file
    3. LastAccessed: get the last accessed date and time for the file
    If not provided, by default it is "LastModified".

Examples:
  • C, GetFileDateTime, "Test1.txt" , "^filedate"
    Date and time of last change to Project/Datapool/Test1.txt is determined and assigned to the DDV variable filedate. The time format is '12-hours am-pm'.


  • C, GetFileDateTime, "C:\Test1.txt" , "^filedate"
    Date and time of last change to C:\Test1.txt is obtained and assigned to the DDV variable filedate. The time format is '12-hours am-pm'.


  • C, GetFileDateTime, "C:\Test1.txt" , "^filedate", true, "Created"
    Date and time of created to C:\Test1.txt is obtained and assigned to the DDV variable filedate. The time format is '24-hours military time' (0-23).


  • C, GetFileDateTime, "C:\Test1.txt" , "^filedate", , "LastAccessed"
    Date and time of last accessed to C:Test1.txt is obtained and assigned to the DDV variable filedate. The time format is '12-hours am-pm'.


[How To Read This Reference]

DDDriverFileCommands::GetFileProtections
RJ TID SDC SE2

Save the file attributes for the file name to the variable provided.

Save the file attributes for the file name to the variable provided. The variable will be an integer containing the attributes for the file, it may be any combination of them. Here is a description of attributes:

0 - Normal file

1 - Read Only file

2 - Hidden file

4 - System file (Windows OS Only)

16 - Directory

32 - Archive file (Windows OS: attrib with 'A'; Other OS: file suffix is .jar, .tar, .rar, .gz etc.)



Fields: [ ]=Optional with Default Value
  1. FileName
    The file path and file name of the file to get the file attribute.


  2. VarName
    variable name to place the attributes in


Examples:
  • C, GetFileProtections, "C:\afile.txt" , varName
    File attributes of the file C:\afile.txt are placed in variable 'varName'. It could be something like 33, which is a read-only file with the archive bit on.


[How To Read This Reference]

DDDriverFileCommands::GetFiles
RC RJ TID SDC SE2

Search the directory provided for files according to possible attribute and write the list of filenames found into the output file.


Fields: [ ]=Optional with Default Value
  1. Directory
    The full name of the directory to be searched for files.


  2. FileName
    Full file path and name of the file to store list of files found in the directory


  3. [ FileAttributes = ]
    Optional File Attributes parameter specifying file attributes to select with Dir directory search command. Default if unspecified is normal files. It may be any combination of them.

    Search directory using following file attributes. Default value is 0 - normal file.

    0 - Normal file, returns only files without other attributes set

    1 - Read Only file

    2 - Hidden file

    4 - System file (Window OS Only)

    8 - Volume Label (Exclusive, if set, no other attribute counts.)

    16 - Directory

    32 - Archive file (Windows OS: attrib with 'A'; Other OS: file suffix is .jar, .tar, .rar, .gz etc.)

    The values in the table can be added together to select multiple attributes.

    For example, to list hidden and system files in addition to normal files set FileAttributes to 6 (6=2+4).

    If FileAttributes is set to 8 (Volume Label), then returns the volume label of the drive specified in the pathname$, or of the current drive if drive is not explicitly specified.

    If volume label attribute is set, all other attributes are ignored.



Examples:
  • C, GetFiles, "C:/Test", "D:/Test/filelist.txt", "16"

    Directory C:/Test is searched for files with normal and directory attributes set and list of files found is written to file D:/Test/filelist.txt



  • C, GetFiles, "C:/Test", "D:/Test/filelist.txt"
    Directory C:/Test is searched and list of files found is written to file D:/Test/filelist.txt


  • C, GetFiles,"^directory", "^file_list"
    Directory defined in ^directory DDV variable searched and list of files found is written to file identified by ^file_List DDV variable


[How To Read This Reference]

DDDriverFileCommands::GetFileSize
RC RJ TID SDC SE2

Determine the file size for file name provided and assign it to a DDV variable.


Fields: [ ]=Optional with Default Value
  1. FileName
    The file path and file name of the file to get file size.


  2. FileSizeVariable
    Name of the DDV variable to be used to store the file size of the file.


Examples:
  • C, GetFileSize, "Test1.txt" , "^filesize"
    Size of file Project/Datapool/Test1.txt is determined and assigned to the DDV variable filesize


  • C, GetFileSize, "C:Test1.txt" , "^filepath"
    Size of Test1.txt file located at C:Test1.txt is obtained and assigned to the DDV variable filepath


[How To Read This Reference]

DDDriverFileCommands::GetINIFileValue
RJ TID SDC SE2

Get value from INI file.


Fields: [ ]=Optional with Default Value
  1. FileName
    The name of the file.

    Note: For Java-based tools like RJ, TID, and SDC this can be a relative path filename. If the value is a simple filename with no path information then the file will be sought in the Project\Datapool\Runtime directory. If there is some relative path information provided then the file will be sought relative to the Project directory. then the file will be sought

  2. Section
    The Section of the file to look in.


  3. Item
    The item to look for.


  4. Variable
    Name of the DDV variable to be used to store the file date and time


Examples:
  • C, GetINIFileValue, "test.INI", Section, Item, Variable
    Look in Project\Datapool\Runtime\test.INI for Item under "[Section]" and store the value in Variable


  • C, GetINIFileValue, "C:\test.INI", Section, Item, Variable
    Look in C:\test.INI for Item under [Section] and store the value in Variable


[How To Read This Reference]

DDDriverFileCommands::GetStringCountInFile
RJ TID SDC SE2

Count the number of occurrences of a target string in a File.

This command opens and reads a file line by line, then sets a specified DDVariable to the number of times the target string is found in the file. String comparisons are case-sensitive by default. The file is assumed to be in the system default encoding unless specified otherwise.

Fields: [ ]=Optional with Default Value
  1. File
    The File to be searched.

    This can be a full filepath, a relative path, or a simple filename. A relative path is appended to the Project's path to deduce the full filename. For a simple filename, the filename is appended to the Project's Datapool\Test directory path to deduce the full filename. An error will be logged if the file does not exist, or cannot be read.

  2. String
    The string to match and count in the file.


  3. [ VarName = GetStringCountInFile ]
    The name of the variable to receive the count.

    Optional. This command should automatically clear the variable value to "0" before counting. If no variable name is provided, then a default variable name of 'GetStringCountInFile' will be used.

  4. [ CaseSensitive = ]
    Set to 'CaseInsensitive' so comparisons are NOT case-sensitive.

    Optional. Comparisons are case-sensitive by default.

  5. [ Encoding = ]
    Charset encoding string like "UTF-8", etc...

    Optional. If not specified the default system encoding is assumed.

Examples:
  • C, GetStringCountInFile, "\tidtest.ini", "SAFS_TEST"
    Count the number of times "SAFS_TEST" is found and store in variable "GetStringCountInFile".

    Open project-relative file at "[project]\tidtest.ini", count the number of times "SAFS_TEST" appears in that file, and store the result in the default variable "GetStringCountInFile". The text comparisons are case-sensitive. The text in the file is assumed to be in the system default encoding when it is read.

  • C, GetStringCountInFile, "somefile.txt", "sample text", MyCounter
    Count the number of times "sample text" is found and store in variable "MyCounter".

    Open project-relative file at "[project]\Datapool\Test\somefile.txt", count the number of times "sample text" appears in that file, and store the result in the default variable "MyCounter". The text comparisons are case-sensitive.

  • C, GetStringCountInFile, "somefile.txt", "SamPLe TexT", MyCounter, "CaseInsensitive"
    Count the number of times "SamPLe TexT" is found and store in variable "MyCounter".

    Open project-relative file at "[project]\Datapool\Test\somefile.txt", count the number of times "SamPLe TexT" appears in that file, and store the result in the default variable "MyCounter". The text comparisons are NOT case-sensitive.

  • C, GetStringCountInFile, "somefile.txt", "SamPLe TexT", MyCounter, "CaseInsensitive", "UTF-8"
    Count the number of times "SamPLe TexT" is found and store in variable "MyCounter".

    Open project-relative file at "[project]\Datapool\Test\somefile.txt", count the number of times "SamPLe TexT" appears in that file, and store the result in the default variable "MyCounter". The text comparisons are NOT case-sensitive. The text in the file is assumed to be UTF-8 encoded when it is read.

[How To Read This Reference]

DDDriverFileCommands::GetSubstringsInFile
RJ TID SDC SE2

Extract dynamic substrings from a file using regular expressions.

This command opens the file, reads it line by line, and sets DDVariables (based on rootname) for each occurrence of string identified by the substring formed between regexstart and regexstop (1 match per line, currently). regexstart and regexstop must both be valid, non-empty strings or no matching substrings will be found.

Fully qualified filename is opened and read line by line. Each line is parsed, searching for a match to the substring formed between regexstart and regexstop.

When a match is found, the string between regexstart and regexstop is saved in a newly created DDVariable based on rootname and the number of occurrences. There will be one DDVariable for each match found and a unique "Count" variable specifying how many matches were found.

The rootname is used as a base to build the DDVariable names which contain the located substring(s) and Count. For example, if rootname is "Chart" and two substring matches are found, then 2 DDVariables are created to store those substrings and another is created to store the count of matches:

  1. DDVariable Chart1 contains the first substring, and
  2. DDVariable Chart2 contains the second substring.
  3. DDVariable ChartCount contains the number of matches found.


Fields: [ ]=Optional with Default Value
  1. file
    Fully-qualified filename


  2. regexstart
    The starting regular expression. Should not be empty.


  3. regexstop
    The stopping regular expression. Should not be empty.


  4. rootname
    The root name of the returned variable(s).

    The rootname is used as a base to build the DDVariable names which contain the located substring(s). For example, if rootname is "Chart" and two substring matches are found, then 2 DDVariables are created to store those substrings and another is created to store the count of matches:
    1. DDVariable Chart1 contains the first substring, and
    2. DDVariable Chart2 contains the second substring.
    3. DDVariable ChartCount contains the number of matches found.


Examples:
  • C GetSubstringsInFile ^file=^fullfilename ^regexstart="img id=""idChart" ^regexstop="""" ^rootname="Chart"
    Assuming 2 strings are found in file, this command will create:
    DDVariable Chart1, which contains the first substring, and
    DDVariable Chart2, which contains the second substring.
    DDVariable ChartCount, which contains the count of matches found.


[How To Read This Reference]

DDDriverFileCommands::GetTextFromImage
RJ SDC TID SE2

Incorporate OCR technology to detect the text in an image file and save the text to a variable.

Two open-source OCRs are integrated into SAFS. One is TesseractOCR (TOCR) at http://code.google.com/p/tesseract-ocr; the other GOCR at http://jocr.sourceforge.net.

TOCR 2.0.4 and GOCR 0.48 are the latest release. They are available in SAFS and only support English. Both two OCR owners claim to support more languages in next release. Chinese, Japanese, and Korean are going to be supported in TOCR's next release 3.00.



Fields: [ ]=Optional with Default Value
  1. ImageFile
    The name of the image file used to detect text in it.

    The name of the image file used to detect text in it. The name of the text file used to store detected text. By default, the files will be stored in the active "Test" directory. If you specify a relative path, the path will be relative to the project directory. The directory for a full or relative path must already exist.

    The extension of the image file can be .bmp, .jpg, .gif, .tif, .png or .pnm.



  2. VariableName
    The name of the variable to receive detected text.

    The name of the variable to receive detected text. Note, if you supply the name of the variable and include the leading caret (^) symbol then the variable must be enclosed in quotes. Otherwise, that variable will be used like any other variable and the substituted value of that variable will be interpreted as the name of the variable you wish to use.

  3. [ OCRId = ]
    OCRId indicating the OCR used to recognize text.

    Two OCR engines are supported. "TOCR" will be taken as default if the parameter is blank. "TOCR" stands for Tesseract OCR; "GOCR" stands for GOCR.

    Note: Seems TOCR performs a bit better than GOCR (personal experience).



  4. [ LangId = ]
    Optional LangId representing the language in use for selected OCR to recognize text.

    For both TOCR and GOCR, only English is supported so far. Language Id takes standard language code, which can be gotten by calling Locale.ENGLISH.getLanguage(). 

    				LangId      Language
				"en"   ---  English
				"cn"   ---  Chinese

    If LangId is not specified with blank or empty string, the language of System locale will be used as default.



  5. [ ScaleRatio = ]
    Optional ScaleRatio indicating the scale ratio for resizing the original image.

    To fit in font size and DPI required by OCR, SAFS needs to resize images before sending them to OCR engines. For screen-captured images with 96DPI, TOCR takes 1.9 as default; GOCR takes 1.5 as default. You may try different ScaleRatio to find an appropriate value if default setting is unable to meet your requirement.

Examples:
  • C, GetTextFromImage, image.gif, Var1, TOCR, en, 2.0
    Detect the text in [project]\Datapool\Bench\image.gif using TOCR with English and ScaleRatio 2.0, then save the text to variable Var1.



[How To Read This Reference]

DDDriverFileCommands::IfExistDir
RJ TID SDC SE2

If the specified directory exists, then execute the following driver command.


Fields: [ ]=Optional with Default Value
  1. DirectoryName
    The full path name of directory to test for


  2. ThenDriverCommand
    Actually, the rest of the parameters include this, which is the driver command to execute if the directory exists, followed by the remaining driver parameters for that command


Examples:
  • C, IfExistDir, "C:\temp\9\7", DeleteDirectory, "C:\temp\9\7"
    only delete the directory if it exists.


[How To Read This Reference]

DDDriverFileCommands::IfExistFile
RJ TID SDC SE2

If the specified file exists, then execute the following driver command.


Fields: [ ]=Optional with Default Value
  1. FileName
    The full path name of file to test for


  2. ThenDriverCommand
    Actually, the rest of the parameters include this, which is the driver command to execute if the file exists, followed by the remaining driver parameters for that command


Examples:
  • C, IfExistFile, "C:\temp\9\7\6.txt", DeleteFile, "C:\temp\9\7\6.txt"
    only delete the file if it exists.


[How To Read This Reference]

DDDriverFileCommands::IsEndOfFile
RJ TID SDC SE2

If the specified file is at the end of file, a 'variable' gets true assigned, otherwise it gets false


Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number for the file to be closed.


  2. Variable
    Variable to assign true or false


Examples:
  • C, IsEndOfFile, 8, variable
    if the file with file number 8 is at the end of file, 'variable' gets true assigned, otherwise it gets false


[How To Read This Reference]

DDDriverFileCommands::OpenFile
RC RJ TID SDC SE2

Open an existing file with the filename, mode and access provided.
TID Note: Multiple ways to open a file:
  1. Mode=Input, Access=Read
  2. Mode=Output, Access=Write
  3. Mode=Append, Access=Write
  4. Mode=AppendRaw, Access=Write


Fields: [ ]=Optional with Default Value
  1. FileName
    The full path file name of the file to be opened.


  2. Mode
    Mode to be used to open the file, Input, Output, Append, and AppendRaw.

    Text Files only. Random Access and Binary files are not supported.

    Append Mode generally rewrites existing file contents with a NEWLINE between textual lines--stripping out OS-specific newline characters and making the file the same regardless of the platform.

    AppendRaw Mode rewrites existing file contents without modification before appending any new data to the file.



  3. Access
    Access to be used to open the file. Read, Write or Read Write.


  4. FileNumberVariable
    DDE Variable name of the variable to store the file number.


  5. [ FileNumber = ]
    Optional File number to be used to open the file Otherwise next available file number is used


Examples:
  • C, OpenFile, "C:\Test\FileTest.txt", "Input", "Read","test_filenum"
    Open the existing file FileTest.txt for Input and reading and store the file number in DDE variable ^test_filenum


  • C, OpenFile, "C:\Test\FileTest.txt", "Output", "Write","test_filenum",8
    Open the file FileTest.txt for Output and Writing with the file number 8 and store the file number 8 in DDE variable ^test_filenum


[How To Read This Reference]

DDDriverFileCommands::OpenUTF8File
RJ TID SDC SE2

Open an existing UTF-8 file with the filename, mode and access provided.
TID Note: Multiple ways to open a file:
  1. Mode=Input, Access=Read
  2. Mode=Output, Access=Write
  3. Mode=Append, Access=Write
  4. Mode=AppendRaw, Access=Write


Fields: [ ]=Optional with Default Value
  1. FileName
    The full path file name of the UTF-8 file to be opened.


  2. Mode
    Mode to be used to open the file, Input, Output, Append, and AppendRaw.

    Text Files only. Random Access and Binary files are not supported.

    Append Mode generally rewrites existing file contents with a NEWLINE between textual lines--stripping out OS-specific newline characters and making the file the same regardless of the platform.

    AppendRaw Mode rewrites existing file contents without modification before appending any new data to the file.



  3. Access
    Access to be used to open the UTF-8 file. Read, Write or Read Write.


  4. FileNumberVariable
    DDE Variable name of the variable to store the file number.


  5. [ FileNumber = ]
    Optional File number to be used to open the UTF-8 file, otherwise, next available file number is used.


Examples:
  • C, OpenUTF8File, "C:\Test\FileTestUTF8.txt", "Input", "Read","test_filenum"
    Open the existing UTF-8 file FileTestUTF8.txt for Input and reading and store the file number in DDE variable ^test_filenum


  • C, OpenUTF8File, "C:\Test\FileTestUTF8.txt", "Output", "Write","test_filenum",8
    Open the UTF-8 file FileTestUTF8.txt for Output and Writing with the file number 8 and store the file number 8 in DDE variable ^test_filenum


[How To Read This Reference]

DDDriverFileCommands::PrintToFile
RC RJ TID SDC SE2

Write output to a sequential file already opened for writing.


Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number of the file to be written to.


  2. ExpressionListVariable
    DDV variable name of the variable that contains the "Expression List"; NOTE: for RobotJ it is the Expression List, if it begins with ^ then it is treated as a variable.


  3. [ PrintOutputPlacement = ]
    Print Output Placement Parameter determines where the next output to the same file should begin
    1. ; will place the output immediately following this print output
    2. , will start output at the next print zone on the same line
    3. Absence of this parameter (Default) will place the next output at the beginning of a new line following a carriage return line feed.


Examples:
  • C, PrinttoFile, 3, ^printexp="This text printed to file",";"
    The text "This text printed to file" is printed to the file opened with file number 3. The next thing printed to the file will start immediately following this output


  • C, PrinttoFile, ^filenumb, ^tempstring,","
    The contents of the DDV variable ^tempstring is printed to the file opened with filenumber contained in DDV Variable ^filenumb. The next thing printed to the file will start at the next print zone on the same line


  • C, PrinttoFile, ^filenumb, ^tempstring
    The contents of the DDV variable ^tempstring is printed to the file opened with filenumber contained in DDV Variable ^filenumb. The next thing printed to the file will start at the beginning of the next line following a carriage return line feed.


[How To Read This Reference]

DDDriverFileCommands::ReadFileChars
RC RJ TID SDC SE2

Read the number of characters from the file defined by file number and assign a string containing the characters read to a DDV variable.


Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number of the file to be read from.


  2. NumberOfChar
    Number of characters to be read from the file
    If the number is -1, then the whole content will be read .


  3. VariableName
    Name of the DDV variable in which to store the characters read from the file


Examples:
  • C, ReadFileChars, ^filenum , 5,"^charread"
    Five characters are read from the file identified by the value in filenum and they are assigned to the DDV variable charread


  • C, ReadFileChars, 8, 5,"^charread"
    Five characters are read from the file identified by filenumber 8 and they are assigned to the DDV variable charread


  • C, ReadFileChars, 8, -1,"^charread"
    All characters are read from the file identified by filenumber 8 and they are assigned to the DDV variable charread


[How To Read This Reference]

DDDriverFileCommands::ReadFileLine
RC RJ TID SDC SE2

Read a line from the file defined by file number and assign a string containing the line read to a DDV variable.


Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number of the file to be read from.


  2. VariableName
    Name of the DDV variable in which to store the line read from the file


Examples:
  • C, ReadFileLine, ^filenum , "^line"
    Line is read from the file identified by the value in filenum and the string containing the line read assigned to the DDV variable line


[How To Read This Reference]

DDDriverFileCommands::ReadFileString
RC

Read a comma-separated value from a file and store it in a DDVariable.

This command provides old Basic 'Input' style handling of file data. It expects that the file contains comma-separated values and only a single value is read from the specified file for each call.

Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number of the file to be read from.


  2. VariableName
    Name of the DDVariable in which to store the value read from the file.


Examples:
  • C, ReadFileString, ^filenum , "value"
    The next value is read from file ^filenum and assigned to the DDVariable ^value


[How To Read This Reference]

DDDriverFileCommands::RenameFile
RC RJ TID SDC SE2

Rename the file from the old file name to the new filename


Fields: [ ]=Optional with Default Value
  1. OldFileName
    The file path and file name of the file to be renamed.


  2. NewFileName
    The new file path and file name of the file.


  3. [ NoVerify = ]
    String Equal to "NOVERIFY" if file is not verified prior to renaming.


Examples:
  • C, RenameFile, "C:/Test/Test1.txt" , "C:/Test/Test2.txt"
    Rename file C:/Test/Test1.txt to C:/Test/Test2.txt


  • C, RenameFile, "C:/Test/Test1.txt" , "C:/Test/Test2.txt","NOVERIFY"
    Rename file C:/Test/Test1.txt to C:/Test/Test2.txt no file existence verification


[How To Read This Reference]

DDDriverFileCommands::SaveTextFromImage
RJ SDC TID SE2

Incorporate OCR technology to detect the text in an image file and save the text to a text file.

Two open-source OCRs are integrated into SAFS. One is TesseractOCR (TOCR) at http://code.google.com/p/tesseract-ocr; the other GOCR at http://jocr.sourceforge.net.

TOCR 2.0.4 and GOCR 0.48 are the latest release. They are available in SAFS and only support English. Both two OCR owners claim to support more languages in next release. Chinese, Japanese, and Korean are going to be supported in TOCR's next release 3.00.



Fields: [ ]=Optional with Default Value
  1. ImageFile
    The name of the image file used to detect text in it.

    The name of the image file used to detect text in it. The name of the text file used to store detected text. By default, the files will be stored in the active "Test" directory. If you specify a relative path, the path will be relative to the project directory. The directory for a full or relative path must already exist.

    The extension of the image file can be .bmp, .jpg, .gif, .tif, .png or .pnm.



  2. OutputFile
    The name of the text file used to store detected text.

    The name of the text file used to store detected text. By default, the files will be stored in the active "Test" directory. If you specify a relative path, the path will be relative to the project directory. The directory for a full or relative path must already exist.

  3. [ OCRId = ]
    OCRId indicating the OCR used to recognize text.

    Two OCR engines are supported. "TOCR" will be taken as default if the parameter is blank. "TOCR" stands for Tesseract OCR; "GOCR" stands for GOCR.

    Note: Seems TOCR performs a bit better than GOCR (personal experience).



  4. [ LangId = ]
    Optional LangId representing the language in use for selected OCR to recognize text.

    For both TOCR and GOCR, only English is supported so far. Language Id takes standard language code, which can be gotten by calling Locale.ENGLISH.getLanguage(). 

    				LangId      Language
				"en"   ---  English
				"cn"   ---  Chinese

    If LangId is not specified with blank or empty string, the language of System locale will be used as default.



  5. [ ScaleRatio = ]
    Optional ScaleRatio indicating the scale ratio for resizing the original image.

    To fit in font size and DPI required by OCR, SAFS needs to resize images before sending them to OCR engines. For screen-captured images with 96DPI, TOCR takes 1.9 as default; GOCR takes 1.5 as default. You may try different ScaleRatio to find an appropriate value if default setting is unable to meet your requirement.

Examples:
  • C, SaveTextFromImage, image.gif, ocr.txt, TOCR, en,
    Detect the text in [project]\Datapool\Bench\image.gif using TOCR with English and default ScaleRatio(1.9), then save the text to [project]\Datapool\test\ocr.txt.



[How To Read This Reference]

DDDriverFileCommands::SetFileProtections
RC RJ TID SDC SE2

Change the file attribute for the file name provided to the value of the new file protection provided.

Change the file attribute for the file name provided to the value of the new file protection provided. An integer containing the new attributes for the file. Here is a description of attributes that can be modified:

0 Normal file (Windows PC Only)

1 Read-only file

2 Hidden file (Windows PC Only)

4 System file (Windows PC Only)

32 Archive - file has changed since last backup (Windows PC Only)

Note: Java-based support like RJ, TID, SDC currently only support setting one file protection at a time--0, 1, 2, 3, 32. They do not yet support Integer values OR'd together to combine settings in a single call.

Note: On platforms other than windows we currently only support setting the READ-ONLY attribute.



Fields: [ ]=Optional with Default Value
  1. FileName
    The file path and file name of the file change the file attribute.


  2. FileProtection
    New value of the attribute of the file to be changed


Examples:
  • C, SetFileProtections, "Test1.txt" , 1
    File attribute of the file Project/Datapool/Test1.txt is changed to 1 (read-only)


  • C, SetFileProtections, "C:Test1.txt" , 0
    File attribute of the file C:Test1.txt is change to 0 (read-write)


[How To Read This Reference]

DDDriverFileCommands::WriteFileChars
RJ TID SDC SE2

Write the specified number of characters to a file already opened for writing.


Fields: [ ]=Optional with Default Value
  1. FileNumber
    The file number/identifier of the file to be written to.


  2. NumberOfChars
    The number of characters to write to the file; however, if this parameter is equal to 'all' then all of the characters from the expression list are written.


  3. ExpressionList
    Expression List, if it begins with ^ then it is treated as a variable.


Examples:
  • C, WriteFileChars, 3, all, ^expression
    All of the text from the expression is written to the file opened with file number 3. The next thing written to the file will start immediately following this output, no additional CRLF is assumed.


  • C, WriteFileChars, ^filenumb, 4, "Text Output"
    The first four characters of string "Text Output" are written to the file opened with filenumber contained in DDV Variable ^filenumb. The next thing written to the file will start immediately following this output, no additional CRLF is assumed.


[How To Read This Reference]