PREVIOUS

Appendix A. KeyKOS Library Functions

This chapter contains descriptions of additional C library functions provided by Key Logic. The format of these descriptions follows the general "man page" style used in UNIX programmer's manual reference guides. The object code for these functions is in KKOSCLIB TXTLIB in CMS and in USER.SYS.KKOSCLIB. in KeyKOS.

KeyKOS Library Functions by Type

Data Conversion

b2dbl
Convert binary character array to double
b2int
Convert binary character array to int
b2long
Convert binary character array to long
dbl2b
Convert double to binary character array
int2b
Convert int to binary character array
long2b
Convert long to binary character array

Long Long Integers

b2lli
Convert binary character array to LLI
lli2b
Convert LLI to binary character array
lliadd
Add LLIs
llicmp
Compare LLIs
llidiv
Divide LLI
llilsl
Shift LLI left
llilsr
Shift LLI right
llisub
Subtract LLIs
llitimes
Multiply to produce LLI

Varying-length strings

bs2dbl
Convert STRING to double
bs2int
Convert STRING to int
c2s
Convert C string to a STRING
dbl2bs
Convert double to STRING
int2bs
Convert int to STRING
lsubstr
Replace substring of STRING (see substr)
s2c
Convert STRING to C string
selemnt
Get a STRING character
sindex
Search a STRING
srindex
Search a STRING (see sindex)
sstrapc
Append character to STRING
sstrcat
Concatenate STRINGs
sstrcmp
Compare STRINGs
sstrcpy
Copy a STRING
sstrcspn
Character span in STRING
sstrlen
STRING length
sstrmax
STRING length
sstrncmp
Compare STRINGs (see sstrcmp)
sstrpbrk
Character break in STRING
sstrpos
Search STRING for character
sstrrpos
Search STRING for character (see sstrpos)
sstrspn
Character span in STRING (see sstrcspn)
sstrtok
Find token in STRING
substr
Get substring of STRING
szero
Make null STRING

Tracing

dotrace
Enable debug trace
notrace
Disable debug trace
trace
Debug trace
_trace
Debug trace (see trace)

NAME

b2dbl - Binary char array to double

SYNOPSIS

#include "cvt.h"

double b2dbl( char *str, int len )

DESCRIPTION

Returns len bytes of char array str as a double.

EXAMPLE

dbl = b2dbl(str, len);

NAME

b2int - Binary char array to integer

SYNOPSIS

#include "cvt.h"

int b2int( char* str, int len )

DESCRIPTION

Returns len bytes of char array str as an integer. The most significant bytes are first. To ensure portability, len should be less than or equal to 2.

NAME

b2lli - Binary char array to long long integer

SYNOPSIS

#include "lli.h"

void b2lli( char * str, int len, LLI * value )

DESCRIPTION

Converts len bytes of char array str to a long long integer and places the result in *value. The most significant bytes are first. To ensure portability, len should be less than or equal to 8.

NAME

b2long - Binary char array to long integer

SYNOPSIS

#include "cvt.h"

long b2long( char *str, int len )

DESCRIPTION

Returns len bytes of char array str as a long integer. The most significant bytes are first. To ensure portability, len should be less than or equal to 4.

NAME

bs2dbl - Binary STRING to double

SYNOPSIS

#include "sstring.h"

double bs2dbl( STRING str, int len )

DESCRIPTION

Returns len bytes of STRING str as a double.

EXAMPLE

dbl = bs2dbl(str, len);

NAME

bs2int - Binary string to integer

SYNOPSIS

#include "sstring.h"

int bs2int( STRING str, int len )

DESCRIPTION

Returns len bytes of STRING str as an integer.

NAME

c2s - Convert a C string to a STRING

SYNOPSIS

#include "sstring.h"

void c2s( char *charstr, STRING str )

DESCRIPTION

c2s copies charstr to a STRING str. Truncation might occur if str.maxlen is less than the length of charstr.

NAME

dbl2b - Store a double in a char array in binary format (S equivalent )

SYNOPSIS

#include "cvt.h"

char *dbl2b( double dbl, char *str, int len )

DESCRIPTION

dbl2b stores dbl in the char array str. The length of str is taken as the minimum of len and 8. Returns the original str string if len < 0. Truncation might occur if len < 8.

dbl2b returns str.

EXAMPLE

dbl2b(dbl, str, len);
KC(anykey,oc) CHARFROM(dbl2b(dbl, str, len), len);

NAME

dbl2bs - Store a double in a STRING in binary format (S equivalent )

SYNOPSIS

#include "sstring.h"

STRING dbl2bs( double dbl, STRING str, int len )

DESCRIPTION

