Scheduling a Job Using the DSTSCHED Servlet

In this section:

The DSTSCHED servlet schedules a new job. It generates a unique, 12-digit schedule ID, which is the key that identifies the new job in BOTSCHED.

By default, the owner of the scheduled job is the user ID from the WebFOCUS cookie.


Top of page

x
DSTSCHED Requirements

DSTSCHED is a direct HTML call with following requirements:

Windows and UNIX only:

OS/390 only:

The report request scheduled for execution and distribution must reside in a partitioned data set (PDS) allocated to ddname EDARPC.



Example: Specifying a Relative Address Using DSTSCHED
<FORM ACTION="/context_root/servlet/DSTSCHED">

where:

context_root

Is the configurable context root for the ReportCaster web application in your Application Server configuration. By default, this is /ibi_apps.


Top of page

x
DSTSCHED Parameters

In this section:

 

The following parameters may be used in an HTML calling form to generate the query string passed to the DSTSCHED servlet.



x
IBIB_active Parameter

Description

Status of job.

Required?

No

Size in bytes

1

Valid Values

Y = Active. Job runs at next scheduled interval.

N = Inactive. Job will not run as scheduled.

Default

Y



x
IBIB_byfield Parameter

Description

Type of report.

Required?

Yes

Size in bytes

1

Valid Values

Y = Report is burst.

N = Report is not burst.

Default

N



x
IBIB_dates Parameter

Description

Day of the month the report request will run.

This parameter can occur multiple times if IBIB_interval is M (monthly) and the report runs twice or more during the month. Values are required for the specific days in the month, such as the 1st and the 15th. This results in multiple instances of IBIB_dates in the parameter string (for example, IBIB_dates=1, IBIB_dates=15).

Required?

Yes, if IBIB_interval is MONTH (or M). Otherwise, it is ignored.

Size in bytes

2

Valid Values

A number between 1 and 31, or the value Last Day, which means the last day of the month. Internally, Last Day is assigned the value 32 by the servlet.

Default

None



x
IBIB_distlist Parameter

Description

Name of the existing Distribution List containing the recipients of the report. The list must reside in the WebFOCUS repository.

Required?

Yes

Size in bytes

50

Valid Values

An existing Distribution List created using the ReportCaster API.

Default

None



x
IBIB_enddate Parameter

Description

Date of last report execution and distribution, in the format YYYYMMDD, where YYYY is the 4-digit year, MM is the month, and DD is the day of the month.

Required?

No

Size in bytes

8

Valid Values

A date specified as YYYYMMDD.

Default

20990101



x
IBIB_endtime Parameter

Description

Time of last report execution and distribution, in the format HHMM, where HH is the hour and MM is the minute.

Required?

No

Size in bytes

4

Valid Values

A time specified as HHMM.

Default

0000 (midnight)



x
IBIB_frequency Parameter

Description

Number of times the report request is executed and distributed within the specified interval. For example, if you specify a monthly interval (IBIB_interval is M), and you also specify 3 for the number of times (IBIB_frequency is 3), then the report runs every 3 months.

Required?

No

Size in bytes

2

Valid Values

Must be numeric. No special characters or decimals are allowed.

Default

1



x
IBIB_interval Parameter

Description

Period of time (the interval) on which report execution and distribution are based.

Required?

Yes

Size in bytes

5

Valid Values

ONCE or O = One time. HOUR or H = Hourly. DAY or D = Daily. WEEK or W = Weekly. MONTH or M = Monthly. YEAR or Y = Yearly.

Default

ONCE



x
IBIB_jobdesc Parameter

Description

Unique, user-supplied description for the report request (job) being scheduled.

Required?

No

Size in bytes

90

Valid Values

Alphanumeric characters with embedded blanks and special characters are allowed.

Default

Value of IBIB_jobname.



x
IBIB_jobname Parameter

Description

Name of the report request to be scheduled for execution and distribution. It must reside in a path defined to the WebFOCUS Reporting Server. On Windows and UNIX, do not include the extension .fex.

Required?

Yes

Size in bytes

8

Valid Values

Single quotation marks and ampersands are not allowed.

Default

None



x
IBIB_method Parameter

Description

Distribution method.

Required?

Yes

Size in bytes

5

Valid Values

FTP or F = FTP distribution. MAIL or M = Mail distribution. PRINT or P = Printer distribution.

Default

MAIL



x
IBIB_notifyflag Parameter

Description

Flag that controls notification of job status.

Required?

Yes

Size in bytes

1

Valid Values

N = Inactive. No notification is sent. E = Error. Content of the log is sent on an error condition. A = Always. Notification is always sent.

Default

N



x
IBIB_parm Parameter

Description

Values passed to the scheduled job. The values are assigned to variables in the scheduled job and used at run time.

