z/OS Utility

Steps

Allocate Data Set

Allocate a non-SMS-managed data set. Note: To create a GDG version add (+1) along with GDG base. An output property DatasetName will contain the actual GDG version dataset name that is created and can be referred in successive steps of the process.

Name Type Description Required
Average Record Unit Enumeration: K/M/U/— Select the unit to use when allocating average record length. U specifies single-record units (bytes). K specifies thousand-record units (kilobytes). M specifies million-record units (megabytes). (—) specifies the system default value. No
Block Size String Specify the number of bytes of data to place in each block, based on the record length. Yes
Data Set Name String Data set name. If the single quotation marks are omitted, the users data set prefix from the TSO profile is automatically appended to the front of the data set name. Yes
Data Set Name Type Enumeration: LIBRARY/PDS LIBRARY, PDS or Default() No
Delete Existing Data Set Boolean Select to delete dataset if already exist before allocation. No
Directory Blocks String The number of directory blocks to allocate. Specify zero for a sequential data set. Specifying LIBRARY in the data set name might override a setting of zero directory blocks. No
Primary Quantity String Specify the primary quantity in average record units. Yes
Record Format Enumeration: F,B/F/V,B/V/U/F,B,A/V,B,A/F,B,M/F,M/V,B,M/V,M   No
Record Length String   Yes
Secondary Quantity String Specify the secondary quantity in average record units. Yes
Space Units Enumeration: BLKS/TRACKS/CYLINDERS BLKS, TRKS, CYLS Yes
Volume Serial String Leave blank to use the system default volume. No

Allocate Data Set From Existing

Create a data set with the attributes of an existing model data set. Note: To create a GDG version add (+1) along with GDG base. An output property DatasetName will contain the actual GDG version dataset name that is created and can be referred in successive steps of the process.

Name Type Description Required
Data Set Name String Data set name. If the single quotation marks are omitted, the users data set prefix from the TSO profile is automatically appended to the front of the data set name. Yes
Delete Existing Data Set Boolean Select to delete dataset if already exist before allocation. No
Like String Specify the name of an existing data set to use as a model. The attributes of this data set are used as the attributes for the data set being allocated. If the single quotation marks are omitted, the users data set prefix from the TSO profile is automatically appended to the front of the data set name. Yes
Primary Quantity String Specify the primary quantity in space units. No
Secondary Quantity String Specify the secondary quantity in space units. No
Space Units Enumeration: —/BLKS/TRACKS/CYLINDERS BLKS, TRKS, CYLS or default() No
Volume Serial String Leave blank to use the system default volume. No

Allocate SMS Managed Data Set

Allocate an SMS-managed data set. Note: To create a GDG version add (+1) along with GDG base. An output property DatasetName will contain the actual GDG version dataset name that is created and can be referred in successive steps of the process.

Name Type Description Required
Data Class String Leave blank to use the default data class. No
Data Set Name String Data set name. If the single quotation marks are omitted, the users data set prefix from the TSO profile is automatically appended to the front of the data set name. Yes
Delete Existing Data Set Boolean Select to delete dataset if already exist before allocation. No
Management Class String Leave blank to use the default management class. No
Storage Class String Leave blank to use the default storage class. No

Copy Artifacts

Load artifacts from a local repository.

Name Type Description Required
Directory Offset String The working directory to use when running the command. This directory is relative to the current working directory. Yes

Copy Data Set

Copy a data set.

Name Type Description Required
Exclude Members String Specify a list of members in the source PDS to skip when copying. Separate member names with newline characters. No
From PDS String Specify the names of the source PDS, separated by newline characters. Use the following format: PDS-NAME (or) PDS-NAME,R. R specifies that all members of the source PDS replace any members with the same name in the target PDS. Yes
Include Members String Specify the members in the source PDS to copy, separated by newline characters. Use the following format: MEMBER-NAME (or) MEMBER-NAME, NEW-MEMBER-NAME[, R] (or) MEMBER-NAME,,R. To rename a member, specify the current name of the member, followed by the new name and optionally the R (replace) parameter. To replace a member, specify the name of the member and the R parameter, separated by two commas. No
Load Module Dataset Boolean Select to use the IEBCOPY COPYMOD control statement when copying load modules. No
To PDS String Specify the name of the target PDS. Yes

