Editing Guide to madagascar programs (section)

==sfcat==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Concatenate datasets. 
|-
! colspan="4" | sfcat > out.rsf order= space= axis=3 nspace=(int) (ni/(20*nin) + 1) o= d= [<file0.rsf] file1.rsf file2.rsf ... 
|-
|  colspan="4" | sfmerge inserts additional space between merged data.
|-
| ''int    '' || '''axis=3''' ||   || 	Axis being merged
|-
| ''float  '' || '''d=''' ||   || 	axis sampling
|-
| ''int    '' || '''nspace=(int) (ni/(20*nin) + 1)''' ||   || 	if space=y, number of traces to insert
|-
| ''float  '' || '''o=''' ||   || 	axis origin
|-
| ''ints   '' || '''order=''' ||   || 	concatenation order  [nin]
|-
| ''bool   '' || '''space=''' ||  [y/n] || 	Insert additional space.
:y is default for sfmerge, n is default for sfcat
|}

<tt>sfcat</tt> and <tt>sfmerge</tt> concatenate two or more files
together along a particular axis. It is the same program, only
<tt>sfcat</tt> has the default <tt>space=n</tt> and <tt>sfmerge</tt>
has the default <tt>space=y</tt>.
Example of <tt>sfcat</tt>:
<pre>
bash$ sfspike n1=2 n2=3 > one.rsf
bash$ sfin one.rsf
one.rsf:
    in="/tmp/one.rsf@"
    esize=4 type=float form=native
    n1=2           d1=0.004       o1=0          label1="Time" unit1="s"
    n2=3           d2=0.1         o2=0          label2="Distance" unit2="km"
        6 elements 24 bytes
bash$ sfcat one.rsf one.rsf axis=1 > two.rsf
bash$ sfin two.rsf
two.rsf:
    in="/tmp/two.rsf@"
    esize=4 type=float form=native
    n1=4           d1=0.004       o1=0          label1="Time" unit1="s"
    n2=3           d2=0.1         o2=0          label2="Distance" unit2="km"
        12 elements 48 bytes
</pre>
Example of <tt>sfmerge</tt>:
<pre>
bash$ sfmerge one.rsf one.rsf axis=2 > two.rsf
bash$ sfin two.rsf
two.rsf:
    in="/tmp/two.rsf@"
    esize=4 type=float form=native
    n1=2           d1=0.004       o1=0          label1="Time" unit1="s"
    n2=7           d2=0.1         o2=0          label2="Distance" unit2="km"
        14 elements 56 bytes
</pre>
In this case, an extra empty trace is inserted between the two merged files.
The axes that are not being merged are checked for consistency:
<pre>
bash$ sfcat one.rsf two.rsf > three.rsf
sfcat: n2 mismatch: need 3
</pre>

====Implementation: [https://github.com/ahay/src/blob/master/system/main/cat.c system/main/cat.c]====
The first input file is either in the list or in the standard input.
<syntaxhighlight lang="c">
    in = (sf_file*) sf_alloc ((size_t) argc,sizeof(sf_file));

    if (!sf_stdin()) { /* no input file in stdin */
	nin=0;
    } else {
	filename[0] = "in";
	nin=1;
    }
</syntaxhighlight>

Everything on the command line that does not contain a "=" sign is
treated as a file name, and the corresponding file object is added to the list.
<syntaxhighlight lang="c">
    for (i=1; i< argc; i++) { /* collect inputs */
	if (NULL != strchr(argv[i],'=')) 
	    continue; /* not a file */
	filename[nin] = argv[i];
	nin++;
    }
    if (0==nin) sf_error ("no input");
</syntaxhighlight>

As explained above, if the <tt>space=</tt> parameter is not set, it is
inferred from the program name: <tt>sfmerge</tt> corresponds to
<tt>space=y</tt> and <tt>sfcat</tt> corresponds to <tt>space=n</tt>.
<syntaxhighlight lang="c">
    if (!sf_getbool("space",&space)) {
	/* Insert additional space.
	   y is default for sfmerge, n is default for sfcat */
	prog = sf_getprog();
	if (NULL != strstr (prog, "merge")) {
	    space = true;
	} else if (NULL != strstr (prog, "cat")) {
	    space = false;
	} else {
	    sf_warning("%s is neither merge nor cat,"
		       " assume merge",prog);
	    space = true;
	}
    }
</syntaxhighlight>

Find the axis for the merging (from the command line <tt>axis=</tt>
argument) and figure out two sizes: <tt>n1</tt> for everything after
the axis and <tt>n2</tt> for everything before the axis.
<syntaxhighlight lang="c">
    n1=1;
    n2=1;
    for (i=1; i <= dim; i++) {
	if      (i < axis) n1 *= n[i-1];
	else if (i > axis) n2 *= n[i-1];
    }
</syntaxhighlight>

In the output, the selected axis will get extended.
<syntaxhighlight lang="c">
    /* figure out the length of extended axis */
    ni = 0;
    for (j=0; j < nin; j++) {
	ni += naxis[j];
    }

    if (space) {
	if (!sf_getint("nspace",&nspace)) 
	    nspace = (int) (ni/(20*nin) + 1);
	/* if space=y, number of traces to insert */ 
	ni += nspace*(nin-1);
    } 

    (void) snprintf(key,3,"n%d",axis);
    sf_putint(out,key,(int) ni);
</syntaxhighlight>

The rest is simple: loop through the datasets reading and writing the
data in buffer-size chunks and adding extra empty chunks if
<tt>space=y</tt>.
<syntaxhighlight lang="c">
    for (i2=0; i2 < n2; i2++) {
	for (j=0; j < nin; j++) {
	    for (ni = n1*naxis[j]*esize; ni > 0; ni -= nbuf) {
		nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
		sf_charread (buf,nbuf,in[j]);
		sf_charwrite (buf,nbuf,out);
	    }
	    if (!space || j == nin-1) continue;
	    /* Add spaces */
	    memset(buf,0,BUFSIZ);
	    for (ni = n1*nspace*esize; ni > 0; ni -= nbuf) {
		nbuf = (BUFSIZ < ni)? BUFSIZ: ni;
		sf_charwrite (buf,nbuf,out);
	    }
	}
    }
</syntaxhighlight>