Programming Guide

Receives data sent via send or from a remote client via service_call

receive [bundle bundleName] [item itemNo] [keep] data fieldExpr

receive {ARGUMENTS | MESSAGE} ([receiveArg])

bundle bundleName

Optionally names the buffer, or bundle, from which to receive data, where bundleName can be a string constant or variable. Bundle data is written by send commands; if the send command supplies a bundle name, Panther creates a bundle with that name. Panther by default maintains up to ten bundles of send data in memory; change the number of available bundles by setting the max_bundles property. If no name is supplied, Panther gets data from the unnamed bundle–that is, a bundle whose data is sent from the last send command that omitted a bundle name.

item itemNo

Specifies the bundle offset from which to start reading data, where item numbering begins at 1. If you omit this argument, receive starts getting bundle data from the first item. receive counts data items in the same order as they were sent. Each item in the bundle can contain one or more occurrences; because an array is regarded as a single data item, Panther disregards its occurrences when it evaluates itemNo.

keep

Specifies to leave the bundle data intact after receive completes execution. This lets multiple receive statements specify the same bundle of data. By default, receive destroys the bundle and frees the memory allocated for it after it completes execution.

data fieldExpr

Specifies the fields or occurrences to receive the bundle data. Refer to "Object Specification" in Application Development Guide for more information about valid field expressions. You can specify multiple fieldExpr arguments delimited by commas.

If fieldExpr is a non-subscripted array, receive reads the bundle data into all of the array's occurrences. You can specify a single occurrence or range of occurrences within an array by subscripting it with this format:

array[intExpr[..[intExpr] ] ]

where intExpr evaluates to an integer. If you omit the last occurrence specifier, receive reads into all occurrences from the one specified to the end of the array. The following examples show different subscripts that are valid:

receive data @widget("empno")[1] //read only occurrence 1
receive data empno[1..10]  //read into occurrences 1-10
receive data empno[ct..]   //read all occurrences from ct

ARGUMENTS

Used by services to receive their arguments from a client agent that initiated a service request. Use of this keyword is restricted to servers.

MESSAGE

Enables clients to receive unsolicited messages via a message handler. Use of this keyword is restricted to clients.

receiveArg

Specifies the target variables to receive the incoming message data. Parentheses are required even when no argument is specified. The format of the incoming data is specified in the JIF's definition of the service. For more information on message data types, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.

Client, Server

The receive command is used in different ways depending on whether it is used to receive data/messages from remote client or server agents using the middleware, or if it is receiving data locally from another screen. In JetNet/Oracle Tuxedo applications, receive is used either by a service to receive data from a client, or in a message handler to receive unsolicited messages from servers.

When a receive executes independently of the middleware, Panther reads data from a bundle that was written by an earlier send command, typically, from another screen. receive reads the data into its fieldExpr arguments in the same order that it was sent. Unless you supply the keep argument, the bundle data is discarded when receive completes execution.

receive sequentially pairs each fieldExpr argument to a data item in the bundle. If the data item contains multiple occurrences, receive reads as many occurrences into fieldExpr as the field allows, or as many as the fieldExpr expression specifies. If any occurrences remain unread, receive ignores them and reads the next data item into its corresponding target.

You can use the item argument to start reading data from a specified offset in the bundle. receive starts reading data from this offset.

If a bundle item has more occurrences than are currently allocated for the target array, Panther allocates new occurrences for the overflow data. If the incoming data overflows the array's maximum number of occurrences or a specified range, receive ignores the extra occurrences.

If a bundle item has fewer occurrences than currently allocated for the target array, receive writes to the array as follows:

• If no range is specified, Panther overwrites the array with the bundle data and discards previous data in remaining occurrences.

• If a range is specified, Panther writes only to those occurrences. Data in other occurrences remains intact. If the range has more occurrences than the incoming data, Panther discards previous data in the remaining occurrences.

• If an unbounded range is specified, for example, DATA empno[4..], Panther overwrites the array from the specified occurrence and discards previous data in remaining occurrences. Data in occurrences that precede the range remains intact.

If a data argument is invalid, for example, the target field does not exist or the range of occurrences is invalid, the receive command aborts data transfer prematurely and posts an error message. Panther ignores remaining bundle data and, unless keep was specified, destroys the bundle.

In JetNet/Oracle Tuxedo applications, when the middleware intercepts receive, it establishes a mapping for incoming data and applies that mapping (unloads the data) when the data is available.

Use the ARGUMENTS keyword along with receiveArg to specify a Panther mapping for the incoming data and to request that the data be unloaded to those Panther targets. For more information on specifying arguments, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.

A message handler uses the receive command to specify a Panther mapping for the incoming message and to request that the message actually be unloaded to those Panther targets based on the mapping specified in receiveArg. A message handler is invoked to process unsolicited messages. These include broadcast messages from other clients or servers, and notify messages from the servers currently processing service requests for the client.

For example, the following code shows receive used in a message handler:

// The message handler
proc msg_handler (type)
vars msgStr
if (type=="JAMFLEX")
{
	receive MESSAGE ({msgStr})
	msg emsg msgStr
}
return

// Install the message handler:
...
@app()->hdl_message = "msg_handler"
...

The next example shows the code for service VAL_PIN, which validates a client logging in with last name and password. The client end of this process is shown in the service_call command.

proc val_pin()
// service VAL_PIN

receive ARGUMENTS ({last_name, pin})
call sm_tm_command("VIEW")

if (!@dmrowcount)
{
	service_return failure \
		({message = "Password or name is invalid; try again"})
}
service_return ({message = @tpi_null, owner_ssn})

When used to receive data via the middleware, the receive command can generate the following exceptions:

Exception	Severity	Cause
TP_INVALID_ARGUMENT	TP_COMMAND	Argument specification doesn't match incoming data.
TP_INVALID_ARGUMENT_LIST	TP_COMMAND	No arguments are available.
TP_INVALID_BUFFER	TP_COMMAND, TP_WARNING	The type of the data buffer received is not the same type as specified in the JIF.
TP_INVALID_BUFFER_VERSION	TP_COMMAND, TP_WARNING	JAMFLEX is the buffer type, but the version is incompatible.
TP_INVALID_CALL	TP_COMMAND	receive ARGUMENTS is used outside of a service.
TP_INVALID_CONTEXT	TP_COMMAND	receive is called from a client but not within a message handler.
TP_NO_OUTSTANDING_MESSAGE	TP_COMMAND	receive MESSAGE is used and there is no message to receive.

send, service_call, service_return

---

---