For more information on specifying a parameter string, see Passing Values to a Scheduled Job Using DSTSCHED.

Required?

No

Size in bytes

75

Valid Values

Must fit on an 80-byte line, which includes all punctuation.

Default

None



x
IBIB_postrpc1 and IBIB_postrpc2 Parameters

Description

Name of a procedure and optionally its parameter string that will run after the scheduled report request. This procedure typically performs cleanup and related tasks. For example, a value for IBIB_postrpc2 might be: cleanup discard = yes.

You can specify up to two procedures.

Required?

No

Size in bytes

65

Valid Values

An existing server procedure residing on EDAPATH.

Default

None



x
IBIB_prerpc1 and IBIB_prerpc2 Parameters

Description

Name of a procedure and optionally its parameter string that will run prior to the scheduled report request. This procedure performs setup tasks. An example of an IBIB_prerpc1 value is: setup region = west.

You can specify up to two procedures.

Required?

No

Size in bytes

65

Valid Values

An existing server procedure residing on EDAPATH.

Default

None



x
IBIB_sendformat Parameter

Description

Format of the distributed report output.

Required?

Yes

Size in bytes

8

Valid Values

HTML = Hypertext Markup Language. PDF = Adobe Acrobat Portable Document Format. PS = PostScript. DOC = Text with ASCII form feeds. WP = Text (non-formatted for multiple word processing applications). EXCEL = Excel spreadsheet. EXL2K = Excel 2000 spreadsheet. WK1 = Lotus 1-2-3 spreadsheet.

Default

HTML



x
IBIB_startdate Parameter

Description

Date of first report execution and distribution, in the format YYYYMMDD, where YYYY is the 4-digit year, MM is the month, and DD is the day of the month.

Required?

No

Size in bytes

8

Valid Values

A date specified as YYYYMMDD.

Default

Current system date.



x
IBIB_starttime Parameter

Description

Time of first report execution and distribution, in the format HHMM, where HH is the hour and MM is the minute.

Required?

No

Size in bytes

4

Valid Values

A time specified as HHMM.

Default

Current system time.



x
IBIB_tcpiplevel Parameter

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.

Size in bytes

1

Valid Values

1 = Resolves special connectivity problems. 0 = Specifies no special connectivity problems.

Default

0



x
IBIB_weekdays Parameter

Description

Day of the week the report request will run.

This parameter can occur multiple times. For example, if you specify a weekly interval (IBIB_interval is W), and you also specify 3 for the number of times (IBIB_frequency is 3), then the report runs every 3 weeks. Values are required for the specific days of the week (such as Monday, Wednesday, and Friday), resulting in multiple parameters in the query string: weekdays=MON, weekdays=WED, weekdays= FRI.

Required?

Yes, if IBIB_interval is WEEK (or W).

If IBIB_interval is DAY (or D), and a value is not supplied, the report runs every day of the week.

In all other cases, this parameter is ignored.

Size in bytes

5

Valid Values

MON = Monday. TUES = Tuesday. WED = Wednesday. THURS = Thursday. FRI = Friday. SAT= Saturday. SUN = Sunday.

Default

None


Top of page

x
Mail Parameters for DSTSCHED

In this section:

The following parameters apply only if IBIB_method is MAIL (or M).



x
IBIB_mailcompany Parameter

Description

The company to which the sender is associated.

Required?

No

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed.

Default

None



x
IBIB_mailfrom Parameter

Description

Email address for return mail (the reply address).

DSTSCHED checks the value for the presence of the character @ and returns a message if it is not there.

Required?

No

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed. An @ symbol must be included.

Default

None



x
IBIB_mailhost Parameter

Description

Name of the mail server that distributes the report.

Required?

Yes, if IBIB_method is MAIL (or M).

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed.

Default

Value specified in the ReportCaster Server configuration file.



x
IBIB_mailsubject Parameter

Description

Text that describes the content or purpose of the email.

Required?

No

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed.

Default

None


Top of page

x
FTP Parameters for DSTSCHED

In this section:

The following parameters apply only if IBIB_method is FTP (or F).



x
IBIB_asvalue Parameter

Description

Name of the FTP index file for a burst report.

Required?

No

Size in bytes

8

Valid Values

First character must be alphabetic.

Default

HOLD



x
IBIB_ftphost Parameter

Description

Name of FTP server that distributes the report.

Required?

Yes, if IBIB_method is FTP (or F).

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed.

Default

Value specified in the ReportCaster Server configuration file.



x
IBIB_ftplocation Parameter

Description

Destination of the FTP-distributed report. It must be a subdirectory of the FTP server root directory, or an alias defined to the FTP server.

Required?

Yes, if IBIB_method is FTP (or F).

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed.

Default

Value specified in the ReportCaster Server configuration file.



x
IBIB_ftppass Parameter

Description

Password associated with the FTP user ID.

