Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

PartitionAdmin

Partition file administration function.

Short Name

PTADMIN()

Type

Utility Function

Declaration

COUNT PartitionAdmin(FILNO datno, pVOID partdesc, LONG prawno, COUNT ptmode)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

PartitionAdmin() manages the partitions for datno, the file number for the host data file.

  • partdesc may be either a pointer to a partition member data file name, a pointer to a key value (already transformed) representative of a partition member, or NULL.
  • prawno may either be a “raw” partition number or its value is ignored.
  • ptmode controls how to interpret partdesc and prawno as well as what action PartitionAdmin() should perform. ptmode is formed by OR-ing together the appropriate bit values from this list defined in ctport.h:

Value

Symbolic Constant

Explanation

Partition Identifier

0x0001

ptADMINname

partdesc is a file name (ignore prawno)

0x0002

ptADMINkey

partdesc is a key value (ignore prawno)

0x0004

ptADMINraw

use prawno (ignore partdesc)

Operation Code

0x0010

ptADMINpurge

remove partition(s)

0x0020

ptADMINadd

add partition(s)

0x0040

ptADMINarchive

archive partition(s)

0x0080

ptADMINbase

modify lower limit on prawno

0x0100

ptADMINnumber*

modify limit on number of partitions

0x0200

ptADMINreuse*

reuse purged member raw #

0x0400

ptADMINactivate

activate archived member(s)

0x0800

ptADMINstatus

return member status in sysiocod

0x1000

ptADMINmulti*

purge, archive, etc. multiple partitions

0x2000

ptADMINrule

partdesc contains rule definition

0x4000

ptADMINrebuild

rebuild a specific member

* The ptADMINnumber, ptADMINreuse, and ptADMINmulti options have NOT been implemented.

Note: All calls to PartitionAdmin() must specify exactly one way in which the partition will be identified (ptADMINname or ptADMINkey or ptADMINraw) and exactly one operation (for example., ptADMINpurge). If the ptmode parameter is not correctly formed, PTADMIN() will return BMOD_ERR (446, Bad mode: parameter out of range).

ptADMINstatus Option

If the ptADMINstatus option is used, then PartitionAdmin() returns either an error code (such as PLOW_ERR, 712, partition number is out of range - low) or NO_ERROR. If NO_ERROR is returned, then sysiocod contains the member status code from this list:

Value

Symbolic Constant

Explanation

0

pmSTATUSnone

member does not exist

1

pmSTATUSexst

member active

2

pmSTATUSopnd

member active and physically opened

3

pmSTATUSarhv

member archived

4

pmSTATUSpurg

member purged

19

pmSTATUSparc

member archive pending

20

pmSTATUSppnd

member purge pending

There is a subtlety here concerning a return of pmSTATUSnone in sysiocod, and some possible error codes returned by PTADMIN(). For example, a NO_ERROR return from PTADMIN(.........,ptADMINstatus) and sysiocod of pmSTATUSnone means that the partition number is in the current valid range, but that no such partition member has been created. A PLOW_ERR (712, out of range - low) return means that the partition number is out of the current valid range (whether or not such a partition was ever created).

A partition that is not in use or a partition that has been opened by the host (that is, not explicitly by the application), and which is not in use by another user, can be archived or purged.

Base Partition Number

The record add and update functions attempt to increase the base partition number of the partitioned file to the first current active partition number if one exists, or to the partition number that will hold the newly-added or updated record if no current active partition exists.

Return

Value

Symbolic Constant

Explanation

0

NO_ERROR

Successful function

712

PLOW_ERR

Partition number out of range - low

713

PHST_ERR

File is not partition host

714

PMBR_ERR

File is not partition member

715

PNOT_ERR

Raw partition does not exist

716

PXPR_ERR

Bad value for partition key

717

POVR_ERR

Could not overload partition number

718

PUSD_ERR

Partition member in use

719

PPND_ERR

Partition member pending purge

720

PPRG_ERR

Partition member purged

721

PARC_ERR

Partition member archived

722

PLST_ERR

Bad partition host list

723

PTRY_ERR

Must retry operation

724

PCRP_ERR

Bad current ISAM position for host

725

PVRN_ERR

Partition resource version error

-726

PPRG_COD

Duplicate error caused by purged part

727

PFMD_ERR

Bad partition file mode settings

728

PSUP_ERR

Attempt to use partitioned file without partition support

729

PUNQ_ERR

Purged unique global keys encountered

730

PHGH_ERR

Partition number out of range - high

731

PRIK_ERR

Illegal operation with partition key

See c-tree Error Codes for a complete listing of valid c-tree error values.

Limitations

  • A raw partition number must be 1 or greater.
  • Encryption is not supported for partitioned files.
  • To support transaction processing, a partitioned file must also support transaction-dependent file creation (TRANDEP).

TOCIndex