RECEIVE

Receive the output from completed asynchronous requests.

Read syntax diagramSkip visual syntax diagramRECEIVEINTO(data-area) LENGTH(data-ref) OBJECT(data-ref) TOKEN(data-ref)WAITDELAY(data-value)IMMEDIATETHREAD(cpsm-token) 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.
1024 OK
The command completed processing successfully.
1027 NODATA
There was no data to receive.
1028 INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • 1280 THREAD
  • 1281 OBJECT
  • 1285 LENGTH
  • 1291 DELAY
  • 1298 INTO
  • 1306 TOKEN

Check the command description for valid parameter syntax.

1029 FAILED
The command failed for one of the following reasons:
1331 ABENDED
Command processing abended.
1359 EXCEPTION
Command processing encountered an exceptional condition.
1030 ENVIRONERROR
An environment error occurred for one of the following reasons:
1321 SOCRESOURCE
A required resource that is owned by the CMAS is not available.
1357 NOSTORAGE
The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
1358 NOSERVICE
The application stub program could not load the API service module.
1033 SERVERGONE
The CMAS to which the processing thread was connected is no longer active.
1034 NOTAVAILABLE
A not available condition occurred for one of the following reasons:
1334 CPSMAPI
The CMAS to which the processing thread is connected is not available for API processing.
1340 APITASK
The API control subtask is not active.
1035 VERSIONINVL
A version conflict occurred for one of the following reasons:
1335 NOTSUPPORTED
The version of the application stub program used for this command is not supported.
1336 NOTVSNCONN
The version of the application stub program used for this command is not the same as the version used with the CONNECT command.
1037 WARNING
The command completed processing with a warning, for the following reason:
1344 AREATOOSMALL
The INTO buffer is not long enough to hold the number of records requested and available.