SET

Modify the attributes of one or more resources.

Read syntax diagramSkip visual syntax diagramSETMODIFY(data-area) LENGTH(data-value) ALLCURRENTFILTER(cpsm-token)MARKEDNOTFILTER(cpsm-token)NOTMARKEDPOSITION(data-value)COUNT(data-value)FORWARDBACKWARDNOREFRESHNOWAITTOKEN(data-value)RESULT(cpsm-token) THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

Description

This command modifies the attributes of one or more resources as represented by resource table records in an existing result set.
  • The SET command is valid only for CICS® Resource and some CPSM Manager resource tables.
  • If the context and scope in effect when you issue a SET command include CICS systems that do not support the requested modification, the request is ignored for those CICS systems.

Related commands

COPY, GET, GROUP, LOCATE, MARK, PERFORM OBJECT, PERFORM SET, SPECIFY FILTER

Options

ALL
Modifies all the resource table records in the result set. When you specify ALL, the COUNT option is ignored.
BACKWARD
Modifies the previous resource table record and continues in a backward direction through the result set modifying as many records as the COUNT option specifies.
Note: If the record pointer is at the bottom of the result set, using BACKWARD modifies the current record (which is the last record) and then continues on to previous records.
COUNT(data-value)
Specifies the number of resource table records to be modified. If you do not specify the COUNT option, only one record is refreshed.

If you do not specify the FORWARD or BACKWARD option, the modification process moves in a forward direction through the result set.

CURRENT
Modifies only the current resource table record. When you specify CURRENT, the COUNT option is ignored.
FILTER(cpsm-token)
Identifies a filter to be used for this operation. The FILTER option indicates that only those resource table records that meet the specified filter criteria should be considered for modification.

The number of records that are modified is determined by the COUNT option. If you do not specify the COUNT option, only the first record that meets the filter criteria is modified.

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

FORWARD
Modifies the current resource table record and continues in a forward direction through the result set modifying as many records as the COUNT option specifies.
LENGTH(data-value)
A fullword value that specifies the length of the MODIFY buffer.
Note: The buffer length you specify should not include any data other than a modification expression.
MARKED
Indicates that only those resource table records that are marked in the result set should be considered for modification.

The number of records that are modified is determined by the COUNT option. If you do not specify the COUNT option, only the first record that is marked is modified.

You can mark resource table records by using the MARK and UNMARK commands.

MODIFY(data-area)
Identifies a buffer containing the modification expression to be used in modifying the resource table records.

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

NOREFRESH
Specifies that the resource table records in the source result set should not be refreshed. The records reflect the status of the resources before the SET command was processed.

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

NOTFILTER(cpsm-token)
Identifies a filter to be used for this operation. The NOTFILTER option indicates that only those resource table records that do not meet the specified filter criteria should be considered for modification.

The number of records that are modified is determined by the COUNT option. If you do not specify the COUNT option, only the first record that does not meet the filter criteria is modified.

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

NOTMARKED
Indicates that only those resource table records that are not marked in the result set should be considered for modification.

The number of records that are modified is determined by the COUNT option. If you do not specify the COUNT option, only the first record that is not marked is modified.

You can mark resource table records by using the MARK and UNMARK commands.

NOWAIT
Returns control to your program as soon as the SET 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.
POSITION(data-value)
Modifies the nth resource table record in the result set. When you specify POSITION, the COUNT option is ignored.

This value must be a number that identifies the record's relative position in the result set. The first record in a result set is identified by the number 1.

For example, to modify the fifth resource table record in a result set, you would specify POSITION(5).

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.
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 SET 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 SET request is complete.

Conditions

The following is a list of the RESPONSE values that can be returned by the SET 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.
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
An invalid data error occurred for one of the following reasons:
MODIFY
An attribute value listed in the MODIFY buffer is not valid for the specified attribute.
NOTSUPPORTED
An attribute listed in the MODIFY buffer is not modifiable.
INVALIDCMD
The command is invalid for the following reason:
LENGTH
The total length of all the options on the command exceeds the maximum limit.
INVALIDPARM
An invalid parameter was detected in either the command string or the MODIFY buffer. The parameter that is invalid is returned as the reason value:
  • ATTRIBUTE
  • COUNT
  • FILTER
  • LENGTH
  • MODIFY
  • NOTFILTER
  • POSITION
  • RESULT
  • 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.
SCOPE
Either none of the MASs in the specified scope are available or none of them support the requested modification.
NOTFOUND
A not found condition occurred for one of the following reasons:
ACTION
An action requested in the MODIFY buffer was not found for the specified resource table.
ATTRIBUTE
An attribute specified in the MODIFY 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.
SERVERGONE
The CMAS to which the processing thread was connected is no longer active.
TABLEERROR
A resource table record is invalid for one of the following reasons:
DATAERROR
The value associated with one or more resource table attributes is invalid. This error can occur if the resource table is missing required attributes, contains one or more conflicting attributes, or is a duplicate. Use the FEEDBACK command to retrieve additional data about this error.
INVALIDVER
The specified version of the resource table is not supported by CICSPlex SM.
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.