Topic: Where's the OpenDCL documentation?

[MP]

By my count there's about 887 OpenDCL functions exposed to AutoLISP, yet I've found documentation for maybe two dozen entries -- where's the rest? Note, I did check the source forge site.

For example, it would be nice to view the docs for closebin, openbin, readbin, writebin ...

Thanks!

[Kerry]

Michael, good to hear from you.
There are quite a few commands exposed in AutoCAD that have never been documented. I've made no attempt , to date, to formalise any of these legacy commands because I believed they were leftovers from experimental ideas Chad had at the time.
Now that the code is tighter and producing consistant results, the time may be right to formalise or remove some of those commands, subject to Owens comments.


The browser is the primary location for finding command descriptions.

[Kerry]

.................For example, it would be nice to view the docs for closebin, openbin, readbin, writebin ...

Thanks!

At the risk of repeating myself ..

Those commands look like they have some potential. !

[MP]

Michael, good to hear from you.

You too Kerry, looks like we're equally busy.

There are quite a few commands exposed in AutoCAD that have never been documented. I've made no attempt , to date, to formalise any of these legacy commands because I believed they were leftovers from experimental ideas Chad had at the time.

Completely understandable. It's a huge undertaking that Owen and Co. have willingly taken on, and the documentation side won't be any cake walk either.

Now that the code is tighter and producing consistent results, the time may be right to formalise or remove some of those commands, subject to Owens comments.

