Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPNOTIFY(3cbl)

Name

TPNOTIFY() - send notification by client identifier

Synopsis

01 TPSVCDEF-REC.
 COPY TPSVCDEF. 
 
01 TPTYPE-REC.
 COPY TPTYPE. 
 
01 DATA-REC.
 COPY User data. 
 
01 TPSTATUS-REC.
 COPY TPSTATUS. 
 
CALL "TPNOTIFY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Description

TPNOTIFY() allows a server to send an unsolicited message to an individual client.

CLIENTID in TPSVCDEF-REC contains a client identifier saved from the TPSVCDEF-REC of a previous or current service invocation.

DATA-REC is the record to be sent and LEN in TPTYPE-REC specifies how much of DATA-REC should be sent. If DATA-REC is a record of type that does not require a length to be specified, then LEN is ignored (and may be 0). If REC-TYPE in TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and a request is sent with no data portion.

Upon successful return from TPNOTIFY(), the message has been delivered to the system for forwarding to the identified client. If TPACK() was set, then a successful return means the message has been received by the client. Furthermore, if the client has registered an unsolicited message handler, the handler will have been called.

The following is a list of valid settings in TPSVCDEF-REC.

TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

If a blocking condition exists in sending the notification, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK or TPBLOCK must be set.

TPNOTIME

This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.

TPTIME

This setting signifies that the caller will receive blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME or TPTIME must be set.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is not restarted and the call fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPACK

This setting signifies that the caller will block waiting for an acknowledgment from the client. Either TPNOACK() or TPACK() must be set.

TPNOACK

This setting signifies that the caller will not block waiting for an acknowledgment from the client. Either TPNOACK() or TPACK() must be set.

Return Values

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

Errors

Under the following conditions, TPNOTIFY() fails and sets TP-STATUS to:

[TPEINVAL]

Invalid arguments were given.

[TPENOENT]

The target client does not exist and TPACK() was set.

[TPETIME]

A blocking timeout occurred. A blocking timeout can occur under either of the following circumstances: (a)TPBLOCK and TPTIME are specified, or (b) TPACK and TPTIME are specified (in which case no acknowledgment is received).

[TPEBLOCK]

A blocking condition was found on sending the notification and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

TPNOTIFY() was called in an improper context (for example, within a client).

[TPESYSTEM]

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

[TPEOS]

An operating system error has occurred.

[TPERELEASE]

When TPACK() is specified and the target is a client from a prior release of the BEA Tuxedo system that does not support the acknowledgment protocol.