11.6 UTILITY FUNCTIONS

Last modified: Tue, 03/24/2020 - 12:01

Ch11 Sec6.

UTILITY FUNCTIONS

The lists below describe the utility functions built into Ferret which are available to the external function writer. These are used to set parameters associated with the external function and to retrieve information provided by Ferret. (Input variables, sending information to Ferret, are in plain type and output variables, getting information from Ferret, are in italic.)

Ch11 Sec6.1.

EF_Util.cmn

External functions need to include the EF_Util.cmn file in each subroutine in order to use various pre-defined parameters. These parameters are defined in the table below:

Parameters defined in EF_Util.cmn

To make the code more readable:
X_AXIS (=1)	ARG1 (=1)	ARG5 (=5)	ARG9 (=9)
Y_AXIS (=2)	ARG2 (=3)	ARG6 (=6)	YES (=2)
Z_AXIS (=3)	ARG3 (=3)	ARG7 (=7)	NO (=0)
T_AXIS (=4)	ARG4 (=4)	ARG8 (=8)
Internal parameters for Ferret:
CUSTOM	result axis is defined by the external function
IMPLIED_BY_ARGS	result axis is inherited from one (or more) of the arguments
NORMAL	this axis does not exist in the result
ABSTRACT	result axis is an indexed axis [1:N]
RETAINED	result axis has same extent as argument axis
REDUCED	result axis is reduced to a point

Ch11 Sec6.2.

Available utility functions (scroll down the page for more detailed information)

Setting Parameters

ef_set_desc(id, desc)
ef_set_num_args(id, num)
ef_set_piecemeal_ok(id, Xyn, Yyn, Zyn, Tyn)
ef_set_piecemeal_ok_6d(id, Xyn, Yyn, Zyn, Tyn, Eyn, Fyn)
ef_set_axis_influence(id, arg, Xyn, Yyn, Zyn, Tyn)
ef_set_axis_influence_6d(id, arg, Xyn, Yyn, Zyn, Tyn, Eyn, Fyn)
ef_set_axis_inheritance(id, Xsrc, Ysrc, Zsrc, Tsrc)
ef_set_axis_inheritance_6d(id, Xsrc, Ysrc, Zsrc, Tsrc, Esrc, Fsrc)
ef_set_arg_name(id, arg, name)
ef_set_arg_desc(id, arg, desc)
ef_set_arg_unit(id, arg, unit)
ef_set_arg_type(id, arg, type)
ef_set_axis_reduction(id, Xred, Yred, Zred, Tred)
ef_set_axis_reduction_6d(id, Xred, Yred, Zred, Tred, Ered, Fred)
ef_set_axis_extend(id, arg, axis, lo_amt, hi_amt)
ef_set_axis_limits(id, axis, lo, hi)
ef_set_custom_axis(id, axis, lo, hi, delta, unit, modulo)
ef_set_num_work_arrays(id, num)
ef_set_work_array_dims(id, array, Xlo, Ylo, Zlo, Tlo, Xhi, Yhi, Zhi, Thi)
ef_set_work_array_dims_6d(id, array, Xlo, Ylo, Zlo, Tlo, Elo, Flo, Xhi, Yhi, Zhi, Thi, Ehi, Fhi)

Getting Information

For all calculations

ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr)
ef_get_res_subscripts_6d(id, res_lo_ss, res_hi_ss, res_incr)
ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr)
ef_get_arg_subscripts_6d(id, arg_lo_ss, arg_hi_ss, arg_incr)
ef_get_bad_flags(id, bad_flag, bad_flag_result)
ef_get_bad_flags_6d(id, bad_flag, bad_flag_result)

Text

ef_get_arg_info(id, arg, name, title, units)
ef_get_arg_string(id, arg, text)
ef_get_axis_info(id, arg, name, units, bkwd, modulo, regular)
ef_get_axis_info_6d(id, arg, name, units, bkwd, modulo, regular)
ef_get_axis_dates(id, arg, tax, direction, numtimes, datebuf)
ef_get_string_arg_element(id, arg, str_arg, i,j,k,l, slen, text)
ef_get_string_arg_element_6d(id, arg, str_arg, i,j,k,l,m,n slen, text)

