Issue a command from a system console

Use this operation to issue a command by using a system console.

HTTP method and URI path

PUT /zosmf/restconsoles/consoles/consolename
PUT /zosmf/restconsoles/consoles/defcn

Where:

consolename: Is the name of the EMCS console that is used to issue the command. The name must be 2 - 8 characters long, and cannot be defcn, which is reserved.
defcn: Indicates that the name of the console that is used to issue the command is generated by the REST Console API, by adding CN to the logon user ID. For example, if the logon user ID is CJOEY, the console name is CJOEYCN. If the user ID is longer than 6 characters, the user ID is truncated. For example, if the user ID is ZOSMFAD, the console name is ZOSMFACN.

Query parameters

None.

Description

This operation issues a command, based on the properties that are specified in the request body. On successful completion, HTTP status code 200 is returned. A JSON object typically contains the command response.

When a command is issued synchronously, the console API attempts to get the solicited messages immediately after the command is issued. If there are no messages available within a certain time interval, approximately 3 seconds when your system workload is not high, the API returns "cmd-response": "" in the response body.

A value for cmd-response of the empty string, "", usually means that there is no command response. However, it is also possible that the command response arrived after 3 seconds. If that is the case, you can use the cmd-response-url field in the response body to retrieve the command response. You might do this several times to ensure that all messages that are related to the command are retrieved.

Alternatively, you might examine unsolicited messages, that is, additional messages that are not part of the command response. To do so, you can issue the command with option unsol-key to detect a keyword in the unsolicited messages.

For the properties that you can specify on the request body, see Request content.

For a description of the response content, see Response content.

The request body can include properties that you can use to control console attributes, such as 'auth', 'routcode', 'mscope', 'storage', and 'auto'. Alternatively, you can use System Authorization Facility or SAF to control console attributes. The RACF ADDUSER command with the OPERPARM parameter sets console attributes when a user establishes an EMCS console. Using the ADDUSER command to control console attributes requires that you know in advance the name of the EMCS console that the z/OS Console service uses. The console name is either a name that you specify on the Issue Command service, or a name that the service generates, as described in Issue a command from a system console. For example, if user CJOEY plans to accept the default console name, CJOEYCN, this user can issue this RACF command to set console attributes for the console:

ADDUSER CJOEYCN OPERPARM(AUTH(MASTER) ROUTCODE(ALL))

Note: To use the properties 'auth', 'routcode', 'mscope', 'storage', or 'auto' in your request, your user ID requires at least READ access to resource CONOPER in class TSOAUTH.

Request content

The request content is expected to contain a JSON object. See Table 1 for a description of the fields.

