NVSF Groningen - software

CIO
1. Variables
2. Expressions
3. Commands
- 3.1 Keywords
- 3.2 Arguments
4. Cio programs
- 4.1 Statements
- 4.2 Pre-processing
5. Declaration commands
6. Program Flow commands
7. Use of char variables as CIO programs. Commands LOAD and LGO
8. Debug commands: STEP, TRACE, Continue
9. Spectra
- 9.1 Memory resident spectra
- 9.2 Spectrum files
10. Survey of commands
11. Automatically assigned CIO variables
12 Examples of CIO scripts
- 12.1 dipfind
See also

CIO

CIO - a command language for interactive programs

1. Variables

1.1 Names

Names of variables consist of 1 to 8 alphanumeric characters. The first character must be a letter.

1.2 Types

The following types of variables are defined:

'i' = int : 32 bit integer

'f' = float : single precision float

'd' = double : double precision float

'c' = char : character

'v' = varlist: an element of type 'v' is the name of another variable.

'o' = overlap: an overlap variable is a subset of another variable.

1.3 Arrays

Variables consisting of more then one element are called arrays.

An array element, or subscripted variable, is written in the form:

    <name>[<subscript>]

where subscript is an integer expression.

Array elements are always numbered from 0 upwards.

1.4 Context

Variables are defined as being either permanent, global, or local. Local variables become undefined when the subprogram in which they were defined is left. Permanent and global variables keep there meaning troughout the program. The name permanent should not be taken too litterally, although it is slightly more difficult to delete a permanent variable than a global variable.

2. Expressions

Expressions are always evaluated in double precision mode. An integer expression is an expression whose result is (within a certain accuracy) equal to an integer.

An expression consists of elements (constants, variables, functions) joined by operators and by parentheses. An expression may contain space characters, but never tab characters or end-of-line.

2.1 Operators

Operators are:

a. arithmetic:

    +  -  *  /  **

b. relational:

    >  <  >=  <=  ==  !=

c. assignment :

    :=  +=  -=  *=  /=

2.2 Numbers

Numerical constants may consist of the following parts (in this order):

sign:

    +  -

0x:

    a leading 0x means the number is in hexadecimal

digits:

    0..9   ( if hexadecimal also  a..f  or  A..F )

fraction:

    decimal point ('.') followed by one or more digits

e or E:

    the letter e indicates floating point and must be followed by

exponent:

    integer number, may be preceded by a sign

    a terminating k multiplies the number by 1024

2.3 Functions

Functions consist of a function designator followed by an expression in parentheses, e.g. sin(45*pi/180). Function designators are:

    sin    cos    tan    asin    acos    atan    exp    ln    sqrt

2.4 Hierarchy of operations

All arithmetic and relational operators have equal priority.

The order of evaluation is from left to right.

Assignment operators have the lowest priority.

Parentheses ( ) may be used to determine the order of computation.

Example:

    the expression:   j:= a + b * c
    is equivalent to: j:= ( (a + b) * c ).

2.5 Further details

Relational expressions yield a value 0 (=false) or 1 (=true). However, any non-zero value is considered as 'true' when used as a condition. There are no special logical operators. The arithmetic '*' can serve as 'and' operator, the '+' as inclusive or.

3. Commands

Commands specify processes to be carried out.

A command consists of a keyword followed by zero or more arguments.

In the following, the delimiter <end of line> will be called EOL, and the delimiter ';' (semicolon) will be called EOK (end of command). Commands and arguments are usually prompted for by a short descriptive text. This prompt is omitted however if input is waiting to be processed.

Some of the options available to the user are:

a) One line per argument

    - input <keyword> EOL
      Now the prompt for the first argument (if any) will appear.
    - input <argument> EOL.
      Then the prompt for the next argument (if any) appears,
      and so on, until the input is complete.

b) Type ahead

    - input <keyword> <argument> <argument> ... EOL
      In this case the prompts are suppressed. However if further
      arguments than those given on this line are required,
      a prompt for the next argument will appear.
      As an alternative to EOL one may use EOK.  In that case it
      is possible to type several statements on one line.

c) Use default arguments

    - input <keyword> EOK
      In this case the prompts are also suppressed, and all
      arguments take default values. Or, if a default is not
      allowed, an error will be generated.

