Modifying managed resources

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.

Modifying resource attributes

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:

Read syntax diagramSkip visual syntax diagramModification Expression
 
   .-,----------.
   V            |
>>---attr=value-+-.--------------------------------------------><
 

where:

attr
Is the name of a modifiable attribute in the resource table.
value
Is the value to which you want the attribute set. The following restrictions apply:
Note:
Be sure to consider the quoting conventions of your programming language when using single quotes in a CICSPlex SM value string.
Note:
A modification expression must be followed by either blank spaces or null characters to the end of the specified buffer. That is, the buffer length you specify (using the LENGTH option) should not include any data other than a modification expression.

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.

Performing an action against a resource

Start of change

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:

Read syntax diagramSkip visual syntax diagramParameter 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:

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.

End of change

Working with CICSPlex SM and CICS definitions

When you work with CICSPlex SM and CICS definitions there are some special API commands and command options available.

Creating, updating, and removing definitions

You can use the following API commands to maintain the CICSPlex SM and CICS definitions in your data repository:

CREATE
Creates a new CICSPlex SM or CICS definition using the attribute values you specify. The new definition is stored in the data repository.
UPDATE
Updates an existing CICSPlex SM or CICS definition according to the attribute values you specify. The updated definition replaces the existing definition in the data repository.
REMOVE
Removes a CICSPlex SM or CICS definition from the data repository.

Notes:
  1. Before you can update or remove a definition you must use the FETCH command to retrieve the appropriate resource table record from a result set.
  2. For CICSPlex SM definitions that have a CICSplex as their context (such as workload management or real-time analysis definitions), any changes you make are automatically distributed to all the CMASs involved in managing the CICSplex.

Start of changeWith 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.End of change

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.

The CHANGETIME and CREATETIME 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.

Using the PARM option

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.

Note:
For a complete list of the CREATE, UPDATE, REMOVE, and GET parameters required (or supported) by a given resource table, see the CICSPlex System Manager Resource Tables Reference.
[[ Contents Previous Page | Next Page Index ]]