Documentation Center

Calling GetDocPerl() to use GetDoc

Description and examples of the use of GetDocPerl() to export an object from SDL Contenta are provided.

Example:
CPCMcommand::GetDocPerl(BSTR bsPdmPath, BSTR bsAdapter, BSTR bsLkWhat, 
BSTR bsCustomArgs, BSTR *bsEditPath)

Description:

bsPdmPath

Description: The SDL Contenta path to the object to be exported.

This can be an idpath or a name path. SDL Contenta Explorer passes the idpath of the currently selected object to the tool being launched on its command line.

Note that the SDL Contenta path may contain one or more rev ids. If it does, in some cases this affects the revision of the document that is exported by the GetDoc adapter. The revision of the document is always affected if the revid(s) pertains to a controlling container—that is, a Configuration or Project object. Older revisions cannot be modified and checked-in using the PutDoc adapter.

Example: If you want to check-out a document that is from a specific revision of a Configuration, you pass the document’s idpath with the desired revision id embedded in it, immediately following the configuration’s id (cfgid). Assume you want to view a document from a configuration checkpoint with a revid = #25738. Assume the target document’s idpath is: /#1/#2/#3801/#3806/#3807 where the configuration id is #3801. The idpath passed in bsPdmPath would be:

/#1/#2/#3801#25738/#3806/#3807

bsAdapter
The name of the top-level Perl module that defines the export subroutine.

Example: PcmGetDocEnt, PcmGetDocFetch

  • The Ent refers to Entities, as in file entities. The PcmGetDocEnt exports each object from SDL Contenta into its own file entity, then creates another file which is a concatenation of the file entities into a single document for editing.
  • PcmGetDocFetch exports the Contenta objects into a single file.

bsLkWhat
What is to be locked when exported; the GetDoc adapters can lock any, all, or none of the objects that are being exported.
ValueDescription
anyWhen specified, any SDL Contenta object which the user can lock, is locked.

For instance, objects already locked by another process cannot be, and are not locked by the current adapter when any is specified.

The data exported from objects that could not be locked is always readonly.

allWhen specified, every object in the tree is locked or else no object is locked and no data is exported.
noneWhen specified, no objects are locked.

For a publish adapter none should be specified for this parameter.

The editor tools use any. There are some fetch versions of the editor tools written for use with SDL’s web version of SDL Contenta Explorer that specify none, allowing the user to view a concatenated document in their choice of an XML editor.

bsCustomArgs
Custom arguments, as in $CustomArgs. This is a pipe delimited string of values used by the adapter.
bsEditPath
This is an out parameter; it is the return value for Visual Basic,Perl, and Java calls to GetDocPerl(). It contains the full pathname to the document exported.
Perl example:
my $CustomArgs = "$ThisToolsFname|$CustomModule|$OptionalCkOutDir|myarg1|myarg2 |";

Description:

ThisToolsFname
For tools launched from:
  • SDL Contenta Explorer, this must be the program or script file name including the filename extension.

    For example: EpicEdit.pl, FrameCheckout.exe, XmEdit.exe.

  • SDL Contenta Web, this must be the tool name that appears in the tools list.

    For example: Epic Check Out, Epic Check In, XMetaL Check Out, Frame Check In.

This is used by the adapter with the top level object’s Document Type as a pair of keys to determine the overriding name of a custom module in AppData.

CustomModule
The name of the perl module that contains customizations to the adapter callbacks.

The custom modules inherit from delivered custom modules and override subroutines that need to behave in a specialized way for a given customer or application.

For example CustomGetDocFetchAcme might be written for Acme Widgets to help publish their data. It inherits from CustomGetDocFetch which in turn, inherits from CustomGetDocFetchDefault.

OptionalCkOutDir
The optional checkout directory in which the document should be created. This location overrides the default which is derived from the registry.

In SDL Contenta Explorer, the checkout directory is specified in the registry under: HKEY_CURRENT_USER > SOFTWARE > XyEnterprise > Content@ > Settings > Directories

myarg1, myarg2

Optional custom arguments. May contain multiple arguments; myarg1, myarg2, arg3, arg<n>. This makes it possible for a tool that calls an adapter to pass extra arguments that are needed by the specialized custom module you write for the particular tool.

Perl example:
$publishPathname = $PCMcmd->GetDocPerl($PcmPath,$Adapter, $lk_what,$CustomArgs);