AccountingIntegrator Rule Engine 2.4.0 Exits and External Calls Save PDF Selected topic Selected topic and subtopics All content Implement the ITR501 exit in different languages You can extend the Rule Engine features by implementing exits. You can use different languages to write IT501 exits; traditional languages like C code and COBOL and more modern languages such as: Java Python Go To be able to use Java, Python or Go, you need to create a function C which calls the function in another language, it is then necessary to wait for its return to send it to Rule Engine so it can treat it. The processing is slower. We recommend that you use these languages for more advanced functions that bring a high added value. For example, an exit that only manipulates strings or simple calculations, will always be faster in C. On the other hand, an exit that connects to a REST API webservice will be more interesting in another language that provides adapted libraries. Axway supports these languages with the following restrictions: Axway does not guarantee the performance of such an exit Axway supports only such implementation in the ITR501 exit Axway only supports such implementation on Linux-type environments Axway supports only the following new languages: Java, Python, GO If your use case does not correspond to these restrictions, do not hesitate to contact Axway to qualify it together. These implementations are to be done by the users. Axway only provides examples to be adapted to the customer needs. Each example includes an example of function C in ITR501 which makes it possible to call a function in a different language and to recover its return. For each language we demonstrate a simple function of concatenation of parameters, as well as a function that returns an anomaly. Example of implementation in Java The files used in these examples are present in the directory: <RDJ_HOME>/envref/exit/sample/java Prerequisite: Java Developer Kit Create a Java archive The sample source file ./com/axway/ruleengine/sample/sample.java includes four methods: The TestOk method receives two String parameters and concatenates them. The return code zero indicates that everything went well. The GetValue method which returns the result of the concatenation made by the TestOk method. The TestKo method also expects two parameters but returns an error (non-zero code). The GetErrMsg method returns the description of the error following the TestKo method's call. To create a Java archive: Before starting the compilation, go to the runtime script directory of the runtime and run the source command ./rdjenv (the compilation must be done with the same version of Java as the Rule Engine runtime). Run the script compile-java.sh to create the Java archive sample.jar. Environment variables Environment variables are necessary for the operation of the exit and for the compilation of the file ITR501_JAVA.c. You must add these variables in the rdjenv script of the runtime: Path to the library Java libjvm.so (to adapt according to the environment and to add after export JAVA_HOME=...) export LIB_JVM_PATH=$JAVA_HOME/jre/lib/amd64/server Change the path to the external libraries to find libjvm.so export LD_LIBRARY_PATH=$LIB_JVM_PATH:$LD_LIBRARY_PATH Variable to the archive created above. (syntax to use multiple archives: EXIT_CLASSPATH=<file1.jar>:<file2.jar>:./lib*.jar:...)) export EXIT_CLASSPATH=$RDJ_HOME/envref/exit/sample/java/sample.jar Particularities of ITR501 in C The sample source file ITR501_JAVA.c, lets you call a Java method through the CallJavaMethod function found in this program. The input parameter expected by the program (parameter of the input form's $ SEARCH) must have the following format: <separator><param1><separator><param2><...>. The separator must have a single character. The first separator indicates which character will be used in the command. The number of parameters is dynamic. Behavior Initialization of the JVM is done through case 79 to be executed once. The call to the Java TestOk method is done through case 50. With the function returning zero, the program will call the Java GetValue method to retrieve the value of the concatenation to return it to the engine. The call to the Java TestKo method is done via case 51. The function returning an error, the program will call the Java GetErrMsg method to retrieve the description of the error to return it to the engine. Additional information Regarding the Java methods called: if they have input parameters, they must be of type String. The output parameter must be an integer. A return code difference of zero indicates an error. The java source must always include GetValue and GetErrMsg methods without any input parameters and returning a String. The file also has a main function in order to be able to test the call autonomously (without starting a session). Exit compilation The makefile itr501_java.mak allows the compilation of the source file ITR501_JAVA.c. The H_JAVA variable that points to the Java headers may need to be modified according to its environment. To compile the exit : Copy the files ITR501_JAVA.c and itr501_java.mak in the exit directory of the runtime. Go to the script directory of the runtime and execute the command source ./rdjenv Go to the exit directory of the runtime to start the compilation: make -f itr501_java.mak A libitr501.so library and a testitr501 test binary are generated (the test binary is compiled with DEBUG info). Execution The test binary expects the following parameters: testitr501 <classe-name> <method-name> <parameters> To launch the case that ends successfully: ./testitr501 "com/axway/ruleengine/sample/sample" TestOk ":PARAM1:PARAM2" To start the case that ends in error: ./testitr501 "com/axway/ruleengine/sample/sample" TestKo ":PARAM1:PARAM2" In Rule Engine, the $SEARCH of the input form must have the following syntax to work with our example: For the case that ends successfully: $SEARCH("050A";"50";":PARAM1:PARAM2") For the case that ends in error: $SEARCH("050A";"51";":PARAM1:PARAM2") Example of implementation in Python The files used in these examples are located in the directory <RDJ_HOME>/envref/exit/sample/python. Prerequisites Python version 3 Python script The sample script sample.py has four functions: The TestOk function receives two String parameters and concatenates them. The return code zero indicates that everything went well. The GetValue function which returns the result of the concatenation made by the TestOk method. The TestKo function also expects two parameters but returns an error (non-zero code). The GetErrMsg function returns the description of the error following the TestKo method's call. Environment variables Environment variables are necessary for the operation of the exit and for the compilation of the file ITR501_JAVA.c. You must add these variables in the rdjenv script of the runtime: For the exit to work correctly, you must indicate the path to the Python scripts that you have created, using an environment variable. This variable is to be added in the Rule Engine runtime rdjenv script : export PYTHONPATH=$RDJ_HOME/envref/exit/sample/python Particularities of ITR501 in C The sample source file ITR501_PY.c, lets you call a Java method through the ExecPython function found in this program. The input parameter expected by the program (parameter of the input form's $ SEARCH) must have the following format: <separator><param1><separator><param2><...>. The separator must have a single character. The first separator indicates which character will be used in the command. The number of parameters is dynamic. Behavior Initialization of the JVM is done through case 79 to be executed once. The call to the Python TestOk function is done through case 50. With the function returning zero, the program will call the Python GetValue function to retrieve the value of the concatenation to return it to the engine. The call to the Python TestKo function is done via case 51. The function returning an error, the program will call the Java GetErrMsg method to retrieve the description of the error to return it to the engine. Use case 80 to exit the interpreter, so it is executed once. Additional information The Python script must always include the GetValue and GetErrMsg functions without any input parameters and returning a String. The file also has a main function in order to be able to test the call autonomously (without starting a session). Exit compilation The makefile itr501_py.mak allows the compilation of the source file ITR501_PY.c. The variable H PY which points to the python headers, and the variable LIBPYTHON which indicates the Python library, could need to be modified according to their environment. To compile the exit: Copy the files ITR501_PY.c and itr501_py.mak to the exit directory of the runtime. Go to the script directory of the runtime and execute the command source ./rdjenv. Go to the exit directory of the runtime to start the compilation: make -f itr501_py.mak A libitr501.so library and a testitr501 test binary are generated (the test binary is compiled with DEBUG info). Execution The test binary expects the following parameters: testitr501 <module-name> <function-name> <parameters> To launch the case that ends successfully: ./testitr501 "sample" TestOk ":PARAM1:PARAM2" To start the case that ends in error: ./testitr501 "sample" TestKo ":PARAM1:PARAM2" In Rule Engine, the $SEARCH of the input form must have the following syntax to work with our example: For the case that ends successfully: $SEARCH("050A";"50";":PARAM1:PARAM2") For the case that ends in error: $SEARCH("050A";"51";":PARAM1:PARAM2") Example of implementation in Go The files used in these examples are located in the directory <RDJ_HOME>/envref/exit/sample/go Prerequisites Go Create a program in Go To be able to interface with the programs of Rule Engine, the parameters received and returned by the Go functions must be of type C (cGo) The sample source file sample.go has four functions: the TestOk function receives two parameters: the second argument is a string array, the first one indicates the number of elements present in the array. The return code zero indicates that everything went well. the GetValue function which returns the result of the concatenation made by the TestOk method. the TestKo function returns an error (code other than zero). the GetErrMsg function returns the description of the error following the TestKo method's call. To use the program in Rule Engine: Create a shared library from the source file using the script compile-go.sh. The compilation generates a sample.so library as well as a sample.h header. Copy the sample.so and sample.h files to the exit directory of the runtime. Note For a function to be exported by the library, it must be preceded by the comment: //export <nom-de-la-fonction> (as is the case for the four functions in the source file sample.go) Particularities of ITR501 in C The source file IITR501_GO.c allows you to call a Go function. The input parameter expected by the program (parameter of the input form's $ SEARCH) must have the following format: <separator><param1><separator><param2><...>. The separator must have a single character. The first separator indicates which character will be used in the command. The number of parameters is dynamic. You can call a Go function the same way you call a standard C function. The header generated via the compilation of the Go source has been included. The Go function is called via the ExecGo function, to which we indicate the pointer to the Go function and the structure containing the parameters. Behavior The call to the Go TestOk function is done through case 50. With the function returning zero, the program will call the GetValue function to retrieve the value of the concatenation to return it to the engine The call to the Go TestKo function is done via case 51. The function returning an error, the program will call the Go GetErrMsg method to retrieve the description of the error to return it to the engine. Additional information The Go source must always include GetValue and GetErrMsg functions without any input parameters and returning a String. The file also has a main function in order to be able to test the call autonomously (without starting a session). Exit compilation The makefile itr501_go.mak allows the compilation of the source file ITR501_GO.c. The LIBGO variable could be changed depending on the name of the shared library generated from the Go sources. To compile the exit : Copy the files ITR501_GO.c and itr501_go.mak in the exit directory of the runtime. Go to the script directory of the runtime and execute the command source ./rdjenv. Go to the exit directory of the runtime to start the compilation: make -f itr501_go.mak A libitr501.so library and a testitr501 test binary are generated (the test binary is compiled with DEBUG info). Execution The test binary expects the following parameters: testitr501 <parameters> For this example, you must launch ./testitr501 ":PARAM1:PARAM2" which will launch the TestOk function and then TestKo : In Rule Engine, the $SEARCH of the input form must have the following syntax to work with our example: For the case that ends successfully: $SEARCH("050A";"50";":PARAM1:PARAM2") For the case that ends in error: $SEARCH("050A";"51";":PARAM1:PARAM2") See the PDF | All AccountingIntegrator 2.4 docs Related Links
Implement the ITR501 exit in different languages You can extend the Rule Engine features by implementing exits. You can use different languages to write IT501 exits; traditional languages like C code and COBOL and more modern languages such as: Java Python Go To be able to use Java, Python or Go, you need to create a function C which calls the function in another language, it is then necessary to wait for its return to send it to Rule Engine so it can treat it. The processing is slower. We recommend that you use these languages for more advanced functions that bring a high added value. For example, an exit that only manipulates strings or simple calculations, will always be faster in C. On the other hand, an exit that connects to a REST API webservice will be more interesting in another language that provides adapted libraries. Axway supports these languages with the following restrictions: Axway does not guarantee the performance of such an exit Axway supports only such implementation in the ITR501 exit Axway only supports such implementation on Linux-type environments Axway supports only the following new languages: Java, Python, GO If your use case does not correspond to these restrictions, do not hesitate to contact Axway to qualify it together. These implementations are to be done by the users. Axway only provides examples to be adapted to the customer needs. Each example includes an example of function C in ITR501 which makes it possible to call a function in a different language and to recover its return. For each language we demonstrate a simple function of concatenation of parameters, as well as a function that returns an anomaly. Example of implementation in Java The files used in these examples are present in the directory: <RDJ_HOME>/envref/exit/sample/java Prerequisite: Java Developer Kit Create a Java archive The sample source file ./com/axway/ruleengine/sample/sample.java includes four methods: The TestOk method receives two String parameters and concatenates them. The return code zero indicates that everything went well. The GetValue method which returns the result of the concatenation made by the TestOk method. The TestKo method also expects two parameters but returns an error (non-zero code). The GetErrMsg method returns the description of the error following the TestKo method's call. To create a Java archive: Before starting the compilation, go to the runtime script directory of the runtime and run the source command ./rdjenv (the compilation must be done with the same version of Java as the Rule Engine runtime). Run the script compile-java.sh to create the Java archive sample.jar. Environment variables Environment variables are necessary for the operation of the exit and for the compilation of the file ITR501_JAVA.c. You must add these variables in the rdjenv script of the runtime: Path to the library Java libjvm.so (to adapt according to the environment and to add after export JAVA_HOME=...) export LIB_JVM_PATH=$JAVA_HOME/jre/lib/amd64/server Change the path to the external libraries to find libjvm.so export LD_LIBRARY_PATH=$LIB_JVM_PATH:$LD_LIBRARY_PATH Variable to the archive created above. (syntax to use multiple archives: EXIT_CLASSPATH=<file1.jar>:<file2.jar>:./lib*.jar:...)) export EXIT_CLASSPATH=$RDJ_HOME/envref/exit/sample/java/sample.jar Particularities of ITR501 in C The sample source file ITR501_JAVA.c, lets you call a Java method through the CallJavaMethod function found in this program. The input parameter expected by the program (parameter of the input form's $ SEARCH) must have the following format: <separator><param1><separator><param2><...>. The separator must have a single character. The first separator indicates which character will be used in the command. The number of parameters is dynamic. Behavior Initialization of the JVM is done through case 79 to be executed once. The call to the Java TestOk method is done through case 50. With the function returning zero, the program will call the Java GetValue method to retrieve the value of the concatenation to return it to the engine. The call to the Java TestKo method is done via case 51. The function returning an error, the program will call the Java GetErrMsg method to retrieve the description of the error to return it to the engine. Additional information Regarding the Java methods called: if they have input parameters, they must be of type String. The output parameter must be an integer. A return code difference of zero indicates an error. The java source must always include GetValue and GetErrMsg methods without any input parameters and returning a String. The file also has a main function in order to be able to test the call autonomously (without starting a session). Exit compilation The makefile itr501_java.mak allows the compilation of the source file ITR501_JAVA.c. The H_JAVA variable that points to the Java headers may need to be modified according to its environment. To compile the exit : Copy the files ITR501_JAVA.c and itr501_java.mak in the exit directory of the runtime. Go to the script directory of the runtime and execute the command source ./rdjenv Go to the exit directory of the runtime to start the compilation: make -f itr501_java.mak A libitr501.so library and a testitr501 test binary are generated (the test binary is compiled with DEBUG info). Execution The test binary expects the following parameters: testitr501 <classe-name> <method-name> <parameters> To launch the case that ends successfully: ./testitr501 "com/axway/ruleengine/sample/sample" TestOk ":PARAM1:PARAM2" To start the case that ends in error: ./testitr501 "com/axway/ruleengine/sample/sample" TestKo ":PARAM1:PARAM2" In Rule Engine, the $SEARCH of the input form must have the following syntax to work with our example: For the case that ends successfully: $SEARCH("050A";"50";":PARAM1:PARAM2") For the case that ends in error: $SEARCH("050A";"51";":PARAM1:PARAM2") Example of implementation in Python The files used in these examples are located in the directory <RDJ_HOME>/envref/exit/sample/python. Prerequisites Python version 3 Python script The sample script sample.py has four functions: The TestOk function receives two String parameters and concatenates them. The return code zero indicates that everything went well. The GetValue function which returns the result of the concatenation made by the TestOk method. The TestKo function also expects two parameters but returns an error (non-zero code). The GetErrMsg function returns the description of the error following the TestKo method's call. Environment variables Environment variables are necessary for the operation of the exit and for the compilation of the file ITR501_JAVA.c. You must add these variables in the rdjenv script of the runtime: For the exit to work correctly, you must indicate the path to the Python scripts that you have created, using an environment variable. This variable is to be added in the Rule Engine runtime rdjenv script : export PYTHONPATH=$RDJ_HOME/envref/exit/sample/python Particularities of ITR501 in C The sample source file ITR501_PY.c, lets you call a Java method through the ExecPython function found in this program. The input parameter expected by the program (parameter of the input form's $ SEARCH) must have the following format: <separator><param1><separator><param2><...>. The separator must have a single character. The first separator indicates which character will be used in the command. The number of parameters is dynamic. Behavior Initialization of the JVM is done through case 79 to be executed once. The call to the Python TestOk function is done through case 50. With the function returning zero, the program will call the Python GetValue function to retrieve the value of the concatenation to return it to the engine. The call to the Python TestKo function is done via case 51. The function returning an error, the program will call the Java GetErrMsg method to retrieve the description of the error to return it to the engine. Use case 80 to exit the interpreter, so it is executed once. Additional information The Python script must always include the GetValue and GetErrMsg functions without any input parameters and returning a String. The file also has a main function in order to be able to test the call autonomously (without starting a session). Exit compilation The makefile itr501_py.mak allows the compilation of the source file ITR501_PY.c. The variable H PY which points to the python headers, and the variable LIBPYTHON which indicates the Python library, could need to be modified according to their environment. To compile the exit: Copy the files ITR501_PY.c and itr501_py.mak to the exit directory of the runtime. Go to the script directory of the runtime and execute the command source ./rdjenv. Go to the exit directory of the runtime to start the compilation: make -f itr501_py.mak A libitr501.so library and a testitr501 test binary are generated (the test binary is compiled with DEBUG info). Execution The test binary expects the following parameters: testitr501 <module-name> <function-name> <parameters> To launch the case that ends successfully: ./testitr501 "sample" TestOk ":PARAM1:PARAM2" To start the case that ends in error: ./testitr501 "sample" TestKo ":PARAM1:PARAM2" In Rule Engine, the $SEARCH of the input form must have the following syntax to work with our example: For the case that ends successfully: $SEARCH("050A";"50";":PARAM1:PARAM2") For the case that ends in error: $SEARCH("050A";"51";":PARAM1:PARAM2") Example of implementation in Go The files used in these examples are located in the directory <RDJ_HOME>/envref/exit/sample/go Prerequisites Go Create a program in Go To be able to interface with the programs of Rule Engine, the parameters received and returned by the Go functions must be of type C (cGo) The sample source file sample.go has four functions: the TestOk function receives two parameters: the second argument is a string array, the first one indicates the number of elements present in the array. The return code zero indicates that everything went well. the GetValue function which returns the result of the concatenation made by the TestOk method. the TestKo function returns an error (code other than zero). the GetErrMsg function returns the description of the error following the TestKo method's call. To use the program in Rule Engine: Create a shared library from the source file using the script compile-go.sh. The compilation generates a sample.so library as well as a sample.h header. Copy the sample.so and sample.h files to the exit directory of the runtime. Note For a function to be exported by the library, it must be preceded by the comment: //export <nom-de-la-fonction> (as is the case for the four functions in the source file sample.go) Particularities of ITR501 in C The source file IITR501_GO.c allows you to call a Go function. The input parameter expected by the program (parameter of the input form's $ SEARCH) must have the following format: <separator><param1><separator><param2><...>. The separator must have a single character. The first separator indicates which character will be used in the command. The number of parameters is dynamic. You can call a Go function the same way you call a standard C function. The header generated via the compilation of the Go source has been included. The Go function is called via the ExecGo function, to which we indicate the pointer to the Go function and the structure containing the parameters. Behavior The call to the Go TestOk function is done through case 50. With the function returning zero, the program will call the GetValue function to retrieve the value of the concatenation to return it to the engine The call to the Go TestKo function is done via case 51. The function returning an error, the program will call the Go GetErrMsg method to retrieve the description of the error to return it to the engine. Additional information The Go source must always include GetValue and GetErrMsg functions without any input parameters and returning a String. The file also has a main function in order to be able to test the call autonomously (without starting a session). Exit compilation The makefile itr501_go.mak allows the compilation of the source file ITR501_GO.c. The LIBGO variable could be changed depending on the name of the shared library generated from the Go sources. To compile the exit : Copy the files ITR501_GO.c and itr501_go.mak in the exit directory of the runtime. Go to the script directory of the runtime and execute the command source ./rdjenv. Go to the exit directory of the runtime to start the compilation: make -f itr501_go.mak A libitr501.so library and a testitr501 test binary are generated (the test binary is compiled with DEBUG info). Execution The test binary expects the following parameters: testitr501 <parameters> For this example, you must launch ./testitr501 ":PARAM1:PARAM2" which will launch the TestOk function and then TestKo : In Rule Engine, the $SEARCH of the input form must have the following syntax to work with our example: For the case that ends successfully: $SEARCH("050A";"50";":PARAM1:PARAM2") For the case that ends in error: $SEARCH("050A";"51";":PARAM1:PARAM2") See the PDF | All AccountingIntegrator 2.4 docs