GET

Identify and optionally return a result set containing selected resource table records.

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

Read syntax diagramSkip visual syntax diagramGETOBJECT(data-value) TESTCOUNT(data-ref)CRITERIA(data-area)LENGTH(data-value)FILTER(cpsm-token)PARM(data-area)PARMLEN(data-value)NOWAITTOKEN(data-value)CONTEXT(data-value)SCOPE(data-value)RESULT(cpsm-token) THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

Description

This command identifies a result set containing selected resource table records. The command returns the identified records, or a count of the identified records, or both the records and the count.
  • The resource table can be one that represents a CICS® resource, a CICSPlex® SM or CICS definition, or a CICSPlex SM runtime object.
  • After a GET command, the record pointer is positioned to the top of the result set (that is, the first record in the result set).
  • If the context and scope in effect when you issue a GET command include CICS systems that do not support the requested resource table, the request is ignored for those CICS systems.
  • In some CICS environments, the resource table attribute values that are returned by CICSPlex SM for:
    Resource table Attribute value CICS Environment
    LOCTRAN RESSEC(RESSECEXT) CICS/MVS
    do not match the CVDA values returned by CICS. The values returned by CICS conflict with CVDA values in other CICS environments. To retain the attributes' uniqueness, CICSPlex SM adds 9000 to the values returned by CICS. For more information about translating CVDA values, see TRANSLATE command.

Related commands

  • DISCARD
  • FETCH
  • GETDEF
  • QUERY
  • RECEIVE
  • REFRESH
  • SPECIFY FILTER
  • SPECIFY VIEW

Options

CONTEXT(data-value)
Identifies the context for this command. The context must be the 1- to 8-character name of a CMAS or CICSplex.

If you do not specify the CONTEXT option, the default context for the thread is assumed.

COUNT(data-ref)
Names a variable to receive the number of resource table records in the target result set after this operation is complete.
CRITERIA(data-area)
Identifies a buffer containing the filter expression to be used for this operation. The CRITERIA option retrieves only those resource table records that meet the specified filter criteria.
FILTER(cpsm-token)
Identifies a filter to be used for this operation. The FILTER option retrieves 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.

LENGTH(data-value)
A fullword value that specifies the length of the CRITERIA buffer.
Note: The buffer length you specify should not include any data other than a filter expression.
NOWAIT
Returns control to your program as soon as the GET 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.

Note: If you specify the TOKEN option, the NOWAIT option is assumed by default.
OBJECT(data-value)
Identifies the resource table for which records are to be retrieved. This value must be the 1- to 8-character name of either a valid resource table or a valid view. If you are using the TEST parameter, you must specify a CICS resource table name for OBJECT. Specifying any other value, including a view name, results in an error.
PARM(data-area)
Identifies a buffer containing the parameter expression to be used in preselecting resource table records.

For details on how to use a parameter expression with the GET command, see Using the PARM option. For a description of the parameters that can be specified for a given resource table, see CICSPlex SM resource tables.

PARMLEN(data-value)
A fullword value that specifies the length of the PARM buffer.
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
  • GROUP
  • PERFORM OBJECT

CICSPlex SM replaces the contents of the existing result set with the resource table records requested by this GET command.

If this field is set to binary zero (in COBOL, C®, PL/I or Assembler) or an uninitialized variable (in REXX), CICSPlex SM creates a new result set and returns its identifying token in the same field.

If you are using the TEST parameter, you must specify a zero value for RESULT. Specifying any other value results in an error.

SCOPE(data-value)
Identifies the scope for this command.
If the current context (as set by this command or by a previous CONNECT or QUALIFY command) is a CICSplex and the OBJECT option identifies a CICS resource, a valid scope is required. The scope can be one of the following:
  • The 1- to 8-character name of the CICSplex itself
  • A CICS system or CICS system group in the CICSplex
  • A logical scope, as defined in a CICSPlex SM resource description (RESDESC)

If OBJECT identifies a CICS definitional resource and the PARM option includes the CSDGROUP parameter, a valid scope can be specified. The scope can be a CICS system in the CICSplex.

If the current context is a CMAS or the OBJECT option identifies any other type of resource table, this option has no meaning and is ignored.

If you do not specify the SCOPE option, the default scope for the thread is assumed. If the current context is a CICSplex and no default scope has been set on a CONNECT or QUALIFY command, you receive an INVALIDPARM response for the SCOPE option.

TEST
Returns only a count of the records that match the request. If you specify TEST, the request returns no records. If you specify TEST, you must specify a CICS resource name for the OBJECT parameter, and a zero value for the RESULT parameter.
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 GET 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 GET request is complete.

Conditions

The following is a list of the RESPONSE values that can be returned by the GET command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.
1024 OK
The command completed processing successfully.
1025 SCHEDULED
The command has been scheduled for processing.
1026 NOTFOUND
A not found condition occurred for the following reason:
1310 ATTRIBUTE
An attribute specified in the CRITERIA buffer was not found for the specified resource table.
1027 NODATA
No records were found that matched the specified search criteria.
1028 INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • 1280 THREAD
  • 1281 OBJECT
  • 1282 CONTEXT
  • 1283 RESULT
  • 1285 LENGTH
  • 1286 FILTER
  • 1294 SCOPE
  • 1299 CRITERIA
  • 1306 TOKEN
  • 1315 PARM
  • 1316 PARMLEN

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.
1342 REQTIMEOUT
One of the CMASs or MASs to which the request was directed did not respond.

If only some of the CMASs or MASs did not respond, the GET command can still yield a valid result. COUNT might be greater than zero and RESULT might be non-zero. Such a result set contains data from those CMASs and MASs that did respond.

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.
1378 NOTPROCESSED
One of the MASs to which the request was directed could not process the request.
1031 NOTPERMIT
A not permitted condition occurred for the following reason:
1345 USRID
The user ID associated with the processing thread does not have the required security authorization.
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:
1294 SCOPE
Either none of the MASs in the specified scope are available or none of them support the requested resource table.
1323 MAINTPOINT
The maintenance point for the current context is not available.
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.
1362 CMAS
A CMAS to which the request was directed is not available.
1366 WORKLOAD
The workload identified on the API request is not available on the local CMAS.
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 one of the following reasons:
1285 LENGTH
The total length of all the options on the command exceeds the maximum limit.
1286 FILTER
The filter expression passed on the operation is too large or complex.
1037 WARNING
The command completed processing with a warning, for the following reason:
1369 MAXRECORDS
The number of records added to the result set by a MAS would have exceeded the MAXHISTRECS value for that MAS. Records within the MAXHISTRECS limit have been added to the result set. Modify the FILTER or PARM parameter values to increase or reduce the number of records the MAS should add to the result set.
Note: If a scope is specified that contains more than one MAS, the total number of records collected can exceed the MASHISTRECS value for an individual MAS.
1038 TABLEERROR
A resource table record is invalid for the following reason:
1361 DATAERROR
The value associated with one or more resource table attributes is invalid. Use the FEEDBACK command to retrieve additional data about this error.
1041 INVALIDATA
Invalid data was detected. The parameter that contains invalid data is returned as the reason value:
1299 CRITERIA
An attribute value listed in the CRITERIA buffer is not valid for the specified attribute.