Chapter 9 – Functions

 

This chapter is about IB functions. Some functions are simple (stripping blanks from a string), while others are somewhat complex (moving a specified number of characters from one string into another string, starting at a specified location in the second string). Other functions return numerous bytes of status information, such as file status, device status, partition status, or logical unit number status. The list goes on.

 

The IB functions are presented in categories. For additional information on any of these functions, please see the reference documentation at the IB web site (www.internetbasic.com).

 

String stripping functions

 

The STRIP function strips leading and trailing blanks from a string. There are two related functions, STRIPL (which strips only the leading blanks) and STRIPR (which strips only the trailing blanks). The syntax is:

 

STRIP(string-argument)

STRIPL(string-argument)

STRIPR(string-argument)

 

When a string is stripped, its current length is adjusted accordingly. The current length is a numeric value that represents the number of characters of data stored in the string field.

 

String length function

 

The LEN function returns the current length of a string-argument. This value is very helpful for programs that need to determine how many characters of data are stored in a string field. (Note: It returns the current length, not the defined length.) The syntax is:

 

LEN(string-argument)

 

String adjustment functions

 

The ADJUSTL and ADJUSTR functions left-justify and right-justify a string-argument, respectively. For example, if the ADJUSTL function is used on a string that contains leading blanks, those blanks are removed and the remaining data is moved so that the first character of data appears in the first position of the string. The ADJUSTR function eliminates trailing blanks and moves the data so that the last character appears in the last position of the string. These functions to not affect the current length of the string. The syntax is:

 

ADJUSTL(string-argument)

ADJUSTR(string-argument)

 

Case adjustment functions

 

The UCASE function converts lower case characters in a string-argument to upper case characters. Other characters in the string-argument (e.g., upper case characters, special characters) remain unchanged. The LCASE function converts upper case characters to lower case. The syntax is:

 

UCASE(string-argument)

LCASE(string-argument)

 

Substring functions

 

SUB

 

The SUB function returns a substring of a specified string-argument. The syntax is:

 

SUB(string-argument,starting-position,length)

 

For example, the following statement returns the 5th, 6th, and 7th characters of the data stored in A$:

 

B$ = SUB(A$,5,3)  ! starting position=5, length of substring=3

 

RSUB

 

The RSUB function returns a substring from the right-hand side of a string argument. The syntax is:

 

RSUB(string-argument,starting-position,length)

 

The starting-position represents value counting from the right-hand side of the string. This function uses the current length (not the defined length) when determining the right-hand-most character.

 

For example, the following statement returns 5 characters from the right-hand size of the ADDRESS$ field:

 

            ZIP$=RSUB(ADDRESS$,1,5)

 

MOVE

 

The MOVE statement moves a specified number of characters from one string into another string, starting at a specified location in the second string. The syntax is:

 

MOVE(string-argument-1,string-argument-2,starting-position,length)

 

Note: This function does not return a value; it simply moves a portion of the first string into the second one.

 

For example:

 
MOVE(A$,B$,2,3)

 

If A$ = “ABCDEFG” and B$ = “123456789”, after the move operation, and B$ is “1ABC56789”.

 

String position functions

 

POS

 

The POS function returns the position of one string argument within a second string argument. The syntax is:

 

POS(string-1,string-2)

 

For example:

 

N = POS("SMITH",NAME$)

 

In this example, the string constant "SMITH" is compared to the string variable NAME$. If "SMITH" is located anywhere within NAME$, its position is returned and stored in the numeric variable N.

 

If "SMITH" is not found in the variable NAME$, the POS function returns a value of 0.  This programming technique can be useful for determining if a particular string value is contained within a specific data field.

 

RPOS

 

The RPOS function returns the position of one string argument within a second string argument scanning from right to left. The syntax is:

 

RPOS(string-1,string-2)

 

For example, assume that A$ = “c:\folder1\misc”:

 

