Software Customisation Reference Manual

Function	Comments
AFTER
BEFORE
DISTANCE
LOWCASE, UPCASE
PART
REPLACE
STRING
SUBS, DSUBS
TRIM
VTEXT

Synopsis	AFTER ( text1 , text2 )	-> text
Description	Return the substring of text1 which is after the leftmost occurrence of text2 in text1. If text2 does not occur in text1, the null string is returned.
Side Effects	None.
Example	AFTER ( ’abcdef’ , ’cd’ ) ->’ef’ AFTER ( ’abcdef’ , ’x’ ) -> ’’ AFTER ( ’abcdef’ , ’’ ) -> ’abcdef’
Errors	None.

Synopsis	BEFORE ( text1 , text2 )	-> text
Description	Return the substring of text1 which is before the leftmost occurrence of text2 in text1. If text2 does not occur in text1, text1 is returned.
Side Effects	None.
Example	BEFORE ( ’abcdef’ , ’cd’ ) -> ’ab’ BEFORE ( ’abcdef’ , ’x’ ) -> ’’ BEFORE ( ’abcdef’ , ’’ ) -> ‘’
Errors	None.

Synopsis	DISTance ( number1 ) DISTance( number1, logical1, logical2, logical3, number2, logical4)	-> text -> text
			Description	For the one-argument form, if the current distance units are FINCH, text is the conversion of the decimal inches value number1 into the format ’aa’bb.cc/dd’. Otherwise, text is the STRING conversion of number1. The six-argument form is more complex. The format is: DIST/ANCE (distance, feet, usformat, fraction, denom_or_dp, zeros)
	where: • distance is the numeric distance in inches that is to be formatted. • feet is a logical flag set to true if output is to be in feet and inches and to false if output is to be in inches. • usformat is a logical set to true if US format is to be used or false if AVEVA E3D™ format is to be used. • fraction is a logical set to true if the fractional component is to be output as a fraction or false if to be output as a decimal denom_or_dp is a number representing the largest denominator if fraction is TRUE or representing the number of decimal places if it is FALSE. • zeros is a logical set to true if zeros are to be shown when that component of the output has no value
	AVEVA E3D™ For both US and AVEVA E3D™ formats the following rules are observed: • If distance is negative, the first symbol is a minus sign. • If feet is true and the distance is at least a foot, then the number of feet is output next, followed by a single quote (’). Only if zeros is true will the number of feet be output as 0 for distances less than a foot. Otherwise the feet will be omitted. • If feet have been output, the inches will be at least two characters wide. Numbers less than ten will be preceded by a space if US format is being used or a zero if AVEVA E3D™ format is used. A zero will be output if there are no whole inches. • If no feet have been output and the distance is at least an inch, then the number of inches is displayed but without any preceding spaces. Only if zeros is true will a 0 be output for distances of less than an inch. • If inches have been output and fraction is true, these will be followed by a decimal point (.).
	• If fraction is TRUE and the number has a fractional component, then the numerator and the denominator are shown separated by a slash (/). This is then blank padded up to the width that the largest numerator and denominator would take. • If fraction is FALSE and the number of decimal places is greater than zero, then the decimal point (.) is displayed followed by the remainder up to the appropriate number of decimal places. If the number of decimal places is 0 then the decimal point is not shown either. • If US format has been selected then the following additional rules are observed on output: • The (’) after the number of feet is followed by a dash (-). • The decimal point separating the inches from the fraction is replaced by a space. • The inches and fraction of inches are followed by a double quote(”).
Side Effects	None.
Example	If the current distance units are FINCH: DISTANCE ( 17.5 ) -> ’1’5.1/2’ Some examples, where the current distance units are feet and inches: DIST(34.5,TRUE,TRUE,TRUE,100,TRUE) -> 2’-10.1/2. DIST(34.5,FALSE,TRUE,FALSE,1,TRUE) -> 34.5” DIST(34.5,FALSE,TRUE,TRUE,4,FALSE) -> 34 1/2” DIST(128.5,TRUE,FALSE,TRUE,2,TRUE) -> 10’08.1/2” The following table shows sets of options that could have been chosen and the format of the output produced for different numbers. Blanks output by the system are represented by underscores(_).
Errors	The value is too big to be converted.

Synopsis	UPCase ( text1 )	-> text
	LOWCase ( text1 )	-> text
Description	Return an upper or lower case version of text1.
Side Effects	None.
Example	UPCASE ( ’False’) -> ’FALSE’ LOWCASE ( ’False’) -> ’false’
Errors	None.

