REFRESH
Refresh the data for resource table records.
Description
- This command refreshes the data for some or all of the resource table records in a result set.
- For the MAS resource table, REFRESH provides data only if the MAS was active when the result set was last built.
Related commands
COPY, GET, LOCATE, MARK, PERFORM OBJECT, SPECIFY FILTER
Options
- ALL
- Refreshes all the resource table records in the result set. When
you specify ALL:
- The COUNT option is ignored.
- Any records that have been deleted are removed from the result set. Any positions previously held by deleted records are filled in and the remaining records are renumbered. Therefore, the relative position of a given record in a result set may be different after a refresh.
- BACKWARD
- Refreshes the previous resource table record and continues in
a backward direction through the result set refreshing as many records
as the COUNT option specifies. Note: If the record pointer is at the bottom of the result set, using BACKWARD refreshes 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 refreshed.
If you do not specify the COUNT option, only one record is refreshed.
If you do not specify the FORWARD or BACKWARD option, the refresh process moves in a forward direction through the result set.
- CURRENT
- Refreshes 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 refresh.
The number of records that are refreshed is determined by the COUNT option. If you do not specify the COUNT option, only the first record that meets the filter criteria is refreshed.
The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.
- FORWARD
- Refreshes the current resource table record and continues in a forward direction through the result set refreshing as many records as the COUNT option specifies.
- MARKED
- Indicates that only those resource table records that are marked
in the result set should be considered for refresh.
The number of records that are refreshed is determined by the COUNT option. If you do not specify the COUNT option, only the first record that is marked is refreshed.
You can mark resource table records by using the MARK and UNMARK commands.
- 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 refresh.
The number of records that are refreshed 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 refreshed.
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 refresh.
The number of records that are refreshed is determined by the COUNT option. If you do not specify the COUNT option, only the first record that is not marked is refreshed.
You can mark resource table records by using the MARK and UNMARK commands.
- NOWAIT
- Returns control to your program as soon as the REFRESH 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. - 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
- 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 REFRESH 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 REFRESH request is complete.
Conditions
The following is a list of the
RESPONSE values that can be returned by the REFRESH 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.
- INVALIDPARM
- An invalid parameter was detected. The parameter that is invalid
is returned as the reason value:
- COUNT
- FILTER
- NOTFILTER
- RESULT
- THREAD
- TOKEN.
- 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.
- RESOURCE
- The resource table type for the result set being refreshed is not supported by this command. To refresh the result set, re-execute the GET command used to originally acquire it. Currently, result sets for the EVCSPEC, HTASK, OSGIBUND, OSGISERV, SYSPARM, and RULE resource tables are not refreshable.
- SCOPE
- One or more of the MASs in the specified scope is unavailable. A MASQRYER resource table record is produced to identify any MAS that did not respond to the request.
- 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 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 attributes, contains one or more conflicting attributes, or does not exist. Use the FEEDBACK command to retrieve additional data about this error.
- 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.