zos_mvs_raw – Run a z/OS program.¶
Synopsis¶
Run a z/OS program.
This is analogous to a job step in JCL.
Defaults will be determined by underlying API if value not provided.
Parameters¶
- program_name
The name of the z/OS program to run (e.g. IDCAMS, IEFBR14, IEBGENER etc.).
required: Truetype: str- parm
The program arguments (e.g. -a=’MARGINS(1,72)’).
required: Falsetype: str- auth
Determines whether this program should run with authorized privileges.
If auth=true, the program runs as APF authorized.
If auth=false, the program runs as unauthorized.
required: Falsetype: booldefault: False- verbose
Determines if verbose output should be returned from the underlying utility used by this module.
When verbose=true verbose output is returned on module failure.
required: Falsetype: booldefault: False- dds
The input data source.
dds supports 6 types of sources
dd_data_set for data set files.
dd_unix for UNIX files.
dd_input for in-stream data set.
dd_dummy for no content input.
dd_concat for a data set concatenation.
dds supports any combination of source types.
required: Falsetype: listelements: dict- dd_data_set
Specify a data set.
dd_data_set can reference an existing data set or be used to define a new data set to be created during execution.
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str- data_set_name
The data set name.
required: Falsetype: str- type
The data set type. Only required when disposition=new.
Maps to DSNTYPE on z/OS.
required: Falsetype: strchoices: library, pds, pdse, large, basic, seq, rrds, esds, lds, ksds- disposition
disposition indicates the status of a data set.
Defaults to shr.
required: Falsetype: strchoices: new, shr, mod, old- disposition_normal
disposition_normal indicates what to do with the data set after a normal termination of the program.
required: Falsetype: strchoices: delete, keep, catlg, catalog, uncatlg, uncatalog- disposition_abnormal
disposition_abnormal indicates what to do with the data set after an abnormal termination of the program.
required: Falsetype: strchoices: delete, keep, catlg, catalog, uncatlg, uncatalog- reuse
Determines if a data set should be reused if disposition=NEW and if a data set with a matching name already exists.
If reuse=true, disposition will be automatically switched to
SHR
.If reuse=false, and a data set with a matching name already exists, allocation will fail.
Mutually exclusive with replace.
reuse is only considered when disposition=NEW
required: Falsetype: booldefault: False- replace
Determines if a data set should be replaced if disposition=NEW and a data set with a matching name already exists.
If replace=true, the original data set will be deleted, and a new data set created.
If replace=false, and a data set with a matching name already exists, allocation will fail.
Mutually exclusive with reuse.
replace is only considered when disposition=NEW
replace will result in loss of all data in the original data set unless backup is specified.
required: Falsetype: booldefault: False- backup
Determines if a backup should be made of an existing data set when disposition=NEW, replace=true, and a data set with the desired name is found.
backup is only used when replace=true.
required: Falsetype: booldefault: False- space_type
The unit of measurement to use when allocating space for a new data set using space_primary and space_secondary.
required: Falsetype: strchoices: trk, cyl, b, k, m, g- space_primary
The primary amount of space to allocate for a new data set.
The value provided to space_type is used as the unit of space for the allocation.
Not applicable when space_type=blklgth or space_type=reclgth.
required: Falsetype: int- space_secondary
When primary allocation of space is filled, secondary space will be allocated with the provided size as needed.
The value provided to space_type is used as the unit of space for the allocation.
Not applicable when space_type=blklgth or space_type=reclgth.
required: Falsetype: int- volumes
The volume or volumes on which a data set resides or will reside.
Do not specify the same volume multiple times.
required: Falsetype: raw- sms_management_class
The desired management class for a new SMS-managed data set.
sms_management_class is ignored if specified for an existing data set.
All values must be between 1-8 alpha-numeric characters.
required: Falsetype: str- sms_storage_class
The desired storage class for a new SMS-managed data set.
sms_storage_class is ignored if specified for an existing data set.
All values must be between 1-8 alpha-numeric characters.
required: Falsetype: str- sms_data_class
The desired data class for a new SMS-managed data set.
sms_data_class is ignored if specified for an existing data set.
All values must be between 1-8 alpha-numeric characters.
required: Falsetype: str- block_size
The maximum length of a block in bytes.
Default is dependent on record_format
required: Falsetype: int- directory_blocks
The number of directory blocks to allocate to the data set.
required: Falsetype: int- key_label
The label for the encryption key used by the system to encrypt the data set.
key_label is the public name of a protected encryption key in the ICSF key repository.
key_label should only be provided when creating an extended format data set.
Maps to DSKEYLBL on z/OS.
required: Falsetype: str- encryption_key_1
The encrypting key used by the Encryption Key Manager.
Specification of the key labels does not by itself enable encryption. Encryption must be enabled by a data class that specifies an encryption format.
required: Falsetype: dict- label
The label for the key encrypting key used by the Encryption Key Manager.
Key label must have a private key associated with it.
label can be a maximum of 64 characters.
Maps to KEYLAB1 on z/OS.
required: Truetype: str- encoding
How the label for the key encrypting key specified by label is encoded by the Encryption Key Manager.
encoding can either be set to
L
for label encoding, orH
for hash encoding.Maps to KEYCD1 on z/OS.
required: Truetype: strchoices: l, h
- encryption_key_2
The encrypting key used by the Encryption Key Manager.
Specification of the key labels does not by itself enable encryption. Encryption must be enabled by a data class that specifies an encryption format.
required: Falsetype: dict- label
The label for the key encrypting key used by the Encryption Key Manager.
Key label must have a private key associated with it.
label can be a maximum of 64 characters.
Maps to KEYLAB2 on z/OS.
required: Truetype: str- encoding
How the label for the key encrypting key specified by label is encoded by the Encryption Key Manager.
encoding can either be set to
L
for label encoding, orH
for hash encoding.Maps to KEYCD2 on z/OS.
required: Truetype: strchoices: l, h
- key_length
The length of the keys used in a new data set.
If using SMS, setting key_length overrides the key length defined in the SMS data class of the data set.
Valid values are (0-255 non-vsam), (1-255 vsam).
required: Falsetype: int- key_offset
The position of the first byte of the record key in each logical record of a new VSAM data set.
The first byte of a logical record is position 0.
Provide key_offset only for VSAM key-sequenced data sets.
required: Falsetype: int- record_length
The logical record length. (e.g
80
).For variable data sets, the length must include the 4-byte prefix area.
Defaults vary depending on format: If FB/FBA 80, if VB/VBA 137, if U 0.
Valid values are (1-32760 for non-vsam, 1-32761 for vsam).
Maps to LRECL on z/OS.
required: Falsetype: int- record_format
The format and characteristics of the records for new data set.
required: Falsetype: strchoices: u, vb, vba, fb, fba- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Falsetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the data set on the z/OS system.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the data set.
required: Falsetype: strdefault: iso8859-1
- dd_unix
The path to a file in UNIX System Services (USS).
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str- path
The path to an existing UNIX file.
Or provide the path to an new created UNIX file when status_group=OCREAT.
The provided path must be absolute.
required: Truetype: str- disposition_normal
Indicates what to do with the UNIX file after normal termination of the program.
required: Falsetype: strchoices: keep, delete- disposition_abnormal
Indicates what to do with the UNIX file after abnormal termination of the program.
required: Falsetype: strchoices: keep, delete- mode
The file access attributes when the UNIX file is created specified in path.
Specify the mode as an octal number similarly to chmod.
Maps to PATHMODE on z/OS.
required: Falsetype: int- status_group
The status for the UNIX file specified in path.
If you do not specify a value for the status_group parameter, the module assumes that the pathname exists, searches for it, and fails the module if the pathname does not exist.
Maps to PATHOPTS status group file options on z/OS.
You can specify up to 6 choices.
oappend sets the file offset to the end of the file before each write, so that data is written at the end of the file.
ocreat specifies that if the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, a new directory and a new file are not created. If the file already exists and oexcl was not specified, the system allows the program to use the existing file. If the file already exists and oexcl was specified, the system fails the allocation and the job step.
oexcl specifies that if the file does not exist, the system is to create it. If the file already exists, the system fails the allocation and the job step. The system ignores oexcl if ocreat is not also specified.
onoctty specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process.
ononblock specifies the following, depending on the type of file
For a FIFO special file
With ononblock specified and ordonly access, an open function for reading-only returns without delay.
With ononblock not specified and ordonly access, an open function for reading-only blocks (waits) until a process opens the file for writing.
With ononblock specified and owronly access, an open function for writing-only returns an error if no process currently has the file open for reading.
With ononblock not specified and owronly access, an open function for writing-only blocks (waits) until a process opens the file for reading.
For a character special file that supports nonblocking open
If ononblock is specified, an open function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device.
If ononblock is not specified, an open function blocks (waits) until the device is ready or available.
ononblock has no effect on other file types.
osync specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write.
otrunc specifies that the system is to truncate the file length to zero if all the following are true: the file specified exists, the file is a regular file, and the file successfully opened with ordwr or owronly.
When otrunc is specified, the system does not change the mode and owner. otrunc has no effect on FIFO special files or character special files.
required: Falsetype: listelements: strchoices: oappend, ocreat, oexcl, onoctty, ononblock, osync, otrunc- access_group
The kind of access to request for the UNIX file specified in path.
required: Falsetype: strchoices: r, w, rw, read_only, write_only, read_write, ordonly, owronly, ordwr- file_data_type
The type of data that is (or will be) stored in the file specified in path.
Maps to FILEDATA on z/OS.
required: Falsetype: strdefault: binarychoices: binary, text, record- block_size
The block size, in bytes, for the UNIX file.
Default is dependent on record_format
required: Falsetype: int- record_length
The logical record length for the UNIX file.
record_length is required in situations where the data will be processed as records and therefore, record_length, block_size and record_format need to be supplied since a UNIX file would normally be treated as a stream of bytes.
Maps to LRECL on z/OS.
required: Falsetype: int- record_format
The record format for the UNIX file.
record_format is required in situations where the data will be processed as records and therefore, record_length, block_size and record_format need to be supplied since a UNIX file would normally be treated as a stream of bytes.
required: Falsetype: strchoices: u, vb, vba, fb, fba- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Falsetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the file on the z/OS system.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the file.
required: Falsetype: strdefault: iso8859-1
- dd_input
dd_input is used to specify an in-stream data set.
Input will be saved to a temporary data set with a record length of 80.
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str- content
The input contents for the DD.
dd_input supports single or multiple lines of input.
Multi-line input can be provided as a multi-line string or a list of strings with 1 line per list item.
If a list of strings is provided, newlines will be added to each of the lines when used as input.
If a multi-line string is provided, use the proper block scalar style. YAML supports both literal and folded scalars. It is recommended to use the literal style indicator “|” with a block indentation indicator, for example; content: | 2 is a literal block style indicator with a 2 space indentation, the entire block will be indented and newlines preserved. The block indentation range is 1 - 9. While generally unnecessary, YAML does support block chomping indicators “+” and “-” as well.
When using the content option for instream-data, the module will ensure that all lines contain a blank in columns 1 and 2 and add blanks when not present while retaining a maximum length of 80 columns for any line. This is true for all content types; string, list of strings and when using a YAML block indicator.
required: Truetype: raw- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Falsetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the data set on the z/OS system.
for dd_input, src_encoding should generally not need to be changed.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the data set.
required: Falsetype: strdefault: iso8859-1
- dd_output
Use dd_output to specify - Content sent to the DD should be returned to the user.
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Truetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the data set on the z/OS system.
for dd_input, src_encoding should generally not need to be changed.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the data set.
required: Falsetype: strdefault: iso8859-1
- dd_dummy
Use dd_dummy to specify - No device or external storage space is to be allocated to the data set. - No disposition processing is to be performed on the data set.
dd_dummy accepts no content input.
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str
- dd_vio
dd_vio is used to handle temporary data sets.
VIO data sets reside in the paging space; but, to the problem program and the access method, the data sets appear to reside on a direct access storage device.
You cannot use VIO for permanent data sets, VSAM data sets, or partitioned data sets extended (PDSEs).
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str
- dd_concat
dd_concat is used to specify a data set concatenation.
required: Falsetype: dict- dd_name
The DD name.
required: Truetype: str- dds
A list of DD statements, which can contain any of the following types: dd_data_set, dd_unix, and dd_input.
required: Falsetype: listelements: dict- dd_data_set
Specify a data set.
dd_data_set can reference an existing data set. The data set referenced with
data_set_name
must be allocated before the module zos_mvs_raw is run, you can use zos_data_set to allocate a data set.required: Falsetype: dict- data_set_name
The data set name.
required: Falsetype: str- type
The data set type. Only required when disposition=new.
Maps to DSNTYPE on z/OS.
required: Falsetype: strchoices: library, pds, pdse, large, basic, seq, rrds, esds, lds, ksds- disposition
disposition indicates the status of a data set.
Defaults to shr.
required: Falsetype: strchoices: new, shr, mod, old- disposition_normal
disposition_normal indicates what to do with the data set after normal termination of the program.
required: Falsetype: strchoices: delete, keep, catlg, catalog, uncatlg, uncatalog- disposition_abnormal
disposition_abnormal indicates what to do with the data set after abnormal termination of the program.
required: Falsetype: strchoices: delete, keep, catlg, catalog, uncatlg, uncatalog- reuse
Determines if data set should be reused if disposition=NEW and a data set with matching name already exists.
If reuse=true, disposition will be automatically switched to
SHR
.If reuse=false, and a data set with a matching name already exists, allocation will fail.
Mutually exclusive with replace.
reuse is only considered when disposition=NEW
required: Falsetype: booldefault: False- replace
Determines if data set should be replaced if disposition=NEW and a data set with matching name already exists.
If replace=true, the original data set will be deleted, and a new data set created.
If replace=false, and a data set with a matching name already exists, allocation will fail.
Mutually exclusive with reuse.
replace is only considered when disposition=NEW
replace will result in loss of all data in the original data set unless backup is specified.
required: Falsetype: booldefault: False- backup
Determines if a backup should be made of existing data set when disposition=NEW, replace=true, and a data set with the desired name is found.
backup is only used when replace=true.
required: Falsetype: booldefault: False- space_type
The unit of measurement to use when allocating space for a new data set using space_primary and space_secondary.
required: Falsetype: strchoices: trk, cyl, b, k, m, g- space_primary
The primary amount of space to allocate for a new data set.
The value provided to space_type is used as the unit of space for the allocation.
Not applicable when space_type=blklgth or space_type=reclgth.
required: Falsetype: int- space_secondary
When primary allocation of space is filled, secondary space will be allocated with the provided size as needed.
The value provided to space_type is used as the unit of space for the allocation.
Not applicable when space_type=blklgth or space_type=reclgth.
required: Falsetype: int- volumes
The volume or volumes on which a data set resides or will reside.
Do not specify the same volume multiple times.
required: Falsetype: raw- sms_management_class
The desired management class for a new SMS-managed data set.
sms_management_class is ignored if specified for an existing data set.
All values must be between 1-8 alpha-numeric characters.
required: Falsetype: str- sms_storage_class
The desired storage class for a new SMS-managed data set.
sms_storage_class is ignored if specified for an existing data set.
All values must be between 1-8 alpha-numeric characters.
required: Falsetype: str- sms_data_class
The desired data class for a new SMS-managed data set.
sms_data_class is ignored if specified for an existing data set.
All values must be between 1-8 alpha-numeric characters.
required: Falsetype: str- block_size
The maximum length of a block in bytes.
Default is dependent on record_format
required: Falsetype: int- directory_blocks
The number of directory blocks to allocate to the data set.
required: Falsetype: int- key_label
The label for the encryption key used by the system to encrypt the data set.
key_label is the public name of a protected encryption key in the ICSF key repository.
key_label should only be provided when creating an extended format data set.
Maps to DSKEYLBL on z/OS.
required: Falsetype: str- encryption_key_1
The encrypting key used by the Encryption Key Manager.
Specification of the key labels does not by itself enable encryption. Encryption must be enabled by a data class that specifies an encryption format.
required: Falsetype: dict- label
The label for the key encrypting key used by the Encryption Key Manager.
Key label must have a private key associated with it.
label can be a maximum of 64 characters.
Maps to KEYLAB1 on z/OS.
required: Truetype: str- encoding
How the label for the key encrypting key specified by label is encoded by the Encryption Key Manager.
encoding can either be set to
L
for label encoding, orH
for hash encoding.Maps to KEYCD1 on z/OS.
required: Truetype: strchoices: l, h
- encryption_key_2
The encrypting key used by the Encryption Key Manager.
Specification of the key labels does not by itself enable encryption. Encryption must be enabled by a data class that specifies an encryption format.
required: Falsetype: dict- label
The label for the key encrypting key used by the Encryption Key Manager.
Key label must have a private key associated with it.
label can be a maximum of 64 characters.
Maps to KEYLAB2 on z/OS.
required: Truetype: str- encoding
How the label for the key encrypting key specified by label is encoded by the Encryption Key Manager.
encoding can either be set to
L
for label encoding, orH
for hash encoding.Maps to KEYCD2 on z/OS.
required: Truetype: strchoices: l, h
- key_length
The length of the keys used in a new data set.
If using SMS, setting key_length overrides the key length defined in the SMS data class of the data set.
Valid values are (0-255 non-vsam), (1-255 vsam).
required: Falsetype: int- key_offset
The position of the first byte of the record key in each logical record of a new VSAM data set.
The first byte of a logical record is position 0.
Provide key_offset only for VSAM key-sequenced data sets.
required: Falsetype: int- record_length
The logical record length. (e.g
80
).For variable data sets, the length must include the 4-byte prefix area.
Defaults vary depending on format: If FB/FBA 80, if VB/VBA 137, if U 0.
Valid values are (1-32760 for non-vsam, 1-32761 for vsam).
Maps to LRECL on z/OS.
required: Falsetype: int- record_format
The format and characteristics of the records for new data set.
required: Falsetype: strchoices: u, vb, vba, fb, fba- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Falsetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the data set on the z/OS system.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the data set.
required: Falsetype: strdefault: iso8859-1
- dd_unix
The path to a file in UNIX System Services (USS).
required: Falsetype: dict- path
The path to an existing UNIX file.
Or provide the path to an new created UNIX file when status_group=OCREAT.
The provided path must be absolute.
required: Truetype: str- disposition_normal
Indicates what to do with the UNIX file after normal termination of the program.
required: Falsetype: strchoices: keep, delete- disposition_abnormal
Indicates what to do with the UNIX file after abnormal termination of the program.
required: Falsetype: strchoices: keep, delete- mode
The file access attributes when the UNIX file is created specified in path.
Specify the mode as an octal number similar to chmod.
Maps to PATHMODE on z/OS.
required: Falsetype: int- status_group
The status for the UNIX file specified in path.
If you do not specify a value for the status_group parameter the module assumes that the pathname exists, searches for it, and fails the module if the pathname does not exist.
Maps to PATHOPTS status group file options on z/OS.
You can specify up to 6 choices.
oappend sets the file offset to the end of the file before each write, so that data is written at the end of the file.
ocreat specifies that if the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, one is not created, and the new file is not created. If the file already exists and oexcl was not specified, the system allows the program to use the existing file. If the file already exists and oexcl was specified, the system fails the allocation and the job step.
oexcl specifies that if the file does not exist, the system is to create it. If the file already exists, the system fails the allocation and the job step. The system ignores oexcl if ocreat is not also specified.
onoctty specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process.
ononblock specifies the following, depending on the type of file
For a FIFO special file
With ononblock specified and ordonly access, an open function for reading-only returns without delay.
With ononblock not specified and ordonly access, an open function for reading-only blocks (waits) until a process opens the file for writing.
With ononblock specified and owronly access, an open function for writing-only returns an error if no process currently has the file open for reading.
With ononblock not specified and owronly access, an open function for writing-only blocks (waits) until a process opens the file for reading.
For a character special file that supports nonblocking open
If ononblock is specified, an open function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device.
If ononblock is not specified, an open function blocks (waits) until the device is ready or available.
ononblock has no effect on other file types.
osync specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write.
otrunc specifies that the system is to truncate the file length to zero if all the following are true: the file specified exists, the file is a regular file, and the file successfully opened with ordwr or owronly.
When otrunc is specified, the system does not change the mode and owner. otrunc has no effect on FIFO special files or character special files.
required: Falsetype: listelements: strchoices: oappend, ocreat, oexcl, onoctty, ononblock, osync, otrunc- access_group
The kind of access to request for the UNIX file specified in path.
required: Falsetype: strchoices: r, w, rw, read_only, write_only, read_write, ordonly, owronly, ordwr- file_data_type
The type of data that is (or will be) stored in the file specified in path.
Maps to FILEDATA on z/OS.
required: Falsetype: strdefault: binarychoices: binary, text, record- block_size
The block size, in bytes, for the UNIX file.
Default is dependent on record_format
required: Falsetype: int- record_length
The logical record length for the UNIX file.
record_length is required in situations where the data will be processed as records and therefore, record_length, block_size and record_format need to be supplied since a UNIX file would normally be treated as a stream of bytes.
Maps to LRECL on z/OS.
required: Falsetype: int- record_format
The record format for the UNIX file.
record_format is required in situations where the data will be processed as records and therefore, record_length, block_size and record_format need to be supplied since a UNIX file would normally be treated as a stream of bytes.
required: Falsetype: strchoices: u, vb, vba, fb, fba- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Falsetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the file on the z/OS system.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the file.
required: Falsetype: strdefault: iso8859-1
- dd_input
dd_input is used to specify an in-stream data set.
Input will be saved to a temporary data set with a record length of 80.
required: Falsetype: dict- content
The input contents for the DD.
dd_input supports single or multiple lines of input.
Multi-line input can be provided as a multi-line string or a list of strings with 1 line per list item.
If a list of strings is provided, newlines will be added to each of the lines when used as input.
If a multi-line string is provided, use the proper block scalar style. YAML supports both literal and folded scalars. It is recommended to use the literal style indicator “|” with a block indentation indicator, for example; content: | 2 is a literal block style indicator with a 2 space indentation, the entire block will be indented and newlines preserved. The block indentation range is 1 - 9. While generally unnecessary, YAML does support block chomping indicators “+” and “-” as well.
When using the content option for instream-data, the module will ensure that all lines contain a blank in columns 1 and 2 and add blanks when not present while retaining a maximum length of 80 columns for any line. This is true for all content types; string, list of strings and when using a YAML block indicator.
required: Truetype: raw- return_content
Determines how content should be returned to the user.
If not provided, no content from the DD is returned.
required: Falsetype: dict- type
The type of the content to be returned.
text
means return content in encoding specified by response_encoding.src_encoding and response_encoding are only used when type=text.
base64
means return content in binary mode.required: Truetype: strchoices: text, base64- src_encoding
The encoding of the data set on the z/OS system.
for dd_input, src_encoding should generally not need to be changed.
required: Falsetype: strdefault: ibm-1047- response_encoding
The encoding to use when returning the contents of the data set.
required: Falsetype: strdefault: iso8859-1
- tmp_hlq
Override the default high level qualifier (HLQ) for temporary and backup datasets.
The default HLQ is the Ansible user used to execute the module and if that is not available, then the value
TMPHLQ
is used.required: Falsetype: str
Examples¶
- name: List data sets matching pattern in catalog,
save output to a new sequential data set and return output as text.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_data_set:
dd_name: sysprint
data_set_name: mypgm.output.ds
disposition: new
reuse: yes
type: seq
space_primary: 5
space_secondary: 1
space_type: m
volumes:
- "000000"
record_format: fb
return_content:
type: text
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: List data sets matching patterns in catalog,
save output to a new sequential data set and return output as text.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_data_set:
dd_name: sysprint
data_set_name: mypgm.output.ds
disposition: new
reuse: yes
type: seq
space_primary: 5
space_secondary: 1
space_type: m
volumes:
- "000000"
record_format: fb
return_content:
type: text
- dd_input:
dd_name: sysin
content:
- LISTCAT ENTRIES('SOME.DATASET.*')
- LISTCAT ENTRIES('SOME.OTHER.DS.*')
- LISTCAT ENTRIES('YET.ANOTHER.DS.*')
- name: List data sets matching pattern in catalog,
save output to an existing sequential data set and
return output as text.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_data_set:
dd_name: sysprint
data_set_name: mypgm.output.ds
disposition: shr
return_content:
type: text
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: List data sets matching pattern in catalog,
save output to a sequential data set. If the data set exists,
then reuse it, if it does not exist, create it. Returns output as text.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_data_set:
dd_name: sysprint
data_set_name: mypgm.output.ds
disposition: new
reuse: yes
type: seq
space_primary: 5
space_secondary: 1
space_type: m
volumes:
- "000000"
record_format: fb
return_content:
type: text
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: List data sets matching pattern in catalog,
save output to a sequential data set. If the data set exists,
then back up the existing data set and replace it.
If the data set does not exist, create it.
Returns backup name (if a backup was made) and output as text,
and backup name.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_data_set:
dd_name: sysprint
data_set_name: mypgm.output.ds
disposition: new
replace: yes
backup: yes
type: seq
space_primary: 5
space_secondary: 1
space_type: m
volumes:
- "000000"
- "111111"
- "SCR002"
record_format: fb
return_content:
type: text
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: List data sets matching pattern in catalog,
save output to a file in UNIX System Services.
zos_raw:
save output to a file in UNIX System Services.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_unix:
dd_name: sysprint
path: /u/myuser/outputfile.txt
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: List data sets matching pattern in catalog,
save output to a file in UNIX System Services.
Return the contents of the file in encoding IBM-1047,
while the file is encoded in ISO8859-1.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_unix:
dd_name: sysprint
path: /u/myuser/outputfile.txt
return_content:
type: text
src_encoding: iso8859-1
response_encoding: ibm-1047
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: List data sets matching pattern in catalog,
return output to user, but don't store in persistent storage.
Return the contents of the file in encoding IBM-1047,
while the file is encoded in ISO8859-1.
zos_mvs_raw:
program_name: idcams
auth: true
dds:
- dd_output:
dd_name: sysprint
return_content:
type: text
src_encoding: iso8859-1
response_encoding: ibm-1047
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SOME.DATASET.*')"
- name: Take a set of data sets and write them to an archive.
zos_mvs_raw:
program_name: adrdssu
auth: yes
dds:
- dd_data_set:
dd_name: archive
data_set_name: myhlq.stor.darv1
disposition: old
- dd_data_set:
dd_name: sysin
data_set_name: myhlq.adrdssu.cmd
disposition: shr
- dd_dummy:
dd_name: sysprint
- name: Merge two sequential data sets and write them to new data set
zos_mvs_raw:
program_name: sort
auth: no
parm: "MSGPRT=CRITICAL,LIST"
dds:
- dd_data_set:
dd_name: sortin01
data_set_name: myhlq.dfsort.main
disposition: shr
- dd_data_set:
dd_name: sortin02
data_set_name: myhlq.dfsort.new
- dd_input:
dd_name: sysin
content: " MERGE FORMAT=CH,FIELDS=(1,9,A)"
- dd_data_set:
dd_name: sortout
data_set_name: myhlq.dfsort.merge
type: seq
disposition: new
- dd_unix:
dd_name: sysout
path: /tmp/sortpgmoutput.txt
mode: 644
status_group:
- ocreat
access_group: w
- name: List data sets matching a pattern in catalog,
save output to a concatenation of data set members and
files.
zos_mvs_raw:
pgm: idcams
auth: yes
dds:
- dd_concat:
dd_name: sysprint
dds:
- dd_data_set:
data_set_name: myhlq.ds1.out(out1)
- dd_data_set:
data_set_name: myhlq.ds1.out(out2)
- dd_data_set:
data_set_name: myhlq.ds1.out(out3)
- dd_unix:
path: /tmp/overflowout.txt
- dd_input:
dd_name: sysin
content: " LISTCAT ENTRIES('SYS1.*')"
- name: Drop the contents of input dataset into output dataset
using REPRO command.
zos_mvs_raw:
pgm: idcams
auth: yes
dds:
- dd_data_set:
dd_name: INPUT
data_set_name: myhlq.ds1.input
- dd_data_set:
dd_name: OUTPUT
data_set_name: myhlq.ds1.output
- dd_input:
dd_name: sysin
content: |
" REPRO -
INFILE(INPUT) -
OUTFILE(OUTPUT)"
- dd_output:
dd_name: sysprint
return_content:
type: text
- name: Define a cluster using a literal block style indicator
with a 2 space indentation.
zos_mvs_raw:
program_name: idcams
auth: yes
dds:
- dd_output:
dd_name: sysprint
return_content:
type: text
- dd_input:
dd_name: sysin
content: |2
DEFINE CLUSTER -
(NAME(ANSIBLE.TEST.VSAM) -
CYL(10 10) -
FREESPACE(20 20) -
INDEXED -
KEYS(32 0) -
NOERASE -
NONSPANNED -
NOREUSE -
SHAREOPTIONS(3 3) -
SPEED -
UNORDERED -
RECORDSIZE(4086 32600) -
VOLUMES(222222) -
UNIQUE)
Notes¶
Note
When executing programs using zos_mvs_raw, you may encounter errors that originate in the programs implementation. Two such known issues are noted below of which one has been addressed with an APAR.
zos_mvs_raw module execution fails when invoking Database Image Copy 2 Utility or Database Recovery Utility in conjunction with FlashCopy or Fast Replication.
zos_mvs_raw module execution fails when invoking DFSRRC00 with parm “UPB,PRECOMP”, “UPB, POSTCOMP” or “UPB,PRECOMP,POSTCOMP”. This issue is addressed by APAR PH28089.
When executing a program, refer to the programs documentation as each programs requirments can vary fom DDs, instream-data indentation and continuation characters.
Return Values¶
- ret_code
The return code.
returned: alwaystype: dict- code
The return code number returned from the program.
type: int
- dd_names
All the related dds with the program.
returned: on successtype: listelements: dict- dd_name
The data definition name.
type: str- name
The data set or path name associated with the data definition.
type: str- content
The content contained in the data definition.
type: listelements: str- record_count
The lines of the content.
type: int- byte_count
The number of bytes in the response content.
type: int
- backups
List of any data set backups made during execution.
returned: alwaystype: dict- original_name
The original data set name for which a backup was made.
type: str- backup_name
The name of the data set containing the backup of content from data set in original_name.
type: str