SCRIPTING: Package (PackageFile Editor) [22894]

Package Component
 
The Package component contains general information about the package file, including the name, prefix, and version number. The properties for this component are displayed in a form interface. This is the default component displayed in the Workspace when a new package file is created, or an existing package file is opened.
 

Property	Description
PackageName	A name to be associated with the PackageFile. The value entered for this property will appear under the Package column when working with the Add Package dialog in E-Studio. The value entered for the Name property will also act as the default prefix for routines.
VariablePrefix	A unique series of characters that will be associated with any variables declared on in the Global component. This prefix helps to prevent variable conflict in the event that multiple package files are added to an experiment.
GUID	A unique, 32-character, identifier for the package file. Press the Reset button to the right of the GUID field to generate a new identifier. This field cannot be left blank and the value must match the default 32-character format. If the field is left blank, or the number is not in the correct format, a new GUID will be generated upon saving the package file.
URL For Updates	An internet address used to obtain updates to the package file.
Icon	The name of the image file that will be associated with the package file. This icon will appear under the Package column when working with the Add Package dialog in E-Studio. The image file must be located in the same directory as the package file itself (i.e., the *.epk3 file). If you choose an image file that is not located in the same folder as the *.epk3 file, you will be prompted to copy it there. While *.ico files are preferred, other image formats (i.e., *.bmp, *.jpg, *.png, and *.gif) can be used.
Version	The current version number of the package file, separated into Major, Minor, Internal, and Build.
Auto Increment	Check this box to have the PackageFile Editor automatically increment the number in the Build field each time the package file is saved.
Version Persist	A number used to determine whether the version of the package file in the *.es3 file being opened is compatible with the version of the package file the user has installed on their machine. For example, if the *.es3 file being opened includes a package file with a Version Persist value of 1, but the user has a previous version of the package file installed (i.e., where Version Persist is 0), a warning will appear indicating that the user must update their version of the *.epk3 file on their machine. Alternatively, if the version on the user’s machine is higher than that of the package file in the *.es3 file, a prompt will appear to upgrade the version of the package file in the *.es3 file to that which is installed on the user’s machine.

 

Script Component

Declare
The Declare component consists of a window used to enter script that will be inserted at the top sections of the Full Script view in E-Studio. This component is primarily used to enter Declare statements that will make calls to external routines or functions in a dynamic link library (i.e., *.DLL). Additionally, data structures may be declared using the Type and End Type keywords. No executable script should be entered into the Declare component. The routines added to the package file via the Routines component do not need to be declared separately in the Declare component. Declare statements for these routines will be automatically generated by the PackageFile Editor and included in the full script generated by an *.es3 file to which the package file has been added.
 
Requirements
Only Declare statements used to make calls to external *.DLL routines and functions may be entered into the Declare component. In addition, the declaration of data structures using the Type and End Type keywords is permitted.
 
The declaration of the routines used by the package file is handled automatically by the PackageFile Editor. Thus, the declaration of routines in the Declare component is not permitted. Additionally, the creation or assignment of variables is not permitted.
 
To avoid naming collisions with other *.epk3 files, all declarations made in the Declare component must use the name of the package file as a prefix. For Declare statements used to make calls to external *.DLL routines or functions, this will require the use of the Alias keyword. The Alias keyword is used to indicate that the *.DLL routine or function being called has a different name from that specified by the Declare statement. For example, in a package file named "PST", a Declare statement used to call GetCurrentDirectoryA in the kernel32.dll file would be set up as follows:
 

Declare Function PST_GetCurrentDirectory Lib "kernel32.dll" Alias "GetCurrentDirectoryA" &_(ByVal nBufferLength As Long, ByVal strBuffer As String) As Long

 
In this example, the name specified in the Declare statement is "PST_GetCurrentDirectory". However, the name of the function being called in the external *.DLL file is "GetCurrentDirectoryA". Thus, the Alias keyword must be used to indicate that PST_GetCurrentDirectory is calling the GetCurrentDirectoryA function in the kernel32.dll file. If the *.DLL function name happened to be "PST_ GetCurrentDirectory", the Alias keyword would not be necessary, since the name would conform to the requirements of the Declare component.
 
Global Variables
The Global Variables component consists of a window used to enter script that will be inserted at the top sections of the Full Script view in E-Studio. The purpose of this component is to define the variables and constants used by the routines in the *.epk3 file via the Dim and Const keywords. No executable script should be entered into the Global Variables component.
 
While variables and constants can be declared within a routine, this limits their scope to within that routine. That is, if a routine is called in an experiment using the PackageCall object, any variables or constants declared within that routine cannot be used outside of it (e.g., in InLine script objects). Variables and constants declared in the Global Variables component, however, can be used in all of the routines associated with the package file, in the PreRun or PostRun associated with a routine, or any InLine objects throughout the experiment.
 
Requirements
Only the Dim and Const keywords should be used in the Global Variables component. The declaration of routines or assignment of variables is not permitted.
 
To avoid naming collisions with other *.epk3 files, all variable and constant names must include the package file name or prefix (specified in the Prefix field of the Package component). For example, a package file named "PST" with the prefix "pst" would have variable declarations as follows:
 

