Table of contents:

• Definition
• Examples
  • 1. Import askiaweb interview data
  • 2. Import PKD data
  • 3. Import Dimensions data (here triple-S)
  • 4. Import SAV data
  • 5. Import Triple S XML data
  • 6. Merge interviews
  • 7. Delete interviews
  • 8. Compact and Repair
  • 9. Transform into loop
  • 10. Transform into multiple
  • 11. Export the datamap to a text file
  • 12. Import fixed length ascii data
  • 13. Export fixed length ascii data
  • 14. Export delimited ascii data
  • 15. Export delimited ascii data stored in SQL
  • 16. Export delimited ascii data stored in the inverted files
  • 17. Export SAV
  • 18. Export Triple S
  • 19. Export multimedia files
  • 20. Merge files using an ID
  • 21. Import from Excel / Access
  • 22. Import XML interviews
  • 23. Stacked Export
  • 24. Export SAV excluding questions
  • 25. Detect & create loops and multiples using regex
  • 26. Run a verification script
  • 27. Opening a live survey
  • 28. Create new data column on-the-fly in delimited ascii export
  • 29. Select questions to export based on their properties using `/questionselection`(from v5.6.0)
• Applying Commands to Multiple Files Quickly
• Use of batch files (with one command split across multiple lines)
• Return error codes

askiatools can be used via Command line which is extremely useful with askiavista's Scheduled Tasks.

Definition

Here the list of arguments which can appear in the command line to start askiatools:

/url:"https://MyServer/CcaWebAPI"

/username:"Supervisor"

/password:"Supervisor pwd"

/after:2019-10-01

/before:2019-10-01

/closeddk:999 

/datafile:"C:\ThisFile.xml"

/entrycodeformultiple:1

/Language:”FRA” 
/language:1036

/multipleseparator:”_”

/opensize:2048

/preservecase:1 

/respondentid:”Respondent.Serial”

/samesizeloopentrycode:1

/setquestion:"Q1" /setvalue="1"

/usefactors:1

/uselongcaption:1

/targetpassword:"password"

/targetUrl:"https://ServerName/CcaWebAPI" 

/targetUserName:"Supervisor"

Examples

1. Import askiaweb interview data

To import .dat files from the command line into a QES file use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /importdat /datafile:"c:\The directory with the .dat" 

2. Import PKD data

To import a .PKD files from the command line into a QES file use the following syntax:

Tools.exe "C:\my directory\My New Qes File.qes" /importpkd /datafile:"c:\my directory\pkdfile.pkd" 

3. Import Dimensions data (here triple-S)

To import a triple-S files from the command line into a QES file use the following syntax:

Tools.exe "d:\qes\res.qes" /importdimensions /datafile:"Provider=mrOleDB.Provider.2;Data Source=mrTripleSDsc;Location=d:\TripleS\P9.asc;Initial Catalog=d:\TripleS\P9.xml;Mode=ReadWrite;MR Init MDSC=mrTripleSDsc;" /pid:201 /"logfile:d:\qes\logfile.txt"

4. Import SAV data

To import a SAV files from the command line into a QES file use the following syntax:

Tools.exe "C:\my directory\My New Qes File.qes" /importsav /datafile:"C:\my directory\savfile.sav" 

To import a SAV files in inverted format from the command line into a QES file use the following syntax:

Tools.exe "C:\my directory\My New Qes File.qes" /importsav /inverted /datafile:"C:\my directory\savfile.sav" 

 5. Import Triple S XML data

To import a triple-S XML files from the command line into a QES file use the following syntax:

Tools.exe "C:\my directory\My New Qes File.qes" /importtriples /datafile:"c:\my directory\triplesfile.sss" 

6. Merge interviews

To merge interviews from the command line from one QES file to another use the following syntax:

Tools.exe "D:\Qes\ex1.qes" /mergeinterviews /"sourcepath:D:\Qes\ex2.qes" /mergetype:1 /delete /completesonly /preserveid /additionalfilter:"EndInterview < now - 14" 

Or with SQL data:

Tools.exe "C:\test\qes1.qes" /mergeinterviews /sourcepath:"C:\test\qes2.qes" /sourcesurveyconnection:"Provider=sqloledb; Data Source=XXXXXXX; Initial Catalog=Surveys;Trusted_Connection=no;User Id=XXXXXX;Password=XXXXX" /sourcesurveyid:123 /sourcetype:3 /mergetype:0

Or with webinterviews data :

Tools.exe "C:\test\qes1.qes" /mergeinterviews /sourcepath:"C:\test\qes2.qes" /sourcesurveyconnection:"Provider=sqloledb; Data Source=XXXXXXX; Initial Catalog=WebInterviews;Trusted_Connection=no;User Id=XXXXXX;Password=XXXXX" /sourcewebtable:"MyWebTable" /sourcetype:4 /mergetype:0

