When a STAX Job is executed (e.g. when a STAX EXECUTE request is
submitted), you can specify the RETURNRESULT option (and optionally then
also specify the DETAILS option).
RETURNRESULT is used to specify that you want completion results for the
job returned. This includes information like the job status, result,
errors logged in the job log, testcase totals, etc. This option is only
valid if the WAIT option is specified.
DETAILS is used to specify that you want detailed completion results for
the job returned, including a list of the individual testcase results.
This option is only valid if the WAIT and RETURNRESULT options are
specified.
Upon successful return, the RC will zero. The result buffer will contain
the following based on if the TEST [RETURNDETAILS] or WAIT
[<Number>[s|m|h|d|w]] [RETURNRESULT [DETAILS]] option is specified on the
EXECUTE request:
If neither the TEST nor WAIT option is specified, the result buffer will
contain the Job ID. Note that when the WAIT option is not specified, the
EXECUTE request returns as soon as it starts the STAX job and does not
wait to return until the STAX job has completed.
If the WAIT option is specified:
If a timeout value is specified for the WAIT option and the request times
out before the Job has completed, a RC 37 (Timeout) is returned and the
result buffer will contain the Job ID.
If the RETURNRESULT option is not specified and the request does not
timeout before the Job has completed, the result buffer will contain the
Job ID.
If the RETURNRESULT option is specified and the DETAILS option is not
specified and the request does not timeout before the Job has completed,
the result will contain a marshalled <Map:STAF/Service/STAX/JobResult>
representing the job result. The map is defined as follows:
Definition of map class STAF/Service/STAX/JobResult
Description: This map class represents the result from a STAX job.
Key Name
Display Name
Type
Format / Value
jobID
Job ID
<String>
startTimestamp
Start Date-Time
<String>
<YYYYMMDD-HH:MM:SS>
endTimestamp
End Date-Time
<String>
<YYYYMMDD-HH:MM:SS>
status
Status
<String>
'Normal' | 'Terminated' | 'Abnormal' | 'Unknown'
result
Result
<String> | <None>
jobLogErrors
Job Log Errors
<List> of <Map:STAF/Service/Log/LogRecord>
testcaseTotals
Testcase Totals
<Map:STAF/Service/STAX/TestcaseTotals>
Notes:
1. The "Status" value is the job completion status and it is set to
one of the following:
'Normal' if the job ended normally
'Terminated' if the job was terminated (this means if the 'main' block was
terminated)
'Abnormal' if the job ended abnormally. This can happen when at least one
unhandled inherited condition remains on the condition stack when the job
completes. For example, this can occur when a break or continue condition
remains on the condition stack because there was no outer loop or iterate
element, or when an exception is thrown but there's no catch element for
it. This state takes precedence if the job is also terminated.
'Unknown' if the job has an unknown status. This should not occur.
2. The "Result" value is set to a "string" version of whatever the
job specified to return, or <None> if the job did not specify anything to
return. The job may not return anything if a <return> element is not
executed in the starting function. This could be due to many reasons, such
as an error occurring, the job being terminated, or if the starting
function doesn't contain a <return> element.
3. The "Job Log Errors" value is a list of any errors logged in the
STAX Job Log. If the DEFAULTMAXQUERYRECORDS setting for the LOG service on
the STAX service machine is set to a non-zero number (the default is 100),
then the maximum number of errors logged will be limited to this number
(e.g. equivalent to specifying LAST <Number> on the LOG QUERY request).
For more information on the RETURNRESULT [DETAILS] options for a STAX
EXECUTE request and on the content of the result when these options are
specified, see sub-section "EXECUTE" under the "Request Syntax" section in
the STAX User's Guide at
http://staf.sourceforge.net/current/STAX/staxug.html#Header_Execute.
So, say you had a STAX job, termJob.xml, that looked like:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
<defaultcall function="Main"/>
<function name="Main">
<sequence>
<terminate block="'main'"/>
<!-- Note: Job flow will never get here as the job was terminated -->
<return>'failed'</return>
</sequence>
</function>
</stax>
Executing this job via a STAX EXECUTE request using the RETURNRESULT
option will result in the following. Note that the "Status" is set to
Terminated which indicates that the job was terminated. Whenever a STAX
job is terminated, the "Result" will be set to None because the <return>
element in the starting function ("Main") was never executed since the job
was terminated before it reached the <return>'failed'</return> element.
C:\>STAF local STAX EXECUTE FILE C:/stax/termJob.xml RETURNRESULT WAIT
Response
--------
{
Job ID : 10
Start Date-Time: 20130708-12:34:26
End Date-Time : 20130708-12:34:27
Status : Terminated
Result : None
Job Log Errors : []
Testcase Totals: {
Tests : 0
Passes: 0
Fails : 0
}
}
If a STAX job ends normally (e.g. is not terminated), then the "Status"
will be set to Normal and the "Result" will be set to whatever the job's
starting function returned (or None if the starting function did not
return anything). For example, say you had a STAX job, normalJob.xml,
that looked like::
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
<defaultcall function="Main"/>
<function name="Main">
<sequence>
<log message="1">'Beginning job...'</log>
<return>'Success'</return>
</sequence>
</function>
</stax>
Executing this job via a STAX EXECUTE request using the RETURNRESULT
option will result in the following. Note that the "Status" is set to
Normal which indicates that the job ended normally and the "Result" will
be set to Success because that's what the starting function's <return>
element set it to.
C:\>STAF local STAX EXECUTE FILE C:/stax/normalJob.xml RETURNRESULT WAIT
Response
--------
{
Job ID : 11
Start Date-Time: 20130708-12:47:29
End Date-Time : 20130708-12:47:29
Status : Normal
Result : Success
Job Log Errors : []
Testcase Totals: {
Tests : 0
Passes: 0
Fails : 0
}
}
You can also get the result from a completed STAX job by submitting a STAX
GET RESULT JOB <Job ID> [DETAILS] request after a STAX job has completed.
For more information, see sub-section "GET RESULT" under the "Request
Syntax" section in the STAX User's Guide at
http://staf.sourceforge.net/current/STAX/staxug.html#Header_GetResult.
The STAX Monitor submits a STAX EXECUTE request to run the specified STAX
job. Its "Active Jobs" table, as described in sub-section "Displaying a
List of Active Jobs" under section "STAX Monitoring" in the STAX User's
Guide at
http://staf.sourceforge.net/current/STAX/staxug.html#Header_MonJobList,
says that the Status and Result fields it displays will contain:
Status - "Pending" if the job is in the process of being submitted for
execution, "Running" if the job is currently running, or "Complete" if the
job has completed but is still being monitored.
Result - A "string" version of the Job Result. Private data will be
masked.
So, the "Status" field for the STAX Monitor's "Active Jobs" table will
always show "Complete" if the job has completed no matter if it completed
normally or was terminated (as its "Status" field is not the same as the
"Status" field in the result provided by a STAX EXECUTE RETURNRESULTS or
STAX GET RESULTS request. However, you can look at the STAX Job Log via
the STAX Monitor, to check if a message was logged stating the job was
terminated or you could submit a STAX GET RESULT request for this job to
determine if the job "Status" was set to Normal, Terminated, or Abnormal.
The "Result" field for the STAX Monitor's "Active Jobs" table is the same
as the "Result" field in the result provided by a STAX EXECUTE
RETURNRESULTS or STAX GET RESULT request. So, the "Result" value is set
to a "string" version of whatever the job specified to return, or None if
the job did not specify anything to return. The job may not return
anything if a <return> element is not executed in the starting function.
This could be due to many reasons, such as an error occurring, the job
being terminated, or if the starting function doesn't contain a <return>
element.
I hope this helps explain things.
--------------------------------------------------------------
Sharon Lucas
IBM Austin, luc...@us.ibm.com
(512) 286-7313 or Tieline 363-7313
From: Cyril SANTUNE <cyril.sant...@gmail.com>
To: staf-users@lists.sourceforge.net,
Date: 07/03/2013 05:11 AM
Subject: [staf-users] [STAX] Change the result and status in Job
monitor
Hi,
I call a stax xml job that contains :
-------------------------------------------------------------
<stax>
...
<function name="main">
...
<terminate block="main"/>
...
<return>job_result</return>
</function>
</stax>
-------------------------------------------------------------
I set the variable "job_result" to return a result for my job.
But in case of error, I stop the job before the end (terminate block end).
In this case, in job monitor, the status is "complete" and the result is
"none".
I want to return meaningful result in this case, something like, status =
error and result = failed
How can I do that ?
------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.
http://p.sf.net/sfu/windows-dev2dev
_______________________________________________
staf-users mailing list
staf-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/staf-users
------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.
http://p.sf.net/sfu/windows-dev2dev
_______________________________________________
staf-users mailing list
staf-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/staf-users
