Inheritance diagram for File:

[legend]

Collaboration diagram for File:

[legend]

Public Member Functions
_.SYS.Journal.Record	GetRecordAfter (_.Library.Integer Address)
	Return the object reference to the record after the given journal location (<parameter>Address</parameter>)

_.SYS.Journal.Record	GetRecordAt (_.Library.Integer Address)
	Return the object reference to the record at the given journal location (<parameter>Address</parameter>)

_.SYS.Journal.Record	GetRecordBefore (_.Library.Integer Address)
	Return the object reference to the record prior to the given journal location (<parameter>Address</parameter>)

_.Library.Status	Open (_.Library.String FileName)
	To open a journal file for record retrieval.

_.Library.Integer	Use ()
	To use an open journal file for record retrieval (necessary when you have multiple journal file instances. More...

Static Public Member Functions
_.Library.Status	Archive (_.Library.Integer NSecondsOld, _.Library.Integer NBackupsOld)
	Purpose: Archive old journal files based on criteria given in number of seconds or backups, taking care not to archive files required for transaction rollbacks or crash recovery. More...

_.Library.Status	ArchiveAll ()
	Archive all journal files except those required for transaction rollbacks or crash recovery. More...

_.Library.Status	ArchiveOne (_.Library.String FilePath)
	Purpose: Archive the journal file with the given name. More...

_.Library.Status	CheckIntegrity (_.Library.String jrnlist, _.Library.Integer Detail, _.Library.String SrcDirs, _.Library.Integer quietly)
	Purpose: Check integrity of the journal file(s) More...

_.Library.Status	Compress (_.Library.String infile, _.Library.String outfile, _.Library.String enginename, _.Library.Integer chunksz)
	Compress a journal file More...

_.Library.Status	Decompress (_.Library.String infile, _.Library.String outfile)
	Decompress a journal file More...

_.Library.String	GetGUID (_.Library.String FileName)
	Get the GUID assigned to the given journal file.

_.Library.Integer	GetMaxSize (_.Library.String FileName)
	Purpose: Get max size of a journal file.

_.Library.Status	GetNext (_.Library.String FileName, _.Library.String NextFileName, _.Library.Boolean MirOnly, _.Library.String MirrorSetName)
	Purpose: Get journal file following the given journal file. More...

_.Library.Status	GetPrev (_.Library.String FileName, _.Library.String PrevFileName, _.Library.Boolean InSession, _.Library.Boolean MirOnly, _.Library.String MirrorSetName)
	Purpose: Get journal file prior to the given journal file. More...

_.Library.String	GetReason (_.Library.SysPath File)
	Return the reason for the creation of the given journal file (<parameter>File</parameter>) in string form.

_.Library.String	GetSystemGUID (_.Library.String FileName)
	Get the GUID assigned to this system in the mirror configuration file. More...

_.Library.Status	IsValidJournal (_.Library.String FileName)
	TRUE if the given <parameter>FileName</parameter> is a journal file.

_.Library.String	LastEncrypted (_.Library.String OldestFile, _.Library.Integer csn)
	Return the path of the last encrypted file no older than OldestFile if given.

_.Library.Status	Purge (_.Library.Integer NDaysOld, _.Library.Integer NBackupsOld)
	Purpose: Purge old journal files based on criteria given in number of days or backups, taking care not to purge files required for transaction rollbacks or crash recovery. More...

_.Library.Status	PurgeAll ()
	Purge all journal files except those required for transaction rollbacks or crash recovery. More...

_.Library.Status	PurgeOne (_.Library.String FilePath, _.Library.String PurgeTimeH, _.Library.Integer LogOnly)
	Purpose: Purge the journal file with the given name. More...

_.Library.Status	RequiredForClusterRecovery (_.Library.String FileName, _.Library.Integer FileCount, _.Library.Boolean SkipSelf)
	Return the path of the oldest journal file on each node that is required. More...

_.Library.Status	RequiredForRecovery (_.Library.String FileName, _.Library.Integer FileCount)
	Return the name of the oldest journal file required for crash recovery, which. More...

_.Library.Status	RequiredForRollback (_.Library.String FileName, _.Library.Integer FileCount)
	Return the path of the oldest journal file containing open transactions. More...

_.Library.Status	Restore (_.Library.String FileName, _.Library.Integer Detail)
	Purpose: (virtually) restore the journal.

_.Library.Status	RestorePIDList (_.Library.String FileName)
	Purpose: Regenerate the jobid->PID translation table based on records stored. More...

_.Library.Status	Summary (_.Library.String FilePath, _.Library.String DataFields)
	FileCount: the file counter value assigned to the file.

_.Library.String	TranslateReason (_.Library.Integer reason)
	Translate the numeric reason for the creation of a new journal file to string form.

Public Attributes
	ClusterStartTime
	Cluster start time in TimeStamp format or "" if not a cluster journal file. More...

	ClusterStartTime0
	Cluster start time in time(0) format (i.e., # of seconds since the Epoch) More...

	End
	The end of the last valid record in the journal file (applicable to open file only) More...

	FirstRecord
	Object reference to the first record in the journal file (applicable to open file only) More...

	LastMarker
	Object reference to the last marker record in the journal file (applicable to open file only) More...

	LastRecord
	Object reference to the last record in the journal file (applicable to open file only) More...

	Name
	Path of the journal file. More...

Static Public Attributes
	DOMAIN = None
	Default Localization Domain.

Detailed Description

Journal file related API.

Member Function Documentation

◆ Archive()

_.Library.Status Archive	(	_.Library.Integer	NSecondsOld,
		_.Library.Integer	NBackupsOld
	)

static

Purpose: Archive old journal files based on criteria given in number of seconds or backups, taking care not to archive files required for transaction rollbacks or crash recovery.

Parameters:

NSecondsOld: journal files must be at least this # of seconds old to be archived
NBackupsOld: journal files must be older than this # of successive successful backups to be archived

If both parameters are specified, only one criterion has to be met to qualify a journal file for archiving (subject to the restriction about rollback and crash recovery).
Note: It is the completion time, rather than the creation time, of a file that must meet the time criterion if specified. Thus, a file may not be OK to archive even though its timestamp appears to meet the time criterion.

◆ ArchiveAll()

_.Library.Status ArchiveAll ( )

static

Archive all journal files except those required for transaction rollbacks or crash recovery.

Warning: Post-backup journal files are not necessarily preserved.

◆ ArchiveOne()

_.Library.Status ArchiveOne ( _.Library.String FilePath )

static

Purpose: Archive the journal file with the given name.

Warning: This method does NOT check for open transactions before deleting the journal file.

FilePath: the full path of the journal file to archive
ArchiveTimeH: Time of archiving in $H format
LogOnly: if 1, skip archiving and log the archived file only. Default = 0

◆ CheckIntegrity()

_.Library.Status CheckIntegrity	(	_.Library.String	jrnlist,
		_.Library.Integer	Detail,
		_.Library.String	SrcDirs,
		_.Library.Integer	quietly
	)

static

Purpose: Check integrity of the journal file(s)

jrnlist can be either a file path or, if passed by reference, a number-indexed array of file paths, e.g.:
jrnlist(1)=path1, jrnlist(2)=path2, etc.
The file paths in the array should be in chronicle order, that is, path1 and path2 are assumed to have been created consecutively in the example above. If it is determined that the files in the given array do not meet that criterion, a single value 0 is returned (for "Invalid Parameter") and the top node of the array is set to the number index of the offending path.
Detail: If 1, scan each given journal file forward to locate the last record and verify it is the last record to be expected.
If 2, verify values stored in each record are retrievable.
If SrcDirs is set to 1 and passed by reference, the database directories used in the specified journal file(s) will be stored in SrcDirs array upon return.

◆ Compress()

_.Library.Status Compress	(	_.Library.String	infile,
		_.Library.String	outfile,
		_.Library.String	enginename,
		_.Library.Integer	chunksz
	)

static

Compress a journal file

engine is the name of one of the supported compression engines (eg. lz4, zstd or zlib)
chunksz is in MB (range=1-16) and specifies how much uncompressed journal data to pack into one compressed chunk. Larger chunks increase compression efficiency but requires larger buffers and reading more data from disk to access a journal file record.

The engine and chunksz parameters use the default system values if omitted.

If compression fails a partially created output file is deleted.
The output file must not exist to start with or an error is returned.
In order to compress an encrypted file the encryption key must be active and the output file will be encrypted.

Caution: Be careful with file names. If the intention is to create a compressed version of a journal file with the system's naming scheme by appending a 'z' to the name, specify a temporary output file and then rename/move the resulting file if the operation is succesful to the target name. It is best to avoid having incomplete files with a file name the system might look for. Also take care to ensure the output file has the proper filesystem level protection.

◆ Decompress()

_.Library.Status Decompress	(	_.Library.String	infile,
		_.Library.String	outfile
	)

static

Decompress a journal file

The output file must not exist or an error is returned
If decompression fails, the output file will be deleted
To decompress an encrypted file the encryption key must be active and the output file will be encrypted.

Caution: Be careful with file names and locations. If the intention is to create a uncompressed version of a journal file with the system's naming scheme by removing the 'z' from the name it is best to specify a temporary file name and then rename/move the resulting file if the operation is succesful to the desired target name. When opening a journal file the system first tries to open the uncompressed version. If it opens a file which is being generated it may think that the file is smaller than it actually is (the size will be determined when it is opened) and may return incorrect results. Also take care to ensure that the output file has the proper filesystem level protection.

◆ GetNext()

_.Library.Status GetNext	(	_.Library.String	FileName,
		_.Library.String	NextFileName,
		_.Library.Boolean	MirOnly,
		_.Library.String	MirrorSetName
	)

static

Purpose: Get journal file following the given journal file.

◆ GetPrev()

_.Library.Status GetPrev	(	_.Library.String	FileName,
		_.Library.String	PrevFileName,
		_.Library.Boolean	InSession,
		_.Library.Boolean	MirOnly,
		_.Library.String	MirrorSetName
	)

static

Purpose: Get journal file prior to the given journal file.

InSession: whether to limit the search within a journal session (default=NO)

◆ GetSystemGUID()

_.Library.String GetSystemGUID ( _.Library.String FileName )

static

Get the GUID assigned to this system in the mirror configuration file.

This is used to help people identify which system created the journal file.
Since this comes from the config file, it's possible that this can change over time but its not supposed to.

◆ Purge()

_.Library.Status Purge	(	_.Library.Integer	NDaysOld,
		_.Library.Integer	NBackupsOld
	)

static

Purpose: Purge old journal files based on criteria given in number of days or backups, taking care not to purge files required for transaction rollbacks or crash recovery.

Parameters:

NDaysOld: journal files must be at least this # of days old to be purged
NBackupsOld: journal files must be older than this # of successive successful backups to be purged

If both parameters are specified, only one criterion has to be met to qualify a journal file for purging (subject to the restriction about rollback and crash recovery).
Note: It is the completion date, rather than the creation date, of a file that must meet the date criterion if specified. Thus, a file may not be OK to purge even though the date in its name appears to meet the date criterion.

◆ PurgeAll()

_.Library.Status PurgeAll ( )

static

Purge all journal files except those required for transaction rollbacks or crash recovery.

Warning: Post-backup journal files are not necessarily preserved.

◆ PurgeOne()

_.Library.Status PurgeOne	(	_.Library.String	FilePath,
		_.Library.String	PurgeTimeH,
		_.Library.Integer	LogOnly
	)

static

Purpose: Purge the journal file with the given name.

Warning: This method does NOT check for open transactions before deleting the journal file.

FilePath: the full path of the journal file to purge
PurgeTimeH: Time of purging in $H format
LogOnly: if 1, skip purging and log the purged file only. Default = 0

◆ RequiredForClusterRecovery()

_.Library.Status RequiredForClusterRecovery	(	_.Library.String	FileName,
		_.Library.Integer	FileCount,
		_.Library.Boolean	SkipSelf
	)

static

Return the path of the oldest journal file on each node that is required.

for cluster recovery, which includes rolling forward and back transactions.
FileName = # of nodes where journal recovery is required
FileName(csn) = the path of the oldest journal file on node <#csn>
If SkipSelf = 1, skip the node where the method is called (local node is covered by RequiredForRecovery()

◆ RequiredForRecovery()

_.Library.Status RequiredForRecovery	(	_.Library.String	FileName,
		_.Library.Integer	FileCount
	)

static

Return the name of the oldest journal file required for crash recovery, which.

includes rolling forward and backward transactions.
FileName="" if journaling is disabled, meaning that none is required, as transactions cannot be rolled forward or backward from a pre-disabling file

◆ RequiredForRollback()

_.Library.Status RequiredForRollback	(	_.Library.String	FileName,
		_.Library.Integer	FileCount
	)

static

Return the path of the oldest journal file containing open transactions.

FileName: the oldest file containing open transactions or current journal file
FileCount: the file counter value assigned to the file

◆ RestorePIDList()

_.Library.Status RestorePIDList ( _.Library.String FileName )

static

Purpose: Regenerate the jobid->PID translation table based on records stored.

in the specified journal file

◆ Use()

_.Library.Integer Use ( )

To use an open journal file for record retrieval (necessary when you have multiple journal file instances.

open at the same time and need to switch from one file to another).

Member Data Documentation

◆ ClusterStartTime

ClusterStartTime

Cluster start time in TimeStamp format or "" if not a cluster journal file.

◆ ClusterStartTime0

ClusterStartTime0

Cluster start time in time(0) format (i.e., # of seconds since the Epoch)

or 0 if not a cluster journal file

◆ End

End

The end of the last valid record in the journal file (applicable to open file only)

◆ FirstRecord

FirstRecord

Object reference to the first record in the journal file (applicable to open file only)

◆ LastMarker

LastMarker

Object reference to the last marker record in the journal file (applicable to open file only)

◆ LastRecord

LastRecord

Object reference to the last record in the journal file (applicable to open file only)

◆ Name

Name

Path of the journal file.

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Function Documentation

◆ Archive()

◆ ArchiveAll()

◆ ArchiveOne()

◆ CheckIntegrity()

◆ Compress()

◆ Decompress()

◆ GetNext()

◆ GetPrev()

◆ GetSystemGUID()

◆ Purge()

◆ PurgeAll()

◆ PurgeOne()

◆ RequiredForClusterRecovery()

◆ RequiredForRecovery()

◆ RequiredForRollback()

◆ RestorePIDList()

◆ Use()

Member Data Documentation

◆ ClusterStartTime

◆ ClusterStartTime0

◆ End

◆ FirstRecord

◆ LastMarker

◆ LastRecord

◆ Name