BinaryProcedureEncode (Stringlist subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(28 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Stringlist:BinaryProcedureEncode subtitle}}
{{Template:Stringlist:BinaryProcedureEncode subtitle}}


This method is used to append data in the format used by ''[[Janus Web Server]]'' to store binary data in procedures to a Stringlist.
This method is used to append data in the format used by <var class="product">[[Janus Web Server]]</var> to store binary data in procedures to a <var>Stringlist</var>.
 
BinaryProcedureEncode is a member of the [[Stringlist class]].


==Syntax==
==Syntax==
Line 10: Line 8:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>sl</th>
<tr><th>sl</th>
<td>A Stringlist object.</td></tr>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>string</th>
<tr><th>string</th>
<td>The string to be converted to binary procedure format.</td></tr>
<td>The string to be converted to binary procedure format.</td></tr>
<tr><th>base64Flag</th>
<tr><th>base64Flag</th>
<td>A boolean value: if <tt>.True</tt>, the data is to be base64 encoded in the Stringlist, not binary encoded. This is an optional argument, and it defaults to <tt>.True</tt>, which results in base64 encoding.</td></tr>
<td>A <var>Boolean</var> value: if <var>True</var>, the data is to be base64 encoded in the <var>Stringlist</var>, not binary encoded. This is an optional argument, and it defaults to <var>True</var>, which results in base64 encoding.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul><li>All errors in BinaryProcedureEncode result in request cancellation.<li>This method (along with BinaryProcedureDecode) facilitates converting data in a longstring into the format used for storing binary data in procedures by ''[[Janus Web Server]]''. This format is necessary if binary data is to be stored in ''Model 204'' procedure files because standard procedure formats are not amenable to storing binary data.<li>All data in the binary procedure encoding is wrapped in container data that makes it convenient to store the data in a procedure. By default, the data is also stored in base64 encoding, which represents the data as common displayable characters, making it even more convenient to work with. The convenience of base64 encoding does have a cost, however: it takes four bytes of encoded data to represent three bytes of binary data. In addition, on storage and retrieval, the data must be converted from binary format to base64 encoding and vice versa, which will require some CPU (though probably not a dramatic amount). If the benefits of base64 encoding are determined to not be worth the costs, the second parameter of BinaryProcedureEncode can be set to <tt>.False</tt> to cause the data not to be base64 encoded.<blockquote>The BinaryProcedureDecode method and all other facilities that read the binary procedure encoding format will automatically determine whether the data is base64 encoded or not and do the appropriate decoding.</blockquote><li>The BinaryProcedureEncode method is available in ''[[Sirius Mods]]'' Version 6.7 and later.</ul>
<ul>
<li>All errors in <var>BinaryProcedureEncode</var> result in request cancellation.
 
<li>This method (along with the <var>[[BinaryProcedureDecode (Stringlist_function)|BinaryProcedureDecode]]</var> method) facilitates converting data in a string into the format used for storing binary data in procedures by <var class="product">[[Janus Web Server]]</var>. This format is necessary if binary data is to be stored in <var class="product">Model 204</var> procedure files because standard procedure formats are not amenable to storing binary data.
 
<li>All data in the binary procedure encoding is wrapped in container data that makes it convenient to store the data in a procedure. By default, the data is also stored in base64 encoding, which represents the data as common displayable characters, making it even more convenient to work with. The convenience of base64 encoding does have a cost, however: it takes four bytes of encoded data to represent three bytes of binary data. In addition, on storage and retrieval, the data must be converted from binary format to base64 encoding and vice versa, which will require some CPU (although probably not a dramatic amount). If the benefits of base64 encoding are determined to not be worth the costs, the second parameter of <var>BinaryProcedureEncode</var> can be set to <var>False</var> to cause the data not to be base64 encoded.
 
<p>'''Note: '''The <var>BinaryProcedureDecode</var> method and all other facilities that read the binary procedure encoding format will automatically determine whether the data is base64 encoded or not and do the appropriate decoding. </p>


