IBI WebFOCUS - Functions available and syntax to use

Using Functions

Functions operate on one or more arguments and return a single value. The returned value can be stored in a field, assigned to a Dialogue Manager variable, used in a calculation or other processing, or used in a selection or validation test. Functions provide a convenient way to perform certain calculations and manipulations.
There are two types of functions:

• Internal functions. Built into the WebFOCUS language, requiring no extra work to access or use. The following reporting and Maintain functions are internal functions. You can not replace any of these internal functions with your own functions of the same name. All other functions are external.
• ABS
• ASIS
• DMY, MDY, and YMD
• DECODE
• EDIT
• FIND
• LAST
• LOG
• LOOKUP
• MAX and MIN
• SQRT
• All Maintain-specific functions
• External functions. Stored in an external library that must be accessed. When invoking these functions, an argument specifying the output field or format of the result is required. External functions are distributed with WebFOCUS. You can replace these functions with your own functions of the same name. However, in this case, you must set USERFNS=LOCAL.

Types of Functions

You can access any of the following types of functions:

• Character functions. Manipulate alphanumeric fields or character strings
• Maintain-specific character functions. Manipulate alphanumeric fields or character strings. These functions are available only in Maintain.
• Data source and decoding functions. Search for or retrieve data source records or values, and assign values
• Date and time functions. Manipulate dates and times.
• Maintain-specific date and time functions. Manipulate dates and times. These functions are available only in Maintain.
• Format conversion functions. Convert fields from one format to another.
• Maintain-specific Light Update Support functions. Retrieve CGI parameter data implicitly from within a Maintain procedure. These functions are available only in WebFOCUS Maintain.
• Numeric functions. Perform calculations on numeric constants and fields.
• Maintain-specific Script functions. Integrate JavaScript and VBScripts into your Maintain application and perform client-side execution without returning to the WebFOCUS Server. These functions are available only in WebFOCUS Maintain.
• System functions. Call the operating system to obtain information about the operating environment or to use a system service.
• Input/Output functions. Call the operating system's input/output routines to open, close, and write records to sequential files.

WebFOCUS-specific Functions

Most Information Builders-supplied functions are available in both WebFOCUS and FOCUS. However, some functions are available only in WebFOCUS. They are:

• REVERSE
• SPAWN
• SYSTEM

ARGLEN

Measures the length of a character string within a field, excluding trailing blanks.

ASIS

Distinguishes between a blank and a zero in Dialogue Manager.

BITSON

Evaluates an individual bit within a character string to determine whether it is on or off.

BITVAL

Evaluates a string of bits within a character string and returns its value.

BYTVAL

Translates a character to its corresponding ASCII or EBCDIC decimal value.

CHKFMT

Checks a character string for incorrect characters or character types.

CTRAN

Translates a character within a character string to another character based on its decimal value.

CTRFLD

Centers a character string within a field.

DCTRAN

Translates a single-byte or double-byte character to another character.

DSTRIP

Removes a single-byte or double-byte character from a string.

EDIT

Extracts characters from or adds characters to a character string.

GETTOK

Divides a character string into substrings, called tokens, where a specific character, called a delimiter, occurs in the string.

JPTRANS

Converts Japanese specific characters.

LCWORD

Converts the letters in a character string to mixed case.

LJUST

Left-justifies a character string within a field.

LOCASE

Converts alphanumeric text to lowercase.

OVRLAY

Overlays a base character string with a substring.

PARAG

Divides a line of text into smaller lines by marking them with a delimiter.

POSIT

Finds the starting position of a substring within a larger string.

REVERSE

Reverses the characters in a character string.

RJUST

Right-justifies a character string.

SOUNDEX

Searches for a character string phonetically without regard to spelling.

SPELLNM

Takes an alphanumeric string or a numeric value with two decimal places and spells it out with dollars and cents. This function is available only for WebFOCUS.

SQUEEZ

Reduces multiple contiguous spaces within a character string to a single space.

STRIP

Removes all occurrences of a specific character from a string.

STRREP

Replaces all occurrences of a specific character string.

SUBSTR

Extracts a substring based on where it begins and its length in the parent string.

TRIM

Removes leading and/or trailing occurrences of a pattern within a character string.

UPCASE

Converts a character string to uppercase.

Character Functions for AnV Fields

LENV

Returns the actual length of an AnV field or the size of an An field.

