STREAM


STREAM

     Spools batch jobs or data from a session or job.  The
optional time-related parameters of the STREAM command may
be used to schedule jobs. (CM)

SYNTAX


STREAM [filename] [,char]

[;AT = timespec]

{day-of-week }
[;DAY = {day-of-month }]
{day-until-month}

[;DATE = datespec]
[;IN = [days[, [hours] [,minutes]]]]

[;JOBQ = queuename]


PARAMETERS


filename The Editor (ASCII) file containing the commands of
the job. The first character of the first record is
assumed to be the replacement character for the
expected colon () that identifies MPE/iX commands.
The user must have READ or EXECUTE access.

char Character used in place of colon () to identify MPE
XL commands within the input file. When the input
file is entered on a device configured to accept
jobs or sessions, this character can be any ASCII
special (non-alphanumeric) character except a colon.
Default is an exclamation point (!).

AT Absolute time specification.

timespec Time specification. This is the absolute time of
day in the format and MM is the minutes If DAY and
DATE are not specified, then

timespec < NOW------------> job logon tomorrow
timespec > NOW------------> job logon today
timespec = NOW------------> job logon immediately
with explanatory
message
DAY Absolute day specification.

day-of-week Day-of-Week. Allowable values are

SUN[DAY]
MON[DAY]
TUE[SDAY]
WED[NESDAY]
THU[RSDAY]
FRI[DAY]
SAT[URDAY]

day-of-month Day-of-Month. The integers 1 through 31. It
indicates the calendar day of the month. If day-of-
month is greater than or equal to the current day-
of-month, the current month is indicated. If day-
of-month is less than the current day-of-month, the
next month is indicated. An error message is
generated if the day-of-month does not correspond to
the month (for example, 31 is entered for February).
If day-of-month is omitted, the current date is used.

days-until-month Days until the end of the month. The negative
integers -31 through -1. It indicates the calendar
day from the end of the specified month on which the
job will run. For example, a -1 value represents
the last day of the month. If the specified day
from the end of the month indicates a day earlier
than the current day, the next month is assumed.
For example, if today is the seventh day from the
end of the month and a -8 value is entered, the job
will be scheduled for the eighth day from the end of
the next month.

DATE Absolute date specification.

datespec Date, specified in the format mm/dd/yy, where mm is
the month (1<=mm<=12), dd is the day (1<=dd<=31),
and yy is the year. If omitted, the current date is used.

IN Relative date or time specification.

days Days. A positive integer indicating the number of
days from the current date.

hours The number of hours from the current
time. If omitted, zero is used.

minutes The number of minutes from the current
time. If omitted, zero is used.

queuename The name of the queue into which the job should
logon. If the queuename is not specified the default
system job queue will be used.

OPERATION


With this command you can initiate jobs while in an
interactive session by constructing your job from your
terminal or by reading records from a disk or tape file.
When the job is read, MPE/iX spools it onto a disk file,
assigns it a job number, and processes it independently as
an entity completely separate from your session. In the
meantime, MPE/iX allows you to continue with your session.

You can initiate jobs in this way only if the system
operator, or a user who has been given operator
capabilities, has enabled the MPE/iX STREAM facility by
entering the console command STREAMS. The console command
STREAMS also specifies a streaming device, which to MPE/iX
appears to be the source of your job input, regardless of
the device you actually use for this input. As a result,
the listing device that corresponds to the streaming device
(and not your terminal) will display the job number assigned
by MPE/iX and the listing generated by the job.

When you enter STREAM without and input file (that is, with
the terminal as the default input device) during a session
or a job, MPE/iX prompts you for input by displaying a
greater than (>) character. When you enter STREAM for a
device other than your terminal, MPE/iX does not print the
prompt character.

Using the parameter ;JOBQ, the user can specify in which queue
a particular job should logon. The name specified here overrides
the queue name specified in the JOB command.

This command may be issued from a session, job, in BREAK, or
from a program. Pressing [Break] aborts the execution of
this command and any partially streamed job.


