Utility Functions

chdir()

Changes spec's current working directory to the user's home directory as obtained from the environment variable HOME. Returns true or false as the command was successful or not. Updates the value of the built-in variable CWD.

chdir(d)

As above but changes to the directory d.

unix()

Spawns an interactive subshell using the program obtained from the user's environment variable SHELL or shell. Uses /bin/sh if the environment variable is unset. Returns exit status of shell.

unix(cmd)

As above, but uses /bin/sh to execute the one-line command cmd.

unix(cmd, var)

As above, but the second argument var is the name of a variable in which to place the string output of cmd. There is no limit to the length of the string saved to var. (Prior to spec release 6.11.04, the maximum length was 4096 bytes, and an optional third argument could specify a larger size.)

time()

Returns the current epoch in seconds. The UNIX epoch is the number of seconds from January 1, 1970, 00:00:00 GMT. The value returned includes a fractional part with the resolution dependent on the host platform. On modern computers, the gettimeofday() system call used to fetch the time returns values with microsecond resolution.

date()

Returns a string containing the current date as "Mon Feb 8 21:04:04 EST 1988". The default format can be changed using the "date_format" option of spec_par(). See the spec_par help file.

date(fmt)

As above, but the output string is formatted according to the specifications in the string fmt. The format is passed to the standard C library strftime() function (see the strftime man page) with one addition: spec fills in the format options "%.1" through "%.9" with the fractional seconds, where the single digit specifies the number of decimal digits. For example,

p date("%m-%d-%Y %T.%.6")

will display a date in the format:

01-14-2005 22:59:30.148067

date(t [, fmt])

As above, but from the epoch given by t. See time() above.

sleep(t)

Suspends execution for t seconds, where t may be non-integral. In old versions, a negative t indicated sleep was for clock ticks (1/60 second each). Returns true.

file_info(f [, cmd])

Returns information on the file or device named f. With just the one f argument, file_info() returns nonzero if the file or device exists and zero otherwise. If f is the string "?", the possible values for cmd are listed. If f is the string ".", spec uses the information from the last stat() system call, avoiding the overhead associated with an additional system call. The values for cmd and the information returned follow. Note that the first set of values essentially mimic the contents of the data structure returned by the stat() system call, and the second set of values have the same meaning as arguments to the test utility invoked from the shell.

"dev"

the device number on which f resides.

"ino"

the inode number of f.

"mode"

number coding the access modes and file attributes.

"nlink"

number of hard links for f.

"uid"

user id of the owner.

"gid"

group id of the owner.

"rdev"

device id if f is a block or character device.

"size"

size in bytes of f.

"lines"

number of newline characters in the file (as of spec 6.03.04). If the file does not end with a newline, the count is increased by one.

"atime"

time when f's data was last accessed.

"mtime"

time when f's data was last modified.

"ctime"

time when f's attributes were last modified.

"isreg" or "-f"

whether f is a regular file.

"isdir" or "-d"

whether f is a directory.

"ischr" or "-c"

whether f is a character device.

"isblk" or "-b"

whether f is a block device.

"islnk" or "-h" or "-L"

whether f is a symbolic link.

"isfifo" or "-p"

whether f is a named pipe (fifo).

"issock" or "-S"

whether f is a socket.

"-e"

whether f exists.

"-s"

whether the size of f is greater than zero.

"-r"

whether f is readable.

"-w"

whether f is writable.

"-x"

whether f is executable.

"-o"

whether f is owned by you.

"-G"

whether f is owned by your group.

"-u"

whether f is setuid mode.

"-g"

whether f is setguid mode.

"-k"

whether f has its sticky bit set.

file_info(pid, "alive")

Returns nonzero if the process associated with the process ID pid exists and zero otherwise.

getenv(s)

Returns the string value of the environment variable s.

get_history(n)

If n is positive, returns the specified history item as a string. If n is negative, subtracts the absolute value from the current history number and returns that history item. For example, get_history(-1) returns the previous command. If the specified number is out of range, returns an empty string.

encode(format, obj [, ...])

Returns a string representation of the spec data objects in the specified format. Currently, the only recognized formats are "json" and "base64". See the encode help file for details.

decode(format, str)

Returns a spec data object obtained from the string representation in format. Currently the only recognized formats are "json" and "base64". See the encode help file for details.

spec_par(args)

Sets, displays or returns values for various internal parameters. See the spec_par help file for details.

queue(cmd [, *arg])

Schedules commands to run once at a fixed time in the future or to repeat at an interval. See the queue help file for details.

Evaluation Functions

eval(cmd_string [, args])

Parses and executes the string cmd_string, which can contain one or more statements or statement blocks. If the last statement in the string cmd_string is an expression, its value is returned. A single number, a quoted string or a single variable is considered an expression and its value will be returned. However, a single uninitialized variable will generate an error.

If the last statement is not an expression, eval() returns true (nonzero) if there were no errors executing the statement(s). The type of errors that normally cause spec to reset to command level (syntax errors, for example) will cause eval() to return false rather than reset to command level.

To distinguish between a true (1) or false (0) return value and an expression returning a value, eval() assigns a code to the built-in global variable EVAL_RESULT (as of spec release 6.04.05). If EVAL_RESULT is -1, there was an error parsing or executing the string, or an attempt was made to return the value of a single uninitialized variable. If EVAL_RESULT is 1, the string was a statement or was a statement list that ended in a statement. If EVAL_RESULT is zero, the string or last statement in the string was an expression.

An empty string or a string containing only white-space characters is a special case. EVAL_RESULT is set to 1 to indicate a statement, but the return value of eval() is zero.

If the string cmd_string contains multiple statements, the value of EVAL_RESULT will be 0 or 1 based on the result of the last statement. If any of the statements generate an error, EVAL_RESULT will be set to -1 and the parsing and execution of the statements in the string cmd_string is abandoned.

If there is an error parsing or executing the string, in most cases, an error message will be assigned to the built-in global variable EVAL_ERR (as of spec release 6.04.05).

EVAL_RESULT and EVAL_ERR are reset to 0 and "" respectively on each call of eval(). With nested calls to eval(), EVAL_RESULT and EVAL_ERR will be associated with the most recently completed call.

Options for args include the following:

"quiet"

Error messages to the screen are suppressed, although EVAL_RESULT and EVAL_ERR are still set and messages are sent to any turned on output files. Messages produced by eprint or eprintf() will also be suppressed (as of spec release 6.10.01). The last such message will be placed in EVAL_ERR, unless it is replaced with an internally generated message from an execution error.

"local_visible" or "local"

Local symbols in the statement blocks surrounding the eval() call are visible and can be read or modified.

"reset_on_error" or "reset"

The type of errors that would cause spec to reset to command level will reset to command level in eval(). Note, EVAL_RESULT and EVAL_ERR will still be set.

Each option can be an argument, or multiple options separated by commas or spaces can be put in a single argument. For example, all the following are valid and have the same effect:

