INFORMIX SOFTWARE, INC., LENEXA, KS
                        Wingz Technical Support Bulletin Number 002
          
          
          Title:    User-defined Functions
          Date:     December 27, 1988
          
          Hyperscript,  the programming language behind Wingz,  can be 
          utilized in more ways than just automating procedural steps. 
          One  of  Hyperscript's  more powerful  capabilities  is  the 
          ability to create user-defined functions.  While Wingz makes 
          available over 140 worksheet functions, there is going to be 
          someone  who  will  want some function that Wingz  does  not 
          provide.   That  is  where user-defined functions will  come 
          into play.
          
          Following is an example of a user-defined function:
          
          FUNCTION circle(r)
          
          RETURN pi()*r^2
          
          END FUNCTION
          
          In the above example, r is an argument that is passed during 
          the  call to this particular function;  in this case,  it is 
          the radius of the circle in question.   The RETURN statement 
          passes  back  the  result of the expression to  the  calling 
          statement.
          
          Another example:
          
          FUNCTION rect(l,w)
          
          DEFINE area
          
          area = l*w
          RETURN area
          
          END FUNCTION
          
          In this example, a local variable has been defined using the 
          command DEFINE.   By being local,  we mean that the variable 
          will  exist  in  memory only for the life of  the  function.  
          When the function is called, a location in memory is created 
          for  the  variable.   When the function finishes  execution, 
          that  location  in memory is deallocated,  thus erasing  the 
          variable and its contents, making it impossible to reference 
          in  any  sheet or script.   This is quite the opposite of  a 
          global  variable  where,  once  a global variable  has  been 
          defined  and  initialized in a script,  then any  script  or 
          sheet can reference it (the exceptions are variables created 
          in dialog boxes).  
          
          To  use a function that you have defined,  it must first  be 
          loaded into the computer's memory.  This is done via the GET 
          SCRIPT  command.   GET SCRIPT loads the function into memory 
          and  makes  it available to be called by other  scripts  and 
          sheets.   RUN SCRIPT will not load nor execute and function. 
          (To   remove  a  loaded  script,   use  the  REMOVE   SCRIPT 
          "script_name" command entered from the entry bar.)
          
          Once  a  script has been loaded into memory,  you must  then 
          call the script.  This is accomplished in one of three ways:
          
          1)  If  the  function is to be used in a sheet to  return  a 
          value,  you  must  precede the call to the function with  an 
          equal sign ("=") and you must precede the function name with 
          the  name of the file it is defined in (the name of the file 
          you loaded into memory with the GET SCRIPT command) followed 
          by a colon.   For illustrative purposes,  suppose the circle 
          function  defined above was defined in a file called  FUNCS. 
          To  call  this function in a worksheet,  you would  use  the 
          following syntax:
          
          =FUNCS:circle(5)
          
          If  this equation was entered into a cell,  the result would 
          be 78.54.
          
          2)   To reference a function within a script and assign  its 
          return  to a variable is similar in syntax to referencing  a 
          function in a worksheet.  The syntax is as follows:
          
          DEFINE a
          a = FUNCS:circle(5)
          
          These  two  statements  will assign the value 78.54  to  the 
          variable "a" defined in the script.
          
          3)   Suppose  we have the following function defined in  the 
          same  file,  FUNCS,  to  format  a  selected  range  on  the 
          worksheet:
          
          FUNCTION fmt()
          
          TEXT FONT "Bookman"
          TEXT SIZE 14
          TEXT STYLE "BU"
          ALIGN CENTER
          
          END FUNCTION
          
          To call this function, you would use the CALL  command.  The 
          syntax for this is:
          
          CALL FUNCS:fmt()
          
          Calls  to  functions can be very useful in  customizing  the 
          Wingz  environment  and  in modularizing  your  applications 
          developed  with  Hyperscript.   If  you have  a  dialog  box 
          defined in a function,  then you can call it from a menuitem 
          you have added to the Wingz menubar.  This procedure is what 
          Wingz  uses to create the dialog boxes you currently see  in 
          Wingz.
          
          Wingz functions have the following limits:
          
          255 functions per script file
          255 local variables per function