API parameters

The parameters for the API commands are described below in alphabetical order.

approval profile
18 character name for an approval profile. Each approval profile name must be unique.

The CICS® Configuration Manager ISPF dialog limits the character set to AZ, 09, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API may impose their own character set restrictions.

approver role
18 character name for an approver role. Approver roles are included in the system authorization facility (SAF) resource key that the CICS Configuration Manager server sends to your external security manager (such as RACF®). The allowed values are determined by your external security manager. For more information on SAF resource keys, see Restricting access to API commands and resource definitions.
change package ID
18 character identifier for a change package. Each change package identifier must be unique.

The CICS Configuration Manager ISPF dialog limits the character set to az, AZ, 09, @, $, #, -, and _. Client applications using the API may impose their own character set restrictions.

checksum
8-digit hexadecimal number that represents the contents of an object, such as the attributes of a resource definition. For example, C3B3A8C1.

You can use checksums to quickly compare resource definitions of the same type, without comparing their individual attributes. For example, if two TRANDEF resource definitions have the same checksum value, it means that their attribute values are identical.

You can use the List command to return checksums. These checksums may be calculated from all the attributes of a resource definition, or a subset of the attributes, depending on the hashing scope specified by the List command.

CCV release
3 digits identifying the CICS Configuration Manager product version, release, and modification number.
CICS configuration
18 character name for a CICS configuration. Each CICS configuration name must be unique.

The CICS Configuration Manager ISPF dialog limits the character set to AZ, 09, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API may impose their own character set restrictions.

CICS release
3 digits identifying the CICS product version, release, and modification number. For example, 230 identifies version 2, release 3, modification 0.
CICS task number
Number of the CICS task that performed the API command.
context
Name of a context in a CICSPlex® SM data repository.
CSD DSN
Fully qualified data set name of a CICS system definition file with no enclosing quotes.
definition version
Version number of a resource definition in a CICSPlex SM context.
description
Up to 80 characters describing a CICS Configuration Manager repository object. Optional.

This is different to the description for a resource definition. The maximum length of the description for a resource definition is determined by CICS or CICSPlex SM.

element count
Number of list elements or repeating group elements to follow. An API command request that uses <ListElement> must, before the first <ListElement>, have a <ListCount> that specifies the number of list elements to follow.
event ID
CICS Configuration Manager journal event identifier. 16 hexadecimal digits. You can use this identifier to select the specific migration of a change package that you want to back out or import.
external reference
Optional alternative 132 character name for a change package. If you use a change control system, then you can use this parameter to link a CICS Configuration Manager change package to an object in your change control system. CICS Configuration Manager does not refer to this name.

The CICS Configuration Manager ISPF dialog limits the character set to az, AZ, 09, @, $, #, -, and _. Client applications using the API may impose their own character set restrictions.

hashing scope
Specified by the <HashingScope> element of a List command request. Determines whether or not the List command returns a checksum for each selected object, and which fields it uses to calculate the checksum returned in <HashingValue>.
integrity token
Checksum that represents the contents of an object, such as the attributes of a resource definition. 8 hexadecimal digits. For example, C3B3A8C1.

When calling the Delete or Update command, to avoid overwriting changes by other users, supply the integrity token from an earlier Inquire or Update command for the same object. If the object has changed since the earlier command, then the Delete or Update command performs no action.

For example, suppose that you want to retrieve and then update the attributes of a resource definition. First, use the Inquire command to retrieve the resource definition. Along with the attributes of the resource definition, the Inquire command returns an integrity token. Later, when you use the Update command to update the attributes, supply this integrity token. The Update command calculates a new checksum for the resource definition, and compares it with the integrity token that you supplied. If the values do not match, then it means that the resource definition has been updated since your Inquire command, and the Update command rejects your update.

journal record type
Record type in the CICS Configuration Manager journal:
  • BAImage
  • EventStart
  • EventData
  • EventEnd

For details, see Journal objects.