N = RPOS("\",A$)

 

The RPOS function scans A$ from the right-hand side, looking for the position of the first backslash. It finds one at position 11 (counting from the left-hand side), which is the value that is assigned to N.

 

String swapping function

 

The SWAP function exchanges the values of two string variables. The syntax is:

 

SWAP(string-varaible-1,string-cariable-2)

 

Note: This function does not return a value; it simply exchanges the two strings.

 

String character duplicator function

 

The STRING function assembles a string of identical characters of specified length. The syntax is:

 

STRING(string-argument,numeric-argument)

 

For example, the following statement assembles a string of 50 asterisks:

 

            A$ = STRING("*",50)

 

Keyed file functions

 

The following functions return the first and last keys, respectively, in a keyed file:

 

FIRST(logical-unit-number [,EXCP=statement-label])

LAST(logical-unit-number [,EXCP=statement-label])

 

The KEY function returns the value of the next key, based on the position of the file pointer. The syntax is:

 

KEY(logical-unit-number [,EXCP=statement-label])

 

The PREV function returns the value of the previous key. The syntax is:

 

PREV(logical-unit-number [,EXCP=statement-label])

 

The RECNUM function returns the record number (numeric) of the keyed file that is open on the specified logical unit number. The syntax is:

 

RECNUM(logical-unit-number [,EXCP=statement-label])

 

Path function

 

The PATH function returns the full path associated with the specified IB directory label. The syntax is:

 

PATH(directory-label)

 

For example:

 

      A$ = PATH("BAS")

 

This statement returns the full path associated with the IB directory named “BAS.”

 

Encryption functions

 

The ENCRYPT function encrypts a string value by using a specified seed string. The syntax is:

 

ENCRYPT(plaintext-string-value,seed-string)

 

The seed-string may contain up to 254 characters. The longer the seed-string, the better the encryption.

 

For example:

 

A$ = "Here is some plain text."

SEED$ = "QWERTY123456ASDFGH567890"

B$ = ENCRYPT(A$,SEED$)

 

The B$ variable contains the encrypted version of A$. To decrypt this value, use the DECRYPT function and the same seed-string that was used to encrypt the plain text. The syntax is:

 

DECRYPT(encrypted-text,seed-string)

 

For example:

 

SEED$ = "QWERTY123456ASDFGH567890"

A$ = ENCRYPT(B$,SEED$)

 

Encoding functions

 

The BASE64 function performs a standardized encoding of a string-argument into printable characters, regardless of the value of the string-argument. The syntax is:

 

BASE64(string-argument,numeric-error-argument)

 

The numeric-error-argument is a numeric variable with a length and precision of at least 1.0. If the BASE64 function successfully encodes the string-argument, the numeric-error-argument is set to 0. If the conversion is unsuccessful (e.g., if the encoding overflows the string accumulator), it is set to 1.

 

This function allows hex strings to be encoded and used for such purposes as hidden fields in an HTML form, cookies, etc. For more information about Base 64 encoding, please see RFC 1421.

 

Note: For every 3 characters of 8 bits each in the string-argument, the BASE64 function returns 4 characters of 6 bits each. This means that the resulting string is longer than the string-argument. For example, if the string-argument is 30 characters, the result is 40 characters.

 

To de-encode a Base 64 string, use the BASE256 function. The syntax is:

 

BASE256(string-argument,numeric-error-argument)

 

The BASE256 function de-encodes the string-argument (a Base 64 string) into its original value.

 

The numeric-error-argument is a numeric variable with a length and precision of at least 1.0. If the BASE256 function successfully de-encodes the string-argument, the numeric-error-argument is set to 0. If the conversion is unsuccessful (e.g., if the string-argument contains an invalid Base 64 character), it is set to 1.

 

Note: For every 4 characters in the string-argument, the BASE256 function returns 3 characters.

 

Numeric functions

 

ABS

 

The ABS function returns the absolute value of a numeric-argument. The syntax is:

 

ABS(numeric-argument)

 

FPT

 

The FPT function returns the fractional portion of a numeric-argument. The syntax is:

 

FPT(numeric-argument)

 

INT

 

The INT function returns the integer portion of a numeric-argument. . The syntax is:

 

INT(numeric-argument)

 

SQRT

 

The SQRT function returns the square root of a numeric-argument. The syntax is:

 

SQRT(numeric-argument)

 

SGN

 

The SGN function returns the sign (positive, negative or zero) of a numeric value according to the following chart:

 

Numeric-argument    Value returned
Positive                        1
Zero                             0
Negative                       1-
 
The syntax is:
 
SGN(numeric-argument)
 
RND
 

The RND function returns a pseudo-random value less than 1 but greater than or equal to 0. The returned value has a length/precision of 8.8 (i.e., all 8 digits are to the right of the decimal point).

 

RND(0) generates a pseudo-random number, while using a non-zero argument, such as RND(1), randomized the value returned by this function.

 

The syntax is:

 

RND(numeric-argument)

 

Conversion functions

 

IB supports several functions that convert data from one form to another.

 

STR

 

The STR function converts a numeric argument to a string value. The syntax is:

 

STR(numeric-argument)

 

For non-expressions, the length of the result is the length of the numeric-argument plus 1 character to account for the sign of an integer, or plus 2 characters to account for the sign and decimal point of a real number.

 

For expressions, the STR function returns 18 characters for a real number (16 digits plus a decimal point and sign) or 17 characters (16 digits plus a sign for an integer). The “precision” in the resulting string is determined by the most precise element in the expression.

 

The STR function provides a sign character at the right-hand side of the converted value. If the numeric-argument contains fractional digits, the STR function inserts a decimal point in the correct location.

 

NUM

 

The NUM function converts a string-argument into its equivalent numeric value, only if the contents of the string-argument are numeric characters. The syntax is:

 

NUM(string-argument,numeric-error-argument)

 

The numeric-error-argument is a numeric variable or numeric array element with a length and precision of at least 1.0 If the NUM function successfully converts the string-argument, the numeric-error-argument is set to 0. If the conversion is unsuccessful, it is set to 1.

 

ASC

 

The ASC function returns the decimal value of the first byte of the string-argument using the 8-bit ASCII code. The syntax is:

 

ASC(string-argument)

 

CHR

 

The CHR function returns a single-byte ASCII character corresponding to the 8-bit binary number equivalent of the numeric-argument. The syntax is:

 

CHR(numeric-argument)

 

The numeric-argument is a decimal value between 0 and 255, inclusive. Only the absolute integer portion of the numeric argument is used for the conversion; the sign and fractional digits (if any) of the numeric argument are ignored.

 

BINARY

 

The BINARY function returns 8 bytes for each character in the string-argument. The returned bytes represent the 8 bits in each character of the string-argument. If the bit is “on,” the corresponding byte will be “1.” If the bit is “off,” the corresponding byte will be “0.” The syntax is:

 

BINARY(string-argument)

 

For example:

 

      A$ = "COOL"

      B$ = BINARY(A$)

 

B$ is the binary equivalent of “COOL” – which is:

 

01000011010011110100111101001100

 

ASCHEX

 

The ASCHEX function converts an ASCII hex string to its equivalent ASCII value. The syntax is:

 

ASCHEX(string-argument, numeric-error-argument)

 

The string-argument represents the string to be converted. Each two bytes of this string-argument must represent one ASCII character (this function provides the conversion to ASCII). The string-argument may be a string constant, a single-element string variable, a string array element, a string expression, or a string function.

 

The numeric-error-argument reports the success or failure of the conversion. It is set to 1 if there is a conversion error; otherwise, it is set to 0. The numeric-error-argument must be a single-element numeric variable or a numeric array element.

 

If there is a conversion error (i.e., if the string-argument contains non-hex characters), the ASCHEX function returns a null result.

 

HEXASC

 

The HEXASC function converts an ASCII hex string to its ASCII hex equivalent, character for character. The syntax is:

 

HEXASC(string-argument)

 

The string-argument represents the string to be converted. The string-argument may be a string constant, a single-element string variable, a string array element, a string expression, or a string function.

 

The result of the HEXASC function contains twice as many characters as the string-argument (because each byte of the string-argument will be represented by 2 bytes in ASCII).

 

DECHEX

 

The DECHEX function converts a decimal number to its hexadecimal string equivalent. The syntax is:

 

DECHEX(numeric-argument, numeric-error-argument)

 

The numeric-argument represents the value to be converted. It may be a constant or variable. The value of the numeric-argument may not exceed 65,535 (i.e., hex "@FFFF@"). The numeric-argument may be a numeric constant, a single-element numeric variable, a numeric array element, a numeric expression, or a numeric function.

 

The numeric-error-argument reports the success or failure of the conversion. It is set to 1 if there is a conversion error; otherwise, it is set to 0. The numeric-error-argument must be a single-element numeric variable or a numeric array element.

 

HEXDEC

 

The HEXDEC function converts a two-byte binary string to its decimal equivalent. The syntax is:

 

HEXDEC(string-argument)

 

The string-argument represents the two-byte binary string to be converted. The string-argument may be a string constant, a single-element string variable, a string array element, a string expression, or a string function.

 

The maximum possible value returned by the HEXDEC function is 65,535, the decimal equivalent of "@FFFF@" hex.

 

INTEL and INTELD

 

The INTEL function returns a 2-byte string in Intel (byte-reversed) format representing the hex equivalent of the decimal numeric-argument. The syntax is:

 

INTEL(numeric-argument)

 

The INTELD function works just like the INTEL function except that it returns a double-word (4-byte) string. The syntax is:

 

INTELD(numeric-argument)

 

The INTEL and INTELD functions were implemented in support of the IB Windows Driver Library. Both functions can be used in data section of the program (with a constant numeric argument) and in the code section of the program (with a constant or variable numeric argument).

 

Date functions

 

DATETONUM

DATE2NUM

NUMTODATE

NUM2DATE

 

Status functions

 

STS

PSTAT

DSTAT

FSTAT

 

Special purpose functions

 

CHKSUM

MID