Streaming Jobs

Begin each job in the input file with the !JOB command and
terminate it with the !EOJ command. Begin all commands with
an appropriate substitute (other than colon) character, as
in !JOB. When the input file is spooled to a disk, MPE/iX
replaces the substitute command identifier with a colon, so
that the data files are properly interpreted when executed.

After reading the !EOJ command that terminates the job, MPE
XL assigns each job a unique job number (JobID). MPE/iX
also assigns each job a preset priority, unless you specify
otherwise in the JOB command, and processes the job
independently of the initiating job or session. Regardless
of which device you use to submit the input file, all jobs
in that file are treated as though they originated on the
unique streaming device designated by the system operator
(with the STREAMS command). The listing for each spooled
job and the job number are written to the standard list
device that corresponds to the streaming device. You may,
however, use the OUTCLASS= parameter of the JOB command to
direct the listing to another device.


Timing Scheduled Jobs

You must specify the time a job is to enter the WAIT state
in absolute or relative time.

Absolute The user supplies an exact time for the job using
the AT parameter with or without the DAY or DATE
parameter.

Relative The user specifies a time offset from the current
time using the IN parameter.

If the time specified is the same as the current time, the
specified job will log on immediately. If the time
specified is earlier than the current time and DAY and DATE
are not specified, a warning message is generated, and the
job is scheduled for the specified time tomorrow.
Otherwise, any time in the current century can be specified.

If no errors are detected, a JobID is displayed on the
user's screen. If more than one job is included in the
inputfile, each job is assigned a unique JobID, and all of
the jobs will be scheduled at the same time.

When a job is scheduled for a future time, it enters the
SCHED state. When the specified time is reached, the job
enters the WAIT state and will be executed when system
variables allow.


Terminating Streamed Jobs

To terminate interactive job input, enter a colon (). In
response, MPE/iX ceases prompting for batch job input and
instead prompts you for another MPE/iX command

> ** Denotes end of batch job input **

** MPE/iX prompts for next command **

Pressing [Break] aborts the execution of this command and
any job currently being entered through the command.
Incompletely spooled disk space is returned to the system.

If you make an error while entering the MPE/iX JOB command,
you will receive an error message on your job listing
device. The system operator, however, receives no
indication of the job or the error.

Terminating Time Scheduled Job

Jobs that have been scheduled for STREAM execution can be
terminated with the ABORTJOB command. Refer to the
Migration Guide System Administrator's Skills (30367-
90003) for information on using the ABORTJOB command to
terminate time-scheduled jobs.

In order to STREAM a file, you must have READ and LOCK
access or EXECUTE access to that file. However, READ and
LOCK access would allow general users to obtain security
information within the file, such as passwords and
lockwords. To allow general users to STREAM the file
without giving them access to secure information, you may
allow EXECUTE access only.

NOTE


Scheduled jobs will survive a START RECOVERY. Any other system starts
will cause scheduled jobs to be deleted. If a job is scheduled for
introduction earlier than the system startup, the job will enter the
WAIT state and execute when the system parameters allow it to execute.

If the system is brought down for any reason, first execute
a SHOWJOB command to show the scheduled jobs. Then
reschedule the jobs when the system is brought back up on
anything other than a START RECOVERY.

A scheduled job uses an entry in the JMAT table. Because of
the limited recoverability of scheduled jobs, it is
recommended that jobs be scheduled no more than a few days
in advance.

If a user specifies a day or date for a job, but does not
specify a time, the job will not enter the WAIT state at
midnight on the specified day. Instead, it will use the
time that the STREAM is executed, and will enter the WAIT
state at that time on the specified day.


EXAMPLE(S)

     To stream a job from a disk file, you must name the input
file in the STREAM command

STREAM ABC

If you use a character other than an exclamation point (!)
as the substitute command identifier in your job input, you
must identify that character in the STREAM command.
Because you enter this character as the second positional
parameter in this command, you must always precede it with a
delimiting comma, even when you omit the input file name
(the first parameter)

