M!INTOUCH® 4GL Y

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])

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

KThese 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. P
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' 0            LINE INPUT AREA 5, 10, 8, 60: text$ -            PRINT AT 10, 1: 'Rewrapped text' &            wt$ = WRAP$(text$, 1, 30) 3            PRINT 'Number of lines: '; PIECES(wt$)             PRINT wt$             PRINT 5            PRINT 'First line was: '; PIECE$(wt$, 1)         20  END

POS(str_expr1, str_expr2[, int_expr])

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

PRETTY$(str_expr)

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

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

QUOTE$(str_expr)

KThe QUOTE$ function encloses a string expression in double quotes. If the Istring expression is already enclosed in double quotes, QUOTE$ leaves it Falone. If the string expression is already wrapped in single quotes, LQUOTE$ replaces them with double quotes. Elements double quoted within the Istring expression are given another pair of double quotes (see following Lexample). 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$ 2              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!"         1        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)

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

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

(

REMAINDER(num_expr1, num_expr2)

IREMAINDER(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)

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

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

LSearches for a list of patterns in the str_expr1 and replaces them with the Goutput 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.

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

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

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

RIGHT[$](str_expr, int_expr)

KRIGHT$ returns the rightmost characters from a string. The int_exp is the Icharacter 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)

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

ROUND(num_expr [, int_expr])

BROUND 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])

GRPAD$ 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)

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

SCAN(str_expr1, str_expr2 [, int_expr])

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

HThe 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)

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

SECONDS(str_expr)

FGiven a full-time string in CCYYMMDD HHMMSS, YYMMDD HHMMSS, HHMMSS or GHHMM 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)

BExtracts the substring given a first and last character position.

SGN(num_expr)

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

SIN(num_expr)

7SIN 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. F
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])

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

-Str_expr1 is the text string to be searched.

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

JInt_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])

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

9Str_expr1 contains the list of elements to be sorted.

9Str_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)

4Returns the number of spaces indicated by num_expr.

SQR(num_expr)

)SQR returns the square root of a number.

STR$(num_expr)

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

SYSTEXT$

SYSTEXT$(int_expr)

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

TAB(int_expr)

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

TAN(num_expr)

BTAN 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)

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

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

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

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

TIME$

TIME$(num_expr)

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

JNum_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)

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

TRIM$(str_expr)

LReturns 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

7Returns 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])

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

UCASE$(str_expr)

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

UNQUOTE$(str_expr)

EThe UNQUOTE$ function removes one set of quotes from a quoted string Iexpression. If the string expression is not quoted, UNQUOTE$ leaves the Dstring 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$ 2              IF  _BACK  OR  _EXIT  THEN  EXIT DO .              IF  line$ = ''  THEN  REPEAT DO         20    PRINT D              PRINT 'Quotes removed using the UNQUOTE$ function...' $              PRINT UNQUOTE$(line$)               DELAY             LOOP         100 END          RNH         Text: 7        ? "I will not take these 'things' for granted"  6        Quotes removed using the UNQUOTE$ function... 3        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.

NMultiple 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)

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

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

H        10  IF  VALID('ann', 'ALLOW ann, dan, tom')  THEN  PRINT 'true' L        20  IF  NOT VALID('10',  'NUMBER; ALLOW 1 to 6; MAXLENGTH 2') & 3                    THEN PRINT 'false'             K        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]G
Returns TRUE if text_str cannot be found on the rule_str list.

C        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 cccM
Returns TRUE if the given characters (letters or numbers) are on the rule_str list.
NOCHARACTERS cccK
Returns TRUE if the given characters are not on the rule_str list.
LETTERSO
Returns TRUE if given text_str consists only of A - Z, a - z or space.
LCASEG
Returns TRUE if given text_str consists of lower-case letters.
UCASEJ
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 8
Specifies the maximum number of decimal places.
NUMBERD
Indicates that text_str is numeric (validates that number).
INTEGERV
Returns TRUE if given integer number is up to 32 bits long (i.e. 2147483647).
INTEGER WORDQ
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
FFor all dates, use 'LENGTH nn' to control whether a 6- or 8-character date is required.
DATE DMONYS
Checks if text_str is a legal date in DD-Mon-YY format and returns TRUE or FALSE.
```
3        10  PRINT VALID('01-May-93', 'DATE DMONY')         20  END          RNH 
        1 
```
DATE DMONCYU
Checks if text_str is a legal date in DD-Mon-CCYY format and returns TRUE or FALSE.
```
6        10  PRINT VALID('01-May-1993', 'DATE DMONCY')         20  END          RNH 
        1 
```

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

7        10  PRINT VALID('19931231 010101', 'FULLTIME') 5            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

PATTERNG
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/NOR
Returns TRUE if text_str consists only of the following: YES, NO, Y or N.

VRULESM
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

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

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

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

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

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

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

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

WRAP$(str_expr, int_expr1, int_expr2)

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

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

XLATE$(str_expr1, str_expr2)

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

Next page... | 6Table 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