!========================================================================
!
! Copyright (C) GemStone Systems, Inc. 1986-2008.  All Rights Reserved.
!
!  Name - pgsvr.hlp
!
!  Description:
!        Help file that is used to create help library for use with PGSVR
!
!        ****> WARNING
!        ****> Text lines in Help messages must be limited to 78 characters
!        ****> The Help run-times add a 2 character space preceding each line
!        ****> of text when the help message is output.
!
!        ****> Do Not use TAB characters.
!
! $Id: pgsvr.hlp,v 1.8 2008-01-09 19:03:28 stever Exp $
!
!========================================================================

1 Overview
PGSVR is a page server utility to serve database pages to GemStone processes.

PGSVR is a Fred shell extension, with a few simple commands to support
interactive use.

Normally, PGSVR is called through a command script (ndbg).  This command script
is referenced from netldi, passing a call-back to the GemStone process.

IF PGSVR is called without any arguments, it takes commands from standard input.
Startup, sloop, and shutdown are the normal actions.  

"agent" can be used to trace activity.

Help on an individual topic is available by typing,
  'topic' helponpgsvr

1 Commands
2 agent
Operator Name: agent
BEFORE: 
AFTER: 
PROTECTION: None

Description:

Create a well-known socket, wait indefinitely on a client, and then
enter the service loop.

Once you have entered the service loop you may exit with control-C.

Example:
startup 'foo' setwks agent sloop

You may now ^C and "sloop" freely.

2 attach
Operator Name: attach
BEFORE: locationString
AFTER: 
PROTECTION: None

Description:

The attach command allows the page server to attach to an existing memory
region allocated for a sharedPageCache.  This allows the dump page commands
to display the contents of pages in the shared cache.
The locationString is the concatination of the stoneName and stoneHostId,
which is used to determine the key for the shared memory region.

2 changesize
Operator Name: changesize
BEFORE: newSize fileHandle
AFTER: fileHandle
PROTECTION: None

Description:

change the filesize of the given dbf.  

2 clientip
Operator Name: clientip
Before: IP address (string)
After:
Protection: None

Description:

Filter all subsequent search/dump commands so that only tranlog records
generated from the designated client machine are reported.

See also gemhost and username.

Use the command nofilter to disable filtering.

2 closedbf
Operator Name: closedbf
BEFORE: fileHandle
AFTER:
PROTECTION: None

Description:

Close the given dbf.  An error is signalled if this is not successful.
Has no effect on pgsvr's extent table.
Compare with opendbf and dump.

2 convertrootpage
Operator Name: convertrootpage
BEFORE:
AFTER:
PROTECTION: None

Desription:
Modifies the root page compatibility level and stnVersion
string to be consistent with the version of this page server
process.  This operation should only be done during DBF 
upgrades, as indiscriminate changing of these fields can 
result in the failure of internal consistancy checks and 
corruption of the database.

This command must be preceded by a readpage on the desired
rootpage, and followed by a writepage to write out the change.

This command must be applied to all extents, and to all 4 
root pages in each extent (for 6.0, on pages 1,17,33, and 49).

2 copydbf
Operator Name: copydbf
BEFORE: fromName toName minSize byteOrder fullInfo ignoreReadErr compressOutput pageReports 
AFTER: statusCode  (0 = success , > 0 means failure)
PROTECTION: None

Description:

Copy the dbfs.  

fromName is a network resource specification of the source file.

toName is a network resource specification of the destination file.

minSize is the minimum size of the destination file, in megabytes.
  0 means use the actual size of the source file.

byteOrder is an integer specifying byte ordering of the destination file.
  0 == native byte ordering of the machine running the copydbf command.
  1 == preserve byte order of source file             (copydbf -P)
  2 == Least significant byte first (Intel x86 native)  (copydbf -l)
  3 == Most significant byte first (SPARC, Rs6000, PA-RISC native) (copydbf -m)

fullInfo is an integer
  0 = normal, print last checkpoint found in a tranlog.
  1 = full information, print all checkpoints in a tranlog, Same as normal
        for other kinds of files.

ignoreReadErr is an integer
  0 = normal
  1 = ignore read errors, and substitute invalid pages in the output;
        only applies to copying extents

