[Artwork] / [QisMLib]

QisMScript

Scripting interface to QisMLib

QisMScript C++ API (qismscript.h)

class QisMScriptUtil

class QisMScriptUtil { ... };

A utility class available to any script handler for commonly used tasks

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied).

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMScriptUtil_cast(const int version) = 0;
virtual const void* QisMScriptUtil_cast(const int version) const = 0;
virtual const char* QisMScriptUtil_name(const int version) const = 0;
virtual int QisMScriptUtil_version() const = 0;

Add_var()

Create a new variable to be referenced elswhere in the script (in other commands)

• type : variable type as string -- e.g "int" or "CMyClass"

• name : identifier for the variable to be used to reference it

• handle : variable value (MUST persist during it's usage in the script)

• All variables added using this method MUST be treated like global variables as far as the script is concerned

xxxxxxxxxx
virtual void Add_var(const char* type, const char* name, void* handle) = 0;

Get_var()

Get the value associated with a variable

• type : variable type as string -- e.g "int" or "CMyClass"

• name : identifier for the variable to be used to reference it

• Return: value (if not NULL). if NULL, the specified variable was not found

xxxxxxxxxx
virtual void* Get_var(const char* type, const char* name) const = 0;

Remove()

Delete a variable and it's value

• type : variable type as string -- e.g "int" or "CMyClass"

• name : identifier for the variable to be used to reference it

• Future calls to Get_var(..) will return NULL

xxxxxxxxxx
virtual void Remove(const char* type, const char* name) = 0;

Log_msg()

Write a log message (stdout / log file)

• format : message format (as with printf)

xxxxxxxxxx
virtual void Log_msg(const char* format, ...) = 0;

class QisMScript

xxxxxxxxxx
class QisMScript { ... };

Represents a script command handler

enum Status

Status codes returned by a command

xxxxxxxxxx
enum Status {
  CMD_OK=0 /* command executed without error */
 ,CMD_WARNING=1 /* command failed (not fatal). continue execution */
 ,CMD_ERROR=2 /* command failed (fatal). abort execution */
 ,CMD_ABORT=3 /* abort execution without error (exit) */
 ,CMD_PROC_OK=4 /* reserved for internal use */
};

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived).

• Get the latest version number.

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied).

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMScript_cast(const int version) = 0;
/*{ //SAMPLE DEFINITION TO BE IMPLEMENTED BY THE HANDLER
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<QisMScript*>(this);
    ...
    case n: return dynamic_cast<QisMScriptVn*>(this);
  }
  return 0;
}*/
virtual const void* QisMScript_cast(const int version) const = 0;
/*{ //SAMPLE DEFINITION TO BE IMPLEMENTED BY THE HANDLER
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<const QisMScript*>(this);
    ...
    case n: return dynamic_cast<const QisMScriptVn*>(this);
  }
  return 0;
}*/
virtual const char* QisMScript_name(const int version) const = 0;
/*{ //SAMPLE DEFINITION TO BE IMPLEMENTED BY THE HANDLER
  switch(version) {
    case 0: return "<class_name>";
    case 1: return "QisMScript";
    ...
    case n: return "QisMScriptVn";
  }
  return 0;
}*/
virtual int QisMScript_version() const = 0;
/*{ //SAMPLE DEFINITION TO BE IMPLEMENTED BY THE HANDLER
  return n;
}*/

On_command()

Callback to handle a specific command registered to this handler

• script_util : utility api for commonly used tasks

• command : registered command name

• code : registered command code (specific to this handler) for quick routing

• argc, argv : arg count and values

• Return : One of QisMScript::Status depending on the results of the operation

xxxxxxxxxx
virtual QisMScript::Status On_command(
  QisMScriptUtil* script_util, const char* command, const int code, 
  const int argc, const char* const* argv
  ) { return QisMScript::CMD_OK; }

Get_last_error_msg()

Get error message if return status is CMD_ERROR or CMD_WARNING

