@database VariablesAdvanced.guide
@remark ENGLISH VERSION
@author Eddie Churchill
@(c) "Copyright © 1993 Inovatronics, Inc."
@$VER: VariablesAdvanced.guide 2.5 (06/01/93)
@wordwrap
@font topaz.font 8
@index "CanDo_LexiconIndex"

@node "CanDo_Variables, Advanced_Index" "Variables, Advanced Commands, Functions and Variables"
@toc "CanDo_LexiconMain"
@{fg highlight}Available Topics...@{fg text}

  Function @{" =Alias()                       " link "CanDo_Alias"}
  Function @{" =BumpRevision()                " link "CanDo_BumpRevision"}
  Function @{" =Case()                        " link "CanDo_Case"}
  Function @{" =CharsToHex()                  " link "CanDo_CharsToHex"}
  Command  @{" DeleteArrayEntry               " link "CanDo_DeleteArrayEntry"}
  Function @{" =Evaluate()                    " link "CanDo_Evaluate"}
  Function @{" =EvaluateExpression()          " link "CanDo_EvaluateExpression"}
  Function @{" =FirstArrayIndex()             " link "CanDo_FirstArrayIndex"}
  Function @{" =FormatValue()                 " link "CanDo_FormatValue"}
  Variable @{" =GetDBObjects                  " link "CanDo_GetDBObjects"}
  Command  @{" Global                         " link "CanDo_Global"}
  Function @{" =HexToChars()                  " link "CanDo_HexToChars"}
  Function @{" =HexToInteger()                " link "CanDo_HexToInteger"}
  Function @{" =IfThen()                      " link "CanDo_IfThen"}
  Variable @{" =Infinity                      " link "CanDo_Infinity"}
  Function @{" =Input()                       " link "CanDo_Input"}
  Command  @{" InsertArrayEntry               " link "CanDo_InsertArrayEntry"}
  Command  @{" InsertRecordNames              " link "CanDo_InsertRecordNames"}
  Function @{" =IntegerToHex()                " link "CanDo_IntegerToHex"}
  Function @{" =IsAlias()                     " link "CanDo_IsAlias"}
  Function @{" =LastArrayIndex()              " link "CanDo_LastArrayIndex"}
  Function @{" =Limit()                       " link "CanDo_Limit"}
  Function @{" =LoadVariable()                " link "CanDo_LoadVariable"}
  Command  @{" Local                          " link "CanDo_Local"}
  Function @{" =Match()                       " link "CanDo_Match"}
  Function @{" =NextArrayIndex()              " link "CanDo_NextArrayIndex"}
  Variable @{" =NotANumber                    " link "CanDo_NotANumber"}
  Function @{" =NumberOfArrayEntries()        " link "CanDo_NumberOfArrayEntries"}
  Function @{" =PatternMatch()                " link "CanDo_PatternMatch"}
  Function @{" =PreviousArrayIndex()          " link "CanDo_PreviousArrayIndex"}
  Command  @{" SaveVariable                   " link "CanDo_SaveVariable"}
  Function @{" =SearchArray()                 " link "CanDo_SearchArray"}
  Command  @{" SetDBObjects                   " link "CanDo_SetDBObjects"}
  Command  @{" SetSearchArrayFlags            " link "CanDo_SetSearchArrayFlags"}
  Command  @{" SortArray                      " link "CanDo_SortArray"}
  Command  @{" Static                         " link "CanDo_Static"}
  Function @{" =ValidReal()                   " link "CanDo_ValidReal"}
  Function @{" =VarType()                     " link "CanDo_VarType"}
  Function @{" =VerifyExpression()            " link "CanDo_VerifyExpression"}

@endnode

@node "CanDo_alias" "<Variable>=Alias({String})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  <Variable>=Alias({String})

@{fg highlight}Description...@{fg text}

  Makes the resulting variable the same as the variable name given in the
{String}.  See the manual for a full description of this function.

  SEE ALSO: @{" IsAlias " link "CanDo_IsAlias"}.

@endnode

@node "CanDo_bumprevision" "Let {String}=BumpRevision({String})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {String}=BumpRevision({String})

