Vocabulary/Foreigns
Jump to navigation
Jump to search
m !: n Foreigns J's access to its environment and facilities Q= query; S= set Back to: Vocabulary reference table bold= a name in standard library Thru to: Dictionary with examples
Overview
Summaries. Click on a group's name for details. m y n 0 1 2 3 4 5 6 7 8 9 0
q.v. Load, sum of:
+1=display +10=continue +100=noun only
Assert Test Assert Test Assert with display 1
q.v. Dir (fdir) Read Write Append Size (fsize/fexist) Mkdir Attrs Permits 1 Index Read Index Write 2→ File numbers Open Close 3→ Locks Lock Unlock 4→ Q CWD S CWD Q DLL 5→ Erase (ferase) 2
→ Execute Host Cmd Spawn Host I/O Wait Getenv (getenv) GetPID GetHw ErrNo 5→ Exit (exit) 3
→ Type & Precision To Byte Rep From Bin/Hex To Hex Rep Integer Conv (ic) Floating Conv (fc) Lock Script Noun Info 1→ To base64 From base64 Convert to lowercase/uppercase 4
→ Part Of Speech (nameclass/nc) Name List (namelist) Scripts Which Script Names Chgd Set Script Name Set Script Number Cached Reference 5→ Erase Name (erase) 5
→ Create From AR AR Boxed Tree Linear Paren Explicit 6
→ Current Session Execute (timex) Delay Parser Calls Q Clk Freq Q Clk Ctr 1→ Perf Monitor Digit time to nanoseconds Nanosecond time to integers Nanosecond time to ISO 8601 ISO 8601 time to nanosecond DateTime String to nanoseond 7
→ Space In Use High-water mark of mallocs Execute (timespacex) Free Blocks Obj Space Locale Space Space reported by OS Total 7!:0 in all threads 8
→ Format Atoms Format Columns Format Table 9
Globals
Even=Q
Odd=S→ RNG Initial State Default Displays Nameref Caching Boxing Chars Error Msgs 1→ Formatted-Numeric Precision OS Type J Ver Box Disp Pos Comp Toler 2→ Mem Limit Fill Element Secure Level Immex Sentence Immex Flag 3→ Executing name Enable assert. Output Control Locale Hash Sizes 4→ Retain Comments RNG Select RNG State Break filename 5→ Allow assignment of intermediate results to zombies Display warning messages for inefficient code Cpu feature Set emsg detail level 13
→ Enable/Disable (dbr) dbs dbsq dbss dbrun dbnxt dbret dbjmp Signal Error (dbsig) dbrr 1→ dbrrx Last Error # (dberr) / Set Error # Last Error Msg (dberm) Show Stack (dbstk) Q/S Latent Exp (dblxq/dblxs) dbtrace Q Enable (dbq) Text Stack (dbst) Cut Stack Back One Frame (dbcut) 2→ Step Over (dbover) Single-Step (dbinto) Step Out (dbout) 15
→ cd memr memw mema memfree cdf symset gh15 fh15 1→ cder cderx Address of header for named value callback Address of data for named value memu nfes callbackx Create cache-aligned data block Address of header of noun 2→ OS Handle 18
→ Classify Name List Locales (conl) Q/S Path (copath) Create S Implied (cocurrent/coclass) Q Implied (coname) Recalculate Bloom filter Set locale permanent 5→ coerase/codestroy 128
→ QR Invert R apply CRC RNG Raw Is NaN Calculate SHA Calculate AES Calculate 32-bit checksum Matrix-sparse vector product (AVX2 only) 1→ LU decomposition (AVX2 only) Trim literal blank
0!:n
m=0 (Scripts) y is either a boxed filename or the unboxed text of a script. If y is a boxed filename, the file is read and the contents used as the script, with the first line being discarded if it starts with #!. Some variants require y to be unboxed. Action n y Description Load 0 boxed filename Stop on error; do not display each line 1 Stop on error; display each line 10 Continue on error; do not display each line 11 Continue on error; display each line 100 unboxed string, containing lines to execute separated by LF Stop on error; do not display each line 101 Stop on error; display each line 110 Continue on error; do not display each line 111 Continue on error; display each line Assert 2 Load script, treating each non-assignment line as an assert. control. Display each line and the result of its execution, but stop, raising assertion error, if the result of any non-assignment line is a noun that contains an atom that is not 1. Test Assertions 3 Load the file, checking assertions as in 0!:2, but produce a result of 0 if an assertion failed, 1 if they all succeeded. Error messages are not displayed. Test Assertions with display 4 Load the file, display each line and the result of its execution, checking assertions as in 0!:2, but produce a result of 0 if an assertion failed, 1 if they all succeeded.
1!:n
m=1 (Files) Action x
(if any)
n y Rank Result Dir 0 file-search-string (optionally boxed) _ Table, where each row is
name-within-directory;timestamp of last change;size;permissions;attributes
1!:0 'j.exe'
+-----+------------------+------+---+------+
|j.exe|2008 2 23 11 17 36|696320|rwx|-----a|
+-----+------------------+------+---+------+
Search starts in current working directoryRead 1 boxed filename, or unboxed file number. y=1 means read from the keyboard, y=3 means read from stdin. 0 The contents of the file, as a list of bytes. If y is a boxed filename, the file is opened, read, and closed. If y is a file number of an open file, the file is read but not closed. Reading from keyboard not allowed while script is loading. Write any noun 2 2 _ 0 x is written to the screen, with the same formatting as if it had been the displayable result of a sentence. The result is x. a list of bytes boxed filename, or unboxed file number. y=4 means write to stdout, y=5 to stderr. x is written to the file y, replacing the previous contents if the file existed. If the file is specified by number, the file number remains open, pointing to the newly written file. Result of the verb is (i. 0 0), except when (y e. 4 5), in which case it is x. Append a list of bytes 3 boxed filename, or unboxed file number. y=2 means write to screen. _ 0 Like 1!:2, but x is appended to the file instead of replacing it. Size 4 boxed filename, or unboxed file number 0 The number of bytes in the file; error if file does not exist. Mkdir 5 boxed directory name 0 The directory is created. Result is 1. Error if directory exists. Query Attributes 6 boxed filename, or unboxed file number 0 A string of bytes, giving the system-dependent attributes. Each attribute is either present or absent. Presence is indicated by an assigned letter, and absence by a dash (-). The assigned letters for Windows are: read-only (r), hidden (h), system (s), directory (d), archivable (a), volume-label (v) Set Attributes A list of bytes, containing only assigned attribute letters and - boxed filename, or unboxed file number 1 0 Result is 1 if there is no error. Each attribute is set if its assigned letter appears in x an odd number of times, cleared otherwise Query Permissions 7 boxed filename, or unboxed file number 0 A string of bytes, giving the system-dependent permissions. Each permission is either present or absent. Presence is indicated by an assigned letter, and absence by a dash (-). The assigned letters for Windows are: readable (r), writable (w), executable (x) Set Permissions A list of bytes, containing only assigned permission letters and - boxed filename, or unboxed file number 1 0 Result is 1 if there is no error. Each permission is set if its assigned letter appears in x an odd number of times, cleared otherwise Indexed Read 11 file;start[,length]
file is filename or file number. start is starting offset, length is number of bytes to read.
1 The bytes read from the file. start may be negative to count back from the end of the file. If length is omitted, the read goes to the end. Indexed Write a list of bytes 12 file;start
file is filename or file number. start is starting offset.
_ 1 x is written to the file file starting at byte offset start, replacing the previous contents if the file existed. start may be negative to count back from the end of the file. The length of the write is (#x). Result of the verb is (i. 0 0). Open Files 20 '' _ A table where each row contains
filenumber;filename
representing one file opened by 1!:21Open 21 boxed filename, or unboxed file number 0 The file is opened. The result is a file number: an integer that can be used to refer to the file. Repeated accesses to a file are faster using file numbers. Close 22 boxed filename, or unboxed file number 0 The file is closed and any locks released. The result is 1. Locks
(Windows only)30 '' _ A table where each row contains
filenumber,start,length
representing one lock established by 1!:31Lock File Region
(Windows only)31 filenumber,start,length
filenumber is a file number from 1!:20
1 The region is locked. Result is 1 if lock was granted, 0 if not. Unlock File Region
(Windows only)32 filenumber,start,length
filenumber is a file number from 1!:30
1 The lock is released. The result is 1. Query CWD 43 '' _ The current working directory, a list of bytes. Set CWD 44 The new working directory, a list of bytes _ Result is 0$0. Query DLL 46 '' _ The path to j.dll, a list of bytes. Erase File/Directory 55 boxed filename, or unboxed file number 0 The file or directory is erased. Error if file does not exist. Result is 1.
2!:n
m=2 (Host) Action n y Rank Result Execute Host Command 0 A character list 1 The list y is passed to the Host for execution. J waits for the command to finish, and the result from the host becomes the result of 2!:1. Not available in Windows. Spawn 1 A character list 1 Like 2!:0, but does not wait for completion. Result is ''. Unix only. Host I/O 2 1 First, two files are opened, appearing in the list returned by 1!:20 as
filenumber;'<',y
and
filenumber;'>',y
Then, y is passed to /bin/sh with the two files connected to stdin and stdout. The files should be closed using 1!:22 when no longer needed. Unix only.Wait 3 An integer 0 Wait for process id y to terminate, and return its status code as the result of 2!:3. Unix only. Getenv 5 A byte list 1 Return the value of the environment variable y, or Boolean 0 if not defined. GetPid 6 '' 1 The process ID of the J process. GetHw 7 '' 1 Hardware capabilities: '' or 'avx' or 'avx avx2' or ... ErrNo 8 '' 1 errno: boxed array of errno and strerror() Exit 55 integer _ No result - the J session terminates with return code y.
3!:n
m=3 (Conversions) Action x n y Rank Result Type/Precision 0 any noun _ A value indicating the type and precision of y. Byte Representation [an atom, one of 0 1 2 3] 1 any noun _ A list of bytes, giving the internal representation of the noun y. If x is given, the sentence
'longlong littleendian' =. 2 2 #: x
would set two names indicating word length (64 or 32 bits) and byte order. If x is omitted, the machine default is used (the PC is littleendian).Hex Representation [an atom, one of 0 1 2 3] 3 any noun _ Like 3!:1, but the result is a table, where each word of the result of 3!:1 (represented by 4 or 8 bytes) becomes one row, with each byte expressed as 2 displayable hexadecimal digits. Convert From Byte Or Hex Representation 2 The list or table resulting from 3!:1 or 3!:3 _ The noun represented by y Convert To J Integers _3 4 A list of bytes _ _ An integer list, each set of 8 bytes of y construed as a 64-bit integer (supported only in 64-bit versions of J) _2 A list of integers, each set of 4 bytes of y construed as a signed 32-bit integer _1 A list of integers, each set of 2 bytes of y construed as a signed 16-bit integer 0 A list of integers, each set of 2 bytes of y construed as an unsigned 16-bit integer Convert From J Integers 1 A numeric atom or list, with atoms tolerantly equal to integers representable in a machine word A list of bytes, 2 bytes per atom of y. Any higher significance is lost. 2 A list of bytes, 4 bytes per atom of y. Any higher significance is lost. 3 A list of bytes, 8 bytes per atom of y (supported only in 64-bit versions of J) Convert To J Floating-Point _2 5 A list of bytes _ _ A floating-point list, each set of 8 bytes of y construed as a 64-bit IEEE-754 floating-point value _1 A floating-point list, each set of 4 bytes of y construed as a 32-bit IEEE-754 floating-point value Convert From J Floating-Point 1 A numeric atom or list, in the range of a 64-bit IEEE floating-point value A list of bytes, 4 bytes per atom of y. Numbers too large or small for 32-bit representation are converted to infinity or zero. 2 A list of bytes, 8 bytes per atom of y. Lock Script 6 a list of bytes, containing the text of a script _ A list of encrypted bytes, the same shape as y, that can be loaded using load or 0!:n Convert to base64 10 an ASCII literal noun 1 The base64 representation of the noun Convert from base64 11 an ASCII literal noun containing a base64 representation 1 The ASCII text for the value Convert to lowercase/uppercase 0=tolower 1=toupper 12 any noun _ If datatype of the argument is literal,unicode2 or unicode4, convert to lowercase/uppercase. Otherwise no-op.
4!:n
m=4 (Names) Action x n y Rank Result Part Of Speech 0 boxed list of characters 0 The part of speech assigned to the name, if any:
_2=invalid, _1=undefined, 0=noun, 1=adverb, 2=conjunction, 3=verbIf the value of the objname[s] in an object locative are improper, an error is raised.
If the name contains a locative that refers to a numeric locale that has been erased, a locale error is raised.Defined Names [characters] 1 numeric where each atom is a part of speech number, or 6 meaning "locale" 0 The atoms of y indicate what names are requested. If 6 is among them, the names of all defined locales will be returned. The presence of values 0-3 requests the corresponding parts of speech from the names currently defined, either in the active private namespace or in the implied locale. If x is given, only names beginning with a letter in x will be returned. To execute 4!:1 in a specified locale l, assign 4!:1 to a name, say nlist, and execute nlist_l_ Script Names 3 '' _ The list of boxed filenames that have been invoked using 0!:n Which Script 4 boxed name 0 The index in (4!:3 '') of the script that loaded the name y, or _1 if not from a script Names Changed 5 0 or 1 0 4!:5 (0) turns off data collection; 4!:5 (1) turns it on and produces a list of global names assigned since the last execution of 4!:5 . Set Script Name 6 Literal list giving the string to use as script name 0 The string is added to the list of script names returned by 4!:3 if it is not there already. The result is the index of the string in that list. Set Script Number 7 The index of a script name in the list returned by 4!:3, or _1 to indicate no script 0 The number given will be used as the index of the script that is defining names. The result of 4!:7 is the previous value of the index. Create Cached Reference an ASCII list representing a well-formed name 8 N/A (4!:8 is an adverb - If the given name is a noun, the result is the noun. Otherwise the result is a cached reference to the given name, which must be defined. Erase Name 55 boxed name 0 Erases the name in y and frees its storage. The result is 0 if the name is invalid, otherwise 1.
5!:n
m=5 (Representation) Action x (m if y not given) n y Rank Result Define From AR (adverb) an atomic representation 0 The entity defined by the AR, which may have any part of speech Create AR 1 boxed name 0 The atomic representation (AR) of the name in y. The AR is an atomic box whose contents give the value of y, as follows: Type Example(s) Description of contents of AR AR(s) of example(s) primitive + F: list of the ASCII graphics of the primitive (<,'+') (<'F:') reference to named entity myverb verb name as an ASCII list (<'myverb') noun (1 2 3) 2 boxes: Boxed literal list '0' followed by boxed value ((<,'0') , (<1 2 3)) executed conjunction N0/V0 C1 N2/V2 <.@:* 2 boxes: AR of C1 followed by box containing list of 2 boxes: AR of N0/V0 followed by AR of N2/V2 ((<'@:'),<(<'<.'),(<,'*')) executed adverb N0/V0 A1 +/ 2 boxes: AR of A1 followed by box containing ravel of 1 box: AR of N0/V0 ((<,'/'),<,(<,'+')) hook V0 V1 (i. +:) 2 boxes: Boxed literal list '2' followed by box containing the ARs of the verbs of the hook, in order ((<,'2'),<(<'i.'),(<'+:')) fork N0/V0 V1 V2 (}. , {.) 2 boxes: Boxed literal list '3' followed by box containing the ARs of the words of the fork, in order ((<,'3'),<(<'}.'),(<,','),(<'{.')) Modifier train X0 X1 [X2] (]: @:) 2 boxes: Boxed literal list '4' followed by box containing the ARs of the words of the modifier, in order ((<,'4'),<(<']:'),(<'@:')) Boxed Display 2 boxed name 0 A list of boxes describing the value of the name Tree Display 4 A character table describing the value of the name Linear Display 5 A character list that, when executed, creates the value of the name Parenthesized Display 6 Like 5!:5, but fully parenthesized Linear Display, Single Valence 1 (monad) or 2 (dyad) 5 boxed name 0 0 The result is the same as 5!:5 y, except that for explicit definitions only the selected valence is shown, the : separator between valences is omitted, and the single-line form is not used. Note that this result may not be executable. Parsed Explicit Definition 1 or 2 7 boxed name 0 0 A table describing the valence given in x of the explicit entity named in y 6!:n
m=6 (Time) Action x n y Rank Result Get Current Time 0 character list, or empty list _ If y is empty, result is a 6-atom numeric list containing year,month,day,hour,minute,second. If y is a nonempty character list, result is a copy of y, with occurrences of the characters 'Y', 'M', 'D', 'h', 'm', and 's' are replaced by digits of the time, up to a maximum of 4, 2, 2, 2, 2, and 5 replacements respectively. Session Time 1 '' _ Number of seconds since J started running. Time Sentence [repetitions] 2 sentence, a list of characters 0 1 Time, averaged over repetitions attempts (default 1), to execute sentence. The time excludes preparation time (i. e. breaking the sentence into words and preliminary analysis) so as to give an accurate measure of how long the sentence will run if executed from an explicit definition. Example:
1e6 (6!:2) '+/ a' [ a =. 0. + i. 10000 5.9263e_7
shows that the time to sum 10000 floating-point atoms was 592ns, not counting the time to create the list.
Sentences run slightly faster in an explicit definition than from the keyboard. To get precise times for very short sentences you should take care to execute 6!:2 from within an explicit definition. The following verb does that:
NB. x is number of repetitions, y is (setup sentence);(timed sentence) etime =: {{ 'setup timed' =. _2 {. boxopen y 3 : (setup ; 'y 6!:2 ' , 5!:5 <'timed') x }} 1e8 etime 'a =. 1000';'a =. a + 1' 3.78431e_8 1e8 etime 'a =: 1000';'a =: a + 1' 7.34605e_8These results show that a sentence to increment a private counter took 38ns, while incrementing a public counter took 73ns. The difference is due to the extra searches required to find a public name and the extra locks needed to modify a public name.
Delay 3 number of seconds 0 Delay for y seconds. Count Parser Calls 4 '' _ Number of times parser has been called since J started running. This is a machine integer and may overflow. Query Clock Frequency 8 '' _ Used by Performance Monitor (PM) Query Clock Counter 9 PM Data Area [control info] 10 Unpack PM Data 11 Add to PM Counter 12 PM Statistics 13 Codes 14-17 convert between three representations of times: ISO 8601 timestamp, a list of bytes; nanosecond time, where the time is represented as a signed integer giving the offset in nanoseconds from the epoch, which is midnight on 2000/01/01; and digit time, where the time is represented as an integer whose digits are YYYYMMDDhhmmss. A time argument can be a single time or an array of times. The functions require 64-bit integers. Convert digit time to nanosecond time 14 Digit time _ Nanosecond time Convert nanosecond time to expanded digit time 15 Nanosecond time _ a 7-atom integer array for each time, giving year,month,day,hours,minutes,seconds,nanoseconds Convert nanosecond time to ISO 8601 time (optional) 3-atom list of bytes giving decimalpoint,timezonechar,precision 16 Nanosecond times _ ISO 8601 times, an array of bytes. The format depends on the arguments given in x. decimalpoint (default '.') gives the separator between integer and fractional seconds; timezonechar (default ' ') gives the character to append to the time to indicate the timezone; precision (default '0') gives the desired output precision, which can be 'd' (date only), '0' (date and time, with no fractional seconds), or '1'-'9' (date and time, with the specified number of fractional digits of seconds). The result is an array of shape (($y),n) where n depends on precision. If a time is outside the years 1800-2200, the corresponding result is the error string ?. Convert ISO 8601 time to nanosecond time [precision[;tzsec]] 17 Literal array of ISO 8601 times _ Array of nanosecond times, one for each ISO 8601 time. precision (default '9'), a single ASCII character, gives the number of fractional digits of precision preserved for the time, or 'd' to keep only the date. If tzsec is given, all UTC times (i. e. those ending with Z or +-hh) are converted to local time by adding tzsec to the UTC value. If a time is outside the years 1800-2200, the corresponding result is the error value, which is the smallest representable integer value. Convert DateTime string to nanosecond time [precision] 18 Literal array of datetime _ Array of string in common datetime formats such as mm/dd/yyyy . precision (default '9'), a single ASCII character, gives the number of fractional digits of precision preserved for the time, or 'd' to keep only the date.
7!:n
m=7 (Space) Action n y Rank Result Space In Use 0 '' _ The number of bytes currently in use in the current thread. OS memory in use, and high-water mark 1 '' or an atom that can be converted to integer _ 2-atom integer list (current number of bytes allocated from the OS,maximum allocation since most recent reset). If y is nonempty, the maximum value is reset to y. Measure Sentence 2 a list of characters _ The number of bytes used to execute the sentence y. Free Blocks 3 '' _ A table of the free blocks being managed by J's internal memory manager. Each row contains
blocksize,count
Space For Object 5 boxed name 0 Number of bytes used by the definition of the name in y Space For Locale 6 boxed name 0 Number of bytes used by the locale in y Space usage reported by OS 7 '' _ Number of bytes in use, as reported by the OS Space For All Threads 8 '' _ The total number of bytes in use in all threads. Before this value can be calculated, all threads must be brought to a stop at the end of a sentence, and released to run when the calculation is complete.
8!:n
m=8 (Format) Action x n y Rank Result Format Atoms The formatting string, a list of bytes 0 A numeric or character noun _ _ Each atom of y is converted to a boxed character list as specified by x. Format Columns 1 A numeric or character atom, list, or table Each column of y is converted to a boxed character table as specified by the corresponding formatting phrase in x. Format Table 2 Like 8!:1, but the columns are joined to create a single character table
9!:n
m=9 (Globals) All ranks are infinite. Values of n come in pairs: n is an even number to query a global value, odd to set the value. y should be an empty list for query (normally ''), and should have a valid value to set. The valid values are described in the table below. Action n
(Q)
n
(S)
Description of value Remarks RNG Initial State 0 1 An integer, or (for the Mersenne Twister RNG) a list of integers 9!:1 puts the selected RNG into an initial state that depends entirely on y Default Displays 2 3 An integer list with numbers selected from 1 2 4 5 6 with no duplicates Non-noun results will be displayed in each format 5!:a where a is an atom in x Nameref Caching 4 5 An integer: 0 to stop marking namerefs as cachable, 1 to mark namerefs encountered while loading the current script (not including scripts it loads), 2 to mark all namerefs encountered Nameref caching is a way to avoid searches through the search path of locale. It will speed up programs that use long search paths or make frequent use of locatives. Most scripts can execute 9!:5(1) near the top of the script without any other changes. A nameref is a word that refers to a named entity. It can be inside an explicit definition or in an executed sentence. When nameref caching is enabled, namerefs are marked as cachable when they are first encountered: for names in an executed sentence, that is when the nameref is parsed; for namerefs in an explicit definition, it is when the explicit definition is processed to produce a verb/adverb/conjunction (i. e. before the first execution of the body of the definition). Exception: indirect locatives, namerefs to names that are privately assigned in the explicit definition being processed, and namerefs created by 'name'~ are not marked as cachable.
When a nameref is cachable, the value found by looking up the name is remembered if it is found in a named locale and is not a noun. The remembered value will be used for subsequent lookups of the nameref without searching the search path again.
If a value that has been remembered in a nameref is modified, the old value is not deleted and continues to occupy space.
More discussion can be found here.
Boxing Characters 6 7 A list of 11 characters The characters will be used for displaying boxed nouns. Error Messages 8 9 A list of 33 boxed character lists. The messages may be modified only by the master thread. The error messages Print Precision 10 11 A numeric atom tolerantly equal to an integer Default precision used for display of numerics OS Type 12 An integer atom System type: UNIX (5), Windows (6), Windows CE (7), or _1 if other J Version 14 A character list Example: j602/2008-03-03/16:45 Boxed Display Positioning 16 17 A numeric atom or list, maximum length 2, each atom tolerantly one of 0 1 2 2$y is the value used for centering the contents of boxes. Comparison Tolerance 18 19 A value between 0 and 2^_44 The default comparison tolerance Memory Limit 20 21 A numeric value tolerantly equal to an integer The maximum size of a single memory allocation (initialized to 1/4 of the virtual address space) Fill element 22 The fill element used by the most recent primitive, or i. 0 0 if none Security Level 24 25 0 or 1 When set to 1, operations that affect the environment are disallowed Immex Sentence 26 27 A character list, containing a J sentence The sentence is executed as controlled by the Immex Flag (9!:29) Immex Flag 28 29 0 or 1 J is in immediate execution mode when it is waiting for keyboard input. It enters immediate execution mode when a top-level sentence completes execution. Possible sources of a top-level sentence are:
- the initialization of J including the starting script
- a sentence typed from the keyboard
- a sentence executed by an event handler
If the immex flag (set by 9!:29) is 1 when J enters immediate execution mode, the immex flag is cleared and then the immex sentence (set by 9!:27) is executed. The normal use for the immex flag is in events handlers, to provide an error handler or simulated user continuation. To provide an error handler, you set the immex flag to 1 on entry to the event, and clear it to 0 at normal exit. If the event handler fails with an error, the immex sentence will be executed. For user continuation, you set the immex sentence and flag just before your handler exits. The immex sentence will be the first thing executed. This allows you to execute the sentence in the user's locale rather than the locale of the event handler; and also to remove the event handler from the execution stack before the immex sentence executes.
Example code to put at the end of a script to cause firstsentence 0 to be executed after the script is loaded:
9!:27 'firstsentence 0'
9!:29 (1)Name that is executing 30 the byte string of the currently-executing entity's name, or if no name is executing Factoring retries 32 33 Integer in range 1-255 The number of random elliptic curves to try when factoring an extended integer using q: y. Default is 3. Enable assert. 34 35 0 or 1 If 0, assert. sentences are ignored. Default is 1. Output Control 36 37 A numeric list of length 4, tolerantly equal to integers The values control the display of results:
atom 0: 0 to end lines with LF, 2 for CRLF
atom 1: maximum line length; characters beyond this length are replaced with ...
atoms 2-3: the values of a and b. Only the first a and the last b lines of a long result are displayed, with the intervening lines replaced by ...
Default is 0 256 0 222Locale Hash-Table Sizes 38 39 A numeric list of length 2, tolerantly equal to integers The number of hashtable entries for named and numbered locales respectively is (_17 + 2 ^ 6 + y). Any value will produce correct results, but it is a good idea for the hashtable to have at least 30% more entries than the number of defined names. Retain Comments and Whitespace 40 41 ignored - 1 is assumed When 0, comments and surplus whitespace were formerly discarded from the saved form of explicit definitions, to save space. Default is 1. RNG Select 42 43 A numeric atom, tolerantly one of 0 1 2 3 4 Selects a random-number generator RNG State 44 45 An opaque internal value Saves/Restores the state of the random-number generator Break file 46 47 A character list, giving the break filename The break filename is the file that is used to break in to a long-running computation. Once set it cannot be modified. Allow intermediate results to be stored in a zombie name 52 53 a boolean atom 0=Do not allow; 1(default)=allow, including incomplete results. Display warning messages when inefficient code executed 54 55 number of messages;excluded message numbers A message will be typed in the session window for the first number of messages executions of inefficient code, not including those with excluded message numbers. If number of messages is negative, the first offending sentence will terminate with an error. CPU feature 56 cores cpu query various cpu features. Error message detail 59 previous value mask:1=suppress all detail; 2=suppress line#s; 4=suppress detailed analysis Indicate how much detail should be put into error messages. By default, errors are examined in detail (y=0). When u :: v or try. is executed, the setting is set to 7 (no detail) during the execution. - the initialization of J including the starting script
13!:n
m=13 (Debug) All ranks are infinite. When debugging is enabled, the interpreter keeps a stack of all named entities that are in execution. Execution may be suspended by an error or by encountering a line that a stop was set for by dbss. When execution is suspended, you can see the status of the executing name and its ancestors, perform single-step operations, or end the suspension to allow execution to resume. A sentence entered during suspension may itself also be suspended.
The following verbs are valid regardless of whether debugging is enabled or not. Name Action x
(if any)
n y Result dbr Enable Debug Suspension 0 0 Empty the debugging stack and disable debugging. 1 Remove one level of suspension from the stack, if there is one, and enable debugging. dbq Query Debug Suspension 17 '' Boolean result, 1 if debugging enabled dbsig Signal Error [optional character list] 8 a numeric noun whose first atom is tolerantly equal to an integer Error number ({.,y) is raised, with the error text changed to x if given
(default error text is (>:y) { 9!:8 '')
Signaling error number 55 has the same effect as throw.dberr Last Error Number 11 '' Result is an integer atom, the error number of the last error signaled dberm Last Error Message 12 '' Result is a character list, the text of the last error signaled Clear non-suspension result non-suspension value (default i. 0 0) 23 any noun The result is y if y is the result of a suspension command, otherwise x. The following verbs produce meaningful results only when debugging is enabled or postmortem debugging is active. dbs Display Stack 1 '' Brief form of the debug stack, which contains an entry for each named entity executed. The display for a name is a line of status (error message or executing line number) followed by the sentence that is being executed. dberr Set error number in threads A list of thread numbers 11 The error number to be set in the threads. May be a single atom or a list with the same length as x. An value of _1 indicates that the task should be terminated when debug suspension ends. The error number is set as specified. dbstk Stack Levels and Local Variables 13 List of desired column numbers, default to (i. 9) if empty The result is a table of boxes, each row having the status of one named entity being executed:
Col# What is shown 0 The name of the executing entity 1 Error number, or 0 if no error 2 Line number in explicit definition, or 0 if tacit definition 3 Name class of executing entity:1=adverb, 2=conjunction, 3=verb 4 Linear representation of the executing entity 5 Name of the script in which the entity was defined, if any 6 Argument(s) to the entity, individually boxed. For adverbs u is shown; for conjunctions u and v; for monadic verbs y; for dyadic verbs x and y. Arguments are not shown during postmortem debugging. 7 All locally-defined names, as a 2-column table of name and value. Tacit definitions have no local names. 8 '*' if the name started a suspension (i. e. if suspension was triggered in the name by a stop or an error), empty otherwise 9 The name/number of the implied locale of the executing entity 10 The 5!:7 representation of the executing entity if explicit, '' if tacit dbst Stack As Text 18 '' Like 13!:13, but in text form dbss Set Stops 3 stop info Explicit stops are requested by name and line number in the argument y, which contains zero or more stop specifications separated by semicolons. Each stop specification indicates a name, line numbers (if any) for the monadic case, a colon, and line numbers (if any) for the dyadic case. An asterisk indicates “all”, and a tilde indicates “except for”. Examples:
13!:3 'f 0' f monadic line 0 13!:3 'f :2' f dyadic line 2 13!:3 'f 0 2:1' f monadic 0 2, dyadic 1 13!:3 'f 0; g :*' f monadic 0 and g all dyadic 13!:3 '* 0:0' monadic 0 and dyadic 0 13!:3 'a* *:*; ~ab* *:*' All monadic and dyadic whose names begin with a, except for any beginning with ab dbstops N/A a list of names in string or boxed form Set the stops list to stop on each line of each name in y dbstop Append a stop on each line of each name in y to the current stops list dbsq Query Stops 2 '' The current stops text dblsx Set Latent Sentence 15 latent sentence The latent sentence is executed, as if entered from the keyboard, when execution is about to be suspended; error messages are suppressed; any continuation must be programmed in the latent sentence. dblsq Query Latent Sentence 14 '' The text of the latent sentence Insert Suspension 24 '' The current debug stack frame is marked as starting a suspension. This will ensure that the next suspension will include only frames after the current one. The following verbs terminate debug suspension, returning to normal execution. The specified action is performed when the result of the verb becomes the result of a sentence that was entered in response to a prompt from debug suspension. dbrun Run Again 4 '' Leave the current line number of the suspended entity unchanged, and resume execution by reexecuting that line in its entirety, after examining argument and parameter values and perhaps changing some. dbnxt Run Next 5 '' Advance the current line number of the suspended entity to the next line, and resume execution on that line. dbret Exit And Return 6 return result Exit the entity at the top of the stack, using y as its result. dbjmp Continue 7 line number Set the current line number of the suspended entity to y, and resume execution on that line. dbrr Rerun [x argument] 9 y argument The entity at the top of the stack must be a tacit verb. Resume execution by running that tacit verb with the argument(s) given. The following verbs perform single-step actions. That is, they terminate debug suspension, set a stop, and return to normal execution. If the debug suspension was caused by an error, the result of the sentence causing the error will be (i. 0 0) when execution resumes.
The specified action is performed when the result of the verb becomes the result of a sentence that was entered in response to a prompt from debug suspension.dbcut Cut Stack Back 19 '' The topmost stack frame is deleted. The execution of the sentence in the new topmost stack frame (i. e. the caller of the frame that was deleted) is aborted, and the caller suspends, with its current line set to reexecute the sentence that was aborted. dbover Step Over [line number] 20 '' If x is given, set the current line of the suspended entity to x. Resume execution, and stop after completion of the (possibly new) current line in the suspended entity. dbinto Step Into [line number] 21 '' If x is given, set the current line of the suspended entity to x. Resume execution, and stop before executing the next sentence in any explicit entity. dbout Step Out [line number] 22 '' If x is given, set the current line of the suspended entity to x. Resume execution, and stop immediately after the suspended entity returns. 15!:n
m=15 (DLL/memory) Action x (if any) n y Rank Result Call DLL character list identifying the function to be called and describing its arguments 0 arguments to the function 1 1 The DLL is called. Details are given here. If you get an error, run cder'' and look the error number up here. Allocate Memory 3 A numeric atom, tolerantly equal to an integer _ y bytes are allocated. The result is the memory address of the allocated region, or 0 if the allocation failed. Free Memory 4 A numeric atom _ The memory region at address y is freed. The result is 0 for success, 1 for failure. Read Memory 1 An integer list
addr,byteoffset,count[,precision]
_ Result is a list of count sequential atoms of the specified precision, read from the memory address at addr+byteoffset. The precision is restricted to one of 1=boolean 2=ASCII 4=integer 8=float 16=complex 131072=char2 262144=char4 (default 2). If precision is a character type, a count of _1 is allowed and means "read up to but not including the first zero atom" Write Memory A numeric noun 2 An integer list
addr,byteoffset,count[,precision]
_ _ (,x) is written to sequential atoms, having the specified precision, starting at the memory address at addr+byteoffset. The precision is restricted to one of 1=boolean 2=ASCII 4=integer 8=float 16=complex 131072=char2 262144=char4 (default 2). count must equal the number of atoms in (,x), except that if precision is a character type, count may be one more, to cause an atom of zero to be appended. The precision of x must match the precision in y, except that Boolean x is converted to integer and vice versa. The result is 0 0$0. Unalias Memory 15 Any noun
_ Same as (y), but possibly copied to a new memory area. Changes made to the result area (for example by a DLL) will have no side-effects. Free DLLs 5 '' _ ? Get address of symbol entry for name 6 A boxed name or an array of boxed names _ Deprecated. For each name, the integer address of the symbol for the name Use a header as a J entity 7 An integer returned by 15!:8 _ The previously-allocated header is put into play as a J entity Allocate header 8 An integer size _ Address of allocated header, an integer atom Free header 9 An integer returned by 15!:8 _ The header is freed cder 10 _ Error number from most recent cd cderx 11 _ Error text from most recent cd Get address of header for named value 12 A boxed name or an array of boxed names _ For each name, the integer address of the header (i. e. the A block) for the value Get address of data for named value 14 A boxed name or an array of boxed names _ For each name, the integer address of the data for the value Set callback address 13 Number of parameters the callback expects _ ? Set Native Front End state 16 new state (0 or 1) _ previous state Return Callback info 17 _ List of (Number of arguments set by most recent 15!:13),(pointer to array of callback addresses) Copy to aligned data block shape 18 any noun _ Result has the shape given by x, with its data area aligned to a cacheline boundary. The value of the result is the same as (x ($,) y). If x is omitted, the shape of y is used, and if y already has the correct alignment it is returned unchanged. If cells of the result have length that is an even multiple of the cacheline size, all of those cells will also be aligned.
Get address of header of value 19 any noun _ Result is the address of the header of the noun y Open DLL 20 boxed character string identifying the DLL _ Result is the OS handle to the DLLy
18!:n
m=18 (Locales) Action x n y Rank Result Locale Name Class 0 A boxed character list 0 Status of the string in y regarded as a locale name: Illegal (_2), Nonexistent (_1), Named (0), or Numbered (1) List Locale Names [character noun] 1 An atom or list all of whose atoms are tolerantly 0 or 1 _ _ _ List of locale names, including named and numbered locales according as y contains 0 or 1. If x is given, the named locales include only names whose initial letter is an atom of x. Query/Set Search Path [list of boxed locale names] 2 A boxed locale name 0 1 0 The monad returns the search path of locale y; the dyad sets the search path of y to x and returns a result of 0 0$0. Note: after the search path has been set, changing it requires interrupting all other threads, except for extending the search path from the beginning. Create Locale [numeric, tolerantly equal to an integer] By default a named locale is permanent; if x<0 the locale is impermanent. Numbered locales are always impermanent. 3 A boxed locale name, or an empty list _ 0 _ Create a locale, a new numbered one if y is empty, otherwise one named y (in which case the locale must not already contain names). (|+*) x, if given, overrides the default hash table size. Result is the boxed name of the created locale. Set Implied Locale 4 A locale name or number, possibly boxed _ Set the implied locale to y after this name exits. 18!:4 cannot be used directly, but only under the cover name cocurrent or coclass. The locale is created if it does not exist. Query Implied Locale 5 '' _ The implied locale, an integer or boxed character list. Recalculate Bloom filter 6 '' _ The name of a locale whose Bloom filter will be recalculated. The result contains internal system information. Erase Impermanent Locale 55 A locale number, as an integer, a boxed integer, or a boxed string _ If the locale y is not permanent, it is erased as soon as it finishes execution (that is, all verbs whose implied locale is y have finished). If you erase the locale that is the implied locale after all verbs have completed execution, the implied locale is set to z (example: type coerase <'base'). 18!:55 has no effect on permanent named locales: you can empty the locale by waiting until the locale has finished execution and then executing
(18!:6@(18!:5 [ 4!:55@nl)) '' in the locale, but the empty locale will survive.
128!:n
m=128 (Miscellaneous) Action x n y Rank Result QR Decomposition 0 A numeric matrix whose columns are linearly independent 2 A list of two boxes, containing Q and R, such that y -: Q +/ . * R. Q has orthogonal columns normalized to unit length (if it is square, it is unitary). R is upper-triangular. If y has shape m×n, Q is m×n and R is n×n. domain error if y has dependent columns. Invert Upper-Triangular R 1 An upper-triangular square matrix 2 The inverse of R. If R is singular, the result may contain infinities. Apply x to y A character list 2 Any noun 1 _ The character list x is executed and must produce a verb result. This resulting verb is applied to y to produce the result of 128!:2. CRC [A 2-element boxed list (p;i) or a numeric list or atom p.] 3 A list of bytes _ _ The 32-bit CRC of y using the polynomial p and initial value i. If i is omitted, _1 is used. The polynomial p, which is given LSB first (known as 'reversed representation' in the literature) may be represented as a Boolean list or an integer. If p is omitted, _306674912 (the standard CRC-32, 0xEDB88320), is used. RNG Raw 4 A numeric atom, tolerantly equal to an integer _ y numbers from the selected RNG. Used for debugging RNGs. Is NaN 5 Any noun _ Result has the shape of y, with each value 1 if and only if the corresponding atom of y is a NaN. Calculate SHA SHA type, default is 1. Result is a literal list: if x>0, of hexadecimal digits, otherwise binary codes 6 A literal noun 1 0 1 x selects the SHA type: 1=SHA1, 2=SHA224, 3=SHA256, 4=SHA384, 5=SHA512, 6=SHA3_224, 7=SHA3_256, 8=SHA3_384, 9=SHA3_512, 10=KECCAK_224, 11=KECCAK_256, 12=KECCAK_384, 13=KECCAK_512, 14=MD4, 15=MD5
Calculate AES A 3- or 4-element boxed list (de;key;iv[;mode]) 7 A literal noun _ _ de 0=encrypt, 1=decrypt
key A 16, 24 or 32-byte literal key for AES128, AES192 or AES256
iv A 16-byte literal initial vector
mode 'ecb' 'cbc' 'ctr' 'ecb nopad' 'cbc nopad' 'ctr nopad'
default to 'cbc' if elided
nopad y pads with null to multiple of 16 bytes
otherwise uses PKCS7 padding
iv is ignored for mode 'ecb' 'ecb nopad'Calculate 32-bit checksum Maximum value, or 0 for full 32 bits (0 if omitted) 8 Any noun _ _ A checksum is calculated for the noun. The checksum is a 32-bit CRC over the atoms of the noun. Checksums of different precisions with equal values may be different. Performing any arithmetic on a floating-point value may change its checksum. The checksum is a signed integer with 32-bit range. If x is omitted or 0, the result is the checksum itself; otherwise the result is an integer in the range [0,x). Matrix-sparse vector product (AVX2 only) 9 g;i;v;M[;toler] _ The sparse vector is specified as a list of indexes i and a list of values v. The product (i {"1 M) +/:1"1 v is calculated, and also the test value 0 e. g+.toler>:product. The result is test value;product with the exception that if test value is 1, product is undefined. toler defaults to 0 if omitted. LU decomposition 10 A non-singular square matrix 2 Result is (permutation);LU where LU=(L-I)+U with L and U being the LU decomposition of (permutation{y) in Doolittle form; that is, with 1s on the principal diagonal of L. In the result LU, the principal diagonal of L is omitted. Trim literal blank 0=dtb 1=dlb 2=dltb 11 A literal noun _ trim trailing blanks, leading blanks or both