Any functionality specified can be limited to the POST method by specifying the /POST qualifier. If the script was activated via the GET method the utility will simply exit with a success status.
One of the primary functions of DEFORM is to parse POST method requests of Content-Type: ``application/x-www-form-urlencoded''. This content type is generated by <FORM METHOD=POST ACTION="..."> HTML and comprises a body in URL-escaped form format.
An example form would be:
<FORM METHOD=POST ACTION="/example/only"> <INPUT TYPE=text NAME=field_one VALUE="default text"> <INPUT TYPE=radio NAME=field_two VALUE="two-a" CHECKED> two-a <INPUT TYPE=radio NAME=field_two VALUE="two-b"> two-b <INPUT TYPE=radio NAME=field_two VALUE="two-c"> two-c <INPUT TYPE=textarea NAME=field_three ROWS=4 COLS=32 VALUE="Line 1; Line 2; " <INPUT TYPE=submit> </FORM>
This would generate an HTTP request body comprising:
field_one=default%20text&field_two=two-a&field_three=Line%201;%0aLine%202;%0a
To make these form fields conveniently available to scripts DEFORM will parse the request body into a series of DCL symbols named after the corresponding field and containing the field's value. The field name is prefixed with WWW_FORM_ to create the symbol name. That is, a field within the body comprising ``test_field=Test%20value!'' would be represented by a symbol named WWW_FORM_TEST_FIELD and containing the string ``Test value!''. This naming convention corresponds to the CERN HTTPd VMS implementation and to the HFRD implementation (for further information see the Technical Guide to the HFRD hypertext enviroment).
This functionality is activated by using the /SYMBOLS qualifier.
An example form (the same as in the earlier example) would be:
<FORM METHOD=POST ACTION="/example/only"> <INPUT TYPE=text NAME=field_one VALUE="default text"> <INPUT TYPE=radio NAME=field_two VALUE="two-a" CHECKED> two-a <INPUT TYPE=radio NAME=field_two VALUE="two-b"> two-b <INPUT TYPE=radio NAME=field_two VALUE="two-c"> two-c <INPUT TYPE=textarea NAME=field_three ROWS=4 COLS=32 VALUE="Line 1; Line 2; " <INPUT TYPE=submit> </FORM>
This would generate symbols comprising:
$ SHOW SYMBOL WWW_FORM_* WWW_FORM_FIELD_ONE == "default text" WWW_FORM_FIELD_TWO == "two_a" WWW_FORM_FIELD_THREE == "Line 1;.Line 2;.."
Symbols could be processed in DCL using the following syntax:
$ DEFORM /SYMBOLS $ IF .NOT. $STATUS THEN EXIT $ IF WWW_FORM_FIELD_TWO .EQS. "two-a" $ THEN WRITE SYS$OUTPUT "a:" + WWW_FORM_FIELD_THREE EXIT $ ENDIF $ IF WWW_FORM_FIELD_TWO .EQS. "two-b" $ THEN WRITE SYS$OUTPUT "b:" + WWW_FORM_FIELD_THREE EXIT $ ENDIF
This is the DCL procedure script.
This provides an online demonstration.
When this link is first selected a GET method request is generated
and the script redirects to an HTML file providing a form. When the form is
submitted a POST method request is generated. This parses the form
fields and returns an HTML document show the field values.
5.1.2 - Constraints
Symbol names are limited to 255 characters. This should be more than
adequate. Symbol values are also limited to 255 characters. This may be of
greater concern in some circumstances. Due to this VMS Run-Time Library
constraint the only alternative is parse the body into a temporary file (see
5.2 - File).
5.2 - File
Due to the limitations on DCL symbol size (see 5.1.2 - Constraints) it may sometimes be necessary to parse the contents of the request body into a temporary file, and process that. The file is formatted as a series of form field names on a single line followed by the form value on one or more subsequent lines. Multiple field names and their values are separated by blank lines.
Any field with an empty value contains only the name line with a blank line following immediately.
All non-empty field value lines begin with a single equal symbol. Hence when processing, all values begin from the second character in the line.
Where the value contains multiple lines (as with a <INPUT TYPE=textarea ...> HTML construct) these lines are reproduced following the field name. If the value contained a blank line, this is differentiated from the field-separating blank lines by the leading equal symbol.
This functionality is activated by using the /FILE qualifier.
An example form (the same as in the earlier example) would be:
<FORM METHOD=POST ACTION="/example/only"> <INPUT TYPE=text NAME=field_one VALUE="default text"> <INPUT TYPE=radio NAME=field_two VALUE="two-a" CHECKED> two-a <INPUT TYPE=radio NAME=field_two VALUE="two-b"> two-b <INPUT TYPE=radio NAME=field_two VALUE="two-c"> two-c <INPUT TYPE=textarea NAME=field_three ROWS=4 COLS=32 VALUE="Line 1; Line 2; " <INPUT TYPE=submit> </FORM>
This would generate a file comprising:
field_one =default text field_two =two-a field_three =Line 1; =Line 2; =
To ensure a unique file name it is generated from time components. After successful creation the file name is available to the script via the DEFORM_FILE symbol. Please ensure the file is deleted when processing is concluded. The file could be opened, processed, closed and deleted in DCL using the following syntax:
$ DEFORM /FILE $ IF .NOT. $STATUS THEN EXIT $ ON ERROR THEN GOTO ERROR_TRAP $ OPEN /READ DFILE 'DEFORM_FILE' . . . $ ERROR_TRAP: $ IF F$TRNLNM("DFILE") .NES. "" THEN CLOSE DFILE $ DELETE 'DEFORM_FILE';*
This is the DCL procedure script.
This provides an online demonstration.
When this link is first selected a GET method request is generated
and the script redirects to an HTML file providing a form. When the form is
submitted a POST method request is generated. This parses the form
fields into a plain text file. The file is opened and read to generate an
HTML document showing the field values. The file then is closed and deleted.
5.2.2 - Other
The DEFORM utility can also be used to conveniently perform other functions in the POST environment. These include: