CSActiveScriptJob
in package
API Object for the ActiveScriptJob Record
Tags
Table of Contents
- INPUT_DATA_KEY = 'INPUT_DATA'
- OUTPUT_DATA_KEY = 'OUTPUT_DATA'
- Constants for the storage of output and input job data in the properties
- START_LOCK_VALUE = -1
- The start value for the lock file handling.
- __construct() : CSActiveScriptJob
- The Constructor
- _endRecord() : mixed
- Ends the Job Output
- _startRecord() : mixed
- Starts the Job Output
- canBeInterrupted() : bool
- Checks whether the current plugin is defined to be interruptible.
- delete() : void
- Deletes the job
- errorHandler() : mixed
- Custom error handler
- existsJobStartLockFile() : bool
- Checks if the start job lock file still exists.
- getActive() : string
- Retrieves the Time Stamp as formatted String when the last Job update was sent
- getActiveScript() : CSActiveScript
- Returns the ActiveScript of this job
- getActiveScriptID() : int
- Returns the ActiveScripts ID for this job
- getActiveScriptLogs() : array<string|int, CSActiveScriptLog>
- Gets all logs for this job
- getActiveScriptPlugin() : CSActiveScriptPlugin
- Returns the ActiveScript plugin of this job
- getAvatarID() : int
- Returns the ID of the user under which identity was running the script
- getCreationDate() : string
- Retrieves the timestamp as formatted String when the job was created
- getCurrentStep() : CSActiveScriptStep
- Tells which step was reached most recently
- getCurrentStepPosition() : int
- Returns the current step position that is stored in the database.
- getDuration() : string
- Tells how long this script was or is running
- getEnd() : string
- Retrieves the Time Stamp as formatted String when the Job was ended
- getErrorCount() : int
- getID() : int
- Retrieves the ID
- getInputValue() : string
- Gets an input value of an ActiveScriptJob
- getNextJobID() : int
- If the script was configured to start a follow up job this method will return the ID of this job
- getOutputData() : CSActiveScriptJobOutputData
- getOutputValue() : string
- Gets a value for a given output key of the current job
- getProgress() : float
- Tells how many percent of the intended steps have been executed
- getRecord() : ActiveScriptJob
- Returns the internal job database record
- getStart() : string
- Retrieves the Time Stamp as formatted String when the Job was started
- getStatus() : int
- Tells the Status of this job
- getStatusColor() : string
- Gives the color name that should be used for the current iStatus in CSS sheets
- getStatusIcon() : string
- Gives the icon that should be used for the current iStatus
- getStatusLabel() : string
- Tells the iStatus of this job as formatted string
- getStatusName() : string
- Tells the non localized iStatus of this job as formatted string
- getStepList() : CSActiveScriptStepList
- Returns the current step list for this job
- getUserID() : int
- Returns the ID of the user that was starting the script
- getValue() : string
- Gets a value
- getWarningCount() : int
- hasEnded() : bool
- Tells if the job reached a final state and will not change any more
- isInOngoingStatus() : bool
- Checks whether the job is still in an ongoing status.
- isInterruptionRequested() : bool
- Tells if a running script job was requested to interrupt
- isJobStarted() : bool
- returns whether a lock file exists for the given ActiveScriptJob
- isPaused() : bool
- Tells if a running script job was requested to interrupt
- isPauseRequested() : bool
- Tells if a running script job was requested to interrupt
- isProcessRunning() : bool
- Checks whether the job process is still running. The check depends on an exclusive lock to be able to handle webserver crashes.
- isRunning() : bool
- Tells if a script script job is still running
- lockJobStart() : bool
- Creates a lock file to mark that job is started
- log() : CSActiveScriptLog
- Adds a Log entry
- logDebug() : CSActiveScriptLog
- Adds a debug Log entry
- logError() : CSActiveScriptLog
- Adds an error Log entry
- logResult() : CSActiveScriptLog
- Adds a Log entry that is considered as an important result
- logResultLink() : CSActiveScriptLog
- Logs an important result as link that can be opened or downloaded in a web browser
- logWarning() : CSActiveScriptLog
- Adds a warning Log entry
- requestInterruption() : void
- Requests an interruption for this job
- requestPause() : void
- Requests a pause for this job
- rerun() : void
- Reruns an active script job in the foreground. This method should only be used if the previous PHP process has been stopped. It will trigger a new PHP process to rerun the active script job in the foreground.
- restart() : void
- Restarts an active script job without waiting for the processing results
- resume() : void
- Resumes a job that was previously paused.
- run() : mixed
- Runs the ActiveScriptJob in the foreground according to the current parameters set of the ActiveScript
- setActive() : void
- Defines the Time Stamp as formatted String when the Job was updated the last time
- setAvatarID() : mixed
- Sets the ID of the user under which identity the script should run
- setDuration() : void
- Sets the Duration time telling how long this script was or is running
- setEnd() : void
- Defines the Time Stamp as formatted String when the Job was ended
- setNextJobID() : void
- If the script was configured to start a follow up job this method will set the ID of this job
- setOutputValue() : void
- Sets an output value of an ActiveScriptJob
- setStart() : void
- Defines the Time Stamp as formatted String when the Job was started
- setStatus() : void
- Sets the iStatus of this job
- setUserID() : mixed
- Sets the ID of the user that was starting the script
- setValue() : void
- Sets a value
- shouldBeKeptAlive() : bool
- Checks whether the current plugin is defined to be kept alive. Only CORE jobs are allowed to define itself as kept alive scripts.
- start() : void
- Kicks off an not yet started job without waiting for the processing results
- store() : void
- Stores the active script job
- supportsAutomaticResume() : bool
- Defines whether the job supports automatic resume or not.
- unlockJobStart() : bool
- Deletes a lock file if exists
- update() : mixed
- Allows to update values for a job and write them directly into the database
Constants
INPUT_DATA_KEY
public
mixed
INPUT_DATA_KEY
= 'INPUT_DATA'
Tags
OUTPUT_DATA_KEY
Constants for the storage of output and input job data in the properties
public
mixed
OUTPUT_DATA_KEY
= 'OUTPUT_DATA'
Tags
START_LOCK_VALUE
The start value for the lock file handling.
public
int
START_LOCK_VALUE
= -1
Tags
Methods
__construct()
The Constructor
public
__construct(mixed $mActiveScriptJobID[, CSActiveScriptJobInputData $oInputData = null ]) : CSActiveScriptJob
Parameters
- $mActiveScriptJobID : mixed
-
The ID of the active script job or the job record itself
- $oInputData : CSActiveScriptJobInputData = null
Tags
Return values
CSActiveScriptJob —_endRecord()
Ends the Job Output
public
_endRecord(int $iStatus[, bool $bKeepAlive = false ][, bool $bRunAfterScript = true ]) : mixed
Parameters
- $iStatus : int
-
the status as one of the CSActiveScript::ACTIVESCRIPT_STATUS_* constants
- $bKeepAlive : bool = false
-
whether the current job is configured to be kept alive
- $bRunAfterScript : bool = true
-
whether to run the onAfterRunScript() method from the plugin
Tags
Return values
mixed —_startRecord()
Starts the Job Output
public
_startRecord() : mixed
Tags
Return values
mixed —canBeInterrupted()
Checks whether the current plugin is defined to be interruptible.
public
canBeInterrupted() : bool
Tags
Return values
bool —True, if the job qualifies itself to be interruptible, otherwise false.
delete()
Deletes the job
public
delete() : void
Tags
Return values
void —errorHandler()
Custom error handler
public
errorHandler(int $code, string $message) : mixed
Parameters
- $code : int
-
the error code
- $message : string
-
the error message
Tags
Return values
mixed —existsJobStartLockFile()
Checks if the start job lock file still exists.
public
static existsJobStartLockFile(int $iActiveScriptJobId) : bool
Parameters
- $iActiveScriptJobId : int
-
The ID of the ActiveScriptJob
Tags
Return values
bool —if the start job lock file still exists.
getActive()
Retrieves the Time Stamp as formatted String when the last Job update was sent
public
getActive() : string
Tags
Return values
string —the time stamp as formatted string
getActiveScript()
Returns the ActiveScript of this job
public
getActiveScript() : CSActiveScript
Tags
Return values
CSActiveScript —the CSActiveScript object
getActiveScriptID()
Returns the ActiveScripts ID for this job
public
getActiveScriptID() : int
Tags
Return values
int —the ActiveScriptID
getActiveScriptLogs()
Gets all logs for this job
public
getActiveScriptLogs([int $iSortOrder = CS_SORT_NUMERICAL_ASC ][, int $iLimit = null ]) : array<string|int, CSActiveScriptLog>
Parameters
- $iSortOrder : int = CS_SORT_NUMERICAL_ASC
-
either CS_SORT_DATE_ASC or CS_SORT_DATE_DESC to sort ascending/descending by timestamp
- $iLimit : int = null
-
if greater than 0 then the results will be limited to this number
Tags
Return values
array<string|int, CSActiveScriptLog> —array with the logs for this job
getActiveScriptPlugin()
Returns the ActiveScript plugin of this job
public
getActiveScriptPlugin() : CSActiveScriptPlugin
Tags
Return values
CSActiveScriptPlugin —The ActiveScript plugin of this job.
getAvatarID()
Returns the ID of the user under which identity was running the script
public
getAvatarID() : int
Tags
Return values
int —the UserID of the Avatar
getCreationDate()
Retrieves the timestamp as formatted String when the job was created
public
getCreationDate() : string
Tags
Return values
string —the timestamp as formatted string
getCurrentStep()
Tells which step was reached most recently
public
getCurrentStep() : CSActiveScriptStep
Tags
Return values
CSActiveScriptStep —the latest step
getCurrentStepPosition()
Returns the current step position that is stored in the database.
public
getCurrentStepPosition() : int
Tags
Return values
int —The current step position.
getDuration()
Tells how long this script was or is running
public
getDuration() : string
Tags
Return values
string —the duration as CS formatted time string
getEnd()
Retrieves the Time Stamp as formatted String when the Job was ended
public
getEnd() : string
Tags
Return values
string —the time stamp as formatted string
getErrorCount()
public
getErrorCount() : int
Tags
Return values
int —the number of errors that were logged to this job
getID()
Retrieves the ID
public
getID() : int
Tags
Return values
int —The ID
getInputValue()
Gets an input value of an ActiveScriptJob
public
getInputValue(string $sKey) : string
Parameters
- $sKey : string
-
the key of the value
Tags
Return values
string —the value or false if the key is not available
getNextJobID()
If the script was configured to start a follow up job this method will return the ID of this job
public
getNextJobID() : int
Tags
Return values
int —the follow up Job ID
getOutputData()
public
getOutputData() : CSActiveScriptJobOutputData
Tags
Return values
CSActiveScriptJobOutputData —the output
getOutputValue()
Gets a value for a given output key of the current job
public
getOutputValue(mixed $sKey) : string
Parameters
- $sKey : mixed
Tags
Return values
string —getProgress()
Tells how many percent of the intended steps have been executed
public
getProgress() : float
Tags
Return values
float —a number between 0 and 1
getRecord()
Returns the internal job database record
public
getRecord() : ActiveScriptJob
Tags
Return values
ActiveScriptJob —getStart()
Retrieves the Time Stamp as formatted String when the Job was started
public
getStart() : string
Tags
Return values
string —the time stamp as formatted string
getStatus()
Tells the Status of this job
public
getStatus([bool $bLoadFromDB = false ]) : int
Parameters
- $bLoadFromDB : bool = false
-
if true the job record will be loaded fresh from the disk to also reflect external status changes
Tags
Return values
int —the iStatus as one of the CSActiveScript::ACTIVE_SCRIPT_STATUS_* constants
getStatusColor()
Gives the color name that should be used for the current iStatus in CSS sheets
public
getStatusColor() : string
Tags
Return values
string —the color name like purple or red, which should be used as css classes
getStatusIcon()
Gives the icon that should be used for the current iStatus
public
getStatusIcon() : string
Tags
Return values
string —the icon relative to the admin
getStatusLabel()
Tells the iStatus of this job as formatted string
public
getStatusLabel([string $language = null ]) : string
Parameters
- $language : string = null
-
the short name of the language if the name should be translated
Tags
Return values
string —the iStatus name as one of the CSActiveScript::ACTIVE_SCRIPT_STATUS_* constants
getStatusName()
Tells the non localized iStatus of this job as formatted string
public
getStatusName() : string
Tags
Return values
string —the non localized iStatus name as one of the CSActiveScript::ACTIVE_SCRIPT_STATUS_* constants
getStepList()
Returns the current step list for this job
public
getStepList() : CSActiveScriptStepList
Tags
Return values
CSActiveScriptStepList —the step list
getUserID()
Returns the ID of the user that was starting the script
public
getUserID() : int
Tags
Return values
int —the UserID
getValue()
Gets a value
public
getValue(string $name) : string
Parameters
- $name : string
Tags
Return values
string —the value
getWarningCount()
public
getWarningCount() : int
Tags
Return values
int —the number of warnings that were logged to this job
hasEnded()
Tells if the job reached a final state and will not change any more
public
hasEnded() : bool
Tags
Return values
bool —true if it has ended
isInOngoingStatus()
Checks whether the job is still in an ongoing status.
public
isInOngoingStatus([bool $bLoadStatusFromDB = false ]) : bool
Parameters
- $bLoadStatusFromDB : bool = false
-
Whether the value should be requested directly from DB or can be used from the loaded object.
Tags
Return values
bool —whether the job is still in an ongoing status.
isInterruptionRequested()
Tells if a running script job was requested to interrupt
public
isInterruptionRequested() : bool
Tags
Return values
bool —true if interruption was requested
isJobStarted()
returns whether a lock file exists for the given ActiveScriptJob
public
static isJobStarted(int $iActiveScriptJobId) : bool
Parameters
- $iActiveScriptJobId : int
-
The ID of the ActiveScriptJob
Tags
Return values
bool —True if a lockfile exists
isPaused()
Tells if a running script job was requested to interrupt
public
isPaused() : bool
Tags
Return values
bool —true if interruption was requested
isPauseRequested()
Tells if a running script job was requested to interrupt
public
isPauseRequested() : bool
Tags
Return values
bool —true if interruption was requested
isProcessRunning()
Checks whether the job process is still running. The check depends on an exclusive lock to be able to handle webserver crashes.
public
isProcessRunning() : bool
Tags
Return values
bool —true if the job is running, otherwise false.
isRunning()
Tells if a script script job is still running
public
isRunning() : bool
Tags
Return values
bool —true if the active script job is still running.
lockJobStart()
Creates a lock file to mark that job is started
public
static lockJobStart(int $iActiveScriptJobId[, int $iTryNumber = self::START_LOCK_VALUE ]) : bool
Parameters
- $iActiveScriptJobId : int
-
The ID of the ActiveScriptJob
- $iTryNumber : int = self::START_LOCK_VALUE
-
The number of the executed tries.
Tags
Return values
bool —true if the lock file exists or was created successfully
log()
Adds a Log entry
public
log(mixed $sMessage[, mixed $iStatus = CSActiveScript::ACTIVE_SCRIPT_STATUS_OK ]) : CSActiveScriptLog
Parameters
- $sMessage : mixed
- $iStatus : mixed = CSActiveScript::ACTIVE_SCRIPT_STATUS_OK
Tags
Return values
CSActiveScriptLog —logDebug()
Adds a debug Log entry
public
logDebug(string $sMessage) : CSActiveScriptLog
Parameters
- $sMessage : string
-
the log message
Tags
Return values
CSActiveScriptLog —logError()
Adds an error Log entry
public
logError(string $sMessage) : CSActiveScriptLog
Parameters
- $sMessage : string
-
the log message
Tags
Return values
CSActiveScriptLog —logResult()
Adds a Log entry that is considered as an important result
public
logResult(string $sMessage) : CSActiveScriptLog
As "important" results you can consider any kind of information that would matter after the script has ended, e.g. the final result of a calculation.
When the result is contained in a file or can be looked up at a permanent URL please use the method @see logResultLink.
When a user runs a script he will see such result logs in a prominent and visually important design.
Parameters
- $sMessage : string
-
log message
Tags
Return values
CSActiveScriptLog —logResultLink()
Logs an important result as link that can be opened or downloaded in a web browser
public
final logResultLink(string $sUrl[, mixed $sFileName = null ][, string $sFolderPrefix = null ][, string $sDescription = null ][, string $sTarget = '_blank' ]) : CSActiveScriptLog
Parameters
- $sUrl : string
-
the URL that a browser can open to retrieve the result link
- $sFileName : mixed = null
- $sFolderPrefix : string = null
-
the folder prefix the link should be stored with when using finalizer steps
- $sDescription : string = null
-
any additional description regarding the link
- $sTarget : string = '_blank'
-
the optional HTML link target like _blank, _self or _top or the name of a window
Tags
Return values
CSActiveScriptLog —logWarning()
Adds a warning Log entry
public
logWarning(string $sMessage) : CSActiveScriptLog
Parameters
- $sMessage : string
-
the log message
Tags
Return values
CSActiveScriptLog —requestInterruption()
Requests an interruption for this job
public
requestInterruption() : void
Tags
Return values
void —requestPause()
Requests a pause for this job
public
requestPause() : void
Tags
Return values
void —rerun()
Reruns an active script job in the foreground. This method should only be used if the previous PHP process has been stopped. It will trigger a new PHP process to rerun the active script job in the foreground.
public
rerun() : void
Tags
Return values
void —restart()
Restarts an active script job without waiting for the processing results
public
restart() : void
This method runs the script in the background. If you are looking for a way to rerun the actual work in the foreground use the method rerun() instead.
Tags
Return values
void —resume()
Resumes a job that was previously paused.
public
resume() : void
The job can only be resumed if the PHP process is still running.
Tags
Return values
void —run()
Runs the ActiveScriptJob in the foreground according to the current parameters set of the ActiveScript
public
run() : mixed
This method does the actual work and needs as long as the work of the script plugin is done. If you are looking for a method to start the job in the background and resume immediately use the method start() instead.
Tags
Return values
mixed —setActive()
Defines the Time Stamp as formatted String when the Job was updated the last time
public
setActive([string $sActive = null ]) : void
Parameters
- $sActive : string = null
-
the last update as formatted date string
Tags
Return values
void —setAvatarID()
Sets the ID of the user under which identity the script should run
public
setAvatarID(int $iAvatarID) : mixed
Parameters
- $iAvatarID : int
-
the UserID of the Avatar
Tags
Return values
mixed —setDuration()
Sets the Duration time telling how long this script was or is running
public
setDuration(string $sDuration) : void
Parameters
- $sDuration : string
-
the duration as CS formatted time string
Tags
Return values
void —setEnd()
Defines the Time Stamp as formatted String when the Job was ended
public
setEnd([string $sEnd = null ]) : void
Parameters
- $sEnd : string = null
-
the end as formatted date string
Tags
Return values
void —setNextJobID()
If the script was configured to start a follow up job this method will set the ID of this job
public
setNextJobID(int $iNextJobID) : void
Parameters
- $iNextJobID : int
-
the follow up Job ID
Tags
Return values
void —setOutputValue()
Sets an output value of an ActiveScriptJob
public
setOutputValue(string $sKey, string $sValue) : void
Parameters
- $sKey : string
-
the key
- $sValue : string
-
the value
Tags
Return values
void —setStart()
Defines the Time Stamp as formatted String when the Job was started
public
setStart([string $sStart = null ]) : void
Parameters
- $sStart : string = null
-
the start as formatted date string
Tags
Return values
void —setStatus()
Sets the iStatus of this job
public
setStatus(int $iStatus[, bool $bWriteToDB = false ]) : void
Parameters
- $iStatus : int
-
the iStatus as one of the CSActiveScript::ACTIVE_SCRIPT_STATUS_* constants
- $bWriteToDB : bool = false
-
if true the status is written also to the db
Tags
Return values
void —setUserID()
Sets the ID of the user that was starting the script
public
setUserID(int $iUserID) : mixed
Parameters
- $iUserID : int
-
the UserID
Tags
Return values
mixed —setValue()
Sets a value
public
setValue(string $name, string $value) : void
Parameters
- $name : string
- $value : string
Tags
Return values
void —shouldBeKeptAlive()
Checks whether the current plugin is defined to be kept alive. Only CORE jobs are allowed to define itself as kept alive scripts.
public
shouldBeKeptAlive() : bool
Tags
Return values
bool —True, if the job qualifies itself to be a keep alive job, otherwise false.
start()
Kicks off an not yet started job without waiting for the processing results
public
start() : void
This method runs the script in the background. If you are looking for a way to run the actual work in the foreground use the method run() instead.
Tags
Return values
void —store()
Stores the active script job
public
store() : void
Tags
Return values
void —supportsAutomaticResume()
Defines whether the job supports automatic resume or not.
public
supportsAutomaticResume() : bool
Tags
Return values
bool —true, if automatic resume is supported, otherwise false.
unlockJobStart()
Deletes a lock file if exists
public
static unlockJobStart(int $iActiveScriptJobId) : bool
Parameters
- $iActiveScriptJobId : int
-
The ID of the ActiveScriptJob
Tags
Return values
bool —true if deletion was successful
update()
Allows to update values for a job and write them directly into the database
public
update(mixed $values) : mixed
Parameters
- $values : mixed
-
array with key and val for updates