Server - Shell Commands

Short and /Long Command Name

Command

[SOLUTIONID
[COMPONENTID
[TRANSACTIONID
[TASKEXECID
[MIN_LOG_LEVEL
[MAX_RECORDS
[FROM_DATE
[TO_DATE]
]]]]]]]

Fetches log records from the database and prints them. All arguments are optional. By default all log records (ever) are printed. Each argument narrows down which log records are printed. The order above is particular: to specify MIN_LOG_LEVEL, for example, you have to specify all other arguments before it.

A log record has several ID fields. Each of these may be null or not. If you want only log records that have a certain field equal to a certain value, specify a value for that field.

Passing in null for an ID argument (the default) means to not exclude records from output based on that field. It does not mean to only print records which have a value of null. Nor does it mean to only print records which have a value that is the string "null". There will never be such an ID anyway.

Since the default is to print all log records ever, and there could be millions, a good rule of thumb is to specify at least SOLUTIONID and one other ID.

ID arguments all have a default of null.

MIN_LOG_LEVEL: Only print log records with a level greater than or equal to this. One of DEBUG, INFO, WARN, ERROR. Default: INFO.

Note that the server maintains it's own filter log level, and records below that level won't be written to the database. So don't be surprised if you pass in a certain log level as this argument yet see no records at that level in the output. This probably just means that the server's filter log level at the time was higher than the log level you just specified.

MAX_RECORDS: Maximum number of records to print. inf ==> infinite; no limit. Records exceeding this maximum will be removed from the end of the output. (Output is in ascending chronological order.) Default: inf

FROM_DATE: Return only records more recent than or the same age as this date. Or 'null' to impose no lower bound. Date must be in this
format: yyyy-MM-dd HH:mm:ss.SSS Default: null

TO_DATE: Same as FROM_DATE, but defines the recent end of the desired range instead.

Sets the server's global log filter level. Log records below this level will neither be written to the database nor sent to any log listeners (such as the GUI monitor.) When the server is started it has a global filter level of INFO.

LOG_LEVEL: One of DEBUG, INFO, WARN, ERROR.

Print the status of interfaces. (That is, events and tasks.) If SOLN_ID is specified, then print status for only that solution's interfaces; otherwise, those of all loaded solutions.

Status consists of:

- a time stamp (when the interface reported its status to the server core)
- a flag indicating the whether the interface is running or paused.
- a flag indicating the wellness of the interface (OK, WARNING, or ERROR)
- some statistics on the activity of the interface, since the solution has been loaded this time around.
- a message

Generally, if an interface is an event, and it doesn't report it's status to the server core every so often (how often is an internal variable -- perhaps 5 seconds), it will show up as being in ERROR. Interfaces can exempt themselves from this rule if they are going to block -- on network input for example. If they exempt themselves their last message could be a year old and they will still show up as OK.

Also generally, if an interface is a task, the timeout rule does not apply, as tasks (generally) are simply executed, then sit idle (as opposed to events, which stick around doing things.) In this general case the status is determined from whether the last execution was successful or not. Alternately, certain types of tasks opt into being polled for status updates periodically. Such a task is able to change its status even if it hasn't executed in a while.

The status messages that interfaces report are of course specific to each type of interface, but they are all all intended to be human-readable and useful. They tend to say more when something is wrong than when everything is fine.

load

Load the solution file FILE.

This should be a path on the server's machine, not the local machine. If FILE is relative, it will be interpreted relative to the current directory of the server process, which will probably be the 'bin' subdirectory of the application, but this is not guaranteed.

Arguments after FILE are optional, and are in the order they appear above, so to specify DO_ALERTS, for example, you have to specify everything before it.

USE_DB: true or false: whether to record component output etc. in the database. Default: true.

RESTORE_FROM_DB: true or false: Whether to try to reconstruct transactions from a certain persisted solution ID in the database. Only used if USE_DB is true. Which solution ID to restore from is determined by SOLUTIONID_IN_DB_TO_RESTORE_FROM. The IDs of transactions started by this loading of the solution will start just after the last transaction ID found for the solution ID in the database. Default: true.

SOLUTIONID_IN_DB_TO_RESTORE_FROM: A solution ID (which will look something like SOLN1234), or null. Only used if RESTORE_FROM_DB is true. If a solution ID: the solution ID in the database to reconstruct from. If null: we will search for a persisted solution in the database that has a signature that matches the solution file currently being loaded. If we find a match, we use it, and reconstruct any unfinished transactions. If we can't find a match, behaviour will be as though as though RESTORE_FROM_DB was false. A new solution ID will be assigned. Default: null.

LOAD_SUSPENDED: Suspend all events and tasks immediately upon loading. If true, no events will fire and no tasks will execute until they are resumed (whether individually or with "resumeallcomponents".) Default: false.

DO_ALERTS: true or false: whether to honour solution- and task-level settings for e-mail / sms alerts. Default: true.

loadlocal

