[{TableOfContents}]

!! Orc the Language

! The pruning combinator seems very inflexible; is there any way to select a publication based on some other criterion than "first"?

Yes! The pruning combinator's behavior was chosen for its simplicity, but more complicated selection is possible using sites. For example, if you want to select the maximum value published by some expression {{f()}} (rather than the first value published):

[{orc runnable='false'

val c = Buffer()
f() >x> c.put(x) >> stop
; maximum(c.getAll())
}]

Another typical request is to select some subset of values, not just one. For example, here is how you could get all the values published by {{f()}} within 1 second (and then terminate {{f}}):

[{orc runnable='false'

val c = Buffer()
repeat(c.get) <<
    f() >x> c.put(x) >> stop
  | Rtimer(1000) >> c.closenb()
}]

These are examples of a general idiom known as "routing", discussed in more detail in the [Programming Methodology|http://orc.csres.utexas.edu/userguide/html/ch02.html] section of the User Guide.

! How does Orc handle exceptions or errors?

Semantically, Orc does not distinguish expressions which fail to yield a value from those which encounter an error. This makes sense in a distributed environment because when a distributed node fails it probably won't have a chance to notify the other nodes. Therefore the standard idiom for handling errors in Orc is to use timeouts or the "otherwise" combinator to detect when an expected publication does not occur and handle it appropriately.

We recognize that this approach has some serious limitations from a software engineering perspective, and we are currently investigating how to add a more traditional exception-handling mechanism to Orc.

!! Running Orc programs

! I can't find ''X''{{.inc}} in the Orc distribution.
! This demo I found on the web site does not work when I try and run it with the Orc interpreter on my computer.

The Orc distribution includes only the standard library for Orc. Many of the demos on the website need additional sites which are not included in the standard library. The implementations of these additional sites and the corresponding include files are found in CVS:

;{{~OrcSites}}: various web services and demo sites which do not require a web server, including search engines, Google Calendar, SMTP/IMAP/POP3 email, algorithmic animation, simple GUI tools, etc. [The User Guide|http://orc.csres.utexas.edu/userguide/html/ch03s04.html] describes how to download {{~OrcSites}} and run examples locally.
;{{Orchard}}: demo sites which do require a web server, including web forms and direct receipt of email. These sites can only be used when running Orc programs via the web interface.  Most users will not need to run these sites locally, but if you do, see HowToInstallOrchard for information on how to set up your own local Orc web service.

! Orc tells me it can't find an include file even though I know the file exists.

At this time, include files need to be in the classpath in the {{orc/inc}} package. If you've checked out ~OrcJava in Eclipse, just drop your include files in the existing {{src/orc/inc}}; if you're running using the jar, create an {{orc/inc}} directory and include its parent directory in the classpath, e.g. {{java -cp orc-0.9.6.jar:. orc.Orc myfile.orc}}

The reason for this limitation is so that include files can still work when Orc is deployed in a web service, which doesn't have any concept of a "working directory".

!! Building Orc

! I am getting a build error trying to compile {{Orchard}} (or {{~OrcSites}}). Help!

Please check the following before emailing us for help:

# You have checked out both {{~OrcJava}} and {{~OrcSites}}.
# You checked out {{~OrcJava}} to a project named {{~OrcJava}} (this is the default).
# All of your orc projects are in the same parent directory (this is the default).
# You have the latest version of all code from CVS (select all projects, right click, and choose Team -> Update).
# If building {{Orchard}}, make sure you have built up-to-date JARs and copied them to {{Orchard/lib}} as instructed.
# Refresh all directories and do a Build -> Clean to make sure Eclipse isn't confused.