Unverified Perl
Top  Previous  Next

Unverified Perl can be used for additional flexibility in SSI Scripting.

SSI Script has been implemented using the Perl Programming Language. When [% Q1 + 3 %] is specified in SSI Web, the server side Perl scripts actually receive that as [% VALUE("Q1") + 3; %] which is valid Perl source code. The Perl scripts evaluate this code and return the result. If additional power and flexibility are needed in your SSI Script, you can enter straight Perl code to accomplish the task. This is definitely an advanced area. SSI Web does not check your Unverified Perl for errors. You must thoroughly test your Perl logic.

Unverified Perl Rules  
Unverified Perl Functions  
Perl Programming Language Basics  
Examples  
Unverified Perl Rules

·Unverified Perl can be entered by using the key words "Begin Unverified Perl" and "End Unverified". For example:  

[%  
   Begin Unverified Perl  
   VALUE("Q1") + 3;  
   End Unverified  
%]  
 
Your Unverified Perl code is not checked for errors.  
 
·Unverified Perl is executed on the server before the web page is sent down to the browser. So in order to execute this:  

[%  
   Begin Unverified Perl  
   VALUE("Q1") + 3;  
   End Unverified  
%]  
 
Q1 must have been answered on a previous page. You cannot refer to the answer to a question if the question is being asked on the same page.  
 
·Each statement must end with a semicolon. For example:  

[%  
   Begin Unverified Perl  
 
   my $intVar = VALUE("Q1") + 3;  
   $intVar = $intVar + (VALUE("Q3") / 3);  
   return $intVar;  
 
   End Unverified  
%]  
 
Notice the semicolons at the end of each line.  
 
·The last statement of the Unverified Perl is evaluated and the result returned. For example:  

[%  
   Begin Unverified Perl  
 
   my $intVar = VALUE("Q1") + 3;  
   $intVar = $intVar + (VALUE("Q3") / 3);  
     
   End Unverified  
%]  
 
returns $intVar after all the math is completed. You can also return explicitly using the "return" keyword. For example:  
 
[%  
   Begin Unverified Perl  
 
   my $intVar = VALUE("Q1") + 3;  
   $intVar = $intVar + (VALUE("Q3") / 3);  
   return $intVar;  
 
   End Unverified  
%]  
 
·To compare two values, use == for numbers and eq for text. For example:  

Begin Unverified Perl  
 
if(VALUE("Q1") == 5)  
{  
   AIC("Q3");  
}  
 
if(VALUE("QName") eq "Sally")  
{  
   ADD("ColorList", 4);  
}  
 
End Unverified  
 
 
·Functions must be in upper case. (There are a few exceptions to this rule. Please see Unverified Perl Functions for details). For example, while creating a constructed list you can specify:  

Begin Unverified Perl  
 
if(VALUE("Q1") > 5)  
{  
   AIC("Q3");  
}  
 
End Unverified  
 
Notice the functions VALUE and AIC are upper case.  
 
·Question names and list names are case-sensitive, and must be enclosed in double quotes when used as function parameters. For example:  

Begin Unverified Perl  
 
ADD("ColorsList");  
AIC("q1");  
 
End Unverified  

The list ColorsList is enclosed in double quotes. "colorslist" is not valid, because the case does not match the case of the name of the defined list. Question names are similar.  
 
·Avoid using single quotes in unverified Perl. If you need to use a single quote, you can do so in a separate Perl script file that you include.  
Unverified Perl Functions

