Page 1 of 2 12>
Topic Options
#64533 - 2002-04-15 02:58 AM UDF Design
Howard Bullock Offline
KiX Supporter
*****

Registered: 2000-09-15
Posts: 5809
Loc: Harrisburg, PA USA
Discussion Issue.

I have been internally debating how a properly constructed UDF should return data including errorcodes and would like input from the board.

Is it as simple as always using "Exit x"?

In some of my UDF's I return an array where the first array element is the value expected to be returned by the UDF and the second and third are the errorcode and error text that may have been encountered by an function or COM call internal to the UDF. For the sake of consistent development, is there a methodology that is preferred over others?

Should a UDF define custom error conditions and use Exit to set @error to a non Microsoft OS error number?

Any and all thoughts are expected.
_________________________
Home page: http://www.kixhelp.com/hb/

Top
#64534 - 2002-04-15 11:56 AM Re: UDF Design
Schuliebug Offline
Hey THIS is FUN
*****

Registered: 2002-01-18
Posts: 379
Loc: Netherlands
Howard,

I try to use exit codes just as Ruud does in the standard Kix functions. E.g. when creating a function InGroups which checks if the user is member of all the groups given, i return the same @error as the InGroup function does.

If it is a completely new UDF, there's no standard. I prefer however to set the @error only if an error occurs (@error=0; no error, @error>0; error !).
_________________________
Kind regards,

Top
#64535 - 2002-04-15 02:34 PM Re: UDF Design
Shawn Administrator Offline
Administrator
*****

Registered: 1999-08-13
Posts: 8611
My two cents:

I think your right, but there are some tough decisions one must make. I`ll make the statement that one should always set the value of @ERROR using EXIT(n). Having said that, here`s some scenarios:

If your function returns data, then you really (should) have no choice. Always set the value of @ERROR using EXIT(n). I would NOT recommend returning an error code as part of the data itself. Why ? Because its not really the standard (kixtart) way of doing things.

If your function doesn`t return any data. Then you got some decisions to make. Should you return the error code ? Should you return nothing and set @ERROR ? Should you do both ?

Looking to Kixtart for guidance isn`t much help because some kixtart functions (like commands) just set the value of @ERROR, while some return @ERROR and set @ERROR.

The nice thing about returning @ERROR is that folks can use your UDF in conditionals, kinda like the OPEN function, eg:

if open(1,"filename") = 0
...
endif

The "problem" with returning @ERROR is that folks will always have to "silence" your UDF if they are not interested in its return code:

$= open(1,"filename")

Sometimes its nice not to have to "worry" about silencing a function. But given that silencing is a quirk unique only to kixtart, and that UDFs are functions and NOT commands, I would suggest that you bite the bullet and do it the kixtart way, and that is to return @ERROR and set @ERROR.

The only exception to this might be highy specialized functions, functions that are more like procedures than anything else. Or for functions that rarely if ever fail (ie console writting functions) or has good error checking, applies lots of defaults and has flawless error recovery.

-Shawn

[ 15 April 2002, 14:39: Message edited by: Shawn ]

Top
#64536 - 2002-04-15 03:37 PM Re: UDF Design
Richard H. Administrator Offline
Administrator
*****

Registered: 2000-01-24
Posts: 4946
Loc: Leatherhead, Surrey, UK
I agree with Shawn with regard to @ERROR. There is no really compelling reason not to set it. One of the minor criticisms of KiXtart is that the use of @ERROR is inconsistant.

You should be able to rely on @ERROR to report the success/failure of a function call in every case, whether it can be intuited from the data returned or not.

Howard, if you are going to use an array to return data, I suggest you re-order it slightly so that the error value is always in the same place. My personal preference would be:
quote:
Element 0 = Error Value
Element 1 = Error String
Element 2 = Number of data returned
Element 3 = Datum 1
Element 4 = Datum 2
...
Element n+2 = Datum n


Top
#64537 - 2002-04-16 02:31 AM Re: UDF Design
Jack Lothian Offline
MM club member
*****

Registered: 1999-10-22
Posts: 1169
Loc: Ottawa,Ontario, Canada
I don't think there is any obvious standard that is an optimal solution in all cases. Returning arrays, no matter how you order them, makes using the function rather complicated. Maybe it is something that should be left open.
_________________________
Jack