@{fg highlight}Description...@{fg text}

  Changes the revision of {String} in the same manner as the Workbench
Duplicate function does with a filename.  See the manual for a full
description of this function.

@endnode

@node "CanDo_case" "Let {Result}=Case({Integer}, {Expression1} [,up to ten expressions] )"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Result}=Case({Integer}, {Expression1} [,up to ten expressions] )

@{fg highlight}Description...@{fg text}

  Returns the expression corresponding to the {Integer}.  For example:

   <- Let X = 2
   <- Echo Case(X,"Gold","Silver","Bronze")
   -> Silver

  SEE ALSO: @{" IfThen " link "CanDo_IfThen"} and @{" Match " link "CanDo_Match"}.

@endnode

@node "CanDo_charstohex" "Let {HexString}=CharsToHex({String})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {HexString}=CharsToHex({String})

@{fg highlight}Description...@{fg text}

  This converts a normal string into a hex- string.  The hexstring will
have twice as many characters as the given string.

   <- Echo CharsToHex("CanDo 1.6")
   -> 43616E446F2056312E36

  SEE ALSO: @{" HexToChars " link "CanDo_HexToChars"} and @{" FileWriteChars " link "CanDo_FileWriteChars"}.

@endnode

@node "CanDo_deletearrayentry" "DeleteArrayEntry <ArrayVar>, {ArrayIndex}"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  DeleteArrayEntry <ArrayVar>, {ArrayIndex}

@{fg highlight}Description...@{fg text}

  Deletes the array entry at the given index in the specified array
variable.  All indices greater than the specified index will be renumbered
starting at Index+1.
  
  SEE ALSO: @{" InsertArrayEntry " link "CanDo_InsertArrayEntry"} and @{" Dispose " link "CanDo_Dispose"}.

@endnode

@node "CanDo_evaluate" "Let {Result}=Evaluate({Expression})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Result}=Evaluate({Expression})

@{fg highlight}Description...@{fg text}

  SEE: @{" EvaluateExpression " link "CanDo_EvaluateExpression"}.

@endnode

@node "CanDo_evaluateexpression" "Let {Result}=EvaluateExpression({Expression})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Result}=EvaluateExpression({Expression})

@{fg highlight}Description...@{fg text}

  If the string contains a valid expression, this function returns its
result.  If the expression is not valid it will cause a run time error.
Use @{" VerifyExpression " link "CanDo_VerifyExpression"} first to avoid such problems.

@endnode

@node "CanDo_firstarrayindex" "Let {ArrayIndex}=FirstArrayIndex(<ArrayVar>)"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {ArrayIndex}=FirstArrayIndex(<ArrayVar>)

@{fg highlight}Description...@{fg text}

  Returns the integer value of the smallest index in the array specified by
VarName.  If the array does not have any entries, this function will return
the value 0 and the system variable @{" SearchFound " link "CanDo_SearchFound"} will be set to @{" False " link "CanDo_False"}.

  SEE ALSO: @{" LastArrayIndex " link "CanDo_LastArrayIndex"}.

@endnode

@node "CanDo_formatvalue" "Let {String}=FormatValue({Value}, {FormatString})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {String}=FormatValue({Value}, {FormatString})

@{fg highlight}Description...@{fg text}

  This will format {Value} using the {FormatString}, which describes how
you want the number to be represented.  See the manual for a full description
of this function.

@endnode

@node "CanDo_getdbobjects" "Let {RecordVar}=GetDBObjects"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {RecordVar}=GetDBObjects

@{fg highlight}Description...@{fg text}

  Returns a record variable containing a Record corresponding to the
matching qualifying Objects in the Current Card.  See the manual for a full
description of this system variable.

  SEE ALSO: @{" SetDBObjects " link "CanDo_SetDBObjects"}.

@endnode

@node "CanDo_global" "Global <VarName>"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Global <VarName>

@{fg highlight}Description...@{fg text}

  All variables are global by default, except those that are declared with
the @{" Local " link "CanDo_Local"} and @{" Static " link "CanDo_Static"} commands, but this command was made for
consistency.