compressOutput is an integer
  0 = normal output
  1 = write output with gzip compression

pageReports is an integer
  0 = normal output
  1 = extra debugging output

Example
  pgsvr> 'a.dbf' 'b.dbf' 0 0 0 0 0 0 copydbf

Errors, if any, are written to stdout and terminate the copy.

A return status code (HOST_EXIT_SUCCESS or HOST_EXIT_ERR) is pushed on
the stack to indicate the status of the operation.

3 Examples
Example 1: To copy between two machines, using this processor's byte ordering
on the output file, say

'in.dbf' 'out.dbf' 0 0 copydbf

Example 2:  On the VAX/80386, to copy a SPARC/MC68000 dbf to 
the vax with the output file having SPARC/MC68000 byte ordering, you would say,

'in.dbf' 'out.dbf' 0 3 copydbf

Example 3: On the SPARC/MC68000, to copy a vax/80386 dbf to the SPARC/MC68000, 
with the output file having vax/80386 byte ordering, you would say,

'in.dbf' 'out.dbf' 0 2 copydbf

2 detach
Operator Name: detach
BEFORE: 
AFTER: 
PROTECTION: None

Description:

To detach from the shared page cache.

2 diffdbfs
Operator Name: diffdbfs
BEFORE: fileHandle fileHandle
AFTER: fileHandle fileHandle
PROTECTION: None

Description:

Do a page-by-page comparison of two extents and print a list of
pageIds which differ between the two extents.

2 dump
Operator Name: dump
BEFORE: fileHandle pageNum
AFTER: fileHandle
PROTECTION: None

Description:

Dump the given page of an open dbf onto standard out.  Compare
with opendbf and closedbf.   Supports multiple extents, if opendbf
used to open files in extent order.

If fileHandle == 0, then pageNum is taken as a RepPageIdType, 
the extentId is taken from pageNum and the extent table (see opendbf) 
is used to determine the file to access for the given page. 
If fileHandle != 0, then pageNum is taken as a absolute page number 
within the specified file.

PageIds not in the primary extent are printed with the format  
<extendId>;<pageInExtent> .
object references in OT leaf pages are printed in the format
 <pageId>+<offset>.  Values of bits in bitmaps are printed as
longs (i.e. raw pageIds). Use printPageId to convert a long to
a formatted pageId.  In commit records, embedded bitmaps stored
within the commit record page have only their treeRoot printed.
To print the complete contents of a commit record containing embedded
bitmaps, use "dumpfull"

2 dumpcrs
Operator Name: dumpcrs
BEFORE: pageId numCrs
AFTER: 
PROTECTION: none

Description:

Dump the complete contents of a chain of commit records.

"pageId" specifies either a repository rootPage or a commit record at which
to start dumping pages.  "pageId" will always be resolved using the
extent table (see "dump") Dumping will continue by chaining through the
commit record field of a root page and through the "next commit record"
field of commit records.  

If "pageId" is 0 or -1, the most current root page
in the circular buffer of root pages in the primary extent will be used 
to determine the first commit record at which to start reading.

"numCrs" is the number of commit records to attempt to dump.
The first page dumped is not included in the count of pages dumped .
 
2 dumpfull
Operator Name: dumpfull
BEFORE: fileHandle pageNum
AFTER: fileHandle
PROTECTION: None

Description:

Dump the the complete contents of the given page of an open dbf onto 
standard out.  This is the same as "dump" except that embedded bitmaps
within commit record pages are printed in full detail. For more
information see "dump".

2 dumphdr
Operator Name: dumphdr
BEFORE: fileHandle pageNum
AFTER: fileHandle
PROTECTION: None

Description:

Dump only the page header of the given page of an open dbf onto 
standard out.    See also   dump, dumpfull  .

2 dumplog
BEFORE: fileHandle blockId numPhysicalRecords
AFTER: fileHandle
PROTECTION: None

Description:

Dump the specified number of physical records in a transaction log or
in a backup file, beginning at the specified blockId in the file.  

ObjSType contents within data records are NOT dumped.

See also: dumplogfull

2 dumplogclasses
BEFORE: fileHandle blockId numPhysicalRecords
AFTER: fileHandle
PROTECTION: None

