Scroll

Command line in Askiatools

Follow
Summary This article describes how to automate task by command line in askiatools.
Applies to askiatools
Written for Data processor
Keywords command line; automate; task; tools; askiatools; commandline

Table of contents:


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:

Argument Value Description
{None} String Path of survey file, QES, specificed between quotes "
/type: Integer Defines the type of survey and/or data, for example:
0: QES
1: in SQL Server (Legacy format)
2: inverted data format
3: Data stored in SQL Server (new SQL format)
4 : Data stored in WebInterviews SQL database
/singletable - flag used when importing data from a SQL server in the new SQL format (deprecated, prefer using type)
/surveyId: Integer Defines the id of survey, when the data are stored in the SQL Server. You also need to fill the surveyConnection parameter. For example: /surveyId:119
/surveyConnection: String Defines the connection string to the survey data (SQL Server), for example:/surveyConnection:"Provider=SQLOLEDB.1;Persist Security Info=False;
User ID=UID;password=PWD;Initial Catalog=Surveys;Data Source=127.0.0.1"
/importprylos - flag used to request an import of askiamobile interviews.
The actual XML file should be specified in the datafile parameter
/importdat - flag used to request an import of askiaweb .dat interviews.
The actual directory should be specified in the datafileparameter
/importpkd - flag used to request an import of a PKD file into inverted QES.
The actual PKD file should be specified in the datafileparameter
/importdimensions - flag used to request an import of any SPSS dimensions file 
into inverted QES. The actual Dimensions connection string should be specified in the datafile parameter
/importtriples - flag used to request an import of a XML triple-S file.
The tripleS file should be specified in the datafile parameter
/importsav - flag used to request an import of a SPSS sav file S file.
The sav file should be specified in the datafile parameter.
The following parameters can be used : datafile, inverted, noscaled
/mergeinterviews - flag used to request a merge of interviews QES.
The following parameters can be used : 
sourcepath,sourcesurveyconnection, sourcesurveyid,
mergetype, delete, preserveid, completesonly, additionalfilter
/deleteinterviews - flag used to request a deletion of interviews QES.
The following parameters can be used :
completes, incompletes, additionalfilter, before, after
/exportfixedlength - flag used to request an export in ASCII fixed length using the simplified data-map. The following parameters can be used :completes, incompletes, additionalfilter, datafile, before, after
/importfixedlength - flag used to request an import in ASCII fixed length using the simplified data-map. The following parameters can be used :datafile
/exportdelimited - flag used to request an export in ASCII delimited.
The following parameters can be used : 
completes, incompletes,additionalfilter, 
datafile, sepquestion, sepresponse, 
closedtype, questions, unicode, before, after, multipleasbinary, semiopen, repeatmultipleseparator
/importdatadelimited - flag used to request an import into an existing QES file.
The following parameters can be used : 
datafile, sepquestion,sepresponse, closedtype, alwayspoint
/exportsav - flag used to request an export in SAV format.
The following parameters can be used : 
completes, incompletes,additionalfilter, datafile, preventreindexing, keepunderscore, prefixloopitems, exportdkasnormal, before, after
/exporttripleS - flag used to request an export in tripleS (2.0) format.
The following parameters can be used : 
completes, incompletes,additionalfilter, datafile, before, after
/exporttiming - flag used to request an export of the timing of the questions.
The following parameters can be used : 
completes,incompletes, additionalfilter, datafile, idquestion, before, after
/runedits - flag used to request a run of the edits
/overwrite - flag used to request an overwrite using a question ID and an ASCII file. The following parameters can be used : 
datafile,idquestion, sepquestion, sepresponse, closedtype
/overwritewithtable - flag used to request an overwrite of a question using a matching ASCII table. The following parameters can be used : datafile, sepquestion, sourcequestion, targetquestion, and for the selection of interviews: completes, incompletes,additionalfilter, datafile, before, after
/overwritewithsql - flag used to request an overwrite of a question using a matching SQL table. The following parameters can be used : datafile (the connection), query, sourcequestion, targetquestion, and for the selection of interviews: completes, incompletes,additionalfilter, datafile, before, after
/createloop - flag used to transform a set of questions into a loop.
The following parameters can be used : 
questions, inverted,modalities, questioncaption, shortcut, delete
/createmultiple - flag used to transform a set of questions into a multiple question.
The following parameters can be used : 
questions,inverted, modalities, questioncaption,
shortcut, delete, noyes
/noyes - flag used to specify if the multiple in createmultiple are defined as No / Yes instead of Yes / No (default)
/createclosed - flag used to transform a numeric or open-ended question into a closed question.
The following parameters can be used :
questions, inverted, questioncaption, shortcut, delete, nohide
/exportdatamap - flag used to export the simplified datamap of a survey.
The following parameters can be used : 
datafile, detailed
/compact - flag used to request a compact and repair of QES file.
/analyseincompletes - flag used to request a report on drop outs.
The following parameters can be used : 
completes, incompletes,additionalfilter, datafile, before, after
/deleteduplicates - flag used to request a removal of duplicates matched by seed, agentID and start interview
/markasincomplete - flag used to request that a selection of interviews to be marked as incomplete (logical deletion).
The following parameters can be used : 
additionalfilter, setquestion, setvalue, before, after
/markascomplete - flag used to request that a selection of interviews to be marked as complete.
The following parameters can be used : 
additionalfilter, setquestion, setvalue, before, after
/exportmultimedia - flag used to export multi-media files (pictures, sounds, etc..) from open-ended questions (in parameter questions) into a directory (parameter directory) using the datafile naming pattern .
The following parameters can be used :
additionalfilter completes incompletes, before, after
/runmacro -

