1 of 5 17/06/2013 9:10 AM

Transcription

1 1 of 5 17/06/2013 9:10 AM

2 2 of 5 17/06/2013 9:10 AM RUNNING ADJUSTMENTS BATCH PROCESSING FROM THE COMMAND LINE Using the STAR*NET Batch File Feature STAR*NET can be executed from a command line and told to run a given project. Upon completion, it writes a run status file and exits. If you wish to use this feature, you or your staff must have the ability to create and execute a batch file (*.bat) and also create additional programs to parse the various output files if that is required for your use for running STAR*NET in a batch fashion. Below is a simple batch file we used to test STAR*NET using the batch file feature. The batch file executes STAR*NET, opens up an existing project Trav3D.prj and then the /RUN command-line option causes the program to run an adjustment. Upon completion of the run, a status file Trav3D.run file is created to document the status of the run. The test batch off :Top REM User programs for constructing STAR*NET data go here REM Run STAR*NET "C:\Program Files\MicroSurvey\Starnet V6\StarNet.exe" C:\JOBS\BatchTest\Trav3D.prj /RUN echo STAR*NET ran and created a run status file C:\JOBS\BatchTest\Trav3D.run... REM User programs for checking run status file and analyzing data files go here REM User programs may sleep for a time betweem runs REM User programs may loop to top or go to End depending on the logic scheme REM This batch test loops to the top and keeps rerunning until manual termination echo echo This test loops to run again - Press Ctrl-C to terminate goto Top :End Note that there are remarks before and after the command line that runs STAR*NET. These lines indicate location of your programs that prepare STAR*NET data and analyze resulting STAR*NET output. The batch test above simply loops continuously - starting up STAR*NET, running it, writing a status file, exiting and then doing all over again until you manually terminate by pressing Control-C. Please let us know if you have questions about this. Notes: 1. The format for the command line that executes the STAR*NET program is: Path\StarNet.exe Path\ProjectName.prj /RUN The /RUN parameter causes the program to run the adjustment and to create a run status file upon completion. By default, the name of the status file is the project name with a run extension and it will be located in the same directory as the the original prj file. If it is preferred that the status file be named something else and written to a specified directory, you can add a

3 3 of 5 17/06/2013 9:10 AM colon : to the /RUN parameter and follow it by complete a path and file name. For example, the line below will create the status file in C:\MyTests with a Status.txt name. Path\StarNet.exe Path\ProjectName.prj /RUN:C:\MyTests\Status.txt If the path and/or filename for either the.prj and/or the specified status file contains a space character, you must use the equivalent short DOS-compatible 8.3 filename for that subfolder/file. To determine the short 8.3 file/folder name, at the command line type "dir /x" to view the short filenames. For example, the path to a project in your My Documents folder might be: C:\Documents and Settings\Your Name\My Documents\MicroSurvey\StarNet\My Project.prj but for each folder or file containing a space you must specify its equivalent DOS-compatible 8.3 name like: C:\DOCUME~1\YOURNA~1\MYDOCU~1\MicroSurvey\StarNet\MYPROJ~1.prj The status file contains one or more lines. The first line always contains a single number which is the status of the run. This number is constructed by setting status bits as defined below. One or more bits are combined to create the status number. A program written by your programmers can read this status number and by examining the individual bits that are set, determine some resulting information about the run. For example, your program logic may be designed to continue the batch process if the adjustment was completed and only bit 0x0001 and/or 0x0002 were set. But it may be designed to terminate if 0x0004 or 0x0008 bits were on. If any of the status bits set in the lower group are on, your batch program sequence must be designed to terminate because the adjustment did not complete! The following shows the status bits (expressed in hexidecimal) and the meaning of each: Adjustment completed: Run Warnings = 0x0001 Run Failed Chi Square Test Lower = 0x0002 Run Failed Chi Square Test Upper = 0x0004 Run Did Not Converge = 0x0008 Adjustment not started or not completed Run Errors = 0x0100 Security Key Failure = 0x0200 Project File Open Failure = 0x0400 Project File Errors = 0x0800 Unable To Start Adjustment = 0x1000 When the status number is zero, this indicates the adjustment ran successfully and there were no errors or warnings. When there are errors or warnings, the status number will be non-zero and your program should decide what to do by testing which bits are set in the status number. When the status number is non-zero, additional lines are printed in the file giving you a way to visually check which errors or warnings were found. The example status file below shows the status number (expressed in decimal) followed by the individual bits (also expressed in decimal) that were set. This adjustment did not run because there was a problem accessing the security key most likely it could not be found by STAR*NET Security Key Failure

4 4 of 5 17/06/2013 9:10 AM The example status file below shows the status number (expressed in decimal) followed by the individual bits (expressed in decimal) that were set. In this example, the adjustment successfully ran, but there were warnings. The fact that the adjustment did not converge should be reason enough for your to terminate the batch process so you can determine why this is happening Run Warnings 8 Run Did Not Converge 4 Run Failed Chi Square Test Upper Bound 4. When STAR*NET is executed from a batch file as illustrated in the example of the first page, before the run status file is written for the current run, STAR*NET will delete the run status file from a previous run if one exists.therefore, since the next command in the batch file will not be executed until STAR*NET has finished, the run status file is guaranteed to be fresh. However, if STAR*NET is executed from another program in the batch file (i.e. it becomes a separate process), there is no guarantee that STAR*NET will finish and and create a new run status file before another program in the batch file checks for it. In case you wish to do this, we have another program called WaitForFile which should be executed just before your program that checks the run status file. Note that to use this program, it will be your responsibility to delete an existing run status file before the batch program runs STAR*NET. The WaitForFile.exe program and command line parameters are as follows: WaitForFile.exe path\filename [ interval [ interval_count ] Filename: Interval: Full or relative path Sleep time in milliseconds between checks for file Optional, default is 100 ms Interval_count: Number of check attempts before timeout Optional (to be present requires interval to also be present Default: no limit Return value: 0 File Found 1 Timeout 2 Bad parameter found Again, this program (or a similar facility written by your programmers) need be used only when the execution of STAR*NET is not started directly from the batch file. See next page for an example of its use in a batch file. The following illustrates how the WaitForFile program might be used in a batch file. This batch file is basically the same as the original example except that STAR*NET is run from another program - not directly from the batch program. This causes STAR*NET to be run in a separate process. Any existing run status file must be deleted before STAR*NET is executed as illustrated below. A separate program WaitForFile.exe is then executed to wait for a status file to be created from STAR*NET.

5 5 of 5 17/06/2013 9:10 off :Top REM User programs for constructing STAR*NET data go here REM Delete existing run status file if present Del C:\WINSTAR\BatchTest\Trav3D.run REM Assume some other user program runs the STAR*NET program here using the same REM project name as illustrated in the original batch example. STAR*NET is now REM running as a separate process... REM Now run the WaitForFile program which keeps looking for the run status file WaitForFile C:\WINSTAR\BatchTest\Trav3D.run on errorlevel 2 goto BadParam on errorlevel 1 goto Timeout REM No errors returned from WaitFor File, therefore the run status file was found echo STAR*NET ran and created a run status file C:\WINSTAR\BatchTest\Trav3D.run... REM User programs for checking run status file and analyzing data files go here REM User programs may sleep for a time betweem runs REM User programs may loop to top or go to End depending on the logic scheme REM This batch test loops to the top and keeps rerunning until manual termination echo echo This test loops to run again - Press Cntrl-C to terminate goto Top :BadParam echo Bad Parameter for WaitForFile program goto End :Timeout echo Timeout for WaitForFile program goto End :End