Table 1. Request content for the issue command request
Field name	Required or Optional	Description
cmd	Required	Specifies the command to issue.
sol-key	Optional	Specifies a keyword that you want to detect in solicited messages, that is, 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 the solKeyReg property.
unsol-key	Optional	Specifies a keyword that you want to detect in unsolicited messages. Case is not significant. This value can be a string or a regular expression. To use a regular expression, you must also set the unsolKeyReg property. Message suppression can prevent the return of an unsolicited message. To determine whether a particular message ID is suppressed through the message processing facility on your system, enter the following command to list the MPF settings: D MPF.
detect-time	Optional	Indicates how long the console attempts to detect the value of unsol-key in the unsolicited messages. The unit is seconds. For example, if the value of detect-time is 10, the console checks the unsolicited messages for 10 seconds. The default is 30 seconds.
async	Optional	Indicates the method of issuing the command: Y Asynchronously N Synchronously. If you omit this property, `N` is used by default.
system	Optional	Name of the system in the same sysplex that the command is routed to. The default is the local system.
unsol-detect-sync	Optional	Indicates how to detect the keyword that is specified with the unsol-key field from unsolicited messages: Y Synchronously detect the keyword from unsolicited messages. The request is not returned until the unsol-detect-timeout value elapses or the detection result is complete. N Asynchronously detect the keyword from unsolicited messages. The request is returned immediately with the detection-url. The client application must invoke the value of detection-url to poll the result of the detection asynchronously. If you omit this property, `N` is used by default.
unsol-detect-timeout	Optional	Indicates how long, in seconds, the request is blocked when the value for unsol-detect-sync is Y and the detection result is not complete. The default value, 20 seconds, is used when this field is not specified and the value for unsol-detect-sync is Y.
solKeyReg	Optional	If the sol-key property is specified, this property indicates whether sol-key represents a regular expression. Y sol-key is a regular expression. N sol-key is a normal string. For example, suppose that you want to use a regular expression to find the phrase `"a regular"` in the message `"This is a regular expression"`. If you are not sure how many spaces exist between `"a"` and `"regular"` in the message, you can use following key: `a[\s]+regular` If you omit this property, `N` is used by default.
unsolKeyReg	Optional	If the unsol-key property is specified, this property indicates whether unsol-key represents a regular expression. Y unsol-key is a regular expression. N unsol-key is a normal string. For example, suppose that you want to use a regular expression to find the phrase `"a regular"` in the message `"This is a regular expression"`. If you are not sure how many spaces exist between `"a"` and `"regular"` in the message, you can use following key: `a[\s]+regular` If you omit this property, `N` is used by default.
auth	Optional	Command authority for the console. The first time the user issues a command from the console, the value of this field is returned to the user. The values are: MASTER Allows this console to act as a master console, which can issue all MVS operator commands. ALL Allows this console to issue system control commands, input/output commands, console control commands, and informational commands. INFO Allows this console to issue informational commands. CONS Allows this console to issue console control and informational commands. IO Allows this console to issue input/output and informational commands. SYS Allows this console to issue system control commands and informational commands. If you omit this property, the value that is defined in your external security manager, such as RACF, is used by default.
routcode	Optional	Routing codes for the console. The first time the user issues a command from the console, the value of this field is returned to the user. The values are: ALL All routing codes. NONE No routing codes. (routing-codes) One or more routing codes or sequences of routing codes. The routing codes can be list of n and n1:n2, where n, n1, and n2 are integers 1 - 128, and n2 is greater than n1. If you omit this property, the value that is defined in your external security manager, such as RACF, is used by default.
mscope	Optional	The systems from which this console can receive messages that are not directed to a specific console. The first time the user issues a command from the console, the value of this field is returned to the user. The values are: (system-name) List of one or more system names, where system-name can be any combination of A - Z, 0 - 9, # (X'7B'), $ (X'5B'), or @ (X'7C'). LOCAL System on which the console is active. ALL All systems. If you omit this property, the value that is defined in your external security manager, such as RACF, is used by default.
storage	Optional	Amount of storage in kilobytes in the TSO/E user's address space, which can be used for message queuing to this console. The first time the user issues a command from the console, the value of this field is returned to the user. If you omit this property, the value that is defined in your external security manager, such as RACF, is used by default. If the expected console message size is large, it is recommended that you increase the STORAGE parameter to a larger value. For example, if the expected response size is 10 megabytes, consider setting the STORAGE parameter to `15M`, based on the following formula: `10M+5M=15M`.
auto	Optional	Specifies whether the console receives messages that are eligible for automation. The first time the user issues a command from the console, the value of this field is returned to the user. The values are: YES The console receives messages that are eligible for automation. NO The console does not receive messages that are eligible for automation. If you omit this property, the value that is defined in your external security manager, such as RACF, is used by default.

Authorization requirements

See Required authorizations.

HTTP status codes

For a successful request, HTTP status code 200 is returned and the response body is provided, as described in Request content.

For unsuccessful requests, the service returns the status codes that are described in Table 2.

