jr3bjcpy
- Organization of this page
Format 1
jr3bjcpy [SAP-destination-information] [SAP-logon-information] [redirection-information] -jn name-of-the-source-job -jc job-count-of-the-source-job [-js number-of-the-first-step-to-start-copying-job] [-djn new-name-of-the-copied-job] [{-tgh target-host|-tgs target-server}] [{-rs|-ri}] [-wait [-time monitoring-time [-cancel]] [-ival monitoring-interval] [-jo SAP-job-log-filename] [-mt [-mts message-type-character-string]]] [-with_child]]
- Note
-
If the character string for the argument specification contains a space, enclose the argument with double quotation marks (").
Format 2
jr3bjcpy -help
Description
Copies a background job in an SAP system.
The background jobs that can be copied on the SAP system are those that can be defined and executed using transaction code SM36.
When the job is successfully copied, the SAP system assigns a job count to it to identify it. This job count is transferred to the standard output as part of a message.
The user can use the job count and the new name of the copied job specified in the -djn option (the name of the source job if the new name of the copied job is not specified) to view the status of a copied job or to cancel job execution.
Use the jr3bjdel command to delete jobs copied on the SAP system.
Arguments
SAP-destination-information
Specify the SAP system in which the job is to be copied. Copied jobs are usually executed with the load distributed among application servers that are capable of executing the jobs. With the -tgh option, however, it is possible to specify the system that will execute the jobs. For details about the format of SAP destination information, see (1) Common argument format for job control function commands.
SAP-logon-information
Specify logon information that is valid in the SAP system in which the job is to be copied. Usually, a valid user for job execution is an SAP user who is specified in the SAP logon information. With the -auth option in the job step information, however, it is possible to specify a valid SAP user for job execution.
The language specified for the -l option in the SAP logon information affects the language for the SAP job log. It also affects the language for the error details that are returned by the SAP system and inserted into a message, such as KAJM0802-E and KAJM0813-E.
To change the language type of the ABAP program defined as a job step from the default of the SAP system when you execute the job, use the -lang option in the job step information. For details about the format of SAP logon information, see (1) Common argument format for job control function commands.
redirection-information
Specify standard output and standard error output files for command execution. For details about the format of redirection information, see (1) Common argument format for job control function commands.
-jn name-of-the-source-job
Specify the job name of the SAP job to be copied. A character string of 1 to 32 bytes can be entered for the job name specification.
Note that the -jn option specification cannot be omitted.
-jc job-count-of-the-source-job
Specify the job count of the SAP job name to be copied. A character string of 1 to 8 bytes can be entered for the job count of the source job. If the specified character string is shorter than 8 bytes, it is padded with leading zeros to be 8 bytes and then copied.
Note that the -jc option specification cannot be omitted.
-js number-of-the-first-step-to-start-copying-job
Specify the job count of the SAP job name from which the copying is started. A character string of 1 to 2 bytes can be entered for the number of the first step to start copying job. If the specified character string is shorter than 2 bytes, it is padded with leading zeros to be 2 bytes and then copied. If 0 or 1 is specified, all job steps are copied.
-djn new-name-of-the-copied-job
Specify the name of the copied SAP job. A character string of 1 to 32 bytes can be entered for the job name. If the new name of the copied job is omitted, the job is copied with the same name as the source job.
-tgh target-host
Specify the host name of the application server that executes the copied job. As the target host designation, a character string of between 1 and 32 bytes can be entered. From the list of host names displayed by the transaction SM51, you can also select the host name assigned to the application server that offers a background processing service.
If you specify this option, the command will select one of the application servers that are running on the specified host and designate it as the target system.
If you omit this option and the -tgs option, the SAP system will dynamically select the target system on which the job will run. You cannot specify the tgh and -tgs options at the same time.
- Note
-
This option is the job definition compatible parameter created for Release 4.0 and earlier SAP systems. To define jobs for Release 4.5 or later SAP systems, use the -tgs option.
-tgs target-server
Specify the name of the application server or the job server group that executes the copied job. You can specify a character string of 1 to 20 bytes for the target server. When you use an application server, you can specify one of the names that are assigned to the application servers for providing background processing services (upper-case and lower-case characters are differentiated). These application server names are listed as host names by transaction SM51. When you use a job server group, you can specify one of the names (upper-case and lower-case characters are differentiated) of the job server groups containing the application servers that provide background processing services. These job server group names are listed by transaction SM61.
If you omit this option and the -tgh option, the SAP system will dynamically select the target system on which the job will run. You cannot specify the tgs and -tgh options at the same time.
-rs
This argument releases the job as soon as possible after its copy.
To release a job as soon as possible means that the job will be released when the system resources necessary for executing the job are allocated.
If the necessary resources cannot be allocated because another job is exclusively using the SAP system resources, release of the job is suspended until the necessary resources are allocated.
-ri
This argument releases the job immediately after its copy.
The job is released immediately after the command is entered, regardless of whether the system resources necessary for executing the job are allocated. Therefore, release of a job fails if another job is exclusively using the SAP system resources.
-wait
This argument performs job monitoring until the execution of the released job ends (until job execution ends, commands cannot be executed from the command line).
If the job being monitored for its completion is interrupted by the SAP system, the completion monitoring may not end. In such a case, a KAJM1836-W message appears. Follow the instructions in the message.
The -wait option is valid when the -rs or -ri option is specified.
-time monitoring-time
Specify the duration of job completion monitoring in minutes. Job completion will be monitored for the specified period of time. Make sure that this monitoring time setting is greater than the monitoring interval value that is specified by the -ival option. The specifiable range for monitoring time is from 1 to 65,535. If the -time option specification is omitted, there is no limit on the monitoring time.
When the -with_child option is specified, all jobs, including the child jobs, are monitored for their completion during this time.
If the job does not end within the specified monitoring time, that terminates the command without regard to the job status occurs.
The -time option is valid when the -wait option is specified.
-cancel
This argument cancels a job having the job count specified by the -jc option if it does not end within the time specified by the -time option. Note that this argument works only on an active job (job currently being executed). It does not cancel jobs under the following conditions:
-
The job whose completion is being monitored is not active.
-
An external program job step is being executed while the job whose completion is being monitored is active.
When the -with_child option is specified, all jobs, including the child jobs, are canceled.
If the -cancel option is not specified, the job execution continues as is in the SAP system.
The -cancel option is valid when the -time option is specified.
-ival monitoring-interval
Specify the interval in seconds at which a job is to be monitored. Job monitoring can be performed at the specified monitoring interval until the job ends (job polling monitoring). The specifiable monitoring interval range is from 1 to 65,535. If a monitoring interval is omitted when the -ival option is specified, the monitoring interval is 5 seconds.
The default monitoring interval setting of 5 seconds can be changed in the environment setup file.
The -ival option is valid when the -wait option is specified.
-jo SAP-job-log-filename
Specify the SAP job log output destination. The SAP job log is acquired when job execution ends (when the return value is 0 or 1 and the -wait option is specified). The length of the character string for the SAP job log filename varies depending on whether Windows or Linux is used.
-
When Windows is used
A character string of 1 to 259 bytes can be entered for the SAP job log filename.
-
When Linux is used
A character string of 1 to 255 bytes can be entered for the SAP job log filename.
If you do not use the full path to specify the SAP job log file, the file is created in the work directory of JP1/AJS3 for EAP. (If the JP1/AJS3 for EAP work directory is not defined, the file will be created in the current directory.)
For the SAP job log file name, do not specify a device file, such as /dev/null. If the SAP job log file is not needed, delete the file that is created.
The SAP job log output is in write-date write-time message-code (message class and message number) message-text format.
You can also write the SAP job log to this file.
-
When the -se option is specified
You can output SAP job logs to the standard error output file specified in the -se option.
-
When you do not specify the -se option, but specify a standard error output file name in the Define Details - [Custom Job] dialog box of JP1/AJS - View
You can view the content of the SAP job log in the Execution Result Details dialog box in the Jobnet Monitor window of JP1/AJS - View.
If you specify YES for the JoblogAddToStderr key of the Command section of the environment settings file, you can output the SAP job log to the specified file and to the standard error output at the same time. Therefore, when the -se option is not specified, you can use JP1/AJS - View to view the contents of the SAP job log as described above.
When the -with_child option is specified, the log of all jobs that are finished or terminated is acquired when the completion monitoring of all jobs, including the child jobs, ends (includes timeout errors).
If the -jo option specification is omitted, the SAP job log will not be output to the JP1/AJS3 for EAP system.
-mt
Specify this option if the message type is output to the SAP job log.
If the -jo option is not specified, this option cannot be specified.
-mts message-type-character-string
Specify this option if the message type in the SAP job log is searched.
A character string of 1 to 8 bytes can be entered for the message type character string. The characters that can be specified and their meaning are shown below. If you specify more than one character, enter a character followed by the other characters.
A: Abnormal termination E: Error S: Successful end I: Information W: Warning
You must specify it if you search the message types. If the -mt option is not specified, this option cannot be specified. The command terminates abnormally with the return value 4 if the message type of the output job log contains the character string specified in the message-type-character-string.
-with_child
This argument monitors the completion of all jobs, including the child jobs, that are generated during the execution of the target job (completion monitoring of parent and child jobs). The target child jobs are those that are detected when the job being monitored for its completion is finished or terminated. A maximum of 100 jobs can be monitored for their completion regardless of the generation numbers of the child jobs.
If the number of jobs to be monitored for their completion exceeds the maximum limit, a KAJM1872-W message appears. The completion monitoring then continues for the jobs that can be monitored for their completion and the system returns 1, indicating that the result of at least one job cannot be checked.
If a job being monitored for its completion is deleted, a KAJM1837-W message or a KAJM1871-W message appears. The completion monitoring then continues for other target jobs and the system returns 1, indicating that the result of at least one job cannot be checked.
If the system detects a child job that is not released, the completion monitoring may not end. In such a case, a KAJM1838-W message appears. Follow the instructions in the message.
The -with_child option is valid when the -wait option is specified.
- Note
-
To specify the -with_child option, JP1/AJS2 for EAP 07-50 or later must be installed on the execution destination host, and the XBP 2.0 interface and the parent and child function must be enabled in the connection destination SAP system.
-help
This argument provides information on using the command.
Return values
-
When the -wait or -cancel option is not specified
- 0
-
The job was successfully copied.
- Integer of 1 or more
-
The job was not copied.
-
When the -wait option is specified
- 0
-
The job ended normally.
All the jobs ended normally (when the -with_child option is specified).
- 1
-
The job was canceled.
One or more jobs were canceled or the result of at least one job could not be checked because the number of jobs to be monitored exceeded the maximum limit or the target job was deleted (when the -with_child option is specified).
- 2
-
The job completion monitoring resulted in a timeout error.
- Integer of 3 or more
-
The command ended abnormally (job copy, release, or monitoring failed).
-
When the -cancel option is specified
- 0
-
The job ended normally.
All the jobs ended normally (when the -with_child option is specified).
- 1
-
The job was canceled.
One or more jobs were canceled or the result of at least one job could not be checked because the number of jobs to be monitored exceeded the maximum limit or the target job was deleted (when the -with_child option is specified).
- 2
-
All the jobs were successfully canceled when the job completion monitoring resulted in a timeout error.
- 3
-
At least one job failed to be canceled when the job completion monitoring resulted in a timeout error.
- Integer of 4 or more
-
The command ended abnormally (job copy, release, or monitoring failed).
-
When the -mts option is specified
- 0
-
The job ended normally.
All the jobs are finished and the message type specified in the -mts option is not output to the job log.
- 1
-
The job was canceled.
One or more jobs were canceled or the result of at least one job could not be checked because the number of jobs to be monitored exceeded the maximum limit or the target job was deleted.
- 2
-
All the jobs were successfully canceled when the job completion monitoring resulted in a timeout error.
- 3
-
At least one job failed to be canceled when the job completion monitoring resulted in a timeout error.
- 4
-
The job was finished and the message type specified in the -mts option is output to the job log.
- Integer of 5 or more
-
The command ended abnormally (job copy, release, or monitoring failed).
Precautions
If one of the following conditions is satisfied, the job execution target option (-tgh or -tgs) specified in the jr3bjcpy command will be ineffective:
-
The release option (-rs or -ri) is not specified.
-
You have normally copied the job, but have failed to release the job.
In this event, no target host is assigned to the job copied on the SAP system.
To execute the job on a particular target host or server, release the job by specifying the target host or server using the -tgh or -tgs option in the jr3bjrel command. If you use the jr3bjrel command to release the job without specifying a target host or server, the SAP system will dynamically select the target host or server on which the job will be executed.
Supplement
-
If an error occurs during copy of job or jr3bjcpy command execution is aborted, unnecessary jobs (nonexecutable jobs) may remain in the SAP system. Delete unnecessary jobs using the jr3bjdel command.
Usage examples
-
Copying job R3JOB1 of user R3USER1
The conditions are as follows:
-
The sapnwrfc.ini file will be used (-d R3SERV1).
-
SAP logon information will be specified (-c 001 -u R3USER1 -p2 HT0110).
-
The job will be released as soon as possible after it is copied (-rs).
-
The job count of the copying SAP job will be specified (-jc 1000).
-
The new name of the copied job will be specified (-djn R3JOB1CP).
-
The SAP job log file, standard output file, and standard error output file will be created in the directory specified by the environment setup file
(-jo JOBLOG1 -so STDOUT1 -se STDERR1).
To create job R3JOB1 of user R3USER1 under the above conditions, make sure that the jr3bjcpy command line is specified as follows:
jr3bjcpy -d R3SERV1 -c 001 -u R3USER1 -p2 HT0110 -jn R3JOB1 -jc 1000 -djn R3JOB1CP -rs -wait -jo JOBLOG1 -so STDOUT1 -se STDERR1
-