Deploy Data Sets

Deploy data sets and HFS files

Name Type Description Required
Allow Creating Data Set String Specify TRUE to create a data set if the specified target data set does not exist. No
Allow Creating Directory String Specify TRUE to create the directory if the specified HFS target directory does not exist. No
Backup for Rollback Boolean Select to create a backup of the data sets and files which are going to be replaced. A backup must exist to do rollback. No
Check Access Boolean Select to check permission to update the data sets to deploy. No
Container Filter String The filter to limit Source datasets to be deployed. Java regular expression matching is used if the filter starts and ends with a forward slash (/). For example, specify /.*LOAD/ to match any data set containers ending with LOAD. If the filter is not a regular expression, exact matching is used. Separate each filter with a newline character. No
Data Set Mapping String Specify a list of mapping rules for the data set packages, separated by newline characters. Use the following format: Source_Data_Set,Target_Data_Set. Use the asterisk (*) in the Source_Data_Set value to match any characters. If multiple rules specify the same Source_Data_Set value, only the first one is used. Use Source_Data_Set,DUMMY mapping to skip backup/deployment for a particular dataset. It will show as deployed at the environment level, but in actuality, the backup/deployment is skipped. No
Delete the Target Directory contents Boolean Select to delete all contents in the target folder and then deploy the artifacts from the selected version. Backup of the target directory will not be taken if this is set. Either the checkbox ‘Delete the Target Directory contents’ should be selected or the checkbox ‘Backup for Rollback’ checkbox should be selected. No
Delta Deploy Enumeration: FULL/INVENTORY/RUNTIME/${p?:delta.deploy.value} Specify FULL deployment type to replace all artifacts with artifacts in the current component version. Specify INVENTORY deployment type, a delta deployment, to reduce the deployment time significantly by deploying only the changes between artifacts. The comparison is based on identity attributes including lastModifiedTimestamp and customer properties starting with SYS.id. Specify RUNTIME deployment type, a delta deployment, to use checksum logic to compare artifacts to be deployed with the same artifacts in the target environment. This check is done for every artifact. Only artifacts with checksums that don’t match are considered as changed and used for deployment.Note:* Two artifacts are considered the same when at least one attribute can be used for comparison and all attributes that are used for comparison match exactly. The attributes used for delta deployment type are explained in the table below. Yes
HFS Directory mappings String Specify target directory mappings to deploy HFS files. It can be either be a single target directory or mapping similar to PDS mapping with source and target directories. No
Replace PDS Member Enumeration: TRUE/FALSE/${p?:deploy.env.replace.pds.member} Specify TRUE to replace PDS member in target if exist. Setting to FALSE will run deployment only if all PDS members to be deployed do not exist. Yes
    Hidden Properties (below)  
Binder API Path String Path to include binder shared libraries(iewbndd6.so/iewbnddx.so) for RUNTIME delta deployment Yes
ISPF Gateway Path String Specify the path for ISPF gateway binary files. Yes
Deployment Base Path String The base location to store deployment results and backups for rollback. The default value is the BUZ_DEPLOY_BASE environment variable, which is set to the deployment base path that was specified during installation. Typically, you do not change this value. Yes
Temporary DSN Prefix String Specify a DSN prefix to be used to create temporary data sets. The default value is the BUZ_TMP_DSN_PREFIX environment variable. If a value is not provided, the prefix in the agent user’s profile or the agent user’s ID is used. No
Is Merged Version String Specify true if this is a merged version. No
Version Name String Version Name Yes
Version Id String Version Id Yes
Version Type String Version Type Yes
Component Name String Component Name Yes
Resource Id String Resource Id Yes
Component Id String Component Id Yes

For each artifact in a delta deployment, the following attributes are compared to the latest inventory version of the same artifact.

Parameter Where Used Description
Last Modified Timestamp INVENTORY IBM UrbanCode Deploy reads the Last Modified Timestamp value when the version is packaged. All load modules that are build by RTC have Last Modified Timestamp values stored in SSI. If SSI has no Last Modified Timestamp values, ZLM4DATE, ZLMTIME and ZLMSEC statistical values are read from ISPF. Note that the JCL-built or third-party tool load modules have a Last Modified Timestamp value of NO.
Custom properties starting with SYS.id (aka identification properties) INVENTORY These properties provide an open framework for the customer or provider to add additional attributes to indicate whether two artifacts are the same. Two artifacts are considered the same when all attributes that are used for comparison match exactly.
checksum RUNTIME The checksum value is determined when the version is packaged. During a RUNTIME deployment, the checksum is calculated for the artifact in the target environment and compared with the checksum calculated during the version creation. These properties can be hash or binder information for load modules.

