API parameters
Many API commands use a common subset of parameters. Rather than repeating the descriptions of these common parameters for each command, the parameters are described in the following list.
- approval profile
- 1 - 8
character name for an approval profile. Each approval profile name
must be unique.
The CICS® Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API might impose their own character set restrictions.
- approver role
- 1 - 8 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
- 1 - 8
character identifier for a change package. Each change package identifier
must be unique.
The CICS Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, a-z, @, $, #, -, 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
- 1 - 8
character name for a CICS configuration. Each CICS configuration
name must be unique.
The CICS Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API might 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 1 - 32 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 0-9, A-Z, a-z, @, $, #, -, 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
- 1 - 8
character name for a migration scheme. Each migration scheme name
must be unique.
The CICS Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API might 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.
- qualification exit data
- Freeform text string passed to an exit program that is attached to an operations qualification exit point. For details, see Extending and customizing the CICS Configuration Manager server with user exits.
- 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 (0001 - 9999).
- mm
- Month. Two digits (01 - 12).
- dd
- Day of the month. Two digits (01 - 31).
- hh
- Hour, in 24-hour clock format. Two digits (00 - 23).
- mm
- Minutes. Two digits (00 - 59).
- ss
- Seconds. Two digits (00 - 59).
- th
- Tenths and hundredths of a second. Two digits (00 - 99).
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 group
1 - 8 character name for a group of transformation rule sets. Each group name must be unique. A transformation group cannot have the same name as a transformation rule set.
The CICS Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API might impose their own character set restrictions.
- transformation rule set
1 - 8 character name for a set of transformation rules. Each set name must be unique. A transformation rule set cannot have the same name as a transformation group.
The CICS Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API might impose their own character set restrictions.
- transformation variable name
- 1 - 8
character name for a transformation variable. Each variable name must
be unique.
The CICS Configuration Manager ISPF dialog limits the character set to 0-9, A-Z, @, $, #, -, and _. The CICS Configuration Manager server converts lowercase characters to uppercase, but does not limit the character set further. Client applications using the API might impose their own character set restrictions.
- transformation variable value
- Allowed values depend on how the transformation variable is used in the transformation rule.