SETOC: Set maximum times to avoid application timeout for an ECB

Use this system macro to set the maximum times that an application can avoid a timeout between loss of control for the specified entry control block (ECB).

Last updated

  • Changed in 2019.
  • Changed for PUT00.

Format

Read syntax diagramSkip visual syntax diagramlabelSETOC ECB= reg1,AVOIDT= reg2
label
A symbolic name that can be assigned to the macro statement.
ECB=reg1
Specifies the system virtual address (SVA) of the target ECB that is to avoid application timeout. The SVA is specified in a register in the range R0 through R6.
AVOIDT=reg2
Specifies the maximum times the program is to avoid timeout. This is in addition to the one time for the timeout of the program. The value is specified in a register in the range R0 through R6.

The value acts as a multiplier of the timeout of the program.

Specify a value of 0-32765.

A value of 0 means the ECB will use the timeout of the program.

Entry requirements

  • C-type programs must be in key 0 and supervisor state when processing 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.

Return conditions

  • Control is returned to the next sequential instruction (NSI).
  • Return codes in R15:
    • If no error occurs, R15 contains zero, and the timeout for this ECB is changed.
    • If an error occurs, an error indication code is returned in R15, and the timeout is not changed. Control is returned to the caller after the first error is found.
  • For E-type programs, the contents of R10 and R14 are unknown.
  • The contents of all other registers are preserved across this macro call.
  • The following tags are generated by the SETOC macro and should be used for interrogating the error indication code returned in R15:
    • IT_SETOC_BAD_ECB_ERR – The address in the ECB parameter register is not a valid system virtual address (SVA) ECB address. The timeout for the ECB is not changed.
    • IT_SETOC_BAD_AVOIDT_ERR – The value in the AVOIDT parameter register is a negative number or a number greater than 32765. The timeout for the ECB is not changed.

Programming considerations

  • For information about macro register conventions, see Register conventions.
  • The contents of the AVOIDT parameter register acts as a multiplier of the timeout value of the program.

    For example, if the timeout value of the program is 500 milliseconds, a value of 3 causes the ECB to wait 3 times in addition to the 1 time for the timeout of the program. The ECB will wait ((3 times 500) plus (1 times 500)), or 2000 milliseconds, before timing out.

  • Specify the minimum AVOIDT value needed. A large value can cause system performance problems or lockout problems.
  • The ECB issuing the SETOC macro must be on the same I-stream as the target ECB, or the ECB should pause the z/TPF system before issuing the SETOC macro on behalf of another ECB.
  • You can use the ZCTKA command to change the value in keypoint A for the number of times to avoid an application timeout. z/TPF system code can use the contents of the CINFC CMMAVMAX field for the contents of the SETOC macro AVOIDT parameter register when issuing the SETOC macro.
  • You can use the ZAPAT command with the TIMEOUT parameter specified to set different timeout values for each program.
  • The SETOC macro does not affect time slice timeout with a 002010 system error.
  • The APL user exit is provided for you to issue the SETOC macro to set the maximum times to avoid timeout for an ECB immediately before the ECB is about to be timed out with a 000010 system error.
  • The SETOC macro sets R15 with a return code. If the SETOC macro is used in the APL user exits, a base register other than R15 should be established for addressability.

Examples

In the following examples, the timeout value of the program is assumed to be 500 milliseconds. For E-type programs, R9 must contain the ECB virtual address (EVA) of the ECB issuing the macro.

  • AVOIDT parameter register contents of 2: 
    (R6 contains the SVM address of an active ECB in the z/TPF system)
LA    R3,2
SETOC ECB=R6,AVOIDT=R3
    This invocation:
    • Changes the timeout for the ECB whose SVA is contained in register 6. The ECB will wait 2 times the timeout of the program in addition to the 1 time for the timeout of the program. The number of milliseconds the ECB will wait before timing out is
      • ((2 times 500) plus (1 times 500)), or 1500 milliseconds.
  • AVOIDT parameter register contents of 32767: 
    (R6 contains the SVM address of an active ECB in the z/TPF system)
LA    R3,=X'00007FFF'             VALUE IS 32767
SETOC ECB=R6,AVOIDT=R3

    This invocation causes an error condition to be returned in R15 because an AVOIDT value greater than 32765 is an error condition. The timeout is not changed.

  • AVOIDT parameter register contents of 0: 
    (R6 contains the SVM address of an active ECB in the z/TPF system)
LA    R3,0
SETOC ECB=R6,AVOIDT=R3

    This invocation resets the timeout to the timeout of the program for the ECB whose SVA is contained in register 6. If the timeout of the program is 500 milliseconds, the ECB will wait 500 milliseconds before timing out.

Related information

See z/TPF Operations for more information about the ZAPAT and ZCTKA commands.