HCL Workload Automation, Version 9.4

Task string to define SAP jobs

This section describes the task string parameters that define and control the running of SAP jobs. You can specify them in the following places when you define their associated HCL Workload Automation jobs:
  • In the R/3 Command Line section of the Task page of the Submit Ad Hoc Jobs action from the Dynamic Workload Console.
  • In the R3 Command Line field of the More Options page of the SAP job definition, if you use the Dynamic Workload Console and selected a SAP job definition.
  • As arguments of the scriptname keyword in the job definition statement, if you use the HCL Workload Automation command line.
  • As arguments of the JOBCMD keyword in the JOBREC statement in the SCRIPTLIB of IBM Workload Scheduler for z/OS, if you are scheduling in an end-to-end environment. The following is an example of a JOBREC statement:
    JOBREC
      JOBCMD('/-job job_name -user user_name -i job_ID -c class_value')
      JOBUSR(TWS_user_name) 
    where:
    class_value
    The priority with which the job runs in the SAP system. For details, see Table 1.
    job_ID
    The unique SAP job ID. For details, see Table 1.
    job_name
    The name of the SAP job to run. For details, see Table 1.
    user_name
    The SAP user who owns the target job. For details, see Table 1.
    TWS_user_name
    The IBM Workload Scheduler for z/OS user who runs the r3batch access method from the end-to-end scheduling environment.
The string syntax is the following:
Read syntax diagramSkip visual syntax diagram
Job definition syntax

>>- -job--job_name--+-----------------+------------------------->
                    '-+- -i--+-job_ID-'   
                      '- -id-'            

>--+-------------------+--+----------------------+-------------->
   '- -user--user_name-'  '-+- -host-+-host_name-'   
                            '- -ts---'               

>--+--------------------+--+-------------------------+---------->
   '- -sg--server_group-'  '- -client--source_client-'   

>--+------------------------------+----------------------------->
   '- -exec_client--target_client-'   

>--+--------------------------------+--+------------------+----->
   '- -rfc_client--rfc_logon_client-'  '- -c--class_value-'   

>--+-----------------------------------------+------------------>
   '- -bdc_job_status_failed--bdc_processing-'   

>--+-----------------+--+-------------------------------+------->
   '-+- -nobdc-----+-'  |                    .-high---. |   
     '- -nobdcwait-'    '- -bapi_sync_level--+-medium-+-'   
                                             '-low----'     

>--+---------------------------+-------------------------------->
   '- -s--starting_step_number-'   

   .----------------------------------------------------------.   
   V                                                          |   
>----+------------------------------------------------------+-+-->
     '- -sStep_number-attribute_name--+-------------------+-'     
                                      '- =attribute_value-'       

>--+-----------------------------+------------------------------>
   '- -vStep_number-variant_name-'   

>--+---------------------------------------+-------------------->
   '- -vtxtStep_number-variant_description-'   

>--+--------------------------------------+--------------------->
   '- -vparStep_number-name=variant_value-'   

>--+--------------------------------------------------------------+-->
   '- -vselStep_number-name=-+-i-+-#operation#lowest-+----------+-'   
                             '-e-'                   '-#highest-'     

>--+--------------------+--+-----------------------------+------>
   '- -vtempStep_number-'  '- -recipient--R/3_login_name-'   

>--+---------------------------+--+-------------------+--------->
   '- -rectype--recipient_type-'  '- -flag -+-reccp-+-'   
                                            '-recbl-'     

>--+--------------+--+--------------+--+-------------------+---->
   '- -flag recex-'  '- -flag recnf-'  '- -flag--+-im----+-'   
                                                 '-immed-'     

>--+------------------------------+----------------------------->
   '- -flag--+-enable_applinfo--+-'   
             '-disable_applinfo-'     

>--+-----------------------------+------------------------------>
   '- -flag--+-enable_appl_rc--+-'   
             '-disable_appl_rc-'     

>--+----------------------------+------------------------------->
   '- -flag--+-enable_joblog--+-'   
             '-disable_joblog-'     

>--+---------------------------------------+-------------------->
   '- -flag--+-enable_job_interceptable--+-'   
             '-disable_job_interceptable-'     

>--+-------------------------------+--+-------------------+----->
   '- -flag--+-enable_spoollist--+-'  '- -flag--pc_launch-'   
             '-disable_spoollist-'                            

