PartitionAdmin

Partition file administration function.

Short Name

PTADMIN()

Type

Utility Function

Declaration

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

Description

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 Identifer
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

* 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).

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.

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 Plus Error Codes for a complete listing of valid c-tree Plus 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).