Return code mapping for r3batch

About this task

Using return code mapping with r3batch can be useful in overcoming differences in the return code mechanisms of R/3, which returns a mixture of messages and numbers, and of HCL Workload Automation, which handles exclusively numeric return codes. By customizing the return code mapping files listed in Return code mapping file names for r3batch, you can map messages from R/3 logs, spool lists, and exceptions from RFC function modules into return code values that HCL Workload Automation can handle.

Note that when you do not use this feature, r3batch does not send any return codes to HCL Workload Automation. In this case, HCL Workload Automation displays only the r3batch exit code, which cannot be used to set up rccondsucc conditions.

The return code mapping mechanism works as follows:

r3batch reads the output retrieved from the R/3 system (R/3 job log, process chain log, spool list, and so on appended to the stdlist of the related HCL Workload Automation job).
Following your specifications in the rcm files, the R/3 return messages or codes are mapped into your custom return codes and passed on to HCL Workload Automation.
These return codes are used together with the rccondsucc keyword set in the extended agent job definition and handled accordingly. Return code mapping is meaningful only if you use the return codes to write the expressions that determine job completion. Conversely, in the case of this extended agent, the use of rccondsucc is significant only if HCL Workload Automation gets return codes (not exit codes) from the access method.

To use the return code mapping feature:

Leave the value of the rcmap option as ON (this is the default).
Depending on which R/3 logs you want r3batch to read and map, leave the default settings of the retrieve_joblog, retrieve_pchainlog, and retrieve_spoollist options as ON and manually create the corresponding rcm files.
If you want to map messages from the R/3 syslog, set the log_r3syslog option to ON and manually create the corresponding rcm file.

When setting up your return code mapping for r3batch, consider the following:

You can define any return code numbers for your use because there are no reserved return codes for the access method or for HCL Workload Automation.
Mapping files are scanned sequentially: the first match found performs the corresponding mapping. When you define a mapping file, write the most restrictive strings first.
When you define a mapping file, remember that the R/3 log messages are read in their entirety. If you want to map only a part of the entry, you must use the wildcard characters.
If two lines match two different patterns, then the return code is set to the higher value. In general the return code is set to the highest value among the ones yielded by the matched patterns. This is shown in the following example:
The job log returned after job PAYT410 has run is:
```
*** ERROR 778 ***  EEWO0778E Failed to modify the job PAYT410 with job id
***       05710310.

*** ERROR 176 ***  EEWO0176E Failed to add step 1.

*** ERROR 552 ***  EEWO0552E The R/3 job scheduling system has found an
***       error for user name * and job name PAYT410. Please check R/3
***       syslog.

*** ERROR 118 ***  EEWO0118E Execution terminated. Could not create and
***       start an instance of the R/3 batch job.
ERROR LEVEL=118
```
and the system log contains the following line:
```
|011:05:12|MAESTRO|SAPMSSY1|EFT|> Step 1 contains illegal values 
```
The r3batch-joblog.rcm file contains the following matching line:
```
"118""*"=100
```
while the r3batch-syslog.rcm file contains the following matching line:
```
"*MAESTRO*Step 1 contains illegal values"=9999
```
In this case, the return code sent back to HCL Workload Automation is 9999 because it is the higher of the two matching patterns.
If no matching takes place, no return code is sent to HCL Workload Automation.