IBM Tivoli NetView for z/OS, Version 6.2

RESET command

High-level language support gives you the option of specifying whether a command procedure is cancelable. The reset flag is set on only when RESET, LOGOFF, or CLOSE IMMED are being issued. See HLL runtime options for more information.

If a command procedure can be cancelled, it behaves according to the rules specified under the RESET command in the NetView® online help The description for RESET NORMAL states that a command stops at its next breakpoint whenever RESET NORMAL is issued. A breakpoint occurs in an HLL command procedure whenever an HLL service routine is started.

If a cancelable command procedure is reset with RESET NORMAL, the command procedure ends with a -5 return code and ends its caller if the caller is also cancelable.

If the command procedure cannot be cancelled, it is reset only when RESET IMMED and RESET DUMP are issued.

Whenever RESET is issued, NetView turns on a reset flag that remains on until the command procedure returns control to NetView or uses the CNMINFI service routine to check RESETREQ.

If RESET NORMAL is issued while a non-cancelable command procedure is running, the reset flag remains on until the noncancelable command procedure either calls or returns to a cancelable command procedure.

A non-cancelable command procedure can check to see if an operator has attempted to reset it by using the RESETREQ function of the CNMINFI service routine. To cancel itself, a command procedure must return to NetView with a -5 return code. This cancels the command procedure that had this return code and all cancelable callers to this command procedure. Cancelable callers include command lists that call a cancelled command procedure, and cancelable command procedures that directly invoke a cancelled command procedure.

Checking the reset flag sets the flag off. As a result, the command procedure that checks the flag must reset the flag. You cannot pass on this responsibility to a higher level through the use of the reset flag. (You can set a user-defined flag for this purpose, but doing so is not recommended.)

Examples

In this example, cancelable command procedure X calls cancelable command procedure Y, which calls cancelable command procedure Z. RESET NORMAL is entered while command procedure Z is running.

Figure 1. Example of command procedure cancellation (1)

As a result of entering RESET NORMAL, Z is reset. Z returns a -5 return code to Y, which causes Y to be reset. Y returns a -5 return code to X, and X is reset.

Keep in mind that the HLL command procedures must invoke the CNMINFI service routines for the reset bit to be checked. Y and X continue executing if they do not invoke any more HLL service routines.

Here cancelable command procedure X calls non-cancelable command procedure Y, which calls cancelable command procedure Z. RESET is entered when command procedure Z is running.

Figure 2. Example of command procedure cancellation (2)

As a result of entering RESET NORMAL, Z is reset. Y receives a -5 return code from the call to Z. Y is not automatically reset by NetView. It can, if it chooses, check the return code and cancel itself, but this is the responsibility of Y. Even though X is cancelable, it is not cancelled because Y is at a lower execution level, and Y is not reset.

In this example, non-cancelable command procedure X calls non-cancelable command procedure Y. Non-cancelable command procedure Y returns control to non-cancelable command procedure X. Non-cancelable command procedure X then calls cancelable command procedure Z. RESET is entered just as X begins execution.

Figure 3. Example of command procedure cancellation (3)

Even though RESET NORMAL is external, X is not cancelled because it is defined as non-cancelable. X calls Y. Y is not cancelled because Y is defined as non-cancelable. Y returns control to X, and then X calls Z. Z is reset and returns control to X with a -5 return code.

Note:

In the example referred to by Figure 3, command procedure X can check the reset flag using the HLL service routine CNMINFI. In this case, the reset flag is turned off and Z is not reset.
Create command procedures that can be cancelled when possible. The HLL support option that cannot be cancelled is provided so that you can code command procedures to perform cleanup (such as free storage) before the procedure is cancelled.
When an HLL command procedure is cancelled, the cleanup that is done is equivalent to that which is done by the STOP statement in PL/I and the EXIT statement in C.

When cleanup is necessary see the following example:

Figure 4. Example of command procedure cancellation (4)

In this example, if RESET is issued while Y is executing, Y is terminated and X performs the cleanup.

Feedback