Table 2. HTTP error response codes for an issue command request
HTTP Status	Return Code	Reason Code	Reason	Description
400	1	3	No match for method PUT and pathInfo=' %s '.	The path information, `%s`, in the original request contains a URL that is not acceptable for the z/OS Console API. Ensure that the request contains the correct URL. A console name must be 2 - 8 alphanumeric characters, the first of which must be alphabetic or one of the special characters #, $ or @.
400	1	5	Console API cannot recognize the JSON field: %s	The JSON field, %s, in the request body, is not a supported field.
400	1	6	The Content-Type ' %s ' cannot be handled, 'application/json' is expected.	The Content-Type, `%s`, in the original request contains an incorrect value for the HTTP Content-Type header. The z/OS Console API accepts only application/json for the Content-Type. Update the value of the HTTP Content-Type header and make sure that the request body is in JSON format.
400	1	11	Format of parameter 'rsize' is wrong, it cannot be changed to a number.	The rsize parameter requires a numeric value, but the supplied value is not a number. Change the value to a number.
400	1	12	The body of the request is not in JSON format.	The request body must be in JSON format, but the supplied request body is not in JSON format. Correct the request body to be in JSON format.
400	1	13	Cannot find 'cmd' in request body, or value of 'cmd' is empty. No command is issued.	No cmd field was found in the request body, or the cmd field is empty. The cmd field specifies the command to be issued. No command is issued. Ensure that the request body includes a cmd field with a value.
400	1	14	Incorrect console name. The length of console name must be greater than 1 and less than 9.	The console name that is specified in the URL is not valid. Supply a valid console name.
400	1	17	Command length must be less than 127.	The value of the cmd field exceeds the maximum length of a command, which is 126 characters. Provide a valid command.
400	1	21	The TSO/E address space cannot be created because an error occurred with the logon procedure or the user settings.	Refer to message IZUG1121E for a detailed explanation. To resolve the issue, try one or more of the following actions: Verify that the logon procedure exists and is valid. Specify a different region size, or use the installation-defined default. If profile sharing is turned on, turn it off. Ensure that you are not simultaneously running a 3270 z/OS® ISPF session. If you want to use profile sharing, do the following: Ensure that each data set that is defined on the ISPPROF DD statement in the logon procedure is allocated with DISP=SHR. Turn on profile sharing in the user settings for the z/OSMF ISPF task. For a 3270 z/OS ISPF session, start the z/OS ISPF application with the SHRPROF option. Use the same logon procedure to start a 3270 z/OS ISPF session, and correct any errors that are identified.
400	1	26	The regular expression is invalid.	The regular expression in `sol-key` is invalid.
500	2	7	Internal https connection timeout.	The internal connection to the z/OSMF REST TSO service timed out. Retry the request. If the problem persists, contact your z/OSMF administrator.
500	2	8	I/O error when connecting TSO service	An error occurred in the internal connection to the z/OSMF REST TSO service. Retry the command. If the problem persists, contact your z/OSMF administrator.
500	2	21	Timeout when creating TSO address space for console `%s`	The internal connection to the z/OSMF REST TSO service timed out. Retry the request. If the problem persists, contact your z/OSMF administrator.
500	2	22	Timeout when activating console `%s`	An error occurred in the internal connection to the z/OSMF REST TSO service. Retry the command. If the problem persists, contact your z/OSMF administrator.
500	3	1	REST TSO service returned non-200 status code when creating TSO address space.	The internal connection to the z/OSMF REST TSO service returned an error HTTP response when creating a TSO address space. Contact your z/OSMF administrator.
500	3	2	REST TSO service returned an error message when creating a TSO address space.	The internal connection to the z/OSMF REST TSO service returned a success (200) HTTP response with an unexpected message. Contact your z/OSMF administrator.
500	3	3	REST TSO service returned non-200 status code when setting up solicited and unsolicited message display.	The attempt to prepare a TSO address space failed. Retry the request. If the problem persists, contact your z/OSMF administrator.
500	3	4	Cannot retrieve TSO AS key from data that is returned by REST TSO service.	The attempt to prepare a TSO address space failed. Retry the request. If the problem persists, contact your z/OSMF administrator.
500	3	6	Unknown error occurred when creating or getting the TSO AS.	An unknown error occurred during an attempt to create a TSO address space. Retry the request. If the problem persists, contact your z/OSMF administrator.
500	3	7	REST TSO service returned a non-200 status code.	The internal connection to the z/OSMF REST TSO service returned an error HTTP response when issuing a command. Contact the z/OSMF administrator.
500	3	8	Server end program cannot be found.	The server end program of the REST Console API cannot be found. Contact the z/OSMF administrator.
500	3	9	JSON serialization failed when calling a REXX program.	An internal error occurred during the process of converting the response from a TSO service. Contact the z/OSMF administrator.
500	3	10	Unexpected messages were found when calling a REST TSO service.	TSO error messages were found when calling the REST TSO service to issue a command. Contact the z/OSMF administrator.
500	3	11	The maximum number of TSO/E address spaces that are allowed for the current user has been reached.	Refer to message IZUG1127E for a detailed explanation. Display the active TSO/E address spaces, and remove or cancel any address spaces that the user no longer needs. To display the active TSO/E address spaces, enter the command `D TS,ALL` from the operator console. To cancel a TSO/E address space, issue the `C u=user-ID,a=ASID` command from the operator console, where `user-ID` is the user's TSO/E ID and `ASID` is the address space identifier.
500	3	14	An exception occurred when connecting to the TSO/E address space. Error description: `%s`.	The request failed because an error occurred. The context of the error is provided in the message text: `error description, %s`. For details about the error, check the z/OSMF logs. Correct any errors that you find. If the problem persists, contact IBM Support and provide the error details.
500	3	18	The maximum number of TSO/E address spaces has been reached.	Refer to IZUG1105E for a detailed explanation. Display the active TSO/E address spaces, and remove or cancel any address spaces that are no longer needed. To display the active TSO/E address spaces, enter the command `D TS,ALL` from the operator console. To cancel a TSO/E address space, enter the command `C u=user-ID,a=ASID` from the operator console, where `user-ID` is the user's TSO/E ID and `ASID` is the address space identifier.
500	3	19	The TSO/E user account number for the console is not defined for use.	Refer to message IKJ56486I for a detailed explanation. One of the following occurred: The specified account number is not defined to the RACF database. The RACF administrator must first define the account number as a RACF resource and then give the user access using the PERMIT command. However, if the procedure is not in the procedure library, the logon attempt will continue to fail. The RACF class ACCTNUM is not active. The RACF administrator must activate the RACF class ACCTNUM using the SETROPTS command.
500	3	20	TSO/E user account number for the console has not been authorized for the user.	Refer to message IKJ56487I for a detailed explanation. The specified account number is defined to the RACF database. However, this particular user ID is not allowed to use it.
500	3	21	TSO/E user account number for the console is not valid.	Refer to message IKJ56702I for a detailed explanation. The specified account number is incorrect.
500	3	30	An error occurred in the TSO/E address space. Error description: `%s`	The request failed because an error occurred. The context of the error is provided in the message text: `error description, %s.` To obtain more details about the error, check the z/OSMF logs. Correct any errors. If the problem persists, contact the IBM Support Center and provide the error details.
500	5	1	REST TSO service returned a non-200 status code when creating a console.	The internal connection to the z/OSMF REST TSO service returned an error HTTP response when creating a console. Contact the z/OSMF administrator.
500	5	2	Incorrect parameters were passed in when creating a console object.	An internal error occurred during an attempt to create a console. Contact the z/OSMF administrator.
500	5	3	No application data returned when initialize time zone for console service.	An internal error occurred during an attempt to prepare a console. Check the JES spool or other system resources for a resource shortage in the system. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	4	Unexpected IEE136I message: `%s`	The returned IEE136I message, `%s`, is not in the correct format. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	5	Failed to retrieve the time zone from message IEE136I. Local Time: `%s`, UTC Time: `%s`	z/OSMF console service failed to retrieve necessary information from the returned IEE136I message. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	6	Cannot retrieve local time zone.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	7	Create console failed due to a TSO console command error.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	8	The number of consoles has reached the limit.	The maximum number of consoles that are supported by the z/OS Console API was reached. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	10	The requested EMCS console exists in another TSO/E address space.	The console is already created by another user. Delete the other console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	12	User is not authorized to MVS.MCSOPER.`console_name`.	The user requires at least READ access for resource profile MVS.MCSOPER.`console_name`.
500	5	14	CONSPROF is not defined as a TSO/E authorized command.	Refer to message IKJ55354I for a detailed explanation. Ensure that the CONSPROF command resides in an authorized library and that the CONSPROF command name is placed in the authorized command name table. For more information, see Customizing the CONSOLE and CONSPROF commands in z/OS TSO/E Customization.
500	5	17	The value for auth is not valid. The following values are valid: MASTER, ALL, INFO, CONS, IO, SYS.	The command authority for the console is not valid. Valid values are: MASTER ALL INFO CONS IO SYS
500	5	18	The value for routcode is not valid.	The routing codes for the console are not valid. Valid values are: ALL NONE List of one or more routing codes in the range 1-128, enclosed in parentheses. Multiple entries are separated by commas.
500	5	19	The value for mscope is not valid.	The message scope for the console is not valid. Valid values are: ALL LOCAL List of one or more system names, which are enclosed in parentheses. Multiple entries are separated by commas.
500	5	20	The value for storage is not valid.	The value for storage must be a number in the range 1 - 2000.
500	5	21	The value for auto is not valid.	The message automation status for the console is not valid. Valid values are: YES NO
500	5	22	The EMCS console cannot be activated because the user has insufficient access to resource profile CONOPER.	User is not authorized to CONOPER. The user requires at least READ access for resource profile CONOPER CLASS(TSOAUTH).
500	5	23	OPERPARM value is not valid.	Check the console's OPERPARM values for syntax errors. Correct the errors and try the request again.
500	8	13	Recovery of persistence data is not complete, try later.	The z/OS Console API recovery process was not complete when you issued the request. Wait a few seconds, then try the request again.
500	8	14	Cannot get the command response.	The z/OS Console API failed to get the command response. Try the request again. If the problem persists, contact the z/OSMF administrator.