Synopsis	PART(text1, number1)	-> text
	PART(text1, number1 , text2)	-> text
Description	With two arguments, returns the number1 component of text1 assuming that text1 is split on any whitespace characters. If number1 is negative, counting of components starts from the right. With three arguments, as above, but use text2 as the separator on which splitting takes place. If you gives a part number higher than the number of components in the string, the function returns an empty string.
Side Effects	None.
Example	PART (’x-y-z’, 1, ’-’ -> ’x’ PART (’a b c d e’, 4-> ’d’ PART (’/PIPE45/B9’, -1, ’/’) -> ’B9’ PART(’aa bb cc’, 2) -> ’bb’ PART(’aa-bb-cc’,3,’-’) -> ’cc’
Errors	None.

Synopsis	REPLace (text1,text2,text3) REPLace(text1,text2,text3,int1) REPLace(text1,text2,text2,int1,int2)	-> text
		-> text
		-> text
Description	Replace search string text2 in input string text1 with replacement string text3. If int1 is given this specifies the first occurrence of text2 at which to start replacement. If int2 is given this specifies the number of replacements to make. int1 and/or int2 may be negative to indicate that the direction is backwards.
Side Effects	None.
Example	Three arguments: REPLACE (’cat dog cat cat dog ’, ’cat’, ’dog’ ) -> ’dog dog dog dog dog’ All occurrences of ’cat’ are replaced with ’dog’. Four arguments: start occurrence given: REPLACE (’cat dog cat cat cat dog’, ’cat’, ’dog’, 2) -> ’cat dog dog dog dog dog
	All occurrence of ’cat’ from the second occurrence onwards are replaced with ’dog’ REPLACE(’cat dog cat cat dog’ ,’cat’, dog’, -2 -> ’dog dog dog cat dog’ All occurrences starting at the second occurrence from the end of the string and moving backwards are replaced Note that a negative fourth argument without a fifth argument implies backwards mode.
	Five arguments: start occurrence and number of replacements given. Replace two occurrences of ’cat’ starting at second occurrence: REPLACE (’cat dog cat cat cat, ’cat’,’dog’, 2,2) -> ’cat dog dog dog cat’ Replace two occurrences in backwards direction starting at the second occurrence: REPLACE (’cat dog cat cat cat’, ,’cat’, ’dog’, 2, -2) -> ’dog dog dog cat cat ’
	Replace two occurrences in forwards direction starting at second occurrence from the end of the string: REPLACE (’cat cat cat cat dog’, ’cat’, ’dog’,-2,2) -> ’cat cat dog dog dog’ Replace two occurrences in backwards direction starting at second occurrence from the end of the string. REPLACE (’cat cat cat cat dog’,’cat’, ’dog’, -2, -2) -> ’cat dog dog cat dog’
	The following examples all give the same result: REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’, 4, 2) REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’, 5, -2) REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’,-6, -2) REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’, -7, 2)
				in each case, the output string is ’cat1 cat2 cat3 dog4 dog5 cat6 cat7 cat8 cat9 cat10’ If the replacement string text3 is a null string the required number of occurrences of the search string text2 are removed. For example: REPLACE (’AAABBABZ’, ’B’, ’’) -> ’AAAAZ’ REPLACE (’AAABBABZ’, ’B’, ’’, -1, -1) -> ’AAABBAZ’
Errors	If the input string text1 is a null string or an unset text attribute, the input string text1 is returned unchanged. For example: REPLACE (’’, ’A’,’B’) -> ’’ If the search string text2 is longer than the input string text1, the input string text1 is returned unchanged. For example: REPLACE(’AA’, ’AAAAA’ , ’B’) -> ’AA’ If no occurrence of the search string text2 is found, the input string text1 is returned unchanged. For example: REPLACE( ’AAAAAA’,’B’,’C’) -> ’AAAAAA
	If required occurrence int1 is not found the input string text1 is returned unchanged. For example: REPLACE(’AAAAAA’, ’A’, ’B’, 10 ) -> ’AAAAAA’ If the number of replacements required int2 is greater than the actual number of occurrence from the specified start occurrence, replacements are made up to the end of the string ( or beginning in backwards mode). For example: REPLACE(’AAAAAA’, ’A’, ’B’, 2, 8) -> ’ABBBBB’ REPLACE (’AAAAAA’, ’A’, ’B’, -3, 8) -> ’BBBBAA’