7. Delete interviews

To delete all complete and incomplete interviews from the command line from one QES file to another use the following syntax:

Tools.exe "D:\Qes\ex1.qes" /deleteinterviews /completes /incompletes /additionalfilter:"EndInterview < now - 14" 

Or with SQL data

Tools.exe "D:\Qes\ex1.qes" /surveyconnection:"Provider=sqloledb; Data Source=XXXXXXX; Initial Catalog=Surveys;Trusted_Connection=no;User Id=XXXXXX;Password=XXXXX" /surveyid:123 /type:3 /deleteinterviews /completes /incompletes /additionalfilter:"EndInterview < now - 14" 

8. Compact and Repair

To compact and repair your QES file from the command line use the following syntax:

Tools.exe "D:\Qes\ex1.qes" /compact

9. Transform into loop

To transform a serie of questions into a loop from the command line use the following syntax:

Tools.exe "D:\Qes\ex1.qes" /createloop /questions:"qa1_12;qa1_13;qa1_14" 

or

Tools.exe "D:\Qes\ex1.qes" /createloop /questions:"qa1_" 

10. Transform into multiple

To transform a serie of questions into a multiple closed question from the command line use the following syntax:

Tools.exe "D:\Qes\ex1.qes" /createmultiple /questions:"qa1_12;qa1_13;qa1_14" 

or

Tools.exe "D:\Qes\ex1.qes" /createmultiple /questions:"qa1_" 

11. Export the datamap to a text file

To export the datamap from the command line use the following syntax:

Tools.exe "D:\Qes\ex1.qes" /exportdatamap /datafile:"D:\Qes\datamap.txt" /detailed

12. Import fixed length ascii data

To import .asc files from the command line into a QES file use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /importfixedlength /datafile:"c:\The directory with the .asc" 

13. Export fixed length ascii data

To export .asc files from the command line from a QES file use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /Exportfixedlength /datafile:"c:\my directory\File.asc" 

14. Export delimited ascii data

To export .asc files from the command line from a QES file use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /exportdelimited /completes /sepquestion:; /sepresponse:, /datafile:"c:\my directory\File.asc" 

15. Export delimited ascii data stored in SQL

To export .asc files from the command line from a QES file with the data stored in SQL use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /exportdelimited /completes /sepquestion:; /sepresponse:, /type:1 /surveyconnection:"Provider=SQLOLEDB.1;Data Source=127.0.0.1;Initial Catalog=Surveys;Persist Security Info=False;UID=XXX;PWD=xxx" /surveyid:xxx  /datafile:"c:\folder\data.txt" /logfile:"c:\folder\log.txt" 

16. Export delimited ascii data stored in the inverted files

To export .asc files from the command line from a QES file where the data is stored in the inverted files use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /type:2 /exportdelimited /completes /sepquestion:; /sepresponse:, /datafile:"c:\my directory\File.asc" 

17. Export SAV

To export .sav files from the command line from a QES file where the data is stored in the QES files use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /exportsav /completes /datafile:"c:\my directory\File.sav" 

18. Export Triple S

To export .sss files from the command line from a QES file where the data is stored in the QES files use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /exporttriples /generate /completes /datafile:"c:\my directory\File.sss" 

19. Export multimedia files

To export collected multimedia files from the survey, use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /exportmultimedia /completes /datafile:"??shortcut????id??" /directory:"c:\my directory" /questions:"q1;q2" 

20. Merge files using an ID

To export collected multimedia files from the survey, use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /mergequestionnaireusingid /sourcepath:"C:\test\qes2.qes" /sourcetype:3 /sourcesurveyconnection:"Provider=sqloledb; Data Source=XXXXXXX; Initial Catalog=Surveys;Trusted_Connection=no;User Id=XXXXXX;Password=XXXXX" /sourcesurveyid:4 /idquestion:"myID"

21. Import  from Excel / Access

To import Excel files into a QES file use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /importado /datafile:"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\my directory\myfile.xlsx;Extended Properties=\"Excel 12.0 Xml;HDR=YES\"" /query:"SELECT * FROM [Feuil1$]" /maxdiscrete:100 /maxresponse:100 /inverted

22. Import XML interviews (from version 5.4.2)

To import XML interview files (AskiaFace for iOS / Android) e into a QES file use the following syntax:

Tools.exe "C:\my directory\My Qes File.qes" /importxmlinterviews /datafile:"C:\Interviews\Here"

23. Stack Export

To export a .qes file of level data use :