LOCASV

Converts alphanumeric text to lowercase in an AnV field.

POSITV

Finds the starting position of a substring in an AnV field.

SUBSTV

Extracts a substring based on where it begins and its length in the parent string in an AnV field.

TRIMV

Removes leading and/or trailing occurrences of a pattern within a character string in an AnV field.

UPCASV

Converts a character string to uppercase in an AnV field.

Maintain-specific Character Functions

The following functions manipulate alphanumeric fields or character strings. They are available only in the Maintain language.

CHAR2INT

Translates an ASCII or EBCDIC character to the integer value it represents, depending on the operating system.

INT2CHAR

Translates an integer into the equivalent ASCII or EBCDIC character, depending on the operating system.

LCWORD and LCWORD2

Converts the letters in a character string to mixed case.

LENGTH

Measures the length of a character string, including trailing blanks.

LJUST

Left-justifies a character string within a field.

LOWER

Converts a character string to lowercase.

MASK

Extracts characters from or adds characters to a character string.

NLSCHR

Converts a character from the native English code page to the running code page.

OVRLAY

Overlays a base character string with a substring.

POSIT

Finds the starting position of a substring within a larger string.

RJUST

Right-justifies a character string.

SELECTS

Decodes a value from a stack.

STRAN

Substitutes a substring for another substring in a character string.

STRCMP

Compares two alphanumeric strings using the ASCII or EBCDIC collating sequence.

STRICMP

Compares two alphanumeric strings using the ASCII or EBCDIC collating sequence, but ignoring case differences.

STRNCMP

Compares a specified number of characters in two character strings starting at the beginning of the strings using the EBCDIC or ASCII collating sequence.

SUBSTR

Extracts a substring based on where it begins and its length in the parent string.

TRIM

Removes trailing occurrences of a pattern within a character string.

TRIMLEN

Determines the length of a character string excluding trailing spaces.

UPCASE

Converts a character string to uppercase.

Data Source and Decoding Functions

The following functions search for data source records, retrieve data source records or values, and assign values.

DB_LOOKUP

Retrieves a data value from a lookup data source.

DECODE

Assigns values based on the coded value of an input field.

FIND

Determines if an incoming data value is in an indexed FOCUS data source field.

LAST

Retrieves the preceding value for a field.

LOOKUP

Retrieves a data value from a cross-referenced FOCUS data source in a MODIFY request.

Standard Date and Time Functions

DATEADD

Adds a unit to or subtracts a unit from a date format.

DATECVT

Converts date formats.

DATEDIF

Returns the difference between two dates in units.

DATEMOV

Moves a date to a significant point on the calendar.

DATETRAN

Formats dates in international formats.

HADD

Increments a date-time field by a given number of units.

HCNVRT

Converts a date-time field to a character string.

HDATE

Extracts the date portion of a date-time field, converts it to a date format, and returns the result in the format YYMD.

HDIFF

Calculates the number of units between two date-time values.

HDTTM

Converts a date field to a date-time field. The time portion is set to midnight.

HEXTR

Extracts components from a date-time value and moves them to a target date-time field with all other components set to zero.

HGETC

Stores the current date and time in a date-time field.

HMASK

Extracts components from a date-time value and moves them to a target date-time field with all other components of the target field preserved.

HHMMSS

Retrieves the current time from the system.

HINPUT

Converts an alphanumeric string to a date-time value.

HMIDNT

Changes the time portion of a date-time field to midnight (all zeroes).

HNAME

Extracts a specified component from a date-time field and returns it in alphanumeric format.

HPART

Extracts a specified component from a date-time field and returns it in numeric format.

HSETPT

Inserts the numeric value of a specified component into a date-time field.

HTIME

Converts the time portion of a date-time field to the number of milliseconds or microseconds.

TIMETOTS

Converts a time to a timestamp.

TODAY

Retrieves the current date from the system.

Legacy Date Functions

AYM

Adds or subtracts months from dates that are in year-month format.

AYMD

Adds or subtracts days from dates that are in year-month-day format.

CHGDAT

Rearranges the year, month, and day portions of alphanumeric dates, and converts dates between long and short date formats.

DA

Convert dates to the corresponding number of days elapsed since December 31, 1899.

DADMY converts dates in day-month-year format.

DADYM converts dates in day-year-month format.

DAMDY converts dates in month-day-year format.