I just hope potentially useful stuff isn't prematurely dumped because of obscurity, like the functions I mentioned in my first post. O/T: can't seem to get the readbin function to return anything. Will have to do more experimenting (binary I/O has been a glaring omission from lisp that I've always missed, resorting to VB / dlls to do the grunt work and report back to lisp -- would be nice to work a little more directly). But I digress ...

The browser is the primary location for finding command descriptions.

Indeed, but it (appears to) drive right past functions that are not form / control centric.

Cheers | Be well | Thanks for the responses.

[Kerry]

The browser is the primary location for finding command descriptions.

Indeed, but it (appears to) drive right past functions that are not form / control centric.

Cheers | Be well | Thanks for the responses.

Yes, you're correct. We should ensure that descriptions and samples are available.

[MP]

Yes, you're correct. We should ensure that descriptions and samples are available.

As you may have surmised, I don't have the luxury of a lot of time these days, but I will endeavor to make a genuine attempt to flag and share anything I note in the docs and source code (stuff I understand that is) that in my mind needs attention of some kind.

Thank you for working on the the documentation Kerry -- generally a thankless task, but ever so important, so vital.

[Kerry]

........... documentation .. -- generally a thankless task, but ever so important, so vital.

Yes, and David White has done an admirable job.

[Kerry]

Michael, I've had a quick look at the functions  closebin, openbin, readbin, writebin

As Owen indicated, the signatures seem to be ;

(odcl_openbin "<filename>" {"r"|"w"}) => opens a file for read or write and returns a file handle

(odcl_closebin <file-handle>) => closes a previously opened file

(odcl_writebin <file-handle> <data1> <data2> ...) => persists arbitrary lisp
data to the file (lists may not be nested more than 2 levels deep)

(odcl_readbin <file-handle>) => reads and returns a list of all data items in the file

The results of testing indicates that some work needs to be done to make the functions bombproof .. but they do work ..

;;///--------------------
;; Test 01
;;
(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-1" "w"))
;;->159287144

(SETQ tmp (ODCL_WRITEBIN fnHandle "Test Data" 1234 56.7 (LIST 8 9)))
;;-> T

;;File must be closed.
(SETQ tmp (ODCL_CLOSEBIN fnHandle))
;;-> nothing ??
;;NOTE : if file is saved twice an Unhandled Exception Reading Violation is generated.



(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-1" "r"))
;;-> 159287864 

(SETQ tmp (ODCL_READBIN fnHandle))
;;-> "Test Data"

(SETQ tmp (ODCL_READBIN fnHandle))
;;-> 1234

(SETQ tmp (ODCL_READBIN fnHandle))
;;-> 56.7

(SETQ tmp (ODCL_READBIN fnHandle))
;;-> (8.0 9.0)

(SETQ tmp (ODCL_READBIN fnHandle))
;;-> nothing ??
;;NOTE : if file is read further an Unhandled Exception is generated.

;;File must be closed.
(SETQ tmp (ODCL_CLOSEBIN fnHandle))
;;-> nothing returned ??


;;///--------------------
;; Test 02
(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-1" "r"))
;;-> 159288584

(SETQ res 0
      result '()
)

(WHILE res
    (SETQ res    (ODCL_readBIN fnHandle)
          result (CONS res result)
    )
    (VL-PRIN1-TO-STRING result)
)

;;-> Unhandled exception, then "(nil   (8.0 9.0) 56.7 1234 \"Test Data\")" 

(SETQ tmp (ODCL_CLOSEBIN fnHandle))

;;///--------------------
;; Test 03
;;
(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-03" "w"))
;;->159287144

(SETQ
    ent (car (entsel))
    tmp (ODCL_WRITEBIN fnHandle (list "Test Data" 1234 56.7 (LIST 8 9) ent )))
;;-> T

;;File must be closed.
(SETQ tmp (ODCL_CLOSEBIN fnHandle))

(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-03" "r"))
(SETQ tmpdata (ODCL_READBIN fnHandle))
;;-> ("Test Data" 1234 56.7 (8.0 9.0) <Entity name: 7efbb2f0>) 

(SETQ tmp (ODCL_CLOSEBIN fnHandle))

.


The data appears to work best at the moment wrapped as a list. Sequential data blobs cause an issue.

As subsequent reads step through the saved items having some form of counter would be handy, or having an identifier for the end of the list ... I'm not sure that 'nil' returned at the end on the data would be suitable because one of the data items may have a nil value and confuse the issue.

These functions definately have potential and I can see their inclusion enhancing the product.

The (odcl_readbin .. does not behave nicely ..

[It's Alive!]

I almost have ODCL_WRITEBIN and ODCL_READBIN cleaned up the way I like it.

No limitation on nesting lists
Each write adds to the list
ODCL_READBIN returns everything in the file as a list

Example:

Code: [Select]

(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-1" "w"))
(SETQ tmp (ODCL_WRITEBIN fnHandle '((1 1)(2 3)) ))
(SETQ tmp (ODCL_WRITEBIN fnHandle (cons 3 3)))
(SETQ tmp (ODCL_WRITEBIN fnHandle '((((((((((1))))))))))  ))
(SETQ tmp (ODCL_WRITEBIN fnHandle "Wow Dood"  ))
(SETQ tmp (ODCL_CLOSEBIN fnHandle))

(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-1" "r"))
(SETQ tmp (ODCL_READBIN fnHandle))
;;-> returns (((1.0 1.0) (2.0 3.0)) (3 . 3) ((((((((((1)))))))))) "Wow Dood")
(SETQ tmp (ODCL_CLOSEBIN fnHandle))

Should I add the code necessary to read/write DXF/XDATA too

Code: [Select]

(SETQ tmp (ODCL_WRITEBIN fnHandle (entget(car(entsel))) ))

[Kerry]

Ver Beta 16 has been revised.

Date: 2007-06-11 08:13
Sender: owenwengerd

In Beta 16, (odcl_readbin) no longer crashes when reading past the end of
the file. The function will just return nil when no more data can be read
(or if there was an error). Likewise, the other functions return nil on
failure, non-nil on success. I added a new (odcl_checkbin) function that
returns nil on error, -1 if the last file operation produced an error, 1 if
the end of file marker has been read (note that the EOF marker isn't read
until *after* calling readbin one more time after the last valid data is
read -- kinda weird, but that's the way it was coded).

The upshot of these functions are that you are expected to know how many
data items were written, and read the same amount of data items back in. If
you have variable data, you should write a count to the file before writing
the data items. The new (odcl_checkbin) function can be used to test for
error state or EOF, but there is no protection against passing a file
handle that has already been closed (doing so will inevitably cause a
crash).

[Kerry]

I almost have ODCL_WRITEBIN and ODCL_READBIN cleaned up the way I like it.

No limitation on nesting lists
Each write adds to the list
ODCL_READBIN returns everything in the file as a list

Daniel, have a look at the beta 16 source. Can you pass your rework on to Owen and we'll get it included in the next build.

..............
Should I add the code necessary to read/write DXF/XDATA too
.........

Code: [Select]

(SETQ tmp (ODCL_WRITEBIN fnHandle (entget(car(entsel))) ))

That would be nice, 'cause the nested limit at the moment would kill that, yes ?

.. So would some generic tools to read and write INI and CSV and XML
oh, and while you're at it, ......< include personal.wishlist; >

[It's Alive!]

Someone want to run a few tests or have a looksie at the code to see if I biffed?  
Ps I added a bool m_bIsOpen; so it souldn’t crash if you close a file twice

[Kerry]

Ohhh, pick me, pick me !

[It's Alive!]

Ohhh, pick me, pick me !

Awesome. I hope it works.. try it with xdata too

Code: [Select]

(SETQ tmp (ODCL_WRITEBIN fnHandle (entget(car(entsel))'("yourApp")) ))

[Kerry]

I've had a quick play, but I need to be in a production meeting so I'll have a look tonight Dan.

Looks good.

I noticed that the readBin doesn't like being called twice ... { though that's just to idiot proof it I 'spose }
  ...

Works nicely with entity lists.

... and with my dataLists from my GridControls ... Wheeeee !

[Kerry]

.... and this was saved

(SETQ tmp (ODCL_WRITEBIN fnHandle (entget(car(entsel))'("ACAD")) ))

and read as ;

((-1 . <Entity name: 7efbc678>)
 (0 . "DIMENSION")
 (330 . <Entity name: 7efb7d18>)
 (5 . "B77")
 (100 . "AcDbEntity")
 (67 . 0)
 (410 . "Model")
 (8 . "ST-DIM")
 (100 . "AcDbDimension")
 (2 . "*D66")
 (10 773.851 4090.5 0.0)
 (11 573.384 4125.5 0.0)
 (12 0.0 0.0 0.0)
 (70 . 32)
 (1 . "")
 (71 . 5)
 (72 . 1)
 (41 . 1.0)
 (42 . 400.934)
 (73 . 0)
 (74 . 0)
 (75 . 0)
 (52 . 0.0)
 (53 . 0.0)
 (54 . 0.0)
 (51 . 0.0)
 (210 0.0 0.0 1.0)
 (3 . "STD35$0")
 (100 . "AcDbAlignedDimension")
 (13 372.917 3757.99 0.0)
 (14 773.851 3757.99 0.0)
 (15 0.0 0.0 0.0)
 (16 0.0 0.0 0.0)
 (40 . 0.0)
 (50 . 0.0)
 (100 . "AcDbRotatedDimension")
 (-3 ("ACAD" (1000 . "DSTYLE")
             (1002 . "{")
             (1070 . 40)
             (1040 . 10.0)
             (1070 . 179)
             (1070 . 1)
             (1002 . "}")
     )
 )
)

[It's Alive!]

Thanks Kerry 
I think I can fix the "reading twice crash"
 

[It's Alive!]

here is another version 

[Kerry]

Thanks Dan,
I'm leaving to catch my train .. so I'll look tonight.

[Kerry]

Works for me Dan !! 

Great Stuff. 

Can you send it to Owen please .. and become part of OpenDCL's history

Michael may want to try to break it first though.


(SETQ fnHandle (ODCL_OPENBIN "c:\\testBinFile-1" "w"))
;;

(SETQ tmp (ODCL_WRITEBIN fnHandle nil (list nil) (cons nil nil)))
;;

(SETQ tmp (ODCL_CLOSEBIN fnHandle))

;; then read
;;=> (nil (nil) (nil))

[It's Alive!]

This one seems to be pretty stable. One issue we should consider, is that importing a whole file into a single list has its limitations. I did a little performance testing, writing files is always extremely fast. Reading 10000 cons lists (cons 101 "1234567890" ) was pretty fast. Reading a 3 megabyte file will certainly fail. Personally I’m going to be working with small amounts of data, so this is perfect for me. But I can’t speak for all the ODCL users..
here is my latest version

[It's Alive!]

I think I want to make one more modification.

(ODCL_READBIN fnHandle T) read the contents to a list
(ODCL_READBIN fnHandle ) read line by line as entered

Opinions?

[Kerry]

Daniel,
This will be VERY handy.
In the past I've saved values for dialogs an command line data input into a global association list .. and read the variable values whenever I called a new instance of the dialog.

The extended capability of WriteBIN and ReadBIN allows me to <in effect> serialize the dialog fields economically .. and reuse them tomorrow or nexr week or exchange them between users.  .. nice stuff.


PS the difference in file size between a debug version and release version is significant, yes !

[Kerry]

I think I want to make one more modification.

(ODCL_READBIN fnHandle T) read the contents to a list
(ODCL_READBIN fnHandle ) read line by line as entered

Opinions?

Sounds like that may be usefull !

I'd use the T flag for line by line ... but I don't think it would matter .. either way would work provided we document it.

[MP]

Very interesting discussion(s) but I must say I'm kinda vexed -- I had assumed with names like readbin, writebin etc. that these functions would allow me to read and write in full binary mode, so I could, for example, open a file and examine it byte for byte, or streams of bytes, not being tripped up by nulls or ascii z (eof trigger) etc.

[It's Alive!]

Very interesting discussion(s) but I must say I'm kinda vexed -- I had assumed with names like readbin, writebin etc. that these functions would allow me to read and write in full binary mode, so I could, for example, open a file and examine it byte for byte, or streams of bytes, not being tripped up by nulls or ascii z (eof trigger) etc.

You’re right, maybe the methods should have been called ReadArchive and WriteArchive.  Essentially it is reading writing in a binary stream format but it’s converting the data to and from types that lisp uses, or what can be put in a result buffer.
There really isn’t an EOF, so the code is writing both an EOL and an EOF marker, so the code knows where to stop and pass the result buffer back to lisp.

Is Reading and writing in a raw byte stream, a feature you would like to have included in ODCL?  Since we are using CArchive, we can use some of that class’s other methods see http://msdn2.microsoft.com/en-us/library/caz3zy5s(VS.80).aspx 

[MP]

You’re right, maybe the methods should have been called ReadArchive and WriteArchive.  Essentially it is reading writing in a binary stream format but it’s converting the data to and from types that lisp uses, or what can be put in a result buffer.
There really isn’t an EOF, so the code is writing both an EOL and an EOF marker, so the code knows where to stop and pass the result buffer back to lisp.

Thanks for explaining the undercarriage Daniel.

Is Reading and writing in a raw byte stream, a feature you would like to have included in ODCL?

In a word yes, but don't front burner it merely for me. <Spock> The needs of the many outweigh the needs of the few -- or the one </Spock>.

Since we are using CArchive, we can use some of that class’s other methods see http://msdn2.microsoft.com/en-us/library/caz3zy5s(VS.80).aspx

I looked at said class and I don't think it would do what I'd want (tho I could be wrong). Essentially I'd like the ability to read and write binary data, probably as list of the ascii codes. While read-char will read a file a byte at a time (including nulls), it will stop on an false eof file marker (ascii 26). Worse, write-char won't let one write nulls, essential for binary I/O.

If one were to draft a quick signature for some of the functions (forgive me, I'm pounding this out real fast because I've only a few minutes) ...

(BinOpen filename "r" | "w" | "rw")

(setq handle (BinOpen "c:\\MyData.data" "rw")) ;; opened for read and write.

(BinGet handle address [length]) ;; optional length, if nil or not present read to true eof

(setq bigStream (BinGet handle 0)) ;; get entire file.

(BinPut handle address listOfAsciiCodes) ;; address is 0 based

(BinPut handle 0 (append '(0 87 111 111 116 33) bigStream)) ;; insert 6 new values to the beginning of the file, starting with a null value (0).

Hope this makes sense.


Like I said, this is just my own wish. Before tackling something like this it's probably advisable to poll the community and see if there's enough interest to warrant the efforts.

Thanks for your interest Daniel (and your most excellent efforts to support the OpenDCL community).

[It's Alive!]

Ok, Try this one guys

Due to what I think might be a bug in AutoCAD, one should be careful of using doted pair lists that begin with a  DXF code.
Two buggy ones I have found are.

(odcl_writebin fnhandle (cons 5005 "Hello")); returns (“hello”)
(odcl_writebin fnhandle (cons 5001 "Hello")); returns junk

Other than that this is a really cool feature for archiving lisp data, entity lists, xdata

Changes:
(odcl_readbin fnhandle t) reads entry by entry
(odcl_readbin fnhandle ) reads everything