Menu

#860 Document RETURNDETAILS option for STAX EXECUTE TEST request

Next
closed-fixed
5
2006-12-04
2006-11-28
No

Document the RETURNDETAILS option for a STAX EXECUTE TEST request and it's result.

It's used by the STAX Job Wizard and others who want be create their own STAX Monitor application might want to use it.

Discussion

  • Sharon Lucas

    Sharon Lucas - 2006-11-28
    • labels: 352137 --> STAX::Service
     
  • Sharon Lucas

    Sharon Lucas - 2006-12-04

    Logged In: YES
    user_id=285070
    Originator: YES

    Here's a cvs diff of the changes:

    Index: services/stax/History

    RCS file: /cvsroot/staf/src/staf/services/stax/History,v
    retrieving revision 1.255
    diff -r1.255 History
    16a17,18
    > - Document the RETURNDETAILS option for a STAX EXECUTE TEST request in the
    > help and in the STAX User's Guide (Bug #1604748)
    Index: services/stax/service/STAX.java
    ===================================================================
    RCS file: /cvsroot/staf/src/staf/services/stax/service/STAX.java,v
    retrieving revision 1.104
    diff -r1.104 STAX.java
    3135c3135,3136
    < " [ HOLD | TEST | WAIT [Timeout] [RETURNRESULT] ]" +
    ---
    > " [ HOLD | TEST [RETURNDETAILS] | " +
    > "WAIT [Timeout] [RETURNRESULT] ]" +
    Index: services/stax/docs/userguide/staxug.html
    ===================================================================
    RCS file: /cvsroot/staf/src/staf/services/stax/docs/userguide/staxug.html,v
    retrieving revision 1.149
    diff -r1.149 staxug.html
    24c24
    < <p><b>November 8, 2006</b>
    ---
    > <p><b>December 4, 2006</b>
    5135c5135
    < [ HOLD | TEST | WAIT [Timeout] [RETURNRESULT] ]
    ---
    > [ HOLD | TEST [RETURNDETAILS] | WAIT [Timeout] [RETURNRESULT] ]
    5196c5196
    < <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [ HOLD | TEST | WAIT [Timeout] [RETURNRESULT] ]</tt>
    ---
    > <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [ HOLD | TEST [RETURNDETAILS] | WAIT [Timeout] [RETURNRESULT] ]</tt>
    5265a5266,5272
    > <p><tt>RETURNDETAILS</tt> is used to specify that you want details about the functions
    > defined for the specified XML document returned. This option is only valid if
    > the <tt>TEST</tt> option is specified.
    > You probably would not use this option unless you were writing your own application
    > to submit a STAX job for execution. For example, the STAX Monitor application's
    > Job Wizard submits a STAX EXECUTE request using this option to populate it's screens
    > that allow you to select a function and enter argument values.
    5313,5314c5320,5324
    < <li>Upon successful return, if the TEST or RETURNRESULT options are not specified, the result buffer
    < contains the Job ID.</li>
    ---
    > <li>Upon successful return, if neither the <tt>TEST</tt> nor <tt>WAIT</tt> options are specified,
    > the result buffer will contain the Job ID.
    > Note that when the <tt>WAIT</tt> option is not specified, the <tt>EXECUTE</tt> request
    > returns as soon as it starts the STAX job and does not wait to return until the STAX
    > job has completed.
    5316,5319c5326,5331
    < <li>Upon successful return, if the TEST option is specified, the result buffer contains nothing.
    < If an error occurs (e.g. due to an invalid execution option or an XML parsing error or
    < a Python compile error in the specified XML document), an error message is returned.
    < </li>
    ---
    > <li>If the <tt>WAIT</tt> option is specified:
    > <p>
    > <ul>
    > <li>If a timeout value is specified for the <tt>WAIT</tt> 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.</li>
    5321,5322c5333,5334
    < <li>If the WAIT option is specified with a Timeout, and the request times out before
    < the Job has completed, a RC 37 (Timeout) is returned and the result buffer contains the Job ID.</li>
    ---
    > <li>If the <tt>RETURNRESULT</tt> option is not specfied and the request does not timeout before
    > the Job has completed, the result buffer will contain the Job ID.</li>
    5324c5336
    < <li>If the WAIT and RETURNRESULT options are specified, and the request does not timeout before
    ---
    > <li>If the <tt>RETURNRESULT</tt> option is specified and the request does not timeout before
    5370a5383,5643
    > </li>
    > </ul>
    > <p>
    > <li>If the <tt>TEST</tt> option is specified:
    > <p>
    > <ul>
    > <li>If not successful (RC is not 0) then an error occurred (such as an invalid execution option,
    > an XML parsing error, or a Python compile error in the specified XML document) and the
    > result buffer contains additional information about the error.</li>
    > <p>
    > <li>If successful (RC is 0) and the <tt>RETURNDETAILS</tt> option was not specified,
    > the result buffer contains nothing indicating that no errors were found in
    > the XML document.</li>
    > <p>
    > <li>If successful (RC is 0) and the <tt>RETURNDETAILS</tt> option is specified,
    > the result buffer will contain a marshalled <tt>&lt;Map:STAF/Service/STAX/JobDetails</tt>
    > representing details about the functions defined in the XML document.
    > The maps used to define the result are defined as follows:
    > <p>
    > <table border>
    > <thead>
    > <tr>
    > <th COLSPAN="4">Definition of map class STAF/Service/STAX/JobDetails</th>
    > </tr>
    > <tr>
    > <td colspan="4"><b>Description: </b>This map class represents details about the
    > functions defined in the STAX XML document. This information is obtained by
    > checking for &lt;defaultcall> and &lt;function> elements in the STAX XML document.</td>
    > </tr>
    > <tr>
    > <th width=20%>Key Name
    > <th width=20%>Display Name
    > <th width=30%>Type
    > <th width=30%>Format / Value
    > </tr>
    > </thead>
    > <tbody>
    > <tr>
    > <td>defaultCall
    > <td>Default Call
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>functionList
    > <td>Functions
    > <td><tt>&lt;List> of &lt;Map:STAF/Service/STAX/FunctionInfo></tt>
    > <td>
    > </tr>
    > </tbody>
    > </table>
    > <p>
    > <table border>
    > <thead>
    > <tr>
    > <th COLSPAN="4">Definition of map class STAF/Service/STAX/FunctionInfo</th>
    > </tr>
    > <tr>
    > <td colspan="4"><b>Description: </b>This map class represents a function
    > defined in the STAX XML document.
    > This information is from each &lt;function> element (and it's sub-elements)
    > defined in the STAX XML document.</td>
    > </tr>
    > <tr>
    > <th width=20%>Key Name
    > <th width=20%>Display Name
    > <th width=30%>Type
    > <th width=30%>Format / Value
    > </tr>
    > </thead>
    > <tbody>
    > <tr>
    > <td>functionName
    > <td>Function Name
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>prolog
    > <td>Prolog
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>epilog
    > <td>Epilog
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>argDefinition
    > <td>Argument Definition
    > <td><tt>&lt;String></tt>
    > <td><tt>'FUNCTION_DEFINES_NO_ARGS' | 'FUNCTION_ALLOWS_NO_ARGS' |
    > 'FUNCTION_DEFINES_ONE_ARG' | 'FUNCTION_DEFINES_LIST_ARGS' |
    > 'FUNCTION_DEFINES_MAP_ARGS' | 'FUNCTION_DEFINES_UNKNOWN_ARGS'</tt>
    > </tr>
    > <tr>
    > <td>argList
    > <td>Arguments
    > <td><tt>&lt;List> of &lt;Map:STAF/Service/STAX/ArgInfo></tt>
    > <td>
    > </tr>
    > </tbody>
    > </table>
    > <p>
    > <table border>
    > <thead>
    > <tr>
    > <th COLSPAN="4">Definition of map class STAF/Service/STAX/ArgInfo</th>
    > </tr>
    > <tr>
    > <td colspan="4"><b>Description: </b>This map class represents a function
    > argument. This information is obtained from each &lt;function-required-arg>,
    > &lt;function-optional-arg> or &lt;function-arg-def> element (and it's
    > sub-elements) defined for a function in the STAX XML document.</td>
    > </tr>
    > <tr>
    > <th width=20%>Key Name
    > <th width=20%>Display Name
    > <th width=30%>Type
    > <th width=30%>Format / Value
    > </tr>
    > </thead>
    > <tbody>
    > <tr>
    > <td>argName
    > <td>Argument Name
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>description
    > <td>Description
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>type
    > <td>Type
    > <td><tt>&lt;String></tt>
    > <td><tt>'ARG_REQUIRED' | 'ARG_OPTIONAL' | 'ARG_OTHER'</tt>
    > </tr>
    > <tr>
    > <td>defaultValue
    > <td>Default Value
    > <td><tt>&lt;String> | &lt;None></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>private
    > <td>Private
    > <td><tt>&lt;String></tt>
    > <td><tt>'Yes' | 'No'</tt>
    > </tr>
    > <tr>
    > <td>properties
    > <td>Properties
    > <td><tt>&lt;List> of &lt;Map:STAF/Service/STAX/ArgPropertyInfo></tt>
    > <td>
    > </tr>
    > </tbody>
    > <tfoot>
    > <tr>
    > <td colspan="4">
    > <b>Notes:</b>
    > <ol compact>
    > <li>The "Default Value" is <tt>&lt;None></tt> if the argument type
    > is <tt>'ARG_REQUIRED'</tt> or <tt>'ARG_OTHER'</tt>.
    > </ol>
    > </tr>
    > </tfoot>
    > </table>
    > <p>
    > <table border>
    > <thead>
    > <tr>
    > <th COLSPAN="4">Definition of map class STAF/Service/STAX/ArgPropertyInfo</th>
    > </tr>
    > <tr>
    > <td colspan="4"><b>Description: </b>This map class represents a property for
    > a function argument. This information is obtained from each &lt;function-arg-property>
    > element defined for a function argument in the STAX XML document.</td>
    > </td>
    > </tr>
    > <tr>
    > <th width=20%>Key Name
    > <th width=20%>Display Name
    > <th width=30%>Type
    > <th width=30%>Format / Value
    > </tr>
    > </thead>
    > <tbody>
    > <tr>
    > <td>propertyName
    > <td>Name
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>propertyDescription
    > <td>Description
    > <td><tt>&lt;String> or &lt;None></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>propertyValue
    > <td>Value
    > <td><tt>&lt;String> or &lt;None></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>propertyData
    > <td>Data
    > <td><tt>&lt;List> of &lt;Map:STAF/Service/STAX/ArgPropertyDataInfo></tt>
    > <td>
    > </tr>
    > </tbody>
    > </table>
    > <p>
    > <table border>
    > <thead>
    > <tr>
    > <th COLSPAN="4">Definition of map class STAF/Service/STAX/ArgPropertyDataInfo</th>
    > </tr>
    > <tr>
    > <td colspan="4"><b>Description: </b>This map class represents data for a property
    > of a function argument.
    > This information is obtained from each &lt;function-arg-property-data> element defined
    > for a property of a function argument in the STAX XML document.</td>
    > </tr>
    > <tr>
    > <th width=20%>Key Name
    > <th width=20%>Display Name
    > <th width=30%>Type
    > <th width=30%>Format / Value
    > </tr>
    > </thead>
    > <tbody>
    > <tr>
    > <td>dataType
    > <td>Type
    > <td><tt>&lt;String></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>dataValue
    > <td>Value
    > <td><tt>&lt;String> or &lt;None></tt>
    > <td>
    > </tr>
    > <tr>
    > <td>dataData
    > <td>Data
    > <td><tt>&lt;List> of &lt;Map:STAF/Service/STAX/ArgPropertyDataInfo></tt>
    > <td>
    > </tr>
    > </tbody>
    > </table>
    > </ul>
    > </li>
    5533a5807,5903
    > <p>
    > <li>
    > <b>Goal:</b> Test if a XML job file named d:\stax\xml\JobA.xml is valid without actually starting
    > the execution of the job and return information about the functions defined in this XML job file.
    > <p><tt>EXECUTE FILE D:\stax\xml\JobA.xml TEST RETURNDETAILS</tt>
    > <p><b>Output:</b>
    > <pre>
    > {
    > Default Call: RunCommand
    > Functions : [
    > {
    > Function Name : RunCommand
    > Prolog :
    > Epilog :
    > Argument Definition: FUNCTION_DEFINES_MAP_ARGS
    > Arguments : [
    > {
    > Argument Name: command
    > Description : A command to execute
    > Type : ARG_REQUIRED
    > Default Value: &lt;None>
    > Private : No
    > Properties : []
    > }
    > {
    > Argument Name: user
    > Description : The user id to run the command under
    > Type : ARG_OPTIONAL
    > Default Value: 'anonymous'
    > Private : No
    > Properties : []
    > }
    > {
    > Argument Name: password
    > Description : The password for the user id
    > Type : ARG_OPTIONAL
    > Default Value: None
    > Private : Yes
    > Properties : []
    > }
    > {
    > Argument Name: numTimes
    > Description : The number of times to run the command
    > Type : ARG_OPTIONAL
    > Default Value: 1
    > Private : No
    > Properties : [
    > {
    > Name : type
    > Description: &lt;None>
    > Value : int
    > Data : []
    > }
    > ]
    > }
    > {
    > Argument Name: color
    > Description : This is the color of the entity
    > Type : ARG_REQUIRED
    > Default Value: &lt;None>
    > Private : No
    > Properties : [
    > {
    > Name : type
    > Description: This defines this argument as an enumeration
    > Value : enum
    > Data : [
    > {
    > Type : choice
    > Value: 'red'
    > Data : [
    > {
    > Type : default
    > Value: &lt;None>
    > Data : []
    > }
    > ]
    > }
    > {
    > Type : choice
    > Value: 'blue'
    > Data : []
    > }
    > {
    > Type : choice
    > Value: 'green'
    > Data : []
    > }
    > ]
    > }
    > ]
    > }
    > ]
    > }
    > ]
    > }
    > </pre>

     
  • Sharon Lucas

    Sharon Lucas - 2006-12-04
    • milestone: --> Next
    • summary: Document RETURNDETAILS option for a STAX EXECUTE TEST reques --> Document RETURNDETAILS option for STAX EXECUTE TEST request
    • status: open --> closed-fixed
     

Log in to post a comment.