EDM Server Context

Using the EDMI Remote Interface one may define as many server contexts as wanted.
The server contexts are distinguished by their unique context name and can be defined in the EDMsupervisor with the command

• Remote Systems->Server Context->Define Context

or with the EDMI functions

• edmiDefineServerContext()
• edmiDefineServerContextEx()

The client can use these server contexts to communicate with databases on different hosts and with different user accounts and access rights. This feature is possible because the EDMI Remote functions are transaction oriented and stateless. Each function operates within a transaction, and is either successful (with commit) or abortive (with abort and no change).

Using HTTP-communication

 
The HTTP (Hypertext Transfer Protocol) is an application protocol that runs on top of the TCP/IP suite of protocols. The HTTP protocol is using port number 80 and this port number is normally accepted by firewalls, because normal web browsing is using HTTP. The disadvantage with this communication is that it is a bit slower and requires a tunnel servlet in between, to pack/unpack all messages between client and server into HTTP-packets. This calls for additional parameters to be set. The required parameters are tunnel program name, tunnel host name and tunnel port number (normally 80). In addition it is possible to define a proxy host if it necessary to go through another host to obtain the communication.

Example parameters:

Communication type   HTTP
EDM server host name:  195.139.163.4
EDM server port number:  4530
EDMIhttpTunnelName  /pilot/servlet/EDMHttpTunnelServlet
EDMIhttpTunnelPortNumber 80
EDMIhttpTunnelHostName  195.139.163.4
Proxy server name:  
Proxy server port number:  
 
The HTTP tunnel is supplied as a Java servlet in a Java Archive (.jar) file. To use this servlet you need a webserver, or to be more precise a Servlet Container like the Apache Tomcat. It is outside the scope for this document how to set up a servlet container.

Using TCP-communication

 
The TCP (Transmission Control Protocol) protocol is used along with the IP (Internet Protocol). The TCP protocol requires only two parameters for the communication, the host name and the port number. The host name and port number must correspond to the host name where the EDMserver is running and the port number used when the EDMserver was started. Examples of EDMserver host names and port numbers:

Communication type:  TCP
EDM server host name:  dbhost
EDM server port number:  9090

Port numbers that are not used for any other communication may be used. The host may also be represented by its IP-address. This will increase communication performance. The local host name may also be given as localhost or 127.0.0.1.

Transactions in EDMserver

 
EDMserver can handle any number of concurrent read-only transactions and one write transaction to one model at the same time. Hence, a start of a write transaction to a model while another write transaction is open on the same model, will be forced to wait until the open write transaction to the model is terminated by commit or abort. A timeout will happen after a given amount of time (25 seconds). Write transactions to different models can be opened and operated simultaneously.
A write transaction must be started by one of the following EDMIinterface operations:
EdmiError edmiStartModelWriteTransaction (SdaiModel modelId);
EdmiError edmiStartModelsWriteTransaction (SdaiModel *modelIds);

• where the argument modelIds is a zero terminated array of modelId’s.
  The actual model(s) to start write transaction on, must be open for sdaiRW access when the edmiStartModelWriteTransaction() or edmiStartModelsWriteTransaction() are performed.
  Transactions can be nested as in earlier EDM versions. The edmiStartModelWriteTransaction() and edmiStartModelsWriteTransaction() operation cannot be performed within an open write transaction, i.e., these operations must be used to start an outer transaction. However any number of edmiStartTransaction() operation can be performed within an open write transaction. Write transactions are terminated in the normal way, i.e., by one of the following EDMIinterface operations: edmiCommitTransaction(), edmiCommitAllTransactions(), edmiAbortTransaction(), edmiAbortAllTransactions().
  All access (also read only accesses) to an EDMserver should be inside an open transaction to ensure a consistent view of the EDM database within one “logical application operation”. One “logical application operation” may contain any number of EDMIinterface operations.
  There are many EDMI operation that cannot be performed within an open transaction, like sdaiOpenModel(), sdaiOpenModelBN() etc.
  A transaction client gets the "latest version" of a model when the model is opened and each time an outer transaction is started. A transaction client will update the EDMserver when a write transaction is committed.
  A transaction client will get the “latest version” of common resources, i.e., repositories, models, schemas, users, groups, etc., when required, i.e., when creating/opening/closing/deleting repositories, models, schemas, etc. A transaction client can explicitly get the latest version of the common resources by invoking the EDMI function: EdmiError edmiRefreshDB (void);

System shutdown