Values

ef_get_arg_ss_extremes(id, arg, ss_min, ss_max)
ef_get_coordinates(id, arg, axis, lo, hi, coords)
ef_get_box_size(id, arg, axis, lo, hi, size)
ef_get_box_limits(id, arg, axis, lo, hi, lo_lims, hi_lims)
ef_get_one_val(id, arg, value)
ef_get_string_arg_element_len(id, arg, str_arg, i,j,k,l, slen)
ef_get_string_arg_element_len_6d(id, arg, str_arg, i,j,k,l,m,n slen)

Other

ef_version_test(version)
ef_bail_out(id, text)

Ch11 Sec6.2.1.

ef_set_desc(id, desc)

Assign a text string description to the external function.

Input arguments:

1. INTEGER id: external function's ID number

2. CHARACTER*(*) desc: description of this function

Ch11 Sec6.2.2.

ef_set_num_args(id, num)

Specify the number of arguments this function will accept. The maximum number of arguments allowed is 9

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER num: number of arguments for this function

Ch11 Sec6.2.3.

ef_set_axis_inheritance(id, Xsrc, Ysrc, Zsrc, Tsrc) and

ef_set_axis_inheritance_6d(id, Xsrc, Ysrc, Zsrc, Esrc, Fsrc)

Specify where the result axes will come from. The acceptable values for each axis will be one of:

CUSTOM	result axis is defined by the external function
IMPLIED_BY_ARGS	result axis is inherited from one (or more) of the arguments
NORMAL	this axis does not exist in the result
ABSTRACT	result axis is an indexed axis [1:N]

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER Xsrc: inheritance flag for the X axis

3. INTEGER Ysrc: inheritance flag for the Y axis

4. INTEGER Zsrc: inheritance flag for the Z axis

5. INTEGER Tsrc: inheritance flag for the T axis

6. INTEGER Esrc: inheritance flag for the E axis, when calling ef_set_axis_inheritance_6d

6. INTEGER Esrc: inheritance flag for the F axis, when calling ef_set_axis_inheritance_6d

Ch11 Sec6.2.4.

ef_set_piecemeal_ok(id, Xyn, Yyn, Zyn, Tyn) and

ef_set_piecemeal_ok_6d(id, Xyn, Yyn, Zyn, Tyn, Eyn, Fyn)

Tell Ferret whether it is ok to break up calculations along a particular axis. (Not implemented, placeholder for future implementation)

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER Xyn: yes/no flag for the X axis

3. INTEGER Yyn: yes/no flag for the Y axis

4. INTEGER Zyn: yes/no flag for the Z axis

5. INTEGER Tyn: yes/no flag for the T axis

6. INTEGER Eyn: yes/no flag for the E axis, when calling ef_set_piecemeal_ok_6d

7. INTEGER Fyn: yes/no flag for the F axis, when calling ef_set_piecemeal_ok_6d

Ch11 Sec6.2.5.

ef_set_arg_name(id, arg, name)

Assign a text string name to an argument.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. CHARACTER*(*) name: argument name

Ch11 Sec6.2.6.

ef_set_arg_desc(id, arg, desc)

Assign a text string description to an argument.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. CHARACTER*(*) desc: argument description

Ch11 Sec6.2.7.

ef_set_arg_unit(id, arg, unit)

Assign a text string to an argument's units.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. CHARACTER*(*) unit: unit description

Ch11 Sec6.2.8.

ef_set_arg_type(id, arg, type)

Specify the type of an argument as either FLOAT_ARG or STRING_ARG. In the ~_compute subroutine, the ef_get_arg_string() function is used to obtain the desired text string.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. INTEGER type: either FLOAT_ARG or STRING_ARG