@endnode

@node "CanDo_hextochars" "Let {String}=HexToChars({HexString})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {String}=HexToChars({HexString})

@{fg highlight}Description...@{fg text}

  This converts the result of @{" CharsToHex " link "CanDo_CharsToHex"} function or the @{" FileReadChars " link "CanDo_FileReadChars"}
command into a normal character string.

@endnode

@node "CanDo_hextointeger" "Let {Integer}=HexToInteger({HexString})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Integer}=HexToInteger({HexString})

@{fg highlight}Description...@{fg text}

  This converts the result of @{" IntegerToHex " link "CanDo_IntegerToHex"} function or the
@{" FileReadChars " link "CanDo_FileReadChars"} command into a normal integer.

@endnode

@node "CanDo_infinity" "Let {Real}=Infinity"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Real}=Infinity

@{fg highlight}Description...@{fg text}

  Returns the IEEE double precision value for Infinity.  See the manual for
a full description of this system variable.
  
  SEE ALSO: @{" NotANumber " link "CanDo_NotANumber"} and @{" ValidReal " link "CanDo_ValidReal"}.

@endnode

@node "CanDo_ifthen" "Let {Result}=IfThen({Logical}, {TrueExpression} [,{FalseExpression}])"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Result}=IfThen({Logical}, {TrueExpression} [,{FalseExpression}])

@{fg highlight}Description...@{fg text}

  This returns the {TrueExpression} if the {Logical} is @{" True " link "CanDo_True"}, otherwise
it returns the {FalseExpression} or @{" Nothing " link "CanDo_Nothing"} if the {False- Expression} is
not given.
  
  SEE ALSO: @{" Match " link "CanDo_Match"} and @{" Case " link "CanDo_Case"}.

@endnode

@node "CanDo_input" "Let {String}=Input({Prompt})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {String}=Input({Prompt})

@{fg highlight}Description...@{fg text}

  Similar to Input Function in BASIC.  It displays the "Prompt" in the CLI
and waits for user to type information ending in the RETURN key being
pressed.  This function returns the information typed by the user.  You
must have a CLI for this to work.

@endnode

@node "CanDo_insertarrayentry" "InsertArrayEntry <ArrayVar>, {ArrayIndex}"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  InsertArrayEntry <ArrayVar>, {ArrayIndex}

@{fg highlight}Description...@{fg text}

  Makes room for a new array index in the specified array.  This causes all
Array Indicies greater than the specified Index to be renumbered starting at
Index+1.  This is useful for adding records to a database.

  SEE ALSO: @{" DeleteArrayEntry " link "CanDo_DeleteArrayEntry"}.

@endnode

@node "CanDo_insertrecordnames" "InsertRecordNames <RecordVar>"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  InsertRecordNames <RecordVar>

@{fg highlight}Description...@{fg text}

  Types the record names for the specified RecordVar into the current
document.  This can be used to find out any unknown Record Names within the
variable specified.

@endnode

@node "CanDo_integertohex" "Let {HexString}=IntegerToHex({Integer})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {HexString}=IntegerToHex({Integer})

@{fg highlight}Description...@{fg text}

  This converts an integer into a hexstring.  The resulting string will be
two, four, six or eight characters long.

   <- Echo IntegerToHex(1256)
   -> 04E8

  SEE ALSO: @{" HexToInteger " link "CanDo_HexToInteger"} and @{" CharsToHex " link "CanDo_CharsToHex"}.

@endnode

@node "CanDo_isalias" "Let {Logical}=IsAlias(<VarName>)"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Logical}=IsAlias(<VarName>)

@{fg highlight}Description...@{fg text}

  This returns @{" True " link "CanDo_True"} if the variable indicated by <VarName> is an aliased
variable.
  
  SEE ALSO: @{" Alias " link "CanDo_Alias"}.

@endnode

@node "CanDo_lastarrayindex" "Let {ArrayIndex}=LastArrayIndex(<ArrayVar>)"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {ArrayIndex}=LastArrayIndex(<ArrayVar>)

@{fg highlight}Description...@{fg text}

  Returns the integer value of the largest index in the array specified by
