Very low
GetDoc adapter callbacks that have been determined by have been determined by SDL Contenta Engineering to be very low in usefulness.
- pcm_get_data_type
-
This method is called after the top node of tree is selected but before export begins.
Other callbacks invoked before this one are pcm_make_file_extension, pcm_make_header, pcm_header_insert.
Examples of possible data types are sgml, xml, and html.
This method sets the {DataType} member of the custom object to the data type and then returns the data type. Data type defaults to xml, but can be overridden by the data type stored in AppData that is specific to the Document Type of the tree's top level object.
Refer to AppData for Adapter Customization.
Return Value: Data type.
- pcm_get_dimap
-
This method creates a file named di.map (where di is the acronym used or Dynamic Import) in the document checkout directory. This di.map file is required by the version 3.1 Epic Editor tool that works with a single file of data exported from a tree of Contenta objects. Currently, the data is exported to file entities and bound into a single file.
The di.map file contains rules about how new objects should be named and which elements are mapped to which types of SDL Contenta objects. For SDL Contenta 3.1, custom code has been written by SDL for editors such as Epic that are interfaced to SDL Contenta by the adapters. This code is separate from the adapter code and is written using the specific editor's API — for Epic it is ACL. The custom code reads the di.map file and uses the rules to control the user's manipulation of object-mapped elements during the editing process. The custom code adds processing instructions (PIs) to the data after each object-mapped element. These tell the PutDoc adapter which objects were modified and how to create and name new objects.
The data that is written to the map file is read from AppData. The command line script file, SDL Contenta_home/encaps/di/ImportDiMap.pl, or Dynamic Import (when used to import the file and data) store the map required by this callback in AppData.
Return Value: None
- pcm_get_doctype
-
This method is called after the top node of tree is selected, but before export begins. The only other callback invoked before this one is pcm_set_editor_name. Examples of possible document types are book, milspec and article. This method sets the {DocType} data member of the custom object to the document type read from the property data field, Document Type, of the SDL Contenta top-level object in the tree.
Return Value: Document type
- pcm_get_entity_def_pathname
-
You should not override this callback unless you have a very good reason and have contacted SDL Contenta Engineering first to discuss it.
Return Value: The pathname of the file into which the entity definitions are written. The file is created after this callback returns and its permissions are set to read only. This callback is not used by PcmGetDocCat.pm.
- pcm_get_entity_extension
-
For the editor tools that require an extension for file entities, this callback returns that extension—for example, xml.
For the Arbortext Editor tools, the custom modules do not override this method. By default the return value is an empty string. No entity extension should be added for the EpicCat version. It confuses the user if s/he looks in the document directory for the document file and finds many files with .xml or .sgm extensions.
Return Value: Filename extension.
- pcm_get_top_element
-
This method is used by the Framemaker and Arbortext Editor tools.
Custom modules for other tools override this with an empty method.
Return Value: The document's root element and it's attributes.
- pcm_get_topfile_extension
-
This callback returns the file extension to be appended to the master file—that is, the one with the header. It is based on data type read from AppData. (Refer to Configuring PUBID, DATATYPE and XMLDECL in AppData.)
Return Value: With the (Arbortext) EpicCat tool, this callback just returns "". EpicCat uses pcm_get_cat_extension to get the extension for the one file that needs the extension, the concatenated document file.
- pcm_get_xml_decl
-
This method is called after the top node of tree is selected, but before export begins.
An example of a possible XML declaration is <?xml version="1.0" encoding="US-ASCII" standalone="no"?>. The default XML declaration is <?xml version="1.0"?>.
This method sets the {XmlDecl} data member of the custom object. The default XMLDECL can be overridden by the XMLDECL members stored in AppData that is specific to the Document Type of the tree's top object.
Refer to AppData for Adapter Customization.
Return Value: See description above.
- pcm_make_doc_pathname
-
This callback returns the pathname that will be returned by GetDocPerl() minus the extension specified in the callback pcm_get_topfile_extension().
The file extension, if there is one, is appended to the return value of this method.
Return Value: Example:
"d:\checkout\EpicEdit\wingstrut_#14#7_01/ wingstrut_#14#7_01"In this case, the tool, such as EpicEdit.pl, that called GetDocPerl( ), launches Arbortext Editor with the path returned by GetDocPerl( ), "d:\checkout\EpicEdit\wingstrut_#14#7_01/ wingstrut_#14#7_01.xml"
- pcm_make_file_extension
-
This method is passed the DataType, which it assigns to the custom object's data member {FileExtension}.
Return Value: In CustomGetDocDefault the value assigned to the {FileExtension} data member is returned by pcm_get_topfile_extension.
- pcm_store_header_name
-
The (Arbortext) EpicEdit tool uses this callback. It stores the name of the header file in the EntIdMap file so that the header file can be inspected for changes to the top element attribute list.
- pcm_write_entity_definition
-
This callback is only called by PcmGetDocEnt, not by PcmGetDocCat.
This callback performs two tasks:
- writes the file entity definitions in the file named EntityDef
- writes the corresponding file entity reference in the parent file entity or header file in the case of EpicEdit entity version. The cat version of the Epic tools writes all data from the root element down to file entities and then concatenates the file entities into a single document file.
Generally you should not modify this callback. However, you can use it to write data before and after the file entity reference being written to the parent file entity or header (branch node editing with EpicEdit and FrameEdit only).
Be aware that any data you write to file entities on export (GetDoc), may be imported on PutDoc unless you strip it out in a PutDoc custom module.
- pcm_write_getdoc_status
-
Introduced in SDL Contenta 3.1C.1, this method is called immediately after each call to pcm_end_node.
The two arguments passed are:
- a reference to the PCMstatus object
- the object count (subtotal of objects exported)
Adding the custom argument -writestatus=true to the GetDocPerl API call, turns status writing on for the web tools.
For an example, see the GetDocPerl call in checkoutXmlCo.jsp, a file delivered on the SDL Contenta web server in <xyroot>\Contenta\web\tools\cw_xml_co\standard\code
- pcm_bind
-
Introduced in SDL Contenta 3.1C.1, this method is not used by the publish adapter PcmGetDocCat.
This method is overridden in CustomGetDocEpicCat.pm where PcmBindBust::Bind is called by this callback.
- pcm_get_change_tracking_pis
- Used by PcmGetDocEnt, it adds processing instructions (PIs) that provide settings which are used by the ArborText Epic custom code (ACL).
- pcm_get_checkout_dir
- Used by PcmGetDocEnt, PcmGetDocCat and PcmGetDocFetch, reads the check out directory setting from the registry. This registry setting can be changed using SDL Contenta . Select the Directories tab.
- pcm_get_custom_bind_module
- Used by PcmGetDocEnt, it returns the name of the editor specific custom bind module. Bind concatenates the objects’ content with the generated header to produce the document.
- pcm_get_new_root_element
-
Used by PcmGetDocEnt, PcmGetDocCat and PcmGetDocFetch, it reads the attributes from AppData setting {Global}/Document Types/<doctype> root_attrs and merges these data into the exported document’s root element. It is used when schema and namespace attributes must be present in the root element of the exported document, but could be used for other reasons.
The attributes added by this call are not stripped by the PutDoc adapter. If the attribute and its value already exist on the root element a duplicate is not added. If the attribute and a different value exist in the root element, the attribute value found in AppData is substituted for the one in the content.
- pcm_get_pubid
- Used by PcmGetDocEnt, PcmGetDocCat and PcmGetDocFetch, it reads and returns the public identifier from AppData setting {Global}/Document Types/<doctype> PUBID. Ultimately this string is inserted into the generated document header so that the document can be validated by a parser using the specified DTD.
- pcm_get_validator
- RESERVED - invoked by PcmGetDocEnt, PcmGetDocCat and PcmGetDocFetch but not used. Originally it returned DTD or schema but then it was learned that sometimes a document must be validated against both; that is, the customer really wants to use a schema but also wants to use entities. To use both a schema and a DTD set PUBID to the correct public identifier and add the required root attributes for the schema to root_attrs. To use only one, set only PUBID or only root_attrs.
PcmGetDocFetch
PcmGetDocFetch has some extra callbacks
- pcm_include_slice_ids_in_export
- Toggle on|off inclusion of slice information.
- pcm_set_max_tree_read_bytes
- Allows you to change the size of content chunks read from pcmportal. The default is the maximum setting allowed, 2mb. You shouldn't need to override the default setting.
- pcm_set_export_criteria
- This callback merely calls other callbacks (the next four below) that set export criteria.
- pcm_content_object_export_criteria
- Override to specify which object types (or classes) TO or NOT TO export by adding them to the pipe delimited list. In your list precede your type or class with a ! to specify NOT TO export. Normally, there is no need to override this callback. Hierarchies of objects tend to be fairly homogenous so you usually want to allow the user to export all of them. In this subroutine there is a separate setting to specify that you list is made of all type or all class names.
- pcm_content_slice_export_criteria
- Override to specify which slice types TO or NOT TO export by adding them to the pipe delimited list. In your list precede your type with a ! to specify NOT TO export. Normally there is no need to override this callback.
- pcm_property_data_export_criteria
- Override to specify which Property Data fields to export by adding the quoted field name to the pipe delimited list. There are only 5 fields exported by default.
- pcm_include_slice_ids_in_export
- Override this callback if you need to turn on the inclusion of slice ids in the export data. Doing this is rarely necessary.