SCRIPTING: Programming: Intermediate (Variables, Writing Subroutines, Writing Functions) [22905]

Intermediate Programming methods include the use of variables, writing subroutines, and writing functions. Understanding basic programming will be useful when applying intermediate methods. The following articles contain intermediate level information on programming in E-Basic:

 

Programming: Intermediate

More on Variables
Rather than overwhelm the beginning programmer, the information presented in this section is by stages of complexity. Intermediate programmers will need to use variables on a frequent basis. The following section details more information on declaration and utilization of variables.

 

NOTE: These examples are designed to illustrate the syntax of E-Basic variable declarations only, and are not intended to be implemented and generated.

 

DataTypes
When using the Dim statement to declare a variable, more information is required than just the name. The type of data the variable can hold must be specified. The script below not only reserves the word “participant_dob” as a variable, it also indicates that the variable is to hold a date (i.e., the participant’s date of birth).

 

Dim participant_dob As Date

 

There are a variety of data types available within E-Basic. The following table illustrates the type and an explanation of the type:

 

Data Type	Description
Boolean	True (-1) or False (0) value
Integer	Whole number ranging from –32767 to 32767
Long	Whole number ranging from –2,147,483,648 to 2,147,483,647
Single	Used to declare variables capable of holding real numbers with up to seven digits of precision:   • Negative: -3.402823E38 to -1.401298E-45   • Positive: 1.401298E-45 to 3.402823E38
Double	Used to declare variables capable of holding real numbers with 15–16 digits of precision:   • Negative: –1.797693134862315E308 to –4.94066E-324   • Positive: 4.94066E-324 to 1.797693134862315E308
Currency	Used to declare variables capable of holding fixed-point numbers with 15 digits to the left of the decimal point and 4 digits to the right (-922,337,203,685,477.5808 to 922,337,203,685,477.5807)
Date	Used to hold date and time values
Object	Used to declare variables that reference objects within an application using OLE Automation
String	Used to hold sequences of characters, each character having a value between 0 and 255. Strings can be any length up to a maximum length of 32767 characters.
Variant	Used to declare variables that can hold one of many different types of data. Refer to the Variant data type topic in the E-Prime Command Reference.
User-Defined	Requires the Type statement

 

Conversion between data types
Once a variable has been declared as a certain data type, it may hold only information of that type. While E-Basic will perform numeric type conversions automatically, which means a runtime error will not occur, it is not good practice to rely on such automated conversions, in part because the results may not always be what you expect. At times, it may be necessary to convert information from one type to another in order to store it in a particular variable. E-Basic contains several functions for the purpose of conversion between data types.

 

Function	Description
CCur	Convertsany expression toa Currency.
CBool	Convertsexpression toTrueor False,returninga Booleanvalue.
CDate, CVDate	Convertsexpression toa date,returninga Datevalue.
CDbl	Convertsany expression toa Double.
CInt	Convertsexpression toan Integer.
Chr, Chr$, ChrB, ChrB$, ChrW, ChrW$	Returnsthecharacterwhose ASCIIvalue is charcode.
CLng	Convertsexpression toa Long.
CSng	Convertsexpression toa Single.
CStr	Convertsexpression toa String.
Cvar	Convertsexpression toa Variant.
Hex, Hex$	Returnsa Stringcontainingthehexadecimal equivalentofnumber.
Str, Str$	Returnsa stringrepresentationofthegiven number.
Val	Convertsa given stringexpression toa number.
NOTE: Some functions offer the optional use of the “$” character. When the “$” character is used, the value returned is a string. When “$” is not used, a string variant is returned.

 

 

Declaring Multiple Variables
Users are not limited to one variable declaration per line. Multiple variables may be declared on a single line using only a single Dim statement. However, the user should take care to specify the data type for each variable declared, even if they are on the same line. Any variable that is not specifically declared with a data type will be declared as a Variant. There are times where variants are useful, but variant data types require more memory than other data types and should be used with care. (Variants are described in more detail in the Advanced Programming section below.) In the example below, participant_dob is declared as a date, Stim is declared as a string and k is declared as an integer. The j variable is declared as a variant because it is not specifically stated to be any other data type.

 

Dim participant_dob As Date, j, k As Integer, stim As String

Declaring multiple variables on the same line may save space, but it also increases the likelihood of human error. A compromise might be to not mix data types within a single line; this can help to organize variables and reduces the chance of error. An example of this type of declaration is shown below:

 

Dim participant_birthdate As Date

Dim j As Integer, k As Integer

Dim stimulus As String, Dim recall As String

 

Initialize and Assign Values
Once a variable is declared, it must be initialized before it can be used. Initializing a variable is nothing more than assigning it an initial or starting value. Most often the purpose of a variable is to hold information that is assigned. An assignment statement simply consists of the variable name followed by an equal sign and then the expression (variable name = expression). In the example below, the counter variable “j” (declared in a previous example) is assigned the expression or value of 1.

 

j =1

 

String values are also assigned using an assignment statement, but the expression value must be enclosed in quotes.

