X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?p=CreaPhase.git;a=blobdiff_plain;f=octave_packages%2Fio-1.0.19%2Fdoc-cache;fp=octave_packages%2Fio-1.0.19%2Fdoc-cache;h=59d6139eea8807aae0699f00c2ae4489899b83a5;hp=0000000000000000000000000000000000000000;hb=f5f7a74bd8a4900f0b797da6783be80e11a68d86;hpb=1705066eceaaea976f010f669ce8e972f3734b05 diff --git a/octave_packages/io-1.0.19/doc-cache b/octave_packages/io-1.0.19/doc-cache new file mode 100644 index 0000000..59d6139 --- /dev/null +++ b/octave_packages/io-1.0.19/doc-cache @@ -0,0 +1,1809 @@ +# Created by Octave 3.6.2, Sun Jun 17 08:16:48 2012 UTC +# name: cache +# type: cell +# rows: 3 +# columns: 28 +# name: +# type: sq_string +# elements: 1 +# length: 11 +append_save + + +# name: +# type: sq_string +# elements: 1 +# length: 799 + append_save M-file function + + Objective: be able to add variables to existing save files. Works for + all the types of save files that "save" supports. + + Input: + 1) A string which specifies the existing save file. + 2) The options you need to pass to the 'save' function to save to the + file type that you want. + 3) A 1x2 cell, with the first element being a string representation + of the variable/symbol that you're trying to add, followed by the + actual variable/symbol itself. + 4) Any number of additional 1x2 cells, following the same format as + the 3rd argument specified immediately before this one. + + Output: + Currently, none. But there might be some debugging / error-code + messages in the future. + + Example: + octave> B = ones(2,2); + octave> append_save( "test.txt", "-binary", {"B", B } ) + + + +# name: +# type: sq_string +# elements: 1 +# length: 29 + append_save M-file function + + + + +# name: +# type: sq_string +# elements: 1 +# length: 15 +calccelladdress + + +# name: +# type: sq_string +# elements: 1 +# length: 239 + calccelladdress (R, C) - compute spreadsheet style cell address from + row & column index (both 1-based). + + Max column index currently set to 18278 (max ODS: 1024, OOXML: 16384). + Row limits for ODF and OOXML are 65536 and 1048576, resp. + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 + calccelladdress (R, C) - compute spreadsheet style cell address from + row & col + + + +# name: +# type: sq_string +# elements: 1 +# length: 23 +chk_spreadsheet_support + + +# name: +# type: sq_string +# elements: 1 +# length: 2406 + Check Octave / Matlab environment for spreadsheet I/O support. + + usage: [ RETVAL ] = chk_spreadsheet_support ( [/PATH/TO/JARS], [,DEBUG_LEVEL] [,PATH_TO_OOO]) + + CHK_SPREADSHEET_SUPPORT first checks ActiveX (native MS-Excel); then + Java JRE presence, then Java support (builtin/activated (Matlab) or + added tru octave-forge Java package (Octave); then check existing + javaclasspath for Java class libraries (.jar) needed for various + Java-based spreadsheet I/O interfaces. + If desired the relevant classes can be added to the dynamic + javaclasspath. In that case the path name to the directory + containing these classes should be specified as input argument + with -TAKE NOTICE- /forward/ slashes. In these jars reside in + different directories, multiple calls to chk_spreadsheet_support + can be made. + + Input arguments (all are optional, but the order is important): + /PATH/TO/JARS = (string) path (relative or absolute) to a + subdirectory where java class libraries (.jar) + for spreadsheet I/O reside. Can be [] or '' + DEBUG_LEVEL = (integer) between [0 (no output) .. 3 (full output] + PATH_TO_OOO = (string) installation directory of Openffice.org, + usually (but not guaranteed): + - Windows: C:\Program Files\OpenOffice.org + - *nix: /usr/lib/ooo + - Mac OSX: ????? + IMPORTANT: PATH_TO_OOO should be such that both: + 1. PATH_TO_OOO/program/ + and + 2. PATH_TO_OOO/ure/.../ridl.jar + resolve OK + Returns: + RETVAL = 0 No spreadsheet I/O support found + <> 0 At least one spreadsheet I/O interface found. RETVAL + RETVAL will be set to the sum of values for found interfaces: + ---------- XLS (Excel) interfaces: ---------- + 1 = COM (ActiveX / Excel) + 2 = POI (Java / Apache POI) + 4 = POI+OOXML (Java / Apache POI) + 8 = JXL (Java / JExcelAPI) + 16 = OXS (Java / OpenXLS) + --- ODS (OpenOffice.org Calc) interfaces ---- + 32 = OTK (Java/ ODF Toolkit) + 64 = JOD (Java / jOpenDocument) + ----------------- XLS & ODS: ---------------- + 128 = UNO (Java / UNO bridge - OpenOffice.org) + + + +# name: +# type: sq_string +# elements: 1 +# length: 63 + Check Octave / Matlab environment for spreadsheet I/O support. + + + +# name: +# type: sq_string +# elements: 1 +# length: 6 +fexist + + +# name: +# type: sq_string +# elements: 1 +# length: 680 + -- Function File: ex = fexist (file, tspec, aspec) + Checks whether a file exists. FILE is the queried file path. + TSPEC is a combination of letters f,d,p,S, corresponding to file + types: + * f: regular file + + * d: directory + + * p: named pipe (FIFO special file) + + * S: socket + + The query is true if the actual file type matches any of the + specified options. + + ASPEC is a combination of letters r,w,x, corresponding to queried + access privileges to the file. The query is true if the current + user has all the spefied types of access, either through "user", + "group" or "other" specs. + + See also: stat, lstat + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 29 +Checks whether a file exists. + + + +# name: +# type: sq_string +# elements: 1 +# length: 12 +getusedrange + + +# name: +# type: sq_string +# elements: 1 +# length: 1637 + -- Function File: [ TOPROW#, BOTTOMROW#, LEFTCOL#, RIGHTCOL# ] = + getusedrange (SPPTR, SHINDEX#) + Find occupied data range in worksheet SHINDEX# in a spreadsheet + pointed to in struct SPPTR (either MS-Excel or OpenOffice_org + Calc). + + SHINDEX# must be numeric and is 1-based. SPPTR can either refer to + an MS-Excel spreadsheet (spptr returned by xlsopen) or an + OpenOffice.org Calc spreadsheet (spptr returned by odsopen). None + of these inputs are checked! + + Be aware that especially for OpenOffice.org Calc (ODS) spreadsheets + the results can only be obtained by counting all cells in all rows; + this can be fairly time-consuming. Reliable ods data size results + can only be obtained using UNO interface. For the ActiveX (COM) + interface the underlying Visual Basic call relies on cached range + values and counts empty cells with only formatting too, so COM + returns only approximate (but then usually too big) range values. + + Examples: + + [trow, brow, lcol, rcol] = getusedrange (ods2, 3); + (which returns the outermost row & column numbers of the rectangle + enveloping the occupied cells in the third sheet of an OpenOffice_org + Calc spreadsheet pointedto in struct ods2) + + [trow, brow, lcol, rcol] = getusedrange (xls3, 3); + (which returns the outermost row & column numbers of the rectangle + enveloping the occupied cells in the third sheet of an Excel + spreadsheet pointed to in struct xls3) + + See also: xlsopen, xlsclose, odsopen, odsclose, xlsfinfo, odsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Find occupied data range in worksheet SHINDEX# in a spreadsheet pointed +to in st + + + +# name: +# type: sq_string +# elements: 1 +# length: 17 +io_ods_testscript + + +# name: +# type: sq_string +# elements: 1 +# length: 180 + (Internal function) Check proper operation of ODS spreadsheet scripts. + Before running, a character variable 'intf' should be initialized with + a value of 'otk', 'jod', or 'uno'. + + + +# name: +# type: sq_string +# elements: 1 +# length: 71 + (Internal function) Check proper operation of ODS spreadsheet scripts. + + + +# name: +# type: sq_string +# elements: 1 +# length: 17 +io_xls_testscript + + +# name: +# type: sq_string +# elements: 1 +# length: 194 + (Internal function) Check proper operation of XLS spreadsheet scripts. + Before running, a character variable 'intf' should be initialized with + a value of 'com', 'poi', 'jxl', 'oxs', or 'uno'. + + + +# name: +# type: sq_string +# elements: 1 +# length: 71 + (Internal function) Check proper operation of XLS spreadsheet scripts. + + + +# name: +# type: sq_string +# elements: 1 +# length: 11 +object2json + + +# name: +# type: sq_string +# elements: 1 +# length: 1521 + Returns a valid json string that will describe object; the string will + be in a compact form (no spaces or line breaks). + + It will map simple octave values this way: + function handles: string with the name of the function + double (numbers): depends: + If it's real it will map to a string representing that number + If it's complex it will map to an object with the next properties: + real: real part of the number + imag: imaginary part of the number + char: A string enclosed by double quotes representing that character + And will map more complex octave values this other way: + struct: an object with properties equal to the struct's field names + and value equal to the json counterpart of that field + cell: it will be mapped depending on the value of the cell (for + example {i} will be mapped to an object with real=0 and imag=1) + vectors or cell arrays: it will map them to a corresponding js + array (same size) with the values transformed to their json + counterpart (Note: that in javascript all arrays are like octave's + cells ,i.e. they can store different type and size variables) + strings or char vectors: they will be mapped to the same string + enclosed by double quotes + Other octave values will be mapped to a string enclosed by double + quotes with the value that the class() function returns + It can handle escape sequences and special chars automatically. + If they're valid in JSON it will keep them if not they'll be + escaped so they can become valid + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 + Returns a valid json string that will describe object; the string will + be in a + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +oct2ods + + +# name: +# type: sq_string +# elements: 1 +# length: 3268 + -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS) + -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS, WSH) + -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS, WSH, RANGE) + -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS, WSH, RANGE, + OPTIONS) + Transfer data to an OpenOffice_org Calc spreadsheet previously + opened by odsopen(). + + Data in 1D/2D array ARR are transferred into a cell range RANGE in + sheet WSH. ODS must have been made earlier by odsopen(). Return + argument ODS should be the same as supplied argument ODS and is + updated by oct2ods. A subsequent call to odsclose is needed to + write the updated spreadsheet to disk (and -if needed- close the + Java invocation holding the file pointer). + + ARR can be any 1D or 2D array containing numerical or character + data (cellstr) except complex. Mixed numeric/text arrays can only + be cell arrays. + + ODS must be a valid pointer struct created earlier by odsopen. + + WSH can be a number (sheet name) or string (sheet number). In + case of a yet non-existing Calc file, the first sheet will be used + & named according to WSH. In case of existing files, some checks + are made for existing sheet names or numbers. When new sheets are + to be added to the Calc file, they are inserted to the right of + all existing sheets. The pointer to the "active" sheet (shown when + Calc opens the file) remains untouched. + + If RANGE omitted, the top left cell where the data will be put is + supposed to be 'A1'; only a top left cell address can be specified + as well. In these cases the actual range to be used is determined + by the size of ARR. Be aware that large data array sizes may + exhaust the java shared memory space. For larger arrays, + appropriate memory settings are needed in the file java.opts; then + the maximum array size for the java-based spreadsheet options can + be in the order of perhaps 10^6 elements. + + Optional argument OPTIONS, a structure, can be used to specify + various write modes. Currently the only option field is + "formulas_as_text", which -if set to 1 or TRUE- specifies that + formula strings (i.e., text strings starting with "=" and ending + in a ")" ) should be entered as litteral text strings rather than + as spreadsheet formulas (the latter is the default). As + jOpenDocument doesn't support formula I/O at all yet, this option + is ignored for the JOD interface. + + Data are added to the sheet, ignoring other data already present; + existing data in the range to be used will be overwritten. + + If RANGE contains merged cells, also the elements of ARR not + corresponding to the top or left Calc cells of those merged cells + will be written, however they won't be shown until in Calc the + merge is undone. + + Examples: + + [ods, status] = ods2oct (arr, ods, 'Newsheet1', 'AA31:GH165'); + Write array arr into sheet Newsheet1 with upperleft cell at AA31 + + [ods, status] = ods2oct ({'String'}, ods, 'Oldsheet3', 'B15:B15'); + Put a character string into cell B15 in sheet Oldsheet3 + + See also: ods2oct, odsopen, odsclose, odsread, odswrite, odsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Transfer data to an OpenOffice_org Calc spreadsheet previously opened +by odsopen + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +oct2xls + + +# name: +# type: sq_string +# elements: 1 +# length: 3321 + -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS) + -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS, WSH) + -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS, WSH, RANGE) + -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS, WSH, RANGE, + OPTIONS) + Add data in 1D/2D CELL array ARR into a cell range specified in + RANGE in worksheet WSH in an Excel spreadsheet file pointed to in + structure XLS. Return argument XLS equals supplied argument XLS + and is updated by oct2xls. + + A subsequent call to xlsclose is needed to write the updated + spreadsheet to disk (and -if needed- close the Excel or Java + invocation). + + ARR can be any 1D or 2D array containing numerical or character + data (cellstr) except complex. Mixed numeric/text arrays can only + be cell arrays. + + XLS must be a valid pointer struct created earlier by xlsopen. + + WSH can be a number or string (max. 31 chars). In case of a yet + non-existing Excel file, the first worksheet will be used & named + according to WSH - extra empty worksheets that Excel creates by + default are deleted. In case of existing files, some checks are + made for existing worksheet names or numbers, or whether WSH + refers to an existing sheet with a type other than worksheet + (e.g., chart). When new worksheets are to be added to the Excel + file, they are inserted to the right of all existing worksheets. + The pointer to the "active" sheet (shown when Excel opens the + file) remains untouched. + + If RANGE is omitted or just the top left cell of the range is + specified, the actual range to be used is determined by the size of + ARR. If nothing is specified for RANGE the top left cell is + assumed to be 'A1'. + + Data are added to the worksheet, ignoring other data already + present; existing data in the range to be used will be overwritten. + + If RANGE contains merged cells, only the elements of ARR + corresponding to the top or left Excel cells of those merged cells + will be written, other array cells corresponding to that cell will + be ignored. + + Optional argument OPTIONS, a structure, can be used to specify + various write modes. Currently the only option field is + "formulas_as_text", which -if set to 1 or TRUE- specifies that + formula strings (i.e., text strings starting with "=" and ending + in a ")" ) should be entered as litteral text strings rather than + as spreadsheet formulas (the latter is the default). + + Beware that -if invoked- Excel invocations may be left running + silently in case of COM errors. Invoke xlsclose with proper + pointer struct to close them. When using Java, note that large + data array sizes elements may exhaust the Java shared memory space + for the default java memory settings. For larger arrays, + appropriate memory settings are needed in the file java.opts; then + the maximum array size for the Java-based spreadsheet options may + be in the order of 10^6 elements. In caso of UNO this limit is not + applicable and spreadsheets may be much larger. + + Examples: + + [xlso, status] = xls2oct ('arr', xlsi, 'Third_sheet', 'AA31:AB278'); + + See also: xls2oct, xlsopen, xlsclose, xlsread, xlswrite, xlsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Add data in 1D/2D CELL array ARR into a cell range specified in RANGE +in workshe + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +ods2oct + + +# name: +# type: sq_string +# elements: 1 +# length: 3684 + -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS) + -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS, WSH) + -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS, WSH, RANGE) + -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS, WSH, RANGE, + OPTIONS) + Read data contained within cell range RANGE from worksheet WSH in + an OpenOffice_org Calc spreadsheet file pointed to in struct ODS. + + ODS is supposed to have been created earlier by odsopen in the + same octave session. + + WSH is either numerical or text, in the latter case it is + case-sensitive. Note that in case of a numerical WSH this number + refers to the position in the worksheet stack, counted from the + left in a Calc window. The default is numerical 1, i.e. the + leftmost worksheet in the ODS file. + + RANGE is expected to be a regular spreadsheet range format, or "" + (empty string, indicating all data in a worksheet). If no range + is specified the occupied cell range will have to be determined + behind the scenes first; this can take some time. + + Optional argument OPTIONS, a structure, can be used to specify + various read modes by setting option fields in the struct to true + (1) or false (0). Currently recognized option fields are: + + "formulas_as_text" + If set to TRUE or 1, spreadsheet formulas (if at all present) + are read as formula strings rather than the evaluated formula + result values. This only works for the OTK and UNO interfaces. + The default value is 0 (FALSE). + + 'strip_array' + Set the value of this field set to TRUE or 1 to strip the + returned output array RAWARR from empty outer columns and + rows. The spreadsheet cell rectangle limits from where the + data actually came will be updated. The default value is + FALSE or 0 (no cropping). + + If only the first argument ODS is specified, ods2oct will try to + read all contents from the first = leftmost (or the only) + worksheet (as if a range of '' (empty string) was specified). + + If only two arguments are specified, ods2oct assumes the second + argument to be WSH. In that case ods2oct will try to read all data + contained in that worksheet. + + Return argument RAWARR contains the raw spreadsheet cell data. + Use parsecell() to separate numeric and text values from RAWARR. + + Optional return argument ODS contains the pointer struct. Field + ODS.limits contains the outermost column and row numbers of the + actually read cell range. + + Optional return argument RSTATUS will be set to 1 if the requested + data have been read successfully, 0 otherwise. + + Erroneous data and empty cells turn up empty in RAWARR. Date/time + values in OpenOffice.org are returned as numerical values with + base 1-1-0000 (same as octave). But beware that Excel spreadsheets + rewritten by OpenOffice.org into .ods format may have numerical + date cells with base 01-01-1900 (same as MS-Excel). + + When reading from merged cells, all array elements NOT + corresponding to the leftmost or upper OpenOffice.org cell will be + treated as if the "corresponding" cells are empty. + + Examples: + + A = ods2oct (ods1, '2nd_sheet', 'C3:ABS40000'); + (which returns the numeric contents in range C3:ABS40000 in worksheet + '2nd_sheet' from a spreadsheet file pointed to in pointer struct ods1, + into numeric array A) + + [An, ods2, status] = ods2oct (ods2, 'Third_sheet'); + + See also: odsopen, odsclose, parsecell, odsread, odsfinfo, + oct2ods, odswrite + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Read data contained within cell range RANGE from worksheet WSH in an +OpenOffice_ + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +odsclose + + +# name: +# type: sq_string +# elements: 1 +# length: 1547 + -- Function File: [ ODS] = odsclose (ODS) + -- Function File: [ ODS] = odsclose (ODS, FILENAME) + -- Function File: [ ODS] = odsclose (ODS, "FORCE") + Close the OpenOffice_org Calc spreadsheet pointed to in struct + ODS, if needed write the file to disk. odsclose will determine if + the file must be written to disk based on information contained in + ODS. An empty pointer struct will be returned if no errors + occurred. Optional argument FILENAME can be used to write changed + spreadsheet files to an other file than opened by odsopen(). + Optional string argument "FORCE" can be specified to force + resetting the file pointer struct. However, in case of UNO, a + hidden OOo invocation may linger on in memory then, preventing + proper closing of Octave. + + You need the Java package >= 1.2.6 plus odfdom.jar + xercesImpl.jar + and/or jopendocument-.jar installed on your computer + + proper javaclasspath set, to make this function work at all. For + UNO support, Octave-Java package >= 1.2.8 + latest fixes is + imperative; furthermore the relevant classes had best be added to + the javaclasspath by utility function chk_spreadsheet_support(). + + ODS must be a valid pointer struct made by odsopen() in the same + octave session. + + Examples: + + ods1 = odsclose (ods1); + (Close spreadsheet file pointed to in pointer struct ods1; ods1 is reset) + + See also: odsopen, odsread, odswrite, ods2oct, oct2ods, odsfinfo, + chk_spreadsheet_support + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Close the OpenOffice_org Calc spreadsheet pointed to in struct ODS, if +needed wr + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +odsfinfo + + +# name: +# type: sq_string +# elements: 1 +# length: 1703 + -- Function File: [ FILETYPE] = odsfinfo (FILENAME [, REQINTF]) + -- Function File: [ FILETYPE, SH_NAMES] = odsfinfo (FILENAME [, + REQINTF]) + Query an OpenOffice_org spreadsheet file FILENAME (with ods + suffix) for some info about its contents. + + If FILENAME is a recognizable OpenOffice.org spreadsheet file, + FILETYPE returns the string "OpenOffice.org Calc spreadsheet", or + '' (empty string) otherwise. + + If FILENAME is a recognizable OpenOffice.org Calc spreadsheet + file, optional argument SH_NAMES contains a list (cell array) of + sheet names contained in FILENAME, in the order (from left to + right) in which they occur in the sheet stack. + + If you omit return arguments FILETYPE and SH_NAMES altogether, + odsfinfo returns the sheet names and for each sheet the actual + occupied data ranges to the screen.The occupied cell range will + have to be determined behind the scenes first; this can take some + time. + + odsfinfo execution can take its time for large spreadsheets as the + entire spreadsheet has to be parsed to get the sheet names, let + alone exploring used data ranges. + + By specifying a value of 'jod', 'otk' or 'uno' for REQINTF the + automatic selection of the java interface is bypassed and the + specified interface will be used (if at all present). + + Examples: + + exist = odsfinfo ('test4.ods'); + (Just checks if file test4.ods is a readable Calc file) + + [exist, names] = odsfinfo ('test4.ods'); + (Checks if file test4.ods is a readable Calc file and return a + list of sheet names) + + See also: odsread, odsopen, ods2oct, odsclose + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Query an OpenOffice_org spreadsheet file FILENAME (with ods suffix) for +some inf + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +odsopen + + +# name: +# type: sq_string +# elements: 1 +# length: 2296 + -- Function File: ODS = odsopen (FILENAME) + -- Function File: ODS = odsopen (FILENAME, READWRITE) + -- Function File: ODS = odsopen (FILENAME, READWRITE, REQINTF) + Get a pointer to an OpenOffice_org spreadsheet in the form of + return argument ODS. + + Calling odsopen without specifying a return argument is fairly + useless! + + To make this function work at all, you need the Java package >= + 1.2.5 plus ODFtoolkit (version 0.7.5 or 0.8.6+) & xercesImpl, + and/or jOpenDocument, and/or OpenOffice.org (or clones) installed + on your computer + proper javaclasspath set. These interfaces are + referred to as OTK, JOD, and UNO resp., and are preferred in that + order by default (depending on their presence). For (currently + experimental) UNO support, Octave-Java package 1.2.8 + latest + fixes is imperative; furthermore the relevant classes had best be + added to the javaclasspath by utility function + chk_spreadsheet_support(). + + FILENAME must be a valid .ods OpenOffice.org file name including + .ods suffix. If FILENAME does not contain any directory path, the + file is saved in the current directory. For UNO bridge, filenames + need to be in the form "file:////filename"; a URL + will also work. If a plain file name is given (absolute or + relative), odsopen() will transform it into proper form. + + READWRITE must be set to true or numerical 1 if writing to + spreadsheet is desired immediately after calling odsopen(). It + merely serves proper handling of file errors (e.g., "file not + found" or "new file created"). + + Optional input argument REQINTF can be used to override the ODS + interface automatically selected by odsopen. Currently implemented + interfaces are 'OTK' (Java/ODF Toolkit), 'JOD' + (Java/jOpenDocument) and 'UNO' (Java/OpenOffice.org UNO bridge). + + Examples: + + ods = odsopen ('test1.ods'); + (get a pointer for reading from spreadsheet test1.ods) + + ods = odsopen ('test2.ods', [], 'JOD'); + (as above, indicate test2.ods will be read from; in this case using + the jOpenDocument interface is requested) + + See also: odsclose, odsread, oct2ods, ods2oct, odsfinfo, + chk_spreadsheet_support + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Get a pointer to an OpenOffice_org spreadsheet in the form of return +argument OD + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +odsread + + +# name: +# type: sq_string +# elements: 1 +# length: 4428 + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread + (FILENAME) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread + (FILENAME, WSH) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread + (FILENAME, WSH, RANGE) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread + (FILENAME, WSH, RANGE, REQINTF) + Read data contained from cell range RANGE in worksheet WSH in + OpenOffice_org Calc spreadsheet file FILENAME. + + You need the octave-forge java package (> 1.2.6) and one or both of + jopendocument-.jar or preferrably: (odfdom.jar (versions + 0.7.5 or 0.8.6+) & xercesImpl.jar v. 2.9.1) in your javaclasspath. + There is also experimental support invoking OpenOffice.org or + clones through Java/UNO bridge. + + Return argument NUMARR contains the numeric data, optional return + arguments TXTARR and RAWARR contain text strings and the raw + spreadsheet cell data, respectively, and LIMITS is a struct + containing the data origins of the various returned arrays. + + If FILENAME does not contain any directory, the file is assumed to + be in the current directory. FILENAME should include the filename + extension (.ods). + + WSH is either numerical or text, in the latter case it is + case-sensitive and it should conform to OpenOffice.org Calc sheet + name requirements. Note that in case of a numerical WSH this + number refers to the position in the worksheet stack, counted from + the left in a Calc window. The default is numerical 1, i.e. the + leftmost worksheet in the Calc file. + + RANGE is expected to be a regular spreadsheet range format, or "" + (empty string, indicating all data in a worksheet). If no range + is specified the occupied cell range will have to be determined + behind the scenes first; this can take some time. + + If only the first argument is specified, odsread will try to read + all contents from the first = leftmost (or the only) worksheet (as + if a range of '' (empty string) was specified). + + If only two arguments are specified, odsread assumes the second + argument to be WSH and to refer to a worksheet. In that case + odsread tries to read all data contained in that worksheet. + + The optional last argument REQINTF can be used to override the + automatic selection by odsread of one interface out of the + supported ones: Java/ODFtoolkit ('OTK'), Java/jOpenDocument + ('JOD') or Java/UNO bridge ('UNO'). + + Erroneous data and empty cells are set to NaN in NUMARR and turn + up empty in TXTARR and RAWARR. Date/time values in date/time + formatted cells are returned as numerical values in OBJ with base + 1-1-000. Note that OpenOfice.org and MS-Excel have different date + base values (1/1/0000 & 1/1/1900, resp.) and internal + representation so MS-Excel spreadsheets rewritten into .ods format + by OpenOffice.org Calc may have different date base values. + + NUMARR and TXTARR are trimmed from empty outer rows and columns, + so any returned array may turn out to be smaller than requested in + RANGE. + + When reading from merged cells, all array elements NOT + corresponding to the leftmost or upper Calc cell will be treated + as if the "corresponding" Calc cells are empty. + + odsread is just a wrapper for a collection of scripts that find out + the interface to be used and do the actual reading. For each call + to odsread the interface must be started and the Calc file read + into memory. When reading multiple ranges (in optionally multiple + worksheets) a significant speed boost can be obtained by invoking + those scripts directly (odsopen / ods2oct [/ parsecell] / ... / + odsclose). + + Examples: + + A = odsread ('test4.ods', '2nd_sheet', 'C3:AB40'); + (which returns the numeric contents in range C3:AB40 in worksheet + '2nd_sheet' from file test4.ods into numeric array A) + + [An, Tn, Ra, limits] = odsread ('Sales2009.ods', 'Third_sheet'); + (which returns all data in worksheet 'Third_sheet' in file test4.ods + into array An, the text data into array Tn, the raw cell data into + cell array Ra and the ranges from where the actual data came in limits) + + See also: odsopen, ods2oct, oct2ods, odsclose, odswrite, odsfinfo, + parsecell + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Read data contained from cell range RANGE in worksheet WSH in +OpenOffice_org Cal + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +odswrite + + +# name: +# type: sq_string +# elements: 1 +# length: 3168 + -- Function File: RSTATUS = odswrite (FILENAME, ARR) + -- Function File: RSTATUS = odswrite (FILENAME, ARR, WSH) + -- Function File: RSTATUS = odswrite (FILENAME, ARR, WSH, RANGE) + -- Function File: RSTATUS = odswrite (FILENAME, ARR, WSH, RANGE, + REQINTF) + Add data in 1D/2D array ARR into sheet WSH in OpenOffice_org Calc + spreadsheet file FILENAME in cell range RANGE. + + RSTATUS returns 1 if write succeeded, 0 otherwise. + + FILENAME must be a valid .ods OpenOffice.org file name (including + file name extension). If FILENAME does not contain any directory + path, the file is saved in the current directory. + + ARR can be any 1D or 2D array containing numerical or character + data (cellstr) except complex. Mixed numeric/text arrays can only + be cell arrays. + + WSH can be a number or string. In case of a not yet existing + OpenOffice.org spreadsheet, the first sheet will be used & named + according to WSH - no extra empty sheets are created. In case of + existing files, some checks are made for existing sheet names or + numbers, or whether WSH refers to an existing sheet with a type + other than sheet (e.g., chart). When new sheets are to be added + to the spreadsheet file, they are inserted to the right of all + existing sheets. The pointer to the "active" sheet (shown when + OpenOffice.org Calc opens the file) remains untouched. + + RANGE is expected to be a regular spreadsheet range. Data is + added to the sheet; existing data in the requested range will be + overwritten. Array ARR will be clipped at the right and/or bottom + if its size is bigger than can be accommodated in RANGE. If ARR + is smaller than the RANGE allows, it is placed in the top left + rectangle of RANGE and cell values outside that rectangle will be + untouched. + + If RANGE contains merged cells, only the elements of ARR + corresponding to the top or left Calc cells of those merged cells + will be written, other array cells corresponding to that cell will + be ignored. + + The optional last argument REQINTF can be used to override the + automatic selection by odswrite of one interface out of the + supported ones: Java/ODFtooolkit ('OTK'), Java/jOpenDocument + ('JOD'), or Java/OpenOffice.org ('UNO'). + + odswrite is a mere wrapper for various scripts which find out what + ODS interface to use (ODF toolkit or jOpenDocument) plus code to + mimic the other brand's syntax. For each call to odswrite such an + interface must be started and possibly an ODS file loaded. When + writing to multiple ranges and/or worksheets in the same ODS file, + a speed bonus can be obtained by invoking those scripts (odsopen / + octods / .... / odsclose) directly. + + Example: + + status = odswrite ('test4.ods', 'arr', 'Eight_sheet', 'C3:AB40'); + (which adds the contents of array arr (any type) to range C3:AB40 + in sheet 'Eight_sheet' in file test4.ods and returns a logical + True (= numerical 1) in status if al went well) + + See also: odsread, oct2ods, ods2oct, odsopen, odsclose, odsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Add data in 1D/2D array ARR into sheet WSH in OpenOffice_org Calc +spreadsheet fi + + + +# name: +# type: sq_string +# elements: 1 +# length: 14 +parse_sp_range + + +# name: +# type: sq_string +# elements: 1 +# length: 199 + Parse a string representing a range of cells for a spreadsheet + into nr of rows and nr of columns and also extract top left + cell address + top row + left column. Some error checks are implemented. + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 + Parse a string representing a range of cells for a spreadsheet + into nr of rows + + + +# name: +# type: sq_string +# elements: 1 +# length: 9 +parsecell + + +# name: +# type: sq_string +# elements: 1 +# length: 1431 + -- Function File: [ NUMARR, TXTARR, LIM ] = parsecell (RAWARR) + -- Function File: [ NUMARR, TXTARR, LIM ] = parsecell (RAWARR, LIMITS) + Divide a heterogeneous 2D cell array into a 2D numeric array and a + 2D cell array containing only strings. Both returned arrays are + trimmed from empty outer rows and columns. This function is + particularly useful for parsing cell arrays returned by functions + reading spreadsheets (e.g., xlsread, odsread). + + Optional return argument LIM contains two field with the outer + column and row numbers of NUMARR and TXTARR in the original array + RAWARR. Optional input argument LIMITS can either be the + spreadsheet data limits returned in the spreadsheet file pointer + struct (field xls.limits or ods.limits), or the file ptr struct + itself. If one of these is specified, optional return argument LIM + will contain the real spreadsheet row & column numbers enclosing + the origins of the numerical and text data returned in NUMARR and + TXTARR. + + Examples: + + [An, Tn] = parsecell (Rn); + (which returns the numeric contents of Rn into array An and the + text data into array Tn) + + [An, Tn, lims] = parsecell (Rn, xls.limits); + (which returns the numeric contents of Rn into array An and the + text data into array Tn.) + + See also: xlsread, odsread, xls2oct, ods2oct + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Divide a heterogeneous 2D cell array into a 2D numeric array and a 2D +cell array + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +pch2mat + + +# name: +# type: sq_string +# elements: 1 +# length: 422 + -- Function File: DATA = pch2mat (FILENAME) + Converts NASTRAN PCH file (SORT2) to a data structure and + frequency vector. A filename as a string is the only needed input. + + The output is in the form of struct. containing a freq vector n x + 1 called data.f, and the remaining data are in the form of + subcases, point ids and directions respectively. for ex. + data.S1.p254686.x and they are n x 2 + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 75 +Converts NASTRAN PCH file (SORT2) to a data structure and frequency +vector. + + + +# name: +# type: sq_string +# elements: 1 +# length: 13 +spsh_chkrange + + +# name: +# type: sq_string +# elements: 1 +# length: 449 + -- Function File: [ TOPLEFTADDR, NROWS, NCOLS, TOPROW, LEFTCOL ] = + spsh_chkrange ( RANGE, ROWSIZE, COLSIZE, INTF-TYPE, FILENAME) + (Internal function) Get and check various cell and range address + parameters for spreadsheet input. + + spsh_chkrange should not be invoked directly but rather through + oct2xls or oct2ods. + + Example: + + [tl, nrw, ncl, trw, lcl] = spsh_chkrange (crange, nr, nc, xtype, fileptr); + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +(Internal function) Get and check various cell and range address +parameters for + + + +# name: +# type: sq_string +# elements: 1 +# length: 12 +spsh_prstype + + +# name: +# type: sq_string +# elements: 1 +# length: 521 + -- Function File: [ TYPE-ARRAY ] = spsh_prstype ( IARRAY, ROWSIZE, + COLSIZE, CELLTYPES, OPTIONS) + (Internal function) Return rectangular array with codes for cell + types in rectangular input cell array IARRAY. Codes are contained + in input vector in order of Numeric, Boolean, Text, Formula and + Empty, resp. + + spsh_prstype should not be invoked directly but rather through + oct2xls or oct2ods. + + Example: + + typarr = spsh_chkrange (cellarray, nr, nc, ctypes, options); + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +(Internal function) Return rectangular array with codes for cell types +in rectan + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +xls2oct + + +# name: +# type: sq_string +# elements: 1 +# length: 4421 + -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS) + -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS, WSH) + -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS, WSH, RANGE) + -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS, WSH, RANGE, + OPTIONS) + Read data contained within cell range RANGE from worksheet WSH in + an Excel spreadsheet file pointed to in struct XLS. + + XLS is supposed to have been created earlier by xlsopen in the + same octave session. + + WSH is either numerical or text, in the latter case it is + case-sensitive and it may be max. 31 characters long. Note that + in case of a numerical WSH this number refers to the position in + the worksheet stack, counted from the left in an Excel window. The + default is numerical 1, i.e. the leftmost worksheet in the Excel + file. + + RANGE is expected to be a regular spreadsheet range format, or "" + (empty string, indicating all data in a worksheet). If no range + is specified the occupied cell range will have to be determined + behind the scenes first; this can take some time for the + Java-based interfaces. Be aware that in COM/ActiveX interface the + used range can be outdated. The Java-based interfaces are more + reliable in this respect albeit much slower. + + Optional argument OPTIONS, a structure, can be used to specify + various read modes by setting option fields in the struct to true + (1) or false (0). Currently recognized option fields are: + + "formulas_as_text" + If set to TRUE or 1, spreadsheet formulas (if at all present) + are read as formula strings rather than the evaluated formula + result values. The default value is 0 (FALSE). + + 'strip_array' + Set the value of this field set to TRUE or 1 to strip the + returned output array RAWARR from empty outer columns and + rows. The spreadsheet cell rectangle limits from where the + data actually came will be updated. The default value is + FALSE or 0 (no cropping). When using the COM interface, the + output array is always cropped. + + If only the first argument XLS is specified, xls2oct will try to + read all contents from the first = leftmost (or the only) + worksheet (as if a range of '' (empty string) was specified). + + If only two arguments are specified, xls2oct assumes the second + argument to be WSH. In that case xls2oct will try to read all data + contained in that worksheet. + + Return argument RAWARR contains the raw spreadsheet cell data. + Use parsecell() to separate numeric and text values from RAWARR. + + Optional return argument XLS contains the pointer struct, If any + data have been read, field XLS.limits contains the outermost + column and row numbers of the actually returned cell range. + + Optional return argument RSTATUS will be set to 1 if the requested + data have been read successfully, 0 otherwise. + + Erroneous data and empty cells turn up empty in RAWARR. Date/time + values in Excel are returned as numerical values. Note that Excel + and Octave have different date base values (1/1/1900 & 1/1/0000, + resp.) Be aware that Excel trims RAWARR from empty outer rows & + columns, so any returned cell array may turn out to be smaller + than requested in RANGE, independent of field 'formulas_as_text' + in OPTIONS. When using COM, POI, or UNO interface, formulas in + cells are evaluated; if that fails cached values are retrieved. + These may be outdated depending on Excel's "Automatic calculation" + settings when the spreadsheet was saved. + + When reading from merged cells, all array elements NOT + corresponding to the leftmost or upper Excel cell will be treated + as if the "corresponding" Excel cells are empty. + + Beware: when the COM interface is used, hidden Excel invocations + may be kept running silently in case of COM errors. + + Examples: + + A = xls2oct (xls1, '2nd_sheet', 'C3:AB40'); + (which returns the numeric contents in range C3:AB40 in worksheet + '2nd_sheet' from a spreadsheet file pointed to in pointer struct xls1, + into numeric array A) + + [An, xls2, status] = xls2oct (xls2, 'Third_sheet'); + + See also: oct2xls, xlsopen, xlsclose, parsecell, xlsread, + xlsfinfo, xlswrite + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Read data contained within cell range RANGE from worksheet WSH in an +Excel sprea + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +xlsclose + + +# name: +# type: sq_string +# elements: 1 +# length: 1895 + -- Function File: [ XLS] = xlsclose (XLS) + -- Function File: [ XLS] = xlsclose (XLS, FILENAME) + -- Function File: [ XLS] = xlsclose (XLS, "FORCE") + Close the Excel spreadsheet pointed to in struct XLS, if needed + write the file to disk. Based on information contained in XLS, + xlsclose will determine if the file should be written to disk. + + If no errors occured during writing, the xls file pointer struct + will be reset and -if COM interface was used- ActiveX/Excel will + be closed. However if errors occurred, the file pinter will be + untouched so you can clean up before a next try with xlsclose(). + Be warned that until xlsopen is called again with the same XLS + pointer struct, hidden Excel or Java applications with associated + (possibly large) memory chunks are kept in memory, taking up + resources. If (string) argument "FORCE" is supplied, the file + pointer will be reset regardless, whether the possibly modified + file has been saved successfully or not. Hidden Excel (COM) or + OpenOffice.org (UNO) invocations may live on, possibly even + impeding proper shutdown of Octave. + + FILENAME can be used to write changed spreadsheet files to an + other file than opened with xlsopen(); unfortunately this doesn't + work with JXL (JExcelAPI) interface. + + You need MS-Excel (95 - 2010), and/or the Java package => 1.2.8 + plus Apache POI > 3.5 and/or JExcelAPI and/or OpenXLS and/or + OpenOffice.org or clones installed on your computer + proper + javaclasspath set, to make this function work at all. + + XLS must be a valid pointer struct made by xlsopen() in the same + octave session. + + Examples: + + xls1 = xlsclose (xls1); + (Close spreadsheet file pointed to in pointer struct xls1; xls1 is reset) + + See also: xlsopen, xlsread, xlswrite, xls2oct, oct2xls, xlsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Close the Excel spreadsheet pointed to in struct XLS, if needed write +the file t + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +xlsfinfo + + +# name: +# type: sq_string +# elements: 1 +# length: 2353 + -- Function File: [ FILETYPE] = xlsfinfo (FILENAME [, REQINTF]) + -- Function File: [ FILETYPE, SH_NAMES] = xlsfinfo (FILENAME [, + REQINTF]) + -- Function File: [ FILETYPE, SH_NAMES, FFORMAT] = xlsfinfo (FILENAME + [, REQINTF]) + Query Excel spreadsheet file FILENAME for some info about its + contents. + + If FILENAME is a recognizable Excel spreadsheet file, FILETYPE + returns the string "Microsoft Excel Spreadsheet", or '' (empty + string) otherwise. + + If FILENAME is a recognizable Excel spreadsheet file, optional + argument SH_NAMES contains a list (cell array) of sheet names (and + in case Excel is installed: sheet types) contained in FILENAME, in + the order (from left to right) in which they occur in the sheet + stack. + + Optional return value FFORMAT currently returns '' (empty string) + unless FILENAME is a readable Excel 97-2003 .xls file or an Excel + 2007 .xlsx / .xlsb file in which case FFORMAT is set to + "xlWorkbookNormal". Excel 95 .xls files can only be read through + the JXL (JExcelAPI) or UNO (OpenOffice.org) Java-based interfaces. + + If no return arguments are specified the sheet names are echoed to + the terminal screen; in case of Java interfaces for each sheet the + actual occupied data range is echoed as well. The occupied cell + range will have to be determined behind the scenes first; this can + take some time for the Java-based interfaces. + + If multiple xls interfaces have been installed, REQINTF can be + specified. This can sometimes be handy, e.g. to get an idea of + occupied cell ranges in each worksheet using different interfaces + (due to cached info and/or different treatment of empty but + formatted cells, each interfaces may give different results). + + For use on OOXML spreadsheets one needs full POI and/or UNO + support (see xlsopen) and 'poi' or 'uno' needs to be specified for + REQINTF. For Excel 95 file use 'jxl' or 'uno'. + + Examples: + + exist = xlsfinfo ('test4.xls'); + (Just checks if file test4.xls is a readable Excel file) + + [exist, names] = xlsfinfo ('test4.xls'); + (Checks if file test4.xls is a readable Excel file and return a + list of sheet names and -types) + + See also: oct2xls, xlsread, xls2oct, xlswrite + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 71 +Query Excel spreadsheet file FILENAME for some info about its contents. + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +xlsopen + + +# name: +# type: sq_string +# elements: 1 +# length: 2964 + -- Function File: XLS = xlsopen (FILENAME) + -- Function File: XLS = xlsopen (FILENAME, READWRITE) + -- Function File: XLS = xlsopen (FILENAME, READWRITE, REQINTF) + Get a pointer to an Excel spreadsheet in the form of return + argument (file pointer struct) XLS. After processing the + spreadsheet, the file pointer must be explicitly closed by calling + xlsclose(). + + Calling xlsopen without specifying a return argument is fairly + useless! + + To make this function work at all, you need MS-Excel (95 - 2003), + and/or the Java package >= 1.2.8 plus Apache POI >= 3.5 and/or + JExcelAPI and/or OpenXLS and/or OpenOffice.org (or clones) + installed on your computer + proper javaclasspath set. These + interfaces are referred to as COM, POI, JXL, OXS, and UNO, resp., + and are preferred in that order by default (depending on their + presence). For OOXML support, in addition to Apache POI support + you also need the following jars in your javaclasspath: + poi-ooxml-schemas-3.5.jar, xbean.jar and dom4j-1.6.1.jar (or later + versions). Later OpenOffice.org versions (UNO) have support for + OOXML as well. Excel'95 spreadsheets can only be read by + JExcelAPI and OpenOffice.org. + + FILENAME should be a valid .xls or xlsx Excel file name (including + extension). But if you use the COM interface you can specify any + extension that your installed Excel version can read AND write; + the same goes for UNO (OpenOffice.org). Using the other Java + interfaces, only .xls or .xlsx are allowed. If FILENAME does not + contain any directory path, the file is saved in the current + directory. + + If READWRITE is set to 0 (default value) or omitted, the Excel file + is opened for reading. If READWRITE is set to True or 1, an Excel + file is opened (or created) for reading & writing. + + Optional input argument REQINTF can be used to override the Excel + interface that otherwise is automatically selected by xlsopen. + Currently implemented interfaces (in order of preference) are + 'COM' (Excel/COM), 'POI' (Java/Apache POI), 'JXL' + (Java/JExcelAPI), 'OXS' (Java/OpenXLS), or 'UNO' + (Java/OpenOffice.org - EXPERIMENTAL!). In most situations this + parameter is unneeded as xlsopen automatically selects the most + useful interface present. + + Beware: Excel invocations may be left running invisibly in case of + COM errors or forgetting to close the file pointer. Similarly for + OpenOffice.org which may even prevent Octave from being closed. + + Examples: + + xls = xlsopen ('test1.xls'); + (get a pointer for reading from spreadsheet test1.xls) + + xls = xlsopen ('test2.xls', 1, 'POI'); + (as above, indicate test2.xls will be written to; in this case using Java + and the Apache POI interface are requested) + + See also: xlsclose, xlsread, xlswrite, xls2oct, oct2xls, xlsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Get a pointer to an Excel spreadsheet in the form of return argument +(file point + + + +# name: +# type: sq_string +# elements: 1 +# length: 7 +xlsread + + +# name: +# type: sq_string +# elements: 1 +# length: 5721 + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread + (FILENAME) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread + (FILENAME, WSH) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread + (FILENAME, RANGE) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread + (FILENAME, WSH, RANGE) + -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread + (FILENAME, WSH, RANGE, REQINTF) + Read data contained in range RANGE from worksheet WSH in Excel + spreadsheet file FILENAME. Return argument NUMARR contains the + numeric data, optional return arguments TXTARR and RAWARR contain + text strings and the raw spreadsheet cell data, respectively. + Return argument LIMITS contains the outer column/row numbers of + the read spreadsheet range where NUMARR, TXTARR and RAWARR have + come from (remember, xlsread trims outer rows and columns). + + If FILENAME does not contain any directory, the file is assumed to + be in the current directory. The filename extension (.xls or + .xlsx) must be included in the file name; when using the COM + interface all file formats can be read that are supported by the + locally installed MS-Excel version (e.g., wk1, csv, dbf, etc.). + + RANGE is expected to be a regular spreadsheet range format, or "" + (empty string, indicating all data in a worksheet). If no range + is specified the occupied cell range will have to be determined + behind the scenes first; this can take some time for the + Java-based interfaces (but the results may be more reliable than + that of ActiveX/COM). + + WSH is either numerical or text; in the latter case it is + case-sensitive and it may be max. 31 characters long. Note that + in case of a numerical WSH this number refers to the position in + the worksheet stack, counted from the left in an Excel window. The + default is numerical 1, i.e. the leftmost worksheet in the Excel + file. + + If only the first argument is specified, xlsread will try to read + all contents (as if a range of '' (empty string) was specified) + from the first = leftmost (or the only) worksheet + + If only two arguments are specified, xlsread assumes the second + argument to be RANGE if it is a string argument and contains a + ":" or if it is '' (empty string), and in those cases assumes the + data must be read from the first worksheet (not necessarily + Sheet1! but the leftmost sheet). + + However, if only two arguments are specified and the second + argument is numeric or a text string that does not contain a ":", + it is assumed to be WSH and to refer to a worksheet. In that case + xlsread tries to read all data contained in that worksheet. + + The optional last argument REQINTF can be used to override the + automatic interface selection by xlsread out of the supported + ones: COM/Excel, Java/Apache POI, Java/JExcelAPI, Java/OpenXLS, or + Java/UNO (OpenOffice.org) (in that -built in- order of preference). + For reading from OOXML files a value of 'com', 'poi' or 'uno' must + be specified for REQINTF (see help for xlsopen); for Excel'95 + files use 'com', or if Excel is not installed use 'jxl', 'basic' + or 'uno' (POI can't read Excel 95 but will try to fall back to + JXL). As REQINTF can also be a cell array of strings, one can + select or exclude one or more interfaces. + + Erroneous data and empty cells are set to NaN in NUMARR and turn + up empty in TXTARR and RAWARR. Date/time values in Excel are + returned as numerical values in NUMARR. Note that Excel and Octave + have different date base values (1/1/1900 & 1/1/0000, resp.). + Spreadsheet date values lying before 1/1/1900 are returned as + strings, formatted as they appear in the spreadsheet. NUMARR and + TXTARR are trimmed from empty outer rows and columns. Be aware + that Excel does the same for RAWARR, so any returned array may + turn out to be smaller than requested in RANGE. + + When reading from merged cells, all array elements NOT + corresponding to the leftmost or upper Excel cell will be treated + as if the "corresponding" Excel cells are empty. + + xlsread is just a wrapper for a collection of scripts that find out + the interface to be used (COM, Java/POI, Java/JXL Java/OXS, + Java/UNO) and do the actual reading. For each call to xlsread the + interface must be started and the Excel file read into memory. + When reading multiple ranges (in optionally multiple worksheets) a + significant speed boost can be obtained by invoking those scripts + directly as in: xlsopen / xls2oct [/ parsecell] / ... / xlsclose + + Beware: when using the COM interface, hidden Excel invocations may + be kept running silently if not closed explicitly. + + Examples: + + A = xlsread ('test4.xls', '2nd_sheet', 'C3:AB40'); + (which returns the numeric contents in range C3:AB40 in worksheet + '2nd_sheet' from file test4.xls into numeric array A) + + [An, Tn, Ra, limits] = xlsread ('Sales2009.xls', 'Third_sheet'); + (which returns all data in worksheet 'Third_sheet' in file 'Sales2009.xls' + into array An, the text data into array Tn, the raw cell data into + cell array Ra and the ranges from where the actual data came in limits) + + numarr = xlsread ('Sales2010.xls', 4, [], {'JXL', 'COM'}); + (Read all data from 4th worksheet in file Sales2010.xls using either JXL + or COM interface (i.e, exclude POI interface). + + See also: xlswrite, xlsopen, xls2oct, xlsclose, xlsfinfo, oct2xls + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Read data contained in range RANGE from worksheet WSH in Excel +spreadsheet file + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +xlswrite + + +# name: +# type: sq_string +# elements: 1 +# length: 4031 + -- Function File: RSTATUS = xlswrite (FILENAME, ARR) + -- Function File: RSTATUS = xlswrite (FILENAME, ARR, WSH) + -- Function File: RSTATUS = xlswrite (FILENAME, ARR, WSH, RANGE) + -- Function File: RSTATUS = xlswrite (FILENAME, ARR, WSH, RANGE, + REQINTF) + Add data in 1D/2D array ARR to worksheet WSH in Excel spreadsheet + file FILENAME in cell range RANGE. + + RSTATUS returns 1 if write succeeded, 0 otherwise. + + FILENAME must be a valid .xls Excel file name (including file name + extension). If FILENAME does not contain any directory path, the + file is saved in the current directory. + + ARR can be any 1D or 2D array containing numerical or character + data (cellstr) except complex. Mixed numeric/text arrays can only + be cell arrays. + + If only 3 arguments are given, the 3rd is assumed to be a + spreadsheet range if it contains a ":" or is a completely empty + string (corresponding to A1:IV65336 for regular .xls or + A1:XFD1048576 for OOXML .xlsx). The 3rd argument is assumed to + refer to a worksheet if it is a numeric value or a non-empty text + string not containing ":" + + WSH can be a number or string (max. 31 chars). In case of a not + yet existing Excel file, the first worksheet will be used & named + according to WSH - the extra worksheets that Excel normally + creates by default are deleted. In case of existing files, some + checks are made for existing worksheet names or numbers, or + whether WSH refers to an existing sheet with a type other than + worksheet (e.g., chart). When new worksheets are to be added to + the Excel file, they are inserted to the right of all existing + worksheets. The pointer to the "active" sheet (shown when Excel + opens the file) remains untouched. + + RANGE is expected to be a regular spreadsheet range. Data is + added to the worksheet; existing data in the requested range will + be overwritten. Array ARR will be clipped at the right and/or + bottom if its size is bigger than can be accommodated in RANGE. + If ARR is smaller than the RANGE allows, it is placed in the top + left rectangle of RANGE and remaining cell values outside the + rectangle will be retained. + + If RANGE contains merged cells, only the elements of ARR + corresponding to the top or left Excel cells of those merged cells + will be written, other array cells corresponding to that cell will + be ignored. + + The optional last argument REQINTF can be used to override the + automatic selection by xlswrite of one interface out of the + supported ones: 'com' (ActiveX/Excel), 'poi' (Java/Apache POI), + 'jxl' (Java/JExcelAPI), or 'uno' (Java/OpenOffice.org). 'oxs' + (Java/OpenXLS) is implemented but disabled for writing as it is + too buggy. For writing to OOXML files (.xlsx) a value of 'com', + 'poi' or 'uno' must be specified for REQINTF. The value of REQINTF + is case-insensitive. Multiple interfaces can be selected if + entered as a cell array of strings. + + xlswrite is a mere wrapper for various scripts which find out what + Excel interface to use (COM, POI, etc) plus code to mimic the other + brand's syntax. For each call to xlswrite such an interface must be + started and possibly an Excel file loaded. When writing to multiple + ranges and/or worksheets in the same Excel file, a speed bonus can + be obtained by invoking those scripts directly with multiple calls + to oct2xls (one for each sheet or range) surrounded by one call to + xlsopen and xlsclose: (xlsopen / octxls / oct2xls / .... / + xlsclose) + + Examples: + + status = xlswrite ('test4.xls', 'arr', 'Third_sheet', 'C3:AB40'); + (which adds the contents of array arr (any type) to range C3:AB40 + in worksheet 'Third_sheet' in file test4.xls and returns a logical + True (= numerical 1) in status if al went well) + + See also: xlsread, oct2xls, xls2oct, xlsopen, xlsclose, xlsfinfo + + + + + +# name: +# type: sq_string +# elements: 1 +# length: 80 +Add data in 1D/2D array ARR to worksheet WSH in Excel spreadsheet file +FILENAME + + + +# name: +# type: sq_string +# elements: 1 +# length: 8 +xmlwrite + + +# name: +# type: sq_string +# elements: 1 +# length: 211 + -- Function File: NB = xmlwrite (FILENAME, VALUE) + -- Function File: NB = xmlwrite (FD, VALUE, [NAME]) + Write a VALUE into FILENAME (FD) as an XML file. + + The number of elements (NB) or 0 is returned. + + + + +# name: +# type: sq_string +# elements: 1 +# length: 48 +Write a VALUE into FILENAME (FD) as an XML file. + + + + +