zmf_console_command – Issue MVS command

Synopsis

  • Issue MVS command by using a system console through z/OS console RESTful services.

  • Retrieve command response and define success condition based on specified keywords in the command response or broadcast messages.

  • Save the command response on Ansible control node.

Parameters

console_broadcastmsg_detect_timeout

Specifies how long, in seconds, the console attempts to detect the value of console_broadcastmsg_keyword in broadcast messages.

required: False
type: int
default: 30
console_broadcastmsg_keyword

Specifies a keyword that you want to detect in broadcast messages. Case is not significant.

This value can be a string or a regular expression. To use a regular expression, you must also set console_broadcastmsg_reg=true.

This variable is designed to help user determine whether the broadcast messages issued after the command matches with user’s expectation.

If console_cmdresponse_keyword is not specified, the module will fail if the specified keyword can not be detected from broadcast messages.

Otherwise, the module will fail if the specified keywords can not be detected from both command response and broadcast messages.

required: False
type: str
console_broadcastmsg_reg

If console_broadcastmsg_keyword is specified, this variable specifies whether console_broadcastmsg_keyword represents a regular expression.

required: False
type: bool
default: false
console_cmd

Specifies the command to issue.

required: True
type: str
console_cmdresponse_keyword

Specifies a keyword that you want to detect in the command response. Case is not significant.

This value can be a string or a regular expression. To use a regular expression, you must also set console_cmdresponse_reg=true.

This variable is designed to help user determine whether the command response matches with user’s expectation.

If console_broadcastmsg_keyword is not specified, the module will fail if the specified keyword can not be detected from the command response.

Otherwise, the module will fail if the specified keywords can not be detected from both command response and broadcast messages.

required: False
type: str
console_cmdresponse_reg

If console_cmdresponse_keyword is specified, this variable specifies whether console_cmdresponse_keyword represents a regular expression.

required: False
type: bool
default: false
console_cmdresponse_retrieve_times

Specifies how many times the console attempts to retrieve the command response.

If the command response contains a large volume of messages, it will not arrive within a certain time interval.

In this case you might retrieve again several times to ensure that all messages related to the command are retrieved.

required: False
type: int
default: 1
console_name

Name of the EMCS console that is used to issue the command.

If this value is omitted, the console name is generated by adding CN to the logon user ID.

required: False
type: str
console_save_output_localpath

The local path on control node where the command response should be saved to. For example, /tmp/cmd_output.

This path can be absolute or relative. The module will fail if parent directory of console_save_output_localpath is a read-only file system.

The directory {{ console_save_output_localpath }}/{{ inventory_hostname }}/ will be created to save the command response.

For example, /tmp/cmd_output/SY1/.

The command response will be saved as separate file and named as {{ console_cmd }}, in which comma and space will be replaced with underline.

For example, /tmp/cmd_output/SY1/display_a_l.

required: False
type: str
console_system

Nickname of the target z/OS system in the same sysplex that the command is routed to.

This variable should be specified as {{ inventory_hostname }}, and its value should be specified in the inventory file as a managed node.

required: True
type: str
zmf_credential

Authentication credentials, returned by module zmf_authenticate, for the successful authentication with z/OSMF server.

If zmf_credential is supplied, zmf_host, zmf_port, zmf_user, zmf_password, zmf_crt and zmf_key are ignored.

required: False
type: dict
jwtToken

The value of JSON Web token, which supports strong encryption.

If LtpaToken2 is not supplied, jwtToken is required.

required: False
type: str
LtpaToken2

The value of Lightweight Third Party Access (LTPA) token, which supports strong encryption.

If jwtToken is not supplied, LtpaToken2 is required.

required: False
type: str
zmf_host

Hostname of the z/OSMF server.

required: True
type: str
zmf_port

Port number of the z/OSMF server.

required: False
type: int
zmf_crt

Location of the PEM-formatted certificate chain file to be used for HTTPS client authentication.

If zmf_credential is supplied, zmf_crt is ignored.

If zmf_credential is not supplied, zmf_crt is required when zmf_user and zmf_password are not supplied.

required: False
type: str
zmf_host

Hostname of the z/OSMF server.

If zmf_credential is supplied, zmf_host is ignored.

If zmf_credential is not supplied, zmf_host is required.

required: False
type: str
zmf_key

Location of the PEM-formatted file with your private key to be used for HTTPS client authentication.

If zmf_credential is supplied, zmf_key is ignored.

If zmf_credential is not supplied, zmf_key is required when zmf_user and zmf_password are not supplied.

required: False
type: str
zmf_password

