Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 2 - Edition Manager / Edition Manager Reference

Edition Manager Routines / Creating and Registering a Section

RegisterSection

When opening a document that contains sections, register each section using the RegisterSection function.

FUNCTION RegisterSection (sectionDocument: FSSpec;
                          sectionH: SectionHandle; 
                          VAR aliasWasUpdated: Boolean): OSErr;

sectionDocument

The volume reference number, directory ID, and filename of the document that contains a section.

sectionH

A handle to the section record for a given section.

aliasWasUpdated

A Boolean value that returns TRUE if the alias for the edition container subscribed to was out of date and was updated. This may occur if the edition file was moved to a new location or was renamed.

DESCRIPTION

The RegisterSection function adds the section record to the Edition Manager's list of registered sections and tries to allocate a control block. After calling the RegisterSection function, the controlBlock field of the section record contains either NIL or a valid control block.

For a subscriber, the controlBlock field contains NIL if the RegisterSection function could not locate the edition container being subscribed to. The RegisterSection function then returns either the containerNotFoundWrn or the userCanceledErr result code. For a publisher, if the RegisterSection function could not locate its corresponding edition container, the Edition Manager creates an edition container in the last place the edition was located and creates a control block for it. If the RegisterSection function could not locate a publisher's corresponding edition container or its volume, the controlBlock field contains NIL. You should never re-register a section that is already registered.

Note that you can compare control blocks for individual sections. If two sections contain the same control block value, these sections publish or subscribe to the same edition (unless the control block is NIL). The Edition Manager keeps track of how many sections are referencing a control block to know when it can be deallocated. The control block maintains a count of how many sections are referencing it. Each time you use the UnRegisterSection function, the control block subtracts 1 from the number of sections. When the number of sections reaches 0, the control block is deallocated.

Your application receives the multiplePublisherWrn result code if there is another registered publisher to the same edition. Your application receives the notThePublisherWrn result code if another publisher (to the same edition) was the last section to write to the edition. The multiplePublisherWrn result code takes priority over the notThePublisherWrn result code.

RESULT CODES

noErr	0	No error
userCanceledErr	-128	User clicked Cancel in dialog box
editionMgrInitErr	-450	Manager not initialized
badSectionErr	-451	Not valid section type
multiplePublisherWrn	-460	Already is a publisher
containerNotFoundWrn	-461	Alias was not resolved
notThePublisherWrn	-463	Not the publisher

SEE ALSO

For information on the section record, see "The Section Record" beginning on page 2-72. For information on file specification records, see Inside Macintosh: Files. For additional information and an example of the use of RegisterSection, see "Opening and Closing a Document Containing Sections" beginning on page 2-22.