Supplying an Argument in a Function

In this section:

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.

Argument Types

The following are acceptable arguments for a function:

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:

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:

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. Supplied functions may require up to six arguments. User-written subroutines may require a maximum of 200 arguments including the output argument. If a function requires more than 200 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

How to:

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

USERFCHK is not supported from Maintain Data.

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:

Syntax: How to Enable Parameter Verification

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

SET USERFNS= {SYSTEM|LOCAL}

where:

SYSTEM

Gives precedence to supplied functions. SYSTEM is the default value. 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.

Note: When USERFNS is set to LOCAL, DT functions only display a six-digit date.

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.

    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.

    Note:

    • The OFF setting will be deprecated in a future release.
    • We strongly recommend that you not use the OFF setting, as disabling parameter checking can lead to unexpected issues.
  • FULL is the same as ON, but also verifies parameters for functions used in Master File DEFINEs.
  • 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:
    • If a parameter provided is the incorrect type, verification fails and processing terminates.
    • Errors encountered during subroutine processing, unless fatal at the system level, are communicated to the calling routine through the return of an unchanged return parameter, which is the last parameter in the subroutine call. This is always communicated as spaces for alphanumeric outputs.

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