Pass parameters to a program by specifying on the function definition the data type of the parameter and whether the parameter to be passed is an input-only (IN), output-only (OUT), or input/out (INOUT) parameter. For example:
%function(DTW_DIRECTCALL) dc2(IN CHAR(3) p1,
INOUT INTEGER p2,
OUT DECIMAL(7,2) p3) {
%EXEC { /QSYS.LIB/NETDATA.LIB/MYPGM.PGM %}
%}
In the above example, the Direct Call language environment passes three parameters, a character variable, an integer, and a packed decimal variable to the program MYPGM. You can pass up to 50 parameters to the called program. Only parameters specified with data types are passed to the program. The Direct Call language environment converts the string corresponding to the parameter to the internal representation of the data type. The language environment then passes pointers to the internal representation of the variables to the called program, in the order specified on the function definition.
Because pointers to the variables are passed to the program, the program can change the value of the variable. However, only OUT or INOUT variables that are changed by the program are reflected back in the macro that called the language environment.
Table 4 lists the data types that are supported by the Direct Call
language environment. Not all of the data types are supported by each
high-level language.
Table 4. Direct Call Data Types
| Data Type | Usage Notes |
|---|---|
|
CHAR(n) CHARACTER(n) CHARACTER | A character string. If n is specified, it must be greater than zero. If the string is not specified, it is assumed to be one character. Because all strings passed from the Direct Call language environment are null-terminated, the language environment allocates n+1 bytes (1 byte for the NULL terminator). Strings that exceed n are truncated. |
| VARCHAR(n) | A variable-length character string, where n is greater than zero, and less than or equal to 32740. The string is null-terminated and the language environment allocates n+2+1 bytes (2 bytes to store the string length, 1 byte for the null-terminator). Strings that exceed n are truncated. The first two bytes of the string contain the string length (binary value). If the parameter is defined as OUT (output only), the string length is set to zero before the variable is passed to the called program. |
|
INTEGER INT | A signed binary integer, 4 bytes long. |
| SMALLINT | A signed binary integer, 2 bytes long |
| FLOAT(p,s) | A single-precision or double-precision, floating point number. For single precision, p must be greater than 0 and less than 25. For double precision, p must be greater than 24 and less than 54. The precision (p) and scale (s) are only used when converting data to a displayable format; for example, to a string. |
| REAL(p,s) | A single-precision floating point number. p must be greater than 0 and less than 25. The precision (p) and scale (s) are only used when converting data to a displayable format; for example, to a string. |
|
DOUBLE (p,s) DOUBLEPRECISION(p,s) | A double-precision floating point number. p must be greater than 0 and less than 53. The precision (p) and scale (s) are only used when converting data to a displayable format; for example, to a string. |
| NUMERIC(p,s) | A zoned decimal number, with precision p and scale s. The value of p must be greater than 0 and less than 32. |
|
DEC(p,s) DECIMAL(p,s) | A packed decimal number, with precision p and scale s. The value of p must be greater than 0 and less than 32. |
| DTWTABLE | A special data type used to pass a Net.Data table to the called program. The Direct Call language environment passes a pointer to the table, which can be manipulated using the Net.Data language environment interface table functions. |
Parameters that are defined to be numeric can include the currency symbol and three-digit separators. The Direct Call language environment removes the currency symbol and three-digit separators when converting a numeric variable from string form to its internal form, before passing the variable to the program. Net.Data retrieves the currency symbol, decimal format, and three-digit separator characters from the process attributes of the process in which Net.Data is running.
If DTW_PAD_PGM_PARMS is set to NO in the configuration file or within the macro, the Direct Call language environment passes string values to your program using a null terminator character (value x'00'). This requires you to write code to handle the string (unless you are using C or C++, which expect null terminated strings).
For example, if you define the parameter field as CHAR(10), but pass a string value that is 5 bytes long, Net.Data puts the null terminator after the fifth byte. Passing the value "12345" as a string in a CHAR(10) field yields:
x'F1F2F3F4F500........'
The bytes following the null terminator are undefined (you cannot assume that the bytes are null or blank).
Because the string is null terminated and contains uninitialized bytes after the null terminator, you cannot use the string in an RPG or COBOL program. For example, if you use the string in a comparison operation, the operation does not yield valid results. The program does not expect the string to contain the null terminator and expects the string to be padded with blanks at the end.
You can use string handling functions within your program to extract the string value or use the VARCHAR data type. This method gives the length of the string in the first two bytes.
If DTW_PAD_PGM_PARMS is set to YES in the configuration file or within the macro, the Direct Call language environment passes string values to your program with the values padded to the right with blanks up to the precision length. Using the same example as above, but with DTW_PAD_PGM_PARMS set to YES, passing the value "12345" as a string in a CHAR(10) field yields:
x'F1F2F3F4F5404040404000'
Because the string has a length of 5, which is less than the specified precision, blanks are inserted after the value up to the precision length. Programs written in languages such as RPG can now use the parameter without the need to handle NULL-terminated strings.
The following list describes errors that can occur when calling programs and passing parameters to the program using the Direct Call language environment. Tips for avoiding these errors are provided.