At any time an EOK is encountered remaining arguments of the current command take default values.

Some commands have a variable number of arguments, such as a list of items to be processed. For those commands often only one prompt is given and the list of arguments is terminated by an EOL.

3.1 Keywords

Keywords consist of alphanumeric characters, i.e. letters and digits.

The first character must be a letter.

No distinction is made between upper case letters and lower case letters. (This in contrast to names of variables!). Most keywords may be abbreviated by leaving out characters from the end. In descriptive texts (help files, documents) the required letters are indicated by upper case, and optional letters by lower case.

Example: If a keyword is described as PRint, then the keywords print prin pri and pr, are all equivalent, as well as variations such as Prin, where one or more of the letters are replaced by upper case letters. The list of valid keywords varies from program to program.

3.2 Arguments

The basic types of arguments are: 'word', 'line' and 'rawline'. From these types, other argument types are derived, such as 'integer', 'real', and 'variable descriptor'.

Commands may have a fixed or a variable number of arguments. The arguments may appear on the same line as the keyword, or on one or more new lines.

a) rawline arguments: A rawline argument consist of text, terminated by an end-of-line (EOL).
b) line arguments: In addition to EOL, also EOK (the character ';') terminates the argument.
c) word arguments: In addition to EOL and EOK also the characters ' ' (space) and ',' (comma) terminate the argument.
d) real arguments: A real argument is a word argument, as described in 3.2.3 above, that is subsequently evaluated as an expression, according to the syntax as described in expressions.
e) integer arguments: An integer argument is a real argument, that is subsequently rounded to the nearest integer. It is acceptable to use decimal points in an integer argument. Example: 1.5E6 (= 1500000)
f) variable descriptor arguments: A variable descriptor is a word argument, that is evaluated as the name and address of a variable. If this is a variable of type 'v' substitution takes place by the variable whose name is the value of the 'v' variable.

Example. Let Country be an array of type 'v', and Country[3] contains the name of an array, Greek. Then Country[3][17] is equivalent to Greek[17].
g) Further details: Since real and integer arguments are also word arguments they can not contain spaces, (unless quotes are being used, see pre-processing).

In special cases, other types of arguments than those listed above may be used (e.g. a line argument, interpreted as an expression).

4. CIO programs

4.1 Statements

A CIO program (also called CIO script) consists of a series of statements, where a statement is either a command, an expression statement, or a variable of type 'c'.

A command begins with a command keyword. An expression statement begins with the name of a numerical CIO variable.

Variables of type 'c' (char) may be used in a way very similar to commands. We will come back to this in use of char variables as CIO programs

Ambiguities between these different types of statements are resolved in the following way:

variables of type char always take precedence. Further, if a statement begins with a command keyword that is also the name of numerical CIO variable, it is an expression statement only if the variable name is followed by an assignment operator.

Statements are separated by the EOK symbol, or by the EOL symbol. The reverse is not always true. A command can span several lines, as explained. In special cases (rawline arguments) also the EOK symbol does not delimit a statement.

A statement may be preceded by one or more leading spaces.

4.2 Pre-processing

Statements and arguments of commands, with the exception of rawline arguments, are pre-processed, and special action is taken if the first character of the argument is one of the symbols listed below.

#: the remainder of the line is treated as comment.

$: In contrast with other special symbols, the $ may occur anywhere in the text, not necessarily as the first character of the argument. The symbol $ leads to action in the following cases:

a)

The $ is followed by the name of a variable of type 'c'. The $name is substituted by the contents of this variable.

b)

The $ is followed by the name of an environmental variable. Again, $name is substituted by the contents of this variable. Example: $HOME

c)

The $ is followed by a numerical expression surrounded by parentheses.

    Example $(atan(1)*4).

The expression is evaluated in double precision, and the result is substituted in formatted form. A format specifier may be given after the expression, before the ).

    Example: $(atan(1)*4,pi = %.12g)

All valid C control strings may be used, but only those specifying a 'double' conversion (%e, %f, %g) are meaningful.

To separate the control string from the expression, a ',' should be used.

': the text following the quote is taken verbatim and terminators space, comma and semicolon are ignored. This lasts until the next quote or the next EOL.