Response content

On successful completion, the service returns a response body, which contains a JSON object. The JSON object varies depending on whether the request was synchronous or asynchronous. For a description of fields in the JSON object, see either of the following tables:

Table 3
Table 4.

Table 3 describes the response content for a successful synchronous issue command response.

Table 3. Response content for a successful synchronous issue command request
Field name	Description
cmd-response	Command response.
cmd-response-url	URL that can be used to retrieve the command response later when the value for cmd-response is empty.
cmd-response-uri	URI that can be used to retrieve the command response later when the value for cmd-response is empty. The URI starts with /zosmf.
cmd-response-key	Key that can be used to retrieve the command response later when the value for cmd-response is empty.
consoleAuth	Command authority for the console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
consoleRoutcde	Routing codes for the console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
consoleMscope	The systems from which this console can receive messages that are not directed to a specific console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
consoleStorage	Amount of storage in kilobytes in the TSO/E user's address space, which can be used for queuing messages to this console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted. Note: If the operand `OPERPARM(STORAGE)` is not specified, the console uses `STORAGE(1)` when the session is established. If the expected console message size is very large, it is recommended that you increase the STORAGE parameter to a larger value. For example, if the expected response size is 10 megabytes, consider setting the STORAGE parameter to `15M`, based on the following formula: `10M+5M=15M`.
consoleAuto	Specifies whether the console receives messages that are eligible for automation. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
sol-key-detected	Returned when sol-key was specified, and unsol-detect-sync was specified as N or not specified. If the keyword was detected in the command response, the value is true. Otherwise, the value is false.
sol-key-timeout	Returned when sol-key was specified. If the execution of the regular expression matching in the sol-key times out, the value is true. Otherwise, the value is false. The default timeout value is 3 seconds.
ipcmsgqbytes	Maximum number of bytes in a single message queue. The returned value is a decimal value in the range 0 - 2147483647. The default value is 2147483647 (or 2G). This field is included only for the first command to be issued with this console. On subsequent uses, this field is omitted. Note: If this value is less than the maximum (2147483647), the z/OSMF Operator Consoles task might lose some solicited or unsolicited messages. If so, your system programmer can use the SETOMVS or SET OMVS command to increase the value of IPCMSGQBYTES.

