A fix is available
APAR status
Closed as new function.
Error description
Support conditional-dependencies for IWS (TWS) operations.
Local fix
Problem summary
**************************************************************** * USERS AFFECTED: All SA z/OS V3R5 customers. * **************************************************************** * PROBLEM DESCRIPTION: SA does currently not support * * conditional-dependencies for TWS * * operations. * * * * SA should allow customers to log all * * output from IWS (TWS) commands within * * the NetView NETLOG, including output * * that comes from the completion * * checking routine. * **************************************************************** * RECOMMENDATION: * **************************************************************** Both, SA and IWS (TWS) will be enhanced to support conditional dependencies for operations that are complete 'C'. SA will provide a new AAO called AOF_AAO_TWS_CHK_OUTPUT_NETLOG similar to the existing AAO AOF_AAO_TWS_CMD_OUTPUT_NETLOG for commands. If its value is YES, it will ensure that the output of the completion checking routine is written to the NETLOG in all cases and not only when the operation ended in error.
Problem conclusion
Temporary fix
Comments
The SA - IWS (TWS) interface has been enhanced to support conditional dependencies for operations that are complete 'C'. Based on the result of the command, customers can now implement different courses of action, regardless of whether the operation completed successfully or failed. When the installation wants to make use of conditional dependencies, it must change the return code processing of the completion checking routine such that any rc <= maxrc is not forced to 0 (as today) just to tell SA, that the operation completed successfully. Instead, the completion checking routine is expected to return the rc as is. The caller of the completion checking routine, EVJESCHK, will then perform the check: If rc = -2 then setup a timer to call completion checking routine after the maximum wait time; If rc <= maxrc then call OPCAPOST with TYPE = 'C' and RETCODE=nnnn; If rc > maxrc then call OPCAPOST with TYPE='E' and ERRCODE=Rnnn; nnnn / nnn is the rc with leading '0's. In summary: o When commands end with a return code <= maxrc (default = 0) the operation is considered complete and the return code is passed to IWS (TWS). o When commands end with a return code > maxrc the operation is considered in error and the error code is passed in format Rnnn to IWS/TWS (no change). o If used, completion checking routine is expected to provide return code > maxrc (instead of >0) in order to post the operation in error with error code Rnnn; - Only, when AOF_AAO_TWS_CHK_CONDDEP = 'YES'; - Otherwise, SA still compares rc > 0. o If used, completion checking routine is expected to provide positive return code <= maxrc in order to post operation complete with return code 'nnnn'; - Only, when when AOF_AAO_TWS_CHK_CONDDEP = 'YES'; - Otherwise, SA still compares rc = 0. o OPCAPOST accepts ERRCODE-keyword parameter in combination with TYPE=C. o OPCACOMP accepts positional error_code parameter in combination with status C. o OPCAQRY shows operation details - Return code is shown for complete operations; - Error code + error message is shown for operations in error. IWS (TWS) provides the following enhancements with APAR PI47790 for IWS 9.3: o IWS introduced new JTOPTS option USINRC(Y|N) to turn conditional dependency support ON or OFF on a global level. - USINRC(N) - no support of conditional dependencies (default). - USINRC(Y) - EQQUSIN and EQQUSINT allow to specify return code for complete operations. o IWS enhanced EQQUSINT - OPERR can be specified with TYPE='C'. - Callers are expected to initialize OPERR to '0000' to guarantee compatible behavior (all SA z/OS code driving this interface have been changed). o IWS enhanced EQQUSIN - ERROR_CODE can be specified with STATUS='C'. - Callers are expected to initialize ERROR_CODE to '0000' to guarantee compatible behavior (all SA z/OS code driving this interface have been changed). APAR PI47790 must be installed in order to exploit SA's new conditional dependencies support. Refer to the documentation in APAR PI47790 for further instructions how to enable the new function. +------ System Automation for z/OS Version 3 Release 5 --------+ | | |PROGRAM NUMBER: 5698-SA3 | | | |TITLE: TWS Automation Programmer's Reference | | and Operator's Guide SC34-2749-00 | | | |CHAPTER 12. TWS Automation Common Routines and Data Areas| |TOPIC: TWS Automation Common Routines | |SUB-TOPIC: OPCAPOST | | | |CHANGE: | | | | Under parameter ERRCODE=xxxx, delete the following Note: | | | | Note: This parameter is only valid with TYPE=E. | | | |--------------------------------------------------------------| | | |SUB-TOPIC OPCACOMP | | | |CHANGE: | | | | Replace the text under parameter error_code with the | | following: | | | | Takes the form cccc. Errors typically start with an | | alphanumeric character followed by 3 digits. If a return code| | is passed along with status C, use 4 digits and pad with '0' | | on the left, when necessary. | | Do not specify the values Uxxx and Sxxx; reserve them for TWS| | Automation. | | | |--------------------------------------------------------------| | | |CHAPTER 9. Automating Applications with TWS Automation | |TOPIC: Completion Checking Routine | |SUB-TOPIC: OPCA | | | |CHANGE: | | | | Replace the complete text that starts with 'The operation is | | considered to be in error...' with the following text: | | | | The operation is considered to be in error when the return | | code is greater than the maximum return code. The completion | | checking routine is used to examine whether the command has | | achieved the expected result. The following return codes are | | issued: | | | | -2 Restarts the completion checking routine... | | | | <= maxrc Successful completion of the command. Return code | | saved for conditional dependency processing. | | | | > maxrc Unsuccessful completion of the command. | | | | Note that AAO AOF_AAO_TWS_CHK_CONDDEP must be set to 'YES' | | for this new behavior. Otherwise, the operation is successful| | (complete) only, if the completion checking routine's return| | code is 0. This will then be also the return code of the | | operation, if conditional dependencies are exploited. | | | |--------------------------------------------------------------| | | |CHAPTER 6. TWS Automation Operator Commands | |TOPIC: OPCAQRY - Display Status of Operations | |SUB-TOPIC: Examples | | | |CHANGE: | | | | At the very end of this sub-topc, add the following: | | | | If the command is in a complete condition, details similar to| | those in Figure <nn> are displayed. | | | | +----------------------------------------------------------+ | | | Return code : 0004 | | | +----------------------------------------------------------+ | | | |--------------------------------------------------------------| | | |TITLE: Messages and Codes SC34-2719-00 | | | |CHAPTER 6. Messages EVJ000I to EVJ440I (TWS Automation) | |TOPIC: EVJ063I | | | |CHANGE: | | | | Replace the explanation for the variable name with the | | following: | | | | The variable name shows the application description as | | defined in TWS. | | | | Replace the explanation for the errcode with the following: | | | | The variable errcode shows the error code, if the operation | | is in error or the return code, if the operation is complete.| | | |--------------------------------------------------------------| | | |TITLE: Customizing and Programming SC34-2715-00 | | | |CHAPTER Appendix A. Global Variables | |TOPIC: Read/Write Variables | | | |CHANGE: | | | | Add the following new AAO to table 25 after | | AOF_AAO_TWS_CMD_OUTPUT_NETLOG: | | | | Variable: | | AOF_AAO_TWS_CHK_OUTPUT_NETLOG | | | | Value: | | YES | | | | Effect: | | Set this AAO to YES to place the | | output of the completion checking | | routine in the netlog. | | | |--------------------------------------------------------------| | | | Variable: | | AOF_AAO_TWS_CHK_CONDDEP | | | | Value: | | YES | | | | Effect: | | Set this AAO to YES to exploit the | | new behavior that allows to save | | the return code passed back from | | the completion checking routine for | | conditional dependency | | processing in case of successful | | operations. | | | +--------------------------------------------------------------+
APAR Information
APAR number
OA49678
Reported component name
SYSTEM AUTO Z/O
Reported component ID
5698SA300
Reported release
350
Status
CLOSED UR1
PE
NoPE
HIPER
NoHIPER
Special Attention
NoSpecatt / Xsystem
Submitted date
2016-01-08
Closed date
2016-10-06
Last modified date
2016-11-02
APAR is sysrouted FROM one or more of the following:
APAR is sysrouted TO one or more of the following:
UA83001 UA83002
Modules/Macros
AOFR1ILL EVJESCHK EVJESCMD EVJESCVY EVJESPCP EVJESPIN EVJESPRQ EVJESPSC EVJESPTE EVJESPVY EVJRVQRY EVJRVST0 EVJRYPST EVJ06 INGRFDBK INGRFTIM INGRFXIT INGRVST0
| SC34274900 | SC34271900 | SC34271500 |
Fix information
Fixed component name
SYSTEM AUTO Z/O
Fixed component ID
5698SA300
Applicable component levels
Fix is available
Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.
[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSWRCJ","label":"IBM Tivoli System Automation for z\/OS"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"350","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]
Document Information
Modified date:
02 November 2016