==Examples==
==Examples==
The BinaryProcedureEncode method takes data from a longstring and places it on a Stringlist, from which it could then be stored in a procedure. In the following example, a GIF (graphical image) is retrieved from another web server using a ''[[Janus Sockets]]'' HTTP helper request and then moved onto a Stringlist with the special binary procedure encoding:
The BinaryProcedureEncode method takes data from a string and places it on a <var>Stringlist</var>, from which it could then be stored in a procedure. In the following example, a GIF (graphical image) is retrieved from another web server using a <var class="product">[[Janus Sockets]]</var> HTTP helper request and then moved onto a <var>Stringlist</var> with the special binary procedure encoding:


<pre>
<p class="code">%req is object httpRequest
%req is object httpRequest
%resp is object httpResponse
%resp is object httpResponse
%gif is longstring
%gif is longstring
Line 35: Line 39:
%procData:binaryProcedureEncode(%gif)
%procData:binaryProcedureEncode(%gif)
%procData:add('END PROCEDURE')
%procData:add('END PROCEDURE')
</pre>
</p>
 
The actual saving of the data to a procedure is not shown, though the example <var>Stringlist</var> could easily be passed to a <var>[[Daemon class|Daemon]]</var> object <var>[[Run (Daemon function)|Run]]</var> method to create the procedure.
The actual saving of the data to a procedure is not shown, though the example Stringlist could easily be passed to a Daemon object Run method ([[Run (Daemon function]]) to create the procedure.


[[Category:Stringlist methods|BinaryProcedureEncode function]]
==See also==
{{Template:Stringlist:BinaryProcedureEncode footer}}

Latest revision as of 21:51, 30 October 2012

Convert from binary procedure format to string (Stringlist class)


This method is used to append data in the format used by Janus Web Server to store binary data in procedures to a Stringlist.

Syntax

sl:BinaryProcedureEncode( string, [base64Flag])

Syntax terms

sl A Stringlist object.
string The string to be converted to binary procedure format.
base64Flag A Boolean value: if True, the data is to be base64 encoded in the Stringlist, not binary encoded. This is an optional argument, and it defaults to True, which results in base64 encoding.

Usage notes

  • All errors in BinaryProcedureEncode result in request cancellation.
  • This method (along with the BinaryProcedureDecode method) facilitates converting data in a string into the format used for storing binary data in procedures by Janus Web Server. This format is necessary if binary data is to be stored in Model 204 procedure files because standard procedure formats are not amenable to storing binary data.
  • All data in the binary procedure encoding is wrapped in container data that makes it convenient to store the data in a procedure. By default, the data is also stored in base64 encoding, which represents the data as common displayable characters, making it even more convenient to work with. The convenience of base64 encoding does have a cost, however: it takes four bytes of encoded data to represent three bytes of binary data. In addition, on storage and retrieval, the data must be converted from binary format to base64 encoding and vice versa, which will require some CPU (although probably not a dramatic amount). If the benefits of base64 encoding are determined to not be worth the costs, the second parameter of BinaryProcedureEncode can be set to False to cause the data not to be base64 encoded.

    Note: The BinaryProcedureDecode method and all other facilities that read the binary procedure encoding format will automatically determine whether the data is base64 encoded or not and do the appropriate decoding.

    Examples

    The BinaryProcedureEncode method takes data from a string and places it on a Stringlist, from which it could then be stored in a procedure. In the following example, a GIF (graphical image) is retrieved from another web server using a Janus Sockets HTTP helper request and then moved onto a Stringlist with the special binary procedure encoding:

    %req is object httpRequest %resp is object httpResponse %gif is longstring %procData is object stringList ... %resp = %req:get %gif = %resp:content(1) %procData = new %procData:add('IN FILE WHATEVER PROCEDURE MUMBLE.GIF') %procData:binaryProcedureEncode(%gif) %procData:add('END PROCEDURE')

    The actual saving of the data to a procedure is not shown, though the example Stringlist could easily be passed to a Daemon object Run method to create the procedure.

    See also