dbl2bs stores dbl in the STRING str. The length of str is taken as the minimum of len, str.maxlen and 8. Returns the unmodified STRING str if len < 0. Truncation might occur if len < 8.

dbl2bs returns str.

EXAMPLE

dbl2bs(dbl, str, len); KC(anykey,oc) STRINGFROM(dbl2bs(dbl, str, len));

NAME

dotrace - Enable debug trace to the specified output KEY

SYNOPSIS

#include "cdebug.h"

int dotrace( int flags, )

DESCRIPTION

dotrace() sets the value of the global variable _traceon (defined in cdebug.h). The value for flags is obtained by a bit-wise "or" of the definitions found in the include file "cdebug.h".

The options are as follows:

SYSPWRITE
enable trace to a terminal

RCOLWRITE
enable trace to an entry-sequenced record collection.

The function returns _traceon value.

EXAMPLE

dotrace(SYSPWRITE | RCOLWRITE); /* write debug trace to a terminal and record collection */

NAME

int2b - Store an int into a char array in binary format

SYNOPSIS

#include "cvt.h"

char *int2b( int i, char *str, int len )

DESCRIPTION

int2b stores i in len characters of the char array str, most significant byte first. len should be less than or equal to 8. str is unchanged if len <= 0. The value is truncated if it does not fit by discarding the high-order bits.

int2b returns str.

NAME

int2bs - Store an int in a STRING in binary format (S equivalent )

SYNOPSIS

#include "sstring.h"

STRING int2bs( int i, STRING str, int len )

DESCRIPTION

int2bs stores i in the STRING str. The length of str is taken as the minimum of len, str.maxlen and 8. Returns the unmodified STRING str if len < 0. Truncation might occur if len < 4 by discarding the high-order bits.

int2bs returns str.

NAME

lli2b - Store a long long integer into a char array in binary format

SYNOPSIS

#include "lli.h"

char *lli2b( char *str, int len )

DESCRIPTION

Stores *i in len characters of the char array str, most significant byte first. len should be less than or equal to 8. str is unchanged if len <= 0. The value is truncated if it does not fit by discarding the high-order bits. Note that LLIs are unsigned.

lli2b returns str.

NAME

lliadd - Add two long long integers

SYNOPSIS

#include "lli.h"

void lliadd( LLI *a, LLI *b )

DESCRIPTION

Adds *b to *a placing the result in *a.

NAME

llicmp - Compare two long long integers

SYNOPSIS

#include "lli.h"

int llicmp( LLI *a, LLI *b )

DESCRIPTION

Returns -1 if *a < *b, 0 if *a == *b, or +1 if *a > *b.

NAME

llidiv - Divide a long long integer

SYNOPSIS

#include "lli.h"

int llidiv( LLI *dividend, unsigned long divisor, unsigned long *quotient, unsigned long *remainder )

DESCRIPTION

Divides *dividend by divisor, setting *quotient and *remainder. Returns 1 if overflow or division by zero, otherwise 0.

Implementation note: Currently, the dividend must be < 2^63 and the divisor must be < 2^31 (otherwise the division is signed). The effect is unpredictable if there is overflow or division by zero.

NAME

llilsl - Shift a long long integer left

SYNOPSIS

#include "lli.h"

void llilsl( LLI *a, unsigned int b )

DESCRIPTION

Performs a logical shift left on *a of b bits.

NAME

llilsr - Shift a long long integer right

SYNOPSIS

#include "lli.h"

void llilsr( LLI *a, unsigned int b )

DESCRIPTION

Performs a logical shift right on *a of b bits.

NAME

llisub - Subtract two long long integers

SYNOPSIS

#include "lli.h"

void llisub( LLI *a, LLI *b )

DESCRIPTION

Subtracts *b from *a, placing the result in *a.

NAME

llitimes - Multiply, producing a long long integer

SYNOPSIS

#include "lli.h"

void llitimes( unsigned long term1, unsigned long term2, LLI *product )

DESCRIPTION

Multiplies the two terms and stores the result in *product.

NAME

long2b - Store an long int into a char array in binary format

SYNOPSIS

#include "cvt.h"

char *long2b( long i, char *str, int len )

DESCRIPTION

Stores i in len characters of the char array str, most significant byte first. len should be less than or equal to 8. str is unchanged if len <= 0. The value is truncated if it does not fit by discarding the high-order bits.

long2b returns str.

NAME

notrace - Disable debug trace from the specified output KEY

SYNOPSIS

#include "cdebug.h"

int notrace( int flags )

DESCRIPTION

notrace() resets the value of the global variable _traceon (defined in cdebug.h). The value for flags is obtained by a bit-wise "or" of the definitions found in the include file "cdebug.h".

