GROUP
Return a summarized result set.
Description
This command returns a summarized
result set by grouping some or all of the resource table records in
a result set.
- The target result set can be an existing result set or a new one
that is created by this process. If you specify an existing result
set as the target of a GROUP command:
- It must be a summarized result set that was produced by a previous GROUP command against the same source result set.
- It must contain the same type of resource table records currently found in the source result set.
- The existing records in the result set are overwritten.
- To create a summarized result set from selected records of a source
result set, you can use:
- The SPECIFY FILTER command to define a filter for the source result set.
- The MARK and UNMARK commands to mark records in the source result set.
- The GROUP command may be used only for attributes with a length of 251 or less. A RESPONSE(INVALIDPARM) REASON(BY) error occurs for attribute lengths greater than 251.
- For more information on processing summarized result sets, see Developing CICSPlex SM applications.
Related commands
DISCARD, EXPAND, FETCH, GET, LOCATE, MARK, ORDER, QUERY, SPECIFY FILTER
Options
- ALL
- Summarizes all the resource table records in the source result set.
- BY(data-value)
- Identifies the resource table attribute whose value is to be used as the grouping factor for this operation. This value must be the 1- to 12-character name of a valid attribute for the resource table.
- COUNT(data-ref)
- Names a variable to receive the number of resource table records in the target result set after this operation is complete.
- FILTER(cpsm-token)
- Identifies a filter to be used for this operation. The FILTER
option summarizes 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.
- FROM(cpsm-token)
- Identifies the source result set for this operation. The result
set can be one produced by any of these commands:
- COPY
- GET
- PERFORM OBJECT.
Note: If you discard the source result set, all of the summarized result sets that were created from it are also discarded. - LENGTH(data-value)
- A fullword value that specifies the length of the SUMOPT buffer.
Note: The buffer length you specify should not include any data other than a summary expression.
- MARKED
- Summarizes only those resource table records that are marked in the source result set. 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 summarizes only those resource table records that do not meet
the specified filter criteria.
The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.
- NOTMARKED
- Summarizes only those resource table records that are not marked in the source result set. You can mark resource table records by using the MARK and UNMARK commands.
- 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.
- SUMOPT(data-area)
- Identifies a buffer containing the summary expression
to be used for this operation. The SUMOPT value overrides the default
summary options for the resource table attributes.
For details on how to form a summary expression, see Developing CICSPlex SM applications. For a list of the default summary options for a given resource table, see the CICSPlex SM resource tables.
- 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.
- TO(cpsm-token)
- Identifies the target result set for this operation. If this field is:
- Set to binary zero (in COBOL, C, PL/I or Assembler)
- An uninitialized variable (in REXX).
Otherwise, you can specify an existing summarized result that was produced by a previous GROUP command against the result set specified in the FROM option. That is, you can reuse a summarized result set, but only to resummarize the records in the same result set.
Note: If you specify the token of a previously produced summarized result set, make sure the result set still exists. When you discard a source result set, all of the summarized result sets that were created from it are also discarded.
Conditions
The following is a list of the
RESPONSE values that can be returned by the GROUP command. The description
of each RESPONSE includes a list of associated REASON values, if appropriate.
- OK
- The command completed processing successfully.
- NODATA
- No records were found that matched the specified search criteria.
- BUSY
- A busy condition occurred for one of the following reasons:
- FROM
- The source result set specified on the FROM option is being processed by another command.
- TO
- The target result set specified on the TO 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.
- 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.
- 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. The parameter that is invalid
is returned as the reason value:
- BY
- FILTER
- FROM
- LENGTH
- NOTFILTER
- SUMOPT
- THREAD
- TO.
- 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 is connected is not available for API processing.
- 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.