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
See Also:
SCRIPTING: Workspace (PackageFile Editor) [22893]
SCRIPTING: Toolbar (PackageFile Editor) [22891]
Comments
0 comments
Please sign in to leave a comment.