Some tips for beginners about using Terminal scripts

Terminal scripts can be used to run pre-designed commands on the terminal, like a batch file.  You can write anything that can be executed on terminal, like for loop, if else and so on,  inside Terminal scripts. In this article, I will show you how to call Terminal scripts, how to use parameters in Terminal scripts and how to avoid session disconnected when running Terminal scripts. If you have any information about how to use Terminal scripts or you have any feedback, please feel free to leave a comment.

1. Running Terminal scripts in Cache or IRIS

If you are using Cache on Windows system, you can use the executable(cterm.exe). This executable can be found on <Your Cache installation path>\bin\There are many other executable programs in this folder that you can use to interact with Cache.

Example of using the command prompt(cmd) to call Terminal scripts:

C:\InterSystems\Cache\bin\cterm.exe /console=cn_iptcp:127.0.0.1[23] C:\TestScript.scr

C:\InterSystems\Cache\bin\cterm.exe is path of the executable. /console=cn_iptcp:127.0.0.1[23] means that the terminal's IP address is 127.0.0.1 and Telnet Port is 23. It uses TCP/IP protocol to connect. Information about IP address and Telnet Port can be found from Preferred Server -> Add/Edit…. C:\TestScript.scr is path of your Cache Terminal script.

Example of using PowerShell to call Terminal scripts:

cd C:\InterSystems\Cache\bin\

Start-Process -FilePath ".\cterm" –ArgumentList @("/console=cn_iptcp:127.0.0.1[23]", "C:\TestScript.scr")

If you are using IRIS on Windows system, you can use the executable(iristerm.exe). This executable can be found on <Your IRIS installation path>\bin\.There are many other executable programs in this folder that you can use to interact with IRIS.

Example of using the command prompt(cmd) to call Terminal scripts:

C:\InterSystems\ IRIS \bin\iristerm.exe /console=cn_iptcp:127.0.0.1[23] C:\TestScript.scr

Example of using PowerShell to call Terminal scripts:

cd C:\InterSystems\IRIS\bin\

Start-Process -FilePath ".\iristerm" –ArgumentList @("/console=cn_iptcp:127.0.0.1[23]", "C:\TestScript.scr")

If you are using Linux system, you can try to use the executable (csession.exe) to execute commands.

 

 2.Adding and using parameters in Terminal scripts

Suppose the executable(cterm.exe) can be found on C:\InterSystems\Cache\bin\. The script is on C:\TestScript.scr and we want to execute this script on our local server.

We can call this script by using this command:

Command prompt(cmd): C:\InterSystems\Cache\bin\cterm.exe /console=cn_iptcp:127.0.0.1[23] C:\TestScript.scr

PowerShell: Start-Process -FilePath ".\cterm" –ArgumentList @("/console=cn_iptcp:127.0.0.1[23]", "C:\TestScript.scr")

Here is an example of this Terminal script (How to write this script can be found in the references below):

 

case match: off



echo: off

wait for:Username

send: ADM<CR>

wait for:Password

send: XXX<CR>

title: Terminal Example

echo: on



logfile: C:\TermExample.log

pause:10



send: znspace "USER"<CR>

wait for:USER>



send: do ##class(ExampleClass).ExampleMethod("abc","bcd”,1)<CR>



send: Do ^ExampleRoutine<CR>

wait for: action:

send: Y<CR>

send: Y<CR>

pause: 50



send: <CR>

closelog

terminate

We also can use parameters to make this script more flexible. The function of command and script below is the same as that of the command and script above.

We can run script below by using this command:

Command prompt(cmd)C:\InterSystems\Cache\bin\cterm.exe /console=cn_iptcp:127.0.0.1[23] C:\TestScript.scr ADM XXX abc 1 Y

PowerShell: Start-Process -FilePath ".\cterm" –ArgumentList @("/console=cn_iptcp:127.0.0.1[23]", "C:\TestScript.scr ADM XXX abc 1 Y")