xxxxxxxxxx
virtual const char* Get_last_error_msg() const { return ""; }

class QisMScriptRegister

xxxxxxxxxx
class QisMScriptRegister: public QisMExtensionAPI { ... };

Represents the register of all scripting commands

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived).

• Get the latest version number.

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied).

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMScriptRegister_cast(const int version) = 0;
virtual const void* QisMScriptRegister_cast(const int version) const = 0;
virtual const char* QisMScriptRegister_name(const int version) const = 0;
virtual int QisMScriptRegister_version() const = 0;

Register_command()

Associate a command with this handler

• command : command name

• usage : usage string

• handler : handler for this specific command

• command_code : code identifying this command for quick routing

xxxxxxxxxx
virtual void Register_command(
  const char* command, const char* usage, QisMScript* handler,
  const int command_code = -1
  ) = 0;

Get_script()

Get the handler associated with a command

• command : command name

• code : if used, buffer to receive the command code

xxxxxxxxxx
virtual QisMScript* Get_script(const char* command, int* code) const = 0;

class QisMScriptRunner

xxxxxxxxxx
class QisMScriptRunner: public QisMExtensionAPI { ... };

API to execute scripts and commands

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived).

• Get the latest version number.

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied).

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMScriptRunner_cast(const int version) = 0;
virtual const void* QisMScriptRunner_cast(const int version) const = 0;
virtual const char* QisMScriptRunner_name(const int version) const = 0;
virtual int QisMScriptRunner_version() const = 0;

Add_var()

Create a new string variable to be referenced elswhere in the script (in other commands)

• name : identifier for the variable to be used to reference it

