Qorus Integration Engine  3.0.4.p7
Working With the System

Contents of this section:

Start Qorus Integration Engine

In order to start the Qorus Integration Engine system, log in with a user account with write access to the Qorus log directory, with read access to the Qorus configuration files (normally the UNIX user qorus), and the UNIX environment configured as specified in the installation instructions, and enter the following at the command line:

unixprompt% qorus [option=value ...]

Output similar to the following should appear:

Qorus Integration Engine v3.0.4.p7 (build 5479), Copyright (C) 2003 - 2010 Qore Technologies
reading system options from "/opt/qorus/etc/options"
auto-recover quark-1: no sessions need recovery
starting instance quark-1 on omq@omq (pgsql) with session ID 459
starting HTTP listener on: <all interfaces>:8001
entering daemon mode, PID: 25979

No error messages should appear. If an error message appears, see the following section for causes.

Note
See the System Reference Manual for more information on the Qorus startup sequence, system programs, and system options. In particular, note that there are functional limitations when starting more than one Qorus instance on the same database schema. These are documented in the Qorus Integration Engine System Reference Manual.
Common Errors Starting the System

Error: Cannot Open System Datasources

Error Message:
ERROR opening datasource omq: DBI:ORACLE:OCI-ERROR
ERROR opening datasource omquser: DBI:ORACLE:OCI-ERROR
cannot open system datasources, aborting
Explanation:
The Qorus system cannot connect to one or more system datasources. The omq and omquser datasources must be accessible for the system to start. To get more detailed information, try to connect from the command-line with sqlplus (Oracle), mysql (MySQL) or psql (PostgreSQL), depending on the database server used for the system schema.

Possible Cause Action to Take
No TNSNAMES.ORA entry for Oracle Databases Have the DBA make the correct entries in the TNSNAMES.ORA file
Database is down Check with DBA and start database if necessary
Login or connection parameters are incorrect Edit the login parameters in the system datasource (dbparams) File file
Network connectivity loss Check with network administrators to fix the problem

Error: Unable to Open Session

Error Message:
2010.10.19 12:18:31.023745 T0: OMQ: Unable to open session (ACTIVE-SESSION-ERROR: [instance name] sessionid 20 is currently active. If this is incorrect, then restart Qorus with auto-recover=True)
Explanation:
There is an entry in the sessions table with this instance key and with status = ACTIVE. Check the process list with "ps" to verify if the instance is running or not.
Possible Cause Action to Take
The instance is already running Take no action (system is already running) or start the system with a new instance key and new HTTP server port.
The instance stopped abnormally Launch the instance with auto-recover=true (see auto-recover) to recover the previous instance

Error: Unable to Create HTTP Server

Error Message:
2010.10.19 12:18:31.023745 T0: OMQ: Unable to start HTTP server on “[host:]port" (HTTP-SERVER-ERROR: could not bind to socket "[host:]port": Address already in use), aborting
Explanation:
The Qorus system could not open the port given with the http-server option because another process is already using that port.
Possible Cause Action to Take
Another process is already listening on this port Start the system with a different HTTP server port (change the http-server option), or stop the other process before trying to start Qorus on the same port.

Error: Cannot Load System Services

Error Message:
2010.10.19 12:18:31.023745 T0: OMQ: Unable to load system services (OMQ-NO-SERVICE: system service "name" does not exist)
Explanation:
The Qorus system could not load the system service listed in the error message.
Possible Cause Action to Take
The system has not been completely installed Make sure the system schema has been installed and all system services have been loaded in the database. See the installation instructions in the Installation Guide for more information.
System datasource points to the wrong database Check that the omq datasource is correctly configured to access the Qorus system schema in the system datasource (dbparams) File file.

Stop Qorus Integration Engine

To stop the Qorus system, either the omq.system.shutdown() or the omq.system.shutdown-wait() API method must be called by sending an appropriately formatted request to Qorus’s HTTP server (Note that the omq.system.shutdown() message is asynchronous; it queues the system exit, whereas the omq.system.shutdown-wait() method returns when the system is shut down).

