//////////////////////////////////////////
// Welcome to Galaxy Examinator Script
// Find more on www.galaxysemi.com
// File: adv_correlation.csl
// 
// Version 2007.1.23
//
// Mission: correlation analysis between two sets of N files (eg: two testers, two loadboards)
//
// Prerequisites:
// a) Folder must hold 2*N STDF files where N is the number of sites tested (minimum: 2 sites)
// b) Each STDF file name is like: <tester_type>_<Nsites-string><string>.std or .stdf
//////////////////////////////////////////

var strWorkingPath;		// To hold folder path where STDF files are located
var	strReportFormat;	// Report format
var bOnError;			// Set when error detected
var iTotalSites;		// Holds total files (sites) per appraiser
var strSiteList;		// Holds ASCII list of sites to analyze 'eg: '12345678')
var strPrefixFile[2];	// To hold file prefix string for Group#1 & Group#2 names
var strGroup[2];		// To hold Group#1 & group#2 names
var iDatasetReference;  // Tells which of the two datasets identified is the reference.
var strGuardBandFile;	// Holds path to GuardBand file.
var strMyReport;		// Holds path to MyReport XML temporary file created for generating Correlation report!

//////////////////////////////////////////
// Startup Init routine
//////////////////////////////////////////
InitFunction()
{
  // Clear error flag
  bOnError = 0;

  // Clear file cont
  iTotalSites = 0;

  // Welcome message
  sysLog('###################################');
  sysLog('#  Correlation Report V2007.1.23  #');
  sysLog('###################################');
}

//////////////////////////////////////////
// Cleanup on exit...
//////////////////////////////////////////
var ExitFunction()
{ 
  // Delete MyReport XML file created for report generation.
  if(fileExists(strMyReport))
    fileDelete(strMyReport);

  // Success!
  return 1;
}

//////////////////////////////////////////
// Prompt user to browse disk and select working folder
//////////////////////////////////////////
var GetWorkingFolder()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Get Working folder
  do
  {
    sysLog('Select any file from working folder...');
    strWorkingPath = sysPrompt();
  }
  while(strWorkingPath == '');

  // Extract path from file string
  var ext, dir, drive, iIndex, iLoop;
  strSplitPath(strWorkingPath,ext,dir,drive);
  strWorkingPath = drive + dir;

  // Skip line
  sysLog();
}

//////////////////////////////////////////
// Prompt user to browse disk and select working folder
//////////////////////////////////////////
GetReportFormat()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Get Output format
  sysLog('Define report format:');
  sysLog('  1: PDF document (default)');
  sysLog('  2: Web/Html page');
  sysLog('  3: Word document');

  var iChoice;
  var bOk=0;
  do
  {
    sysLog('Your choice (1,2 or 3)?');
    iChoice = sysPrompt();
    switch(iChoice)
    {
      case 1:
	  strReportFormat = 'pdf';
      bOk = 1;
	  break;
      
	  case 2:
	  strReportFormat = 'html';
      bOk = 1;
	  break;
      
	  case 3:
	  strReportFormat = 'word';
      bOk = 1;
	  break;
      
	  default:
	  if(iChoice != '')
	    break;
      bOk = 1;   
	  sysLog('PDF format selected');
	  strReportFormat = 'pdf';
	  break;
    }
  }
  while(bOk != 1);
}

//////////////////////////////////////////
// Check if STDF files available
//////////////////////////////////////////
var CheckValidFileCount()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Counts how many STDF files are in folder
  var vFileCount = 0;
  var vExt = '*.std;*.stdf';
  var vFile = fileFindFirst(strWorkingPath,vExt);

  while(vFile != '')
  {
    // Update cfile count
    vFileCount ++;

    // Get next file to process
    vFile = fileFindNext(); 
  };

  // Check if even number
  if(vFileCount % 2)
  {
    sysLog("*Error: Even number of STDF files found in folder!");
    sysLog("Note: Correlation can only be conducted\nover odd number of files.");
   
    // Return error code
    bOnError = 1;
    return 0;
  }

  // Check if at least four files in folder
  if(vFileCount < 4)
  {
    sysLog("*Error: Note enough STDF files in folder!");
    sysLog("Note: Correlation requires at least \nfour STDF files.");
   
    // Return error code
    bOnError = 1;
    return 0;
  }

  // Compute total files per appraiser (ie: number of tested sites)
  iTotalSites = vFileCount / 2;

  // Build numerical string listing all sites . eg: '_12345678'
  vFileCount = vFileCount /2;
  var iSiteID;
  strSiteList = '_';	// Site list starts with '_'
  for(iSiteID=1; iSiteID <= vFileCount; iSiteID++)
  {
    // String concatenation
    strSiteList += iSiteID;
  }

  // Success
  return 1;
}