DAMYD converts dates in month-year-day format.

DAYDM converts dates in year-day-month format.

DAYMD converts dates in year-month-day format.

DMY, MDY, and YMD

Calculate the difference between two dates.

DOWK and DOWKL

Find the day of the week that corresponds to a date.

DT

Converts the number of days elapsed since December 31, 1899 to the corresponding date.

DTDMY converts numbers to day-month-year dates.

DTDYM converts numbers to day-year-month dates.

DTMDY converts numbers to month-day-year dates.

DTMYD converts numbers to month-year-day dates.

DTYDM converts numbers to year-day-month dates.

DTYMD converts numbers to year-month-day dates.

GREGDT

Converts dates in Julian format to year-month-day format.

JULDAT

Converts dates from year-month-day format to Julian (year-day format).

YM

Calculates the number of months that elapse between two dates. The dates must be in year-month format.

Maintain-specific Legacy Date Functions

ADD

Adds a given number of days to a date.

DAY

Extracts the day of the month from a date.

JULIAN

Determines the number of days that have elapsed so far in the year up to a given date.

MONTH

Extracts the month from a date.

QUARTER

Determines the quarter of the year in which a date resides.

SETMDY

Sets a value to a date.

SUB

Subtracts a given number of days from a date.

WEEKDAY

Determines the day of the week for a date.

YEAR

Extracts the year from a date.

Format Conversion Functions

The following functions convert fields from one format to another.

ATODBL

Converts a number in alphanumeric format to double-precision format.

EDIT

Converts an alphanumeric field that contains numeric characters to numeric format or converts a numeric field to alphanumeric format.

FTOA

Converts a number in a numeric format to alphanumeric format.

HEXBYT

Obtains the ASCII or EBCDIC character equivalent of a decimal integer value.

ITONUM

Converts a large binary integer in a non-FOCUS data source to double-precision format.

ITOPACK

Converts a large binary integer in a non-FOCUS data source to packed-decimal format.

ITOZ

Converts a number in numeric format to zoned format.

PCKOUT

Writes a packed number of variable length to an extract file.

PTOA

Converts a packed decimal number from numeric format to alphanumeric format.

UFMT

Converts characters in alphanumeric field values to hexadecimal representation.

XTPACK

Stores a packed number with up to 31 significant digits in an

Numeric Functions

The following functions perform calculations on numeric constants or fields.

ABS

Returns the absolute value of a number.

ASIS

Distinguishes between a blank and a zero in Dialogue Manager.

BAR

Produces a horizontal bar chart.

CHKPCK

Validates the data in a field described as packed format.

DMOD, FMOD, and IMOD

Calculate the remainder from a division.

EXP

Raises the number "e" to a specified power.

FMLLIST

Returns a string containing the complete tag list for each row in an FML request.

FMLFOR

Retrieves the tag value associated with each row in an FML request.

FMLCAP

Returns the caption value for each row in an FML hierarchy request.

INT

Returns the integer component of a number.

LOG

Returns the natural logarithm of a number.

MAX and MIN

Return the maximum or minimum value, respectively, from a list of values.

MIRR

Calculates the modified internal rate of return for a series of periodic cash flows.

NORMSDST and NORMSINV

Perform calculations on a standard normal distribution curve.

PRDNOR and PRDUNI

Generate reproducible random numbers.

RDNORM, and RDUNIF

Generate random numbers.

SQRT

Calculates the square root of a number.

XIRR

Calculates the internal rate of return for a series of cash flows that can be periodic or non-periodic.

System Functions

The following functions call the operating system to obtain information about the operating environment or to use a system service.

FEXERR

Retrieves an Information Builders error message.

FINDMEM

Determines if a specific member of a partitioned data set (PDS) exists in batch processing.

Available Operating Systems: z/OS

GETPDS

Determines if a specific member of a partitioned data set (PDS) exists, and if it does, returns the PDS name.

Available Operating Systems: z/OS

GETUSER

Retrieves the ID of the connected user.

HHMMSS

Retrieves the current time from the system.

MVSDYNAM

Transfers a FOCUS DYNAM command to the DYNAM command processor.

Available Operating Systems: z/OS

SLEEP

Suspends execution for a specified number of seconds.

SPAWN

Spawns a child process to execute system commands without terminating the current procedure. After the child process terminates, control returns to the parent process. This function is available only for WebFOCUS.

