## STGuru User's Guide

Appendix

A.3 Command Line Guide (Only for STGuru Standard Edition)

Versions:

* The command line feature is dedicated to STGuru Standard Edition (available only in STGuru Standard Edition, not supported by other STGuru editions)

* All STGuru Standard Edition users can use the standard command line features (single process only, with task queue support)

* Super-high-end customers can order multiple process versions

Target customers

* High-end developers and alike - developers, site administrators and computer geeks familiar with command line operations - that are interested in dynamical real-time conversions

Features

* You can specify and switch between Simplified Chinese and Traditional Chinese conversion packs in real time

* Can realize full range of file and folder conversions: Any combinations between Simplified Chinese (GBK, UTF-8, Unicode and Unicode BE) and Traditional Chinese (Big5, GBK, UTF-8, Unicode and Unicode BE), totally 9*8=72 types of conversions

* General users familiar with command line operations can also make custom batch files based on the command line feature (you can refer to the sample batch files listed in the pack at the end of this guide). They are actually fully automatic batch conversion packs

* If you use our scheduling product Anasoft Scheduler PE, you can also carry out command line operations at specified times

A3.1 Introduction

1) Prerequisites

Before performing command line operations, following pre-requirements must be met:

Requirement 1: You must first set STGuru to run in single-instance mode

You only need to set it once. However, when you do not use the command line feature, you can also cancel this mode in the same way:

Steps: Start STGuru and follow the instructions in the Options dialog box to set it: Tools -> Options -> Command Line.

If you regularly use the command line feature, and really need to open multiple instances of STGuru at the very same time, you can install STGuru Standard Edition and STGuru Traditional Chinese Edition at the same time. Clients that buy STGuru Standard License are granted the right to use the full versions of STGuru Standard Edition and Traditional Chinese at the same time. The Traditional Chinese version is not subject to the restriction by the single-instance mode, and it has UIs in English, Simplified Chinese and Traditional Chinese, so can be used smoothly in any language versions of Windows.

Requirement 2: The product folder of STGuru Standard Edition should have been registered in Windows

It can be set by going through the very same steps described above.

If you do not have the permissions the set this setting, you can call STGuru to perform the command line commands with STGuru's full path.

Suggestion: Fully start STGuru before sending command line commands to it

STGuru needs about 0.5 second to start, during which it may not respond to all external calls. Therefore, when you call STGuru with an external program, please do not send commands during its startup time.
It is strongly recommended that you fully start STGuru before sending out command line commands to it.

2) Types of Commands (Control Commands, Conversion Commands and Command Queue)

Command line commands start with playplay. There are two types of them:

a) Control commands, started with set. They are used as control instructions

b) Conversion commands, started with convert, including file conversions (file) and folder or directory conversions (directory)

Except for a few commands (there are 4: set cancel, set halt, set continue and set ProgressReportPath), all commands will be added into the queue after they are received by STGuru and then, will run sequentially. You can specify an ID for each command in the queue. The ID can be used to delete or cancel this command. If you haven't specified an ID for a command, the system will add one for it automatically.

3) Status Feedback

a) Path of the log file is: {Product Package Folder}\PlayPlayLog\yyyy-mm.log

e.g.: C:\Program Files\Anasoft\STGuru Standard Edition (Trial Version)\PlayPlayLog\2009-01.log

b) Two facts are specified in the progress report file: (1) Total number of tasks and task the list, including the ID and command of each task, and (2) the percentage progress of the current task

The default path of the progress report file is: {Product Package Folder}\PlayPlayLog\progress.log

e.g.: C:\Program Files\Anasoft\STGuru Standard Edition (Trial Version)\PlayPlayLog\progress.log

However, you can also specify the path of the progress report file by the command line command set ProgressReportPath.

4) Uppercase and Lowercase

Except for command ID {CommandID}, all parameters in a command are NOT case sensitive.

5) Command IDs and How to Cancel Commands

Each command can have a Command ID in the following syntax:
{ProductExe} playplay {[ID="{CommandID}"]} set singleinstance {nSet}
Example:
STGurud playplay [ID="SetSingle"] set singleinstance 1
Where "{CommandID}" = "SetSingle"
{CommandID} is case sensitive. Its primary purpose is to be used as a handle for you to cancel or delete a command currently running or waiting in the command line queue.

If you haven't set a command ID, the system will set the ID for you. The default ID is Command ID.

If an ID already exists, the system will add a serial number after the ID, such as Command ID (1), or Command ID (2).

Command IDs can be found in the progress report file (see 3 above).

You can also cancel the current command or all commands by the set cancel command.

6) Trial Version and Full Version

Both the current trial version and the full version are single-process, which means you can only perform tasks one by one. Tasks can be queued, but cannot run simultaneously.

All licenses are restricted to be used only by the buyers - the individuals or organizations whoever buy it. It is strictly prohibited from being used for providing free or paying service for a third party or third parties, or used in developing similar product(s) or module(s) that can be used directly or indirectly by a third party or third parties.

Trial version (single process)

There is a 30-day free trial period within which you can convert files or text of up to 40 KB in unit size; in site/directory conversion, you can convert up to 40 files.