The script with parameters:

case match: off

echo: off

wait for:Username

send: <p1><CR>

wait for:Password

send: <p2><CR>

title: Terminal Example

echo: on



logfile: C:\TermExample.log

pause:10



send: znspace "USER"<CR>

wait for:USER>



send: do ##class(ExampleClass).ExampleMethod("<p3>","bcd”, <p4>)<CR>



send: Do ^ExampleRoutine<CR>

wait for: action:

send: <p5><CR>

send: Y<CR>

pause: 50



send: <CR>

closelog

terminate

By using parameters, you can run different commands separately without needing to create a lot of Terminal scripts. It can also help you avoid hardcoding some sensitive information.

 

3.Avoiding session disconnected when commands are running

Sometimes the terminal session is closed when commands are still running. 

One way to solve this problem is using switch namespace command, if you cannot decide these commands' output.

Example:

send: do ##class(ExampleClass).ExampleMethod("<p3>","bcd”, <p4>)<CR>



send: znspace "USER"<CR>

wait for:USER>



send: Do ^ExampleRoutine<CR>

wait for: action:

send: <p5><CR>

send: Y<CR>

pause: 50



send: znspace "USER"<CR>

wait for:USER>



send: <CR>

closelog

terminate

Terminal will wait  until command executed successful because there is another switch namespace command wait to be executed below.

Here is another solution for this problem. According to Luis Fernando's poster in Stack Overflow (link can be found in References), if  you can edit output of your commands that you want to run on terminal, you can solve problem by using command: wait for.

Example:

wait for:"final output of your last command"

 

References

Docs.intersystems.com. (2018). Using Terminal Scripts - Using the Terminal. [online] Available at: https://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY... [Accessed 23 Dec. 2018].

Docs.intersystems.com. (2018). Using the Terminal in Batch Mode - Using the Terminal. [online] Available at: https://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY... [Accessed 23 Dec. 2018].

Stack Overflow. (2018). How to prevent <session disconnected> errors while running Intersystems Caché terminal scripts?. [online] Available at: https://stackoverflow.com/questions/198493/how-to-prevent-session-discon... [Accessed 23 Dec. 2018].

 

  • + 4
  • 2
  • 362
  • 6

Comments

Hello Chao,

This was a very interesting article.  I wanted to know if you had any more examples or pointers in respects to using the following commands, ‘Test’, ‘If empty’, ‘On error’, ‘Goto’, ‘Subroutine’.  Every time I try to use the ‘Test’ and ‘If empty’ and the ‘On error’ and ‘Timer’ commands they never seem to work.  I have read the documentation provided by Intersys many times with no success.  Do you know if Intersys offers any courses or tutorials in creating terminal commands and scripts?  If anything a few more examples could do the trick.  Do you know what is the root language from which the cterm/IRISterm terminal is originally derived from?  I have been using terminal scripts for the Centricity Business IDX product

Thanks for your help,

Raul Munoz

Hi Raul,

I haven't used Test or If Empy, but I can help with the rest.  Here's a prototype example of subroutines:

wait for: and so it begins
subroutine: $ALPHA
subroutine: $BETA
notify: Success...
exit

$ALPHA:
wait for: some junk
send: some other junk
return

$BETA:
wait for: some other other junk
send: junk completion
return

Here's a working example that uses a timer, on error,  and goto statements to answer repeated OK? N=> prompts with Y.  When the questions stop the timer runs down and the script terminates.

$looper:

on error: $terminate
timer: 100
wait for: OK? N=>
goto $prompted
goto $terminate

$prompted:
timer: 0
send: Y<CR>
goto: $looper

$terminate:
Exit

The real key when working with scripts is to only expect them to do exactly as told.  I remind myself constantly that the scripting language is only minorly dynamic and that I cannot treat it as a programming language.

John

Pease consider using code formatting button to format large (multiline) code listings.

Dear Eduard, Thanks! It looks much better!