Available Operating Systems: UNIX

SYSTEM

Calls a DOS program, a DOS batch program, or a Windows application. This function is available only for WebFOCUS.

Available Operating Systems: Windows

TODAY

Retrieves the current date from the system.

Character Function

In addition to the functions discussed in this topic, there are character functions that are available only in the Maintain language.
For many functions, the output argument can be supplied either as a field name or as a format enclosed in single quotation marks. However, if a function is called from a Dialogue Manager command, this argument must always be supplied as a format, and if a function is called from a Maintain procedure, this argument must always be supplied as a field name.

ARGLEN: Measuring the Length of a String

The ARGLEN function measures the length of a character string within a field, excluding trailing spaces. The field format in a Master File specifies the length of a field, including trailing spaces.
In Dialogue Manager, you can measure the length of a supplied character string using the .LENGTH suffix.

Syntax: How to Measure the Length of a Character String

ARGLEN (inlength, infield, outfield)

Where:

Inlength

Integer

Is the length of the field containing the character string, or a field that contains the length.

infield

Alphanumeric

Is the name of the field containing the character string.

outfield

Integer

Is the field that contains the result or the format of the output value enclosed in single quotation marks?

BITVAL: Evaluating a Bit String as an Integer

The BITVAL function evaluates a string of bits within a character string. The bit string can be any group of bits within the character string and can cross byte and word boundaries. The function evaluates the bit string as a binary integer and returns the corresponding value.

Syntax: How to Evaluate a Bit String

BITVAL (string, startbit, number, outfield)

Where:

string

Alphanumeric

Is the character string to be evaluated, enclosed in single quotation marks, or a field or variable that contains the character string.

startbit

Integer

Is the number of the first bit in the bit string, counting from the left-most bit in the character string. If this argument is less than or equal to 0, the function returns a value of zero.

number

Integer

Is the number of bits in the bit string. If this argument is less than or equal to 0, the function returns a value of zero.

outfield

Integer

Is the name of the field that contains the binary integer equivalent, or the format of the output value enclosed in single quotation marks.

CTRAN: Translating One Character to Another

The CTRAN function translates a character within a character string to another character based on its decimal value. This function is especially useful for changing replacement characters to unavailable characters, or to characters that are difficult to input or unavailable on your keyboard. It can also be used for inputting characters that are difficult to enter when responding to a Dialogue Manager -PROMPT command, such as a comma or apostrophe. It eliminates the need to enclose entries in single quotation marks.
To use CTRAN, you must know the decimal equivalent of the characters in internal machine representation. For printable EBCDIC or ASCII characters and their decimal equivalents see the Character Chart for ASCII and EBCDIC. Note that the coding chart for conversion is platform dependent, hence your platform and configuration option determines whether ASCII, EBCDIC, or Unicode coding is used.
In Unicode configurations, this function uses values in the range:

• 0 to 255 for 1-byte characters.
• 256 to 65535 for 2-byte characters.
• 65536 to 16777215 for 3-byte characters.
• 16777216 to 4294967295 for 4-byte characters (primarily for EBCDIC).

Syntax: How to Translate One Character to Another

CTRAN (charlen, string, decimal, decvalue, outfield)

Where:

charlen

Integer

Is the number of characters in the string, or a field that contains the length.

string

Alphanumeric

Is the character string to be translated enclosed in single quotation marks, or the field or variable that contains the character string.

decimal

Integer

Is the ASCII or EBCDIC decimal value of the character to be translated.

decvalue

Integer

Is the ASCII or EBCDIC decimal value of the character to be used as a substitute for decimal.

outfield

Alphanumeric

Is the name of the field that contains the result, or the format of the output value enclosed in single quotation marks.

EDIT: Extracting or Adding Characters

The EDIT function extracts characters from or adds characters to an alphanumeric string. It can extract a substring from different parts of the parent string, and can also insert characters from a parent string into another substring. For example, it can extract the first two characters and the last two characters of a string to form a single substring.

Syntax: How to Extract or Add Characters

EDIT (fieldname, 'mask');

where:

fieldname

Alphanumeric

Is the source string from which characters will be extracted. It should be at least as long as the mask.

mask

Alphanumeric

GETTOK: Extracting a Substring (Token)