Dim PST_nSubject As Integer
Dim PST_strFilenameRecovery As String, PST_strFilenameEDAT As String

 
Or, as an alternative, the package file prefix could be used:
 

Dim pst_nCount As Integer
Dim pst_strFilenameRecovery As String, pst_strFilenameEDAT As String

 

InitGlobals
The InitGlobals component consists of a window used to enter script that will be placed inside the InitGlobals routine generated by E-Studio in the Full Script view. The primary use of this component is to assign default values to variables that will be used by the package file. Additionally, values can be retrieved from or assigned to the Context object (i.e., the experimental context) passed into the InitGlobals routine.
 
For example, the InitGlobals component can be used to specify a particular value for the Subject attribute in the experimental context. That is, rather than entering a value for this attribute at the start of the experiment using a Startup Info prompt, you can use executable script to assign a number randomly, or to obtain a value from an external file. In this situation, script similar to the following would be entered into the InitGlobals component. Note that this script assumes that you have declared a variable of type Integer named PST_nSubject in the Global Variables component:
 

PST_nSubject = ‘Enter script used to assign a random number, or to obtain the number from an
‘external text file or database here.

c.SetAttrib "Subject", PST_nSubject

 
As long as the Subject startup info parameter is disabled in the *.es3 file, the experiment will use the number assigned by the InitGlobals script for data logging, counterbalancing, etc.
 
Another example would be using the InitGlobals component to create a value for an attribute that is already being referenced in the *.es3 file. For instance, if the location of stimuli files used by the experiment will vary from run to run, it may be useful to create an attribute that contains the path for the directory the files are located (e.g., by using script to determine this location, by loading the location from an external text file/database, etc), or to assign a value to an existing attribute used for this purpose.
 
Requirements
While executable script may be entered into the InitGlobals component, the declaration of routines and the creation of variables are not permitted.
 
Because the InitGlobals routine that is generated by E-Studio in the Full Script view is called before the InitDevices and InitObjects routine, access to devices and objects is limited in the InitGlobals component. Thus, the initialization of any resources (e.g., objects, devices, etc) is not permitted in the InitGlobals component. This type of initialization should be directed to the InitPackages component.
 
UnInitGlobals
The UnInitGlobals component consists of a window used to enter script that will be placed inside the UnInitGlobals routine generated by E-Studio in the Full Script view. The purpose of this component is to permit for the cleanup of any global variables defined by the package file. For example, if any references were created in, InitGlobals; these references should be released in UnInitGlobals.
 
Requirements
While executable script may be entered into the UnInitGlobals component, the declaration of routines and the creation of variables are not permitted.
 
Because the UnInitGlobals routine that is generated by E-Studio in the Full Script view is called as one of the last running portions of an E-Prime experiment, access to many elements of the experiment is limited in the UnInitGlobals component. Thus, the closing of any resources (e.g., objects, devices, etc) is not permitted in the UnInitGlobals component. This type of maintenance should be directed to the UnInitPackages component.
 
InitPackages
The InitPackages component consists of a window used to enter script that will be placed inside the InitPackages routine generated by E-Studio in the Full Script view. The purpose of this component is to permit for the initialization of any objects, variables, and resources that will be used by the package file.
 
An example would be creating a custom name for the *.txt and *.edat3 files used for data logging. By default, E-Prime 3.0 will use the experiment name, Subject number, and Session number to create a name for these files. Since any script entered into the InitPackages component will run before the SessionProc (i.e., the start of logging in the experiment) but after E-Prime 3.0 has created the default name for the recovery and data files, a custom filename can be specified. In this situation, script similar to the following would be entered into the InitPackages component. This script assumes that you have created two String variables (i.e., PST_strFilenameRecovery and PST_strFilenameEDAT) in the Global Variables component:
 

PST_strFilenameRecovery = "Custom.txt" PST_strFilenameEDAT = "Custom.edat2"
c.DataFile.Filename = PST_strFilenameRecovery

 
Requirements
While executable script may be entered into the InitPackages component, the declaration of routines is not permitted. Additionally, the creation of variables is not permitted in the InitPackages component.
 
The InitPackages generated by E-Studio in the Full Script view is called after the devices used by the experiment have been opened, but prior to the InitObjects routine. Therefore, access to all elements (i.e., objects, etc) of the experiment will be limited. Any initialization that requires access to all experiment resources should be performed inside a Routine and called in the experiment via a PackageCall object.
 
UnInitPackages
The UnInitPackages component consists of a window used to enter script that will be placed inside the UnInitPackages routine generated by E-Studio in the Full Script view. The purpose of this component is to permit for the uninitialization of any objects, variables, or resources that were created or assigned in the InitPackages component. For example, if any references were created in the InitPackages component, these references should be released in the UnInitPackages component.
 
Requirements
While executable script may be entered into the UnInitPackages component, the declaration of routines is not permitted. Additionally, the creation of variables is not permitted in the UnInitPackages component.
 
The UnInitPackages generated by E-Studio in the Full Script view is called after the UnInitObjects routine, but before devices used by the experiment are closed. Therefore, access to all elements (i.e., objects, etc) of the experiment will be limited. Any uninitialization that requires access to all experiment resources should be performed inside a Routine and called in the experiment via a PackageCall object.
 
See Also:
SCRIPTING: PackageFile Editor [22888]