//////////////////////////////////////////
// Extract root name for the two datasets
// And ask user associated names.
//////////////////////////////////////////
var GetGroupNames()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Get full file name
  var vFileName = '*' + strSiteList;
  var vExt = vFileName + '*.std;' + vFileName + '*.stdf';
  var vFile[2];		// To hold two matching file
  var vTempFile;	// Temp. buffer

  // Get first file matching criteria
  vFile[0] = fileFindFirst(strWorkingPath,vExt);

  if(vFile[0] != '')
  {
    vFile[1] = fileFindNext();
    if(vFile[1] != '')
    {
      // We should only find two files matching the criteria '*_12345678*.std'
      vTempFile = fileFindNext();
      if(vTempFile != '')
      {
         sysLog('*Error: We should have only TWO files matching criteria:');
		 sysLog(vFileName);
		 bOnError = 1;
		 return 0;
	  }
	}
	else
	{
	  // Error, only one file matching criteria
       sysLog('*Error: We should have TWO files matching criteria (instead of one):');
       sysLog(vFileName);
	   bOnError = 1;
	   return 0;
	}
  }
  else
  {
    // Error, no file matchig criteria!
    sysLog('*Error: We should have TWO files matching criteria (instead of none):');
    sysLog(vFileName);
    bOnError = 1;
    return 0;
  }

  // Extract prefix string of the two files identified.
  var ext, dir, drive, iIndex, iLoop;
  for(iLoop = 0; iLoop <= 1; iLoop ++)
  {
    strPrefixFile[iLoop] = strSplitPath(vFile[iLoop],ext,dir,drive);
    iIndex = strIndexOf(strPrefixFile[iLoop], strSiteList)-1;
    strPrefixFile[iLoop] = strLeftJustify(strPrefixFile[iLoop], iIndex);
  }


  // Display to user the two datasets names identified
  var strString;
  sysLog('Datasets detected for correlation:');
  strString = '  Dataset#1: ' + strPrefixFile[0];
  sysLog(strString);
  strString = '  Dataset#2: ' + strPrefixFile[1];
  sysLog(strString);
  sysLog('\n');

   // Get Group1 label (as will appear in Galaxy reports)
  do
  {
    sysLog('Please enter a short name for Dataset#1:');
    strGroup[0] = sysPrompt();
  }
  while(strGroup[0] == '');

  // Get Group2 label (as will appear in Galaxy reports)
  do
  {
    sysLog('Please enter a short name for Dataset#2:');
    strGroup[1] = sysPrompt();
  }
  while(strGroup[1] == '');

  // Check if the two groups are identical...
  if(strGroup[0] == strGroup[1])
  {
    sysLog("Sorry but you can't use the same name for both dataset!\nStart over!");
    bOnError = 1;
    return 0;
  }

  // Ask which of the two dataset is the reference
  do
  {
    sysLog('Which Dataset# is the reference (1 or 2)?');
    iDatasetReference = sysPrompt();
  }
  while((iDatasetReference != '1') && (iDatasetReference != '2'));
  iDatasetReference--;	// Decrement it to be in line with array indexes.

  // Success
  return 1;
}

//////////////////////////////////////////
// Get path to Released guard band file
//////////////////////////////////////////
var GetReleasedGuardBandFile()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Check if only one CSV file found if folder. If so, use it, otherwise prompt user to select it
  strGuardBandFile = fileFindFirst(strWorkingPath,'*.csv');
  if(strGuardBandFile == '')
  {
    // No GuardBand file in folder...ask user to select one!
    do
    {
	  sysLog('Please select GuardBand file to use:');
      strGuardBandFile = sysPrompt();
    }
    while(fileExists(strGuardBandFile) == 0);
  }
  else
  {
    // A CSV file was found, check if it is the only CSV file in folder!
    var strTmpFile = fileFindNext(); 
	if(strTmpFile != '')
	{
      do
      {
	    sysLog('Please select GuardBand file to use:');
        strGuardBandFile = sysPrompt();
      }
      while(fileExists(strGuardBandFile) == 0);
	}
  }

  // Build MyReports file instructing to generate a Correlation report.
  strMyReport = strWorkingPath + '/tmp_my_report.grt';
  var hFile = fileOpen(strMyReport,fileOpenWrite);
  if(hFile == 0)
  {
    // Disk WRITE error
    sysLog("*Error: Failed creating 'MyReport' script file");
    bOnError = 1;
    return 0;
  }

  fileWrite(hFile,'<galaxy_template>\n');
  fileWrite(hFile,'<section_home_page>\n');
  fileWrite(hFile,'HomeText=\n');
  fileWrite(hFile,'HomeLogo=\n');
  fileWrite(hFile,'</section_home_page>\n');
  fileWrite(hFile,'<section_tester_correlation_gb>\n');
  fileWrite(hFile,'Title=Section: Tester-to-tester Correlation + GuardBand\n');
  var strString = 'GuardBandFile=' + strGuardBandFile + '\n';
  fileWrite(hFile,strString);
  fileWrite(hFile,'</section_tester_correlation_gb>\n');
  fileWrite(hFile,'</galaxy_template>\n');
  fileClose(hFile);

  // Success!
  return 1;
}


