WebSiphon Environment

appendLog

beep

exec

isQuitting

run

saveGlobals

throw

Scheduling

reschedule

rescheduleFor

schedule

scheduleFor

sleep

yield

Semaphores

acquireSem

attemptSem

releaseSem

semCount

Variables and Data Types

coerceTo

defined

sizeOfBinary

typeOf

undefined

Process Control

getCurrentProcess

getFrontProcess

getProcessInfo

getProcessList

launchProcess

quitProcess

setFrontProcess

Commerce

authorizeCreditCard

creditCardType

verifyCreditCard

Other

calcCRC

checkCRC

getImageSize

getServerFonts

random

sendAppleEvent

Parameter	Description
message	text to add to log

This function will append the string message to WebSiphon's main text log file in addition to displaying it on-screen if the log window is open on the server. This function is useful in creating a central log file for your server.

The current date and time are automatically inserted at the beginning of every log entry.

Writing to a log file other than WebSiphon's may be done using the text file functions.

Example:

appendLog("Something terrible went wrong!");

Parameter	Description
[num]	number of times to beep [optional]

This function will play the standard beep alert sound on the server once, or num times if it is defined.

Example:

if error_code = "RED" then
  beep(3);
end if;

Parameter	Description
siphonscript	one or more valid siphonscript statements
[variable-list]	list of name/value pairs [optional]

This function allows execution of arbitrary SiphonScript statements. The optional variable-list parameter is a list of variable names and values, in the format: [[varA, valueA], [varB, valueB], ...]. These runtime instance variables have the same scope as those created by GET or POST arguments.

Arbitrary SiphonScript execution is also accessible via an AppleEvent interface using the 'run script' verb.

Example:

result = exec(script_code, [["sid" session_user] ["page" 2]]);

See Also:

• run

Indicates if WebSiphon is currently in the middle of a quit sequence.

Parameter	Description
template-path	URI to template
[variable-list]	list of name/value pairs [optional]

This function allows you to execute any WebSiphon template from within any other template. The template to run is specified with its URI in template-path. A list of variable names and values are passed as a list in variable-list.

The returned value will be the text results of the template (much as would be output to a web browser if the template were run directly). If you wish to include the output of template, use the print statement or enclose the function call within braces (outside of a SiphonScript block).

Examples:

1. output = run("/my_template.t", [["mode" "t"] ["sid" session_id]]);

2. print run("/people/index.html");

Immediately saves all global variable data to the disk storage.

Parameter	Description
[err-num]	runtime error number reference [optional]
[err-string]	explanatory string [optional]

Used in conjunction with try/catch exception handling.

See Also:

• try/catch statements

Parameter	Description
delay	delay in seconds

Schedules the current template to be run again in delay seconds.

Parameter	Description
time-secs	time in seconds since January 1st, 1904

Schedules the current template to be run again at time-secs. The time-secs paramater is the time in seconds since January 1st, 1904.

Parameter	Description
template-name	template name or path
delay	delay in seconds

Schedules the template specified in template-name to be run in delay seconds.

Parameter	Description
template-name	template name or path
time-secs	time in seconds since January 1st, 1904

Schedules the template specified in template-name to be run again at time-secs. The time-secs paramater is the time in seconds since January 1st, 1904.

Parameter	Description
delay	delay in seconds

Pauses execution of the template for the number of seconds specified in delay, without using valuable CPU cycles.

See Also:

• yield

Yields CPU cycles to other currently executing templates.

See Also:

• sleep

Parameter	Description
sem-name	semaphore name
[initial-count]	permitted concurrent threads [optional]

Attempts to acquire a semaphore whose name is sem-name, and will block the current template from executing until the semaphore is available.

The optional initial-count parameter may be used to enable more than one executing template to acquire the named semaphore for use. If not specified, the parameter uses its default value of 1 so no other template can acquire the semaphore until it has been released.

Parameter	Description
sem-name	semaphore name
[initial-count]	permitted concurrent threads [optional]

Attempts to acquire a semaphore whose name is sem-name, and will return a boolean indicating whether or not it was successful rather than blocking.

The optional initial-count parameter may be used to enable more than one executing template to acquire the named semaphore for use. If not specified, the parameter uses its default value of 1 so no other template can acquire the semaphore until it has been released.

Parameter	Description
sem-name	semaphore name
[initial-count]	permitted concurrent threads [optional]

Releases a semaphore whose name is sem-name, which will allow other templates to acquire it.