eval(cmd_string, "local_visible", "reset_on_error")
eval(cmd_string, "local, reset")
eval(cmd_string, "local_visible reset_on_error")

With the local_visible option, in order to have local variables within the eval() command string that only have scope within that command, use curly brackets to form a statement block that includes the local declaration.

eval2(cmd_string [, args])

Deprecated version of eval() that sets the "local_visible" option. See eval() above.

Command Files

dofile(f [, start])

Queues the file f for reading commands. Returns nonzero if the file cannot be opened. If the optional argument start is an integer, the number specifies at which line to start reading the file. (Currently, only positive integers are allowed.) If the argument is anything else, it is considered a search string, and text is read from the file starting at the first line containing that search string.

The search string may contain the *, ? and [] metacharacters. A * matches any string, and a ? matches any single character. With the [...] pattern, any string that contains the characters within the square brackets is matched. Two characters separated by a hyphen specify a range of characters that will match. An initial ^ negates the enclosed character set. (Support for [] added in spec release 6.07.) Initial and trailing white space is ignored when searching for a match.

qdofile(f [, start])

As above, but doesn't echo the contents of the file to the screen.

Help Functions

gethelp(f [, flags])

Prints the paginated help file f on the screen. If f contains a /, the argument is treated as an absolute or relative pathname. Otherwise, the argument refers to a file in the spec_help (or help) subdirectory of the SPECD directory.

Prior to spec release 6, spec contained an internal help file parser and formatter. With release 6, help files are formatted using the standard groff utility and paginated using the standard less utility.

If the argument f is a pathname and the optional flags argument has bit 0x02 set, spec will use groff formatting macros appropriate for help files written using pre-release 6 conventions.

Returns non-zero if the file couldn't be opened.

whatis(s, ["info"])

With one argument, returns a number that indicates what the string argument s is. With two arguments, returns a string containing a text description of what s is. The number is a two-word (32-bit) integer, with the low word containing a code for the type of object and the high word containing more information for certain objects.

High Word	Low Word	Meaning
0	0	Not a command, macro or keyword
0	1	Command or keyword
Length	2	Macro name (length is in bytes)
0x0001	4	New-style data array
0x0010	4	Number-valued
0x0020	4	String-valued
0x0040	4	Constant-valued
0x0100	4	Associative array
0x0200	4	Built-in
0x0400	4	Global
0x0800	4	Unset
0x2000	4	Immutable
0x4000	4	Local
0x8000	4	Associative array element
0	8	Numerical constant

Most type-4 symbols have more than one of the high-word bits set. Note, the whatis() function does not evaluate any expressions contained in the argument s.

Controlling Output Files

open()

Lists all open files. Returns zero.

open(file_name)

Makes file_name, which is a string constant or expression, available for output. Files are opened to append. Returns zero for success, -1 if the file can not be opened or if there are too many open files.

close(file_name)

Closes file_name and removes it from the table of files available for output. Returns zero for success, -1 if the file wasn't open. Any open file should be closed before attempting to modify the file with other UNIX utilities. Otherwise the file may be corrupted if two processes are writing to the file.

on()

Lists all open files and indicates which ones are currently turned on for output.

on(file_name)

Turns on file_name for output. All messages, except for some error and debugging messages, but including all print and printf() output, are sent to all turned-on devices. If file_name has not been made available for output with the open() function, it will be opened. Returns zero for success, -1 if the file can't be opened or if too many open files.

off(file_name)

Turns off output to file_name, but keeps it in the list of files available for output. If this was the last turned-on file or device, tty is turned back on automatically. Returns zero for success, -1 if the file wasn't open.

Macro-Related Functions

cdef(name, s, [key, [flags]])

The function cdef() is used to define chained macros. The function can be used to maintain a macro definition in pieces that can be selectively included into a complete macro definition. The argument name is the name of the macro. The argument s contains a piece to add to the macro.

The chained macro can have three parts: a front, a middle and a back. Pieces included in each of the parts of the macros are sorted lexicographically by the keys. Pieces without a key are placed in the middle, in the order in which they were added, but after any middle pieces that include a key.

With the optional key argument, the pieces can be selectively replaced or deleted. The flags argument controls whether the pieces are added to the front or to the back of the macro or whether the pieces should be selectively included in the definition based on whether key is a currently configured motor or counter mnemonic.

The bit meanings for flags are as follows:

0x01

only include if key is a motor mnemonic and the motor is not disabled.

0x02

only include if key is a counter mnemonic and the counter is not disabled.

0x10

place in the front part of the macro.

0x20

place in the back part of the macro.

If flag is the string "delete", the piece associated with key is deleted from the named macro, or if the name is the null string, from all the chained macros.

If flag is the string "enable", the parts of the named macro associated with key are enabled, and if flag is the string "disable", the associated parts are disabled. If name is the null string "", then all chained macros that have parts associated with key will have those parts enabled or disabled.

If key is the null string, the flags have no effect.

For "delete", "enable" and "disable", the key can include the standard metacharacters *, ? and []. (As of spec release 6.10.01.)

The cdef() function can be used to define macro functions (as of spec release 6.12.01). If any of the cdef() calls include parenthesis after the macro name, the macro will become a macro function. Note, though, cdef() macro functions don't allow arguments in the definition. However, a cdef()-defined macro function can be called with arguments that can be accessed in the definitions using the argc, argv[], arg1, arg2, ... features. (See the macros help file for details.) spec will automatically add an initial and final curly bracket to the pieces of the chained macro.

The cdef() function will remove any existing macro defined using def or rdef. Likewise, def and rdef will remove an existing cdef() macro with the same name.

The commands lsdef, prdef and undef work with chained macros, with lsdef indicating "cdef" macros with an asterisk and prdef using the # cdef() comment before the macro definition. The clone() commands creates an ordinary macro as the cloned copy.

When spec starts, when the reconfig command is run (or the config macro is invoked) or when individual motors or counters are enabled or disabled, all the chained macros are adjusted for the currently configured and enabled motors and counters.

cdef("?")

Lists all the pieces of all the chained macros.

cdef(name, "?")

Lists the pieces of the macro named name, as will a "?" as the third or fourth argument.

clone(dest, src)

Duplicates the macro src as a new macro named dest. Currently a clone of a cdef chained macro becomes an ordinary macro.

strdef(s [, arr])

Returns a string containing the macro definition of s. If s is not a defined macro, returns the string s itself. If an associative array arr is included as an argument, elements will be created and assigned as follows. If the macro s is a macro function, elements of arr indexed starting at 0 will be assigned the string names of the arguments to the macro function. The element arr["argc"] will be assigned the number of arguments to the macro function (as of spec release 6.11.02). For all macros, the element arr["file"] will be assigned the name of file where the macro was defined, "tty" if the macro was defined at the keyboard, "cdef()" if the macro is a chained macro or "clone" if the macro is a clone of another macro (as of spec release 6.06.01).

strdef(s, key [, *arr])

