ds
ds is the main Deriscope spreadsheet function.
It takes up to 30 optional arguments and has the following form:
=ds( [arg1], [arg2], ..., [arg30] )
Each input argument can - in principle - be anything: text, number, boolean or range.
Note, this function is best generated and pasted in the spreadsheet with the help of the Wizard, which ensures that the input arguments contain valid values.
Deriscope will attempt to parse the given arguments according to certain rules stated further below.
If it fails, it will return the handle name of an Error object that contains diagnostic information.
All input arguments must lead to a collection of Key-Value pairs that contain the data needed by the function to carry its task.
While there exist specific rules that govern the formatting constraints of the input arguments, the standard approach is to let the wizard generate the appropriate arguments for a chosen task and paste the complete function in the designated spreadsheet range.
The same applies to reading the message associated with the returned text label of an Error object.
Although there exists a spreadsheet formula that takes that text label as input and returns the associated message, the standard approach is to let the wizard present the message upon selection of the cell that contains the text label.
The first argument arg1 can play a special role as a switch flag that controls whether the function is executed or not.
If it is a boolean equal to TRUE, the function runs its course and returns the calculated result.
If it is a boolean equal to FALSE, the function simply returns the old data that happen to exist in the function's output range.
If it is a single value equalling either some text starting with the hash sign # or some number, the function returns that single value.
More seldom used, arg1 may also contain the special text *InputAsText* or *InputAsText_OuterTrimmed*, that instructs Deriscope to initially parse all input data as if they were pure text, with the second case also resulting in the trimming of all leading and trailing white spaces of these data.
Be careful to enter the special text exactly as it appears here, including the special prefix and suffix characters *
If arg1 is already used as a switch flag, then the second argument arg2 may carry the special text mentioned above.
The parsing rules are as follows:
The Key-Value pairs may be distributed in several input ranges.
In each input range, the keys should be either at its left column or top row and the corresponding values should be adjacent to them.
If a key is supplied alone in an argument, the corresponding value must be supplied in the next argument.
A value can be 1D-array or 2D-array or 3D-array
If a value is a 2D-array, it must occupy a single argument and its corresponding key must be the preceding argument.
If a value is a 3D-array, its constituent ranges must correspond to consecutive arguments and its corresponding key must be the preceding argument.
The 3 keys TYPE, OBJECT and FUNCTION are very important.
The key FUNCTION= is needed for supplying the name of the Deriscope Function
For example, the Key-Value pair FUNCTION= Create specifies the standard Deriscope function Create that is capable of creating new objects.
Similarly, the Key-Value pair FUNCTION= Fair Rate specifies a specialized Deriscope function named "Fair Rate" that is capable of calculating the rate that makes the NPV of a referenced contract to equal 0.
Both of these examples show that specifying the function alone is not sufficient.
The function Create is meaningless if not accompanied by the Deriscope Type of the object that needs to be created.
Similarly, the Fair Rate function is meaningless if not accompanied by the specific Deriscope Object for which the fair rate needs to be calculated.
The function Create is an example of a static function, which is how a function is designated if its operating context is specified through a supplied Deriscope Type
The Fair Rate function is an example of a local function, which is how a function is designated if its operating context is specified through a supplied Deriscope Object
The Deriscope Type or Deriscope Object - as applicable - is referred as the function's caller and must be always supplied, typically through the key TYPE= or OBJECT=, as applicable.
For a given caller and function, there are two shortcut rules that sidestep the need for providing the keys TYPE= or OBJECT=
Shortcut Rule 1: The first argument can contain the text: "caller::function"
For example: IRS::Create or MyIRS.1::FairRate, where MyIRS.1 is the handle name of an object of type IRS
Shortcut Rule 2: The first argument can contain the text: function and the second argument the text caller
For example, the comma separated two arguments could be: "Create" , "IRS" or "FairRate" , "MyIRS.1"
The Excel Deriscope Ribbon has a button named Syntax - shown below - that pastes in the spreadsheet several examples of the ds formula.
