Running a Scheduled Job Using the DSTRUN Subroutine

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.


Top of page

x
Reference: DSTRUN Requirements

Top of page

x
Syntax: How to Immediately Run a Scheduled Job Using DSTRUN
-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:

&var_name

Is the variable that will contain the return code.


Top of page

x
DSTRUN Subroutine Arguments

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.



x
srv_userid Argument for DSTRUN

Description

Valid user ID on WebFOCUS Reporting Server and ReportCaster user with schedule privilege. It must match the user ID stored in the ReportCaster 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).



x
srv_userid_length Argument for DSTRUN

Description

Length of the user ID.

Required?

Yes

Format

I4

Valid Values

Integer



x
srv_userpass Argument for DSTRUN

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.



x
srv_userpass_length Argument for DSTRUN

Description

Length of the srv_userpass value.

Required?

Yes

Format

I4

Valid Values

Integer



x
hostname_port Argument for DSTRUN

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.

  • If the port number is 80 (the default), you may omit the colon and port number. For example,
    'hostname',
  • If the port number is not 80, use a colon as a delimiter and then specify the port number. For example,
    'hostname:81',

    Is the host name (or IP address) and port number of the Web server on which the WebFOCUS Client is installed. The maximum character length for port is 10.

Note: Since there is no longer a specific ReportCaster web application, you must provide information so that the interface is explicitly directed to go to the WebFOCUS application context root. For example, the following method can be used to correctly pass the hostname parameter:

<host>:<port>/ibi_apps:ibi_apps',&LEN,

The hostname parameter is the third parameter passed to DSTBULK. Be sure to substitute the actual hostname for <host> and port number for <port>. After the slash (/) delimiter, this is followed by the name of the default context root for the WebFOCUS web application (which is ibi_apps in most cases), followed by a colon delimiter (:). Next, indicate the name of the ReportCaster web application which in release 77 and higher is always the same as the WebFOCUS web application. For example: serv01:8080/ibi_apps:ibi_apps',&LEN, provided that serv01 is the hostname of the box where your application server resides and 8080 is the port it is listening on. In addition, this assumes that you are using the default context root for WebFOCUS of ibi_apps if not substituted accordingly. Finally, &LEN should contain the length in digits of the string of this parameter.

The maximum character length for the context root is 40.

Required?

Yes

Format

A123

Valid Values

No restrictions.



x
hostname_port_length Argument for DSTRUN

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



x
scheduleid Argument for DSTRUN

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.



x
scheduleid_length Argument for DSTRUN

Description

Length of scheduleid.

Required?

Yes, if scheduleid is supplied.

Format

I4

Valid Values

Integer



x
jobdesc Argument for DSTRUN

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.



x
jobdesc_length Argument for DSTRUN

Description

Length of the description for the scheduled job.

Required?

Yes, if jobdesc is supplied.

Format

I4

Valid Values

Integer



x
priority Argument for DSTRUN

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.



x
owner Argument for DSTRUN

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



x
user_length Argument for DSTRUN

Description

Length of the user ID of the owner of the scheduled job.

Required?

Yes

Format

I4

Valid Values

Integer



x
parm Argument for DSTRUN

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.



x
parm_length Argument for DSTRUN

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



x
httpuser/pswd Argument for DSTRUN

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.



x
httpuser/pswd_length Argument for DSTRUN

Description

Length of the Web server user ID and password, including the character /.

Required?

Yes, if httpuser/pswd is supplied.

Format

I4

Valid Values

Integer



x
tcpiplevel Argument for DSTRUN

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.



x
returncode Argument for DSTRUN

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'



Example: Immediately Running a Scheduled Job Using DSTRUN

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:

  1. The FILEDEF command establishes the location of a file named sublog.ftm. DSTRUN writes error codes and messages (if there are any) to this file, as coded in line 12. The -RUN command executes the FILEDEF command.

    For more information about the FILEDEF command, see your the Developing Reporting Applications manual.

  2. The -SET Dialogue Manager command calls the ReportCaster API subroutine DSTRUN. It sets the amper variable &SUBERR to the value of the return code that is provided on successful, or non-successful, completion of the subroutine.

    The Execution ID ('userid'), included in single quotation marks, and length of 'userid' (6), are the first arguments passed to the subroutine.

  3. The Execution ID password ('mypass') and length of the password (6) are passed to the subroutine.
  4. The name of the Web Server or Application Server running the WebFOCUS Client is 'webhost' and the port number is 80. The value 80 is not specified because it is the default. The length of the server name is 7.
  5. This line illustrates the required code for the arguments scheduleid and scheduleid_length. The argument scheduleid is an optional alphanumeric argument; it is only required if there are multiple schedules for a job. If you do not supply a value for an optional alphanumeric argument, you must code the line as shown to hold the position for the argument and to indicate a length of zero.
  6. The user-supplied description of the job is 'myjob'. The length of the description is 5.
  7. The priority level is the lowest possible, 5.
  8. The ID of the user who owns the scheduled job is 'cdmsales'. The ID length is 8.
  9. Two parameters are being passed. The value ENGLAND is assigned to the variable COUNTRY, and the value JAGUAR is assigned to the variable CAR. The variables exist in the report request and require values at run time. They are enclosed in single quotation marks. The total length of this string is 25.
  10. In our example, the Web server is running with security on, so a valid Web server user ID and password are required. The Web server user ID (webuser) and password (webpass) are passed to the subroutine. The length of the user ID and password string is 15, which includes the character /. The string is enclosed in single quotation marks.
  11. The format of the value of the return code ('I4') is the last argument passed to the subroutine.
  12. The error handling code tests the value of &SUBERR, which holds the return code from the subroutine. If the return code is 0, which indicates successful completion of the subroutine, the procedure terminates.

    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.



Example: Running a Schedule with a Different Execution ID

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