?: an argument is asked from stdin instead of the current input stream. The text following the ? is used as a prompt. This text should be enclosed in single quotes (') if it consists of more than one word.

&: The effect of this symbol, when given instead of an argument, is to force an error condition and cancel the current command.

5. Declaration commands

Declaration commands define the properties and size of variables, and allocate the storage required. They may also be used to assign initial values to variables.

For each of the types of variable described in types there is a declaration command.

5.1 Declaration of numerical variables

For the numerical types (int, float, double) the syntax of a declaration command is:

    <type> [<level>] <declaration> <declaration> ...

where <type> is the command (INT DOUBLE or FLOAT).
[<level>] is an optional argument, and may be one of the forms -p, -g, or -l:

    -p: declare permanent variables
    -g: declare global variables
    -l: declare local variables (default).

<declaration> may be of the following forms:

    a. <name>
    b. <name>=<expression>
    c. <name>[integer expression]

The last form may be used to declare an array. Each <declaration> is a word argument, thus <declaration>s within one command may be separated by commas or spaces. A declaration command is terminated by EOK or EOL.

example:

    int i, j=20; float -g x[j]; double -p pi=atan(1)*4

5.2 Declaration of char variables

The declaration command for variables of type 'c' may be of the forms:

    a. char [<level>] <name>
    b. char [<level>] <name>=<text>
    c. char [<level>] <name>[integer expression]
    d. char [<level>] <name>[integer expression]=<text>
    e. alias [<level>] <name> <text>
    f. alias [<level>] <name>[integer expression] <text>

The forms b to f define an array. The length of the array specified by form b or e is determined by the length of <text>.

Each declaration is a rawline argument, which implies that <text> may contain spaces, commas and semicolons, and is terminated by EOL. Only one char variable can be declared per CHAR command.

The command ALIAS is essentially the same as CHAR, with the difference that the '=' sign is not used.

[<level>] is an optional argument, with possible values -p,-g,-l, as in declaration of numerical variables.

An array of char is also automatically defined by the command LOad. The length of such an array is the length of the file loaded, and the name is derived from the file name.

5.3 The command 'var'. Declaration of variables of type 'v'

The command VAR serves to define variables of type 'v', ( i.e. arrays of variable names ), as well as to set values for members of such arrays.

a) var def

The declaration is of the form:

    var def [<level>] <varlist_name>[<integer expression>]

The size specification, [<integer expression>], should be omitted if the list has only one member.

[<level>] is an optional argument, with possible values -p,-g,-l, as in declaration of numerical variables.

b) var (m)set

To assign values to the members of a variable of type 'v' one may use:

    var set <varlist_name> (<name[i]>,i=0..size-1)
    or
    var mset <varlist_name> <first> <last> (<name[i]>,i=first..last)

In the first form ( var set ) all names of the varlist are set, while the second form sets or modifies a restricted number of names, as specified by the indices <first> and <last>.

The actual variable corresponding to <name[i]> may be declared either before or after 'var set' or 'var mset' is given.

c) var list

To obtain a survey of the current contents of a varlist one may use:

    var list <varlist_name>.

d) var wipe

An other options of the command var is

    var wipe <varlist_name>.

This should be used instead of the commands wipe (see deleting variables below), when the variable of type 'v' itself should be addressed, rather then a member of the list. Strictly speaking, this is only necessary if the varlist has a size of one.

5.4 Declaration of variables of type 'o'. The command 'ovar'

The command OVAR serves to define variables of type 'o', ( i.e. variables that overlap existing variables ). The declaration is of the form:

    ovar [<level>] <new_name> <original_name> <offset> <nelements>

The new variable <new_name> is of the the same type as the original variable <original_name>. Usually the original variable is an array, and the new variable is a subset of the original one. It starts at array element <offset> of the original variable, and has <nelements> elements.
[<level>] is an optional argument, with possible values -p,-g,-l, as in declaration of numerical variables.

5.6 Deleting variables

The command WIPE may be used to delete variables:

    WIPE {-l/-g/-P} varname ...

    If option -l is given, or no option, only local variables can be deleted.
    If option -g is given, also deletion of global variables is allowed.
    If option -P is given, even 'permanent' variables may be deleted.

For variables of type 'v' command VAR WIPE may be used.

5.6 Listing variables

