cb_nmer(3B)                                           Last changed: 09-26-03

NAME
	cb_nmer - Creates an array of subsequences of a bit string

SYNOPSIS

	C/C++:

	#include <cbl.h>
	void cb_nmer( long *db, long dblen, long *dbe, long nmer_size, 
                      long mode, long *errno);

	Fortran:

	use cb_bits
	call cb_nmer( db, dblen, dbe, nmer_size, mode, errno)


IMPLEMENTATION

	UNICOS/mp and Cray SV1 series UNICOS systems

DESCRIPTION

	cb_nmer creates an output array of substrings of bit fields, called nmers,
	stored one nmer per word. The size of the bit fields is determined by
	the value of mode. The number of consecutive fields in each output
	word is determined by nmer_size. The nmers are limited in size to the 
	size of the array elements, typically 64 bits. Consecutive substrings
	are separated in the input string by a the bit field size, and the
	length of each nmer is fixed.  For example, ASCII characters are
	stored in memory fields that are 8 bits wide.  If the input bit string
	represented the letters:

        db: ABCDEFGHIJKLMN

	and mode = 8 (for bit fields of length 8) and the nmer_size = 5, then
	the output would be

        dbe: ABCDE
             BCDEF
             CDEFG
             DEFGH
             EFGHI
             FGHIJ
             GHIJK
             HIJKL
             IJKLM
             JKLMN

	The letters in the output array, dbe, represent 40 bits, which are left
	justified. The remaining 24 bits of each word are set to zero.

	db (input) stream of bits representing consecutive fields of bits
		as described by the mode argument. In Fortran, db should be
		an INTEGER(8) array. 

	dblen (input) The number of bit fields in the db array.  The size of
		the bit fields is specified by mode. The total size of db
		is dblen*mode bits, or (dblen*mode + 63)/64 words. The final
		word of db is padded with zero bits if necessary. For example,
		if mode = 2 and the data in db represents compressed
		nucleotide data (see cb_compress(3B)) then dblen is the
		number of nucleotides stored in db.  In Fortran, dblen should
		be an INTEGER(8) variable, constant, or expression.

	dbe (output) Array containing the resulting nmers. Memory for dbe must
		be allocated before calling cb_nmer, and be at least
		dblen - (nmer_size-1) 64-bit words in length.  In Fortran, 
		dbe should be an INTEGER(8) array.

	nmer_size (input) The number of consecutive bit fields stored in each
		word of the output array dbe. In Fortran, nmer_size should be
		an INTEGER(8) variable, constant, or expression.

	mode (input) Allowed values are 1, 2, 4, and 8. Mode specifies the
		size of the fields in bits. The values 2 and 4 are used
		for nucleotide data that has been compressed using the 
		same mode values with the cb_compressed(3B) routine. In 
		this case, each field represents one nucleotide. The value
		8 is used of db contains uncompressed ASCII data. The value
		1 is used to create nmers from every starting position in
		the input string. See the NOTES below for possible uses
		of mode = 1.  In Fortran, mode should be an INTEGER(8) 
		variable, constant, or expression.

	errno (output) Returned error number.  The possible values are
		errno = 0  : no error
		errno = 30 : nmer_size value is too large or too small
		errno = 31 : dblen is smaller than nmer_size
		errno = 32 : mode value is not 1, 2, 4, or 8. 
		In Fortran, errno should be an INNTEGER(8) variable.
 
NOTES       
	cb_nmer is single-threaded (i.e. not tasked) and may be called 
	from within a parallel region.

	Nmers with starting spacings other than the ones provided with the 
	mode values supported can be obtained by calling cb_nmer with mode = 1 
	and discarding part of the results. For example, nmers starting every 
	7th bit location are in every 7th element of the dbe() array created 
	with mode = 1.

	Nmers longer than 64 bits in length can also be obtained using the
	output of cb_nmer with mode = 1. Such nmers require more than one
	word of storage each.  For example, nmers of length 96 bits require
	two 64-bit words of storage. The first of these words is located
	every 96 elements of the dbe() array. The second word of each pair
	is 64 elements past the first element. The trailing 32 bits of the
	second word then needs to be cleared.  Note that for the case of 96
	bit nmers, you could also use the output of mode=8,and index every
	12 and 8 words of the dbe() array.  For the general case, the mode=1
	result will always work.

SEE ALSO

	cb_compress(3B), INTRO_LIBCBL(3B)

	This man page is available only online.