Next: , Previous: Overview, Up: Top



2 Invoking BPEL2oWFN

The standard invocation of BPEL2oWFN is:

     bpel2owfn -i inputfile.bpel -f owfn -o

where inputfile.bpel is a BPEL process. The option -f owfn cause BPEL2oWFN to generate an open workflow net. This net is written to a file named inputfile.owfn, because of the option -o. For more examples, see Examples.

BPEL2oWFN can be called without any parameter. In this case, it acts as a parser for BPEL, that reads its input from the standard input (stdin).

2.1 Options

BPEL2oWFN supports the following command-line options:

--help
-h
Print an overview of the command-line options and exit.
--version
-v
Print version information and exit.
--input=filename.bpel
-i filename.bpel
Read BPEL input from file filename.bpel. If this parameter is omitted, input is read from standard input (stdin).
--output[=filename]
-o
The generated files are written to a file called filename. If the short form is used or the filename is omitted, the input file name is taken and extended by the suffix of the chosen file format(s). If this parameter is omitted, the output is passed to the standard output (stdout).
--log[=filename]
-l
All additional information like warnings and processing information are written to a file called filename. If the short form is used or the filename is omitted, the output file name is taken and extended by the suffix .log. If this parameter is omitted, the information is passed to the standard error output (stderr).
--debug=1-4 | flex | bison
-d 1-4 | flex | bison
This option triggers different debug levels, and can enable additional information from Flex and Bison about how the input is lexed and parsed.
--bpel2pn
This option makes BPEL2oWFN behave like its predecessor, BPEL2PN: it generates a Petri net LoLA format and an information file. The option --bpel2pn is a shortcut for --mode=petrinet --format=lola --format=info --output.

2.1.1 Modes

When invoking BPEL2oWFN several modes are possible.

--mode=modus
-m modus
BPEL2oWFN supports four different modes for handling BPEL, so modus can be one of the following options:
ast
Outputs the AST (abstract syntax tree) generated while parsing the input file to standard output. This option is mostly used for debugging reasons since it shows the implicit transformations and the phylum names used when generating the Petri net.
petrinet
Generates a Petri net representing the semantics of the given process. Other options can be added to simplify or modify that generated Petri net (see below).
pretty
Outputs the parsed BPEL file in XML representation. Any unnecessary attributes are omitted. This option is mostly used for debugging reasons as it shows the implicit transformations and the identifiers of the BPEL constructs.
Please note that you can only use at most one mode.

2.1.2 Additional parameters

These options control some Petri net-related options. See Petri Net-related Functions for more details.

--parameter=par
-p par
simplify
Structurally simplify the generated Petri net.
finishloop
Add an extra loop transition to the final place of the generated Petri net to live-lock the system in order to find deadlocks.
nostandardfaults
When the parameter is set, only used-defined faults using the <throw> activity can occur.
cyclicwhile
When the parameter is set, the pattern for the <while> activity is cyclic as depicted in Fig. 18 of [Sta05]. If the parameter is not set (standard case), the pattern is acyclic: the activity embedded in the <while> activity is at most executed once, chosen non-deterministically.

If you want to enable more than one parameter you have to add -p/ --parameter to each parameter.

2.1.3 Output formats

Especially for the Petri net mode, a variaty of output formats are supported, see File Formats for more information. There are invoked by the following option:

--format=fileformat
-f fileformat
apnn
Create a Petri net in APNN (Abstract Petri Net Notation). Implies the mode petrinet.
dot
Create a Dot representation of the structure generated in the current mode which can be any kind of Petri net (mode petrinet).
info
Create an additional information file. Implies the mode petrinet.
lola
Create a LoLA place/transition net. Implies the mode petrinet.
owfn
Create a low-level oWFN in LoLA file format. Implies the mode petrinet.
pep
Create a Petri net in low-level PEP notation. Implies the mode petrinet.
pnml
Create a PNML Petri net. Implies the mode petrinet.
xml
Create an XML (Extensible Markup Lanuage) file. Implies the mode pretty.

If you want to use more than one output file format you have to add -f/ --fileformat to each file format. Please note that the underlying modes of the given file formats are the same, i.e. you cannot create XML and LoLA files together since XML uses the mode pretty whereas LoLA uses the mode petrinet.

2.2 Examples

In this section we show some examples how BPEL2oWFN can be invoked.

bpel2owfn -i sample.bpel -flola -finfo -o -p simplify
Reads the file sample.bpel, generates a structural simplified low-level Petri net and saves it in a LoLA file sample.lola. For further information a file sample.info is generated.
bpel2owfn -i sample.bpel -fowfn -d3 -o
Reads the file sample.bpel, generates a low-level open workflow net and saves it in an oWFN file sample.owfn. For further information a file sample.info is generated. During the conversion several debug messages are printed to standard output.
prog | bpel2owfn -fdot -m petrinet | dot -Tpng -osample.png
Runs the program prog and reads its output as BPEL process, generates a Petri net and outputs its Dot representation. This stream is read by Dot which layouts the Petri net and creates an output PNG (Portable Network Graphic) file sample.png.
bpel2owfn -i sample.bpel -m ast
Reads the file sample.bpel and prints the abstract syntax tree (AST) to standard output.

2.3 Exit Values

When BPEL2oWFN is invoked and run without any error, the exit value is 0.

0
No error. The input file could be correctly opened, parsed and the output file(s) could be generated without any error.
1
Lexical or syntax error. This error occurs while lexing or parsing the input file. It is thrown by the lexer or the parser, resp. Usually the `source' of the error (i.e. the filename and line number) is indicated together with the unexpected (last read) and expected token.

An example:

          Error while parsing
          
          syntax error, unexpected X_SLASH, expecting X_OPEN
          Error in `example.bpel' in line 12:
            token/text last read was `/'
     

Please note that the indicated position (i.e. the line number) may be fuzzy — it should be understood as a hint to the erroneous line.

2
`File not found' exception. The given input file was not found resp. could not be opened.

An example:

          An error has occurred while parsing "example.bpel"!
          
          Exception #2 occurred!
          
             File `example.bpel' not found.
     

3
`File could not be opened' exception. An output file could not be opened for write access. You may check the appropriate for the target directory or the file if it already exists.

An example:

          An error has occured while parsing "example.bpel"!
          
          Exception #3 occured!
          
             File "example.dot" could not be opened for writing access!
     

10
Option mismatch. The given command-line options cannot be processed together.

An example:

          An error has occurred while parsing "example.bpel"!
          An error has occured while parsing "<STDIN>"!
          
          Exception #10 occured!
          
             Choose only one mode
          
           Additional information:
             Type ./bpel2owfn -h for more information.
     

30
`Dynamic cast error' exception. While building an internal scope tree an unexpected error has occurred.
40
Node not found.
41
`Node already defined' exception. While generating the Petri net a node was found having a history entry covered by another node before.

An example:

          An error has occurred while parsing "example.bpel"!
          
          Exception #41 occurred!
          
             Place with role `1.internal.final' already defined.
     

42
`Merging error' exception. While generating the Petri net an error occurred while merging two nodes. It happens either when one of the nodes was not found or one of the nodes is a guarded transition—the merging of guarded transitions is not yet supported.
43
`Arc error' exception. While generating the Petri net an error occurred while adding an arc to the net. It happens either on type errors — i.e. an arc between two transitions (or two places, resp.) should be drawn — or when the source or target node of an arc was not found.

Please report the occurrence of any exception with numbers 30–50 since it indicates a bug in BPEL2oWFN we would like to fix immediately (see Reporting Bugs).