EXECUTIL - IBM-REXX

« Previous Topics
Execio
Dropbuf
Delstack
Next Topics »
He
Hi
Ht

EXECUTIL

lets you change various characteristics that control how an exec processes in the TSO/E address space. You can use EXECUTIL:

  • In a REXX exec that runs in a TSO/E address space
  • From TSO/E READY mode
  • From ISPF — the ISPF command line or the ISPF option that lets you enter a TSO/E command or CLIST
  • In a CLIST.

You can use EXECUTIL in a CLIST to affect exec processing. However, it has no effect on CLIST processingYou can also use EXECUTIL with the HI, HT, RT, TS, and TE operands from a program that is written in a high-level programming language by using the TSO service facility.From READY mode or ISPF, the HI, HT, and RT operands are not applicable because an exec is not currently running.

Use EXECUTIL to:

  • Specify whether the system exec library (the default is SYSEXEC) is to be closed after the exec is located or is to remain open
  • Start and end tracing of an exec
  • Halt the interpretation of an exec
  • Suppress and resume terminal output from an exec
  • Change entries in a function package directory
  • Specify whether the system exec library (the default is SYSEXEC) is to be searched in addition to SYSPROC.

Additional Considerations for Using EXECUTIL:

  • All of the EXECUTIL operands are mutually exclusive, that is, you can only specify one of the operands on the command.
  • The HI, HT, RT, TS, and TE operands on the EXECUTIL command are also, by themselves, immediate commands.Immediate commands are commands you can issue from the terminal if an exec is running in TSO/E and you press the attention interrupt key and enter attention mode. When you enter attention mode, you can enter an immediate command.Note that HE (Halt Execution) is an immediate command, but HE is not a valid operand on the EXECUTIL command.You can also use the TSO/E REXX commands TS (Trace Start) and TE (Trace End) in a REXX exec that runs in any address space (TSO/E and non-TSO/E
  • In general, EXECUTIL works on a language processor environment basis. That is, EXECUTIL affects only the current environment in which EXECUTIL is issued. For example, if you are in split screen in ISPF and issue EXECUTIL TS from the second ISPF screen to start tracing, only execs that are invoked from that ISPF screen are traced. If you invoke an exec from the first ISPF screen, the exec is not traced.

Using the EXECDD and SEARCHDD operands may affect subsequent language processor environments that are created.For example, if you issue EXECUTIL SEARCHDD from TSO/E READY mode and then invoke ISPF, the new search order defined by EXECUTIL SEARCHDD may be in effect for the ISPF session also.This depends on whether your installation has provided its own parameters modules IRXTSPRM and IRXISPRM and the values specified in the load module.

EXECDD(CLOSE)or EXECDD(NOCLOSE)
Specifies whether the system exec library is to be closed after the system locates the exec but before the exec runs.

CLOSE causes the system exec library, whose default name is SYSEXEC, to be closed after the exec is located but before the exec runs. You can change this condition by issuing the EXECUTIL EXECDD(NOCLOSE) command.

NOCLOSE causes the system exec library to remain open. This is the default condition and can be changed by issuing the EXECUTIL EXECDD(CLOSE) command. The selected option remains in effect until it is changed by the appropriate EXECUTIL command, or until the current environment is terminated.

Notes:

  1. The EXECDD operand affects the ddname specified in the LOADDD field in the module name table. The default is SYSEXEC.
  2. If you specify EXECDD(CLOSE), the exec library (DD specified in the LOADDD field) is closed immediately after an exec is loaded.
  3. Specify EXECDD(CLOSE) or EXECDD(NOCLOSE) before running any execs out of the SYSEXEC file. If you attempt to use EXECDD(CLOSE) or EXECDD(NOCLOSE) after SYSEXEC has already been opened, you may not get the expected result because the SYSEXEC file must be closed at the same MVS task level at which it was opened.

Any libraries defined using the ALTLIB command are not affected by the EXECDD operand. SYSPROC is also not affected.

TS
Use TS (Trace Start) to start tracing execs. Tracing lets you interactively control the processing of an exec and debug problems.

If you issue EXECUTIL TS from READY mode or ISPF, tracing is started for the next exec you invoke. Tracing is then in effect for that exec and any other execs it calls. Tracing ends:

  • When the original exec completes
  • If one of the invoked execs specifies EXECUTIL TE
  • If one of the invoked execs calls a CLIST, which specifies EXECUTIL TE
  • If you enter attention mode while an exec is running and issue the TE immediate command.

If you use EXECUTIL TS in an exec, tracing is started for all execs that are running.This includes the current exec that contains EXECUTIL TS, any execs it invokes, and any execs that were running when the current exec was invoked. Tracing remains active until all execs that are currently running complete or an exec or CLIST contains EXECUTIL TE.

For example, suppose exec A calls exec B, which then calls exec C. If exec B contains the EXECUTIL TS command, tracing is started for exec B and remains in effect for both exec C and exec A. Tracing ends when exec A completes. However, if one of the execs contains EXECUTIL TE, tracing ends for all of the execs.

If you use EXECUTIL TS in a CLIST, tracing is started for all execs that are running, that is, for any exec the CLISTinvokes or execs that were running when the CLIST was invoked. Tracing ends when the CLIST and all execs that are currently running complete or if an exec or CLIST contains EXECUTIL TE. For example, suppose an exec calls a CLIST and the CLIST contains the EXECUTIL TS command. When control returns to the exec that invoked the CLIST, that exec is traced.

You can use EXECUTIL TS from a program by using the TSO service facility. For example, suppose an exec calls a program and the program encounters an error.The program can invoke EXECUTIL TS using the TSO service facility to start tracing all execs that are currently running.

You can also press the attention interrupt key, enter attention mode, and then enter TS to start tracing or TE to end tracing. You can also use the TS command and TE command in an exec.

TE
Use TE (Trace End) to end tracing execs. The TE operand is not really applicable in READY mode because an exec is not currently running. However, if you issued EXECUTIL TS to trace the next exec you invoke and then issued EXECUTIL TE, the next exec you invoke is not traced.

If you use EXECUTIL TE in an exec or CLIST, tracing is ended for all execs that are currently running. This includes execs that were running when the exec or CLIST was invoked and execs that the exec or CLIST calls. For example, suppose exec A calls CLIST B, which then calls exec C. If tracing was on and CLIST B contains EXECUTIL TE, tracing is ended and execs C and A are not traced.

You can use EXECUTIL TE from a program by using the TSO service facility. For example, suppose tracing has been started and an exec calls a program. The program can invoke EXECUTIL TE using the TSO service facility to end tracing of all execs that are currently running.

You can also press the attention interrupt key, enter attention mode, and then enter TE to end tracing. You can also use the TE immediate command in an exec.

HT
Use HT (Halt Typing) to suppress terminal output generated by an exec.The exec continues running. HT suppresses any output generated by REXX instructions or functions (for example, the SAY instruction) and REXX informational messages. REXX error messages are still displayed. Normal terminal output resumes when the exec completes.You can also use EXECUTIL RT to resume terminal output.

HT has no effect on CLISTs or commands. If an exec invokes a CLIST and the CLIST generates terminal output, the output is displayed. If an exec invokes a command, the command displays messages.

Use the HT operand in either an exec or CLIST. You can also use EXECUTIL HT from a program by using the TSO service facility. If the program invokes EXECUTIL HT, terminal output from all execs that are currently running is suppressed. EXECUTIL HT is not applicable from READY mode or ISPF because no execs are currently running.

If you use EXECUTIL HT in an exec, output is suppressed for all execs that are running. This includes the current exec that contains EXECUTIL HT, any execs the exec invokes, and any execs that were running when the current exec was invoked.Output is suppressed until all execs that are currently running complete or an exec or CLIST contains EXECUTIL RT.

If you use EXECUTIL HT in a CLIST, output is suppressed for all execs that are running, that is, for any exec the CLIST invokes or execs that were running when the CLIST was invoked. Terminal output resumes when the CLIST and all execs that are currently running complete or if an exec or CLIST contains EXECUTIL RT.

For example, suppose exec A calls CLIST B, which then calls exec C. If the CLIST contains EXECUTIL HT, output is suppressed for both exec A and exec C.

If you use EXECUTIL HT and want to display terminal output using the SAY instruction, you must use EXECUTIL RT before the SAY instruction to resume terminal output.

RT
Use RT (Resume Typing) to resume terminal output that was previously suppressed. Use the RT operand in either an exec or CLIST. You can also use EXECUTIL RT from a program by using the TSO service facility. If the program invokes EXECUTIL RT, terminal output from all execs that are currently running is resumed.EXECUTIL RT is not applicable from READY mode or ISPF because no execs are currently running.

If you use EXECUTIL RT in an exec or CLIST, typing is resumed for all execs that are running.

HI
Use HI (Halt Interpretation) to halt the interpretation of all execs that are currently running in the language processor environment. From either an exec or a CLIST, EXECUTIL HI halts the interpretation of all execs that are currently running. If an exec calls a CLIST and the CLIST contains EXECUTIL HI, the exec that invoked the CLIST stops processing.

EXECUTIL HI is not applicable from READY mode or ISPF because no execs are currently running.

You can use EXECUTIL HI from a program by using the TSO service facility. If the program invokes EXECUTIL HI, the interpretation of all execs that are currently running is halted.

If an exec enables the halt condition trap and the exec includes the EXECUTIL HI command, the interpretation of the current exec and all execs the current exec invokes is halted. However, any execs that were running when the current exec was invoked are not halted. These execs continue running. For example, suppose exec A calls exec B and exec B specifies EXECUTIL HI and also contains a SIGNAL ON HALT instruction (with a HALT: label). When EXECUTIL HI is processed, control is given to the HALT subroutine.When the subroutine completes, exec A continues processing at the statement that follows the call to exec B.

RENAME Use EXECUTIL RENAME to change entries in a function package directory. A function package directory contains information about the functions and subroutines that make up a function package.

A function package directory contains the following fields for each function and subroutine:

  • Func-name -- the name of the external function or subroutine that is used in an exec.
  • Addr -- the address, in storage, of the entry point of the function or subroutine code.
  • Sys-name -- the name of the entry point in a load module that corresponds to the code that is called for the function or subroutine.
  • Sys-dd -- the name of the DD from which the function or subroutine code is loaded.

You can use EXECUTIL RENAME with the SYSNAME and DD operands to change an entry in a function package directory as follows:

  • Use the SYSNAME operand to change the sys-name of the function or subroutine in the function package directory. When an exec invokes the function or subroutine, the routine with the new sys-name is invoked.
  • Use EXECUTIL RENAME NAME(function-name) without the SYSNAME and DD operands to flag the directory entry as null.This causes the search for the function or subroutine to continue because a null entry is bypassed. The system will then search for a load module and/or an exec.

EXECUTIL RENAME clears the addr field in the function package directory to X'00'. When you change an entry, the name of the external function or subroutine is not changed, but the code that the function or subroutine invokes is replaced.

You can use EXECUTIL RENAME to change an entry so that different code is used.

NAME(function-name)
Specifies the name of the external function or subroutine that is used in an exec. This is also the name in the func-name field in the directory entry.

SYSNAME(sys-name)
Specifies the name of the entry point in a load module that corresponds to the package code that is called for the function or subroutine. If SYSNAME is omitted, the sys-name field in the package directory is set to blanks.

DD(sys-dd)
Specifies the name of the DD from which the package code is loaded. If DD is omitted, the sys-dd field in the package directory is set to blanks.

SEARCHDD(YES/NO)
Specifies whether the system exec library (the default is SYSEXEC) should be searched when execs are implicitly invoked. YES indicates that the system exec library (SYSEXEC) is searched, and if the exec is not found, SYSPROC is then searched. NO indicates that SYSPROC only is searched.

EXECUTIL SEARCHDD lets you dynamically change the search order.The new search order remains in effect until you issue EXECUTIL SEARCHDD again, the language processor environment terminates, or you use ALTLIB. Subsequently created environments inherit the same search order unless explicitly changed by the invoked parameters module.

ALTLIB affects how EXECUTIL operates to determine the search order. If you use the ALTLIB command to indicate that user-level, application-level, or system-level libraries are to be searched, ALTLIB operates on an application basis.

EXECUTIL SEARCHDD generally affects the current language processor environment in which it is invoked. For example, if you are in split screen in ISPF and issue EXECUTIL SEARCHDD from the second ISPF screen to change the search order, the changed search order affects execs invoked from that ISPF screen.If you invoke an exec from the first ISPF screen, the changed search order is not in effect. However, if you issue EXECUTIL SEARCHDD from TSO/E READY mode, when you invoke ISPF, the new search order may also be in effect for ISPF. This depends on whether your installation has provided its own parameters modules IRXTSPRM and IRXISPRM and the values specified in the load module.

Return Codes:EXECUTIL returns the following return codes.

EXECUTIL returns

Examples

  1. Your installation uses both SYSEXEC and SYSPROC to store REXX execs and CLISTs. All of the execs you work with are stored in SYSEXEC and your CLISTs are stored in SYSPROC.Currently, your system searches SYSEXEC and SYSPROC and you do not use ALTLIB.You want to work with CLISTs only and do not need to search SYSEXEC.To change the search order and have the system search SYSPROC only, use the following command: EXECUTIL SEARCHDD(NO)
  2. You are updating a REXX exec and including a new internal subroutine. You want to trace the subroutine to test for any problems. In your exec, include EXECUTIL TS at the beginning of your subroutine and EXECUTIL TE when the subroutine returns control to the main program. For example:
  3. /* REXX program */
    MAINRTN:
    ...
    CALL SUBRTN
    "EXECUTIL TE"
    ...
    EXIT
    /* Subroutine follows */
    SUBRTN:
    "EXECUTIL TS"
    ...
    RETURN
  4. You want to invoke an exec and trace it. The exec does not contain EXECUTIL TS or the TRACE instruction. Instead of editing the exec and including EXECUTIL TS or a TRACE instruction, you can enter the following from TSO/E READY mode: EXECUTIL TS When you invoke the exec, the exec is traced. When the exec completes processing, tracing is off.
  5. Suppose an external function called PARTIAL is part of a function package. You have written your own function called PARTIAL or a new version of the external function PARTIAL and want to execute your new PARTIAL function instead of the one in the function package. Your new PARTIAL function may be an exec or may be stored in a load module. You must flag the entry for the PARTIAL function in the function package directory as null in order for the search to continue to execute your new PARTIAL function. To flag the PARTIAL entry in the function package directory as null, use the following command:
  6. EXECUTIL RENAME NAME(PARTIAL)

When you execute the function PARTIAL, the null entry for PARTIAL in the function package directory is bypassed.The system will continue to search for a load module and/or exec that is called PARTIAL.

« Previous Topics
Execio
Dropbuf
Delstack
Next Topics »
He
Hi
Ht

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-REXX Topics