Use this system macro to change C function trace information for the
specified entry control block (ECB). By using this macro you can:
- Specify a particular ECB to change
- Specify the size of the C function trace table to allocate
- Specify the size of the C function trace user area to allocate
- Change the subtrace of stack data.
- Change the subtrace of static data.
After a C function trace table has been allocated for an ECB, this macro
has no effect, except that an error indication code is returned in register 15
(R15).
Format
- label
- A symbolic name assigned to the macro statement.
- ECB=Rx
- Changes the C function trace settings for the ECB with its system virtual
address (SVA) specified in a register in the range R0 - R6.
- SIZE
- Specifies the size of the C function trace table to allocate for the
specified ECB. The size is saved and used later when the C function
trace table is created.
If a C function trace table already exists for the specified ECB, the value
specified by the SIZE parameter is not saved and an error indication code is
returned in register R15.
- Ry
- A register in the range R0 - R6 containing the number of 4096-byte
(4 KB) blocks of heap storage to allocate for the C function trace
table. This number is from 1 to a maximum of 256
(X'100').
If the value in the register does not fall within the 1 - 256 range,
the value is not saved and an error indication code is returned in register
R15.
- SYSTEM
- The TPF system value for the trace table size is one 4 KB block (4096
bytes).
- SAME
- Do not change the size of the C function trace table. If the size
has not been specified by a previous SETTC macro, a value of one 4 KB block
(4096 bytes) is used when the C function trace table is created.
- USERSIZE
- Specifies the size of the C function trace user area to allocate when
tracing starts for the specified ECB.
If a C function trace user area already exists for the specified ECB, the
value specified by the USERSIZE parameter is not saved and an error indication
code is returned in register R15.
- Rz
- A register in the range R0 - R6 containing the number of 4096-byte
blocks of heap storage to allocate for the C function trace user area.
This number is in the 1 to 256 (X'100') range.
If the value in the register does not fall in the 1 to 256 range, the value
is not saved and an error indication code is returned in register R15.
- NONE
- Do not allocate a C function trace user trace table.
- SAME
- Do not change the existing size of the C function trace user area.
If the size has not been specified by a previous SETTC macro, a C function
trace user area will not be created.
- STACK
- Changes tracing of C stack data for the specified ECB.
- ON
- Specifies that 68 bytes of the stack user information are placed into the
trace table entry.
- OFF
- Specifies that the address of the stack area is placed into the trace
entry and no C stack information is placed in the trace table.
- SAME
- Do not change the current setting of C function trace stack data.
If the setting of STACK has not been specified by a previous SETTC macro, the
current system STACK value is used.
- STATIC
- Changes tracing of C static data for the specified ECB.
- ON
- Specifies that 68 bytes of the C static information are placed into the
trace table.
- OFF
- Specifies that the address of the static area is placed into the trace
entry, but no C static data is placed in the trace table.
- SAME
- Do not change the current setting of C function trace of static
data. If the setting of STATIC has not been specified by a previous
SETTC macro, the current system STATIC value is used.
Entry Requirements
- For C-type code, the code must be in key of zero and supervisor state when
executing this macro, and R13 must point to a valid system stack area.
- For E-type programs, R9 must contain the ECB virtual address (EVA) of the
ECB issuing the macro.
- The code issuing the SETTC macro must be on the same I-stream as the
target ECB.
- The TPF system should be paused before issuing this macro on behalf of
another ECB.
Return Conditions
- Control is returned to the next sequential instruction (NSI).
- For C-type code, register R15 contains the return code, and the contents
of all other registers are preserved across this macro call.
- For E-type code, the contents of R10 and R14 are unknown, R15 contains the
return code and the contents of all other registers are preserved across this
macro call.
- If no errors occur, register R15 contains zero.
- If an error occurs, no C function trace information is saved and an error
indication code is returned in register R15. If there are multiple
errors, control is returned to the caller after the first error is
found.
- An error indication code is returned in register R15 when:
- The ECB address in the register specified by the ECB parameter is not a
valid system virtual address (SVA) ECB address.
- The C function trace table or the user area already exists for the
specified ECB.
- A register is used with the SIZE parameter and the value in the register
does not fall in the 1 to 256 range.
- A register is used with the USERSIZE parameter and the value in the
register does not fall in the 1 to 256 range.
- The following tags are generated by the SETTC macro and should be used for
interrogating the error indication code.
- IT_BAD_CID_ERR
- Incorrect CID SVM address in target ECB detected by $GSVAC macro.
- IT_BAD_ECB_ERR
- Not a valid system virtual address (SVA) ECB address.
- IT_BAD_TCA_ERR
- Incorrect TCA SVM address in target ECB detected by $GSVAC macro.
- IT_SIZE_ERR
- The value in the SIZE register is not in the range of 1 to 256.
- IT_TRACE_TABLE_ERR
- C function trace table already exists.
- IT_USER_AREA_ERR
- C function trace user area already exists.
- IT_USER_SIZE_ERR
- The value in the USERSIZE register is not in the range of 1 to 256.
Programming Considerations
- Once a C function trace table has been allocated for an ECB, the SETTC
macro cannot change the C function trace settings and returns an error
indication code in register R15.
- On any error, the SETTC macro does not change the C function trace
settings and returns an error indication code in register R15.
- The C function trace user area is an optional storage area, unique per
ECB, the contents of which are controlled by the user. Its purpose is
to provide a user area to store additional information beyond what is stored
in the C function trace table.
Examples
- This invocation:
(R4 contains the SVM address of an active ECB in the TPF system)
LA R5,11
LA R6,3
SETTC ECB=R4,SIZE=R5,USERSIZE=R6,STATIC=ON,STACK=OFF
- Changes the C function trace information for the ECB whose SVA is
specified in register 4.
- Specifies the size of 11 (45 056 bytes, or X'B000'
bytes) for the C function trace table.
- Specifies the size of 3 (12 288 bytes, or X'3000' bytes)
for the C function trace user area.
- Starts the sub-tracing of static data when C function trace is later
activated through the ENATC macro or the ZSTRC command.
- Stops the sub-tracing of stack data (only the stack address is traced)
when C function trace is later activated via the ENATC macro or the ZSTRC
command.
- For E-type programs, R9 must contain the ECB virtual address (EVA) of the
ECB issuing the macro.
- This invocation:
LA R5,4
SETTC ECB=R6,SIZE=R5,USERSIZE=NONE,STATIC=ON,STACK=ON
- Changes the C function trace information for the ECB whose SVA is
specified in register 6.
- Specifies the size of 4 (16 384 bytes, or X'4000' bytes)
for the C function trace table.
- Specifies that there should be no C function trace user area.
- Starts the sub-tracing of static and stack data when C tracing is later
activated via the ENATC macro or the ZSTRC operator command.
- For E-type programs, R9 must contain the ECB virtual address (EVA) of the
ECB issuing the macro.
- This invocation:
(R4 contains the SVM address of an active ECB in the TPF system)
LA R6,8192
SETTC ECB=R4,SIZE=R6,USERSIZE=SAME,STATIC=ON,STACK=OFF
- Does not save any C function trace information.
- Returns the error indication code IT_SIZE_ERR in register R15.
Reason: 8192 is greater than the maximum value of 256
(X'100'). The specified value should be the number of 4096-byte
blocks to allocate.
If the caller wanted to specify a C function trace table size of 8192
(X'2000') bytes, the caller should load register R6 with the value
2.
- For E-type programs, R9 must contain the ECB virtual address (EVA) of the
ECB issuing the macro.