Ch11 Sec6.2.9.

ef_set_axis_extend(id, arg, axis, lo_amt, hi_amt)

Tell Ferret to extend the range of data passed for an argument. This is useful for cases like smoothers where the result at a particular point depends upon a range of input values around that point.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. INTEGER axis: axis number

4. INTEGER lo_amt: extension to the lo range (–1 means get one more point than in the result)

5. INTEGER hi_amt: extension to the hi range (+1 means get one more point than in the result)

Ch11 Sec6.2.10.

ef_set_axis_influence(id, arg, Xyn, Yyn, Zyn, Tyn) and

ef_set_axis_influence_6d(id, arg, Xyn, Yyn, Zyn, Tyn, Eyn, Fyn)

Specify whether this argument's axes "influence" the result axes. A value of YES for a particular axis means that the result should have the same axis as this argument. If the result should have the same axis as several input arguments, then each argument should specify YES for the axis in question. Note that ef_set_axis_inheritance must have specified IMPLIED_BY_ARGS for this axis.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. INTEGER Xyn: influence flag for the X axis

4. INTEGER Yyn: influence flag for the Y axis

5. INTEGER Zyn: influence flag for the Z axis

6. INTEGER Tyn: influence flag for the T axis

7. INTEGER Eyn: influence flag for the E axis, when calling ef_set_axis_influence_6d

8. INTEGER Fyn: influence flag for the F axis, when calling ef_set_axis_influence_6d

Ch11 Sec6.2.11.

ef_set_axis_reduction(id, Xred, Yred, Zred, Tred) and

ef_set_axis_reduction_6d(id, Xred, Yred, Zred, Tred, Ered, Fred)

Specify whether the result axes are RETAINED or REDUCED with respect to the argument axes from which they are inherited. Setting the axis reduction flag to REDUCED means that the result axis is reduced to a point by the external function. The axis reduction flag need only be set when the result is reduced to a point but SET REGION information should still be applied to the external function arguments.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER Xred: reduction flag for the X axis

3. INTEGER Yred: reduction flag for the Y axis

4. INTEGER Zred: reduction flag for the Z axis

5. INTEGER Tred: reduction flag for the T axis

6. INTEGER Ered: reduction flag for the E axis, when calling ef_set_axis_reduction_6d

7. INTEGER Fred: reduction flag for the F axis, when calling ef_set_axis_reduction_6d

Ch11 Sec6.2.12.

ef_set_axis_limits(id, axis, lo, hi)

Specify the lo and hi limits of an axis. (This is not needed for most functions and must appear in a separate subroutine named ~func_name~_result_limits(id)).

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER axis: axis number

3. INTEGER lo: index value of the lo range of this axis

4. INTEGER hi: index value of the hi range of this axis

Ch11 Sec6.2.13.

ef_set_custom_axis(id, axis, lo, hi, delta, unit, modulo)

Create a custom axis. This is only used by functions which create a custom axis and must appear in a separate subroutine named ~func_name~_custom_axes(id). See also the discussion of the custom_axis subroutine. If the axis is a time axis, the units should be the unit only (e.g. "year", "day"), and should not include the time origin. Set the time origin separately as noted in the discussion of the custom_axis subroutine.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER axis: axis number

3. REAL lo: coordinate value of the lo range of this axis

4. REAL hi: coordinate value of the hi range of this axis

5. REAL delta: increment for this axis

6. CHARACTER*(*) unit: unit for this axis

7. INTEGER modulo: flag for modulo axes (1 = modulo)

Ch11 Sec6.2.14.

ef_set_num_work_arrays(id, nwork)

Set the number of work arrays to be allocated. The maximum number of work arrays allowed is 9.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER nwork: number of storage arrays

Ch11 Sec6.2.15.

ef_set_work_array_dims(id, iarray, xlo, ylo, zlo, tlo, xhi, yhi, zhi, thi) and

