This loads a font easier to read for people with dyslexia.
This renders the document in high contrast mode.
This renders the document as white on black
This can help those with trouble processing rapid screen movements.
Decrease text size Increase text size Reset text size
Accessibility menu
Search icon
Menu

Archiver

1. Establishing communication

Communication between Archiver and the providers is done using the Tcl-DP RPC facilities. Archiver implements a command called ProviderCommunicate which providers call to tell make requests to Archiver. Providers must have a command called ArchiverCommunicate for Archiver to make requests to the provider.

When Archiver starts, it sets itself up as a Tcl-DP RPC server using the command:

dp_MakeRPCServer archiver where archiver is defined in the /etc/services database on the host. Providers need to set themselves up as a Tcl-DP RPC client with a command like: set ARCHIVER [dp_MakeRPCClient $ARCHIVER_HOST archiver] where ARCHIVER_HOST is a Tcl variable containing the name of the host on which Archiver is running and archiver is defined in the /etc/services database on the host running the provider. The Tcl variable ARCHIVER becomes the RPC peer handle for communicating to Archiver.

When a provider is established as a Tcl-DP RPC client, it can send commands to Archiver using the dp_RPC command as per the following:

dp_RPC $ARCHIVER ProviderCommunicate command args where ARCHIVER is a variable containing the RPC peer handle returned by the dp_MakeRPCClient command, command and args are the command and extra arguments specified to the ProviderCommunicate command.

When a provider registers using the register command, Archiver uses the file handle obtained to establish a reverse connection to the provider. The provider must implement a command ArchiverCommunicate for Archiver to call.

2. Commands the provider can send to Archiver

The declaration of ProviderCommunicate is:

proc ProviderCommunicate {Command args} { . . . } ProviderCommunicate returns a list. The first element is a number which is the error/status code. The second element is optional and depends upon the value of Command. The argument Command is one of the keywords which specifies the action the provider is requesting of Archiver. args is a list of extra arguments. The structure of args depends upon the value of Command. This is given in the descriptions below under the heading of "Extra args:".

Command can have one of the following values:

  • register - Make your existence known to Archiver.
  • bye - Conduct an orderly exit.
  • state - Notify Archiver of change of state.
  • allocate - Ask Archiver for a place to put data.
  • deallocate - Inform Archiver that an allocated partition is no longer required.
  • root - Tell Archiver you are using this root to put files into.
  • noroot - Tell archiver that you are no longer putting files here.
  • status - Get the status of Archiver.
  • go - Make a CDROM.
  • hello - No operation.
  • addlog - Add an entry to Archiver's log.
  • updateroot - Inform Archiver that you have changed a directory.