>--+---------+--+-------------------+--+------------+----------><
   '- -debug-'  '- -tracelvl--+-1-+-'  '- -rfctrace-'   
                              +-2-+                     
                              '-3-'                     

Table 1 describes the parameters for the task string to define SAP jobs.
Note:
  1. You can specify both -i or -id and -user in the same job definition, but the user name is ignored.
  2. When you specify the job ID, both -client and -exec_client are ignored because the ID is unique for the entire SAP system.
  3. Typically, the -debug and -trace options are for debugging the extended agent and should not be used in standard production.
Table 1. Task string parameters for SAP jobs. The following are the task string parameters for the SAP jobs
Section Parameters Description GUI Support
JOB -job job_name The name of the job to run. This parameter is mandatory.

-i job_ID
-id job_ID

The unique SAP job ID. Specify this parameter if you are submitting a job that refers to a predefined job template stored in the SAP database for which you want to change a parameter.
-user user_name The SAP user who owns the target job. Use this parameter when the target SAP system has only one job with the specified name for the specified user. This parameter has no effect if a job ID is specified in the job definition.

-host host_name
-ts host_name

The name of the SAP workstation where the job is to be run. host_name has the format hostname_SAPsystemname_SAPsystemnumber.

For example, the name of a host might be amss80a0_gs7_90

These parameters are mutually exclusive with -sg.

-sg server_group The name of the SAP server group where the job is to be run. Use this parameter to run the job on an application server that belongs to the group. The server group must exist on the SAP system, otherwise an error code is returned and the job is not launched.

This parameter is case-sensitive and can be up to 20 characters. It is mutually exclusive with -host and -ts.

JOB -client source_client The number that identifies the SAP client where the job definition is to be found, regardless of the client number defined by the r3client keyword in the options file. This parameter has no effect if a job ID is specified in the job definition.  
-exec_client target_client The number that identifies the SAP client where the job is to be run, regardless of the client number defined by the r3client keyword in the options file. This parameter has no effect if a job ID is specified in the job definition.  
-rfc_client rfc_logon_client The number that identifies the SAP client to be used for RFC logon. This value overwrites the value specified by the r3client keyword in the corresponding r3batch options file.  
-c class_value The priority with which the job runs in the SAP system. Possible values are:
A
High priority
B
Medium priority
C
Low priority. This is the default value.
-bdc_job_status_failed bdc_processing How HCL Workload Automation sets the completion status of a job running BDC sessions, according to a possible BDC processing failure. The allowed values are:
n
If at least n BDC sessions failed (where n is an integer greater than 0), HCL Workload Automation sets the job completion status as failed.
all
If all the BDC sessions failed, HCL Workload Automation sets the job completion status as failed.
ignore
When all the BDC sessions complete, regardless of their status, HCL Workload Automation sets the job completion status as successful. This is the default.

If -nobdc or -nobdcwait is set, this option is ignored.

-nobdc
-nobdcwait

Disables the BDC Wait option (enabled by default) to have the job considered as completed even if not all its BDC sessions have ended.
-bapi_sync_level Specifies the synchronization level between the SAP function modules BAPI_XBP_JOB_COPY and BAPI_XBP_JOB_START_ASAP. Allowed values are:
high
All RFC calls between BAPI_XBP_JOB_START_ASAP and BAPI_XBP_JOB_COPY are synchronized. This is the default.
medium
The RFC calls to BAPI_XBP_JOB_START_ASAP are synchronized.
low
The RFC calls are not synchronized.
 
STEP -s starting_step_number The number of the starting step.
-sStep_number attribute_name=attribute_value The step number and its attributes, where:
step_number
The number of the step being defined. Each step is identified by a sequential number (1, 2, 3, ...n) using the step number
attribute_name
The name of the attribute.
attribute_value
The value of the attribute. It is optional for some attributes.

Attributes can be defined in any order, but cannot be repeated for the same step. Attribute validation is performed before the job is created in the SAP system. If the validation fails, the HCL Workload Automation job goes into the ABEND state. For a detailed description of each attribute and its value, see Defining attributes for ABAP steps and Defining attributes for external programs and external commands steps.

