System Language Environment

The System language environment supports executing commands and calling external programs.

Configuring the System Language Environment

Add the following configuration statement to the initialization file, on one line:

ENVIRONMENT (DTW_SYSTEM)   DTWSYS    ( OUT RETURN_CODE )

See Environment Configuration Statements to learn more about the Net.Data initialization file and language environment ENVIRONMENT statements.

Issuing Commands and Calling Programs

To issue a command, define a function that uses the System (DTW_SYSTEM) language environment that includes a path to the command to be issued in an EXEC statement. For example:

%FUNCTION(DTW_SYSTEM) sys1() {
      %EXEC { ADDLIBLE.CMD %}
 %}

You can shorten the path to executable objects if you use the EXEC_PATH configuration variable to define paths to directories that contain the objects (such as, commands and programs). See EXEC_PATH to learn how to define the EXEC_PATH configuration variable.

Example 1: Issues a command

%FUNCTION(DTW_SYSTEM) sys2() {
      %EXEC { MYPGM %}
 %}

Example 2: Calls a program

%FUNCTION(DTW_SYSTEM) sys3() {
      %EXEC {MYPGM.EXE %}
 %

Passing Parameters to Programs

There are two ways to pass information to a program that is invoked by the System (DTW_SYSTEM) language environment, directly and indirectly.

Directly
Pass parameters directly on the call to the program. For example:
%DEFINE INPARM1 = "SWITCH1"
                           
%FUNCTION(DTW_SYSTEM) sys1() {
 %EXEC{
  CALL1.CMD  $(INPARM1) "literal string"
 %}
%}

The Net.Data variable INPARM1 is referenced and passed to the program. The parameters are passed to the program in the same way the parameters are passed to the program when the program is called from the command line. The parameters that are passed to the program using this method are considered input type parameters (the parameters passed to the program can be used and manipulated by the program, but changes to the parameters are not reflected back to Net.Data).

Indirectly

The System language environment cannot directly pass or retrieve Net.Data variables, so they are made available to programs in the following manner:

The following example shows how Net.Data passes variables from a macro.

%FUNCTION(DTW_SYSTEM) sys1 (IN P1, OUT P2, P3) {
   %EXEC {
      UPDPGM
   %}
 %}

You can pass Net.Data tables to a program called by the System language environment. The program accesses the values of a Net.Data macro table parameter by their Net.Data name. The column headings and field values are contained in variables identified with the table name and column number. For example, in the table myTable, the column headings are myTable_N_j, and the field values are myTable_V_i_j, where i is the row number and j is the column number. The number of rows and columns for the table are myTable_ROWS and myTable_COLS.

It is not recommended that you pass tables with many rows because the number of environment variables for the process is limited.

System Language Environment Example

The following example shows a macro that contains a function definition with three parameters, P1, P2, and P3. P1 is an input (IN) parameter and P2 and P3 are output (OUT) parameters. The function invokes a program, UPDPGM, which updates the parameter P2 with the value of P1 and sets P3 to a character string. Prior to processing the statement in the %EXEC block, the DTW_SYSTEM language environment stores P1 and the corresponding value in the environment space.

%DEFINE {
   MYPARM2 	= "ValueOfParm2"
   MYPARM3 	= "ValueOfParm3"
 %}
 %FUNCTION(DTW_SYSTEM) sys1 (IN P1, OUT P2, P3) {
   %EXEC {
      UPDPGM
   %}
 %}
 
 %HTML(upd1) {
 <p>
 Passing data to a program.  The current value 
 of MYPARM2 is "$(MYPARM2)", and the current value of MYPARM3 is
 "$(MYPARM3)".  Now we invoke the Web macro function.
 
 @sys1("ValueOfParm1", MYPARM2, MYPARM3)  
 
 <p>
 After the function call, the value of MYPARM2 is "$(MYPARM2)", 
 and the value of MYPARM3 is "$(MYPARM3)".
 %}


[ Top of Page | Previous Page | Next Page | Index ]