ITTUINIT — Activate external CTRACE recording

Description

Note: ITTUINIT is a linkable system service.

ITTUINIT is one of a set of services that an unauthorized program can use to write CTRACE output. The other services in the set are ITTUWRIT and ITTUTERM. The services must be invoked under the same task in problem state.

Use the ITTUINIT service to activate external CTRACE recording. Once ITTUINIT has been invoked, multiple calls to the ITTUWRIT service can be made to write the CTRACE entries. The ITTUTERM service is invoked to end external CTRACE recording.

The caller of ITTUINIT provides a data structure containing parameters for the service. At the conclusion of its processing, ITTUINIT returns information for the user in the same data structure.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state with PSW key 8-15
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: Must be in the primary address space.

Programming requirements

  1. To build the parameter area required by ITTUINIT, you must include the ITTUIPRM mapping macro (see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/).
  2. Before calling ITTUINIT, the caller must provide the following in the fully-initialized ITTUIPRM mapping macro:
    • The component name
    • The name of the format table for the component
    • The ddname to which CTRACE output is to be written
    • The maximum length of an ITTCTE that will be accepted by ITTUWRIT.
    • The number of bytes of virtual storage that the unauthorized CTRACE writer is authorized to use for trace buffers.
    • An option bit that requests NOWRAP processing. WRAP processing is requested when this bit is zero.

    DSECT=NO may be specified for initial values.

  3. The caller determines whether ITTUINIT processing was successful by examining the return code.
  4. Successful ITTUINIT processing results in the following updated field in ITTUIPRM:
    • A token whose value must be passed to the ITTUWRIT and ITTUTERM services.

Restrictions

The caller cannot have any enabled, unlocked task (EUT) FRRs established.

Input register information

Before linking to ITTUINIT, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
Address of the parameter list
13
Address of a standard 72-byte save area in the primary address space

Before linking to ITTUINIT, the caller does not have to place any information into any access register (AR).

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14
Used as work register by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

Use the following form of the LINK macro to invoke the ITTUINIT service: 
Read syntax diagramSkip visual syntax diagram
>>-label-------------------------------------------------------->

>--+-LINK--EP--=--ITTUINIT--,--MF--=--(--E--,--parmarea--)--------------------------------------+-><
   '-LINKX--EP--=--ITTUINIT--,--MF--=--(--E--,--parmarea--)--+--------------------------------+-'   
                                                             '-,--SF--=--(--E--,--parmlist--)-'     
Note: As an alternative to using LINK or LINKX, callers in 31-bit AMODE can also:
  1. Issue the MVS™ LOAD macro to load the ITTUINIT service and obtain its entry point address.
  2. Issue the CALL macro to call the service. Specify MF=(E,your_parmlist) on the call.

Parameters

The parameters are explained as follows:

label
The name on the macro invocation.
LINK
LINKX
Names the system service that is to be used for linkage.
EP=ITTUINIT
Specifies the entry point name for the ITTUINIT service.
,MF=(E,parmarea)
Specifies the address of the parameter list to be passed to ITTUINIT. The parameter list consists of the following address:
  • The address of the fully-initialized ITTUIPRM.
,SF=(E,parmlist)
For use with LINKX when your program is reentrant. Before you call LINKX with this parameter, define parmlist using the LIST form of LINKX.

Return and reason codes

When the ITTUINIT service returns control to your program, Register 15 contains a return code.

Decimal Return Code Meaning and Action
00 Meaning: The ITTUINIT request completed successfully.

Action: None required.
16 Meaning: Warning. The ITTUINIT request did not complete successfully.

Action: Reissue ITTUINIT.