Controlling system operations (CCAIN)

Overview

Commands that control system operations are entered into the CCAIN input stream after the user environment is defined. System control commands are executed immediately. No compilation is required.

This page presents a summary of system control commands that can be issued by the system manager, User 0, operator, and system administrator classes, followed by discussions on using some of these commands to:

• Terminate and monitor an Online system
• Monitor internal Model 204 special functions (pseudo subtasks)
• Control processing in response to job return codes
• Control the priority class of individual users

System control commands

The following table describes system control commands.

System control commands

Command	Purpose/comments	Issued by
*DEVICE	Enables BATCH2 applications to change the values used for OUTMRL and OUTLPP parameters.	BATCH2 jobs
*SLEEP	Suspends input processing for one user for a specific amount of time in Online, batch, and CMS single-user environments. The maximum time is 86400 seconds. *SLEEP can be issued by a user with User 0, system manager, or system administrator privileges. When using IFAM4, the *SLEEP specification must be longer than the application program needs to finish. If *SLEEP times out before completion of the program, IFAM4 ends and file damage can occur.	System administrator
*SNAP	Generates a formatted dump for debugging purposes that shows system control blocks, user control blocks, and disk buffers.	System administrator, Operator
ALLOCATE	Dynamically allocates data sets under z/OS or CMS.	System administrator
AUTHCTL	Displays information about the Model 204 external security interface in use (RACF, ACF2, Top Secret, or none).	System manager
BROADCAST	Adds, changes, or removes the system LOGIN message. If the operator specifies URGENT, the message is displayed almost immediately. Otherwise, it is displayed the next time the user is at command level.	System administrator, Operator
BUMP	Logs out a particular Model 204 user, all current users, all users logged in with a particular user ID, or all users who have opened a particular file. The BUMP command returns the message: M204.1124: nnnnn USERS(s) BUMPED	System administrator, Operator
BUMPSNAP	Logs out a particular user or a set of users and takes a CCASNAP for the user or users being Bumped. The following message is written to CCAAUDIT/CCAJLOG and is printed at the top of each page of CCASNAP: MSIR.0661: Snap taken, user bumped by BUMPSNAP command Available in Model 204 as of version 7.5 (previously only in Sirius Mods).	System administrator, Operator
CHKABORT	Aborts a pending request for a checkpoint.	System manager
COPY	Copies the contents of one stream or data set to another.	System administrator
CREATE (file)	Creates a Model 204 file.	Superuser
CREATE (perm file group)	Creates a Model 204 permanent file group.	System manager
CREATE (temp file group)	Creates a Model 204 temporary file group.	Any user
CREATEG	Creates the CCAGRP file in a batch run before the first permanent group is created. The User 0 stream must contain a login command with system manager privileges. CREATEG cannot be issued from a procedure.	System manager
DEFINE	Specifies or defines the characteristics of a data set, printer, process, sequential I/O stream, permanent group, field, or punched output. System manager privileges are required for DEFINE STREAM. Any user can use DEFINE FIELD. All other forms of DEFINE require system administrator privileges. DEFINE DATASET can precede User 0's parameter line in the CCAIN input stream. It is required when using the RESTART facility.	Various (see Purpose/comments column)
DELETE	Deletes a procedure or a field.	Any user
DELETE (perm file group)	Deletes a Model 204 permanent file group.	System manager
DELETE (temp file group)	Deletes a Model 204 temporary file group.	Any user
DISPLAY EW	Displays early warnings that have been applied to the Model 204 ONLINE module. Valid in pre-7.5 versions only. See DISPLAY ZAPS.	System administrator
DISPLAY ZAPS	Displays the numbers of the zaps that have been applied to Model 204. Available as of version 7.5.	Any user
DUMPG	Copies the CCAGRP data set to a sequential data set on magnetic tape or on a direct access device. DUMPG is used in periodic backups and in conjunction with RESTOREG when recovering from a system failure if the Checkpoint and Roll Forward facilities are not used. Never issue an OPEN command for CCAGRP before issuing DUMPG. System manager privileges are required to issue DUMPG.	System manager
ENQCTL	Examines or modifies the status of a list of jobs contained in each file (enqueuing list) that have control of the file. Indiscriminate use of ENQCTL can affect the integrity of a shared DASD by removing list entries for active systems or jobs.	System administrator or operator
EOD	Specifies end-of-day and requests that all users log out. Only a user with system manager privileges can log in after all users are logged out. EOD cannot be issued from a procedure. (See ONLINE termination.)	System manager
EOJ	Specifies end-of-job and initiates Model 204 termination. Active users are forced off. File integrity might be damaged. EOJ normally appears at the end of User 0's input stream. Omission causes a user restart and sets the job step return code to 6. If the login feature is used, an Online user with system manager privileges can issue the EOJ command from a terminal.	System manager
FREE	Releases a data set and its set of attributes (template) that were previously allocated by the ALLOCATE command or in the JCL used to start up Model 204. A data set cannot be freed if it is currently in use or if it is a Model 204 system data set. System administrator privileges are required to issue the FREE command unless the ALOCPRIV parameter allows the privilege to other users.	System administrator
HALT	Suspends the reading of User 0's input and provides a means of communication between the console operator and ONLINE. HALT affects only User 0. Online users continue to be served. Note that Model 204 automatically terminates when all of User 0's input is read. HALT writes a message to the operator's console and causes User 0 to wait for a reply from the operator. Replies can be those specified in the HALT command, an operator command (see ONLINE termination), or a reiteration of the message. WAITING is the default message, if no message is specified in the HALT command.	User 0
IFAMCLOSE	Closes the Host language IFAM2 channel. Before IFAMCLOSE is accepted, IFAM2 must be completely drained by issuing the IFAMDRAIN command. IFAMCLOSE is useful to free any IFAM2 programs that are waiting as the result of an IFAMDRAIN command and to allow the channel name to be switched.	System manager
IFAMDRAIN	Halts a Host Language IFAM2 thread. All idle threads are immediately halted. Any threads in use are started, if they were halted, and allowed to process until a IFDTHRD or IFFNSH call is issued.	System manager
IFAMFORCE	Forcibly terminates a Host Language IFAM2 thread. IFAMFORCE is useful in obtaining a clean checkpoint and to resolve thread allocation deadlocks (two programs each reserve one thread and are then unable to obtain a second). Forcing threads that are updating files can render a file logically inconsistent.	System manager
IFAMHALT	Temporarily halts a Host Language IFAM2 thread. IFAMHALT is useful to improve User Language performance and to preserve an IFAM2 state for examination. Programs can time-out (ABEND 522) if they are halted too long. IFAMSTART restarts threads halted by IFAMHALT.	System manager
IFAMOPEN	Opens a specified Host Language IFAM2 channel. IFAMOPEN used in conjunction with IFAMCLOSE is useful to change the IFAM2 CRAM channel name.	System manager
IFAMSTART	Restarts the Host Language IFAM2 facility or a specified IFAM2 thread.	System manager
IFAMSTAT	Displays the status of a Host Language IFAM2 thread.	System manager
LOGCTL (file) LOGCTL (group) LOGCTL (user ID)	Modifies file, group, or user ID entries in the password table. Password, privileges, user class, field security levels, and terminal list can be modified.	System manager
LOGFILE	Lists file entries in the password table, including privileges but not passwords. System manager privileges are required to issue LOGFILE.	System manager
LOGGRP	Lists group entries in the password table, including privileges but not passwords. System manager privileges are required for issuing LOGGRP.	System manager
LOGKEY	Specifies a password table key.	System manager
LOGLST	Lists user ID entries in the password table, including privileges but not passwords.	System manager
MONITOR	Checks the operations of an Online system and provides statistics for SNA Communications Server (formerly VTAM) interfaces and application subsystems. (See Statistics and monitoring of pseudo subtasks.)	System administrator, System manager, User 0
MONITOR (operator)	Requests the utility to return information about what is currently happening in Model 204. Available in Model 204 as of version 7.5 (previously only in Sirius Mods).	Operator
MSG	Sends messages between users and between users and the operator.	Operator, Any user (depends on message type)
MSGCTL	Specifies the actions Model 204 takes when issuing an error or informational message. MSGCTL is useful to write error messages or classes of error messages to the audit trail or journal data sets. (See Job step return codes.)	System administrator
OFFLOAD	Manually starts an offload at any time during system operations. OFFLOAD is available only to RING output streams and is useful when AUTOOFFLOAD of DEFINE STREAM is set to a high value and system shutdown may occur before offloading starts. System manager or operator privileges are required to issue OFFLOAD.	System manager, Operator
PRIORITY	Assigns a user to a priority class or displays information about priority assignments. (See Priority scheduling.)	System manager, System administrator, Operator
REACTIVATE	Reactivates all or specified terminals that have encountered severe I/O errors and have been taken off the polling list. REACTIVATE restarts the user and requires a login to continue. REACTIVATE applies to IODEV=15, IODEV=25, IODEV=33, and IODEV=35.	System administrator, Operator
REGENERATE	Restores Model 204 files when storage integrity is lost because of a hard system error, such as a disk head crash. REGENERATE can be used only within a single-user (batch) run.	User 0
REGENERATE ONEPASS	Restores Model 204 files when storage integrity is lost because of a hard system error, such as a disk head crash. REGENERATE ONEPASS processing runs only Pass One through the CCAGEN data set. REGENERATE ONEPASS is significantly faster than REGENERATE but cannot be used across recovery runs or discontinuities (such as file create or delete).	User 0
RESTART	Restarts Model 204 and, optionally, recovers files after a system failure. RESTART is used in conjunction with the Checkpoint, Roll Back, and Roll Forward facilities. If system recovery facilities are used, the Online job must contain a RESTART command in CCAIN.	User 0
RESTART (operator)	Requests that the Restart utility issue the equivalent of a user abend in Model 204 for the indicated user or task. Available in Model 204 as of version 7.5 (previously only in Sirius Mods).	Operator
RESTOREG	Restores the CCAGRP file from a sequential data set. RESTOREG is used in conjunction with DUMPG when recovering from a system failure where Checkpoint and Roll Forward facilities are not used.	System manager
RESTOREG and RESTOREGX	At Fast/Backup authorized sites, the RESTOREG command invokes Fast/Backup rather than the standard Model 204 restore processing. Available in Model 204 as of version 7.5 (previously only in Sirius Mods).	System administrator
START (file or group)	Makes a file or group available to users.	System administrator
START (link, processgroup, or CNOS sessiongroup)	Reactivates a link, processgroup, or CNOS sessiongroup	System manager, System administrator, User 0
START (application subsystem)	Activates an application subsystem	Defined in the subsystem definition
STATUS (files)	Lists recovery information about one or more files. Any user can issue the STATUS command, but only the system manager or the system administrator can list information about all files.	System manager, System administrator, Any user
STATUS (users)	Lists the user IDs of all users who are currently logged into Model 204. When issued by the operator, STATUS has the effect of LOGWHO by listing all current users, user IDs, terminal IDs (including access method), open files, dead terminal lines, and threads that can be reactivated.	Operator
STATUS (Restart or SirTune)	Requests the current status of the Restart utility or SirTune. Available in Model 204 as of version 7.5 (previously only in Sirius Mods).	Operator
STOP (file or group)	Makes a file or permanent group unavailable to users.	System administrator
STOP (remote or session group)	Stops a Horizon CNOS remote or session group.	System manager, System administrator, User 0
STOP (link or processgroup)	Stops a Horizon or Model 204 SQL link or process group.	System manager, system administrator, User 0
STOP (application subsystem)	Stops an application subsystem.	Defined in the subsystem definition
STOP (SirTune)	Requests that SirTune stop collecting both sampling and compilation data and close the sample data set. Available in Model 204 as of version 7.5 (previously only in Sirius Mods).	Operator
TMASKUPDATE	Updates all the password table terminal lists at once.	System manager
VIEW	Displays current settings of Model 204 parameters or sets of parameters. System manager or system administrator privileges are required to issue VIEW ERRORS. All other options can be viewed by any user.	System manager, System administrator, Any user
VTAMOFF	Closes the SNA Communications Server (formerly VTAM) terminal interface. For IBM z/OS and z/VM systems only.	System manager, Operator
VTAMON	Restarts the SNA Communications Server (formerly VTAM) terminal interface, under z/VM only.	System manager, Operator
WARN	Sends a message immediately to any active user.	System manager, Operator

