HttpResponse Method (RUNTIME)

9.9A

The HttpResponse method formats program data into a valid Http message that is output to the runtime StdOut channel and terminates any active FastCGI session. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A RUNTIME object that has been previously declared.

return

Optional. A Numeric Variable that returns the pass\failure values for the execution of the method.

httpcode

Required. A Numeric Variable or decimal number that specifies the http return code to be included in the http message body. This should be a valid http code or the http code of 500 is used.

mimetype

Optional. A Character String Variable or string literal that specifies the mime type of the data that is included in the body parameter.

body

Optional. A Character String Variable or string literal that contains the HTTP body text to be sent in the response. The body text is a text, JSON, or XML string that is returned in the response message.

extra

Optional. A Character String Variable or string literal that contains any other generated HTTP header fields to be included in the response message. Each line must be terminated with the 0x0D and 0x0A characters.

outfile

Optional. A Character String Variable or string literal that contains the name of a data file where the response data is to be stored. This parameter debugs the REST program output.

options

Optional. A Numeric Variable or decimal number that specifies a bit mask value that controls the behaviors of this method.

Flags Affected: OVER, ZERO

Note the following:

1. The ZERO flag is set if the {return} value is zero.

2. The {return} value indicates whether the method passes or fails as follows:

 

Value	Description
0	Method executed successfully.
1	PL/B program attempted to execute the 'HttpResponse' method more than once for REST API response. All attempts to execute this method after the first REST API response are ignored.
2	The {httpcode} value is invalid.
3	Unable to open CGI event for Windows IPC interactions.
4	Unable to create CGI event for Windows IPC interactions.
5	CGI event timeout waiting for Windows IPC interaction.

 

3. The OVER flag is set TRUE if the {return} variable is too small to receive the numeric result.

4. The supported {httpcode} values must be a valid http response code as shown in the following table. Any {httpcode} values not defined in the following table are replaced with a '500 Internal Server Error' message and the method {body} is replaced with an appropriate error message.

5. The supported {httpcode} values must be a valid http response code as shown in the following table.

 

Http Code Value	<pre-defined string>
200	OK
201	Created
202	Accepted
204	No Content
205	Reset Content
206	Partial Content
301	Moved Permanently
302	Found
303	See Other
304	Not Modified
400	Bad Request
401	Unauthorized
402	Payment Required
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable
407	Proxy Authentication Required
408	Request Timeout
409	Conflict
410	Gone
411	Length Required
412	Precondition Failed
413	Payload Too Large
414	URI Too Long
415	Unsupported Media Type
416	Range Not Satisfiable
417	Expectation Failed
418	I'm a teapot
421	Misdirected Request
422	Unprocessable Entity
423	Locked
424	Failed Dependency
426	Upgrade Required
428	Precondition Required
429	Too Many Requests
431	Request Header Fields Too Large
451	Unavailable For Legal Reasons

 

6. The {mimetype} identifies the mime type (i.e., format) of the data that is included in the {body} parameter. If the {mimetype} is not given, the HttpResponse uses the 'text/plain' as the default. Simple mime types can be specified as:

 

"text/html"

"application/json"

"application/xml"

 

7. The {body} is a text, JSON string, or XML string generated and provided by the executing program. The {body} format and syntax that is generated by the user program should be consistent with the {mimetype} parameter.

8. The {extra} parameter specifies any other HTTP header fields that are to be included in the response message. For example, a POST operation might return the location of the new item as follows:

 

Location: http://127.0.0.1/MyServices/PhoneMsg/24

 

9. The {options} parameter is a bitmask value the forces specialized behaviors for the execution of the RUNTIME 'HttpResponse' method. The bitmask values are defined as follows:

 

$HttpResp_NoAccessControl EQU 1

 

When this bit is set the 'HttpResponse' does not include the default 'Access-Control-Allow' headers fields in the HTTP message. See the 'PL/B Web Server' manual for details on these header fields.

 

$HttpResp_AllowCacheControl EQU 2

 

10. When this bit is set the 'HttpResonse' does not include the default 'Cache-Control:' HTTP header field in the HTTP message headers. See the 'PL/B Web Server' manual for details on this header field.

11. This method is not available under Windows CE or the PL/B Web Server.

See Also: RUNTIME, RUNTIME Methods, Method Syntax