SCORE (System CORE) has two main functions. The first and perhaps most important is to smooth over the differences between different C implementations and define the parameters which drive most of the conditional compilations in the rest of PACT. Secondly, it contains several groups of functionality that are used extensively throughout PACT.
Although C is highly standardized now, that has not always been the case. Roughly speaking C compilers fall into three categories: ANSI standard; derivative of the Portable C Compiler (Kernighan and Ritchie); and the rest. PACT has been successfully ported to many ANSI and PCC systems. It has never been successfully ported to a system in the last category. The reason is mainly that the standard C library supplied with such implementations is so far from true ANSI or PCC standard that PACT would have to include its own version of the standard C library in order to work at all.
Even with standardized compilers life is not dead simple. The ANSI standard leaves several crucial points ambiguous as implementation defined. Under these conditions one can find significant differences in going from one ANSI standard compiler to another.
SCOREs job is to include the requisite standard headers and ensure that certain key standard library functions exist and function correctly (there are bugs in the standard library functions supplied with some compilers) so that, to applications which include the SCORE header(s) and load with SCORE, all C implementations look the same. This is a tall order, but in practice once SCORE has been successfully compiled only the areas of graphics, IPC, and binary data handling require special handling! This has more of an impact on some programmers than on others. Those who prefer to specify only the exact headers to be included in each source file will find SCORE and PACT unusual. At the expense of a slight increase in compile time, the most commonly used headers are always included. This is crucial to getting the C implementation independence.
Typically, the SCORE header scstd.h includes the following:
ANSI stdlib.h stddef.h stdarg.h float.h
PCC sys/types.h varargs.h malloc.h
Both limits.h stdio.h string.h math.h ctype.h signal.h setjmp.h time.h
The single header, scstd.h, smooths over most of the generic problems that arise because of implementation defined behavior in the host C implementation. The remainder of the PACT sources ultimately include scstd.h. This strategy has been extremely successful for PACT and applications which use PACT.
There are basically three other areas which SCORE functions address: memory management; hash table management; and extended string handling.
2.0 SCORE Constants
HSZSMALL = 31
- small table size
HSZSMINT = 67
- small intermediate table size
HSZLRINT = 127
- large intermediate table size
HSZLARGE = 521
- large table size
DOC = 1
- documentation
NODOC = 0
- no documentation
MAX_LEX_BUFFER = 4096
- default size of lexical token buffer
SC_WSPC_TOK = 0
- whitespace token
SC_DELIM_TOK = 1
- delimiter token
SC_IDENT_TOK = 2
- identifier token
SC_DINT_TOK = 3
- decimal integer number token
SC_REAL_TOK = 4
- decimal floating point number token
SC_OINT_TOK = 5
- octal integer number token
SC_HINT_TOK = 6
- hexidecimal integer number token
SC_OPER_TOK = 7
- operator token
SC_STRING_TOK = 8
- string token
SC_KEY_TOK = 9
- keyword token
SC_PRED_TOK = 10
- predicate token
SC_CMMNT_TOK = 11
- comment token
SC_HOLLERTOK = 1000
- hollerith string token
REAL = double | float
- THINK C | otherwise
HUGE_REAL = 1.0e30 | 1.0e100
- THINK C | otherwise
ERRDEV = stderr
- device to dump diagnostic messages to
ABORT = 3
- error return flag for longjmps
ERR_FREE = 2
- error free return flag for longjmps
CODE =
- name of program using the package
VERSION =
- version designation of CODE2.0.1
scstd.h
BINARY_MODE_R = rb
BINARY_MODE_W = wb
BINARY_MODE_RPLUS = r+b
BINARY_MODE_WPLUS = w+b
TRUE = 1
FALSE = 0
ON = 1
OFF = 0
FIXNUM = long
- if not already defined
SMALL = 1.0e-100
HUGE = 1.0e100
HUGE_INT = LONG_MAX | (1 << (sizeof(long)-1)) - 1
- if defined | otherwise
RAND_MAX = 32767.0 | 2147483647.0
- if not already defined
MAXLINE = 200
- if not already defined
SC_BITS_BYTE = 8
- bits per byte
SC_CHAR_I = A
SC_SHORT_I = B
SC_INTEGER_I = C
SC_LONG_I = D
SC_FLOAT_I = E
SC_DOUBLE_I = F
SC_STRING_I = G
SC_POINTER_I = H
SEEK_SET = 0
- fseek sets file position relative to beginning
SEEK_CUR = 1
- fseek sets file position relative to current position
SEEK_END = 2
- fseek sets file position relative to end
This function looks up the given name in the specified hash table and returns an object associated with the name if one was previously installed with
TICKS_SECOND = 1000000 | CLOCKS_PER_SEC
| 100*ZQHERTZ | CLK_TCK
directory_delim = / | \\ | :
directory_delim_c = / | \\ | :
3.0 The SCORE API
This section of the manual details the SCORE functions intended for use by C application programs. Functions here are presented in alphabetical order and are given with full ANSI C prototypes.3.1
Hash Table Handling
These routines allow applications to manage multiple heterogeneous open hash tables. They form a generalized version of the hashing routines described in Kernighan and Ritchies The C Programming Language. They are most conveniently used by a call by value language such as C.
F77 Binding: void *schlkp(integer nc, char *name, integer tab)
SX Binding:
An ASCII string, name, and a HASHTAB *, tab are the arguments to this function.
This routine clears out a hash table for possible reuse. It frees the memory allocated to the
F77 Binding: integer schclr(integer tab)
SX Binding:
The only argument is the HASHTAB *, tab to be cleared.
This function returns an array of the names installed in the given hash table. In this way the contents of a hash table may be checked at runtime. The names are alphabetically sorted according the C library function
F77 Binding:
SX Binding:
The arguments are the HASHTAB *, tab to be listed or dumped and an ASCII string, pattern.
This function removes the item specified by name from the indicated hash table.
This function installs an object, obj, with type in the specified hashtable under the identifier, name. The procedure is an adaptation of the function described in Kernighan and Ritchie in The C Programming Language. It allows an application program to have multiple hash tables simultaneously. Furthermore by including a type with the installation of an object, applications can install different types of objects in a single table and distinguish between types so that they may be handled appropriately. The type is in no way used by the hash package. It is solely for the use of the application.
F77 Binding: integer schrem(integer nc, char *name, integer tab)
SX Binding:
F77 Binding: integer schins(integer nc, char *name, obj, integer nt, char *type,
integer cp, integer tab)
SX Binding:
In the FORTRAN binding, the argument cp is a flag requesting that the installed object is a copy of the argument pointed to by obj. In that case, schins will allocate one item of type type and copy one such item from obj into the new space. The new space will be installed in the hash table.
This function looks up the given name in the given hash table and returns an
F77 Binding:
SX Binding:
An ASCII string, name, and a HASHTAB *, tab are the arguments to this function.
This is the function which creates new hash tables. The size of a hash table should be a prime number for greatest efficiency. For C based applications, there are four #defined sizes in the header,
F77 Binding: integer scmkht(integer size, integer docflag)
SX Binding:
Applications can have documentation with the installed objects, and for efficiency in searching a hash table for documentation a flag is provided in the hash table structure telling whether or not the objects which are installed have documentation. The predefined flags in C applications are DOC and NODOC (1 and 0 respectively).
Two integers, size and docflag, are the input to SC_make_hash_table.
The return value is a HASHTAB * if successful and a null pointer (NULL) otherwise.
F77 Binding: integer scrlht(integer tab)
SX Binding:
hash table by SC_make_hash_table. Call SC_hash_clr first to release the space associated with hash elements.
3.2
Lexical Stream Handling
The following routines assist code developers with integrating automatically generated lexical scanners into their applications and controlling them. The SC_lexical_stream structure encapsulates the lexical scanner, the I/O stream, and various buffers so that applications can apply arbitrarily many lexical scanners to any number of input streams. The SC_lexical_token describes a lexical token for parsers and other applications.
This function closes the given lexical stream. Closing the lexical stream means closing the I/O stream if it is not stdin and releasing the buffer spaces as well as the SC_lexical_stream itself.
F77 Binding: integer scclls(integer strid)
SX Binding:
This function has no return value.
This function permits applications to view an input stream as a sequence of tokens returned by the lexical scanner bound in an
F77 Binding:
SX Binding:
The argument to this function is: str, a pointer to a SC_lexical_stream.
A pointer to an SC_lexical_token is returned or NULL if the end of the input stream has been reached.
SEE ALSO: SC_open_lexical_stream, SC_close_lexical_stream, SC_scan.
This function initializes a new lexical stream and returns a pointer to it. A lexical stream consists of: an input buffer; a string buffer for tokens; an output buffer for text not handled by the lexical scanner; an SC_lexical_token buffer; a lexical scanning function produced by a tool such as
F77 Binding: integer scopls(integer nchr, char *name, integer inbs, integer strbs,
integer function scan)
SX Binding:
The main attempt here is to encapsulate the functions and data structures necessary to support an application in the use of multiple independent lexical scanners. Such capability can be used in conjunction with parsers or other applications where some sort of input language must be broken down into proper sized pieces.
In the C binding, this function returns a non-NULL pointer to a newly allocated SC_lexical_stream if successful and NULL if not. In the FORTRAN binding, this function returns a non-negative integer identifier for the lexical stream if successful and -1 otherwise.
SEE ALSO: SC_close_lexical_stream, SC_scan, SC_get_next_lexical_token.
This function reads a line from the specified lexical streams input stream into its input buffer.
This function scans the current input buffer in the specified lexical stream and returns arrays of tokens.
F77 Binding: integer scrdls(integer strid, integer nc, char *s)
SX Binding:
F77 Binding: integer scscan(integer strid, integer mxtok, integer width, char *tok,
integer ntok, integer nctok, integer ixtok, integer toktyp,
REAL tokval)
SX Binding:
The string to be scanned is contained in the lexical stream. A call to scrdls can be made to read a new line of text from the input stream into the input buffer, otherwise the current contents of the input buffer will be scanned.
The default scanner, f77lxr, defines the following token types:
TYPE NAME EXAMPLE
1
DELIMITER & ( ) , : < = > _ |
2
ALPHANUM abc
3
INTEGER 10
4
REAL 1.2 6.0e10
5
OCTAL 17b
6
HEX #17
7
OPERAND .and.
8
STRING foo
1000
HOLLERITH 3hFOO
Invoke the lexical scanner to traverse the current input buffer and identify the lexical tokens as defined by the lexical rules which generated the scanner. These are placed in a buffer of SC_lexical_tokens.
If the rd argument it TRUE an new line is read from the input stream into the input buffer before it is scanned.
This routine changes the value associated with name on the specified association list. If there is no value associated with the name key then the value is added to the list under the name. Because of this property is is permissible to pass a NULL association list into this function. In this way association list can be built up without explicitly creating them. It also means that the return list may not have the same address as the input list and consequently the return list must be used in all future calls to these routines.
3.3
Association List Handling
Association lists are similar to hash tables in that they associate a key (in this case an ASCII string) with a value. They differ from hash tables in that the elements are chained together in a linked list instead of being organized in a hashed table. The principle advantage of association lists is lower memory overhead. The disadvantage is the relative inefficiency of checking each key until a match is found. The application developer must decide.
F77 Binding: integer scchal(integer al, integer nn, char *pname, integer nt, char
*ptype, integer nv, val)
SX Binding:
Removes the named element from the association list, al. Because the specified element may be the first on the list, the modified list is returned and must be used in all future calls to these functions!
Free the specified association list, al. The level argument refers to how much information is to be released. If level is 1 the only the name key is released; if level is 2 only the value is released; and if level is 3 both are released.
This routine returns a copy of the given association list if successful.
This routine copies the contents of association list al2 to association list al1. As always a NULL list for al1 or al2 is acceptable. The modified assocation list al1 is returned if successful.
F77 Binding: integer scrmal(integer al, integer nn, char *name)
SX Binding:
F77 Binding: integer scrlal(integer al, integer level)
SX Binding:
F77 Binding: integer sccpal(integer al)
SX Binding:
F77 Binding:
SX Binding:
3.4
String Handling
3.4.1
Predicates
The functions test strings for specific properties and return TRUE or FALSE depending on the outcome.
Return TRUE iff the string is a valid representation of a a number.
Return TRUE iff the string is a valid representation of an integer in the specified base.
Return TRUE iff the string is a valid representation of a floating point number.
Return TRUE iff the string contain printable characters only.
Return TRUE iff string1 is blank or a comment. A comment begins with a character in string2 followed by a blank, tab, or end of line.
3.4.2
Pattern Matching
These functions do certain patterm matching operations.
Find the first occurrence of string2 in string1.
Find the first case insensitive occurrence of string2 in string1.
Replace all non-overlapping occurrences of patto in string s with pattn.
Match string s against regular expression patt. * matches any number of characters. ? matches any single character.
3.4.3
String Sorting
These functions are involved in sorting operations on strings.
Sort an array of character pointers by what they point to. The arguments are: s, an array of pointers to ASCII strings, and number, the number of strings.
3.4.4
String Operations Involving Case
These functions are used in connection with the case of the characters in strings.
Compare two strings ignoring case.
Convert a string to all uppercase.
Convert a string to all lowercase.
3.4.5
Tokenizers
These functions supplement the string tokenizing capability of the standard C library.
Find the first token in a string.
Find the first token or quoted token string in a string.
Find the last token in a string.
3.4.6
Other String Operations
These additional string operations do not fitt into any of the above categories.
Reverse a string in place.
Count the occurrences of a specified character in a string.
Replace contiguous blanks in a stirng with a single blank and remove leading and trailing blanks.
Return the combined user and system processor time in seconds and microseconds consumed since the first call to SC_cpu_time. Most systems limit actual time resolution to 0.01 seconds to reduce overhead.
Return the wall clock time in seconds and microseconds since the first call to SC_wall_clock_time. Most systems limit actual time resolution to 0.01 seconds to reduce overhead.
Get the time and date. This is a guaranteed to work version of the standard C library function ctime.
3.5
Time and Date Handling
The SCORE routines dealing with time and date are provided mainly for true portability and standardization.
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
3.6
Memory Management
Given a pointer to space allocated with SC_alloc or
F77 Binding: integer scalen(pointer ptr)
SX Binding:
The number of bytes pointed to by ptr is returned if successful, and -1 if not.
Allocate a new space in memory nitems x bytepitem long and return a pointer to it. The arguments are: nitems, the number of items (e.g. floats); and bytepitem, the number of bytes per item.
F77 Binding: use scmake
SX Binding: memory management is automatic
Release the space pointed to by ptr. Returns TRUE if successful, FALSE otherwise.
Return the number of
F77 Binding: use scfree
SX Binding: memory management is automatic
F77 Binding: integer scmemt(void)
SX Binding:
Return -1 if the forward and backward counts differ, -2 if a NULL pointer occurs in the chain, -3 if the link count exceeds the number of blocks; otherwise return the number of chunks of memory being managed.
Reallocate the space in memory associated with ptr so that it is nitems x bytepitem long and return a pointer to it. Copy the contents of the old space into the new space if necessary, but preserve the original contents pointed to. Ptr must be a pointer to a space previously allocated by
F77 Binding: use screma
SX Binding: memory management is automatic
Returns a non-NULL pointer to a newly allocated space if successful and NULL if not. The pointer should be cast to the appropriate type in C.
Allocate a new space in memory large enough to contain the char array s, copy its contents to the new space, and return a pointer to it. S must be a null terminated array of characters.
Allocate a new space in memory the size of type and return a pointer to it which has been
F77 Binding:
SX Binding:
F77 Binding: use scmake
SX Binding: memory management is automatic
Returns a non-NULL pointer to a newly allocated space if successful and NULL if not.
Allocate a new space in memory for ni items the size of type (C) or bpi bytes each (FORTRAN) and return a pointer to it. In the C binding, which is a macro, type is a primitive or derived type specifier, and the return value is a pointer cast to type *. In the FORTRAN binding, which is intended for use in FORTRAN implementations which support the pointer extension, ptr is a pointer (e.g. ipa of pointer (ipa, a)).
Reallocate the space in memory associated with ptr to the size of type and return a pointer to it, which has been
F77 Binding: integer scmake(pointer ptr, integer ni, integer bpi)
SX Binding: memory management is automatic
F77 Binding: use screma
SX Binding: memory management is automatic
Returns a non-NULL pointer to a reallocated space if successful and NULL if not.
Reallocate the space in memory associated with ptr to be ni items the size of type (C) or bpi bytes each (FORTRAN) and return a pointer to it. Copy the contents of the old space into the new space if necessary. In the C binding, which is a macro, type is a primitive or derived type specifier, and the returned pointer is cast to type *. The FORTRAN binding is intended for use in FORTRAN implementations which support the pointer extension.
Release the space pointed to by ptr. The FORTRAN binding is intended for use in FORTRAN implementations which support the pointer extension and always returns 1.
If flag is non-zero, memory will be zeroed out when allocated and when released. The latter is useful (in spite of the overhead) in order to spot the situation where space is freed when more than one pointer points to it. The default is for space to be zeroed out.
F77 Binding: integer screma(pointer ptr, integer ni, integer bpi)
SX Binding: memory management is automatic
F77 Binding: integer scfree(pointer ptr)
SX Binding: memory management is automatic
F77 Binding: integer sczrsp(integer flag)
SX Binding: not applicable
3.7 Miscellaneous Routines
3.7.1
Bit Level Manipulations
F77 Binding:
SX Binding:
number of set bits in the specified number of bytes of a given long.
F77 Binding:
SX Binding:
bits of a given unsigned int.
Convert a string to an int. Return 0 if the string is null.
Convert a string to a long and return a pointer to any unconverted suffix. This 3.7.2
Numeric Conversion
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
macro invokes either the standard C library function atof or the guaranteed to work SCORE equivalent.
Convert a string to a double. Return 0.0 if the string is null.
Convert a string to a double and return a pointer to any unconverted suffix. This
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
Return the absolute value of a double.
Return the greater of the two arguments.
Return the lesser of the two arguments.
Is the string the name of an existing file?
Is the string the name of an existing ascii file?
3.7.3
Other Numeric
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
3.7.4
File Search
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
F77 Binding:
SX Binding:
directories for a file and return the full path name if the file exists.
3.7.5
I/O
3.7.6
Interrupts
F77 Binding:
SX Binding:
interrupt handler, top level longjump, and output buffering for an application.
F77 Binding:
SX Binding:
interrupts in a default sort of way.
3.7.7
Other
F77 Binding:
SX Binding:
banner on stdout.
F77 Binding: integer scpaus(void)
SX Binding:
stdin.
4.0
Examples
This section will illustrate the use of the SCORE functions.5.0
Related Documentation
SCORE is one part of a collection of libraries called PACT. It provides the foundation for PACT. Its functionality includes memory management, hash table functions, and string handling support.
The list of PACT Documents is:
PACT Users Guide, UCRL-MA-112087
SCORE Users Manual, UCRL-MA-108976 Rev.1 (this document)
PPC Users Manual UCRL-MA-108964 Rev.1
PML Users Manual, UCRL-MA-108965 Rev.1
PDBLib Users Manual, M-270 Rev.2
PGS Users Manual, UCRL-MA-108966 Rev.1
PANACEA Users Manual, M-276 Rev.2
ULTRA II Users Manual, UCRL-MA-108967 Rev.1
PDBDiff Users Manual, UCRL-MA-108975 Rev.1
PDBView Users Manual, UCRL-MA-108968 Rev.1
SX Users Manual, UCRL-MA-112315