ONLINE termination

Caution: To avoid damaging the integrity of a Model 204 file, do not cancel the Model 204 program with the CANCEL command from the operator's console once the Model 204 program has begun to run.

Manual termination

The following steps, initiated by a user with system manager privileges, terminate ONLINE safely, if the login feature is used.

To manually terminate ONLINE:

1. Issue the EOD command without arguments or with the ON argument to notify users that ONLINE is terminating.

   The following message is displayed to users when they are at command level:

   *** M204.1028: PLEASE LOGOUT AND HANG UP

   If User 0's input stream does not contain a login command, the following message is displayed on the operator's console when the last active user logs out:

   *** M204.0354: ALL USERS ARE LOGGED OUT

   After EOD is issued, only a user with system manager privileges is allowed to log in to Model 204. EOD or EOD ON can be canceled by issuing EOD OFF.

2. Issue the LOGWHO command to verify that all users have closed their files and logged off.

   A list of active user IDs, their terminal IDs (indicating whether SNA Communications Server or IUCV access methods are being used), and currently open files is displayed.

3. Issue the EOJ command to terminate the job.

   EOJ must be confirmed before it is executed by a Y response to the query issued by Model 204:

   M204.1076: DO YOU REALLY WANT TO END THE RUN?

   The default response is Y if the system manager's PROMPT parameter includes the 16 option.

