Conference ilbbak::ibi_focus

191.0. "List of FOCUS Functions/Subroutines" by INCH::OTTEN (Take me to your Lizard) Wed Mar 29 1989 08:00

Hi,
    
    There's been a lack of FOCUS Documentation her in ADG, So I conned
    one of our temps to produce this listing for me. It's a brief Precis
    of the FOCUS-supplied functions, and is only intended as a
    quick-reference guide. I posted it (on request) in the SHIRE::FOCUS
    notesfile, and was asked to cross-post it in this one....
    
    
    Here goes.......
    
    David



ARGLEN (inlength, infield, outfield)
	The ARGLEN subroutine measures the length of a character string 
	within a field, excluding trailing blanks. (The field format
	specifies the length of the field, but this includes trailing 
	blanks.)


ATOBDL (number, inlength, outfield)
	The ATOBDL subroutine converts numbers from alphanumeric to
	double-precision format.


AYM    (indate, months, outfield)
	The AYM subroutine adds and subtracts months from dates. The
	dates must be in year-month format. You can convert a date to
	this format by using the CHGDAT subroutine (described in Section
	4.2.1). If the date is in integar year-month-day format(16YMD or
	18YYMD), simply divide the date by 100 to convert to year-month 
	format.


AYMD   (indate, days, outfield)
        The AYMD subroutine adds and subtracts days from dates. This
	subroutine is not limited to the 20th century.
	The subroutine only operates on dates in year-month-day format.
	You can convert a date to this format using the CHGDAT subroutine
	(described in Section 4.2.1).


BAR	(barlength, infield, maxvalue, char, outfield)
	The BAR subroutine allows you to produce horizontal bar charts in
	TABLE reports. The bars, which consist of repeating characters, 
	constitute a field with each bar a field value. When the TABLE
	request prints the field, the bars appear in the report.


BITSON (bitnumber, infield, outfield)
	The BITSON subroutine evaluates individual bits within character
	strings, determining if a bit is on or off. If the bit is on, the
	subroutine returns a 1; otherwise it returns a 0. This subroutine
	is useful in interpreting multi-punch data, where each punch conveys
	an item of information.


BITVAL (infield, startbit, number, outfield)
        The BITVAL subroutine evaluates strings of bits within character
	strings. It evaluates the bit strings as binary integars and returns
	the corresponding values. Note that the bit strings can be any group of
	bits within the character string and can cross byte and word boundaries.


CHGDAT (oldformat, newformat, indate, outfield)
	The CHGDAT subroutine rearranges the year, month, and day portions of
	dates and converts dates between long and short date formats.(Long
	formats contain the year, month, and day;short formats contain one 
	or two of these elements, such as year and month or just the day.)
	A format can be longer by coding the year by its four digits (for
	example, 1987), or shorter by coding the year by its last two digits
	(for example,87). For more information on date formats, see the
	chapters 3 and 4 of the FOCUS Users Manual.


CHKFMT (numchar, infield, mask, outfield)
	The CHKFMT subroutine checks character strings for incorrect character
	types. It compares each string to a second string (calleda "mask"),
	comparing each character in the input to the corresponding character
	in the mask. If all characters in the string match the characters or 
	character types of those in the mask, CHKFMT returns a value of 0.
	Otherwise, CHKFMT returns the position of the first character in the
	string not matching the mask.
	If the mask is shorter than the character string, then the subroutine
	checks only the portion of the character string corresponding to the
	mask. For example, if you are using a 4-character mask to test a 
	9-character string, only the first four characters in the string are
	checked; the rest are ignored.


CHKPCK (inlength, infield,error, outfield)
	The CHKPCK subroutine validates packed fields, checking if their values
	are in packed format. The subroutine prevents data exceptions that occur
	when FOCUS requests read packed fields from files containing values
	that are not valid packed numbers.


CTRAN  (inlength, infield, incode, outcode, outfield)
	The CTRAN subroutine converts a character appearing in a string to 
	another character. To use this function, you need to know the 
	decimal equivalent of the characters in internal machine representation,
	the code your machine uses to store alphanumeric data. On DIGITAL 
	machines, this code is called ASC11.
	CTRAN enables you to convert a character wherever it appears in a
	string to any other character, even to a characterthat you cannot type on
	on your keyboard. Another subroutine that can produce any character is 
	the HEXBYT subroutine, described in Section 5.2.1
	The CTRAN subroutine also makes it easier to type entries with special
	characters during a MODIFY PROMPT session, because it dispenses with 
	the need to enclose the entries in quotation marks if it contains a 
	comma.


CTRFLD  (infield, inlength, outfield)
	The CTRFLD subroutine centers character strings within fields. The
	number of leading blanks is equal to or one less than the number of 
	trailing blanks.
	The CTRFLD subroutine is useful for centering a heading that consists 
	only of an embedded field. The TABLE phrase HEADING CENTER centers each field 
	value including trailing blanks.To center the field value without the 
	trailing blanks, first center the value within the field using the 
	CTRFLD subroutine.


