#Till Process Module

Till Process Module is a system module, that is used for running executable programs (EP).

Module:

process

Properties:

path – full or relative path to the executable program (EP)
arg – scalar or list variable for EP argument(s) (scalar or list variable that is set on module construction and cannot be accessed by the module, but the variable itself can be set)
exitcode – EP returned exit code

Functions:

execute – execute EP (no returned value, program run continues)
run – run EP and get result (program waits until EP finished running and returned result)
stop – stop EP process

Program from reference “/process/single/process.single.till” that demonstrates how to construct the module:

! this program denmonstrates various ways of process module
! construcion

! process reconstruction is not mandatory, unless process
! was constructed with static parameters that are to be 
! changed


path '../bin/action.exe'

! construct process with static path
process '../bin/action.exe'

! reconstruct with different path (mandatory)
process '../bin/action2.exe'

! construct process with dynamic path
process path

! change path and reconstruct (not mandatory)
path '../bin/action2.exe'
process path

! creating process with one argument
process path 'argument'

! creating process with list of arguments
args 'arg1' 10 \t
process path args

! change arguments and reconstruct (not mandatory)
args ->->
args <- 'arg2'
args <- 11
args <- \f
process path args

! change path and arguments and reconstruct (not mandatory)
path '../bin/action2.exe'
data [ 'arg2', 11, \f ]
args data
process path args

Process module has two functions for executing processes “execute” and “run”. While they both execute the process, there are two differences between them: calling program run state and returning values.

Program from reference “/process/single/process.execute.single.till” that demonstrates how to use function “execute”:

! ATTENTION: This program uses a process that should be already 
!            created. Follow the instructions in file 'SETUP'.

! results will be at file 'action.result'

path '../bin/action.exe'

! construct process
process path
process.execute

! pause and run again
pause 1
process.execute

Function “execute” executes the process, and does not return value, while the calling program continues to run. This usually fits launch and forget scenarios, where there is no need for the program to wait for the process to complete its task, and there is no need to get results.

Program from reference “/process/single/process.run.single.till” that demonstrates how to use function “run”:

! ATTENTION: This program uses a process that should be already 
!            created. Follow the instructions in file 'SETUP'.

path '../bin/textinv.exe'
arg 'ABC'

! construct process
process path arg
result string.trim process.run
print result

! change argument
arg 'DEF'
result string.trim process.run
print result

! recreate module and use arguments list 'args'
args ['GHI']
process path args
result string.trim process.run
print result

! change arguments list 'args'
args ['JKL']
result string.trim process.run
print result

Function “run” blocks program run and executes the process. While some processes are running very fast, others take time to finish. Anyway, the program will wait for the process to complete.

Function “run” returns a result, that is the output of the process. It is up to the process developers whether to return a result, and if no result returned, then the returned result will be an empty string.

EPs exit with a numeric value called the “exit code”. If process ran successfully than its exit code is zero (by convention, unless set to another value). The exit code can be seen at property “exitcode”. Usually, the process run state messages order is synchronized with the exit code values.

In this example there is process “proc.till” with validity checks that exit with exit codes, and returned result:

OK 0
NOARG 1
EMPTYARG 2
NONNUMERIC 3

arg in 0

! existance check
null arg ? exit NOARG
! empty check
arg '' ? exit EMPTYARG
! numeric check
num number.of arg
null num ? exit NONNUMERIC

! argument ok, continue...

result 2 * num

out 'got: ' + arg
out 'result: ' + result

Create fast TEP “proc.exe”:

> till proc fx

and use in “proc.app.instances.till” (multi instances demo):

! ATTENTION: this program is for demonstrating the use of module
!            instances. more efficient way is to use static module
!            with dynamic argument (variable)


runresult ''
errmsgs 'OK' 'No Argument' 'Empty Argument' 'Non-Numeric'

proc_without_arg process 'proc'
runresult proc_without_arg.run
report 'proc_without_arg' proc_without_arg.exitcode

proc_with_empty_arg process 'proc' ''
runresult proc_with_empty_arg.run
report 'proc_with_empty_arg' proc_with_empty_arg.exitcode

proc_with_non_numeric_arg process 'proc' 'arg'
runresult proc_with_non_numeric_arg.run
report 'proc_with_non_numeric_arg' proc_with_non_numeric_arg.exitcode

proc_with_numeric_arg process 'proc' 10
runresult proc_with_numeric_arg.run
report 'proc_with_numeric_arg' proc_with_numeric_arg.exitcode


report instance _exitcode:
  ! process result text includes newline in the end
  ! use system function 'string.trim' to trim
  _runresult string.trim runresult

  m 'run: ' + instance + newline
  m ++ ' - result: <' + _runresult + '>' + newline
  m ++ ' - state: ' + errmsgs _exitcode
  print m + newline

run: proc_without_arg
 - result: <>
 - state: Non-Numeric

run: proc_with_empty_arg
 - result: <>
 - state: Empty Argument

run: proc_with_non_numeric_arg
 - result: <>
 - state: Non-Numeric

run: proc_with_numeric_arg
 - result: <got: 10
result: 20>
 - state: OK

Or “proc.app.till” (one instance):

runresult ''
errmsgs 'OK' 'No Argument' 'Empty Argument' 'Non-Numeric'

! for the process to work correctly with dynamic argument
! and without redeclaration, the argument 'arg' must be 
! declared and for every change, it must be changed
arg
proc process 'proc' arg

! report
instance ''

instance 'proc_without_arg'
run

instance 'proc_with_empty_arg'
run ''

instance 'proc_with_non_numeric_arg'
run 'arg'

instance 'proc_with_numeric_arg'
run 10


run _arg:
  arg _arg
  runresult proc.run
  report

report:
  ! process result text includes newline in the end
  ! use system function 'string.trim' to trim
  _runresult string.trim runresult

  m 'run: ' + instance + newline
  m ++ ' - result: <' + _runresult + '>' + newline
  m ++ ' - state: ' + errmsgs proc.exitcode
  print m + newline

And the static version “proc.app.static.till”:

runresult ''
errmsgs 'OK' 'No Argument' 'Empty Argument' 'Non-Numeric'

! for the process to work correctly with dynamic argument
! and without redeclaration, the argument 'arg' must be 
! declared and for every change, it must be changed
arg
process 'proc' arg

! report
instance ''


instance 'proc_without_arg'
run

instance 'proc_with_empty_arg'
run ''

instance 'proc_with_non_numeric_arg'
run 'arg'

instance 'proc_with_numeric_arg'
run 10


run _arg:
  arg _arg
  runresult process.run
  report

report:
  ! process result text includes newline in the end
  ! use system function 'string.trim' to trim
  _runresult string.trim runresult

  m 'run: ' + instance + newline
  m ++ ' - result: <' + _runresult + '>' + newline
  m ++ ' - state: ' + errmsgs process.exitcode
  print m + newline