This section describes various ways in which you can modify the resources managed by CICSPlex® SM. The actions described here are issued against resource table records in a result set. However, the changes that you request are made to the actual resources which those records represent.
You can change the current value of a resource attribute by using the SET or UPDATE command. SET modifies the attributes of a CICS® resource, while UPDATE modifies CICSPlex SM and CICS definitions. The MODIFY option of these commands accepts a modification expression, which is a character string that defines the attribute changes to be made.
A modification expression can be made up of one or more attribute expressions in the form:
Modification Expression .-,----------. V | >>---attr=value-+-.--------------------------------------------><
where:
DESCRIPTION=‘Payroll.OCT’
DESCRIPTION=‘October’’s Payroll’
For example, to disable one or more local transactions (LOCTRAN), you could specify:
STATUS=DISABLED.
in the MODIFY option of a SET command.
If you issue a SET command against CICS systems that do not support the requested modification, the request is ignored for those CICS systems. If your context and scope consist solely of CICS systems that do not support the modification, you receive RESPONSE and REASON values of NOTAVAILABLE SCOPE.
To change the task storage location of a CICS transaction definition (TRANDEF), you could specify:
TASKDATALOC=ANY
in the MODIFY option of an UPDATE command.
Note that the MODIFY option of UPDATE is valid only for CICS Definition resource tables.
For a list of the attributes for each resource and their valid values, refer to the CICSPlex System Manager Resource Tables Reference.
In addition to modifying individual attributes, you can also perform actions against many resources by using either of the PERFORM commands; PERFORMáOBJECT or PERFORMáSET. The difference between these two commands is that PERFORMáSET performs an action against the resource table records in an existing result set, while PERFORMáOBJECT first creates a result set and then performs the requested action.
Some actions are self-contained and self-explanatory; specifying the action is enough to indicate the changes to be made to the resource. For example, you can discard a local file by issuing the DISCARD action against a LOCFILE resource table record.
Some actions are self-contained and self-explanatory; specifying the action is enough to indicate the changes to be made to the resource. For example, you can discard a local file by issuing the DISCARD action against a LOCFILE resource table record.
Other actions require you to specify additional parameters. For these actions a parameter expression you might require a parameter expression to obtain the function you need. A parameter expression can be made up of one or more parm expressions in the form:
Parameter Expression .-----------. V | >>---parm_expr-+-.--------------------------------------------->< parm_expr:: |--+-parm_name----+---------------------------------------------| '-.parm_value.-'
where:
Multiple instances of parm_exp should be delimited by spaces. The parameter expression buffer is terminated with a period (.).
For example:
PARM('BUSY(cvda).')
where cvda is
a valid CVDA value for the file busy condition.PARM('DUMPCODE(PMR12345) TITLE('Doc for PMR12345').')
Note
that if the parm_value contains special characters such as spaces
or periods, the value must be enclosed in single quotes. Also note
that all parameter values are folded to upper case.The PERFORM OBJECT command does not require an existing result set, as it will effectively run a GET command followed be a PERFORM SET. In this case any parameter expression may be passed on the GET or PERFORM SET phase of the command depending on whether the parameter expression is valid on the GET or PERFORM SET as follows:
For a list of the valid actions for each resource and their required parameters, refer to the CICSPlex System Manager Resource Tables Reference.
When you work with CICSPlex SM and CICS definitions there are some special API commands and command options available.
You can use the following API commands to maintain the CICSPlex SM and CICS definitions in your data repository:
With each of these commands, you use the FROM option to supply a CICSPlex SM Definition
or CICS definition resource table record for the definition you are
working with. The record must include all of the attributes in the
resource table for the definition. If you do not want to specify certain
optional attributes, you must set those fields to null (that is zero)
values.
As an alternative, when you are updating CICS definitions, you can use the RESULT and MODIFY options of the UPDATE command. These options enable you to modify multiple definitions at one time (this is the equivalent of issuing the ALTER action command from the CICSPlex SM end-user interface).
To update CICS definitions, identify a result set that contains CICS Definition resource table records in the RESULT option. Then use the MODIFY option to specify the changes to be made to the definitions. MODIFY accepts a modification expression, as described in Modifying resource attributes.
When you work with existing CICSPlex SM or CICS definitions, keep in mind that the first 8 bytes of each record contain an attribute called CHANGETIME, which reflects the date and time at which the record was last modified. CICS Definition records also include a CREATETIME attribute, which is the date and time at which the definition was created.
The CHANGETIME and CREATETIME attributes are maintained internally by CICSPlex SM; you should not attempt to modify these attribute values. When you update or remove a definition resource table record, the CHANGETIME and CREATETIME values you return to CICSPlex SM must be the same values you received.
For most CICSPlex SM and CICS definitions, all of the information needed to process an API request is included in the attributes of the resource table. Some definitions, however, allow you to supply optional data and some actually require additional data. For those definitions, you have to specify the PARM option on the appropriate API command:
The PARM option accepts a parameter expression, which is a character string that defines the parameters required for a definition to be processed.
For example, suppose you want to create an LNKSMSCG definition, which is a CICSPlex SM definition that describes the association between a CICS system group and a monitor specification (MONSPEC). Before CICSPlex SM can process your request, it must know how to handle other links that may be affected by the change. So when you issue the CREATE command, you must specify a parameter expression like this on the PARM option:
PARM('FORCE.')
which tells CICSPlex SM that all CICS systems in the CICS system group are to inherit the new specification.
The PARM option is especially useful when working with CICS definitions. For each CICS Definition resource table there is another resource table that describes the definition's association with a resource group (RESGROUP), if one exists. For example, the CONNDEF resource table represents a connection definition and the CONINGRP resource table represents an association between a connection definition and a resource group. The RESGROUP parameter provided with the CREATE and GET commands for CICS Definitions simplifies the processing of these records.
When you create a CICS Definition record, you can identify an existing resource group to which the definition should be added. To do this, use the PARM option to identify the resource group like this:
PARM('RESGROUP(resgroup).')
Using the RESGROUP parameter automatically creates an xxxINGRP record (such as a CONINGRP record), which describes the association between the CICS definition and its resource group.
When you use the GET command to request CICS Definition records from the data repository, you can select definitions according to the resource group to which they belong. To do this, use the PARM option to identify the resource group like this:
PARM('RESGROUP(resgroup).')
which tells CICSPlex SM to select CICS definitions only from the specified resource group. If you do not use the PARM option, CICSPlex SM selects definitions from all resource groups, according to the other criteria you specify on the GET command.