INTOUCH^® 4GL
A Guide to the INTOUCH Language

Returns the value 3.141592653589793.

PIECES(str_expr1 [,str_expr2])

and

PIECE$(str_expr1,num_expr[,str_expr2])

PIECE$ returns an element from str_expr1 specified by num_expr. Str_expr1 contains a list of elements. The separator can be indicated by str_expr2. The default separator is a carriage-return line-feed pair.

These two functions are similar to the ELEMENTS() and ELEMENT$() functions except that:

no leading or trailing spaces are removed from the text.
quoted data is not skipped over.
the default separator is the two-character sequence. CHR$(13)+CHR$(10), the CR/LF sequence used by WRAP$().

        10 CLEAR 
            MESSAGE 'Press GOLD/F when done' 
            LINE INPUT AREA 5, 10, 8, 60: text$ 
            PRINT AT 10, 1: 'Rewrapped text' 
            wt$ = WRAP$(text$, 1, 30) 
            PRINT 'Number of lines: '; PIECES(wt$) 
            PRINT wt$ 
            PRINT 
            PRINT 'First line was: '; PIECE$(wt$, 1) 
        20  END

POS(str_expr1, str_expr2[, int_expr])

POS searches for a substring within a string. It returns the substring's starting character position. Str-exp1 is the string to be searched, str-exp2 is the substring to locate, and int-exp is the OPTIONAL character position at which to begin the search. (The default is the start of the string.)

PRETTY$(str_expr)

PRETTY$ converts text so that the text displays on any terminal. Named control characters show up with their names. Other control characters show up as {X} where "X" is the letter to press or as {XX} where "XX" is the hexadecimal value of the character.

        10  a$ = 'Hello' + CHR$(5) + CHR$(161) + CHR$(7) 
        20  PRINT PRETTY$(a$) 
        30  END 
 
        RNH 
        Hello{^E}{A1}{bel}

QUOTE$(str_expr)

The QUOTE$ function encloses a string expression in double quotes. If the string expression is already enclosed in double quotes, QUOTE$ leaves it alone. If the string expression is already wrapped in single quotes, QUOTE$ replaces them with double quotes. Elements double quoted within the string expression are given another pair of double quotes (see following example). Elements single quoted within the string expression are ignored.

        10  DO 
              CLEAR 
              PRINT AT 1,1: 
              MESSAGE 'Enter a line of text to be quoted' 
              PRINT 'Text:' 
              INPUT '', LENGTH 30: line$ 
              IF  _BACK  OR  _EXIT  THEN  EXIT DO 
              IF  line$ = ''  THEN REPEAT DO 
        20    PRINT 
              PRINT 'Quoted text using the QUOTE$ function...' 
              PRINT quote$(line$) 
              DELAY 
            LOOP 
        30  END 
 
        RNH 
        Text: 
        ? The little boy cried "wolf!" 
        
        Quoted text using the QUOTE$ function... 
        "The little boy cried ""wolf!"""

RAD(num_expr)

Given a measurement in degrees, returns the number of radians.

REAL(num_expr)

REAL changes any numeric expression into a real or floating-point value and assigns the real value to the variable specified.

        10  INPUT 'Your age': age% 
            LET decimal_age = REAL(age%) 
            PRINT 'Your number is'; decimal_age 
        20  END

REMAINDER(num_expr1, num_expr2)

REMAINDER(x,y) returns the remainder when X is divided by Y. It differs subtly from MOD. MOD(-4,3) = 2 while REMAINDER(-4,3) = -1.

REPEAT$(str_expr, int_expr)

Creates a string composed of the specified string repeated the specified number of times.

REPLACE$(str_expr1, str_expr2 [,str_sep1][,str_sep2])

Searches for a list of patterns in the str_expr1 and replaces them with the output string from str_expr2. Returns the replaced string expression.

Str_expr1 is a list of patterns to search for.

Str_expr2 is the replacement list.

Str_sep1 is the optional separator for replacement items. The default is a comma.

Str_sep2 is the optional separator between the input and output text in items. Default is =.

        10  text$ = '01-Mar-1981' 
            PRINT REPLACE$(text$, 'r=y 8=9' , ' ') 
        20  END 
                       
        RNH 
        01-May-1991

RIGHT[$](str_expr, int_expr)

RIGHT$ returns the rightmost characters from a string. The int_exp is the character position of the last character to be included in the substring COUNTING FROM THE RIGHT.

        10  ans$ = RIGHT$('Daniel', 2) 
            PRINT 'rightmost char.= ', ans$ 
        20  END 
 
        RNH 
        rightmost char.= el

RND

RND(num_expr)

RND returns a random number greater than or equal to zero and less than one. If a numeric expression (num_expr) is given, RND returns a whole number between one and the numeric expression.

