LISTEN

Request a notification be sent to the processing thread.

Read syntax diagramSkip visual syntax diagramLISTENEVENT(data-value) NOTIFICATION(data-ref )FILTER(cpsm-token)NOTFILTER(cpsm-token)TOKEN(data-value)CONTEXT(data-value)THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

Description

This command requests that a notification be sent to the processing thread when a specific event occurs in the CICSplex.
  • An event is represented by a resource table with a type of CPSM Notification.
  • The LISTEN command is used in conjunction with the RECEIVE command. If you use LISTEN to request notification of an event, you must use a subsequent RECEIVE command to retrieve information about the event.
  • 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, CANCEL, RECEIVE

Options

CONTEXT(data-value)
Identifies the context for this command. The context must be the 1- to 8-character name of a CMAS or CICSplex.

If you do not specify the CONTEXT option, the default context for the thread is assumed.

EVENT(data-value)
Identifies the resource table that represents the event to be listened for. This value must be the 1- to 8-character name of a valid CPSM Notification resource table. For a list of the CICSPlex SM resource tables by type, see Developing CICSPlex SM applications.
FILTER(cpsm-token)
Identifies a filter to be used for this operation. The FILTER option listens for only those events that meet the specified filter criteria.
Using the FILTER option, you can limit the notifications you receive to events that are associated with a specific CMAS or CICSplex. For example, you could create a filter like this: 
  PLEXNAME=EYUPLX01.
and specify that filter on the LISTEN command to be notified only of events generated by CICSplex EYUPLX01.

The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.

NOTFILTER(cpsm-token)
Identifies a filter to be used for this operation. The NOTFILTER option listens for only those events that do not meet the specified filter criteria.

The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.

NOTIFICATION(data-ref)
Names a variable to receive the fullword token that CICSPlex SM assigns to this notification request.

This identifying token must be specified on the CANCEL command when you want to cancel the notification request.

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.
TOKEN(data-value)
Defines a 1- to 4-character token that you choose to correlate this LISTEN request with the result of a subsequent RECEIVE command. This token is for use by your program; CICSPlex SM makes no use of the value. The token is returned by the RECEIVE command when an event of the specified type occurs.

Conditions

The following is a list of the RESPONSE values that can be returned by the LISTEN command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.
OK
The command completed processing successfully.
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.
INCOMPATIBLE
An incompatible condition occurred for the following reason:
INVALIDEVT
The specified event is not compatible with the filter specified on the FILTER or NOTFILTER option.
INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • CONTEXT
  • EVENT
  • FILTER
  • NOTFILTER
  • NOTIFICATION
  • 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 was trying to connect is not available for API processing.
PLEXMGR
The CMAS to which the processing thread is currently connected does not participate in managing the specified CICSplex and no other CMAS is available that does manage the CICSplex.
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.