Functions

The following sections describe functions in the UP.SDK Perl HDML utility library.

---

OutputDeck()

Description

OutputDeck() prints an HDML deck with appropriate HTTP headers to standard output.

Synopsis

require 'HDMLUtils.pl';
...
&AppUtils::OutputDeck($deck);

Arguments

Argument	Meaning
$deck	The deck to output.
$charset	The character set used in the deck. If you don't specify a character set, none is used.

Example

The following code:

#!/usr/local/bin/perl5.001
#
require 'HDMLUtils.pl';
$DECK =
    "<HDML VERSION=3.0>".
    "<DISPLAY>".
    "<LINE>Trading Alert:".
    "<LINE>INTCQH Puts".
    "<LINE>Exceed Black-Scholes valuation".
    "</DISPLAY>".
    "</HDML>";
&AppUtils::OutputDeck($DECK);

generates the HTTP response below and the display card shown in Figure 5-1.

Content-type: text/x-hdml; charset=utf-8

<HDML VERSION=3.0>
    <DISPLAY>
        <LINE>Trading Alert:
        <LINE>INTCQH Puts
        <LINE>Exceed Black-Scholes valuation
    </DISPLAY>
</HDML>

FIGURE  5-1.     Display card generated by OutputDeck()

---

OutputDigest()

Description

Prints an UP.Link digest with appropriate HTTP headers to standard output.

Synopsis

require 'HDMLUtils.pl';
...
&AppUtils:OutputDigest($digest->asString();

Arguments

Argument	Meaning
$digest	The digest to output.

Example

The following code generates the digest depicted in Figure 5-2:

#! /usr/local/bin/perl5.001
# Sample libraries path (sdk_dir/examples/apputils)
BEGIN { push (@INC, "../apputils"); }
require Digest;
require 'HDMLUtils.pl';

# Define two HDML decks with display cards.
$deck1 = '<HDML VERSION=3.0>'.
    '<DISPLAY>'.
    '<ACTION TYPE=ACCEPT TASK=GO DEST="?NS=DECK2">'.
    'This is deck1'.
    '</DISPLAY>'.
    '</HDML>';
$deck2 = '<HDML VERSION=3.0>'.
    '<DISPLAY>'.
    '<ACTION TYPE=ACCEPT TASK=GO DEST="?NS=DECK1">'.
    'This is deck2'.
    '</DISPLAY>'.
    '</HDML>';

# Create the digest
my $digest = new Digest;

# Add decks to the digest along with their content locations
$digest->addHDMLDeck("?NS=DECK1", $deck1);
$digest->addHDMLDeck("?NS=DECK2", $deck2);

# Output the digest
&AppUtils::OutputDigest($digest->asString());

FIGURE  5-2.     A digest containing two decks

---

HTTPEscapeString()

Description

HTTPEscapeString() converts characters that are reserved in URLs to legal escape sequences. For example, if you pass HTTPEscapeString() a string containing spaces, it converts them to plus signs (+).

Synopsis

require 'HDMLUtils.pl';
...
&AppUtils::HTTPEscapeString($string);

Arguments

Argument	Meaning
$string	The string to escape.

Example

The following code:

#!/usr/local/bin/perl5.001
#
require 'HDMLUtils.pl';
$estr = &AppUtils::HTTPEscapeString("John Smith");
print $estr;
. . .

prints:

John+Smith

---

HDMLEscapeString()

Description

HDMLEscapeString() converts characters that are reserved in HDML (such as angle brackets) to legal escape sequences. For example, if a URL contains an ampersand, HDMLEscapeString() converts it to an & string.

Synopsis

require 'HDMLUtils.pl';
...
&AppUtils::HDMLEscapeString($string);

Arguments

Argument	Meaning
$string	A string containing reserved characters.

Example

The following code:

#!/usr/local/bin/perl5.001
#
require 'HDMLUtils.pl';
$estr = &AppUtils::HDMLEscapeString("S&P");
print $estr;

prints:

S&amp;P

---

ParseCGIVars()

ParseCGIVars() parses CGI environment variables into an associative array.

Description

Extracts the key-data pairs from the CGI environment and into an associative array.

Returns

An associative array of all CGI environment key-data pairs.

Example

The following code prints the UP.Link subscriber number after a request from an UP.Link server:

#!/usr/local/bin/perl5.001
#
require 'HDMLUtils.pl';
%cgiVars = &AppUtils::ParseCGIVars();
$subno = $cgiVars{"HTTP_X_UP_SUBNO"};
$DECK = sprintf "<HDML VERSION=3.0><DISPLAY>Subscriber: %s </DISPLAY></HDML>", $subno;
&AppUtils::OutputDeck($DECK);

---

ParseURLEncodedString()

Description

Extracts key-data pairs from a URL-encoded string.

Synopsis

require 'HDMLUtils.pl';
...
&AppUtils::ParseURLEncodedString($string);

Arguments

Argument	Meaning
$string	The URL-encoded input string to parse.

Returns

Returns an associative array of the key-data pairs in the specified string.

Example

The following code:

#!/usr/local/bin/perl5.001
#
require 'HDMLUtils.pl';
$string = "abcd=this+is+a+test&xyz=hello%26world";
%parsedVars = &AppUtils::ParseURLEncodedString($string);
$abcd = $parsedVars{"abcd"};
print $abcd;

prints:

This is a test

---

ErrorExit()

Description

Prints an error deck to standard output, then exits.

Synopsis

require 'HDMLUtils.pl';
...
&AppUtils::ErrorExit();

Arguments

Argument	Meaning
$str1	Error description.
$str2	Additional error description.

Example

The following code:

#!/usr/local/bin/perl5.001
#
require 'HDMLUtils.pl';
&AppUtils::ErrorExit("1234", "CBOE connection lost.");

generates the HTTP response below and the display card shown in Figure 5-3.

Content-type: text/x-hdml; charset=utf-8
<HDML VERSION=3.0 TTL=0>
    <DISPLAY>
        <LINE>Service Error
        <LINE>1234
        <LINE>Connection lost
    </DISPLAY>
</HDML>

FIGURE  5-3.     Display card generated by ErrorExit()