FTP Artifacts

Load artifacts from a remote repository using FTP.

Name Type Description Required
Directory Offset String The working directory to use when running the command. This directory is relative to the current working directory. Yes

Generate Artifact Information

Note:

Generate text information for selected version artifacts. The information is sent to the text output property for use by later steps. Note: From version 51, groovy string methods are not interpreted in Template input since the code is rewritten in Java. Use our new plugin https://urbancode.github.io/IBM-UCx-PLUGIN-DOCS/UCD/zos-multi-generate-artifact-info/ to generate multiple templates using a single step

Name Type Description Required
Container Name Filter String Specify a filter to use on the container name. The container can be data set, directory, or generic artifact group. Java regular expression matching is used if the filter starts and ends with a forward slash (/). For example, specify /.*LOAD/ to match any text that ends with LOAD. If the filter is not a regular expression, exact matching is used. No
Custom Properties Filter String Specify a list of custom properties filters, separated by newline characters. Use the following format: propertyName=valueFilter. A property without valueFilter selects all artifacts that have that property. Java regular expression matching is used if the filter starts and ends with a forward slash (/). For example, specify developer=/M.*/ to match artifacts with a developer property where the value of the property starts with M. If valueFilter is not a regular expression, exact matching is used. For example, developer=Martin matches artifacts where the value of the developer property is Martin. No
Deploy Type Filter String Specify a filter to use on the deploy type. Java regular expression matching is used if the filter starts and ends with a forward slash (/). For example, specify /.*LOAD/ to match any text that ends with LOAD. If the filter is not a regular expression, exact matching is used. No
Fail On Empty Boolean Select to set the step to fail if no text is generated. No
Ignore unresolved properties Boolean Check this box to ignore unresolved properties in the template. On Default(unchecked) this step will fail if any unresolved properties are found. No
For Each Enumeration:
1) Member
2) PDS
3) Sequential
4) DeletedMember
5) DeletedPDS
6) DeletedSequential
7) Directory
8) File
9) DeletedFile
10) GenericArtifactGroup
11) GenericArtifact
12) Deleted PDS Member - Exclude missing members		 Generate information for each artifact of the selected type. Yes
Order By Enumeration:
ASC
DESC
SHIPLIST		   Yes
Resource Name Filter String Specify a filter to use on the resource name. The resource can be data set member, file, or generic artifact. Java regular expression matching is used if the filter starts and ends with a forward slash (/). For example, specify /.*LOAD/ to match any text that ends with LOAD. If the filter is not a regular expression, exact matching is used. No
Target Data Set Name Filter String Specify a filter to use on the target data set name. Java regular expression matching is used if the filter starts and ends with a forward slash (/). For example, specify /.*LOAD/ to match any text that ends with LOAD. If the filter is not a regular expression, exact matching is used. No
Template String Specify the template to use to generate text. The text output property contains the generated text from this step. Subsequent steps can access this text with the${p:stepName/text} property. Add separators, including line breaks, in the template as needed. Use ${propname} to access custom properties. The following built-in properties are available: ${sourceDataset} for the source dataset name. ${dataset} for the target dataset name. ${member} for the member name. ${deployType} for the deployment type. ${artifactGroup} for the generic artifact group name. ${artifact} for the generic artifact name. ${directory} for the directory name. ${file} for the file name. ${inputsUrl} for the url of the inputs. All property names are case-sensitive. Do not use the built-in names for custom properties. Yes
Deployment Action Filter Enumeration:
${p?:artifact.deployment.action}<br/CREATED
UPDATED		 Specify the template to use to generate text. The text output property contains the generated text from this step. Subsequent steps can access this text with the${p:stepName/text} property. Add separators, including line breaks, in the template as needed. Use ${propname} to access custom properties. The following built-in properties are available: ${sourceDataset} for the source dataset name. ${dataset} for the target dataset name. ${member} for the member name. ${deployType} for the deployment type. ${artifactGroup} for the generic artifact group name. ${artifact} for the generic artifact name. ${directory} for the directory name. ${file} for the file name. ${inputsUrl} for the url of the inputs. All property names are case-sensitive. Do not use the built-in names for custom properties. Yes
    Hidden Properties (below)  
