Remarks

This method instantiates and returns a Session object.

The Session object is the heart of the persistence engine. It represents an individual session or connection with the database and provides the methods necessary to connect, disconnect, save and retrieve objects and much more.

NewSession first creates an instance of the class indicated by the Server.SessionClassName property. This property by default equals to "fdoSession" but can be set  with the name of a valid fdoSession custom subclass. If the class name is invalid, NewSession cancels the operation, logs a message in the Errors collection and returns the .Null. value.

NewSession method sets initial session object properties from the values stored on equivalent properties in the server object, like:

Then, NewSession() instructs the session object to load the schema file received as a parameter, or the Server.DefaultSchemaFileName if no one was received, by calling the Session.LoadSchema() method.

When the schema file specified does not exists, depending on the Server.DefaultLearningMode (or Session.MappingSchema.LearningMode) property, NewSession method will:

If the Server.ConnectedSessionsOnly property is set to .F. (False), the NewSession method returns an object pointer to the created Session object. Note this session object is not connected to a datasource.

If the Server.ConnectedSessionsOnly property is set to  .T. (True), the NewSession method will instruct the session object to connect to the datasource passed as parameter or to a default datasource, by calling the Session.Connect method. See the Session.Connect method on this reference for a complete description on the  default datasource lookup mechanism and the connection process. Once connected, NewSession will execute all the optional actions indicated on the datasource object, like checking for a database in the server, selecting the database (USE), checking the database and tables status, creating the database and/or database objects and upgrading the database schema to the last version. This is done by calling the Session.EnsureDatabaseStatus method with the CheckStautsLevel value indicated by the datasource object. For a complete description, see the Session.EnsureDatabaseStatus method reference and the datasource class reference.

NewSession returns a valid Session object or .Null. if something went wrong. In that case, the Errors collection structure holds all the information about the session object creation failure.

SET PROCEDURE TO FDO ADDITIVE

oServer=CREATEOBJECT("fdoServer")

oServer.DefaultDataSource.Database_Path="C:\Data"

oServer.DefaultDataSource.Database_Name="MyData.DBC"

oServer.DefaultSchemaFileName="C:\MyApp\MyApp.FDO"

oSession=oServer.NewSession()

SET PROCEDURE TO FDO ADDITIVE
oServer=CREATEOBJECT("fdoServer")

oDS=oServer.NewDataSource("MySQL")
oDS.Database_Name=”Contacts”
oDS.ODBC_SRV="192.168.0.5"
oDS.ODBC_PORT=3307

oSession=oServer.NewSession("MyApp.fdo",oDS)

This sample creates a DataSource object for MySQL and passes it to the NewSession() method along with the main schema file to be used.
 

#INCLUDE fdo.h
SET PROCEDURE TO FDO ADDITIVE
oServer=CREATEOBJECT("fdoServer")
 

oServer.DefaultDataSourceLookupMode = DSLOOKUPMODE_SCHEMAFILE

oSession = oServer.NewSession("MyApp.fdo")

This sample relies on a Data Source definition stored on the MyApp.fdo schema file and marked as "Default". Also shows how to use the provided named constant file fdo.h to help get well documented code.

#INCLUDE fdo.h
SET PROCEDURE TO FDO ADDITIVE
oServer=CREATEOBJECT("fdoServer")
 

oServer.DefaultDataSourceLookupMode = DSLOOKUPMODE_SERVER
oServer.SetDefaultDataSource("Postgres")
oServer.DefaultDataSource.SetProperties(cDataSourceStringFromSomewhereElse)

oSession = oServer.NewSession("MyApp.fdo")
 

This sample code instructs FDO to use the Server.DefaultDatasource object, ignoring the Data Source definitions the schema file may have stored.
It also shows how you could "Restore" all the properties for a DataSource object from a string taken from some other place (it assumes you have previously generated the string from an equivalent object using the GetProperties() method and stored it in that place). You may envisage that is very easy to bind a DataSource object to a form to edit their properties and then get a string with all of its values serialized. The Schema Manager mapping tool works in this way, having specialized forms for each specialized fdoDatasource subclass, that lets you edit all the data source properties graphically, and then storing its values as a string on a schema file record.
 

SET PROCEDURE TO FDO ADDITIVE
oServer=CREATEOBJECT("fdoServer")
 

oServer.ConnectedSessionsOnly=.F.

oSession = oServer.NewSession("MyApp.fdo")

This sample shows how to get a disconnected session by setting the Server.ConnectedSessionsOnly property to .F.

See Also

DataSource class | Server.SetDefaultDataSource method | Server.DefaultSchemaFile property | Server.SessionClassName property | Server.ConnectedSessionsOnly property | Server.DefaultDataSourceLookupMode property | Server.DefaultLearningMode property | Session.Connect method  | Session.EnsureDatabaseStatus method