ef_set_work_array_dims_6d(id, array, Xlo, Ylo, Zlo, Tlo, Elo, Flo, Xhi, Yhi, Zhi, Thi, Ehi, Fhi)

Set the working array axis lengths.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER iarray: array number

3. INTEGER xlo: index value of the lo range of x axis

4. INTEGER ylo: index value of the lo range of y axis

5. INTEGER zlo: index value of the lo range of z axis

6. INTEGER tlo: index value of the lo range of t axis

7. INTEGER xhi: index value of the hi range of x axis

8. INTEGER yhi: index value of the hi range of y axis

9. INTEGER zhi: index value of the hi range of z axis

10. INTEGER thi: index value of the hi range of t axis

When calling ef_set_work_array_dims_6d, integers Elo, Flo, Ehi, Fhi are index values of the low and high range of the E and F axes.

Ch11 Sec6.2.16.

ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr) and

ef_get_res_subscripts_6d(id, res_lo_ss, res_hi_ss, res_incr)

Return lo and hi indices and increments to be used in looping through the calculation of the result.

Input arguments:

1. INTEGER id: external function's ID number

Output arguments:

1. INTEGER res_lo_ss(4): the lo end indices for the X, Y, Z, T axes of the result

2. INTEGER res_hi_ss(4): the hi end indices for the X, Y, Z, T axes of the result

3. INTEGER res_incr(4): the increment to be applied to the X, Y, Z, T axes of the result

or when calling ef_get_res_subscripts_6d,

1. INTEGER res_lo_ss(6): the lo end indices for the X, Y, Z, T, E, F axes of the result

2. INTEGER res_hi_ss(6): the hi end indices for the X, Y, Z, T, E, F axes of the result

3. INTEGER res_incr(6): the increment to be applied to the X, Y, Z, T, E, F axes of the result

Sample code:

CALL ef_get_res_subscripts(id,
res_lo_ss, res_hi_ss, res_incr) ... 

DO 400 n=res_lo_ss(F_AXIS), res_hi_ss(F_AXIS) 

DO 300 m=res_lo_ss(E_AXIS), res_hi_ss(E_AXIS)
... 

300 CONTINUE 

400 CONTINUE

Ch11 Sec6.2.17.

ef_get_arg_info(id, iarg, arg_name, arg_title, arg_units)

Return strings describing argument: name, title, units.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER iarg: argument number

Output arguments:

1. CHARACTER*24 arg_name: the name of the argument

2. CHARACTER*128 arg_title: title associated with the argument

3. CHARACTER*32 arg_units: the argument's units.

Ch11 Sec6.2.18.

ef_get_arg_string(id, iarg, text)

This name is deprecated, and renamed to ef_get_one_arg_string.

Ch11 Sec6.2.19.

ef_get_one_arg_string(id, iarg, text)

Return the string associated with an argument of type STRING_ARG. This routine like ef_get_one_val, may be called during the init phase of an external function, in the routines to set custom or abstract axes (but not in the ~init subroutine itself).

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER iarg: argument number

Output arguments:

1. CHARACTER*(*) text: the actual text string for the argument

Sample code:

…

CHARACTER arg_text*160

* *************************
* USER CONFIGURABLE PORTION
* 
* 
INTEGER i,j,k,l
INTEGER i1, j1, k1, l1