Tools.exe "C:\my directory\My Qes File.qes" /stackedexport /datafile:"C:\my directory\My Stacked File.qes" /definitionfile:"C:\my directory\Stacked Export Definition.xml"

24. Export SAV excluding questions (from version 5.4.8)

To export all questions except Q1, Q2 and Q3 use the following syntax :

Tools.exe "C:\my directory\My Qes File.qes" /exportsav /datafile:"C:\my directory\Output.sav /excludequestions:"Q1;Q2;Q3"

25. Detect & create loops and multiples using regex (from version 5.4.8) - The order of the questions does not matter i.e. they do not need to be consecutive in the .qes file

Ex1.

To create multiples from questions where alphanumeric string before '_' underscore marker is the same and text after is a number to denote response order in the multiple:

Tools.exe "C:\my directory\QesImportedFromSAV" /createmultiple /noyes /regex:"(.+)_[0-9]+"

e.g. this will group

• Questions RB93_1 through to RB93_20 into a multicode 'QRB93' with 20 codes
• Questions SA1_1 through to SA1_100 into a multicode 'QSA1' with 100 codes
• ... and continue to create more multiple questions with any groups of questions that match the pattern specified.

Ex2.

To create loops from questions where variable names end with "SLICE". Immediately before this there is a number to denote iteration order in the loop. Immediately before this there is some alphanumeric string for the variable names.

Tools.exe "C:\my directory\QesImportedFromSAV" /createloop /regex:"(.+)[0-9]+SLICE"

e.g. this will group

• Questions D15B1SLICE through to D15B10SLICE into a 10 iteration loop, 'Loop_D15B1SLICE' with child question, 'QD15B'.
• Questions SA-1SLICE through to SA-50SLICE into a 50 iteration loop, 'Loop_SA-1SLICE' with child question, 'QSA-'.
• ... and continue to create more looped questions with any groups of questions that match the pattern specified.

26. Run a verification script (from version 5.4.9)

To run a verification script use the following syntax :

Tools.exe "C:\my directory\EX.qes" /runverification /completes /definitionfile:"C:\my directory\MyScript.txt" /logfile:"C:\my directory\Output.txt /reducedsurvey

The ouput file looks like this

Asserts run: 400
Asserts failed: 201
Interviews run: 200
Interviews failed: 151

*** Line 1: 100 failed
   Interview 2
   Interview 3
   ...

*** Line 2: 101 failed
   Interview 2
   Interview 3
   ...

The process returns a value that can be read in powershell - it can be one of these

#define TER_NO_DATA_SELECTED                -5
#define TER_FILE_EXCEPTION                  -9    (cannot read source file)
#define TER_CANNOT_CREATE_TARGET_FILE       -7
#define TER_INVALID_DEFINITION              -6  (compilation error in script file)
#define TER_CANNOT_OPEN_SOURCE_SURVEY_DB    -1
#define TER_CANNOT_READ_SOURCE_INTERVIEW    -2

Any positive or zero value: the number of interviews which failed the verification process

27. Opening a live survey (from version 5.4.9)

To export to ASCII delimited a live survey (you no longer need to use the SQL connection strings to access the live data), use the following command line:

 Tools.exe /url:"http://ServerName/CcaWebApi" /username:"Supervisor" /password:"pwd" /surveyId:11 /exportdelimited /datafile:"c:\Qes\IhisOut.txt" /completes

28. Create new data column on-the-fly in delimited ascii export (from 5.4.9.4)

Create new data column on-the-fly in delimited ascii export which can access data from questions or individual responses conditionally by script.

You can add as many columns as you wish using the following syntax.

Tools.exe "C:\MyDirectory\EX.qes" /exportdelimited /completes /sepquestion:; /sepresponse:, /datafile:"C:\MyDirectory\MyExport.txt" questions:^i2_Age^ /addcolumn:"Male:^i1_Gender^ has {1}" /addcolumn:"Female:^i1_Gender^ has {2}"

29. Select questions to export based on their properties using `/questionselection` (from v 5.6.0)

Use the following command line to select open ended and date/time questions to ASCII delimited format

Tools.exe "C:\Qes\EX.qes" /type:0 /exportdelimited /completes /closedtype:2 /questionselection:"(CurrentQuestion.Type has {\"open\";\"datetime\"} )" /datafile:"C:\Qes\Myexport.txt" 

The syntax below selects questions with tags "Demog" + "LifeStyle" and opend ended with anonymised question to Askia survey QES file format

Tools.exe "C:\Qes\Me\ExportData\ex.qes" /exportqes /completes /datafile:"C:\Qes\Me\ExportData\ExportDataRes.qes" /questionselection:"(CurrentQuestion.Tags Has {\"Demog\";\"LifeStyle\"} or CurrentQuestion.Type = \"open\") And (CurrentQuestion.IsAnonymised = False)" /additionalfilter:"i1_Gender = 1"