VarName.  If the array does not have any entries, this function will return
the value 0 and the system variable @{" SearchFound " link "CanDo_SearchFound"} will be set to @{" False " link "CanDo_False"}.

  SEE ALSO: @{" FirstArrayIndex " link "CanDo_FirstArrayIndex"}.

@endnode

@node "CanDo_limit" "Let {Integer}=Limit({MinLimit}, {MaxLimit}, {TestInteger})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Integer}=Limit({MinLimit}, {MaxLimit}, {TestInteger})

@{fg highlight}Description...@{fg text}

  Returns the {TestInteger} if it is between {MinLimit} and {MaxLimit}.  If
{TestInteger} is greater than both limits, it will return the larger of the
limits.  If {TestInteger} is smaller than both limits, it will return the
smaller of the limits.

@endnode

@node "CanDo_loadvariable" "Let {Result}=LoadVariable({FilePath})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Result}=LoadVariable({FilePath})

@{fg highlight}Description...@{fg text}

  Returns the contents of the variable which was saved in the given file.
  
  SEE ALSO: @{" SaveVariable " link "CanDo_SaveVariable"}.

@endnode

@node "CanDo_local" "Local <VarName>"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Local <VarName>

@{fg highlight}Description...@{fg text}

  Declares a variable as available only to the currently running script.
  
  SEE ALSO: @{" Static " link "CanDo_Static"} and @{" Global " link "CanDo_Global"}.

@endnode

@node "CanDo_match" "Let {Integer}=Match({Integer or String}, {MatchingData1} [,up to ten matching datas])"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Integer}=Match({Integer or String}, {MatchingData1} [,up to ten matching datas])

@{fg highlight}Description...@{fg text}

  Returns an integer value indicating which {Integer or String} matches any
of the {MatchingData}s, or 0 if none do.  See the manual for a full
description of this function.

  SEE ALSO: @{" Case " link "CanDo_Case"} and @{" IfThen " link "CanDo_IfThen"}.

@endnode

@node "CanDo_nextarrayindex" "Let {ArrayIndex}=NextArrayIndex(<ArrayVar>, {ArrayIndex})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {ArrayIndex}=NextArrayIndex(<ArrayVar>, {ArrayIndex})

@{fg highlight}Description...@{fg text}

  Returns the next larger Index value greater than <Index> in the array
specified by VarName.  If there is not one, this function will return the
given Index and set the system variable @{" SearchFound " link "CanDo_SearchFound"} to @{" False " link "CanDo_False"}.

  SEE ALSO: @{" PreviousArrayIndex " link "CanDo_PreviousArrayIndex"}.

@endnode

@node "CanDo_notanumber" "Let {Real}=NotANumber"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Real}=NotANumber

@{fg highlight}Description...@{fg text}

  Contains the value returned by some floating point operations which have
undefined results.  See the manual for a full description of this system
variable.

  SEE ALSO: @{" Infinity " link "CanDo_Infinity"} and @{" ValidReal " link "CanDo_ValidReal"}.

@endnode

@node "CanDo_numberofarrayentries" "Let {Integer}=NumberOfArrayEntries(<ArrayVar>)"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Integer}=NumberOfArrayEntries(<ArrayVar>)

@{fg highlight}Description...@{fg text}

  Returns the number of entries in the specified array.

@endnode

@node "CanDo_patternmatch" "PatternMatch({string},{pattern})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {boolean} = PatternMatch({string},{pattern})

@{fg highlight}Description...@{fg text}

  This function tests if a string matches the given DOS pattern.  If it
does, the function returns TRUE, otherwise it returns FALSE.  See your
AmigaDOS manual for a descrition of Patterns.

@endnode

@node "CanDo_previousarrayindex" "Let {Integer}=PreviousArrayIndex(<ArrayVar>, {ArrayIndex})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Integer}=PreviousArrayIndex(<ArrayVar>, {ArrayIndex})

@{fg highlight}Description...@{fg text}

  Returns the next smaller Index value smaller than <Index> in the array