STREAM ,*
>*JOB MAC.TECHPUBS

>*FORTGO MYPROG
>*EOJ
#J74
>


** Asterisk is used as a substitute command identifier **

If your job input file contains subsystem commands, such as
commands directed to the editor, do not enter any command
identifier character at the beginning of these commands.
For instance, when using the editor, enter the subsystem
commands as follows

STREAM EXAMPLE ** The job input file is EXAMPLE. **
!JOB WXYZ,WRITER.TEC ** Initiates the job WXYZ. **
!EDITOR ** Invokes the Editor. **
TEXT ABC ** Subsystem commands without (!) as **
** an identifier. **
LIST ALL,OFFLINE
EXIT
!EOJ ** Terminates job. **
#J87 ** Job number supplied by MPE/iX. **


If you want the job listing to appear on a device other than
the standard listing device associated with the streaming
device, you can specify this other device in the MPE/iX JOB
command. Enter

STREAM
>!JOB MAC.TECHPUBS;OUTCLASS=12

The following section contains additional examples of
STREAM command usage. For these examples, assume that the
current date and time are Monday, June 8, 1987, 12:00 p.m.
Also assume the job file contains a valid STREAM job.

STREAM JOBFILE JOBFILE will be introduced immediately.

STREAM JOBFILE;AT=8:00 JOBFILE will be introduced at 8:00 a.m.,
Tuesday, June 9.

STREAM JOBFILE;AT=20:00 JOBFILE will be introduced at 8:00 p.m.,
Monday, June 8.

STREAM JOBFILE;IN=,8 JOBFILE will be introduced in eight hours,
at 8:00 p.m., Monday, April 8.

STREAM JOBFILE;IN=1,8 JOBFILE will be introduced in one day plus
eight hours, at 8:00 p.m., Tuesday, June 9.

STREAM JOBFILE;
DAY=MON;AT=8:00 Since the time specified (8:00 a.m.) is
earlier than the current time, JOBFILE
will be introduced at 8:00 a.m., Tuesday,
June 9.

STREAM JOBFILE;
DAY=MONDAY;AT=20:00 Since the time specified (8:00 p.m. is later
than the current time, JOBFILE will be
introduced at 8::00 p.m., Monday, June 8.

STREAM JOBFILE;
DAY=9;AT=20:00 Since the day of the month (9) is later
than the current day of the month (8),
the current month is assumed. JOBFILE
will be introduced on Tuesday, June 9, at
8:00 p.m.

STREAM JOBFILE;DAY=5 Since the day of the month (5) is earlier
than the current day (8), the next month is
assumed. Since no time was specified,
JOBFILE will be introduced on Sunday, July
5, at 12:00 p.m.

STREAM JOBFILE;DAY=31 Since there is no June 31, the next month
is assumed. Since there is a July 31, this
is a legal command. JOBFILE will be
introduced on Friday, July 31, at 12:00
p.m. If there were no July 31, this would
result in an error.

STREAM JOBFILE;DAY=-2 The"-2" means the second to last day of the
month, and since no time was specified, the
current time is used. JOBFILE will be
introduced on Sunday, June 29, at 12:00
p.m.

STREAM JOBFILE;DAY=-20 The "-20" means the twentieth day from the
end of the month. Using the assumed date of
June 8 as the current date, this implies that
the job will be streamed on Thursday, June 11
at 12:00 p.m.

STREAM JOBFILE;
DATE=4/8/87;AT=8:00 Since the specified time is earlier than the
current time, this command is not legal and
will result in an error.

STREAM JOBFILE;
DATE=4/8/87;AT=20:00 The specified time is later than the current
time, so this command is legal. JOBFILE will
be introduced on Monday, June 8, at 8:00 p.m.

STREAM JOBFILE; JOBFILE will be introduced to the queue
JOBQ=MYJOBQ MYJOBQ.

ADDITIONAL INFORMATION

Commands:   JOB, STREAMS

Manuals : Performing System Operation Tasks (32650-90137)