Very low

PutDoc adapter callbacks that have been determined by SDL Contenta Engineering to be very low in usefulness.

pcm_get_headers_top_element
This subroutine is only called if the header file time stamp changed.

The top element is written to the header file for EpicEdit and FrameEdit branch node editing. The attributes may have been modified in the top element in which case they must be extracted and imported with the rest of the content for the top object of the exported branch.

Example: For Arbortext and Frame Maker, the header file may look like:
<! DOCTYPE …
[ … ]>
<chapter length=”3395”>
&xyent-rw001;
</chapter>

The contents of the top element are in a file entity referenced by "xyent-rw001"

pcm_get_newentity_filename
It is extremely unlikely that you will need to override this method. It is used by the SDL Contenta version 3.1 EpicEdit (EpicCat) tool that maps some of the document's elements to SDL Contenta objects.

If an object-mapped element is inserted by the Arbortext user, the PutDoc adapter creates a new file entity to temporarily hold that element until it is imported into a freshly created SDL Contenta object.

This method is overridden in CustomPutDocEpicCat.pm to return the filename of this new file entity.

pcm_insert_child_slice_where
A child slice is about to be created.

This callback gives you a chance to control where in the slice list, the current child slice goes.

Returning "" causes the slice to be appended to the end of the slice list which the adapter is rebuilding. The slice id you return (for example: "#01") identifies where the child slice should be created—it is created before the slice id that is returned.

Also see pcm_reorder_slices which can be more useful.

Argument passed to this callback is:
  • $CompoundO - Contains data describing the currently selected SDL Contenta object. Methods on this object include:
    • SliceOrderGet( ) - returns a string of slice id's in their current slice order, example: "#1 #2 #3 #4 #5"
    • SliceList( ) - returns a PCMdata object that contains records describing the slices. The records are in slice order.
pcm_insert_content_slice_where
A content slice is about to be created.
This callback gives you a chance to control where in the slice list it goes.
  • Returning "" causes the slice to be appended to the end of the slice list.
  • Returning "#01" results in the content slice being appended before the slice with an id of 01. In other words, the slice is inserted before the slice whose id you return.

Also see pcm_reorder_slices.

Arguments passed to this callback are:
  • $CompoundO - Contains data describing the currently selected SDL Contenta object. Methods on this object include:
    • SliceOrderGet( ) - returns a string of slice id's in their current slice order, example: "#1 #2 #3 #4 #5"
    • SliceList( ) - returns a PCMdata object that contains records describing the slices. The records are in slice order.
  • $ref_slice - A reference to the data that is to be written to the slice.

    This is passed to help you decide where you want the slice to go.

    If, for instance, you want to see if the data contains the string <?end of work?>, regardless of case:

    $$ref_slice =~ /<\?end of work\?>/gsi;

    The double $ in $$ref_slice is intentional; it is needed because the argument is passed as a reference.

pcm_check_link_cfg

This callback performs a database query to determine if the Link Manager is configured to run on SDL Contenta objects of the passed Document Type. If this callback returns true (1), than the pcm_launch_link_mgr callback is invoked.

Arguments passed to this callback are:
  • $doctype - The value read from the Document Type property data field of the SDL Contenta object that the user selected for edit.
  • $CmdO - Reference to command object.

Return Value: true (1) or false (0)

pcm_launch_link_mgr
If the Link Manager is installed and configured this callback is used to launch the Link Manager tool after all data has been imported.
pcm_set_checkout_dir
Arguments passed to this callback are:
  • $PcmCheckOutDir - The directory pathname passed to PCMcommand::GetDocPerl( ) by the tool that made the API call.

    $PcmCheckOutDir contains the directory pathname of the checked out document. In addition to the document file, this directory may also contain support files required for checking the data back into SDL Contenta.

This method is called right after the custom object is constructed. PcmCheckOutDir is the directory in which all the objects were exported as file entities and all of the support files are created.

This method simply assigns the $PcmCheckOutDir to a data member of the custom object as follows:
$self->{PcmCheckOutDir} = $PcmCheckOutDir;
pcm_set_top_element
This callback was created to help with Epic (entity version) and FrameMaker, which require the top level element to be in the header file. Note that it is not called if XMetaL is the editor.
Argument passed to this callback is:
  • $top_element - The top element as it appears in the header file.
pcm_what_child_slice_type
Argument passed to this callback is:
  • $CompoundO - A reference to the currently selected SDL Contenta CompoundAscii-based object into which the child slice is about to be created.

The default TYPE returned is "". Override this method if you have a need to set it. Changing the slice type has no impact on any delivered tools.

pcm_what_content_slice_type
Arguments passed to this callback are:
  • $CompoundO - A reference to the currently selected SDL Contenta CompoundAsciibased object into which the content slice is about to be created.
  • $ref_slice - The data referred to by $ref_slice is written to the slice after the slice object is created—which happens after this callback returns.

    The data is passed for your inspection to help you decide what TYPE to assign this slice if you want to do that.

    Because it’s a reference, if you change the data in $ref_slice, you will change the copy that is written to the slice.

    For example:
    $$ref_slice =~ s|<rare/>|(rare)|gsi;

    The default TYPE returned is "". When the returned type is "", SGML is the default type assigned to the slice.

    Override this method if you have a need to set the type.

    Changing the slice type has no impact on any delivered tools.

pcm_write_putdoc_status

Status is being written to AppData as the modified file entities are imported. Even with the (Arbortext) Epic tool (EpicCat version), the concatenated file is busted into file entities, one file entity for each object-mapped element whose PI contains modified="yes". The callback is invoked immediately after each object import has completed.

Status writing is turned on in the SDL Contenta Web Check In tool by adding the following custom argument to the PutDocPerl API call:
"-writestatus=true"

Example: Refer to the file checkinXmlCi.jsp in <xyroot>\Contenta\web\tools\cw_xml_ci\standard\code

pcm_bust

This method calls PcmBindBust::Bust when overridden in CustomPutDocEpicCat.pm, passing the Bust subroutine $self->{catfile} to bust modified and new object-mapped elements into file entities.

Example: As delivered in CustomPutDocDefault.pm:
sub pcm_bust {
my $self=shift;
my $DocumentDirPath = shift;
# directory containing the document and support files
my $entidmap = shift;
my $StatusO = shift;# PCMstatus object
# implemented by Epic Cat only, see
# CustomPutDocEpicCat.pm
pcm_get_custom_bust_module
Returns the name of the editor specific custom bust module. The custom bust modules rarely need to customized, but with the introduction of PutDocDiffing, this may change.
pcm_fix_delete_list
RESERVED - This is used for DITA but even then it should only rarely need to be overridden.
pcm_print_debug
RESERVED - not implemented yet.