ITTUWRIT — Queue a group of CTRACE entries

Description

Note: ITTUWRIT is a linkable system service.

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

Use the ITTUWRIT service to queue a group of CTRACE entries. Whenever new CTRACE entries overflow a buffer, recording of the entries occurs.

The caller of ITTUWRIT provides the token returned by the ITTUINIT service and the address of the storage area containing the ITTCTE entries.

Multiple calls to the ITTUWRIT service can be made to write the CTRACE entries. When ITTUWRIT is in control, the system writes the ITTCTE entries from the storage area passed to ITTUWRIT into the CTRACE output buffers immediately. If necessary, the system may need to discard trace entries because of timing considerations or error conditions such as I/O errors or storage overlays. ITTUWRIT adds control information to the trace data set whenever data losses occur, if possible.

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

To reference the parameter area required by ITTUWRIT, 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/).
The caller determines whether ITTUWRIT processing was successful by examining the return code.

Restrictions

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

Input register information

Before linking to ITTUWRIT, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
1: Address of parameter list
13: Address of a standard 72-byte save area in the primary address space

Before linking to ITTUWRIT, 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 ITTUWRIT service:


>>-label-------------------------------------------------------->

>--+-LINK--EP--=--ITTUWRIT--,--MF--=--(--E--,--parmarea--)--------------------------------------+-><
   '-LINKX--EP--=--ITTUWRIT--,--MF--=--(--E--,--parmarea--)--+--------------------------------+-'   
                                                             '-,--SF--=--(--E--,--parmlist--)-'

Note: As an alternative to using LINK or LINKX, callers in 31-bit AMODE can also:

Issue the MVS™ LOAD macro to load the ITTUWRIT service and obtain its entry point address.
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=ITTUWRIT

Specifies the entry point name for the ITTUWRIT service.

,MF=(E,parmarea)

Specifies the address of the parameter list to be passed to ITTUWRIT. The parameter list consists of the following three addresses:

The address of the token passed from ITTUINIT.
The address of a fullword containing the size of the block of CTE entries.
The address of the area containing the CTE entries.

,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 ITTUWRIT service returns control to your program, Register 15 contains a return code.

Decimal Return Code	Meaning and Action
00	Meaning: The ITTUWRIT request completed successfully. Action: None required.
16	Meaning: Warning. The ITTUWRIT request did not complete successfully. Action: Reissue ITTUWRIT.