SETCLIP(name[,value])

SAY SETCLIP(`path', `DF0:s') -> 1
SAY SETCLIP(`path') -> 1

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

Examines the names in the Clip List

FILES

Examines the currently open logical file names

LIBRARIES

Examines the names in the Library List, which are either function libraries or function hosts.

PORTS

Examines 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.

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

SAY SIGN(12) -> 1
SAY SIGN(-33) -> 1

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE(1)-> /*A simple test program*/

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

SAY SPACE(`Now is the time',3) -> `Now is the time'
SAY SPACE(`Now is the time',0) -> `Nowisthetime'
SAY SPACE(`1 2 3',1, `+') -> `1+2+3'

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied 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. See also EXPORT().

For example:

SAY STORAGE() -> ` 248400
oldval = STORAGE(`0004 0000'x, `The answer')
CALL STORAGE `0004 0000'x,,32, `+'

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

SAY STRIP(` say what? `) -> `say What?'
SAY STRIP(` say what? `,'L') -> `say what?
SAY STRIP(`++123+++', `B', `+') -> `123'

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

SAY SUBSTR(`123456',4,2) -> 45
SAY SUBSTR(`myname',3,6, `=') -> name==

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

SAY SUBWORD(`Now is the time `,2,2) -> is the

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol ha been assigned a value, VAR is returned. For example:

SAY SYMBOL(`J') -> VAR
SAY SYMBOL(`x') -> LIT
SAY SYMBOL(`++') -> BAD

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

CIVIL

Current time in 12 hour format (a.m./p.m.) hours/minutes

ELAPSED

Elapsed time in seconds since program start

HOURS

Current time in hours since midnight

MINUTES

Current time in minutes since midnight

NORMAL

Current time in 24 hour format (hours/minutes/seconds)

RESET

Reset the elapsed time clock

SECONDS

Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

/*Suppose that the time is 1:02 AM . . .*/
SAY TIME(`C'( -> 1:02 AM
SAY TIME(`HOURS') -> 1
SAY TIME(`M') -> 62
SAY TIME(`N') -> 01:02:54
SAY TIME(`S') -> 3720
call TIME(`R') /*reset timer*/
SAY TIME(`E') -> .020
SAY TIME() -> 01:02:00

Sets the tracing mode (see Chapter 6) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

/*Assume tracing mode is ?ALL*/
SAY TRACE(`Results') -> ?A

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to uppercase. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always for the same length as the original string. The input and output tables may be of any length. For example:

SAY TRANSLATE("abcde", "123", "cbade", "+") -> 321++
SAY TRANSLATE("low") -> LOW
SAY TRANSLATE("0110", "10", "01") -> 1001