Table 4 describes the response content for a successful asynchronous issue command response.

Table 4. Response content for a successful asynchronous issue command request
Field name	Description
cmd-response-url	URL that can be used to retrieve the command response.
cmd-response-uri	URI that can be used to retrieve the command response. The URI starts with /zosmf.
cmd-response-key	Key that can be used to retrieve the command response.
consoleAuth	Command authority for the console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
consoleRoutcde	Routing codes for the console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
consoleMscope	The systems from which this console can receive messages that are not directed to a specific console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
consoleStorage	Amount of storage in kilobytes in the TSO/E user's address space, which can be used for queuing messages to this console. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted. Note: If the operand `OPERPARM(STORAGE)` is not specified, the console uses `STORAGE(1)` when the session is established. If the expected console message size is very large, it is recommended that you increase the STORAGE parameter to a larger value. For example, if the expected response size is 10 megabytes, consider setting the STORAGE parameter to `15M`, based on the following formula: `10M+5M=15M`.
consoleAuto	Specifies whether the console receives messages that are eligible for automation. The first time the user issues a command from the console, the value of this field is returned to the user. Otherwise, this field is omitted.
detection-url	The URL that can be used later to retrieve the detection result for detecting a keyword from unsolicited messages. Returned when unsol-key was specified to detect a keyword in unsolicited messages, and unsol-detect-sync was specified as N or not specified.
detection-uri	The URI that can be used later to retrieve the detection result for detecting a keyword from unsolicited messages. Returned when unsol-key was specified to detect a keyword in unsolicited messages, and unsol-detect-sync was specified as N or not specified.
detection-key	Returned when unsol-key was specified to detect a keyword in unsolicited messages. You can use this value to retrieve the result.
status	Status of the unsolicited detection request. Returned when sol-key was specified, and unsol-detect-sync is specified as Y. The values are: expired The detection request is expired. No matching record in the unsolicited messages was found in the time that is specified by detect-time. detected Matching records in the unsolicited messages were found in the time that is specified by detect-time. msg contains the message that contains the keyword. timeout The unsol-detect-timeout elapsed before the detection result completed. regex-timeout The execution of regular expression matching in unsol-key timed out before the result completed. The default timeout value is 3 seconds. detection-url The URL that can be used to retrieve the detection result for detecting a keyword from unsolicited messages. detection-uri The URI that can be used to retrieve the detection result for detecting a keyword from unsolicited messages. detection-key The key that can be used to retrieve the unsolicited keyword detection result. Note: If the URL in the `detection-url` is used to retrieve the result, the unsolkey continues to be detected in the time that is specified by `detect-time`, even if the regular expression detection times out.
ipcmsgqbytes	Maximum number of bytes in a single message queue. The returned value is a decimal value in the range 0 - 2147483647. The default value is 2147483647 (or 2G). This field is included only for the first command to be issued with this console. On subsequent uses, this field is omitted. Note: If this value is less than the maximum (2147483647), the z/OSMF Operator Consoles task might lose some solicited or unsolicited messages. If so, your system programmer can use the SETOMVS or SET OMVS command to increase the value of IPCMSGQBYTES.