The command LIST gives a survey of all currently defined variables. To see the contents of a numerical variable, on may use

    printx varname

To list the contents of an array of numerical variables, use command TYPE. This command also works for arrays of type 'c' (e.g. CIO programs).

For arrays of type 'v', command VAR LIST may be used.

6. Program Flow commands

Program Flow commands determine the sequence of operations.

6.1 The IF and ENDIF commands

The form of the IF command is

    if <condition>

The ENDIF command simply has the form

    endif

Every IF command should have a corresponding ENDIF command. The ENDIF defines the end of the range of the IF command.

The IF command evaluates the condition, and if the result is non-zero, or true, control is transferred to the command following the IF command. Otherwise, control is transferred to the statement following the corresponding ENDIF command.

<condition> may be a normal arithmetic expression, or a test condition. Test conditions test the existence or the type of variables, or compare two strings. They begin with one of the symbols '=' or '!', followed by some property. These properties may be abbreviated, e.g. ''-exist'' is equivalent to ''-e''. The possibilities are tabulated below.

test conditions:

    =exist <varname>; true if variable exists
    !exist <varname>; true is variable does not exist
    =d <varname>; true if variable exists and is of type double
    !d <varname>; true if variable does not exist or is not of type double
      similarly:  =i <varname>, !i <varname>, =f <varname>, !f <varname>,
                  =c <varname>, !c <varname>, =v <varname>, !v <varname>
    =str <string1> <string2>; true if strings are equal
    !str <string1> <string2>; true if strings differ.
      <string1> and <string2> can be of the form $<name>, with
      <name> a CIO variable or an environmental variable.

    example: if =s $HOST os90; mtr go m1 m2 m3; endif

6.2 The WHILE and ENDWHILE commands

The WHILE command is used to execute repeatedly a specified series of commands. The form of the WHILE command is

    while <condition>

The ENDWHILE command is the single word

    endwhile

Every WHILE command should have a corresponding ENDWHILE command. The ENDWHILE terminates the range of the WHILE command.

The WHILE command evaluates the condition, and if the result is non-zero, or true, control is transferred to the command following the WHILE command. When the ENDWHILE command is reached, the expression is evaluated again, and if true, control is again transferred to the command following the WHILE command. If the result is false, or 0, control is transferred to the statement following the ENDWHILE command.

<condition> may be a normal arithmetic expression, but also a test as for the IF command.

    Example:
    # calculate 10!
      int j;
      double fac;
      fac:=j:=1;
      while (j+=1) <= 10; fac*=j; endwhile
      print $(fac)

Note that in the above the statement fac*=j is executed 9 times, with j values of 2 .. 10, since j is incremented before the comparison with 10 is made.

Alternative ways to execute repeatedly a specified series of commands are provided by the commands 'repeat' and 'do'.

6.3 The REPEAT and ENDREP commands

The form of the REPEAT command is

    repeat <expression>

The ENDREP command is the single word

    endrep

Every REPEAT command should have a corresponding ENDREP command. The ENDREP terminates the range of the REPEAT command.

The REPEAT command evaluates the expression, and stores the result as an integer count. If this count is positive, control is transferred to the command following the REPEAT command. When the ENDREP command is reached, the count is decremented. If it is still positive, the process is repeated. If the count is 0, or negative, control is transferred to the statement following the ENDREP command.

    Example:
    # calculate 10!
      int j;
      double fac;
      fac:=j:=1;
      repeat 9; j+=1; fac*=j; endrep
      print $(fac)

6.4 The DO and ENDDO commands

The form of the DO command is

    do <index> <expression1> <expression2>

The ENDDO command is the single word

    enddo

The ENDDO command terminates the range of the DO command.

In the DO command, <index> should be an existing CIO variable of type int. The value of <expression1> is assigned to <index>. The difference, <expression2> - <expression1>, is stored as an integer count. If this count is positive, control is transferred to the command following the DO command. When the ENDDO command is reached, the count is decremented. If it is still positive, the <index> variable is incremented by 1, and the process is repeated. If the count is 0, or negative, control is transferred to the statement following the ENDDO command.

    Example:
    # calculate 10!
      int j;
      double fac;
      fac:=1;
      do j,2,10; fac*=j; enddo;
      print $(fac)

6.5 Nesting