For example, the following step (step 8) is an ABAP module running the report MYPGM and has two attributes, only one of which has a value.
-s8 type=A -s8 program=MYPGM
-s8 pr_cover="My title" -s8 pr_immed
VARIANT -vstep_number name The variant name for the specified step number.
-vtxtstep_number variant_description The textual description of the variant, in the HCL Workload Automation logon language (customizable with the TWSXA_LANG option of r3batch). The maximum length is 30 characters.
-vparstep_number name=value For ABAP modules only. The value for a variant parameter for the specified step number. This parameter is mandatory when creating a new variant. See Defining attributes for ABAP steps for a complete list of the supported attributes for ABAP steps.
-vselstep_number name=sign#operation#lowest[#highest] For ABAP modules only. The value for a variant selection option for the specified step number.
sign
Sign of the operation. Possible values are:
I
Include
E
Exclude
operation
Possible values are:
EQ
Equals
NE
Not equal to
BT
Between
NB
Not between
LT
Less than
LE
Less than or equal to
GT
Greater than
GE
Greater than or equal to
CP
Contains pattern
NP
Does not contain pattern
lowest
Low value of the selection. You can use up to 45 characters.
highest
High value of the selection. You can use up to 45 characters. This attribute is optional.
For a complete list of the supported attributes for ABAP steps, seeDefining attributes for ABAP steps.

-vtempstep_number For ABAP modules only. Specifies to assign a temporary variant to the specified step number. Temporary variants are created ad-hoc by the SAP system and assigned to the job instance when it is run. The lifecycle of the temporary variant is determined by the SAP system. If the job is deleted by SAP, then the temporary variant is deleted. See Examples: Dynamically defining and updating SAP jobs to refer to examples that demonstrate the behavior of temporary variants.  
SPOOL -recipient name The login name of an SAP user.  
-flag {reccp|recbl} Specifies how the spool list is sent to the recipient. Possible values are:
reccp
The spool list is sent as a copy.
recbl
The spool list is sent as a blind copy.
 
-flag recex Specifies that the spool list is sent as an express message to the recipient.  
-flag recnf Specifies that the recipient is not allowed to forward the spool list.  
-rectype type Specifies the recipient type. Possible values are:
' '
SAP user (default value)
'B'
SAP user
'C'
Shared distribution list
'D'
X.500 address
'G'
Organization object/ID
'H'
Organization unit
'I'
SAP object
'L'
Telex number
'O'
SAPoffice user
'P'
Private distribution list
'R'
SAP user in another SAP system
'U'
Internet address
'1'
Other recipient type
 
FLAGS

-flag im
-flag immed

Specifies to launch job immediately, meaning that if there are no spare work processes, the job fails.

-flag enable_applinfo
-flag disable_applinfo

Enables or disables the retrieval and appending of the SAP application log to the stdlist of HCL Workload Automation.

-flag enable_appl_rc
-flag disable_appl_rc

Enables or disables the mapping of the SAP application return code to the HCL Workload Automation return code.

The SAP application return code is mapped only if -flag enable_applinfo is set and the application log contains the application return code.

 

-flag enable_joblog
-flag disable_joblog

Enables or disables retrieval of the joblog.

-flag enable_job_interceptable
-flag disable_job_interceptable

Enables or disables the job launched by r3batch to be intercepted by SAP. If enabled, when r3batch launches a job and the SAP job interception feature is enabled, the job can be intercepted if it matches previously defined criteria. If disabled, the job launched by r3batch cannot be intercepted by SAP. This setting overwrites the setting in the common options file.

-flag enable_spoollist
-flag disable_spoollist

Enables or disables retrieval of the spool lists of the job.

-flag pc_launch

Specifies to launch child jobs that are in scheduled state.
ON
The product launches child jobs that are in scheduled state.
OFF
The product does not launch child jobs that are in scheduled state. This is the default value.
Note: You can use this option only if you activated the parent-child feature on the SAP system. On the XBP 2.0 (or later)SAP system you can activate this feature using the INITXBP2 ABAP report
 
TRACING -debug Enables maximum trace level.
-tracelvl 1|2|3 Specifies the trace setting for the job. Possible values are:
1
Only error messages are written in the trace file. This is the default.
2
Informational messages and warnings are also written in the trace file.
3
A most verbose debug output is written in the trace file.
For detailed information, refer to Configuring the tracing utility.

-rfctrace
-trace

Enables RFC trace.  
The following is an example for an SAP job named BVTTEST with ID 03102401 and user myuser:
-job BVTTEST –i 03102401 -user myuser -debug