Skip to content

Function Clause

The FUNCTION clause invokes a special routine to reformat or convert the data before it appears in your report field.

function clause

Function Clause: Coding Rules

  • Function-name must be alphanumeric and must be either a standard supplied function name or a user-written one. It may begin with a numeric character. A full list of standard function names is given below, and you or any other person may add new ones to the list at any time.

  • The FUNCTION clause may be used only at the elementary level, in place of SOURCE, SUM, or VALUE. It is permissible for the entry to have no COLUMN or PICTURE clause, i.e. the entry may be a dummy. You may use it in a multiple-choice entry, if so desired.

  • The number of parameters you need, if any, and their formats are stated below (see 3.7.4 Built-In Functions) for each built-in function. User-written functions should also have a description that tells you this information. Some functions take no parameters while others allow either a fixed or a variable number.

  • Each parameter may be any identifier. It may also be an integer, literal, or arithmetic expression, for example:

    FUNCTION DAYSIN (SALES-DATE + 365).

    in which case the parameter is given to the Function routine as a one-word signed binary field. You cannot use SUM or COUNT terms in the expression. Neither can you use LENGTH OF, ADDRESS OF, BY CONTENT, or BY REFERENCE, as part of a parameter.

  • The FUNCTION keyword may also be used in the format FUNCTION IS function-name (...) in a SOURCE clause or in a condition in a PRESENT WHEN clause. In such cases function-name is a COBOL intrinsic function and is not part of the FUNCTION clause described here.

Function Clause: Operation

  • The function routine behaves like a subroutine whose parameters consist of the parameters specified in the FUNCTION clause, if any, together with information about the size of the report field, if any, and the report field's contents, both of which are automatically supplied by report writer. Details on the linkage to function routines are given later (see Developing User-Written Functions).

  • If you code an edited PICTURE (numeric or alphanumeric) with the FUNCTION clause, report writer invokes the function routine using an internal intermediate field that has the unedited equivalent of your PICTURE. This is obtained by removing all insertion characters, including any decimal point. Also any "Z" or "*" symbol or floating sign or currency symbols are converted to an equivalent number of "9" symbols. The "<" symbol is also removed. For example, if your entry is as follows: 05 COL 21 PIC $$,$$9.<99 FUNCTION MONEY (WS-VAL). Report writer will provide the function routine with an intermediate field with a PICTURE of 9999V99 as a parameter for receiving the output value. Report writer then executes a MOVE from the intermediate field to your original report field. This means that all functions, including user-written ones, can operate with edited report fields, without function routine developers needing to allow for the many possible edited formats.

  • One of the parameters report writer passes to the function routine is the size in bytes of the report field, if any, to be output. If the PICTURE is edited, this size is the size of the intermediate field. Using the case given in the previous paragraph, for instance, the function routine will be told that the size is 6. The Function routine may decide to produce different formats for the output report field, depending on the number of bytes implied by this size. It may also simply truncate the output value (on the left or the right) down to the number of characters required. This can give you freedom to choose from many possible PICTUREs to use with a function. For example, if MDATE is used, and today's date is 5th January, 1997:

    picture

    Functions cannot detect the kind of PICTURE symbols used. For example PICTURE XXBXXBXX produces the same result as PICTURE 99B99B99.

  • The clause SOURCE IS CURRENT-DATE behaves operationally like an implicit “Function”, since it invokes a run time routine.

Built-in Functions

