RECEIVE
Receive the output from completed asynchronous requests.
>>-RECEIVE--INTO--(--data-area--)--LENGTH--(--data-ref--)-------> >--OBJECT--(--data-ref--)--+-----------------------+------------> '-TOKEN--(--data-ref--)-' .-WAIT--------------------. >--+-------------------------+--THREAD--(--cpsm-token--)--------> +-DELAY--(--data-value--)-+ '-IMMEDIATE---------------' >--RESPONSE--(--data-ref--)--REASON--(--data-ref--)------------><
Description
This command receives the output
from completed asynchronous requests associated with the processing
thread.
- Asynchronous output can result if you previously issued either
a LISTEN command or one of these commands with the NOWAIT option:
- GET
- PERFORM OBJECT
- PERFORM SET
- REFRESH
- SET.
- To determine if there is any asynchronous output to be received, issue the ADDRESS command and check the SENTINEL value before you issue the RECEIVE command.
- An API processing thread can have a maximum of 256 completed asynchronous requests outstanding at one time. If you do not issue the RECEIVE command at regular intervals and your processing thread reaches its maximum of 256, asynchronous requests are discarded and are not processed. For a complete description of asynchronous processing, see Developing CICSPlex SM applications.
Related commands
ADDRESS, GET, LISTEN, PERFORM OBJECT, PERFORM SET, REFRESH, SET
Options
- DELAY(data-value)
- Specifies the number of seconds that processing will wait if no
output is available when the RECEIVE command is issued. At the end
of the specified number of seconds, control returns to the processing
thread, whether or not any output becomes available. If output becomes
available during the delay period, control returns to the processing
thread. If output is immediately available, there is no delay; control
returns immediately to the processing thread.
DELAY must specify a non-zero value. If you want to make sure that your program never enters a wait, use the IMMEDIATE option instead of DELAY.
- IMMEDIATE
- Returns control to the processing thread immediately, whether or not any output is available.
- INTO(data-area)
- Identifies a buffer to receive asynchronous output, if any is
available for this thread. This buffer must be long enough to hold
all the output being received. The output returned can be:
- A resource table record representing an event named in a previous LISTEN command
- An ASYNCREQ resource table record representing completion of an asynchronous GET, PERFORM, REFRESH, or SET request.
- LENGTH(data-ref)
- A fullword value that specifies the length of the INTO buffer.
After the operation is complete, this field is set to the actual length of the data returned in the INTO buffer. If the operation cannot complete because the buffer is not long enough, this field is set to the length that is required.
- OBJECT(data-ref)
- Names a variable to receive a resource table name, if output is available for this thread.
- REASON(data-ref)
- Names a variable to receive the fullword reason value returned by this command.
- RESPONSE(data-ref)
- Names a variable to receive the fullword response value returned by this command.
- THREAD(cpsm-token)
- Identifies the API thread to be used for this operation. The cpsm-token value that identifies a thread is returned by the CONNECT command.
- WAIT
- Waits until asynchronous output becomes available before returning
control to the processing thread. Note: The WAIT option waits indefinitely for asynchronous output. Be sure to verify that there are completed asynchronous requests outstanding by issuing the ADDRESS command before you issue RECEIVE.
- TOKEN(data-ref)
- Names a variable to receive the user-defined token associated with the asynchronous output. This value is the token you defined on the GET, LISTEN, PERFORM, REFRESH or SET command that produced the output.
Conditions
The following is a list of the
RESPONSE values that can be returned by the RECEIVE command. The description
of each RESPONSE includes a list of associated REASON values, if appropriate.
- OK
- The command completed processing successfully.
- NODATA
- There was no data to receive.
- WARNING
- The command completed processing with a warning, for the following
reason:
- AREATOOSMALL
- The INTO buffer is not long enough to hold the number of records requested and available.
- ENVIRONERROR
- An environment error occurred for one of the following reasons:
- NOSERVICE
- The application stub program could not load the API service module.
- NOSTORAGE
- The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
- SOCRESOURCE
- A required resource that is owned by the CMAS is not available.
- FAILED
- The command failed for one of the following reasons:
- ABENDED
- Command processing abended.
- EXCEPTION
- Command processing encountered an exceptional condition.
- INVALIDPARM
- An invalid parameter was detected. The parameter that is invalid
is returned as the reason value:
- DELAY
- INTO
- LENGTH
- OBJECT
- THREAD
- TOKEN.
- NOTAVAILABLE
- A not available condition occurred for one of the following reasons:
- APITASK
- The API control subtask is not active.
- CPSMAPI
- The CMAS to which the processing thread is connected is not available for API processing.
- SERVERGONE
- The CMAS to which the processing thread was connected is no longer active.
- VERSIONINVL
- A version conflict occurred for one of the following reasons:
- NOTSUPPORTED
- The version of the application stub program used for this command is not supported.
- NOTVSNCONN
- The version of the application stub program used for this command is not the same as the version used with the CONNECT command.