The GETTOK function divides a character string into substrings, called tokens. In order to use GETTOK, the data must have a specific character, called a delimiter,  that occurs in the string and separates the string into tokens. GETTOK returns the token specified by the token_number argument. GETTOK ignores leading and trailing blanks in the parent character string.
For example, suppose you want to extract the fourth word from a sentence. You can use the space character for a delimiter and four for the token_number. GETTOK divides the sentence into words using this delimiter, then extracts the fourth word. If the string is not divided by the delimiter, use the PARAG function for this purpose.

Syntax: How to Extract a Substring (Token)

GETTOK(infield, inlen, token_number, 'delim', outlen, outfield)

where:

infield

Alphanumeric

Is the field containing the parent character string.

inlen

Integer

Is the length of the parent string in characters. If this argument is less than or equal to 0, the function returns spaces.

token_number

Integer

Is the number of the token to extract. If this argument is positive, the tokens are counted from left to right. If this argument is negative, the tokens are counted from right to left. For example, -2 extracts the second token from the right. If this argument is 0, the function returns spaces. Leading and trailing null tokens are ignored.

'delim'

Alphanumeric

Is the delimiter in the parent string enclosed in single quotation marks. If you specify more than one character, only the first character is used.

Note: In Dialogue Manager, to prevent the conversion of a delimiter space character (' ') to a double precision zero, include a non-numeric character after the space (for example, '%'). GETTOK uses only the first character (the space) as a delimiter, while the extra character (%) prevents conversion to double precision.

outlen

Integer

Is the maximum size of the token. If this argument is less than or equal to 0, the function returns spaces. If the token is longer than this argument, it is truncated; if it is shorter, it is padded with trailing spaces.

outfield

Alphanumeric

Is the name of the field that contains the token, or the format of the output value enclosed in single quotation marks. The delimiter is not included in the token.

REVERSE: Reversing the Characters in a String

The REVERSE function reverses the characters of a string. This reversal includes all trailing blanks, which then become leading blanks. However, in an HTML report with SET SHOWBLANKS=OFF (the default value), the leading blanks are not visible.

Syntax: How to Reverse the Characters in a String

REVERSE (length, string, outfield)

Where:

length

Integer

Is the length in characters of string and outfield, or a field that contains the length.

string

Alphanumeric

Is the character string enclosed in single quotation marks, or a field that contains the character string.

outfield

Alphanumeric

Is the name of the field that contains the result, or the format of the output value enclosed in single quotation marks.

TRIM: Removing Leading and Trailing Occurrences

The TRIM function removes leading and/or trailing occurrences of a pattern within a character string.
There is a version of the TRIM function that is available only in the Maintain language

Syntax: How to Remove Leading and Trailing Occurrences

TRIM (trim_where, string, string_length, pattern, pattern_length, outfield)

where:

trim_where

Alphanumeric

Is one of the following, which indicates where to remove the pattern:

'L' removes leading occurrences.

'T' removes trailing occurrences.

'B' removes both leading and trailing occurrences.

string

Alphanumeric

Is the source character string enclosed in single quotation marks, or the field containing the string.

string_length

Integer

Is the length of the string in characters.

pattern

Alphanumeric

Is the pattern to remove enclosed in single quotation marks.

pattern_length

Integer

Is the number of characters in the pattern.

outfield

Alphanumeric

Is the field to which the result is returned, or the format of the output value enclosed in single quotation marks.

SUBSTR: Extracting a Substring

The SUBSTR function extracts a substring based on where it begins and its length in the parent string. SUBSTR can vary the position of the substring depending on the values of other fields.
There is a version of the SUBSTR function that is available only in the Maintain language.

Syntax: How to Extract a Substring

SUBSTR (inlength, parent, start, end, sublength, outfield)

Where:

inlength

Integer

Is the length of the parent string in characters, or a field that contains the length.

parent

Alphanumeric

Is the parent string enclosed in single quotation marks, or the field containing the parent string.

start

Integer

Is the starting position of the substring in the parent string. If this argument is less than one, the function returns spaces.

end

Integer

Is the ending position of the substring. If this argument is less than start or greater than inlength, the function returns spaces.

sublength

Integer

Is the length of the substring (normally end - start + 1). If sublength is longer than end - start +1, the substring is padded with trailing spaces. If it is shorter, the substring is truncated. This value should be the declared length of outfield. Only sublength characters will be processed.

outfield

Alphanumeric

Is the field to which the result is returned, or the format of the output value enclosed in single quotation marks.