The system shutdown process proceeds as follows: first, all executing workflows must terminate, and then all running services must be stopped and deleted. Therefore there could be a delay between executing the omq.system.shutdown() command and the time the system is fully stopped.

To shut down the system, execute the following command-line to send this command to the server:

unixprompt% ocmd shutdown-wait

Output similar to the following should appear: 

OK

No error messages should appear. If an error message appears, see the following section for causes.

Note
For more information, see the System Reference Manual for more information on the Qorus shutdown sequence; for information on Qorus command-line programs, see Command-Line Programs, for API method information, see the Network System API, and see System Service Reference for more information on system service methods.
Common Errors Stopping the System

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Error: System is Already Shutting Down

Error Message:
ERROR system shutdown is already in progress
Explanation:
The system is already shutting down. Once the system shutdown command has been received, the shutdown process cannot be stopped. It could take some time for all running workflows to terminate and for all running services to stop, so if the shutdown command is sent after it has already been received, and before the Qorus HTTP server is stopped, this error message will be the result.
Possible Cause Action to Take
System is still shutting down Wait for all running workflow execution instances to terminate and the system should shut down cleanly afterwards.
A deadlock has occurred Deadlocks can occur for several reasons; for example, if someone locks an object in the Qorus system schema by hand (for example, by leaving an uncommitted transaction open) then a deadlock could happen. In this case, the locked database objects should be unlocked, which should resolve the situation. In the case of another unforeseen error, the Qorus process must be killed and the application session recovered when Qorus is next launched.

View System Options

To view Qorus system options, the omq.system.get-option-info() api method must be called by sending an appropriately-formatted request to the Qorus HTTP server. Execute the following command-line to send this command to the server:

unixprompt% ostatus -o

Output similar to the following should appear:

Qorus 3.0.4.p7 development-qore2-1 sessionid 1920
* auto-recover              = True
* daemon-mode               = True
* max-log-files             = 10
* system-pool-minimum       = 5
* system-pool-maximum       = 20
  verbose                   = 11
  max-retries               = 5
  max-async-retries         = 20
  recover_delay             = 300
  async_delay               = 1200
  detach-delay              = 1200
  cache-max                 = 1000000
* logdir                    = "/appl/omq/prod/log/"
  tibco-daemon              = 
  tibco-network             = 
  tibco-service             = 
  tibco-timeout             = 90000
* http-server               = "localhost:8001"
* http-secure-server        = 
* http-secure-certificate   = 
* http-secure-private-key   = 
* instance-key              = "quark-1"
* rbac-security             = True
* rbac-force-user           = (localhost="admin", 192.168.*="admin")
* option-file               = "/appl/omq/prod/etc/options"
* dbparams-file             = "/appl/omq/prod/etc/dbparams"
* logfile-template          = "OMQ-$instance"
* wf-logfile-template       = "OMQ-$instance-$name"
* svc-logfile-template      = "OMQ-$instance-SVC-$type-$name"
* flush-status              = False
* force-gui-encoding        = 
* max-events                = 100000
  workflow-params           = ACTIVATION=(*=verbose="10", 2.0=)
* db-max-threads            = 10

Option names preceded by an asterisk are locked and cannot be changed after the system has started. These options can only be set in the System Options File file or on the command-line when the Qorus server process starts.

See Set System Options for information on how to change system options.

Note
See the System Reference Manual for more information on system options, Command-Line Programs for information about Qorus command-line programs, and the Network System API for more information on Qorus API methods.

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Set System Options

To set Qorus system options in a running process, the omq.system.set-option() api method must be called by sending an appropriately-formatted request to the Qorus HTTP server. Execute the following command-line to send this command to the server:

unixprompt% ocmd set-option <option>=<value>

Output similar to the following should appear: 

OK

No error messages should appear. If an error message appears, see the following section for causes.

This will change the options in the running server. To make the options permanent and write them back out to the System Options File file, you can call omq.system.flush-options() as follows:

