Command: database

Syntax

database <name>

Description

Create a database identifier and link it to an external database.

Parameters

• <name>
  The name of the database identifier.

Switches

• -ap=<string>
  Append <string> to the line used to invoke the database interface program. This enables custom parameters to be passed to the interface. This switch is applicable only to old-style mx interfaces and is ignored for fx interfaces.

• -con=<string>
  Same as -nam.

• -dbif=<file>
  The name of a database interface program used to communicate with the database. Usually the database interface is indicated by a proprietor code (-prop), which looks in the system configuration file to obtain the program name, but if the interface program is known, this switch may be used in client/server situations. The interface program must use the fx command protocol rather than the old style mx interface.

• -enc
  If this switch is present then the system will encode the connect string (-con or -nam) to hide it from prying eyes at the operating system level.

• -mul
  When set, commands sent to the database interface will be buffered and only sent when a command is issued which requires a reply, e.g. a fetch operation. This option is available only with fx interfaces in network service mode.

• -nam=<>string>
  The name of the external database or the connect string to it. If omitted, the database identifier name is used. This string may be an encoded value, created by the external utility fxencode. This option is not required for network services.

• -ov
  Overwrite the identifier if it already exists. The default action, if it exists, is to report an error.

• -prop=<dbif>
  The proprietor name of a database interface. This is text indicating one of the proprietary database interfaces (usually a vendor name) known to the system via entries in the System Configuration File. It defines how the system communicates with the external database. This option is not required for network services.

Configuration File entries take the following form:

dbif <vendor> <program> fx | mx

where:

• dbif
  A fixed word to indicate a that this line describes a database interface entry.

• <vendor>{/<text>}
  Describes the interface. It is this value which is used in the -prop switch to select an interface. It may a single word, e.g. "oracle", "odbc", or a vendor/text pair, e.g. "oracle/fx" to differentiate between similar interfaces.

• <program>
  An executable database interface program to be used to communicate with the database.

• fx | mx
  A fixed word to indicate whether the protocol used by <program>. If omitted, mx is assumed.

Examples

dbif oracle $MXBIN/fx8i fx

dbif odbc $MXBIN/fxodbc fx

dbif ingres $MXBIN/mxingres mx

If the value of -prop is a simple vendor name rather than a vendor/text pair, then the first dbif entry in the Configuration File satisfying the vendor part is used. When a database interface is started a check is made to ensure that it is the requested vendor.

In client/server situations, if the -prop switch is omitted, the first "dbif" entry in the Configuration File is used.

When used in conjunction with the -req switch, for a connection to a network database service, the -prop switch is used only to check the integrity of the service, and may be omitted.

• req=<string>
  The url of a remote database interface service running on a web server. If this is present, then the proprietor name (-prop) may be omitted, and the -dbif and -ap switches are ignored. Only fx services may be requested in this mode.

• -tim=<num>
  A timeout, in seconds, to wait for a connection to and subsequent responses from the external database. If not specified, the timeout is 60 seconds. A value of 0 indicates no timeout, i.e. blocking reads, and is not advised.

Notes

The connection to the external database is made behinf the scenes via an Embedded SQL statement, e.g.

• Informix:

database <string>

• Oracle/ODBC:

connect <string>

Database identifiers can have global or application scope.

A database can be closed by deleting the identifier via a delid command, or by the database.close() function.

Examples

Link to an external database. This assumes a dbif entry called informix is present in the configuration file.

database stores,-prop=informix

Link to an external Oracle database.

database gdb,-prop=oracle/8i,-con=scott/tiger@zeus

Link to a network database service.

database gdb,-req='//zeus/xmarc/Broker?service=ZSVC'

Link to an external database, via a known interface program.

database myorac,-dbif=$BINDIR/fxoracle

See Also