In this section: How to: Reference: |
The DSTRUN subroutine is a procedure-based call that immediately runs a job that has previously been scheduled. This only pertains to server-based schedules.
With this subroutine, you can pass values to the scheduled job that you are running. The values are assigned to the appropriate variables in the scheduled job and used at run time.
The specified job will run as soon as a server agent is available. The status of the job (active or inactive) is ignored.
Note: To run the scheduled job with an execution ID other than the execution ID stored with the schedule information in the ReportCaster tables, see Running a Schedule With a Different Execution ID.
-SET &var_name=DSTRUN(srv_userid,srv_userid_length,
- 'srv_userpass',srv_userpass_length,
- 'hostname_port',hostname_port_length,
- 'scheduleid',scheduleid_length,
- 'jobdesc',jobdesc_length,
- priority,
- 'owner',user_length,
- 'parm',parm_length,
- 'httpuser/pswd',httpuser/pswd_length,
[- vtcpiplevel,']
- 'I4');
where:
Is the variable that will contain the return code.
In this section: |
|
The following sections describe the arguments for the DSTRUN subroutine. For an example that uses the DSTRUN subroutine, see Immediately Running a Scheduled Job Using DSTRUN.
Description |
Valid user ID on WebFOCUS Reporting Server and ReportCaster user with schedule privilege. It must match the user ID stored in the WebFOCUS repository. |
Required? |
Yes |
Format |
A48 (Windows and UNIX) A8 (OS/390) |
Valid Values |
Single quotation marks, ampersands, and spaces are not allowed. First character must be alphanumeric (OS/390). |
Description |
Length of the user ID. |
Required? |
Yes |
Format |
I4 |
Valid Values |
Integer |
Description |
Valid password for srv_userid. Must be the same value to validate password on WebFOCUS Reporting Server and ReportCaster table. |
Required? |
Yes |
Format |
A240 |
Valid Values |
Alphanumeric characters and spaces are allowed. |
Description |
Length of the srv_userpass value. |
Required? |
Yes |
Format |
I4 |
Valid Values |
Integer |
Description |
Is the host name (or IP address) and port number of the web server on which the WebFOCUS Client is installed. You must use a colon to separate the server name and port number.
Note: If you configure a context root for the ReportCaster web application in your Application Server configuration that is not the default value (/ibi_apps), then this argument would be: 'hostname:port:rc_context_root' The maximum character length for the context root is 40. |
Required? |
Yes |
Format |
A123 |
Valid Values |
No restrictions. |
Description |
Is the length of the host name and port number. This is only the length of the host name if the port number is omitted. |
Required? |
Yes |
Format |
I4 |
Valid Values |
Integer |
Description |
Unique, API-generated key that identifies the scheduled job. |
Required? |
Yes, if there are multiple schedules for a job. If the job was scheduled to run once, either this argument or jobdesc is required. |
Format |
A12 |
Valid Values |
First character must be alphanumeric. Single quotation marks and ampersands are not allowed. |
Description |
Length of scheduleid. |
Required? |
Yes, if scheduleid is supplied. |
Format |
I4 |
Valid Values |
Integer |
Description |
Unique, user-supplied description for the scheduled job. |
Required? |
Yes, if the job was scheduled to run once and scheduleid is not supplied. |
Format |
A90 |
Valid Values |
Alphanumeric characters with embedded blanks and special characters are allowed. |
Description |
Length of the description for the scheduled job. |
Required? |
Yes, if jobdesc is supplied. |
Format |
I4 |
Valid Values |
Integer |
Description |
Priority level for the job scheduled to run. |
Required? |
Yes |
Format |
I4 |
Valid Values |
1 = Highest priority. 2 = Class 2 priority. 3 = Class 3 priority. 4 = Class 4 priority. 5 = Lowest priority. |
Description |
User ID of the owner of the scheduled job. Optionally, an execution ID other than the execution ID stored with the schedule information in the ReportCaster tables can be specified in the schedule_owner parameter. The specified execution ID must conform to the security rules for the ReportCaster Subroutine API. For more information, see Running a Schedule With a Different Execution ID |
Required? |
Yes. This feature enables a logon user to run a job owned by another user, whose ID is supplied on owner. |
Format |
A99 (Windows and UNIX)A8 (OS/390) |
Valid Values |
Single quotation marks, ampersands, and spaces are not allowed. First character must be alphanumeric (OS/390). |
Description |
Length of the user ID of the owner of the scheduled job. |
Required? |
Yes |
Format |
I4 |
Valid Values |
Integer |
Description |
Values passed to the scheduled job. The values are assigned to variables in the scheduled job and used at run time. Only one value is supported for each argument specified. |
Required? |
No |
Format |
A151 |
Valid Values |
Must fit on an 80-byte line, which includes all punctuation. |
Description |
Length of the parameter string. |
Required? |
Yes, if parm is supplied. This value is the total parameter length, meaning that it may include multiple parameters in a single string. |
Format |
I4 |
Valid Values |
I4 |
Description |
Web server user ID and password. |
Required? |
Yes, if the web server is running with security on. |
Format |
A1000 |
Valid Values |
Valid web server user ID and password. |
Description |
Length of the web server user ID and password, including the forward slash character ( / ). |
Required? |
Yes, if httpuser/pswd is supplied. |
Format |
I4 |
Valid Values |
Integer |
Description |
Method ReportCaster uses for securing sockets from TCP/IP, based on a specific SAS/C library. |
Required? |
Yes, if the WebFOCUS Reporting Server runs on OS/390. |
Format |
I4 |
Valid Values |
1 = Resolves special connectivity problems. 0 = Specifies no special connectivity problems. |
Description |
Value that DSTRUN returns to the calling procedure, indicating successful completion (0) or an error condition. For more information, see ReportCaster API Subroutine Messages. |
Required? |
Yes |
Format |
I4 |
Valid Values |
'I4' |
The following Dialogue Manager procedure calls DSTRUN to immediately run a scheduled job. The procedure resides on a WebFOCUS Reporting Server for Windows. The numbers to the left of the code refer to the annotations that follow.
1. FILEDEF SUBLOG DISK D:\ibi\srv77\wfs\catalog\sublog.ftm -RUN 2. -SET &SUBERR = DSTRUN( - 'userid',6, 3. - 'mypass',6, 4. - 'webhost',7, 5. - ' ',0, 6. - 'myjob',5, 7. - 5, 8. - 'cdmsales',8, 9. - 'COUNTRY=ENGLAND,CAR=JAGUAR',25, 10. - 'webuser/webpass',15, 11. - 'I4'); 12. -IF &SUBERR EQ 0 GOTO EXIT; -INCLUDE DSTRUNER -WRITE SUBLOG &SUBERR -EXIT
The procedure runs as follows:
For more information about the FILEDEF command, see the Developing Reporting Applications manual.
The Execution ID ('userid'), included in single quotation marks, and length of 'userid' (6), are the first arguments passed to the subroutine.
If it is a non-zero value, indicating an error condition, the procedure continues to the next line, which incorporates the supplied file DSTRUNER. DSTRUNER translates return codes into meaningful messages. Messages are written to the file sublog.ftm, which was defined by the FILEDEF command in the first line of code.
For more information about DSTRUNER, see ReportCaster API Subroutine Messages.
Note: The initial hyphen and space on each line are required for a continuation line.
To run the scheduled job with an execution ID other than the execution ID stored with the schedule information in the ReportCaster tables, you can specify the execution ID within the schedule_owner parameter in the DSTRUN subroutine call. The maximum size of the schedule_owner parameter is 200 characters.
The specified execution ID must conform to the security rules for the ReportCaster Subroutine API which means that it must be a valid user ID and password on the WebFOCUS Server, and a ReportCaster user with schedule privilege.
The format to specify a different execution ID in the schedule_owner parameter is schedule_owner:execID. In the example below, the execution ID is specified in line 10. The execution ID specified in the schedule_owner parameter must match the execution ID specified the execID parameter in line 4.
1. FILEDEF SUBLOG DISK C:\SUBLOG.FTM 2. RUN 3. -SET &SUBERR=DSTRUN( 4. - 'execid2',7, 5. - 'execid2',7, 6. - 'jetsetter:8080',14, 7. - 'S11o9sddut01',12, 8. - ' ',0, 9. - 5, 10. - 'admin:execid2',13, 11. - ' ',0, 12. - ' ',0, 13. - 'I4'); 14. -IF &SUBERR EQ 0 GOTO EXIT; -INCLUDE DSTRUNER -WRITE SUBLOG &SUBERR -EXIT
If the execution ID specified in the schedule_owner parameter does not match the execution ID specified the execID parameter, the execution ID value stored for the schedule in the ReportCaster tables is used to run the scheduled job.
If the execution ID and password in the WF_COOKIE exists in the ReportCaster tables (BOTUPROF) but the password in the WF_COOKIE does not match the password in the ReportCaster tables, an authentication error is given.
WebFOCUS |