Nesting of DO .. ENDDO, REPEAT .. ENDREP, WHILE .. ENDWHILE and IF .. ENDIF constructs is allowed. schematic example:

    if expr1; command1; if expr2; command2; endif; command3; endif

Here command1 and command3 will be executed if expr1 yields true; command2 is only executed if both expr1 and expr2 yield true.

6.6 The exit command

The EXIT command may be used to leave a CIO program and return to the next higher level. The same occurs automatically when the end of the program is encountered.

6.7 The error command

The ERROR command may be used to force an error condition, leave all CIO programs, and return to the interactive level. The form of this command is

    error <text>

where <text> is an arbitrary line of text, terminated by EOL or EOK. This text is printed to the terminal when the error occurs.

6.8 The SILENT command

The SILENT command has the forms:

    silent yes

    silent no

This command may be used to suppress console output, and is intended for long loops or iterations that contain commands (e.g. SUM) whose individual outputs are not interesting. 'silent yes' turns output off, and 'silent no' turns it back on.

Console output is also turned on when an error condition occurs.

7. Use of char variables as CIO programs. Commands LOAD and LGO

The program flow is also altered when a char variable is used as a statement. The contents of such a variable is then considered as a CIO program, which is entered when the statement is executed.

Instead of a char variable, a variable of type 'v' may also be used, provided:

- the variable name is preceded by the symbol $.

- the evaluation of the variable leads to a variable of type 'c'.

Whenever a CIO program is entered, the current input stream is temporarily replaced by the CIO program, and a new context is defined. Variables defined within this context automatically lose their meaning when the CIO program is left. It is possible to prevent this, by declaring them as as global or permanent.

A CIO program, declared by a command ALIAS, consists of only one line of text. Longer CIO programs may be read in from a file, with the command LOAD, which has the form:

    load [<filename>] [-s <subfile>] [-v <varname>] [-w]

<filename> is the name of a file, whose name is supposed to end in .pro

If option -v is not given the name of this variable will be the same as the filename, stripped of this extension, and also of directory names preceding the base name.

The command LGO (LOAD and GO) has the same effect, and in addition, starts the CIO program immediately after it is loaded.

Options recognized by LGO and LOAD include:

a) option -s <subfile>: read a specified subfile, instead of the whole file, into an array of 'c'. If option -v is not given the name of this variable will be the same as <subfile>. In the text a subfile starts after a header line ####<subfile> and is terminated by the next line beginning with ####.
b) option -v <varname>: Specify a name for the char variable. If this option is not given the name defaults to <filename> or <subfile>.
c) option -w: If a variable of the same name exists already, it is first deleted. Default for <filename> is the last file used by LGO or LOAD.

The commands LOAD and LGO look for the file <filename>.pro in the following directories:

a) The current directory
>b) $HOME/pro
c) $GROUP/pro
d) $PRO

Recursion and nesting of CIO programs is possible.

Example:

    # CIO program recurs
      print calculate factorial ( n! ) using recursion
    # The following line declares sub-program ff:
      char ff=if n>0; n-=1; ff; fac*=(n+=1); endif; if n==0; fac:=1; endif
      int n;
      double fac;
      n:= ?'input value for n:'
      ff;
      print fac($(n)) = $(fac,%.15g)

Example: Use of variables of type 'v' to substitute array names:

    print copy one array of numbers to another
    var def from,to; # define indirect variable names 'from' and 'to'
    int len,i;
    var set from  ?from:; # ask actual names for 'from' and 'to'
    var set to    ?to:;
    len:= ?length:;
    do i 0, len-1; to[i]:=from[i]; enddo;

Example: substitute array names by command 'input <char variable>':

    print copy one array of numbers to another
    char from[9];
    char to[9]; # define char variable names 'from' and 'to'
    int len,i;
    input from  ?from:; # ask user for actual names for 'from' and 'to'
    input to ?to:;
    len:= ?length:;
    do i 0, len-1; $to[i]:=$from[i]; enddo;

Example: Use of variables of type 'v' to form a switch.

    var def -g v[2]
    var set v cmd0 cmd1
    char -g cmd0= ......
    char -g cmd1= ......
    # Now, statement $v[0] is equivalent with cmd0, and $v[1] = cmd1.
    # A switch may be formed by using $v[<integer expression>].

