Calling a Function From a Dialogue Manager Command

In this section:

You can call a function with Dialogue Manager in the following ways:

Dialogue Manager converts a numeric argument to double-precision format. This occurs when the value of the argument is numeric; this is not affected by the format expected by the function. This means you must be careful when supplying arguments for a function in Dialogue Manager.

If the function expects an alphanumeric string and the input is a numeric string, incorrect results will occur because of conversion to floating-point double-precision. To resolve this problem, append a non-numeric character to the end of the string, but do not count this extra character in the length of the argument.

Dialogue Manager date variables such as &YYMD return alphanumeric legacy dates, not a date format (an offset from a base date). If a function requires a date offset rather than a legacy date, you must convert any date variable to a date offset (using the DATECVT function) before using it as an argument. You can then convert the result back to a legacy date, again with the DATECVT function. For example:

-SET &TODAY_OFFSET=DATECVT(&YYMD , 'I8YYMD' , 'YYMD');
-SET &BEG_CUR_YR=DATEMOV(&TODAY_OFFSET.EVAL , 'BOY');
-SET &CLOSE_DTBOY=DATECVT(&BEG_CUR_YR.EVAL , 'YYMD' , 'I8YYMD')';

Top of page

x
Assigning the Result of a Function to a Variable

How to:

You can store the result of a function in a variable with the -SET command.

A Dialogue Manager variable contains only alphanumeric data. If a function returns a numeric value to a Dialogue Manager variable, the value is truncated to an integer and converted to alphanumeric format before being stored in the variable.



x
Syntax: How to Assign the Result of a Function to a Variable
-SET &variable = function(arg1, arg2[.LENGTH],..., 'format');

where:

variable

Is the variable to which the result will be assigned.

function

Is the function.

arg1, arg2

Are the function's arguments.

.LENGTH

Returns the length of the variable. If a function requires the length of a character string as an input argument, you can prompt for the character string and determine the length with the .LENGTH suffix.

format

Is the format of the result enclosed in single quotation marks. You cannot specify a Dialogue Manager variable for the output argument unless you use the .EVAL suffix; however, you can specify a variable for an input argument.



Example: Calling a Function From a -SET Command

AYMD adds 14 days to the value of &INDATE. The &INDATE variable is previously set in the procedure in the six-digit year-month-day format.

-SET &OUTDATE = AYMD(&INDATE, 14, 'I6');

The format of the output date is a six-digit integer (I6). Although the format indicates that the output is an integer, it is stored in the &OUTDATE variable as a character string. For this reason, if you display the value of &OUTDATE, you will not see slashes separating the year, month, and day.


Top of page

x
Branching Based on the Result of a Function

How to:

You can branch based on the result of a function by calling a function from a Dialogue Manager -IF command.

If a branching command spans more than one line, continue it on the next line by placing a dash (-) in the first column.



x
Syntax: How to Branch Based on the Result of a Function
-IF function(args) relation expression GOTO label1 [ELSE GOTO label2];

where:

function

Is the function.

args

Are the arguments.

relation

Is an operator that determines the relationship between the function and expression, for example, EQ or LE.

expression

Is a value, logical expression, or function. Do not enclose a literal in single quotation marks unless it contains a comma or embedded blank.

label1, label2

Are user-defined names up to 12 characters long. Do not use embedded blanks or the name of any other Dialogue Manager command except -QUIT or -EXIT. Do not use a word that can be confused with a function, or an arithmetic or logical operation.

The label text can precede or follow the -IF criteria in the procedure.

ELSE GOTO

Passes control to label2 when the -IF test fails.



Example: Branching Based on the Function’s Result

The result of the AYMD function provides a condition for a -IF test. One of two requests is executed, depending on the function's result:

   -LOOP 
1. -IF &INDATE EQ 0 GOTO EXIT; 
2. -SET &WEEKDAY = DOWK(&INDATE, 'A4'); 
3. -TYPE START DATE IS &WEEKDAY &INDATE 
4. -IF AYMD(&INDATE, &DAYS, 'I6YMD') LT 960101 GOTO EARLY; 
5. -TYPE LONG PROJECT
   -*EX LONGPROJ
   -RUN
   -GOTO EXIT 
6. -EARLY
   -TYPE SHORT PROJECT
   -*EX SHRTPROJ
   -RUN
   -EXIT

The procedure processes as follows:

  1. If you enter a 0, it passes control to -EXIT which terminates execution.
  2. The DOWK function obtains the day of the week for the start date.
  3. The -TYPE command displays the day of the week and start date of the project.
  4. The AYMD function calculates the date that the project will finish. If this date is before January 1, 1996, the -IF command branches to the label EARLY.
  5. If the project will finish on or after January 1, 1996, the TYPE command displays the words LONG PROJECT and exits.
  6. If the procedure branches to the label EARLY, the TYPE command displays the words SHORT PROJECT and exits.

Top of page

x
Calling a Function From an Operating System RUN Command

How to:

You can call a function that contains only alphanumeric arguments from a Dialogue Manager -TSO RUN or -MVS RUN command. This type of function performs a specific task but typically does not return a value.

If a function requires an argument in numeric format, you must first convert it to floating-point double-precision format using the ATODBL function because, unlike the -SET command, an operating system RUN command does not automatically convert a numeric argument to double-precision.



x
Syntax: How to Call a Function From an Operating System -RUN Command
{-TSO|-MVS} RUN function, input1, input2, ... [,&output]

where:

-TSO|-MVS

Is the operating system.

function

Is the name of the function.

input1, input2,...

Are the arguments. Separate the function name and each argument with a comma. Do not enclose an alphanumeric literal in single quotation marks. If a function requires the length of a character string as an argument, you can prompt for the character string, then use the .LENGTH suffix to test the length.

&output

Is a Dialogue Manager variable. Include this argument if the function returns a value; otherwise, omit it. If you specify an output variable, you must pre-define its length using a -SET command.

For example, if the function returns a value that is eight bytes long, define the variable with eight characters enclosed in single quotation marks before the function call:

-SET &output = '12345678';


Example: Calling a Function From an Operating System -RUN Command

The following example calls the CHGDAT function from a -MVS RUN command:

-SET &RESULT = '12345678901234567';
-MVS RUN CHGDAT, YYMD., MXDYY, &YYMD, &RESULT
-TYPE &RESULT

WebFOCUS