Time-out termination

The following commands in User 0's input causes automatic system termination at the specific time:

*SLEEP number-of-seconds-ONLINE-is-available (User 0 suspended) EOD *SLEEP number-of-seconds-for-user-logoff EOJ

Operator control

Using the following commands in User 0's input require operator interaction:

HALT n, message1, m, reply1 EOD HALT n, message2, m, reply2 EOJ

Where:

• n is the number of characters in the message.
• message1 is the text of the first message.
• m is the number of character in the reply.
• reply1 is the text of the first response.

The system responds:

xx jobname ** 000 ** message1

Where:

• xx is a message number assigned by the system.
• jobname is the name of the activity.

Take the following steps:

1. The operator must make note of the request number (xx) when ONLINE first comes up and message1 appears on the console.
2. The operator replies to message1 with reply1 when it is time to terminate ONLINE.

   This causes processing of the EOD command and notifies the Online users.

3. The operator replies with reply2 when message2 is received and is displayed:

   ALL USERS ARE LOGGED OUT.

   This causes the EOJ command to terminate ONLINE without confirmation by requesting a checkpoint (if checkpoint logging is enabled) before termination processing starts. After checkpoint occurs or times out, termination proceeds.

The following sections explain replies to the HALT messages and EOD processing.

HALT processing