8. Debug commands: STEP, TRACE, Continue

The commands STEP and TRACE have the forms:

    step yes
    step no
    trace yes
    trace no

When STEP is enabled (after command 'step yes', or, 'step;'), the execution of a CIO program is interrupted after every command. It may be continued by the command Continue. Before typing continue, the user may give commands to inspect the current values of variables, but not commands that modify internal stacks, such as declaration of variables.

When TRACE is enabled (after command 'trace yes', or, 'trace;'), every line of a CIO program is printed before it is interpreted and executed. This allows the user to follow the course of the program.

9. Spectra

9.1 Memory resident spectra

A spectrum is a numerical array of data, together with some associated information. The spectrum structure contains:

- The spectrum name

- An numerical array of type 'f', or sometimes 'i', with the same name - A label record.

The label record is a structure, containing descriptive information, in the form of integer and single precision float numbers, and an array of char (notes[128]).

Spectra are often used to store measured data, hence the name. In a CIO program a spectrum (or rather the array with the same name), may be used wherever a numerical variable is required.

To define a spectrum, the command DEFsp is available, with the form:

    defsp {-i/-e} <name>[<size>]

The square brackets around the integer expression <size> may be omitted, and several declarations of either form may be given in one DEFsp command.

Example:

    defsp Jan[4k], Piet 1000

In contrast with basic CIO variables, no special action is required when a spectrum, defined in a sub-program, should be used in the calling program. When a spectrum is defined, the associated numerical array is automatically declared as a permanent variable.

A spectrum may be deleted from memory by the command UNDEF. Do not use the command WIPE for this purpose, since it will only delete the numerical array, not the whole structure.

Options may be given before the first declaration of a defsp command, and pertain to all following declarations of that command.

option -i

The numerical array should be of type int, and not of the default type float.
option -e

The numerical array exists already. An error message is given if it does not exist, or has the wrong type or length. If a correct array is found, it is promoted to a permanent variable.

The list of currently defined spectra is obtained with the command SPList, while the contents of a label record may be inspected using command PLAB.

9.2 Spectrum files

Spectra may be stored in disk files with a special format. For each spectrum the file contains the label record, followed by the data in a compressed form. Several spectra may be stored on one file, in sequential order.

Each spectrum in a file is associated with a sequence number. This sequence number is sufficient to identify the spectrum on retrieval.

The input and output of spectra may be accomplished with the commands GET and PUT, and the command LABlst may be used to list information from the label records of a spectrum file. These commands require that the file be previously opened, and associated with a 'logical unit number', or LU. This may be done with command Open. This command can also be used to create and initialize a spectrum file.

10. Survey of commands

