Commands STREAM thru XEQ

The STREAM command allows you to 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 specify the queue name into which a particular job should go. The name specified overrides the queue name specified in the JOB command.

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 STREAMS console command. The STREAMS console command 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 (not necessarily your terminal) displays the job number assigned by MPE/iX and the listing generated by the job.

When you enter STREAM without an 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.

How to Stream 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/iX 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.

How To Time Schedule Jobs

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

If the time specified is the same as the current time, the specified job logs 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 are 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 is executed when system variables allow.

Terminating Streamed Jobs

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

>:  ** Denotes end of batch job input **
 
:  ** MPE XL 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 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 Introduction to MPE XL for MPE V System Administrators (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 survive a START RECOVERY. Any other type of system startup causes scheduled jobs to be deleted. If a job is scheduled for introduction earlier than the system startup, the job enters the WAIT state and executes 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 does not enter the WAIT state at midnight on the specified day. Instead, it uses the time that the STREAM is executed, and enters the WAIT state at that time on the specified day.

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

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). In the following example, an asterisk (*) is used as a substitute command identifier:

 STREAM ,*
>*JOB USER.TECHPUBS
 
>*FORTGO MYPROG
*EOJ
*#J74
*>:
 
:

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
!JOB WXYZ,WRITER.TEC 
!EDITOR   
TEXT ABC   
n
EXIT
!EOJ    
#J87    
 
:

In the preceding example, the job input file is EXAMPLE which initiates the job WXYZ. WXYZ invokes the editor subsystem where the file ABC is referenced. The EOJ command terminates the job and #J87 is the job number assigned 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 USER.TECHPUBS;OUTCLASS=12

The following section contains additional examples of using the STREAM command. 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.