ROUND(num_expr [, int_expr])

ROUND rounds a num_expr to the specified number of decimal places (int_expr). The default int_expr is 0.

RPAD$(text_str, size[,pad_str])

RPAD$ pads a string on the right with pad characters. The default pad character is a space.

        10  PRINT RPAD$('123', 6, '0') 
        20  END 
 
        RNH 
        123000

RTRIM$(str_expr)

Returns a string without any trailing spaces (those on the right side).

SCAN(str_expr1, str_expr2 [, int_expr])

Scans str_expr1 for the characters in str_expr2 and returns the position at which str_expr2 begins. Int_expr specifies a character position at which the search is to begin.

The characters in str_expr2 need not appear contiguously in str_expr1.

        10  LET a$ = 'Cameron Whitehorn' 
            LET b$ = 'amr Wtor' 
            LET position = SCAN(a$, b$) 
            PRINT position 
        20  END 
 
        RNH 
        2

SEC(num_expr)

Returns a secant of a given angle (1/COS(num_expr)). Num_expr is a passed angle.

SECONDS(str_expr)

Given a full-time string in CCYYMMDD HHMMSS, YYMMDD HHMMSS, HHMMSS or HHMM format, returns the number of seconds since the INTOUCH base date (January 1, 1600 00:00:00).

The number of seconds is returned as a floating point number.

        10  z  = SECONDS('19931201 103050') 
            z1 = SECONDS('931201 103050') 
            z2 = SECONDS('103050') 
            z3 = SECONDS('1030') 
        20  PRINT 'Seconds CYMDHMS ='; z 
            PRINT 'Seconds  YMDHMS ='; z1 
            PRINT 'Seconds     HMS ='; z2 
            PRINT 'Seconds     HM  ='; z3 
        30  END 
 
        RNH 
        Seconds CYMDHMS = 12430837850 
        Seconds  YMDHMS = 12430837850 
        Seconds     HMS = 37850 
        Seconds     HM  = 37800

SEG$(str_expr, int_expr1, int_expr2)

Extracts the substring given a first and last character position.

SGN(num_expr)

Returns the sign of a number. It returns a +1 if the expression is positive, a -1 if the expression is negative, and 0 if the expression is zero.

SIN(num_expr)

SIN returns the sine of an angle specified in radians.

SINH(num_expr)

SINH(X) returns the hyperbolic sine X.

SIZE(array_name [,int_expr])

Returns the number of elements in one dimension of an array.

array-name Array to examine

int-expr Dimension to get the size of. The default dimension is 1.

SKIP(str_expr1 [, str_expr2] [, int_expr])

SKIP returns the position of the character following the last skipped character.

Str_expr1 is the text string to be searched.

Str_expr2 contains the list of characters which are to be skipped. If only one argument is given, SKIP will skip over spaces, tabs and nulls.

Int_expr contains the search start position. This parameter is optional.

        10  a$ = '31415 hello' 
            z = SKIP(a$, '1234567890 ') 
        20  PRINT mid(a$, z) 
        30  END 
 
        RNH 
        Hello

SORT$(str_expr1 [,str_expr2])

Sorts the elements from a str_expr1 in ASCII value order. Returns a list of the sorted elements.

Str_expr1 contains the list of elements to be sorted.

Str_expr2 is an optional separator. Default is a comma.

        10  a$ = 'code area is' 
            a_sort$ = SORT$(a$, ' ') 
            PRINT a_sort$ 
        20  END 
 
        RNH 
        area code is

SPACE$(num_expr)

Returns the number of spaces indicated by num_expr.

SQR(num_expr)

SQR returns the square root of a number.

STR$(num_expr)

STR$ changes a number to a numeric string. The string that is created does not have any extra leading or trailing spaces.

SYSTEXT$

SYSTEXT$(int_expr)

SYSTEXT$ returns the text associated with the operating system status specified. If no int_expr is supplied, INTOUCH returns the text for the last system status.

TAB(int_expr)

When used with the PRINT statement, the TAB function moves the cursor or print mechanism to the right to a specified column.

TAN(num_expr)

TAN returns the tangent of an angle that is specified in radians.

TANH(num_expr)

Returns the hyperbolic tangent of the numeric expression given.

TIME(int_expr)

The value returned by the TIME function depends on the value of int_expr.

If int_expr = 0, TIME returns the number of seconds since midnight.

If int_expr = 1, TIME returns the CPU time of the process in tenths of a second.

If int_expr = 2, TIME returns connect time of the current process in minutes.

TIME$

TIME$(num_expr)

If num_expr is NOT specified, TIME$ returns the current time of day in HH:MM:SS format.

