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 !