Top
#64538 - 2002-04-16 10:30 AM Re: UDF Design
Richard H. Administrator Offline
Administrator
*****

Registered: 2000-01-24
Posts: 4946
Loc: Leatherhead, Surrey, UK
The problem is that there is no clean standard way to return multiple values. This thread is proposing a way of defining a standard method to achieve it. It's not about enforcing a method but rather producing quidelines for a standard way of doing it if you want to, the "KiXtart Result Array Passing" HOWTO if you like. Perhaps someone can think up an acronym for it?

The purpose of ordering the values in a particular way is so that it makes sense for the error value to be in the same place every time.

I don't believe that the process adds significant complexity. Here is a trivial example:
code:
Function udfSquare($iNumber)
Dim $Result[4]
;
$Result[0]=0 ; Success
$Result[1]="Operation completed successfully"
;
$Result[3]=$iNumber * $iNumber
$Result[2]=1 ; One data value returned
;
$udfSquare=$Result
Exit $Result[0] ; Set ERROR on exit
EndFunction
;
;
$avResult=udfSquare(1024)
If @ERROR
udfErrorHandler($avResult)
Else
"Result: " $avResult[3]
EndIf

There is very little extra code in the function, and no extra code in the calling script.

You can immediatley see another benefit. If an error occurs I hand off the processing to a generic error handler routine. This can display the error number and message, and can even display the returned value(s) for debugging. This error handling will work for every function which is coded with an array returned in the suggested format.

[ 16 April 2002, 10:31: Message edited by: Richard Howarth ]

Top
#64539 - 2002-04-16 01:39 PM Re: UDF Design
Howard Bullock Offline
KiX Supporter
*****

Registered: 2000-09-15
Posts: 5809
Loc: Harrisburg, PA USA
Richard, with your latest post this thread is headed right where I hoped it would. My goal was to spur discussion and possibly develop some level of consensus about UDF design.

My issue started with the TranslateName UDF. I have four COM calls and wanted to know the original error text which indicated which call failed. This detail was lost if I only set @error with Exit(@error). You are correct the main reason for pursuing this direction is the enhanced ability to return sufficient information for properly reporting the failure and start debugging or even just understanding the issue is the code itself is sound.

The TranslateName UDF was failing on specific computers from time to time. It was a real pain. The additional data returned help isolate the problem to the NameTranslate.Init call which in turn was traced to a DNS issue that kept the client from finding the GC:.
_________________________
Home page: http://www.kixhelp.com/hb/

Top
#64540 - 2002-04-16 06:10 PM Re: UDF Design
Jack Lothian Offline
MM club member
*****

Registered: 1999-10-22
Posts: 1169
Loc: Ottawa,Ontario, Canada
The point I was trying to make was not about enforcing standards rather it was a question about where should one should take kixtart. In my opinion, one of kixtart greatest advantages was its simplicity. Novices could leap right in and use it. You didn’t need to be a programmer or think like one to use it. In a previous life, I was a programmer and I understand good programming practices but I also know that everyone in the world can not think like a programmer.

As a example, EXCEL use to be a wonderful programming tool used by hundreds of thousands of non programmers. Many years ago even secretaries made word & excel macros. Today, visual basic for applications replaces those old macros & all those people stopped making “programs”. Only hard core programmers think this is an improvement. Unfortunately, at MS the teckies dominate & programming for the masses is not an option.

In my mind, I always thought Ruud swam against this flow. He was a teckie who tried to talk to the masses.

I was just posing a question about balance. Don’t forget the masses.
_________________________
Jack

Top
#64541 - 2002-04-16 07:21 PM Re: UDF Design
Shawn Administrator Offline
Administrator
*****

Registered: 1999-08-13
Posts: 8611
Jack, et al

[good to see you back by the way, Jack]

I agree with Jack. Making a UDF more complex than it needs to be just doesn't make sense. After all, the whole purpose of the UDF in first place was to hide some sort of complexity. Im not saying that returning structured arrays is complex, just that its overkill for the job at hand.

My strategy has always been to "recycle" existing Microsoft @ERROR codes (and ideally their asscociated @SERROR string descriptions). For example, if one builds a UDF to search an array for a string, and one wanted an error code to represent string not found, simply recycle ERROR 2 (file not found). If an internal UDF function or command failed, one might just blindy return that to the user, then abort the UDF.