ProviderCommunicate can return any one of the following error codes in the first element of the return value:

  • 0: Normal successful completion.
  • -1: The provider is not known to Archiver (hasn't registered).
  • -2: The provider is already registered. This happens if the provider tries to register again.
  • -3: The root is not allocated to the provider sending the command.
  • -4: reserved
  • -5: A private root supplied with the root command is one of the partitions owned by Archiver.
  • -6: An invalid ISO-9660 volume name was supplied. A valid ISO-9660 volume contains only uppercase characters, digits and underscores is no longer than 32 characters. A null string is not allowed.
  • -7: Archiver is busy. Try again later.
  • -8: The provider name being registered is not unique. Choose another.
The value of subsequent elements are listed below under the heading "Return value:".

register

Extra args:

  • name: The name of the application registering as a provider. The name must be unique among the providers currently registered with Archiver. If it is not unique, Archiver returns the -8 error code.
  • description: A description of the provider. This can be any string which describes what the provider does.
  • host: The name of the host on which the provider is running.
Return value: none

If Archiver says that the provider name is not unique, then another must be chosen. It is recommended that the wish interpreter name be used as the first try. If this is not unique, then add a string of the form #n where n starts at 2 and increments until a unique provider name is found. An example of this is:

# Register with Archiver. Assumes the following variables have been set: # APPLICATION_NAME: The name of the application. # PROVIDER_DESCRIPTION: The description of the provider. # ARCHIVER: The peer handle of the RPC for Archiver. set Num 2 set AName $APPLICATION_NAME while 1 { set R [lindex [dp_RPC $ARCHIVER ProviderCommunicate register \ $AName PROVIDER_DESCRIPTION] 0] if {$R == 0} { break } elseif {$R == -8} { set AName "${APPLICATION_NAME} #${Num}" incr Num } else { error "Invalid error from Archiver: ${R}" } }

bye

Extra args: none

Return value: none

This is the reverse of the register command. If the provider exits abnormally, Archiver will usually be able recognize that the port has closed and will be able to do an implicit bye command.

state

Extra args:

  • newstate: This is the new state of the provider.
Return value: none

The state of a provider is just a string which the provider supplies to describe how it is feeling at the moment. Except for the QUIET and REMOTE states, Archiver does nothing with the string but display it. If the provider is running on a different host to Archiver, this command is ignored. In this case, Archiver always displays the state of the provider as REMOTE. Local providers should not use a state of REMOTE.

If the provider is running on the same host as Archiver, then Archiver will display the current value of the state string. When Archiver sends a provider the qreq command, the provider is required to change to QUIET state as soon as possible. When in the QUIET state, the provider should do no substantial disk or network I/O.

allocate

Extra args: none

Return value:
  • root: The root which was allocated. This will be an empty string if there was no free partition.

This command is only available to providers running on the same host as Archiver.

Archiver maintains several disk partitions which can be used as temporary storage areas for CDROM data. These can be dynamically allocated to providers for their use while gathering data from an external source (eg, Exabyte tape). The allocate command is used by a provider to ask to be allocated a free partition. When the provider has finished with the partition, it uses the deallocate command to inform Archiver. Archiver ensures that a partition allocated to a provider will be empty.

Once a provider has a partition allocated, it should call the updateroot command whenever it changes the contents of the partition.

deallocate

Extra args:

  • root: The root to be deallocated.
Return value: none

This command is only available to providers running on the same host as Archiver.

The deallocate command deallocates a disk partition allocated by the allocate command.

root

Extra args:

  • extern-root: The name of a directory where the provider is putting files.
Return value: none

If the provider is building a CDROM source in a private directory, Archiver can be notified of this so that it can be displayed in the Archiver control panel. This gives the Archiver user the ability to look at the root and display the current contents and size of the files in that directory. The extern-root directory must be visible to Archiver.

Telling Archiver that a provider is using a directory to build files is entierly optional for the provider. When archiver gets this specification, it just displays as part of the provider specification, so that the Archiver user can display the contents of the root.

Once a provider has told Archiver that it is using a directory to store files, it should call the updateroot command whenever it changes the contents of that directory.

noroot

Extra args:

  • extern-root: An external root the provider no longer using.
Return value:

If the provider used the root command to specify an external root to Archiver, this command tells Archiver that the provider is no longer using that directory, and Archiver removes it from the display.

status

Extra args: none

Return value:
  • archiver-list: A list of the providers currently registered with Archiver.

Makes Archiver return information about all the providers which are currently registered. The format of this information is not yet defined.

go

Extra args:

  • root: The source specification for the CDROM.
  • name-table: The ISO-9660 name translation table for the CDROM.
  • vol-name: The volume name of the CDROM.
  • description: A description string for the CDROM label.
  • copyright: A copyright string for the CDROM label.
  • class: The class of the CDROM job.
Return value: none

If the Pv routines are being used, the PvDiscPending should be set before executing the go command.

hello

Extra args: none

Return value:
  • hello-string: The string "Archiver".

Makes Archiver return the string "Archiver".

addlog

Extra args:

  • log-entry: A string to go into the Archiver log.
Return value: none

This command puts an entry into the Archiver log. The string can be any piece of short text. Archiver prepends the time, date and provider name to the string before it is put into the log.

updateroot

Extra args:

  • root: The directory to be updated.
Return value: none

For every provider, Archiver keeps a list of directory roots. These are set up using the allocate and root commands. The updateroot command should be called whenever a provider updates one of these directories, giving the directory as the argument to the command. This tells Archiver to update the listing of the directory, if one is being displayed.

3. Commands Archiver can send to the provider

Every provider is required to implement the ArchiverCommunicate command. The declaration of ArchiverCommunicate is:

proc ArchiverCommunicate {Command args} { . . . } ArchiverCommunicate returns a value depending upon the value of Command. The argument Command is one of the keywords which specifies the action Archiver is requesting of the provider. args is a list of extra arguments. The structure of args depends upon the value of Command. This is given in the descriptions below under the heading of "Extra args:".

Command can have one of the following values:

  • hello - No operation.
  • qreq - Archiver is requesting the provider go into QUIET mode as soon as possible.
  • qfin - Provider can exit QUIET mode.
  • discfin - The disc requested by the provider has complted.
ArchiverCommunicate returns a string, depending upon the command. TThis string is listed below under the heading "Return value"

hello

Extra args: none

Return value:
  • hello-string: The string provider.

Makes the provider return the string "provider".

qreq

Extra args: none

Return value: none

This command will only be sent to providers running on the same host as Archiver.

This is the "quiet request" command from Archiver. It will only be delivered to providers running on the same host as Archiver. As soon as possible (as soon as any current I/O activity has finished), the provider should go into QUIET state. While in QUIET state, the provider shouldn't perform any substantial disk or network I/O.

Archiver needs to stop all I/O and most CPU activity on the host machine when it is making a CDROM. When a request comes in from a provider to make a CDROM, Archiver sens the qreq command to all registered local providers (including the one which sent the disc request command, if it is local). When all providers are in the QUIET state, the CDROM is made. When the CDROM is finished, Archiver sends the qfin command to all the local providers.

qfin

Extra args: none

Return value: none

This command will only be sent to providers running on the same host as Archiver.

This is the "quiet finished" command from Archiver. The provider should switch out of QUIET state and continue with any I/O tasks which were interrupted by the qreq command.

discfin

Extra args:

  • error-status: A number indicating how the disc job finished. It can have one of the following values:
    • 0: The disc was successful. The barcode argument contains the barcode of the disc which was made.
    • 1: DirectWrite reported that the disc failed. The error-string argument contains the error reported by DirectWrite. The barcode argument will contain the barcode of the disc if DirectWrite found one.
    • 2: The disc was aborted by the Archiver user pressing the Cancel button.
    • 3: The software couldn't write the volume id to the premaster file. The error-string argument contains the error returned by the volume id software.
    • 4: The disc authoring script couldn't be made. The error-string argument contains the error generated by the DAS generation software.
    • 5: There was an error creating the disc premaster file. The error-string argument contains the error generated by the premaster software.
  • barcode: The barcode of the CDROM, if one was found. The barcode is a string of 12 decimal digits. If no barcode was found (due to some kind of error), barcode will be a null string.
  • error-string: The error string returned from whatever piece of software generated the error. This will be empty if error-status is equal to zero.
Return value: none

This command is sent to the requester of a CDROM job when the disc has been made. The provider can determine if the job was successful, and if so, the barcode of the CDROM which was made.

4. The Pv routines

To make life easier for provider implementers, a set of standard procedures has been written to take care of the communications between the provider and Archiver. It implements the ArchiverCommunicate command described above and a small set of states, which should be sufficient for most purposes. A provider which makes use of the Pv routines doesn't need to call any of the Tcl-DP commands to communicate with Archiver.

The description of the Pv facilities is divided into three sections:

  • Global variables - Variables either set by the Pv routines, or required by the Pv routines.
  • Global procedures - Procedures the provider can call to synchronize with Archiver.
  • Callouts - Procedures which, if they exist, the Pv routines will call on certain events.

Global variables

PvAPPLICATION_NAME

The provider must set PvAPPLICATION_NAME to the generic name of the provider. It may be set to the Tk interpreter name. The Pv routines use the value of PvApplicationName to derive the provider name to send to Archiver.

PvPROVIDER_DESCRIPTION

The provider must set PvPROVIDER_DESCRIPTION to a string which describes the function of the provider. Archiver displays this string init's on-screen display.

Global procedures

  • PvInit - Initialize the Pv routines and open a connection to Archiver.
  • PvClose - Close the connection with Archiver.
  • PvMakeBusy - Go into BUSY state to do some processing.
  • PvMakeIdle - Go into IDLE state when the processing is finished.
  • PvAllocate - Ask Archiver for a place to put data.
  • PvDeallocate - Inform Archiver that an allocated partition is no lonver required.
  • PvRoot - Tell Archiver you are using a root to put files into.
  • PvNoRoot - Tell Archiver that you are no longer putting files here.
  • PvStatus - Get the status of Archiver.
  • PvGo - Make a CDROM.
  • PvHello - No operatio.
  • PvAddLog - Add an entry to Archiver's log.
  • PvUpdateRoot - Inform Archiver that you have changed a directory contents.

PvInit

PvClose

PvMakeBusy

PvMakeIdle

PvAllocate

PvDeallocate

PvRoot

PvNoRoot

PvStatus

PvGo

PvHello

PvAddLog

PvUpdateRoot

Callouts

  • PvSetQuiet - Called just before entering QUIET mode.
  • PvUnsetQuiet - Called just after exiting QUIET state.
  • PvDiscFin - Called after a requested CDROM job has finished.

PvSetQuiet

PvUnsetQuiet

PvDiscFin

5. Translating between Rock Ridge and ISO-9660 names.

6. Log files

7. Examples

8. System configuration

Original: dloone@atnf.csiro.au
Modified: nmckay (9-Oct-1995)