Dim stringVal As String

stringVal = "This is the value of the string."

If the expression extends past a single line, the expression statement must be divided into separate strings, which are concatenated. The ampersand (&) is used for this purpose. No linefeeds or carriage returns are included in the concatenation of strings, unless the new line (\n) character is included.

 

stringVal = "This is the value of a very long string "&_

'"extending over more than one line. The "&_

'"individual parts will be joined to form "&_

'"a continuous display." &_

"\n\nThis will be displayed two lines lower"

 

Variables themselves may be used in expression statements. For example, in an assignment statement, the current value of a variable could be used to set the value of another variable.

 

Dim i As integer, j As Integer, k As Integer

j = k * i

 

Variables themselves may be used in expression statements. For example, in an assignment statement, the current value of a variable could be used to set the value of another variable.

 

Dim i As integer, j As Integer, k As Integer
j = k * i

 

In this case, rather than making a literal assignment to the variable j, the current values of the “k” and “i” variables are determined at the point that the script is executed, and those values are used to calculate the value of “j.”

 

Variables may also be used to pass information to a command or function. For example, the value of stringVal defined above could be used with the MsgBox command to display the intended string.

 

MsgBox stringVal

 

Constants
A constant is used when requiring the use of a value that does not change. When working with a value that does not change, you could technically use a variable to hold the value, but it makes more sense to use a constant because it cannot be modified. To declare a constant, use a Const statement in the same manner a Dim is used to declare a variable. The only difference between the Const and the Dim declaration is that a value is specified immediately after the data type.

Const speed_of_light As String = "Really, really fast!"

Const exercise As Boolean = True

 

Writing Subroutines

Subroutines are composed of a series of commands combined into a unit. This unit may then be run by a call to the subroutine from within an InLine object. A subroutine is defined using the Sub…End Sub statement. For example, a simple subroutine may be created to “clear” the background of a Canvas object to a particular color.

 

Example: Clear the Screen to the Current Color

 

In the script below, the ClearToRed subroutine sets the fill color to red, and then uses the Clear command to clear the screen using the current FillColor setting. the following script would need entered on the User script tab in the Script window. Once defined, the subroutine is available to any InLine object, and the ClearToRead subroutine can be run by referring to it by name.

 

'Subroutine containing the script necessary to set the

'background to red.

Dim cnvs As Canvas

Sub ClearToRed

cnvs.FillColor = Ccolor("Red")

cnvs.Clear

End Sub

 

In the example below, the ClearToRed subroutine is called to quickly set the background to red before ten circles are drawn on the Canvas. The script below would be placed in an InLine object called during the experiment. 
 

'Clear the screen to red and draw 10 circles of random

'size

Dim i As Integer

Dim x As Integer

Dim y As Integer

Dim rad As Integer

Set cnvs = Display.Canvas

ClearToRed

x = 50

y = 100

For i = 1 To 10

cnvs.Pencolor = Ccolor("white")

cnvs.Fillcolor = Ccolor("white")

rad = Random (3,20)

x = x + 50

cnvs.Circle x, y, rad

Next I

Sleep 1000

 

Subroutines are most useful when a section of script is used repetitively. The use of subroutines aids in the prevention of errors, and minimizes script maintenance. Additionally, it should be noted that subroutines may only be used in the User Script. Using subroutines in an InLine Object will result in compile errors.

 

Writing Functions

Like subroutines, functions are units composed of a series of script commands. Functions differ from subroutines in that they may be used in a command, and may return a value (e.g., if the function requested a response from the user, or performed a data transformation).

 

Example: Calculate a Mean Value

 
In the example below, the DoMean function is passed two parameters (total and count). Total is divided by count (using the “/” operator) to determine the value for DoMean. This script is entered on the User Script window to define the DoMean function.
 

Function DoMean(total As Double, count As Integer)As Double

DoMean = total/count

End Function

 

Once it is entered in the User Script, the DoMean function may be used at any time during the experiment. The CalcMean InLine object below calls the DoMean Function to calculate the mean of 5 randomly chosen numbers. To run this example, after entering the script above on the User Script window, enter the script below on the Setup InLine object.

 

Dim total As Double

Dim count As Integer

Dim i As Integer

Dim next_val As Integer

total = 0

count = 5

For i = 1 To count

next_val = Random (1,20)

MsgBox “Value #” & i & “: “& next_val

total = total + next_val

Next i

MsgBox “The total is “ & CStr(total) & “\n” &_

“The count is “ & CStr(count) & “\n” &_

“The mean is “ & DoMean (total, count)

 

Next Article: SCRIPTING: Programming: Advanced [22909]
Previous Article: SCRIPTING: Programming: Basic (Logical Operators, Flow Control, Examples and Exercises) [25423]

 

See Also:

Lastly, the E-Prime 2.0 Intermediate Scripting Webinar contains information for intermediate level programmers with E-Basic. Materials for the webinar are attached to this article.  

 

For further information on scripting using E-Basic, please refer to the E-Prime Command Reference (https://pstnet.com/ecr).