The client application can use any one of detection-url, detection-uri, or detection-key to retrieve the detection result.

If a failure occurs, the response body contains a JSON object that describes the error.

Table 5. Response content for an unsuccessful issue command request
Field name	Description
return-code	Category of the error.
reason-code	Specific error.
reason	Text that describes the cause of the error.

Example HTTP interactions

The example in Figure 1 shows a request to issue the system command d a,pegasus synchronously.

Figure 1. Sample request to issue a command synchronously


PUT https://pev076.pok.ibm.com/zosmf/restconsoles/consoles/ibmusecn
{"cmd":"d a,PEGASUS", "routcode" : "ALL"}

The following is the response body for the request. In the response, \r is the return character.

Figure 2. Sample response body

{
"cmd-response-key":"C6557643",
"cmd-response-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C6557643",
"IPCMSGQBYTES":"2147483647",
"consoleRoutcde":"ALL",
"consoleMscope":"ALL",
"consoleAuto":"NO",
"cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C6557643",
"cmd-response":" CNZ4106I 04.22.11 DISPLAY ACTIVITY 532\r  
JOBS     M\/S    TS USERS    SYSAS    INITS   ACTIVE\/MAX VTAM    OAS\r 00002    00015    00002      00032    00005    00001\/00020 00011\r  
PEGASUS  PEGASUS  *OMVSEX  IN   SO  A=0038   PER=NO   SMC=000\r                                      
PGN=N\/A  DMN=N\/A  AFF=NONE\r                                      
CT=006.589S  ET=05.49.06\r                                      
WUID=STC00061 USERID=ZOSMFAD\r                                      
WKL=SYSTEM   SCL=SYSSTC   P=1\r                                      
RGP=N\/A      SRVR=NO  QSC=NO\r                                      
ADDR SPACE ASTE=01ED0E00",
"consoleStorage":"1024",
"consoleAuth":"INFO"}

