Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPSBLKTIME(3cbl)

Name

TPSBLKTIME() - routine for setting blocktime in seconds for the next service call or for all service calls

Synopsis

01 TPBLKDEF-REC.
	COPY TPBLKDEF.
01 TPSTATUS-REC.
	COPY TPSTATUS.

CALL "TPSBLKTIME" USING TPBLKDEF-REC TPSTATUS-REC.

Description

TPSBLKTIME() is used to set the blocktime value, in seconds, of a potential blocking API. A potential blocking API is defined as any system API that can use the flag TBNOBLOCK as a value. It does not have any effect on transaction timeout values.

BLKTIME in TPBLKDEF-REC sets blocking time in seconds. The blocktime range is 0 to 32767. A 0 blocktime value indicates that any previously set blocking time flag value is cancelled, and the blocking time set with a different blocktime flag value prevails. If TPSBLKTIME() is not called, the BLOCKTIME value in the *SERVICES section or the default *RESOURCES section of the UBBCONFIG file is used.

Note: Blocking timeouts set with TPSBLKTIME() take precedence over the BLOCKTIME parameter set in the SERVICES and RESOURCES section of the UBBCONFIG file. The precedence for blocktime checking is as follows:
TPSBLKTIME(TPBLK-NEXT), TPSBLKTIME(TPBLK-ALL), *SERVICES, *RESOURCES

Exactly one of the following values must be in TPBLKDEF-REC:

TPBLK-NEXT

Sets the blocktime value, in seconds, for the next potential blocking API.
Any API that is called containing the TPNOBLOCK flag is not effected by TPSBLKTIME (TPBLK-NEXT)and continues to be non-blocking.

A TPBLK-NEXT blocktime value overrides a TPBLK-ALL blocktime value for those API calls that immediately follow it.

TPSBLKTIME(TPBLK-NEXT) operates on a per-thread basis. Therefore, it is not necessary for applications to use any mutex around the TPSBLKTIME(TPBLK-NEXT) call and the subsequent API call which it affects.

TPBLK-ALL

This flag sets the blocktime value, in seconds, for the all subsequent potential blocking APIs until the next TPSBLKTIME() is called within that context. Any API that is called containing the TPNOBLOCK flag is not effected by TPSBLKTIME(TPBLK-ALL) and continues to be non-blocking.

TPSBLKTIME(TPBLK-ALL) operates on a per-context basis. Therefore, it is necessary to call TPSBLKTIME(TPBLK-ALL) in only one thread of context that is used in multiple threads.

TPSBLKTIME(TPBLK-ALL) will not affect any context that follows after TPTERM(3cbl) is called.

Notes: In order to perform blocking time values that are not affected by thread timing dependencies, it is best that TPSBLKTIME(TPBLK-ALL) is called in a multi-threaded context immediately after TPINITIALIZE(3cbl) using the TP-MULT-ICONTEXTS flag and before the return value of TPGETCTXT(3cbl) is made available to other threads.

When TPSBLKTIME(TPBLK-ALL) is called in a service on a multi-threaded server, it will affect the currently executed thread only. To set the blocktime for all services, it is best that you use TPSBLKTIME(TPBLK-ALL) with TPSVRINIT(3cbl).

Return Values

Upon successful completion, TPSBLKTIME() sets TP-STATUS to [TPOK].

Errors

Under the following conditions, TPSBLKTIME fails and sets TP-STATUS to one of the following values. The failure does not affect transaction timeout values.

[TPEINVAL]

Invalid arguments were given. For example, a value other than TPBLK-NEXT or TPBLK-ALL was specified in TPBLKDEF-REC.

[TPERELEASE]

TPSBLKTIME() was called in a client attached to a workstation handler running an earlier Tuxedo release.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.