Archiver
- 1. Establishing communication
- 2. Commands the provider can send to Archiver
- 3. Commands Archiver can send to the provider
- 4. The Pv routines
- 5. Translating between Rock Ridge and ISO-9660 names
- 6. Log files
- 7. Examples
- 8. System configuration
- 9. Related documents
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:
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:
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:
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.
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.
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:
bye
Extra args: 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.
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
- 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.
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.
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.
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
- 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.
If the Pv routines are being used, the PvDiscPending should be set before executing the go command.
hello
Extra args: none
- hello-string: The string "Archiver".
Makes Archiver return the string "Archiver".
addlog
Extra args:
- log-entry: A string to go into the Archiver log.
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.
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:
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.
hello
Extra args: none
- hello-string: The string provider.
Makes the provider return the string "provider".
qreq
Extra args: 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
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.
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 name of the application.
- PvPROVIDER_DESCRIPTION - A description of the provider.
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)