Synopsis	STRing ( any scalar type )	-> text
	STRing ( number , text1 )	-> text
	STRing ( pos , text1 )	-> text
Description	Turns a value into a text string. With a single argument the STRING function can be applied to the following scalar data types: • Numeric • Logical • Id • Position • Direction • Orientation With only one argument, decimal places are output to give a maximum of six significant figures. Trailing zeros are always removed in this case. With two arguments the data type may be either numeric (scalar) or position or direction. With two arguments, convert a number or position into a text string using the format described by text1, which may take any of the values between ’D0’ and ’D6’ (or ’d0’ and ’d6’), where the number indicates the number of decimal places. For numbers, STRING always outputs values as millimetres. If unit conversion is needed then the DIST function should be used. For positions, the current distance units are used.
Side Effects	None.
Example	STRING ( 1 ) -> ’1’ STRING ( 1 , ’D3’ ) -> ’1.000’ STRING ( 1.23456789 ) -> ’1.23457’ STRING(1.1230000) ->’1.123’ STRING ( 1.23456789 , ’D3’ ) -> ’1.235’ STRING (9*9 LT 100) -> ’TRUE’ STRING (OWN OF CE) -> ’/PIPE1’ STRING(POS) -> ’W1000 N20000 U18000’ STRING(POS, ’D4’ ) -> ’W10000.1234 N20000.1234 U18000.1234’ STRING(HDIR OF /PIPE1-1) -> ’D’ STRING(E 22.0125 N, ’D2’) -> ’E 22.01 N’ STRING (ORI OF NEXT) -> ’Y IS D AND Z IS U’
Errors

Synopsis	SUBString ( text1 , number1 )	-> text
	SUBString ( text1 , number1 , number2 )	-> text
			Description	With two arguments, return the substring of text1 beginning at the position number1 to the end of text1. With three arguments, return the substring of text1 beginning at the position number1 and of length number2. If number1 is negative, then counting of characters starts from the RHS of the input string. If number2 is negative, then characters up to and including the start position are returned.
			Side Effects	None.
Example	SUBSTRING ( ’abcdef’ , 3 ) -> ’cdef’ SUBSTRING ( ’abcdef’ ,-3 ) -> ’abcd’ SUBSTRING ( ’abcdef’ , 3 , 2 ) -> ’cd’ SUBSTRING ( ’abcdef’ , -3, 2 ) -> ’de’ SUBSTRING ( ’abcdef’ , 3 , -2 ) -> ’bc’ SUBSTRING ( ’abcdef’ , 10 ) -> ’’ SUBSTRING ( ’abcdef’ , -10 , 2 ) -> ’ab’
Errors	None.

Synopsis	TRIM ( text1 )	-> text
	TRIM ( text1, text2 )	-> text
	TRIM ( text1, text2, text3 )	-> text
Description	When only one argument is supplied, TRIM removes all spaces to the left (leading) and right (trailing) of text1 and returns the answer in text. When two arguments are supplied, text2 specifies where the spaces should be removed from: either ’L’ or ’l’ for left, ’R’ or ’r’ for right, and ’M’ or ’m’ for multiple (where multiple occurrences of blanks are squeezed to a single spaces) or any combination of the three key letters. So the default is ’LR’ when this field is omitted. When the third argument text3 is also supplied, this should only be a single character which overrides the space character as the character being trimmed.
Side Effects	None.
Example	TRIM ( ’ How now, brown cow ’, ’LRM’ ) -> ’How now, brown cow’ TRIM ( ’10.3000’, ’R’, ’0’ ) -> ’10.3’
Errors	None.

Synopsis	VTEXT ( variable-name )	-> text
	VTEXT ( variable-name , number )	-> text
Description	With one argument, it gets the value of the scalar variable or the value of the array variable element. With two arguments, it gets the value of the element corresponding to the index number. The value is returned as a text string. See also VLOGICAL used for late evaluation when a logical result is required, and VVALUE used for late evaluation when a numeric result is required.
Side Effects	If the scalar variable, the array variable or the array variable element does not exist, the result is undefined.
Example	VTEXT ( !var ) -> ’hello’ VTEXT ( !array[1] ) -> ’1.00’ VTEXT ( !array , 2 ) -> ’0.00’
Errors	Errors Scalar variable may not be indexed (e.g. VTEXT (!var[1]) ). Array variable must have an index (e.g. VTEXT ( !array ) ).