Load the solution file FILE, which resides on the local machine -- not the server machine. The file's contents will be automatically sent to the server. If FILE is relative, it will be interpreted relative to the current directory.

All other options are the same as for "resumeallcomponents".

Prints the given task's input queue. The elements at the front of the queue are printed first.

Note the task exec IDs printed. Every task input queue element in a solution will have a unique task exec ID. (Unique within the solution,
that is.) You will need one of these IDs to identify a queue element for a remove, modify, or insert operation.

INCLUDE_COMP_INPUTS_INFO: true or false. Whether to print the lists of which inputting components' outputs have been received vs. which are still being waited on. For each input that has already arrived, the XML document will be printed as well. Default: false.

Prints a list of past outputs of the specified task. If a particular execution result is a success or a failure, then the outputted XML will be printed as well. (No XML is output with branch cancels.)

INCLUDE_XML_DOCS: true or false. Whether to include any output XML documents in the listing.
Default: false.

LAST_N: Get only this many of the most recent result. -1 ==> no max -- get all.

FROM_DATE: Return only records more recent than or the same age as this date. Or 'null' to impose no lower bound. Date must be in this
format: yyyy-MM-dd HH:mm:ss.SSS Default: null

TO_DATE: Same as FROM_DATE, but defines the recent end of the desired range instead.

Suspend the interface (that is, event or task) with id COMPONENT_ID, within the solution with id SOLUTIONID. Solution IDs must be unique within in the server, and component IDs must be unique within their solutions. Therefore this will suspend a maximum of one event.

If the interface is an event:

Suspending an event prevents it from firing. What this means is particular to each type of event, but the general contract stipulates that the event shut down just as if the entire solution had been unloaded. e.g. a server socket will be closed.

Even "placeholder" events, such as those that are fired by external programs, such as the database event or the coldfusion
event (which you may or may not have in your installation), will not fire while suspended.

If the interface is a task:

If an event upstream from this task fires while this task is suspended, the task will not execute, but rather it's input queue will build up. Naturally it will not be sending any output to tasks downstream of it either.

Opposite of 'suspendinterfacebyid'.

If the interface is an event:

It will be loaded and able to fire again -- eg. attempt to acquire it's server socket.

If the interface is a task:

It will begin processing any queue-up messages, outputting data to downstream tasks again, and performing business-oriented side effects.

Resumes all events and tasks in the given solution. If some weren't suspended, that doesn't matter.

SOLUTIONID

TASKID

Removes the specified task queue input element.

The element at the front of the queue may only be removed if the task is paused, because if it's not paused, then that element is already executing, and it's too late to remove it.

Modifies the XML data within the specified task input queue element.

The element at the front of the queue may only be modified if the task is paused, because if it's not paused, then that element is already
executing, and it's too late to modify it.

INPUTCOMPID is the inputting component whose output you want to override. For example, consider a solution that looks like this:

E1
|
R3---T2

If you want to modify an input queue element of the task T2, then you could give an INPUTCOMPID of E1 or R3. (If you want to modify this element's copy of the output from both E1 and R3, you must call this command twice.)

One restriction: if your target queue element is still waiting for output from some components, you may not supply supply output for those elements. You can only change this queue element's copy of the output it has already received.

INPUTXMLFILENAME is a file containing some XML. If this argument is not present, standard input is read instead.

Inserts a new element into the given task's input queue.

TASKEXECIDTOINSERTAFTER This argument allows you to insert the new element anywhere in the queue, not just at the end.

Note for power users:
You can only use this method to insert into the part of the queue where the elements are not waiting for any outputs from other components. So "the end of the queue" here really means: the end of the part of the queue where all inputs have arrived.

If you just want to add the new element to the end of the queue, give the word 'null' for this argument. Otherwise, the new task queue element will be inserted after the element with the given exec ID. If this exec ID can't be found, then the operation fails.

INPUTCOMPID0 INPUTXMLFILENAME0, 1, 2, ....
are pairs of inputting comp IDs and files containing XML data to be fed to the task. Each task's needs are precise; in the example solution above, to insert a new queue element into T2's queue, you would need to supply two XML documents, resulting in 4 args for this part:

E1
someXmlThatLooksLikeItCameFromE1.xml
R3
someXmlThatLooksLikeItCameFromR3.xml

If you want to pass in a null document, pass in an empty argument for a filename (how to do this depends on your shell, but "" will probably work.)

TASKEXECID refers to an execution that finished some time in the past. (Unlike some other commands which require a task exec ID which refers to an element in an input queue.) These IDs are available from a historical results listing, whether from this program or the GUI monitor.

This command will first fetch, from the database, the original XML input documents that fed the specified historical execution. Then it will make a new input element from these historical inputs and place it on the end of the task's input queue, ready for execution.

The new input queue element will have a new execution ID.

(Each task exec ID is tied to a certain task. This happens to be the last task ID that appears in the exec ID. Any other task IDs appearing in an exec ID are tasks that are upstream of the task in question -- the task whose execution the exec ID identifies. This is why there is no TASKID parameter to this command. It would be redundant.)