CVTSTIME (number, infield, outfield)
	  The GETSTIME and CVTSTIME subroutines retrieve, convert and write
	  the DEC standard date and time fields.
          CVTSTIME converts a 64-bit date/time field into a printable	
	  character string.


DAxxx   (indate, outfield)
	The DA subroutines convert dates to the corresponding number of days
	elapsed since January 1, 1900 (January 1, 1900 is day 1). There are
	six DA subroutines; each subroutine accepts dates in a different format.
	


DMOD   (dividend, divisor, outfield)
	The MOD subroutines calculate the remainder from a division.
	There are three MOD subordinates:
	- IMOD, which returns the remainder as an integar.
	- FMOD, which returns the remainder as a floating-point number.
	- DMOD, which returns the remainder as a double-precision number.


{DOWK }
{DOWKL}(indate, outfield)
	The DOWK subroutine finds the day of the week (Sunday through Saturday)
	of dates. The DOWK subroutine returns the day as a 3-letter
	abbreviation;to display the full name of the day, specify DOWKL instead.
	The subroutine is not limited to the 20th century.


DTxxx  (number, outfield)
	The DT subroutines convert numbers representing the days elapsed 
	since January 1, 1900 (January1, 1900 is day 1) into corresponding
	dates. There are six DT subroutines; each subroutine converts the 
	numbers into dates of a different format.


EXP    (power, outfield)
	The EXP subroutine raises the number "e" (approximately 2.72) to a
	power you specify. This subroutine is the converse of the LOG function
	described in Chapter 2 of the FOCUS Users Manual.


FMOD   (dividend, divisor, outfield)
	(RE: MOD )



FTOA   (number, '(format)', outfield)
	The FTOA subroutine converts numbers from numeric to alphanumeric
	format and supplies the converted numbers with edit options, such
	as commas and dollar signs.


GETTOK (in, inlen, toknum, delim, outlen, outfield)
	The GETTOK subroutine divides a character string where a specific
	character , called the delimiter, occurs in the string. It then returns
	one of the substrings, called a token.
	For example, suppose you want to extract the fourth word from a
	sentence. The subroutine divides the sentence into words using spaces 
	as delimiters, then extracts the fourth word.
	Note that the delimiter is not included in the tokens.


GETSTIME(outfield)
	 The GETSTIME and CVSTIME subroutines retrieve, convert and write the
	 DEC standard date and time fields.
	 GETSTIME extracts the systems date and time into an 8-character 
	 (64-bit) string.


GETUSER (outfield)
	The GETUSER subroutine retrieves the user ID, or jobname if the 
	subroutine is run from a batch job.


GREGDT (indate, outfield)
	This subroutine converts dates in Julian format (explained in Section 
	4.2.2) to year-month-day format.


HEXBYT (number, outfield)
	The HEXBYT subroutine translates an integar between 0 and 255 (base 10)
	into the character it represents in ASC11. You can use this subroutine
	to produce characters that are not on your keyboard, similar to the 
	CTRAN subroutine (discussed in Section 2.3.2).


HHMMSS (outfield)
	The HHMMSS subroutine retrieves the current time from the system. It 
	returns the time as an 8-byte character string with embedded periods
	seperating the hours, minutes, and seconds.


ILOCAS (cstring, inlength, infield, outfield)
	The ILOCAS subroutine converts a set of defined characters appearing in	
	a string to user-specified equivalents.
	This routine enables you to define a set of characters and assign 
	equivalents. Whenever you type a defined character it can be converted
	to the equivalent that you assigned.


IMOD   (dividend, divisor, outfield)
	IMOD is an MOD subroutine which returns the remainder from a division
	as an integar.


ITOZ   (outlength, number, outfield)
	The ITOZ subroutine converts numbers in numeric format to zoned 
	format. Although FOCUS does not process zoned numbers, FOCUS
	requests can write zoned fields to extract files for use by external
	programs.


IUPCAS (cstring, inlength, infield, outfield)
	The IUPCAS subroutine converts a set of defined characters appearing
	in a string to user-specified equivalents.
	This routine enables you to define a set of characters and assign
	equivalents. Whenever you type a defined character it can be converted
	to the equivalent that you assigned.


JULDAT (indate, outfield)
	The JULDAT subroutine converts dates from year-month-day format to
	Julian (year-day) format. Dates in Julian format are 5-digit numbers.
	The first two digits are on the year, the last three digits are the 
	number of the day counting from January 1. For example, January 1, 1987
	in Julian format is 87001, and December 31, 1987 is 87365.


LJUST  (inlength, infield, outfield)
	The LJUST subroutine left-justifies a character string within a field.
	All leading blanks become trailing blanks. The LJUST subroutine is 
	helpful in left-justifying character strings previously 
	right-justified or centered.