The options are as follows:

SYSPWRITE
disable trace to a terminal
RCOLWRITE
disable trace to an entry-sequenced record collection.
The function returns _traceon value.

EXAMPLE

notrace(SYSPWRITE); /* disable debug trace from a terminal */

NAME

s2c - Convert a STRING to a C string

SYNOPSIS

#include "sstring.h"

void s2c( STRING str; char *charstr )

DESCRIPTION

s2c copies the STRING str to the C string charstr. A '\0' will be placed at the end of charstr.

NAME

selemnt - Get a STRING character

SYNOPSIS

#include "sstring.h"

char *selemnt( STRING str, int pos )

DESCRIPTION

selemnt returns a pointer to a character of the STRING str. pos specifies the number of the character to be returned (pos = 0 specifies the first element of the string).

The function returns NULL if pos does not point to an element of the STRING str.

EXAMPLE

STRING name(20) = "KeyKOS";
char *c;
c = selemnt(name,2);  /* c points to 'y' in the STRING name */

NAME

sindex, srindex - Character search in STRING

SYNOPSIS

#include "sstring.h"

char *sindex( STRING str, char chr )

char *srindex( STRING str, char chr )

DESCRIPTION

sindex returns a pointer to the first occurrence of the character chr in the STRING str. srindex returns a pointer to the last occurrence of chr. NULL is returned if the search fails in either function.

EXAMPLE

STRING name(20) = "KeyKOS";
char *c, c1, c2 = 'K';
c1 = *sindex(name, c2);
c = srindex(name, c2);

NAME

sstrapc - Append a character to a STRING

SYNOPSIS

#include "sstring.h"

sstrapc( STRING dst, char c )

DESCRIPTION

sstrapc appends a character to the end of the STRING dst if there is a space available. No action is taken if the values of actual and maximum length of the STRING are the same.

NAME

sstrcat - STRING concatenation

SYNOPSIS

#include "sstring.h"

STRING sstrcat( STRING dst, STRING src )

DESCRIPTION

sstrcat copies the STRING src to the end of the STRING dst. Truncation occurs if src.actlen > available space in dst. sstrcat returns dst.

EXAMPLE

STRING name(20) = "KeyKOS";
STRING s(20) = "new name";
STRING s1(20);
sstrcat(s, name);
s1 = sstrcat(s, name);

NAME

sstrcmp, sstrncmp - STRING compare

SYNOPSIS

#include "sstring.h"

int sstrcmp( STRING s, STRING t )

int sstrncmp( STRING s, STRING t, int max )

DESCRIPTION

sstrcmp compares the STRINGs s and t. If the actual lengths of the strings are not the same, -1 is returned. A negative value is returned if s < t, a zero if s == t, and a positive value if s > t.

The routine sstrncmp is similar to sstrcmp, except that at most max characters are compared.

If the actual length of the STRING s or the STRING t is less then max, then the number of characters compared is taken as the minimum of s.actlen , t.actlen, and max.

NAME

sstrcpy - STRING copy

SYNOPSIS

#include "sstring.h"

STRING sstrcpy( STRING dst, STRING src )

DESCRIPTION

sstrcpy copies the STRING src to the beginning of the STRING dst. The number of bytes copied from src to dst is taken as the minimum of dst.maxlen and src.actlen.

sstrcpy returns dst.

EXAMPLE

STRING name(20) = "KeyKOS";
STRING s(20) = "new name";
sstrcpy(s, name);
s = sstrcpy(s, name);

NAME

sstrcspn, sstrspn - Character span in STRING

SYNOPSIS

#include "sstring.h"

int sstrcspn( STRING str, char *charset )

int sstrspn( STRING str, char *charset )

DESCRIPTION

sstrcspn searches characters in the STRING str until it finds one which is an element of charset, or encounters end of string. The function returns the number of elements which were skipped over. Another way of looking at it is that the function returns the subscript of the character in STRING str which matched a character in charset. If there are no characters common to both str and charset, sstrcspn returns the length of the STRING str.

sstrspn searches characters in the STRING str until it finds one which is not an element of charset, or encounters end of string. The function returns the number of elements which were skipped over. Another way of looking at it is that the function returns the subscript of the character in STRING str which did not match a character in charset. If all the characters of STRING str appear in charset, sstrcspn returns the length of the STRING str. This function is similar to the PL/I function verify.

NAME

sstrlen - STRING length

SYNOPSIS

#include "sstring.h"

int sstrlen( STRING str )

DESCRIPTION

sstrlen returns the actual length of the STRING str.

EXAMPLE

