Use of the new optional parameter -q will then require that a configuration file be indicated along with the ID of the query within the configuration file to execute. The -q will use the dataset parameter to indicate where the output files will be located as it does today. However, the dataset directory will not be cleared when running with the -q as it is otherwise. Only one of the -t, -x, or -q flags can be used at in a single db_snapshot command. The -p is irrelevant with the -q because multiprocessing is not possible and therefore it will be ignored if included.

The configuration file must be placed in the environment's $udata directory. The configuration file must have bcpqry as its extension. Enter the configuration file name without the .bcpqry extension, after the -q flag. Immediately following the configuration file name in the db_snapshot command there must be a colon (:) followed by the ID of the query to be executed. For example, if the configuration file is named foo.bcpqry and the ID of the query to be executed is '29', the db_snapshot command will have -q foo:29 as parameters.

• <ID> query-id
  • ID of the query.
  IDs do not need to be in any particular order. If an ID is repeated in a subsequent query block, the first query block with a matching ID found will be used.
• <FILENAME> filename base
  • base name to use for the output file name.
  The file name may be a table name but will not be validated as an actual valid table in the database and will not be verified to match a table in the query either. The file name cannot be identical to another file name run in parallel if it will be placed in the same dataset. In this case an additional component may be needed such as in rls.1, rls.2, rls.n, etc.
• <SQL> sql-query
  • SQL query beginning with "select .
  Long queries may wrap over several lines, as long as the <SQL> keyword and the start of the query "SELECT are on the same line, and the constraint of line length (see above) is not violated. The query must be surrounded by double quotes (") and any nested quotations within the query must alternate between single quotes (') and double quotes ("). The quotation mark characters must be ASCII 0x27 (') (&apos;) and 0x22 (") (&quot;). Smart quotes will be misinterpreted and cause an error.
• The configuration file may also include comments by preceding them with a !, #, or ;. This can only be done on a separate line and cannot be added to the end of a line in the configuration file. See example below.
• Each query-block is terminated by the keyword <END>. This keyword also serves to terminate the SQL statement. The keyword <END> must occur as the first non-white characters on the line on which it occurs. Any text on that line after the <END> keyword is a syntax error.
• Conventionally, there is at least one line of whitespace between the <END> of one query block and the <ID> of the following block. This is optional, however. Comments and lines of whitespace are ignored by the parser used by db_restore.

These elements must be in the above order. They can be repeated in this order up to 49 times. The total text of an individual query block, <ID> through <END>, must be < 2048 characters. Each line must be < 200 words. A word is defined as a string of characters separated by whitespace at the beginning and end. Each word must be < 30 characters.

Whitespace consists of any unquoted occurrence of one or more characters from the set of space, horizontal tab, vertical tab, formfeed, newline, carriage return (0x20, 0x09, 0x0B, 0x0C, 0x0A, 0x0D).

	<ID> base 
	<FILENAME> rtx 
	<SQL> "select * from rtx" 
	<END> 
	
	<ID> delta 
	<FILENAME> rtx 
	<SQL> "select rtx.* from rtx, ras 
	where rtx.por_s = ras.por_s 
	and (rtx.d_run_s > ras.d_prev_cmplt_day_s 
	or (rtx.d_run_s = ras.d_prev_cmplt_day_s 
	and rtx.t_run_s > ras.t_prev_cmplt_day_s))" 
	<END> 
	
	<ID> rlsgroup1 
	<FILENAME> rls.1 
	<SQL> "select * from rls where por_s <= '50'" 
	<END> 
	
	<ID> rlsgroup2 
	<FILENAME> rls.2 
	<SQL> "select * from rls where por_s > '50'" 
	<END> 
	
	<ID> rlsagroup1 
	<FILENAME> rlsa.1 
	<SQL> "select rlsa.* from rlsa, rls 
	where rlsa.lse_s = rls.lse_s and rls.por_s <=; '50'" 
	<END>

	<ID> rlsagroup2 
	<FILENAME> rlsa.2 
	<SQL> "select rlsa.* from rlsa, rls 
	where rlsa.lse_s = rls.lse_s and rls.por_s > '50'" 
	<END> 

The output file(s) created by db_snapshot -q will be located in the dataset sub-directory (see About Datasets specified in the db_snapshot command. The files will be named using the structure of filename.yyyymmdd.pbcp.# where filename is the value for <FILENAME> in the configuration file, yyyymmdd is the current date at the beginning of the script execution, and # is the sequence number. The sequence number will begin at 1 and be incremented by 1 for each subsequent segment created, but no number will be added if only one file is created. No segment can be greater than 2GB and, therefore, larger output will be segmented into separate files using the sequence number to create unique names. For example rtx.20130329.pbcp will be the first file created when the filename is rtx and it is run on March 29, 2013. If multiple files need to be created due to more than 2GB the first file will be renamed using the sequence number "1".

This description of when a new file is added to a large table export, is approximate. We can say that each segment will end immediately after the record terminator of the record whose contents pushed the file over the 2-billion byte limit. Since it is very unlikely that a single row in any table will exceed the 147MB of padding available between 2 billion and 2 GB, we can safely say that no export file will exceed 2GB. See About Datasets.

When running db_snapshot -q, the script will first check the designated dataset directory to determine if any files exist which begin with the same filename and date as this run intends to use. In the example of a file named rtx.20130329.pbcp.1, the filename is rtx and the date is 20130329, so db_snapshot will check for any files named rtx.20130329.pbcp* before executing. If a file beginning with this name is found, db_snapshot will abort, and no further snapshot files will be created. Otherwise the processing will continue as described.