If s is a chained macro, returns a string containing only the definition segment associated with key. If s is not a defined macro, returns the string s itself. If s is a macro, but not a chained macro, returns the definition. If s is a chained macro, but doesn't contain a segment associated with key, returns the null string. (Available as of spec release 6.03.04.) The key can include the standard metacharacters *, ? and [] (as of spec release 6.10.01). If an associative array arr is included as an argument, values are assigned as described above.

User Input and Output

input()

Reads a line of input from the keyboard. Removes leading white space and trailing newline and returns the string. Returns the null string "" if only white space was entered.

input(s)

As above, but prompts with the string s.

input(n)

This function behaves differently depending on whether the input source is the keyboard (the normal case) or a pipe from another program (as when spec is invoked with the -p fd pid option with nonzero fd.)

In the normal case, if n is less than or equal to zero, the tty state is set to cbreak mode and input echo is turned off. Then input() checks to see if the user has typed a character and immediately returns a null string if nothing has been typed. Otherwise, it returns a string containing the single (or first) character the user typed. If n is less than zero, the cbreak, no-echo mode remains in effect when input() returns. If n is greater than zero, the normal tty state is restored (as it is also if there is an error, if the user types ^C or if the user enters the exit command). Also, no characters are read and the null string is returned. The normal tty state will always be restored before the next main prompt is issued, whether due to an error, a ^C, or through the normal flow of the program.

If n is -2 or less, there is an added feature where input() will return special codes for particular special key sequences. Currently, the arrow-key and forward delete key sequences are recognized, with return codes of 0xE8, 0xEA, 0xEB, 0xEC and 0xFF for left, up, down, right and forward delete, respectively. (As of spec release 6.01.)

When spec is invoked with the -p fd pid option with nonzero fd, input() reads nothing but does return the number of characters available to be read. If n is nonzero, input() simply reads and returns a line of text, as if it had been invoked with no argument.

yesno([s, ] x)

Prompts the user with the optional string s, then waits for a yes or no response. The function returns 1 if the user answers with a string beginning with Y, y or 1. The value of x is returned if the user simply enters return. Otherwise the function returns 0. If the prompt string s is present, the characters " (YES)? " or " (NO)? " are appended depending on the value of x.

getval([s, ] x [, u])

Prompts the user with the string s, if present, then waits for a user response. If the user enters a value, that value is returned. The value of x is returned if the user simply enters return. If the prompt string s is present, the string is printed followed by the current value of x and the string u, if present, in parenthesis, a question mark and a space. The function works with both number and string values. The optional third argument is intended to be used for a unit string.

getsval([s, ] x)

Like getval() above, prompts the user with the string s, if present, then waits for a user response. The value of x is returned if the user simply enters return. If the prompt string s is present, the string is printed followed by the current value of x in parenthesis, a question mark and a space. Unlike getval(), this function does not convert hexadecimal or octal input (number strings that begin with 0, 0x or 0X) to the corresponding decimal value. Rather, the getsval() function returns the literal string as entered.

getline(file [, arg [, ...]])

Reads one or more lines from the ASCII file given by the string file. With no optional arguments, the next line in the file is read and returned, including the trailing newline.

To distinguish between an end of file, an error or a literal -1, getline() assigns a value to a built-in variable named GETLINE_EOF (as of spec release 6.03.05). The value of GETLINE_EOF will be 1 if there was an end-of-file condition on the read of the file, -1 if there was an error reading the file or if the file couldn't be opened and zero if the read was successful.

For each file given as argument, spec will remember the current position until getline(file, "close") is called. In addition to the file name, spec remembers the device and inode numbers of the file. As long the absolute or relative path name for file refers to the same file, spec will remember the current position. Note, the current position is saved as a byte offset, not a line number.

(Ability to read multiples lines with starting and ending line numbers, end-of-string regular expressions and reading to the end of file was added in spec release 6.09.04. Ability to remember the current position of mulitiple files was added in spec release 6.11.07.)

Usage is as follows:

getline(file, "open")

Attempts to open named file. Returns zero for success. This call isn't necessary, as files will be opened automatically when reading, but can be used to test if a file is accessible. Resets the line counter to zero for the given file to zero.

getline(file, "close")

Closes file if it is open and returns zero.

getline(file)

Returns the next line of file. Opens the file if needed. Sets GETLINE_EOF flag to 1 if the end of file is reached and to -1 if there is an error.

getline(file, "position")

Returns the line number of the most recently read line. Returns zero before any lines are read. Returns -1 if the file isn't open. Sets GETLINE_EOF if at the end of file.

getline(file, num)

Returns line number num. Values for num of both 0 and 1 return the first line of the file. If num is greater than the number of lines in the file, returns -1 and sets GETLINE_EOF to 1.

getline(file, "end")

Returns all the lines from the current position to the end of file.

getline(file, num, "end")

Returns all the lines from line number num to the end of file.

getline(file, "match", regex)

Returns all the lines from the current position to the first line that matches the regular expression regex, inclusive. If regex is invalid, returns -1 and sets GETLINE_EOF to -2. If no match found, returns -1 and sets GETLINE_EOF to -1.

getline(file, num, "match", regex)

Returns all the lines from line number num to the first line that matches the regular expression regex, inclusive. If regex is invalid, returns -1 and sets GETLINE_EOF to -2. If no match found, returns -1 and sets GETLINE_EOF to -1.

getline(file, "match_one", regex)

Returns the first line that matches the regular expression regex starting from the current position in the file. If regex is invalid, returns -1 and sets GETLINE_EOF to -2. If no match found, returns -1 and sets GETLINE_EOF to -1.

getline(file, num, "match_one", regex)

Returns the first line that matches the regular expression regex starting at line number num. If regex is invalid, returns -1 and sets GETLINE_EOF to -2. If no match found, returns -1 and sets GETLINE_EOF to -1.

getline(file, beg, end)

Returns all the lines from line number beg through line number end, inclusive.

sscanf(s, fmt, arg [, ... ])

Scans the literal string or string variable s for data, where fmt contains a format specification in the same style as the C language scanf() function. Each arg is a variable name or array element that will be assigned the values scanned for. The function returns the number of items found in the string.

printf(fmt [, a, ...])

Does formatted printing on the turned-on output devices. See printf() in a C-manual. Returns true.

fprintf(file_name, fmt [, a, ...])

Does formatted printing on file_name. All other devices (except log files) are turned off when the string is printed.

eprintf(fmt [, a, ...])

Same behavior as printf(), above, except that if an error-log file is open, the generated output will also be written to that file, in addition to any other files or device turned on for output. The first line of any strings written to the error-log files will be prefixed with the #E characters.

spec_menu(menu [, modes [, dumbterm]])

Creates an interactive menu. When the menu is active, the user can use arrow and control keys to navigate the options and edit strings. The menu argument is a two-dimensional associative array that completely describes the menu. The first index of the array is a number that identifies an item. The second index of the array is a string that matches one of a set of keys that identify an attribute for the item. The value of the array element depends on the key. The optional modes argument is a single value where each bit can be associated with a menu item. If the dumbterm argument is present and nonzero, no cursor positioning will be used, and the menu options will be presented one line at a time. The function returns a possibly modified value for modes. See the spec_menu help file for complete details.