The following commands are available through the CIO library. In an actual program not necessarily all of these commands are included, while on the other hand, the program is likely to have some special purpose commands, not listed below. The right column lists the keyword and arguments.

 a. Program Flow
 ===============
 IF               IF condition
 ENDIF            ENDIF
 WHile            WHILE condition
 ENDWhile         ENDWHILE
 REPeat           REPEAT count
 ENDRep           ENDREP
 DO               DO index first last
 ENDDo            ENDDO
 EXIT             EXIT
 ERROR            ERROR text
 STEP             STEP {Yes/No}
 TRace            TRACE {Yes/No}
 Continue         CONTINUE
 b. Variables
 ============
 INT              INT    {varname/varname[size]/varname=expression} ...
 DOUBLE           DOUBLE {varname/varname[size]/varname=expression} ...
 FLOAT            FLOAT  {varname/varname[size]/varname=expression} ...
 CHAR             CHAR   {varname/varname[size]/varname=text} ...
 VAR              VAR DEF varlist_name[size]
                  VAR SET varlist_name varname ...
                  VAR MSET varlist_name first last varname varname ...
                  VAR LIST varlist_name
                  VAR WIPE varlist_name
 OVAR             OVAR new_name original_name offset nelements
 LGO              LGO  [file] [-s subfile] [-v <varname>] [-w]
 LOad             LOAD [file] [-s subfile] [-v <varname>] [-w]
 LIst             LIST
 WIPE             WIPE {-g/-l/-P} varname ...
 c. File Manipulation
 ====================
                  ( lu = integer expression
                  file = char expression, word )
 Open             OPEN lu file {Read/Write} {Ascii/Spectrum/PE}
 CLose            CLOSE lu
 REWind           REWIND lu.
 CDir             CDIR directory
                  change current directory.
 DIR              DIR [options] filenames
 DLU              DLU
 d.1 Binary Spectrum File Input and Output
 =========================================
 Get              GET spectrum seqnr lu
 PUT              PUT spectrum lu factor notes
 LABlst           LABLST lu first nspectra {Short/Full}
                  ( spectrum = char expression
                  seqnr = integer expression
                  lu = integer expression
                  factor = double expression
                  notes = char expression, line )
 d.2 Ascii File Input and Output
 =========================================
 Xport            XPORT lu {Yes/No} nspectra spectrum_name(s)
                  first_channel last_channel
                  Note. {Yes/No} refers to 'Use channel nrs as x-coord'
                  If 'Y' nspectra spectrum_names are asked
                  If 'N' nspectra+1 spectrum_names are
                  asked, the first one is the X spectrum.
 IMPort           IMPORT lu nspectra X_spectrum_name Y_spectrum_name(s)
 RDAS             RDAS lu Nspectra Nchannels sp_name ...
                  RDAS lu 0
                  RDAS lu -1 search_string
                  The first form reads an Ascii coded file, and decodes
                  it as numerical data.
                  The second form just reads one line of text.
                  The third form skips to a line starting with the
                  specified search_string.
 FPRint           FPRINT LU_nr line
 e. Spectrum Manipulation
 ========================
 DEFsp            DEFSP spectrum_name length
 UNDefsp          UNDEF spectrum_name
 PLAB             PLAB  specrum_name
 LABGET           LABGET spectrum_name label_field varname
                  copy parameters of a spectrum label to CIO variables.
 LABSET           LABSET spectrum_name label_field varname
                  copy parameters from CIO variables to a spectrum label.
 SPList           SPLIST
 f. Array Manipulation
 =====================
 RESet            RESET varname ...
 SUM              SUM varname first last
                  Note. The result is stored in local variable spsum
 INC              INC varname first last increment
 MINmax           MINMAX varname first last
 NORM             NORM varname first last normalize_to
 TRUNC            TRUNC varname first last min max
 MULR             MULR varname first last factor
 INPut            INPUT varname first last expression ...
                  INPUT varname text
                  Note. the last form applies if variable is of type CHAR
 TYPe             TYPE varname first last {Y/N}
                  Note. {Y/N} refers to 'suppress channel numbers'.
                  Note. If variable is of type CHAR the arguments 'first
                        last {Y/N}' are not needed and not used.
 ZERO             ZERO varname first last {+/-/Both}
                  Note. The result is stored in local variable spzero

 MULT             A B factor     (B:= factor * A)
 VLG              A B            (B:= log10(A))
 VLN              A B            (B:= ln(A) )
 VSQRT            A B            (B:= sqrt(A) )
 DIFF             A B nsmooth    (B:= deriv. A)
 INTEG            A B            (B:= integral A)

 ADD              A B C          (C:= A + B)
 ADDF             A B C factor   (C:= A + factor*B)
 SUB              A B C          (C:= A - B)
 MULS             A B C          (C:= A * B)
 DIVS             A B C          (C:= A / B)

 CTR              CTR varname a b c d e f
 MOve             MOVE A B n m l  (B[m+k]:=A[n+k], k=0,l-1)
 SHift            SHIFT A B oldch1 newch1 oldch2 newch2
                  Move with shift and stretching or compression
 g. Evaluation of expressions
 ============================
 Kalk             KALK expression
 EVal             EVAL expression
 PRINTX           PRINTX expression
 h. Formatted Output
 ===================
 PRint            PRINT line
 SPRint           SPRINT varname line
 FPRint           FPRINT LU_nr line
                  With the use of the $(expression,format) option, these
                  commands may be used to output formatted text to the
                  console, a 'c' variable, and an Ascii file.
 i. Graphics
 ===========
 GRint            GRINT option(s) (set parameters for display)
 DISplay          DISPLAY spectrum_name first_ch last_ch [options]
 DIX              DIX spectrum_name [options]
                  'options' in the above apply to choice and size of
                  symbols, style of graph, letter fonts, extra texts,
                  etc.
 CURsor           CURSOR
                  Starts a graphics cursor, whose position is read when
                  a keyboard key or mouse button is hit.
                  keyboard 'm' or middle button: set left border
                  keyboard 'l' or right  button: set right border and
                  redisplay region between left and right border.
                  keyboard 's': stop Graphics Cursor Input (GIN) mode.
 PLOT             PLOT
 GEPPOst          GEPPOST PostScript_file
 j. Miscellaneous commands
 =========================
 CLEAR            CLEAR
 History          HISTORY file_name
                  If file_name is is given, the history is written to
                  the file.
                  This may be useful when composing a CIO program.
 HELp             HELP command
                  HELP *
 LOG              LOG {OFF/ON} [file_name] (log session)
 EDit             EDIT filename  (using vi or $EDITOR)
 MORE             MORE filename  (using pg or $LIST)

 TIMe             TIME [variable] (print time, optionally store)
 SYS              SYS unix_command  (executes one system command)
 SHell            SHELL             (forks a shell)
 SILENT           SILENT {Yes/No}
 SLEEP            SLEEP seconds
 STOP             STOP

