CalcIt Commands

SET

All types of variables other that simple variables need the SET command to be defined. These are:

  • Array
  • Automation
  • File
  • Buffer
  • Class

All of them except Class variables can be redefined more than once in the same piece of CalcIt code using as many times as needed the SET command.

To define (or redefine) Array variables we can use the following syntax variations:

  • SET arr(ArrSize, ReservSpace) Defines or redefines an array variable of ArrSize initial size. Initial size can be zero. Additionally ReservSpace parameter configures the space will be reserved by the array in case more elements has to be added. See more at Fine tuning Dynamic arrays. Both parameters are optional.
  • SET arr=ArrExpr Initializes array arr with the contents of the array returned by array expression ArrExpr.
  • SET arr&=ArrExpr Copies the contents of the array returned by array expression ArrExpr at the end of array arr.

See more about array expressions.

See also INTERN, EXTERN

We can create array variables locally in local functions and also we are able to define array parameters (IN or IN/OUT) in local functions and UDF.

To define (or redefine) Automation variables we use the following syntax:

SET ao=OBJC(ProgID)

e.g.

SET ao=OBJECT('Excel.Application')

This command first tries to connect with an existing running instance of the requested server. If server application is not running then creates a new instance. All kinds of automation servers can be used, DLL, OCX etc.

We can use SET command to create "empty" automation variables as placeholders of intermediate objects returned by properties or methods.

SET tmpo=OBJC;

Using SET and keyword OBJV we can declare an automation variable and assign to it an object, coming from the property or method of another object or from another Automation variable:

SET tmpo=OBJV(obj.ActiveDocument.Words);

if the Automation variable is already declared then a simple assignment is enough to achieve the same task:

set tmp=OBJC;
tmp:=obj.ActiveDocument.Words;

As expected the SET command, any time is used, can create a new automation variable or redefine a previous defined to contain another object.

In case of imported (through DLL) functions that return automation pointers we can use OBJP keyword to create the automation variable:

SET ao=OBJECTPTR(aoptr);

where aoptr is a pointer to an automation object returned by an API routine.

We can create automation variables locally in local functions and also we are able to define automation parameters (IN or IN/OUT) in local functions and UDF.

See also EXTERN

To define (or redefine) File variables we use the following syntax:

SET f=FILE(FileName,ReadOnly,InitialSize)

  • FileName. The name of the file the variable will connect
  • ReadOnly. If true we cannot change the file. Optional. If omitted then ReadOnly=TRUE.
  • InitialSize. If the requested file doesn't exists and this is defined as a positive number above zero then a file of this size is created filled with zeroes. If the file exists this parameter has no effect. Optional. If omitted then zero is assumed.

We can create global File variables and also local in Local functions or properties. Parameters of this type for local functions and UDF can be declared as well only as IN/OUT (BY REFERENCE).  In this case the placement of & symbol is optional.

When the declaration of an uninitialized global File variable is needed the following syntax can be used:

SET f=FILE;

Read more about this feature at Using File Variables topic.

To define (or redefine) Form variables we use the following syntax:

SET f=FORM(LayoutID,FormID,CenterForm,Title,EventProc)

  • LayoutID. Here is passed a value returned by FORMDef command for the definition of the Form's layout.
  • FormID. Any numeric or alphanumeric value uniquely identifying the created Form instance
  • CenterForm. If it is true then the prLeft, prTop properties is ignored and the Form appears centered in the screen. Optional. If it is omitted then the form is not centered automatically.
  • Title. Optional. Title in the caption of the Form. If it is omitted then the title defined in FORDDef will be used.
  • EventProc. Optional. If it is omitted then a local routine with the name EventProc, with three IN parameters and one IN/OUT is searched in the code for event handling. If you choose a different Event handling routine for this Form instance there is no need to be implemented before SET statement. Can be placed in any part of your code.

We can create global and local (in local functions) variables of this type. Parameters of this type in local functions or UDF can be declared only as IN/OUT (BY REFERENCE).  In this case the placement of & symbol is optional.

If we need to create a forward declaration of a Form variable we use the following syntax:

SET f=FORM;

It is possible to create alias for a Form variable through its Form ID using FORMID command:

SET AliasVar=FORMID(100);