The same selection can be exported to Askia survey inverted format

Tools.exe "C:\Qes\Me\ExportData\ex.qes" /exportinverted /completes /datafile:"C:\Qes\Me\ExportData\ExportDataInv.qex" /questionselection:"(CurrentQuestion.Tags Has {\"Demog\";\"LifeStyle\"} or CurrentQuestion.Type = \"open\") And (CurrentQuestion.IsAnonymised = False)" /additionalfilter:"i1_Gender = 1"

And to Askia survey inverted field (SQL) format

Tools.exe "C:\Qes\Me\ExportData\ex.qes" /exportfield /targetUrl:"http://127.0.0.1/ccawebapi" /targetUserName:"Administrator" /targetPassword:”pwd" /completes /datafile:"NewExport" /questionselection:"(CurrentQuestion.Tags Has {\"Demog\";\"LifeStyle\"} or CurrentQuestion.Type = \"open\") And (CurrentQuestion.IsAnonymised = False)" /additionalfilter:"i1_Gender = 1"

Applying Commands to Multiple Files Quickly

To apply the same command to multiple files, one option is to use FORFILES from the command line. For example, to delete all interviews from all .qes files in the current directory and sub-directories, use the following:

FORFILES /S /M *.qes /C "cmd /S /C ^0x22C:\Program^ Files^ ^0x28x86^0x29\Askia\Tools.exe^0x22 @PATH /deleteinterviews /completes /incompletes" 

Note the use of the ASCII code 0x22 to indicate quotes in the command line path. Similarly, 0x28 and 0x29 are used for opening and closing parentheses. These are necessary because the location of the AskiaTools executable is not added to the PATH variable of the server. The typical location (on an x64 version of Windows) is "C:\Program Files (x86)\Askia".

Multiple commands can be included by using an ampersand - & - separator. For example:

FORFILES /S /M *.qes /C "cmd /S /C ECHO @PATH & ^0x22C:\Program^ Files^ ^0x28x86^0x29\Askia\Tools.exe^0x22 @PATH /deleteinterviews /completes /incompletes" 

Use of batch files (with one command split across multiple lines)

If you wish to keep a record of the command you use or wish to re-run it we suggest you create a batch (.BAT) file that contains the command(s). You may find the .BAT file easier to read and maintain if you split long command lines across several lines within the file. The general idea is that the ^ character indicates the next line will be a continuation.

So, for example, this command...

Tools.exe "D:\Qes\ex1.qes" /compact

..could appear in a .BAT file across 3 lines like this...

Tools.exe ^
"D:\Qes\ex1.qes" ^
/compact

However, if you need to split anything that appears within speech-marks across several lines it is a little more complicated. In that instance you will need a command in your .BAT file to indicate this is the case AND include some additional characters.
So, for example, this command...

Tools.exe "xtest.qes" /createmultiple /questions:"ANSWER_1;ANSWER_2;ANSWER_3;ANSWER_4;ANSWER_5"

...would require a .BAT file that looked like this...

setlocal EnableDelayedExpansion
Tools.exe "xtest.qes" ^
/createmultiple ^
/questions:"ANSWER_1;!"=!^
ANSWER_2;^
ANSWER_3;^
ANSWER_4;^
ANSWER_5"

For more information, you may find this article useful.

Return error codes

Add this on a new line after your command has run to capture the error code in the command window:

cmd /k echo Exit Code is %errorlevel%

The process can return the values below. For more information, you may find this article useful.

#define TER_CANNOT_OPEN_SOURCE_SURVEY_DB       -1
#define TER_CANNOT_READ_SOURCE_INTERVIEW       -2
#define TER_CANNOT_WRITE_INTERVIEW             -3
#define TER_UNKOWN_EXCEPTION                   -4
#define TER_NO_DATA_SELECTED                   -5
#define TER_INVALID_DEFINITION                 -6
#define TER_CANNOT_CREATE_TARGET_FILE          -7
#define TER_CANNOT_LIST_SOURCE_INTERVIEWS      -8
#define TER_FILE_EXCEPTION                     -9
#define TER_EXECUTION_ERROR                    -10
#define TER_LOGIN_REFUSED                      -11
#define TER_SURVEY_NOT_FOUND                   -12
#define TER_INVALID_SURVEY_FILE                -13

#define TER_UNKNOWN_QUESTION                 -101
#define TER_INCOMPATIBLE_QUESTION            -102
#define TER_CANNOT_READ_SOURCE_FILE          -103