PERFORM OBJECT

Perform an action on one or more resources.

Description

This command performs an action on one or more resources.

The resources to be acted upon by PERFORM OBJECT do not have to exist as records in a result set; a result set is implicitly created by this process.
If the context and scope in effect when you issue a PERFORM OBJECT command include CICS® systems that do not support the requested action, the request is ignored for those CICS systems.
The PERFORM OBJECT command contains two phases; the first is to build the result set, and the second is to take the requested action against the records in the result set. If an error occurs during the building of the result set, but the result set is not empty, the requested action will still be attempted on the records that are present in the result set.

Related commands

DISCARD, GET, LOCATE, PERFORM SET, QUERY, SET, SPECIFY FILTER

Options

ACTION(data-value)

Identifies the action to be performed. This value must be the 1- to 12-character name of a valid action for the resource table.

For a description of the actions that are valid for a given resource table, see CICSPlex SM resource tables.

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.

COUNT(data-ref)

Names a variable to receive the number of resource table records in the target result set after this operation is complete.

CRITERIA(data-area)

Identifies a buffer containing the filter expression to be used for this operation. The CRITERIA option retrieves only those resource table records that meet the specified filter criteria.

For details on how to form a filter expression, see Developing CICSPlex SM applications.

FILTER(cpsm-token)

Identifies a filter to be used for this operation. The FILTER option retrieves only those resource table records that meet the specified filter criteria.

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

LENGTH(data-value)

A fullword value that specifies the length of the CRITERIA buffer.

Note: The buffer length you specify should not include any data other than a filter expression.

NOREFRESH

Specifies that the resource table records in the result set created by PERFORM OBJECT should not be refreshed. The records reflect the status of the resources when the result set was created.

If you do not specify the NOREFRESH option, the resource table records are refreshed to reflect the resource status after this operation is complete.

NOWAIT

Returns control to your program as soon as the PERFORM OBJECT command has been accepted, which allows the command to be processed asynchronously.

If you specify the NOWAIT option, you must use a subsequent RECEIVE command to test for the completion of this request. The results of an asynchronous request are returned as ASYNCREQ resource table records. For a complete description of asynchronous processing, see Developing CICSPlex SM applications.

Note: If you specify the TOKEN option, the NOWAIT option is assumed by default.

OBJECT(data-value)

Identifies the resource table against which the action is to be performed. This value must be the 8-character name of a valid resource table.

PARM(data-area)

Identifies a buffer containing the parameter expression to be used in performing the action.

For details on how to use a parameter expression with the PERFORM OBJECT command, see Developing CICSPlex SM applications. For a description of the parameters that are required for a given resource table action, see CICSPlex SM resource tables.

PARMLEN(data-value)

A fullword value that specifies the length of the PARM buffer.

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.

RESULT(cpsm-token)

Identifies the API result set to be processed by this operation. The result set can be one produced by any of these commands:

COPY
GET
GROUP
PERFORM OBJECT.

CICSPlex® SM replaces the contents of the existing result set with the resource table records requested by this PERFORM OBJECT command.

If this field is:

Set to binary zero (in COBOL, C, PL/I or Assembler)
An uninitialized variable (in REXX).

CICSPlex SM creates a new result set and returns its identifying token in the same field.

SCOPE(data-value)

Identifies the scope for this command.

To use the SCOPE option, the current context (as set by this command or a previous CONNECT or QUALIFY command) must be a CICSplex. The scope can be:

The 1- to 8-character name of the CICSplex itself
A CICS system or CICS system group within the CICSplex
A logical scope, as defined in a CICSPlex SM resource description (RESDESC).

If OBJECT identifies a CICS definitional resource and the PARM option includes the CSDGROUP parameter, a valid scope can be specified. The scope can be:

A CICS system in the CICSplex.

If the current context is a CMAS or the OBJECT option identifies any other type of resource table, this option has no meaning and is ignored.

If you do not specify the SCOPE option, the default scope for the thread is assumed. If the current context is a CICSplex and no default scope has been set on a CONNECT or QUALIFY command, you receive an INVALIDPARM response for the SCOPE option.

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 an asynchronous PERFORM OBJECT 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 this PERFORM OBJECT request is complete.

Conditions

The following is a list of the RESPONSE values that can be returned by the PERFORM OBJECT command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.

OK

The command completed processing successfully.

SCHEDULED

The command has been scheduled for processing.

NODATA

No records were found that matched the specified search criteria.

BUSY

A busy condition occurred for the following reason:

RESULT: The result set specified on the RESULT option is being processed by another command.

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.
NOTPROCESSED: One of the MASs to which the request was directed could not process the request.
REQTIMEOUT: One of the CMASs or MASs to which the request was directed did not respond.
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.

INVALIDATA

Invalid data was detected. The parameter that contains invalid data is returned as the reason value:

PARM: An attribute value listed in the PARM buffer is not valid for the specified attribute.
CRITERIA: An attribute value listed in the CRITERIA buffer is not valid for the specified attribute.

INVALIDCMD

The command is invalid for one of the following reasons:

FILTER: The filter expression passed on the operation is too large or complex.
LENGTH: The total length of all the options on the command exceeds the maximum limit.

INVALIDPARM

An invalid parameter was detected. The parameter that is invalid is returned as the reason value:

ACTION
CONTEXT
CRITERIA
FILTER
LENGTH
OBJECT
PARM
PARMLEN
RESULT
SCOPE
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.
CMAS: A CMAS to which the request was directed is not available.
CPSMAPI: The CMAS to which the processing thread is connected is not available for API processing.
MAINTPOINT: The maintenance point for the current context is not available.
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.
SCOPE: Either none of the MASs in the specified scope are available or none of them support the requested action.
WORKLOAD: The workload identified on the API request is not available on the local CMAS.

NOTFOUND

A not found condition occurred for one of the following reasons:

ACTION: The action specified on the ACTION option was not found for the specified resource table.
ATTRIBUTE: An attribute specified in the CRITERIA or PARM buffer was not found for the specified resource table.

NOTPERMIT

A not permitted condition occurred for the following reason:

USRID: The user ID associated with the processing thread does not have the required security authorization.

TABLEERROR

A resource table record is invalid for the following reason:

DATAERROR: The value associated with one or more resource table attributes is invalid. This error can occur if the resource table is missing required fields, contains one or more conflicting fields, or is a duplicate. For BAS this error can also occur if you do not have the required security authorization. Use the FEEDBACK command to retrieve additional data about this error.

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:

ACTION: The specified action is not supported for the version used with the CONNECT command.
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.

WARNING

The PERFORM OBJECT command may have only partially completed for one of the following reasons:

RESULT: During the building of the result set to be used on the command, a non-OK response was received. However some result set records were available and the requested action was successfully performed against them. Use the FEEDBACK command without the RESULT option to obtain information about the non-OK response.
ACTION: During the building of the result set to be used on the command, a non-OK response was received. However some result set records were available and the requested action was attempted. The action specified did not complete successfully on, at least one result set record due to a TABLEERROR or DATAERROR CICSPlex SM response or reason.
Use the FEEDBACK command without the RESULT option to obtain information about the error that occurred during the building of the result set. Use the FEEDBACK command with the RESULT option to obtain information about records that caused the TABLEERROR or DATAERROR response or reason.

WORKLOAD

The workload identified on the API request is not available on the local CMAS.