HCL Workload Automation, Version 9.4

Task string to define SAP jobs dynamically

This section describes the task string that controls the running of SAP jobs. You can build an entire job definition by using the six main sections concerning SAP job parameters. These sections are grouped in Table 1 and are related to the:

Job
Job steps
Variants associated with the steps (for ABAP modules only)
Spool list recipients associated with the job
Flags associated with the job
Tracing specifications for the job

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) 
```

To define and submit an SAP R/3 job dynamically, use the following syntax:


Job definition syntax

>>- -job--job_name--+-----------------+-- -flag type=exec------->
                    '-+- -i--+-job_ID-'                     
                      '- -id-'                              

>--+----------------------+--+--------------------+------------->
   '-+- -host-+-host_name-'  '- -sg--server_group-'   
     '- -ts---'                                       

>--+-------------------------+---------------------------------->
   '- -client--source_client-'   

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

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

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

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

   .----------------------------------------------------------.   
   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-'                     

>--+--------------------------------+--------------------------><
   '- -rfc_client--rfc_logon_client-'

The following is an example of a definition for the SAPTEST job:

-job SAPTEST -C A -s1 program=BTCTEST -s1 type=A -s1 pr_release
-s2 report=BTCTEST -s2 variant=BVT –s2 type=A -flag type=exec 
-vpar2 TESTNAME=test -vtxt2 Test

Table 1 describes the parameters for the task string to define SAP jobs dynamically.

Note: The parameter values are case sensitive.

Table 1. Task string parameters for SAP jobs (dynamic definition). This table shows Task string parameters for Sap jobs
Section	Parameters	Description
JOB	-job job_name	The name of the job to be 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.
	-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.
	-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 key 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` key in the options file. This parameter requires that the client-dependent data (such as the user name and report variants) exists on both the source and target clients. 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.
	-flag type=exec	Specify this parameter to enable the dynamic definition of the SAP job. This parameter is mandatory.
JOB	-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 value. 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 values, 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. Not valid for temporary variants.
	-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. For a complete list of the supported attributes for ABAP steps, see Defining 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, see Defining 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: blank 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 the 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_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 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 activate this feature by 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 more details, refer to Configuring the tracing utility.
	-rfctrace -trace	Enables RFC trace.

Note: See Examples: Dynamically defining and updating SAP jobs to refer to examples that demonstrate the behavior of variants and temporary variants.

The following rules apply when you create or update SAP jobs dynamically:
- To create or reference a variant within an ABAP step, you can use one of the following equivalent syntaxes:
  - -s1 Variant=Var1
  - -s1 Parameter=Var1
  - -v1 Var1
- If a variant does not exist, it is created with the parameters specified in the job definition statement. In this case, all the required attributes of the variant must be given a value. You cannot create empty variants. For example, if you specify -vtemp1, with no value assigned, an empty temporary variant is erroneously created.
- If a variant is already present in the SAP system, its values are modified according to the command line parameters. If the existing variant is an extended one, a new instance of it is created with resolved placeholders and updated counters. This new variant instance is then updated using the values from the command line. Finally, the job step is run using this variant instance.
- All changes to the variant values are permanent. That is, HCL Workload Automation neither restores the old values of the variants, nor deletes the variants created after the job is run. HCL Workload Automation does not change the case of the variant values.