Enscribe Programmer’s Guide Abstract This manual describes how to create, access, and load the five types of disk files supported by the Enscribe software. HP Part Number: 520369-009 Published: June 2014 Edition: Enscribe 1.
© Copyright 1999, 2014 Hewlett-Packard Development Company L.P.. Legal Notices Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Contents What’s New in This Manual.........................................................................10 Manual Information................................................................................................................10 New and Changed Information................................................................................................10 Changes to the 520369-009 Version of the Manual...............................................................
No Automatic Update........................................................................................................34 Alternate Keys in a Key-Sequenced File.................................................................................34 Alternate Keys in an Entry-Sequenced File.............................................................................34 Alternate Keys in a Relative File............................................................................................
Appending to the End of a File............................................................................................66 6 Key-Sequenced Files.................................................................................68 Enscribe Key-Sequenced Files...................................................................................................68 Applicable System Procedures..................................................................................................68 Types of Access.......
Blocks............................................................................................................................125 Disk Extent Size...............................................................................................................125 File Creation Examples.....................................................................................................125 Accessing Entry-Sequenced Files.........................................................................................
Loading a Partitioned, Alternate-Key File..................................................................................163 A ASCII Character Set...............................................................................165 B Block Formats of Structured Files...............................................................169 C Action of Current Key, Key Specifier, and Key Length...................................180 Variable Definitions.................................................................
Figures 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 A Record With Three Fields in a Structured File....................................................................25 Primary Keys in Structured Files..........................................................................................26 An Alternate-Key Field......................................................................................................
11 12 Locking Modes..............................................................................................................150 ASCII Character Set.......................................................................................................165 Examples 1 Sample Relative File.......................................................................................................
What’s New in This Manual Manual Information Abstract This manual describes how to create, access, and load the five types of disk files supported by the Enscribe software. Product Version Enscribe 1.0 Supported Release Version Updates (RVUs) This publication supports J06.03 and all subsequent J-series RVUs, H06.03 and all subsequent H-series RVUs, and G06.27 and all subsequent G-series RVUs until otherwise indicated by its replacement publications.
Changes to the 520369-007 Version of the Manual • Added a note about the Restrictions on Partitioned Unstructured files (page 62). Changes to the 520369-006 Version of the Manual • Added new procedures for 64-bit to File-System Procedures (page 39).
Changes to the 520369-004 Version of the Manual • These topics have been updated to support Enscribe 64 partitions which is introduced as of H06.22 and J06.11 and later RVUs.
Changes to the G06.18 Manual • Added a caution note in Section 7 (Queue Files) to advise the user that the use of queue files with multiple sub-queues can cause high utilization of CPU resources by the disk process and affect performance. • Added a Performance Considerations section to discuss the practical limits on how many processes should be used when multiple servers (dequeuing processes) are used on a Queue File. • Changed a table entry to read “4 GB – 4 KB”.
About This Manual This manual documents the Enscribe database record manager. It is written for programmers, database designers, and analysts whose job is to design, develop, and maintain database applications to be executed on HP NonStop™ systems.
UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown.
CALL STEPMOM ( process-id ); If there is no space between two items, spaces are not permitted. In the following example, there are no spaces permitted between the period and any other items: $process-name.#su-name Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections.
{ } Braces. A group of items enclosed in braces is a list of all possible items that can be displayed, of which one is actually displayed. The items in the list might be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: obj-type obj-name state changed to state, caused by { Object | Operator | Service } process-name State changed from old-objstate to objstate { Operator Request. } { Unknown.
1 Introducing the Enscribe Record Manager Overview and Features SPR Requirements for Increased Enscribe Limits for the H06.28/J06.17 Release As of the H06.28 and J06.17 RVUs, format 2 legacy key-sequenced 2 (LKS2) files with increased limits, format 2 standard queue files with increased limits, and enhanced key-sequenced (EKS) files with increased limits are introduced. EKS files with increased limits support 17 to 128 partitions along with larger record, block, and key sizes.
This manual describes the use of the Enscribe software with the DP2 disk process.
• Extents: a unit of storage allocation for a file to be allocated as contiguous space on disk. Each extent consists of some specified number of 2048-byte pages. • Block: the unit of physical I/O. A block consists of one or more logical records plus some control information for structured files. When you are using sequential block buffering, a block is the unit of transfer between the file system and the disk process. The block size is specified as a number of bytes.
number and record number, external to the data record, specifying the record's storage location within the file. For relative files, the primary key is an ordinal number, again external to the data record, denoting the record's position within the file. In addition to access by primary key, you can specify alternate keys for key-sequenced, entry-sequenced, and relative files. Queue files cannot have alternate keys.
(SCF) to label the disk, by estimating how many files you want each directory extent to hold. The system translates this to an approximate extent size when it creates the actual directory file. The actual number of files that fit in a directory extent varies according to the types of files involved, because some file types need larger file labels than other types. Therefore, the actual capacity might not always be precisely what you specified.
Operations on Files Common file operations include creating files, describing record formats, loading files, and manipulating records.Table 2 (page 23) summarizes the record management functions that are most commonly used with Enscribe files. Creating Files You create disk files either by calling the FILE_CREATE_ system procedure or by issuing FUP commands: • Programmatic creation of disk files is accomplished by supplying the appropriate parameters to the FILE_CREATE_ or FILE_CREATELIST_ procedure.
Table 2 Record Management Functions Summary (continued) Function Description Procedures UNLOCKREC, UNLOCKFILE, WRITEUPDATEUNLOCK Update Updates a record in a random position in a file. FILE_READUPDATE64_, FILE_WRITEUPDATE64_, READUPDATE, WRITEUPDATE Comparison of Structured File Characteristics The Enscribe product provides four types of structured files: key-sequenced files, queue files, entry-sequenced files, and relative files.
2 Positioning Within Structured Files Structured File Records A record in an Enscribe structured file consists of one or more data fields, as illustrated in Figure 1 (page 25) Figure 1 A Record With Three Fields in a Structured File CUSTOMER Record Name Address Region Fields Each record in a structured file is uniquely identified among other records in that file by the value of its primary key.
Figure 2 Primary Keys in Structured Files Key-Sequenced Files: Name Address Region Primary Key Queue Files: Mfg. Site Timestamp Description Part Number Primary Key Entry-Sequenced Files: Name Account Number Primary Key Relative Files: Item Description Primary Key Except for queue files, structured files can also include up to 255 alternate-key fields.
By using alternate-key values, you can process a subset of records that all contain the same value in a particular data field. For example, using Figure 4 (page 27) again, the REGION field is defined as an alternate key and the value CENTRAL provides you with access to two records. Figure 4 Using Key Values to Locate Records In a key-sequenced file, only one record can have the primary-key value JONES, J.A. JONES, J.A. DAYTON, OHIO CENTRAL MOORE, Q.A. LOS ANGELES, CALIFORNIA WESTERN SMITH, S.A.
Figure 5 Access Paths Employee Number Records in Order by EMPLOYEE NUMBER Access Path RYAN KING C A 005 008 010 011 FISH ADAMS BROWN STEVENS D B A C 012 013 OBRIEN MASTERS D C 016 WATSON B ADAMS B A 005 002 013 BROWN FISH KING MASTERS D A C D C 011 OBRIEN RYAN STEVENS 016 WATSON B 002 Access Path KING A 010 008 016 BROWN ADAMS WATSON A B B 001 011 RYAN STEVENS C C 013 005 MASTERS FISH C D 012 OBRIEN D 012 001 Records in Order by DEPT Access Path Dept 001 002 Access
Figure 6 Key Fields and Key Specifiers Primary-Key Field PART NO. Alternate-Key Fields DESCRIPTION ON-HAND 0 System-Defined Key Specifier PRICE LOCATION OH LO VENDOR VN Application-Defined Key Specifiers Current Key Value and Current Position The current key value defines a file's current position. You can set the current key value explicitly by calling the FILE_SETKEY_, FILE_SETPOSITION_,POSITION or KEYPOSITION procedure.
Exact mode selects only those records whose access path key value matches the supplied key value exactly. Figure 8 (page 30) shows examples of subsets returned by each positioning mode. The positioning mode, comparison length, and current key value supplied in a KEYPOSITION procedure call together specify a subset of records and the first record in that subset to be accessed. The subset of records in the current access path can consist of all, part, or none of the records in a file.
NOTE: For entry-sequenced and relative files, generic positioning by the primary key is the equivalent of exact positioning. Exact Positioning Exact positioning means the only records accessed are those whose key field, as designated by the current key specifier, contains a value that is both: • exactly as long as the specified comparison length • equal to the current key value. When the current key no longer matches, an EOF indication is returned. Exact positioning accesses no more than one record.
Figure 9 Alternate-Key Implementation Primary Data file Record Format: Alternate-Key Primary-Key PART NO. DESCRIPTION 0 Key Specifier ON-HAND PRICE LOCATION OH LO VENDOR VN Alternate-Key File Record Format (Access Path OH): OH ON-HAND PART NO. Key Specifier Field Value PrimaryKey Value Sample Data in Primary Data File: 0115 TOASTER 20 12.50 C TWR 0201 T.V. SET 5 200.00 A ACME 0205 PHONOGRAPH 52 55.00 B ACR 0206 RADIO 97 9.95 A BROWN 0310 FRY PAN 19 37.
Key Specifier To identify a particular data field as an alternate-key access path, you must differentiate it from other fields by assigning it a 2-byte key specifier (such as OH for the on-hand field). You supply the 2-byte key specifier when you create the primary file. Key Offset For each alternate key you must specify its offset from the start of the record (where the alternate-key field begins) when creating or altering characteristics of the primary file.
No Automatic Update You can designate that the alternate-key file contents for an alternate key not be automatically updated by the system when the value of an alternate-key field changes. Two reasons for doing so are: • Certain fields might not be referred to until a later date. Therefore, they can be updated in a batch (one-pass) mode more efficiently. • A field can have multiple null values.
Here are two reasons why you do not want to have separate alternate-key files: • System control-block space is allocated for each opening of an alternate-key file (that is, each opening of the primary file). • A file control block (FCB) is allocated for the first opening of an alternate-key file. Figure 10 (page 35) illustrates the record structure of an alternate-key file.
Record Locking Requests and Alternate Key Files An application request to lock a record requires a file number as input. The file number is necessarily that of the primary file, since the application has no file number for any alternate key file. If the request is FILE_READ[UPDATE]LOCK64_, READ[UPDATE]LOCK, FILE_LOCKREC64_ or LOCKREC, Enscribe locks the referenced primary file record but does not lock any alternate key records.
SETMODE 4,6 and 4,7 can help applications to handle the asynchronous locking of alternate key records caused by transaction aborts. With SETMODE 4,6, a process whose write to a primary file collides with another process's system-generated lock of an aborting transaction will wait until the system-generated lock is released. This approach makes the lock contention invisible to the application in exchange for the possibility of an occasional lock wait.
Figure 11 Relational Access Among Structured Files Order No. Name Date 0021 JONES, J.A. 10-17-95 0022 ADAMS, A.B. 10-18-95 0023 WATSON, N.A. 10-20-95 0030 SMITH, C.J. 10-24-95 0032 0034 BROWN, E.G. CARTER, J.M. 10-26-95 11-07-95 Total Order Header File Name Customer File Address Region ADAMS, A.B. LOS ANGELES, CA 5 BROWN, E.G. PITTSBURGH, PA 2 CARTER, J.M. PLAINS, GA 3 JONES, J.A. LAS VEGAS, NEV 4 SMITH, C.J. BOSTON, MASS 1 WATSON, N.A. CUPERTINO, CA 5 Item Order No.
3 System Procedures File-System Procedures You can use file-system procedures or a separate set of sequential I/O (SIO) procedures to create and access Enscribe files. The two sets of procedures are mutually exclusive; with regard to any given file, use one set or the other. Table 4 (page 39) summarizes the functions of the applicable file-system procedures. Table 4 File-System Procedures Procedure Description AWAITIO[X] Waits for completion of an outstanding I/O operation pending on an open file.
Table 4 File-System Procedures (continued) 40 Procedure Description FILE_READUPDATE64_ Returns the record indicated by the current key value; FILE_READUPDATE64_ is used to randomly read an open file. FILE_READUPDATELOCK64_ Is the same as FILE_READUPDATE64_, but it locks the record before reading it. FILE_RENAME_ Changes the name of an open file. If the file is temporary, causes the file to be made permanent. Supersedes RENAME.
Table 4 File-System Procedures (continued) Procedure Description LOCKREC Locks a record (or a set of records if generic locking is enabled for a key-sequenced file) in an open disk file so that other processes cannot access it. POSITION Sets position by primary key within an entry-sequenced or relative file; defines a subset of the file for subsequent access, by setting the current position, access path, and positioning mode; also can specify new current position within an unstructured file.
File Number Parameters All of the file-system procedures except DISK_REFRESH_, FILE_CREATE_, FILE_GETINFOBYNAME_, FILE_OPEN_, FILE_PURGE_, FILENAME_FINDNEXT64_, and FILENAME_FINDNEXT_, use the filenum parameter returned by the FILE_OPEN_ procedure to identify which file the call refers to. The FILE_CREATE_, FILE_GETINFOBYNAME_, FILE_OPEN_, and FILE_PURGE_ procedures refer to the file by filename; the LASTRECEIVE and FILE_REPLY64_, REPLY procedures always refer to the $RECEIVE file.
= (CCE) The operation was successful. Error Numbers An error number is associated with each call completion. As shown in Table 5, the error numbers fall into three major categories. The setting of the condition code indicates the general category of the error associated with a completed call. Table 5 Error Number Categories Error Number Condition Code Category 0 = (CCE) No error. The operation executed successfully. 1-9 > (CCG) Warning.
External Declarations Like all other procedures in an application program, the file-system procedures must be declared before being called. These procedures, however, are declared externally to the application program in a system file named $SYSTEM.SYSTEM.EXTDECS0. The compiler command SOURCE, specifying this file, should be included in the source program after the global declarations but before the first call to one of these procedures, as in this example: global-declarations ?SOURCE $SYSTEM.SYSTEM.
• The OPEN^FILE procedure lets an application alter the characteristics of SIO operations when a file is opened. Also, the SET^FILE procedure makes this possible before or after the file is opened. Some optional characteristics are: ◦ Record blocking and deblocking ◦ Duplicative file capability, where data read from one file is automatically echoed to another file ◦ An error-reporting file, where all error messages are directed.
4 General File Creation and Access Information This chapter describes general file creation and access information for all Enscribe file types. File Creation This subsection discusses certain parameters that you can specify and capabilities that you can enable when creating Enscribe files. File Codes When creating an Enscribe disk file, you can assign it an arbitrary numeric file code. This code is typically used to categorize files according to the kind of information they contain.
Both file formats are supported. The user usually does not have to specify the format. If left unspecified, the system chooses format 1. File format 2 is required when: • An enhanced key-sequenced (EKS) file is used. EKS files are supported in J06.11 and H06.22 and later RVUs. • A key-sequenced file with increased limits is used. To use increased Enscribe limits, the minimum RVUs are H06.28 and J06.17 with specific SPRs. For a list of the required H06.28/J06.
Table 7 Comparison of Format 1 Versus Format 2 Files (continued) File Attribute or Procedure Call Format 1 Files Format 2 Files File Types All All Non-Key-Sequenced Primary Key Value in Alternate Key Records 4-byte (32-bit) primary-key value 8-byte (64-bit) primary-key value 1 For unstructured format 1 files in 512 byte disks such as ESS/JBOD, the pri-extent-size and sec-extent-size must both be divisible by 14. If the file is unpartitioned, DP2 automatically rounds up the size.
if programs use the 32-bit file-system attributes that describe them. In particular, the End of File (EOF) and Maximum File Size attributes cannot describe files greater than approximately 2 GB (as a signed integer) or 4 GB (unsigned) in the 32-bit form, so the 64-bit forms should be used instead. EKS key-sequenced files with increased limits can have up to 128 partitions and the maximum possible size is ~127 TB. Queue files cannot be partitioned.
Even when AC compression is enabled for a file, not every AC record is compressed. Also, some limits are imposed to keep the space used for recording the compression from becoming greater than the unchanged fragments that would be omitted. • If the record length is less than a certain limit, the disk process does not compress the record. This limit is subject to change from release to release. • If an update changes the record length, the disk process does not compress the AC record.
File Access The following paragraphs describe different ways to access Enscribe files. Opening and Closing Files You use the FILE_OPEN_ procedure to establish communication with a permanent disk file: LITERAL name^length = 23, syncdpth = 1; LITERAL usebigkeys = 1D; INT error; INT filenum; STRING .filename [0:22] := "$VOL1.MYSUBVOL.
Read Reverse With Structured Files You can read Enscribe structured files (key-sequenced, queue, entry-sequenced, and relative) sequentially in descending key or record number order. You enable this feature by setting a bit in the options parameter of FILE_SETKEY_ or the positioningmode parameter of the KEYPOSITION procedure call.
Next-record pointer = record number or address that follows the current-record pointer. For entry-sequenced files, the record pointers contain a record address; for relative files, the record pointers contain a relative record number. The contents of the current-record and next-record pointers are accessible with the FILE_GETINFOLIST_ system procedure.
record, a disk write by another process may have occurred between your read call and the CONTROL 27 call. Because the automatic resending of a CONTROL 27 request could be queued behind a disk write request by another process (thus missing it), the file open through which you issue the CONTROL 27 call should have a sync depth of 0.
be indicated by error 122. Buffered cache is the default for audited files because TMF can recover committed, buffered updates lost due to a system failure. NOTE: Be careful in using the combination of nonaudited, buffered files with a sync-depth of 0 (no checkpointing). This combination provides high-performance updates but might compromise data integrity in certain situations. Restartable applications (old master to new master, for example) are not a concern.
Reading the buffered data does not use the disk process until: • The block has been traversed, at which time the disk process fetches another block. • An intervening FILE_SETPOSITION_, FILE_SETKEY_, POSITION, or KEYPOSITION is performed. In this case, the next READ request causes a new block to be fetched.
specification in the buffer. Thus the benefits and limitations of sequential block buffering apply to the alternate-key file I/O, not to the primary file I/O. Shared File Access For sequential block buffering, the file usually should be opened with protected or exclusive access. Combining sequential block buffering and shared access is allowed, but be aware that this combination can cause concurrency problems.
in an application that requires fast unstructured access and derives no real benefit from the use of cache memory. Refreshing the End-of-File (EOF) Pointer Each file's end-of-file (EOF) pointer is kept in its file control block (FCB) in main memory. To maximize performance, the EOF pointer is normally written to the file's disk label only when needed. Although refreshing the file's disk label only under limited conditions maximizes system performance, certain considerations should be taken into account.
None of these actually physically erases data. Instead, they all reset various pointers to indicate that either: • The file no longer exists (FUP PURGE command or the FILE_PURGE_ system procedure) • The file exists but contains no data (FUP PURGEDATA command or CONTROL 20 system procedure) In the first case, if the file space is subsequently reallocated to another file, the new file's owner can read the logically purged data. For security reasons, you might want to avoid this.
5 Unstructured Files Enscribe Unstructured Files An Enscribe unstructured file is essentially a byte array on disk that starts at byte address zero and continues sequentially upward through whatever byte address is identified by the end-of-file (EOF) pointer. The file system imposes no further structure on such files. How data is grouped into records and how records are ordered within the file are the responsibility of the application process.
Creating Unstructured Files You create Enscribe unstructured files with the File Utility Program (FUP) or by calling either the FILE_CREATE_ procedure or the FILE_CREATELIST_ procedure. When you create an unstructured file, you must consider the buffer size and the disk extent sizes. Buffer Size The buffer size attribute lets you define the internal buffer size to be used by the disk process when accessing an unstructured file. The buffer size attribute can be any of these: 512 bytes, 1 KB, 2 KB, or 4 KB.
maximum number of extents to be allocated for the file (16 or more for nonpartitioned unstructured files). If you do not specify extent sizes, both the primary and secondary extent sizes default to one page. If you do not specify a maximum number of extents, MAXEXTENTS defaults to 16. For nonpartitioned unstructured files, you can change the MAXEXTENTS value dynamically during program execution by using either the SETMODE 92 system procedure or the FUP ALTER command.
namelen, file^code, pri^extent, sec^extent, , file^type, , , buffer^size); Accessing Unstructured Files This subsection discusses the pointers and different types of access associated with unstructured files. File Pointers Three major pointers are associated with an Enscribe unstructured file: Current-record pointer Specifies the RBA of the location that was most recently read from or written to. Next-record pointer Specifies the RBA of the next location to be read from or written to.
a FUP ALTER command. When you do so, however, whatever you designate applies until you reverse it with a subsequent FUP ALTER command or until the file is closed. Table 8 summarizes the values that the various pointers are set to upon conclusion of the particular system procedure. In this table, count is the transfer count specified by the read or write procedure call. If the file is an odd unstructured file, the value specified by count is the number of bytes transferred.
If the file is an odd unstructured file, both the number of bytes transferred and the amount by which the pointers are incremented are exactly the number of bytes specified by the write count or read count parameter. If the file is an even unstructured file, the values of the write count and read count parameters are rounded up to an even number before the transfer takes place and the file pointers are incremented by the rounded-up value.
Figure 12 Example of Encountering the EOF Read #1 (512 Bytes) Read #2 (512 Bytes) 0 512 Relative Byte Address Read #3 (512 Bytes) 1024 Read #8 (512 Bytes) 1536 3584 Read #9 (CCG) 4096 (EOF) Each of the first eight READ calls transfers 512 bytes into the designated buffer, returns a num^read of 512, and sets the condition code to CCE (operation successful).
The next-record pointer now contains -1. This indicates to the file system that subsequent WRITE calls should append to the end of the file. This WRITE call, if issued immediately after the FILE_SETPOSITION_ -1 call, appends 512 bytes to the end of the file: CALL WRITE ( filenum, buffer, 512, num^written ); The file system transfers 512 bytes from the designated buffer to the relative byte address pointed to by the EOF pointer.
6 Key-Sequenced Files Enscribe Key-Sequenced Files NOTE: As of the H06.28 and J06.17 RVUs, format 2 legacy key-sequenced 2 (LKS2) files with increased limits, format 2 standard queue files with increased limits, and enhanced key-sequenced (EKS) files with increased limits are introduced. EKS files with increased limits support 17 to 128 partitions along with larger record, block, and key sizes.
• FILE_READ64_, FILE_READLOCK64_, FILE_READUPDATE64_, FILE_READUPDATELOCK64_, READ[X], READLOCK[X], READUPDATE[X], READUPDATELOCK[X] • FILE_WRITE64_, FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITE[X], WRITEUPDATE[X], WRITEUPDATEUNLOCK[X] • FILE_GETINFO_, FILE_GETINFOLIST_, FILE_GETINFOBYNAME_, FILE_GETINFOLISTBYNAME_ • SETMODE, CONTROL, FILE_CONTROL64_ Types of Access Key-sequenced files can be accessed either sequentially or randomly.
Typically, in a changing database most blocks will be approximately two-thirds full at any given time. When using the FUP LOAD command to load data into a key-sequenced file, you can specify how much empty space to provide for future growth.
• When creating an EKS file, the primary extent size of the primary partition is adjusted based on the block length of the file. The secondary extent size for the primary partition is ignored. • When accessing the primary partition of an EKS file in unstructured mode, reads on the file return FEEOF (1) and writes return FEFILEFULL (45). This is because the meta data stored in the primary partition cannot be accessed by non-privileged applications.
Table 9 Comparison of LKS Files, LKS2 Files, Standard Queue Files, EKS Files, and EKS Files with Increased Limits (continued) LKS and Standard Queue File Attributes Allowed Values LKS2 and Standard Queue File Attributes Allowed Values Block Length 512, 1 KB, 2 KB, 4 KB 512, 1 KB, 2 KB, 4 KB (With increased limits, 32 KB is supported.) Record Length Format 1: Up to 4062 Up to 4040 (With Up to 4040 Format 2: Up to 4040 increased limits, up to 27,648.
A customer application revolves around the use of an Enscribe key-sequenced file with 16 partitions. Over time the number of requestors for the application has increased and I/O on the key-sequenced file has become a bottleneck. The customer decides to increase the number of partitions from 16 to 64 in order to provide higher disk I/O throughput and to also increase the maximum size of the database from approximately 16 GB to approximately 200 GB.
record that is longer than the defined maximum record length, the file system rejects the operation and returns an error 21 (illegal count). Blocks A block is the unit of information transferred between the disk process and the disk (or, when you are using sequential block buffering, between the disk process and the process file segment). A block consists of one or more logical records and, in the case of key-sequenced files, associated control information.
For key-sequenced files and any of their partitions, you can change the MAXEXTENTS value dynamically during program execution using either the SETMODE 92 system procedure or the FUP ALTER command. Primary Keys For key-sequenced files, you must define both the offset from the beginning of the record where the primary-key field begins and the length of the key field.
• If there is enough similarity among records that the first records of successive blocks have similar primary-key values, then key compression of index blocks is also desirable. • Key compression in data blocks is useful for alternate-key files where several alternate keys tend to have the same value. Index Compaction A separate mechanism is also automatically used to make all index records more compact regardless of whether key compression is in effect.
If you designate the primary extent size as 5000 pages and the secondary extent size as 2000 pages, then the primary extent will accommodate 65,000 credit records and each secondary extent will accommodate 26,000 additional credit records. When all 16 extents are eventually used, the file will accommodate a total of 455,000 credit records. The primary-key length is 34 bytes.
Byte Offset: 0 2 partno 32 descr 40 price 42 avail-qty Primary-Key Field 46 loc Alternate-Key Field LO 54 vendor Alternate-Key Field VN You could create the file by using these FUP commands: volume $store1.
INT .
value^list.altkey^descr[1].null^value := 0; value^list.altkey^descr[1].attributes := 0; value^list.num^alt^key^files := num^altkey^files; value^list.name^length^info[0].file^name^len := 6; value^list.file^names ':=' "INVALT"; ERROR := FILE_CREATELIST_ (filename:name^length,namelen, item^list, item^list^len, value^list, $LEN(value^list), error2); END; When you use a system procedure to create your key-sequenced file, you must create your alternate key files separately.
PROC DO^THE^WORK MAIN; BEGIN LITERAL name^length = 3, num^altkeys = 2, num^altkey^files = 1, item^list^len = 14; INT error; INT error2; INT namelen; STRING .filename [0:name^length-1] := "INV"; INT .
value^list.key^length := 2; value^list.pri^extent := 32; value^list.sec^extent := 8; value^list.fileformat := 2; !format 2 value^list.altkeys := num^altkeys; value^list.altkey^descr[0].key^specifier ':=' "LO"; value^list.altkey^descr[0].key^length := 4; value^list.altkey^descr[0].key^offset := 42; value^list.altkey^descr[0].key^filenum := 0; value^list.altkey^descr[0].null^value := 0; value^list.altkey^descr[0].attributes := 0; value^list.altkey^descr[1].key^specifier ':=' "VN"; value^list.altkey^descr[1].
Example 5: Creating a Partitioned, Key-Sequenced File This example shows how to create a key-sequenced file that will span six partitions. The record format is the same as in “Example 1: Creating a Key-Sequenced File” (page 76) Byte Offset: 34 0 name 134 address 142 current-balance 150 limit Primary-Key Field The file is to reside on six volumes and be partitioned in this manner: Names Whose First Two Letters are in the Range: Reside On: 00 . . $PART0 DA . . $PART1 HA . . $PART2 LA . .
-set part (5,$part5,50,20,"TA") -show TYPE K CODE 1000 EXT ( 50 PAGES, 20 PAGES ) PART ( 1, $PART1, 50 PAGES, PART ( 2, $PART2, 50 PAGES, PART ( 3, $PART3, 50 PAGES, PART ( 4, $PART4, 50 PAGES, PART ( 5, $PART5, 50 PAGES, REC 150 BLOCK 2048 IBLOCK 2048 KEYLEN 34 KEYOFF 0 -create custfile CREATED - $PART0.SVOL1.
STRING vol^names [0:29]; INT part^part^key^len; STRING part^part^key^val [0:9]; END; namelen := name^length; item^list ':=' [ZSYS^VAL^FCREAT^FILETYPE, ZSYS^VAL^FCREAT^FILECODE, ZSYS^VAL^FCREAT^LOGICALRECLEN, ZSYS^VAL^FCREAT^BLOCKLEN, ZSYS^VAL^FCREAT^KEYOFFSET, ZSYS^VAL^FCREAT^KEYLEN, ZSYS^VAL^FCREAT^PRIMEXTENTSIZE, ZSYS^VAL^FCREAT^SCNDEXTENTSIZE, ZSYS^VAL^FCREAT^NUMPRTNS, ZSYS^VAL^FCREAT^PRTNDESC, ZSYS^VAL^FCREAT^PRTNVOLLEN, ZSYS^VAL^FCREAT^PRTNVOLNAMES, ZSYS^VAL^FCREAT^PRTNPARTKEYLEN, ZSYS^VAL^FCREAT^PRTNP
blocks interspersed among in-use blocks. When you are adding data to a key-sequenced file, the EOF pointer increments each time a new block is added because there are no empty blocks. The system maintains a working copy of the file's EOF pointer in the file control blocks (FCBs) that are in both the primary and backup system processes that control the associated disk volume.
Deleting Records You perform record deletion by using the FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITEUPDATE or WRITEUPDATEUNLOCK system procedure with a write count of zero. Record deletion always applies to the current position in a file. Current Primary-Key Value A key-sequenced file's current primary-key value is taken from the primary key associated with the last FILE_READ64_, FILE_READLOCK64_, READ or READLOCK operation or FILE_SETKEY_ or KEYPOSITION operation by primary key.
name address region curbal limit ADAMS MIAMI, FL SO 0000.00 0500.00 BROWN, A REEDLEY, CA WE 0256.95 0300.00 BROWN, B BOSTON, MA EA 0301.00 1000.00 EVANS BUTTE, MT WE 0010.00 0100.00 HARTLEY CHICAGO, IL NO 0433.29 0500.00 JONES DALLAS, TX SO 1234.56 2000.00 KOTTER NEW YORK, NY EA 0089.00 0500.00 RICHARDS MINNEAPOLIS, MN NO 0000.00 0500.00 ROGERS BOISE, ID WE 1024.00 1500.00 SANFORD LOS ANGELES, CA WE 0301.00 1000.00 SMITH DAYTON, OH NO 0010.00 0500.
ADAMS MIAMI, FL SO 0000.00 0500.00 BROWN, A REEDLEY, CA WE 0256.95 0300.00 BROWN, B BOSTON, MA EA 0301.00 1000.00 EVANS BUTTE, MT WE 0010.00 0100.00 HARTLEY CHICAGO, IL NO 0433.29 0500.00 JONES DALLAS, TX SO 1234.56 2000.00 KOTTER NEW YORK, NY EA 0089.00 0500.00 RICHARDS MINNEAPOLIS, MN NO 0000.00 0500.00 ROGERS BOISE, ID WE 1024.00 1500.00 SANFORD LOS ANGELES, CA WE 0301.00 1000.00 SMITH DAYTON, OH NO 0010.00 0500.
Current Position After KEYPOSITION Call BROWN, B BOSTON, MA EA 0301.00 1000.00 KOTTER NEW YORK, NY EA 0089.00 0500.00 HARTLEY CHICAGO, IL NO 0433.29 0500.00 RICHARDS MINNEAPOLIS, MN NO 0000.00 0500.00 SMITH DAYTON, OH NO 0010.00 0500.00 ADAMS MIAMI, FL SO 0000.00 0500.00 JONES DALLAS, TX SO 1234.56 2000.00 BROWN, A REEDLEY, CA WE 0256.95 0300.00 EVANS BUTTE, MT WE 0010.00 0100.00 ROGERS BOISE, ID WE 1024.00 1500.00 SANFORD LOS ANGELES, CA WE 0301.
Primary-Key Field 1 ADAMS MIAMI, FL SO 0000.00 0500.00 2 BROWN, A REEDLEY, CA WE 0256.95 0300.00 3 BROWN, B BOSTON, MA EA 0301.00 1000.00 4 EVANS BUTTE, MT WE 0010.00 0100.00 5 HARTLEY CHICAGO, IL NO 0433.29 0500.00 6 JONES DALLAS, TX SO 1234.56 2000.00 7 KOTTER NEW YORK, NY EA 0089.00 0500.00 8 RICHARDS MINNEAPOLIS, MN NO 0000.00 0500.00 9 ROGERS BOISE, ID WE 1024.00 1500.00 10 SANFORD LOS ANGELES, CA WE 0301.00 1000.
The KEYPOSITION call sets the current position at the first record in the primary data file that contains the value EA in the region (RG) field. Access is by the alternate-key access path RG. Successive read calls within the read loop access all of the records in the primary data file that contain the value EA or greater in the RG field. When two or more records contain the same value in the RG field, those records are accessed in ascending order by the primary key.
compare^len , generic ); cust^eof := 0; WHILE NOT cust^eof DO BEGIN ! read loop CALL READ (cust^filenum, cust^rec, $LEN(cust^rec) ); IF > THEN cust^eof := 1 ! end-of-file ELSE IF < THEN ... ! error ELSE BEGIN ! process the record : END; END; ! read loop The KEYPOSITION call sets the current position at the first record in the primary data file that contains the value BROWN as the first five characters in the primary-key field. Access is by the primary-key access path.
The KEYPOSITION call sets the current position at the first record in the primary data file that contains the value SMITH as the first five characters in the primary-key field. Access is by the primary-key access path. Exact positioning by a primary-key value always gives you access to only one record in the primary data file: the record at the current position after the KEYPOSITION call. The read loop is executed twice.
AlternateKey Field RG 1 HARTLEY CHICAGO, IL NO 0433.29 0500.00 2 RICHARDS MINNEAPOLIS, MN NO 0000.00 0500.00 3 SMITH DAYTON, OH NO 0010.00 0500.00 4 EOF Example 7: Insertion of a Record Into a Key-Sequenced File This sample TAL code shows how to insert a new record into a key-sequenced primary data file: ! blank the customer record cust^rec ':=' " " & cust^rec FOR $LEN(cust^rec) -1 BYTES; ! move the new data into cust^rec cust^rec.cust^name cust^rec.cust^address cust^rec.
name address region curbal limit ADAMS MIAMI, FL SO 0000.00 0500.00 BROWN, A REEDLEY, CA WE 0256.95 0300.00 BROWN, B BOSTON, MA EA 0301.00 1000.00 EVANS BUTTE, MT WE 0010.00 0100.00 HARTLEY CHICAGO, IL NO 0433.29 0500.00 HEATHCLIFF PORTLAND, OR WE 0000.00 0500.00 JONES DALLAS, TX SO 1234.56 2000.00 KOTTER NEW YORK, NY EA 0089.00 0500.00 RICHARDS MINNEAPOLIS, MN NO 0000.00 0500.00 ROGERS BOISE, ID WE 1024.00 1500.00 SANFORD LOS ANGELES, CA WE 0301.
The data record written from the application buffer to the disk file is: HARTLEY CHICAGO, IL NO 0463.29 0500.00 Example 9: Random Update of a Nonexistent Record This example shows an attempt to update a nonexistent record. Because the KEYPOSITION procedure does no searching of indexes, the attempt to access the nonexistent record is not discovered until the subsequent READUPDATE call. The first four records in the primary data file are: ADAMS MIAMI, FL SO 0000.00 0500.
IF < THEN ... ! error ELSE BEGIN ! process the record IF cust^rec.cust^limit >= 1000.00F AND cust^rec.cust^limit < 2000.00F THEN BEGIN cust^rec.cust^limit := 2000.00F; CALL WRITEUPDATE (cust^filenum, cust^rec, $LEN(cust^rec) ); IF < THEN ... ! error END; END; END; ! read loop This illustration shows the contents of the customer file after all of the applicable records have been updated: limit ADAMS MIAMI, FL SO 0000.00 0500.00 BROWN, A REEDLEY, CA WE 0256.95 0300.
! blank the key key ':=' " "; key[1] ':=' key FOR name^len - 1 BYTES; key ':=' "EVANS"; CALL KEYPOSITION (cust^filenum, key); CALL WRITEUPDATE (cust^filenum, cust^rec , 0); IF <> THEN ... ! error This illustration shows the contents of the applicable portion of the customer file after the deletion: BROWN, B BOSTON, MA EA 0301.00 2000.00 HARTLEY CHICAGO, IL NO 0433.29 0500.
BROWN, A REEDLEY, CA WE 0256.95 0300.00 BROWN, B BOSTON, MA EA 0301.00 2000.00 HARTLEY CHICAGO, IL NO 0433.29 0500.00 JONES DALLAS, TX SO 1234.56 2000.00 KOTTER NEW YORK, NY EA 0089.00 0500.00 ROGERS BOISE, ID WE 1024.00 2000.00 SANFORD LOS ANGELES, CA WE 0301.00 2000.00 SMITH DAYTON, OH NO 0010.00 0500.
orderno name date total 0020 SMITH 95/09/30 0000.00 0021 JONES 95/10/01 0000.00 0176 BROWN, B 95/10/17 0000.00 0410 SANFORD 95/10/22 0000.00 0498 ROGERS 95/11/02 0000.00 0601 SMITH 95/11/08 0000.00 0622 HARTLEY 95/11/12 0000.00 0623 KOTTER 95/11/12 0000.
orderno itemno partno qty itemtot 0020 0001 23167 00002 0000.00 0020 0002 02010 00001 0000.00 0020 0003 12950 00005 0000.00 0021 0001 00512 00022 0000.00 0021 0002 23167 00001 0000.00 0176 0001 32767 00001 0000.00 0410 0001 01234 00010 0000.00 0410 0002 03379 00010 0000.00 00010 0000.
The contents of the inventory file are: partno descr price availqty loc vendor 00002 HI-FI 0129.95 00050 A01 TAYLOR 00512 RADIO 0010.98 00022 G10 GRAND 00987 TV SET 0200.00 00122 A76 TAYLOR 02010 TOASTER 0022.50 00000 F22 ACME 03379 CLOCK 0011.75 00512 A32 ZARF 12950 TOASTER 0020.45 00010 C98 SMYTHE 20211 WASHER 0314.29 00005 B44 SOAPY • • • 23167 ANTENNA 0022.50 00008 A01 TAYLOR 32767 IRON 0025.95 00051 A82 HOT 65535 DRYER 0299.
CALL READ (order^filenum, order, $LEN(order) ); IF > OR order.order^date >= limit^date THEN order^eof :=1 ELSE BEGIN ! fill order ! read customer file CALL KEYPOSITION (cust^filenum, order.order^name); CALL READUPDATE (cust^filenum,cust^rec, $LEN(cust^rec) ); ! print the order header ! read order detail file for current order compare^len := 2; generic := 1; CALL KEYPOSITION (orderdet^filenum, order.
From the order detail file: 0020 0001 23167 00002 0000.00 0020 0002 02010 00001 0000.00 0020 0003 12950 00005 0000.00 From the inventory file: 23167 ANTENNA 0022.50 00008 A01 TAYLOR 02010 TOASTER 0022.50 00000 F22 ACME 12950 TOASTER 0020.45 00010 C98 SMYTHE The following are the contents of those same records after filling the first order. In the order file: 0020 SMITH 95/09/30 0147.25 In the customer file: SMITH DAYTON, OH NO 0157.25 0500.
23167 ANTENNA 0022.50 00006 A01 TAYLOR 02010 TOASTER 0022.50 00000 F22 ACME 12950 TOASTER 0020.
7 Queue Files Enscribe Queue Files An Enscribe queue file is a special type of key-sequenced disk file that can function as a queue. Processes can queue and dequeue records in a queue file. Queue files contain variable-length records that are accessed by values in designated key fields. Unlike other key-sequenced files, queue files have primary keys but cannot have alternate keys. The primary key for a queue file includes an 8–byte timestamp; you can add a user key if desired.
• FILE_WRITE64_, WRITE[X] • FILE_GETINFO_, FILE_GETINFOLIST_, FILE_GETINFOBYNAME_, FILE_GETINFOLISTBYNAME_ Types of Access Like key-sequenced files, queue files can be accessed by applications either sequentially or randomly. Queue File Structure Queue files are physically organized as one or more bit-map blocks and a B-tree structure of index and data blocks. Organization is the same as for key-sequenced files, described in “Key-Sequenced Files” (page 68).
Queue File Examples These examples illustrate the three different ways to create queue files. Example 1: Creating a Queue File with FUP This example shows how you might use FUP to create a queue file: 10> FUP - SET TYPE K - SET CODE 1001 - SET QUEUEFILE - SET EXT (20,10) - SET MAXEXTENTS 64 - SET KEYLEN 10 - SET REC 100 - SET AUDIT - CREATE QFILE - EXIT > Example 2: Creating a Queue File With the FILE_CREATE_Procedure This TAL example creates a queue file using the FILE_CREATE_Procedure.
INT QF^NameLen; LITERAL Key^Length = 8; ! Key length ! (must be >= 8) INT Key^Len; STRING .Key[0:Key^Length - 8]; ! Application key LITERAL Rec^Len = 100; ! Record length INT Items[0:20]; ! Attribute numbers INT Value[0:40]; ! Attribute values INT Error; ! Returned error code INT Error^Item; ! Returned item-in-error ?SOURCE $SYSTEM.SYSTEM.
Specifying Sync-Depth When you open a queue file, you can specify a sync depth for the file. A non zero sync depth is supported for all operations except for dequeuing; the sync depth for dequeuing operation must equal zero. If you specify a sync depth that I snot equal to zero for any operation other than dequeuing, the file system attempts to recover from path-related errors (200, 201, 210, and 211).
To read a record with the FILE_READUPDATELOCK64_/READUPDATELOCK[X] procedure, these requirements must be met: • An application must have write access to the file. • The sync depth must be zero. • The record must not be locked. • The record must satisfy any key comparison rules defined by a prior call to the KEYPOSITION procedure. (For more information about positioning, see Dequeuing With Positioning“Dequeuing With Positioning” (page 114).
FILE_READUPDATELOCK64_/READUPDATELOCK[X] operation causes the record to be deleted from the file. If a transaction that is associated with a dequeue request aborts, the disk process reinserts the record at the same logical location from which it came. The abort operation also awakens any processes waiting to dequeue a record from the file.
For audited queue files only, your application can recover from a timeout error by calling the ABORTTRANSACTION procedure to ensure that any dequeued records are reinserted into the file. The corresponding transaction must then be restarted. NOTE: For unaudited queue files, your application should never call AWAITIO[X]/FILE_AWAITIO64_ with a time limit greater than OD if a READUPDATELOCK[X]/FILE_READUPDATELOCK64_ is pending. The recovery procedure described above does not work on unaudited queue files.
Figure 17 Using Approximate Positioning With a Queue File Process A READUPDATELOCK READUPDATELOCK Process B Get Record "MB1000" File is Empty (request is retained) WRITE: Record "MA1001" inserted Disk process returns record "MA1001" READUPDATELOCK File is Empty (request is retained) WRITE: Record "AA1002" inserted (request is retained) This example shows two special actions of the queue file, compared to a standard key-sequenced file: • The second READUPDATELOCK call retrieved a record whose key w
Figure 18 Using Generic Positioning With a Queue File Process B Process A READUPDATELOCK READUPDATELOCK Get Record "TA1000" File is Empty (request is retained) WRITE: Record "TA1001" inserted Disk process returns record "TA1001" READUPDATELOCK File is Empty (request is retained) WRITE: Record "TB1002" inserted (request is retained) WRITE: Record "TA1003" inserted Disk process returns record "TA1003" READUPDATELOCK File is Empty (request is retained) Note that the second insertion does not cause Pro
This behavior affects the operation of the FILE_GETINFOLIST_ and FILERECINFO operations. The FILE_GETINFOLIST_ procedure does not return a meaningful current key value after a FILE_WRITE64_, WRITE[X], FILE_READUPDATELOCK64_ or READUPDATELOCK[X] operation. It can, however, return a current key value after a FILE_READ64_/READ[X] operation. The FILERECINFO procedure does not return the current key value for queue files.
Access Examples These examples show how to access queue files. For brevity, the timestamps shown in the examples have been truncated to 4-byte numeric strings (for example, “1001”). If the key used in the example is longer than eight bytes, the key is displayed as “”for example, “AB1001”). Example 1: Opening a Queue File This TAL example opens a queue file: INT QF^Num; ! Queue File number STRING .QF^Name[0:33] := "$spool.lkp.
CALL ENDTRANSACTION; RETURN Error <> 0; END; ! End the transaction Example 3: Dequeuing a Record This TAL example dequeues the first record from a queue file. Note that the queue file must be opened before calling this procedure. INT QF^Num; ! Queue File number STRING .QF^Name[0:33] := "$spool.lkp.qfile"; ! File name LITERAL QF^NameLength = 16; ! Length in bytes of file name INT QF^NameLen; LITERAL Key^Length = 8; ! Key length (must be >= 8) INT Key^Len; STRING .
END ELSE ! Some other error BEGIN status := ABORTTRANSACTION; !abort this transaction RETURN -1; END; END ! Execute one dequeue operation UNTIL 0; END; Example 4: Using KEYPOSITION for Generic Positioning In this example, the queue file has a key-length of 10 bytes, so the user-key length is 2 bytes. Note that you must open the queue file and specify a key range in key before calling GET^GENERIC. INT QF^Num; ! Queue File number STRING .QF^Name[0:33] := "$pub1.spl1111.
1); ! positioning-mode = generic ! Note: In practice, it is only necessary to call ! KEYPOSITION once to establish the desired key range. DO BEGIN Error := BEGINTRANSACTION(Trans^Tag); ! Start trans.
In summary, if you require protection from path loss conditions, use audited files.
8 Entry-Sequenced Files Enscribe Entry-Sequenced Files Enscribe entry-sequenced files are designed for sequential access. They consist of variable-length records that are always appended to the end of the file; as a result, the records in the file are arranged physically in the order in which they were added to the file. Figure 19 (page 124) illustrates the structure of an entry-sequenced file.
UNLOCKFILE, READLOCK, LOCKREC, and UNLOCKREC.Enscribe entry-sequenced files are not designed for random access. If the data records contain unique alternate-key values, however, you can use KEYPOSITION in conjunction with FILE_READ64_, FILE_READLOCK64_, READ or READLOCK to access them randomly. NOTE: If an error occurs during an attempt to insert a record into an alternate-key file, 0-length records might occur in the primary entry-sequenced file.
For entry-sequenced files, the maximum length of a logical record is 24 bytes (or 48 bytes for format 2 files) less than the block size. The maximum allowed block size for format 2 files is 4 KB. The data records that you write to an entry-sequenced file can be of varying lengths, but none can exceed the maximum logical record size specified when the file was created.
Example 1: Creating an Entry-Sequenced File This example shows how to create a file for logging summary records of financial transactions as they occur. Because the records will always be written to the file sequentially in the order in which they are generated, it is reasonable to use an entry-sequenced file for storing them.
? READ) ?LIST PROC DO^THE^WORK MAIN; BEGIN namelen := name^length; ERROR := FILE_CREATE_ (filename:name^length,namelen,, pri^extent, sec^extent,, file^type,, rec^len, data^block^len); ERROR := FILE_OPEN_ (filename:name^length, filenum); ERROR := FILE_CLOSE_ (filenum); END; Example 2: Creating an Entry-Sequenced File With Alternate Keys This example shows how to create the file illustrated in Section : Example 1: Creating an Entry-Sequenced File, but defines the terminal-number field as an alternate key.
"$STORE1.SVOL1.TRANFILE"; INT .item^list [0:item^list^len-1]; STRUCT value^list; BEGIN INT file^type; INT logical^reclen; INT block^length; INT pri^extent; INT sec^extent; INT altkeys; STRUCT altkey^descr [0:num^altkeys-1]; BEGIN STRING key^specifier [0:1]; INT key^length; INT key^offset; INT key^filenum; INT null^value; INT attributes; END; INT num^alt^key^files; STRUCT name^length^info [0:num^altkey^files-1]; BEGIN INT file^name^len; END; STRING file^names [0:20]; END; ?NOLIST ?SOURCE $SYSTEM.ZSYSDEFS.
ERROR := FILE_CREATELIST_ (filename:name^length,namelen, item^list, item^list^len, value^list, $LEN(value^list), error2); END; When you use a system procedure to create your entry-sequenced file, you must create your alternate key files separately, as shown in the next example. Example 3: Creating an Alternate-Key File Programmatically When you use FUP to create the primary file, FUP automatically creates any required alternate-key files.
Note that each partition must reside on a separate disk volume. Within those volumes, however, the partitions all have the same subvolume name and file name (SVOL1.TRANFILE in this example). All four partitions are created at the same time. When all 16 extents of the primary partition (#0) have been entirely used, the file system automatically begins using partition #1; when all 16 extents of that partition have been entirely used, the file system then begins using partition #2; and so forth.
value^list.block^length := 4096; value^list.pri^extent := 1000; value^list.sec^extent := 500; value^list.partitions := 3; value^list.part^info[0].part^pri^extent := 1000; value^list.part^info[0].part^sec^extent := 500; value^list.part^info[1].part^pri^extent := 1000; value^list.part^info[1].part^sec^extent := 500; value^list.part^info[2].part^pri^extent := 1000; value^list.part^info[2].part^sec^extent := 500; value^list.vol^name^len.vol^name^act^len[0] := 7; value^list.vol^name^len.
Access Examples The remainder of this section presents annotated examples illustrating the most common ways to access Enscribe entry-sequenced files. Example 1. Writing to an Entry-Sequenced File To append a new data record to the end of an entry-sequenced file you use WRITE or WRITEX to add your data record to the file. CALL WRITE (filenum, buffer, write^count); IF <> THEN ...
compare^length, generic); read^count := 200; eof := 0; WHILE NOT eof DO BEGIN ! read loop CALL READ (filenum, buffer, read^count, count^read); IF > THEN eof := 1 ELSE IF < THEN ... ! error ELSE BEGIN . ! process the record (the returned . ! parameter specifies . ! the actual record length in bytes) END; END; ! read loop Example 4.
9 Relative Files Enscribe Relative Files Enscribe relative files consist of fixed-length physical records on disk that are accessed by relative record number. A record number is an ordinal value and corresponds directly to the record's position in the file. The first record is identified by record number zero; succeeding records are identified by ascending record numbers in increments of one. Figure 20 (page 134) illustrates the structure of a relative file.
be inserted into any available position by supplying a record number of -2 to FILE_SETPOSITION_ before inserting records into the file. You can specify that subsequent records be appended to the end of a file by supplying a record number of -1 to the FILE_SETPOSITION_ procedure. For example, in a relative file in which only record number 10 contains data, you can position to an empty location (such as record number 5) and use the WRITE procedure to insert a new record in that location.
When the data records of a relative file include one or more alternate-key fields, there are two other values that are used for manipulating the pointers by way of alternatekey files: Current key specifier Identifies which alternate-key field is to be used for accessing records in the file. When the current access path is by primary key, the current key specifier value is zero. Current key value Identifies the particular alternate-key value that is currently being used within the current access path.
Format 1 Files For relative format 1 files, the maximum length of a logical record is 24 bytes less than the block size. Using the maximum allowed block size of 4096, the absolute maximum logical record size allowed for relative files is 4072 bytes. Format 2 Files For relative format 2 files, the maximum length of a logical record is 48 bytes less than the block size. Using the maximum allowed block size of 4096, the absolute maximum logical record size allowed for relative files is 4048 bytes.
Example 1: Creating a Relative File This example shows how to create an employee data file in which the individual records are to be accessed by employee number. If the employee numbering scheme starts at zero or one (for the first employee) and proceeds sequentially upward in increments of one, it is reasonable to use a relative file.
EXT ( 60 PAGES, 30 PAGES ) REC 112 BLOCK 4096 MAXEXTENTS 16 -create empfile CREATED - $STORE1.SVOL1.EMPFILE Using the FILE_CREATE_ system procedure, you could create the same file by including the TAL code in one of your application modules. The node name is not specified, so the FILE_CREATE_ procedure obtains the node name from the current value of the VOLUME attribute of the =_DEFAULTS DEFINE. For more information on the =_DEFAULTS DEFINE, see the TACL Programming Guide.
REC 112 BLOCK 4096 ALTKEY ( "DP", FILE 0, KEYOFF 80, KEYLEN 5 ) ALTFILE ( 0, $STORE1.SVOL1.DEPT ) ALTCREATE -create empfile CREATED - $STORE1.SVOL1.EMPFILE CREATED - $STORE1.SVOL1.DEPT Using the CREATE procedure, you could create the same file by including this TAL code in one of your application modules. The node name and volume name for the new file are obtained from the current value of the VOLUME attribute of the =_DEFAULTS DEFINE.
INT num^alt^key^files; STRUCT name^length^info [ 0:num^altkey^files-1]; BEGIN INT file^name^len; END; STRING file^names [0:9]; END; ?NOLIST ?SOURCE $SYSTEM.ZSYSDEFS.ZSYSTAL(FILESYSTEM^ITEMCODES) ?SOURCE $SYSTEM.SYSTEM.
LITERAL name^length = 20, pri^extent = 30, sec^extent = 15, file^type = 3, rec^len = 11, data^block^len = 4096, key^length = 11, ! max. alternate key length ! + primary-key length ! + 2 key^offset = 0; INT namelen; INT error; STRING .filename [0:name^length-1] := "$STORE1.SVOL1.INVALT"; namelen := name^length; error := FILE_CREATE_(filename:name^length, namelen,, pri^extent, sec^extent,, file^type,, rec^len, data^block^len, key^length, key^offset); IF error <> 0 THEN ...
INT error; INT error2; INT namelen; STRING .filename [0:name^length-1] := "$PART1.SVOL1.EMPFILE"; INT .item^list [0:item^list^len-1]; STRUCT value^list; BEGIN INT file^type; INT logical^reclen; INT block^length; INT pri^extent; INT sec^extent; INT partitions; STRUCT part^info [0:num^partitions-1]; BEGIN INT part^pri^extent; INT part^sec^extent; END; STRUCT vol^name^len [0:num^partitions-1]; BEGIN INT vol^name^act^len; END; STRING vol^names [0:18]; END; ?NOLIST ?SOURCE $SYSTEM.ZSYSDEFS.
item^list, item^list^len, value^list, $LEN(value^list), error2); END; Accessing Relative File The following paragraphs discuss the file pointers and access methods for Enscribe relative files. The File Pointers Separate next-record and current-record pointers are associated with each opening of a relative disk file so that if the same file is open several times simultaneously, each opening will provide a logically separate access.
FILE_SETKEY_, KEYPOSITION Sets the current access path to the specified key field. • With nonunique alternate keys: changes the content of the current-record and next-record pointers so that they both point to the first (lowest) record in the file that contains the specified key-value (or partial key-value) in the specified alternate-key field.
When you are writing data records, a succession of FILE_WRITE64_/WRITE calls writes data to successively higher physical records in the file. Note that FILE_WRITE64_/WRITE will only write data to empty physical records. If you attempt to FILE_WRITE64_/WRITE to a physical record that already contains data, the operation fails with an error 10 (record already exists).
Deleting Records Record deletion, which is accomplished by way of a FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITEUPDATE or WRITEUPDATEUNLOCK call with a write-count of zero, always applies to the physical record indicated by the current-record pointer. File Access Examples The remainder of this section presents annotated examples illustrating the most common ways to access Enscribe relative files.
Note that the sequence skips empty records (records 12, 13, and 16 in the sample file).
After doing so, you can obtain the address of the physical record that was actually used by issuing this procedure call: item := 202; error := FILE_GETINFOLIST_ (filenum, item, 1, primary^key, 8); Random Access by Primary Key You access individual records randomly within a relative file by using FILE_SETPOSITION_ calls to explicitly identify the desired record by primary key (relative record number). CALL FILE_SETPOSITION_ (filenum,38F); ! sets next-rec.
10 File and Record Locking Enscribe File and Record Locks Access to shareable Enscribe files among two or more processes is coordinated by file locks and record locks. Files can be either audited or nonaudited. An audited file is one that is being accessed under the control of TMF. For nonaudited files, locks are granted on a file-open basis; that is, they are requested and granted in conjunction with individual file numbers associated with separate calls to the FILE_OPEN_ system procedure.
Table 11 Locking Modes (continued) FILE_READUPDATELOCK64_, READLOCK, and READUPDATELOCK are treated as in normal mode. Read-warn/reject mode FILE_READ64_, FILE_READUPDATE64_, READ and READUPDATE requests ignore existing record and file locks; although an existing lock will not delay or prevent reading the record, it causes a CCG completion with a warning code of 9.
Note that if generic locking is enabled for a key-sequenced file, the FILE_LOCKREC64_/LOCKREC procedure also locks any other records in the file whose keys begin with the same character sequence as the key of the referenced record. Generic locking applies only to key-sequenced files.
The length of the generic lock key length must be less than the length of the entire key. Note that there are now two key lengths: the overall key length defined at file creation time and the generic lock key length; each is defined on a per-file basis. Consider this example: File X is a key-sequenced file with a defined key length of 6.
For example, assume that there exists an empty key-sequenced file with a defined key length of four and that generic locking is enabled with a generic lock key length of two. If process #1 inserts a record with the key AAaa, it thereby owns a generic lock for the byte-string AA. If process #2 at that time attempts to insert a record with the key AAcc, the attempt is rejected with a CCL and an error code 73.
. . LOCKREC: record 2 LOCKREC: record 1 Here, process A has record 1 locked and is requesting a lock for record 2, while process B has record 2 locked and is requesting a lock for record 1. One possible way to avoid deadlock is to always lock the records in the same order. Thus, this illustrated situation could never happen if each process requested the lock to record 1 before it requested the lock to record 2.
By performing heavy activity against an audited database, an application process can generate a large number of locks and thereby inadvertently create deadlock situations with other application processes. Therefore, when designing your application, you should consider the coordinated use of file locks and/or generic record locks among those processes that need access to the same database. A TMF transaction is begun by a call to BEGINTRANSACTION and terminated by a call to ENDTRANSACTION.
Figure 22 (page 157) illustrates these principles: • The terminal control process (TCP) interprets BEGINTRANSACTION and obtains the transid before requesting database activity from the servers. • The transid is transmitted to the servers as part of the request message, and any disk activity performed by the servers is associated with the particular transid.
Reading Deleted Records If transaction T1 deletes a record and another transaction T2 attempts to read the same record while T1 is still active, then: • If T2's request is a FILE_READ64_/READ call following exact positioning through the alternate file, the request fails with an error 1 (end-of-file) irrespective of the locking mode specified.
11 Errors and Error Recovery Error Message Categories The file system generates a number of messages indicating errors or other special conditions. You can encounter these messages during execution of any program module that uses system procedures. Both a condition code and an error number are associated with the completion of each file-system procedure call. For successful completions, the condition code is CCE and the error number is 0.
status := FILE_GETINFO_ ( filenum, error );. ... END ELSE GOTO loop; The first five WRITEs are successful (number^written = 400), but the sixth fails after transferring 48 bytes from the buffer to the disk (number^written = 48). If insufficient disk space is available to allocate another extent, the error number returned by FILE_GETINFO_ is 43 (unable to obtain disk space for file extent).
12 File Loading File Utility Program (FUP) Commands The File Utility Program (FUP) commands that you use to load data into an existing file are LOAD and LOADALTFILE. The LOAD command loads data into an existing structured disk file without affecting any related alternate-key files. Any previous data in the file being loaded is lost. When loading data into key-sequenced files, the input records can be in either sorted or unsorted order; unless you specify the SORTED option, unsorted is assumed.
The LOADALTFILE command loads PRIFILE's key file 0 ($VOL1.SVOL.ALTFILE) with the alternate-key records for key specifier NM and for any other alternate keys defined for key file zero. An index block slack percentage of 10 is specified. Creating an Alternate-Key File This example creates an alternate-key file for the primary file $VOL1.SVOL.FILEA, which is an entry-sequenced file. The new alternate-key file will be named $VOL1.SVOL.FILEB.
-VOLUME $vol1.svol -RESET -SET TYPE K -SET KEYLEN 19 -SET REC 19 -SET EXT (9000,1000) -SET PART (1,$vol2,9000,1000,"SNM") -CREATE altfile If the primary file contains any data, the empty alternate key file will be loaded with the associated key records. In this example, the primary file is named PRIFILE, and it specifies ALTFILE as its alternate key file number 0.
The LOAD command loads the secondary partition $VOL2.SVOL.ALTFILE with the alternate-key records for key specifier F2. Note that the record blocking here is complementary to that used with BUILDKEYRECORDS.
A ASCII Character Set Table 12 shows the USA Standard Code for Information Interchange (ASCII) character set, and the corresponding code values in octal notation.
Table 12 ASCII Character Set (continued) SP 020000 000040 Space ! 020400 000041 Exclamation point " 021000 000042 Quotation mark # 021400 000043 Number sign $ 022000 000044 Dollar sign % 022400 000045 Percent sign & 023000 000046 Ampersand ' 023400 000047 Apostrophe ( 024000 000050 Opening parenthesis ) 024400 000051 Closing parenthesis * 025000 000052 Asterisk + 025400 000053 Plus , 026000 000054 Comma - 026400 000055 Hyphen (minus) .
Table 12 ASCII Character Set (continued) E 042400 000105 Uppercase E F 043000 000106 Uppercase F G 043400 000107 Uppercase G H 044000 000110 Uppercase H I 044400 000111 Uppercase I J 045000 000112 Uppercase J K 045400 000113 Uppercase K L 046000 000114 Uppercase L M 046400 000115 Uppercase M N 047000 000116 Uppercase N O 047400 000117 Uppercase O P 050000 000120 Uppercase P Q 050400 000121 Uppercase Q R 051000 000122 Uppercase R S 051400 000123 Uppe
Table 12 ASCII Character Set (continued) j 065000 000152 Lowercase j k 065400 000153 Lowercase k l 066000 000154 Lowercase l m 066400 000155 Lowercase m n 067000 000156 Lowercase n o 067400 000157 Lowercase o p 070000 000160 Lowercase p q 070400 000161 Lowercase q r 071000 000162 Lowercase r s 071400 000163 Lowercase s t 072000 000164 Lowercase t u 072400 000165 Lowercase u v 073000 000166 Lowercase v w 073400 000167 Lowercase w x 074000 000170 Lowe
B Block Formats of Structured Files This appendix describes the block formats for key-sequenced, queue, entry-sequenced, and relative files. A block in a structured file usually consists of a header, a record area, and a map of offsets pointing to the beginning of each record. For relative files, an array of record lengths replaces the offsets map. Figure 24 (page 170) shows the format 1 block and Figure 31 (page 175) shows the format 2 block.
Figure 24 Block Format for Structured Format 1 Files [0] eye-catcher Length in Bytes 1 [1] relative-sector-number 3 [4] flags 1 [5] index-level 1 [6] volume-sequence-number 6 [12] checksum 2 [14] type-specific-block-header Decimal Offset Common Block Header [18, 20, 24, or 30] [4, 6, 10, or 16] (record 0) (record 1) Data Area (record N, where N = number-of-records -1) free space (key-sequenced, queue, and entry-sequenced files only) (reserved) 2 byte offset from [0] to record N (
Bits 3 through 5: These three bits indicate the file type as: 000 (reserved) 001 Relative File 010 Entry-Sequenced File 011 Key-Sequenced or Queue File 100 (reserved) 101 (reserved) 110 (reserved) 111 Directory Bits 6 and 7: These two bits indicate the block type as: 00 Data or Index 01 Bit Map (must be key-sequenced, queue, or relative file) 10 Free (must be key-sequenced or queue file) 11 (reserved) index-level contains the tree level of the block.
The relative-sector-number field in an index record points to the start of the block associated with this key. A null key value is used when KEYLEN = 0; this occurs in any index record pointing to an index block or to the first data record.
Figure 27 Header for Entry-Sequenced Data Block Offset (Decimal) 0 common-block-header Length in Bytes 14 14 number-of-records-allocated 2 16 (reserved) 4 20 (record 0) The fields in Figure 27 are defined as: common-block-header is the 14-byte common block header shown in Figure 24. number-of-records-allocated indicates how many records have been allocated in the block.
Figure 29 Header for Bit-Map Block Offset (Decimal) 0 common-block-header 14 number-of-free-bits 18 bit-map Length in Bytes 14 4 block size - 18 The fields in Figure 29 are defined as: common-block-header is the 14-byte common block header shown in Figure 24. number-of-free-bits indicates how many bits in this bit-map identify blocks that are free (empty) in a key-sequenced or queue file. For relative files, it indicates how many bits identify blocks that are not full.
Figure 31 Block Format for Structured Format 2 Files Decimal Offset Common Block Header relative-block number [0] 4 [4] flags 2 [6] block-level 2 [8] large-block-flags 4 [12] checksum 2 [14] block-version 2 8 volume-sequence-number [16] [24] checksum-32-bit [28] Length in Bytes 4 type-specific-block- header (record 0) Data Area (record N, where N = number-of-records -1) free space (key-sequenced, queue, and entry-sequenced files only) Offsets Map or Recordsize Array byte offset
100 (reserved) 101 (reserved) 110 (reserved) 111 Directory Bits 6 and7: These two bits indicate the block type as: 00 Data or Index 01 Bit Map (must be key-sequenced, queue, or relative file ) 10 Free (must be key-sequenced or queue file) 11 (reserved) block-level contains the tree level of the block. large-block-flags Bit 0: This bit is set (=1) if the checksum is valid. Bit 1: This bit is set (=1) if the 32-bit checksum is valid. Bit 2: This bit is set (=1) if the partial checksum is used.
The relative-block-number field in an index record points to the start of the block associated with this key. A null key value is used when KEYLEN = 0; this occurs for the first record in an index block.
relative-block-number of previous data block provides a link to the previous logical block. Figure 34 Header for Format 2 Entry-Sequenced Data Block Offset (Decimal) 0 common-block-header 28 number-of-records-allocated 32 (record 0) Length in Bytes 28 4 2 The fields in Figure 34 are defined as: common-block-header is the 28-byte common block header shown in Figure 31. number-of-records-allocated indicates how many records have been allocated in the block.
Figure 36 Header for Bit-Map Block Offset (Decimal) 0 common-block-header 28 number-of-free-bits 32 bit-map Length in Bytes 28 4 block size - 32 The fields in Figure 36 are defined as: common-block-header is the 28-byte common block header shown in Figure 31. number-of-free-bits indicates how many bits in this bit-map identify blocks that are free (empty) in a key-sequenced or queue file. For relative files, it indicates how many bits identify blocks that are not full.
C Action of Current Key, Key Specifier, and Key Length This appendix contains pseudocode descriptions of the behavior of basic file-system operations and their relationships to file-currency information. The variables and functions used in the pseudocode are defined first. By evaluating the pseudocode, you can determine the action of the current key, key specifier, and key length for the different file-system operations.
• • • find (mode, specifier, key value, comparison length, direction) returns the position of first record in the file according to mode, specifier, key value, comparison length, and direction. ◦ If mode = 0 (approximate) positioning is to the first record whose key field, as designated by the key specifier, is greater than or equal to the key value. If no such record exists, an end-of-file indication is returned.
next := false; REVERSE := reverse; FILE_SETPOSITION_, POSITION: CKV := rip := record specifier; CKS := primary if format I file format then CMPL := CKL := 4 else CMPL := CKL := 8; MODE := approx; next := false; REVERSE := false; READ: position := if next then find^next (MODE, CKS, CKV, CMPL, REVERSE) else find (MODE, CKS, CKV, CMPL, REVERSE); if error then return; record := file[position]; CKV := rip := keyfield (record, CKS); CKL := keylength (record, CKS); next := true; READUPDATE: position := find (ex
next := true; end; Pseudocode Descriptions 183
Index A Access examples entry-sequenced files, 131 key-sequenced files, 87 queue files, 118 relative files, 147 unstructured files, 64 Access modes, 22 Access paths exact positioning mode, 31 generic positioning mode, 30 overview, 27 relational access, 37 Accessing files entry-sequenced files, 131 key-sequenced files, 69, 85 queue files, 110 relative files, 135, 144 unstructured files, 60 Alternate keys attributes automatic updating, 34 null value, 33 attributes:null value, 33 automatic maintenance, 33 exam
Deleting data, 58 Deleting records, 87, 98, 147 Dequeuing records, 111 Device operation errors, 159 Direct-I/O cache access mode, 57 Directory, 21 Disk extent size entry-sequenced files, 125 key-sequenced files, 74 relative files, 137 unstructured files, 61 E EDIT files how to read, 60 structure imposed by EDIT, 60 EDITREAD procedure, 60 End-of-file pointer, 135 Entry-sequenced files access examples, 131 accessing, 131 comparison with other types, 24 creating, 124 disk extent size, 125 example of file crea
description of, 151 interaction with record locks, 154 unstructured files, 155 File numbers, 42 File opening access types, 57 partitioned files, 21, 51 permanent disk file, 51 File size limits, 48 entry-sequenced files, 49 key-sequenced files, 48 relative files, 49 unstructured files, 49 File types, 20 File Utility Program see FUP File, defined, 19 FILE_OPEN_ procedure, behavior of, 181 FILE_RENAME_ procedure error 27 for uncompleted operations, 41 FILE_SETPOSITION_ procedure behavior of, 182 description of
N Next-record pointer relative files, 135, 144 unstructured files, 63 NEXTFILENAME procedure, 41 Nowait I/O, defined, 22 Null value attribute, 33 PURGE procedure, 41 Purging data, 58 Q ODDUNSTR parameter, 65 OPEN procedure behavior of, 181 description of, 41 example, 51 sequential block buffering, 56 Queue files access examples, 118 accessing, 108, 110 description of, 107 file creation examples, 109 primary key, 108 record format, 108 structure, 108 sync depth, 111 timestamp in primary key, 108 Queuing
description of, 41, 151 key-sequenced files, 86 queue files, 111 read access required, 43 relative files, 146 Record definition, 19 structure, 25 Record length key-sequenced files, 68 maximum size, 73 relative files, 134 Record locks description of, 151 interaction with file locks, 154 unlocking, 152 unstructured files, 155 Records deleting, 87, 98, 147 inserting, 86, 146 REFRESH procedure, 41 Refreshing file information, 63, 144 Refreshing the EOF pointer, 58 Relational access, 37 Relational processing exa
random access, 66 record locks, 155 types of access, 60 V Verification of WRITE operations, 50 W Waited I/O, defined, 22 WRITE procedure AWAITIO required with nowait I/O, 41 behavior of, 182 description of, 41 effects on current-record pointer, 64 effects on EOF pointer, 64 effects on next-record pointer, 64 key-sequenced files, 86 queue files, 111 relative files, 146 unstructured files, 64, 67 verification, 50 write access required, 43 Write-only access, 22 WRITEUPDATE procedure behavior of, 182 descript
