Project Name VieleRETS 1.1
Publication Name Configuration Guide
Publication Date May 2006
Maintainer mlesswing@realtors.org
Configuration Guide Table of Contents
5.0 Command Line Usage
The package can also be executed from the command line with either interactive or batch file control. The same script is called for both purposes and is called {INSTALLATION_DIRECTORY} /run_interactive_job.php. Usage notes for each mode are included below.
Interactive Control
The package can be executed from the command line and you will be prompted for the following items if you do not supply any arguments:
  • EXTRACT - The name of Extract to use. This information is required. If you do not specify a value, processing stops.

  • QUERY_VALUE - You will be prompted for a value for each available query field in DMQL notation. If no information is supplied, the package generates a NULL query.
To suppress HTML artifacts generated by PHP, a suggested execution of the script would look like: php -f ./run_interactive_job.php Note the use of the -f flag to denote the script. You could also run the script with the -q flag (quiet mode) like this: php -q ./run_interactive_job.php With the setting of the register_argc_argv to Off (to increase performance) in the php.ini file it is possible to cause errors when running from the command line. To bypass the php.ini file you can include the -n argument when calling the tools this looks like: php -n -f ./run_interactive_job.php or php -n -q ./run_interactive_job.php
Batch File Control
A Batch Control File is created for for each extract and is located in an XML formatted file found at {INSTALLATION_DIRECTORY} / {BCF_DIRECTORY} /{EXTRACT_NAME}. By default, the QUIET and UPDATE_ONLY tags are commented out.

The following items are specified in a Batch File Control:
  • EXTRACT - The name of Extract to use. This element is required.

  • QUERY_VALUE - You should include one tag for each element you want to be used. The attribute name is used to identify the element. The data for the tag is the query value in DMQL notation. The element is not required. If no tags are specified, the package generates a NULL query. If you specify an attribute type and set it to the value ADVANCED, the tage value will override any other QUERY_VALUE tags. Using this Advanced Query capability is entirely a manual process only achieved by editing the Batch Control File by hand.

  • QUIET - The presence of this tag denotes that only error messages should be sent to standard output. You should include this tag if you plan to use that package with packages like cron. By default, this tag is commented out.

  • UPDATE_BCF - The presence of this tag denotes that the Batch Control File should be updated from the Interactive Mode. By default, this tag is not commented out.

  • UPDATE_ONLY - The presence of this tag denotes that only listings that have changed since the LAST_RUN date will be fetched. You should include this tag if you plan to use that package with packages like cron and you only want "deltas". By default, this tag is commented out.

  • LAST_RUN - The timestamp of the last successful fetch. This value is updated by both the command line and browser-based modes.

  • LIMIT - The number of records to fetch. This value is updated by both the command line and browser-based modes and overrides settings from the EXTRACT definition.
The package will be executed from the command line using the contents of the Batch Control File for script input. To suppress HTML artifacts generated by PHP, a suggested execution of the script would look like: php -f ./run_interactive_job.php batch_control_files/Default Note the use of the -f flag to denote the script. you could also run the script with the -q flag (quiet mode) like this: php -q ./run_interactive_job.php batch_control_files/Default
Advanced Query Processing
The GUI supplied with the package can be limiting to some power users. Complex queries cannot be defined. If you know the RETS DMQL language, complex queries can be defined directly in the Batch Control File. To take advanatge of this Advanced Query feature, you will need to make manual changes to the Batch Control File.

I typical Batch Control File might look like this: <VIELE_BATCH> <EXTRACT> Default </EXTRACT> <UPDATE_BCF/> <QUERY_VALUE name="ListingID"> </QUERY_VALUE> <LAST_RUN> 2006-05-09T17:33:35 </LAST_RUN> </VIELE_BATCH> Because no value is specified for the "ListingID" argument, all listings would be returned.

With the addition of a single line, the Advanced Query feature can be invoked. Adding a QUERY_VALUE tag with an attribute called type set to ADVANCED directs the package to disregard all subsequent query processing information. An example of a Batch Control File that has been altered to use the Advanced Query feature is: <VIELE_BATCH> <EXTRACT> Default </EXTRACT> <UPDATE_BCF/> <QUERY_VALUE type="ADVANCED"> (ListingID=localhost-101) </QUERY_VALUE> <LAST_RUN> 2006-05-09T17:33:35 </LAST_RUN> </VIELE_BATCH> In this example, the user has used the Advanced Query feature to change the query to return only a single listing, in this case, the listing with the MLS ID "localhost-101".

It is important to note that Batch Control Files altered in this way override all GUI processing as well. Once manually modified, changes to queries specified with the GUI have not effect.
Configuration Guide Table of Contents