flibsci

FLIBSCI, the Fortran Library of Synergistic Consultants Incorporated

FLIBSCI is a library of subroutines, callable from Fortran, C and C++, which was written by John H. Letcher Professor of Computer Science of the University of Tulsa and President of Synergistic Consultants Incorporated.
FLIBSCI is a comprehensive and coordinated library of FORTRAN subroutines which enable a programmer to simply and efficiently construct a FORTRAN program without having to be concerned about machine-dependent features in input/output and number conversion operations. All the FLIBSCI subroutines are called in normal FORTRAN fashion. FLIBSCI is an acronym for FORTRAN LIBRARY by Synergistic Consultants Incorporated. A reasonable question at this point might be 'Why bother?'. The experienced programmer is undoubtedly aware that in spite of the ASA Standard for FORTRAN, there are still subtle differences (and some not so subtle) between compilers with respect to the handling of input/output chores. For example, there are many different methods used to check for an end-of-file following a READ operation. FLIBSCI, by reducing all FORTRAN I/O unit record operations to standard subroutine and function calls, greatly reduces the burden on the programmer. Another reason for using FLIBSCI is that FORTRAN, by design, is not well equipped for handling alphanumeric strings. (in addition, many FORTRAN compilers are not equipped to perform bit manipulation such as bit-by-bit logical operations or shifting operations.) FLIBSCI includes routines that efficiently and completely fill these gaps in the language. A shortcoming of many FORTRAN compilers is that most error handling is done by the object time library routines, and relatively insignificant errors can cause execution to abort in a most ungraceful fashion leaving the user with little explanation and much frustration. FLIBSCI, to a large extent, leaves error handling to the user program, by the means of error flags passed as subroutine parameters. Thus, an 'error' may be overlooked, or handled in some other suitable way, or cause termination, all at the programmer s discretion. Section 1 contains a list of the name and parameters for each of the routines of FLIBSCI. Ordinarily, this list would be found in the back of the report in an appendix. However, since it is hoped that this document will be frequently referenced, this summary is placed near the front, where it is hoped the user will find it easier to locate and use. Section 2 gives a detailed explanation and examples of the usage of each subroutine. This section begins with a list of terms and their definitions as used in this document. Section 3 contains a listing and discussion of each of the major labeled Common Blocks used by FLIBSCI routines. Section 4 describes the FLIBSCI validation program. Sections 5 and 6 describe additional specialized FLIBSCI routines. 1. List of Subroutine Names and Parameters In the following list, the name of each FLIBSCI subroutine and its formal parameters are given in the format of a FORTRAN Subroutine statement. In the parameter lists, underlining is used to indicate the usage of each variable according to the following convention: PARAM, A straight underline indicates that the value of the parameter is ----- supplied by the calling program and is never changed by the subroutine. PARAM, A wavy underline indicates that the value of the parameter is ~~~~~ supplied by the calling program, but may be changed by the subroutine. A constant should not be used in this case. PARAM, No underline indicates that the value of the parameter may be changed by the subroutine and no reference is made to its previous value. SUBROUTINE ACCEP(IBUF,NCHAR,NFIL,IECHO,MFIL,IEOF) ~~~~~ ---- ----- ---- SUBROUTINE CONVE(IBUF,NPOS,RVAR,NWID,NDEC) ---- ---- ---- ---- SUBROUTINE CONVF(IBUF,NPOS,RVAR,NWID,NDEC) ---- ---- ---- ---- SUBROUTINE CONVI(IBUF,NPOS,IVAR,NWID,IMODE) ---- ---- ---- ----- SUBROUTINE CONVN(KBUF,NPOS,JLTH,IVAR,RVAR,IERR) ---- ---- ---- SUBROUTINE DUMPZ(IVAR) ---- LOGICAL FUNCTION EQUAL(ISTR1,NPOS1,NCHAR1,ISTR2,NPOS2,NCHR2) ----- ----- ------ ----- ----- ----- LOGICAL FUNCTION EQUBL(IBUF,NPOS,NCHR) ---- ---- ----- SUBROUTINE ERROL SUBROUTINE ERROR(NWORD) ----- LOGICAL FUNCTION ESCAPE(IDUM) SUBROUTINE EXIT FUNCTION IBIT(IWORD,NBIT) ----- ----- SUBROUTINE JBIT(IWORD,NBIT) ~~~~~ ---- SUBROUTINE KBIT(IWORD,NBIT) ~~~~~ ---- FUNCTION KCHAR(IBUF,NPOS) ---- ---- SUBROUTINE JCHAR(IBUF,NPOS,JVAL) ~~~~ ---- ---- FUNCTION LAND(IVAL,JVAL) ---- ---- FUNCTION LNOT(IVAL) ---- FUNCTION LOCF(IVAR) ---- FUNCTION LOR(IVAL,JVAL) ---- ---- SUBROUTINE MOVE(IAFR,NCFR,JATO,NCTO,NCHR) ---- ---- ~~~~ ---- ---- SUBROUTINE MOVBL(IBUF,NPOS,NCHR) ---- ---- SUBROUTINE PAGE(NFIL) ---- SUBROUTINE PRINT(JBUF,NCHAR,JFIL) ---- ----- ---- SUBROUTINE SEPAR(IBUF,ITABL,JTABL,NWDS,NCHR) ---- SUBROUTINE SHIFTL(IWORD,NBITS) ~~~~~ ----- SUBROUTINE SOPEN(N,NFILE,IERR) - ----- 2. The FLIBSCI Subroutines This section begins with definitions of the terms to be used in the discussion of the FLIBSCI subroutines. The major part of this section is a detailed explanation of each subroutine including examples of its use. 2.1 Definition of Words and Symbols Certain terms used in this discussion need to be defined in order to preclude confusion or misunderstanding. The definitions that follow are not meant to be universal, or even in complete agreement with usages elsewhere. Array - A group of variable locations which are identified by one variable name, but which may be addressed independently by subscripting the variable name. Bit - This refers to a binary digit; that is, a digit that can take on the values of zero or one. This is the basic unit of information in most digital computers. Word - This is a group of bits, taken as a unit. The number of bits which make up one word varies from one computer to another. A word is usually the basic unit for storing or reading the computer s memory. Byte - This is also a group of bits, taken as a unit. A byte is usually considered as the basic unit for manipulation of data, especially when referring to alphanumeric data. Bits can be fiddled with, but bytes are better. In most machines, a byte is either 6 bits or 8 bits. Device - This refers to an I/O (Input/Output) device, which is a piece of equipment that handles the movement of desired information into and out of a computer system, and its translation into different formats and media. For example, a card reader is an input device, and a teletype printer is an output device; the teletype keyboard is an input device which actually operates independently of the printer. Escape character - A special character on the operator console keyboard which can be used by the system to specify termination of a computing task. The actual character or key may vary from one system to another. File - A unit of information which is terminated by an end-of-file mark. This is a complete and self-contained unit of information. In terms of a program, this is the largest division of information. In FORTRAN, a file is usually considered to be made up of unit-records. Character - The basic unit of alphanumeric information. The letter A is a character; so is a 9 or a plus sign (+) group of bits that can represent one character. Line - A string which is followed by a line terminator character. The length of the line is the number of characters in the string, not including the line terminator character. Record - A unit of information which is terminated by an end-of-record mark. If this doesn t mean much, don t worry, as this term does not come up again. Unit-record - This is the same as a line. It may represent a card image or print line. It can contain 0 to 132 characters. String - An ordered group of characters, located in consecutive bytes of memory or other storage medium. For example, this sentence is a string. cr - This stands for the carriage return character (in a string) or key (on a device). lt - This stand for the line terminator character. 2.2 Description of Subroutines The subroutines are discussed in the same order as they are listed in Section 1. In each case, the subroutine name is given, with the list of formal parameters; the usage of each parameter is indicated by underlining as described in Section 1. Next, a verbal discussion of the action of the subroutine is given, followed by examples of its usage. In the examples shown, a blank character in a string is designated by the symbol b. SUBROUTINE ACCEP(IBUF,NCHAR,NFIL,IECHO,MFIL,IEOF) ~~~~~ ---- ----- ---- This subroutine inputs characters from the file identified by NFIL, and stores them in array IBUF, beginning at the first character position. The exact action of this routine depends mainly upon the values of parameters NCHAR and NFIL. a) If NFIL is equal to the value of NTTI (see Common Block/IO/ in Section 3) a question mark (?) character followed by one blank space is output to the operator console device to indicate the system is awaiting input from the console input device. Characters are then accepted from the console input device until a carriage return or the 132nd character is input. Each character is echoed back to the console output device as it is entered. (Remember that the operator console is actually two separate devices, one for input and one for output.) If the first four characters entered are the word EXIT, then the program is terminated by calling SUBROUTINE EXIT; otherwise, a carriage return-line feed sequence is output to the operator console. IEOF is set to logical .FALSE., and NCHAR is set to the number of characters input up to, but not including, the carriage return. A line terminator is placed in the character position corresponding to the carriage return. b) If NFIL is not equal to the value of NTTI (per Common Block/IO/) characters are input from the file identified by NFIL and stored in array IBUF. If NCHAR is greater than zero, characters are input until NCHAR characters are input or the end of the file is reached. If NCHAR is equal to zero, characters are input until a line terminator or the 132nd character is input (whichever occurs first). NCHAR is set to the number of characters input up to, but not including, the line terminator (i.e. the line terminator is stored in character position NCHAR+1 of IBUF). If the end of the file is reached during the read operation, IEOF is set to the logical value .TRUE.; otherwise, IEOF is set to the logical value .FALSE.. Examples -------- The file identified by NIN2 is positioned at the beginning of the following string: ABCDEbbFG lt ZYXWVUT lt bb12.95 lt (END OF FILE) The array JBUF contains the string XXXXXXXXXX---------------------(i.e. filled with X s). a) NCHAR = 0 CALL ACCEP(JBUF,NCHAR,NIN2,.FALSE.,NTTO,IEOF) . . JBUF now contains ABCDEbbFG lt XXXX------------- and variable IEOF has the value logical .FALSE. NCHAR now contains the value of 10. b) NCHAR = 14 CALL ACCEP(JBUF,NCHAR,NIN2.TRUE.,NTTO,IEOF) . . JBUF now contains ABCDEbbFG lt ZYXWXXXX----------- and the line ABCDEbbFG is typed out on the operator console. IEOF is .FALSE. c) NCHAR = 100 CALL ACCEP(JBUF,NCHAR,NIN2,.FALSE.,NTTO,IEOF) . . JBUF now contains ABCDEbbFG lt ZYXWVUT lt bb12.95 lt XXXX----- NCHAR now has the value of 26, and IEOF is .TRUE. d) NCHAR = 0 CALL ACCEP(JBUF,NCHAR,NTTI,.TRUE.,NOUT1,IEOF) At this point a question mark (?) is typed out on the operator console. The operator then types in the string HOWbNOWbBROWNbCOW. cr Array JBUF now contains HOWbNOWbBROWNbCOW. lt XXX------------- NCHAR now contains the value 19 IEOF now contains the value logical .FALSE. SUBROUTINE CONVE(IBUF,NPOS,RVAR,NWID,NDEC) ---- ---- ---- ---- This routine encodes the decimal exponential ('E Format') representation of the floating point value of the real variable RVAR into the string beginning at the NPOSth character of the array IBUF. The field encoded is NWID characters wide. NDEC gives the number of digits following the decimal point in the mantissa. Its maximum value is dependent on the numerical significance of the computer being used. The representation is in the form rm.mmm-mEsee where r is a blank or minus sign, m is a digit of the mantissa s is a plus or minus sign , e is a digit of the exponent. Note that the field width should always be at least (NDEC+7), to allow for sign and exponent. Examples -------- Array ILINE initially contains ZZZZZZZZZZZZZ... a) CALL CONVE(ILINE,2,-150.61,10,3) Z-1.506E+02ZZZ.... b) CALL CONVE(ILINE,3,.1500,12,4) ZZbb1.5000E-01ZZZ... SUBROUTINE CONVF(IBUF,NPOS,RVAR,NWID,NDEC) ---- ---- ---- ---- This routine encodes the decimal floating point representation of the floating point value of the real variable RVAR into the string beginning at the NPOSth character of the array IBUF. The field encoded is NWID characters wide. NDEC gives the number of digits encoded to the right of the decimal point. The floating point number is right justified in the field, with blank fill. If the floating point representation is too large to fit within the field specified by NWID, the greatest possible number of low-oder digits will be encoded in the field, and an asterisk will be placed in the low order position of the field. Examples -------- Array ILINE initially contains the string ZZZZZZZZZZ.... a) CALL CONVF(ILINE,4,16.5,5,2) ZZZ16.50ZZ... b) CALL CONVF(ILINE,4,-16.5,5,2) ZZZ1*.50ZZ.... (Note that the sign caused the field to overflow.) c) CALL CONVF(ILINE,4,0.0,5,0) ZZZbbb0.ZZ.... SUBROUTINE CONVI(IBUF,NPOS,IVAR,NWID,IMODE) ---- ---- ---- ----- This routine encodes the decimal integer representation of the integer value of IVAR into the string beginning at the NPOSth character of the array IBUF. The integer field encoded is NWID characters wide. If IMODE has a value of zero, the integer is encoded right justified in the field, with blank fill. If IMODE is positive, the integer is encoded right justified with zero fill. If the integer representation is too large to fit in the field (i.e. has more than NWID digits), then NWID lowest order digits are encoded, and an asterisk is placed in the right hand character position of the field. Examples -------- Array JLINE initially contains ZZZZZZZZ..... a) CALL CONVI(JLINE,3,15,4,0) JLINE now contains ZZbb15ZZ.... b) CALL CONVI(JLINE,3,15,4,1) JLINE now contains ZZ0015ZZ.... c) CALL CONVI(JLINE,3,-15000,4,0) JLINE now contains ZZ500*ZZ.... SUBROUTINE CONVN(KBUF,NPOS,NLTH,IVAR,RVAR,IERR) ---- ---- ---- This routine decodes the representation of a numeric value found in the string beginning at the NPOSth character position of the array KBUF, and containing NLTH characters. The decoded value is stored in floating point form in variable RVAR; the fraction part is truncated and the integer value is stored in variable IVAR. The character representation of the number may be in almost any FORTRAN numeric format, including I (integer, no decimal), F (floating decimal point) and E (exponential) suffixing the character B to the number in any of the above formats (and using only digits 0-7, of course) ignored. The plus sign(+) is optional for positive numbers or exponents. If for any reason the number cannot be properly interpreted, the variable IERR is returned with the value of logical .TRUE.; otherwise, IERR is returned .FALSE.. Examples -------- In the following examples, the string to be interpreted is found in the first ten characters of array INBUF. The values that will be returned for IVAR, RVAR and IERR are shown for the calling sequence: CALL CONVN(INBUF,1,10,IVAR,RVAR,IERR) CONTENTS OF STRING IVAR RVAR IERR bbbbb12bbb 12 12.0 .FALSE. bbbbb12Bbb 10 10.0 .FALSE. bbbbb1b2bb 12 12.0 .FALSE. bb4.56E4bb 45600 45600.0 .FALSE. bb4.56E-4b 0 0.000456 .FALSE. -4.506E+2B -296 -296.75 .FALSE. 1bbbbbbbbb 1 1.0 .FALSE. 1bbbXbbbbb Previous values are .TRUE. unchanged SUBROUTINE DUMPZ(IVAR) ---- This routine prints the binary representation of the lowest order 16 bits of variable IVAR on the field designated by NTTO (see Common Block/IO/). Example ------- Variable IVAR contains the value 107 (=153 ) 10 8 CALL DUMPZ(IVAR) The following string is printed on the operator console: 0000000001101011 LOGICAL FUNCTION EQUAL(ISTR1,NPOS1,NCHR1,ISTR2,NPOS2,NCHR2) ----- ----- ------ ----- ----- ----- If the contents of NCHR1 AND NCHR2 are equal, then two strings are compared character by character by equality. The first string is in array ISTR1, beginning with the NPOS1th character; the second string is in array ISTR2, beginning with the NPOS2th character. Each string is NCHR1 (or NCHR2) characters long. If each corresponding character of the two strings are the same, the value of EQUAL is .TRUE.. If NCHR1 does not equal NCHR2, or the character in any position of one string is not the same as the character in the same position of the other string (with the exception noted below), the value of EQUAL is returned as .FALSE.. If a character in the string ISTR1 is an asterisk, the value of the comparison for that position is .TRUE. regardless of the value of the corresponding character in the other string. Examples -------- Array ISTR contains THEbDOGbISbGOOD Array JSTR contains THEbFOGbAINTbBAD a) I = EQUAL(ISTR,1,3,JSTR,1,) The value of I is now logical .TRUE. b) IF (EQUAL(ISTR,1,3,JSTR,1,2)) GO TO 20 12 A = B + C Statement 12 will be executed as a result of the IF statement (EQUAL is .FALSE.. Note that the string lengths are different.) c) IF (EQUAL(7HTHEb*OG,1,7,JSTR,1,7)) CALL EXIT The CALL EXIT statement will be executed (EQUAL is .TRUE. since the first string has an asterisk in the same position as the F in the second string, and the other characters are the same in both strings). LOGICAL FUNCTION EQUBL(IBUF,NPOS,NCHR) ---- ---- ---- The function variable EQUBL is assigned the value .TRUE. if and only if the string of NCHR characters beginning in the NPOSth character position of array IBUF is all blanks. If NCHR is negative or zero, the function is .FALSE., regardless of the contents of IBUF. Examples -------- Array IBUF contains the string AbBROWNbbbbbbbRAN a) ILOG = EQUBL(IBUF,1,18) The variable ILOG now has the logical value .FALSE.. b) IF (EQUBL(IBUF,9,5)) GO TO 105 10 CONTINUE The GO TO statement will be executed since EQUBL IS .TRUE.. SUBROUTINE ERROL This subroutine prints the message COMMAND LENGTH ERROR on the file designated by NTTO (the second variable in Common Block/IO/). Example ------- CALL ERROL The message COMMAND LENGTH ERROR is printed on the operator console. SUBROUTINE ERROR(NWORD) ----- This routine results in the message AN ERROR WAS FOUND IN WORD - w w w w ... w w being printed on the file designated by the variable NTTO in Common Block/IO/ (this is normally the operator console device) SUBROUTINE DRIVER; if a return is made from DRIVER, then a normal return from ERROR to the calling routine is made. The string w w w...w w represents the string of characters found in array INBUF, beginning at the character position given by ITAB(NWORD) with a length of JTAB(NWORD) characters; INBUF, ITAB and JTAB are all found in Common Block/INPUT/. The usual use of this routine is for displaying errors found in checking command syntax. Examples -------- The array INBUF contains the string SETbTIMEb14X25 lt The array ITAB and JTAB contain the values ITAB(1) = 1 JTAB(1) = 3 ITAB(2) = 5 JTAB(2) = 4 ITAB(3) = 10 JTAB(3) = 5 a) CALL ERROR(3) causes the following message to be printed on the operator console: AN ERROR WAS FOUND IN WORD - 14X25 b) CALL ERROR(2) causes the following message to be printed on the operator console: AN ERROR WAS FOUND IN WORD - TIME LOGICAL FUNCTION ESCAPE(IDUM) The value of this function is returned as logical .TRUE. if and only if the last character entered on the operator console device was an escape character; otherwise, the function returns the logical value .FALSE. (the variable IDUM is a dummy variable) terminating a long computation process without having to abort or otherwise terminate execution. Example ------- . . IF (ESCAPE(N)) CALL EXIT GO TO 22 . . If, when the sequence is encountered, the last character the operator entered was an escape character, the CALL EXIT branch is taken and the program will be terminated; otherwise, the GO TO statement is executed. SUBROUTINE EXIT This routine serves two major functions: first, it contains the DATA statements which initialize all FLIBSCI Common Block variables; secondly, this routine is called when program execution is to be terminated. When this routine is called, all files are closed, I/O buffers flushed, and a normal return to the operating system is initiated. Because of the initialization feature, SUBROUTINE EXIT must be loaded if any FLIBSCI routines are referenced. Example ------- CALL EXIT Files are closed, buffers emptied, and control is returned to the operating system. The fact that the routine is referenced insures that it will be loaded. FUNCTION IBIT(IWORD,NBIT) ----- ---- The value of this function is returned as an integer variable containing binary zeros in all bit positions except the NBITth; this bit has the same value as the corresponding bit in integer variable IWORD. Bit position is counted from low order position to high order position, with the low order bit being in position 0. Note that the bit position is the power of two represented by that bit. Example ------- Variable IVAL contains the value 6 (binary 0...0110). a) K = IBIT(IVAL,0) K now contains the value 0. b) K = IBIT(IVAL,2) K now contains the value 4 (binary 0...0100). c) K = IBIT(IVAL,3) K now contains the value 0. SUBROUTINE JBIT(IWORD,NBIT) ~~~~~ ---- SUBROUTINE KBIT(IWORD,NBIT) ~~~~~ ---- This pair of subroutines modifies the contents of the integer variable IWORD. Subroutine JBIT causes the NBITth bit of IWORD to be turned on (set to binary 1); while subroutine KBIT causes the NBITth bit of IWORD to be turned off (set to binary 0) unaffected. Bit position is numbered from low to high order position, with the low order bit being in position 0. Examples -------- a) IWORD contains 14 (binary 0...01110) CALL KBIT(IWORD,1) IWORD now contains 12 (binary 0...01100) b) IWORD contains 6 (binary 0...00110) CALL JBIT(IWORD,3) IWORD now contains 14 (binary 0...01110) c) IVAL contains 13 (binary 0...01101) CALL JBIT(IVAL,3) IVAL still contains 13 (binary 0...01101) Note that bit 4 was already on; thus there is no change) FUNCTION KCHAR(IBUF,NPOS) ---- ---- This FUNCTION subprogram extracts the character which is in the NPOSth character position in the array, IBUF; the character is returned right justified in the variable KCHAR, with zero fill. Example ------- IBUF contains ABCDEF.... I = KCHAR(IBUF,3) I now contains the value of character C, right justified with zero fill. SUBROUTINE JCHAR(IBUF,NPOS,JVAL) ~~~~ ---- ---- The character contained in variable JVAL is inserted into the NPOSth character position of array IBUF; the preceding and following characters in the array are unchanged. The character in JVAL must be right justified with zero fill. Example ------- Array JBUF contains ZZZZZZ...... J contains the character H, right justified with zero fill M4 contains the integer value 4 CALL JCHAR(JBUF,M4,J) JBUF now contains ZZZHZZ..... FUNCTION LAND(IVAL,JVAL) This function returns the integer value obtained by taking the binary bit-by-bit logical product of (also called 'AND-ing') the contents of the two integer variables IVAL and JVAL. The operands are not changed. The logical product operation causes a bit of the result to be one if and only if the corresponding bit of each operand is one. The binary truth table for the logical product is: First operand 1010 Second operand 1100 ---- Result 1000 Example ------- IVX contains the value 11 (binary 1011) JVY contains the value 13 (binary 1101) K = LAND(IVX,JVY) K now contains the value 9 (binary 1001) FUNCTION LNOT(IVAL) ---- This function returns the integer value obtained by taking the binary bit-by-bit logical complement of (also called 'NOT-ing') the contents of the integer variable IVAL. The operand is not changed. The logical complement causes a bit of the result to be one if and only if the corresponding bit of the operand is zero. The binary truth table for the logical complement is: Operand 10 -- Result 01 Example ------- IMS contains the binary value 0...01110 M = LNOT(IMS) M now contains the binary value 1...10001 (The extension dots are used to indicate that the full integer variable width (bits) is filled out as shown). FUNCTION LOCF(IVAR) ---- The integer value returned in variable LOCF represents the memory address of the variable IVAR. Example ------- Variable Name Memory Address Contents I 1000 1000 J 1001 10 K 1002 777 a) MEM = LOCF(J) The variable MEM now contains the value 1001. b) K = LOCF(I+2) The variable K now contains the value 777. FUNCTION LOR(IVAL,JVAL) ---- ---- This function returns the integer value obtained by taking the binary bit-by-bit logical sum (also called 'OR-ing') the contents of the two integer variables IVAL and JVAL. The operands are not change. The logical sum operation causes a bit of the result to be zero if and only if the corresponding bit of each operand is zero. The binary truth table for the logical sum is: First Operand 1010 Second Operand 1100 ---- Result 1110 Examples -------- a) IVT contains the value 11 (binary 1011) IVS contains the value 5 (binary 0101) K = LOR(IVS,IVT) K now contains the value 15 (binary 1111). b) J = LOR(40,6) J now contains the value 46 40 = binary 101000 6 = binary 110 logical sum = binary 101110 = 46 SUBROUTINE MOVE(IAFR,NCFR,JATO,NCTO,NCHAR) ---- ---- ~~~~ ---- ----- A string of NCHAR characters is moved from array IAFR, beginning with the NCFRth character position, into the array JATO, beginning at the NCTOth character position. Caution must be used to avoid overlapping locations during the transfer operation, as no intermediate buffer is used. Examples -------- Array IBUF contains the string ZZZZZZZZ Array JBUF contains the string ABCDEF a) CALL MOVE(JBUF,2,IBUF,3,4) Array IBUF now contains ZZBCDEZZ.... b) CALL MOVE(JBUF,2,JBUF,3,13) The contents of array JBUF are now unpredictable. The intent of this could be accomplished by using CALL MOVE(JBUF,2,JTEMP,1,3) CALL MOVE(JTEMP,1,JBUF,3,3) where JTEMP is a temporary array (at least three characters in length). SUBROUTINE MOVBL(IBUF,NPOS,NCHR) ~~~~ ---- ---- This subroutine moves a string of NCHR blanks into array IBUF, beginning at the NPOSth character position. If NCRH is less than or equal to zero, IBUF is not changed. Examples -------- Array IBUF initially contains ZZZZZZZZ... a) CALL MOVBL(IBUF,3,3) IBUF now contains ZZbbbZZZ... b) NBLK = -3 CALL MOVBL(IBUF,3,NBLK) IBUF now contains ZZZZZZZZ... Note the value of NBLK is negative. SUBROUTINE PAGE(NFIL) ---- This routine causes a form feed character to be output to the file identified by NFIL. Example ------- CALL PAGE(NIN3) A form feed character is output to the file identified by NIN3. SUBROUTINE PRINT(JBUF,NCHAR,JFIL) ---- ----- ---- This routine outputs a line from the array JBUF to the file specified by JFIL. The first NCHAR characters of the buffer JBUF are output followed by a line terminator. The contents of JBUF are not modified. Example ------- Array JBUF contains the string ABbbE lt FGbb--------- a) CALL PRINT(JBUF,5,NTTO) The line ABbbE is printed on the operator console. b) CALL PRINT(JBUF,3,NOUT1) The line ABb lt is output to the file identified by NOUT1. c) CALL PRINT(JBUF,8,NDEV) The line ABbbE lt FG lt is output to the file identified by NDEV. SUBROUTINE SEPAR(IBUF,ITABL,JTABL,NWDS,NCHR) ---- This routine separates the elements of the line contained in IBUF, up to the line terminator or the 138th character, whichever is encountered first. NCHR is set to the number of characters which were encountered (i.e. length of line) including blanks. NWDS is set to the number of word elements found in the line. A word element is a group of contiguous non-delimiter characters preceded by a word delimiter and followed by a word delimiter or a line terminator. A word delimiter is one or more blanks, or a comma. The beginning character position of each word element is stored in the corresponding element of array ITABL, and the number of characters in each word element is stored in the corresponding element of the array JTABL. The (NWDS+1)th values of ITABL and JTABL are set to one and zero, respectively. Example ------- Array IBUF contains the string bPRINTbb15bLINES,12,14.6b-4 lt CALL SEPAR(IBUF,IT,JT,NW,NC) IBUF is unchanged NWDS now contains the value 6 NCHR now contains the value 27 The arrays IT and JT contain the following: Location IT JT 1 2 5 2 9 2 3 12 5 4 18 2 5 21 4 6 26 2 7 1 0 8 unchanged unchanged SUBROUTINE SHIFTL(IWORDS,NBITS) ~~~~~~ ----- This routine causes the contents of integer variable IWORD to be left shifted NBITS bit positions; the shift is end-off with zero fill (that is high-order bits are discarded, low-order bits are filled in with zero bits). Example ------- Variable IVAL contains the value 11 (binary 0...01011) CALL SHIFTL(IVAL,2) IVAL now contains the value 44 (binary 0...0101100) Note that this has the same effect as multiplying by 4; isn t that interesting! SUBROUTINE SOPEN(N,NFILE,IERR) - ----- Word number N in array INBUF of Common Block/INPUT/ is interpreted as a name and after closing a file at file slot NFILE, if one is open, opens this named file. The logical variable IERR is set depending upon whether or not the open was successful. Example ------- It is desired to request, via the operator console, the name of a file and to open that file for use during execution. This may be done by the following sequence: COMMON/IO/NTTI,NTTO,NIN2,NIN3,NIN4,NOUT1,NOUT2 COMMON/INPUT/DOTS,NCHR,NWDS,MAX,ITAB(100),JTAB(100),INBUF(7) DIMENSION ITEMP(2) . . IECHO = .FALSE. 1 CALL PRINT(11HFILE NAME = ,11,NTTO) CALL ACCEP(IBUF,0,NTTI,IECHO,NTTO,IEOF) C THE FIRST WORD ENTERED IS THE FILE NAME CALL SEPAR(INBUF,ITAB,JTAB,NWDS,NCHR) CALL SOPEN(1,NIN3,IERR) IF(IERR) GO TO 1 C PRINT THE NAME OF THE FILE CALL PRINT(ITEMP,8,NTTO) . . 3. Common Blocks The following Common Blocks are used by FLIBSCI: a) /MSK/M0,M1,M2,M3,M4,M5,M6,M7,M10,M11,M12,M13,M14,M15,M16,M17 These variables are initialized in subroutine EXIT. Each variable contains an integer, the octal value of which is reflected by the number following M; for example, M15 contains octal 15 = decimal 13. b) /IO/NTTI,NTTO,NIN2,NIN3,NIN4,NOUT1,NOUT2 Each variable contains a file identifier code; the actual contents vary according to hardware system requirements. Values are initialized by EXIT. c) /INPUT/DOTS,NCHAR,NWORDS,MAXIN,ITAB(100),JTAB(100),INBUF(70) DOTS contain the value 4H...., which can be printed to indicate command completion, etc. NCHAR Not initialized. May be used as character NWORDS and word counters. MAXIN is initialized to the size (in words) of the ITAB and JTAB arrays by EXIT. ITAB is an array used to contain word position pointers for strings in INBUF. JTAB is an array used to contain word length pointers for strings in INBUF. INBUF is an array used to contain character strings. d) /IPARAM/LWORD,LCHAR,IMASK,IEL,SIGNIF These variables contain machine-dependent installation parameters; all are initialized by EXIT. LWORD is the number of characters normally held in an integer variable. LCHAR is the number of bits (binary digits) used to express one character. IMASK contains a character mask of LCHAR one-bits, right justified in the word, with zero fill. IEL is the character representation for end-of-line (i.e. the lt character) on input, right justified with zero fill. SIGNIF is the smallest positive value (compared with unity) of -n significance for a real variable. This is greater than or equal to 2 where n is the number of bits in the mantissa of a real variable. e) /SYMBOL/ICB,ICE,ICZ,ICP,ICM,IC,ICA,ICDIV,ICPER,ICCOM,ICEQU,ICQUO,ICLP,ICRP These variables each contain the representation of a single character right justified with zero fill. The corresponding characters are shown below. All are initialized by EXIT. ICB = B ICE = E ICZ = 0 (zero) ICP = + ICM = - IC = (blank) ICA = * ICDIV = / ICPER = . ICCOM = ICEQU = = ICQUO = ' ICLP = ( ICRP = ) f) /HEIDGC/ISTART ISTART is a flag variable used by PRINT and ACCEPT for initializing files. 4. The FLIBSCI Validation Program The program FLIBST is a FORTRAN program which has three main purposes: first, it serves as an example of how to write a program using the FLIBSCI subroutines; second, it is a thorough and flexible means of validating the FLIBSCI routines; and finally, it provides the user of FLIBSCI a convenient way to determine the exact action of the FLIBSCI software without having to write debug and test his own 'try it out' programs. This section describes how the program functions and includes a complete annotated source listing. 4.1 Operation When FLIBST is called into execution, the initial header 'THE SCI TEST PROGRAM' is printed on the operator console. A carriage return-line feed sequence is output, and a question mark is printed at the beginning of the line: this indicates the program is ready for the next test command to be entered (as discussed in the next section) result of a call to ACCEP) after completion of each test. The format of the test commands is as follows: TEST [testname] [parameters] cr [string] In the first case, the response will vary according to the test specified by [test name] and the parameters given by [parameters], as described in the next section. In the second case, the program will respond by typing out, in a fixed format, the contents of the variables found in Common Blocks /IPARAM/ and /SYMBOL/, if [string] contains less than two characters. It should be noted that all numeric values output by the program are decimal values. Numbers input are decimal values, unless the number is followed by the character B; in which case the number is taken as an octal value. For each TEST command, the parameters must be entered in the order shown separated by one or more blanks, or by one comma and (optionally) blanks. If a character string is to include leading, trailing or imbedded blanks the entire string must be enclosed within one pair of quotation marks. The following parameter terms will be used in the discussion of the commands: [number] A character string representing a number, in any legitimate FORTRAN format (i.e. integer, floating point or exponential; decimal or binary). [string] A group of characters; may be enclosed in one pair of quotation marks. [position] A number representing the character position within a string counting from left to right. The first (left hand) character in a string is position one (1) and the last character is position n, where there are n characters in the string. [character count] A number specifying a quantity of characters to be manipulated. [file name] A string representing the name of a system file. The format of the string depends upon the system being used. 4.2 Tests In this section, all entries made by the operator are underlined, and responses output by the computer are not. In general, the test name corresponds to the name of the FLIBSCI subroutine being tested. In each example, the first line indicates the test command, and the results and responses follow with comments added. A. cr -- This command (a carriage return only) is used to print out the system parameters. The first line contains the variables of the FLIBSCI Common Block/IPARAM/. The second line contains the character symbols found in Common Block/SYMBOL/, followed by the integer value of the characters A and 0 (zero). The third line is the binary representation of the address of a memory location; this represents a test of LOCF and DUMPZ. Remember that the actual values printed in this test will depend upon the hardware system being used. Example ------- ? LWORD= 2 LCHAR=8 CMASK=255 IEL= 0 SIGNF= 1.00E-06 MAXIN=1OO BE0+- */.,='() A= 65 0= 48 0000001010010000 ? B. TEST CONV [number] cr ---------------------- [number] is in the format sdddd or sddddddd.ddddd or sdddd.ddddEse or [any of the above]B where s is blank, +, - or omitted d is a digit 0 to 9 e is one or two digits (the exponent) E is the character E B is the character B The number is converted to internal integer and floating point representations, and printed back out in the following form: CONVN [binary integer value] [decimal integer value] [floating point value-F10.2] [exponential value-E10.2] [exponential value-E10.3] Example ------- ? TEST CONVN 12.5 CONVN 0000000000001100 0000000012 12 12.50 1.25E+01 1.250E+01 ? TEST CONVN 12.5E1B CONVN 0000000001010101 0000000085 85 85.00 8.50E+01 8.500E+01 ? TEST CONVN -.0023 CONVN 0000000000000000 0000000000 0 0.00 -2.30E-03 -2.300E-03 ? C. TEST MOVE [string] [position] cr ---------------------------------- The response is as follows: MOVE ABCDEFGHIJKLMNOPQRSTUVWXYZ [modified string] where [modified string] is the alphabet string (line2), with the contents of [string] inserted beginning at [position]. Example ------- ? TEST MOVE 'ZZZZZZZZZZ' 4 MOVE ABCDEFGHIJKLMNOPQRSTUVWXYZ ABCZZZZZZZZZZNOPQRSTUVWXYZ ? TEST MOVE ZZZ 3 MOVE ABCDEFGHIJKLMNOPQRSTUVWXYZ ABZZZFGHIJKLMNOPQRSTUVWXYZ ? TEST MOVE ' ' 4 MOVE ABCDEFGHIJKLMNOPQRSTUVWXYZ ABC EFGHIJKLMNOPQRSTUVWXYZ ? D. TEST IBIT [number] [bit position] cr ------------------------------------- where [bit position] is a number specifying the bit in [number] for which the value is to be returned. The response is as follows: IBIT [binary representation of [number]] [binary representation of value returned] Example ------- ? TEST IBIT 7777B 3 IBIT 0000111111111111 0000000000001000 ? TEST IBIT 10 0 IBIT 0000000000001010 0000000000000000 ? E. TEST JBIT [number] [bit position] cr where [bit position] is a number specifying the bit in [number] which is to be changed to a binary one (1). The response is as follows: JBIT [binary representation of [number]] [binary representation of value retrieved] Example ------- ? TEST JBIT 7700B 1 JBIT 0000111111000000 0000111111000010 ? TEST JBIT 15 2 JBIT 0000000000001111 0000000000001111 ? F. TEST KCHAR [string] [position] cr ---------------------------------- The response is as follows: KCHAR [string] [character] [dollar sign] [binary value of [character]] where [character] is the character which is found at [position] in [string]. The character is typed at the left hand side of the page. [dollar sign] is the character $; the dollar sign is located immediately under the [position]th character of [string], to indicate where the character was found. Example ------- ? TEST ICHAR ABCDE 5 ICHAR ABCDE E $ 0000000001000101 ? TEST ICHAR ' ABCED' 2 ICHAR ABCED A$ 0000000001000001 ? G. TEST JCHAR [string] [position] cr ---------------------------------- The response is: JCHAR [string] [modified string] where [modified string] is the original string with a period inserted in the location given by [position]. Example ------- ? TEST JCHAR ZZZZZZZZ 3 JCHAR ZZZZZZZZ ZZ.ZZZZZ ? TEST JCHAR ABCDEFG 7 JCHAR ABCDEFG ABCDEF. ? H. TEST EQUAL [string] string] cr ------------------------------- The response is as follows: EQUAL [logical value] where [logical value] is either the word TRUE or the word FALSE, corresponding to the value returned (i.e. the equality of the strings according to subroutine EQUAL). Example ------- ?TEST EQUAL ABCDE 12345 EQUAL FALSE ? TEST EQUAL ABCDE ABCDE EQUAL TRUE ? TEST EQUAL ABC*D ABCXD EQUAL TRUE ? TEST EQUAL ABCDE ABC*E EQUAL FALSE ? TEST EQUAL ABC*E ABC*E EQUAL TRUE ? I. TEST EXIT cr ------------- The response is as follows: USER EXIT and the execution of the program is terminated. Example ------- ? TEST EXIT USER EXIT ]] J. TEST SHIFTL [number] [number of bits] cr ----------------------------------------- The value of [number] is converted to internal integer format, and then left shifted by [number of bits] bit positions by subroutine SHIFTL. The response is as follows: [binary representation of [number]] [binary representation of shifted value] Example ------- ? TEST SHIFTL 1 0 0000000000000001 0000000000000001 ? TEST SHIFTL -1 1 1111111111111111 1111111111111110 ? TEST SHIFTL 77B 2 0000000000111111 0000000011111100 ? K. TEST ESCAPE cr --------------- Following this command, the program will accept no further input except the escape character; after this character is entered, the program is ready for the next TEST command. Example ------- ? TEST ESCAPE ? L. [string(not beginning with TEST)] cr ------------------------------------- If a string which does not begin with the word element TEST is entered the action of the FLIBSCI subroutine SEPAR is shown. The response is as follows: NCHAR = [number of characters in string] NWORDS = [number of word elements in string] [element number] [ start] [length] [element string] where [element number] is the number of the word element, counting from left to right in the string. [start] is the character position of the first character in a word element string. [length] is the number of characters in the word element string. [element string] is the string of characters in the word element. Example ------- ? TST SEPAR, A SUBROUTIE FOR CRACKING CHAR STRINGS. NCHAR= 49 NWORDS= 8 1 1 3 TST 2 5 5 SEPAR 3 12 1 A 4 14 9 SUBROUTIE 5 24 3 FOR 6 28 8 CRACKING 7 37 4 CHAR 8 42 8 STRINGS. ? M. [illegal command] cr --------------------- Entry of an illegal command string results in a call to subroutine ERROR or ERROL. An illegal command is a string which is not in one of the specified command formats. Example ------- ? TEST EQUAL COMMAND LENGTH ERROR ? TEST CONVN JT1 4 AN ERROR WAS FOUND IN WORD - JT1 ?