Replies to the HALT messages issued by User 0 can be:

• Responses coded in the HALT command
• Message itself, if no reply is specified
• WAITING (default message), if no message is specified
• Special operator commands, which result in execution of the command and redisplay of the message:

  BROADCAST BUMP MSG OFFLOAD PRIORITY REACTIVATE STATUS VTAMOFF VTAMON WARN *SNAP

EOD processing

The following considerations apply to EOD processing:

• EOD processing is impacted by the OFFLOAD process.

  The CLOSE=AUTO option indicates that the data accumulated in ring members since the last completed offload process must be offloaded during close processing. Unless EOD processing has begun and the CLOSE=AUTO parameter has been specified, the offload stream is closed whenever there are no further ring members to offload. The offload stream in this instance is left open so that the contents of all remaining full members can be offloaded.

• If the offload stream is open when EOD processing begins, it remains open even if the offload process enters an idle state before the stream is closed. This allows the final offload to continue writing to the same output data set.

Console operator communications with Model 204 (z/VSE)

The Model 204 HALT command allows the operator to communicate with the Model 204 ONLINE configuration. The HALT message is displayed on the operator's console when the system is initialized. A response from the operator is not required.

To communicate with Model 204, follow these steps:

1. Issue the z/VSE MSG Attention Routine command to signal an ONLINE configuration:

   MSG pp

   where pp is the SYSLOG ID (such as, BG or F3) of the partition in which ONLINE is executing

2. The response to the MSG command is a message from ONLINE containing:
   • SYSLOG ID
   • z/VSE reply ID number
   • z/VSE job name of the ONLINE job stream
   • User number (always 0)
   • HALT message from the HALT command
3. The operating system issues a prompting message containing the SYSLOG ID and the z/VSE reply ID number.
4. You can issue any of the special operator commands by keying the reply ID number, at least one blank, and the command.

In the following sample dialog, the operator requests system status information from the ONLINE configuration running in F2.

The operator keys:

MSG F2

The Online responds:

F2 - 002 ONLINE *** 0 *** MODEL 204 IS AVAILABLE F2 - 002

The operator keys:

2 status

The Online responds:

F2 - 002 system status information ...

Pseudo subtasks

A pseudo subtask (PST) is an internal Model 204 process that performs special functions outside of normal user processing, such as checkpointing and I/O operation control. Asynchronous external events such as expiration of the checkpoint timer tend to trigger a pseudo subtask.

There are no restrictions on which internal Model 204 functions and structures a pseudo subtask can use. A user with system manager privileges specifies the pseudo subtasks processed and the resources used during a Model 204 run.

Pseudo subtasks have their own internal Model 204 structures, pushdown lists, and copies of certain server areas to enable them to take complete advantage of Model 204 facilities. Each pseudo subtask requires approximately 1500 bytes of additional storage.

Statistics and monitoring of pseudo subtasks

Pseudo subtask statistics are gathered on CPU time and elapsed connect time. The information is viewable through the MONITOR command (USERS option), partial and final statistics displays.

Each pseudo subtask has a user ID, account, and user number for external viewing. The user IDs are listed in the "Internal pseudo subtasks" table:

Internal pseudo subtasks

