RECEIVE

Receive the output from completed asynchronous requests.

Read syntax diagramSkip visual syntax diagram>>-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.

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.
Check the command description for valid parameter syntax.
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.
[[ Contents Previous Page | Next Page Index ]]