unixprompt% ocmd flush-options
Note
See the System Reference Manual for more information on system options, Command-Line Programs for information about Qorus command-line programs, and the Network System API for more information on Qorus API methods.
Common Errors

Error: Invalid Option

Error Message:
ERROR: OPTION-ERROR: one or more options given was invalid
Explanation:
The option name given is not a valid system option.
Possible Cause Action to Take
Option name is incorrect Check the option name (options are case-sensitive) and try the command again with the correct option name. See System Options for a list of system options

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Persistently Redefine Datasource Connection Values

From time to time it may be necessary to reconfigure a Qorus instance to connect to another database. To do this, any datasources pointing to that database must be redefined to point to the new database.

To redefine a user datasource, edit the system datasource (dbparams) File file with the new parameters. Then unload the system datasource service. The next time the datasource service is referenced, it will parse the system datasource (dbparams) File file and initialize all datasources defined in the file with the new definitions. To unload the datasource service from memory, enter the following command:

unixprompt% ocmd delete-service datasource

Output similar to the following should appear: 

OK

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Temporarily Redefine Datasource Connection Values

To temporarily redefine a user datasource connection for the length of an application session (or more correctly, for the duration of time the system datasource service is loaded), call the omq.system.service.datasource.update() API method with the following parameters as follows:

unixprompt% ocmd omq.system.service.datasource.update <name> <type> <user> <password> <dbname> [character_set] [host]

If the named datasource does not exist, it will be created. If it already exists, the login parameters will be redefined and future requests for that datasource will get an object (Datasource or DatasourcePool, depending on the request) using the new connection parameters.

Note
This will only update the definition of the datasource in the datasource service , any workflows or services that have already acquired the datasource will have the old definition; in order to force affected workflows and services to reacquire the datasource with the new definition, you have to reset the workflows and services manually as well by calling omq.system.reset-workflow() or omq.user.reset-service() respectively.
This method only redefines the datasource for the currently-running Qorus application session. To redefine the datasource in a persistent way, see Persistently Redefine Datasource Connection Values or call omq.system.service.datasource.flushToFile() after calling the update method.

Output similar to the following should appear: 

OK

If an error message appears, see the following section for causes.

Common Errors

Error: Missing Parameter

Error Message:
ERROR: UPDATE-DATASOURCE-ERROR: missing <parameter>
Explanation:
One or more of the parameters to the method was not given.
Possible Cause Action to Take
Command-line was incomplete Check the command line and try it again with all required parameters.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Rotate Log Files

To rotate log files, the omq.system.rotate-log-files() API method must be called. This can be done with the ocmd program as follows:

unixprompt% ocmd omq.system.rotate-log-files

Log files will be rotated (and old versions deleted as necessary) according to the configuration of the max-log-files system option. The output should look as follows: 

OK

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

View System Properties

To view system properties, call the omq.system.service.prop.get() API method with optional parameters as follows:

unixprompt% ocmd omq.system.service.prop.get [domain [key]]

If no key is given, all values in the domain are returned. If no domain is given, then all system properties are returned. Example output looks similar to the following: 

hash: (4 members)
  omq : hash: (3 members)
    schema-version : "3.0.3"
    schema-compatibility : "3.0.3"
    schema-load-compatibility : "3.0.2"
  arch : hash: (5 members)
    directory : "/appl/logs/omq/arch"

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Update System Properties

To update system properties, call the omq.system.service.prop.update() API method with the following parameters (note that to delete a key, do not send a value):

unixprompt% ocmd omq.system.service.prop.update <domain> <key> [value]

The output should look as follows: 

INSERT

If an error message appears, see the following section for causes.

Common Errors

Error: Missing Parameter

Error Message:
ERROR: PARAMETER-ERROR: ‘key’ is a required parameter
Explanation:
One or more of the parameters to the method was not given.
Possible Cause Action to Take
Command-line was incomplete Check the command line and try it again with all required parameters.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.