The example in Figure 3 shows a request to issue the system command d a,PEGASUS synchronously, and attempt to detect PEGASUS in the command response.

Figure 3. Sample request to issue a command and detect a keyword

PUT https://pev076.pok.ibm.com/zosmf/restconsoles/consoles/ibmusecn

{"cmd":"d a,PEGASUS","sol-key":"PEGASUS"}

The following is the response body for the request.

Figure 4. Sample response body

{"cmd-response": "CNZ4106I 07.30.59 2016.011 DISPLAY ACTIVITY 070\r JOBS  M/S   TS USERS   SYSAS   INITS  ACTIVE/MAX
VTAM   OAS\r 00003  00013   00002   00032  00011   00001\V00020   00015\r PEGASUS NOT FOUND", 
"sol-key-detected":true, "cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291", 
"cmd-response-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291",
"cmd-response-key":"C005291"}

The example in Figure 5 shows a request to issue the system command s PEGASUS asynchronously and attempt to detect PEGASUS in the unsolicited messages.

Figure 5. Sample request to issue a system command asynchronously

PUT https://pev076.pok.ibm.com/zosmf/restconsoles/consoles/defcn

{"cmd":"s PEGASUS","unsol-key":"PEGASUS","async":"Y"}

The following is the response body for the request.

Figure 6. Sample response body

{"cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291",
"detection-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/detections\/dec6800",
"detection-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/detections\/dec6800",
"detection-key":"dec6800",
"cmd-response-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291",
"cmd-response-key":"C005291"}

The example in Figure 7 shows a request to issue an s PEGASUS command synchronously, by using the default console, and detect keyword PEGASUS in the unsolicited messages synchronously. The keyword is found in unsolicited messages before the timeout is reached.
Figure 7. Sample request to issue an s PEGASUS command synchronously and detect the keyword PEGASUS
```
PUT https://PEV076.pok.ibm.com/zosmf/restconsoles/consoles/defcn

{"cmd":"s PEGASUS","unsol-key":"PEGASUS","unsol-detect-sync":"Y"}
```
The following is the response body for the request.
Figure 8. Sample response body
```
{"status":"detected","cmd-response":"BPXM023I (ZOSMFAD) CFZ02300I: Configuration property 
httpAuthType is not supported. Setting ignored.","msg":"$HASP100 PEGASUS ON STCINRDR"}
```

The example in Figure 7 shows a request to issue an s PEGASUS command asynchronously, by using the default console, and detect keyword XIAOX in the unsolicited messages synchronously. The detection result is not complete before the timeout (the default of 20 seconds) was reached.

Figure 9. Sample request to issue an s PEGASUS command asynchronously and detect the keyword XIAOX

PUT https://PEV076.pok.ibm.com/zosmf/restconsoles/consoles/defcn

{"cmd":"s PEGASUS","async":"Y","unsol-key":"XIAOX","unsol-detect-sync":"Y"}

The following is the response body for the request.

Figure 10. Sample response body

{"cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/defcn\/solmsgs\/C2790426","detection
-url":"https:\/\/PEV076.pok.ibm.com:443
\/zosmf\/restconsoles\/consoles\/defcn\/detections\/D5303564","detection-uri":"
\/zosmf\/restconsoles\/consoles\/defcn\/detections
\/D5303564","detection-key":"D5303564","status":"timeout","cmd-response-url":"https:
\/\/PEV076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/defcn\/solmsgs\/C2790426",
"cmd-response-key":"C2790426"}