Net.Data provides many functions you will find useful in your Web applications. It is easy to write your own functions too.
You can define your own functions or use Net.Data's library of functions. For functions which are not in the Net.Data library, use a FUNCTION block to define the function to the Net.Data macro. Details are in Net.Data Language Environment Guide. The syntax is shown here:
%FUNCTION(type) function-name([usage parameter, ...]) [RETURNS(return-var)] {
executable-statements
[report-block]
[message-block]
%}
Identifies a language environment that is configured in the initialization file. The language environment invokes a specific language processor (which processes the executable statements) and provides a standard interface between Net.Data and the language processor.
Several default language environments are provided with Net.Data.
This is the name of the FUNCTION block. The FUNCTION block is executed by referencing this name elsewhere in the Net.Data macro, preceded by an at (@) sign. Executing a FUNCTION block is a function call. See "Calling Functions" for details.
Multiple FUNCTION blocks can exist with the same name. They must all have identical parameter lists. When the function is called, all FUNCTION blocks with the same name are executed in the order that they are defined in the Net.Data macro.
The name of a variable with local scope that is replaced with the value of a corresponding argument specified on a function call. Parameter references, for example $(parm1), in the executable statements or report block are replaced with the actual value of the parameter. In addition, parameters are passed to the language environment and are accessible to the executable statements using the natural syntax of that language or as environment variables. Parameter variable references are not valid outside the FUNCTION block.
You can also pass implicit parameters on a function call of a type you specify. You must define the parameters in the ENVIRONMENT statement in the initialization file.
Define functions at the outermost Net.Data macro layer and before they are called in the Net.Data macro.
Invoke a function from a Net.Data macro using the at (@) character followed by a FUNCTION block name:
@function_name([ argument,... ])
When a FUNCTION block is invoked, Net.Data proceeds this way:
The rules for using and modifying variables from a FUNCTION block in a function call can be summarized as follows:
When MESSAGE block and REPORT block processing is done, the value of the function call is used to replace the function call in the Net.Data macro.
Stored procedures are called simply as an SQL function. Stored procedures can offer greater performance and integrity by keeping compiled SQL statements with the database server.
Stored procedures can use these data types for most platforms:
Table 2. Stored Procedures Data Types
| BLOB | DOUBLEPRECISION | SMALLINT |
| CHAR | FLOAT | TIME |
| CLOB | INTEGER | TIMESTAMP |
| DATE | GRAPHIC | VARCHAR |
| DBCLOB | LONGVARCHAR | VARGRAPHIC |
| DOUBLE | LONGVARGRAPHIC |
|
See your database documentation for more information about these data types. Net.Data might not support all the data types supported by your database. See the appendix of Net.Data Reference Guide for details.
Here is an example of calling a stored procedure as a function named stored_proc1:
%FUNCTION(DTW_SQL) stored_proc1 ( IN float(7,2) arg1,
INOUT SMALLINT arg2,
OUT VARCHAR(9) retval)
RETURNS (RESULT) {
CALL statsrpt
%}
%HTML(REPORT) {
@stored_proc1(arg1, arg2, retval)
%}
The name of the stored procedure is statsrpt, which is called with the CALL statement. The function stored_proc1 is the name of the function that calls the stored procedure.
The MESSAGE block lets you determine how to proceed after a function call based on the success or failure of the function call, and lets you display information to the caller of the function.
Net.Data sets RETURN_CODE, an implicit variable, for each function call. RETURN_CODE is set to the return code of the call to the language environment the function calls. When the function call completes, the MESSAGE block uses the value of RETURN_CODE to determine how to proceed. A MESSAGE block consists of a series of message statements, each statement specifying a return code value, message text, and an action to take. The syntax of a MESSAGE block is shown here:
>>-%message--{-------------------------------------------------->
+----------------------------------------------------------------------+
V |
>----+------------------------------------------------------------------+-+->
+-| return code spec |--:--| message text spec |--| action spec |--+
>-%}-----------------------------------------------------------><
return code spec
|--+-DEFAULT-------+-------------------------------------------|
+- +DEFAULT-----+
+- -DEFAULT-----+
+-+---+-number--+
+---+
+-+-+
message text spec
+-----------------------+
V |
|---+-"----+--------------------++--"---+----------------------|
| +-string-------------+ |
| +-variable reference-+ |
| +-function call------+ |
| +-----------------------+ |
| V | |
+-{----+--------------------++--%}--+
+-string-------------+
+-variable reference-+
+-function call------+
action spec
|--:--+-EXIT-----+---------------------------------------------|
+-CONTINUE-+
A MESSAGE block can have a global or a local scope. If the MESSAGE block is defined in a FUNCTION block, its scope is local to that FUNCTION block. If it is specified at the outermost macro layer, it has global scope, and is active for all function calls executed in the Net.Data macro. If you defined more than one global MESSAGE block, the last one defined is active.
Net.Data uses these rules to process a RETURN_CODE from a function call:
Here's an example of part of a Net.Data macro with a global MESSAGE block and a MESSAGE block for a function.
%{ global message block %}
%MESSAGE {
-100 : "Return code -100 message" : exit
100 : "Return code 100 message" : continue
+default : {
This is a long message that spans more
than one line. You can use HTML tags, including
anchors and forms, in this message. %} : continue
%}
%{ local message block inside a FUNCTION block %}
%FUNCTION(DTW_REXX) my_function() {
%EXEC { my_command.cmd %}
%MESSAGE {
-100 : "Return code -100 message" : exit
100 : "Return code 100 message" : continue
-default : {
This is a long message that spans more
than one line. You can use HTML tags, including
anchors and forms, in this message. %} : exit
%}
If my_function() returns with RETURN_CODE set to 50, Net.Data processes the error in this order:
Now that Net.Data found a match, it sends the message text to the Web browser and checks the requested action. Because continue is specified, Net.Data continues to process the Net.Data macro after printing the message text.
For example, if a macro calls my_functions() five times and error 100 is found during processing with the MESSAGE block in the example, output from a program can look like this:
. 11 May 1997 $245.45 13 May 1997 $623.23 19 May 1997 $ 83.02 return code 100 message 22 May 1997 $ 42.67 Total: $994.37
See Appendix A. "Dynamic Query Sample" for another example of a local message block.