EXPAND

Description

This command supports the expansion of summary result sets. The command accepts a token from a summarized result set produced by the GROUP command, and a selected record identified by the position of the record pointer in the result set to be expanded. The position of the record pointer depends on the options that you specify on the command. It creates a new result set that contains all the records that are summarized in a summary record.

Related commands

FETCH, GET, GROUP, LOCATE, MARK, ORDER, QUERY, REFRESH, SPECIFY FILTER, UNMARK

Options

BACKWARD(data-value)

Expands the record at the position arrived at by moving backwards from the current pointer position for data-valuenumber of records. If the data-value value is greater than the remaining number of records, the first record in the summary result set is expanded.

BOTTOM

Expands the last record in the summary result set.

COUNT(data-ref)

The number of resource table records in the TO result set after this operation is complete. This parameter is output-only.

CURRENT

Expands the current record in the FROM result set.

FILTER(cpsm-token)

Identifies the filter to be used for this operation and performs an EXPAND operation on the record or records that match the filter criteria. It is used with the FIRST, LAST, NEXT and PREV options.

FIRST

Expands either the first marked record in the result set or the first record that matches the filter criteria. If no record is found, a NODATA code is returned.

FORWARD(data-value)

Expands the record at the position arrived at by moving forwards from the current pointer position for data-value number of records. If the data-value value is greater than the remaining number of records in the summary result set, the last record is expanded.

FROM (cpsm-token)

The summary result set on which the EXPAND command is to operate. If no matching result set can be found, an INVALIDPARM return code is issued with a reason code of FROM.

LAST

Expands either the last marked record in the result set or the last record that matches the filter criteria. If no record is found, a NODATA code is returned.

MARKED

Expands one or more records that have been selected using the MARK command. It is used in conjunction with the FIRST, LAST, NEXT, and PREV options.

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

NEXT

Starting at the record currently selected and moving forward through the result set, NEXT expands either the next marked record or the next record that matches the filter criteria. If no record is found, a NODATA code is returned.

NOTFILTER(cpsm-token)

Identifies the filter that is to be used for this operation and performs an EXPAND operation on the record or records that do not match the filter criteria. It is used in conjunction with the FIRST, LAST, NEXT and PREV options.

NOTMARKED

Expands one or more records that have been left unselected by the MARK command. It is used in conjunction with the FIRST, LAST, NEXT and PREV options.

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

POSITION(data-value)

Expands the record at a position in the summary result set indicated by the supplied value.

PREVIOUS

Starting at the record currently selected and moving backwards through the result set, PREVIOUS expands either the next marked record in the result set or the next record that matches the filter criteria. If no record is found, a NODATA code is returned.

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.

THREAD(cpsm-token)

The API thread to be used for the EXPAND operation. The cpsm-token value that identifies a thread is returned by the CONNECT command.

TO (cpsm-token)

Identifies the summary result set to contain the expanded records on which the EXPAND command operates. If this result set already exists, any existing resource table records that relate to it are replaced by the resource table records produced by this EXPAND command.

TOP

Expands the first record in the summary result set.

Conditions