The other strategy one may use is to simply define your own error codes, starting at a base (say 1) and working-up to however many you need. Or I think theres an upper limit to the number of win32 error codes anyways, so maybe you could start your numbering at that level (i think if you go above 6000 your safe). But, one may critize this strategy by saying that the std @SERROR descriptions won't "line-up" with the meaning.

I know things get can get tricky with larger UDF's. A UDF that has many steps with function calls that can potentially return the same ERROR code (how would the user know which "step" failed), but the given the ideals behind encapsulation, the question becomes:

"Should the user care which step failed" ?

I've rambled.

-Shawn

[ 16 April 2002, 19:28: Message edited by: Shawn ]

Top
#64542 - 2002-04-16 09:30 PM Re: UDF Design
Howard Bullock Offline
KiX Supporter
*****

Registered: 2000-09-15
Posts: 5809
Loc: Harrisburg, PA USA
Rambling is good as long as its close to the topic.
_________________________
Home page: http://www.kixhelp.com/hb/

Top
#64543 - 2002-04-16 11:26 PM Re: UDF Design
New Mexico Mark Offline
Hey THIS is FUN
****

Registered: 2002-01-03
Posts: 223
Loc: Columbia, SC
A couple of additional thoughts here:

1. Shawn has a good point about recycling MS error codes, where possible. However, a UDF that uses hundreds or thousands of possible error codes is far exceeding the scope of a function. If you limit (and therefore identify) a subset of MS errors, you might as well make your own system.

2. There are two ways to represent errors. If only one error will ever be returned, a 32-bit integer can represent over billions of distinct errors. However, in most cases, there is less need for this many error codes and more need for one error number that can represent zero, one, or more than one simultaneous errors. In this case, a 32-bit number can represent 32 distinct errors. Of course, there are still billions of possible combinations of errors, but one only need parse the 32 bits and use error handling as necessary from there.

For example, we have a pretty extensive logon script, as it is doing much of the job in lieu of SMS while the USAF is experimenting with brain-dead Tivoli [motto - "We do one-quarter of the job of SMS at only twenty times the cost!"]. First, I set the values of the errors, with the array element number corresponding to the bit number of the error.

code:
; General structure is:
; Bits 0 - 7 General messages and minor change reporting
; Bits 8 - 15 Major change reporting / non-fatal errors
; Bits 16 - 23 Fatal errors and security violations
; Bits 24 - 30 Internal script errors
for $intCtr = 0 to ubound($aryMsgCat)
$aryMsgCat[$intCtr] = ""
next
$aryMsgCat[0] = "INF" ; 1
$aryMsgCat[1] = "MND" ; 2
$aryMsgCat[2] = "UCC" ; 4
$aryMsgCat[3] = "SCC" ; 8
$aryMsgCat[4] = "VSF" ; 16
$aryMsgCat[5] = "MIF" ; 32
$aryMsgCat[6] = "RAS" ; 64
$aryMsgCat[7] = "LCF" ; 128
$aryMsgCat[8] = "CDF" ; 256
$aryMsgCat[9] = "NFE" ; 512
$aryMsgCat[10] = "NLA" ; 1024
$aryMsgCat[11] = "NSS" ; 2048
$aryMsgCat[12] = "NSD" ; 4096
$aryMsgCat[16] = "ERR" ; 65536
$aryMsgCat[17] = "SEC" ; 131072
$aryMsgCat[18] = "NOS" ; 262144
for $intCtr = 0 to ubound($aryMsgTxt)
$aryMsgTxt[$intCtr] = ""
next
$aryMsgTxt[0] = "Debugging and status INFormation"
$aryMsgTxt[1] = "Mapped Network Drive"
$aryMsgTxt[2] = "User Configuration Change"
$aryMsgTxt[3] = "System Configuration Change"
$aryMsgTxt[4] = "Virus Signature File update"
$aryMsgTxt[5] = "MIF File creation or update"
$aryMsgTxt[6] = "RAS connection"
$aryMsgTxt[7] = "Local Configuration Flag"
$aryMsgTxt[8] = "unable to Create Directory or File"
$aryMsgTxt[9] = "Non-Fatal Error"
$aryMsgTxt[10] = "Not in Local Administrators group"
$aryMsgTxt[11] = "Non-Standard Script program or version"
$aryMsgTxt[12] = "Non-Standard Domain"
$aryMsgTxt[16] = "external or internal ERRor"
$aryMsgTxt[17] = "SECurity problem or error"
$aryMsgTxt[18] = "Non-Standard Operating system or server"