location name
Name of the location containing the data that you want to work with. This must be appropriate to the location type:
location type
location name
CConfig
CICS configuration name. Required.
Context
CICSPlex SM context name. Required.
CSD
Fully qualified data set name of a CICS system definition file with no enclosing quotes. Required.
Journal or Repository
Not applicable: do not specify. If you do specify a location name, it is ignored.
location type
Type of the location containing the data that you want to work with. Must be one of the following:
CConfig
CICS configuration
Context
CICSPlex SM context
CSD
CICS system definition file
Journal
CICS Configuration Manager journal
Repository
CICS Configuration Manager repository
migration scheme
18 character name for a migration scheme. Each migration scheme name must be unique.

The CICS Configuration Manager ISPF dialog limits the character set to AZ, 09, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API may impose their own character set restrictions.

object instance
Identifies a specific version of an object in the CICS Configuration Manager repository or journal. 8 hexadecimal digits for a repository object, 26 for a journal object. For example, 00000001 for a repository object, BC2AD2211C69FA000000000114 for a journal object.

The object instance is returned by the List command. You can specify an object instance to the Delete or Inquire command to delete a specific version of a repository object, or retrieve a specific version of a journal object. You need to specify object criteria to identify the object, and then, additionally, specify the object instance to identify a version of that object. The object instance is similar to a version number; on its own, it does not uniquely identify an object.

object name
Name of a resource definition or a CICS Configuration Manager repository object.
object type
One of the object types listed in API object types. Required.

Some commands allow the literal All or * to indicate all object types. For details, see the individual command descriptions.

remote system connection
Name of a remote system connection defined in a CICS configuration. This must match the name of a connection resource definition in the CICS configuration. The connection resource definition refers to the remote CSD-based CICS region on which you want to perform an action, such as "install". For details, see Optional: Configure the agent for CSD-based CICS regions.
reason code
See Reason codes.
resource group
Name of a group in a CSD file or a RESGROUP in a CICSPlex SM data repository.
resource name
Name of a resource definition.
resource type
One of the resource definition object types supported by CICS Configuration Manager. For details, see Resource definition objects.

Some commands allow you to use the value * (asterisk) or All to specify all resource definition object types. You cannot use masked values to specify a subset of types: you must specify a single type or all types.

restriction field name
Name of the field (that is, the resource definition attribute) whose value you want to restrict in the List command response.
restriction field value
Value of the field (that is, the resource definition attribute) to be used for restriction criteria in the List command.

Values for attributes which are limited to specific values cannot contain a masking character. For other attributes, you may use the following masking characters:

*
Matches zero or more characters
+
Matches any single character
restriction operator
One of the following comparison operators:
EQ
Equal to
NE
Not equal to
LT
Less than
GT
Greater than
LE
Less than or equal to
GE
Greater than or equal to
return code
See Return codes.
SAF class
The SAF resource class that the CICS Configuration Manager server uses for security checks. For details, see Restricting access to API commands and resource definitions.
SAF prefix
The character string that the CICS Configuration Manager server prepends to security keys. For details, see Restricting access to API commands and resource definitions.
sequence
Integer identifying the order in which journal records were created for a particular event.
SMF system identifier
Four-character MVS™ System Management Facilities (SMF) system identifier. Identifies the MVS system that runs the CICS Configuration Manager server.
time stamp
Date and time, in the format:
ccyy/mm/dd hh:mm:ss.th
ccyy
Year. Four digits (00019999).
mm
Month. Two digits (0112).
dd
Day of the month. Two digits (0131).
hh
Hour, in 24-hour clock format. Two digits (0023).
mm
Minutes. Two digits (0059).
ss
Seconds. Two digits (0059).
th
Tenths and hundredths of a second. Two digits (0099).

For example, the following time stamp represents midday, 20 July 2005:

2005/07/20 12:00:00.00
trace flag
IBM® internal use only.
transformation rule set
18 character name for a set of transformation rules. Each set name must be unique.

The CICS Configuration Manager ISPF dialog limits the character set to AZ, 09, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API may impose their own character set restrictions.

transformation variable name
18 character name for a transformation variable. Each variable name must be unique.

The CICS Configuration Manager ISPF dialog limits the character set to AZ, 09, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API may impose their own character set restrictions.

transformation variable value
Allowed values depend on how the transformation variable is used in the transformation rule.