Task name	Handles...
CHKPAWW	Wait for preimage writes (31-bit only)
CHKPPST	Checkpointing
CHKPTIMO	Time limit for quiescing users
CHKPTIMR	Checkpoint every CPTIME minutes
CMSVTAM	Asynchronous SNA Communications Server exits for CMS/SNA Communications Server; handles loss of IUCV connection to VT204
MQDELDTP	MQ subtasks and associated resources that need to be detached and released when the current MQ operation has finished.
OFFLOAD	Offload of ring streams
PRT-PERF	Logging of performance data
PRT-PART	Printing of partial statistics
VTNTDIED	Notification of SNA Communications Server crashing
VTNTERRS	SNA Communications Server LOGON errors for NTO devices
VTNTREAD	Input from SNA Communications Server NTO devices
VT62ACBS	Special services for Horizon links
VT62CLPS	CLOSE LINK FORCE processing
VT62RAPS	Input from Horizon partner processes
VT75DIED	Notification of SNA Communications Server crashing
VT75ERRS	SNA Communications Server LOGON errors for 3270 devices
VT75READ	Input from SNA Communications Server 3270 devices

Messages

The pseudo subtask feature issues messages when:

• Pseudo subtask starts processing
• Pseudo subtask completes processing
• Specified number of terminals (NOTERM) in an interface group is too large. The number displayed indicates the actual number of threads available. When this occurs, the interface is initialized and awakened, not left in a hanging state.

Messages are issued for SNA Communications Server NTO and SNA Communications Server 3270.

Job step return codes

Job step return codes provide the operating system with information that determines whether a step is executed or aborted. The handling of individual job step return codes is installation specific. Many installations choose to ignore all return codes in the range 0-95 for ONLINE runs.

The job step return code is available from z/OS and z/VM operating systems and in the following audit trail AD line message under all operating systems:

*** M204.1075: TERMINATION COMPLETE. RETURN CODE=nnn

Using MSGCTL command with SYSOPT parameter to produce an abend

Using the MSGCTL command you can set the precise return code when you want the error to return. You can set the error to any non-zero return code. If the SYSOPT parameter is set to include 40, any non-zero return code from a Model 204 message will generate an abend without a dump at termination.

The "Job step return codes" table summarizes the most common return codes issued for Model 204 steps:

Job step return codes

Return code	Meaning
0	Successful completion of the job step
6	User restarted
8	Warning
16	Error during User Language request compilation
20	Error in file operation
24	Error during FLOD compilation
32	Maximum number of errors exceeded
40	Error during User Language request evaluation
44	In a batch run, an uninitialized or physically inconsistent file is opened. Expect a return code of 44 in some circumstances, such as when a CREATE and INITIALIZE is done. OPEN after CREATE (and before INITIALIZE) produces a return code of 44 indicating that the file is not yet initialized.
48	Table A, B, C, D, E or X is full
52	Error in recovery or restart operation
56	Serious error during User Language request evaluation
60	Scratch file full or run canceled with dump
64	Error during FLOD evaluation
72	Error due to Table D inconsistency (message 0447)
80	Error during system initialization
88	Error during system termination
96	Serious error in Model 204; a SNAP is written to the CCASNAP data set
100	SNAP production failed
104	I/O error on CHKPOINT or CCAJRNL file

Conditional job control

Under z/OS and z/VSE, you can code conditional job control statements based on job step return codes by coding the operating system COND parameter. Please consult IBM documentation regarding the COND parameter for details.

Priority scheduling

The system manager uses the PRIORITY command and the PRIORITY parameter on a user IODEV line in CCAIN to allocate Model 204 resources to users based upon their relative service requirements.

Users can be in one of three priority classes: LOW, STANDARD, or HIGH. In general, HIGH priority users receive service sooner than STANDARD priority users, and STANDARD priority users receive service sooner than LOW priority users.

You can also specify ranges for the PRIORITY command.

PRIORITY command and PRIORITY parameter syntax

LOW, STANDARD, and HIGH use the following default ranges:

Priority	Cur	Min-Max
LOW	016	001-047
STANDARD	048	032-079
HIGH	096	080-127

PRIORITY command syntax

Use this syntax when issuing the PRIORITY command:

PRIORITY [userno [,LOW|STANDARD|HIGH]]

or

PRIORITY [userno [,cur|,(cur,min,max)] [,keyword=value]]

or

PRIORITY userno, CANCEL

PRIORITY parameter syntax for IODEV threads

Use this syntax when specifying a priority on an IODEV thread defined in CCAIN:

PRIORITY=[LOW | STANDARD | HIGH]

or

PRIORITY=(cur[,min,max])[,keyword=value]

Where:

• userno specifies the user number to modify or display. If no other parameters are specified, the specified user's current settings are displayed.
• cur specifies a new current priority, 0-253, for the specified user.

  A user's current priority is not required to be within his range. However, as the user ages, the current value will rise or fall until it falls within the given range.

