| glosdump | Dump a glossary entry to a file. |
| isclose | Close an ISAM file. |
| isdelcurr | Delete the current record. |
| isdelete | Delete a specific record. |
| isfield | Identify a field by name. |
| isopen | Open an ISAM data file. |
| ispop | Restore prior file postion |
| ispush | Save the current file postion |
| isread | Read a record from an ISAM data file. |
| isrewcurr | Rewrite the current record. |
| isrewrite | Rewrite a specific record. |
| issetunique | Set a unique identifier. |
| isstart | Select and index and locate a record. |
| isuniqueid | Return a unique identifier |
| iswrite | Write a new record. |
Function Dump a glossary entry to a file.
IS_NULL glosdump ( IS_FILE fp, IS_STRING name ); Remarks The glossary entry name will be written to the file stream fp. This function is used within reports to write a report record using a predefined template (the glossary entry). Any glossary variables appearing within the glossary entry will be substituted as the glossary entry is read and written.
Returns glosdump does not return any result.
See also define(), glos_close(), glos_open().
Function Close an ISAM file.
IS_INTEGER isclose ( IS_ISAM fd ); Remarks The isclose function closes an ISAM file identified by fd that was opened with isopen. All locks on the file are released when it is closed.
ISAM files must be closed when you are through with them. Not doing so may corrupt files in certain environments.
Returns isclose returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isopen().
Function Delete the current record.
IS_INTEGER isdelcurr ( IS_ISAM fd ); Remarks Delete the current record in the ISAM file identified by fd. This function differs from isdelete, which deletes a record identified by a key value.
All index entries associated with the current record are also deleted. You must open the file with the ISINOUT option. Otherwise the operation fails.
Returns isdelcurr returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isdelete().
Function Delete a specific record.
IS_INTEGER isdelete ( IS_ISAM fd , { ... } record ); Remarks Delete a record from a file using a key value. Fd identifies a currently open ISAM file. Record is a search value pertaining to the current key of the record to be deleted.
If duplicate primary keys are allowed, then isdelete should not be used and the isread and isdelcurr functions should be used instead.
Any index entries associated with the deleted record are also deleted.
The isrecnum pointer is set to the record just deleted, and the current record position is unchanged.
You must open the file with the ISINOUT option. Otherwise, the operation fails.
Returns isdelete returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isdelcurr().
Function Identify a field by name.
IS_INTEGER isfield ( IS_ISAM fd, IS_STRING name ); Remarks ISAM files are read using isread which returns a record in an array. The index numbers of fields in these arrays may be identfied using isfield. The named field is searched for in the ISAM file identified by fd.
Returns isfield returns a positive index (including zero) of the field matching name
See also isopen().
Function Open an ISAM data file.
IS_ISAM isopen ( IS_STRING name, IS_INTEGER mode ); Remarks Open a data file for processing. The call returns an ISAM file identifier that is to be used by subsequent ISAM calls on that file. Use the isclose function to close the file. Name is a string identifying the name of the ISAM file to be opened. Mode values are described below.
The current index is set to the primary key.
The current record pointer is set to the first record in the file based on the order in the primary index. It can be set to the first record in another index by using the isstart function.
The mode parameter specifies the lock mode and the read/write mode in effect while the file is open. The value of the mode parameter is the arithmetic sum of a lock mode value and a read/write mode value.
The lock mode values are defined in $Utools/Utools/include/pi.h as:
These modes have the following effects:
Lock Mode Description ISAUTOLOCK automatic record lock ISMANULOCK manual record lock ISEXCLLOCK exclusive isam file lock The read/write mode values are defined in pi.h as:
- When ISAUTOLOCK is used, each record is locked when it is read, and unlocked after the next function call is made.
- When ISMANULOCK is used, the user must manually lock and unlock each record to perform any operation on that record. A record can be locked by using the ISLOCK mode in the isread function call, and unlocked with the isrelease function call.
- When ISEXCLLOCK is used, the entire file is locked. Other users can neither read from nor to the file. The file is automatically unlocked when it is closed with isclose.
Returns isopen returns an ISAM file identifier on success. Otherwise, it returns NULL.
Access Modes Description ISINPUT open for reading only ISOUTPUT open for writing only ISINOUT open for reading and writing See also isclose().
Function Read a record from an ISAM data file.
{ ... } isread ( IS_ISAM fd, IS_INTEGER mode, [, { ... } record ] ); Remarks Read a record from the ISAM file identified by fd. Mode is an integer identifying which record is read and whether random or sequential access is used. Also can be used to lock the record manually. The possible values are described below. Record will be used as a search key during random access, and so only needs to be supplied for ISEQUAL, ISGREAT and ISGTEQ searches.
If isread executes successfully, the current record position pointer is set to the record just read.
The mode parameter determines which record is read. The possible values depend on whether you want sequential or random access.
The values of mode for sequential access are specified in the $Utools/Utools/include/pi.h header file as:
During random access, the function compares a value stored in the record parameter to the corresponding data in the records. The mode parameter determines the comparison logic as follows:
Read Mode Description ISFIRST first record ISLAST last record ISNEXT next record ISPREV previous record ISCURR current record The search value is placed in the record argument. The record that first satisfies the condition (in the order of the index currently in use) will be returned.
Read Mode Description ISEQUAL record equal to search value ISGREAT record greater than search value ISGTEQ record greater than or equal to search value Returns isread returns an array containing the record just read on success. Otherwise, it returns NULL.
See also isstart().
Function Restore prior file postion
IS_INTEGER ispop ( IS_ISAM fd ); Remarks This routine restores the current record saved during a prior ispush call on an ISAM file identified by fd.
Returns ispop returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also ispush().
Function Save the current file postion
IS_INTEGER ispush ( IS_ISAM fd ); Remarks This routine saves the current record and file position on an ISAM file identified by fd.
Returns ispush returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also ispop().
Function Rewrite the current record.
IS_INTEGER isrewcurr ( IS_ISAM fd , { ... } record ); Remarks Overwrite the current record in an ISAM file. Fd identifies a currently open ISAM file. Record is a search value pertaining to the current key of the record to be overwritten.
Each index defined on the data file, including the primary index, is also updated as needed. Unchanged keys are not rewritten.
The record array should be loaded with the new data before the call is issued.
On return, the current record position is unchanged.
Returns isrewcurr returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isrewrite().
Function Rewrite a specific record.
IS_INTEGER isrewrite ( IS_ISAM fd , { ... } record ); Remarks Rewrite a record specified by its primary key when the primary key does not allow duplicate values. Fd identifies a currently open ISAM file. Record is a search value pertaining to the current key of the record to be overwritten.
The record array should be loaded with the new data before the isrewrite call is issued. The primary key field must match that of the record to be updated.
Each index defined on the data file, including the primary index, is also updated as needed. Unchanged keys are not rewritten.
On return, the current record position is unchanged.
Returns isrewrite returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isrewcurr().
Function Set a unique identifier.
IS_INTEGER issetunique ( IS_ISAM fd , IS_INTEGER id ); Remarks Set the value of a stored unique identifier to the one specified. The identifier can then be incremented as desired. The unique identifier is an integer contained in uniqueid. Fd identifies a currently open ISAM file.
Returns issetunique returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isuniqueid().
Function Select and index and locate a record.
IS_INTEGER isstart ( IS_ISAM fd, IS_INTEGER key, IS_INTEGER length, { ... } record, IS_INTEGER mode ); Remarks This function selects an index for subsequent use. It also locates, but does not read, a record based on the selected index. Use the isread function to read this and subsequent records using this index.
If the mode is set to ISEQUAL, ISGREAT, or ISGTEQ, then prior to calling the function a key value is placed in the record array. The length parameter determines how many bytes of the key are used in the search.
- fd An ISAM file identifier.
- key The index number to use. O = current, 1 = first, etc.
- length The length of the key to be used.
- record A record to be used as a search key for random access.
- mode The search order, described next.
The mode parameter tells isstart how to find the desired record. The allowed modes as defined in $Utools/Utools/include/pi.h are:
If the desired record is known to be the first or last in the current ordering, then use the ISFIRST or ISLAST mode value. In these cases, the record and length parameters are not used.
Start Mode Description ISFIRST first record ISLAST last record ISEQUAL record equal to search value ISGREAT record greater than search value ISGTEQ record greater than or equal to search value If the position of the desired record is not first or last, then use one of the ISEQUAL, ISGREAT, or ISGTEQ mode values (and a key value in record) to locate the desired record.
- If ISFIRST is used, then the pointer is positioned just before the first record in the selected index order. You should then call the isread function using the ISNEXT mode parameter to read the first record in the selected order.
- If ISLAST is used, then the pointer is positioned just after the last record in the selected index order. You should then call the isread function using the ISPREV mode parameter to read the last record in the selected order.
Returns isstart returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
- If ISEQUAL is used, the function locates the first record with a key value matching the record parameter.
- If ISGREAT is used, the function locates the first record whose key value is greater than the key field in the record parameter.
- If ISGTEQ is used, the function locates the first record whose key value is greater than or equal to the key field in the record parameter.
See also isread().
Function Return a unique identifier
IS_INTEGER isuniqueid ( IS_ISAM fd ); Remarks This routine returns a unique identifier for an ISAM file previously opened by isopen, and identified by fd.
Returns isuniqueid returns a positive integer on success. Otherwise, it returns NULL on error.
See also issetunique().
Function Write a new record.
IS_INTEGER iswrite ( IS_ISAM fd , { ... } record ); Remarks Write a new record into the ISAM file identified by fd. Fd identifies a currently open ISAM file. Record is the record which will be written.
The current record position pointer is left unchanged.
Any indexes are updated as needed.
If the record contains any duplicate values in fields that are defined with NODUPS attribute, an error is produced and no record is written.
Returns iswrite returns zero on success. Otherwise, it returns a non-zero value which indicates the error.
See also isrewcurr().