Deployment Base Path String The base location to store deployment results and backups for rollback. No
Version Name String Version Name No
Component Name String Component Name No
Resource Id String Resource Id Yes

Remove All Versions

Remove all versions in an environment.

Name Type Description Required
Dry Run Boolean Select to specify a dry run, which does not delete versions. Instead, the versions to be deleted are written to the output log for verification. No

Remove Redundant Versions

Remove redundant versions in an environment. Redundant versions are versions that are completely replaced by subsequent versions.

Name Type Description Required
Dry Run Boolean Select to specify a dry run, which does not delete versions. Instead, the versions to be deleted are written to the output log for verification. No

Replace Tokens MVS

Replace tokens in MVS data set using properties.

Name Type Description Required
Allow Wildcard Boolean Select to use an asterisk (*) as a wildcard character in the Include Data Sets field. The asterisk matches any characters. Using wildcard characters can result in updates to a large number of data set members or unexpected updates. Yes
End Token Delimiter String The end delimiter character to use for identifying tokens. No
Exclude Data Sets String Specify a list of data set patterns to exclude from processing. Separate patterns with commas or newline characters. Use an asterisk (*) to match any characters. For example, USERID.JCL(ABC*) No
Explicit Tokens String Specify a list of explicit tokens to replace, separated by newline characters. Use the following format: token->value. For example, mytoken->new_value will replace the mytoken string with new_value in all files. This field is not affected by the delimiter or prefix fields. To replace @token@ with new_value, specify @token@->new_value. If you specify a value in the Property List field, the explicit tokens are added as additional values to replace and override any properties that have the same name. Regular expressions are not supported. No
Fail On Truncate Boolean Select to set the step to fail if the line exceeds the record length after replacement. If cleared, the line is truncated to fit the record length. No
Include Data Sets String Specify a list of patterns that describe data sets to process. Separate patterns with commas or newline characters. For example, specify USERID.JCL(ABC) for a partitioned data set, or USERID.DATA for a sequential data set. Yes
Property List String Specify a value here to use existing property names as tokens to replace in the target files. For example, specify ${p:environment/allProperties} use the names of all component environment properties tokens and the property values as the replacements. Similarly, specify ${p:component/allProperties},${p:environment/allProperties} to use all component and component environment properties for token replacement. The delimiter and prefix settings above apply. For example, if the start and end token delimiters are the at sign (@) and property is called token1, then the step searches for @token1@ to replace. No
Property Prefix String Specify a prefix to use to determine which properties are included in token replacement. Leave blank to use all properties. No
Start Token Delimiter String The start delimiter character to use for identifying tokens. No

Rollback Data Sets

Rollback data sets and HFS files to a backup created in the previous deployment.

NOTE: Uncheck Delete Backup Data check box in the Rollback step. Instead add Cleanup Backup Files step as a last step in the rollback process design. To delete backup files from z/OS Unix system.

Name Type Description Required
Check Access Boolean Select to check permission to update the data sets to deploy. No
Delete Backup Data Boolean Select to remove the backup data that was created during deployment for this version. No
HFS Target Directory String Specify a target directory to deploy HFS files. No
Prevent Risky Rollback Enumeration: true/false/${p?:prevent.risky.rollback} Set to TRUE to prevent risky rollback. A risky rollback tries to rollback modules that have been replaced by a subsequent version. Yes
Run to Check Risk Only Boolean Select to do a dry run which only checks for risky rollback. No actual rollback is done when doing a dry run. The step will fail when risk is detected, otherwise, the step will pass. No
    Hidden Properties (below)  
Deployment Base Path String The base location to store deployment results and backups for rollback. Yes
Temporary DSN Prefix String Specify a DSN prefix to be used to create temporary data sets. The default value is the BUZ_TMP_DSN_PREFIX environment variable. If a value is not provided, the prefix in the agent user’s profile or the agent user’s ID is used. No
Environment Id String Environment Id Yes
Version Name String Version Name Yes
Version Id String Version Id Yes
Version Type String Version Type Yes
Component Name String Component Name Yes
Resource Id String Resource Id Yes
Component Id String Component Id Yes