• handle : variable value (MUST persist during it's usage in the script)

• All variables added using this method MUST be treated like global variables as far as the script is concerned

• The added value can also be retreived anytime using QisMScriptUtil::Get_var(type, name) where type is "#" and return is const char*

xxxxxxxxxx
virtual void Add_var(const char* name, const char* value) = 0;

Get_var()

Get the value associated with a string variable

• name : identifier for the variable to be used to reference it

• Return: string value (if not NULL). if NULL, the specified variable was not found

• The value can also be retreived anytime using QisMScriptUtil::Get_var(type, name) where type is "#" and return is const char*

xxxxxxxxxx
virtual const char* Get_var(const char* name) const = 0;

Run_script_command()

Run a command (arguments specified as one string)

• command_str : command name and arguments separated by ' ' (space)

• Return : status of the execution. See QisMScript::Status

xxxxxxxxxx
virtual QisMScript::Status Run_script_command(const char* command_str) = 0;

Run_script_command_v()

Run a command (arguments specified as an array of strings)

• command : command name

• argc, argv : command argument count and values

• Return : status of the execution. See QisMScript::Status

xxxxxxxxxx
virtual QisMScript::Status Run_script_command_v(
  const char* command, const int argc, const char* const* argv
  ) = 0;

Run_script_command_file()

Run a script (text) file containing a list of commands (one per line)

• file_path : path of the script file to execute

• Return : status of the execution. See QisMScript::Status

xxxxxxxxxx
virtual QisMScript::Status Run_script_command_file(const char* file_path) = 0;

Get_script_help()

Get available command names and usage

• search_string : filter list using a sub-string of the command name

• Return : command names and usage as a string

xxxxxxxxxx
virtual const char* Get_script_help(const char* search_string = 0) const = 0;

Get_last_error_msg()

Get error message and code for the last error condition

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;

class QisMScriptRunnerV2

xxxxxxxxxx
class QisMScriptRunnerV2: public QisMScriptRunner { ... };

Add_handle()

Create a new object variable to be referenced elswhere in the script (in other commands)

• name : identifier for the variable to be used to reference it

• type : handle type

• handle : variable value (MUST persist during it's usage in the script)

• All variables added using this method MUST be treated like global variables as far as the script is concerned

• The added value can also be retreived anytime using QisMScriptUtil::Get_var(type, name)

xxxxxxxxxx
virtual void Add_handle(const char* type, const char* name, void* handle) = 0;

Get_handle()

Get the value associated with a object variable

• name : identifier for the variable to be used to reference it

• type : handle type

• Return: handle of the specified type (if not NULL). if NULL, the specified variable was not found

• The value can also be retreived anytime using QisMScriptUtil::Get_var(type, name)

xxxxxxxxxx
virtual void* Get_handle(const char* type, const char* name) const = 0;

Remove_var()

Remove a variable from the scripting sub-system

• name : identifier for the variable to be used to reference it

• type : variable type ("#" means string)

• From this point on, Get_handle or Get_var for the specified name+type will return NULL

xxxxxxxxxx
virtual void Remove_var(const char* type, const char* name) = 0;

Basic (QisMScript) Commands

Various utility commands that aid in the development of a script Available to all applications using the QisMLib system with scripting enabled

script.procedure

xxxxxxxxxx
script.procedure {procedure_name}

• Begin definition of a new procedure called {procedure_name}

• Every script.procedure MUST have a matching script.end_procedure

• Nested procedures are not allowed. i.e A procedure cannot define another procedure from within itself. It can however, call other procedures already defined at the time of execution

• A procedure definition MUST appear before it is called using script.call or script.foreach

script.end_procedure

xxxxxxxxxx
script.end_procedure

• Close the definition of the procedure in question

script.call

xxxxxxxxxx
script.call {procedure_name}

• Execute the specified procedure (already defined at this point)

• All the variables (object handles and strings) defined at this point are available to the called procedure

• Procedures can call other procedures already defined at the time of execution

script.push

xxxxxxxxxx
script.push {token}+

• Add one or more tokens to a list of tokens that will be passed to every subsequent command

script.pop

xxxxxxxxxx
script.pop [{token}]

• Remove the specified token from the list of tokens that will be passed to every subsequent command

• If no token is specified, the entire list is cleared

script.required

xxxxxxxxxx
script.required {var_id}+

• Confirm that all of the specified var(s) have been defined before proceeding with the next command to avoid unexpected outcomes of the subsequent command execution(s)

• {var_id} represents name of one or more variables of type # (string variables) that can be referenced elsewhere in the script as ((var_id))

• This command will return an error if even one of the specified var(s) have not been defined. If this command is part of a script file, the execution of that script will be terminated

script.if

xxxxxxxxxx
script.if {condition} {cmd} {args}*

• Execute a command ONLY IF {condition} evaluated to TRUE

• {condition} can be one of the following:

  • {key} : TRUE if a string variable called {key} is defined and not empty

  • !{key} : TRUE if a string variable called {key} is NOT defined or is empty

  • {key}=={value} : TRUE if a string variable called {key} has been set to {value}

  • {key}!={value} : TRUE if a string variable called {key} does not exist or has a value other than {value}

  • {key}~={value} : TRUE if a string variable called {key} CONTAINS the string {value}

  • {key}~!{value} : TRUE if a string variable called {key} DOES NOT CONTAIN the string {value}

  • {key}@@{regex} : TRUE if a string variable called {key} matches a DOS-like regular expression {regex}

  • {key}@!{regex} : TRUE if a string variable called {key} DOES NOT MATCH a DOS-like regular expression {regex}

  • {key1}|{key2}...|{keyn} : TRUE if at least one of the {key1...n} are defined

  • {key1}&{key2}...&{keyn} : TRUE if all of the {key1...n} are defined

  • extension={name} : TRUE if the specified extension identified by {name} is loaded

• {cmd} {args}* is the command to be executed if the condition is TRUE along with it's arguments

script.set

xxxxxxxxxx
script.set {{key}={value}}+

• Define one or more string variables to be used in the script

• Once defined, a string variable can be referenced elsewhere in the script using (({key}))

script.setif

xxxxxxxxxx
script.setif {{key}={value}}+

• Define one or more string variable ONLY IF not defined already

• Once defined, a string variable can be referenced elsewhere in the script using (({key}))

script.ifset

xxxxxxxxxx
script.ifset {{key}={value}}+

• Assign a value to one or more string variable ONLY IF that variable already has a value

• Subsequently referencing that string variable elsewhere in the script using (({key})) will return the new value

script.substr

xxxxxxxxxx
script.substr 
  in={string} 
  &out={var_name} 
  old={sub_string_to_replace} 
  new={replacement_sub_string}

• Substitute all occurrence of {sub_string_to_replace} in an input string with {replacement_string}

• The modified string is then stored in a string variable called {var_name} and can be accessed in the subsequent command using (({var_name}))

script.tokenize

xxxxxxxxxx
script.tokenize
  in={string}
  &out={var_name}
  old={string_of_separators}
  new={char_separator}

• Separate the specified string into tokens based on a list of character separators represented by {string_of_separators} and compose a new string where those tokens are concatenated using a new separator {char_separator}

• The modified string is then stored in a string variable called {var_name} and can be accessed in the subsequent command using (({var_name}))

script.parse

xxxxxxxxxx
script.parse 
  str={string}
  format={...}
  &vars={id0}[,{id1}...{idn}]

• Parse a string represented by str={string} and based on the format spec. format={...}, set the variables specified by &vars={...}

• The format spec. uses %{index}% to reference the variable from the list of vars. E.g %0% references the very first variable in &var

• The parser will match {string} and {format} until a variable is referenced or if there is an error till either of the two end

• It will print a message (({var})) = {value} for every variable successfully captured

script.branch

xxxxxxxxxx
script.branch script={script_file_path} [{key}={value}]*

• Create a branch to another script as if executing a function defined in form of that script

• {script_file_path} is the path of another script file containing commands representing the branch

• {key}={value} are optional arguments that can be passed on to the branching script and are valid only for the duration of the branch execution

• Nested branches are allowed. A branch can invoke branching commands to another script(s). There is no limit on the number of levels

• Cyclic/recursive branching while possible is to be avoided as it may lead to infinite recursion (and therefore a stack overflow)

• Errors from branching scripts are treated as warnings. Aborts (exit) are ignored

script.capture

xxxxxxxxxx
script.capture &var={id} {program} {args}*

• Execute an application or command provided and capture the it's output to stdout

• &var={id} is name of a string variable where the std output of the command will be saved

• {program} is the appropriate application/command to execute

• {args} are one or more paramters to pass per the application/command's usage

• This is the same as the system command except it allows the capture of the output to a string variable rather than just logging it

• It's best used when the command being invoked is a utility that prints exactly the information to be captured

script.foreach

xxxxxxxxxx
script.foreach
  &token={var_name} 
  {loop={from},{to},{increment}} | {list={list_of_tokens} | file={token_file}}
  {branch={script_file_path} | call={procedure_name}}
  [sep={separator}] 
  [{key}={value}]*

• Execute a loop for each item in a list of items

• loop= creates a for loop starting with an integer {from} upto {to} with a step of {increment}. On each run, the specified token is assigned the value of the for iterator. If {increment} is positive, the test is {from} <= {to}. Otherwise, the test is {from} >= {to}

• Alternately list={list_of_tokens} creates a loop based on a string containing one or more tokens separated by separators. On each run, the specified token is assigned the current item from the list

• Alternately, file={token_file} creates a loop based on a list of items in a text file, one item per line. On each run, the specified token is assigned the item at the current line

• {separator} if used is a list of characters to be used as separators in the list. Default separator is , (comma)

• {var_name} represents the name of a string variable that will temporarily hold a token from the specified list. The value of this token will change as this command iterates through the specified list

• {script_file_path} is the path of another script file containing commands representing the branch to be executed for each token in the list (as if it's a function)

• {procedure_name} is name of a procedure that has already been defined at this point in the execution

• {key}={value} are optional arguments that can be passed on to the branching script and are valid only for the duration of the script.foreach command

• Nested branches are allowed. A branch can invoke branching commands to another script(s). There is no limit on the number of levels

• Nested procedure calls are not allowed

• Cyclic/recursive branching while possible is to be avoided as it may lead to infinite recursion (and therefore a stack overflow)

• Errors from branching scripts are treated as warnings. Aborts (exit) are ignored

script.convert

xxxxxxxxxx
script.convert
  from={spec} 
  to={spec} 
  values={list} 
  [&var={id}] 

• Convert a comma-separated list of values from one unit to another

• {spec} can be one of the following :-

  • m

  • cm

  • mm

  • um

  • nm

  • in

  • mils

  • dpi

  • dbu,{db_id}

  • uu,{db_id}

• For dpi conversions, the value to be converted is implied to be the pixel-size (or the dot-size)

• {db_id} is a variable of type QisMFile* representing the database in question. dbu is the database-unit and uu is the user-unit of that database

• values provides a comma-separated list of values in the source (from) units

• scale if specified multiplies the result with the specified value

• &var if specified will add a new string variable represented by {id} containing a comma-separated list of results

• E.g --

  • from=um to=dpi values=1 will result in 25400. I.e a pixel of size 1um is equivalent to 25400 dots-per-inch

  • from=mm to=um values=1,0.001 will result in 1000,1

  • For a UM db F with NM resolution (units = 1e-6 m and grid = 1e-9 m),

    • from=uu,F to=dpi values=1 will result in 25400 (1um = 25400dpi)

    • from=dpi to=dbu,F values=25400 will result in 1000 (25400dpi = 1000nm)

script.rename

xxxxxxxxxx
script.rename $old={old_id} type={type_name} $new={new_id}

• Move a script variable of name {old_id} and type {type_name} to a new name {new_id}

• The old id for the specified type will cease to exist from this point on

• The type remains the same

• CAUTION -- Any other dependent variables that were added alongside {old_id} such as {old_id}.{something} will continue to exist as is. Therefore, this command should be used sparingly and only when there is no other alternative solution

script.make_id

xxxxxxxxxx
script.make_id str={string} &id={id}

• Convert an arbitrary string {string} into another string {id} that is more suitable to be used as a script variable name

• Replaces most non-alphanumeric characters with an underscore or a hyphen

• Does not guarantee uniqeness. Two non-identical strings could potentially result in the same id

script.num_cpus

xxxxxxxxxx
script.num_cpus [&var={name}]

• Print the no. cpu(s) in the system

• If name is specified, the value is stored as a string variable by that name

script.phys_mem_size

xxxxxxxxxx
script.phys_mem_size [&var={name}]

• Print the amount of physical memory in the system (RAM)

• If name is specified, the value (mem. size in bytes) is stored as a string variable by that name

script.file_name

xxxxxxxxxx
script.file_name 
  path={file_path} 
  [&dir={var}] 
  [&name={var}] 
  [&ext={var}]
  [&basename={var}]
  [&full={var}]

• Get various components of a file at the specified {file_path}

  • &dir if specified, retrieves the directory

  • &name if specified, retrieves the file name (with extension)

  • &ext if specified, retreives the extension

  • &basename if specified, retreives the name (without extension)

  • &full if specified, get the absolute full path

script.file_size

xxxxxxxxxx
script.file_size 
  path={file_path} 

• Print file size

script.new_window_set

xxxxxxxxxx
script.new_window_set 
  &set={set_id}
  llur={name}:{lx},{ly},{ux},{uy}
  llwh={name}:{lx},{ly},{width},{height}
  cwh={name}:{cx},{cy},{width},{height}
  @llur={name}:{txt_file}
  @whll={name}:{txt_file}
  @whc={name}:{txt_file}
  tilerc={name}:{roi_lx},{roi_ly},{roi_ux},{roi_uy}:{cols},{rows}[:{i},{j}]*
  tilewh={name}:{roi_lx},{roi_ly},{roi_ux},{roi_uy}:{width},{height}[:{i},{j}]*
  cxy={name}:{width},{height}[:{cx},{cy}]+
  rand={name}:{roi_lx},{roi_ly},{roi_ux},{roi_uy}:{width},{height}:{count}
  [expand={uu}]
  [shuffle]

• Create a new set of rectangular windows

• Multiple arguments can be used for building a cumulative set

• All co-ordinates and dimensions are in file-units (e.g um, mm, inch) associated with the CAD source

• {set_id} represents name of the variable of type QisMBoxSet* associated with the newly created set

• The QisMBoxSet C++ interface can be found in qismbase.h

• {name} is a string identifier associated with a window which may be used to determine the name of the output file corresponding to that window

• {lx}, {ly}, {ux}, {uy} represent lower-left and upper-right co-ordinates

• {width}, {height} represent the window size

• {cx}, {cy} represents co-ordinates of the window center

• {txt_file} is the path to an existing text file which contains the following :-

  • for @llur= , each line contains {lx},{ly},{ux},{uy} representing one window

  • for @llwh= , the first line contains {width},{height} representing the window size and each subsequent lines contains {lx},{ly} representing the position of the window's lower-left corner

  • for @cwh= , the first line contains {width},{height} representing the window size and each subsequent lines contains {cx},{cy} representing the position of the window's center

• For generating tiles, {roi_lx},{roi_ly},{roi_ux},{roi_uy} represents the region of interest (ROI) to be tiled

• {cols},{rows} represents the number of tiles along X and Y respectively

• {width}, {height} represent the tile size

• {i},{j} is optional represents the position of one or more tiles to be added (1 <= i <= {cols} and 1 <= j <= {rows}). If used, all other tiles not in this list will be dropped

• For the random tile generator rand= , {count} represents the number of tiles to be generated at random locations within the ROI

• expand={uu} if specified, expands (enlarges or shrinks) each tile by the specified amount in user-units on each side

• If shuffle is specified, all the tiles will be randomly shuffled

• Every set created using this command MUST be eventually destroyed by the script using script.delete_window_set to avoid resource leaks

script.delete_window_set

xxxxxxxxxx
script.delete_window_set $set={set_id}

• Delete a rectangular window set created using script.new_window_set

• {set_id} represents name of the variable of type QisMBoxSet* associated with set to be destroyed

script.window_set_to_file

xxxxxxxxxx
script.window_set_to_file $set={set_id} path={file_path} [format={TXT | GDS | OAS}] [units={u_m},{g_m}] [id]

• Write the specified set of windows to a TEXT file

• {set_id} represents name of the variable of type QisMBoxSet* associated with set to be used

• {file_path} is the path of a file to be written

• format=TXT (default) writes a text file where each line of the text file represents one window from the set in the format {minx},{miny},{maxx},{maxy}

• format=GDS or format=OAS writes a GDSII or OASIS file with the boxes on layer 0:0. In that case, units={u_m},{g_m} specifies the units and grid in meters

• id if specified causes the position of the tiles to be written as well

script.window_set_to_string

xxxxxxxxxx
script.window_set_to_string
  $set={set_id}
  &out={var_name}
  sep={char}

• Create a string from the co-ordinates of the windows from the specified set of windows

• {set_id} represents name of the variable of type QisMBoxSet* associated with set to be used

• The new string is then stored in a string variable called {var_name} and can be accessed in the subsequent command using (({var_name}))

• The format of that string is {minx},{miny},{maxx},{maxy}[{char}{minx},{miny},{maxx},{maxy}]* where {char} is the new separator of windows

script.print_vars

xxxxxxxxxx
script.print_vars

• Print the complete list of script variables and their values available at this moment

• Each variable will be reported as {type}.{name} = {value}

• For variables that represent object handles, {value} is an address