STRING name(20) = "KeyKOS";
len = sstrlen(str);

NAME

sstrmax - STRING length

SYNOPSIS

#include "sstring.h"

int sstrmax( STRING str )

DESCRIPTION

sstrmax returns the maximum length of the STRING str.

EXAMPLE

STRING name(20) = "KeyKOS";
len = sstrmax(str);

NAME

sstrpbrk - Character break in STRING

SYNOPSIS

#include "sstring.h"

char *sstrpbrk( STRING str, char *charset )

DESCRIPTION

sstrpbrk returns a pointer to the first character of the STRING str which is found in charset. If there are no characters common to the STRING str and charset, sstrpbrk returns a null pointer.

NAME

sstrpos, sstrrpos - Find position of character in STRING

SYNOPSIS

#include "sstring.h"

int sstrpos( STRING str, char chr )

int sstrrpos( STRING str, char chr )

DESCRIPTION

sstrpos returns the subscript in the STRING str of the first occurrence of chr. If the character is not found, then -1 is returned.

sstrrpos differs only in that the offset of the last occurrence of chr in the STRING str is returned.

NAME

sstrtok - Find token in STRING

SYNOPSIS

#include "sstring.h"

int sstrtok( STRING src, int offset, char *charset, STRING token )

DESCRIPTION

sstrtok returns the next token's length and copies the newly found token from src to token. A token is considered to be any string of characters delimited by the separator characters provided in charset.

In order to get a token starting from the beginning of the STRING src, offset needs to be equal to 0. The next token from the STRING src may be found by specifying a new value for offset. If src does not contain any characters from charset, then src will be copied into token. The number of characters copied is the minimum of the remaining bytes of src (actlen - offset), and token.maxlen.

Function returns the length of the token found.

EXAMPLE

STRING cc(40)  = "The name of the system is KeyKOS";
STRING token(30);
int len, i;

len = 1; i = 0;
while (len > 0) {
      len = sstrtok(cc, i, " ", token);
      i = i+len+1;
}
This will produce the following tokens: "The", "name", "of", "the", "system", "is", "KeyKOS".

NAME

substr, lsubstr - Get substring of STRING

SYNOPSIS

#include "sstring.h"

STRING *substr( STRING dst, STRING src, int pos, int len )

STRING *lsubstr( STRING dst, int pos, int len, STRING src )

DESCRIPTION

substr takes len bytes starting from the position pos of the STRING src and puts them into the STRING dst. dst.actlen is set equal to len.

lsubstr replaces len bytes of the STRING dst starting from the position pos by the corresponding number of bytes from the STRING src (starting from the beginning). No changes are made if src.actlen < len.

substr and lsubstr return a pointer to the STRING dst.

The STRING dst is not modified if pos or len is incorrectly specified.

NAME

szero - Make null STRING (set actlen of STRING to 0)

SYNOPSIS

#include "sstring.h"

void szero( STRING str )

DESCRIPTION

szero initializes the STRING str to a null string.

NAME

trace, _trace - Put a debug trace to a specified output KEY(s)

SYNOPSIS

#include "cdebug.h"

int trace( KEY termkey, KEY rcolkey, char *control, {p1, p2, p3, p4, p5, p6, p7, p8, p9, p10} )

int _trace( char *control, {p1, p2, p3, p4, p5, p6, p7, p8, p9, p10} )

DESCRIPTION

dotrace() must be called prior to use of trace() or _trace().

These routines are used to format various types of data. Data can either be written to a terminal, or to a record collection, or to both. In the case of a terminal, termkey must be a SOK key. In the case of a record collection, rcolkey must be an entry sequenced record collection key.

The string control is the format-control string (see printf() description). Up to ten parameters are allowed. The number and type of these parameters must correspond to the format specifiers of the string control; otherwise unpredictable results will occur.

The _trace() function is similar to trace(), except that it uses the global KEY variables _sysp and _rcol instead of parameters termkey, and rcolkey used by trace(). _sysp and _rcol must be declared as external KEYs and initialized prior to use.

The function returns either the number of bytes written to a specified KEY or -1, if the write operation failed.

EXAMPLE

int traceval;
KEY sysp = 11;
KEY rcol = 12;

traceval = dotrace(SYSPWRITE | RCOLWRITE);
trace(sysp, rcol, "Trace = %d\n", traceval);
The output "Trace = 3" will be written to a terminal and to a record collection.

int traceval;
extern KEY _sysp, _rcol;

_rcol = 12; _sysp = 13;
traceval = dotrace(RCOLWRITE);
_trace("Trace = %d\n", traceval);
The output "Trace = 3" will be written to a record collection.

NEXT