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.
References Component
One package file may reference another package file in order to incorporate routines and variables from the latter. References to other package files can be added by clicking the Insert Reference icon in the toolbar. When inserting a reference, the "Open Package File" dialog will appear. Once the *.epk3 file you want to reference is selected, click the "Open" button. Each reference will appear individually under the References component in the Explorer window. When a reference has been added to the experiment, the References component can be expanded by clicking the "+" icon next to the component, and collapsed by clicking the "-" icon next to the component.
References can be removed by selecting the reference you want to remove in the Explorer window and then clicking the Remove Reference icon in the toolbar.
When adding a package file that includes a reference to another *.epk3 file to an E-Prime experiment, the referenced package files must also be added to that experiment. Take, for example, a package file named "PST" that references another package file named "EP". If the "PST" package file is added to an *.es3 file, the "EP" package must also be added. If the referenced package file has not been added, a warning will be displayed indicating the name of the package that is referenced and must be added. A warning will also be displayed if the referenced package file does not exist on your machine.
Clicking the name of a referenced package file under the References component will open a form interface containing information about the reference. Several properties are also available to specify how the reference will work in the context of the package file that is referencing it.
| Property | Description |
| Name | The name associated with the referenced package file. |
| GUID | A unique, 32-character, identifier associated with the referenced package file. |
| Position | A property used to specify where the referenced package file should appear in the Add Package dialog within E-Studio relative to the package file referencing it. Possible values are "Before", "After", and "Any" (indicating that the position of the reference in the Add Package dialog is not significant). When adding a package file that references other *.epk3 files, a warning will appear if the referenced package files are not placed in accordance with the Position setting for the reference. |
| Version | The current version number of the referenced package file, separated into Major, Minor, Internal, and Build. By default, this number will be based on the package file selected in the Open Package File dialog when inserting the reference. |
| Version Persist | A number used to determine the minimum version of the referenced package file that must exist on the user’s machine. A warning will appear if the user does not have access to the required version, indicating that the referenced package file must be updated. |
| ForbidVersionPersistP | A number used to determine the maximum version of the referenced package file that can exist on the user’s machine. |
| ForbidVersionPersist Warning | A warning message that should appear if the version persist value of the referenced package file on the user’s machine exceeds the value entered into ForbidVersionPersist. |
Routines Component
A new routine can be added to the package file by clicking the Insert Routine icon in the toolbar. The new routine will appear under the Routines component, and will be automatically named "RoutineX", where X is the next available number. The routine can be renamed by right-clicking it in the Explorer window and selecting “Rename”. Routines can be named using alphanumeric characters only and must begin with a letter. Routine names cannot contain special characters or spaces. The name you specify for the routine in the PackageFile Editor (See E-STUDIO: PackageCall Object [22713] ) is what will appear in the Routine property of the PackageCall object.
To remove a routine from the package file, select it in the Explorer window and click the Remove Routine icon in the toolbar.
The various properties and windows associated with a routine are separated into six tabs. When selecting a routine in the Explorer window, the active tab is displayed in the Workspace. By default, the Definition tab is displayed.
Definition Tab
The Definition tab displays general information about the routine, and includes properties used to specify the parameters associated with the routine, an icon that will be displayed in E-Studio when the routine is added, and when PreRun/PostRun script will run.
The Definition tab also allows the user to specify whether the routine will be advertised within the PackageCall object. Checking the box next to "Advertise this routine with the PackageCall object" will result in the routine name appearing in the Routine property of a PackageCall object. Essentially, this allows users to access and use this routine even if they are not explicitly aware of it. If this box is unchecked, the routine will not appear in the PackageCall object. To access a routine, users will be forced to know the syntax of the routine beforehand, and will need to enter this syntax into an InLine object.
| Property | Description |
| Routine Name | The name associated with the routine. This property can be changed by changing the name of the routine in the Explorer window. This property determines the syntax for calling the routine. |
| Syntax | The syntax for the routine. The syntax is based on the name of the package file, the name of the routine, and any parameters associated with the routine. If the user will run the routine from an InLine, this syntax must be entered. |
| Return Value | The type of data that will be returned by the routine. Possible values include any of the available data types within E-Basic. If a Return Value is specified, the routine cannot be advertised within the PackageCall object since InLine script must be used to assign the return value to a variable. |
| Parameters | The parameters associated with the routine. Parameters can be required or optional. The parameters determine the syntax for calling the routine. |
| Icon | The icon associated with the routine. If this property is left blank, the default icon for the package file is used. 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 images are preferred, other image formats (i.e., *.bmp, *.jpg, *.png, and *.gif) can be used. |
Parameters
The parameters section of the Definition tab lists the parameters associated with the routine. Selecting an existing parameter in the list and clicking the "Remove" button will remove the parameter. Clicking the "Edit" button after selecting an existing parameter will open the Parameter Edit dialog. The properties within the dialog will contain the values that were specified when the parameter was added and/or when the parameter was last edited. Clicking the "Add…" button opens the default Parameter Edit dialog.
| Property | Description |
| Name | The name of the parameter. The value of the Name property is reflected in the syntax for the routine, and will be used to access the value of the parameter in the Script tab. |
| Type | The type of data that will be passed to the routine for this parameter. Possible values include any of the available data types within E-Basic. If the parameter will be optional, the Data Type property must be "Variant". |
| Pass | Determines the manner in which the parameter is passed, either “ByRef” (by reference, which is the default) or “ByVal” (by value). When passing by reference, any change made to the value of the parameter by the routine will be permanent. When passing by value, a copy of the parameter is passed into the routine, and changes made to the value of the parameter by the routine are not permanent. |
| Optional | Determines whether the parameter is required or optional. If this property is set to "Yes", the Data Type property must be set to "Variant". |
| Default Value | The value that will be used if nothing is specified when the routine is called. |
| Description | A brief description of the parameter and its function. |
Overview Tab
The Overview tab consists of a text window that can be used to enter general information about the routine. This information will appear in the PackageCall object when the routine is selected. Text entered into the Overview tab is placed at the top of any information displayed about the routine in the PackageCall object. Overview information typically includes a brief description of what the routine will do. For example, "Displays a message box containing the text specified".
Remarks Tab
The Remarks tab consists of a text window that can be used to enter additional information about the routine. This information will appear in the PackageCall object when the routine is selected. Text entered into the Remarks tab is placed below the Overview and Parameters information displayed in the PackageCall object. Remarks typically include information about how the routine is typically used, or any additional effects the routine may have. For example, "This routine is typically placed at the start of the experiment as a welcome message."
Script Tab
The Script tab consists of a window used to enter executable script that will run when the routine is called. This is where the function of the routine is defined (i.e., what the routine will do). Any external *.DLL calls or types defined in the Declare component and any variables or constants defined in the Global Variables component can be used in the Script tab. Any parameters that have been specified for the routine can also be used.
Variables and constants can be defined in the Script tab. However, they will only be available within the routine itself. Any variables or constants that will be used within a routine but must also be available for access outside of the routine (e.g., in an InLine object) should be defined in the Global Variables component of the package file.
Requirements
The Script tab should be used primarily to enter executable script that will carry out the specific function of the routine. Variable and constant definitions are permitted in the Script tab. Routine declarations are not permitted. If another routine is required, it should be created using the Insert Routine button on the toolbar.
Routines should not assume that a specific object or device is available within the experiment. The reason for this is that the object or device being accessed may not share an identical name in every experiment to which the package file is added. For example, if a routine will copy an image onto the screen using the Canvas object, Display.Canvas.Copy should not be used unless the routine checks to ensure that the Display device exists in the experiment. This can be done using the Rte.GetObject() function:
Dim theDisplayDevice As DisplayDevice
Set theDisplayDevice = CDisplayDevice(Rte.GetObject("Display"))
If Not theDisplayDevice Is Nothing Then
‘Insert Canvas script here.
End If
If a routine will rely on objects within the experiment, it is recommended that the object names be passed into the routine as parameters. For example, a parameter could be created on the Definition tab named strDisplayName. When the routine is called using a PackageCall object or through an InLine object, the name of the device can be passed as a parameter. It is also recommended that any parameters that will be used to pass an object or device name to a routine be of type String. This limits the cause of an error when an object name is passed to a routine.
For example, if a routine has a parameter that will be used to pass an object name, and the parameter is set to a specific type (e.g., RteRunnableInputObject, Slide, etc), an error could be caused if the name of the object passed is not valid (i.e., the object specified does not exist) or if an object that does not match the type specified by the parameter is passed. However, if the parameter is of type String, the cause of an error will be that the object name passed to the routine is invalid. Following these recommendations, the script example above would be changed to the following. This script assumes that a String parameter named strDisplayName has been created on the Definition tab of the routine:
Dim theDisplayDevice As DisplayDevice
Set theDisplayDevice = CDisplayDevice(Rte.GetObject(strDisplayName))
If Not theDisplayDevice Is Nothing Then
‘Insert Canvas script here.
End If
PreRun and PostRun Tabs
The PreRun and PostRun tabs consist of a window used to enter executable script that will run before and after the routine itself, respectively.
| Property | Description |
| PreRun Rule | Determines when PreRun script associated with the routine will run. If “Inherit” is selected, the Procedure on which the routine is being called will determine when PreRun script will execute. If “Object” is selected, PreRun script will run immediately before the routine is called, If “Procedure” is selected, PreRun script will run at the beginning of the Procedure on which the routine will run. |
| PostRun Rule | Determines when PostRun script associated with the routine will run. If “Inherit” is selected, the Procedure on which the routine is being called will determine when PostRun script will execute. If “Object” is selected, PostRun script will run immediately following the routine, If “Procedure” is selected, PostRun script will run at the end of the Procedure on which the routine will run. |
The exact location of the script entered into the PreRun and PostRun tabs within the experimental structure will depend on the PreRun and PostRun Rule settings on the Definition tab. If the PreRun Rule is set to “Object”, the script entered into the PreRun tab will be run immediately before the routine is called. If the PreRun Rule is set to “Procedure”, the script entered into the PreRun tab will run at the beginning of the Procedure on which the routine is called (i.e., not necessarily immediately before the routine). Finally, if the PreRun Rule is set to “Inherit”, the Procedure on which the routine is called will determine where the PreRun script is run (i.e., whether the PreRun rule is Object or Procedure).
If the PostRun Rule is set to “Object”, the script entered into the PostRun tab will be run immediately after the routine is called. If the PostRun Rule is set to “Procedure”, the script entered into the PostRun tab will run at the end of the Procedure on which the routine is called (i.e., not necessarily immediately after the routine). Finally, if the PostRun Rule is set to “Inherit”, the Procedure on which the routine is called will determine where the PostRun script is run (i.e., whether the PostRun rule is Object or Procedure).
Requirements
The PreRun and PostRun tabs should consist of executable script only. No variable or constant definitions should occur in the PreRun or PostRun tabs. The primary reason for this is that, if a routine is called multiple times on the same Procedure, a conflict will occur as the same variables and constants would also be declared multiple times. Any variables or constants that need to be used in the PreRun or PostRun tabs must be declared in the Global Variable component using the appropriate naming conventions (See E-STUDIO: Local and Global Values [22734]).
Routine declarations are also not permitted on the PreRun and PostRun tabs. If another routine is required, it should be created using the Insert Routine button on the toolbar.
Script entered into the PreRun and PostRun tabs should not assume that a specific object or device is available within the experiment. The reason for this is that the object or device being accessed may not share an identical name in every experiment to which the package file is added. For example, if PreRun or PostRun script will copy an image onto the screen using the Canvas object, Display.Canvas. Copy should not be used unless the script first checks to ensure that the Display device exists in the experiment. This can be done using the Rte.GetObject() function as follows. This script assumes that a DisplayDevice variable named theDisplayDevice has been created on the Global Variables component:
Set theDisplayDevice = CDisplayDevice(Rte.GetObject(“Display”))
If Not theDisplayDevice Is Nothing Then
‘Insert Canvas script here.
End If
Next Article: PACKAGEFILE: PackageFile Hierarchy [22897]
Previous Article: PACKAGEFILE: PackageFile Editor Interface [22889]
Comments
0 comments
Please sign in to leave a comment.