Description:

Dump the specified number of physical records in a transaction log or
in a backup file, beginning at the specified blockId in the file.  

Same as dumplog, except oops of object classes  are also printed where
available.

2 dumplogfull
BEFORE: fileHandle blockId numPhysicalRecords
AFTER: fileHandle
PROTECTION: None

Description:

Dump the specified number of physical records in a transaction log or in
a backup file, beginning at the specified blockId in the file.  

ObjSType contents within data records ARE dumped.

See also: dumplog

2 dumproot
Operator Name: dumproot
BEFORE: fileHandle pageNum
AFTER: fileHandle
PROTECTION: None

Description:

starting with the specified pageNum in the specified file (which must
be an extent), perform a partial dump of REP_NUM_CHECKPOINTS 
(currently 4) root pages.

The information dumped is sufficient to determine by inspection
which root page is the most current.

2 filename
Operator Name: filename
BEFORE: fileHandle 
AFTER: fileHandle
PROTECTION: None

Description: 

Prints the name of the file

2 filenamesequal
Operator Name: filenamesequal
BEFORE: filename1 filename2 
AFTER: 
PROTECTION: None

Description: 

Prints whether the two filenames are equal

2 filesize
Operator Name: filesize
BEFORE: fileHandle 
AFTER: fileHandle
PROTECTION: None

Description:

prints the size of the file in records

2 findcheckpoints
Operator Name: findcheckpoints
BEFORE: none 
AFTER: none
PROTECTION: None

Description:

Cause subsequent "searchlog" commands to print all checkpoint records
encountered.  The default for "searchlog" is that checkpoint records
are not printed.

2 findinstvar
Operator Name: findinstvar
BEFORE: oop 
AFTER: none
PROTECTION: None

Description:

Adds oop to the buffer of instVar values to be searched for when analyzing
a transaction log with "searchlog".  This buffer will match any
instvars and tags in objects.

2 findnone
Operator Name: findnone
BEFORE: none 
AFTER: none
PROTECTION: None

Description:

Clear all search buffers used by the "searchlog" command.  This cancels
all preceeding "findoop", "findpage", "findinstvar", and "findcheckpoints".

2 findoop
Operator Name: findoop
BEFORE: oop 
AFTER: none
PROTECTION: None

Description:

Adds oop to the buffer of oops to be searched for when analyzing
a transaction log with "searchlog".  This buffer matches against the
hdr.objId of objects in data records, and matches resource identifier
records containing oops.

2 findpage
Operator Name: findpage
BEFORE: pageId 
AFTER: none
PROTECTION: None

Description:

Adds pageID to the buffer of pageIds to be searched for when analyzing
a transaction log with "searchlog".  This buffer matches against
resource identifer records containing pageIds, and against the crPageId
field of commit records in the log .

2 findrestore
Operator Name: findrestore
BEFORE: none 
AFTER: none
PROTECTION: None

Description:

When analyzing a transaction log with "searchlog", print information
about checkpoints that represent "in-restore" state, and the transtions
into and out of restore state.  To cancel, use "findnone" .

2 finishio
Operator Name: finishio
BEFORE: fileHandle 
AFTER: fileHandle
PROTECTION: None

Description:

complete async writes from rdbfio to pgsvr

2 flushdbf
Operator Name: flushdbf
BEFORE: fileHandle 
AFTER: fileHandle
PROTECTION: None

Description:

Flush the DBF (sync)

2 fullpathname
Operator Name: fullpathname
BEFORE: fileName
AFTER: newName
PROTECTION: None

Description:

Expand the given (DBF) filename to its full extent.

2 gemhost
Operator Name: gemhost
Before:  hostName (string)
After:
Protection: None

Description:

Filter all subsequent search/dump commands so that only tranlog records
generated from a topaz/gem process on the designated host machine are reported.

See also clientip and username.

Use the command nofilter to disable filtering.

2 getGeometry
Operator Name: getGeometry
BEFORE: fileHandle
AFTER: fileHandle
PROTECTION: None

Description:

Print the file's geometry

2 getprotocol
Operator Name: getprotocol
BEFORE: 
AFTER: aStr 
PROTECTION: None

Description:

Returns the protocol served by this server