• min specifies a new minimum priority, 1-253, for the specified user.
• max specifies a new maximum priority, 1-253, for the specified user.
• keyword=value changes the value assigned to one of the keywords listed in the table below; for example IOSLICE=60. To reset values to system defaults, specify a null value (as shown below in Examples.

  The following table lists the recognized command and parameter keywords. A command keyword is used on the PRIORITY command, and a parameter keyword is used when setting priority on an IODEV line in CCAIN.

  Command keyword	Parameter keyword	Specifies
  IOSLICE	UIOSLIC	CPU milliseconds allowed while user is I/O bound.
  CPUSLICE	UCPUSLIC	CPU milliseconds allowed while user is CPU bound.
  SLCWAIT	USLCWAIT	Sleep time in milliseconds, invoked each time a user reaches minimum priority level.
  SLCMAX	USLCMAX	Number of Stop-Loop-Checks (SLCs) before CSLICE invoked (max=65535). Reducing this number increases the accuracy of the slice interval, However, CPU overhead increases. Note: SLC is an internal Model 204 routine that prevents infinite user loops.

• CANCEL ends the user's current request. The error procedure is invoked if the user is in a subsystem.

Viewing changes in priority

When you issue the PRIORITY command to change a user's priority, the values existing prior to the command are shown. To verify the new values, issue the PRIORITY command again, as shown in the following example.

PRIORITY 9,33 USER USERID P CUR,MIN-MAX SLICE IOSLICE CPUSLIC MAX SLCWAIT SERV CPU 9 USERXX H 095,080-127 0.000I 0.030 0.010 50 0.00 1 0.000 PRIORITY 9 USER USERID P CUR,MIN-MAX SLICE IOSLICE CPUSLIC MAX SLCWAIT SERV CPU 9 USERXX H 033,080-127 0.000I 0.030 0.010 50 0.00 1 0.000

Duration of PRIORITY assignments

Once a priority has been assigned, that priority remains in effect until it is changed by another PRIORITY command or until you log out of Model 204. On logoff or restart, all priority parameters are reset to either their user default values (set on IODEV) or their system values.

Setting PRIORITY to 0

If a user priority is set to zero, that user will no longer be dispatched. Instead the user remains logged in, but is suspended during evaluation. The suspension can occur at command level or at the bottom of a FOR loop. That user must be reset to a non-zero priority to continue. (Exception: If the user is updating or holds critical resources, they will be allowed to run to COMMIT or END of request before being suspended.)

Examples

The following priority command changes the current priority of User 38 to 100, minimum to 80 and maximum to 120. The value of IOSLICE, for this user only, is also changed to 60.

PRIORITY 38,(100,80,120),IOSLICE=60

To reset argument values back to system defaults, specify a null value. For example, to change User 38 back to the system default value for IOSLICE:

PRIORITY 38,,IOSLICE=,

The trailing comma is required and indicates the null value. The double commas after 38 indicate that current priority or priority range has been omitted.

Delaying work

When necessary, the system administrator can delay work to accommodate other, higher priority work. For example, if low importance BATCH2, HORIZON or other IODEV threads are running and work of higher importance must be run the low importance threads may be set to an extremely low and narrow priority range and SLCWAIT and SLCMAX values may be added.

Let's say you want to drastically increase the elapsed time a BATCH2 thread requires to run, essentially run it as a very low priority, background task. If the BATCH2 thread is user 59, the following PRIORITY command will allow that thread to run once every 2 seconds (SLCWAIT) for 100 milliseconds (IOSLICE). After 100 milliseconds or when the thread issues any kind of wait for an external event — disk I/O, READ SCREEN, server swap, record/resource locking conflict resolution, pause, and so on — the thread will wait for two seconds before being dispatched again:

PRIORITY 59,(5,5,5),IOSLICE=100,SLCMAX=1,SLCWAIT=2000

Users may also be suspended with the PRIORITY command. If you suspect a runaway application, but want to confirm before bumping the user, you could suspend that user by setting priority to zero:

PRIORITY 72,0

Note: Setting a user to low or zero priority, however, must be done with care. Record locks continue to be held for a LOW or zero priority user. Other users, who need to process those records, may be blocked.

PRIORITY command output

The output of the PRIORITY command includes a header line that indicates the meanings of the statistics in the user lines that follow. User and server numbers occupy up to five characters.

If PRIORITY is entered with no parameters, all users are displayed. You may abbreviate the PRIORITY command to PRI.

Note: The column below labeled MAX is SLCMAX.

PRIORITY USER USERID P CUR,MIN-MAX SLICE IOSLICE CPUSLIC MAX SLCWAIT SERV CPU 0 NO USERI S 253,032-079 0.000I 0.070 0.100 50 0.00 OUT 0.001 1 BECKETT S 061,032-079 0.000I 0.070 0.100 50 0.00 OUT 0.013 2 LESTER H 127,080-127 0.000I 0.070 0.100 50 0.00 5 0.170 3 MATSUZAK S 061,032-079 0.000I 0.070 0.100 50 0.00 OUT 0.012 4 PENNY H 104,080-127 0.000I 0.070 0.100 50 0.00 1 0.422 5 WAKEFIEL H 114,080-127 0.000I 0.070 0.100 50 0.00 3 0.105 6 VARITEK S 079,032-079 0.000I 0.070 0.100 50 0.00 OUT 0.063 7 YOUKILIS S 079,032-079 0.000I 0.070 0.100 50 0.00 OUT 0.069 8 PEDROIA S 079,032-079 0.000I 0.070 0.100 50 0.00 6 0.133 9 LOWELL S 072,032-079 0.000I 0.070 0.100 50 0.00 OUT 0.032 11 LUGO S 079,032-079 0.000I 0.070 0.100 50 0.00 2 0.112

The priority (P) column (third from the left in the previous priority display) can have the values listed in the following table:

Priority column	Specifies...
L	Low
S	Standard
H	High
*	User defined
Z	Sleeping (priority=zero);
?	Deferred priority change in progress, which will take effect when the user issues COMMIT command, BACKOUT command, or request processing ends.

The SLICE column displays either I for I/O bound or C for CPU bound.

Consider this scenario of user scheduling

For a user, who in this example is USER11, USERID=LUGO, PRIORITY can be set as follows:

PRIORITY 11,(20,16,40),SLCWAIT=2000,SLCMAX=2, X IOSLICE=30,CPUSLICE=10

USER11 will begin work with a priority of 20. Any users with STANDARD priority or higher will receive CPU cycles ahead of USER11. Once USER11 has received 30 milliseconds of CPU (the IOSLICE value at which the user is declared CPU-BOUND), USER11 will be declared CPU-BOUND for the next 10 milliseconds.

At selected times during the processing (loop, FIND, FOR, and so on), the Model 204, internal, Stop-Look-Check (SLC) routine will be called on behalf of USER11 to evaluate his time slice. Since SLCMAX=2, the first SLC will skip the check of the time slice. On the second call, the usage will be examined. If USER11 has exceeded 10 milliseconds (CPUSLICE), then USER11 will be time sliced (rescheduled), and a user with higher priority is allowed to run.

Each time USER11 is rescheduled and is found to be CPU-BOUND, their priority will be lowered by 2. So, after approximately 40 (30+10) milliseconds of CPU, USER11 now has a priority of 18. USER11 continues to run, and two SLC calls later, USER11 is again time sliced.

USER11 has now consumed approximately 50 (30+10+10) milliseconds of CPU and their priority is now 16. This is the bottom of his range, so the SLCWAIT parameter becomes active.

Since SLCWAIT=2000, USER11 is placed in a timed 2-second (2000 milliseconds) wait and will not be rescheduled for evaluation until this time has elapsed. If no other work is found for Model 204 to process, Model 204 will enter an operating system wait until USER11 or another user becomes eligible to be dispatched. In the meantime while Model 204 waits, the operating system may schedule other address spaces, virtual machines, or partitions.

CUSTOM=(9) setting

The CUSTOM=(9) setting suppresses all output from all forms of the PRIORITY command.

Scheduler performance parameters

Use the scheduler performance parameters, listed below in "Scheduler performance parameters," to tune the scheduler's performance characteristics. You can set these parameters on User 0's parameter line or reset them if you are a user with system manager privileges.

Use the VIEW CWAIT command to examine scheduler parameters.

Scheduler performance parameters

Parameter	Description
AGEINCR	Internal priority increment associated with aging promotion
AGEINTVL	Real-time interval in milliseconds a user must wait before being promoted by the aging feature
AGESCAN	Allowable real-time interval in milliseconds between scans of wait queues performed by the aging logic
AGESLICE	CPU time-slice increment associated with aging promotion
CFRWPCT	Specifies the percentage of servers, NSERVS, that can be occupied by non-swappable users waiting for exclusive access to a critical file resource (CFR).
CPUSLICE	CPU time-slice allotment for CPU-bound users
IOSLICE	CPU time-slice allotment for non-CPU-bound users
PRIOMAX	Maximum priority that aging promotion is allowed to produce
SIOSLICE	Server real-time-slice allotment in milliseconds for non-CPU-bound users
SLICEMAX	Maximum CPU time-slice in milliseconds that immunity aging can produce
SRVSLICE	Server real-time-slice allotment in milliseconds for CPU-bound users
UCPUSLIC	CPU time slice allotment for an individual user
UIOSLIC	I/O time slice allotment for individual user
USLCMAX	Maximum CPU time slice for an individual user
USLCWAIT	Sleep time at minimum slice priority
WAITSCAN	Real-time interval allowed to pass between wait queue checks

Dynamic dispatching

Dynamic dispatching is the internal process used by Model 204 to alter user priorities. Individual users within the same priority class are not necessarily treated equally, because internal priorities can temporarily modify the order of processing. Model 204 adjusts the internal priority of each user, subject to the limits imposed by the user's priority class, in order to maximize the total Model 204 throughput.

Dynamic dispatching rules

The dynamic dispatching rules used by Model 204 reward users who perform terminal I/O, especially input, and discourage users who consume a lot of CPU time without performing any terminal or disk I/O.

Just prior to processing a command, Model 204 sets a user's internal priority to the central value of the user's priority class (LOW = 16, STANDARD = 48, HIGH = 96). Increases are subject to the maximum internal priority implied by the user's priority class.

• Each terminal output raises the user's internal priority by 1.
• Each terminal input raises the user's internal priority by 2.

Each time a user consumes more than a preset amount of CPU time without performing any I/O (disk or terminal), the user is judged to be CPU-bound and the internal priority is decremented by two units, subject to the minimum internal priority implied by the user's priority class.

Each time a user, previously judged to be CPU-bound, voluntarily surrenders the CPU by performing disk or terminal I/O, the user's internal priority is incremented by one, subject to the maximum internal priority implied by the user's priority class.

Balancing CPU bound and I/O bound users

The CPUSLICE and IOSLICE parameters provide additional control over CPU bound users. The default values in milliseconds are:

• CPUSLICE=10
• IOSLICE=30

Each user receives a slice of CPU time whenever the user is dispatched, that is, given the CPU. The CPU time slice is initially set to IOSLICE milliseconds. As a user consumes CPU, the amount consumed is compared to the IOSLICE value.

• A user who relinquishes the CPU and goes into a wait state, by issuing a READ SCREEN statement or by performing database I/O to Table A, B, C, or D before consuming IOSLICE milliseconds of CPU, is considered I/O bound.
• If a user has not gone into a wait state within IOSLICE milliseconds, the user is considered CPU bound.

When a user becomes CPU bound, the user's priority is decremented by two points and the CPU time slice value is changed from IOSLICE to CPUSLICE milliseconds. Until the user voluntarily goes into a wait state, the amount of CPU time provided per time slice equals the CPUSLICE value.

This improves response time for I/O bound users by preventing CPU bound users from monopolizing the CPU.

Queue aging

Queue aging, which increases a user's priority when a wait for Model 204 resources (server areas, the CPU, disk buffers, and others) occurs, sets a maximum allowed service time for lower priority requests:

• As users are aged, they are assigned a time-slicing immunity value, which also increases with time, subject to specified limits.
• An aged user's priority is not decreased until the user has consumed an amount of CPU time equal to or greater than the user's current time-slice immunity.
• Once an aged user's priority reaches a level that allows selection for running, the aged priority is maintained until the user's time-slice immunity has been exhausted. At that point, the user's priority is returned to its pre-aging value and the time-slicing immunity is removed.

Although the application of aging defeats normal priority scheduling, its impact can be minimized through careful selection of aging parameters (default settings do not allow aging to take place). Proper aging parameter settings avoid interruptions that higher priority users might experience as lower priority users receive a greater level of service before returning to a lower priority.

User 0's priority

User 0 receives the highest possible priority of any Model 204 user when a HALT command is issued. The settings of the minimum, maximum, and current priorities are set to 128, which allows User 0 the highest possible dispatching priority of any Model 204 user.

Capturing abends

Asynchronous SVC dumps can be generated and written to SYS1.DUMP data sets on Model 204 abends. Model 204 continues as soon as the pages are copied to the DUMPSERV address space. All physical I/O is done from DUMPSERV, which frees the Online system sooner.

You can enable the asynchronous dump by specifying SNAPCTL=X'05', which is a separate setting that produces a complete region asynchronous dump. For a more detailed discussion of the SNAPCTL parameter, see SNAPCTL.

Attention: Familiarize yourself with the memory requirements of the asynchronous dump process to ensure that enough expanded and page space is available. Memory shortage can cause severe system degradation while an asynchronous dump is processing the DUMPSERV address space. If you use this setting and you have not properly configured the DUMPSERV memory requirements, you risk locking your z/OS system.

Note: If the dump is not taken, due to suppression by Dump Analysis Elimination (DAE) or a z/OS problem, the following IBM error message is written to the operator:

'DUMP FAILED - REASON XX'

The reason codes are listed in the SDUMPX macro in the z/OS Auth Assm Service Reference LLA-SDU. The number of the manual varies according to the release of z/OS.