Required?

Yes, if IBIB_method is FTP (or F).

Size in bytes

64

Valid Values

Spaces are not allowed.

Default

Value specified in the ReportCaster Server configuration file.



x
IBIB_ftpuser Parameter

Description

User ID authorized for FTP transfer.

Required?

Yes, if IBIB_method is FTP (or F).

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed.

Default

Value specified in the ReportCaster Server configuration file.


Top of page

x
Notification Parameters for DSTSCHED

In this section:

The following parameters apply only if IBIB_notifyflag is E or A.



x
IBIB_notifyaddress Parameter

Description

Email address of the person who will receive full notification (complete log report).

DSTSCHED checks the value for the presence of the character @ and returns a message if it is not there.

Required?

Yes, if IBIB_notifyflag is E or A and IBIB_notifybrief is not supplied. May also be supplied if IBIB_notifybrief is present.

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed. An @ symbol must be included.

Default

None



x
IBIB_notifybrief Parameter

Description

Email address of cell phone, pager, or other hand-held device that will receive the abbreviated notification (job schedule ID, job description, and brief status messages).

Required?

Yes, if IBIB_notifyflag is E or A and IBIB_notifyaddress is not supplied. May also be supplied if IBIB_notifyaddress is present.

Size in bytes

64

Valid Values

No restrictions.

Default

None



x
IBIB_notifyreply Parameter

Description

Email address for return mail (the response to the notification message).

DSTSCHED checks the value for the presence of the character @ and returns an error message if it is not there.

Required?

Yes, if IBIB_notifyflag is E or A.

Size in bytes

64

Valid Values

Single quotation marks and ampersands are not allowed. An @ symbol must be included.

Default

None



x
IBIB_notifysubject Parameter

Description

Text that describes the content or purpose of the notification message.

Required?

No

Size in bytes

90

Valid Values

Single quotation marks and ampersands are not allowed.

Default

Value of IBIB_jobdesc.


Top of page

x
Passing Values to a Scheduled Job Using DSTSCHED

How to:

With DSTSCHED, you can pass values to the job that you are scheduling. The values are assigned to the appropriate variables in the scheduled job and used at run time.

You can pass an unlimited number of values to a scheduled job. The values are stored in the BOTPARMS table in the WebFOCUS repository.

Use one of the following formats to pass values to a scheduled job:



x
Syntax: How to Pass Values to a Scheduled Job Using a Variable Within the Parameter
IBIB_parm_variable_name='variable_value'

where:

IBIB_parm_variable_name

Is the composite name of the parameter (IBIB_parm) and the Dialogue Manager variable in the scheduled job (variable_name).

variable_value

Is the value for the Dialogue Manager variable. Embedded blanks must be enclosed in single quotation marks.



Example: Passing a Value to a Report Request Using a Variable Within the Parameter

Consider the following report request, which contains the Dialogue Manager amper variable &TITLE:

TABLE FILE MOVIES
PRINT DIRECTOR CATEGORY
BY TITLE
WHERE TITLE IS '&TITLE'
END

The HTML calling form prompts the user for a value for IBIB_parm_TITLE. Assume that the user enters 'DOG DAY AFTERNOON'. The report request, when run, selects only the record for that movie.

TITLE

DIRECTOR

CATEGORY

DOG DAY AFTERNOON

LUMET S.

DRAMA

The following example illustrates the format used on an HTML form to pass the value to the request:

<input type="text" name="IBIB_parm_TITLE" value="DOG DAY AFTERNOON"

The query string assignment that results is:

IBIB_parm_TITLE='DOG DAY AFTERNOON'


x
Syntax: How to Pass Values to a Scheduled Job Using a Full Assignment Statement
IBIB_parm='variable_name=variable_value'

where:

variable_name

Is the name of the Dialogue Manager variable in the scheduled job.

variable_value

Is the value for the Dialogue Manager variable. Embedded blanks must be enclosed in single quotation marks.



Example: Passing a Value to a Report Request Using a Full Assignment Statement

Consider the following report request, which contains the Dialogue Manager amper variable &TITLE:

TABLE FILE MOVIES
PRINT DIRECTOR CATEGORY
BY TITLE
WHERE TITLE IS '&TITLE'
END

The HTML calling form prompts the user for a value for IBIB_parm_TITLE. Assume that the user enters 'DOG DAY AFTERNOON'. The report request, when run, selects only the record for that movie.

TITLE

DIRECTOR

CATEGORY

DOG DAY AFTERNOON

LUMET S.

DRAMA

The following example illustrates the format used on an HTML form to pass the value to the request:

<input type="text" name="IBIB_parm" value="TITLE=DOG DAY AFTERNOON"

The query string assignment that results is:

IBIB_parm='TITLE=DOG DAY AFTERNOON'

WebFOCUS