REXX Built-in Functions
This chapter describes the REXX library of built-in functions. It is divided into three parts:
First a general introduction to built-in functions, pointing out concepts, pitfalls, parameter conventions, peculiarities, and possible system dependencies.
Then there is the reference section, which describes in detail each function in the built-in library.
At the end, there is documentation that describes where and how Regina differs from standard REXX, as described in the two other sections. It also lists Regina's extensions to the built-in library.
It is recommended that you read the first part on first on first reading of this documentation, and that you use the second part as reference. The third part is only relevant if you are going to use Regina.
This section is an introduction to the built-in functions. It describes common behavior, parameter conventions, concepts and list possible system-dependent parts.
In the description of the built-in functions, the syntax of each one is listed. For each of the syntax diagrams, the parts written in italic font names the parameters. Terms enclosed in [square brackets] denote optional elements. And the courier font is used to denote that something should be written as is, and it is also used to mark output from the computer. At the right of each function syntax is an indication of where the function is defined.
(ANSI) ANSI Standard for REXX 1996
(EXT-ANSI) Extended REXX
(SAA) System Application Architecture - IBM
(OS/2) IBM OS/2 REXX
(CMS) REXX on CMS
(AREXX) AREXX on Amiga
(REGINA) Additional function provided by Regina
Definitions of the AREXX built-in functions have been taken verbatum from http://dfduck.homeip.net/dfd/ados/arexx/main.shtml
Note that in standard REXX it is not really allowed to let the last possible parameter be empty if all commas are included, although some implementations allow it. In the following calls:
say D2X( 61 )
say D2X( 61, 1 )
say D2X( 61, )
The two first return the string consisting of a single character A, while the last should return error. If the last argument of a function call is omitted, you can not safely include the immediately preceding comma.
The built-in library uses its own internal precision for whole numbers, which may be the range from -999999999 to +999999999. That is probably far more than you will ever need in the built-in functions. For most functions, neither parameters nor return values will be effected by any setting of NUMERIC. In the few cases where this does not hold, it is explicitly stated in the description of the function.
In general, only parameters that are required to be whole numbers are used in the internal precision, while numbers not required to be whole numbers are normalized according to the setting of NUMERIC before use. But of course, if a parameter is a numeric expression, that expression will be calculated and normalized under the settings of NUMERIC before it is given to the function as a parameter.
In the descriptions of the built-in functions, several generic names are used for parameters, to indicate something about the type and use of that parameter, e.g. valid range. To avoid repeating the same information for the majority of the functions, some common "rules" for the standard parameter names are stated here. These rules implicitly apply for the rest of this chapter.
Note that the following list does not try to classify any general REXX "datatypes", but provides a binding between the sub-datatypes of strings and the methodology used when naming parameters.
Length is a non-negative whole number within the internal precision of the built-in functions. Whether it denotes a length in characters or in words, depends on the context.
String can be any normal character string, including the nullstring. There are no further requirements for this parameter. Sometimes a string is called a "packed string" to explicitly show that it usually contains more than the normal printable characters.
Option is used in some of the functions to choose a particular action, e.g. in DATE() to set the format in which the date is returned. Everything except the first character will be ignored, and case does not matter. note that the string should consequently not have any leading space.
Start is a positive whole number, and denotes a start position in e.g. a string. Whether it refers to characters or words depends on the context. The first position is always numbered 1, unless explicitly stated otherwise in the documentation. Note that when return values denotes positions, the number 0 is generally used to denote a nonexistent position.
Padchar must be a string, exactly one character long. That character is used for padding.
Streamid is a string that identifies a REXX stream. The actual contents and format of such a string is implementation dependent.
Number is any valid REXX number, and will be normalized according to the settings of NUMERIC before it is used by the function.
If you see one of these names having a number appended, that is only to separate several parameters of the same type, e.g. string1, string2 etc. They still follow the rules listed above. There are several parameters in the built-in functions that do not easily fall into the categories above. These are given other names, and their type and functionality will be described together with the functions in which they occur.
There are several errors that might occur in the built-in functions. Just one error message is only relevant for all the built-in functions, that is number 40 (Incorrect call to routine). In fact, an implementation of REXX can choose to use that for any problem it encounters in the built-in functions. Regina also provides further information in errors in built-in functions, as defined by the ANSI standard. This additional information is provided as sub-error messages and usually provide a more detailed explanation of the error.
Depending on the implementation, other error messages might be used as well. Error message number 26 (Invalid whole number) might be used for any case where a parameter should have been a whole number, or where a whole number is out of range. It is implied that this error message can be used in these situations, and it is not explicitly mentioned in the description of the functions.
Other general error messages that might be used in the built-in functions are error number 41 (Bad arithmetic conversion) for any parameter that should have been a valid REXX number. The error message 15 (Invalid binary or hexadecimal string) might occur in any of the conversion routines that converts from binary or hexadecimal format (B2X(), X2B(), X2C(), X2D()). And of course the more general error messages like error message 5 (Machine resources exhausted) can occur.
Generally, it is taken as granted that these error messages might occur for any relevant built-in function, and this will not be restated for each function. When other error messages than these are relevant, it will be mentioned in the text.
In REXX, it is in general not an error to specify a start position that is larger than the length of the string, or a length that refers to parts of a string that is beyond the end of that string. The meaning of such instances will depend on the context, and are described for each function.
Some of the functions in the built-in library are more or less system or implementation dependent. The functionality of these may vary, so you should use defensive programming and be prepared for any side-effects that they might have. These functions include:
ADDRESS() is dependent on your operating system and the implementation of REXX, since there is not standard for naming environments.
ARG() at the main level (not in subroutines and functions) is dependent on how your implementation handles and parses the parameters it got from the operating system. It is also dependent on whether the user specifies the -a command line switch.
BITAND(), BITOR() and BITXOR() are dependent on the character set of your machine. Seemingly identical parameters will in general return very different results on ASCII and EBCDIC machines. Results will be identical if the parameter was given to these functions as a binary or hexadecimal literal.
C2X(), C2D(), D2C() and X2C() will be effected by the character set of your computer since they convert to or from characters. Note that if C2X() and C2D() get their first parameter as a binary or hexadecimal literal, the result will be unaffected by the machine type. Also note that the functions B2X(), X2B(), X2D() and D2X() are not effected by the character set, since they do not use character representation.
CHARIN(), CHAROUT(), CHARS(), LINEIN(), LINEOUT(), LINES() and STREAM() are the interface to the file system. They might have system dependent peculiarities in several ways. Firstly, the naming of streams is very dependent on the operating system. Secondly, the operation of stream is very dependent on both the operating system and the implementation. You can safely assume very little about how streams behave, so carefully read the documentation for your particular implementation.
CONDITION() is dependent on the condition system, which in turn depends on such implementation dependent things as file I/O and execution of commands. Although the general operation of this function will be fairly equal among systems, the details may differ.
DATATYPE() and TRANSLATE() know how to recognize upper and lower case letters, and how to transform letters to upper case. If your REXX implementation supports national character sets, the operation of these two functions will depend on the language chosen.
DATE() has the options Month, Weekday and Normal, which produce the name of the day or month in text. Depending on how your implementation handles national character sets, the result from these functions might use the correct spelling of the currently chosen language.
DELWORD(), SUBWORD(), WORD(), WORDINDEX(), WORDLENGTH(), WORDPOS() and WORDS() requires the concept of a "word", which is defined as a non-blank characters separated by blanks. However, the interpretation of what is a blank character depends upon the implementation.
ERRORTEXT() might have slightly different wordings, depending on the implementation, but the meaning and numbering should be the same. However, note that some implementations may have additional error messages, and some might not follow the standard numbering. Error messages may also be returned in the user's native language.
QUEUED() refers to the system specific concept of a "stack", which is either internal or external to the implementation. The result of this function may therefore be dependent on how the stack is implemented on your system.
RANDOM() will differ from machine to machine, since the algorithm is implementation dependent. If you set the seed, you can safely assume that the same interpreter under the same operating system and on the same hardware platform will return a reproducible sequence. But if you change to another interpreter, another machine or even just another version of the operating system, the same seed might not give the same pseudo-random sequence.
SOURCELINE() has been changed between REXX language level 3.50 and 4.00. In 4.00 it can return 0 if the REXX implementation finds it necessary, and any request for a particular line may get a nullstring as result. Before assuming that this function will return anything useful, consult the documentation.
TIME() will differ somewhat on different machines, since it is dependent on the underlying operating system to produce the timing information. In particular, the granularity and accuracy of this information may vary.
VALUE() will be dependent on implementation and operating system if it is called with its third parameter specified. Consult the implementation specific documentation for more information about how each implementation handles this situation.
XRANGE() will return a string, which contents will be dependent on the character set used by your computer. You can safely make very few assumptions about the visual representation, the length, or the character order of the string returned by this function.
As you can see, even REXX interpreters that are within the standard can differ quite a lot in the built-in functions. Although the points listed above seldom are any problem, you should never assume anything about them before you have read the implementation specific documentation. Failure to do so will give you surprises sooner or later.
And, by the way, many implementations (probably the majority) do not follow the standard completely. So, in fact, you should never assume anything at all. Sorry ...
Note that the description differs between "blanks" and the <space> character. A blank is any character that might be used as "whitespace" to separate text into groups of characters. The <space> character is only one of several possible blanks. When this text says "blank" it means any one from a set of characters that are used to separate visual characters into words. When this text says <space>, it means one particular blank, that which is generally bound to the spacebar on a normal computer keyboard.
All implementation can be trusted to treat the <space> character as blank. Additional characters that might be interpreted as blanks are <tab> (horizontal tabulator), <ff> (formfeed), <vt> (vertical tabulator), <nl> (newline) and <cr> (carriage return). The interpretation of what is blank will vary between machines, operating systems and interpreters. If you are using support for national character sets, it will even depend on the language selected. So be sure to check the documentation before you assume anything about blank characters.
Some implementations use only one blank character, and perceives the set of blank characters as equivalent to the <space> character. This will depend on the implementation, the character set, the customs of the operating system and various other reasons.
Below follows an in depth description of all the functions in the library of built-in functions. Note that all functions in this section are available on all ports of Regina. Each function is designated as being part of the ANSI standard, or from other implementations. Following sections describe those built-in functions that are available on specific ports of Regina, or when Regina is built with certain switches.
ABBREV(long,short[,length]) (ANSI)
Returns 1 if the string short is strictly equal to the initial first part of the string long, and returns 0 otherwise. The minimum length which short must have, can be specified as length. If length is unspecified, no minimum restrictions for the length of short applies, and thus the nullstring is an abbreviation of any string.
Note that this function is case sensitive, and that leading and trailing spaces are not stripped off before the two strings are compared.
ABBREV('Foobar','Foo') |
1 |
ABBREV('Foobar','Foo',4) |
0 /*Too short */ |
ABBREV('Foobar','foo') |
0 /*Different case */ |
ABS(number) (ANSI)
Returns the absolute value of the number, which can be any valid REXX number. Note that the result will be normalized according to the current setting of NUMERIC.
ABS(-42) |
42 |
ABS(100) |
100 |
ADDRESS() (ANSI)
Returns the current default environment to which commands are sent. The value is set with the ADDRESS clause, for more information, see documentation on that clause.
ADDRESS() |
UNIX /* Maybe */ |
ARG([argno[,option]]) (ANSI)
Returns information about the arguments of the current procedure level. For subroutines and functions it will refer to the arguments with which they were called. For the "main" program it will refer to the arguments used when the REXX interpreter was called.
Note that under some operating systems, REXX scripts are run by starting the REXX interpreter as a program, giving it the name of the script to be executed as parameter. Then the REXX interpreter might process the command line and "eat" some or all of the arguments and options. Therefore, the result of this function at the main level is implementation dependent. The parts of the command line which are not available to the REXX script might for instance be the options and arguments meaningful only to the interpreter itself.
Also note that how the interpreter on the main level divides the parameter line into individual arguments, is implementation dependent. The standard seems to define that the main procedure level can only get one parameter string, but don't count on it.
For more information on how the interpreter processes arguments when called from the operating system, see the documentation on how to run a REXX script.
When called without any parameters, ARG() will return the number of comma-delimited arguments. Unspecified (omitted) arguments at the end of the call are not counted. Note the difference between using comma and using space to separate strings. Only comma-separated arguments will be interpreted by REXX as different arguments. Space-separated strings are interpreted as different parts of the same argument.
Argno must be a positive whole number. If only argno is specified, the argument specified will be returned. The first argument is numbered 1. If argno refers to an unspecified argument (either omitted or argno is greater than the number of arguments), a nullstring is returned.
If option is also specified, the return value will be 1 or 0, depending on the value of option and on whether the numbered parameter was specified or not. Option can be:
[O]
(Omitted) Returns 1 if the numbered argument was omitted or unspecified. Otherwise, 0 is returned.
[E]
(Existing) Returns 1 if the numbered argument was specified, and 0 otherwise.
If called as:
CALL FUNCTION 'This' 'is', 'a',, 'test',,
ARG() |
4 /*Last parameter omitted */ |
ARG(1) |
'This is' |
ARG(2) |
'a' |
ARG(3) |
'' |
ARG(9) |
'' /*Ninth parameter doesn't exist*/ |
ARG(2,'E') |
1 |
ARG(2,'O') |
0 |
ARG(3,'E') |
0 /*Third parameter omitted */ |
ARG(9,'O') |
1 |
B2C(binstring) (AREXX)
Converts a string of binary digits(0,1)into the corresponding(packed)character representation. The conversion is the same as though the argument string had been specified as a literal binary string(e.g. '1010'B). Blanks are permitted in the string,but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks.
B2C('00110011') |
'3' |
B2C('01100001') |
'A' |
B2X(binstring) (ANSI)
Takes a parameter which is interpreted as a binary string, and returns a hexadecimal string which represent the same information. Binstring can only contain the binary digits 0 and 1. To increase readability, blanks may be included in binstring to group the digits into groups. Each such group must have a multiple of four binary digits, except from the first group. If the number of binary digits in the first group is not a multiple of four, that group is padded at the left with up to three leading zeros, to make it a multiple of four. Blanks can only occur between binary digits, not as leading or trailing characters.
Each group of four binary digits is translated into on hexadecimal digit in the output string. There will be no extra blanks in the result, and the upper six hexadecimal digits are in upper case.
B2X('0010 01011100 0011') |
'26C3' |
B2X('10 0101 11111111') |
'26FF' |
B2X('0100100 0011') |
'243' |
BEEP(frequency[,duration]) (OS/2)
Sounds the machine's bell. The frequency and duration (in milliseconds) of the tone are specified. If no duration value is specified, it defaults to 1. Not all operating systems can sound their bells with the given specifications.
BEEP(50,1000) |
|
BITAND(string1[,[string2][,padchar]]) (ANSI)
Returns the result from bytewise applying the operator AND to the characters in the two strings string1 and string2. Note that this is not the logical AND operation, but the bitwise AND operation. String2 defaults to a nullstring. The two strings are left-justified; the first characters in both strings will be AND'ed, then the second characters and so forth.
The behavior of this function when the two strings do not have equal length is defined by the padchar character. If it is undefined, the remaining part of the longer string is appended to the result after all characters in the shorter string have been processed. If padchar is defined, each char in the remaining part of the longer string is logically AND'ed with the padchar (or rather, the shorter string is padded on the right length, using padchar).
When using this function on character strings, e.g. to uppercase or lowercase a string, the result will be dependent on the character set used. To lowercase a string in EBCDIC, use BITAND() with a padchar value of 'bf'x. To do the same in ASCII, use BITOR() with a padchar value of '20'x.
BITAND('123456'x,'3456'x) |
'101456'x |
BITAND('foobar',,'df'x) |
'FOOBAR' /*For ASCII*/ |
BITAND('123456'x,'3456'x,'f0'x) |
'101450'x |
BITCHG(string,bit) (AREXX)
Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string.
BITCHG('0313'x,4) |
'0303'x |
BITCLR(string,bit) (AREXX)
Clears (sets to zero) the specified bit in the argument string. Bit numbers aredefined such that bit 0 is the low-order bit of the rightmost byte of the string.
BITCLR('0313'x,4) |
'0303'x |
BITCOMP(string1,string2,bit[,pad]) (AREXX)
Compares the argument strings bit-by-bit,starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ,or -1 if the strings are identical.
BITCOMP('7F'x,'FF'x) |
'7' |
BITCOMP('FF'x,'FF'x) |
'-1' |
BITOR(string1[,[string2][,padchar]]) (ANSI)
Returns the result from bytewise applying the operator OR to the characters in the two strings string1 and string2. Note that this is not the logical OR operation, but the bitwise OR operation. String2 defaults to a nullstring. The two strings are left-justified; the first characters in both strings will be OR'ed, then the second characters and so forth.
The behavior of this function when the two strings do not have equal length is defined by the padchar character. If it is undefined, the remaining part of the longer string is appended to the result after all characters in the shorter string have been processed. If padchar is defined, each char in the remaining part of the longer string is logically OR'ed with the padchar (or rather, the shorter string is padded on the right length, using padchar).
When using this function on character strings, e.g. to uppercase or lowercase a string, the result will be dependent on the character set used.
BITOR('12x) |
'12'x |
BITOR('15'x,'24'x) |
'35'x |
BITOR('15'x,'2456'x) |
'3556'x |
BITOR('15'x,'2456'x,'F0'x) |
'35F6'x |
BITOR('1111'x,,'4D'x) |
'5D5D'x |
BITOR('pQrS',,'20'x) |
'pqrs' /* ASCII */ |
BITSET(string,bit) (AREXX)
Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string.
BITSET('0313'x,2) |
'0317'x |
BITTST(string,bit) (AREXX)
The boolean return indicates the state of the specified bit in the argument string.
Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte to the string.
BITTST('0313'x,4) |
'1' |
BITXOR(string1[,[string2][,padchar]]) (ANSI)
Works like BITAND(), except that the logical function XOR (exclusive OR) is used instead of AND. For more information see BITAND().
BITXOR('123456'x,'3456'x) |
'266256'x |
BITXOR('FooBar',,'20'x) |
'fOObAR' /*For ASCII */ |
BITXOR('123456'x,'3456'x,'f0'x) |
'2662A6'x |
BUFTYPE() (CMS)
This function is used for displaying the contents of the stack. It will display both the string and notify where the buffers are displayed. It is meant for debugging, especially interactive, when you need to obtain information about the contents of the stack. It always returns the nullstring, and takes no parameters.
Here is an example of the output from calling BUFTYPE (note that the second and fourth buffers are empty):
==> Lines: 4
==> Buffer: 3
"fourth line pushed, in third buffer"
==> Buffer: 2
==> Buffer: 1
"third line pushed, in first buffer"
==> Buffer: 0
"second line pushed, in 'zeroth' buffer"
"first line pushed, in 'zeroth' buffer"
==> End of Stack
C2B(string) (AREXX)
Converts the supplied string into the equivalent string of binary digits.
C2B('abc') |
'011000010110001001100011' |
C2D(string[,length]) (ANSI)
Returns a whole number, which is the decimal representation of the packed string string, interpreted as a binary number. If length (which must be a non-negative whole number) is specified, it denotes the number of characters in string to be converted, and string is interpreted as a two's complement representation of a binary number, consisting of the length rightmost characters in string. If length is not specified, string is interpreted as an unsigned number.
If length is larger than the length of string, string is sign-extended on the left. I.e. if the most significant bit of the leftmost char of string is set, string is padded with 'ff'x chars at the left side. If the bit is not set, '00'x chars are used for padding.
If length is too short, only the length rightmost characters in string are considered. Note that this will not only in general change the value of the number, but it might even change the sign.
Note that this function is very dependent on the character set that your computer is using.
If it is not possible to express the final result as a whole number under the current settings of NUMERIC DIGITS, an error is reported. The number to be returned will not be stored in the internal representation of the built-in library, so size restrictions on whole numbers that generally applies for built-in functions, do not apply in this case.
C2D('foo') |
'6713199' /*For ASCII machines */ |
C2D('103'x) |
'259' |
C2D('103'x,1) |
'3' |
C2D('103'x,2) |
'259' |
C2D('0103'x,3) |
'259' |
C2D('ffff'x,2) |
'-1' |
C2D('ffff'x) |
'65535' |
C2D('ffff'x,3) |
'65535' |
C2D('fff9'x,2) |
'-6' |
C2D('ff80'x,2) |
'-128' |
C2X(string) (ANSI)
Returns a string of hexadecimal digits that represents the character string string. Converting is done bytewise, the six highest hexadecimal digits are in uppercase, and there are no blank characters in the result Leading zeros are not stripped off in the result. Note that the behavior of this function is dependent on the character set that your computer is running (e.g. ASCII or EBCDIC).
C2X('ffff'x) |
'FFFF' |
C2X('Abc') |
'416263' /*For ASCII Machines */ |
C2X('1234'x) |
'1234' |
C2X('011 0011 1101'b) |
'033D' |
CD(directory) (REGINA)
CHDIR(directory) (REGINA)
Changes the current process's directory to the directory specified. A more portable, though non-standard alternative is to use the DIRECTORY BIF.
CHDIR('/tmp/aa') |
/* new directory now /tmp/aa */ |
CENTER(string, length [, padchar ] ) (ANSI)
CENTRE(string, length [, padchar ] ) (ANSI)
This function has two names, to support both American and British spelling. It will center string in a string total of length length characters. If length (which must be a non-negative whole number) is greater than the length of string, string is padded with padchar or <space> if padchar is unspecified. If length is smaller than the length of string character will be removed.
If possible, both ends of string receives (or loses) the same number of characters. If an odd number of characters are to be added (or removed), one character more is added to (or removed from) the right end than the left end of string.
CENTER('Foobar',10) |
' Foobar ' |
CENTER('Foobar',11) |
' Foobar ' |
CENTRE('Foobar',3) |
'oob' |
CENTER('Foobar',4) |
'ooba' |
CENTER('Foobar',10,'*') |
'**Foobar**' |
CHANGESTR(needle, haystack, newneedle ) (ANSI)
The purpose of this function is to replace all occurrences of needle in the string haystack with newneedle. The function returns the changed string.
If haystack does not contain needle, then the original haystack is returned.
CHANGESTR('a','fred','c') |
'fred' |
CHANGESTR('','','x') |
'' |
CHANGESTR('a','abcdef','x') |
'xbcdef' |
CHANGESTR('0','0','1') |
'1' |
CHANGESTR('a','def','xyz') |
'def' |
CHANGESTR('a','','x') |
'' |
CHANGESTR('','def','xyz') |
'def' |
CHANGESTR('abc','abcdef','xyz') |
'xyzdef' |
CHANGESTR('abcdefg','abcdef','xyz') |
'abcdef' |
CHANGESTR('abc','abcdefabccdabcd','z') |
'zdefzcdzd' |
CHARIN([streamid][,[start][,length]]) (ANSI)
This function will in general read characters from a stream, and return a string containing the characters read. The streamid parameter names a particular stream to read from. If it is unspecified, the default input stream is used.
The start parameter specifies a character in the stream, on which to start reading. Before anything is read, the current read position is set to that character, and it will be the first character read. If start is unspecified, no repositioning will be done. Independent of any conventions of the operating system, the first character in a stream is always numbered 1. Note that transient streams do not allow repositioning, and an error is reported if the start parameter is specified for a transient stream.
The length parameter specifies the number of characters to read. If the reading did work, the return string will be of length length. There are no other ways to how many characters were read than checking the length of the return value. After the read, the current read position is moved forward as many characters as was read. If length is unspecified, it defaults to 1. If length is 0, nothing is read, but the file might still be repositioned if start was specified.
Note that this function read the stream raw. Some operating systems use special characters to differ between separate lines in text files. On these systems these special characters will be returned as well. Therefore, never assume that this function will behave identical for text streams on different systems.
What happens when an error occurs or the End-Of-File (EOF) is seen during reading, is implementation dependent. The implementation may choose to set the NOTREADY condition (does not exist in REXX language level 3.50). For more information, see chapter on Stream Input and Output.
(Assuming that the file "/tmp/file" contains the first line: "This is the first line"):
CHARIN() |
'F' /*Maybe*/ |
CHARIN(,,6) |
'Foobar' /*Maybe*/ |
CHARIN('/tmp/file',,6) |
'This i' |
CHARIN('/tmp/file',4,6) |
's is t' |
CHAROUT([streamid][,[string][,start]]) (ANSI)
In general this function will write string to a streamid. If streamid is not specified the default output stream will be used.
If start is specified, the current write position will be set to the startth character in streamid, before any writing is done. Note that the current write position ca not be set for transient streams, and attempts to do so will report an error. Independent of any conventions that the operating system might have, the first character in the stream is numbered 1. If start is not specified, the current write position will not be changed before writing.
If string is omitted, nothing is written, and the effect is to set the current write position if start is specified. If neither string nor start is specified, the implementation can really do whatever it likes, and many implementations use this operation to close the file, or flush any changes. Check implementation specific documentation for more information.
The return value is the number of characters in string that was not successfully written, so 0 denotes a successful write. Note that in many REXX implementations there is no need to open a stream; it will be implicitly opened when it is first used in a read or write operation.
(Assuming the file referred to by outdata was empty, it will contain the string FoobWow afterwards. Note that there might will not be an End-Of-Line marker after this string, it depends on the implementation.)
CHAROUT(,'Foobar') |
'0' |
CHAROUT(outdata,'Foobar') |
'0' |
CHAROUT(outdata,'Wow',5) |
'0' |
CHARS([streamid]) (ANSI)
Returns the number of characters left in the named streamid, or the default input stream if streamid is unspecified. For transient streams this will always be either 1 if more characters are available, or 0 if the End-Of-File condition has been met. For persistent streams the number of remaining bytes in the file will be possible to calculate and the true number of remaining bytes will be returned.
However, on some systems, it is difficult to calculate the number of characters left in a persistent stream; the requirements to CHARS() has therefore been relaxed, so it can return 1 instead of any number other than 0. If it returns 1, you can therefore not assume anything more than that there is at least one more character left in the input stream.
CHARS() |
'1' /* more data on def. input stream */ |
CHARS() |
'0' /* EOF for def. input stream */ |
CHARS('outdata') |
'94' /* maybe */ |
CLOSE(file) (AREXX)
Closes the file specified by the given logical name. The returned value is a boolean success flag, and will be 1 unless the specified file was not open.
CLOSE('input') |
'1' |
COMPARE(string1,string2[,padchar]) (ANSI)
This function will compare string1 to string2, and return a whole number which will be 0 if they are equal, otherwise the position of the first character at which the two strings differ is returned. The comparison is case-sensitive, and leading and trailing space do matter.
If the strings are of unequal length, the shorter string will be padded at the right hand end with the padchar character to the length of the longer string before the comparison. If a padchar is not specified, <space> is used.
COMPARE('FooBar','Foobar') |
'4' |
COMPARE('Foobar','Foobar') |
'0' |
COMPARE('Foobarrr','Fooba') |
'6' |
COMPARE('Foobarrr','Fooba','r' ) |
'0' |
COMPRESS(string[,list]) (AREXX)
If the list argument is omitted,the function removes leading,trailing,or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string.
COMPRESS(' why not ') |
'whynot' |
COMPRESS('++12-34-+','+-') |
'1234' |
CONDITION([option]) (ANSI)
Returns information about the current trapped condition. A condition becomes the current trapped condition when a condition handler is called (by CALL or SIGNAL) to handle the condition. The parameter option specifies what sort of information to return:
[C]
(Condition) The name of the current trapped condition is return, this will be one of the condition named legal to SIGNAL ON, like SYNTAX, HALT, NOVALUE, NOTREADY, ERROR or FAILURE.
[D]
(Description) A text describing the reason for the condition. What to put into this variable is implementation and system dependent.
[I]
(Instruction) Returns either CALL or SIGNAL, depending on which method was current when the condition was trapped.
[S]
(State) The current state of the current trapped condition. This can be one of ON, OFF or DELAY. Note that this option reflect the current state, which may change, not the state at the time when the condition was trapped.
For more information on conditions, consult the chapter Conditions. Note that condition may in several ways be dependent on the implementation and system, so read system and implementation dependent information too.
COPIES(string,copies) (ANSI)
Returns a string with copies concatenated copies of string. Copies must be a non-negative whole number. No extra space is added between the copies.
COPIES('Foo',3) |
'FooFooFoo' |
COPIES('*',16) |
'****************' |
COPIES('Bar ',2)'Bar Bar ' |
|
COPIES('',10000) |
'' |
COUNTSTR(needle,haystack) (ANSI)
Returns a count of the number of occurrences of needle in haystack that do not overlap.
COUNTSTR('','') |
0 |
COUNTSTR('a','abcdef') |
1 |
COUNTSTR(0,0) |
1 |
COUNTSTR('a','def') |
0 |
COUNTSTR('a','') |
0 |
COUNTSTR('','def') |
0 |
COUNTSTR('abc','abcdef') |
1 |
COUNTSTR('abcdefg','abcdef' |
0 |
COUNTSTR('abc','abcdefabccdabcd') |
3 |
CRYPT(string,salt) (REGINA)
Encrypts the given string using the supplied salt and returns the encrypted string. Only the first two characters of salt are used. Not all operating systems support encryption, and on these platforms, the string is returned unchanged. It is also important to note that the encrypted string is not portable between platforms.
CRYPT('a string', '1x') |
'1xYwPPWI1zRJs' /* maybe */ |
DATATYPE(string[,option]) (ANSI)
With only one parameter, this function identifies the "datatype" of string. The value returned will be "NUM" if string is a valid REXX number. Otherwise, "CHAR" is returned. Note that the interpretation of whether string is a valid number will depend on the current setting of NUMERIC.
If option is specified too, it will check if string is of a particular datatype, and return either "1" or "0" depending on whether string is or is not, respectively, of the specified datatype. The possible values of option are:
[A]
(Alphanumeric) Consisting of only alphabetic characters (in upper, lower or mixed case) and decimal digits.
[B]
(Binary) Consisting of only the two binary digits 0 and 1. Note that blanks are not allowed within string, as would have allowed been within a binary string.
[L]
(Lower) Consisting of only alphabetic characters in lower case.
[M]
(Mixed) Consisting of only alphabetic characters, but the case does not matter (i.e. upper, lower or mixed.)
[N]
(Numeric) If string is a valid REXX number, i.e. DATATYPE(string) would return NUM.
[S]
(Symbolic) Consists of characters that are legal in REXX symbols. Note that this test will pass several strings that are not legal symbols. The characters includes plus, minus and the decimal point.
[U]
(Upper) Consists of only upper case alphabetic characters.
[W]
(Whole) If string is a valid REXX whole number under the current setting of NUMERIC. Note that 13.0 is a whole number since the decimal part is zero, while 13E+1 is not a whole number, since it must be interpreted as 130 plus/minus 5.
[X]
(Hexadecimal) Consists of only hexadecimal digits, i.e. the decimal digits 0-9 and the alphabetic characters A-F in either case (or mixed.) Note that blanks are not allowed within string, as it would have been within a hexadecimal string.
If you want to check whether a string is suitable as a variable name, you should consider using the SYMBOL() function instead, since the Symbolic option only verifies which characters string contains, not the order. You should also take care to watch out for lower case alphabetic characters, which are allowed in the tail of a compound symbol, but not in a simple or stem symbol or in the head of compound symbol.
Also note that the behavior of the options A, L, M and U might depend on the setting of language, if you are using an interpreter that supports national character sets.
DATATYPE(' - 1.35E-5 ') |
'NUM' |
DATATYPE('1E999999999') |
'CHAR' |
DATATYPE('1E9999999999') |
'CHAR' |
DATATYPE('!@#&#$(&*%`') |
'CHAR' |
DATATYPE('FooBar','A') |
'1' |
DATATYPE('Foo Bar','A') |
'0' |
DATATYPE('010010111101','B') |
'1' |
DATATYPE('0100 1011 1101','B') |
'0' |
DATATYPE('foobar','L') |
'1' |
DATATYPE('FooBar','M') |
'1' |
DATATYPE(' -34E3 ','N') |
'1' |
DATATYPE('A_SYMBOL!?!','S') |
'1' |
DATATYPE('1.23.39E+4.5','S') |
'1' |
DATATYPE('Foo bar','S') |
'0' |
DATATYPE('FOOBAR','U') |
'1' |
DATATYPE('123deadbeef','X') |
'1' |
DATE([option_out [,date [,option_in]]]) (ANSI)
This function returns information relating to the current date. If the option_out character is specified, it will set the format of the return string. The default value for option_out is "N".
Possible options are:
[B]
(Base) The number of complete days from January 1st 0001 until yesterday inclusive, as a whole number. This function uses the Gregorian calendar extended backwards. Therefore Date('B') // 7 will equal the day of the week where 0 corresponds to Monday and 6 Sunday.
[C]
(Century) The number of days in this century from January 1st -00 until today, inclusive. The return value will be a positive integer.
[D]
(Days) The number of days in this year from January 1st until today, inclusive. The return value will be a positive integer.
[E]
(European) The date in European format, i.e. "dd/mm/yy". If any of the numbers is single digit, it will have a leading zero.
[M]
(Month) The unabbreviated name of the current month, in English.
[N]
(Normal) Return the date with the name of the month abbreviated to three letters, with only the first letter in upper case. The format will be "dd Mmm yyyy", where Mmm is the month abbreviation (in English) and dd is the day of the month, without leading zeros.
[O]
(Ordered) Returns the date in the ordered format, which is "yy/mm/dd".
[S]
(Standard) Returns the date according the format specified by International Standards Organization Recommendation ISO/R 2014-1971 (E). The format will be "yyyymmdd", and each part is padded with leading zero where appropriate.
[U]
(USA) Returns the date in the format that is normally used in USA, i.e. "mm/dd/yy", and each part is padded with leading zero where appropriate.
[W]
(Weekday) Returns the English unabbreviated name of the current weekday for today. The first letter of the result is in upper case, the rest is in lower case.
[T]
(time_t) Returns the current date/time in UNIX time_t format. time_t is the number of seconds since January 1st 1970.
Note that the "C" option is present in REXX language level 3.50, but was removed in level 4.00. The new "B" option should be used instead. When porting code that use the "C" option to an interpreter that only have the "B" option, you will can use the conversion that January 1st 1900 is day 693595 in the Gregorian calendar.
Note that none of the formats in which DATE() return its answer are effected by the settings of NUMERIC. Also note that if there are more than one call to DATE() (and TIME()) in a single clause of REXX code, all of them will use the same basis data for calculating the date (and time).
If the REXX interpreter contains national support, some of these options may return different output for the names of months and weekdays.
Assuming that today is January 6th 1992:
DATE('B') |
'727203' |
DATE('C') |
'33609' |
DATE('D') |
'6' |
DATE('E') |
'06/01/92' |
DATE('M') |
'January' |
DATE('N') |
'6 Jan 1992' |
DATE('O') |
'92/01/06' |
DATE('S') |
'19920106' |
DATE('U') |
'01/06/92' |
DATE('W') |
'Monday' |
DATE('T') |
694620000 |
If the date option is specified, the function provides for date conversions. The optional option_in specifies the format in which date is supplied. The possible values for option_in are: BDEOUNST.
The default value for option_in is N.
DATE('O','13 Feb 1923') |
'23/02/13' |
DATE('O','06/01/50','U') |
'50/06/01' |
If the date supplied does not include a century in its format, then the result is chosen to make the
year within 50 years past or 49 years future of the current year.
The date conversion capability of the DATE BIF was introduced with the ANSI standard.
DELSTR(string,start[,length]) (ANSI)
Returns string, after the substring of length length starting at position start has been removed. The default value for length is the rest of the string. Start must be a positive whole number, while length must be a non-negative whole number. It is not an error if start or length (or a combination of them) refers to more characters than string holds
DELSTR('Foobar',3) |
'Foo' |
DELSTR('Foobar',3,2) |
'Foor' |
DELSTR('Foobar',3,4) |
'Foo' |
DELSTR('Foobar',7) |
'Foobar' |
DELWORD(string,start[,length]) (ANSI)
Removes length words and all blanks between them, from string, starting at word number start. The default value for length is the rest of the string. All consecutive spaces immediately after the last deleted word, but no spaces before the first deleted word is removed. Nothing is removed if length is zero.
The valid range of start is the positive whole numbers; the first word in string is numbered 1. The valid range of length is the non-negative integers. It is not an error if start or length (or a combination of them) refers to more words than string holds.
DELWORD('This is a test',3) |
'This is ' |
DELWORD('This is a test',2,1) |
'This a test' |
DELWORD('This is a test',2,5) |
'This' |
DELWORD('This is a test',1,3) |
'test' /*No leading space*/ |
DESBUF() (CMS)
This function removes all buffers on the stack, it is really just a way of clearing the whole stack for buffers as well as strings. Functionally, it is equivalent to executing DROPBUF with a parameter of 0. (Actually, this is a lie, since DROPBUF is not able to take zero as a parameter. Rather, it is equivalent to executing DROPBUF with 1 as parameter and then executing DROPBUF without a parameter, but this is a subtle point.) It will return the number of buffers left on the stack after the function has been executed. This should be 0 in all cases.
DESBUF() |
0 |
DIGITS() (ANSI)
Returns the current precision of arithmetic operations. This value is set using the NUMERIC statement. For more information, refer to the documentation on NUMERIC.
DIGITS() |
'9' /* Maybe */ |
DIRECTORY([new directory]) (OS/2)
Returns the current directory for the running process, and optionally changes directory to the specified new directory. If the new directory exists, and the change to new directory succeeds, the new directory is returned. If the new directory does not exist or an error occurred changing to that new directory, the empty string is returned.
DIRECTORY() |
'/tmp' /* Maybe */ |
DIRECTORY('c:\temp') |
'c:\temp' /* Maybe */ |
D2C(integer[,length]) (ANSI)
Returns a (packed) string, that is the character representation of integer, which must be a whole number, and is governed by the settings of NUMERIC, not of the internal precision of the built-in functions. If length is specified the string returned will be length bytes long, with sign extension. If length (which must be a non-negative whole number) is not large enough to hold the result, an error is reported.
If length is not specified, integer will be interpreted as an unsigned number, and the result will have no leading <nul> characters. If integer is negative, it will be interpreted as a two's complement, and length must be specified.
D2C(0) |
'' |
D2C(127) |
'7F'x |
D2C(128) |
'80'x |
D2C(128,3) |
'000080'x |
D2C(-128) |
'80'x |
D2C(-10,3) |
'fffff5'x |
D2X(integer[,length]) (ANSI)
Returns a hexadecimal number that is the hexadecimal representation of integer. Integer must be a whole number under the current settings of NUMERIC, it is not effected by the precision of the built-in functions.
If length is not specified, then integer must be non-negative, and the result will be stripped of any leading zeros.
If length is specified, then the resulting string will have that length. If necessary, it will be sign-extended on the left side to make it the right length. If length is not large enough to hold integer, an error is reported.
D2X(0) |
'0' |
D2X(127) |
'7F' |
D2X(128) |
'80' |
D2X(128,5) |
'00080'x |
D2X(-128) |
'80'x |
D2X(-10,5) |
'ffff5'x |
DROPBUF([number]) (CMS)
This function will remove zero or more buffers from the stack. Called without a parameter, it will remove the topmost buffer from the stack, provided that there were at least one buffer in the stack. If there were no buffers in the stack, it will remove all strings in the stack, i.e. remove the zeroth buffer.
If the parameter number was specified, and the stack contains a buffer with an assigned number equal to number, then that buffer itself, and all strings and buffers above it on the stack will be removed; but no strings or buffers below the numbered buffer will be touched. If number refers to a buffer that does not exist in the stack; no strings or buffers in the stack is touched.
As an extra extension, in Regina the DROPBUF() built-in function can be given a non-positive integer as parameter. If the name is negative then it will convert that number to its absolute value, and remove that many buffers, counted from the top. This is functionally equivalent to repeating DROPBUF() without parameters for so many times as the absolute value of the negative number specifies. Note that using -0 as parameter is equivalent to removing all strings and buffers in the stack, since -0 is equivalent to normal 0. The number is converted during evaluation of parameters prior to the call to the DROPBUF() routine, so the sing is lost.
The value returned from this function is the number of buffers left on the stack after the buffers to be deleted have been removed. Obviously, this will be a non-negative integer. This too, deviates from the behavior of the DROPBUF command under CMS, where zero is always returned.
DROPBUF(3) |
2 /* remove buffer 3 and 4 */ |
DROPBUF(4) |
0 /* no buffers on the stack */ |
DROPBUF() |
4 /* if there where 5 buffers */ |
EOF(file) (AREXX)
Checks the specified logical file name and returns the boolean value 1(True) if the end-of-file has been reached, and 0(False)otherwise.
EOF('infile') |
'1' /* maybe */ |
ERRORTEXT(errno[, lang]) (ANSI)
Returns the REXX error message associated with error number errno. If the lang character is specified, it will determine the native language in which the error message is returned. The default value for lang is "N".
Possible options are:
[N]
(Normal) The error text is returned in the default native language.
[S]
(Standard English) The error text is returned in English.
For more information on how Regina supports different native languages, see Native Language Support.
If the error message is not defined, a nullstring is returned.
The error messages in REXX might be slightly different between the various implementations. The standard says that errno must be in the range 0-99, but in some implementations it might be within a less restricted range which gives room for system specific messages. You should in general not assume that the wordings and ordering of the error messages are constant between implementations and systems.
ERRORTEXT(20) |
'Symbol expected' |
ERRORTEXT(30) |
'Name or string too long' |
ERRORTEXT(40) |
'Incorrect call to routine' |
errno can also be specified as an errno followed by a sub error number, with a period between. The resulting string will be the text of the sub-error number with placemarkers indicating where substitution values would normally be placed.
ERRORTEXT(40.24) |
<bif> argument 1 must be a binary string; found "<value>" |
Regina also supports messages in several native languages. See the section on Native Language Support for details on how this is configured. With DE as the native language in effect:
ERRORTEXT(40.24) |
Routine <bif>, Argument 1 muß eine Binätzeichenkette sein; "<value>" |
ERRORTEXT(40.24,'S') |
<bif> argument 1 must be a binary string; found "<value>" |
EXISTS(filename) (AREXX)
Tests whether the specified name of the given filename exists. The filename string may include any portion of a full file path specification. Note that the argument is not a logical file name used in other ARexx file functions. A more portable equivalent of this is to use the 'QUERY EXISTS' command of the STREAM BIF.
EXISTS('c:\temp\infile.txt') |
'1' /* maybe */ |
EXPORT(address,[string],[length][,pad]) (AREXX)
Copies data from the (optional) string into a previously-allocated memory area, which must be specified as a 4-byte address. The length parameter specifies the maximum number of characters to be copied; the default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls('00'x). The returned value is the number
of characters copied.
Caution is advised in using this function. Any area of memory can be overwritten,possibly causing a system crash.
See also STORAGE() and IMPORT().
Note that the address specified is subject to a machine's endianess.
EXPORT('0004 0000'x,'The answer') |
'10' |
FIND(string,phrase) (CMS)
Searches string for the first occurrence of the sequence of blank-delimited words phrase, and return the word number of the first word of phrase in string. Multiple blanks between words are treated as a single blank for the comparison. Returns 0 if phrase not found. Deprecated: see WORDPOS().
FIND('now is the time','is the time') |
2 |
FIND('now is the time','is the') |
2 |
FIND('now is the time','is time') |
0 |
FORK() (REGINA)
This function spawns a new process as a child of the current process at the current point in the program where FORK is called. The program then continues from this point as two separate processes; the parent and the child. FORK returns 0 to the child process, and the process id of the child process spawned to the parent (always non-zero). A negative return value indicates an error while attempting to create the new process. FORK is not available on all platforms. If FORK is not supported, it will always return '1'. It is safe to assume that a return value of '1' means that FORK is not supported. All platforms AFAIK, will never return '1' as a child process id; that number is usually reserved for the first process that starts on a machine.
FORK() |
'0' /* To child */ |
|
'3456' /* maybe to parent */ |
FORM() (ANSI)
Returns the current "form", in which numbers are presented when exponential form is used. This might be either SCIENTIFIC (the default) or ENGINEERING. This value is set through the NUMERIC FORM clause. For more information, see the documentation on NUMERIC.
FORM() |
'SCIENTIFIC' /* Maybe */ |
FORMAT(number[,[before][,[after][,[expp][,[expt]]]]]) (ANSI)
This function is used to control the format of numbers, and you may request the size and format in which the number is written. The parameter number is the number to be formatted, and it must be a valid REXX number. note that before any conversion or formatting is done, this number will be normalized according to the current setting of NUMERIC.
The before and after parameters determines how many characters that are used before and after the decimal point, respectively. Note that before does not specify the number of digits in the integer part, it specifies the size of the field in which the integer part of the number is written. Remember to allocate space in this field for a minus too, if that is relevant. If the field is not long enough to hold the integer part (including a minus if relevant), an error is reported.
The after parameter will dictate the size of the field in which the fractional part of the number is written. The decimal point itself is not a part of that field, but the decimal point will be omitted if the field holding the fractional part is empty. If there are less digits in the number than the size of the field, it is padded with zeros at the right. If there is more digits then it is possible to fit into the field, the number will be rounded (not truncated) to fit the field.
Before must at least be large enough to hold the integer part of number. Therefore it can never be less than 1, and never less than 2 for negative numbers. The integer field will have no leading zeros, except a single zero digit if the integer part of number is empty.
The parameter expp the size of the field in which the exponent is written. This is the size of the numeric part of the exponent, so the "E" and the sign comes in addition, i.e. the real length if the exponent is two more than expp specifies. If expp is zero, it signalizes that exponential form should not be used. Expp must be a non-negative whole number. If expp is positive, but not large enough to hold the exponent, an error is reported.
Expt is the trigger value that decides when to switch from simple to exponential form. Normally, the default precision (NUMERIC DIGITS) is used, but if expt is set, it will override that. Note that if expt is set to zero, exponential form will always be used. However, if expt tries to force exponential form, simple form will still be used if expp is zero. Negative values for expt will give an error. Exponential form is used if more digits than expt is needed in the integer part, or more than twice expt digits are needed in the fractional part.
Note that the after number will mean different things in exponential and simple form. If after is set to e.g. 3, then in simple form it will force the precision to 0.001, no matter the magnitude of the number. If in exponential form, it will force the number to 4 digits precision.
FORMAT(12.34,3,4) |
' 12.3400' |
FORMAT(12.34,3,,3,0) |
' 1.234E+001' |
FORMAT(12.34,3,1) |
' 12.3400' |
FORMAT(12.34,3,0) |
' 12.3' |
FORMAT(12.34,3,4) |
' 12' |
FORMAT(12.34,,,,0) |
'1.234E+1' |
FORMAT(12.34,,,0) |
'12.34' |
FORMAT(12.34,,,0,0) |
'12.34' |
FREESPACE(address,length) (AREXX)
Returns a block of memory of the given length to the interpreter's internal pool. The address argument must be a 4-byte string obtained by a prior call to GETSPACE(),the internal allocator. It is not always necessary to release internally-allocated memory,since it will be released to the system when the program terminates. However,if a very large block has been allocated,returning it to the pool may avoid memory space problems. The return value is a boolean success flag.
See also GETSPACE()
FREESPACE('00042000'x,32) |
'1' |
FUZZ() (ANSI)
Returns the current number of digits which are ignored when comparing numbers, during operations like = and >. The default value for this is 0. This value is set using the NUMERIC FUZZ statement, for more information see that.
FUZZ() |
'0' /* Maybe */ |
GETENV(environmentvar) (REGINA)
Returns the named UNIX environment variable. If this variable is not defined, a nullstring is returned. It is not possible to use this function to determine whether the variable was unset, or just set to the nullstring.
This function is now obsolete, instead you should use:
VALUE( environmentvar, ,'SYSTEM' )
GETPID() (REGINA)
Returns the process id of the currently running process.
GETPID() |
'234' /* Maybe */ |
GETSPACE(length) (AREXX)
Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the 4-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the Rexx program terminates,so this function
should not be used to allocate memory for use by external programs.
See also FREESPACE()
GETSPACE(32) |
'0003BF40' /* maybe */ |
GETTID() (REGINA)
Returns the thread id of the currently running process.
GETTID() |
'2' /* Maybe */ |
HASH(string) (AREXX)
Returns the hash attribute of a string as a decimal number,and updates the internal hash value of the string.
HASH('1') |
'49' |
IMPORT(address[,length]) (AREXX)
Creates a string by copying data from the specified 4-byte address. If the length parameter is not supplied,the copy terminates when a null byte is found.
See also EXPORT()
Note that the address specified is subject to a machine's endianess.
IMPORT('0004 0000'x,8) |
'The answer' /* maybe */ |
INDEX(haystack,needle[,start]) (CMS)
Returns the character position of the string needle in haystack. If needle is not found, 0 is returned. By default the search starts at the first character of haystack (start is 1). This can be overridden by giving a different start, which must be a positive, whole number. See POS function for an ANSI function that does the same thing.
INDEX('abcdef','cd') |
'3' |
INDEX('abcdef','xd') |
'0' |
INDEX('abcdef','bc',3) |
'0' |
INDEX('abcabc','bc',3) |
'5' |
INDEX('abcabc','bc',6) |
'0' |
INSERT(string1,string2[,position[,length[,padchar]]]) (ANSI)
Returns the result of inserting string1 into a copy of string2. If position is specified, it marks the character in string2 which string1 it to be inserted after. Position must be a non-negative whole number, and it defaults to 0, which means that string2 is put in front of the first character in string1.
If length is specified, string1 is truncated or padded on the right side to make it exactly length characters long before it is inserted. If padding occurs, then padchar is used, or <space> if padchar is undefined.
INSERT('first','SECOND') |
'SECONDfirst' |
INSERT('first','SECOND',3) |
'fiSECONDrst' |
INSERT('first','SECOND',3,10) |
'fiSECOND rst' |
INSERT('first','SECOND',3,10,'*') |
'fiSECOND****rst' |
INSERT('first','SECOND',3,4) |
'fiSECOrst' |
INSERT('first','SECOND',8) |
'first SECOND' |
JUSTIFY(string,length[,pad]) (CMS)
Formats blank-delimited words in string, by adding pad characters between words to justify to both margins. That is, to width length (length must be non-negative). The default pad character is a blank.
string is first normalized as though SPACE(string) had been executed (that is, multiple blanks are converted to single blanks, and leading and trailing blanks are removed). If length is less than the width of the normalized string, the string is then truncated on the right and any trailing blank is removed. Extra pad characters are then added evenly from the left to right to provide the required length, and the blanks between words are replaced with the pad character.
JUSTIFY('The blue sky',14) |
'The blue sky' |
JUSTIFY('The blue sky',8) |
'The blue' |
JUSTIFY('The blue sky',9) |
'The blue' |
JUSTIFY('The blue sky',9,'+') |
'The++blue' |
LASTPOS(needle,haystack[,start]) (ANSI)
Searches the string haystack for the string needle, and returns the position in haystack of the first character in the substring that matched needle. The search is started from the right side, so if needle occurs several times, the last occurrence is reported.
If start is specified, the search starts at character number start in haystack. Note that the standard only states that the search starts at the startth character. It is not stated whether a match can partly be to the right of the start position, so some implementations may differ on that point.
LASTPOS('be',To be or not to be') |
17 |
LASTPOS('to',to be or not to be',10) |
3 |
LASTPOS('is',to be or not to be') |
0 |
LASTPOS('to',to be or not to be',0) |
0 |
LEFT(string,length[,padchar]) (ANSI)
Returns the length leftmost characters in string. If length (which must be a non-negative whole number) is greater than the length of string, the result is padded on the right with <space> (or padchar if that is specified) to make it the correct length.
LEFT('Foo bar',5) |
'Foo b' |
LEFT('Foo bar',3) |
'Foo' |
LEFT('Foo bar',10) |
'Foo bar ' |
LEFT('Foo bar',10,'*') |
'Foo bar***' |
LENGTH(string) (ANSI)
Returns the number of characters in string.
LENGTH('') |
'0' |
LENGTH('Foo') |
'3' |
LENGTH('Foo bar') |
'7' |
LENGTH(' foo bar ') |
'10' |
LINEIN([streamid][,[line][,count]]) (ANSI)
Returns a line read from a file. When only streamid is specified, the reading starts at the current read position and continues to the first End-Of-Line (EOL) mark. Afterwards, the current read position is set to the character after the EOL mark which terminated the read-operation. If the operating system uses special characters for EOL marks, these are not returned by as a part of the string read..
The default value for streamid is default input stream. The format and range of the string streamid are implementation dependent.
The line parameter (which must be a positive whole number) might be specified to set the current position in the file to the beginning of line number line before the read operation starts. If line is unspecified, the current position will not be changed before the read operation. Note that line is only valid for persistent steams. For transient streams, an error is reported if line is specified. The first line in the stream is numbered 1.
Count specifies the number of lines to read. However, it can only take the values 0 and 1. When it is 1 (which is the default), it will read one line. When it is 0 it will not read any lines, and a nullstring is returned. This has the effect of setting the current read position of the file if line was specified.
What happens when the functions finds a End-Of-File (EOF) condition is to some extent implementation dependent. The implementation may interpret the EOF as an implicit End-Of-Line (EOL) mark is none such was explicitly present. The implementation may also choose to raise the NOTREADY condition flag (this condition is new from REXX language level 4.00).
Whether or not stream must be explicitly opened before a read operation can be performed, is implementation dependent. In many implementations, a read or write operation will implicitly open the stream if not already open.
Assuming that the file /tmp/file contains the three lines: "First line", Second line" and "Third line":
LINEIN('/tmp/file',1) |
'First line' |
LINEIN('/tmp/file') |
'Second line' |
LINEIN('/tmp/file',1,0) |
'' /* But sets read position */ |
LINEIN('/tmp/file') |
'First line' |
LINEIN() |
'Hi, there!' /* maybe */ |
LINEOUT([streamid][,[string][,line]]) (ANSI)
Returns the number of lines remaining after having positioned the stream streamid to the start of line line and written out string as a line of text. If streamid is omitted, the default output stream is used. If line (which must be a positive whole number) is omitted, the stream will not be repositioned before the write. If string is omitted, nothing is written to the stream. If string is specified, a system-specific action is taken after it has been written to stream, to mark a new line.
The format and contents of the first parameter will depend upon the implementation and how it names streams. Consult implementation-specific documentation for more information.
If string is specified, but not line, the effect is to write string to the stream, starting at the current write position. If line is specified, but not string, the effect is only to position the stream at the new position. Note that the line parameter is only legal if the stream is persistent; you can not position the current write position for transient streams.
If neither line nor string is specified, the standard requires that the current write position is set the end of the stream, and implementation specific side-effects may occur. In practice, this means that an implementation can use this situation to do things like closing the stream, or flushing the output. Consult the implementation specific documentation for more information.
Also note that the return value of this functions may be of little or no value, If just a half line is written, 1 may still be returned, and there are no way of finding out how much (if any) of string was written. If string is not specified, the return value will always be 0, even if LINEOUT() was not able to correctly position the stream.
If it is impossible to correctly write string to the stream, the NOTREADY flag will be raised. It is not defined whether or not the NOTREADY flag is raised when LINEOUT() is used for positioning, and this is not possible.
Note that if you write string to a line in the middle of the stream (i.e. line is less than the total number of lines in the stream), then the behavior is system and implementation specific. Some systems will truncate the stream after the newly written line, other will only truncate if the newly written line has a different length than the old line which it replaced, and yet other systems will overwrite and never truncate.
In general, consult your system and implementation specific documentation for more information about this function. You can safely assume very little about how it behaves.
LINEOUT(,'First line') |
'1' |
LINEOUT('/tmp/file','Second line',2) |
'1' |
LINEOUT('/tmp/file','Third line') |
'1' |
LINEOUT('/tmp/file','Fourth line',4) |
'0' |
LINES([streamid][,option]) (ANSI)
Returns 1 if there is at least one complete line remaining in the named file stream or 0 if no complete lines remain in the file. A complete line is not really as complete as the name might indicate; a complete line is zero or more characters, followed by an End-Of-Line (EOL) marker. So, if you have read half a line already, you still have a "complete" line left. Note that it is not defined what to do with a half-finished line at the end of a file. Some interpreters might interpret the End-Of-File as an implicit EOL mark too, while others might not.
The format and contents of the stream streamid is system and implementation dependent. If omitted, the default input stream will be used.
The ANSI Standard has extended this function from TRL2. It allows an option:
[C]
(Count) Returns the actual number of complete lines remaining in the stream, irrespective of how expensive this operation is.
[N]
(Normal) Returns 1 if there is at least one complete line remaining in the file or 0 if no lines remain. This is the default. To maintain backwards compatibility with older releases of Regina, the OPTION; NOFAST_LINES_BIF_DEFAULT can be used to make the default option behave as though LINES(streamid,'C') was specified.
LINES will only return 0 or 1 for all transient streams, as the interpreter can not reposition in these files, and can therefore not count the number of remaining lines.
As a result, defensive programming indicates that you can safely only assume that this function will return either 0 or a non-zero result. If you want to use the non-zero result to more than just an indicator on whether more lines are available, you must check that it is larger than one. If so, you can safely assume that it hold the number of available lines left.
As with all the functions operating on streams, you can safely assume very little about this function, so consult the system and implementation specific documentation.
LINES() |
'1' /* Maybe */ |
LINES() |
'0' /* Maybe */ |
LINES('/tmp/file','C') |
'2' /* Maybe */ |
LINES('/tmp/file') |
'1' /* Maybe */ |
MAKEBUF() (CMS)
Creates a new buffer on the stack, at the current top of the stack. Each new buffer will be assigned a number; the first buffer being assigned the number 1. A new buffer will be assigned a number which is one higher than the currently highest number of any buffer on the stack. In practice, this means that the buffers are numbered, with the bottom-most having the number 1 and the topmost having a number which value is identical to the number of buffers currently in the stack.
The value returned from this function is the number assigned to the newly created buffer. The assigned number will be one more than the number of buffers already in the stack, so the numbers will be "recycled". Thus, the assigned numbers will not necessarily be in sequence.
MAKEBUF() |
1 /* if no buffers existed */ |
MAKEBUF() |
6 /* if 5 buffers existed */ |
MAX(number1[,number2]...) (ANSI)
Takes any positive number of parameters, and will return the parameter that had the highest numerical value. The parameters may be any valid REXX number. The number that is returned, is normalized according to the current settings of NUMERIC, so the result need not be strictly equal to any of the parameters.
Actually, the standard says that the value returned is the first number in the parameter list which is equal to the result of adding a positive number or zero to any of the other parameters. Note that this definition opens for "strange" results if you are brave enough to play around with the settings of NUMERIC FUZZ.
MAX(1,2,3,5,4) |
'5' |
MAX(6) |
'6' |
MAX(-4,.001E3,4) |
'4' |
MAX(1,2,05.0,4) |
'5.0' |
MIN(number[,number]...) (ANSI)
Like MAX(), except that the lowest numerical value is returned. For more information, see MAX().
MAX(5,4,3,1,2) |
'1' |
MAX(6) |
'6' |
MAX(-4,.001E3,4) |
'-4' |
MAX(1,2,05.0E-1,4) |
'0.50' |
OPEN(file,filename,['Append'|'Read'|'Write']) (AREXX)
Opens a file for the specified operation. The file argument defines the logical name by which the file will be referenced. The filename is the external name of the file, and may include any portions of a full file path.
The function returns a boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneusly, and all open files are closed automatically when the program exits.
See also CLOSE(), READ(), WRITE()
OPEN('myfile','c:\temp\aa.txt','R') |
'1' |
OPEN('infile','/tmp/fred.txt') |
'1' |
OVERLAY(string1,string2[,[start][,[length][,padchar]]]) (ANSI)
Returns a copy of string2, totally or partially overwritten by string1. If these are the only arguments, the overwriting starts at the first character in string2.
If start is specified, the first character in string1 overwrites character number start in string2. Start must be a positive whole number, and defaults to 1, i.e. the first character of string1. If the start position is to the right of the end of string2, then string2 is padded at the right hand end to make it start-1 characters long, before string1 is added.
If length is specified, then string2 will be stripped or padded at the right hand end to match the specified length. For padding (of both strings) padchar will be used, or <space> if padchar is unspecified. Length must be non-negative, and defaults to the length of string1.
OVERLAY('NEW','old-value') |
'NEW-value' |
OVERLAY('NEW','old-value',4) |
'oldNEWlue' |
OVERLAY('NEW','old-value',4,5) |
'oldNEW e' |
OVERLAY('NEW','old-value',4,5,'*') |
'oldNEW**e' |
OVERLAY('NEW','old-value',4,2) |
'oldNEalue' |
OVERLAY('NEW','old-value',9) |
'old-valuNEW' |
OVERLAY('NEW','old-value',12) |
'old-value NEW' |
OVERLAY('NEW','old-value',12,,'*') |
'old-value**NEW' |
OVERLAY('NEW','old-value',12,5,'*') |
'old-value**NEW**' |
POPEN(command[,stem.]) (REGINA)
Runs the operating system command. If the optional stem. is supplied all output from the command is placed in the specified stem variable as a REXX array. Note that only the command's stdout can be captured.
This command is now deprecated. ADDRESS WITH can do the same thing, and can also capture the command's stderr.
POPEN('ls -l', 'lists.') |
/* LISTS. stem has list */ |
ADDRESS SYSTEM 'ls -l' WITH OUTPUT STEM LISTS. |
/* same as above */ |
POS(needle,haystack[,start]) (ANSI)
Seeks for an occurrence of the string needle in the string haystack. If needle is not found, then 0 is returned. Else, the position in haystack of the first character in the part that matched is returned, which will be a positive whole number. If start (which must be a positive whole number) is specified, the search for needle will start at position start in haystack.
POS('be','to be or not to be') |
4 |
POS('to','to be or not to be',10) |
14 |
POS('is','to be or not to be') |
0 |
POS('to','to be or not to be',18) |
0 |
QUALIFY([streamid]) (ANSI)
Returns a name for the streamid. The two names are currently associated with the same resource and the result of this function may be more persistently associated with that resource.
QUALIFY('../mypath/fred.the') |
'/home/mark/mypath/fred.the' |
QUEUED() (ANSI)
Returns the number of lines currently in the external data queue (the "stack"). Note that the stack is a concept external to REXX, this function may depend on the implementation and system Consult the system specific documentation for more information.
QUEUED() |
'0' /* Maybe */ |
QUEUED() |
'42' /* Maybe */ |
RANDOM(max) (ANSI)
RANDOM([min][,[max][,seed]]) (ANSI)
Returns a pseudo-random whole number. If called with only the first parameter, the first format will be used, and the number returned will be in the range 0 to the value of the first parameter, inclusive. Then the parameter max must be a non-negative whole number, not greater than 100000.
If called with more than one parameter, or with one parameter, which is not the first, the second format will be used. Then min and max must be positive whole numbers, and max can not be less than min, and the difference max-min can not be more than 100000. If one or both of them is unspecified, the default for min is 0, and the default for max is 999.
If seed is specified; (it must be a positive whole number) you may control which numbers the pseudo-random algorithm will generate. If you do not specify it, it will be set to some "random" value at the first call to RANDOM() (typically a function of the time). When specifying seed, it will effect the result of the current call to RANDOM().
The standard does not require that a specific method is to be used for generating the pseudo-random numbers, so the reproducibility can only be guaranteed as long as you use the same implementation on the same machine, using the same operating system. If any of these change, a given seed may produce a different sequence of pseudo-random numbers.
Note that depending on the implementation, some numbers might have a slightly increased chance of turning up than other. If the REXX implementation uses a 32 bit pseudo-random generator provided by the operating system and returns the remainder after integer dividing it by the difference of min and max, low numbers are favored if the 2^32 is not a multiple of that difference. Supposing that the call is RANDOM(100000) and the pseudo-random generator generates any 32 bit number with equal chance, the change of getting a number in the range 0-67296 is about 0.000010000076, while the changes of getting a number in the range 67297-100000 is about 0.000009999843.
A much worse problem with pseudo-random numbers are that they sometimes do not tend to be random at all. Under one operating system (name withheld to protect the guilty), the system's pseudo-random routine returned numbers where the last binary digit alternated between 0 and 1. On that machine, RANDOM(1) would return the series 0, 1, 0, 1, 0, 1, 0, 1 etc., which is hardly random at all. You should therefore never trust the pseudo-random routine to give you random numbers.
Note that due to the special syntax, there is a big difference between using RANDOM(10) and RANDOM(10,). The former will give a pseudo-random number in the range 0-10, while the latter will give a pseudo-random number in the range 10-999.
Also note that it is not clear whether the standard allows min to be equal to max, so to program compatible, make sure that max is always larger than min.
RANDOM() |
'123' /*Between 0 and 999 */ |
RANDOM(10) |
'5' /*Between 0 and 10 */ |
RANDOM(,10) |
'3' /*Between 0 and 10 */ |
RANDOM(20,30) |
'27' /*Between 20 and 30 */ |
RANDOM(,,12345) |
'765' /*Between 0 and 999, and sets seed */ |
RANDU([seed]) (AREXX)
Returns a uniformly-distributed pseudorandom number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU()can be used to generate pseudorandom numbers on an arbitrary interval.
The optional seed argument is used to initialize the internal state of the random number generator.
See also RANDOM()
RANDU() |
'0.371902021' |
RANDU(45) |
'0.873' /*numeric digits 3*/ |
READCH(file,length) (AREXX)
Reads the specified number of characters from the given logical file and retruns them. The length of the returned string is the actual number of characters read,and may be less than the requested length if, for example, the end-of-file was reached.
See also READLN()
READCH('infile',10) |
'a string o' |
READLN(file) (AREXX)
Reads characters from the given logical file into a string until a "newline" character is found. The returned string does not include the "newline".
See also READCH()
READLN('infile') |
'a string of chars' |
REVERSE(string) (ANSI)
Returns a string of the same length as string, but having the order of the characters reversed.
REVERSE('FooBar') |
'raBooF' |
REVERSE(' Foo Bar') |
'raB ooF ' |
REVERSE('3.14159') |
'95141.3' |
RIGHT(string,length[,padchar]) (ANSI)
Returns the length rightmost characters in string. If length (which must be a non-negative whole number) is greater than the length of string the result is padded on the left with the necessary number of padchars to make it as long as length specifies. Padchar defaults to <space>.
RIGHT('Foo bar',5) |
'o bar' |
RIGHT('Foo bar',3) |
'bar' |
RIGHT('Foo bar',10) |
' Foo bar' |
RIGHT('Foo bar',10,'*') |
''***Foo bar' |
RXFUNCADD(externalname,library,internalname) (SAA)
Registers the internalname in library as an external function callable from with the current program by referencing externalname. library is a REXX external functon package in the format of shared library or dynamic link library (DLL). library and internalname are case-sensitive. library is the base name of the shared library or dynamic link library. On platforms that support DLLs, the full name of the external function package is library.dll. On Unix environments, the full name of the shared library is liblibrary.a (AIX), liblibrary.sl (HPUX) or liblibrary.so (most other Unixes). External function packages are searched for in the location where shared libraries or DLLs are normally foundby the operating system. DLLs are normally located in directories specified in the PATH or LIBPATH environment variables. Shared libraries are normally searched for in LD_LIBRARY_PATH or LIBPATH environment variables.
This function returns 0 if the function is registered successfully.
RXFUNCADD('SQLLoadFuncs','rexxsql','SQLLoadFuncs') |
0 |
RXFUNCDROP(externalname) (SAA)
Removes the specified externalname from the list of external functions available to be called. This function returns 0 if the function was successfully dropped.
RXFUNCDROP('SQLLoadFuncs') |
0 |
RXFUNCERRMSG() (REGINA)
Returns the error message associated with the last call to RXFUNCADD. This function is generally used immediately after a failed call to RXFUNCADD to determine why it failed.
RXFUNCERRMSG() |
'rexxsql.dll not found' /* Maybe */ |
RXFUNCQUERY(externalname) (SAA)
Returns 0 if the externalname is already registered, or 1 if the externalname is not registered.
RXFUNCQUEURY('SQLLoadFuncs') |
1 /* Maybe */ |
RXQUEUE(command[,queue]) (OS/2)
This function interfaces to the Regina internal or external queue mechanism. If OPTIONS INTERNAL_QUEUES is set, all operations on queues are internal to the interpreter.
[C]
(Create) Request the interpreter or rxstack to create a new named queue. If the queue name already exists, a new unique queue name is generated. The name of the queue that was created (either the specified queue or the system-generated queue) is returned. All queue names are case-insensitive; ie the queue name FRED and fred are the same.
[D]
(Delete) Deletes the specified queue. The default queue; SESSION becomes the current queue.
[G]
(Get) Returns the current queue name.
[S]
(Set) Sets the current queue name to that queue specified. The previously current queue is returned. It is valid to set a queue name to a queue that has not been created.
[T]
(Timeout) Sets the timeout period (in milliseconds) to wait for something to appear on the specified queue. By default, when a line is read from a queue will a PULL command, it either returns immediately with the top line in the stack, or it will wait for a line to be entered by the user via the process' stdin. If 0 is specified, Regina will wait forever for a line to be ready on the stack.
RXQUEUE('Create') |
'S0738280' |
RXQUEUE('Create','fred') |
'FRED' |
RXQUEUE('Create', 'fred') |
'S88381' |
RXQUEUE('Get') |
'S88381' |
RXQUEUE('Delete','fred') |
'SESSION' |
RXQUEUE('Set','fred') |
'SESSION' |
RXQUEUE('Timeout','fred',10) |
'' |
SEEK(file,offset,['Begin'|'Current'|'End') (AREXX)
Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file.
SEEK('infile',10,'B') |
'10' |
SEEK('infile',0,'E') |
'356' /* file length */ |
SHOW(option,[name],[pad]) (AREXX)
Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are Clip, Files, Libraries, and Ports, which are described below.
Clip. Examines the names in the Clip List.
Files. Examines the names of the currently open logical file names.
Libraries. Examines the names in the Library List,which are either function libraries or function hosts.
Ports. Examine the names in the system Ports List.
If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character,if one was supplied. If the name argument is given, the returned boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.
Only the Files option is valid on all platforms. All other values for option are only applicable to the Amiga and AROS ports.
SIGN(number) (ANSI)
Returns either -1, 0 or 1, depending on whether number is negative, zero, or positive, respectively. Number must be a valid REXX number, and are normalized according to the current settings of NUMERIC before comparison.
SIGN(-12) |
'-1' |
SIGN(42) |
'1' |
SIGN(-0.00000012) |
'-1' |
SIGN(0.000) |
'0' |
SIGN(-0.0) |
'0' |
SLEEP(seconds) (CMS)
Pauses for the supplied number of seconds.
SLEEP(5) |
/* sleeps for 5 seconds */ |
SOURCELINE([lineno]) (ANSI)
If lineno (which must be a positive whole number) is specified, this function will return a string containing a copy of the REXX script source code on that line. If lineno is greater than the number of lines in the REXX script source code, an error is reported.
If lineno is unspecified, the number of lines in the REXX script source code is returned.
Note that from REXX language level 3.50 to 4.00, the requirements of this function were relaxed to simplify execution when the source code is not available (compiled or pre-parsed REXX). An implementation might make two simplifications: to return 0 if called without a parameter. If so, any call to SOURCELINE() with a parameter will generate an error. The other simplification is to return a nullstring for any call to SOURCELINE() with a legal parameter.
Note that the code executed by the INTERPRET clause can not be retrieved by SOURCELINE().
SOURCELINE() |
'42' /*Maybe */ |
SOURCELINE(1) |
'/* This Rexx script will ... */' |
SOURCELINE(23) |
'var = 12' /*Maybe */' |
SPACE(string[,[length][,padchar]]) (ANSI)
With only one parameter string is returned, stripped of any trailing or leading blanks, and any consecutive blanks inside string translated to a single <space> character (or padchar if specified).
Length must be a non-negative whole number. If specified, consecutive blanks within string is replaced by exactly length instances of <space> (or padchar if specified). However, padchar will only be used in the output string, in the input string, blanks will still be the "magic" characters. As a consequence, if there exist any padchars in string, they will remain untouched and will not affect the spacing.
SPACE(' Foo bar ') |
'Foo bar' |
SPACE(' Foo bar ',2) |
'Foo bar' |
SPACE(' Foo bar ',,'*') |
'Foo*bar' |
SPACE('Foo bar',3, '-') |
'Foo--bar' |
SPACE('Foo bar',,'o') |
'Fooobar' |
STATE(streamid) (CMS)
Returns 0 if the streamid exists, or 1 if it deos not. Use STREAM(streamid, 'C', 'QUERY EXISTS') for portability.
STORAGE([address],[string],[length],[pad]) (AREXX)
Calling STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a 4-byte string,and the function copies data from the optional string into the indicated memory area. The length parameter specifies the maximum number of bytes to be copied,and defaults to the length of the string. If the specified length is longer than the string,the remaining area is filled with the pad character or nulls('00'x.)
The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents.
Caution is advised in using this function. Any area of memory can be overwritten,possibly causing a system crash.
STORAGE() |
'248400' |
STORAGE('0004 0000'x,'The answer') |
'question' /* maybe */ |
STREAM(streamid[,option[,command]]) (ANSI)
This function was added to REXX in language level 4.00. It provides a general mechanism for doing operations on streams. However, very little is specified about how the internal of this function should work, so you should consult the implementation specific documentation for more information.
The streamid identifies a stream. The actual contents and format of this string is implementation dependent.
The option selects one of several operations which STREAM() is to perform. The possible operations are:
[C]
(Command) If this option is selected, a third parameter must be present, command, which is the command to be performed on the stream. The contents of command is implementation dependent. For Regina, the valid commands follow. Commands consist of one or more space separated words.
[D]
(Description) Returns a description of the state of streamid. The return value is implementation dependent.
[S]
(Status) Returns a state which describes the state of streamid. The standard requires that it is one of the following: ERROR, NOTREADY, READY and UNKNOWN. The meaning of these are described in the chapter; Stream Input and Output.
Note that the options Description and Status really have the same function, but that Status in general is implementation independent, while Description is implementation dependent.
The command specifies the command to be performed on streamid. The possible operations are:
[READ]
Open for read access. The file pointer will be positioned at the start of the file, and only read operations are allowed. This command is Regina-specific; use OPEN READ in its place.
[WRITE]
Open for write access and position the current write position at the end of the file. An error is returned if it was not possible to get appropriate access. This command is Regina-specific; use OPEN WRITE in its place.
[APPEND]
Open for append access and position the current write position at the end of the file. An error is returned if it was not possible to get appropriate access. This command is Regina-specific; use OPEN WRITE APPEND in its place.
[UPDATE]
Open for append access and position the current write position at the end of the file. An error is returned if it was not possible to get appropriate access. This command is Regina-specific; use OPEN BOTH in its place.
[CREATE]
Open for write access and position the current write position at the start of the file. An error is returned if it was not possible to get appropriate access. This command is Regina-specific; use OPEN WRITE REPLACE in its place.
[CLOSE]
Close the stream, flushing any pending writes. An error is returned if it was not possible to get appropriate access.
[FLUSH]
Flush any pending write to the stream. An error is returned if it was not possible to get appropriate access.
[STATUS]
Returns status information about the stream in human readable form that Regina stores about the stream.
[FSTAT]
Returns status information from the operating system about the stream. This consists of at least 8 words:
Device Number Under DOS, Win32, OS/2, this represents the disk number, with 0 being Drive A.
Inode Number Under DOS, Win32, OS/2, this is zero.
Permissions User/Group/Other permissions mask. Consists of 3 octal numbers with 4 representing read, 2 representing write, and 1 representing execute. Therefore a value of 750 is read/write/execute for user, read/execute for group, and no permissions for other.
Number Links Under DOS, Win32, OS/2, this will always be 1.
User Name The owner of the stream. Under DOS, Win32, OS/2, this will always be “USER”.
Group Name The group owener of the stream. Under DOS, Win32, OS/2, this will always be “GROUP”.
Size Size of stream in bytes.
Stream Type One or more of the following:
RegularFile a normal file.
Directory a directory.
BlockSpecial a block special file.
FIFO usually a pipe.
SymbolicLink a symbolic link
Socket a socket
SpecialName a named special file.
If the stream is a symbolic link, the the details returned are details about the link, not the file the link points to. CharacterSpecial a character special file.
[RESET]
Resets the stream after an error. Only streams that are resettable can be reset.
[READABLE]
Returns 1 if the stream is readable by the user or 0 otherwise.
[WRITABLE]
Returns 1 if the stream is writeable by the user or 0 otherwise.
[EXECUTABLE]
Returns 1 if the stream is executable by the user or 0 otherwise.
[QUERY]
Returns information about the named stream. If the named stream does not exists, then the empty string is returned. This command is further broken down into the following sub-commands:
DATETIME returns the date and time of last modification of the stream in Rexx US Date format; MM-DD-YY HH:MM:SS.
EXISTS returns the fully-qualified file name of the specified stream.
HANDLE returns the internal file handle of the stream. This will only return a valid value if the stream was opened explicitly or implicitly by Regina.
SEEK READ CHAR returns the current read position of the open stream expressed in characters.
SEEK READ LINE returns the current read position of the open stream expressed in lines.
SEEK WRITE CHAR returns the current write position of the open stream expressed in characters.
SEEK WRITE LINE returns the current write position of the open stream expressed in lines.
SEEK SYS returns the current read position of the open stream as the operating reports it. This is expressed in characters.
SIZE returns the size, expressed in characters, of the persistent stream.
STREAMTYPE returns the type of the stream. One of TRANSIENT, PERSISTENT or UNKNOWN is returned.
TIMESTAMP returns the date and time of last modifcation of the stream. The format of the string returned is YYYY-MM-DD HH:MM:SS.
You can use POSITION in place of SEEK in the above options.
[OPEN]
Opens the stream in the optional mode specified. If no optional mode is specified, the default is OPEN BOTH.
READ The file pointer will be positioned at the start of the file, and only read operations are allowed.
WRITE Open for write access and position the current write pointer at the end of the file. On platforms where it is not possible to open a file for write without also allowing reads, the read pointer will be positioned at the start of the file. An error is returned if it was not possible to get appropriate access.
BOTH Open for read and write access. Position the current read pointer at the start of the file, and the current write pointer at the end of the file. An error is returned if it was not possible to get appropriate access.
WRITE APPEND Open for write access and position the write pointer at the end of the file. On platforms where it is not possible to open a file for write without also allowing reads, the read pointer will be positioned at the start of the file.
WRITE REPLACE Open for write access and position the current write position at the start of the file. On platforms where it is not possible to open a file for write without also allowing reads, the read pointer will be positioned at the start of the file. This operation will clear the contents of the file. An error is returned if it was not possible to get appropriate access.
BOTH APPEND Open for read and write access. Position the current read position at the start of the file, and the current write position at the end of the file. An error is returned if it was not possible to get appropriate access.
BOTH REPLACE Open for read and write access. Position both the current read and write pointers at the start of the file. An error is returned if it was not possible to get appropriate access.
[SEEK position READ|WRITE [CHAR|LINE]]
Positions the file's read or write pointer in the file to the specified position. SEEK is a synonym for POSITION.
position A position can be of the following forms. [relative]offset.
relative can be one of:
= The file pointer is moved to he specifiled offset relative to the start of the file. This is the default.
< The file pointer is moved to he specifiled offset relative to the send of the file.
- The file pointer is moved backwards relative to the current position.
+ The file pointer is moved forwards relative to the current position.
offset is a positive whole number.
READ The read file pointer will be positioned.
WRITE The write file pointer is positioned.
CHAR The offset specified in position above is in terms of characters.
LINE The offset specified in position above is in terms of lines.
Assume a file; '/home/mark/myfile' last changed March 30th 2002 at 15:07:56, with 100 lines, each line 10 characters long, and the following command executed in sequence.
STREAM('myfile','C','QUERY EXISTS') |
'/home/mark/myfile' |
STREAM('myfile','C','QUERY SIZE') |
1100 |
STREAM('myfile','C','QUERY TIMESTAMP') |
2002-03-30 15:07:56 |
STREAM('myfile','C','QUERY DATETIME') |
03-30-02 15:07:56 |
STREAM('myfile','D') |
|
STREAM('myfile','S') |
UNKNOWN |
STREAM('myfile','C','QUERY SEEK READ') |
|
|
|
STREAM('myfile','C','OPEN READ') |
READY: |
STREAM('myfile','D') |
|
STREAM('myfile','S') |
READY |
STREAM('myfile','C','QUERY SEEK READ') |
1 |
STREAM('myfile','C','CLOSE') |
UNKNOWN |
STREAM('myfile','C','STATUS') |
|
STREAM('myfile','C','FSTAT') |
773 35006 064 1 mark |
STREAM('myfile','C','READABLE') |
1 |
STREAM('myfile','C','WRITABLE') |
1 |
STREAM('myfile','C','EXECUTABLE') |
0 |
STREAM('myfile','C','??') |
|
STRIP(string[,[option][,char]]) (ANSI)
Returns string after possibly stripping it of any number of leading and/or trailing characters. The default action is to strip off both leading and trailing blanks. If char (which must be a string containing exactly one character) is specified, that character will be stripped off instead of blanks. Inter-word blanks (or chars if defined, that are not leading of trailing) are untouched.
If option is specified, it will define what to strip. The possible values for option are:
[L]
(Leading) Only strip off leading blanks, or chars if specified.
[T]
(Trailing) Only strip off trailing blanks, or chars if specified.
[B]
(Both) Combine the effect of L and T, that is, strip off both leading and trailing blanks, or chars if it is specified. This is the default action.
STRIP(' Foo bar ') |
'Foo bar' |
STRIP(' Foo bar ','L') |
'Foo bar ' |
STRIP(' Foo bar ','t') |
' Foo bar' |
STRIP(' Foo bar ','Both') |
'Foo bar' |
STRIP('0.1234500',,'0') |
'.12345' |
STRIP('0.1234500 ',,'0') |
'.1234500' |
SUBSTR(string,start[,[length][,padchar]]) (ANSI)
Returns the substring of string that starts at start, and has the length length. Length defaults to the rest of the string. Start must be a positive whole, while length can be any non-negative whole number.
It is not an error for start to be larger than the length of string. If length is specified and the sum of length and start minus 1 is greater that the length of string, then the result will be padded with padchars to the specified length. The default value for padchar is the <space> character.
SUBSTR('Foo bar',3) |
'o bar' |
SUBSTR('Foo bar',3,3) |
'o b' |
SUBSTR('Foo bar',4,6) |
' bar ' |
SUBSTR('Foo bar',4,6,'*') |
' bar**' |
SUBSTR('Foo bar',9,4,'*') |
'****' |
SUBWORD(string,start[,length]) (ANSI)
Returns the part of string that starts at blank delimited word start (which must be a positive whole number). If length (which must be a non-negative whole number) is specified, that number of words are returned. The default value for length is the rest of the string.
It is not an error to specify length to refer to more words than string contains, or for start and length together to specify more words than string holds. The result string will be stripped of any leading and trailing blanks, but inter-word blanks will be preserved as is.
SUBWORD('To be or not to be',4) |
'not to be' |
SUBWORD('To be or not to be',4,2) |
'not to' |
SUBWORD('To be or not to be',4,5) |
'not to be' |
SUBWORD('To be or not to be',1,3) |
'To be or' |
SYMBOL(name) (ANSI)
Checks if the string name is a valid symbol (a positive number or a possible variable name), and returns a three letter string indicating the result of that check. If name is a symbol, and names a currently set variable, VAR is returned, if name is a legal symbol name, but has not a been given a value (or is a constant symbol, which can not be used as a variable name), LIT is returned to signify that it is a literal. Else, if name is not a legal symbol name the string BAD is returned.
Watch out for the effect of "double expansion". Name is interpreted as an expression evaluating naming the symbol to be checked, so you might have to quote the parameter.
SYMBOL('Foobar') |
'VAR' /* Maybe */ |
SYMBOL('Foo bar') |
'BAD' |
SYMBOL('Foo.Foo bar') |
'VAR' /* Maybe */ |
SYMBOL('3.14') |
'LIT' |
SYMBOL('.Foo->bar') |
'BAD' |
TIME([option_out [,time [option_in]]]) (ANSI)
Returns a string containing information about the time. To get the time in a particular format, an option_out can be specified. The default option_out is Normal. The meaning of the possible options are:
[C]
(Civil) Returns the time in civil format. The return value might be "hh:mmXX", where XX are either am or pm. The hh part will be stripped of any leading zeros, and will be in the range 1-12 inclusive.
[E]
(Elapsed) Returns the time elapsed in seconds since the internal stopwatch was started. The result will not have any leading zeros or blanks. The output will be a floating point number with six digits after the decimal point.
[H]
(Hours) Returns the number of complete hours that have passed since last midnight in the form "hh". The output will have no leading zeros, and will be in the range 0-23.
[L]
(Long) Returns the exact time, down to the microsecond. This is called the long format. The output might be "hh:mm:ss.mmmmmm". Be aware that most computers do not have a clock of that accuracy, so the actual granularity you can expect, will be about a few milliseconds. The hh, mm and ss parts will be identical to what is returned by the options H, M and S respectively, except that each part will have leading zeros as indicated by the format.
[M]
(Minutes) Returns the number of complete minutes since midnight, in a format having no leading zeros, and will be in the range 0-59.
[N]
(Normal) The output format is "hh:mm:ss", and is padded with zeros if needed. The hh, mm and ss will contain the hours, minutes and seconds, respectively. Each part will be padded with leading zeros to make it double-digit.
[R]
(Reset) Returns the value of the internal stopwatch just like the E option, and using the same format. In addition, it will reset the stopwatch to zero after its contents has been read.
[S]
(Seconds) Returns the number of complete seconds since midnight, in a format having no leading spaces, and will be in the range 0-59.
[T]
(time_t) Returns the current date/time in UNIX time_t format. time_t is the number of seconds since January 1st 1970.
Note that the time is never rounded, only truncated. As shown in the examples below, the seconds do not get rounded upwards, even though the decimal part implies that they are closer to 59 than to 58. The same applies for the minutes, which are closer to 33 than to 32, but is truncated to 32.
None of the formats will have leading or trailing spaces.
Assuming that the time is exactly 14:32:58.987654 on March 30th 2002, the following will be true:
TIME('C') |
'2:32pm' |
TIME('E') |
'0.01200' /* Maybe */ |
TIME('H') |
'14' |
TIME('L') |
'14:32:58.987654' |
TIME('M') |
'32' |
TIME('N') |
'14:32:58' |
TIME('R') |
'0.430221' /* Maybe */ |
TIME('S') |
'58' |
If the time option is specified, the function provides for time conversions. The optional option_in specifies the format in which time is supplied. The possible values for option_in are: CHLMNS.
The default value for option_in is N.
TIME('C','11:27:21') |
'11:27am' |
TIME('N','11:27am','C') |
'11:27:00' |
The time conversion capability of the TIME BIF was introduced with the ANSI standard.
TRACE([setting]) (ANSI)
Returns the current value of the trace setting. If the string setting is specified, it will be used as the new setting for tracing, after the old value have be recorded for the return value. Note that the setting is not an option, but may be any of the trace settings that can be specified to the clause TRACE, except that the numeric variant is not allowed with TRACE(). In practice, this can be a word, of which only the first letter counts, optionally preceded by a question mark.
TRACE() |
'C' /* Maybe */ |
TRACE('N') 'C' |
|
TRACE('?') 'N' |
|
TRANSLATE(string[,[tableout][,[tablein][,padchar]]]) (ANSI)
Performs a translation on the characters in string. As a special case, if neither tablein nor tableout is specified, it will translate string from lower case to upper case. Note that this operation may depend on the language chosen, if your interpreter supports national character sets.
Two translation tables might be specified as the strings tablein and tableout. If one or both of the tables are specified, each character in string that exists in tablein is translated to the character in tableout that occupies the same position as the character did in tablein. The tablein defaults to the whole character set (all 256) in numeric sequence, while tableout defaults to an empty set. Characters not in tablein are left unchanged.
If tableout is larger than tablein, the extra entries are ignored. If it is smaller than tablein it is padded with padchar to the correct length. Padchar defaults to <space>.
If a character occurs more than once in tablein, only the first occurrence will matter.
TRANSLATE('FooBar') |
'FOOBAR' |
TRANSLATE('FooBar','ABFORabfor','abforABFOR') |
'fOObAR' |
TRANSLATE('FooBar','abfor') |
'F B ' |
TRANSLATE('FooBar','abfor',,'#') |
'F##B##' |
TRIM(string) (AREXX)
Removes trailing blanks from the string argument. A more portable option is to use the Trailing option of the STRIP BIF.
TRIM(' abc ') |
' abc' |
TRUNC(number[,length]) (ANSI)
Returns number truncated to the number of decimals specified by length. Length defaults to 0, that is return an whole number with no decimal part.
The decimal point will only be present if the is a non-empty decimal part, i.e. length is non-zero. The number will always be returned in simple form, never exponential form, no matter what the current settings of NUMERIC might be. If length specifies more decimals than number has, extra zeros are appended. If length specifies less decimals than number has, the number is truncated. Note that number is never rounded, except for the rounding that might take place during normalization.
TRUNC(12.34) |
'12' |
TRUNC(12.99) |
'12' |
TRUNC(12.34,4) |
'12.3400' |
TRUNC(12.3456,2) |
'12.34' |
UNAME([option]) (REGINA)
Returns details about the current platform. This function is basically a wrapper for the Unix command; uname. Valid values for option are:
[A]
(All) The default. Returns a string with the all following option values. Equivalent to:
UNAME('S') UNAME('N') UNAME('R') UNAME('V') UNAME('M').
[S]
(System) The name of the operating system.
[N]
(Nodename) The name of the machine.
[R]
(Release) The release of the operating system.
[V]
(Version) The version of the operating system.
[M]
(Machine) The machine's hardware type.
Example running Linux Redhat 6.1 on 'boojum', Athalon K7
UNAME('S') |
Linux |
UNAME('N') |
boojum |
UNAME('R') |
2.2.12.-20 |
UNAME('V') |
#1 Mon Sep 27 10:40:35 EDT 1999 |
UNAME('M') |
i686 |
Example running Windows NT 4.0 on 'VM_NT', Intel Pentium
UNAME('S') |
WINNT |
UNAME('N') |
VM_NT |
UNAME('R') |
0 |
UNAME('V') |
4 |
UNAME('M') |
i586 |
UNIXERROR(errorno) (REGINA)
This function returns the string associated with the errno error number that errorno specifies. When some UNIX interface function returns an error, it really is a reference to an error message which can be obtained through UNIXERROR.
This function is just an interface to the strerror() function call in UNIX, and the actual error messages might differ with the operating system.
This function is now obsolete, instead you should use:
ERRORTEXT(100 + errorno) |
|
UPPER(string) (AREXX)
Translates the strip to uppercase. The action of this function is equivalent to that of TRANSLATE(string),but it is slightly faster for short strings.
UPPER('One Fine Day') |
'ONE FINE DAY' |
USERID() (REGINA)
Returns the name of the current user. A meaningful name will only be returned on those platforms that support multiple users, otherwise an empty string is returned.
USERID() |
'mark' /* Maybe */ |
VALUE(symbol[,[value],[pool]]) (ANSI)
This function expects as first parameter string symbol, which names an existing variable. The result returned from the function is the value of that variable. If symbol does not name an existing variable, the default value is returned, and the NOVALUE condition is not raised. If symbol is not a valid symbol name, and this function is used to access an normal REXX variable, an error occurs. Be aware of the "double-expansion" effect, and quote the first parameter if necessary.
If the optional second parameter is specified, the variable will be set to that value, after the old value has been extracted.
The optional parameter pool might be specified to select a particular pool of variables to search for symbol. The contents and format of pool is implementation dependent. The default is to search in the variables at the current procedural level in REXX. Which pools that are available is implementation dependent, but typically one can set variables in application programs or in the operating system.
Note that if VALUE() is used to access variable in pools outside the REXX interpreter, the requirements to format (a valid symbol) will not in general hold. There may be other requirements instead, depending on the implementation and the system. Depending on the validity of the name, the value, or whether the variable can be set or read, the VALUE() function can give error messages when accessing variables in pools other than the normal. Consult the implementation and system specific documentation for more information.
If it is used to access compound variables inside the interpreter the tail part of this function can take any expression, even expression that are not normally legal in REXX scripts source code.
By using this function, it is possible to perform an extra level of interpretation of a variable.
VALUE('FOO') |
'bar' |
VALUE('FOO','new') |
'bar' |
VALUE('FOO') |
'new' |
VALUE('USER','root','SYSTEM') |
'guest' /* If SYSTEM exists */ |
VALUE('USER',,'SYSTEM') |
'root' |
VERIFY(string,ref[,[option][,start]]) (ANSI)
With only the first two parameters, it will return the position of the first character in string that is not also a character in the string ref. If all characters in string are also in ref, it will return 0.
If option is specified, it can be one of:
[N]
(Nomatch) The result will be the position of the first character in string that does exist in ref, or zero if all exist in ref. This is the default option.
[M]
(Match) Reverses the search, and returns the position of the first character in string that exists in ref. If none exists in ref, zero is returned.
If start (which must be a positive whole number) is specified, the search will start at that position in string. The default value for start is 1.
VERIFY('foobar','barfo') |
'2' |
VERIFY('foobar','barfo','M') |
'2' |
VERIFY('foobar','fob','N') |
'5' |
VERIFY('foobar','barf','N',3) |
'3' |
VERIFY('foobar','barf','N',4) |
'0' |
WORD(string,wordno) (ANSI)
Returns the blank delimited word number wordno from the string string. If wordno (which must be a positive whole number) refers to a non-existing word, then a nullstring is returned. The result will be stripped of any blanks.
WORD('To be or not to be',3) |
'or' |
WORD('To be or not to be',4) |
'not' |
WORD('To be or not to be',8) |
'' |
WORDINDEX(string,wordno) (ANSI)
Returns the character position of the first character of blank delimited word number wordno in string, which is interpreted as a string of blank delimited words. If number (which must be a positive whole number) refers to a word that does not exist in string, then 0 is returned.
WORDINDEX('To be or not to be',3) |
'7' |
WORDINDEX('To be or not to be',4) |
'10' |
WORDINDEX('To be or not to be',8) |
'0' |
WORDLENGTH(string,wordno) (ANSI)
Returns the number of characters in blank delimited word number number in string. If number (which must be a positive whole number) refers to an non-existent word, then 0 is returned. Trailing or leading blanks do not count when calculating the length.
WORDLENGTH('To be or not to be',3) |
'2' |
WORDLENGTH('To be or not to be',4) |
'3' |
WORDLENGTH('To be or not to be',0) |
'0' |
WORDPOS(phrase,string[,start]) (ANSI)
Returns the word number in string which indicates at which phrase begins, provided that phrase is a subphrase of string. If not, 0 is returned to indicate that the phrase was not found. A phrase differs from a substring in one significant way; a phrase is a set of words, separated by any number of blanks.
For instance, "is a" is a subphrase of "This is a phrase". Notice the different amount of whitespace between "is" and "a".
If start is specified, it sets the word in string at which the search starts. The default value for start is 1.
WORDPOS('or not','to be or not to be') |
'3' |
WORDPOS('not to','to be or not to be') |
'4' |
WORDPOS('to be','to be or not to be') |
'1' |
WORDPOS('to be','to be or not to be',3) |
'6' |
WORDS(string) (ANSI)
Returns the number of blank delimited words in the string.
WORDS('To be or not to be') |
'6' |
WORDS('Hello world') |
'2' |
WORDS('') |
'0' |
WRITECH(file,string) (AREXX)
Writes the string argument to the given logical file. The returned value is the actual number of characters written.
WRITECH('outfile','Testing') |
'7' |
WRITELN(file,string) (AREXX)
Writes the string argument to the given logical file with a "newline" appended. The returned value is the actual number of characters written, including the“newline” character(s).
WRITELN('outfile','Testing') |
'8' /* Unix */ |
WRITELN('outfile','Testing') |
'9' /* DOS */ |
XRANGE([start][,end]) (ANSI)
Returns a string that consists of all the characters from start through end, inclusive. The default value for character start is '00'x, while the default value for character end is 'ff'x. Without any parameters, the whole character set in "alphabetic" order is returned. Note that the actual representation of the output from XRANGE() depends on the character set used by your computer.
If the value of start is larger than the value of end, the output will wrap around from 'ff'x to '00'x. If start or end is not a string containing exactly one character, an error is reported.
XRANGE('A','J') |
'ABCDEFGHIJ' |
XRANGE('FC'x) |
'FCFDFEFF'x |
XRANGE(,'05'x) |
'000102030405'x |
XRANGE('FD'x,'04'x) |
'FDFEFF0001020304'x |
X2B(hexstring) (ANSI)
Translate hexstring to a binary string. Each hexadecimal digits in hexstring will be translated to four binary digits in the result. There will be no blanks in the result.
X2B('') |
'' |
X2B('466f6f 426172') |
'010001100110111101101111010000100110000101110010' |
X2B('46 6f 6f') |
'010001100110111101101111' |
X2C(hexstring) (ANSI)
Returns the (packed) string representation of hexstring. The hexstring will be converted bytewise, and blanks may optionally be inserted into the hexstring between pairs or hexadecimal digits, to divide the number into groups and improve readability. All groups must have an even number of hexadecimal digits, except the first group. If the first group has an odd number of hexadecimal digits, it is padded with an extra leading zero before conversion.
X2C('') |
'' |
X2C('466f6f 426172') |
'FooBar' |
X2C('46 6f 6f') |
'Foo' |
X2D(hexstring[,length]) (ANSI)
Returns a whole number that is the decimal representation of hexstring. If length is specified, then hexstring is interpreted as a two's complement hexadecimal number consisting of the number rightmost hexadecimal numerals in hexstring. If hexstring is shorter than number, it is padded to the left with <NUL> characters (that is: '00'x).
If length is not specified, hexstring will always be interpreted as an unsigned number. Else, it is interpreted as an signed number, and the leftmost bit in hexstring decides the sign.
X2D('03 24') |
'792' |
X2D('0310') |
'784' |
X2D('ffff') |
'65535' |
X2D('ffff',5) |
'65535' |
X2D('ffff',4) |
'-1' |
X2D('ff80',3) |
'-128' |
X2D('12345',3) |
'837' |
For those built-in functions where the last parameter can be omitted, Regina allows the last comma to be specified, even when the last parameter itself has been omitted.
The error messages are slightly redefined in two ways. Firstly, some of the have a slightly more definite text, and secondly, some new error messages have been defined.
The environments available are described in chapter [not yet written].
Parameter calling
Stream I/O
Conditions
National character sets
Blanks
Stacks have the following extra functionality: DROPBUF(), DESBUF() and MAKEBUF() and BUFTYPE().
Random()
Sourceline
Time
Character sets
ALLOCATED([option])
Returns the amount of dynamic storage allocated, measured in bytes. This is the memory allocated by the malloc() call, and does not concern stack space or static variables.
As parameter it may take an option, which is one of the single characters:
[A]
It will return a string that is the number of bytes of dynamic memory currently allocated by the interpreter.
[C]
Returns a number that is the number of bytes of dynamic memory that is currently in use (i.e. not leaked).
[L]
Returns the number of bytes of dynamic memory that is supposed to have been leaked.
[S]
This is the default value if you do not specify an option. Returns a string that is nicely formatted and contains all the other three options, with labels. The format of this string is:
"Memory: Allocated=XXX, Current=YYY, Leaked=ZZZ".
This function will only be available if the interpreter was compiled with the TRACEMEM preprocessor macro defined.
DUMPTREE()
Prints out the internal parse tree for the REXX program currently being executed. This output is not very interesting unless you have good knowledge of the interpreter's internal structures.
DUMPVARS()
This routine dumps a list of all the variables currently defined. It also gives a lot of information which is rather uninteresting for most users.
LISTLEAKED()
List out all memory that has leaked from the interpreter. As a return value, the total memory that has been listed is returned. There are several option to this function:
[N]
Do not list anything, just calculate the memory.
[A]
List all memory allocations currently in use, not only that which has been marked as leaked.
[L]
Only list the memory that has been marked as leaked. This is the default option.
TRACEBACK()
Prints out a traceback. This is the same routine which is called when the interpreter encounters an error. Nice for debugging, but not really useful for any other purposes.
F$CVSI
F$CVTIME
F$CVUI
F$DIRECTORY
F$ELEMENT
F$EXTRACT
F$FAO
F$FILE_ATTRIBUTES
F$GETDVI
F$GETJPI
F$GETQUI
F$GETSYI
F$IDENTIFIER
F$INTEGER
F$LENGTH
F$LOCATE
F$LOGICAL
F$MESSAGE
F$MODE
F$PARSE
F$PID
F$PRIVILEGE
F$PROCESS
F$SEARCH
F$SETPRV
F$STRING
F$TIME
F$TRNLNM
F$TYPE
F$USER
Table of Contents
REXX Built-in Functions 1
1General Information 1
1.1The Syntax Format 1
1.2Precision and Normalization 2
1.3Standard Parameter Names 2
1.4Error Messages 3
1.5Possible System Dependencies 3
1.6Blanks vs. Spaces 5
2Regina Built-in Functions 6
ABBREV(long,short[,length]) (ANSI) 6
ABS(number) (ANSI) 6
ADDRESS() (ANSI) 6
ARG([argno[,option]]) (ANSI) 6
B2C(binstring) (AREXX) 8
B2X(binstring) (ANSI) 8
BEEP(frequency[,duration]) (OS/2) 8
BITAND(string1[,[string2][,padchar]]) (ANSI) 8
BITCHG(string,bit) (AREXX) 9
BITCLR(string,bit) (AREXX) 9
BITCOMP(string1,string2,bit[,pad]) (AREXX) 9
BITOR(string1[,[string2][,padchar]]) (ANSI) 9
BITSET(string,bit) (AREXX) 10
BITTST(string,bit) (AREXX) 10
BITXOR(string1[,[string2][,padchar]]) (ANSI) 10
BUFTYPE() (CMS) 10
C2B(string) (AREXX) 11
C2D(string[,length]) (ANSI) 11
C2X(string) (ANSI) 12
CD(directory) (REGINA) 12
CHDIR(directory) (REGINA) 12
CENTER(string, length [, padchar ] ) (ANSI) 12
CENTRE(string, length [, padchar ] ) (ANSI) 12
CHANGESTR(needle, haystack, newneedle ) (ANSI) 13
CHARIN([streamid][,[start][,length]]) (ANSI) 13
CHAROUT([streamid][,[string][,start]]) (ANSI) 14
CHARS([streamid]) (ANSI) 15
CLOSE(file) (AREXX) 15
COMPARE(string1,string2[,padchar]) (ANSI) 15
COMPRESS(string[,list]) (AREXX) 16
CONDITION([option]) (ANSI) 16
COPIES(string,copies) (ANSI) 16
COUNTSTR(needle,haystack) (ANSI) 17
CRYPT(string,salt) (REGINA) 17
DATATYPE(string[,option]) (ANSI) 17
DATE([option_out [,date [,option_in]]]) (ANSI) 19
DELSTR(string,start[,length]) (ANSI) 21
DELWORD(string,start[,length]) (ANSI) 21
DESBUF() (CMS) 22
DIGITS() (ANSI) 22
DIRECTORY([new directory]) (OS/2) 22
D2C(integer[,length]) (ANSI) 22
D2X(integer[,length]) (ANSI) 23
DROPBUF([number]) (CMS) 23
EOF(file) (AREXX) 24
ERRORTEXT(errno[, lang]) (ANSI) 24
EXISTS(filename) (AREXX) 25
EXPORT(address,[string],[length][,pad]) (AREXX) 25
FIND(string,phrase) (CMS) 26
FORK() (REGINA) 26
FORM() (ANSI) 26
FORMAT(number[,[before][,[after][,[expp][,[expt]]]]]) (ANSI) 26
FREESPACE(address,length) (AREXX) 27
FUZZ() (ANSI) 28
GETENV(environmentvar) (REGINA) 28
GETPID() (REGINA) 28
GETSPACE(length) (AREXX) 28
GETTID() (REGINA) 28
HASH(string) (AREXX) 29
IMPORT(address[,length]) (AREXX) 29
INDEX(haystack,needle[,start]) (CMS) 29
INSERT(string1,string2[,position[,length[,padchar]]]) (ANSI) 29
JUSTIFY(string,length[,pad]) (CMS) 30
LASTPOS(needle,haystack[,start]) (ANSI) 30
LEFT(string,length[,padchar]) (ANSI) 30
LENGTH(string) (ANSI) 31
LINEIN([streamid][,[line][,count]]) (ANSI) 31
LINEOUT([streamid][,[string][,line]]) (ANSI) 32
LINES([streamid][,option]) (ANSI) 33
MAKEBUF() (CMS) 34
MAX(number1[,number2]...) (ANSI) 34
MIN(number[,number]...) (ANSI) 34
OPEN(file,filename,['Append'|'Read'|'Write']) (AREXX) 35
OVERLAY(string1,string2[,[start][,[length][,padchar]]]) (ANSI) 35
POPEN(command[,stem.]) (REGINA) 36
POS(needle,haystack[,start]) (ANSI) 36
QUALIFY([streamid]) (ANSI) 36
QUEUED() (ANSI) 36
RANDOM(max) (ANSI) 37
RANDOM([min][,[max][,seed]]) (ANSI) 37
RANDU([seed]) (AREXX) 38
READCH(file,length) (AREXX) 38
READLN(file) (AREXX) 38
REVERSE(string) (ANSI) 38
RIGHT(string,length[,padchar]) (ANSI) 39
RXFUNCADD(externalname,library,internalname) (SAA) 39
RXFUNCDROP(externalname) (SAA) 39
RXFUNCERRMSG() (REGINA) 39
RXFUNCQUERY(externalname) (SAA) 40
RXQUEUE(command[,queue]) (OS/2) 40
SEEK(file,offset,['Begin'|'Current'|'End') (AREXX) 40
SHOW(option,[name],[pad]) (AREXX) 41
SIGN(number) (ANSI) 41
SLEEP(seconds) (CMS) 41
SOURCELINE([lineno]) (ANSI) 41
SPACE(string[,[length][,padchar]]) (ANSI) 42
STATE(streamid) (CMS) 42
STORAGE([address],[string],[length],[pad]) (AREXX) 42
STREAM(streamid[,option[,command]]) (ANSI) 43
STRIP(string[,[option][,char]]) (ANSI) 47
SUBSTR(string,start[,[length][,padchar]]) (ANSI) 48
SUBWORD(string,start[,length]) (ANSI) 48
SYMBOL(name) (ANSI) 48
TIME([option_out [,time [option_in]]]) (ANSI) 49
TRACE([setting]) (ANSI) 50
TRANSLATE(string[,[tableout][,[tablein][,padchar]]]) (ANSI) 51
TRIM(string) (AREXX) 51
TRUNC(number[,length]) (ANSI) 51
UNAME([option]) (REGINA) 52
UNIXERROR(errorno) (REGINA) 53
UPPER(string) (AREXX) 53
USERID() (REGINA) 53
VALUE(symbol[,[value],[pool]]) (ANSI) 53
VERIFY(string,ref[,[option][,start]]) (ANSI) 54
WORD(string,wordno) (ANSI) 54
WORDINDEX(string,wordno) (ANSI) 55
WORDLENGTH(string,wordno) (ANSI) 55
WORDPOS(phrase,string[,start]) (ANSI) 55
WORDS(string) (ANSI) 56
WRITECH(file,string) (AREXX) 56
WRITELN(file,string) (AREXX) 56
XRANGE([start][,end]) (ANSI) 56
X2B(hexstring) (ANSI) 56
X2C(hexstring) (ANSI) 57
X2D(hexstring[,length]) (ANSI) 57
3Implementation specific documentation for Regina 58
3.1Deviations from the Standard 58
3.2Interpreter Internal Debugging Functions 58
3.3REXX VMS Interface Functions 60