The following is a list of the built-in functions.

  • CTIME (Clock Time) is similar to TIME (see below) except that it uses the 12-hour clock and prints either AM or PM (or blanks at midnight (0.00)and noon (12.00)). The (unedited) PICTURE should therefore allow fortwo additional non-numeric characters. For example, PIC 99":"99BXXcould result in 11:30 PM.

  • DATE (European Date) returns a date in any one of a number of display formats in the order day/month/year. The date does not change after the first invocation of the function.

    Number of parameters: 0 or 1.

    If no parameter is supplied, the date will be the current date at the start of the run. If one parameter is supplied, it must be either a 7-digit date held in a PIC S9(7) COMP-3 (packed) format in the form ccyyddds (s = sign), or a 5-digit date held in a PIC S9(5) COMP-3 (packed) format in the form yyddds (in which case the current century is assumed).

    date function

  • DAY (Day-of-Week) returns the alphabetic day-of-the-week represented by the given date.

    Number of parameters: 0 or 1.

    If no parameter supplied, the current date is used. If one parameter is supplied, it may be either a 7-digit date held in a PIC S9(7) COMP-3 (packed) format in the form ccyyddds (s = sign), or a 5-digit date held in a PIC S9(5) COMP-3 (packed) format in the form yyddds (when the current century is assumed), or a two- or four-byte (PIC S9(9) COMP or PIC S9(4) COMP) location containing a value from 1 (= Monday) to 7 (= Sunday), or a one-byte (PIC 9 DISPLAY) location containing a value from 1 to 7.

    day function

  • DAYSIN (Days Elapsed Since Base Date) converts a binary number of days since January 1st, 1601 to a date in the same format as for DATE. This function is identical to MDAYS, except that the date is returned in the order: day/month/year.

  • MDATE (US Date) returns a date in any one of a number of display formats in the order month/day/year. It is similar to the DATE function, except that the day and month fields are reversed.

    mdate function

  • MDAYS (Days Elapsed - US Format) converts a binary number of days since the Codasyl/ANSI standard base date of January 1st, 1601 to a date in the same format as MDATE, that is, month/day/year. See MDATE above for more information on report field lengths.

    Number of parameters: 1.

    The parameter must be the number of days since January 1st 1601 inclusive, held as one fullword binary (such as PIC S9(9) COMP). This is the base date, 584,693 days since absolute year zero (ignoring calendar reforms). A zero value means December 31 1600. A negative value gives a date before December 31 1600. You may change the base date by re-compiling the source of the FUNCTION supplied with this product, in which case your new function should have a different name to avoid incompatibility.

  • MONTH (Month Name) returns an alphabetic month name.

    not VSE

    Number of parameters: 0 or 1

    If no parameter is supplied, the current month is returned. If a parameter is supplied, it should be either a 7-digit date held in a PIC S9(7) COMP-3 (packed) format in the form ccyyddds (s = sign), or a 5-digit date held in a PIC S9(5) COMP-3 (packed) format in the form yyddds (when the current century is assumed), or a two-byte (PIC 99 DISPLAY) location containing a value from 01 to 12, or a four-byte binary (PIC S9(9) COMP) location containing a value from 1 to 12.

    month function

  • MOVE (Save Register) copies any report writer special register to a specified working location. This is a dummy function which requires no report field and may be coded without a COLUMN or PICTURE clause. (If the entry is not a dummy, the field will be space-filled.)

    Number of parameters: 2.

    Parameter 1 is any numeric special register, typically LINE-COUNTER or COLUMN-COUNTER. It may also be a user-defined data-name specified in a VARYING clause.

    Parameter 2 is any half-word binary location (PIC S9(4) COMP) to receive the contents of parameter 1.

    This FUNCTION is used to capture on the fly the contents of a register whose value is constantly changing. The following sample code prints up to 12 monthly payments to print side-by-side showing only those which are not zero and, by storing each value of the VARYING subscript R-MONTH in LAST-MONTH for those occurrences selected, it is able tostate which month was the last to be printed.

    move function

  • RDATE (Real DATE) is similar to DATE without the optional parameter, except that the current date is always fetched. Compare RMDATE.

  • RMDATE (Real MDATE) is similar to MDATE without the optional parameter, except that, if the date changes during the run, because the time passes through midnight (00:00:00), the date is changed.

    rmdate function

  • RYDATE (Real YDATE) is similar to YDATE (see below) without the optional parameter, except that the current date is always fetched. Compare RMDATE.

  • STATE (US State) returns the name of one of the US states, plus "DC".

    Number of parameters: 1

    The parameter may be either a state number with PICTURE 99 (DISPLAY) ranging from 01 (ALABAMA) to 51 (WYOMING), in alphabetical order of their full names, or a two-character standard abbreviation e.g. "AL" or "WY".

    The report-field length must be at least 14. If it is less than 20, then DISTRICT OF COLUMBIA is rendered as D.C.

  • STATEF (US State or Territory) is similar to STATE (see above) except that the five overseas territories are included, merged into the set of 51 domestic states, in alphabetical order of their full names.

  • STIME (Static Time) is similar to TIME (see below) except that the time is only fetched initially from the operating system and therefore does not change in value throughout the program.

  • TIME (Run Time) returns the current time in format hhmmsstt, where tt is hundredths of a second, if available, otherwise zeros. The value of the time may change on each invocation of the function.

    Number of parameters: none

    time function

  • YDATE (Date Reversed) returns a date in any one of a number of display formats in the order year/month/day. Apart from this order, it is similar to DATE and MDATE.

  • ZIP (Zip Code) prints a standard US or Canadian ZIP code.

    Number of parameters: 1.

    The single parameter must contain the ZIP code in the format S9(9) COMP-3. This is then output in the form nnnnn-nnnn, but the final -nnnn is left blank if the last four digits are 9999.

Compatibility

Only new Report Writer provides FUNCTION as an independent clause.

Back to top