GETDEF

Return a result set containing selected descriptive records for a resource table.

Read syntax diagramSkip visual syntax diagramGETDEFOBJECT(data-value) RESOURCE(data-value)ATTRIBUTE(data-value)ACTION(data-value)ACTIONPARM(data-value)COUNT(data-ref)REPLACEADDRESULT(cpsm-token) THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

Description

This command returns a result set containing selected descriptive records for a resource table.
  • GETDEF is a variation of the GET command. GET retrieves data records for the resource represented by a table. GETDEF, on the other hand, retrieves internal data that describes the resource table itself.
  • The GETDEF command retrieves its data, which is called meta-data, from internal resource tables that describe each of the external resource tables. These internal resource tables are called CPSM MetaData tables. The attributes of a CPSM MetaData table are the characteristics of the external table, not the resource that it represents. For a list of the CPSM MetaData resource tables that can be retrieved by GETDEF, see the description of the OBJECT option, Object.
  • You can use GETDEF to find out what resource tables are available for processing by other commands. In addition, you can identify the attributes of a resource table, the values allowed for its modifiable attributes, and the actions that can be performed on it. You can also use GETDEF to request descriptions of the CPSM MetaData resource tables themselves.
  • You can use the GETDEF command only with resource tables supplied by CICSPlex SM. GETDEF is not valid for user-defined views of a resource table that were created by the SPECIFY VIEW command.
  • You cannot use the REFRESH command to refresh the data records retrieved by GETDEF.

Related commands

DISCARD, FETCH, GET, LOCATE, QUERY

Options

ACTION(data-value)
The 12-character name of an action against the resource table for which CPSM MetaData records are to be retrieved.
ACTIONPARM(data-value)
The 12-character name of a parameter to an action against the resource table for which CPSM MetaData records are to be retrieved, as it appears in the API parameter string.
ADD
Adds the CPSM MetaData resource table records that are being retrieved to an existing target result set. If no existing result set is specified as the target, the ADD option is ignored.
ATTRIBUTE(data-value)
Identifies one or more attributes of the resource table specified on the RESOURCE option for which CPSM MetaData records are to be retrieved.

Depending on which CPSM MetaData table is named in the OBJECT option, this value can be the 1- to 12-character name of a specific attribute or an asterisk (*), for all attributes in the resource table. If you do not specify the ATTRIBUTE option for an OBJECT that does not require it, data is retrieved for all attributes in the resource table.

For details on the CPSM MetaData resource tables and the valid ATTRIBUTE values for each, see the description of the OBJECT option.

COUNT(data-ref)
Names a variable to receive the number of resource table records in the target result set after this operation is complete.
OBJECT(data-value)
Identifies the type of meta-data to be retrieved for the resource table specified on the RESOURCE option. This value must be one of the following CPSM MetaData resource table names:
OBJECT
One record is returned for each instance of the resource table specified on the RESOURCE option. The record describes the resource table's general characteristics. Related options and restrictions include:
  • ACTION is ignored.
  • ATTRIBUTE is ignored.
  • ACTIONPARM is ignored.
  • RESOURCE must be a specific resource table name or * for all resource tables.
OBJACT
One record is returned for each action that is available for the resource table specified on the RESOURCE option.
Related options and restrictions include:
  • ACTION is normally omitted. If present, it may specify the name of an action or *.
  • ATTRIBUTE is ignored.
  • ACTIONPARM is ignored.
  • RESOURCE must be a specific resource table name; a value of * is not allowed.
METADESC
One record is returned for each attribute of the resource table specified on the RESOURCE option. Each record provides only the basic structure of the attribute, including the name, data type, length, and offset in the resource table. Such information might be useful for accessing the attribute fields in a buffer returned by the FETCH command.
Related options and restrictions include:
  • ACTION is ignored.
  • ATTRIBUTE can be a specific attribute name or * for all attributes in the resource table.
  • ACTIONPARM is ignored.
  • RESOURCE must be a specific resource table name; a value of * is not allowed.
ATTR
One record is returned for each attribute of the resource table specified on the RESOURCE option. Each record provides complete information about the attribute.
Related options and restrictions include:
  • ATTRIBUTE can be a specific attribute name or * for all attributes in the resource table.
  • RESOURCE must be a specific resource table name; a value of * is not allowed.
ATTRAVA
One record is returned for each of the EYUDA or CVDA values that are valid for the specified attribute.
Related options and restrictions include:
  • ATTRIBUTE must be the name of a specific attribute that has a data type of EYUDA, CVDAS, or CVDAT.
  • RESOURCE must be a specific resource table name; a value of * is not allowed.
Note: The AVAAVAIL attribute of the ATTR internal resource table indicates whether an AVA list is available for a given attribute.
METANAME
One record is returned for each CVDA and EYUDA. The RESOURCE, ATTRIBUTE, ACTION and ACTIONPARM keywords are ignored.
METAPARM
One record is returned for every parameter for the specified RESOURCE and ACTION.
  • ACTION must be a specific action name; a value of * is not allowed.
  • ACTIONPARM is ignored.
  • RESOURCE must be a specific table; a value of * is not allowed.
PARMAVA
One record is returned for the specified RESOURCE, ACTION, and ACTIONPARM.
  • ACTION must be a specific action name; a value of * is not allowed.
  • ACTIONPARM must be a specific parameter name; a value of * is not allowed.
  • RESOURCE must be a specific table; a value of * is not allowed.
REASON(data-ref)
Names a variable to receive the fullword reason value returned by this command.
REPLACE
Deletes the contents of an existing target result set and replaces them with the results of this operation. If the operation does not result in any CPSM MetaData resource table records being selected, the target result set is discarded.

If no existing result set is specified as the target, the REPLACE option is ignored.

RESOURCE(data-value)
Identifies the resource table for which CPSM MetaData records are to be retrieved.

If you specify the ATTRIBUTE option, this value must be the 1- to 8-character name of a specific CICSPlex SM resource table. Otherwise, you can specify a value of asterisk (*) to retrieve data for all resource tables.

Note: You can use GETDEF only with resource tables supplied by CICSPlex SM. GETDEF is not valid for user-defined views of a resource table that were created by the SPECIFY VIEW 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 GETDEF command. If the operation does not result in any resource table records being selected, the target result set is discarded.
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 result set and returns its identifying token in the same field.
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 GETDEF command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.
OK
The command completed processing successfully.
NODATA
OBJACT was specified with the OBJECT option, but there are no actions defined for the specified RESOURCE.
BUSY
A busy condition occurred for the following reason:
RESULT
The result set specified on the RESULT 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.
INCOMPATIBLE
An incompatible condition occurred for the following reason:
INVALIDOBJ
The target result set specified on the RESULT option is not compatible with the output of this command. The result set must contain the same type of meta-data (as specified on the OBJECT option) as the command produces.
INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • ACTION
  • ACTIONPARM
  • ATTRIBUTE
  • OBJECT
  • RESOURCE
  • RESULT
  • THREAD.
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.
TABLEERROR
A resource table record is invalid for one of the following reasons:
DATAERROR
The value associated with one or more resource table attributes is invalid. Use the FEEDBACK command to retrieve additional data about this error.
INVALIDVER
The specified version of the resource table is not supported by CICSPlex SM.
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.