LBL-4684 BDMS Berkeley Database Management System (programmer's manual) (Version 2.2) David R.Richards Computer Science and Applied Mathematics Department Lawrence Berkeley Laboratory University of California Berkeley, California 94720 Acknowledgements BDMS had its origin in the joint development of a particle physics data system by the Berkeley Particle Data Group and the Caltech Data Compilation Group. The diversity of databases that make up that system necessitated the use of a common database management system, while the complexity of the data demanded capabilities not available in any existing DBMS. The new system which was developed to meet this need proven to be of general usefulness, and responsibility for its continued support and further development has been assumed by the Computer Science and Applied Mathematics Department at LBL. As the system evolved, many people contributed ideas and assisted with programming. They include Tricia Coffeen, Paul Chan, Geoffrey Fox, Marge Hutchinson, Tom Lasinski, Deane Merrill, Gill Ringland, Alan Rittenberg, Silvia Sorell, Paul Stevens, Tom Trippe, Vicky White, and George Yost. The users of BDMS also deserve thanks for contending with the seemingly endless change to which a developing system is subject. Their comments, criticism, and unfailing ability to flush out even the most recluse bugs have been and continue to be invaluable. This work was supported by the U.S. Department of Energy (formerly U.S. Energy Research and Development Administration and U.S. Atomic Energy Commission), the National Science Foundation, and the National Bureau of Standards. Table of Contents 06 Apr 78 1. Introduction 1 2. Housekeeping 2 2.1 SUBROUTINE INIT(IFILE,JFILE) 3 2.2 SUBROUTINE OPEN(IFILE,IDIR,invert,IERR) 4 2.3 SUBROUTINE CLOSE 5 2.4 System Common Blocks 6 2.5 FUNCTION IDENT(IPCK,NCHAR) 7 3. Record Access 8 3.1 SUBROUTINE CREATE(IREC,IERR) 9 3.2 SUBROUTINE STORE(IERR) 10 3.3 SUBROUTINE FETCH(IREC,IERR) 11 3.4 SUBROUTINE REMOVE(IREC,IERR) 12 3.5 SUBROUTINE SPROC(MODE,IERR) [user written] 13 3.6 FUNCTION KMOD(IDE,N) 14 3.7 SUBROUTINE FPROC(IERR) [user written] 15 3.8 SUBROUTINE KPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user 16 written] 3.9 SUBROUTINE KMAP(IUNPCK,NCHAR) [user written] 17 4. Data Element Access 18 4.1 FUNCTION IN(IDE,IOCC,IPAR) 19 4.2 FUNCTION IFIRST(IDE) 20 4.3 SUBROUTINE GET(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) 21 4.4 SUBROUTINE INSERT(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) 23 4.5 SUBROUTINE REPL(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) 25 4.6 SUBROUTINE DELETE(IDE,IOCC,IPAR,IERR) 26 5. Query Processing 27 5.1 SUBROUTINE RPNSET(IQUERY,LQUERY,ISET,IERR) 28 5.2 SUBROUTINE RPNOP(IQUERY,LQUERY,iop,IERR) 29 5.3 SUBROUTINE RPNREC(IQUERY,LQUERY,IREL1,IREC1,IREL2, 30 IREC2,IERR) 5.4 SUBROUTINE RPNDE(IQUERY,LQUERY,IDE,IREL1,IVAL1,LVAL1, 31 IREL2,IVAL2,LVAL2,IERR) 5.5 SUBROUTINE EVAL(IQUERY,LQUERY,ISET,LSET,IERR) 33 5.6 SUBROUTINE ORDER(ISET,IDE,n,IERR) [not yet implemented] 34 5.7 FUNCTION IFOUND(ISET,IREC) 35 5.8 SUBROUTINE PURGE(ISET,IERR) 36 6. Record Display 37 6.1 SUBROUTINE LIST(IFILE,LINE,MODE,NPRE,IERR) 38 6.2 SUBROUTINE LSET(IDE,N,IERR) 40 6.3 SUBROUTINE OPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user 41 written] 7. User Extension of the Database Executive and Load Utility 42 7.1 SUBROUTINE IPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user 43 written] 7.2 SUBROUTINE QPROC(IDE,IREL,IVALUE,LVALUE,MWORD,IERR) 44 [user written] Table of Contents 06 APR 78 8. Character Manipulation 46 8.1 SUBROUTINE PACKC(IPCK,ICHAR,IUNPCK,NCHAR) 47 8.2 SUBROUTINE UNPCKC(IPCK,ICHAR,IUNPCK,NCHAR) 48 8.3 SUBROUTINE MOVEC(IPCK,ICHAR,JPCK,JCHAR,NCHAR) 49 8.4 SUBROUTINE DECODE(IVALUE,ITYPE,IUNPCK,NCHAR,IERR) 50 8.5 SUBROUTINE DECODV(IVALUE,NELEM,ITYPE,IUNPCK,NCHAR, 51 IERR) 8.6 SUBROUTINE ENCODE(IVALUE,ITYPE,IUNPCK,NCHAR,NPRE,IERR) 52 8.7 SUBROUTINE ENCODV(IVALUE,NELEM,ITYPE,IUNPCK,NCHAR, 53 NPRE,IERR) 9. Utility Routines 54 9.1 SUBROUTINE OUTLN(IARRAY,NCHAR,IFILE,LNMAX,ISTAT) 55 9.2 SUBROUTINE OUTERR(IPCK,NCHAR,I,IFILE,LNMAX,ISTAT) 56 1. Introduction 1 1. Introduction This manual describes the program interface to BDMS. There are two levels at which user software may be interfaced to the system. One is the provision of user processors to tailor the standard system. The philosophy of user processors is described in the user's manual, while their detailed specifications can be found here. The second interface level is the invocation of BDMS subroutines from a user-written main program. Common applications of this type include report generators and application-specific user interfaces. By calling appropriate subroutines, a user program may add records to a database, modify or delete existing records, or display all or part of the contents of a record. The full power of the query language is available to a user program. It may generate a query to locate tho- se records satisfying an arbitrarily complex condition on key data element values and order the resulting subset of records on the values of any one or more data elements. Various subroutines of general usefulness are also described-- cha- racter manipulation routines, message output routines, and routines to output an index in linear form and read the resulting file. 2. Housekeeping 2 2. Housekeeping This chapter describes the routines used to initiate and terminate a BDMS session, the common blocks that a user may need to access, and the ident function, which translates data element names into the in- ternal ID's used by other routines. 2.4 Housekeeping 6 system common blocks 2.4 System Common Blocks Three of the system common blocks that a user may wish to access are described in this section. COMMON /DBCHAR/ BLANK,COMMA,PERIOD,SEMI,PLUS,MINUS,STAR,SLASH, 1 LPAR,RPAR,E,NUM(16),LBASE(6),IBASE(6),OP(3),FBLANK, 2 SPARE3(5) INTEGER BLANK,COMMA,PERIOD,SEMI,PLUS,STAR,SLASH,RPAR,E,OP,FBLANK DATA BLANK,COMMA,PERIOD,SEMI,PLUS,MINUS,STAR,SLASH,LPAR,RPAR,E 1 /1H ,1H,,1H.,1H;,1H+,1H-,1H*,1H/,1H(,1H),1HE/ DATA NUM/1H0,1H1,1H2,1H3,1H4,1H5,1H6,1H7,1H8,1H9,1HA,1HB,1HC,1HD, 1 1HE,1HF/ DATA LBASE/1HB,1HO,1HQ,1HD,1HH,1HZ/,IBASE/2,8,8,10,16,16/ DATA OP/1H=,1H<,1H>/ DATA FBLANK/1H^/ This contains the literal constants used by the system for inter- pretation of input. FBLANK is the character interpreted as a forced leading or trailing blank in a data element value (cf. User's Manual, Section 4.2); It may be desirable to change its value. COMMON /DBMACH/ NBPV,NCPW,RPRE,DPRE,LARGE,BITSON,SPARE4(5) INTEGER BITSON DOUBLE PRECISION DPRE This contains the parameters describing the machine on which the system is running. NBPW number of bits per word NPCW number of characters per word RPRE criterion for equality of single precision real quantities DPRE criterion for equality of double precision real quantities LARGE word containing largest possible positive integer BITSON word with all bits on A user attempting to write machine-independent software may wish to access NBPW. *COMDECK DBWORK COMMON /DBWORK/ LWORK,W(3000) INTEGER W DATA LWORK/3000/ This contains the system work space. It may be necessary to incre- ase its size for applications involving large records. This is done by increasing the dimension of W and setting LWORK to the new length cho- sen. 2.5 Housekeeping 7 FUNCTION IDENT(IPCK,NCHAR) 2.5 FUNCTION IDENT(IPCK,NCHAR) Arguments INPUT IPCK array holding data element name in packed form (last word blank filled) NCHAR number of characters in name OUTPUT IDENT >0 data element ID =0 IPCK is not a valid data element name Description This function returns the ID corresponding to a given data element name. Use of IDENT is recommended over embedding data element ID's in application programs since the application code is then insulated from changes in database definition that can change the ID's. A call to IDENT may be embedded in a call to one of the record manipulation ro- utines, e.g. CALL GET(IDENT(3HABC,3), ...) Although it is usually more efficient to set up a user common block containing all data element ID's used in the application program and initialize these ID variables at the start of execution with a series of calls to IDENT. Unpacked data element names may be packed by a call to the PACKC subroutine (cf. Section 8.1). 3. Record Access 8 3. Record Access This chapter describes the routines providing basic record at a ti- me access to the database. A new record may be created, an existing an existing one fetched or removed, and a new or modified record may be stored in the database by a call to the appropriate subroutine. Also described are the routines that may be supplied by a user for special processing of records as they are fetched or stored and for special processing and character code mapping of key data element values as they are stored in the indices. 3.1 Record Access 9 SUBROUTINE CREATE(IREC,IERR) 3.1 SUBROUTINE CREATE(IREC,IERR) Arguments OUTPUT IREC ID of newly-created record IERR error flag 0 operation successful 1 work space exceeded Description This subroutine creates in core a new empty record into which data may be inserted. The record must be stored to become a permanent part of the database. 3.2 Record Access 10 SUBROUTINE STORE(IERR) 3.2 SUBROUTINE STORE(IERR) Arguments OUTPUT IERR error flag 0 operation successful 1 record stored but not fully indexed 2 record was empty, if new it was not stored, if old it was deleted 3 empty old record deleted but not fully de-inde- xed 4 fatal error, database not modified Description This subroutine stores the new or modified record currently in the record buffer on the disk file data and updates the directory and in- version files appropriately. 3.3 Record Access 11 SUBROUTINE FETCH(IREC,IERR) 3.3 SUBROUTINE FETCH(IREC,IERR) Arguments INPUT IREC ID of record to be fetched (>0) OUTPUT IERR error flag 0 operation successful 1 work space exceeded 2 illegal record ID 3 requested record is deleted 4 length of retrieved record does not match the directory 5 ID of retrieved record incorrect 6 error return from FPROC Description This subroutine fetches the specified record from the disk file da- ta into the record buffer. 3.4 Record Access 12 SUBROUTINE REMOVE(IREC,IERR) 3.4 SUBROUTINE REMOVE(IREC,IERR) Arguments INPUT IREC ID of record to be deleted (>0) OUTPUT IERR error flag 0 operation successful 1 record deleted but not fully de-indexed 2 fatal error, database not modified Description This subroutine deletes the specified record from the disk file da- ta and updates the directory and inversion files appropriately. 3.5 Record Access 13 SUBROUTINE SPROC(MODE,IERR) [user written] 3.5 SUBROUTINE SPROC(MODE,IERR) [user written] Arguments INPUT MODE store mode 1 storing new record 2 storing modified record 3 deleting record OUTPUT IERR error flag =0 user processing complete <>0 error in user processing, abort store or remo- ve operation Description This subroutine is called by store just before a record is stored in the database and by remove just before a record is removed from the database. It may perform an intra-record data integrity check for a store operation and generate or modify data element values. For exam- ple, using values of data elements already present in the record, it may generate values for virtual key data elements that will be added to or deleted from the indices depending on the operation being per- formed. (In this connection, see also the description of KMOD, Section 3.6.) The error flag IERR is set to zero before the subroutine is called. If it is set to a non-zero value by SPROC, the store or remove opera- tion will be aborted; if an error message is desired, it must be gene- rated by SPROC (via a call to subroutines OUTLN or OUTERR, cf. Secti- ons 9.1 or 9.2). 3.6 Record Access 14 FUNCTION KMOD(IDE,N) 3.6 FUNCTION KMOD(IDE,N) Arguments INPUT IDE array of data element ID's to be checked for chan- ge N length of IDE in words OUTPUT KMOD 1 at least one of the specified data elements has a changed value 0 none of the specified data elements has changed -1 invalid arguments (N<=0, some IDE(j)<=0 or > number of defined data elements) Description This function is provided as an aid to the writer of an SPROC sub- routine. If SPROC generates virtual key data elements from some combi- nation of other data element values, it can determine whether any of those values have been changed by a modification of the record (when SPROC is called with MODE=2). If none of them has been changed, then the virtual data element in question should not be generated, and the cost of reindexing it will not be incurred. 3.7 Record Access 15 SUBROUTINE FPROC(IERR) [user written] 3.7 SUBROUTINE FPROC(IERR) [user written] Arguments OUTPUT IERR error flag =0 user processing complete <>0 error in user processing, abort fetch operation Description This subroutine is called by FETCH just after a record is fetched from the database. Its primary use is to generate ("rematerialize"), from data element values already present in the record, those virtual data elements that are to be visible to the user. The error flag IERR is set to zero before the subroutine is called. If it is set to a non-zero value by FPROC, the fetch operation will be aborted; if an error message is desired, it must be generated by FPROC (via a call to subroutines OUTLN or OUTERR, cf. Section 9.1 or 9.2) 3.8 Record Access 16 SUBROUTINE KPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user written] 3.8 SUBROUTINE KPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user written] Arguments INPUT/ IVALUE array holding value of key data element; format OUTPUT depends on database definition (see description) LVALUE length of value in elements, characters, or bits for numeric vector, char or bit type data ele- ments, respectively; LVALUE=0 is a null value INPUT IDE data element ID MWORD length in words of array IVALUE OUTPUT IERR error flag =0 processing complete <>0 fatal error, do not alter index Description If the KPROC attribute is specified for a key data element in the database definition, this subroutine will be called by INDEX to pro- cess each value of that data element before it is added to or deleted from an index. Normally, this would be done if it were desirable to store in the index a form of the value different from that in the re- cord. For example, one might like to remove all punctuation from the index form of a char-type data element, and then perform the same operation on the values of this data element appearing in a query (via QPROC, cf. Section 7). This would increase the likelihood of finding the requested values if a casual user is likely to make punctuation errors when formulating a query. The format of a data element value passed to and returned by this subroutine depends on the value of its KPROC attribute in the database definition. The options are: EXTERNAL the value is passed to and returned by KPROC in exter- nal format, i.e. unpacked character string (one charac- ter/word, left-adjusted, blank filled). INTERNAL the value is passed to and returned by KPROC in inter- nal format, i.e. internal binary numeric representati- on, packed character or bit string. CONVERT the value is passed to KPROC in external format and re- turned by KPROC in internal format. The error flag IERR is set to zero before the subroutine is called. If it is set to a non-zero value by KPROC, the data element value will not be added to or deleted from the index; if an error message is de- sired, it must be generated by KPROC (via a call to subroutines OUTLN or OUTERR, cf. Sections 9.1 or 9.2). 3.9 Record Access 17 SUBROUTINE KMAP(IUNPCK,NCHAR) [user written] 3.9 SUBROUTINE KMAP(IUNPCK,NCHAR) [user written] Arguments INPUT IUNPCK array holding unpacked character representation of char type key (one character/word, left-adjusted, blank filled) NCHAR length of IUNPCK in characters (words) Description This subroutine is called by INDEX to perform a character code map- ping on a char type data element value that is being added to or dele- ted from an index. The principle reason this might be done is when the user desires a collating sequence for ordered output of indices (cf. SUBROUTINE OUTINV, section 9.3) different from that of the standard character codes used by his computer. 4. Data Element Access 18 4. Data Element Access This chapter describes the routines providing data-element-at-a-ti- me access to the record currently in the record buffer. One may get single data element occurrences, insert new occurrences, and replace or delete existing occurrences by calls to the appropriate subrouti- nes, whose action is analogous to the corresponding editor commands described in the user's manual. It should be noted that these subroutines form a family with closely parallel argument structure and a common set of error returns. 4.1 Data Element Access 19 FUNCTION IN(IDE,IOCC,IPAR) 4.1 FUNCTION IN(IDE,IOCC,IPAR) Arguments INPUT IDE data element ID IOCC >0 occurrence number =0 last occurrence IPAR parent data element location (see description) OUTPUT IN >0 location of specified data element occurrence -2 invalid arguments (IDE<=0 or > number of defined data elements, IOCC<0) -3 parent data element occurrence does not exist -4 specified occurrence does not exist Description This function returns the location of a specified data element oc- currence within a specific parent data element occurrence (for non-re- cord-level data elements). The desired data element occurrence is specified by giving its oc- currence number IOCC. IOCC=0 specifies the last occurrence of the data element subordinate to the specified parent data element occurrence. The desired parent data element occurrence is specified by giving its location IPAR, which in turn may be found by calling IN. Thus the calls to IN may be nested recursively. For example, if data element 3 is subordinate to data element 2, which in turn is subordinate to a record-level data element 1, the entry point of the second occurrence of data element 3 within the last occurrence of data element 2 within the first occurrence of data element 1 is IENTRY = IN(3,2,IN(2,0,IN(1,1,0))). IPAR=0 specifies the last occurrence of the parent data element. IPAR is ignored for a record level data element (since it has no pa- rent data element); a good convention is to set it to zero as in the above example. 4.2 Data Element Access 20 FUNCTION IFIRST(IDE) 4.2 FUNCTION IFIRST(IDE) Arguments INPUT IDE data element ID OUTPUT IFIRST >0 entry point of occurrence at physical beginning of chain -2 invalid argument (IDE<=0 or > number of defined data elements) Description This function returns the location of the occurrence at the physi- cal beginning of the chain of all occurrences of a specified data ele- ment. This will be the first occurrence subordinate to some (but not necessarily the first) occurrence of its parent data element. It is necessary, for example, to use IFIRST to set the starting lo- cation for a series of IDE<0 calls to subroutine GET if one wishes to chain through all occurrences of a data element (cf. Section 4.3). 4.3 Data Element Access 21 SUBROUTINE GET(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) 4.3 SUBROUTINE GET(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) Arguments INPUT/ LVALUE on entry, length in words of array IVALUE; on OUTPUT return, length of value in elements, characters, or bits for numeric vector, char, or bit type data elements, respectively IOCC occurrence number or location, depending on sign of IDE (see description) INPUT |IDEl data element ID; sign specifies meaning of IOCC (see description) IPAR parent data element location; ignored if IDE<0 or if IDE identifies a record-level data element (see description) OUTPUT IVALUE array holding data element value; char type value is packed IERR error flag 0 normal return 1 insufficient space in array IVALUE; as much of the value as possible is returned 2 invalid argument (IDE=0 or |IDE| > number of defined data elements, data element type is node, LEN<0 on entry) 3 parent data element occurrence does not exist 4 specified occurrence does not exist Description This subroutine returns the value of the specified data element oc- currence and the length of that value; LEN=0 is returned for a null value. The occurrence may be specified in either of two ways, by oc- currence number or by location; the sign of ide determines the mode. If IDE>0, IOCC>=0 is the occurrence number and IPAR is the parent data element location (set by a call to function IN, cf. Section 4.1). IOCC=0 specifies the last occurrence of the data element subordinate to the specified parent data element occurrence. IPAR=0 specifies the last occurrence of the parent data element. IPAR is ignored for a re- cord level data element; a good convention is to set it to zero. If IDE<0, on entry |IOCC| is the location of the desired data ele- ment occurrence (set by a call to function IN or IFIRST, cf. Sections 4.1 Or 4.2). On return, IOCC is set to +- the location of the next oc- currence to facilitate chaining through several data element occurren- ces within a loop. IOCC<0 if the occurrence just accessed was the last subordinate to some occurrence of its parent, while IOCC=0 if the oc- currence just accessed was at the physical end of the chain of all occurrences of that data element. Thus, in general, if the starting location for a loop is set by a call to IN, the loop should be exited 4.3 Data Element Access 22 SUBROUTINE GET(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) when IOCC<0 is returned, while if the starting location is set by a call to IFIRST, the loop should be exited only when IOCC=0. IPAR is ignored; a good convention is to set it to zero. 4.4 Data Element Access 23 SUBROUTINE INSERT(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) 4.4 SUBROUTINE INSERT(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) Arguments INPUT/ IOCC occurrence number or location, depending on sign OUTPUT of IDE (see description) INPUT |IDE| data element id; sign specifies meaning of IOCC (see description) IPAR parent data element location; ignored if IDE<0 or if IDE identifies a record-level data element (see description) IVALUE array holding data element value; char type value is packed; ignored if data element type is node LVALUE length of value in elements, characters, or bits for NUMERIC VECTOR, CHAR, or BIT type data ele- ments, respectively; ignored if data element type is node OUTPUT IERR error flag 0 normal return 1 work space exceeded 2 invalid arguments (IDE=0 or |IDE| > number of defined data elements, LVALUE<0 for non-node type data elements) 3 parent data element occurrence does not exist Description This subroutine inserts a new occurrence of the specified data ele- ment before the specified occurrence. After the insertion, the previ- ously-existing occurrence is identified by an occurrence number one larger than before, while the new occurrence is identified by the spe- cified occurrence number. A value and its length must be specified for non-node type data elements; LVALUE=0 is a null value. The occurrence may be specified in either of two ways, by occurrence number or by lo- cation; the sign of IDE determines the mode. If IDE>0, IOCC>=0 is the occurrence number and IPAR is the parent data element location (set by a call to function IN, cf. Section 4.1). If IOCC=0 or IOCC > the number of occurrences subordinate to the spe- cified parent data element occurrence, the new occurrence is inserted after the last such occurrence; the new occurrence becomes the last occurrence. IPAR=0 specifies the last occurrence of the parent data element; if none exists, as much of a parent hierarchy as is necessary will be generated with null values. IPAR is ignored for a record-level data element; a good convention is to set it to zero. If IDE<0, on entry |IOCC| is the location of the desired data element occurrence (set by a call to function IN or IFIRST, cf. Sections 4.1 or 4.2). On return, IOCC is set to +- the location of 4.4 Data Element Access 24 SUBROUTINE INSERT(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) the occurrence following the specified occurrence before the insertion was made. IOCC<0 if the specified occurrence was the last subordinate to some occurrence of its parent, while IOCC=0 if the specified occurrence was at the physical end of the chain of all occurrences of that data element. IPAR is ignored; a good convention is to set it to zero. 4.5 Data Element Access 25 SUBROUTINE REPL(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) 4.5 SUBROUTINE REPL(IDE,IOCC,IPAR,IVALUE,LVALUE,IERR) Arguments INPUT/ IOCC occurrence number or location, depending on sign OUTPUT of IDE (see description) INPUT |IDE| data element ID; sign specifies meaning of IOCC (see description) IPAR parent data element location; ignored if IDE<0 or if IDE identifies a record-level data element (see description) IVALUE array holding data element value; char type value is packed LVALUE length of value in elements, characters, or bits for NUMERIC VECTOR, CHAR, or BIT type data elements, respectively OUTPUT IERR error flag 0 normal return 1 work space exceeded 2 invalid arguments (IDE=0 or |IDE| > number of defined data elements, data element type is node, LVALUE<0) 3 parent data element occurrence does not exist 4 specified occurrence does not exist Description This subroutine replaces the value of an existing data element oc- currence with the new value specified; LVALUE=0 is a null value. The occurrence may be specified in either of two ways, by occurrence num- ber or by location; the sign of ide determines the mode. If IDE>0, IOCC>=0 is the occurrence number and IPAR is the parent data element location (set by a call to function ID, cf. Section 4.1). IOCC=0 specifies the last occurrence of the data element subordinate to the specified parent data element occurrence. IPAR=0 specifies the last occurrence of the parent data element. IPAR is ignored for a re- cord-level data element; a good convention is to set it to zero. If IDE<0, on entry |IOCC| is the location of the desired data ele- ment occurrence (set by a call to function IN or IFIRST, cf. Sections 4.1 or 4.2). On return, IOCC is set to +- the location of the next oc- currence. IOCC<0 if the occurrence just replaced was the last subordi- nate to some occurrence of its parent, while IOCC=0 if the occurrence just replaced was at the physical end of the chain of all occurrences of that data element. IPAR is ignored; a good convention is to set it to zero. 4.6 Data Element Access 26 SUBROUTINE DELETE(IDE,IOCC,IPAR,IERR) 4.6 SUBROUTINE DELETE(IDE,IOCC,IPAR,IERR) Arguments INPUT/ IOCC occurrence number or location, depending on sign OUTPUT of IDE (see description) INPUT |IDE| data element ID; sign specifies meaning of IOCC (see description) IPAR parent data element location; ignored if IDE<0 or if IDE identifies a record-level data element (see description) OUTPUT IERR error flag 0 normal return 1 work space exceeded 2 invalid arguments (IDE=0 or |IDE| > number of defined data elements) 3 parent data element occurrence does not exist 4 specified occurrence does not exist Description This subroutine deletes the specified data element occurrence and all occurrences of data elements subordinate to that occurrence. After the deletion, all higher numbered occurrences of the data element su- bordinate to the specified parent occurrence will be identified by occurrence numbers one smaller than before. The occurrence may be spe- cified in either of two ways, by occurrence number or by location; the sign of ide determines the mode. If IDE>0, IOCC>=0 is the occurrence number and IPAR is the parent data element location (set by a call to function IN, cf. Section 4.1). IOCC=0 specifies the last occurrence of the data element subordinate to the specified parent data element occurrence. IPAR=0 specifies the last occurrence of the parent data element. IPAR is ignored for a re- cord-level data element; a good convention is to set it to zero. If IDE<0, on entry |IOCC| is the location of the desired data ele- ment occurrence (set by a call to function IN or IFIRST, cf. Sections 4.1 or 4.2). On return, IOCC is set to +- the location of the next oc- currence. IOCC<0 if the occurrence just deleted was the last subordi- nate to some occurrence of its parent, while IOCC=0 if the occurrence just deleted was at the physical end of the chain of all occurrences of that data element. IPAR is ignored; a good convention is to set it to zero. 5. Query Processing 27 5. Query Processing This chapter describes the routines used to construct a query and search the database for the set of records satisfying it. The facili- ties provided are analogous to those of the user-level query language described in the user's manual, but take the form of subroutine calls. The routines needed to access records from a retrieved set and manage the system's set list are also described. 5.1 Query Processing 28 SUBROUTINE RPNSET(IQUERY,LQUERY,ISET,IERR) 5.1 SUBROUTINE RPNSET(IQUERY,LQUERY,ISET,IERR) Arguments INPUT/ IQUERY array in which query is being constructed OUTPUT LQUERY length of query in words, incremented on return INPUT ISET set id to be added to query OUTPUT IERR error flag 0 set ID added to query 1 invalid set ID (ISET<=0) Description This subroutine adds the ID of an existing set to an RPN query be- ing formulated. 5.2 Query Processing 29 SUBROUTINE RPNOP(IQUERY,LQUERY,IOP,IERR) 5.2 SUBROUTINE RPNOP(IQUERY,LQUERY,IOP,IERR) Arguments INPUT/ IQUERY array in which query is being constructed OUTPUT LQUERY length of query in words, incremented on return INPUT IOP code for boolean operator to be added to query 1 OR 2 AND 3 AND NOT 4 NOT OUTPUT IERR error flag 0 boolean operator added to query 1 invalid boolean operator code Description This subroutine adds a boolean operator to an prn query being for- mulated. 5.3 Query Processing 30 SUBROUTINE RPNREC(IQUERY,LQUERY,IREL1,IREC1,IREL2,IREC2,IERR) 5.3 SUBROUTINE RPNREC(IQUERY,LQUERY,IREL1,IREC1,IREL2,IREC2,IERR) Arguments INPUT/ IQUERY array in which query is being constructed OUTPUT LQUERY length of query in words, incremented on return INPUT IREL1 code for relational operator modifying IREC1; if IREL2>0, only 1, 3, and 5 are legal values 1 = 2 < 3 > 4 <= 5 >= 6 <> 7 indefinite IREC1 record ID; marks beginning of range if IREL2>0 IREL2 code for relational operator modifying IREC2 0 IREC2 not used 1 = 2 < 4 <= IREC2 record ID marking end of range OUTPUT IERR error flag 0 record ID condition added to query 1 invalid record ID(s) 2 invalid relational code(s) or illegal combination of relational codes for range Description This subroutine adds a record ID condition to an RPN query being formulated. 5.4 Query Processing 31 SUBROUTINE RPNDE(IQUERY,LQUERY,IDE,IREL1,IVAL1,LVAL1,IREL2,IVAL2,LVAL2 5.4 SUBROUTINE RPNDE(IQUERY,LQUERY,IDE,IREL1,IVAL1,LVAL1,IREL2 IREL1 code for relational operator modifying IVAL1; if IREL2>0, only 1, 3, and 5 are legal values 1 = 2 < 3 > 4 <= 5 >= 6 <> 7 indefinite IVAL1 value of data element (may be array); marks beginning of range if IREL2>0; character string values are unpacked (one character/word, left adjusted, blank filled) LVAL1 length of value IVAL1 in elements, characters, or bits for numeric vector, char, or bit type data elements, respectively; LVAL1=0 is a null value IREL2 code for relational operator modifying IVAL2 0 IVAL2 not used 1 = 2 < 4 <= IVAL2 data element value marking end of range LVAL2 length of value IVAL2 OUTPUT IERR error flag 0 data element condition added to query 1 invalid data element ID (IDE<=0 or > number of defined data elements) 2 non-key data element 3 invalid relational code(s) or illegal combination of relational codes for range 4 invalid data element length(s) (LVAL1<0 or LVAL2<=0) Description This subroutine adds a data element condition to an RPN query being constructed. Values are converted to proper key value form, i.e. they are truncated or zero filled to the fixed key length and char type 5.4 Query Processing 32 SUBROUTINE RPNDE(IQUERY,LQUERY,IDE,IREL1,IVAL1,LVAL1,IREL2,IVAL2,LVAL2 values are processed by the user-supplied character code conversion routine kmap before being packed. Relational codes, values, and lengths are ignored for a NODE type data element. 5.5 Query Processing 33 SUBROUTINE EVAL(IQUERY,LQUERY,ISET,LSET,IERR) 5.5 SUBROUTINE EVAL(IQUERY,LQUERY,ISET,LSET,IERR) Arguments INPUT IQUERY array which holds query LQUERY length of query in words OUTPUT ISET ID of set created by query (undefined if LSET=0) LSET >0 number of records in set =0 no records satisfy query, no set created IERR error flag 0 query successfully evaluated 1 query was null (LQUERY<=0) 2 invalid data element ID in query 3 non-key data element in query 4 invalid record ID in query 5 invalid relational code in query or illegal combination of relational codes for range 6 invalid set ID in query 7 invalid boolean operator code in query 8 improper RPN syntax in query 9 work space exceeded 10 index pointer error 11 index page integrity violation Description This subroutine evaluates an RPN query that has been constructed by calls to the RPNXXX routines. If any records satisfy the query, a new retrieved set is created whose records subsequently may be fetched or removed. 5.6 Query Processing 34 SUBROUTINE ORDER(ISET,IDE,N,IERR) [not yet implemented] 5.6 SUBROUTINE ORDER(ISET,IDE,N,IERR) [not yet implemented] Arguments INPUT ISET previously-retrieved set number IDE array of ID's specifying data elements on which ordering is to be done (see description) N length of IDE array OUTPUT IERR error flag 0 set ordered 1 invalid arguments (ISET<=0 or > number of sets existing, n<=0, some lide(j)l=0 or > number of defined data elements) 2 workspace exceeded Description The subroutine orders the records in a retrieved set on the values of one or more data elements. The list of data element ID's is speci- fied in the array IDE of length N. The first element of the array spe- cifies the primary ordering, the second element specifies the seconda- ry ordering, etc. If some IDE(J)<0, the ordering on the data element specified by its absolute value is by descending rather than ascending value. 5.7 Query Processing 35 FUNCTION IFOUND(ISET,IREC) 5.7 FUNCTION IFOUND(ISET,IREC) Arguments INPUT ISET previously-retrieved set number (>0) IREC relative record number within retrieved set (>0) OUTPUT IFOUND >0 ID of specified record =0 specified record or set does not exist Description This function returns the ID of a specified record within a specified previously-retrieved set. It is often helpful to think of IFOUND as a 2-dimensional array and nest its call within a call to FETCH or REMOVE, i.e. CALL FETCH (IFOUND(ISET,IREC),IERR) CALL REMOVE(IFOUND(ISET,IREC),IERR) 5.8 Query Processing 36 SUBROUTINE PURGE(ISET,IERR) 5.8 SUBROUTINE PURGE(ISET,IERR) Arguments INPUT ISET >0 number of set to be purged (presently restricted to the last set created) =0 purge all existing sets OUTPUT IERR error flag 0 operation successful 1 fatal error Description This subroutine purges the last-created or all existing sets, freeing the space occupied in the set list and on the disk file hit. This should be done by an application program as soon as a set is no longer needed. 6. Record Display 37 6. Record Display All or a selected part of a record that has been created or fetched may be displayed by a call to LIST, possibly preceded by a call to LSET. The user-supplied data element output processor OPROC is also described in this chapter since it is called by LIST. 6.1 Record Display 38 SUBROUTINE LIST(IFILE,LINE,MODE,NPRE,IERR) 6.1 SUBROUTINE LIST(IFILE,LINE,MODE,NPRE,IERR) Arguments INPUT IFILE logical unit number of output file LINE length of output lines in characters (excluding carriage control character if present) MODE format of output (see description) NPRE real value format (see description) OUTPUT IERR error flag 0 list successfully completed 1 work space exceeded 2 invalid mode parameter 3 record buffer uninitialized 4 interrupt flag set by interactive user Description This subroutine may be called to list the record currently in the record buffer in one of several formats. There are two general formats available -- display format, suitable for listing a record in human-readable form, and dump format, a machine-readable variant. In display format, a record begins with the pseudo data element REC-ID in the form. followed by the data element occurrences. Each data element occurrence begins on a new line and is numbered if several occurrences of that data element are linked to the same pa- rent occurrence, or if it is a record level data element which occurs more than once. Subordinate data elements are listed following the pa- rent occurrence to which they are linked. If |MODE|=1, the subordinate data elements are indented according to their level in the record structure. If |MODE|=2, there is no indentation. If the line length is insufficient for indentation of a very deep hierarchy, an automatic switch is made to |MODE|=2 at the point where there is no more room. In DUMP format, REC-ID is omitted, there is no indentation, and multiple data element occurrences are not numbered. If |MODE|=3, the output lines are completely filled, with several data element occur- rences on a single line. If |MODE|=4, each data element occurrence starts on a new line to facilitate editing the file with a text edi- tor. In either case, data element values that overrun the end of a line are simply wrapped around to begin a new line. The sign of MODE controls whether or not virtual data elements will be listed. If MODE<0, the virtual's will not be listed, while if 6.1 Record Display 39 SUBROUTINE LIST(IFILE,LINE,MODE,NPRE,IERR) MODE>0, they will be. Further control of which data elements are actually listed is possible using the LSET SUBROUTINE (cf. Section 6.2). NPRE controls the precision or number of significant figures with which real or double type data elements will be listed. See the description of the ENCODE subroutine for further details. 6.2 Record Display 40 SUBROUTINE LSET(IDE,n,IERR) 6.2 SUBROUTINE LSET(IDE,N,IERR) Arguments INPUT IDE array of ID's specifying data elements to be output or not output by LIST (see description) N >0 length of ide array =0 set list to output all data elements. OUTPUT IERR error flag 0 data element display list altered 1 invalid arguments (N<0, some |IDE(J)|=0 or > number of defined data elements) Description This subroutine gives an application programmer control of the data element display list that controls the list subroutine. It is passed a list of data element ID's in the IDE array. If an individual element of IDE is negative, the data element with that ID will not be output by LIST until a subsequent call to LSET is made where some element of IDE contains that ID with a positive sign (or N=0). After BDMS is initialized, but before any call is made to LSET, all data elements will be output by LIST. If LSET is called with n=0, this initial condition is restored. 6.3 Record Display 41 SUBROUTINE OPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user written] 6.3 SUBROUTINE OPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user written] Arguments INPUT/ IVALUE array holding value of data element; format OUTPUT depends on database definition (see description) LVALUE length of value in elements, characters, or bits for NUMERIC VECTOR, CHAR, or BIT type data ele- ments, respectively; LVALUE=0 is a null value INPUT IDE data element ID MWORD length in words of array IVALUE OUTPUT IERR error flag =0 processing complete <>0 fatal error, do not output value Description If the OPROC attribute is specified for a data element in the database definition, this subroutine will be called by list to process each value of that data element before it is output. Normally, this would be done if it were desirable to present the values to a user in a form different from that stored in the record. In such a case, the IPROC subroutine (cf. Section 7.1) probably would perform the inverse transformation on input data. The format of a data element value passed to and returned by this subroutine depends on the value of its OPROC attribute in the database definition. The options are EXTERNAL the value is passed to and returned by OPROC in exter- nal format, i.e. unpacked character string (one charac- ter/word, left-adjusted, blank filled). INTERNAL the value is passed to and returned by OPROC in inter- nal format, i.e. internal binary numeric representati- on, packed character or bit string. CONVERT the value is passed to OPROC in internal format and re- turned by OPROC in external format. The error flag IERR is set to zero before the subroutine is called. If it is set to a non-zero value by OPROC, the data element value will not be output; if an error message is desired, it must be generated by OPROC (via a call to subroutines OUTLN or OUTERR, cf. Sections 9.1 or 9.2). 7. User Extension of the Database Executive and Load Utility 42 7. User Extension of the Database Executive and Load Utility This chapter describes the routines that may be supplied by a user for special processing or validation of data element values appearing in input to the EDITOR or QUERY subsystems of the database executive, or in input to the LOAD utility. See also the descriptions of SPROC (section 3.5), FPROC (section 3.7), KPROC (section 3.8), KMAP (section 3.9), and OPROC (section 6.3). If user processors require initialization or termination (e.g. set- ting up a common block of data element ID's, opening and closing spe- cial files, etc.), The necessary code or subroutine calls may be inserted in the database executive and load utility main programs at the locations indicated by comments. 7.1 User Extension of the Database Executive and Load Utility 43 SUBROUTINE IPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user written] 7.1 SUBROUTINE IPROC(IDE,IVALUE,LVALUE,MWORD,IERR) [user written] Arguments INPUT/ IVALUE array holding value of data element; format OUTPUT depends on database definition, (see description) LVALUE length of value in elements, characters, or bits for NUMERIC VECTOR, CHAR, or BIT type data ele- ments, respectively; LVALUE=0 is a null value INPUT IDE data element ID MWORD length in words of array IVALUE OUTPUT IERR error flag =0 processing complete <>0 fatal error (e.g. value is not valid), do not store value in record Description If the IPROC attribute is specified for a data element in the database definition, this subroutine will be called by EDIT to process each value of that data element appearing in the input data stream before it is stored in the record. IPROC may check the validity of the value and/or modify it. In the latter case, if it were desirable to present the values to a user in a form different from that stored in the record, the OPROC subroutine (cf. Section 6.3) Probably would perform the inverse transformation on output data. The format of a data element value passed to and returned by this subroutine depends on the value of its IPROC attribute in the database definition. The options are EXTERNAL the value is passed to and returned by IPROC in external format, i.e. unpacked character string (one character/word, left-adjusted, blank filled). INTERNAL the value is passed to and returned by IPROC in internal format, i.e. internal binary numeric representation, packed character or bit string. CONVERT the value is passed to IPROC in external format and returned by IPROC in internal format. The error flag IERR is set to zero before the subroutine is called. If it is set to a non-zero value by IPROC, the data element value will not be stored in the record; if an error message is desired, it must be generated by IPROC (via a call to subroutines OUTLN or OUTERR, cf. Sections 9.1 or 9.2). 7.2 User Extension of the Database Executive and Load Utility 44 SUBROUTINE QPROC(IDE,IREL,IVALUE,LVALUE,MWORD,IERR) [user written] 7.2 SUBROUTINE QPROC(IDE,IREL,IVALUE,LVALUE,MWORD,IERR) [user written] Arguments INPUT/ IREL code for relational operator modifying value OUTPUT 1 = 2 < 3 > 4 <= 5 >= 6 <> 7 indefinite IVALUE array holding value of data element; format depends on database definition (see description) LVALUE length of value in elements, characters, or words for NUMERIC VECTOR, CHAR, or BIT type data elements, respectively; LVALUE=0 is a null value INPUT IDE data element ID MWORD length in words of array IVALUE OUTPUT IERR error flag =0 processing complete <>0 fatal error (e.g. value is not valid), do not evaluate query Description If the QPROC attribute is specified for a data element in the database definition, this subroutine will be called by query to process each value of that data element appearing in a query before that query is evaluated. QPROC may check and/or modify the value and/or its relational operator. The format of a data element value passed to and returned by this subroutine depends on the value of its QPROC attribute in the database definition. The options are EXTERNAL the value is passed to and returned by QPROC in external format, i.e. unpacked character string (one character/word, left-adjusted, blank filled). INTERNAL the value is passed to and returned by QPROC in internal format, i.e. internal binary numeric representation, packed character or bit string. CONVERT the value is passed to QPROC in external format and returned by QPROC in internal format. The error flag IERR is set to zero before the subroutine is called. If it is set to a non-zero value by QPROC, the query will not be 7.2 User Extension of the Database Executive and Load Utility 45 SUBROUTINE QPROC(IDE,IREL,IVALUE,LVALUE,MWORD,IERR) [user written] evaluated; if an error message is desired, it must be generated by QPROC (via a call to subroutines OUTLN or OUTERR, cf. Sections 9.1 Or 9.2). 8. Character Manipulation 46 8. Character Manipulation This chapter describes a collection of character manipulation routines that may be of use to a programmer writing user processors or using BDMS routines directly. Included are subroutines to - pack and unpack character strings - move packed character strings - convert scalar and vector numeric values between character string and internal binary representation 8.1 Character Manipulation 47 SUBROUTINE PACKC(IPCK,ICHAR,IUNPCK,NCHAR) 8.1 SUBROUTINE PACKC(IPCK,ICHAR,IUNPCK,NCHAR) Arguments INPUT/ ICHAR starting character position in IPCK; incremented OUTPUT by lNCHARl on return (ICHAR=1 is the first character in IPCK(1)) INPUT IUNPCK unpacked character array |NCHAR| number of characters (words) in IUNPCK to be packed; sign controls filling of last word of IPCK (see description) OUTPUT IPCK packed character array Description This subroutine packs |NCHAR| characters from the array IUNPCK into the array IPCK, starting at character position ICHAR. The format of IUNPCK is one character/word, left adjusted, blank filled (fortran a1 format). On return, ICHAR is incremented by |NCHAR| to point to the next available character position in IPCK. If NCHAR>0, the last word written in IPCK will be blank filled. If NCHAR<0, the unused character positions in the last word written in IPCK will not be modified. 8.2 Character Manipulation 48 SUBROUTINE UNPCKC(IPCK,ICHAR,IUNPCK,NCHAR) 8.2 SUBROUTINE UNPCKC(IPCK,ICHAR,IUNPCK,NCHAR) Arguments INPUT IPCK packed character array ICHAR starting character position in IPCK; (ICHAR=1 is the first character in IPCK(1)) NCHAR number of characters to be unpacked OUTPUT IUNPCK unpacked character array Description This subroutine unpacks NCHAR characters from the array IPCK, starting at character position ICHAR, into the array IUNPCK. The format of IUNPCK is one character/word, left adjusted, blank filled (fortran a1 format). 8.3 Character Manipulation 49 SUBROUTINE MOVEC(IPCK,ICHAR,JPCK,JCHAR,NCHAR) 8.3 SUBROUTINE MOVEC(IPCK,ICHAR,JPCK,JCHAR,NCHAR) Arguments INPUT/ ICHAR starting character position in IPCK; incremented OUTPUT by |NCHAR| on return (ICHAR=1 is the first character in IPCK(1)) INPUT JPCK input packed character string JCHAR starting character position in JPCK (JCHAR=1 is the first character in JPCK(1)) |NCHAR| number of characters to be moved; sign controls filling of last word of IPCK (see description) OUTPUT IPCK output packed character string Description This subroutine moves |NCHAR| characters from the packed array JPCK, starting at character position JCHAR, into the packed array IPCK, starting at character position ICHAR. On return, ICHAR is incremented by |NCHAR| to point to the next available character position in IPCK. If NCHAR>0, the last word written in IPCK will be blank filled. If NCHAR<0, the unused character positions in the last word written in IPCK will not be modified. 8.4 Character Manipulation 50 SUBROUTINE DECODE(IVALUE,ITYPE,IUNPCK,NCHAR,IERR) 8.4 SUBROUTINE DECODE(IVALUE,ITYPE,IUNPCK,NCHAR,IERR) Arguments INPUT ITYPE code for type of value 0 decimal integer 1 integer 2 real 3 double precision real (not yet implemented) IUNPCK array holding unpacked character representation of value (one character/word, left-adjusted, blank filled); see description for format NCHAR length of IUNPCK in characters (words) OUTPUT IVALUE decoded numeric value in internal binary representation (two words if double precision); this may be a location within IUNPCK IERR error flag 0 conversion successful 1 invalid input character string 2 invalid arguments (ITYPE<0 or >3, NCHAR<1) Description This subroutine converts a numeric value in character string form into its internal binary representation. The value of an integer type data element must be a series of digits preceded optionally by a + or - sign. The value may be expressed as a binary, octal, decimal, or hexadecimal number; the base is specified by a single letter following the number as follows B binary O or Q octal D or absent decimal H or Z hexadecimal The set of allowable digits is that subset of (0-9, A-F) appropriate for the base chosen. If ITYPE=0, the number must be decimal. The value of a real or double type data element must be a series of decimal digits preceded optionally by a + or - sign. It may, in addition, have a decimal point and/or a power-of-ten multiplier expressed as an e followed by the decimal integer exponent with an optional sign. Blanks anywhere within a numeric value are ignored. Numeric values must not exceed the maximum size and precision that can be stored as a single precision number (or double precision number for double type) by the computer being used. 8.5 Character Manipulation 51 SUBROUTINE DECODV(IVALUE,NELEM,ITYPE,IUNPCK,NCHAR,IERR) 8.5 SUBROUTINE DECODV(IVALUE,NELEM,ITYPE,IUNPCK,NCHAR,IERR) Arguments INPUT/ NELEM on entry, maximum number of elements that may be OUTPUT placed in IVALUE; on return, the actual number of elements in value INPUT ITYPE code for type of value 0 decimal integer 1 integer 2 real 3 double precision real (not yet implemented) IUNPCK array holding unpacked character representation of value (one character/word, left-adjusted, blank filled); see description for format NCHAR length of IUNPCK in characters (words) OUTPUT IVALUE array holding decoded numeric vector value in internal binary representation (two words/element if double precision) IERR error flag 0 conversion successful 1 invalid input character string 2 invalid arguments (ITYPE<0 or >3, NCHAR<1) 3 not enough room in array IVALUE for decoded vector value Description This subroutine converts a numeric vector value in character string form into its internal binary representation. The allowable formats for individual elements are those described for subroutine DECODE (cf. Section 8.4). The elements are separated by commas in the input character string. 8.6 Character Manipulation 52 SUBROUTINE ENCODE(IVALUE,ITYPE,IUNPCK,NCHAR,NPRE,IERR) 8.6 SUBROUTINE ENCODE(IVALUE,ITYPE,IUNPCK,NCHAR,NPRE,IERR) Arguments INPUT/ NCHAR on entry, maximum number of characters that may be OUTPUT placed in IUNPCK; on return, actual number of characters in IUNPCK INPUT IVALUE numeric value in internal binary representation (two words if double precision); this may be a location within IUNPCK ITYPE code for type of value 1 integer 2 real 3 double precision real (not yet implemented) NPRE required precision or number of significant figures for real value (see description) OUTPUT IUNPCK array holding unpacked character representation of value (one character/word, left-adjusted, blank filled); see description for format IERR error flag 0 conversion successful 1 not enough space in IUNPCK 2 invalid argument (ITYPE<1 or >3) Description This subroutine converts a numeric value in internal binary form into its character string representation. The format of a real number is controlled by the value of NPRE as follows NPRE>=0 is interpreted as the required number of places after the decimal point. F format will be used if value>=10**-NPRE and if NCHAR is large enough to allow IUNPCK to hold the sign (if necessary) and number with NPRE places after the decimal point. Otherwise E format will be used, but if there is not space for one place before and NPRE places after the decimal point plus the sign and exponent, IERR=1 will be returned. NPRE<0 is interpreted as minus the required number of significant digits. F format will be used if 0.1<=value<=10**|NPRE|. Otherwise, E format will be used with one place before and |NPRE|-1 places after the decimal point. If there is not space for |NPRE| significant digits plus the sign and exponent, IERR=1 will be returned. 8.7 Character Manipulation 53 SUBROUTINE ENCODV(IVALUE,NELEM,ITYPE,IUNPCK,NCHAR,NPRE,IERR) 8.7 SUBROUTINE ENCODV(IVALUE,NELEM,ITYPE,IUNPCK,NCHAR,NPRE,IERR) Arguments INPUT/ NCHAR on entry, maximum number of characters that may be OUTPUT placed in IUNPCK; on return, actual number of characters in IUNPCK INPUT IVALUE array holding numeric vector value in internal binary representation (two words/element if double precision) NELEM number of elements in value ITYPE code for type of value 1 integer 2 real 3 double precision real (not yet implemented) NPRE required precision or number of significant figures (see description) OUTPUT IUNPCK array holding unpacked character representation of value (one character/word, left-adjusted, blank filled); see description for format IERR error flag 0 conversion successful 1 not enough space in IUNPCK 2 invalid argument (ITYPE<1 or >3) Description This subroutine converts a numeric vector value in internal binary form into its character string representation. The format of a real number is controlled by the value of NPRE as described for subroutine ENCODE (cf. section 8.6). The elements are separated by commas in the output character string. 9. Utility Routines 54 9. Utility Routines This chapter describes several utility routines that may be of use to a programmer writing user processors or using BDMS routines directly. Included are subroutines to - output messages - linearize an index - read a linearized index one entry at a time 9.1 Utility Routines 55 SUBROUTINE OUTLN(IARRAY,NCHAR,IFILE,LNMAX,ISTAT) 9.1 SUBROUTINE OUTLN(IARRAY,NCHAR,IFILE,LNMAX,ISTAT) Arguments INPUT IARRAY array holding either packed or unpacked character string to be output lNCHARl length of string in characters; sign specifies format (see description) IFILE logical unit number of output file LNMAX maximum output line length in characters OUTPUT ISTAT status flag 0 normal return 1 user wishes output to be terminated (signal from terminal interface routine) Description This subroutine outputs a message to a specified file. The message may be either a packed or unpacked character string; the format is specified by the sign of NCHAR. If NCHAR<0, the message is assumed to be unpacked (one character/word, left-adjusted, blank filled), while if NCHAR>0, it is assumed to be packed. 9.2 Utility Routines 56 SUBROUTINE OUTERR(IPCK,NCHAR,I,IFILE,LNMAX,ISTAT) 9.2 SUBROUTINE OUTERR(IPCK,NCHAR,I,IFILE,LNMAX,ISTAT) Arguments INPUT IPCK array holding packed error message NCHAR length of message in characters I >0 numeral to be appended to end of message =0 no numeral appended IFILE logical unit number of output file LNMAX maximum output line length in characters OUTPUT ISTAT status flag 0 normal return user wishes output to be terminated (signal from terminal interface routine) Description This subroutine appends ***ERROR*** to the beginning of a packed error message and optionally appends a numeral to its end before calling OUTLN to output the message to a specified file.