The executable name of the trial version is STGurud.exe (so the value of {ProductExe} below should be STGurud).

Full version (single process)

1) No above-mentioned limits on time, or on maximum number of characters or files

2) The license for the full version is simply that for STGuru Standard Edition. You can check its current rate here. The full version is also a single-process version. It can be used only on one computer (activation required). You can update it free of charge for 3 years.

The executable file name of the full version is STGuru.exe (so the {ProductExe} below should have a value of STGuru).

We have no specific plan in developing multi-process full version so far. If you need one, welcome to order it in advance. The plan is like this:

1) 10-process license: You can start up to 10 full versions on the computer you specify. This is still a one computer license. It has 5 years of free update, can be used for 8 years. The expected price is about $1600. 2) 50-process license: You can start up to 50 full versions on the computer you specify. This is still a one computer license. It has 5 years of free update, can be used for 8 years. The expected price is about$5000.

System requirements:

10 process license: a 4-core computer is required, 8-core suggested, or the 10-process license would not be necessary.

50 process license: at least an 8-core computer is required, or the 50-process license would not be necessary.

To pre-order a multi-process full version:

50% prepayment is required. The delivery period is 1-2 months.

7) Command Line Options

A Command Line options page is added to STGuru's Options dialog box, where you can modify the following command line related options:

* Launch STGuru in single-instance mode (on or off).

* Add STGuru's product folder into Windows search path (on or off). You can let STGuru to set it for automatically (but you must restart Windows) or you can do it manually by following the instructions given (effective immediately).

* Set the path of the progress report file. If you clean this path, no feedback will be provided. You can also reset it to a default path if you want.

A3.2 Command Details

1) Control Commands That Run Instantly (Not Joining the Command Line Queue)

set cancel Cancel Command

This command can be used to cancel the current command or all commands in the queue.

Syntax (nSet=1 -> set; nSet=0 -> cancel)
{ProductExe} playplay set cancel 0
{ProductExe} playplay set cancel all
{ProductExe} playplay set cancel "{CommandID}"
If the part after cancel is 0, the current command will be cancelled/deleted.
If the part after cancel is all, all commands will be cancelled.
If there is an ID after cancel, the command connected with this ID will be cancelled/deleted.

Example
STGurud playplay set cancel "SetSingle"
The command with ID "SetSingle" will be cancelled.

set halt / set continue Suspend or Continue Command

These two commands can be used to halt or continue command line operations.

Halt
Syntax
{ProductExe} playplay set halt

Continue
Syntax
{ProductExe} playplay set continue

Example
STGurud playplay set halt
STGurud playplay set continue

set ProgressReportPath Set Progress Report File Path

The command is used to set the path of the progress report file. As progress reports are written in frequently, if you worry about any possible influence on your hard disk, you can also alternate a path, or stop the program from writing the report.

Syntax
{ProductExe} playplay {[ID="{CommandID}"]} set ProgressReportPath {ProgressReportPath}

Example
STGurud playplay set ProgressReportPath
STGurud playplay set ProgressReportPath ""
The two above statements clear the path, so no progress will not be reported.
STGurud playplay set ProgressReportPath reset
This command let you use the application's default path at: {Product Folder}\PlayPlayLog\Progress.log
STGurud playplay set ProgressReportPath "c:\temp\progress.txt"
Set the path to "c:\temp\progress.txt"

2) Control Commands That Are Carried Out in the Command Line Queue

set singleinstance Set/Cancel Single Instance

STGuru must run in single instance (which means only one instance of STGuru can be opened) before it can perform command line commands correctly. So if you need to perform command line operations, please set it to run in single instance first. If you do not need to use command line commands, you can cancel the single instance mode.

Syntax (nSet=1 -> set; nSet=0 -> cancel):
{ProductExe} playplay {[ID="{CommandID}"]} set singleinstance {nSet}

Example:
STGurud playplay set singleinstance 1
STGurud playplay set singleinstance 0
STGurud playplay [ID="SetSingle"] set singleinstance 1

set pack Set Conversion Pack

The command is used to set the current conversion pack.

Syntax
{ProductExe} playplay {[ID="{CommandID}"]} set pack {Pack Path}

Example
STGurud playplay set pack C:\conversion\stcp\international\Sony\VAIO\VAIO.stcp
STGurud playplay set pack C:\conversion\stcp\local\anasoft\anasoftstudio.stcp

3) File/Folder Conversion Commands

convert file / convert directory Convert File/Directory

These two commands are used to convert a file and a directory, respectively. There are 9x8=72 directions - all possible combinations between Simplified Chinese (in GBK, UTF8, Unicode and Unicode BE) and Traditional Chinese (in GBK, Big5, UTF8, Unicode and Unicode BE). You can set the options of prohibiting converting into the source path itself to protect the source file/folder. When converting a directory, you can also set the option of copying non-text files and converting all files in all levels of subdirectories. The software can recognize text files automatically. If you have text and non-text files in the directory, the software will only convert text files while keep non-text files untouched (you can select to copy non-text files to the same position in the target directory).