Automatic Server shutdown

 
For simplicity both the EDMserver and the _EDMappServer_ (s) can be stopped automatically using a command script calling another command script. The example below shows how to do it. The EDMconnector™ is used instead of the EDMsupervisor™, because the no license problem will be obtained. The command script can for example be named "stop_servers.cmd" and contain the line:
%EDM_HOME%\bin\Edms_connector.exe shutdown_edm.EDM_SCRIPT
The script "shutdown_edm.EDM_SCRIPT" must contain the lines:
RemoteSystems>Servercontext>DefineContext(shutdown, superuser, $, pwd, tcp, localhost, 9090, $, $, $, $, $, $, $, $)
RemoteSystems>Server>Terminate>(shutdown, pwd, $,"ALL_SERVERS,FORCE_TO_TERMINATE")
Exit>Exit()
 
The password named 'pwd' must be edited correctly. Before using the script "stop_servers.cmd", all users should be informed to log off from the database. See how the servers were started in Automatic Server start-up

EDM Server shutdown

 
The EDMsupervisor or EDMconnector should be used to stop the EDMserver and the EDMappServer(s) in a controlled way, either manually or automatically with a script (see next chapter). Before the EDMdatabase is stopped, it is advised that all clients (users) should complete their work and log out – or they are interrupted and may lose some of their work. The EDMserver™/ EDMappserver should not be handled as a simple application that can be started and stopped at any time by just shutting down the processes.
By default the configuration parameter EDM_TRANSACTION_SECURITY is set to BIM_LOG (Before Image Log). This normal setting should secure that all committed transactions are stored (safe) into the EDMdatabase. In case of an abnormal termination of the EDMserver™ no committed transaction should be lost with this option.
The EDMsupervisor is available both as an EDMfatClient & EDMremoteClient (edms_client.exe) and as an EDMstandAlone and & EDMremoteClient (edms.exe). Therefore a double set of commands is available. The EDMconnector only has the EDMremoteClient commands available. Both sets of commands are given below:
 

 
Note: These commands will stop the EDMserver and all EDMappServers if the option ALL_SERVERS is used. The option FORCE_TO_TERMINATE will force the servers to terminate even if some clients are connected.

System Startup

Automatic Server start-up

 
For simplicity both the EDM Server and the EDM Application Server(s) can be started automatically using a command script. This script can be written/modified by a person knowing a little about Windows script programming. An example is presented below to show how to do it. This script can for example be named "start_servers.cmd" and contain the lines:
start edmserver –s9090 –l../projabc/db -nabc –pabc –o
start edmappserver.exe –s9090
start edmappserver.exe –s9090
 
Then the servers needed to operate on database "abc" (with name "abc" and password "abc") can be started from the directory where this script is stored with the simple command: "start_servers".

EDM Application Server start-up

 
At least one EDM Application Server, called EDMappserver, is needed to use the EDMI Remote Interface. The EDMappserver allows multiple clients to access the EDMserver simultaneously, and encloses all work intensive operations to improve performance. The program is located in the %EDM_HOME%\bin directory. Due to performance reasons, the EDM Application Server(s) will normally run in the same system as the EDMserver. However, the configuration is so flexible that an EDMappserver may run in any system in the network. Some options are available when the EDMappserver is started. The only mandatory parameter is the server port number. Some of the trace output from the EDMappserver is added to the trace generated from the EDMserver to produce a complete trace list. Under normal conditions, no trace output should be used. Some of the options (can be lower or upper letter) are listed below:

-h<host-name> specify the server host name (default is localhost)
-s<port-number> specify the server port number
-ap<port-number> specify EDMappserver port number (By default, the EDMappserver™ port number is incremented by 1 for each EDMappserver process started, starting at the EDMserver port number +1)
-t trace message headers
-w trace message body
-?  display the complete options list
 
Examples of EDMappserver startup commands:
start %EDM_HOME%\bin\edmappserver – s4530
or
start edmappserver.exe –s9090 –t -w

EDM Database Server start-up

 
The EDMserver may be installed on a dedicated host (PC) or on the same PC where the EDM client is running. The program is located in the $EDM_HOME\bin directory. EDMserver is started with a list of selected startup parameters. The only mandatory parameter is the server port number. For debugging purposes it is useful to use the trace output parameters, but under normal conditions no trace should be used. It is possible to connect to the database directly when the EDMserver is started, by giving database location, database name, database password and one of the database options, like -o.
Some of the options are listed below. Options are case insensitive. For a complete list, use the -? or –h option.

-s<port-number> specify server port number
-l<db-location> specify database location (directory containing database)
-n<db-name> database name
-p<db-password> database password
-c create database
-d delete database (will destroy old database!)
-o open database
-t trace message headers
-w trace message body
-?  display the complete options list
 
Examples of EDMserver startup commands:
start %EDM_HOME%\bin\edmserver.exe –s9090 –t –w
or
start %EDM_HOME%\bin\edmserver –s4530 –Lc:\home\db -Nmydb –Ppwd –o
There is also implemented command line options for scheduled online backups, please see EDMserver Scheduled Online Backup if you want to use these options.

Automatic restart of EDMappServer