DBCONNECT

8.0.4, PLBCMP GUI or PLBLinux Only

 

The DBCONNECT instruction establishes a connection to a local or remote database. The instruction uses the following format:

 

 

[label]

DBCONNECT

[{window};]{dbfile},{host}:

 

 

 

{user},{pass}[,{conn}[,{ext}][,{flags}]]

 

Where:

label

Optional. A Program Execution Label.

window

Optional. A previously created WINDOW object variable.

dbfile

Required. A DBFILE variable defining the database associated with the connection.

host

Required. A Character String Variable or Literal containing the database source.

user

Required. A Character String Variable or Literal containing the user name that makes the connection.

pass

Required. A Character String Variable or Literal containing the password that makes the connection.

conn

Optional. A Character String Variable or Literal defining additional login information that makes the connection.

ext

Optional. A Character String Variable or Literal defining the extension used for the database, the mode for the database open.

flags

Optional. A Numeric Variable or decimal number defining any special settings for the connection.

Flags Affected: none

Note the following for all connections:

  1. The optional {window} parameter is used only for the Windows ODBC database driver.

  2. The {host} parameter may contain a driver name indicator in the format

    <driver>;;<host>

    The driver indicator obtains an entry from the INI file with the same name as the driver indicator. The entry must contain the name of the driver library first. Then, using comma separation, the entry can also contain a replacement host value and a replacement ext value.

    Examples: 

    3. .

     

     

    .Example {host} parameter strings for program:

    .

     

     

    OdbcHost

    INIT

    "Myodbc3-test"

    OdbcHost1

    INIT

    "Sun Test"

    MyHost

    INIT

    "MYSQL;;192.168.112.30"

    AdoHost

    INIT

    "DBADO;;DSN=Myodbc3-test"

    SQLiteHost

    INIT

    "SQLite;;c:\mypath\mydatabase.db"

    SQLiteDM

    INIT

    "MySQLite;;c:\mypath\mydatabase.db"

     

    Example INI entries:

     

    MYSQL=Sunwmsql.dll

    DBADO=Sunwado.dll

  1. A special driver library name of 'FILEMAN' allows access a Database connection through a data manager. The entry in the INI file must have a driver library name of 'FILEMAN', the I/P address of the data manager, and the port number of the data manager, all separated by commas. The data manager configuration file must also have an entry that has the same name as the driver. The entry must contain the name of the driver library first. Then, using comma separators, the entry can also contain a replacement host value and a replacement extension value.

    2.  

    Example {host} parameter strings for program:

     

    OdbcHost INIT "ODBCR;;MyOdbc3-test"

    OdbcHost1 INIT "ODBCR;;Sun Test"

    MyHost INIT "MYSQL;;111.0.0.1"

    AdoHost INIT "DBADO;;MyOdbc3-test"

    AdoHost1 INIT "DXADO;;"

     

    Example INI entries to access SUNDM:

     

    ODBCR=FILEMAN,99.0.0.1,3934

    MYSQL=FILEMAN,99.0.0.1,3934

    DBADO=FILEMAN,99.0.0.1,3934

    MySQLite=FILEMAN,99.0.0.1,3934

     

    Example CFG entries for SUNDM:

     

    ODBCR=Sunwodbc.dll

    MYSQL=Sunwmsql.dll

    DBADO=Sunwado.dll

    DXADO=Sunwado.dll,DSN=MyOdbc3-testX

     MySQLite=SQLite or MySQLite=SQLite,c:\sundmpath\mydm.db

 

  1. If no driver name indicator is found, the runtime defaults to the ODBC driver and Linux runtimes employ the PLB_SQL.

  2. The {flags} parameter is bit map value that can be any valid combination of the following values:

    3.  

    Value

    Description

    1

    The cursor should be kept at the server

    2

    The cursor should be kept at the client

    4

    When using the ODBC driver, the SQL connection is made using a NOPROMPT driver completion mode. The NOPROMPT flag setting is only used when the {host} string is NULL and the {conn} string makes the connection. (9.9)

     

  3. If a FILEPI instruction is active, it is terminated.

Note the following for ADO connections:

  1. The {window} option is disregarded.

  2. The {host} parameter is an ADO specific connection string.

  3. {user} is not used and may be specified as the null literal.

  4. {pass} is not used and may be specified as the null literal.

  5. {conn} is not used.

  6. If {ext} contains 'READ', the database is opened in READ ONLY mode.

Note the following for ODBC connections:

  1. If the optional {window} is not specified, the currently active window is used.

  2. If the {host} is a Null String and the {conn} parameter is not a Null String, the string found in {conn} defines a connect string that establishes the connection with a database source. The definition of the connect string contents is different for each ODBC driver used. See appropriate ODBC driver documentation for connect string specifications.

  3. {user} is not always needed and may be specified as the null literal.

  4. {pass} is not always needed and may be specified as the null literal.

  5. If {ext} contains 'READ', the database is opened in READ ONLY mode. If {ext} contains 'NOAC', the database is opened with SQL auto commit turned off. The {ext} string can only be set either 'READ' or 'NOAC' and not both.

  6. DBCONNECT is not supported by the PLBCE runtime.

Note the following for MySQL and Linux SQL access:

  1. The {window} option is disregarded.

  2. The {host} parameter may be a hostname or an IP address. If {host} is a Null String or the string "localhost", a connection to the local host is assumed. If the OS supports sockets, they are used instead of TCP/IP to connect to the server.

  3. The {user} parameter should contain the user's database login id. If user is a Null String, the current user is assumed. Under Linux, this is the current login name.

  4. The {pass} parameter contains the password for user. If {pass} is a Null String, only entries in the user table for the user that have a blank (empty) password field are checked for a match. This allows the database administrator to set up the privilege system in such a way that users get different privileges depending on whether they have specified a password.

  5. {conn} is the database name. If {conn} is a Null String, the connection will set the default database to this value.

  6. {ext} defines the TCP/IP port number. If {ext} is specified, the value is the port number for the TCP/IP connection. Note that the host parameter determines the type of the connection.

Note the following for SQLite access:

  1. If the database file name is specified in the {host} parameter, the database file is created if it does not exist.

  2. If the database file name is not specified in the {host} parameter, the SQLite database engine creates a private database as a temporary on-disk file. This private database is automatically deleted as soon as the database connection is closed.

  3. If the database file name ":memory:" is specified in the {host} parameter, the SQLite database engine creates a private database as a temporary in-memory database for the connection. This in-memory database vanishes when the database connection is closed.

  4. The {user} and {pass} parameters for the DBCONNECT instruction are not used by the SQLite database engine.

 

 

See Also: Example Code, SQL Instructions

 


PL/B Language Reference DBCLOSE DBDISCONNECT