LOCASE (inlength, infield, outfield)
	The LOCASE subroutine converts characters in alphanumeric field
	values to lower case.
	- In Fidel. The FIDEL option CRTFORM LOWER retains the case of entries
	as they were typed. When you use this option, the LOCASE subroutine 
	enables you to convert entries of certain fields in lower case.
	-In sorting. In normal ascending sort order, lower case comes before 
	upper case. The LOCASE subroutine enables you to sort entries by 
	alphabetical order without regard to case.


MXCASE (inlength, infield, outfield)
	The MXCASE subroutine converts the initial character of each word in	
	alphanumeric field values to upper case.


OVRLAY (base, baselen, substring, sublen, position, out)		
	The OVRLAY subroutine overlays a substring on another character string.
	When used in MODIFY requests, the subroutine allows you to edit a part 
	of an alphanumeric field without replacing the field entirely.


PARAG  (inlength, outlength, subsize, outfield)
	The PARAG subroutine divides lines of text into smaller lines by marking
	them of with a delimiter character. The GETTOK subroutine can then 
	place the smaller lines, called "sublines", into different fields.
	The PARAG subroutine works by scanning a specific number of characters
	from the beginning of the line and replacing the last space in this 
	group with a delimiter. It then scans the next group of characters
	starting from the delimiter and replaces the last space in this group
	with a second delimiter. It repeats this process until the end of the 
	line. Each group of characters marked of by the delimiter becomes a 
	subline.


PCKOUT (infield, outlength, outfield)
	The PCKOUT subroutine allows requests to write packed numbers of 
	different lengths to extract files (HOLD, SAVE and SAVB files).
	When a request saves packed fields in extract files, it  writes
	them as 8-byte fields regardless of their format specifications.
	With the PCKOUT subroutine, you can vary their lengths between one
	and eight bytes.


POSIT  (parent, inlength, substring, sublength, outfield)
	The POSIT subroutine finds the starting positions of substrings within
	larger strings. For example, the position of the substring "DUCT" in the
	character string "PRODUCTION" is position 4.


PRDNOR (seed, outfield)
	The PRDNOR subroutine generates reproducible sets of double-precision
	random numbers normally distributed with an arithmetic mean of 0
	and a standard deviation of 1. For an explanation of these terms ,
	see Section 3.4.3.


PRDUNI (seed, outfield)
	The PRDUNI subroutine generates reproducible sets of double-precision
	random numbers uniformly distributed between 0 and 1. One of the 
	subroutine parameters is a number called a "seed". Each seed results in a 
	specific set of random numbers. To reproduce a set, pass the subroutine
	the same seed.


RDNORM (outfield)
	The RDNORM subroutine generates double-precision random numbers that
	are normally distributed with an arithmetic mean of 0 and a standard 
	deviation of 1. 


RDUNIF (outfield)
	The RDUNIF subroutine generates double-precision random numbers
	uniformly distributed between 0 and 1. Any random number it generates
	has an equal probability of being anywhere between 0 and 1.


RJUST (inlength, infield, outfield)
	The RJUST subroutine right-justifies a character string within a field.
	All trailing blanks become leading blanks. This subroutine is helpful 
	when you display alphanumeric fields containing numbers.


SOUNDEX(inlength, string, outfield)
	The SOUNDEX subroutine allows you to search for character strings 
	phonetically; that is, by how a string is pronounced rather than
	the way it is spelled. It works by converting character strings into
	4-character codes. The first character is the first character in the 
	string. The last three characters represent the first three significant
	sounds in the string.


SUBSTR (inlength, parent, start, end, sublength, outfield)
	The SUBSTR subroutine extracts substrings, based on where the 
	substring starts and ends in the parent string.


TODAY  (outfield)
	The TODAY subroutine retrieves the current date from the system.
	It returns the date as an  8-character string in month-day-year
	format, with embedded slashes seperating the month, day, and year
	portions.


UPCASE (inlength, infield, outfield)
	The UPCASE subroutine converts characters in alphanumeric field 
	values to upper case.
	The subroutine has two important applications:

	- In FIDEL. The FIDEL option CRTFORM LOWER retains  the case of 
	entries as they were typed. When you use this option, the UPCASE
	subroutine enables you to convert entries of certain fields in
	upper case.

	- In sorting. In normal ascending order (ASC11 code), lower case 
	comes before upper case. The UPCASE subroutine enables you to sort
	entries by alphabetical order without regard to case.


YM     (fromdate, todate, outfield)
	The YM subroutine finds the number of months that elapse
	between two dates. The dates must be in year-month format.
	You can convert a date to this format by using the CHGDAT 
	subroutine (described in Section 4.2.1). If the date is in integar
	year-month-day format (16YMD or 18YYMD), simply divide the date by 100
	to convert to year-month format.