./doc/en/msql.rd

# `Msql`

mSQL client class.

### constant

`Msql::CONFIG_GROUP_GENERAL`

  For Msql.get_config.

`Msql::CONFIG_GROUP_SYSTEM`

  For Msql.get_config.

`Msql::CONFIG_GROUP_W3MSQL`

  For Msql.get_config.

`Msql::INST_DIR`

  mSQL installed directory.

`Msql::SERVER_VERSION`

  mSQL server version.

`Msql::TARGET`

  mSQL target platform.

`Msql::VERSION`

  Ruby/mSQL versions.

### class method

`Msql.connect([host], [database_name])`

  Try to connect mSQL server specified the host and select database specified the database_name. If you omit host or specified the nil as host, then connect local mSQL server.

  ex.

  Msql.connect 'sublime', 'artists' #=> connect server on host 'sublime' and select database 'artists'.

  Msql.connect nil, 'singles' #=> connect local server and select database 'singles'.

  Msql.connect 'frogman' #=> connect server on host 'frogman'.

  Msql.connect #=> connect local server.

  Returns:

    - Msql: mSQL client.

  Exceptions:

    - TypeError: host and/or database_name aren't String.

    - MsqlError: connection failed.

`Msql.get_config(group)`

  Get config values from loaded config file. group only accepts below

  - Msql::CONFIG_GROUP_GENERAL --- "general"

  - Msql::CONFIG_GROUP_SYSTEM --- "system"

  - Msql::CONFIG_GROUP_W3MSQL --- "w3-msql"

  Returns:

    - Hash: config values of specified group.

    - nil : unkown group.

`Msql.load_config_file([conf_file])`

  Load config file specified the conf_file.

  Exceptions:

    - TypeError: conf_file isn't String.

    - MsqlError: loading failed.

### instance method

`Msql#close`

  Close the connection with the connected server.

  Exceptions:

    - MsqlError: closing failed.

`Msql#connect([host], [database_name])`

  See Msql.connect.

  Exceptions:

    - TypeError: host and/or database_name aren't String.

    - MsqlError: already connected or connection failed.

`Msql#copy_db(src_db, dest_db)`

  Copy a database from the src_db to the dest_db. This is administrator operation.

  Exceptions:

    - TypeError: src_db and/or dest_db aren't String.

    - MsqlError: copying failed.

`Msql#create_db(db_name)`

  Create new database named db_name. This is administrator operation.

  Exceptions:

    - TypeError: db_name isn't String.

    - MsqlError: creating failed.

`Msql#drop_db(db_name)`

  Delete database named db_name completely. This is administrator operation.

  Exceptions:

    - TypeError: db_name isn't String.

    - MsqlError: droping failed.