I echo these values to each user's log to help our Help Desk folks read the codes in the logs:

code:
  
Write(@CRLF + 'The following is a list of active error codes used in the script.',1)
Write('Spaces inserted in acronyms here to prevent false hits in searches.',1)
Write('CATEGORY BIT VALUE DESCRIPTION',1)
FOR $iCtr = 0 to UBound($aMsgCat)
IF $aMsgCat[$iCtr] <> ''
$iTmp = Exp(2,$iCtr)
$sTmp = SubStr($aMsgCat[$iCtr],1,1) + ' ' +
SubStr($aMsgCat[$iCtr],2,1) + ' ' +
SubStr($aMsgCat[$iCtr],3,1) + ' ' +
SubStr(' ',1,2 - Len($iCtr)) + $iCtr + ' ' +
SubStr(' ',1,9 - Len($iTmp)) + $iTmp + ' ' +
$aMsgTxt[$iCtr]
Write($sTmp,1)
ENDIF
NEXT

During script execution, I log errors and information. Then, at the end of the script, I do a summary of the error codes set during script execution:

code:
  
Write('Exit code: ' + $iExCode,1)
Write('This can be decoded as follows...',1)
FOR $iCtr = 0 to 30
$Exp = Exp(2,$iCtr)
IF $iExCode & $Exp
Write($aMsgCat[$iCtr] + '- ' + $Exp + ' ' + $aMsgTxt[$iCtr],1)
ENDIF
NEXT
ELSE
Write('INF - TGLOGON.KIX completed with no significant actions or errors.',1)
ENDIF

Similarly, my UDF's have bitwise error codes. If the UDF is more complex, I might set a single script-level error code by evaluating one or more UDF error codes returned in @error.

Finally, always returning an array in order to include error codes and information seems excessive and cumbersome to me. I liked the comments about VBA vs. the old Excel macro language. VBA is MUCH more powerful... so almost no one uses it. [Wink]

In this case, we are in a gray area, as most of the people writing KiXtart script are assumed to have some level of proficiency with KiXtart. But I'd still try to apply the following rules to a returned value:

1. Return nothing (since a UDF acts as both a function and a procedure in KiXtart) or a single value wherever possible.
2. Return it in the format expected. (I.e. I would expect Exp(x,y) to return a number, not an array of strings)
3. Keep the default operation of the function as simple as possible. By putting errors in the error value of the function, the user has the option of evaluating that error code or not. Forcing the user to deal with this every time is not necessarily a kindness.

My .02.

Thanks,

New Mexico Mark

Top
#64544 - 2002-04-16 11:44 PM Re: UDF Design
Jack Lothian Offline
MM club member
*****

Registered: 1999-10-22
Posts: 1169
Loc: Ottawa,Ontario, Canada
Hi Shawn,

In real life, I am a mathematician. I took up this "hobby" because the local middle school had buckets of money invested in computers but none invested in people. Nothing worked, not even the new equipment. I and 3 other parents decided to build a system for the school. We finished our work about 2 years ago.

For the last 2 years, I have been out of it, but the school is looking into putting in Win2000 & we were asked to help in the upgrade. So, I was just snooping around & I couldn't help it, I had to open my mouth. I am not sure if my return to the board is permanent or not. It depends on a lot of factors at the school. For now, I am just trying to get current.

I am impressed with this board. All the old folks are still here plus thousands of new ones. (With the exception of Davidson - where is he? I would miss him since he was one of the few school related people that I encountered regularly on this site.)

Howard,

Sorry - I think these ramblings might be off topic but your intro does say discussions. I took liberties.
_________________________
Jack

Top
#64545 - 2002-04-17 01:02 AM Re: UDF Design
Howard Bullock Offline
KiX Supporter
*****