2 getlocationstr
Operator Name: getlocationstr
BEFORE: 
AFTER: aStr 
PROTECTION: None

Description:

Returns the name of the SharedPageCache locationstring

2 getnumpages
Operator Name: getnumpages
BEFORE: 
AFTER: anInt
PROTECTION: None

Description:

Returns the number of pages allocated for the sharedPageCache.

2 getnumprocs
Operator Name: getnumprocs
BEFORE: 
AFTER: anInt
PROTECTION: None

Description:

Returns the number of processes allowed for the sharedPageCache.

2 getspinlockcount
Operator Name: getspinlockcount
BEFORE: 
AFTER: anInt
PROTECTION: None

Description:

Returns the number of trys that the process will make attempting to 
get a lock before sleeping on a semaphore.

2 getwks
Operator Name: getwks
BEFORE: 
AFTER: aStr 
PROTECTION: None

Description:

Returns the name of the well-known socket.

2 lookupoop
Operator Name: lookupoop
BEFORE: pageId levels objId
AFTER:
Protection: None

Description:

Given OT root pageId,levels,  tries to lookup objId .
and prints the dataPageId found.  Must have opened all extents with
opendbf or opendbfnolock in extentId order .

2 makeemptydp
Operator Name: makeemptydp

Before: pageId
After: none

set the contents of the static page buffer to be an empty data page,
for subsequent use by writepage.

2 nofilter
Operator Name: nofilter
Before:
After:
Protection: none

Description:

Disables any search/dump filtering in effect.
See commands clientip, gemhost, and username 
for information on filtering search/dump output.

2 nopause
Operator Name: nopause
Before: 
After:
Protection: none

Description:

Disable pause at end of each screen of output. See also "pause"

2 opendbf
Operator Name: opendbf
BEFORE: dbfName
AFTER: fileHandle
PROTECTION: None

Description:

Open the given database file.  
If the file is an extent, appends the resulting file handle to the 
pgsvr extent table; otherwise for transaction logs and files produced by
full backup, just puts the fileHandle on the fred stack.  The root page(s)
of files are read automatically to determine type of file (extent, tranlog,
or backup) and byte order.

The extent table is initialized to empty at executable startup.
Extents must be opened in order of their extentIds in order for 
handling of multiple extents to work properly.

Read-only  files may be opened with this command .

synonims: openextent

See also: opendbfnolock

2 opendbfnolock
Operator Name: opendbf
BEFORE: dbfName
AFTER: fileHandle
PROTECTION: None

Description:

Open the given DBF without placing an advisory lock on the DBF.
The file being opened must have read and write permissions.

Otherwise the same as opendbf.

synonyms: openextentnolock openlog

2 pause
Operator Name: pause
Before: 
After:
Protection: none

Description:

Enable pause at end of each screen of output. See also "nopause"

2 printbitmap
Operator Name: printbitmap
BEFORE: pageId levels
AFTER: 
Protection: None

Description:

Prints the entire contents of a bitmap.  File handles for extents
will be taken from the pgsvr extent table(see opendbf).

2 printpageid
Operator Name: printpageid
BEFORE: pageId
AFTER: 
PROTECTION: None

Description:

print the pageId using the format <extentId>;<pageInExtent>

2 pushpage
Operator Name: pushpage

 Obsolete, no longer implemented.   See writepage, readpage .

2 readpage
Operator Name: readpage
BEFORE: pageId
AFTER:  none
PROTECTION: None

Description:

read given page into static page buffer for subsequent examination
with a C debugger, from already open extent specified by pageId. extents
must have been opened in extentId order with opendbf .

2 remove
Operator Name: remove
BEFORE: aFileName
AFTER:
PROTECTION: None

synonims:  removedbf 

Description:

Remove the given DBF

2 searchlog
BEFORE: fileHandle blockId numPhysicalRecords
AFTER: fileHandle
PROTECTION: None

Description:

Search the specified number of physical records in a transaction log or
in a backup file, beginning at the specified blockId in the file.  
Only those records which match a previous "findoop", "findpage",
"findinstvar", or "findcheckpoints" command will be printed.

ObjSType contents within data records are NOT dumped.

See also: dumplog, findnone

