ORDER

Sort the resource table records in a result set.

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

Description

This command sorts the resource table records in a result set into a user-specified order.

By default, records are sorted by the key attributes for the resource table.
The sort order you specify for a result set remains in effect until you issue another ORDER command.
If the result set contains deleted records, those records are included in the sorting process. They are sorted by the same attributes as other records and their position in the newly ordered result set may be difficult to determine. To prevent this happening, issue the REFRESH command before issuing ORDER; REFRESH removes any deleted records from the result set.

Related commands

COPY
GET
GETDEF
GROUP
LOCATE
PERFORM OBJECT

Options

BY(data-area)

Identifies a buffer containing the order expression to be used for this operation.

An order expression is a list of attributes to be used in sorting the resource table records. For example:

  CICSSYS,TRANID.

where the attribute names are separated by commas or blank spaces and the whole expression ends with a period.

In this example, the resource table records are sorted using CICS® system name as the primary sort key and transaction ID as the secondary key. The default sort order is ascending. To sort attribute values in descending order, add /D to the end of the attribute name.

For more information on using order expressions with the ORDER command, see An overview of the CICSPlex SM API.

LENGTH(data-value)

A fullword value that specifies the length of the BY buffer.

Note: The buffer length you specify should not include any data other than an order expression.

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

Conditions

The following is a list of the RESPONSE values that can be returned by the ORDER command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.

1024 OK

The command completed processing successfully.

1028 INVALIDPARM

An invalid parameter was detected. The parameter that is invalid is returned as the reason value:

1280 THREAD
1283 RESULT
1285 LENGTH
1300 BY

Check the command description for valid parameter syntax.

1029 FAILED

The command failed for one of the following reasons:

1331 ABENDED: Command processing abended.
1359 EXCEPTION: Command processing encountered an exceptional condition.

1030 ENVIRONERROR

An environment error occurred for one of the following reasons:

1321 SOCRESOURCE: A required resource that is owned by the CMAS is not available.
1357 NOSTORAGE: The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
1358 NOSERVICE: The application stub program could not load the API service module.

1032 BUSY

A busy condition occurred for the following reason:

1283 RESULT: The result set specified on the RESULT option is being processed by another command.

1033 SERVERGONE

The CMAS to which the processing thread was connected is no longer active.

1034 NOTAVAILABLE

A not available condition occurred for one of the following reasons:

1334 CPSMAPI: The CMAS to which the processing thread is connected is not available for API processing.
1340 APITASK: The API control subtask is not active.

1035 VERSIONINVL

A version conflict occurred for one of the following reasons:

1335 NOTSUPPORTED: The version of the application stub program used for this command is not supported.
1336 NOTVSNCONN: The version of the application stub program used for this command is not the same as the version used with the CONNECT command.

1036 INVALIDCMD

The command is invalid for the following reason:

1285 LENGTH: The total length of all the options on the command exceeds the maximum limit.