Registered: 2000-09-15
Posts: 5809
Loc: Harrisburg, PA USA
Jack, No problem. [Smile]

Mark,
quote:
(I.e. I would expect Exp(x,y) to return a number, not an array of strings)
That does not have to be the case. Try this code:
{edit} By no means is this suppose to be a valid EXP function.
code:
function EXP($x,$y)
dim $x, $y, $z
? "X = " + $x + " of type " + vartypename($x)
? "Y = " + $y + " of type " + vartypename($y)
$z = $x
for $i=2 to $y
$z = $z * $x
next
$err = @Error
$errtext = @Serror
? "Z = " + $z + " of type " + vartypename($z)
$EXP = $z, $err, $errtext
endfunction
$result = EXP(2,3)
? ? "Results:"
for $i=0 to Ubound($result)
? "element $i = '" + $result[$i] + "' is type " + vartypename($result[$i])
next



[ 17 April 2002, 01:04: Message edited by: Howard Bullock ]
_________________________
Home page: http://www.kixhelp.com/hb/

Top
#64546 - 2002-04-17 08:58 AM Re: UDF Design
NTDOC Administrator Offline
Administrator
*****

Registered: 2000-07-28
Posts: 11623
Loc: CA
In my opinion I don't want or need error codes for UDFs. I want or assume that the code is solid enough to work on 99% of all of my systems from the get go. If I only have 5 machines out of 5,000 having a problem with the code, I would blame those 5 machines and not the code. If on the other hand I am using the error code as a part of the decision process of the script, then it may be a different matter.

I would only want or need error codes typically to help me track down why my UDF is not working, or for debugging someone else’s code.

I don't disagree with the idea of "advanced" programmers wanting a "standard". I agree that one should be used by those so inclined, as it can be helpful. However, to attempt to coerce or indicate that a UDF is not valid or not good because it either does not have error routines built-in or because it does not conform to a "standard" is also wrong in my opinion. KiXtart is a logon script first and foremost. Yes, we can and do have it do so much more now days... but a simple/complex UDF that is written well and performs well should not need to be debugged by other members that download the code and use it.

At the risk of sounding off base, (in my opinion again - from most of the posting I see, I would have to say there "appear" to be less then a dozen "regularly posting" members that I would put in this ADVANCED PROGRAMMER category...of which I do not include myself). I would say that the vast majority of us are at varying degrees of understanding "advanced" code samples, and we USE it more so then CREATE it.

Howard, if I'm missing the boat here please let me know. Maybe you're meaning or wanting something else based on your original question then what I'm replying with. It's late and maybe I'm just not reading the thread and request properly.

Top
#64547 - 2002-04-17 10:45 AM Re: UDF Design
Richard H. Administrator Offline
Administrator
*****

Registered: 2000-01-24
Posts: 4946
Loc: Leatherhead, Surrey, UK
quote:
It's not about enforcing a method but rather producing quidelines for a standard way of doing it if you want to
{EDIT} Pre-coffee rant deleted {/EDIT}

The ideal solution would be if a function returned an object whose properties are (say):
quote:
$oResult.ERROR
$oResult.SERROR
$oResult.Value