Num_expr is the number of seconds since midnight. The result is returned in HH:MM format.

        10  PRINT TIME$(1800) 
            PRINT TIME$(54178) 
        20 END 
 
        RNH 
        00:30 
        15:02

TIME(5)

Returns the number of seconds since INTOUCH was invoked. This function can be used to time events to the nearest 100th/sec.

TRIM$(str_expr)

Returns the string specified stripped of any leading or trailing spaces and tabs.

        10  LET a$ = '    HELLO    ' 
        20  PRINT '*'; a$; '*' 
        30  LET stripped$ = TRIM$(a$) 
        40  PRINT '*'; stripped$; '*' 
 
        RNH 
        *    HELLO    * 
        *HELLO*

TRUE

Returns the constant 1. It is returned as an integer.

TRUNCATE(num_expr, int_expr)

Truncates a real number to a given number of decimal places.

UBOUND(array_name [, int_expr])

Given an array and a dimension number, returns the upper bound for that dimension. It returns an integer value. The default dimension is 1.

UCASE$(str_expr)

UCASE returns a string expression with all letters in upper case.

UNQUOTE$(str_expr)

The UNQUOTE$ function removes one set of quotes from a quoted string expression. If the string expression is not quoted, UNQUOTE$ leaves the string alone. UNQUOTE$ does not affect internally quoted elements.

        10  DO 
              CLEAR 
              PRINT AT 1,1: 
              MESSAGE 'Enter a line of text to be unquoted' 
              PRINT 'Text:' 
              INPUT '', LENGTH 50: line$ 
              IF  _BACK  OR  _EXIT  THEN  EXIT DO 
              IF  line$ = ''  THEN  REPEAT DO 
        20    PRINT 
              PRINT 'Quotes removed using the UNQUOTE$ function...' 
              PRINT UNQUOTE$(line$) 
              DELAY 
            LOOP 
        100 END 
 
        RNH 
        Text: 
        ? "I will not take these 'things' for granted" 
 
        Quotes removed using the UNQUOTE$ function... 
        I will not take these 'things' for granted

VAL(num_str)

VAL returns the floating-point value of a numeric string.

VALID(text_str, rule_str)

VALID is used to validate user responses.

Text_str is the text to be validated.

Rule_str is the list of validation rules.

Multiple validation rules are separated by a semi-colon. If given characters are NOT between quotes, they are upper-cased.

VALID returns an error if there is an invalid validation rule.

        'Illegal validation rule' (-4021)

VALID returns TRUE or FALSE according to the following validation rules:

ALLOW text1, text2, text3 [to text4]
ALLOW compares the text_str with each element on the rule_str list (defaults to CHARACTER) and returns TRUE if found.
For numeric comparison, "NUMBER" or "INTEGER" must be used, otherwise, VALID() will do a string-compare validation...left justified.

        10  IF  VALID('ann', 'ALLOW ann, dan, tom')  THEN  PRINT 'true' 
        20  IF  NOT VALID('10',  'NUMBER; ALLOW 1 to 6; MAXLENGTH 2') & 
                    THEN PRINT 'false'             
        30  IF  VALID('12', 'NUMBER; ALLOW 1 TO 24,99') THEN  PRINT 'true' 
        40  END 
 
        RNH  
        true   
        false 
        true

DISALLOW text1, text2, text3 [to text4]
Returns TRUE if text_str cannot be found on the rule_str list.

        10  IF VALID('10', 'DISALLOW 01,03,05; MINLENGTH 2') & 
              THEN PRINT 'true' 
        20  END 
 
        RNH 
        true

MINLENGTH nn
Minimum of nn characters long.
MAXLENGTH nn
Maximum of nn characters long.
LENGTH nn
Exactly nn characters long.
CHARACTERS ccc
Returns TRUE if the given characters (letters or numbers) are on the rule_str list.
NOCHARACTERS ccc
Returns TRUE if the given characters are not on the rule_str list.
LETTERS
Returns TRUE if given text_str consists only of A - Z, a - z or space.
LCASE
Returns TRUE if given text_str consists of lower-case letters.
UCASE
Returns TRUE if given text_str consists of upper-case characters.
DIGITS
Returns TRUE if text_str consists of the numbers 0 - 9.
DECIMALS nn
Specifies the maximum number of decimal places.
NUMBER
Indicates that text_str is numeric (validates that number).
INTEGER
Returns TRUE if given integer number is up to 32 bits long (i.e. 2147483647).
INTEGER WORD
Returns TRUE if given integer number is up to 16 bits long (i.e. 32767).
DATE
Validates a given date in: YYMMDD or CCYYMMDD format.

DATE YMD YYMMDD format

DATE DMY DDMMYY format

DATE MDY MMDDYY format

DATE MDCY MMDDCCYY format