//////////////////////////////////////////
// Create Examinator groups for correlation
//////////////////////////////////////////
var CreateDatasets()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Compare groups of files...
  gexGroup('reset','all');
  gexQuery('db_report','DataSet');

  // Define array offset to dataset NOT the reference
  var iOtherDataset=0;		// To hold Array index to dataset NOT the reference
  if(iDatasetReference == 0)
    iOtherDataset = 1;

  // Create all groups for Dataset NOT the reference
  var iIndex, iSiteID, group_id, strSites;
  var strString, strFile;
  for(iIndex = 1; iIndex <= iTotalSites; iIndex++)
  {
    // Build sites list (FIFO type).
     strSites = '_';	// Site list starts with '_'
    for(iSiteID=0; iSiteID < iTotalSites; iSiteID++)
    {
      // String concatenation. eg: '34567812'
	  if(iSiteID+iIndex > iTotalSites)
        strSites += (iSiteID+iIndex-iTotalSites);
	  else
        strSites += (iSiteID+iIndex);
    }

    // Build group name: 'Unit X - <DatasetLabel>'. eg: 'Unit 1 - carsem'
    strString = 'Unit ' + iIndex + ' - ' + strGroup[iOtherDataset];
    group_id = gexGroup('insert',strString);
	// Find full path to relevant file...
	strFile = strPrefixFile[iOtherDataset] + strSites + '*.std;' + strPrefixFile[iOtherDataset] + strSites + '*.stdf';
    strFile = fileFindFirst(strWorkingPath,strFile);
    gexFile(group_id,'insert',strFile,'All','all',' ','','','');
	if(fileExists(strFile) == 0)
	{
	  sysLog("Error: File name convention breached. Can't find file:");
	  sysLog(strFile);
      bOnError = 1;
      return 0;
	}
  }

  // Create all groups for REFERENCE Dataset
  for(iIndex = 1; iIndex <= iTotalSites; iIndex++)
  {
    // Build sites list (FIFO type).
     strSites = '_';	// Site list starts with '_'
    for(iSiteID=0; iSiteID < iTotalSites; iSiteID++)
    {
      // String concatenation. eg: '34567812'
	  if(iSiteID+iIndex > iTotalSites)
        strSites += (iSiteID+iIndex-iTotalSites);
	  else
        strSites += (iSiteID+iIndex);
    }

    // Build group name: 'Unit X - <DatasetLabel>'. eg: 'Unit 1 - ref'
    strString = 'Unit ' + iIndex + ' - ' + strGroup[iDatasetReference];
    group_id = gexGroup('insert',strString);

	// Find full path to relevant file...
	strFile = strPrefixFile[iDatasetReference] + strSites + '*.std;' + strPrefixFile[iDatasetReference] + strSites + '*.stdf';
    strFile = fileFindFirst(strWorkingPath,strFile);
	gexFile(group_id,'insert',strFile,'All','all',' ','','','');
	if(fileExists(strFile) == 0)
	{
	  sysLog("Error: File name convention breached. Can't find file:");
	  sysLog(strFile);
      bOnError = 1;
      return 0;
	}
  }

  // Success!
  return 1;
}

//////////////////////////////////////////
// Main entry point.
//////////////////////////////////////////
var BuildCorrelationReport()
{
  // If error occured previously, return now!
  if(bOnError)
    return 0;

  // Update output format
  gexOptions('output','format',strReportFormat);

  // Path to MyReport XML file...
  gexReportType('adv_my_report','template',strMyReport);

  // Trigger report creation
  gexBuildReport('home','0');
}

//////////////////////////////////////////
// Main entry point.
//////////////////////////////////////////
var main()
{ 
  // Init sequence
  InitFunction();

  // Get user define path to files to process
  GetWorkingFolder();

  // Get user define output format
  GetReportFormat();

  // File count validity check
  CheckValidFileCount();
  
  // Get report label to associate to each dataset
  GetGroupNames();

  // Get path to released guard band file
  GetReleasedGuardBandFile();

  // Create Dataset groups
  CreateDatasets();

  // Build report!
  BuildCorrelationReport();

  // Cleanup
  ExitFunction();
}