List Functions:
SSI Script:
"Unverified" Perl:
Description:
·ADD (ListName)  
·ADD (ListName, Member#)  
·ADD (ListName, StartMember#, EndMember#)  
·ADD ("ListName")  
·ADD ("ListName", Member#)  
·ADD ("ListName",  
  StartMember#, EndMember#)
Adds members from a specified list to the end of the constructed list.
More info.

·AIC (QuestionName)  
·AIC (QuestionName, Member#)  
·AIC (QuestionName, StartMember#, EndMember#)  
·AIC ("QuestionName")  
·AIC ("QuestionName", Member#)  
·AIC ("QuestionName", StartMember#, EndMember#)  

 Add If Chosen: Adds members chosen in a select-type question onto a new constructed list. More info.


AIE (QuestionName, Value)
AIE ("QuestionName", Value)
Add If Equal: Adds members in a grid numeric, grid constant sum, grid ranking, grid with all radio buttons, constant sum, or ranking question that were given answers equal to a specific value.
More info.
AIG (QuestionName, Value)
AIG ("QuestionName", Value)
Add If Greater: Adds members in a grid numeric, grid constant sum, grid ranking, grid with all radio buttons, constant sum, or ranking question that were given answers greater than a specific value.
More info.
AIL (QuestionName, Value)
AIL ("QuestionName", Value)
Add If Less: Adds members in a grid numeric, grid constant sum, grid ranking, grid with all radio buttons, constant sum, or ranking question that were given answers less than a specific value.
More info.
ANC (QuestionName)
ANC (QuestionName, Member#)
ANC (QuestionName,
  StartMember#, EndMember#)

ANC ("QuestionName")
Add if Not Chosen: Adds members not chosen in a select-type question onto a new constructed list.
More info.
ANE (QuestionName, Value)
ANE ("QuestionName", Value)
Add if Not Equal: Adds members in a grid numeric, grid constant sum, grid ranking, grid with all radio buttons, constant sum, or ranking question that were given answers not equal to a specific value.
More info.
·INSERT (TargetPosition#, ListName)  
·INSERT (TargetPosition#,  
  ListName, Member#)
·INSERT (TargetPosition#,  
  ListName, StartMember#,
  EndMember#)
·INSERT (TargetPosition#,  
  "ListName")
·INSERT (TargetPosition#,  
  "ListName", Member#)
·INSERT (TargetPosition#,  
  "ListName", StartMember#, 
  EndMember#)
Inserts members from a specified list to an exact position within a constructed list.
More info.

ListHasParentMember
(ListName, ParentMember#)

LISTHASPARENTMEMBER 
("ListName", ParentMember#)
Is true if the specified parent member exists in the specified list.
More info
ListLabel (ListName,
  Member#)
LISTLABEL ("ListName",
  Member#)
Returns the label of a specified member number in a list.
ListLabelsArray (ListName)
LISTLABELSARRAY ("ListName"
Returns a comma-separated list of member labels enclosed in quotes.
ListLength (ListName)
LISTLENGTH ("ListName")
Returns the number of members in the list.
ListMax (Value)
LISTMAX (Value)
Controls the maximum length of a list.
More info.
ListMin (Value)
LISTMIN (Value)
Controls the minimum length of a list.
More info.

ListValue (ListName,
  Member#)
LISTVALUE ("ListName",
  Member#)
Returns the value of the specified member number in a list.
ListValuesArray (ListName)
LISTVALUESARRAY
  ("ListName")
Returns a list of list values (example: [1, 4, 6]).
·Randomize ()  
·Randomize (SeedValue)  
·Randomize (StartMember#, EndMember#)  
·Randomize (SeedValue, StartMember#, EndMember#)  
·RANDOMIZE ()  
·RANDOMIZE (SeedValue)  
·RANDOMIZE (StartMember#, EndMember#)  
·RANDOMIZE (SeedValue, StartMember#, EndMember#)  
 Randomizes the members of a constructed list.
More info.
·Remove (ListName)  
·Remove (ListName, Member#)  
·Remove (ListName, StartMember#, EndMember#)  
·REMOVE ("ListName")  
·REMOVE ("ListName", Member#)  
·REMOVE ("ListName", StartMember#, EndMember#)  
 Removes the members in the specified list from the constructed list.
More info.
Reverse ()
REVERSE ()
Reverses the members in a list. For example, list members A, B, C, D when reversed become D, C, B, A.
SetListLength ()
SETLISTLENGTH ()
Controls the length of a list.
More info.
SortByLabel ()
SORTBYLABEL ()
Sorts a list based on list labels. Numbers are sorted below letters.
SortByValue ()
SORTBYVALUE ()

Sorts the members in a constructed list with respect to their natural order (lowest to highest value) from their parent predefined list. For example, list members with values 5, 3, 2, 7 would be sorted as 2, 3, 5, 7.


System Functions:
      
SSI Script:
"Unverified" Perl:
Description:
Answered(QuestionName)
ANSWERED("QuestionName")
Is true if the question was answered by the respondent, false otherwise.
More info
Browser()
BROWSER()
Returns information on respondent's browser.
Debug()
DEBUG()
Returns debug information that assists you when testing the questionnaire.
DisplayTotal
 FirstQuestionName,
 LastQuestionName, Width)
DISPLAYTOTAL
("FirstQuestionName",
"LastQuestionName", Width)
Returns a greyed out box displaying the total of all questions on the same page beginning with FirstQuestionName and ending with LastQuestionName. Especially useful for free-format constant sum questions.
EncodeForURL(QuestionName)
ENCODEFORURL(QuestionName)
Converts characters that are not valid for use in URLs to URL-supported strings.
IPAddress()
IPADDRESS()
Returns respondent's IP Address.
GraphicsPath()
GRAPHICSPATH()
Returns the system graphics path.
JavaScript()
JAVASCRIPT()
Is true if they have JavaScript, false otherwise.
More info
Label(QuestionName)
LABEL("QuestionName")
Returns the label that is associated with the answer to a single select response type question.
LinkButton("URL")
LINKBUTTON("URL")
Returns an HTML "submit" button (this helps in linking surveys).
NumChecked(QuestionName)
NUMCHECKED("QuestionName")
Returns number of response options checked. QuestionName can be a select checkbox (i.e. Q1), a row or column of checkboxes (i.e. Q1_r1 or Q1_c1), or a Free Format question (i.e. Q1_checked).
OperatingSystem()
OPERATINGSYSTEM()
Returns information on respondent's operating system.
PageNumber()
PAGENUMBER()
Returns current page number.
PopUp("LinkText",
 "File.htm", Width, Height)
POPUP("LinkText", "File.htm",
 Width, Height)
Returns the HTML for a JavaScript pop-up. File.htm is assumed to be in the graphics folder. Or, File.htm can be elsewhere if referenced with full http:// path. More info
ProgressBar()
PROGRESSBAR()
Returns the progress bar to the screen. Typically placed in the Global Header or Global Footer.
RandNum(Seed)
RandNum(Seed, Min#, Max#)

RANDNUM(Seed)
RANDNUM(Seed, Min#, Max#)
Returns a random number. If one parameter is given, returns a uniform random decimal value between 0 and 1. If three parameters are given, returns a random integer value from Min# to Max#. Seed must be an integer. If Seed is 0, the system clock is used to seed the random number generator.
More info.
RespNum()
RESPNUM()
Returns the internal respondent number converted to an integer.
RespNumLabel() 
RESPNUMLABEL()
Returns the internal respondent number as converted to a label (letters) or a "string".
Shown(QuestionName)
SHOWN("QuestionName")
Is true if the question has been seen by the respondent, or false if the question was not seen by the respondent
More info
SysRand()
SysRand(Min#, Max#)

SYSRAND()
SYSRAND(Min#, Max#)
Returns a random number seeded by the system clock (different seed every time instruction is encountered).
SystemTime() 
time()
Returns the number of non-leap seconds since January 1, 1970.
TabWidth()
TABWIDTH()
Returns the global tab width specified in global settings .
TotalPages()
TOTALPAGES()
Returns the total number of pages in the study.
UserAgent()
USERAGENT()
Returns respondent's User Agent.
Value(QuestionName)
VALUE("QuestionName")
Returns the value of the question as it is recorded in the STUDYNAMEdat.cgi file. More Info.


Quota Control Functions:
         
SSI Script:
"Unverified" Perl:
Description:
Value(QuestionName)
VALUE("QuestionName")
Returns the quota cell value to which the respondent has been assigned for the quota question referred to by QuestionName; returns 0 if unassigned.
QuotaCellName
  (QuestionName)  
QUOTACELLNAME
("QuestionName")
Returns the quota cell name to which the respondent has been assigned; returns empty string (nothing) if unassigned
IsQuotaCellOpen
  (QuestionName,
   QUOTA_CELL_NAME)
IsQuotaCellOpen
  (QuestionName,
   QUOTA_CELL_VALUE) 
ISQUOTACELLOPEN
("QuestionName",
QUOTA_CELL_VALUE)
Returns true (1) if the cell is open, false (0) if the cell is closed
QuotaCellRemaining
  (QuestionName,
  QUOTA_CELL_NAME)
QuotaCellRemaining
  (QuestionName,
  QUOTA_CELL_VALUE) 
QUOTACELLREMAINING
("QuestionName",
QUOTA_CELL_VALUE)

Returns number of completes left to fill the quota cell. Returns 0 if quota cell is full.
QuotaCellLimit
  (QuestionName,
  QUOTA_CELL_NAME)
QuotaCellLimit
  (QuestionName,
  QUOTA_CELL_VALUE) 
QUOTACELLLIMIT
("QuestionName",
QUOTA_CELL_VALUE)
Return the quota cell limit
QuotaCellCompletes
  (QuestionName,
  QUOTA_CELL_NAME)
QuotaCellCompletes
  (QuestionName,
  QUOTA_CELL_VALUE) 
QUOTACELLCOMPLETES
("QuestionName",
QUOTA_CELL_VALUE)
Returns number of completes in the quota cell
AreAllQuotasClosed()

AREALLQUOTASCLOSED()
Returns true if all cells have been closed. This might be useful if you don't want to show a "survey closed" message but would like to skip the respondent to a different survey.
AreAllQuotaCellsClosed
  (QuestionName)
AREALLQUOTACELLSCLOSED
("QuestionName")
Returns true if all cells have been closed for the specified quota.
AreAnyQuotasClosed()

AREANYQUOTASCLOSED()

Returns true if all cells have been closed for any quota.



Math Functions:

SSI Script:
"Unverified" Perl:
Description:
Abs (*NUMBER)
ABS (NUMBER)
Returns the absolute value of NUMBER.
Ceiling (NUMBER)
CEILING (NUMBER)
Rounds the NUMBER up to the closest integer.
Exp (NUMBER)
EXP (NUMBER)

Returns e (2.71828183) raised to the power of NUMBER
Floor (NUMBER)
int (NUMBER)
Rounds the NUMBER down to the closest integer.
Log10 (NUMBER)
LOG10 (NUMBER)
Returns the log (base 10) of NUMBER.
Ln (NUMBER)
LOG (NUMBER)
Returns the natural log of NUMBER.
POWER (NUMBER1, NUMBER2)
POWER (NUMBER1, NUMBER2)
Returns NUMBER1 raised to the NUMBER2 power.
ROUND (NUMBER)
ROUND (NUMBER, #DECIMALS)
ROUND (NUMBER, 0)
ROUND (NUMBER, #DECIMALS)
Rounds NUMBER to the #DECIMALS places. If no decimal places are specified, rounds to nearest integer.
Sqrt (NUMBER)
sqrt (NUMBER)
Returns the square root of NUMBER.
*For all math functions, NUMBER can be any QuestionName that contains a numeric value or any numeric expression (including functions and mathematical operators) that returns a numeric value.


String Functions:

SSI Script:
"Unverified" Perl:
Description:
IsNumber (QuestionName)
ISNUMBER ( 
 VALUE("QuestionName"))
Is true if the entire string is all digits, false otherwise.
More info
Length (QuestionName)
length (
 VALUE("QuestionName"))
Returns the number of characters contained in the response.
Mid (QuestionName,
  BeginPosition,
  Length)
MID (VALUE("QuestionName",
 BeginPosition, 
 Length))

Extracts a substring of a string given by QuestionName. The substring is extracted starting at the character number specified in BeginPosition (1-based counting) with length specified in Length.
QuestionName ()
QUESTIONNAME ()
Returns the name of the current question. May be used in Header 1, etc. sections, and also in skip patterns.
TextExists (QuestionName,
 "TextToLookFor")
TEXTEXISTS ("QuestionName",
 "TextToLookFor")
Searchers for "TextToLookFor" in the answer of QuestionName. If found, a 1 is returned; if not found, a 0 is returned.
ToLower (QuestionName)
lc (VALUE("QuestionName"))
Returns a lowercased version of the response.
ToUpper (QuestionName)
uc (VALUE("QuestionName"))
Returns an uppercased version of the response.


Error Functions:

SSI Script:
"Unverified" Perl:
Description:
ErrCursum ()
ERRCURSUM ()
Returns the current sum of the constant sum question.
ErrField ()
ERRFIELD ()
Returns the question number on the page.
ErrMax ()
ERRMAX ()
Returns the maximum value allowed for the question.
ErrMin ()
ERRMIN ()

Returns the minimum value allowed for the question.
ErrQName ()
ERRQNAME ()
Returns the question name.
ErrText ()
ERRTEXT ()
Returns the question-specific error message that is optionally specified at the question level, under the Advanced... button.

ErrTotal ()
ERRTOTAL ()
Returns the total amount that the responses to the constant sum question should add to.


CBC Functions:

SSI Script:
"Unverified" Perl:
Description:
CBCDesignConceptValue
 (CBCQuestionName,
 ConceptPosition#)

CBCDESIGNCONCEPTVALUE
 ("CBCQuestionName",
 ConceptPosition#)

Returns the actual concept number from the design that is being displayed to the screen in ConceptPosition#. Position numbers will only differ if concept sorting is in place. This function is used when researchers want to customize the format of their CBC questions.
CBCDesignLevelText
  (CBCQuestionName,
  ConceptPosition#,
  LevelTextPosition#)

CBCDESIGNLEVELTEXT
 ("CBCQuestionName",
 ConceptPosition#,
 LevelTextPosition#)
Returns the level text for the specified CBC question for the specified concept position and level text position. This function is used when researchers want to customize the format of their CBC questions.
CBCNone ()
CBCNONE ()
Returns the "None" text for the CBC question (traditional "None" option only) and is only used in Shelf Facing Display CBC questions.
CBCVersion ()
CBCVERSION ()
Returns the design version number and question name. This function is useful when creating paper-and-pencil interviews. (Example: D-1, T-CBCRAN1)


ACA Functions:

SSI Script:
"Unverified" Perl:
Description:
ACAAttribute ()
ACAATTRIBUTE ()
Returns the text for the attribute label within the ACARAT or ACAIMP questions.
ACABest ()
ACABEST ()
Within the ACAIMP question, returns the level text for the "best" level rated from the previous ACARAT question.
ACABestLevelLabel
 (Attribute#, Rank#)
ACABESTLEVELLABEL
 (Attribute#, Rank#)
Returns label for best attribute level of Attribute #. Rank# optional. Rank# of 2 returns second-best attribute level.
ACABestLevelValue
 (Attribute#, Rank#)
ACABESTLEVELVALUE
 (Attribute#, Rank#)
Returns level number for best attribute level of Attribute #. Rank# optional. Rank# of 2 returns second-best attribute level number.
ACAImportance
 (Attribute#)
ACAIMPORTANCE
 (Attribute#)
Returns the importance score for the attribute, as specified by Attribute#. May be used after the ACAIMP question section. (See also ACAStrictImportance.)
ACALeastImpAttLabel 
 (Rank#)
ACALEASTIMPATTLABEL 
 (Rank#)
Returns label for the least important attribute. Rank# optional. Rank# of 2 returns second-least important attribute.
ACALeastImpAttValue
 (Rank#)
ACALEASTIMPATTVALUE
 (Rank#)
Returns attribute number of the least important attribute. Rank# optional. Rank# of 2 returns second-least important attribute number.
ACAMostImpAttLabel
 (Rank#)
ACAMOSTIMPATTLABEL
 (Rank#)