Run MVS Command

Run MVS system commands.

Name Type Description Required
Fail Message String Specify messages that indicate command failure. The step fails if any of these messages are in the system responses. Separate multiple messages with newline characters. No
MVS Commands String Specify a list, separated by newline characters, of MVS system commands to run. Yes
Stop On Fail Boolean Select to stop running commands after a command fails. No

Run TSO or ISPF Command

Run TSO and ISPF commands using the ISPF gateway.

Name Type Description Required
Command To Run String Specify the TSO and ISPF commands to run. Separate multiple commands with newline characters. Interactive TSO commands are not supported. Yes
ISPF TSO Profile String Specify an existing ISPF profile to use in the call. No
Run In A Reusable ISPF Session Boolean Select to run commands in a reusable ISPF session that stays active between calls. No
Show Operation Log Boolean   No
Stop On Fail Boolean Select to stop running commands after a command fails with a non-zero return code. No
TSO Or ISPF Enumeration: TSO/ISPF Only ISPF supports return code. Yes

Submit Job

Submit job.

Note:

Name Type Description Required
Default Job Statement String Default job statement to use if no job statement is found in the JCL. The job statement is not validated. Ensure that the job statement contains valid values for your system. Token replacement rules are not applied to the default job statement. No
JCL String Enter the JCL to submit. No
JCL Dataset String Submits JCL from a partitioned data set (PDS) member. Input can be a PDS member name: A.B.C(MEM). Or a PDS member pattern: A.B.C(D*X). Or a PDS name: A.B.C. When the input is a member pattern, all matching members are submitted. When the input is a PDS name, all members are submitted. Multiple JCL statements are submitted in sequence using the same settings. Multiple input JCL statements cannot be used together with Replace Token sets for Each Job field. No
JCL File String Submits JCL in a file in the UNIX file system. For example, /u/userid/jobname.jcl No
Max Lines String Specify the maximum number of lines to display in the log. Set it to -1 to display all the lines. No
Max Return Code String Specify the maximum return code for the step. The step fails if the JCL return code is greater than the specified value. Yes
Replace Token sets for Each Job String One job is submitted for each set of token replacement rules. Each set must be separated by a line containing only two forward slashes (//) characters. Within a set, each rule must be on a separate line. No
Replace Tokens String Specify replacement rules to apply to the JCL before submission. Rules are represented by a list of explicit tokens to replace in the following format: token->value. Separate rules with newline characters. For example, mytoken->new_value will replace the mytoken string with new_value in all files. To replace @token@ with new_value, specify @token@->new_value. Regular expressions are not supported. No
Show Output String Specify the output data set to be displayed in the log. Separate multiple data sets with commas. Specify ALL for all data sets. No
Stop On Fail Boolean Select to stop submitting jobs after a job fails. Failure is determined by the Max Return Code and Timeout fields. A JCL error is always considered a failure. No
Timeout String Specify the timeout in seconds. No
Wait For Job Boolean Select to wait for the job to complete. If cleared, the Timeout, Show Output, Max Lines, and Max Return Code fields are not used. No
    Hidden Properties (below)  
Use Agent/Impersonation Id to submit Job Enumeration: TRUE/FALSE/${p:jes.use.run.id} Set it to TRUE to submit the job using the Agent Id (or) impersonation Id used to run this step. Set it to FALSE to submit the job with a specific UserId and password/passticket. Yes
Host Name String Host Name or IP address to connect JMON Yes
Job Monitor Port String JES job monitor port (1-65535). Default is 6715. Yes
User Name String User Name No
Password String Password No
Use Passticket Boolean Use PassTicket authentication if a password is not provided. See the z/OS Utility plug-in documentation for the required configuration to allow PassTickets. No
IRRRacf.jar File String Specify the full path to the System Access Facility (SAF) JAR file, which is IRRRacf.jar. The default value is /usr/include/java_classes/IRRRacf.jar. Yes
IRRRacf Native Library Path String Specify the path to the System Access Facility (SAF) native library, which is libIRRRacf.so. There is one library for 31-bit Java and one for 64-bit Java. You must specify the path of the appropriate library based on the version of Java that you are running. The default value is /usr/lib. Yes
Print job output of each job in separate page Boolean When mutliple jobs are submitted in a single plugin step, check this box to get each output in separate page. First page will be blank and output will start from second page No

Wait For Job

Wait for a submitted job to complete. Note: Using passphrase in place of password is supported from JMON version v2.9.14. Passphrase authentication is enabled by setting property PASS_PHRASE to ON in JMON configurations. JMON binaries with passphrase support are copied to #HLQ#.SBUZAUTH dataset from agent version 7.1.2.0 after agent install or upgrade.

Name Type Description Required
Job ID String Specify the job ID. For example, JOB06663. Use the ${p:submitStepName/jobId} property to refer to the job ID from an earlier Submit Job step. No
Max Lines String Specify the maximum number of lines to display in the log. Set it to -1 to display all the lines. No
Max Return Code String Specify the maximum return code for the step. The step fails if the JCL return code is greater than the specified value. Yes
Show Output String Specify the output data sets to display in the log. Separate multiple data sets with commas. Specify ALL to display all data sets. No
Timeout String Specify the timeout in seconds. No
    Hidden Properties (below)  
Use Agent/Impersonation Id to wait For Job Enumeration: TRUE/FALSE/${p:jes.use.run.id} Set it to TRUE to submit job using the Agent Id (or) impersonation Id used to run this step. Set it to FALSE to submit job with a specific UserId and password/passticket. Yes
Host Name String Host Name or IP address to connect JMON Yes
Job Monitor Port String JES job monitor port (1-65535). Default is 6715. Yes
User Name String User Name No
Password String Password No
Use Passticket Boolean Use PassTicket authentication if a password is not provided. See the z/OS Utility plug-in documentation for the required configuration to allow PassTickets. No
IRRRacf.jar File String Specify the full path to the System Access Facility (SAF) JAR file, which is IRRRacf.jar. The default value is /usr/include/java_classes/IRRRacf.jar. Yes
IRRRacf Native Library Path String Specify the path to the System Access Facility (SAF) native library, which is libIRRRacf.so. There is one library for 31-bit Java and one for 64-bit Java. You must specify the path of the appropriate library based on the version of Java that you are running. The default value is /usr/lib. Yes

Delete Dataset

Deletes a dataset PDS or Sequential.

Name Type Description Required
Dataset Name String Name of the datasets to be deleted. It can be a sequential dataset or PDS member or PDS. Separate dataset names with a newline. If the single quotation marks are omitted, the user’s data set prefix from the TSO profile is automatically appended to the front of the dataset name. Wildcards are not allowed. GDGs with relative generation number are not allowed. Yes
Members List String Specify members to be deleted from the only PDS mentioned in Datasets input. Separate member names with a newline. No

Cleanup Backup Files

Delete backup files created during deploy datasets step.

All the properties in the step are hidden properties

Name Type Description Required
Deployment Base Path String The base location where deployment results and backups for rollback are stored. Yes
Version Name String Name of the version Yes
Component Name String Name of the component Yes
Resource Id String Resource Id Yes

Restore Backup Datasets

Restored datasets from backup taken during deployment

Name Type Description Required
Restore Dataset Mapping String Specify list of mapping rules for the datasets to be restored, separated by newline characters. Use the following format: Env_Dataset,Restore_Dataset. Use the asterisk (*) in the Env_Dataset value to match any characters. If multiple rules specify the same Env_Dataset value, only the first one is used. Yes
Allow Creating Dataset Boolean Select to create a dataset if the specified restore dataset does not exist. No
    Hidden Properties (below)  
ISPF Gateway Path String Specify the path for ISPF gateway binary files. Yes
Deployment Base Path String The base location to store deployment results and backups for rollback. The default value is the BUZ_DEPLOY_BASE environment variable, which is set to the deployment base path that was specified during installation. Typically, you do not change this value. Yes
Temporary DSN Prefix String Specify a DSN prefix to be used to create temporary data sets. The default value is the BUZ_TMP_DSN_PREFIX environment variable. If a value is not provided, the prefix in the agent user’s profile or the agent user’s ID is used. No
Version Name String Version Name Yes
Component Name String Component Name Yes
Resource Id String Resource Id Yes
Back to …   Latest Version z/OS Utility        
All Plugins Deploy Plugins 90.1167616 Readme Overview Troubleshooting Usage Downloads