This chapter lists functions built into the Open GENIE command language which don't fall directly under the other section headings but are likely to be fairly essential in writing any Open GENIE programs.
| Alias() | Allows the definition of aliases for command names and qualifiers |
| As_integer | Truncates an Open GENIE real number to an integer. |
| Called_as_function | Test if a procedure was called as a function, ie x = command(y) |
| Defined | Tests whether a variable has a defined value (not undefined). |
| Free | Deletes a variable or workspace field and frees the storage. |
| Inquire | Prompts the user for terminal input and reads back an input variable. |
| Interactive | Tests whether code is running as part of a procedure or not. |
| Is_a | Tests the type of an Open GENIE variable. |
| Now | Returns the current date and time as a string. |
| Read_terminal | Read a string back from the input terminal into a variable |
Allows the definition of aliases for command names and qualifiers
| ALIAS | [alias_name=String] [full_name=String] | Define one or more aliases for commands and qualifiers. |
example:
# Some aliases defined for the display command >> alias "d/e/m/l" "display/errors/markers/line" >> d/e/l # can have more than one alias defined for a command >> alias "showit/Ebars/stars/wigglything" "display/errors/markers/line" >> showit/e_bars/wigglything
Note: Open GENIE already defines some common aliases for commands (eg d/e for display/errors).
The Alias() command is provided as a convenience for the command line interface to Open GENIE. It allows any Open GENIE procedure to effectively take on another, usually shorter name. The same can be done for any qualifiers taken by the procedure. The command relies on matching up the names of the real command and qualifiers with the names you wish to alias them to. The procedure and number of qualifiers must match in the two strings and those in the second string must be a valid command and its qualifiers (or they will not work).
This command is so powerful that some care should be used when exercising it! Note that it is entirely possible to define aliases which swap or duplicate the meanings of procedures and qualifiers.
A more serious use for this command is when defining a custom procedure in place of a standard Open GENIE procedure. For example, say we wish to redefine the Spectrum() command to load up some custom two theta values. By aliasing the original Spectrum command as old_spectrum. We can write a new Spectrum() procedudure which first calls the old old_spectrum() procedure to get most of the data and then add our own code to fix the two theta values. To the user, there is no change to how the command works and they can still call Spectrum() but will get the modified version (Note that without aliasing the name, Open GENIE would think that we were writing Spectrum() as a recursive procedure).
Alias_name (String)
These are the new (fictitious) names for the command and its qualifiers. It is not necessary to specify all the qualifiers a command has, just the ones that you wish to abbreviate or alias. Any unspecified qualifiers from the original command will still work perfectly with the new command name.
full_name (String)
The exact command name and qualifiers which we wish to alias, keeping the order so that this list matches the aliasing parameters in number and position.
Truncates an Open GENIE real number to an integer.
| AS_INTEGER | var=Real | Convert to integer |
example:
# Convert 2.5 to an integer >> printn As_integer(2.5) 2
Note: Add 0.5 before truncating to get the nearest integer instead
A simple function to convert Open GENIE real numbers into integers. Note that Open GENIE loops work fine with Real numbers as loop counters so the most likely reason for converting to an integer is to index into an array or if exact precision arithmetic is required (a loop with real numbers may be subject to systematic floating point errors).
Var (Real)
An Open GENIE real value.
RESULT = (Integer)
An Open GENIE integer or undefined value if the number cannot be converted successfully. For example if the real number is larger than the representation available for the integer.
Test if a procedure was called as a function, ie x = command(y)
| CALLED_AS_FUNCTION | Test whether a procedure should alter its parameters |
example:
# Procedure which checks how it is called PROCEDURE double PARAMETERS w=workspace RESULT wres IF Called_as_function() # leave the parameter untouched wres = w wres.y = w.y * 2.0 ELSE # change the parameter w.y = w.y * 2.0 ENDIF ENDPROCEDURE
This procedure is very important for a language which allows procedures to be called either as functions returning results or as keyword commands where the paramters are affected. For example, with the Rebin() command, it may be called either as
w = rebin( s(1), ... )
where the last thing we would want to do is replace the value "s(1)" with the result of the rebinning. Alternatively we could type
Rebin w ...
where of course, we would expect to change the contents of workspace "w".
If this check is not made a sequence of functions could produce unexpected results, for example
>> x = bad_rebin(w, v.x) >> y = bad_rebin(w, v.x) >> printn (x=y) $FALSE
RESULT = (Boolean)
Returns $TRUE if the currently executing procedure was called as a function.
Tests whether a variable has a defined value (not undefined).
| DEFINED | var=Any | Returns $TRUE if var was defined |
example:
# Check for arithmetic undefined values >> x = 5.5 / 0.0 >> printn Defined(x) $FALSE
Note: Useful for testing the presence or absence of procedure parameters.
Tests an Open GENIE variable to see if its value is undefined. This may happen either as the result of an arithmetic expression which returns an undefined value or because a value has not yet been given to a variable. The results of procedures that terminate with an error are also generally set to undefined.
One of the major uses of this test is to check whether procedure parameters have been supplied by the user. Any parameters which have not been supplied will take an undefined value and can be checked and maybe supplied with a default value if required.
Var (Any)
Variable to test for being defined.
RESULT = (Boolean)
Returns $TRUE if the variable has a defined value.
Deletes a variable or workspace field and frees the storage.
| FREE | variable=String [subvariable=String] | Delete a variable |
| [/PROC] | Delete a procedure definition | |
| [/TYPE] | Delete a user defined workspace type |
example:
# Delete a workspace field "test" and then an array "arr" >> printn w Workspace [] ( test = 45.0 ) >> free "w" "test" Workspace [] ( ) >> free "arr"
This command is provided to allow the user a little more control over the disposal of memory used by large variables. If for example, a large data array is known to be unused it would normally be automatically removed from memory eventually by Open GENIE. To remove it explicitly may be useful, for example, if the user knows they are about to create another large array.
/Proc
Interpret the given string as procedure name.
/Type
Interpret the given string as user defined type name.
Variable (String)
A string giving the name of the item to be deleted - must be double quoted.
Subvariable (String)
For workspaces only, this parameter contains a string which is the name of the field to delete from the workspace.
Prompts the user for terminal input and reads back an input variable.
| INQUIRE | [aprompt=String] | Inquire information from the user interactively |
example:
# Read in a lower limit from the user
>> llimit = inquire("Enter lower limit")
Enter lower limit: 45.678
>> printn llimit
45.6779999999999
>> printn Is_a(llimit, "Real")
$TRUE
Note: To read a string without any conversions or prompting use Read_terminal()
This command reads input from the users terminal. It also supplies a prompt string to obtain input from the user. The Inquire() command attempts to read the input variable back into the correct type of Open GENIE internal variable. Currently, this is only the case for single Integer or Real values. Any unrecognized type is returned as a string.
Aprompt (String) [ default = " :" ]
A string which tells the user what information is required, a ":" is appended to the prompt.
RESULT = (Any)
Either a string or the value of the variable as a Real or Integer. If no input is given "" is returned.
Tests whether code is running as part of a procedure or not.
| INTERACTIVE() | Returns $TRUE if it is run within a procedure |
example:
# Only print date if this is code is running # outside of a procedure (in a .gcl file for example) IF Interactive() printn "Running as batch file at " Now() ENDIF
Note: Useful for code fragments which may be used in different ways
The Interactive() command checks to see which of two possible modes a piece of Open GENIE code is executing in.
RESULT = (Boolean)
Returns $TRUE if the command was run outside a procedure.
Tests the type of an Open GENIE variable.
| IS_A() | var=Any typestring=String | Checks to see what type an Open GENIE variable is |
example:
# Convert a real if necessary IF Is_a(x, "real") x = As_integer(x) ENDIF
Note: Important when using user defined workspace types.
The format of this command appears a little strange at first however it is designed to be easily used in the sort of programming situations where type checking is common, see the example above. It is possible to test a variable for being any Open GENIE predefined type or any user defined workspace type.
A generic type may also be checked for, for example
>> printn Is_a(y, "Array") $TRUE >> printn Is_a(y, "Realarray") $FALSE
Var (Any)
The variable to be checked
Typestring (String)
The name of the type being checked for.
RESULT = (Boolean)
Returns $TRUE if the variable was of the type specified.
Returns the current date and time as a string.
| NOW() | Returns date and time as a string | |
| NOW:SEC() | Returns integer number of seconds since the clock was last reset or rolled over to 0. |
example:
# Printin the date and time as a string >> printin Now() 11-Jul-97 8:47:50 # Printin the date and time in seconds >> printin Now:sec() 1425508
Note: Use Substring() and Locate() to select time or date individually
The Now() command returns out a simple time and date string. If time or date are required individually they can be chopped out of the string using the Substring() and Locate() commands to take the date before the space or the time after the space.
RESULT = (String or Integer)
Combined time and date string [default] or integer seconds.
Read a string back from the input terminal into a variable
| READ_TERMINAL() | Return a string typed in at the terminal |
example:
# Read a string
>> printn "(" read_terminal() ")"
abcd efg
(abcd efg)
>>
Note: To read numbers as well as strings you may wish to use the Inquire() command.
This command reads a string (terminated by a carriage return) from the terminal. A numeric string can be converted by using As_variable() on the string returned by Read_terminal(). This is the way the Inquire() command is written.
RESULT = (String)
The string read from the terminal, not including the return character which terminated the input.