2 searchlogclasses
BEFORE: fileHandle blockId numPhysicalRecords
AFTER: fileHandle
PROTECTION: None

Description:

Same as searchlog, but oops of classes of objects are printed where
available.

2 searchlogfull
BEFORE: fileHandle blockId numPhysicalRecords
AFTER: fileHandle
PROTECTION: None

Description:

same as searchlog except that entire contents of transaction log records,
not just objectIds, are dumped.

Only those records which match a previous "findoop", "findpage",
"findinstvar", or "findcheckpoints" command will be printed.

ObjSType contents within data records ARE dumped.

Reminder: use "nopause" in conjunction with this command.

See also: dumplog, findnone

2 setfileprefix
Operator Name: setfileprefix
BEFORE: aStr
AFTER:
PROTECTION: None

Desscription:
Set the default filename prefix used by copydbf command 
when  destinationNRS is a file system directory.  See man page of copydbf
for more details.

2 setlocationstr
Operator Name: setlocationstr

2 setprotocol
Operator Name: setprotocol
BEFORE: aStr
AFTER:
PROTECTION: None

Desscription:
Set the connection protocol used in next startup command

2 setlocationstr
Operator Name: setlocationstr
BEFORE: aStr
AFTER: 
PROTECTION: None

Description:

Sets the name of the SharedPageCache location string.  This string is used
as a filename from which a unique key is determined to identify the 
shared memory and semaphore structures.

2 setnumpages
Operator Name: setnumpages
BEFORE: anInt
AFTER: 
PROTECTION: None

Description:

Sets the number of pages that should be allocated for a shared page cache
if startup is executed and there is no shared memory segment allocated
for the specified well known socket.

2 setnumprocs
Operator Name: setnumprocs
BEFORE: anInt
AFTER: 
PROTECTION: None

Description:

Sets the number of processes that should be allowed for a shared page cache
if startup is executed and there is no shared memory segment allocated
for the specified well known socket.

2 setspinlockcount
Operator Name: setspinlockcount
BEFORE: anInt
AFTER: 
PROTECTION: None

Description:

Sets the number of times that a process should try to get a spin lock before
it sleeps on a semaphore.  Used if startup is executed and there is no 
shared memory segment allocated for the specified well known socket.

2 setwks
Operator Name: setwks
BEFORE: aStr
AFTER: 
PROTECTION: None

Description:

Sets the name of the well-known socket.

2 shutdown
Operator Name: shutdown
BEFORE: 
AFTER: 
PROTECTION: None

Description:

Turns off the well-known socket.

2 sloop
Operator Name: sloop
BEFORE: 
AFTER: 
PROTECTION: None

Description:

Attempt a NetFakeConnect (accept with timeout) on the client.
Once you have entered the service loop you may exit with control-C.

2 startup
Operator Name: startup
BEFORE: 
AFTER:
PROTECTION: None

Description:

Fires up server using current parameters

2 truncatedbf
Operator Name: truncatedbf
BEFORE: aFileName aPercentage
AFTER: statusCode  (0 = success , > 0 means failure)
PROTECTION: None

Description:

truncate the specified file to  aPercentage of it's original size
aPercentage must be an integer between 0 and 100 inclusive .
The new size of the file is
  oldSize * aPercentage / 100 
in units of dbf records .

2 truncatetosize
Operator Name: truncatedbf
BEFORE: aFileName aSize
AFTER: statusCode  (0 = success , > 0 means failure)
PROTECTION: None

Description:

truncate the specified file to aSize dbf records .
aSize must be an integer between 0 and the size of the file.
aSize is in units of physical records 
(8KB for extent, 512 bytes for tranlog, 128KB for backups) 

2 username
Operator Name: username
Before:  userName (string)
After:
Protection: None

Description:

Filter all subsequent search/dump commands so that only tranlog records
generated by the designated UserName are reported.

Use the command nofilter to disable filtering.

See also clientip , gemhost, printusernames, noprintusernames .

2 writepage
Operator Name: writepage
BEFORE: pageId
AFTER:  none
PROTECTION: None

Description:

write static page buffer to extent specified by pageId.
extents must have been opened in extentId order with opendbf .
Compare with readpage, dumppage, and opendbf.