If the default property/method (I'm not that familiar with objects) is the $oResult.Value, then the functions would continue to work as they currently do, i.e.
code:
Function udfSetString()
$udfSetString="A String"
EndFunction
;
; Call function
udfSetString() ?

When called the function will return "A String" as you'd expect.
However if you wanted you could use the other properties:
code:
Function udfDivide($iDividend,$iDivisor)
If Val($iDivisor)=0
$udfDivide.ERROR=1
$udfDivide.SERROR="Whoa! caught a divide-by-zero error in udfDivide()"
Else
$udfDivide=Val($iDividend) / Val($iDivisor)
EndIf
Exit $udfDivide.ERROR
EndFunction

This way if someone else uses your function and doesn't care about the extra information they can still assign the return value and get the expected "natural" result.

[ 17 April 2002, 11:13: Message edited by: Richard Howarth ]

Top
#64548 - 2002-04-18 12:55 AM Re: UDF Design
Will Hetrick Offline
Hey THIS is FUN

Registered: 2001-10-02
Posts: 320
Loc: Harrisburg, PA USA
As I was reading this Discussion and where it was heading, I decided to input some thought.

As a former School teacher, I understand the notion that its better to teach someone to fish and they will eat for a lifetime.

Now with that out of my head, The thought of adding a return code to the UDF other than the microsoft simple error code is a good idea from the programmers point of view so that he can debug it, but How many people come on to this board as programmers?

Most of the people I see that want to use the UDF's and who we make the UDF's available for are the ones who can't program, need a quick fix for a problem and do not know what to do with the error codes to begin with.

Why make it harder for the people we are trying to help make it easier for in the first place?

[ 17 April 2002, 12:56: Message edited by: Will Hetrick ]
_________________________
You have at least 2 choices. Each choice changes your destiny. Choose wisely!

Top
#64549 - 2002-04-17 07:43 PM Re: UDF Design
New Mexico Mark Offline
Hey THIS is FUN
****

Registered: 2002-01-03
Posts: 223
Loc: Columbia, SC
Howard:

That was an interesting example. I'm surprised it works... I guess this is an example of an array of variants? Either that or an array can contain mixed types. I wouldn't have expected that, but then again, I haven't dug into the internals of KiXtart nearly as much as a few others here. Some of these folks probably get coding projects handed off to them on the sly by Ruud. [Wink]

Yet, the problem still remains that if I expect (for example) an integer to be returned and I get an array, it adds to the complexity of how I deal with the result. Admitted, this is a trivial addition, and you may find the added information returned to be very useful. However, it is non-intuitive and could be problematic to those not used to working with arrays.

Richard's idea of object properties is very intriguing. I like it, but have no idea how that could be made to work.

As for those arguing 'simpler is always better', I would have to disagree. Often external simplicity and power is at the cost of great internal complexity. So long as the end user doesn't have to understand the internal complexity, and that complexity doesn't cost too much in performance / resources, I'm for it. A GUI is incredibly complex, but my four-year-old is able to open programs, enter data (her name), and play games involving selection and manipulation of on-screen objects after only minimal instruction. Behind that 'simplicity' are millions of lines of code and many, many standards of coding and inter-process communication.

Programming is 10 percent core logic and 90 percent interface logic. Obviously, this isn't nearly so much of an issue with UDF's, but I appreciate the following 'best practices' in some of the coolest UDF's I've seen:

1. They are pretty much unbreakable. They prevent or handle internal errors to the greatest extent possible. They still return a value of the type expected if they break -- thus helping prevent type mismatches -- but the value is zero, empty, or null. If the values supplied should never return this data, the data itself can act as the error. Otherwise, the function should set an error number on exit to be tested.

2. They are independent. All internal variables are declared so they will not be confused with global variables. (Side note -- Howard, I notice you tend to 'Dim' your argument variables as well. Unless I'm misunderstanding the process, this happens automatically simply because they are arguments.) Also, files are opened and closed in a way that they can't interfere with file numbers in the calling script.

3. They return what I intuitively expect. This way I don't have to dig through the code to see what is going on. In other words, most numeric functions returns a number. Most string functions return a string. There are obvious exceptions, of course. I would expect instr() to return a number. But I would be very surprised if it returned an array!

4. They are well documented and tested. Even better if extensive testing code is available along with expected results so I can verify those results on my particular combination of HW/OS/KiX versions before implementing the function.

5. They are readable so I can customize, if so desired. (This is strictly a personal preference. Most people probably only want to use a UDF, not tinker with it.)

I don't give a rip about 'function police' [motto - "Badges? We don' need no steenking badges!"] , and I don't think that is where this is going.

However, I welcome ideas and feedback on how to write better, cleaner, more robust code. And the more the most active KiXtart developers can agree on 'best practices', the more the entire KiXtart community benefits -- not only from better scripts and functions, but also from the respect of other scripting communities.

Cheers from a crazy idealist,

New Mexico Mark

Top
#64550 - 2002-04-17 08:11 PM Re: UDF Design
Howard Bullock Offline
KiX Supporter
*****

Registered: 2000-09-15
Posts: 5809
Loc: Harrisburg, PA USA
Mark, I just used "dim" out of habit trying to keep local vars local. I did check and verified that you are correct parameters are local to the function and do not need to be "dim"'ed. Thanks for educating me.

Your comments on the file handles are a different matter as I interpret your statment. File handles do appear to be global. the following test code illustrates the point.
code:
function writelog ($x)
$rc = open (1, "Junk2.txt", 5)
? "function open: $rc"
$rc = writeline (1, $x)
$rc = close(1)
? "function close: $rc"
endfunction

IF Open(1, "junk.txt", 5) = 0
? "File handle 1 opened to junk.txt"
endif
writelog ("stuff for junk2")
$rc=writeline (1, "more stuff")
$rc = close(1)
? "Script close: $rc"
exit

I like Richard's object oriented ideas as well.
Everyone so far has made valuable contributions to this discussion. It may be that the best thing I learn here is to provide code in format and function that can be useful and similiar to the exisiting base of UDF's out there.

I think that for simple UDF's I will return a single value and set @error while attempting to prevent any fatal script errors with minimal code.

I would still like to here more opinions from those that want to post them.
_________________________
Home page: http://www.kixhelp.com/hb/

Top
#64551 - 2002-04-17 08:46 PM Re: UDF Design
BrianTX Offline
Korg Regular

Registered: 2002-04-01
Posts: 895
A lot depends on the complexity of UDFs we are talking about. If I were to write a UDF that performed a square root function to a given number of decimal places, the only possible errors would be that:

1. My UDF couldn't handle a number that large.
2. My initial number input is negative.

As such, I don't really see the need for a complex array to report errors. The best practice is to keep things simple so that the person using the UDF doesn't have to do a lot of extra programming to handle errors.

If I were to create a more complex UDF that were to open one file, and find all the instances of words from another file, and output their line numbers to a third file, I can see there being many more possibilities for errors. So, there might be a use for more descriptive error codes in such a case -- provided I am using someone else's UDF. If I wrote it myself, then I can customize my own error code system to suit my own needs.

I'm not sure how it would be possible to take both scenarios and mesh them together in one "standard" system of error coding. Some disadvantages for doing so are: (I know I'm repeating what has been said)

1. Making simple, straightforward UDF's harder to use.

2. Lengthening code unecessarily.

On the other hand, some UDFs will have enough complexity to warrant extended error codes. In that situation, what standard should be used?

I believe that it would be simplest to just return errorcodes in the same manner that KIXtart returns them (Microsoft system error codes). This way prevents proprietary schemes competing that confuse everyone. Although using an array to return errors sounds like a good idea, in my opinion its benefits are outweighed by increased complexity.

So, in summary, my thoughts are:

1. NO extended error codes for most UDFs
2. Use the Microsoft system error codes if extra codes are needed.
3. Do not use arrays as this increases complexity.

.... It's interesting how this seems fairly identical to the way KIXtart has been programmed.

Just my two cents...

Brian

Top
#64552 - 2002-04-17 09:38 PM Re: UDF Design
Bryce Offline
KiX Supporter
*****

Registered: 2000-02-29
Posts: 3167
Loc: Houston TX
Great stuff yall!

My input on returning an array from a UDF call.

I am guilty of this, several of my UDF's return an array.

In all cases the array that is returned is 100% pure data, and using an array seemed like the natural way to present the data being requested.

With the addition of the enhanced array tools in Kix 4.x, working with array's is much simpler.

take for example my GroupMembers() UDF.

This UDF returns an array, and the array size will always be unknown.

All groupmembers() really is, is the "(ADSI Group Object).members" interface wrapped up into an easy to use UDF with some simple filter capabilities.

The "(ADSI Group Object).members" object is an array of "(ASDI Groups Objects)" that the given user is a member of.

So in this case, returning an Array just seemed logical.

Bryce

Top
Page 1 of 2 12>


Moderator:  Glenn Barnas, NTDOC, Arend_, Jochen, Radimus, Allen, ShaneEP, Ruud van Velsen, Mart 
Hop to:
Shout Box

Who's Online
2 registered (morganw, mole) and 414 anonymous users online.
Newest Members
gespanntleuchten, DaveatAdvanced, Paulo_Alves, UsTaaa, xxJJxx
17864 Registered Users

Generated in 0.516 seconds in which 0.012 seconds were spent on a total of 13 queries. Zlib compression enabled.

Search the board with:
superb Board Search
or try with google:
Google
Web kixtart.org