GROUP

Return a summarized result set.

Read syntax diagramSkip visual syntax diagramGROUPBY(data-value) FROM(cpsm-token) TO(cpsm-token) ALLFILTER(cpsm-token)MARKEDNOTFILTER(cpsm-token)NOTMARKEDCOUNT(data-ref)SUMOPT(data-area)LENGTH(data-value)THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

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).
CICSPlex SM creates a new summarized result set and returns its identifying token in the same field.

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.
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 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.