11. Automatically assigned CIO variables

Some commands automatically assign CIO variables. The following table gives some examples:

 Name         type  comment
 ==========================
 ctrsum         d   command CTR
 ctrbackg       d
 ctrcentr       d
 ctrwidth       d
 Gontheta       d   command GON
 Gonphi         d
 spsum          d   commands SUM, MINMAX, NORM
 spzero         d   command ZERO
 spvalmin       d   command MINMAX
 spvalmax       d
 spchmin        d
 spchmax        d
 dmierror       d   command DMI
 adctime[8]     d   command DMI
 RVARS[16]      d   comands MTR go, MTR inq

12 Examples of CIO scripts

(See also the examples in the text above)

12.1 dipfind

This program determines the position of a dip in an angular scan, by first differentiating, and subsequently locating a zero crossing. This and other applications may be found in directory ~peter/pro/.

 # prior to calling this program the following commands should be given:
 # > var def scan[3]
 # > var set scan <list of spectra containing an angular scan>
 # The following variables must exist and be set:
 #   venster, firstch, nch     scan[venster][firstch,firstch+nch-1]
 #                             is region to be analysed
 # The following variables are optional:
 #   dipmaxdv                  Input, maximum allowed deviation
 #   firstm1, firstm2, firstm3 Input, motor pos corresponding to firstch
 #   incm1, incm2, incm3       Input, increment of motors per  ch
 # The following variables are set by this program:
 #   dipch                     Output, ch nr of dip
 #   dipm1, dipm2, dipm3       Output, motor pos of dip

 if !exist nch; error : nch not defined ; endif;
 if !exist firstch; error : firstch not defined ; endif;
 if !exist venster; error : venster not defined ; endif;
 float d0[nch+6], d1[nch+6]; double chzero, devch; int i;

 # transfer the spectrum and add some channels left and right
 do i,0,nch-1; d0[i+3]:= scan[venster][i+firstch]; enddo
 do i,0,2; d0[i]:=d0[3]; d0[i+nch+3]:=d0[nch+2]; enddo

 # differentiate
 diff d0 d1 3;

 # find zero crossing, close to the minimum
 minmax d0 3 nch+2; zero d1 spchmin-3 spchmin+3 +; chzero:= spzero-3;
 if !d dipch; double -g dipch; endif
 dipch:= chzero+firstch; print dip found at ch $(dipch);
 dis scan[venster] firstch firstch+nch-1;
 grint line dipch 0 dipch spvalmax;

 # check deviation from wanted value
 if =exist dipmaxdv;
   devch:= chzero - (0.5*nch)
   if (devch**2) > (dipmaxdv**2); error !!!!! dip too far off; endif;
 endif;

 # determine motor positions for the dip
 if =exist firstm1;
  if !exist dipm1; double -g dipm1,dipm2,dipm3; endif
  dipm1:= chzero*incm1 + firstm1;
  dipm2:= chzero*incm2 + firstm2;
  dipm3:= chzero*incm3 + firstm3;
  print dip found at ch $(dipch), mp= $(dipm1), $(dipm2), $(dipm3);
 endif

CIO command language

CIO