specified by VarName.  If there is not one, this function will return the
given Index and set the system variable @{" SearchFound " link "CanDo_SearchFound"} to @{" False " link "CanDo_False"}.

  SEE ALSO: @{" NextArrayIndex " link "CanDo_NextArrayIndex"}.

@endnode

@node "CanDo_savevariable" "SaveVariable <VarName>, {FilePath}"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  SaveVariable <VarName>, {FilePath}

@{fg highlight}Description...@{fg text}

  Saves the contents of Variable into the specified file.  If the variable
is an array or record, the entire array or record will be saved.
  
  SEE ALSO: @{" LoadVariable " link "CanDo_LoadVariable"}.

@endnode

@node "CanDo_searcharray" "Let {ArrayIndex}=SearchArray(<ArrayVar>, {DataToSearchFor} [,{KeyString} [,{StartAtIndex}]])"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {ArrayIndex}=SearchArray(<ArrayVar>, {DataToSearchFor} [,{KeyString} [,{StartAtIndex}]])

@{fg highlight}Description...@{fg text}

  Searches the given array for the given value.  The {KeyString} specifies
the record name or subarray index to search on.  The {StartAtIndex} may
also be specified.

  SEE ALSO: @{" SetSearchArrayFlags " link "CanDo_SetSearchArrayFlags"} and @{" SearchFound " link "CanDo_SearchFound"}.

@endnode

@node "CanDo_setdbobjects" "SetDBObjects <RecordVar>"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  SetDBObjects <RecordVar>

@{fg highlight}Description...@{fg text}

  Sets the DataBase qualifying objects in the window to the corresponding
record entries.
  
  SEE ALSO: @{" GetDBObjects " link "CanDo_GetDBObjects"}.

@endnode

@node "CanDo_setsearcharrayflags" "SetSearchArrayFlags <flags>"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  SetSearchArrayFlags <flags>

@{fg highlight}Description...@{fg text}

  This adjusts the searching parameters used by the @{" SearchArray " link "CanDo_SearchArray"} function.

@endnode

@node "CanDo_sortarray" "SortArray <ArrayVar>, <flags> [,{KeyString}]"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  SortArray <ArrayVar>, <flags> [,{KeyString}]

@{fg highlight}Description...@{fg text}

  Sorts the specified array variable.

@endnode

@node "CanDo_static" "Static <VarName>"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Static <VarName>

@{fg highlight}Description...@{fg text}

  This is like @{" Local " link "CanDo_Local"}, except static variables survive beyond the current
execution, which means that the next time thru this script the variable
will still contain the old value.

  SEE ALSO: @{" Global " link "CanDo_Global"}.

@endnode

@node "CanDo_validreal" "Let {Logical}=ValidReal({Real})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Logical}=ValidReal({Real})

@{fg highlight}Description...@{fg text}

  Returns @{" True " link "CanDo_True"} if the value is a valid non-infinite real number and is
not a NotANumber.  See the manual for a full description of this function.

  SEE ALSO: @{" NotANumber " link "CanDo_NotANumber"} and @{" Infinity " link "CanDo_Infinity"}.

@endnode

@node "CanDo_vartype" "Let {String}=VarType(<VarName>)"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {String}=VarType(<VarName>)

@{fg highlight}Description...@{fg text}

  Returns a string indicating the value type for a specified <VarName>.
This can be:  "String", "Integer", "Real", "Logical", "Nothing", "System",
"Array" or "Record".  NOTE:  @{" Alias " link "CanDo_Alias"} variables can only be discovered with
the @{" IsAlias " link "CanDo_IsAlias"} function.

@endnode

@node "CanDo_verifyexpression" "Let {Logical}=VerifyExpression({Expression})"
@toc "CanDo_Variables, Advanced_Index"
@{fg highlight}Command...@{fg text}

  Let {Logical}=VerifyExpression({Expression})

@{fg highlight}Description...@{fg text}

  Returns @{" True " link "CanDo_True"} if the string contains a valid expression, otherwise it
returns @{" False " link "CanDo_False"}.  This command should be used before using the
@{" EvaluateExpression " link "CanDo_EvaluateExpression"} function to avoid run time errors.

@endnode