Using a Control File |
Top Previous Next |
Kicking off a file import or export with dbFile involves passing a number of switches and arguments to the executable program. For simple, one-off operations, that can be quick and handy. Even so, even the most minimal command line will include specifications for direction (import or export), the database path, the file specification for the import or export file and Firebird authentication credentials. For anything you might want to repeat, or for an operation with a lot more than the minimum options, you can prepare a control file in your favourite text editor. Supposing you had created a properly constructed control file named mydef.def, specifying the options for exporting data from a Firebird database, the following command is all that is required: dbFile -x mydef.def The -x switch, while available on POSIX platforms, is optional there. If it is omitted, the file is read via the stdin stream. Writing a Control File A control file comprises a set of options and an SQL INSERT statement. Options are specified in the control file using the marker keyword options with a range of keywords that equate to the corresponding command-line switches. You can mix options in the control file and the command line if you wish. Options specified in the control file overrule any switches passed in the command line. The control file may be any number of lines. Options lines come first: each line can be up to 4096 characters long. One and only one DSQL statement follows, consisting of any number of lines, with a maximum size of 4088 characters, including white space, embedded data qualifying attributes and commented sections. For an import, the control file may be written so as to embed the data for input. by including in a section after the SQL statement, headed up by a STARTDATA directive. The syntax for expressing an option is: options <keyword>[=<argument>] where <keyword> is one of a set of available keywords and <argument> is a valid argument for the specific keyword. The <, > and square brace symbols used here are not part of the syntax. Arguments are not quoted, even if they are strings. Space characters should not be inserted on either side of the "=" sign. Some options do not require an argument. For example, in options excel, the keyword excel stands alone to instruct the parser to conform to certain specific rules that apply to reading and writing .csv files generated by or for Microsoft Excel. In general, for options that do take arguments, the argument is required. Multiple options in a control file can be continuously "run-on" with no line breaks or can be broken up into separate lines to simplify editing. However, take note of some special rules that apply to option lines:
Minimum Options The minimum options are:
Login Credentials Both the user name and password must be supplied. If the ISC_USER and ISC_PASSWORD environment variables are available, the user name and password can be omitted. NOTE :: Mixing will NOT work. That is to say, if you supply just one of user name or password, and rely on an environment variable to complete the credentials, you'll get an authentication error. The SQL Statement The SQL statement follows all of the options lines.
The statement can occupy any number of lines in the control file. No special continuation characters are needed to continue a statement but words may not be split between lines as a space will always be added in between multiple lines of SQL. The "pound" (#) sign may be used on any option or SQL line to indicate that all characters to its right are to be ignored. Parsing will recommence at the start of the next line. CAUTION Parameters and Position Firebird parameter placeholders are positional, each represented by a questionmark (?), for example: UPDATE OR INSERT INTO COUNTRY (COUNTRY,CURRENCY) VALUES (?,?) For cases where the field order in the input file is different to that in the DSQL statement, an optional, 1-based position argument can be included in the statement to map the field position of each field of the file record to the field position in the statement's input list. The following example (normally unnecessary) expresses exact mapping for the statement above, where the input records have fields in the same order as the input list of the DSQL statement: UPDATE OR INSERT INTO COUNTRY ( COUNTRY {position=1}, CURRENCY {position=2}) VALUES (?,?) The following syntax enforces the mapping of the second field of the input record to the first parameter of the INSERT statement: UPDATE OR INSERT INTO COUNTRY ( CURRENCY {position=2},COUNTRY {position=1}) VALUES (?,?) NOTE :: This specific usage of the {position} specifier is for delimited record types. Fixed format records use it differently, as explained below under Fixed Position Text Records. Processing the Control File Processing the control file is no more than invoking the dbFile executable with the switch -x <path_to_control_file> For an example with simplified syntax, to execute a file named mydef.def in which you have set your options, call dbfile -x mydef.def In practice, of course you must abide by platform and shell rules for invoking executables from the command line and filesystem rules for accessing and expressing the path to the control file.
|