Using the Command Line

Top  Previous  Next

Of course, dbFile is a command-line utility:  that is, it is designed to be run from a command shell.  Invoking dbFile with the -x switch pointing to a well-thought-out control file is the most natural and sturdy way to perform your import or export.  If you are operating on a Windows platform, it is the only way to use dbFile. 

But, even if your platform is not Windows, the control file approach is recommended, especially if you plan to repeat similar operations.  As explained earlier, the typing at run-time is minimal and you have a much better chance of specifying the operation correctly and completely.

Using the Command Line Without a Control File

On POSIX platforms, including MacOSX, an import from or export to a delimited file may be done directly from the command line, without using a control file.  Those who habitually write scripts to accomplish tasks on these platforms will find equivalents to virtually all of the descriptor options available for control file usage.  As well as each of the minimum options described for usage in control file mode, dbFile has switches to enable you to pass the attributes applicable to delimited file imports or exports.  They are described in their entirety, along with all of the control file options, in the next section, List of Options and Switches

Command Format

The format for the "raw" invocation of dbFile is the same as when invoking it with a control file except that, while there is no -x switch, there will be a number of other switches, along with their arguments.  Following the switches is a block of redirected data wrapped in a pair of alphanumeric symbols invented by you (avoiding any symbols that are significant to the shell parser, of course!).  For example, you could use the characters 'EOF' or 'XYZ' as the marker for your block.  The dots in the following patterns are standing in for your actual content.

dbfile ....<<EOF

...content...

EOF

dbfile ....<<XYZ

...content...

XYZ

What you include in your block is up to you.  In the simplest case it would be just your SQL SELECT or DML statement;  but it could also include options directives (ahead of the SQL) and even a STARTDATA block following the SQL statement.  The same rules of placement that apply inside a control file also apply inside your redirected block.

The Essential Switches

The "essential" switches are the ones that are required to specify a non-control import or export from or to a delimited file.  Each consists of an alphabetic character preceded by a hyphen, e.g. -u, followed by a space followed (in most cases) by an argument.  For example:

dbfile -u sparky -p icuryy4me  

Switches can be lower or upper case on any platform;  that is, a lower case letter and its ANSI upper case equivalent are semantically identical for switches.  The same may or may not be true for the argument!  Arguments are unquoted.

User Authentication Switches

Switch

Argument

Comments

Options Equivalent

-u

User name

Valid Firebird user name.  The user must be one that has the appropriate privileges to the database tables and/or objects that will be accessed by the DSQL statement.  Case-insensitive unless the user was created in double-quotes AND has any characters that are not 7-bit upper-case.

USER=

-p

Password

Valid password for the user name.  Always case-sensitive.

PASSWORD=

 

If the environment variables ISC_USER and ISC_PASSWORD are available, or you are on a POSIX server logged in as root, then these switches are optional.

On a POSIX server where system UIDs have authentication profiles in the Firebird security database, the system user login should be sufficient.


Data-related Switches

Switch

Argument

Comments

Options Equivalent

-db

A string

Full qualified path or alias to the database, according to platform, server model and whether it is local or remote.

Don't forget that, on POSIX, a local connection cannot be made if the server is Superserver and, on Windows, Classic 1.5.x versions cannot take a local connection.

DB=

-i or -o

A file specification (string)

The argument is the qualified or relative path to the input file if the switch is -i or the output file if the switch is -o.

DIRECTION=
together with
FILE=

-c

Single character
or xNN

Character that is used as the field delimiter in the input record or is to be used as the field delimiter in the output record.  You may use xNN hex notation for special characters; e.g. x08 for tab

DELIMITER=

-n

A whole number

Number of variables in the input or output record.  For output it may be a '?' but it should be escaped to ensure it is ignored by the parser.

VARIABLES=

-t

A character set identifier

Sets the client character set.  NAME is the identifier or alias of a character set known to the database

CHARSET=


More switches are described in the next section.

For delimited files, using the command line alone may be sufficient. However, note that

unless the -c and -n switches are used for delimited file input, a control file must be used to specify options.
all options specified in a control file override any equivalent arguments specified in the command line call

The SQL Statement

The SQL statement should be the first (or only) content in the redirected block.  If you happen to incorporate the actual data in your command, the STARTDATA directive must follow the SQL statement on a line of its own.

The following illustrates a "quick and dirty" call from the command line on POSIX to load a trivial set of data on the fly:

echo "let us try some silly load stuff"

dbFile -n 2 -i -d /tmp/mydb.fdb ..... -c '|' <<EOF 

insert into fubar (foo, bar) values (? ?) 

STARTDATA 

monkey|shine 

blue|moon 

sick|input 

crazy|text 

EOF

echo "we just loaded some silly data"

Special Characters

Characters such as brackets, semi-colon, colon, comma, parentheses, single or double quotes, questionmark or the pipe symbol (vertical bar) may have to be escaped on the command line, if the same characters are syntactic elements of the command shell interpreter.

Escaping Shell-Sensitive Characters

"Escaping a character" means inserting another special character, before the shell-sensitive character to tell the command shell interpreter to ignore its syntactic significance and treat it as a literal.  The inserted character and the character it operates on are together referred to as "an escape sequence". 

SQL users may be already familiar with "escaping" literal single-quote characters by preceding them with another single quote, a convention sometimes referred to as "doubling".  The concept is similar, but command shells do not use doubling.  Instead, they use a specific character that is reserved as the escape character.

In most POSIX shells, including MacOSX, the escape character is the backslash (\)
In the Windows command shell the escape character is the caret (^)

Line Break Characters

Both carriage return (CR) and newline (NL) alias linefeed (LF) are very special characters.  One or the other, or both, are used as line terminators.  Which one depends on the operating environment.  On Windows, a line break consists of both CR and LF, in that order. On POSIX, including the MacOSX text terminal, it is a NL alone.  In the original Macintosh operating system it was CR alone.  On a MacOSX system, the GUI terminal might be configured to conform with the text command shell or with other GUI applications, which still use the native Macintosh convention.

Delimited Input Files

Since string data might contain embedded line terminators of either kind, there can be problems for output as well as for input files.Text blob files are handled correctly, but delimited input files with embedded line breaks will cause fatal problems. 

Be aware that, for delimited input files, dbFile does not have a catch-all solution for the problem of embedded line breaks. It remains the user's responsibility to deal with any pre-processing of the data to hide the line-breaks.

Fixed format data files are not prone to this problem since a different read method is used, that ignores the syntactic role of CR and NL altogether.

Delimited Output Files

When outputting delimited files, dbFile substitutes all embedded NL/LF and CR characters with the non-printable 7-bit characters x01 and x02, respectively. Such output can be passed safely in an input file and dbFile will replace them appropriately with the NL/LF and CR characters.