Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

IBIS-Q System Documentation - Reference

Function File

Function files contain the measure-specific information needed to run a query on a dataset. A function file is a definition file and is saved as MeasureName.def, for example, Count.def or CrudeRate.def.

There are two main types of function files. The most flexible is the special function file. It has the SAS code inside the function file and will be discussed first. In general references and examples of function files are special function files. There are also standard function files that are preprogrammed into the CGI application. This means the SAS code is contained in the CGI code and is therefore not flexible. Standard Function files will be discussed at the bottom of this page.

Survey data requires a separate type of function file. The function file structure doesn't change, but two different system variables are added and the type changed. For information on and examples of survey data function files, see Proc Surveymeans Function File within this section.

There are three parts in a function file:
  1. Data Restrictions. The first section contains IBIS query parameters for this specific SAS template (lines 1-5). In general, it is common procedure to put a label comment on the first line.
    1. Type (line 3): has to be "special2"
    2. data_where and pop_where can be used for data restrictions if needed (lines 4-5, commented out with # sign in example)
  2. SAS Template. The second section contains the SAS code that will be used to run the query (Count.def lines 8-21; CrudeRate.def lines 8-87). Function files can be written in many ways; the example section shows one way.
    The %cross1% and %cross2% hold SAS variables passed by query string (Count.def lines 16-17; CrudeRate.def line 19).
  3. Format and Output. The third section lists the exported SAS variables with their format and order and the XML Element Output Value Mapping file to be used for the results (Count.def lines 26-27; CrudeRate.def lines 95-100).
    1. The variable order in the list must match the order of xml tags in XML Element Output Value Mapping file (XMLOutputNames.map) exactly (Count.def line 27; CrudeRate.def lines 96-100).
    2. xml_out_map_file has to point to a XML Element Output Value Mapping file file, for example in CrudeRate.def it has this line "xml_out_map_file XMLRateNumerDenomLCLUCL.map" and the XMLRateNumerDenomLCLUCL.map file saved in the same directory as the function file (Count.def line 26 and see XMLCount.map; CrudeRate.def line 95 and see XMLRateNumerDenomLCLUCL.map).

Other Information

To turn off the total row on the results page add the following line to the function file:
f no_total true

The function file will not work properly if there is a space after the "1 script" line. (See Count.def example, line 7.)

If using a Windows machine all the function files need to be standard MS-DOS text type to work properly.

The BoNdArY line must have an even number of dashes because they are used as a pair. It is standard practice to use 8 dashes at the beginning and ending of the line (See Count.def line 6).

Syntax

File name: MeasureName.def
# measure name 
f type special2 
#f data_where SAS code for data restriction
#f pop_where SAS code for data restriction
#########################################
--------BoNdArY--------
1 script
SAS code

--------BoNdArY--------
f out_variable  (left over from previous system - needs to be here)
########changed 11/3/04#########################################
f xml_out_map_file XMLOutputNames.map
--------BoNdArY--------
f out_detail lbl_not_used__see_xml_out_map_file
var1    format
var2   format
var3...
--------BoNdArY--------

Example

File name: Count.def 
1	####Part one:data restriction### count
2	f type special2 
3	#f data_where %cross1%^=99
4	#f pop_where sex=1&and&15<=age<=44
5	###Part two: SAS code template#################################
6	--------BoNdArY--------
7	1 script
8	data tmp;
9	set tmp;
10	x=1;
11	run;
12	 
13	proc summary data=tmp n;
14	var x sex;
15	class sex %cross1% 
16	?cross2? %cross2%
17	;
18	output out=tmp sum=n;
19	run;
20	
21	--------BoNdArY--------
22	f out_variable 
23	###Part three: Output specification####################
24	f xml_out_map_file XMLCount.map
    --------BoNdArY--------
25  f out_detail lbl_not_used__see_xml_out_map_file
26	n 15.0
27	--------BoNdArY--------

File name: XMLCount.map 
1 COUNT

File name: CrudeRate.def 
1	##########Part one: data restriction#######
2	# Crude Rate
3	f type special2 
4	#f data_where 
5	#f pop_where 
6	#########Part two: SAS code template######
7	--------BoNdArY--------
8	1 script
9	OPTIONS MPRINT MLOGIC SYMBOLGEN;
10	OPTION SPOOL;

11	%let flag=0; 
12	?popcross1? %let flag=1; 
13	?popcross2? %let flag=1;
14	?popcross1? ?popcross2? %let flag=2;
15	
16	proc summary data=tmp;
17	 var x;
18	 class %cross1% %cross2%;
19	 output out=tmp sum=number;
20	 run;
21	
22	%macro popcross;
23	%if &flag=0 %then %do;
24	 proc summary data=poptmp;
25	 var popcount;;
26	 output out=pop sum=popnum;
27	 run;
28	
29	proc sql;
30	 create table rate as
31	 select tmp.*, pop.*
32	 from tmp, pop
33	 quit;
34	%end;
35	
36	%if &flag=1 %then %do;
37	proc summary data=poptmp;
38	var popcount;;
39	class %popcross1% %popcross2%;
40	output out=pop sum=popnum;
41	 run;
42	
43	proc sql;
44	 create table rate as
45	 select tmp.*, pop.*
46	 from tmp, pop
47	where 
48	?popcross1? tmp.%cross1%=pop.%popcross1%;
49	?popcross2? tmp.%cross2%=pop.%popcross2%;
50	 quit;
51	%end;
52	
53	%if &flag=2 %then %do;
54	  proc summary data=poptmp;
55	  var popcount;;
56	class %popcross1% %popcross2%  ;
57	 output out=pop sum=popnum;
58	 run;
59	 
60	proc sql;
61	 create table rate as
62	 select tmp.*, pop.*
63	 from tmp, pop
64	where tmp.%cross1%=pop.%popcross1% and
65	tmp.%cross2%=pop.%popcross2%;
66	 quit;
67	%end;
68	
69	%mend;
70	
71	%popcross;
72	
73	 data tmp;
74	 set rate;
75	 rate=number/popnum;
76	 stdev=1.96*sqrt(rate*(1-rate)/popnum);
77	 t1=(rate-stdev)*100000;
78	 if (t1<0) then t1=0;
79	 r1=put(t1, 8.2);
80	 r2=put((rate+stdev)*100000, 8.2);
81	 rate=rate*100000;
82	 r1=compress(r1);
83	 r2=compress(r2);
84	 ci=r1 || ' - ' || r2;
85	n=number;
86	  run;
87	
88	--------BoNdArY--------
89	f out_variable 
90	#########Part three: SAS output variable list ########
91	f xml_out_map_file XMLRateNumerDenomLCLUCL.map
92	--------BoNdArY--------
93	f out_detail lbl_not_used__see_xml_out_map_file
94	rate 15.2
95	n 15.0
96	popnum 15.0
97	r1 15.
98	r2 15.
--------BoNdArY--------

File name: XMLRateNumerDenomLCLUCL.map 
1 RATE
2 RATE_NUMERATOR
3 RATE_DENOMINATOR
4 RATE_LOWER_CONFIDENCE_LIMIT
5 RATE_UPPER_CONFIDENCE_LIMIT


Proc Surveymeans Function File

Function files with "proc surveymeans" contain the measure-specific information needed to run a query on a survey dataset. The manner in which survey statistics are processed differs from other statistics that SAS runs: survey data statistics must be run over the whole year of that dataset, regardless of the selected filter variables.

Basic file structure is the same as for special function files (discussed above). However, the following differences apply:
  1. Type (line 3): has to be "special_survey"
  2. The second section containing the SAS code that will be used to run the query. (Count.def lines 8-21; CrudeRate.def lines 8-87) contain an additional cross variable: %cross3%
  3. Two other system variables are added in section two: %surveyvar1% and %surveyvar2% hold filter variables passed by query string
    %surveyvar1% is a group of filter variables with "*". The syntax is "*var1*var2" and it needs to be on the domain statement with %cross% variable (Line 7).
    %surveyvar2% is a group of filter variables without "*". It looks like "var1 var2" and needs to be on the proc summary statement with %cross% variable (Line 24)

Syntax

File name: MeasureName.def
# measure name 
f type special_survey 
#f data_where SAS code for data restriction
#f pop_where SAS code for data restriction
#########################################
--------BoNdArY--------
1 script
(SAS code)

--------BoNdArY--------
f out_variable  (left over from previous system - needs to be here)
########changed 11/3/04#########################################
f xml_out_map_file XMLOutputNames.map
--------BoNdArY--------
f out_detail lbl_not_used__see_xml_out_map_file 
var1  format
var2   format
var3...
--------BoNdArY--------

Example

File name: HlthCareCov.def (SAS template in function file. Currently Utah has this code in an include file.)
1	proc surveymeans data=tmp ;
2	var &varname. ;
3	class &varname. ;
4	strata yr stratum ;
5	cluster psu;
6	domain 
7	?cross1? ?cross3? %cross1%*%cross3% %surveyvar1%
8	?cross1? %cross1% %surveyvar1%
9	?cross3? %cross3% %surveyvar1%
10	   ;
11	ods output statistics=stats
12	summary=sum 
13	domain=domain ;
14	weight weight ;
15	run;
16	
17  (%surveyvar2% is the same group of filter variables 
	without "*" , looks like "var1 var2". It needs be on proc 
	summary statement with %cross% variable.) 
18	***********************************
19	(SAS template in func file)
20	proc summary data=tmp5;
21	 var n percent;
22	 class %cross1% 
23	 ?cross3? %cross3%
24	 %surveyvar2%
25	;
26	 output out=total sum(n percent)=;
27	 run;
28	***********************************


Standard Function File

The standard function file is one that is preprogrammed into the CGI program. These standard function files include the following:

Other Information

Standard function files can only handle 2 cross variables. If you want to use 3 cross variables then you need to use the special function file.

For the ajrate2 standard function file the standard population needs to be specified as a parameter in the module.xml file. It looks like this: 
<PARAMETER>
  <NAME>stdpop</NAME>
  <VALUE>2000</VALUE>
</PARAMETER>

When you don't use the stdpop you get an error message 
<ERROR ID='7'>
WARNING: 
No standard population was selected, 2000 US population is used.
</ERROR>
</IBISQ_DATA>

The IBISQ_DATA tag has no beginning tag and therefore you will not see your results on the results page even though they were returned.

Syntax

File name: MeasureName.def
1	f label Label&of&Measure
2	f type (specify type here)
3	f xml_out_map_file (name of output mapping file)
4	f out_detail lbl_not_used__see_xml_out_map_file
5	(conditions needed for the type or dataset you are working with)

Example

File name: Count.def 
1	f label Number&of&death
2	f type count
3	f xml_out_map_file XMLCount.map
4	f out_detail lbl_not_used__see_xml_out_map_file

File name: Average.def
With 'average' you need to specify the variable to average (line 5).
1	f label Average&of&Death&Age
2	f type average
3	f xml_out_map_file XMLAverageNumerDenomLCLUCL.map
4	f out_detail lbl_not_used__see_xml_out_map_file 
5	f variable age

File name: CrudeRate.def
Line 5 shows an optional multiple to use with the rate. Line 6 specifies the variable to use for the denominator.
1	f label Crude&Death&Rate&(per&100,000&pop.)
2	f type rate
3	f xml_out_map_file XMLRateNumerDenomLCLUCL.map
4	f out_detail lbl_not_used__see_xml_out_map_file
5	f multiple 100000
6	f pop_count popcount

File name: AgeRate.def
Lines 7-9 are used to specify parameters for the file. Line 3 and 6 are optional data conditions.
1	f label Age-adjusted&Death&Rate
2	f type ajrate2
3	f data_where status=10
4	f xml_out_map_file XMLRateNumerDenomLCLUCL.map
5	f out_detail lbl_not_used__see_xml_out_map_file 
6	f multiple 10000
7	f age_group agepop
8	f pop_group agepop
9	f pop_count popcount