PAUSE



PAUSE

     Allows the user to suspend current activity for a specified number
     of seconds, or until one or more jobs or sessions has reached a
     certain state.

SYNTAX


PAUSE [num_seconds]
[JOB= jobid]
[INTERVAL=interval_secs
[;EXIST | WAIT | NOTEXIST]

PARAMETERS


Before the parameters can be discussed a term must be defined. In the
text below the word "while_state" refers to the event that ends the
pause. Collectively EXIST, WAIT and NOTEXIST are referred to as the
"while_state" since PAUSE sleeps while the specified state is true.
That is, PAUSE continues while the job exists, or while the job is
waiting, or while the job does not exists.


num_seconds If num_seconds is specified without jobid PAUSE
sleeps for that many seconds, or until the process
issuing the pause is interrupted by the break signal

If jobid is also supplied then num_seconds has a
different meaning. In this case it indicates the
maximum duration for the PAUSE command, such that
PAUSE should continue while the selected jobs are in
their "while_state" or when "num_seconds" has
expired, whichever is SHORTEST. Thus, num_seconds
represents the maximum length of the pause. If
PAUSE completes but one or more jobs are still in
their "while state" a CI warning is reported. Note:
to pause while a job is in its "while_state" or
until num_seconds has expired, whichever is LONGEST,
one can execute the following two commands:

PAUSE x
PAUSE job=y ;z

If after X seconds job Y is still in state Z then
the second PAUSE continues while state Z applies. On
the other hand, if after X seconds job Y is not in
state Z then the pause is complete.

jobid jobid can be one of: [#]Jnnn, [#]Snnn,
[@J|S:][jobname,]user.acct, @, @J, @S. The "@J|S:"
modifier supports selecting only jobs or only
sessions that also match the "user.acct"
specification. Note if "jobname" is included then
the jobid must be quoted since the comma is a
treated as a delimiter.

If the JOB= parameter is specified PAUSE sleeps
while jobid is in its "while_state". jobid can be an
executing, waiting, scheduled job, or a session.
jobid can also name many jobs or sessions.
Wildcarding is supported, and a non-wildcarded
"[jname,]user.acct" can match several jobs or
sessions. The job name can be "," (empty) to match
all jobs or sessions without a job name. When more
than one job or session matches jobid PAUSE sleeps
while all matching jobs are in their "while_state".
If the job executing PAUSE matches jobid it will not
be selected.

interval_secs If interval_secs is specified PAUSE sleeps for this
many seconds between attempts to see if jobid is
still in its "while_state". Otherwise, PAUSE sleeps
a variable amount of seconds depending on the job
state and the number of previous times a particular
job has been polled. This default computed method
favors executing jobs that terminate quickly.

EXIST (default) means to pause while all jobs and sessions
matching "jobid" exist. These jobs can be scheduled,
waiting, executing, etc., but as long as the SHOWJOB
command displays one or more of the jobs defined by
jobid, the pause continues.

WAIT means to pause while the selected job or jobs are
waiting. As soon as all the matching jobs are no
longer waiting (meaning all the job states are no
longer "introduced", "waiting", or "scheduled") the
pause ends.

NOTEXIST means to pause while the matching job or jobs do not
As soon as any jobs matching "jobid" exist (in any
state) the pause completes. PAUSE might miss finding
short-lived jobs. This is particularly true for a
match on a single job/session number. A more
practical use might be:

PAUSE job=@J;notexist

which means to sleep while no jobs exist. As soon
as the first job is streamed the above pause stops.

OPERATION

     The value of this command lies in providing a way to suspend one
     instance forcing a user command to "idle" while waiting for the
     creation of a key file or the setting of a crucial flag.  You may
     use several MPE/iX commands to query user or system variables, or
     the system itself, in order to verify the existence of the desired
     condition.

     For pausing on one or more jobs, the PAUSE commands uses an
     efficient polling algorithm. The polling interval is controlled by
     the interval_secs parameter. A process cannot pause on itself.

USE

    
 This command is available in BREAK and from a program. You can execute BREAK while PAUSE is active.

EXAMPLE(S)

     A process must read data from a file called LOGDAT.GXK.PROCCTRL,but
     that file must be created by a second process.  PAUSE allows the
     current process to suspend current activity pending a test for the
     existence of  the vital file.

     The output from this example of a job shows how the PAUSE command
     can be used to refine your control of a job (or a command file):

     STREAM JLOGEND
     #J123
     ...
     ...
     SETVAR start_cpu hpcpusecs
     WHILE not finfo("LOGDAT.GXK.PROCCTRL","exists") and &
hpcpusecs-start_cpu < 5 do
PAUSE 2
ENDWHILE
DELETEVAR start_cpu

Note that the number of CPU seconds used by the WHILE loop is
not allowed to exceed 5 seconds.

If the file does not exist and the WHILE loop has consumed less
than five CPU seconds, the job pauses for 2 seconds (this pause
does not use CPU-time). The CPU check is included to prevent an
infinite loop that might result if JLOGEND were to abort
unexpectedly and fail to build the LOGDAT file.


The next example pauses until job #J24 terminates:

PAUSE job=#j24


The next example sleeps as long as MANGER.SYS has any jobs or
sessions running or waiting:

PAUSE job=manager.sys; exists


The next example pauses until the job just streamed starts
executing. This handles cases where job execution is delayed due to
jobfence or job limit constraints:

STREAM myjob
PAUSE job=!hplastjob; wait


The following example sleeps until all jobs have logged off or 5
minutes, whichever occurs first. Note if this PAUSE was executing
from a job, that job would not be included in the @J selection:

PAUSE 300, @J
IF hpcierr = -9032 then
# pause terminated but one or more jobs are still running


The next example pauses while all jobs (by naming convention only)
in the PROD account are running:

PAUSE job="J@,@.PROD"


The next example sleeps while the backup job ("JBACKUP,OP.SYS") has
been streamed. PAUSE reports CIWARN 9032 if the job is not streamed
within 30 minutes:

PAUSE 1800, job="jbackup,op.sys"; notexist


The last example polls every 3 minutes looking for any job or
session matching a user name that includes the letters "MGR", and
waits for all such job/sessions to terminate before the pause
ends:

PAUSE ,@mgr@.@, 180

RELATED INFORMATION

COMMANDS:    SHOWJOB, ALTJOB