Supplying an Argument in a Function

When supplying an argument in a function, you must understand which types of arguments are acceptable, the formats and lengths for these arguments, and the number and order of these arguments.

In this section: Argument Types Argument Formats

Argument Length Number and Order of Arguments Verifying Function Parameters

Argument Types

The following are acceptable arguments for a function:

• Numeric constant, such as 6 or 15.
• Date constant, such as 022802.
• Date in alphanumeric, numeric, date, or AnV format format.
• Alphanumeric literal, such as STEVENS or NEW YORK NY. A literal must be enclosed in single quotation marks.
• Number in alphanumeric format.
• Field name, such as FIRST_NAME or HIRE_DATE. A field can be a data source field or temporary field. The field name can be up to 66 characters long or a qualified field name, unique truncation, or alias.
• Expression, such as a numeric, date, or alphanumeric expression. An expression can use arithmetic operators and the concatenation sign (|). For example, the following are valid expressions:

CURR_SAL * 1.03

and

FN || LN

• Dialogue Manager variable, such as &CODE or &DDNAME.
• Format of the output value enclosed in single quotation marks.
• Another function.
• Label or other row or column reference (such as R or E), or name of another RECAP calculation, when the function is called in an FML RECAP command.

Argument Formats

Depending on the function, an argument can be in alphanumeric, numeric, or date format. If you supply an argument in the wrong format, you will cause an error or the function will not return correct data. The following are the types of argument formats:

• Alphanumeric argument. An alphanumeric argument is stored internally as one character per byte. An alphanumeric argument can be a literal, an alphanumeric field, a number or date stored in alphanumeric format, an alphanumeric expression, or the format of an alphanumeric field. A literal is enclosed in single quotation marks, except when specified in operating systems that support Dialogue Manager RUN commands (for example, ‑MVS RUN).
• Numeric argument. A numeric argument is stored internally as a binary or packed number. A numeric argument includes integer (I), floating‑point single-precision (F), floating-point double‑precision (D), and packed decimal (P) formats. A numeric argument can be a numeric constant, field, or expression, or the format of a numeric field.

All numeric arguments are converted to floating-point double‑precision format when used with a function, but results are returned in the format specified for the output field.

• Date argument. A date argument can be in either alphanumeric, numeric, or date format. The list of arguments for the individual function will specify what type of format the function accepts. A date argument can be a date in alphanumeric, numeric, or date format; a date field or expression; or the format of a date field.

If you supply an argument with a two-digit year, the function assigns a century based on the DATEFNS, YRTHRESH, and DEFCENT parameter settings.

Argument Length

An argument is passed to a function by reference, meaning that the memory location of the argument is passed. No indication of the length of the argument is given.

You must supply the argument length for alphanumeric strings. Some functions require a length for the input and output arguments (for example, SUBSTR), and others use one length for both arguments (for example, UPCASE).

Be careful to ensure that all lengths are correct. Providing an incorrect length can cause incorrect results:

• If the specified length is shorter than the actual length, a subset of the string is used. For example, passing the argument 'ABCDEF' and specifying a length of 3 causes the function to process a string of 'ABC'.
• If the specified length is too long, whatever is in memory up to that length is included. For example, passing an argument of 'ABC' and specifying a length of 6 causes the function to process a string beginning with 'ABC' plus the three characters in the next three positions of memory. Depending on memory utilization, the extra three characters could be anything.

Some operating system routines are very sensitive to incorrectly specified lengths and read them into incorrectly formatted memory areas.

Number and Order of Arguments

The number of arguments required varies according to each function. Functions supplied by Information Builders may require up to six arguments. User-written subroutines may require a maximum of 28 arguments including the output argument. If a function requires more than 28 arguments, you must use two or more calls to pass the arguments to the function.

Arguments must be specified in the order shown in the syntax of each function. The required order varies according to the function.

Verifying Function Parameters

The USERFCHK setting controls the level of verification applied to DEFINE FUNCTION and Information-Builders-supplied function arguments. It does not affect verification of the number of parameters; the correct number must always be supplied.

How to: Enable Parameter Verification Control Function Parameter Verification

Example: Verifying Parameters With Correctable Errors Verifying Parameters With Uncorrectable Errors

USERFCHK is not supported from Maintain.

Functions typically expect parameters to be a specific type or have a length that depends on the value of another parameter. It is possible in some situations to enforce these rules by truncating the length of a parameter and, therefore, avoid generating an error at run-time.

The level of verification and possible conversion to a valid format performed depends on the specific function. The following two situations can usually be converted satisfactorily:

• If a numeric parameter specifies a maximum size for an alphanumeric parameter, but the alphanumeric string supplied is longer than the specified size, the string can be truncated.
• If a parameter supplied as a numeric literal specifies a value larger than the maximum size for a parameter, it can be reduced to the proper value.

Syntax: How to Enable Parameter Verification

Parameter verification can be enabled only for DEFINE FUNCTIONs and functions supplied by Information Builders. If your site has a locally written function with the same name as an Information-Builders-supplied function, the USERFNS setting determines which function will be used:

SET USERFNS= {SYSTEM|LOCAL}

where:

SYSTEM

Gives precedence to functions supplied by Information Builders. SYSTEM is the default setting. This setting is required in order to enable parameter verification.

LOCAL

Gives precedence to locally written functions. Parameter verification is not performed with this setting in effect.

Syntax: How to Control Function Parameter Verification

Issue the following command in FOCPARM, FOCPROF, on the command line, in a FOCEXEC, or in an ON TABLE command. Note that the USERFNS=SYSTEM setting must be in effect

SET USERFCHK = setting

where:

setting

Can be one of the following:

ON is the default value. Verifies parameters in requests, but does not verify parameters for functions used in Master File DEFINEs. If a parameter has an incorrect length, an attempt is made to fix the problem. If such a problem cannot be fixed, an error message is generated and the evaluation of the affected expression is terminated.

Note that if a parameter provided is the incorrect type, verification fails and processing terminates.

Because parameters are not verified for functions specified in a Master File, no errors are reported for those functions until the DEFINE field is used in a subsequent request when, if a problem occurs, the following message is generated:

(FOC003) THE FIELDNAME IS NOT RECOGNIZED

OFF does not verify parameters except in the following cases:

• If a parameter that is too long would overwrite the memory area in which the computational code is stored, the size is automatically reduced without issuing a message.
• If an alphanumeric parameter is too short, it is padded with blanks to the correct length.

FULL is the same as ON, but also verifies parameters for functions used in Master File DEFINEs.

Note that if a parameter provided is the incorrect type, verification fails and processing terminates.

ALERT verifies parameters in a request without halting execution when a problem is detected. It does not verify parameters for functions used in Master File DEFINEs. If a parameter has an incorrect length and an attempt is made to fix the problem behind the scenes, the problem is corrected with no message. If such a problem cannot be fixed, a warning message is generated. Execution then continues as though the setting were OFF, but the results may be incorrect.

Note that if a parameter provided is the incorrect type, verification fails and processing terminates.

Example: Verifying Parameters With Correctable Errors

The following request uses SUBSTR to extract the substring that starts in position 6 and ends in position 14 of the TITLE field. The fifth argument specifies a substring length (500) that is too long (it should be no longer than 9):

SET USERFCHK = ON                                         
TABLE FILE MOVIES                                         
PRINT TITLE                                      
COMPUTE                                                   
  NEWTITLE/A9  = SUBSTR(39, TITLE, 6  ,14, 500, NEWTITLE);
WHERE CATEGORY EQ 'CHILDREN'                               
END                                                       

When the request is executed with USERFCHK=ON or OFF, the incorrect length is corrected and the request continues processing:

TITLE                                    NEWTITLE 
-----                                    -------- 
SMURFS, THE                              S, THE   
SHAGGY DOG, THE                          Y DOG, TH
SCOOBY-DOO-A DOG IN THE RUFF             Y-DOO-A D
ALICE IN WONDERLAND                       IN WONDE
SESAME STREET-BEDTIME STORIES AND SONGS  E STREET-
ROMPER ROOM-ASK MISS MOLLY               R ROOM-AS
SLEEPING BEAUTY                          ING BEAUT
BAMBI                                             

Example: Verifying Parameters With Uncorrectable Errors

The following request has an incorrect data type in the last argument to SUBSTR. This parameter should specify an alphanumeric field or format for the extracted substring:

SET USERFCHK = ON                                         
TABLE FILE MOVIES                                         
PRINT TITLE                                      
COMPUTE                                                   
  NEWTITLE/F9  = SUBSTR(39, TITLE, 6  ,14, 500, 'F9');
WHERE CATEGORY EQ 'CHILDREN'                               
END                                                       

• When the request is executed with USERFCHK=ON, a message is produced and the request terminates:

ERROR AT OR NEAR LINE      5  IN PROCEDURE USERFC3 FOCEXEC 
(FOC279) NUMERIC ARGUMENTS IN PLACE WHERE ALPHA ARE CALLED FOR 
(FOC009) INCOMPLETE REQUEST STATEMENT                          
UNKNOWN FOCUS COMMAND  WHERE 
 BYPASSING TO END OF COMMAND 

• When the request is executed with USERFCHK=OFF, no verification is done and no message is produced. The request executes and produces incorrect results. In some environments, this type of error may cause abnormal termination of the application:

DIRECTOR           TITLE                                     NEWTITLE
--------           -----                                     --------
                   SMURFS, THE                              *********
BARTON C.          SHAGGY DOG, THE                          *********
                   SCOOBY-DOO-A DOG IN THE RUFF             *********
GEROMINI           ALICE IN WONDERLAND                              1
                   SESAME STREET-BEDTIME STORIES AND SONGS    -265774
                   ROMPER ROOM-ASK MISS MOLLY               *********
DISNEY W.          SLEEPING BEAUTY                          *********
DISNEY W.          BAMBI                                            0