Password to be used for authenticating with z/OSMF server.

If zmf_credential is supplied, zmf_password is ignored.

If zmf_credential is not supplied, zmf_password is required when zmf_crt and zmf_key are not supplied.

If zmf_credential is not supplied and zmf_crt and zmf_key are supplied, zmf_user and zmf_password are ignored.

required: False
type: str
zmf_port

Port number of the z/OSMF server.

If zmf_credential is supplied, zmf_port is ignored.

required: False
type: int
zmf_user

User name to be used for authenticating with z/OSMF server.

If zmf_credential is supplied, zmf_user is ignored.

If zmf_credential is not supplied, zmf_user is required when zmf_crt and zmf_key are not supplied.

If zmf_credential is not supplied and zmf_crt and zmf_key are supplied, zmf_user and zmf_password are ignored.

required: False
type: str

Examples

- name: Issue command to display active jobs
  zmf_console_command:
    zmf_host: "sample.ibm.com"
    console_cmd: "display a,l"
    console_system: "{{ inventory_hostname }}"

- name: Issue command to display active jobs and save the command response
  zmf_console_command:
    zmf_host: "sample.ibm.com"
    console_cmd: "display a,l"
    console_system: "{{ inventory_hostname }}"
    console_save_output_localpath: "/tmp/cmd_output"

- name: Issue command to start CIM server and detect if it is started successfully or not
  zmf_console_command:
    zmf_host: "sample.ibm.com"
    console_cmd: "start pegasus"
    console_system: "{{ inventory_hostname }}"
    console_cmdresponse_keyword: "SLP registration initiated"

- name: Issue command to start CIM server and detect if it is started successfully or not
  zmf_console_command:
    zmf_host: "sample.ibm.com"
    console_cmd: "start pegasus"
    console_system: "{{ inventory_hostname }}"
    console_broadcastmsg_keyword: "started CIM server"

Return Values

changed

Indicates if any change is made during the module operation.

returned: always
type: bool
message

The output message generated by the module to indicate whether the command is successful.

If either console_cmdresponse_keyword or console_broadcastmsg_keyword is specified, indicate whether the specified keyword is detected.

If console_save_output_localpath is specified, indicate whether the command response is saved on control node.

returned: on success
type: str

sample:

"The command is issued successfully."

"The command is issued successfully. The specified keyword is detected in the command response."

"The command is issued successfully. The specified keyword is detected in broadcast messages."

"The command is issued successfully. The command response is saved in: /tmp/output/SY1/display_a_l"
cmd_response

The command response.

returned: on success
type: list

sample:

[" CNZ4105I 04.32.31 DISPLAY ACTIVITY 458", "  JOBS     M/S    TS USERS    SYSAS    INITS   ACTIVE/MAX VTAM     OAS", " 00002    00015    00002      00032    00005    00001/00020       00011", "  VLF      VLF      VLF      NSW  S  IGVDGNPP IGVDGNPP PRIMEPSA OWT  S", "  VTAM44   VTAM44   VTAM     NSW  S  RACF     RACF     RACF     NSW  S", "  GRSSTMON GRSSTMON STEP1    OWT  S  SDSF23   SDSF23   SDSF     NSW  S", "  HZR      HZR      IEFPROC  NSW  S  JES2     JES2     IEFPROC  NSW  S", "  SDSFAUX  SDSFAUX  SDSFAUX  NSW  S  TCAS     TCAS     TSO      OWT  S", "  TCPIP    TCPIP    TCPIP    NSW  SO RESOLVER RESOLVER EZBREINI NSW  SO", "  RRS      RRS      RRS      NSW  S  OMPROUTE OMPROUTE OMPROUTE NSW  SO", "  INETD1   STEP1    INETD    OWT  AO FTPDEV1  STEP1    FTPD     OWT  AO", "  PEGASUS  PEGASUS  *OMVSEX  IN   SO", " IBMUSER  OWT      ZOSMFAD  IN   O"]
cmdresponse_keyword_detected

Indicate whether the specified keyword is detected in the command response.

returned: on success when console_cmdresponse_keyword is specified
type: bool
broadcastmsg_keyword_detected

Indicate whether the specified keyword is detected in broadcast messages.

returned: on success when console_broadcastmsg_keyword is specified
type: bool
detected_broadcastmsg

The message that contains the specified keyword that was detected in broadcast messages.

returned: on success when console_broadcastmsg_keyword is specified
type: list

sample:

[" BPXM023I (ZOSMFAD) CFZ10030I: Started CIM Server version 2.14.2."]