The operator executes this command after a startup to enable the STREAM facility. The STREAMS device must be enabled each time the system is brought back online in order to allow users to stream jobs. (Streamed jobs are processed separately by MPE/iX, allowing users to continue with other work at their terminal. If the streamed job is submitted on a tape drive rather than from a terminal, MPE/iX processes it without requiring the user's attention.) Any attempt to stream a job when the STREAMS facility is disabled generates the following message:

STREAM FACILITY NOT ENABLED: SEE OPERATOR. (CIERR 82)

The device normally configured as the STREAMS device is LDEV 10. However, LDEV 10 may not correspond to an actual device, such as a tape drive, physically connected to the computer. If this is the case, then the STREAMS device is considered a "pseudo-device." Regardless of whether the device physically exists or not, it must be entered into the I/O configuration table as a legitimate logical device. It must be assigned the device class JOBTAPE.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be issued only from the console unless distributed to users with the ALLOW command.

To enable jobs and data streams on logical device number 10, enter:

STREAMS 10

To disable data streams, enter:

STREAMS OFF

When the spooler process is suspended, the message SP# ldev
SPOOLER SUSPENDED is displayed on the console. You may also determine the spooler's status by entering SHOWOUT SP;JOB=@. If suspended, any spool files listed will be READY for printing; none are ACTIVE, and a SHOWDEV of the spooled device indicates that the device is still spooled. Refer to the SHOWOUT command in this manual.

When suspending an ACTIVE spool file, first take the output device offline. This gives you time to enter the command and determine that the ACTIVE file is the one being printed. If you issue SUSPENDSPOOL without taking the device offline, that file might finish printing while you enter the command, and another file might start.

When your instruction has been sent to the spooler process, MPE/iX returns a colon prompt (:). The command is not executed, however, until the output device is returned online. Only then do you receive the SPOOLER SUSPENDED message.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be issued only from the console unless distributed to users with the ALLOW or ASSOCIATE command.

To suspend printing on logical device 6, enter:

SUSPENDSPOOL 6

To suspend printing on logical device 6 once the currently active spool file is completely printed, enter:

SUSPENDSPOOL 6;FINISH

None.

When the SWITCHLOG command is executed, MPE/iX displays the previous system log file number (xxx), the percentage of file space used (yy), and the current open log file (zzz), as shown in the following example:

 SYSTEM LOG FILE #xxx IS yy% FULL
 SYSTEM LOG FILE #zzz IS ON

If this command is issued and logging is not active the following message is displayed:

 NO LOGGING
 LOG FILE xxx IS yy% FULL

	NOTE: Do not create new log files with the BUILD command since MPE/iX creates them automatically. If you use the BUILD command to create a new log file and then attempt to switch the current log file to the file you created, user logging suspends in an error state and the following message is displayed: SYSTEM LOG FILE #xxx ENCOUNTERED ERROR #nnn LOGGING SUSPENDED.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. System supervisor (OP) capability is required to use this command.

To switch logging to a new log file, enter:

 SWITCHLOG

The SYSGEN command initiates the configurator/user interface. Once executing, SYSGEN can be used to create new system configurations, to modify existing ones, and to create installation tapes for any MPE/iX system.

System supervisor capability (OP) is required to view configuration data. System manager (SM) capability is required to make configuration changes and keep them or to create an installation tape.

To begin interaction with the MPE/iX configurator, the SYSGEN command is entered. During the interaction, system configurations can be created, modified, or used to create installation tapes.

The base for configuration changes or tape creation can be specified on the SYSGEN command with the base group. The group name to which the configuration is to be kept with a SYSGEN KEEP command can be specified on the SYSGEN command line with the newgroup parameter.

Input for the configurator interaction can be redirected from a file with the SYSGEN command inputfile parameter. Any output during the interaction can be redirected to a file with the SYSGEN command outputfile parameter. In addition, input and output can be redirected with file equations using the formal designators SYSGIN and SYSGOUT, respectively, prior to entering the SYSGEN command.

This command is available in a session and programmatically. It is not available from a job. Pressing Break suspends the execution of this command. Entering the RESUME command continues the execution.

The following four examples perform the same action. Each causes the group CONFIG.SYS to be used as the basis for configuration data, the group NEWCONF.SYS to be used for any KEEP command without a group specification, the file $STDIN to be used for input and the file $STDLIST to be used for output.

 SYSGEN CONFIG,NEWCONF,$STDIN,$STDLIST
 
 SYSGEN CONFIG,NEWCONF
 
 SYSGEN ,NEWCONF
 
 FILE SYSGIN=$STDIN
 
 FILE SYSGOUT=$STDLIST
 
 SYSGEN ,NEWCONF

This command transmits a message from the sender's job or session to one or more sessions currently running. The message appears on the receiving session list device. Messages sent with this command may include escape and control characters that invoke bells or inverse video. If a message is sent to a terminal that is currently interacting with a program, MPE/iX queues the message as high as possible among the current input/output requests but does not interrupt any read or write in progress. If the session or user designated to receive the message is not running, or if the job is spooled, the transmitting job/session receives a system message indicating this. MPE/iX blocks the TELL command if the receiving device is operating in the QUIET mode (refer to the SETMSG command) and informs the sender with:

 Snnn username.acctname NOT ACCEPTING MESSAGES

You cannot send TELL messages to a job or to yourself. If you try to send a message to a job, the following warning is issued:

 TARGET MUST BE INTERACTIVE, NO MESSAGE SENT.
 (CIWARN 1627).

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command.

To send a message to a user identified as BROWN, logged on under account A, running a session named BROWNSES telling him to use a particular file, enter:

 TELL BROWNSES,BROWN.A USE FILEX

To send a message asking all users logged on in account A to log off, enter:

 TELL @.A PLEASE LOG OFF

This command sends a message to the system console. The message text appears on the system console, preceded by the time it was transmitted and your job/session number. Like messages transmitted between users (TELL command), this message is printed as soon as possible without interrupting any console input/output currently in progress. The message can be sent to the system console, even if no session is logged on or if an active session is running in QUIET mode.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command.

To ask the system operator to mount a tape, enter:

 TELLOP PLS MOUNT MYTAPE,VERSION 1

Where qinfo is written in the following form:

	NOTE: Misuse of this command can significantly degrade system operating efficiency.

The system manager uses the TUNE command to change the characteristics of the circular scheduling subqueues to more efficiently manage the current processing load.

A process in the CS, DS, or ES scheduling subqueues typically begin execution at the base priority. When the process stops (for disk I/O, terminal I/O, preemption, etc.), the amount of CPU it has consumed is used to determine its new priority. If the process has completed a Dispatcher transaction, typically by issuing a terminal read, its priority is reset to the base, and the quantum value for that workgroup is recalculated. If the process has exceeded the quantum (filter) value since its priority was last reduced, the priority is decreased without exceeding the limit priority. If the boost property for the workgroup is oscillate, process priorities are reset to the base value once they decay to the limit.

The parameters min and max refer to the absolute bounds of the quantum, or a filter representing the average transaction time of processes in that subqueue. The quantum is recomputed after every user Dispatcher transaction is complete, and then compared against the CPU time of a process to determine whether the priority of the process should be decreased.

	NOTE: With Release 5.0 of MPE/iX, all three circular scheduling subqueues, CS, DS, and ES, have dynamically calculated quantums. By default, the DS and ES subqueues have their bounds set to the same value.

If the values specified for max are too large, system response may become erratic. If they are too small, excessive memory management may occur due to frequent process swapping. Either case degrades system performance. The values for min and max may range from 1 to 32,767. The recommended settings are listed in the table below.

The timeslice value determines how long a process in a given scheduling subqueue will be allowed to hold the CPU. This value is different than the quantum, which determines how rapidly process priorities decay. The timeslice does interrupt the process if the process is interruptable. The timeslice is a multiple of 100 milliseconds and has a minimum value of 100 milliseconds.

The following default settings are established when the system is booted from the system disk (a START RECOVERY or START NORECOVERY), unless the user has customized a TUNE configuration.

 START RECOVERY or START NORECOVERY
 
 CQ base: 152  DQ base: 202  EQ base: 240
   limit: 200    limit: 238    limit: 253
      min:  1     min: 2000     min: 2000
     max: 2000   max: 2000      max: 2000
  boost: DECAY  boost: DECAY  boost: DECAY
    tslice: 200  tslice: 200     tslice: 200

	NOTE: The MPE/iX Scheduler now supports the workgroup concept. However, backward compatibility is maintained through five default workgroups created by the system. The scheduling characteristics of the CS_Default, DS_Default, and ES_Default workgroups mimic those of the CS, DS, and ES scheduling subqueues. In fact, changing the scheduling characteristics of the CS, DS, and ES scheduling subqueues, via the TUNE command, is equivalent to changing the characteristics of the corresponding default workgroup through ALTWG. Please refer to the NEWWG and ALTWG commands for more detail. Workload Manager users should use ALTWG rather than TUNE since TUNE does not modify user-defined workgroups. If you aren't using Workload Manager, and you want to change one of the system-defined workgroups, you may wish to use ALTWG because it only examines member processes of a specific workgroup and not all processes on the system.

The TUNE command may be issued from a session, job, program or in BREAK. Pressing Break has no effect on this command. TUNE requires System Supervisor (OP) or System Manager (SM) capability.

To set the CS subqueue's base to 152, limit to 200, and max quantum (filter) to 300; and the DS subqueue's base to 202, limit to 238, min and max quantum (filter) to 1000, and cause oscillation boosting, enter:

 TUNE CQ=152,200,300,300;DQ=202,238,1000,1000,OSCILLATE

To set the CS subqueue to oscillation with a 300 millisecond timeslice and the DS subqueue's base to 180, limit to 238, boost property to decay, and timeslice to 1500, enter:

 TUNE CQ=,,,,OSCILLATE,300;DQ=180,238,,,DECAY,1500

This command makes available to users a device previously taken offline with the DOWN command. Ownership of the device is not affected by the UP command. If a device is owned by the system at the time it is downed, the system retains ownership even after the UP command is executed.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be issued only from the console unless distributed to users with the ALLOW or ASSOCIATE command.

To allow logical device number 10 to function again, enter:

 UP 10
 SHOWDEV 10
 LDEV AVAIL OWNERSHIP VOLID ASSOCIATION
 
 10 A AVAIL

If the movable volume facility is enabled when you issue a VMOUNT
OFF command, users having reserved volume sets are unaffected; the command is satisfied when the last access is complete.

The MPE/iX naming convention for volume sets differs from that of MPE V/E for private volumes. Refer to the MOUNT, DISMOUNT, VSRESERVE, and VSRELEASE commands in this chapter.

Once the movable volume facility has been enabled, use the VSUSER command to determine which users have which volume sets reserved. Refer to the VSUSER command in this chapter.

The movable volume facility is enabled immediately following a system startup. (The setting is equivalent to VMOUNT ON,AUTO.) However, you still receive console messages concerning volume set requests.

The operator has the greatest interactive control over the use of volume sets by using VMOUNT ON;ALL. The command that least interrupts the operator when users are accessing volume sets is VMOUNT ON,AUTO.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be issued only from the console unless distributed to users with the ALLOW command.

To disable the movable volume facility so that no messages are sent to the console when users attempt to reserve volume sets (the default condition) enter:

 VMOUNT OFF

To disable the movable volume facility and still receive messages on the console when users attempt to reserve volume sets, enter:

 VMOUNT OFF;ALL

This command notifies the system to close the volume set and take it offline. This is done when all users have ceased using files on the volume set, and when any program file that has been allocated on the volume set has been deallocated (via the DEALLOCATE command). Once the VSCLOSE command is issued for a volume set, individual users can no longer issue VSRESERVE or MOUNT commands for the volume set.

Specifying the NOW parameter permits the operator to take the volume set offline immediately, unless a VSRESERVESYS or an LMOUNT command has been issued, or unless a program file has been allocated on the volume set.

This command restricts access to the volume set. Jobs or sessions are granted access to the volume set only if they have at least one open file on the volume set or if they have already issued an explicit VSRESERVE or a MOUNT command for the volume set.

The MPE/iX naming convention for volume sets differs from that of MPE V/E for private volumes.

In MPE V/E, the name A.B.C indicates that B is the name of a group and that C is the name of an account. MPE/iX accepts that name, but no interpretation is made as to the referencing of B and C. Instead, MPE/iX treats A.B.C as a single, long string name. It is the flexibility of the MPE/iX naming convention that makes it possible for MPE/iX to work with a volume set designated A.B.C.

MPE/iX volume set names may consist of any combination of alphanumeric characters, including the underbar (_) and the period (.). The name must begin with an alphabetic character and must consist of no more than 32 characters.

A volume set called MY_OWN_PERSONAL_VOLUME_SET is acceptable in MPE/iX, and so is MY.OWN.PERSONAL.VOLUME.SET; similarly, A.B.C is acceptable. If a volume set is named according to the MPE V/E naming convention (A.B.C), you must use an unambiguous reference when using the MPE/iX volume set commands, such as:

 Vcommand A.B.C

Entering Vcommand A fails to access the volume set. You cannot specify the first part of the volume set name alone and expect the group and account to default.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. This command may be issued only from the system console unless distributed to other users with the ALLOW command.

To close the volume set ACCOUNTING_PAYROLL, enter:

 VSCLOSE ACCOUNTING_PAYROLL

However, if a VSRESERVESYS command has been issued for ACCOUNTING_PAYROLL, then a message is displayed on the console. In order to close this volume set and take it offline, the operator has to issue these commands:

 VSRELEASESYS ACCOUNTING_PAYROLL
 VSCLOSE ACCOUNTING_PAYROLL

This command notifies the system to open the specified volume set. Because bringing a volume set online opens the set by default, this command is needed only for a volume set for which a VSCLOSE command has been issued.

The MPE/iX naming convention for volume sets differs from that of MPE V/E for private volumes. In MPE V/E, the name A.B.C indicates that B is the name of a group and that C is the name of an account. MPE/iX accepts that name, but no interpretation is made as to the referencing of B and C. Instead, MPE/iX treats A.B.C as a single, long string name. It is the flexibility of the MPE/iX naming convention that makes it possible for MPE/iX to work with a volume set designated A.B.C.

MPE/iX volume set names may consist of any combination of alphanumeric characters, including the underbar (_) and the period (.). The name must begin with an alphabetic character and consist of no more than 32 characters.

A volume set called MY_OWN_PERSONAL_VOLUME_SET is acceptable in MPE/iX, and so is MY.OWN.PERSONAL.VOLUME.SET; similarly, A.B.C is acceptable.

If a volume set is named according to the MPE V/E naming convention (A.B.C), you must use an unambiguous reference when using the MPE/iX volume set commands, such as:

 Vcommand A.B.C

Entering Vcommand A fails to access the volume set. You cannot specify the first part of the volume set name alone and expect the group and account to default.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. This command may be issued only from the system console unless distributed to other users with the ALLOW command.

To open the volume set ACCOUNTING_PAYROLL, enter:

 VSOPEN ACCOUNTING_PAYROLL

This command releases a volume set when it is no longer in use and negates a previous reservation of a volume set.

The MPE/iX naming convention for volume sets differs from that of MPE V/E for private volumes.

In MPE V/E, the name A.B.C indicates that B is the name of a group and that C is the name of an account. MPE/iX accepts that name, but no interpretation is made as to the referencing of B and C. Instead, MPE/iX treats A.B.C as a single, long string name. It is the flexibility of the MPE/iX naming convention that makes it possible for MPE/iX to work with a volume set designated A.B.C.

MPE/iX volume set names may consist of any combination of alphanumeric characters, including the underbar (_) and the period (.). The name must begin with an alphabetic character and consist of no more than 32 characters.

A volume set called MY_OWN_PERSONAL_VOLUME_SET is acceptable in MPE/iX, and so is MY.OWN.PERSONAL.VOLUME.SET; similarly, A.B.C is acceptable.

If a volume set is named according to the MPE V/E naming convention (A.B.C), you must use an unambiguous reference when using the MPE/iX volume set commands, such as:

 Vcommand A.B.C

Entering: Vcommand A fails to access the volume set. You cannot specify the first part of the volume set name alone and expect the group and account to default.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. Use volumes (UV) or create volumes (CV) capability is required to use this command.

To request that volume set ACCOUNTING_PAYROLL be released, enter:

 VSRELEASE ACCOUNTING_PAYROLL

This command is used to negate a previously issued VSRESERVESYS command for the specified volume set. It informs the system that the volume set is no longer reserved system-wide.

This command does not prohibit individual VSRESERVE (MOUNT) or VSRELEASE (DISMOUNT) commands issued for the specific volume set by individual users.

The MPE/iX naming convention for volume sets differs from that of MPE V/E for private volumes. Refer to the MOUNT, DISMOUNT, VSRESERVE, and VSRELEASE commands in this chapter.

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. This command may be issued only from the system console unless distributed to other users with the ALLOW command.

To request that volume set ACCOUNTING_PAYROLL be released for all users on the system, enter:

 VSRELEASESYS ACCOUNTING_PAYROLL