flag used to request the run of a macro to create mutliple question and loops.
The following parameters can be used :
datafile, isExitOnError,isForceOnError

/importinnewlevel  -

flag used to request the import of a survey into a new level. The matching is done using a question whose shortcut is defined in the parameter 'idquestion". The new loop's shortcut is defined by the parameter "shortcut" .
The following parameters can be used : idQuestion, shortcut, sourcepath, sourcetype, sourcesurveyconnection, sourcesurveyid

/mergequestionnaire  -

flag used to merge two surveys which have the same number of interviews .
The following parameters can be used : sourcepath, sourcetype, sourcesurveyconnection, sourcesurveyid

/mergequestionnaireusingid  -

flag used to request the import of a survey and data with an ID into a new level. The matching is done using a question whose shortcut is defined in the parameter 'idquestion".
The following parameters can be used : idQuestion, sourcepath, sourcetype, sourcesurveyconnection, sourcesurveyid

 /executequery -

flag used to run one more more query for a selection of interviews in any database. The following parameters can be used : datafile (the connection), query and for the selection of interviews: completes, incompletes,additionalfilter, datafile, before, after

/datafile: String Used to specify the additional file or directory or DB connection, for example:
 /datafile:"C:\ThisFile.xml"
/sourcepath: String Used to specify the source QES file
/sourcesurveyconnection: String Used to specify the source QES connection string if the data is in SQL server
/sourcesurveyid: Integer Used to specify the id of the source survey if the data is in SQL server
/sourcetype Integer Used to indicate the type of the source file (See parameter type)
/mergetype: Integer 0,1 or 2 to specify which merge is used
(Assume questionnaires are superposable, Using shortcuts and entry codes, Using internal question and response ids...)
/delete - flag used to indicate if the interviews should be deleted after having been moved when using mergeinterviews. Indicate that the source questions should be deleted when using createloop, createmultiple or createclosed
/preserveid - flag used to indicate if the IDS of the interview should be kept
(and not the auto increment property)
/completesonly - flag used to indicate if only completes should be imported
/additionalFilter: String script to specify which interviews are selected
/logfile: String path of the file that should be used as a logfile for reporting errors
(errors will be appended at the end)
/pid: String Process ID : an identifier that will be used when reporting error in the logfile
/completes - flag used to indicate if the selection should include the completes
(used by deleteinterviews, exportfixedlength, exportdelimited, exporttiming)
/incompletes - flag used to indicate if the selection should include the incompletes
(used by deleteinterviews, exportfixedlength,exportdelimited, exporttiming)
/idquestion: String A shortcut for the question used as an ID
(used by exporttiming, overwrite, importinnewlevel, mergequestionnaireusingid)
/sourcequestion: String A shortcut for the question used as source (used in overwritewithtable and overwritewithsql)
 /targetquestion: String A shortcut for the question used as target (used in overwritewithtable and overwritewithsql)
/sepquestion: String A string to specify the question separator in an ASCII file
(tab by default) (used by overwrite, overwritewithtable, exportdelimited)
/sepresponse: String A string to specify the response separator for a multiple question in an ASCII file
(tab by default)
(used by overwrite,exportdelimited)
/multipleasbinary - indicates that the multiple questions are exported as separate questions for each responses (0/1) (used by exportdelimited)
/semiopen - indicates that a field is added to export semi-open questions (used by exportdelimited)
/repeatmultipleseparator - always export the same number of separators for multiple questions (used by exportdelimited)
/closedtype: Integer

A number to indicate how closed modalities are identified :
0 = order, 1 = caption, 2 = entry codes, 3 entry codes numeric

(Update: 1 = order, 2 = caption, 3 = entry codes, 4 entry codes numeric)