The optional initial-count parameter may be used to enable more than one executing template to acquire the named semaphore for use. If not specified, the parameter uses its default value of 1 so no other template can acquire the semaphore until it has been released.

Parameter	Description
sem-name	semaphore name

Returns the current count of the semaphore whose name is sem-name. If the returned value is positive, then that number of threads can acquire the semaphore before blocking. A negative value indicates the number of threads waiting on the semaphore to continue execution.

Parameter	Description
value	any value
new-type	standard data type

Given any value in value, this function will coerce it to the data type specified in new-type and return the coerced value.

Valid values for new-type:

"null"        "string"
"integer"     "list"
"float"       "binary"

Example:

the_num = "12";
print typeOf(the_num);

>> string

the_num = coerceTo ( the_num, "integer" );
print typeOf(the_num);

  >> integer

See Also:

• typeOf

Parameter	Description
varname	any variable name

This function will return true if the variable name varname has been assigned a value and is therefored defined.

This is very useful when working with GET or POST arguments, as you can check to see if a variable has been defined, and give it a default value if it has not.

Example:

if not defined(graphics) then
  graphics = true;  // Default is to display graphics.
end if;
...
if graphics then
  << <img src="HomeGraphic.jpg"> >>
else
  << <h1>Welcome to My Home Page!</h1> >>
end if;

See Also:

• undefined

Parameter	Description
binary-data	any binary data

Given binary-data, this function will return the size of the item in bytes as an integer.

See Also:

• sizeOf
• strlen

Parameter	Description
value	any value

Given value, this function will return its data type as a string.

The returned string may be one of:

"null"        "string"
"integer"     "list"
"float"       "binary"

See Also:

• coerceTo

Parameter	Description
varname	any variable name

This function will return true if the variable name varname has not been assigned a value and is therefored undefined.

This is very useful when working with GET or POST arguments, as you can check to see if a variable has been defined, and give it a default value if it has not.

Example:

if undefined(graphics) then
  graphics = true;  // Default is to display graphics.
end if;
...
if graphics then
  << <img src="HomeGraphic.jpg"> >>
else
  << <h1>Welcome to My Home Page!</h1> >>
end if;

See Also:

• defined

Returns the name of the application process that is currently executing on the server, which should nearly always be "WebSiphon.acgi".

Example:

print getCurrentProcess();

>> WebSiphon.acgi

Returns the name of the application process which is currently active on the server. This is the application whose windows and menu bar are the front-most.

Example:

print getFrontProcess();

>> WebSiphon.acgi

Parameter	Description
process-name	any running process name

Given the name of a currently running application process in process-name, this function will return a list containing details about the process.

The returned list has the following structure:

Returns a list containing the names of all application processes running on the server.

Parameter	Description
process-path	full path to application

Given the full path to an application in process-path, this function will launch it into the background.

Parameter	Description
process-name	any running process name

Given the name of a running application process in process-name, this function will send the standard Quit AppleEvent to the process.

Parameter	Description
process-name	any running process name

Given the name of a running application process in process-name, this function will set it as the front-most process on the server.

Parameter	Description
sale-amount	dollar amount of sale
card-number	credit card number (no spaces)
card-expiration	credit card expiration date

Given a credit card number in card-number and its expiration date in card-expiration, this function will communicate with MacAuthorize to authorize a sale in the amount of sale-amount. The card-number parameter should be the numbers only and not contain any formatting spaces or other delimiters. The card-expiration paramter should be in the format MMYY with no slashes or other delimiters.

A list is returned detailing the results of the transaction. The first item in the returned list indicates the status, and may be one of:

"Unknown"     "Pending"     "Authorized"
"Declined"    "Referral"    "Error"
"Voided"      "Other"       "Pickup"

The second item in the returned list is a description of the result. If the sale was declined, this description may be displayed to the user.

Example:

result = authorizeCreditCard("99.00", "1234123412341234", "1099");
if (result'1 = "Authorized")
  print "Thanks!";
else
  print "Sorry, your credit card was declined: " & result'2;
end if;

Parameter	Description
card-number	credit card number (no spaces)

Given any credit card number in card-number, with no spaces or other delimiter, this function will return a string indicating what type of credit card it is.

The returned string may be one of:

"American Express"    "JCB"
"Diner's Club"        "MasterCard"
"Visa"                "Discover"
"enRoute"             "Unknown"

Parameter	Description
card-number	credit card number (no spaces)

Given a credit card number in card-number, with no spaces or other delimiter, this function will return a boolean indicating if it is a valid credit card account.

Parameter	Description
value	any value

Given value, this function calculates and returns a CRC on the value. This can be used in conjunction with checkCRC() to check data integrity after passing values through URL or POST arguments, and is quite helpful for tracking user sessions securely.

See Also:

• checkCRC

Parameter	Description
value	any value
crc	crc string to check

Given value, this function returns a boolean indicating whether or not crc is a valid CRC of the value. This can be used in conjunction with calcCRC() to check data integrity after passing values through URL or POST arguments, and is quite helpful for tracking user sessions securely.

See Also:

• calcCRC

Parameter	Description
image-file	full path to image file

Given the full pathname to a graphic file in image-file, a list is returned containing the image's width, height, and depth (in bits per pixel). If the file does not exist, or if an error occurred, the list will contain all zeros.

File formats supported are GIF 87a, GIF 89a, JPEG, and progressive JPEG.

The returned list has the following structure:

Examples:

1. file_path = template_path & "icon.gif";
   the_size = getImageSize(file_path);
   print the_size;
   
   >> 32 32 8

2. print getImageSize("non-existant-file.jpg");
   
   >> 0 0 0

Parameter	Description
[min]	lower end of returned range [optional]
[max]	upper end of returned range [optional]
[list]	any list [optional]

This function is used to create random numbers or other types. It reacts in different ways depending on what parameters are defined:

• If no parameters are defined, a random long integer will be returned.
• If max is defined, but min is not, then a random integer between 0 and max will be returned.
• If both min and max are defined, a random integer between the two will be returned.
• If a list of items is passed to random in list, a random item in the list will be returned.

Examples:

1. // print a random number
   print random();
   
   >> 1263

2. // print a random number from 0 to 99
   print random(99);
   
   >> 62

3. // print a random number from 1 to 10
   print random(1, 10);
   
   >> 7

4. // print a random day of the work week
   print random(["monday" "tuesday" "wednesday" "thursday" "friday"]);
   
   >> friday

Parameter	Description
process-name	the application name or signature
event-class	the event class
event-id	the event id
[param-list]	list of name/value pairs or AEGizmo string [optional]

This function allows you to send an AppleEvent direction from within a SiphonScript. The event will be sent to the application whose name is process-name, and will use event-class and event-id as specified. The param-list should be a list of AppleEvent parameter IDs and values.

Alternatively, param-list may be a complex AEGizmo formatted string. This method is required to send object model AppleEvents. Though cryptic in nature, the functionality is very powerful. We recommend that users who wish to use this feature utilize a utility to help build the complex string, such as West Code Software's Capture AE control panel available at the URL:

ftp://ftp.WestCodeSoft.com/OneClick_Scripting_Tools/CaptureAE.sit.hqx

Examples:

1. // This example sends the standard CGI AppleEvent to Tango, therefore
   // "back-ending" the CGI to WebSiphon. The event class shown in the example 
   // below is actually "WWW<omega>" using the Macintosh extended omega character 
   // yielded by pressing option-Z on your keyboard. It is shown as "WWW*" below 
   // as the omega character is not printable in an HTML page.
   app_name = "Tango.acgi";
   the_script = "/test.qry";
   result = sendAppleEvent(app_name, "WWW*", "sdoc", 
            [["scnm" the_script] ["kfor" search_arguments] 
             ["user" username] ["pass" password] ["frmu" from_user] 
             ["addr" client_address] ["post" post_arguments]
             ["meth" http_method] ["svnm" server_name] ["svpt" server_port]
             ["ctyp" content_type] ["refr" referer] ["Agnt" user_agent] 
             ["Kact" action_name] ["Kapt" action_path]
             ["Kcip" client_ip_address] ["Kfrq" full_client_request]]);
   // The result variable now holds the complete result returned from Tango, 
   // including the HTTP header.

2. // This example sends the "Stop Logging" AppleEvent to WebSTAR.
   // In gizmo_string below, << and >> are chevron characters 
   // (option-backslash and shift-option-backslash respectively).
   app_name = "WebSTAR 1.2";
   gizmo_string = "'----':obj {want:type(prop), from:'null'(), 
                   form:prop, seld:type(Plog)}, data:bool(<<00>>)";
   sendAppleEvent(app_name, "core", "setd", gizmo_string);