Editing Scanco User Instructions (section)

==DCL Programming Guide==
The OpenVMS systems allow for scripts to be written in a language called '''DCL (DIGITAL Command Language)'''. It was not designed to be more difficult than other scripting languages, but learning any new programming language comes with its learning curve.

*DCL has 243 commands, but most programs can be written with a base set of about 20 commands. The goal of this section is to provide a convenient reference for these commonly-used commands.

It is recommended to open a text editor, enter the whole series of commands, and then run them as a whole program. The terminal on OpenVMS is technically a DCL interpreter, so these commands could be typed in sequence into a terminal with the same result. Typing code interactively is helpful when testing a small code snippet in more detail.

===Your First DCL Script===
Ever since Kernighan and Ritchie wrote the book "The C Programming Language", it has been custom to start with a program that prints the text "Hello, world" to the screen. Open a text editor (for example "EVE") and enter the text below.
<pre>
$! My First DCL Script
$ mymessage = "Hello, world"
$ WRITE SYS$OUTPUT mymessage
$ EXIT
</pre>
Now save the file as HELLO1.COM, and run it using <pre>$ @HELLO1.COM</pre>

Several things are happening in the above program:
*'''Comment !''': The exclamation mark can appear anywhere on the line, and everything following the mark will be treated as a comment. 
*'''Variable''': "mymessage" variable is populated with the string "Hello, world", which can be used in the rest of the script. 
*'''Command''' "WRITE" send text to various places, in this case to "SYS$OUTPUT", that is to the standard output (i.e. screen). 
*'''EXIT''' command tells the DCL interpreter that the script is done and we should exit.
*Commands in DCL are '''NOT case sensitive''', so the command "write sys$output mymessage" would produce the exact same result, but by convention we write commands in all uppercase.

*'''Special Comment !!''' automatically prints the contents of the comment to the screen/logfile. It is useful when you want to know what part of the script you are in.

===Basic Arithmetic===
The DCL language supports several types of data in variables. In the "Hello, world" example above, we saw how to store a string in a variable. We could have stored an integer, that is a positive or negative whole number, in the variable, and done some basic math.
*Refer to [[Scanco_User_Instructions#Arithmetic_operations|'''Arithmetic Operations''']],  For example:
<pre>
$ i = 1
$ WRITE SYS$OUTPUT i+1
$ j = 3
$ k = j * (i + 1)
$ WRITE SYS$OUTPUT k
$ WRITE SYS$OUTPUT (k / 4)
$ WRITE SYS$OUTPUT 2 + 2 * 2
$ EXIT
will return:

2
6
1
6
</pre>
Two things are worth noting. 
*Because we are limited to integers, division of 6 / 4 needs to return an integer (1.5 is not an integer); the value is truncated, which means rounding is always done toward zero. 
*Order of operations is done in the "correct" order, and not left-to-right, so "2 + 2 * 2" is interpreted as "2 + (2 * 2)".

===Conditional Statements===
Sooner or later, you will want to run a program with some logic. The general syntax is:
<pre>
IF [condition]
THEN
  [do something]
ELSE
  [do something else]
ENDIF
</pre>
*The "ELSE" component is optional. 
*If you need a very simple if..then with only one command, it can be written on one line without the "ENDIF": 
<pre>
IF [condition] THEN [do something]
</pre>
*Refer to [[Scanco_User_Instructions#Numeric_comparisons|'''Numeric Comparisons''']], [[Scanco_User_Instructions#String_comparisons|'''String Comparisons''']] and [[Scanco_User_Instructions#Logical_expressions|'''	Logical Expressions''']] for all possible logical operators (very similar to Fortran).

===Loops===
Most programming languages have 3 kinds of loops: 
*Precondition Loops: Condition is tested at the beginning of the loop
*Postcondition Loops: Condition is tested after the loop has executed at least once
*Iterative Loops: A variable changes in a predetermined fashion each time the loop is called. 

DCL has none of these. Instead, it has the concept of a "label" and the "GOTO" command. A loop in DCL would look like this:
<pre>
$ i = 1
$loop1:
$   IF i .GE. 10 THEN GOTO exitloop1
$   WRITE SYS$OUTPUT i
$   i = i + 1
$   GOTO loop1
$exitloop1:
$ EXIT
</pre>
This program will print the numbers from 1 to 10 in sequence.

===Subroutines===
Most programming languages allow to define a set of commands that can be called from various parts of the program. 
*In DCL, the subroutine can be defined anywhere in the file (unlike C or Python, where the definition must precede the call).
<pre>
$ CALL mycustomsub Joe
$ CALL mycustomsub Mary
$ EXIT
$mycustomsub: SUBROUTINE
$ WRITE SYS$OUTPUT "Hello, ", P1, "!"
$ EXIT
$ ENDSUBROUTINE
</pre>

The first line calls a subroutine named "mycustomsub", which jumps execution to the 4th line. The parameters after the name of the function get copied over to local variables named "P1", "P2", "P3" etc. (in this example, only one parameter, but the maximum is 8) that are available to the subroutine. Note that the command "WRITE" accepts several arguments separated by commas, which get printed on one line. 
*The subroutine should be terminated with the command "EXIT" followed by "ENDSUBROUTINE".
*Note that the parameters get passed literally to the subroutine, that is the subroutine gets the text "Joe", and not the contents of a variable named "Joe". 
*To force symbol substitution, the parameter would need to be enclosed in single quotes.
<pre>
$ Joe = "Joe Smith"
$ Mary = "Mary Jane"
$ CALL mycustomsub 'Joe'
$ CALL mycustomsub 'Mary'
$ EXIT
$mycustomsub: SUBROUTINE
$ WRITE SYS$OUTPUT "Hello, ", P1, "!"
$ EXIT
$ ENDSUBROUTINE
</pre>

===Reading from files===
Sometimes you have a list of files (for example Micro-CT scans) that are to be processed in a certain way. The obvious way is to copy-paste the code several times, changing only the name of the file, but this is error-prone and inefficient. 
*A better way is to put the list of models into a text file, and then call a subroutine on each model file. For example:
<pre>
$ CLOSE/NOLOG foo
$ OPEN/READ foo DISK3:[MICROCT.PROJECTS.OWOC.COM]MYLIST.TXT
$read_loop:
$   READ/END=done foo myline
$   CALL process_me 'myline'
$   GOTO read_loop
$done:
$ CLOSE/NOLOG foo
$ EXIT
$process_me: SUBROUTINE
$ scriptname = DISK3:[MICROCT.PROJECTS.OWOC.COM]MYSCRIPT.COM
$ SUBMIT/NOPRINT/QUE=SYS$FAST/PARAM='P1' 'scriptname'
$ EXIT
$ ENDSUBROUTINE
</pre>
*The first line closes the file handle, in case it was left open in a previous script. 
*The second opens the file "MYLIST.TXT" for reading, and assigns the open file a handle named "foo". 
*A loop reads the file line-by-line, calling a subroutine with the contents of each line. 
*When the end of the file is reached, the file is closed and the script exits.


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]