The above will create an alias (AliasVar) of any Form variable initialized in the same code with FormID=100. With this alias variable we can access the Form of the original variable in exactly the same way. This command is indented for use in the EventProc routine where can simplify code in some situations and also is the only way to access there Form variables declared as local variables in local functions.

Read more about this feature at Using Form variables topic.

To define or redefine Buffer variables we use the following syntax variations:

SET bf = BUFFER(BufDefID) ADDR(MemAdr) API(DLLName, ReturnedValueType=atINTEGER, WinAPICall=true) = ArrExpr

BufDefID is a value returned by a previous call in BUFDEF command and represents the structure definition of the defined or redefined Buffer variable.

SET bf = BUFDEF(FieldDefList) ADDR(MemAdr) API(DLLName, ReturnedValueType=atINTEGER, CDECL=false)USE(APIFunctionName) = ArrExpr

or alternatively:

SET bf = BUFDEF(FieldDefList) ADDR(MemAdr) CALLAT(CallAddr, ReturnedValueType=atINTEGER, CDECL=false) = ArrExpr

In this syntax a Buffer variable is defined or redefined the same time with its structure. See BUFDEF for the structure definition section of this syntax.

As we can see in the above two syntax variations there are three optional "extension" sections.

  • ADDR(MemAdr): Makes the Buffer variable to point at MemAdr where MemAdr is any valid memory address. We can get a memory address from any API call or using the "Address of" operator (&) to get the memory address of other Buffer variables or File variables. If ADDR is omitted then memory equal to the size of the structure used is allocated automatically to the Buffer variable. This memory is initialized with zeroes.
  • API(DLLName, ReturnedValueType, CDECL=false): This optional section is used when we want to import exported functions from a DLL. At DLLName is the file name of the DLL. 
    ReturnedValueType     is the type of the value returned by the exported function. Is Optional. If omitted then atINTEGER is assumed. Valid return types are atINTEGER, atBYTE, atSHORT, atWORD, atFLOAT, atPOINTER. In using this way to define API function calls the name of the Buffer variable is also important and must be the same as the one of the exporting function in the DLL. As it is obvious it is used to locate the function inside the DLL and obtain its 32 bit call address.
    CDECL     defines the calling conventions for the exported function. This parameter takes the values of true of false (C/C++ call or Windows API call). Is optional. If omitted then false is assumed (Windows API calling conventions). In Windows, the Window calling conventions are used for the most DLLs (from Microsoft or third party) and it is the recommended choice if you write your own DLLs to extend CalcIt.
  • USE(APIFunctionName). This optional extension keyword is used in cases when we want to use a diferent name for the Buffer variable than the one of the actual API function call. When the name of the function call is provided via the USE keyword, the name of the Buffer variable can be anything the user chooses.
  • CALLAT(CallAddr, ReturnedValueType, CDECL=false): This optional section is alternative of the API section. It is used in cases the address of an API routine is already obtained (for example is returned by an API function call). CallAddr parameter accepts the 32 bit address of the routine. The rest of the parameters have the same meaning as in case of API. In using this way to make an API function call the name of the Buffer variable is not important and can be anything the user chooses.
  • In the last optional section denoted by the symbol of equality we can supply an array expression to easily initialize the Buffer variable. If we supply the initialization part the fields of the variable are initialized sequentially. The first element in the array expression initializes the first field and so on. In case of array fields first all elements of the array must be initialized before we go to the next field.

We can create global Buffer variables and also local in Local functions or properties. Parameters (IN or IN/OUT) can be declared in local functions and UDF.

NOTE: If for any reason we want to make a forward declaration of a Buffer variable then the following syntax is available:

SET bf=BUFFER

Read more about this feature at Using Buffer Variables topic.

To define Class variables we use the following syntax:

SET NewClassVar=CLASS ClassName(...)

The above creates a new Class variable as a instance of the Class ClassName. When this command is issued the construction code of the Class ClassName is called. The Class ClassName is an element in the Classes List. The Class construction can have parameters.

Please note that by contrary on all other types of variables created using the SET command, Class variables cannot be redefined.

We can create global and local (in local functions) variables of this type. Parameters of this type in local functions or UDF can be declared only as IN/OUT (BY REFERENCE). In this case the placement of & symbol is optional.

NOTE: When a Class variable is declared locally in a local function then its destructor (if any) will be called automatically when the code execution leaves the function.

Read more about this feature at Using Classes and Class variables topic.

Go Back