CALL ef_get_arg_string(id, 1, arg_text)
WRITE(6,49) arg_text
49 FORMAT ('The text is : ''',a,'''')

…

Ch11 Sec6.2.20.

ef_get_axis_info(id, iarg, axname, ax_units, backward, modulo, regular) and

ef_get_axis_info_6d(id, iarg, axname, ax_units, backward, modulo, regular)

Return strings describing argument: name, title, units.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER iarg: argument number

Output arguments:

1. CHARACTER*16 ax_name(4): the name of the four axes
or CHARACTER*16 ax_name(4) when calling ef_get_axis_info_6d

2. CHARACTER*16 ax_units(4): units of the four axes
or CHARACTER*16 ax_units(6) when calling ef_get_axis_info_6d

3. LOGICAL backward(4): true if axis is backward axis
or LOGICAL backward(6) when calling ef_get_axis_info_6d

4. LOGICAL modulo(4): true if axis is modulo axis
or LOGICAL modulo(6) when calling ef_get_axis_info_6d

5. LOGICAL regular(4): true if axis is regular axis
or LOGICAL regular(6)when calling ef_get_axis_info_6d

Ch11 Sec6.2.21.

ef_get_axis_dates(id, iarg, taxis, direction, numtimes, precision, datebuf)

Returns the string date buffer associated with the time axis of an argument.

(Previous to Ferret v6.72 Ferret did not have an F axis and this function had only five arguments; it did not include argument 4: dimension. The precision argument was added with version 7.5)

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER iarg: argument number

3. REAL*8 taxis(numtimes): time coordinate values to translate

4. DIRECTION: Axis direction in the grid: 4 for Time axis or 6 for Forecast-time axis

5. INTEGER numtimes: number of timesteps to return

6. INTEGER precision: one of the following codes:
3 for day-month-year
4 for day-month-year hour
5 for day-month-year hour:minute
6 for day-month-year hour:minute:second
7 for day-month-year hour:minute:second.fraction

Output arguments:

1. CHARACTER*24 datebuf(numtimes): the string-date buffer for each time. This can be shorter if the precision chosen is less than full precision.

Ch11 Sec6.2.22.

ef_get_axis_calendar(id, iarg, calname, yrdays, nmonths, days_in_month)

Returns the calendar name, days per year, number of months, and days per month associated with the time axis of an argument.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER iarg: argument number

Output arguments:

1. CHARACTER calname: the string name of the axis

2. REAL yrdays: the number of days in the year, including fractional days as in 365.2425 for the standard calendar

3. INTEGER nmonths: the number of months in the year. Currently Ferret has only 12-month years defined

4. INTEGER days_in_month(12): The number of days in each month

Ch11 Sec6.2.23.

ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr) and

ef_get_arg_subscripts_6d(id, arg_lo_ss, arg_hi_ss, arg_incr)

Return lo and hi indices and increments to be used in looping through the calculation of the result. If you call ef_get_arg_subscripts to generate a custom axis, see the discussion under the custom_axis subroutine.299

Input arguments:

1. INTEGER id: external function's ID number

Output arguments:

1. INTEGER arg_lo_ss(4,EF_MAX_ARGS): the lo end indices for the X, Y, Z, T axes of each argument

2. INTEGER arg_hi_ss(4,EF_MAX_ARGS): the hi end indices for the X, Y, Z, T axes of each argument

3. INTEGER arg_incr(4,EF_MAX_ARGS): the increment to be applied to the X, Y, Z, T axes of each argument

or, when calling ef_get_arg_subscripts_6d:

1. INTEGER arg_lo_ss(6,EF_MAX_ARGS): the lo end indices for the X, Y, Z, T, E, F axes of each argument

2. INTEGER arg_hi_ss(6,EF_MAX_ARGS): the hi end indices for the X, Y, Z, T, E, F axes of each argument

3. INTEGER arg_incr(6,EF_MAX_ARGS): the increment to be applied to the X, Y, Z, T, E, F axes of each argument

Sample code:

INTEGER i,j,k,l, m, n 
INTEGER i1, j1, k1, l1, m1, n1 
INTEGER i2, j2, k2, l2, m2, n2

CALL ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr) 
CALL ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr) 
CALL ef_get_bad_flags(id, bad_flag, bad_flag_result) 

i1 = arg_lo_ss(X_AXIS,ARG1) 
i2 = arg_lo_ss(X_AXIS,ARG2) 

DO 400 i=res_lo_ss(X_AXIS), res_hi_ss(X_AXIS) 
… 
i1 = i1 + arg_incr(X_AXIS,ARG1) 
i2 = i2 + arg_incr(X_AXIS,ARG2) 
400 CONTINUE

Ch11 Sec6.2.24.

ef_get_arg_ss_extremes(id, num_args, ss_min, ss_max) and

ef_get_arg_ss_extremes_6d(id, num_args, ss_min, ss_max)

Return the maximum and minim index values for all the arguments. These define the domain of the data.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER num_args: number of arguments for which to return index extremes

Output arguments:

1. INTEGER ss_min(4,EF_MAX_ARGS): the minimum indices for the X, Y, Z, T axes of each argument

2. INTEGER ss_max(4,EF_MAX_ARGS): the maximum indices for the X, Y, Z, T axes of each argument

or, when calling ef_get_arg_ss_extremes_6d,

1. INTEGER ss_min(6,EF_MAX_ARGS): the minimum indices for the X, Y, Z, T, E, F axes of each argument

2. INTEGER ss_max(6,EF_MAX_ARGS): the maximum indices for the X, Y, Z, T, E, F axes of each argument

Example:

INTEGER id, num_args
INTEGER ss_min(4,EF_MAX_ARGS), ss_max(4,EF_MAX_ARGS)

num_args = 3
CALL ef_get_arg_ss_extremes(id, num_args, ss_min, ss_max)

Ch11 Sec6.2.25.

ef_get_bad_flags(id, bad_flag, bad_flag_result)

Return the missing value flags for each argument and for the result.

Input arguments:

1. INTEGER id: external function's ID number

Output arguments:

1. REAL bad_flag(EF_MAX_ARGS): missing value flags for each argument

2. REAL bad_flag_result: missing value flag for the result

Sample code:

CALL ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr) 
CALL ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr) 
CALL ef_get_bad_flags(id, bad_flag, bad_flag_result) 

… 

IF ( arg_1(i1,j1,k1,l1) .EQ. bad_flag(ARG1) ) THEN 
result(i,j,k,l) = bad_flag_result 
ELSE 
...

Ch11 Sec6.2.26.

ef_get_coordinates(id, arg, axis, lo, hi, coords)

Return the "world coordinates" associated with a particular arg, axis and lo:hi range.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. INTEGER axis: axis number

4. INTEGER lo: lo index of desired range

5. INTEGER hi: hi index of desired range

Output arguments:

1. REAL*8 coords(*): array of "world coordinate" values (NB_ these values are associated with index values lo:hi but are returned as coords(1:hi-lo).)

Sample code:

[Not that Previous to Ferret v6.8, in the work_size subroutine, we needed to define twice as many elements as coordinates so as to have storage for REAL*8 numbers. In Ferret v6.8 and higher all variables are double precision so this special treatment is unnecessary. The REAL declaration defines double precision variables because of the compiler flags we use.]

SUBROUTINE myfcn_work_size(id)
INCLUDE 'ferret_cmn/EF_Util.cmn'
INCLUDE 'ferret_cmn/EF_mem_subsc.cmn'
INTEGER id

* Set the work arrays, X/Y/Z/T dimensions

INTEGER nxout, nx2
INTEGER arg_lo_ss(4,1:EF_MAX_ARGS), arg_hi_ss(4,1:EF_MAX_ARGS),
arg_incr(4,1:EF_MAX_ARGS)

CALL ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr)

nxout = 1 + arg_hi_ss(X_AXIS,ARG4) - arg_lo_ss(X_AXIS,ARG4)
nx2 = nxout* 2

* Define work array XAX

CALL ef_set_work_array_dims (id, 1, 1, 1, 1, 1, nx2, 1, 1, 1)
RETURN
END

[In the compute subroutine, prior to Ferret v6.8, we needed to dimension the REAL*8 coordinate array with half the wkr1hix dimension (wrk1lox:wrk1hix, etc are defined by the work_size subroutine, so the xax declaration below would have had xax(wrk1lox:wrk1hix/2... )]

SUBROUTINE myfcn_compute(id, arg_1, arg_2, result, xax)
…
REAL arg_1(mem1lox:mem1hix, mem1loy:mem1hiy, mem1loz:mem1hiz, 
. Mem1lot:mem1hit) 
REAL result(memreslox:memreshix, memresloy:memreshiy, 
. memresloz:memreshiz, memreslot:memreshit)

INTEGER res_lo_ss(4), res_hi_ss(4), res_incr(4)
INTEGER arg_lo_ss(4,EF_MAX_ARGS), arg_hi_ss(4,EF_MAX_ARGS),
. Arg_incr(4,EF_MAX_ARGS)

C Dimension the work array: X dimension was defined twice as large 
C as the # coordinates, for double precision work array.

REAL*8 xax(wrk1lox:wrk1hix, wrk1loy:wrk1hiy,
. wrk1loz:wrk1hiz, wrk1lot:wrk1hit)
… 

CALL ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr) 
CALL ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr) 
CALL ef_get_bad_flags(id, bad_flag, bad_flag_result) 

CALL ef_get_coordinates(id, ARG1, X_AXIS, arg_lo_ss(X_AXIS
. ARG1), arg_hi_ss(X_AXIS, ARG1), xax ) 

… 

dummy = 1 
DO 30 i = arg_lo_ss(Y_AXIS, ARG1), arg_hi_ss(Y_AXIS, ARG1)
cstr(i) = 1.0 / cos( xax(dummy) * (1.0/radian) ) 
dummy = dummy + 1 
30 CONTINUE

Ch11 Sec6.2.27.

ef_get_box_size(id, arg, axis, lo, hi, size)

Return the grid-cell box sizes (in "world coordinates") associated with a particular arg, axis and lo:hi range.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. INTEGER axis: axis number

4. INTEGER lo: lo index of desired range

5. INTEGER hi: hi index of desired range

Output arguments:

1. REAL size(*): array of box size values (NB_ these values are associated with index values lo:hi but are returned as coords(1:hi-lo).)

Sample code:

REAL tk_y(wrk1lox:wrk1hix, wrk1loy:wrk1hiy/2,
. wrk1loz:wrk1hiz, wrk1lot:wrk1hit)
REAL tk_dx(wrk2lox:wrk2hix, wrk2loy:wrk2hiy,
. wrk2loz:wrk2hiz, wrk2lot:wrk2hit)

INTEGER dummy 

… 

CALL ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr) 
CALL ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr) 
CALL ef_get_bad_flags(id, bad_flag, bad_flag_result) 
CALL ef_get_coordinates(id, ARG1, Y_AXIS, arg_lo_ss(Y_AXIS, ARG1),
. arg_hi_ss(Y_AXIS, ARG1), tk_y ) 
CALL ef_get_box_size(id, ARG1, X_AXIS, arg_lo_ss(X_AXIS, ARG1),
. arg_hi_ss(X_AXIS, ARG1), tk_dx ) 

… 

dummy = 1 
DO 20 i = arg_lo_ss(X_AXIS, ARG1), arg_hi_ss(X_AXIS, ARG1) 
dxt4r(i) = 1.0 / ( 4.0 * tk_dx(dummy) * radius/radian ) 
dummy = dummy + 1 
20 CONTINUE

Ch11 Sec6.2.28.

ef_get_box_limits(id, arg, axis, lo, hi, lo_lims, hi_lims)

Return the box limits (in "world coordinates") associated with a particular arg, axis and lo:hi range.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. INTEGER axis: axis number

4. INTEGER lo: lo index of desired range

5. INTEGER hi: hi index of desired range

Output arguments:

1. REAL lo_lims(*): array of box lower limit values (NB_ these values are associated with index values lo:hi but are returned as coords(1:hi-lo).)

2. REAL hi_lims(*): array of box upper limit values (NB_ these values are associated with index values lo:hi but are returned as coords(1:hi-lo).)

Ch11 Sec6.2.29.

ef_get_one_val(id, arg, value)

Return the value of 1×1×1×1 variable.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

Output arguments:

1. REAL value : The value of the variable

Ch11 Sec6.2.30.

ef_get_string_arg_element(id, arg, str_arg, i,j,k,l, slen, text) and

ef_get_string_arg_element_6d(id, arg, str_arg, i,j,k,l,m,n slen, text)

Return one single string element from a string variable.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. REAL str_arg: the argument, e.g. arg_1, pointer to the string argument.

4-7. INTEGER i,j,k,l: the indices of the string element to return.
When calling ef_get_string_arg_element_6d, m n are the indices in the E and F directions for the element to return.

Output arguments:

1. INTEGER slen : The length of the string element

2. CHARACTER text : The string. If the string variable you have declared in the external function is too short for the string in the argument, the variable text will be truncated, but the value of slen will contain the length of the string in the argument.

Ch11 Sec6.2.31.

ef_get_string_arg_element_len (id, arg, str_arg, i,j,k,l, slen) and

ef_get_string_arg_element_len_6d (id, arg, str_arg, i,j,k,l,m,n, slen)

Return the length of a single string element from a string variable.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. REAL str_arg: the argument, e.g. arg_1, pointer to the string argument.

4-7. INTEGER i,j,k,l: the indices of the string element to return.
When calling ef_get_string_arg_element_len_6d, m n are the indices in the E and F directions for the element to return.

Output arguments:

1. INTEGER slen : The length of the string element

Ch11 Sec6.2.32.

ef_get_string_arg_max_len (id, arg, str_arg, slen)

Return the length of a single string element from a string variable.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER arg: argument number

3. REAL str_arg: the argument, e.g. arg_1, pointer to the string argument.

Output arguments:

1. INTEGER slen : The maximum length of the strings in the array

Ch11 Sec6.2.33.

ef_version_test (version)

Return the version number of the external functions code that is in place.

Output argument:

1. REAL version : The version number

Ch11 Sec6.2.34.

ef_bail_out(id, text)

Bail out of an external function, returning to Ferret and issuing a message to the user.

Input arguments:

1. INTEGER id: external function's ID number

2. INTEGER text: text string to output.

The bail-out message looks like this, where the text supplied in the call to ef_bail_out is on the second line:

Bailing out of external function "ffta":
Time axis must be a regular axis
**ERROR: : error in external function

Search form

You are here

Ch11 Sec6.

Ch11 Sec6.1.

Ch11 Sec6.2.

Ch11 Sec6.2.1.

Ch11 Sec6.2.2.

Ch11 Sec6.2.3.

Ch11 Sec6.2.4.

Ch11 Sec6.2.5.

Ch11 Sec6.2.6.

Ch11 Sec6.2.7.

Ch11 Sec6.2.8.

Ch11 Sec6.2.9.

Ch11 Sec6.2.10.

Ch11 Sec6.2.11.

Ch11 Sec6.2.12.

Ch11 Sec6.2.13.

Ch11 Sec6.2.14.

Ch11 Sec6.2.15.

Ch11 Sec6.2.16.

Ch11 Sec6.2.17.

Ch11 Sec6.2.18.

Ch11 Sec6.2.19.

Ch11 Sec6.2.20.

Ch11 Sec6.2.21.

Ch11 Sec6.2.22.

Ch11 Sec6.2.23.

Ch11 Sec6.2.24.

Ch11 Sec6.2.25.

Ch11 Sec6.2.26.

Ch11 Sec6.2.27.

Ch11 Sec6.2.28.

Ch11 Sec6.2.29.

Ch11 Sec6.2.30.

Ch11 Sec6.2.31.

Ch11 Sec6.2.32.

Ch11 Sec6.2.33.

Ch11 Sec6.2.34.