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:


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:

You can specify both -i or -id and -user in the same job definition, but the user name is ignored.
When you specify the job ID, both -client and -exec_client are ignored because the ID is unique for the entire SAP system.
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.	✓
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.	✓
	-vtemp`step_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