| | Programming Guide |
Receives data from a screen sent via send or from a remote client via service_call
receive [bundlebundleName] [itemitemNo] [keep] datafieldExprreceive {ARGUMENTS | MESSAGE} ([receiveArg])
bundlebundleName- Optionally names the buffer, or bundle, from which to receive data, where
bundleNamecan be a string constant or variable. Bundle data is written by send statements; if the send statement supplies a bundle name, Panther creates a bundle with that name. Panther by default maintains up to ten bundles of send data in memory; set the number of available bundles with themax_bundlesproperty. 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.itemitemNo- 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.
datafieldExpr- 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
fieldExprarguments delimited by commas.If
fieldExpris 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
intExprevaluates 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 ctARGUMENTS- 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/BEA Tuxedo Guide.
Client, Server
The
receivecommand 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/BEA Tuxedo applications,receiveis used either by a service to receive data from a client, or in a message handler to receive unsolicited messages from servers.
When a
receiveexecutes independently of the middleware, Panther reads data from a bundle that was written by an earlier send statement, typically, from another screen. receive reads the data into itsfieldExprarguments in the same order that it was sent. Unless you supply the keep argument, the bundle data is discarded after receive completes execution.
receivesequentially pairs eachfieldExprargument to a data item in the bundle. If the data item contains multiple occurrences, receive reads as many occurrences intofieldExpras the field allows, or as many as thefieldExprexpression 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.
In JetNet/BEA 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
ARGUMENTSkeyword along withreceiveArgto 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/BEA Tuxedo Guide.A message handler uses the
receivecommand 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 inreceiveArg. 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 theservice_callcommand.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
receivecommand can generate the following exceptions:
service_call, service_return, send