1 # Created by Octave 3.6.2, Sun Jun 17 08:16:48 2012 UTC <root@brouzouf>
13 # name: <cell-element>
17 append_save M-file function
19 Objective: be able to add variables to existing save files. Works for
20 all the types of save files that "save" supports.
23 1) A string which specifies the existing save file.
24 2) The options you need to pass to the 'save' function to save to the
25 file type that you want.
26 3) A 1x2 cell, with the first element being a string representation
27 of the variable/symbol that you're trying to add, followed by the
28 actual variable/symbol itself.
29 4) Any number of additional 1x2 cells, following the same format as
30 the 3rd argument specified immediately before this one.
33 Currently, none. But there might be some debugging / error-code
34 messages in the future.
37 octave> B = ones(2,2);
38 octave> append_save( "test.txt", "-binary", {"B", B } )
42 # name: <cell-element>
46 append_save M-file function
51 # name: <cell-element>
58 # name: <cell-element>
62 calccelladdress (R, C) - compute spreadsheet style cell address from
63 row & column index (both 1-based).
65 Max column index currently set to 18278 (max ODS: 1024, OOXML: 16384).
66 Row limits for ODF and OOXML are 65536 and 1048576, resp.
70 # name: <cell-element>
74 calccelladdress (R, C) - compute spreadsheet style cell address from
79 # name: <cell-element>
83 chk_spreadsheet_support
86 # name: <cell-element>
90 Check Octave / Matlab environment for spreadsheet I/O support.
92 usage: [ RETVAL ] = chk_spreadsheet_support ( [/PATH/TO/JARS], [,DEBUG_LEVEL] [,PATH_TO_OOO])
94 CHK_SPREADSHEET_SUPPORT first checks ActiveX (native MS-Excel); then
95 Java JRE presence, then Java support (builtin/activated (Matlab) or
96 added tru octave-forge Java package (Octave); then check existing
97 javaclasspath for Java class libraries (.jar) needed for various
98 Java-based spreadsheet I/O interfaces.
99 If desired the relevant classes can be added to the dynamic
100 javaclasspath. In that case the path name to the directory
101 containing these classes should be specified as input argument
102 with -TAKE NOTICE- /forward/ slashes. In these jars reside in
103 different directories, multiple calls to chk_spreadsheet_support
106 Input arguments (all are optional, but the order is important):
107 /PATH/TO/JARS = (string) path (relative or absolute) to a
108 subdirectory where java class libraries (.jar)
109 for spreadsheet I/O reside. Can be [] or ''
110 DEBUG_LEVEL = (integer) between [0 (no output) .. 3 (full output]
111 PATH_TO_OOO = (string) installation directory of Openffice.org,
112 usually (but not guaranteed):
113 - Windows: C:\Program Files\OpenOffice.org
116 IMPORTANT: PATH_TO_OOO should be such that both:
117 1. PATH_TO_OOO/program/
119 2. PATH_TO_OOO/ure/.../ridl.jar
122 RETVAL = 0 No spreadsheet I/O support found
123 <> 0 At least one spreadsheet I/O interface found. RETVAL
124 RETVAL will be set to the sum of values for found interfaces:
125 ---------- XLS (Excel) interfaces: ----------
126 1 = COM (ActiveX / Excel)
127 2 = POI (Java / Apache POI)
128 4 = POI+OOXML (Java / Apache POI)
129 8 = JXL (Java / JExcelAPI)
130 16 = OXS (Java / OpenXLS)
131 --- ODS (OpenOffice.org Calc) interfaces ----
132 32 = OTK (Java/ ODF Toolkit)
133 64 = JOD (Java / jOpenDocument)
134 ----------------- XLS & ODS: ----------------
135 128 = UNO (Java / UNO bridge - OpenOffice.org)
139 # name: <cell-element>
143 Check Octave / Matlab environment for spreadsheet I/O support.
147 # name: <cell-element>
154 # name: <cell-element>
158 -- Function File: ex = fexist (file, tspec, aspec)
159 Checks whether a file exists. FILE is the queried file path.
160 TSPEC is a combination of letters f,d,p,S, corresponding to file
166 * p: named pipe (FIFO special file)
170 The query is true if the actual file type matches any of the
173 ASPEC is a combination of letters r,w,x, corresponding to queried
174 access privileges to the file. The query is true if the current
175 user has all the spefied types of access, either through "user",
176 "group" or "other" specs.
178 See also: stat, lstat
184 # name: <cell-element>
188 Checks whether a file exists.
192 # name: <cell-element>
199 # name: <cell-element>
203 -- Function File: [ TOPROW#, BOTTOMROW#, LEFTCOL#, RIGHTCOL# ] =
204 getusedrange (SPPTR, SHINDEX#)
205 Find occupied data range in worksheet SHINDEX# in a spreadsheet
206 pointed to in struct SPPTR (either MS-Excel or OpenOffice_org
209 SHINDEX# must be numeric and is 1-based. SPPTR can either refer to
210 an MS-Excel spreadsheet (spptr returned by xlsopen) or an
211 OpenOffice.org Calc spreadsheet (spptr returned by odsopen). None
212 of these inputs are checked!
214 Be aware that especially for OpenOffice.org Calc (ODS) spreadsheets
215 the results can only be obtained by counting all cells in all rows;
216 this can be fairly time-consuming. Reliable ods data size results
217 can only be obtained using UNO interface. For the ActiveX (COM)
218 interface the underlying Visual Basic call relies on cached range
219 values and counts empty cells with only formatting too, so COM
220 returns only approximate (but then usually too big) range values.
224 [trow, brow, lcol, rcol] = getusedrange (ods2, 3);
225 (which returns the outermost row & column numbers of the rectangle
226 enveloping the occupied cells in the third sheet of an OpenOffice_org
227 Calc spreadsheet pointedto in struct ods2)
229 [trow, brow, lcol, rcol] = getusedrange (xls3, 3);
230 (which returns the outermost row & column numbers of the rectangle
231 enveloping the occupied cells in the third sheet of an Excel
232 spreadsheet pointed to in struct xls3)
234 See also: xlsopen, xlsclose, odsopen, odsclose, xlsfinfo, odsfinfo
240 # name: <cell-element>
244 Find occupied data range in worksheet SHINDEX# in a spreadsheet pointed
249 # name: <cell-element>
256 # name: <cell-element>
260 (Internal function) Check proper operation of ODS spreadsheet scripts.
261 Before running, a character variable 'intf' should be initialized with
262 a value of 'otk', 'jod', or 'uno'.
266 # name: <cell-element>
270 (Internal function) Check proper operation of ODS spreadsheet scripts.
274 # name: <cell-element>
281 # name: <cell-element>
285 (Internal function) Check proper operation of XLS spreadsheet scripts.
286 Before running, a character variable 'intf' should be initialized with
287 a value of 'com', 'poi', 'jxl', 'oxs', or 'uno'.
291 # name: <cell-element>
295 (Internal function) Check proper operation of XLS spreadsheet scripts.
299 # name: <cell-element>
306 # name: <cell-element>
310 Returns a valid json string that will describe object; the string will
311 be in a compact form (no spaces or line breaks).
313 It will map simple octave values this way:
314 function handles: string with the name of the function
315 double (numbers): depends:
316 If it's real it will map to a string representing that number
317 If it's complex it will map to an object with the next properties:
318 real: real part of the number
319 imag: imaginary part of the number
320 char: A string enclosed by double quotes representing that character
321 And will map more complex octave values this other way:
322 struct: an object with properties equal to the struct's field names
323 and value equal to the json counterpart of that field
324 cell: it will be mapped depending on the value of the cell (for
325 example {i} will be mapped to an object with real=0 and imag=1)
326 vectors or cell arrays: it will map them to a corresponding js
327 array (same size) with the values transformed to their json
328 counterpart (Note: that in javascript all arrays are like octave's
329 cells ,i.e. they can store different type and size variables)
330 strings or char vectors: they will be mapped to the same string
331 enclosed by double quotes
332 Other octave values will be mapped to a string enclosed by double
333 quotes with the value that the class() function returns
334 It can handle escape sequences and special chars automatically.
335 If they're valid in JSON it will keep them if not they'll be
336 escaped so they can become valid
340 # name: <cell-element>
344 Returns a valid json string that will describe object; the string will
349 # name: <cell-element>
356 # name: <cell-element>
360 -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS)
361 -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS, WSH)
362 -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS, WSH, RANGE)
363 -- Function File: [ ODS, RSTATUS ] = oct2ods (ARR, ODS, WSH, RANGE,
365 Transfer data to an OpenOffice_org Calc spreadsheet previously
368 Data in 1D/2D array ARR are transferred into a cell range RANGE in
369 sheet WSH. ODS must have been made earlier by odsopen(). Return
370 argument ODS should be the same as supplied argument ODS and is
371 updated by oct2ods. A subsequent call to odsclose is needed to
372 write the updated spreadsheet to disk (and -if needed- close the
373 Java invocation holding the file pointer).
375 ARR can be any 1D or 2D array containing numerical or character
376 data (cellstr) except complex. Mixed numeric/text arrays can only
379 ODS must be a valid pointer struct created earlier by odsopen.
381 WSH can be a number (sheet name) or string (sheet number). In
382 case of a yet non-existing Calc file, the first sheet will be used
383 & named according to WSH. In case of existing files, some checks
384 are made for existing sheet names or numbers. When new sheets are
385 to be added to the Calc file, they are inserted to the right of
386 all existing sheets. The pointer to the "active" sheet (shown when
387 Calc opens the file) remains untouched.
389 If RANGE omitted, the top left cell where the data will be put is
390 supposed to be 'A1'; only a top left cell address can be specified
391 as well. In these cases the actual range to be used is determined
392 by the size of ARR. Be aware that large data array sizes may
393 exhaust the java shared memory space. For larger arrays,
394 appropriate memory settings are needed in the file java.opts; then
395 the maximum array size for the java-based spreadsheet options can
396 be in the order of perhaps 10^6 elements.
398 Optional argument OPTIONS, a structure, can be used to specify
399 various write modes. Currently the only option field is
400 "formulas_as_text", which -if set to 1 or TRUE- specifies that
401 formula strings (i.e., text strings starting with "=" and ending
402 in a ")" ) should be entered as litteral text strings rather than
403 as spreadsheet formulas (the latter is the default). As
404 jOpenDocument doesn't support formula I/O at all yet, this option
405 is ignored for the JOD interface.
407 Data are added to the sheet, ignoring other data already present;
408 existing data in the range to be used will be overwritten.
410 If RANGE contains merged cells, also the elements of ARR not
411 corresponding to the top or left Calc cells of those merged cells
412 will be written, however they won't be shown until in Calc the
417 [ods, status] = ods2oct (arr, ods, 'Newsheet1', 'AA31:GH165');
418 Write array arr into sheet Newsheet1 with upperleft cell at AA31
420 [ods, status] = ods2oct ({'String'}, ods, 'Oldsheet3', 'B15:B15');
421 Put a character string into cell B15 in sheet Oldsheet3
423 See also: ods2oct, odsopen, odsclose, odsread, odswrite, odsfinfo
429 # name: <cell-element>
433 Transfer data to an OpenOffice_org Calc spreadsheet previously opened
438 # name: <cell-element>
445 # name: <cell-element>
449 -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS)
450 -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS, WSH)
451 -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS, WSH, RANGE)
452 -- Function File: [ XLS, RSTATUS ] = oct2xls (ARR, XLS, WSH, RANGE,
454 Add data in 1D/2D CELL array ARR into a cell range specified in
455 RANGE in worksheet WSH in an Excel spreadsheet file pointed to in
456 structure XLS. Return argument XLS equals supplied argument XLS
457 and is updated by oct2xls.
459 A subsequent call to xlsclose is needed to write the updated
460 spreadsheet to disk (and -if needed- close the Excel or Java
463 ARR can be any 1D or 2D array containing numerical or character
464 data (cellstr) except complex. Mixed numeric/text arrays can only
467 XLS must be a valid pointer struct created earlier by xlsopen.
469 WSH can be a number or string (max. 31 chars). In case of a yet
470 non-existing Excel file, the first worksheet will be used & named
471 according to WSH - extra empty worksheets that Excel creates by
472 default are deleted. In case of existing files, some checks are
473 made for existing worksheet names or numbers, or whether WSH
474 refers to an existing sheet with a type other than worksheet
475 (e.g., chart). When new worksheets are to be added to the Excel
476 file, they are inserted to the right of all existing worksheets.
477 The pointer to the "active" sheet (shown when Excel opens the
478 file) remains untouched.
480 If RANGE is omitted or just the top left cell of the range is
481 specified, the actual range to be used is determined by the size of
482 ARR. If nothing is specified for RANGE the top left cell is
485 Data are added to the worksheet, ignoring other data already
486 present; existing data in the range to be used will be overwritten.
488 If RANGE contains merged cells, only the elements of ARR
489 corresponding to the top or left Excel cells of those merged cells
490 will be written, other array cells corresponding to that cell will
493 Optional argument OPTIONS, a structure, can be used to specify
494 various write modes. Currently the only option field is
495 "formulas_as_text", which -if set to 1 or TRUE- specifies that
496 formula strings (i.e., text strings starting with "=" and ending
497 in a ")" ) should be entered as litteral text strings rather than
498 as spreadsheet formulas (the latter is the default).
500 Beware that -if invoked- Excel invocations may be left running
501 silently in case of COM errors. Invoke xlsclose with proper
502 pointer struct to close them. When using Java, note that large
503 data array sizes elements may exhaust the Java shared memory space
504 for the default java memory settings. For larger arrays,
505 appropriate memory settings are needed in the file java.opts; then
506 the maximum array size for the Java-based spreadsheet options may
507 be in the order of 10^6 elements. In caso of UNO this limit is not
508 applicable and spreadsheets may be much larger.
512 [xlso, status] = xls2oct ('arr', xlsi, 'Third_sheet', 'AA31:AB278');
514 See also: xls2oct, xlsopen, xlsclose, xlsread, xlswrite, xlsfinfo
520 # name: <cell-element>
524 Add data in 1D/2D CELL array ARR into a cell range specified in RANGE
529 # name: <cell-element>
536 # name: <cell-element>
540 -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS)
541 -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS, WSH)
542 -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS, WSH, RANGE)
543 -- Function File: [ RAWARR, ODS, RSTATUS ] = ods2oct (ODS, WSH, RANGE,
545 Read data contained within cell range RANGE from worksheet WSH in
546 an OpenOffice_org Calc spreadsheet file pointed to in struct ODS.
548 ODS is supposed to have been created earlier by odsopen in the
551 WSH is either numerical or text, in the latter case it is
552 case-sensitive. Note that in case of a numerical WSH this number
553 refers to the position in the worksheet stack, counted from the
554 left in a Calc window. The default is numerical 1, i.e. the
555 leftmost worksheet in the ODS file.
557 RANGE is expected to be a regular spreadsheet range format, or ""
558 (empty string, indicating all data in a worksheet). If no range
559 is specified the occupied cell range will have to be determined
560 behind the scenes first; this can take some time.
562 Optional argument OPTIONS, a structure, can be used to specify
563 various read modes by setting option fields in the struct to true
564 (1) or false (0). Currently recognized option fields are:
567 If set to TRUE or 1, spreadsheet formulas (if at all present)
568 are read as formula strings rather than the evaluated formula
569 result values. This only works for the OTK and UNO interfaces.
570 The default value is 0 (FALSE).
573 Set the value of this field set to TRUE or 1 to strip the
574 returned output array RAWARR from empty outer columns and
575 rows. The spreadsheet cell rectangle limits from where the
576 data actually came will be updated. The default value is
577 FALSE or 0 (no cropping).
579 If only the first argument ODS is specified, ods2oct will try to
580 read all contents from the first = leftmost (or the only)
581 worksheet (as if a range of '' (empty string) was specified).
583 If only two arguments are specified, ods2oct assumes the second
584 argument to be WSH. In that case ods2oct will try to read all data
585 contained in that worksheet.
587 Return argument RAWARR contains the raw spreadsheet cell data.
588 Use parsecell() to separate numeric and text values from RAWARR.
590 Optional return argument ODS contains the pointer struct. Field
591 ODS.limits contains the outermost column and row numbers of the
592 actually read cell range.
594 Optional return argument RSTATUS will be set to 1 if the requested
595 data have been read successfully, 0 otherwise.
597 Erroneous data and empty cells turn up empty in RAWARR. Date/time
598 values in OpenOffice.org are returned as numerical values with
599 base 1-1-0000 (same as octave). But beware that Excel spreadsheets
600 rewritten by OpenOffice.org into .ods format may have numerical
601 date cells with base 01-01-1900 (same as MS-Excel).
603 When reading from merged cells, all array elements NOT
604 corresponding to the leftmost or upper OpenOffice.org cell will be
605 treated as if the "corresponding" cells are empty.
609 A = ods2oct (ods1, '2nd_sheet', 'C3:ABS40000');
610 (which returns the numeric contents in range C3:ABS40000 in worksheet
611 '2nd_sheet' from a spreadsheet file pointed to in pointer struct ods1,
612 into numeric array A)
614 [An, ods2, status] = ods2oct (ods2, 'Third_sheet');
616 See also: odsopen, odsclose, parsecell, odsread, odsfinfo,
623 # name: <cell-element>
627 Read data contained within cell range RANGE from worksheet WSH in an
632 # name: <cell-element>
639 # name: <cell-element>
643 -- Function File: [ ODS] = odsclose (ODS)
644 -- Function File: [ ODS] = odsclose (ODS, FILENAME)
645 -- Function File: [ ODS] = odsclose (ODS, "FORCE")
646 Close the OpenOffice_org Calc spreadsheet pointed to in struct
647 ODS, if needed write the file to disk. odsclose will determine if
648 the file must be written to disk based on information contained in
649 ODS. An empty pointer struct will be returned if no errors
650 occurred. Optional argument FILENAME can be used to write changed
651 spreadsheet files to an other file than opened by odsopen().
652 Optional string argument "FORCE" can be specified to force
653 resetting the file pointer struct. However, in case of UNO, a
654 hidden OOo invocation may linger on in memory then, preventing
655 proper closing of Octave.
657 You need the Java package >= 1.2.6 plus odfdom.jar + xercesImpl.jar
658 and/or jopendocument-<version>.jar installed on your computer +
659 proper javaclasspath set, to make this function work at all. For
660 UNO support, Octave-Java package >= 1.2.8 + latest fixes is
661 imperative; furthermore the relevant classes had best be added to
662 the javaclasspath by utility function chk_spreadsheet_support().
664 ODS must be a valid pointer struct made by odsopen() in the same
669 ods1 = odsclose (ods1);
670 (Close spreadsheet file pointed to in pointer struct ods1; ods1 is reset)
672 See also: odsopen, odsread, odswrite, ods2oct, oct2ods, odsfinfo,
673 chk_spreadsheet_support
679 # name: <cell-element>
683 Close the OpenOffice_org Calc spreadsheet pointed to in struct ODS, if
688 # name: <cell-element>
695 # name: <cell-element>
699 -- Function File: [ FILETYPE] = odsfinfo (FILENAME [, REQINTF])
700 -- Function File: [ FILETYPE, SH_NAMES] = odsfinfo (FILENAME [,
702 Query an OpenOffice_org spreadsheet file FILENAME (with ods
703 suffix) for some info about its contents.
705 If FILENAME is a recognizable OpenOffice.org spreadsheet file,
706 FILETYPE returns the string "OpenOffice.org Calc spreadsheet", or
707 '' (empty string) otherwise.
709 If FILENAME is a recognizable OpenOffice.org Calc spreadsheet
710 file, optional argument SH_NAMES contains a list (cell array) of
711 sheet names contained in FILENAME, in the order (from left to
712 right) in which they occur in the sheet stack.
714 If you omit return arguments FILETYPE and SH_NAMES altogether,
715 odsfinfo returns the sheet names and for each sheet the actual
716 occupied data ranges to the screen.The occupied cell range will
717 have to be determined behind the scenes first; this can take some
720 odsfinfo execution can take its time for large spreadsheets as the
721 entire spreadsheet has to be parsed to get the sheet names, let
722 alone exploring used data ranges.
724 By specifying a value of 'jod', 'otk' or 'uno' for REQINTF the
725 automatic selection of the java interface is bypassed and the
726 specified interface will be used (if at all present).
730 exist = odsfinfo ('test4.ods');
731 (Just checks if file test4.ods is a readable Calc file)
733 [exist, names] = odsfinfo ('test4.ods');
734 (Checks if file test4.ods is a readable Calc file and return a
737 See also: odsread, odsopen, ods2oct, odsclose
743 # name: <cell-element>
747 Query an OpenOffice_org spreadsheet file FILENAME (with ods suffix) for
752 # name: <cell-element>
759 # name: <cell-element>
763 -- Function File: ODS = odsopen (FILENAME)
764 -- Function File: ODS = odsopen (FILENAME, READWRITE)
765 -- Function File: ODS = odsopen (FILENAME, READWRITE, REQINTF)
766 Get a pointer to an OpenOffice_org spreadsheet in the form of
769 Calling odsopen without specifying a return argument is fairly
772 To make this function work at all, you need the Java package >=
773 1.2.5 plus ODFtoolkit (version 0.7.5 or 0.8.6+) & xercesImpl,
774 and/or jOpenDocument, and/or OpenOffice.org (or clones) installed
775 on your computer + proper javaclasspath set. These interfaces are
776 referred to as OTK, JOD, and UNO resp., and are preferred in that
777 order by default (depending on their presence). For (currently
778 experimental) UNO support, Octave-Java package 1.2.8 + latest
779 fixes is imperative; furthermore the relevant classes had best be
780 added to the javaclasspath by utility function
781 chk_spreadsheet_support().
783 FILENAME must be a valid .ods OpenOffice.org file name including
784 .ods suffix. If FILENAME does not contain any directory path, the
785 file is saved in the current directory. For UNO bridge, filenames
786 need to be in the form "file:///<path_to_file>/filename"; a URL
787 will also work. If a plain file name is given (absolute or
788 relative), odsopen() will transform it into proper form.
790 READWRITE must be set to true or numerical 1 if writing to
791 spreadsheet is desired immediately after calling odsopen(). It
792 merely serves proper handling of file errors (e.g., "file not
793 found" or "new file created").
795 Optional input argument REQINTF can be used to override the ODS
796 interface automatically selected by odsopen. Currently implemented
797 interfaces are 'OTK' (Java/ODF Toolkit), 'JOD'
798 (Java/jOpenDocument) and 'UNO' (Java/OpenOffice.org UNO bridge).
802 ods = odsopen ('test1.ods');
803 (get a pointer for reading from spreadsheet test1.ods)
805 ods = odsopen ('test2.ods', [], 'JOD');
806 (as above, indicate test2.ods will be read from; in this case using
807 the jOpenDocument interface is requested)
809 See also: odsclose, odsread, oct2ods, ods2oct, odsfinfo,
810 chk_spreadsheet_support
816 # name: <cell-element>
820 Get a pointer to an OpenOffice_org spreadsheet in the form of return
825 # name: <cell-element>
832 # name: <cell-element>
836 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread
838 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread
840 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread
841 (FILENAME, WSH, RANGE)
842 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = odsread
843 (FILENAME, WSH, RANGE, REQINTF)
844 Read data contained from cell range RANGE in worksheet WSH in
845 OpenOffice_org Calc spreadsheet file FILENAME.
847 You need the octave-forge java package (> 1.2.6) and one or both of
848 jopendocument-<version>.jar or preferrably: (odfdom.jar (versions
849 0.7.5 or 0.8.6+) & xercesImpl.jar v. 2.9.1) in your javaclasspath.
850 There is also experimental support invoking OpenOffice.org or
851 clones through Java/UNO bridge.
853 Return argument NUMARR contains the numeric data, optional return
854 arguments TXTARR and RAWARR contain text strings and the raw
855 spreadsheet cell data, respectively, and LIMITS is a struct
856 containing the data origins of the various returned arrays.
858 If FILENAME does not contain any directory, the file is assumed to
859 be in the current directory. FILENAME should include the filename
862 WSH is either numerical or text, in the latter case it is
863 case-sensitive and it should conform to OpenOffice.org Calc sheet
864 name requirements. Note that in case of a numerical WSH this
865 number refers to the position in the worksheet stack, counted from
866 the left in a Calc window. The default is numerical 1, i.e. the
867 leftmost worksheet in the Calc file.
869 RANGE is expected to be a regular spreadsheet range format, or ""
870 (empty string, indicating all data in a worksheet). If no range
871 is specified the occupied cell range will have to be determined
872 behind the scenes first; this can take some time.
874 If only the first argument is specified, odsread will try to read
875 all contents from the first = leftmost (or the only) worksheet (as
876 if a range of '' (empty string) was specified).
878 If only two arguments are specified, odsread assumes the second
879 argument to be WSH and to refer to a worksheet. In that case
880 odsread tries to read all data contained in that worksheet.
882 The optional last argument REQINTF can be used to override the
883 automatic selection by odsread of one interface out of the
884 supported ones: Java/ODFtoolkit ('OTK'), Java/jOpenDocument
885 ('JOD') or Java/UNO bridge ('UNO').
887 Erroneous data and empty cells are set to NaN in NUMARR and turn
888 up empty in TXTARR and RAWARR. Date/time values in date/time
889 formatted cells are returned as numerical values in OBJ with base
890 1-1-000. Note that OpenOfice.org and MS-Excel have different date
891 base values (1/1/0000 & 1/1/1900, resp.) and internal
892 representation so MS-Excel spreadsheets rewritten into .ods format
893 by OpenOffice.org Calc may have different date base values.
895 NUMARR and TXTARR are trimmed from empty outer rows and columns,
896 so any returned array may turn out to be smaller than requested in
899 When reading from merged cells, all array elements NOT
900 corresponding to the leftmost or upper Calc cell will be treated
901 as if the "corresponding" Calc cells are empty.
903 odsread is just a wrapper for a collection of scripts that find out
904 the interface to be used and do the actual reading. For each call
905 to odsread the interface must be started and the Calc file read
906 into memory. When reading multiple ranges (in optionally multiple
907 worksheets) a significant speed boost can be obtained by invoking
908 those scripts directly (odsopen / ods2oct [/ parsecell] / ... /
913 A = odsread ('test4.ods', '2nd_sheet', 'C3:AB40');
914 (which returns the numeric contents in range C3:AB40 in worksheet
915 '2nd_sheet' from file test4.ods into numeric array A)
917 [An, Tn, Ra, limits] = odsread ('Sales2009.ods', 'Third_sheet');
918 (which returns all data in worksheet 'Third_sheet' in file test4.ods
919 into array An, the text data into array Tn, the raw cell data into
920 cell array Ra and the ranges from where the actual data came in limits)
922 See also: odsopen, ods2oct, oct2ods, odsclose, odswrite, odsfinfo,
929 # name: <cell-element>
933 Read data contained from cell range RANGE in worksheet WSH in
938 # name: <cell-element>
945 # name: <cell-element>
949 -- Function File: RSTATUS = odswrite (FILENAME, ARR)
950 -- Function File: RSTATUS = odswrite (FILENAME, ARR, WSH)
951 -- Function File: RSTATUS = odswrite (FILENAME, ARR, WSH, RANGE)
952 -- Function File: RSTATUS = odswrite (FILENAME, ARR, WSH, RANGE,
954 Add data in 1D/2D array ARR into sheet WSH in OpenOffice_org Calc
955 spreadsheet file FILENAME in cell range RANGE.
957 RSTATUS returns 1 if write succeeded, 0 otherwise.
959 FILENAME must be a valid .ods OpenOffice.org file name (including
960 file name extension). If FILENAME does not contain any directory
961 path, the file is saved in the current directory.
963 ARR can be any 1D or 2D array containing numerical or character
964 data (cellstr) except complex. Mixed numeric/text arrays can only
967 WSH can be a number or string. In case of a not yet existing
968 OpenOffice.org spreadsheet, the first sheet will be used & named
969 according to WSH - no extra empty sheets are created. In case of
970 existing files, some checks are made for existing sheet names or
971 numbers, or whether WSH refers to an existing sheet with a type
972 other than sheet (e.g., chart). When new sheets are to be added
973 to the spreadsheet file, they are inserted to the right of all
974 existing sheets. The pointer to the "active" sheet (shown when
975 OpenOffice.org Calc opens the file) remains untouched.
977 RANGE is expected to be a regular spreadsheet range. Data is
978 added to the sheet; existing data in the requested range will be
979 overwritten. Array ARR will be clipped at the right and/or bottom
980 if its size is bigger than can be accommodated in RANGE. If ARR
981 is smaller than the RANGE allows, it is placed in the top left
982 rectangle of RANGE and cell values outside that rectangle will be
985 If RANGE contains merged cells, only the elements of ARR
986 corresponding to the top or left Calc cells of those merged cells
987 will be written, other array cells corresponding to that cell will
990 The optional last argument REQINTF can be used to override the
991 automatic selection by odswrite of one interface out of the
992 supported ones: Java/ODFtooolkit ('OTK'), Java/jOpenDocument
993 ('JOD'), or Java/OpenOffice.org ('UNO').
995 odswrite is a mere wrapper for various scripts which find out what
996 ODS interface to use (ODF toolkit or jOpenDocument) plus code to
997 mimic the other brand's syntax. For each call to odswrite such an
998 interface must be started and possibly an ODS file loaded. When
999 writing to multiple ranges and/or worksheets in the same ODS file,
1000 a speed bonus can be obtained by invoking those scripts (odsopen /
1001 octods / .... / odsclose) directly.
1005 status = odswrite ('test4.ods', 'arr', 'Eight_sheet', 'C3:AB40');
1006 (which adds the contents of array arr (any type) to range C3:AB40
1007 in sheet 'Eight_sheet' in file test4.ods and returns a logical
1008 True (= numerical 1) in status if al went well)
1010 See also: odsread, oct2ods, ods2oct, odsopen, odsclose, odsfinfo
1016 # name: <cell-element>
1020 Add data in 1D/2D array ARR into sheet WSH in OpenOffice_org Calc
1025 # name: <cell-element>
1032 # name: <cell-element>
1036 Parse a string representing a range of cells for a spreadsheet
1037 into nr of rows and nr of columns and also extract top left
1038 cell address + top row + left column. Some error checks are implemented.
1042 # name: <cell-element>
1046 Parse a string representing a range of cells for a spreadsheet
1051 # name: <cell-element>
1058 # name: <cell-element>
1062 -- Function File: [ NUMARR, TXTARR, LIM ] = parsecell (RAWARR)
1063 -- Function File: [ NUMARR, TXTARR, LIM ] = parsecell (RAWARR, LIMITS)
1064 Divide a heterogeneous 2D cell array into a 2D numeric array and a
1065 2D cell array containing only strings. Both returned arrays are
1066 trimmed from empty outer rows and columns. This function is
1067 particularly useful for parsing cell arrays returned by functions
1068 reading spreadsheets (e.g., xlsread, odsread).
1070 Optional return argument LIM contains two field with the outer
1071 column and row numbers of NUMARR and TXTARR in the original array
1072 RAWARR. Optional input argument LIMITS can either be the
1073 spreadsheet data limits returned in the spreadsheet file pointer
1074 struct (field xls.limits or ods.limits), or the file ptr struct
1075 itself. If one of these is specified, optional return argument LIM
1076 will contain the real spreadsheet row & column numbers enclosing
1077 the origins of the numerical and text data returned in NUMARR and
1082 [An, Tn] = parsecell (Rn);
1083 (which returns the numeric contents of Rn into array An and the
1084 text data into array Tn)
1086 [An, Tn, lims] = parsecell (Rn, xls.limits);
1087 (which returns the numeric contents of Rn into array An and the
1088 text data into array Tn.)
1090 See also: xlsread, odsread, xls2oct, ods2oct
1096 # name: <cell-element>
1100 Divide a heterogeneous 2D cell array into a 2D numeric array and a 2D
1105 # name: <cell-element>
1112 # name: <cell-element>
1116 -- Function File: DATA = pch2mat (FILENAME)
1117 Converts NASTRAN PCH file (SORT2) to a data structure and
1118 frequency vector. A filename as a string is the only needed input.
1120 The output is in the form of struct. containing a freq vector n x
1121 1 called data.f, and the remaining data are in the form of
1122 subcases, point ids and directions respectively. for ex.
1123 data.S1.p254686.x and they are n x 2
1129 # name: <cell-element>
1133 Converts NASTRAN PCH file (SORT2) to a data structure and frequency
1138 # name: <cell-element>
1145 # name: <cell-element>
1149 -- Function File: [ TOPLEFTADDR, NROWS, NCOLS, TOPROW, LEFTCOL ] =
1150 spsh_chkrange ( RANGE, ROWSIZE, COLSIZE, INTF-TYPE, FILENAME)
1151 (Internal function) Get and check various cell and range address
1152 parameters for spreadsheet input.
1154 spsh_chkrange should not be invoked directly but rather through
1159 [tl, nrw, ncl, trw, lcl] = spsh_chkrange (crange, nr, nc, xtype, fileptr);
1165 # name: <cell-element>
1169 (Internal function) Get and check various cell and range address
1174 # name: <cell-element>
1181 # name: <cell-element>
1185 -- Function File: [ TYPE-ARRAY ] = spsh_prstype ( IARRAY, ROWSIZE,
1186 COLSIZE, CELLTYPES, OPTIONS)
1187 (Internal function) Return rectangular array with codes for cell
1188 types in rectangular input cell array IARRAY. Codes are contained
1189 in input vector in order of Numeric, Boolean, Text, Formula and
1192 spsh_prstype should not be invoked directly but rather through
1197 typarr = spsh_chkrange (cellarray, nr, nc, ctypes, options);
1203 # name: <cell-element>
1207 (Internal function) Return rectangular array with codes for cell types
1212 # name: <cell-element>
1219 # name: <cell-element>
1223 -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS)
1224 -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS, WSH)
1225 -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS, WSH, RANGE)
1226 -- Function File: [ RAWARR, XLS, RSTATUS ] = xls2oct (XLS, WSH, RANGE,
1228 Read data contained within cell range RANGE from worksheet WSH in
1229 an Excel spreadsheet file pointed to in struct XLS.
1231 XLS is supposed to have been created earlier by xlsopen in the
1232 same octave session.
1234 WSH is either numerical or text, in the latter case it is
1235 case-sensitive and it may be max. 31 characters long. Note that
1236 in case of a numerical WSH this number refers to the position in
1237 the worksheet stack, counted from the left in an Excel window. The
1238 default is numerical 1, i.e. the leftmost worksheet in the Excel
1241 RANGE is expected to be a regular spreadsheet range format, or ""
1242 (empty string, indicating all data in a worksheet). If no range
1243 is specified the occupied cell range will have to be determined
1244 behind the scenes first; this can take some time for the
1245 Java-based interfaces. Be aware that in COM/ActiveX interface the
1246 used range can be outdated. The Java-based interfaces are more
1247 reliable in this respect albeit much slower.
1249 Optional argument OPTIONS, a structure, can be used to specify
1250 various read modes by setting option fields in the struct to true
1251 (1) or false (0). Currently recognized option fields are:
1254 If set to TRUE or 1, spreadsheet formulas (if at all present)
1255 are read as formula strings rather than the evaluated formula
1256 result values. The default value is 0 (FALSE).
1259 Set the value of this field set to TRUE or 1 to strip the
1260 returned output array RAWARR from empty outer columns and
1261 rows. The spreadsheet cell rectangle limits from where the
1262 data actually came will be updated. The default value is
1263 FALSE or 0 (no cropping). When using the COM interface, the
1264 output array is always cropped.
1266 If only the first argument XLS is specified, xls2oct will try to
1267 read all contents from the first = leftmost (or the only)
1268 worksheet (as if a range of '' (empty string) was specified).
1270 If only two arguments are specified, xls2oct assumes the second
1271 argument to be WSH. In that case xls2oct will try to read all data
1272 contained in that worksheet.
1274 Return argument RAWARR contains the raw spreadsheet cell data.
1275 Use parsecell() to separate numeric and text values from RAWARR.
1277 Optional return argument XLS contains the pointer struct, If any
1278 data have been read, field XLS.limits contains the outermost
1279 column and row numbers of the actually returned cell range.
1281 Optional return argument RSTATUS will be set to 1 if the requested
1282 data have been read successfully, 0 otherwise.
1284 Erroneous data and empty cells turn up empty in RAWARR. Date/time
1285 values in Excel are returned as numerical values. Note that Excel
1286 and Octave have different date base values (1/1/1900 & 1/1/0000,
1287 resp.) Be aware that Excel trims RAWARR from empty outer rows &
1288 columns, so any returned cell array may turn out to be smaller
1289 than requested in RANGE, independent of field 'formulas_as_text'
1290 in OPTIONS. When using COM, POI, or UNO interface, formulas in
1291 cells are evaluated; if that fails cached values are retrieved.
1292 These may be outdated depending on Excel's "Automatic calculation"
1293 settings when the spreadsheet was saved.
1295 When reading from merged cells, all array elements NOT
1296 corresponding to the leftmost or upper Excel cell will be treated
1297 as if the "corresponding" Excel cells are empty.
1299 Beware: when the COM interface is used, hidden Excel invocations
1300 may be kept running silently in case of COM errors.
1304 A = xls2oct (xls1, '2nd_sheet', 'C3:AB40');
1305 (which returns the numeric contents in range C3:AB40 in worksheet
1306 '2nd_sheet' from a spreadsheet file pointed to in pointer struct xls1,
1307 into numeric array A)
1309 [An, xls2, status] = xls2oct (xls2, 'Third_sheet');
1311 See also: oct2xls, xlsopen, xlsclose, parsecell, xlsread,
1318 # name: <cell-element>
1322 Read data contained within cell range RANGE from worksheet WSH in an
1327 # name: <cell-element>
1334 # name: <cell-element>
1338 -- Function File: [ XLS] = xlsclose (XLS)
1339 -- Function File: [ XLS] = xlsclose (XLS, FILENAME)
1340 -- Function File: [ XLS] = xlsclose (XLS, "FORCE")
1341 Close the Excel spreadsheet pointed to in struct XLS, if needed
1342 write the file to disk. Based on information contained in XLS,
1343 xlsclose will determine if the file should be written to disk.
1345 If no errors occured during writing, the xls file pointer struct
1346 will be reset and -if COM interface was used- ActiveX/Excel will
1347 be closed. However if errors occurred, the file pinter will be
1348 untouched so you can clean up before a next try with xlsclose().
1349 Be warned that until xlsopen is called again with the same XLS
1350 pointer struct, hidden Excel or Java applications with associated
1351 (possibly large) memory chunks are kept in memory, taking up
1352 resources. If (string) argument "FORCE" is supplied, the file
1353 pointer will be reset regardless, whether the possibly modified
1354 file has been saved successfully or not. Hidden Excel (COM) or
1355 OpenOffice.org (UNO) invocations may live on, possibly even
1356 impeding proper shutdown of Octave.
1358 FILENAME can be used to write changed spreadsheet files to an
1359 other file than opened with xlsopen(); unfortunately this doesn't
1360 work with JXL (JExcelAPI) interface.
1362 You need MS-Excel (95 - 2010), and/or the Java package => 1.2.8
1363 plus Apache POI > 3.5 and/or JExcelAPI and/or OpenXLS and/or
1364 OpenOffice.org or clones installed on your computer + proper
1365 javaclasspath set, to make this function work at all.
1367 XLS must be a valid pointer struct made by xlsopen() in the same
1372 xls1 = xlsclose (xls1);
1373 (Close spreadsheet file pointed to in pointer struct xls1; xls1 is reset)
1375 See also: xlsopen, xlsread, xlswrite, xls2oct, oct2xls, xlsfinfo
1381 # name: <cell-element>
1385 Close the Excel spreadsheet pointed to in struct XLS, if needed write
1390 # name: <cell-element>
1397 # name: <cell-element>
1401 -- Function File: [ FILETYPE] = xlsfinfo (FILENAME [, REQINTF])
1402 -- Function File: [ FILETYPE, SH_NAMES] = xlsfinfo (FILENAME [,
1404 -- Function File: [ FILETYPE, SH_NAMES, FFORMAT] = xlsfinfo (FILENAME
1406 Query Excel spreadsheet file FILENAME for some info about its
1409 If FILENAME is a recognizable Excel spreadsheet file, FILETYPE
1410 returns the string "Microsoft Excel Spreadsheet", or '' (empty
1413 If FILENAME is a recognizable Excel spreadsheet file, optional
1414 argument SH_NAMES contains a list (cell array) of sheet names (and
1415 in case Excel is installed: sheet types) contained in FILENAME, in
1416 the order (from left to right) in which they occur in the sheet
1419 Optional return value FFORMAT currently returns '' (empty string)
1420 unless FILENAME is a readable Excel 97-2003 .xls file or an Excel
1421 2007 .xlsx / .xlsb file in which case FFORMAT is set to
1422 "xlWorkbookNormal". Excel 95 .xls files can only be read through
1423 the JXL (JExcelAPI) or UNO (OpenOffice.org) Java-based interfaces.
1425 If no return arguments are specified the sheet names are echoed to
1426 the terminal screen; in case of Java interfaces for each sheet the
1427 actual occupied data range is echoed as well. The occupied cell
1428 range will have to be determined behind the scenes first; this can
1429 take some time for the Java-based interfaces.
1431 If multiple xls interfaces have been installed, REQINTF can be
1432 specified. This can sometimes be handy, e.g. to get an idea of
1433 occupied cell ranges in each worksheet using different interfaces
1434 (due to cached info and/or different treatment of empty but
1435 formatted cells, each interfaces may give different results).
1437 For use on OOXML spreadsheets one needs full POI and/or UNO
1438 support (see xlsopen) and 'poi' or 'uno' needs to be specified for
1439 REQINTF. For Excel 95 file use 'jxl' or 'uno'.
1443 exist = xlsfinfo ('test4.xls');
1444 (Just checks if file test4.xls is a readable Excel file)
1446 [exist, names] = xlsfinfo ('test4.xls');
1447 (Checks if file test4.xls is a readable Excel file and return a
1448 list of sheet names and -types)
1450 See also: oct2xls, xlsread, xls2oct, xlswrite
1456 # name: <cell-element>
1460 Query Excel spreadsheet file FILENAME for some info about its contents.
1464 # name: <cell-element>
1471 # name: <cell-element>
1475 -- Function File: XLS = xlsopen (FILENAME)
1476 -- Function File: XLS = xlsopen (FILENAME, READWRITE)
1477 -- Function File: XLS = xlsopen (FILENAME, READWRITE, REQINTF)
1478 Get a pointer to an Excel spreadsheet in the form of return
1479 argument (file pointer struct) XLS. After processing the
1480 spreadsheet, the file pointer must be explicitly closed by calling
1483 Calling xlsopen without specifying a return argument is fairly
1486 To make this function work at all, you need MS-Excel (95 - 2003),
1487 and/or the Java package >= 1.2.8 plus Apache POI >= 3.5 and/or
1488 JExcelAPI and/or OpenXLS and/or OpenOffice.org (or clones)
1489 installed on your computer + proper javaclasspath set. These
1490 interfaces are referred to as COM, POI, JXL, OXS, and UNO, resp.,
1491 and are preferred in that order by default (depending on their
1492 presence). For OOXML support, in addition to Apache POI support
1493 you also need the following jars in your javaclasspath:
1494 poi-ooxml-schemas-3.5.jar, xbean.jar and dom4j-1.6.1.jar (or later
1495 versions). Later OpenOffice.org versions (UNO) have support for
1496 OOXML as well. Excel'95 spreadsheets can only be read by
1497 JExcelAPI and OpenOffice.org.
1499 FILENAME should be a valid .xls or xlsx Excel file name (including
1500 extension). But if you use the COM interface you can specify any
1501 extension that your installed Excel version can read AND write;
1502 the same goes for UNO (OpenOffice.org). Using the other Java
1503 interfaces, only .xls or .xlsx are allowed. If FILENAME does not
1504 contain any directory path, the file is saved in the current
1507 If READWRITE is set to 0 (default value) or omitted, the Excel file
1508 is opened for reading. If READWRITE is set to True or 1, an Excel
1509 file is opened (or created) for reading & writing.
1511 Optional input argument REQINTF can be used to override the Excel
1512 interface that otherwise is automatically selected by xlsopen.
1513 Currently implemented interfaces (in order of preference) are
1514 'COM' (Excel/COM), 'POI' (Java/Apache POI), 'JXL'
1515 (Java/JExcelAPI), 'OXS' (Java/OpenXLS), or 'UNO'
1516 (Java/OpenOffice.org - EXPERIMENTAL!). In most situations this
1517 parameter is unneeded as xlsopen automatically selects the most
1518 useful interface present.
1520 Beware: Excel invocations may be left running invisibly in case of
1521 COM errors or forgetting to close the file pointer. Similarly for
1522 OpenOffice.org which may even prevent Octave from being closed.
1526 xls = xlsopen ('test1.xls');
1527 (get a pointer for reading from spreadsheet test1.xls)
1529 xls = xlsopen ('test2.xls', 1, 'POI');
1530 (as above, indicate test2.xls will be written to; in this case using Java
1531 and the Apache POI interface are requested)
1533 See also: xlsclose, xlsread, xlswrite, xls2oct, oct2xls, xlsfinfo
1539 # name: <cell-element>
1543 Get a pointer to an Excel spreadsheet in the form of return argument
1548 # name: <cell-element>
1555 # name: <cell-element>
1559 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread
1561 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread
1563 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread
1565 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread
1566 (FILENAME, WSH, RANGE)
1567 -- Function File: [ NUMARR, TXTARR, RAWARR, LIMITS] = xlsread
1568 (FILENAME, WSH, RANGE, REQINTF)
1569 Read data contained in range RANGE from worksheet WSH in Excel
1570 spreadsheet file FILENAME. Return argument NUMARR contains the
1571 numeric data, optional return arguments TXTARR and RAWARR contain
1572 text strings and the raw spreadsheet cell data, respectively.
1573 Return argument LIMITS contains the outer column/row numbers of
1574 the read spreadsheet range where NUMARR, TXTARR and RAWARR have
1575 come from (remember, xlsread trims outer rows and columns).
1577 If FILENAME does not contain any directory, the file is assumed to
1578 be in the current directory. The filename extension (.xls or
1579 .xlsx) must be included in the file name; when using the COM
1580 interface all file formats can be read that are supported by the
1581 locally installed MS-Excel version (e.g., wk1, csv, dbf, etc.).
1583 RANGE is expected to be a regular spreadsheet range format, or ""
1584 (empty string, indicating all data in a worksheet). If no range
1585 is specified the occupied cell range will have to be determined
1586 behind the scenes first; this can take some time for the
1587 Java-based interfaces (but the results may be more reliable than
1588 that of ActiveX/COM).
1590 WSH is either numerical or text; in the latter case it is
1591 case-sensitive and it may be max. 31 characters long. Note that
1592 in case of a numerical WSH this number refers to the position in
1593 the worksheet stack, counted from the left in an Excel window. The
1594 default is numerical 1, i.e. the leftmost worksheet in the Excel
1597 If only the first argument is specified, xlsread will try to read
1598 all contents (as if a range of '' (empty string) was specified)
1599 from the first = leftmost (or the only) worksheet
1601 If only two arguments are specified, xlsread assumes the second
1602 argument to be RANGE if it is a string argument and contains a
1603 ":" or if it is '' (empty string), and in those cases assumes the
1604 data must be read from the first worksheet (not necessarily
1605 Sheet1! but the leftmost sheet).
1607 However, if only two arguments are specified and the second
1608 argument is numeric or a text string that does not contain a ":",
1609 it is assumed to be WSH and to refer to a worksheet. In that case
1610 xlsread tries to read all data contained in that worksheet.
1612 The optional last argument REQINTF can be used to override the
1613 automatic interface selection by xlsread out of the supported
1614 ones: COM/Excel, Java/Apache POI, Java/JExcelAPI, Java/OpenXLS, or
1615 Java/UNO (OpenOffice.org) (in that -built in- order of preference).
1616 For reading from OOXML files a value of 'com', 'poi' or 'uno' must
1617 be specified for REQINTF (see help for xlsopen); for Excel'95
1618 files use 'com', or if Excel is not installed use 'jxl', 'basic'
1619 or 'uno' (POI can't read Excel 95 but will try to fall back to
1620 JXL). As REQINTF can also be a cell array of strings, one can
1621 select or exclude one or more interfaces.
1623 Erroneous data and empty cells are set to NaN in NUMARR and turn
1624 up empty in TXTARR and RAWARR. Date/time values in Excel are
1625 returned as numerical values in NUMARR. Note that Excel and Octave
1626 have different date base values (1/1/1900 & 1/1/0000, resp.).
1627 Spreadsheet date values lying before 1/1/1900 are returned as
1628 strings, formatted as they appear in the spreadsheet. NUMARR and
1629 TXTARR are trimmed from empty outer rows and columns. Be aware
1630 that Excel does the same for RAWARR, so any returned array may
1631 turn out to be smaller than requested in RANGE.
1633 When reading from merged cells, all array elements NOT
1634 corresponding to the leftmost or upper Excel cell will be treated
1635 as if the "corresponding" Excel cells are empty.
1637 xlsread is just a wrapper for a collection of scripts that find out
1638 the interface to be used (COM, Java/POI, Java/JXL Java/OXS,
1639 Java/UNO) and do the actual reading. For each call to xlsread the
1640 interface must be started and the Excel file read into memory.
1641 When reading multiple ranges (in optionally multiple worksheets) a
1642 significant speed boost can be obtained by invoking those scripts
1643 directly as in: xlsopen / xls2oct [/ parsecell] / ... / xlsclose
1645 Beware: when using the COM interface, hidden Excel invocations may
1646 be kept running silently if not closed explicitly.
1650 A = xlsread ('test4.xls', '2nd_sheet', 'C3:AB40');
1651 (which returns the numeric contents in range C3:AB40 in worksheet
1652 '2nd_sheet' from file test4.xls into numeric array A)
1654 [An, Tn, Ra, limits] = xlsread ('Sales2009.xls', 'Third_sheet');
1655 (which returns all data in worksheet 'Third_sheet' in file 'Sales2009.xls'
1656 into array An, the text data into array Tn, the raw cell data into
1657 cell array Ra and the ranges from where the actual data came in limits)
1659 numarr = xlsread ('Sales2010.xls', 4, [], {'JXL', 'COM'});
1660 (Read all data from 4th worksheet in file Sales2010.xls using either JXL
1661 or COM interface (i.e, exclude POI interface).
1663 See also: xlswrite, xlsopen, xls2oct, xlsclose, xlsfinfo, oct2xls
1669 # name: <cell-element>
1673 Read data contained in range RANGE from worksheet WSH in Excel
1678 # name: <cell-element>
1685 # name: <cell-element>
1689 -- Function File: RSTATUS = xlswrite (FILENAME, ARR)
1690 -- Function File: RSTATUS = xlswrite (FILENAME, ARR, WSH)
1691 -- Function File: RSTATUS = xlswrite (FILENAME, ARR, WSH, RANGE)
1692 -- Function File: RSTATUS = xlswrite (FILENAME, ARR, WSH, RANGE,
1694 Add data in 1D/2D array ARR to worksheet WSH in Excel spreadsheet
1695 file FILENAME in cell range RANGE.
1697 RSTATUS returns 1 if write succeeded, 0 otherwise.
1699 FILENAME must be a valid .xls Excel file name (including file name
1700 extension). If FILENAME does not contain any directory path, the
1701 file is saved in the current directory.
1703 ARR can be any 1D or 2D array containing numerical or character
1704 data (cellstr) except complex. Mixed numeric/text arrays can only
1707 If only 3 arguments are given, the 3rd is assumed to be a
1708 spreadsheet range if it contains a ":" or is a completely empty
1709 string (corresponding to A1:IV65336 for regular .xls or
1710 A1:XFD1048576 for OOXML .xlsx). The 3rd argument is assumed to
1711 refer to a worksheet if it is a numeric value or a non-empty text
1712 string not containing ":"
1714 WSH can be a number or string (max. 31 chars). In case of a not
1715 yet existing Excel file, the first worksheet will be used & named
1716 according to WSH - the extra worksheets that Excel normally
1717 creates by default are deleted. In case of existing files, some
1718 checks are made for existing worksheet names or numbers, or
1719 whether WSH refers to an existing sheet with a type other than
1720 worksheet (e.g., chart). When new worksheets are to be added to
1721 the Excel file, they are inserted to the right of all existing
1722 worksheets. The pointer to the "active" sheet (shown when Excel
1723 opens the file) remains untouched.
1725 RANGE is expected to be a regular spreadsheet range. Data is
1726 added to the worksheet; existing data in the requested range will
1727 be overwritten. Array ARR will be clipped at the right and/or
1728 bottom if its size is bigger than can be accommodated in RANGE.
1729 If ARR is smaller than the RANGE allows, it is placed in the top
1730 left rectangle of RANGE and remaining cell values outside the
1731 rectangle will be retained.
1733 If RANGE contains merged cells, only the elements of ARR
1734 corresponding to the top or left Excel cells of those merged cells
1735 will be written, other array cells corresponding to that cell will
1738 The optional last argument REQINTF can be used to override the
1739 automatic selection by xlswrite of one interface out of the
1740 supported ones: 'com' (ActiveX/Excel), 'poi' (Java/Apache POI),
1741 'jxl' (Java/JExcelAPI), or 'uno' (Java/OpenOffice.org). 'oxs'
1742 (Java/OpenXLS) is implemented but disabled for writing as it is
1743 too buggy. For writing to OOXML files (.xlsx) a value of 'com',
1744 'poi' or 'uno' must be specified for REQINTF. The value of REQINTF
1745 is case-insensitive. Multiple interfaces can be selected if
1746 entered as a cell array of strings.
1748 xlswrite is a mere wrapper for various scripts which find out what
1749 Excel interface to use (COM, POI, etc) plus code to mimic the other
1750 brand's syntax. For each call to xlswrite such an interface must be
1751 started and possibly an Excel file loaded. When writing to multiple
1752 ranges and/or worksheets in the same Excel file, a speed bonus can
1753 be obtained by invoking those scripts directly with multiple calls
1754 to oct2xls (one for each sheet or range) surrounded by one call to
1755 xlsopen and xlsclose: (xlsopen / octxls / oct2xls / .... /
1760 status = xlswrite ('test4.xls', 'arr', 'Third_sheet', 'C3:AB40');
1761 (which adds the contents of array arr (any type) to range C3:AB40
1762 in worksheet 'Third_sheet' in file test4.xls and returns a logical
1763 True (= numerical 1) in status if al went well)
1765 See also: xlsread, oct2xls, xls2oct, xlsopen, xlsclose, xlsfinfo
1771 # name: <cell-element>
1775 Add data in 1D/2D array ARR to worksheet WSH in Excel spreadsheet file
1780 # name: <cell-element>
1787 # name: <cell-element>
1791 -- Function File: NB = xmlwrite (FILENAME, VALUE)
1792 -- Function File: NB = xmlwrite (FD, VALUE, [NAME])
1793 Write a VALUE into FILENAME (FD) as an XML file.
1795 The number of elements (NB) or 0 is returned.
1800 # name: <cell-element>
1804 Write a VALUE into FILENAME (FD) as an XML file.