`Msql#database`

  Get selected database name (same as specified in Msql.connect or Msql#connect or Msql#select_db).

  Returns:

    - String: database name.

`Msql#get_host`

  Get connected host name (same as specified in Msql.connect or Msql#connect).

  Returns:

    - String: host name.

`Msql#get_host_info`

  Get connected host name and connection protocol name.

  Returns:

    - String: host name and protocol name.

`Msql#get_sequence_info`

  Get information of sequence.

  Returns:

    - MsqlSequence: sequence info.

    - nil: no sequence exists.

`Msql#get_server_stats`

  Get states of the connected server (for console ouput). Output config file name, max connections, current connections, server running as user and connection table.

`Msql#get_server_info`

  Get version of the connected mSQL server.

  Returns:

    - String: version number.

`Msql#list_dbs`

  Get all database names on the connected server.

  Returns:

    - MsqlResult: database names.

  Exceptions:

    - MsqlError: failed.

`Msql#list_fields(table_name)`

  Get all filed names on the table specified the table_name.

  Returns:

    - MsqlResult: field names.

  Exceptions:

    - TypeError: table_name isn't String.

    - MsqlError: failed.

`Msql#list_index(table_name, index)`

  Get information of the index on the table specified the table_name.

  Returns:

    - MsqlResult: type of the index and filed names included by the index.

  Exceptions:

    - TypeError: table_name and/or index aren't String.

    - MsqlError: failed.

`Msql#list_tables`

  Get all table names on the connected server.

  Returns:

    - MsqlResult: table names.

  Exceptions:

    - MsqlError: failed.

`Msql#move_db(src_db, dest_db)`

  Move a database from the src_db to the dest_db. This is administrator operation.

  Exceptions:

    - TypeError: src_db and dest_db aren't String.

    - MsqlError: moving failed.

`Msql#query(query)`

  Execute query. Must do Msql#select_db before this operaion.

  Returns:

    - Integer: number of records effected by the query.

  Exceptions:

    - MsqlError: query failed.

`Msql#reload_acls`

  Reload ACL(Access Control List) file. This is administrator operation.

  Exceptions:

    - MsqlError: reloading failed.

`Msql#select_db(db_name)`

  Select database on the connected server. Must do this before Msql#query.

  Exceptions:

    - MsqlError: selection failed.

`Msql#shutdown`

  Shutdown connected server. This is administrator operation.

  Exceptions:

    - MsqlError: shutdowning failed.

`Msql#store_result`
`Msql#get_result`

  Get query results (SELECT statement). Must do Msql#query before this operaion. And must do this operaion before execute next Msql#query.

  Returns:

    - MsqlResult: query results.

  Exceptions:

    - MsqlError: failed.

# `MsqlResult`

mSQL query result class.

### class method

    No class method.

### instance method

`MsqlResult#data_seek(pos)`

  Set cursor at pos. MsqlResult#fetch_row fetch a row at a position of the cursor.

`MsqlResult#each_field {|field|...}`

  Iterated access to each filed. (notice: start at cursor position)

`MsqlResult#each_field_with_index {|field, index|...}`

  Iterated access to each filed with index number. (notice: start at cursor position)

`MsqlResult#each_row {|row|...}`

  Iterated access to each row. (notice: start at cursor position)

`MsqlResult#each_row_with_index {|row, index|...}`

  Iterated access to each row with index number. (notice: start at cursor position)

`MsqlResult#fetch_all_fields`

  Get all fields. (notice: range of fields is from the cursor position to the end)

  Returns:

    - Array: array of fields.

`MsqlResult#fetch_all_rows`

  Get all rows. (notice: range of rows is from the cursor position to the end)

  Returns:

    - Array: array of rows.

`MsqlResult#fetch_field`

  Fetch one field from the result.

  Returns:

    - MsqlField: information of the field.

          ex. As if a MsqlResult instance has a result such as
          +---------------------+-----------+
          | name                | genre     |
          +---------------------+-----------+
          | Anthony & Cleopatra | Tragedies |
          | Corilanus           | Tragedies |
          | Hamlet              | Tragedies |
          | Julius Caesar       | Tragedies |
          | King Lear           | Tragedies |
          +---------------------+-----------+
          then fetch_field returns field object of 'name'
          and the cursor move to the next 'genre' field
          (next fetch_field return this field).

    - nil: no more fileds.

`MsqlResult#fetch_hash`

  Fetch one row as hash from the result.

  Returns:

    - Hash: key is field name and value is element.

          ex. As if a MsqlResult instance has a result such as
          +---------------------+-----------+
          | name                | genre     |
          +---------------------+-----------+
          | Anthony & Cleopatra | Tragedies |
          | Corilanus           | Tragedies |
          | Hamlet              | Tragedies |
          | Julius Caesar       | Tragedies |
          | King Lear           | Tragedies |
          +---------------------+-----------+
          then fetch_hash returns
          {"name"=>"Anthony & Cleopatra", "genre"=>"Tragedies"}
          and the cursor move to the next row.

    - nil: no more rows.

`MsqlResult#fetch_row`

  Fetch one row from the result.

  Returns:

    - Array: array of (String) elements of each fields.

          ex. As if a MsqlResult instance has a result such as
          +---------------------+-----------+
          | name                | genre     |
          +---------------------+-----------+
          | Anthony & Cleopatra | Tragedies |
          | Corilanus           | Tragedies |
          | Hamlet              | Tragedies |
          | Julius Caesar       | Tragedies |
          | King Lear           | Tragedies |
          +---------------------+-----------+
          then fetch_row returns
          ["Anthony & Cleopatra", "Tragedies"]
          and the cursor move to the next row:
          ["Corilanus", "Tragedies"](next fetch_row return this row).

    - nil: no more rows.

`MsqlResult#field_seek(pos)`

  Set cursor at pos. MsqlResult#fetch_field fetch a field at a position of the cursor.

`MsqlResult#num_fields`

  Get number of fields of the results.

  Returns:

    - Integer: number of fields.

`MsqlResult#num_rows`

  Get number of rows of the results.

  Returns:

    - Integer: number of rows.

# `MsqlField`

mSQL field has a information of column.

### constant

`MsqlField::INT_TYPE`

  Field data type: integer.

`MsqlField::CHAR_TYPE`

  Field data type: charactor.

`MsqlField::REAL_TYPE`

  Field data type: real number.

`MsqlField::IDENT_TYPE`

  Field data type: identify.

`MsqlField::NULL_TYPE`

  Field data type: null.

`MsqlField::TEXT_TYPE`

  Field data type: text.

`MsqlField::DATE_TYPE`

  Field data type: date.

`MsqlField::UINT_TYPE`

  Field data type: unsigned integer.

`MsqlField::MONEY_TYPE`

  Field data type: money.

`MsqlField::LAST_REAL_TYPE`

  Field data type: last real number.

`MsqlField::IDX_TYPE`

  Field data type: index.

`MsqlField::SYSVAR_TYPE`

  Field data type: system variable.

`MsqlField::ANY_TYPE`

  Field data type: any.

### class method

    No class method.

### instance method

`MsqlField#name`

  Get field name.

  Returns:

    - String: field name.

`MsqlField#table`

  Get table name.

  Returns:

    - String: table name.

`MsqlField#type`

  Get filed type.

  Returns:

    - Integer: filed type.

      - MsqlField::INT_TYPE

      - MsqlField::CHAR_TYPE

      - MsqlField::REAL_TYPE

      - MsqlField::IDENT_TYPE

      - MsqlField::NULL_TYPE

      - MsqlField::TEXT_TYPE

      - MsqlField::DATE_TYPE

      - MsqlField::UINT_TYPE

      - MsqlField::MONEY_TYPE

      - MsqlField::LAST_REAL_TYPE

      - MsqlField::IDX_TYPE

      - MsqlField::SYSVAR_TYPE

      - MsqlField::ANY_TYPE

`MsqlField#length`

  Get filed length.

  Returns:

    - Integer: filed length.

`MsqlField#flags`

  Get field flags. Usually, access with MsqlField#is_not_null or MsqlField#is_unique.

  Returns:

    - Integer: field flags.

`MsqlField#is_not_null`
`MsqlField#is_not_null?`

  Return true if field defined as NOT NULL.

  Returns:

    - true/false: field is 'NOT NULL' or not.

`MsqlField#is_unique`
`MsqlField#is_unique?`

  Return true if field is unique. Returns:

  - true/false: field is unique or not.

# `MsqlSequence`

Sequence information.

### class method

    No class method.

### instance method

`MsqlSequence#step`

  Get sequence step.

  Returns:

    - Integer: sequence step.

`MsqlSequence#value`

  Get sequence value.

  Returns:

    - Integer: sequence value.