Get the detect result for unsolicited messages

Use this operation to get the result for detecting a keyword in unsolicited messages after an Issue Command request. The command must have been issued with the unsol-key field.

HTTP method and URI path

GET /zosmf/restconsoles/consoles/consolename/detections/Dkey-number
GET /zosmf/restconsoles/consoles/defcn/detections/Dkey-number

where:

consolename: is the name of the EMCS console that was used in the Issue Command request.
defcn: indicates that name of the console that was used to issue the command was generated by the REST Console API.
Dkey-number: is the detection key from the Issue Command request.

The URL is be returned by the Issue Command request in the detection-url field.

Query parameters

None.

Description

This operation gets the results of attempting to detect a keyword in the unsolicited messages that were issued following an Issue Command request. The keyword being detected was specified with the unsol-key field on the Issue Command service.

On successful completion, HTTP status code 200 is returned. The response content is described in Response content.

The Issue Command service returns the URL in the detection-url field. For more information about the response content of the Issue Command service, see Response content.

Request content

None.

Authorization requirements

See Required authorizations.

HTTP status codes

On successful completion, HTTP status code 200 is returned and the response body is provided, as described in Response content.

Otherwise, the HTTP status codes in Table 1 are returned for the indicated errors.

Table 1. HTTP error response codes for a detect result for unsolicited messages request
HTTP Status	Return Code	Reason Code	Reason	Description
400	1	3	No match for method GET 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	14	Invalid 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.
500	3	1	REST TSO service returned a non-200 status code when creating a TSO address space.	The internal connection to the zOSMF REST TSO service returned an error HTTP response when creating a TSO address space. Contact your zOSMF administrator.
500	3	2	REST TSO service returned an error message when creating a TSO address space.	The internal connection to the zOSMF REST TSO service returned a success (200) HTTP response with an unexpected message. Contact your zOSMF administrator.
500	3	3	REST TSO service returned a 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 zOSMF administrator.
500	3	4	Cannot retrieve TSO AS key from data returned by REST TSO service.	The attempt to prepare a TSO address space failed. Retry the request. If the problem persists, contact your zOSMF administrator
500	3	7	REST TSO service returned a non-200 status code.	The internal connection to the zOSMF REST TSO service returned an error HTTP response when issuing a command. Contact the zOSMF administrator.
500	3	8	Server end program cannot be found.	The server end program of the REST Console API cannot be found. Contact the zOSMF administrator.
500	3	9	JSON serialization failed when calling a REXX program.	An internal error occurred during the process of translating the response from a TSO service. Contact the zOSMF 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 zOSMF administrator.
500	5	1	REST TSO service returned a non-200 status code when creating a console.	The internal connection to the zOSMF REST TSO service returned an error HTTP response when creating a console. Contact the zOSMF administrator.
500	5	2	Invalid parameters were passed in when creating a console object.	An internal error occurred during an attempt to create a console. Contact the zOSMF administrator.
500	5	3	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	4	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	5	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	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 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 supported by the z/OS Console API was reached. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	9	Cannot find the result for specified detection ID.	Cannot find the result for the specified detection ID. Ensure that the detection ID is correct.
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 retry the request.
500	10	2	The detection result you requested cannot be retrieved due to earlier shutdown of the z/OSMF server.	The detection result cannot be retrieved because of an earlier shutdown of zOSMF server.

Response content

On successful completion, the service returns a response body, which contains a JSON object. Table 2 lists the fields in the JSON object.

Table 2. Response content for a successful get detect result request
Field name	Description
status	Status of the detection request: waiting The detection request is still valid, the keyword has not yet been detected in the unsolicited messages. expired The detection request expired, and the keyword was not found in the unsolicited messages. The detection request expires when the value for detect-time on the issue command request is exceeded. detected The keyword was found in the unsolicited messages.
msg	Returned when the value of status is detected. This is the message that contains the keyword that was detected.

If a failure occurs, the response body contains a JSON object with a description of the error.

Table 3. Response content for an unsuccessful get detect result 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 interaction

The example in Figure 1 shows a request to get the results for a detect request. The command was issued with a generated console name. The detection key returned by the issue command request is D002185.
Figure 1. Sample request to get the detect result
```
GET https://pev076.pok.ibm.com/zosmf/restconsoles/consoles/defcn/detections/D002185
```
The following is the response body for the request. The request is still valid, but the keyword has not been found.
Figure 2. Sample response body for a get detect result request
```
{"status":"waiting","msg":""}
```
The example in Figure 1 shows a request to get the results for a detect request. The command was issued with a generated console name. The detection key that was returned by the issue command request is D122033.
Figure 3. Sample request to get the detect result
```
GET https://pev076.pok.ibm.com/zosmf/restconsole/consoles/defcn/detections/D122033
```
The following is the response body for the request. The keyword was found. In the response, \r is the return character.
Figure 4. Sample response body for a successful get detect result request
```
{"status":"detected","msg":"BPXM023I (ZOSMFAD)\r CFZ12584W: CIM Runtime Environment Userid currently only has READ\r access to
BPX.SERVER. It is recommended to have either UPDATE access\r to BPX.SERVER or has to be UID 0."}
```