/inverted - flag used to indicate if the data should be read or written from / into the inverted data format
(used by importtriples,importsav, createloop, createmultiple, createclosed, importado )
/systemdk: String A string to specify which responses (separated by ;) will be set with a Don't Know base type
(used by importpkd,importdimensions and importtriples)
/groupdk - flag to indicate that all modalities defined in systemdk should be coded as the system DK (code -1)
(used by importpkd,importdimensions and importtriples)
/numericDK String flag to indicate if a numeric value should be interpreted as a system DK ( used by  importpkd and importdimensions)
/prefixsubquestions - flag to indicate that sub-question will be prefixed by their parent chapter or loop (used by importpkd and importdimensions)
/questions: String A string to specify which questions will be used: you can use a prefix and all questions whose shortcut start by this will be selected or you can separate shortcuts by;
(used by exportdelimited, createloop, createmultiple, createclosed, exportmultimedia and exportsav [from v5.4.6.0]))
/questioncaption: String A string to specify the caption of the question created by createloop, createclosed and createmultiple
/shortcut: String A string to specify the shortcut of the question created by createloop, createclosed, createmultiple, importinnewlevel
/modalities: String A string to specify the modalities (string ; separated) or the loop items of the question created by createmultiple or createloop
/directory: String A string to specify where the files will be generated.
Used exportmultimedia
/detailed - flag used to indicate if the export indicates the modalities
(used by exportdatamap)
/generate - flag used to indicate if the datamap should be generated if not present (it's not saved)
(used by exportfixedlength andexportdatamap)
/noscaled - flag used to indicate that the imported single questions should not be marked as scaled
(used by importsav)
/nohide - flag used to indicate that the used questions are not hidden in analyse, if delete is not used
(used by createclosed)
/unicode - flag used to make sure the data is exported in Unicode
(used by exporttriples and exportdelimited)
/alwayspoint - flag used to make sure the decimal point is always . a not a comma in French for instance
(used by exportdelimited,importdatadelimited )
/preventreindexing - flag used to prevent shortcuts being incorrectly reindexed (https://dev.askia.com/issues/5906)
(used by exportsav)
/exportdkasnormal -

flag to prevent system closed DKs to be exported as 0 (used by exportsav)

/keepunderscores - flag used to ensure the underscores are kept in the shortcuts (used by exportsav )
/prefixloopitems - flag used to prefix captions with loop items (https://dev.askia.com/issues/4611) (used by exportsav )
/setquestion String

shortcut of the question that will be updated when the interview is marked as complete / incomplete (used by markascomplete,markasincomplete )

/setvalue String

value taken by the question that will be updated when the interview is marked as complete / incomplete (used by markascomplete,markasincomplete )

/opensize Integer

The command line default is set to 1024 since Askia Tools 5.3.3.5 (12/08/2014). In previous versions it is set to 255. N.B. Any open enders longer than the open ender size will be CLEARED and not truncated, therefore you must ensure the size you have declared is large enough. Usage example: /opensize:2048

/after String

Indicates that only interviews whose start interviews is after the indicated string are selected (used by exporttriples, exportfixedlength, exportsav, exporttiming, exportdelimited, analyseincompletes, exportmultimedia, deleteinterviews, markascomplete, markasincomplete)

/before String Indicates that only interviews whose start interviews is before the indicated string are selected (used by exporttriples, exportfixedlength, exportsav, exporttiming, exportdelimited, analyseincompletes, exportmultimedia, deleteinterviews, markascomplete, markasincomplete)
/exitonerror  - Flag used to indicate that the run should be interrupted if an error is encountered (used by runmacro)
/forceonerror  - Flag used to indicate that the errors should be ignored (used by runmacro)
/importado  - Flag used to indicate an ADO importation

/query:

String

Indicates the SQL query used during the ADO importation (used by importado and overwritewithsql)

/maxdiscrete Integer

Indicates the maximum number of discrete values, above which the imported question will be considered a numerical question (default 10) (used by /importado)

/maxresponse Interger

Indicates the maximum number of responses, above which the imported question will be considered a closed question (default 20) (used by /importado)

/webtable String

Indicates the webinterview SQL table to use when exporting data from WebInterviews (used by /type:4)

/sourcewebtable String

(used by /type:4, /sourcesurveyconnection, /ImportInNewLevel, /MergeQuestionnaire, /MergeQuestionnaireusingID)

/importxmlinterviews
 -  Flag to import XML interviews
/stackedexport
 - Flag used to request an export of stacked (level) data. Only works with predefined xml stacked export definition. The following parameters are required: definitionfile, datafile.
/definitionfile: String Stacked export xml definition file.


Examples

1. Import askiaweb interview data

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

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

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

Or with SQL data:

AskiaToolsU.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:3 /mergetype:0

Or with webinterviews data :

AskiaToolsU.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" /mergetype:4

7. Delete interviews

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

AskiaToolsU.exe "D:\Qes\ex1.qes" /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:

AskiaToolsU.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:

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

or

AskiaToolsU.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:

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

or

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

AskiaToolsU.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:

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

23. Stacked Export

To export a .qes file of level data:

AskiaToolsU.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"

 

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\AskiaToolsU.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\AskiaToolsU.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...

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

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

AskiaToolsU.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...

AskiaToolsU.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
AskiaToolsU.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

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

#define TER_NOERROR 0
#define TER_CANNOT_OPEN_SOURCE_SURVEY_DB -1
#define TER_CANNOT_READ_SOURCE_INTERVIEW -2
#define TER_CANNOT_WRITE_INTERVIEW -3
#define TER_INVALID_DEFINITION -6
#define TER_CANNOT_CREATE_TARGET_FILE -7
#define TER_CANNOT_LIST_SOURCE_INTERVIEWS -8

 

Have more questions? Submit a request

Comments