Note
For all dates, use 'LENGTH nn' to control whether a 6- or 8-character date is required.

DATE DMONY
Checks if text_str is a legal date in DD-Mon-YY format and returns TRUE or FALSE.

        10  PRINT VALID('01-May-93', 'DATE DMONY') 
        20  END 
 
        RNH 
        1

DATE DMONCY
Checks if text_str is a legal date in DD-Mon-CCYY format and returns TRUE or FALSE.

        10  PRINT VALID('01-May-1993', 'DATE DMONCY') 
        20  END 
 
        RNH 
        1

FULLTIME
Checks if text_str is a legal date and time in CCYYMMDD HHMMSS or YYMMDD HHMMSS format and returns TRUE or FALSE.

        10  PRINT VALID('19931231 010101', 'FULLTIME') 
            PRINT VALID('931231 010101', 'FULLTIME') 
        20  END 
 
        RNH 
        1 
        1

CODE
Checks for VALID INTOUCH code syntax.

        10  a$ = 'PRINT 'Hello, ' name$' 
            IF  NOT VALID(a$, 'CODE')  THEN  PRINT 'false' 
        30  END

PATTERN
Matches text_str with PATTERN's rule_str. For details see the PATTERN$ function.
REQUIRED
Returns TRUE if text_str is not null or space(s).
YES/NO
Returns TRUE if text_str consists only of the following: YES, NO, Y or N.

VRULES
Checks if a text_str is a legal set of validation rules, and returns TRUE or FALSE.

        10  PRINT VALID('integer', 'vrules') 
        20  END 
        
        RNH 
        1

PRINTMASK
Checks the format of text_str and returns TRUE if it is legal or FALSE otherwise.

        10  text_str$ = '##.##' 
            PRINT VALID(text_str$, 'PRINTMASK') 
        20  END 
 
        RNH 
        1

EXPRESSION
Validates a text_str$ and returns TRUE if it is a legal INTOUCH expression or FALSE otherwise.

        10  text_str$ = 'total = a% + 30' 
            PRINT VALID(text_str$, 'EXPRESSION') 
            PRINT VALID('##~-###', 'EXPRESSION') 
        20  END 
 
        RNH 
        1 
        0

MENU
Validates a text_str$ and returns TRUE if it is a legal menu description for an INPUT MENU statement, or FALSE otherwise.

        10  text_str$ = '%multi,a,b,c' 
            PRINT VALID(text_str$, 'MENU') 
        20  END 
 
        RNH 
        1

FILTER
Filters the text_str before the validation. The following filters are allowed:
- LTRIM$ - Remove leading spaces.
- RTRIM$ - Remove trailing spaces.
- TRIM$ - Remove both leading and trailing spaces.
- UCASE$ - Convert to upper-case characters.
- LCASE$ - Convert to lower-case characters.
- REPLACE - If text_str contains a few 'old_t1' characters, all of them will be replaced by 'new_t1'.
```
        old_t1=new_t1, old_t2=new_t2, .... 
```
- REMOVE - Removes any characters from the text_str.
- CHANGE - Changes specified characters. For details see the CHANGE$ function.
```
        10  IF  VALID('abcd10', & 
                  'FILTER REMOVE "10"; LETTERS'  THEN  PRINT 'true' 
            IF  VALID("ab1cd1", "FILTER REPLACE '1'='e';LETTERS") & 
                  THEN  PRINT 'true' 
            IF  VALID(" 1234  ","FILTER TRIM; NUMBER") & 
                  THEN  PRINT 'true' 
        30  END 
 
        RNH 
        true 
        true 
        true 
```
- RESTORE - Restores data to pre-filtered state for further validations. Can be used for multiple validation rules.
```
        10  IF  VALID("123", & 
                    "FILTER REPLACE '1'='a';RESTORE;NUMBER") & 
            THEN  PRINT "true" 
        20  END 
 
        RNH 
        true 
```

WRAP$(str_expr, int_expr1, int_expr2)

Returns a word-wrapped text string, given left and right margins. Each line of the string is separated with a CR/LF.

Where string_expr = text string to wrap, int_expr1 = left margin, int_expr2 = right margin.

XLATE$(str_expr1, str_expr2)

The XLATE$ function translates one string to another by referencing a table you supply. For example, the XLATE$ function can translate from EBCDIC to ASCII. The first str_expr is the string to be translated. The second str_expr is the translation table.

Next page... | Table of Contents

	array-name	Array to examine
	int-expr	Dimension to get the size of. The default dimension is 1.

DATE	YMD	YYMMDD format
DATE	DMY	DDMMYY format
DATE	MDY	MMDDYY format
DATE	MDCY	MMDDCCYY format

INTOUCH® 4GL A Guide to the INTOUCH Language