Syntax
{File Conversion}
{ProductExe} playplay convert file[{Switches},{SourceCode}-{SourceLan,{TargetCode}-{TargetLan] s="{SourcePath}" d="{TargetPath}"
{Directory Conversion}
{ProductExe} playplay convert directory[{Switches},{SourceCode}-{SourceLan,{TargetCode}-{TargetLan] s="{SourcePath}" d="{TargetPath}"

Notes:
{Switches}
There are 3 switches - n/s/c. Please read details on how to use them below. s and c are only for directory conversions. You only need to set switch(es) actually used. The switches not to be used do not need to appear. Used switches can be placed closely together, such as nsc. The three switches can be placed in any order.
n: Conversion results should be saved in a new file/web page. When setting it, the source and destination file cannot be in the same path, or conversion will not be performed.
s: Including subdirectories (only applicable for directory conversions)
c: Copying non-text files to the new site (only applicable for directory conversions)

{SourceCode}/{TargetCode}:
GBK, Big5, Unicode, Unicode BE, UTF8

{SourceLan}/{TargetLan}:
s: Simplified Chinese

Notes:
1) The proper writing of UTF8 is 'UTF8', rather than 'UTF-8'.
2) There is no such a combination as Big5-s. All other combinations are valid.
3) {SourceCode} cannot be the same as {TargetCode}-{TargetLan], otherwise no conversion will happen.
4) A conversion will be skipped upon other invalid conditions, such as invalid file path or the destination directory is not blank.

Example
STGurud.exe playplay convert directory[nsc,utf8-s,utf8-t] s="C:\test\directories\utf8_s" t="C:\test\directories\utf8_t"

A3.3 Sample Pack

Extract

After you complete download, you can extract it in the root path of c:\.

The first-level subdirectory after extraction is:

c:\test

There are 4 second-level subdirectories:

C:\test\files

C:\test\directories

C:\test\directories_s

C:\test\directories_ss

If you extract it into a deeper level, you can adjust the paths by yourself.

Notes

Preparations

Before running a batch file

a) You must have added STGuru's installation folder to Windows search path (for details, see Prerequisites above), and

b) You must have set STGuru to run in single instance mode (for details, see Prerequisites above), and

c) You are strongly suggested to fully open STGuru. STGuru needs about 0.5 second to start, during which it may not respond to all external calls. Therefore, when you call STGuru with an external program, please do not send commands during its startup time.

1) In each of the 4 directories there is a .bat file started with stgurud_, and another one started with stguru_. The first one is a batch file for the trial version; the other is for the full version.

2) There are three sections in each batch file. The first two statements are the first two sections. They start STGuru, and delay for 1 second so STGuru can fully start. The following commands are normal command line commands. They are the third section. If STGuru has already been fully started before you run a batch file, the first two statements, or the first two sections can be skipped. Of course, if you do not mind waiting for 1 useless second, you can keep them.

Section 1: Start STGuru with the "start" shell command. In the start command in the batch file for the trial version, a command line command is append as the first one sent to STGuru. It will run automatically after STGuru starts.

Section 2: Delay for 1 second. The "ping" command is used. We do not need to ping anything. It is used here because the performing of this command lasts about 1 second. We need this one second so STGuru can have enough time to fully start before following command line flow comes. The "ping" command can be performed properly only when you have Internet connection.

Section 3: Normal command line commands.

files

3) In the first-level subdirectory files, there is a gbk_s subdirectory, and there is a text file in Simplified Chinese in GBK in this folder. The batch files in the files folder will convert this file to other 8 codes in 8 new subdirectories, with one code in one subdirectory.

directories, directories_s and directories_ss

4) Files in these folders are provided for you to test directory conversions. The only difference between them are the number of files they include - there are 30+ files in the directories directory, half of the number in the directories_s directory, and less than 10 files in the directories_ss directory, the smallest one.

5) The proper source code for all these directories should be Simplified Chinese in UTF-8, but there are also files in "wrong" code and there are binary files - they cannot be properly converted. They are there just for you to test what will happen if you convert files in a wrong source code. In each of the three directories subfolders, there is a utf8_s subfolder. This means this folder should contain files in Simplified Chinese in UTF-8. However, in order for you to have a chance to test all possible situations - good source files, wrong source files and irrelevant ones - not all files in this folder are actually of the format "Simplified Chinese in UTF-8". There are three subdirectories:

proper_code_utf8_s

Only the files in this folder are correct (they are really "Simplified Chinese in UTF-8"), so can be converted properly. This folder has a subfolder word_files_useful_only_in_utf8 that includes XML format of Microsoft word files. Microsoft Word can read it only when these files are converted to UTF-8 (Simplified Chinese or Traditional Chinese). Word will not be able to read them if they are in other codes.

wrong_code

There is a folder gbk_s in it with files in Simplified Chinese in GBK This folder is used to display the situation when you convert files from a "wrong" code. Obviously, the result will be wrong.

binary_files

There are some Microsoft doc files in this folder. They are actually binary files. These files will not be converted. They will be copied directly to the target folders.