.\"  $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.TH ADEPERLF 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
adeperlf \- call an ADE Perl function
.br
.ne 5
.SH SYNOPSIS
.B adeperlf
\*[ade_standard_synopsis_component]
.I function
[
.I arguments \fR ...
]
.br
.ne 5
.SH DESCRIPTION
.B Adeperlf
provides a command line interface to the ADE Perl library.
.br
.ne 5
.SH CONFIGURATION
None.
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.br
.ne 5
.SH EXIT STATUS
On success
.B adeperlf
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
This first example shows what happens when an unknown function is called:
.IP
.nf
.fam C
.B adeperlf '&f;'
adeperlf: ERROR: frame#0: code failed to execute (Undefined subroutine &main::f called at (eval 5) line 1.)
adeperlf: ERROR: frame#1: application's entry function failed
.fam T
.fi
.PP
This second example shows the importance of returning sensible return codes:
.IP
.nf
.fam C
.B adeperlf 'sub f { &ade_err_error($errstack_ref, ade_err_misc, \[dq]this is a test\[dq]); }; &f;'
.fam T
.fi
.PP
(Failure to return 
.B $ade_err_fail 
meant that no need to dump the error stack was detected, so there was no output,
despite an error frame having been added to the error stack.) This third example
makes the same call but with the right return code:
.IP
.nf
.fam C
.B adeperlf 'sub f { &ade_err_error($errstack_ref, ade_err_misc, \[dq]this is a test\[dq]); return $ade_err_fail; }; &f;'
adeperlf: ERROR: frame#0: this is a test
adeperlf: ERROR: frame#1: code executed, but returned non-zero (1)
adeperlf: ERROR: frame#2: application's entry function failed
.fam T
.fi
.PP
This fourth example makes the same call but having first configured the stack dumper to dump only
the top frame:
.IP
.nf
.fam C
.B adeperlf 'sub f { &ade_err_error($errstack_ref, ade_err_misc, \[dq]this is a test\[dq]); return $ade_err_fail; }; &ade_err_resetstack($errstack_ref, dumpall=>0); &f;'
adeperlf: ERROR: this is a test
.fam T
.fi
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B adeperlf\fR.
.br
.ne 5
.SH SEE ALSO
adeshf(1), ade-config(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2003-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.