tty_cntl(s)

Sends terminal-specific escape sequences to the display. The sequences are only written to the "tty" device and only if it is turned on for output. The sequences are obtained from the system terminal-capability data base using the value of the environmental variable TERM. The following values for s are recognized:

"ho"

move the cursor to the home position (upper left corner).

"cl"

clear the screen.

"ce"

clear to the end of the line.

"cd"

clear from current position to the end of the screen.

"so"

start text stand-out mode.

"se"

end text stand-out mode.

"md"

start bold (intensified) mode.

"me"

end bold mode.

"us"

start underline mode.

"ue"

end underline mode.

"mb"

start blink mode. (Note, xterms don't blink.)

"mh"

start half-bright mode.

"mr"

start reverse video mode.

"up"

move up one row.

"do"

move down one row.

"le"

move left one column.

"nd"

move right one column (non-destructive space).

tty_cntl("resized?")

Updates the ROWS and COLS variables in the event the window size has changed and returns a nonzero value if the window size has changed since the last call to tty_cntl("resized?").

tty_fmt(x, y, w, s)

Writes the string s to the screen starting at column x and row y, where column 0, row 0 is the upper left corner of the screen. The string is only written to the "tty" device and only if it is turned on for output. If s is longer than the width given by w, the string is split at space characters such that no line is longer then w. Newlines in the string are retained, however. The function will truncate words that are wider than w and drop lines that would go off the bottom of the screen. Negative x or y position the cursor relative to the left or bottom edges of the screen, respectively. The function returns the number of lines written.

The two-letter control sequences listed above for the tty_cntl() function can be included in the string s by using the special string "\[xx]", where xx is the two-letter sequence. Note, though, the formatting code may fail if the sequence changes the current position of the output text.

tty_move(x, y [, s])

Moves the cursor to column x and row y, where column 0, row 0 is the upper left corner of the screen. If the third argument s is present, it is written as a label at the given position. The two-letter control sequences listed above for the tty_cntl() function can be included in the string s by using the special string "\[xx]", where xx is the two-letter sequence. The sequences and string are only written to the "tty" device and only if it is turned on for output.

Negative x or y position the cursor relative to the left or bottom edges of the screen, respectively.

Relative moves are specified by adding +/-1000 to x or y. Both arguments must specify either relative or absolute moves. If one coordinate specifies a relative move, the absolute move in the other coordinate will be ignored. The command:

tty_move(1000, 1000, "\[so]string\[se]")

is a relative move of zero in both x and y, displaying the string in bold at the current position. Relative moves of zero enable use of the special sequences without the need to consider position on the screen. Note, not all terminal types support relative moves.

Counting and Moving

mcount(t)

Begins counting for t monitor counts. Returns true.

tcount(t)

Begins counting for t seconds. Returns true.

cnt_mne(i)

Returns the string mnemonic of counter i as given in the configuration file.

cnt_name(i)

Returns the string name of counter i as given in the configuration file.

cnt_num(mne)

Returns the counter number corresponding to the counter mnemonic mne, or -1 if there is no such counter configured. As of spec release 6.05.01, mne can be a variable or an expression. If mne is an uninitialized variable, the function returns -1.

counter_par(i, s [, v])

Returns or sets configuration parameters for counter i. See the counting help file for more information.

mca_sel(n)

Selects which MCA-type device to use for subsequent calls of the mca_get(), mca_put() and mca_par() functions. The MCA device numbering is set in the config file with the string @mca_N, where N is the device number (from 0 to 31). Returns -1 if not configured for device n, otherwise returns zero. It is not necessary to use mca_sel() if only one MCA-type device is configured and is configured as device 0.

mca_sel("?")

Lists the configured MCA devices and indicates which device is currently selected for the mca_get(), mca_put() and mca_par() functions with an asterisk. Also displays the MCA device number for use with the mca_sget(), mca_sput() and mca_spar() functions and displays whether the presence test found the unit unresponsive or if the user has disabled the unit. Returns the total number of MCA devices recognized in the config file. Note, the value of the built-in global variable MCAS is always set to the number of MCA devices.

mca_sel(n, "?")

Returns a string containing one line of information about MCA device n, or 0 if spec isn't configured for device n.

mca_get(arr [, roi_beg [, roi_end]])

Gets data from the currently selected MCA-type device, and transfers it to the array arr. If the optional starting channel and ending channel are given, the data is read from those hardware channels and placed starting at the beginning of the array. For example,

SPEC.1> ulong array data[1024]
SPEC.2> mca_get(data)
SPEC.3> mca_get(data, 32, 128)
SPEC.4> mca_get(data[32:128], 32, 128)

The last example uses subarray syntax to position the data in array elements corresponding to the MCA channel positions.

mca_get(g, e [, roi_beg [, roi_end]])

As above, but transfers the data to element e of data group g instead of an array. Returns the number of points transferred.

mca_sget(sel, ...)

Like the above functions, but uses the MCA device numbered sel in the config file.

mca_put(...) and mca_sput(sel, ...)

These functions have the same syntax as the above, but transfer data to the MCA device (for devices that support transfer in that direction).

mca_par(cmd [, arg])

A function to access various features and parameters of the currently selected MCA device. The string cmd selects an option. The argument arg contains an optional value. Some values for cmd apply to all MCA devices, and some only apply to certain devices. See the mca help file for additional information.

mca_spar(sel, cmd [, arg])

Like the above, but uses the MCA device numbered sel in the config file.

image_get(sel, arr)

Reads image data from the 2D acquisition device numbered sel into the data array arr.

image_put(sel, arr)

Writes image data from the data array arr to the 2D acquisition device numbered sel (for devices that support transfer in that direction).

image_par(sel [, v])

Returns or sets configuration parameters for 2D acquisition devices.

wait()

Wait for all asynchronous activity to complete. Returns true.

wait(w)

Wait for moving (w=1), counting (w=2), other data acquisition (MCAs, CCDs, etc.) (w=4) or remote connections and remote asynchronous events (w= 8), to complete. If bit 5 of w is set, returns true if activities flagged by bits 0, 1, 2 or 3 are active. Returns false otherwise. See the wait help file for details.

stop(w)

Stop moving (w=1), or counting and other asynchronous data acquisition (w=2). If w is zero or missing all asynchronous activity is halted. Returns true.

set_sim(i)

Turns simulate mode on (i=1), off (i=0), or only reports state (i=-1), The first two return the value of the previous state as true (on) or false (off) and do a wait() before changing state. set_sim(0) reads in the motor settings file to restore motor positions. See the set_sim help file for details.

motor_mne(i)

Returns the string mnemonic of motor i as given in the configuration file.

motor_name(i)

Returns the string name of motor i as given in the configuration file.

motor_num(mne)

Returns the motor number corresponding to the motor mnemonic mne, or -1 if there is no such motor configured. As of spec release 6.05.01, mne can be a variable or an expression. If mne is an uninitialized variable, the function returns -1.

motor_par(i, s [, v])

Returns or sets configuration parameters for motor i. Values for the string s include "acceleration", "base_rate", "step_size", "velocity" or "backlash". The values may be modified by giving a value for v, although modifications to "step_size" must be enabled using

spec_par("modify_step_size", 1)

first. See the motors help file and the help file for particular motor controllers for more information on possible parameters. Rereading the config file resets the values of the motor parameters to the values in the config file. Little consistency checking is done by spec on the values programmed with motor_par(). Be sure to use values meaningful to your particular motor controller.

move_info()

Returns a 2D associative array indexed by motor number and keyword that contains information on what would happen on a subsequent move_all command. Keywords and associated value are:

"to_move"	nonzero if motor will move
"error"	reason the motor will not move
"commanded"	the commanded position
"magnitude"	magnitude of the move in user units
"current"	current position in user units
"current_dial"	current position in dial units
"target"	target position in user units
"target_dial"	target position in dial units
"backlash"	backlash for this move in user units
"leftover"	remainder due to motor resolution

The "error" key element will be present only if there is a condition that would prevent the associated motor from moving. Possible errors are:

"low limit"	move exceeds low limit
"high limit"	move exceeds high limit
"busy"	motor is busy
"read only"	motor is configured as read only
"protected"	motor configuration does not allow moving
"disabled"	motor has been disabled
"externally disabled"	shared motor has been disabled
"unusable"	motor did not respond to presence test

See the move_info help file for more details.

move_info(i)

Returns a 1D associative array for the specified motor indexed by the keywords above.

move_info(key)

Returns a 1D associative array indexed by motor number for the particular keyword.

move_info(i, key)

Returns a single value for the specified motor and keyword.

get_lim(i, w)

Returns the dial limit of motor i. If w > 0, returns high limit. If w < 0, returns low limit. If w > 1, returns high limit corrected for configured backlash. If w < 1, returns low limit corrected for configured backlash.

set_lim(i, u, v)

Sets the low and high dial limits of motor i. It doesn't matter which order the limits, u and v, are given. Returns -1 if not configured for motor i or if the motor is protected, unusable or moving, else returns 0.

dial(i, u)

Returns the motor dial position for motor i corresponding to user angle u.

user(i, d)

Returns the user angle for motor i corresponding to dial position u.

chg_dial(i, u)

Sets the dial position of motor i to u by changing the contents of the controller registers. Returns -1 if not configured for motor i or if the motor is protected, unusable or moving, else returns 0.

chg_dial(i, s [, u])

Starts motor i on a home or limit search, according to the value of s, as follows:

"home+"

move to home switch in positive direction.

"home-"

move to home switch in negative direction.

"home"

move to home switch in positive direction if current dial position is less than zero, otherwise move to home switch in negative direction.

"lim+"

move to limit switch in positive direction.

"lim-"

move to limit switch in negative direction.

Positive and negative direction are with respect to the dial position of the motor. (Not all motor controllers implement the home or limit search feature.) If present, the value of the third argument is used to set the motor's dial position when the home or limit position is reached. Returns -1 if not configured for motor i or if the motor is protected, unusable or moving, else returns 0.

chg_offset(i, u)

Sets offset (determining user angle) of motor i to u. Returns -1 if not configured for motor i or if the motor is unusable or moving, else returns 0.

read_motors(mode [, which])

Reads the motors and places the motor positions in the A[] array with options set by mode, as follows:

Bit 0 (0x01)

If clear, user positions are put into A[]. If set, dial positions are put into the motor array.

Bit 1 (0x02)

If set, forces reading the hardware. For many motor controllers, spec doesn't necessarily read the hardware if the position hasn't been changed by spec since the controller was last read.

Bit 2 (0x04)

If set, position discrepancies between spec and the motor hardware will be silently resolved in favor of the hardware. Otherwise, spec will prompt the user as to whether the software or hardware positions should be considered correct.

Bit 3 (0x08)

If set, the hardware is read, but the contents of the A[] array are not modified.

Bit 4 (0x10)

If set, the "commanded" positions are placed in A[]. The hardware is not accessed. If the optional argument which is set to a particular motor number or mnemonic, A[] is not modified, and the return value will be the commanded position for the specified motor.

Plotting and Analysis

See the arrays help file for more detailed explanations of the following data-array based functions.

array_copy(a, b [, c, ...])

Fills consecutive bytes in the destination array (or subarray) a with bytes from the arrays or strings in the subsequent arguments. The arrays can be of different types, which allows creating a binary data stream of mixed types. If a source argument is not a data array, the string value of the argument is copied.

array_dump([file, ] a [, b, ...] [, options, ...])

Efficiently writes the data in the array a and optionally arrays b, ..., etc. If the initial optional file argument is given, the output is just to the named file or device. Otherwise, output is to all "on" output devices. If the file argument is the null string "", the formatted output is returned as a string, and nothing is written to the screen. The additional options arguments are strings that specify the format of the numbers. See the arrays help file.

array_fit(pars, a [, b, ...])

Performs a linear fit of the data in the array a. The fitted parameters are returned in the array pars. The function returns the chi-squared value of the fit, if the fit was successful. A -1 is returned if the covariance matrix is singular. The fit algorithm is along the same lines as the lfit() routine in Numerical Recipes (W.H. Press, et al., Cambridge University Press, 1986, page 512).

array_op("cmd", a [, args ...])

Performs operations on the array arguments as indicated by "cmd". Possible commands include: "fill", "contract", "every", "min", "max", "i_at_min", "i_at_max", "rmin", "rmax", "cmin", "cmax", "i_<=_value", "i_>=_value", "sum", "sumsq", "transpose", "updated?", "rows", "cols", "type", "row_wise", "col_wise", "sort", "merge", "swap", "frame_size", "latest_frame", "tag", "untag", "info", "meta", "fwhm", "cfwhm", "uhmx", "lhmx", "com", "x_at_min" and "x_at_max". See the arrays help file for details.

array_plot(a [, b, ...])

Plots the data in the array a. Depending on whether a is a row-wise or column-wise array, the first column or first row elements are used for x. Subsequent elements (up to a maximum of 64) are plotted along the y axis. If preceded by a call of plot_cntl("addpoint") and the ranges have not changed, only the last point in the array is drawn. If preceded by a call of plot_cntl("addline") the current plot will not be erased, and the plot ranges will not be changed. The plotting area is not automatically erased by a call of array_plot() - use plot_cntl("erase") for that. The axis ranges are set using the plot_range() function. See plot_cntl() for other options that affect drawing the plot.

array_read(file_name, a [, options])

Reads data from the ASCII text file file_name, and stuffs the data into the array a. For a row-wise array, the values on each line of the file are assigned into successive columns for each row of the array. If more items are on a line in the file than columns in the array, or if more points are in the file than rows in the array, the extra values are ignored. For a column-wise array, each row of the data file is assigned to successive columns of the array. See the arrays help file for details.

array_pipe(program [, args [, arr_out [, arr_in]]])

Initiates or resumes synchronous execution of the special process named program. See the data_pipe help file for details.

plot_cntl(s)

Selects built-in plotting features. The argument s is a string of comma- or space-delimited options. See the plot_cntl help file for descriptions of the many options.

plot_move(x, y [, s [, c]])

Moves the current position to column x and row y, where column 0, row 0 is the upper left corner of the screen. The range of values is 0 <= x < 80 and 0 <= y < 25. Fractional values are allowed (as of spec release 6.00.04). If the third argument s is present, it is written as a label at the given position. If using color high-resolution graphics, the fourth argument, if present, is the color to use to draw the label. (See the colors help file.) The background color for the entire label will be the background color at the starting position. If graphics mode is not on, plot_move() works just as tty_move().

plot_range(xmin, xmax, ymin, ymax)

Sets the ranges of the internally generated plots. If any of the arguments is the string "auto", the corresponding range limit is determined automatically from the data at the time the plot is drawn. If any of the arguments is the string "extend", the corresponding range limit is only changed if the current data decrease the minimum or increase the maximum. Returns true.

splot_cntl(cmd [, arr])

Sends commands to the Python splot utility. Several commands are executed or processed in spec, namely "open", "status", "send" and "kill". Remaining commands are sent via a socket to the running splot program. The "open" and "kill" commands start the process and terminate the process, respectively. The "status" command returns one of the strings "not connected", "trying to connect" or "connected". The "send" command sends the data array arr as data to be plotted using the splot "adddata" command. If it is a one-dimensional array, spec creates an associated x array based on the element index. The elements in the array are sent as y values for the plot. The command "command_list" returns a list of commands available in the running Python splot program. The splot_cntl() function returns the replies sent back through the socket connection.

fmt_read(file, format, array [, header [, flags]])

Reads data from file using the indicated format into array, possibly assigning elements to header which can be an associative array or a string. See the arrays help file for more details.

fmt_write(file, format, array [, header [, flags]])

Saves data from array to file using the indicated format, possibly also writing elements of header, which can be an associative array or string. See the arrays help file for more details.

fmt_close(file, format)

Calls the file close routine associated with format for file.

h5_file(), h5_data(), h5_attr() and h5_link()

See the hdf5 help file for detailed usage.

See the data help file for more detailed explanations of the following data-group based functions. Note, the data group feature is deprecated. The array-based functions above should be used instead.

data_grp(g, n, w)

Configures data group g. The group will have n points, each having w elements. If n and w match the previous values for the group, the data in the group is unchanged. Otherwise, the data values of the reconfigured group are set to zero. If w is zero, the group is eliminated.

data_info(g, s)

Returns a number representing a parameter of the data group g according to the string s as follows:

"elem"

number of elements (width).

"npts"

number of points.

"last"

last modified (added) point.

Returns -1 if the group or command is invalid.

data_put(g, n, e, v)

Assigns the value v to element e of point n in group g.

data_get(g, n, e)

Returns the value of element e of point n in group g.

data_nput(g, n, v0 [, v1 ... ])

Assigns values to point n of group g. Element 0 is assigned v0, element 1 is assigned v1, etc. Not all elements need be given, although elements are assigned successively, starting at element 0.

data_uop(gs, es, gd, ed, uop [, arg])

Performs the unary operation specified by the string uop on element es for all points in group gs. The results are put in element ed of the corresponding points in group gd. The source and destination groups and/or elements may be the same. If the number of points in the groups differ, the operation is carried out on up to the smallest number of points among the groups. See the data help file for possible values for uop.

data_bop(gs0, es0, gs1, es1, gd, ed, bop)

Performs the binary operation specified by the string bop on elements es0 and es1 for all points in the groups gs0 and gs1. The results are put in element ed for the corresponding points of group gd. The source and destination groups and/or elements may be the same. If the number of points in the groups differ, the operation is carried out on up to the smallest number of points among the groups. See the data help file for possible values for bop.

data_anal(g, s, n, e0, e1, op)

Performs the operations indicated by op on n points in group g, starting at point s. The operations use the values in element e0 (if applicable) and e1. If n is zero, the operations are performed on points from s to the last point added using data_nput() or data_put(). See the data help file for possible values for op.

data_dump(g, s, n, e0 [, e1 ...] [, fmt1] [, fmt2])

Efficiently writes elements from group g to turned on output devices. The starting point is s and the number of points is n. The elements specified by e0, e1, etc., are printed. If e0 is the string "all", all the elements for each point are printed. If n is zero, only the points from s to the last point added using data_nput() or data_put() are printed. The optional argument fmt1 is a string, having the format "%#", that specifies how many data points (specified by the number #) to be printed on each line. The optional argument fmt2 is a string that specifies an alternate printf()-style format for the values. Only e, g and f formats are recognized. For example, "%15.8f" uses fixed-point format with eight digits after the decimal point and a fifteen-character-wide field. The default output format is "%g". See printf() in a C manual for more information. Note that in the default installation, the internal data arrays use single-precision floating values, which contain only about 8 decimal digits of significance.

data_read(file_name, g, s, n)

reads data from the ASCII file file_name, and stuffs the data into group g starting at point s, reading up to n points. If n is zero, all the points in the file are read. The values on each line of the file are assigned into successive elements for each point in the group. If there are more elements on a line in the file than fit in the group, or if more points are in the file than in the group, the extra values are ignored. Returns -1 if the file can't be opened, otherwise returns the number of points read.

data_plot(g, s, n, e0, e1 [, e2 ...])

Plots the current data in group g starting at point s and plotting n points. Element e0 is used for x. Elements given by the subsequent arguments (up to a maximum of 64) are plotted along the y axis. If n is zero, only the points from s to the last point added using data_nput() or data_put() are plotted. If proceeded by a call of plot_cntl("addpoint") and the ranges have not changed, only point s + n - 1 is drawn. If proceed by a call of plot_cntl("addline") the current plot will not be erased, and the plot ranges will not be changed. The plotting area is not automatically erased by a call of data_plot()-use plot_cntl("erase") for that. The axis ranges are set using the plot_range() function. See plot_cntl() for other options that affect drawing the plot.

data_plot(g, s, n, "all")

As above, but uses element zero for x and the remaining elements (up to a maximum of 64) for y values. The number of elements is set with the data_grp() function.

data_fit(pars, g, s, n, edata, epars [, ...])

Performs a linear fit of the data in element edata to the terms in the elements specified by epars. The fitted parameters are returned in the array pars supplied by the user. The function returns the chi-squared value of the fit, if the fit was successful. A -1 is returned if insufficient arguments or the covariance matrix is singular. The fit algorithm is along the same lines as the lfit() routine in Numerical Recipes (W.H. Press, et al., Cambridge University Press, 1986, page 512).

data_pipe(program [, args [, grp_out [, grp_in]]])

Initiates or resumes synchronous execution of the special process named program. See the data_pipe help file for details.

CAMAC Hardware

ca_get(i, a)

Returns the 24-bit value read (using F = 0) from the i-th (i = 0, 1, ... ) CAMAC I/O device (from the config file) using subaddress a.

ca_put(x, i, a)

Writes the 24-bit value x (using F = 16) to the i-th (i = 0, 1, ... ) CAMAC I/O device (from the config file) using subaddress a. Returns the value written.

ca_fna(f, n, a [, v])

Sends the arbitrary FNA command to the module in slot n. If the dataway command given by f is a write function, the 24-bit value to be written is contained in v. If the dataway command given by f is a read command, the function returns the 24-bit value obtained from the module. The user should avoid issuing commands that would cause a LAM and should certainly avoid issuing commands to slots that are being used for motor or counter control by spec's internal hardware code.

ca_cntl(cmd [, arg])

Performs a CAMAC crate initialize if cmd is "Z" or "init", performs a crate clear if cmd is "C" or "clear", sets crate inhibit if cmd is "inhibit" and arg is 1, and clears crate inhibit if cmd is "inhibit" and arg is 0. During normal operation, you should not need to issue these commands. You should probably issue a reconfig after sending a crate initialize or clear.

User Level Access To Hardware Interfaces

gpib_cntl(), gpib_get(), gpib_put(), gpib_poll(), gpib_par()

See the gpib help file for detailed usage.

ser_get(), ser_put(), ser_par()

See the serial help file for detailed usage.

sock_get(), sock_put(), sock_par()

See the sockets help file for detailed usage. Note a sock_io() function is recognized but its use is deprecated.

vme_get(), vme_get32(), vme_move(), vme_put(), vme_put32()

See the vme help file for detailed usage.

vxi11_get(), vxi11_put(), vxi11_par()

See the vxi11 help file for detailed usage.

epics_get(), epics_put(), epics_par()

See the epics help file for detailed usage. Only available when spec is linked with EPICS channel access libraries.

taco_io(), taco_dc(), taco_db()

See the taco help file for detailed usage. Only available when spec is linked with the TACO libraries.

tango_io(), tango_get(), tango_put(), tango_db()``

See the tango help file for detailed usage. Only available when spec is linked with the TANGO libraries.

madoca_io()

MADOCA is a distributed instrument control package developed at SPring-8. See the madoca help file for detailed usage.

The following functions are for generic access to spec's built-in support for fieldbus devices. Fieldbus refers to a family of industrial computer network protocols. Currently, supported protocols are Modbus and a limited implementation of CANbus. See the fbus help file for details.

fbus_put(unit, d0 [, d1, ...])

Sends a message to the fieldbus device specified as controller number unit in the hardware config file.

For CANbus, bits 0 through 28 of d0 hold the CAN ID when in PeliCAN mode. Bits 0 through 10 of d0 hold the CAN ID when in BasiCAN mode. Bit 31 of d0 indicates whether to set CAN RTR (the Remote Transmission Request bit). The CAN message is contained in d1 through d8, which are interpreted as 8-bit byte values. Any missing values are interpreted as zero.

For Modbus, d0 is the Modbus function code, where codes 5, 6, 15, 16, 21 and 22 use fbus_put(). Remaining arguments vary depending on the particular function code. See the fbus help file for details.

fbus_get(unit [, d0, d1, ...])

Reads a message from the field-bus device specified as controller number unit in the hardware config file.

For CANbus, returns an eight-element data array of long (32-bit) integers. Only the low order byte of each element of the returned array contains data. No arguments beyond the unit number are used.

For Modbus, d0 is the Modbus function code, where codes 1, 2, 3, 4, 7, 8, 11, 12, 17, 20, 23, 24 and 43 use fbus_get(). Remaining arguments vary depending on the particular function code. Returns a scaler if the arguments specify a single value. Otherwise, returns an unsigned short integer data array sized to accommodate the values requested. See the fbus help file for details.

PC Port Hardware

port_get(a)

Reads one byte from the PC I/O port with the address a. Ports must be selected in the config file.

port_getw(a)

As above, but reads a 16-bit word.

port_put(a, b)

Write the byte b to the PC I/O port with the address a. Writable ports must be selected in the config file.

port_putw(a, b)

As above, but writes a 16-bit word.

Server/Client Functions

See the server help file for more details on the spec server/client functions.

There is only one built-in function available to a spec server to communicate with its clients.

prop_send(property, value)

Sends an event to all clients registered for property. There is nothing to prevent a user-level call of prop_send() from generating events for built-in properties, although that may lead to an unexpected client response.

The remaining functions are for a spec instance that is a client to a spec server.

prop_get(host, property)

Reads and returns the current value of property from the remote host. Single-valued, associative-array and data-array types can be returned.

prop_put(host, property, value)

Sets property to value on the remote host. Single-valued, associative-array and data-array types can be sent.

prop_watch(host, property)

Registers property on the remote host. When the property value changes, the remote host will send an event to the client. See the server help file for details.

remote_stat(host)

Returns nonzero if the connection to host is up, otherwise returns zero.

remote_stat(host, "?")

Returns the string "up" if the connection to host is up. Returns the string "lost" if the connection had been up, but has been lost. Returns the string "trying" if in the process of creating a connection. Returns the string "no connection" if unable to contact the host. Returns the string "not connected" if the client has not attempted to create a connection to the host.

remote_par(host, "connect")

Initiates a connection to host. Connections are initiated automatically when spec server hardware is configured or when a server is accessed with the commands below. One might want to explicitly create the connection, though, in order to set a timeout for remote_eval() prior to accessing the host or to check the availability of a connection with remote_stat(), above.

remote_par(host, "close")

Closes the connection to the spec server host, but only if no server hardware is configured on the client.

remote_par(host, "abort")

Sends an SV_ABORT message to the server host, which has the effect on the server as if a ^C had been typed at its keyboard.

remote_par(host, "timeout" [, value])

Returns or sets the timeout interval for a remote_eval() call to complete. The units are seconds, and the default value is four seconds.

remote_cmd(host, cmd)

Puts the spec command cmd on the execution queue of the remote host. This function does not wait for the command to execute on the server. The return is immediate. Use remote_eval() or remote_async() with remote_poll() for synchronous execution of commands on the remote server.

remote_eval(host, cmd)

Puts the spec command cmd on the execution queue of the remote host and returns the result. The function will not return until the command has been executed on the server. Single-valued (number or string), associative-array and data-array return values are allowed. If a ^C keyboard interrupt is received before the host returns a result and before the connection timeout interval, an SV_ABORT message will be sent to the server, which will have the same effect on the server as a ^C from the server's keyboard. In addition, any pending commands in the server queue from the client will be removed.

id = remote_async(host, cmd)

Puts the spec command cmd on the execution queue of the remote host and returns a unique id. The return value of the command can be retrieved using the remote_poll() function, below. A ^C keyboard interrupt will clear the local queue of all pending events, but will not stop the commands from being executed on the remote host. The wait() command can be used to wait for all asynchronous remote events. Bit 0x8 in the (optional) argument to wait() corresponds to remote events.

remote_poll(id, "status")

Returns 1 (or 0) to indicate whether result number id from remote_async() is available (or not). Returns -1 if id is no longer in the queue or if the connection to the server has disappeared.

remote_poll(id)

Returns the result of the command associated with the id value of a particular call to remote_async(). Single-valued result types (number or string), along with associative-array and data-array results are allowed. Note, if called before the result is available, the id will be removed from the queue, and the return value will be zero. Always check first if the result is available using either the "status" option above or the wait() function for remote events before fetching the result. Returns -1 if id is not in the queue or if the connection to the server has disappeared.

Hooks To User-Added C-Code Functions

calc(i)

Calls user-added function having code i. Returns user supplied value.

calc(i, x)

As above, but passes argument x to the function.

String Handling

asc(s)

Returns the ASCII value of the first character of the string value of the argument s.

asc(s, position)

Returns the ASCII value of the character at position in string s, counted from 1. If position isn't within the string, returns 0. (Available in spec release 6.08.05.)

tolower(s [, count [, start]])

Returns a string with upper case letters converted to lower case. If count is specified, only that many characters are converted. If start is specified, the conversion starts at that position, counted starting from 1. Returns the original string if no conversions are possible. (Function added in spec release 6.08.05.)

toupper(s [, count [, start]])

Returns a string with lower case letters converted to upper case. If count is specified, only that many characters are converted. If start is specified, the conversion starts at that position, counted starting from 1. Returns the original string if no conversions are possible. (Function added in spec release 6.08.05.)

length(s)

Returns length of string s.

index(s1, s2)

Returns an integer indicating the position of the first occurrence of string s2 in string s1, counted from 1, or zero if s1 does not contain s2.

split(s, a)

splits the string s at space characters and assigns the resulting substrings to successive elements of the array a, starting with element 0. The space characters are eliminated. The functions returns the number of elements assigned.

split(s, a, t)

splits the string s into the elements that are delimited by the string t and assigns the resulting substrings to successive elements of the array a, starting with element 0. The delimiting characters are eliminated. Returns the number of elements assigned. If t is the null string, "", the string s will be split into characters (as of spec release 6.08.07). Note, to match the behavior of the standard awk utility (the origin of much of spec's syntax), a trailing terminator in the source string will generate a final empty element in the returned array.

substr(s, m)

Returns the portion of string s that begins at m, counted from 1.

substr(s, m, n)

As above, but the returned string is no longer than n.

sprintf(fmt [, a, ...])

Returns a string containing the formatted print. See printf() in a C manual.

String Handling With Regular Expressions

Regular expressions are sequences of special characters for searching for patterns in strings. spec implements extended regular expression using the C library regcomp() and regexec() functions, which have a somewhat platform-dependent implementation. See the regular expression man page (man 7 regex on Linux and man re_format on OS X) for details of regular expression syntax. The names and usage of the following spec functions resemble those used in the UNIX awk utility. (These functions added in spec release 6.03.04.)

rsplit(s, a, re)

Similar to split() above, but the optional delimiter argument can be a regular expression. The string s is split into elements that are delimited by the regular expression re and the resulting substrings are assigned to successive elements of the array a, starting with element 0. The delimiting characters are eliminated. Returns the number of elements assigned.

sub(re, sub, s)

Replaces the first instance of the regular expression re in the source string s with the substitute string sub. A & in the substitute string is replaced with the text that was matched by the regular expression. A "\&" (which must be typed as "\\&") will produce a literal &. Returns the modified string.

gsub(re, sub, s)

Replaces all instances of the regular expression re in the source string s with the substitute string sub. A & in the substitute string is replaced with the text that was matched by the regular expression. A "\&" (which must be typed as "\\&") will produce a literal &. Returns the modified string.

gensub(re, sub, which, s)

Replaces instances of the regular expression re in the source string s with the substitute string sub based on the value of which. If which is a string beginning with G or g (for global), all instances that match are replaced. Otherwise, which is a positive integer that indicates which match to replace. For example, a 2 means replace the second match.

In addition, the substitute text may contain the sequences \N (which must be typed as "\\N"), where N is a digit from 0 to 9. That sequence will be replaced with the text that matches the Nth parenthesized subexpression in re. A \0 is replaced with the text that matches the entire regular expression.

Returns the modified string.

match(s, re [, a])

Returns the position in the source string s that matches the regular expression re. The first position is 1. Returns 0 if no match or -1 if the regular expression is invalid. If the associative array a is provided, its contents are cleared and new elements are assigned based on the consecutive matching parenthesized subexpressions in re. The zeroth element, a[0], is assigned the entire matching text, a[0]["start"] is assigned the starting position of the match and a[0]["length"] is assigned the length of the match. Elements from 1 onward are assigned matches, positions and lengths of the corresponding matching parenthesized subexpressions in re.

Useful Conversion Functions

int(x)

Returns integer part of x.

bcd(x)

Returns binary-coded decimal integer of positive x.

dcb(x)

Returns decimal equivalent of 32-bit BCD x.

rad(x)

Returns x * PI / 180.

deg(x)

Returns x * 180 / PI.

Standard Math Functions

Note, if called with invalid arguments, the functions log(), log10(), sqrt(), acos(), asin(), pow() and atan2() generate an error message, but return the value of the argument (or first argument for pow() and atan2()). Best practice is to test that the arguments are valid before calling the functions. For example, for sqrt() make sure the argument is not less than zero.

fabs(x)

Returns absolute value of x.

sqrt(x)

Returns square root of x.

cos(x)

Returns cosine of x.

sin(x)

Returns sine of x.

tan(x)

Returns tangent of x.

acos(x)

Returns arc cosine of x.

asin(x)

Returns arc sine of x.

atan(x)

Returns arc tangent of x.

atan2(y, x)

Returns the arc tangent of y/x using the signs of the arguments to determine the quadrant of the return value. The return value is in the range -PI to PI.

exp(x)

Returns exponential of x.

exp10(x)

Returns power of 10 to the x.

log(x)

Returns natural logarithm of x.

log10(x)

Returns logarithm, base 10, of x.

pow(x, y)

Returns power of y to the x.

rand()

Returns a random integer between 0 and 32767.

rand(r)

If r is positive, returns a random integer between 0 and r, inclusive. If r is negative, returns a random integer between -r and r, inclusive. Values of r greater than 32767 or less than -16383 are set to those limits. If r is zero, a zero is returned. The C library rand() function is used to obtain the values. The seed is set to the time of day on the first call. The randomness (or lack thereof) of the numbers obtained reflects the C library implementation.

srand(seed)

Sets the seed value for the random generator used by the rand() function to the integer value seed. This feature allows the same sequence of random numbers to be generated reproducibly by resetting the seed to the same value. Returns the value of the previous seed (as of spec release 6.03.04).