ADVANCED: How To Call The Mac OS Directly From LabVIEW Part VI: Documentation and Error Handling
Let's take a break from the detailed "how to" of calling the OS, and spend some time talking about documentation and error handling.
First, lets talk about documentation. Because there is not always a one to one relationship between C code and LabVIEW code, its usually a good idea to include the information from the header file, and any accompanying documentation, on the call. This would include prototype, description, parameter descriptions, return value, side effects, conditions and any other documentation. You will also want to include struct, enum and constant declarations. When including struct documentation, calculate the offsets of each member of the struct and include them in the documentation.
I like to keep most of this information in labels on the block diagram. That way I can better see a relationship between the C code and the LabVIEW code. If you use any constants, set the label on the constant to the C name for the constant.
Any of the parameters that you expose on the front panel should have the parameter description and any other documentation from the function description that would be needed to make the call. You will probably also want to include much of the overview and description in the VI documentation also, so it can be read from Context Help.
As far as error handling, there are a few things to keep in mind. In most cases, if an error comes in, you do not want to make any calls into the OS. The exceptions would be disposeXXX, deleteXXX, freeXXX, releaseXXX, closeXXX, etc. Things that terminate a data type need to be called to do cleanup, and then you have to merge any errors you get with the error in cluster (which gets precedence).
Usually, there will be a big switch on the error in terminal, with the no error case making the calls. If the call returns an OSErr or an OSStatus, you can check for zero. If it is zero, just return the error in, otherwise, set status to true, the code to the OSErr or OSStatus, and put the VI name in the source (or something meaningful to track down the error).
If you allocate, retain, create, etc. something on your block diagram, try to make sure it is always cleaned up properly before your diagram ends.
First, lets talk about documentation. Because there is not always a one to one relationship between C code and LabVIEW code, its usually a good idea to include the information from the header file, and any accompanying documentation, on the call. This would include prototype, description, parameter descriptions, return value, side effects, conditions and any other documentation. You will also want to include struct, enum and constant declarations. When including struct documentation, calculate the offsets of each member of the struct and include them in the documentation.
I like to keep most of this information in labels on the block diagram. That way I can better see a relationship between the C code and the LabVIEW code. If you use any constants, set the label on the constant to the C name for the constant.
Any of the parameters that you expose on the front panel should have the parameter description and any other documentation from the function description that would be needed to make the call. You will probably also want to include much of the overview and description in the VI documentation also, so it can be read from Context Help.
As far as error handling, there are a few things to keep in mind. In most cases, if an error comes in, you do not want to make any calls into the OS. The exceptions would be disposeXXX, deleteXXX, freeXXX, releaseXXX, closeXXX, etc. Things that terminate a data type need to be called to do cleanup, and then you have to merge any errors you get with the error in cluster (which gets precedence).
Usually, there will be a big switch on the error in terminal, with the no error case making the calls. If the call returns an OSErr or an OSStatus, you can check for zero. If it is zero, just return the error in, otherwise, set status to true, the code to the OSErr or OSStatus, and put the VI name in the source (or something meaningful to track down the error).
If you allocate, retain, create, etc. something on your block diagram, try to make sure it is always cleaned up properly before your diagram ends.
posted by Marc | 9:30 AM
0 Comments:
Post a Comment
<< Home