Mapi Interface

The complete MAPI library is available to setup communication between mserver and clients.

Clients may initialize a private listener to implement specific services. For example, in an OLTP environment it may make sense to have a listener for each transaction type, which simply parses a sequence of transaction parameters.

Authorization of access to the server is handled as part of the client record initialization phase.

This library internally uses pointer handles, which we replace with an index in a locally maintained table. It provides a handle to easily detect havoc clients.

A cleaner and simpler interface for distributed processing is available in the module remote.

MODULE mapi;

PATTERN mapi.bind(X_0:int, X_1:str):bat[:any_2];
COMMENT "Bind a remote variable to a local one.";

PATTERN mapi.bind(X_0:int, X_1:str, X_2:str, X_3:int):bat[:any_2];
COMMENT "Bind a remote variable to a local one.";

PATTERN mapi.bind(X_0:int, X_1:str, X_2:str, X_3:str, X_4:int):bat[:any_2];
COMMENT "Bind a remote variable to a local one.";

PATTERN mapi.connect(X_0:str, X_1:int, X_2:str, X_3:str, X_4:str):int;
COMMENT "Establish connection with a remote mserver.";

COMMAND mapi.destroy(X_0:int):void;
COMMENT "Destroy the handle for an Mserver.";

COMMAND mapi.disconnect(X_0:int):void;
COMMENT "Terminate the session.";

COMMAND mapi.disconnect():int;
COMMENT "Close connections with all remote Mserver.";

COMMAND mapi.disconnect(X_0:str):int;
COMMENT "Close connection with a remote Mserver.";

COMMAND mapi.error(X_0:int):int;
COMMENT "Check for an error in the communication.";

COMMAND mapi.explain(X_0:int):str;
COMMENT "Turn the error seen into a string.";

COMMAND mapi.fetch_all_rows(X_0:int):lng;
COMMENT "Retrieve all rows into the cache.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):bte;
COMMENT "Retrieve a single bte field.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):int;
COMMENT "Retrieve a single int field.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):lng;
COMMENT "Retrieve a single lng field.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):oid;
COMMENT "Retrieve a single void field.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):sht;
COMMENT "Retrieve a single sht field.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):str;
COMMENT "Retrieve a single field.";

COMMAND mapi.fetch_field(X_0:int, X_1:int):void;
COMMENT "Retrieve a single void field.";

COMMAND mapi.fetch_field_array(X_0:int):bat[:str];
COMMENT "Retrieve all fields for a row.";

COMMAND mapi.fetch_line(X_0:int):str;
COMMENT "Retrieve a complete line.";

COMMAND mapi.fetch_reset(X_0:int):int;
COMMENT "Reset the cache read line.";

COMMAND mapi.fetch_row(X_0:int):int;
COMMENT "Retrieve the next row for analysis.";

COMMAND mapi.finish(X_0:int):int;
COMMENT "Remove all remaining answers.";

COMMAND mapi.getError(X_0:int):str;
COMMENT "Get error message.";

COMMAND mapi.get_field_count(X_0:int):int;
COMMENT "Return number of fields.";

COMMAND mapi.get_row_count(X_0:int):lng;
COMMENT "Return number of rows.";

COMMAND mapi.listen():int;
COMMENT "Start a Mapi server with the default settings.";

COMMAND mapi.listen(X_0:int):int;
COMMENT "Start a Mapi listener on the port given.";

COMMAND mapi.listen(X_0:str):int;
COMMENT "Start a Mapi listener on the unix socket file given.";

COMMAND mapi.lookup(X_0:str):int;
COMMENT "Retrieve the connection identifier.";

COMMAND mapi.malclient(X_0:streams, X_1:streams):void;
COMMENT "Start a Mapi client for a particular stream pair.";

COMMAND mapi.next_result(X_0:int):int;
COMMENT "Go to next result set.";

COMMAND mapi.ping(X_0:int):int;
COMMENT "Test availability of an Mserver.";

COMMAND mapi.prepare(X_0:int, X_1:str):int;
COMMENT "Prepare a query for execution.";

PATTERN mapi.put(X_0:int, X_1:str, X_2:any_1):void;
COMMENT "Send a value to a remote site.";

PATTERN mapi.put(X_0:str, X_1:any_1):str;
COMMENT "Prepare sending a value to a remote site.";

COMMAND mapi.query(X_0:int, X_1:str):int;
COMMENT "Send the query for execution";

PATTERN mapi.query_array(X_0:int, X_1:str, X_2:str...):int;
COMMENT "Send the query for execution replacing '?' by arguments.";

COMMAND mapi.query_handle(X_0:int, X_1:str):int;
COMMENT "Send the query for execution.";

COMMAND mapi.reconnect(X_0:int):void;
COMMENT "Re-establish a connection.";

PATTERN mapi.reconnect(X_0:str, X_1:int, X_2:str, X_3:str, X_4:str, X_5:str):int;
COMMENT "Re-establish connection with a remote mserver.";

PATTERN mapi.reconnect(X_0:str, X_1:int, X_2:str, X_3:str, X_4:str):int;
COMMENT "Re-establish connection with a remote mserver.";

COMMAND mapi.resume():void;
COMMENT "Resume connection listeners.";

COMMAND mapi.rows_affected(X_0:int):lng;
COMMENT "Return number of affected rows.";

PATTERN mapi.rpc(X_0:int, X_1:str):bat[:any_2];
COMMENT "";

PATTERN mapi.rpc(X_0:int, X_1:str...):any;
COMMENT "Send a simple query for execution and fetch result.";

COMMAND mapi.rpc(X_0:int, X_1:str):int;
COMMENT "Send a simple query for execution.";

COMMAND mapi.setAlias(X_0:int, X_1:str):void;
COMMENT "Give the channel a logical name.";

COMMAND mapi.stop():void;
COMMENT "Terminate connection listeners.";

COMMAND mapi.suspend():void;
COMMENT "Suspend accepting connections.";

COMMAND mapi.trace(X_0:int, X_1:int):void;
COMMENT "Toggle the Mapi library debug tracer.";