SERENA 

DIMENSIONS CM 12.2.1 

Developer’s Reference
Serena Proprietary and Confidential Information
Copyright © 1988–2012 Serena Software, Inc. All rights reserved.
This document, as well as the software described in it, is furnished under license and may
be used or copied only in accordance with the terms of such license. Except as permitted
by such license, no part of this publication may be reproduced, photocopied, stored in a
retrieval system, or transmitted, in any form or by any means, electronic, mechanical,
recording, or otherwise, without the prior written permission of Serena. Any reproduction
of such software product user documentation, regardless of whether the documentation
is reproduced in whole or in part, must be accompanied by this copyright statement in its
entirety, without modification.
This document contains proprietary and confidential information, and no reproduction or
dissemination of any information contained herein is allowed without the express
permission of Serena Software.
The content of this document is furnished for informational use only, is subject to change
without notice, and should not be construed as a commitment by Serena. Serena
assumes no responsibility or liability for any errors or inaccuracies that may appear in this
document.
Third party programs included with the Dimensions product are subject to a restricted
use license and can only be used in conjunction with Dimensions.

Trademarks
Serena, TeamTrack, StarTool, PVCS, Collage, Comparex, Dimensions, Serena Dimensions,
Mashup Composer, Mashup Exchange, Prototype Composer, Mariner and ChangeMan are
registered trademarks of Serena Software, Inc. The Serena logo, Version Manager,
Meritage and Mover are trademarks of Serena Software, Inc. All other products or
company names are used for identification purposes only, and may be trademarks of their
respective owners.

U.S. Government Rights

Any Software product acquired by Licensee under this Agreement for or on behalf of the
U.S. Government, its agencies and instrumentalities is "commercial software" as defined
by the FAR. Use, duplication, and disclosure by the U.S. Government is subject to the
restrictions set forth in the license under which the Software was acquired. The
manufacturer is Serena Software, Inc., 1900 Seaport Boulevard, 2nd Floor, Redwood City,
California 94063-5587.

Publication date: July 2012

Table of Contents

Welcome to Serena Dimensions CM . . . . . . . . . . . . . . . . . 17

Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Contacting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Part 1 C/C++ API DTK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 1 What is the Dimensions CM Toolkit Interface? . . . . . . . . . . 21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Positioning Your Solutions within the DTK . . . . . . . . . . . . . . . . . . . . . . . . 22
Client Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Event Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Interactions between the Two Architectures . . . . . . . . . . . . . . . . . . . 23
Scope of the DTK Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 2 Writing Dimensions CM DTK Applications . . . . . . . . . . . . . 25

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
DTK Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DTK Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PcmsCallbackStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PcmsChdAttachmentStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PcmsEventStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
PcmsLcStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
PcmsObjAttrDefStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
PcmsObjAttrStruct. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
PcmsObjStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
PcmsPendingUserStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
PcmsPendStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PcmsRelStruct. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PcmsRelTypeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PcmsRoleStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PcmsTypeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PcmsUserRoleStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
DTK System Attribute Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
DTK Constant Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Memory Allocation within the DTK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Usage of the Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 3 DTK API Functions for C/C++ . . . . . . . . . . . . . . . . . . . . . 45

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Memory Allocation by DTK Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Developer's Reference 3
Table of Contents

Access Security in DTK Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

PcmsAttrDefInit - Get Attribute Definition . . . . . . . . . . . . . . . . . . . . . . . . 49
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
PcmsAttrGetLov - Get Attribute's List of Values . . . . . . . . . . . . . . . . . . . . 50
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
PcmsAttrValidate - Validate an Attribute Value . . . . . . . . . . . . . . . . . . . . 53
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
PcmsCheckMessages - Check Results of Dimensions CM Command . . . . . . 54
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
PcmsCntrlPlanGet - Get Dimensions CM Process Model Information . . . . . . 56
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
PcmsConnect - Connect to Dimensions CM Database . . . . . . . . . . . . . . . . 59
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Related Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
PcmsDisconnect - Disconnect from a Dimensions CM Database . . . . . . . . . 61
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Related Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

4 Serena® Dimensions® CM 12.2.1

 Table of Contents

PcmsEvntCalloc – Allocate Zero Initialized Memory . . . . . . . . . . . . . . . . . 62

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
PcmsEvntFree – Free Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
PcmsEvntMalloc – Allocate Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
PcmsEvntRealloc – Re-Allocate Memory . . . . . . . . . . . . . . . . . . . . . . . . . 65
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
PcmsExecCommand - Execute Dimensions CM Command Synchronously . . 66
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Related Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
PcmsFullQuery - Find Dimensions CM Objects, Returning Complete Objects 68
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
PcmsGetAttachments - Obtain Request Attachment Structures . . . . . . . . . 72
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
PcmsGetAttrDefNum - Get Attribute Definition Number . . . . . . . . . . . . . . 73
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
PcmsGetAttrFile - Get Request Descriptions . . . . . . . . . . . . . . . . . . . . . . 74
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
PcmsGetAttrs - Get Dimensions CM Object Attributes. . . . . . . . . . . . . . . . 76

Developer's Reference 5
Table of Contents

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
PcmsGetBaseDbOptions - Retrieve Base Database Options . . . . . . . . . . . . 77
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
PcmsGetCandidates - Retrieve Candidates for Delegation . . . . . . . . . . . . . 78
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
PcmsGetCommandLine – Get the Dimensions CM Command . . . . . . . . . . . 79
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PcmsGetConnectDesc - Get Input File Descriptor . . . . . . . . . . . . . . . . . . . 80
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
PcmsGetDimensionsVersions - Obtain List of Loaded DLLs and Dates and Times for
Each. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
PcmsGetPendingUsers - Obtain Inbox User Structures . . . . . . . . . . . . . . . 82
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
PcmsGetRSAttrs - Retrieve Attribute Numbers in a Role Section . . . . . . . . 84
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6 Serena® Dimensions® CM 12.2.1

 Table of Contents

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
PcmsGetRSNames - Obtain Role Section Names for a Product . . . . . . . . . . 86
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
PcmsGetStringSymbolValue - Obtain Values Associated with a Symbol. . . . 88
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
PcmsGetSymbolInfo - Look Up Symbol in Structured Information Return Table89
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
PcmsGetUserRelTypes - Obtain User Relationship Subtypes . . . . . . . . . . . 91
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
PcmsGetUserRoles - Obtain User Role Structures. . . . . . . . . . . . . . . . . . . 93
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
PcmsGetWsetObj - Get User's Current Project . . . . . . . . . . . . . . . . . . . . . 95
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
PcmsInitSpec - Get Dimensions CM Object Details by Specification . . . . . . 96
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Developer's Reference 7
Table of Contents

PcmsInitUid - Get Dimensions CM Object Details by Uid . . . . . . . . . . . . . . 97

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
PcmsLovFree - Free a List of Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
PcmsObjFree - Free Dimensions CM Object Structures . . . . . . . . . . . . . . . 99
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
PcmsObjGetBackRels - Get Dimensions CM Object Reverse Relationships . . 100
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
PcmsObjGetRels - Get Dimensions CM Object Relationships . . . . . . . . . . . 102
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
PcmsObjInSecondary - Is Request Object in Secondary Catalog . . . . . . . . 104
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
PcmsPendGet - Retrieve Dimensions CM Object Inboxes for a User . . . . . . 105
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
PcmsPendWhoGet - Retrieve Users for Object . . . . . . . . . . . . . . . . . . . . . 107
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

8 Serena® Dimensions® CM 12.2.1

 Table of Contents

Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
PcmsPopulate - Populate an Object's Attributes Values . . . . . . . . . . . . . . . 109
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
PcmsQuery - Find Dimensions CM Objects, Returning Uids . . . . . . . . . . . . 110
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
PcmsSendCommand - Execute Dimensions CM Command Asynchronously . 114
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
PcmsSetAttrs - Set Dimensions CM Object Attributes . . . . . . . . . . . . . . . . 116
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
PcmsSetCallback - Set Dimensions CM API Server Callback. . . . . . . . . . . . 118
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
PcmsSetDbErrorCallback - Set Server Error Callback . . . . . . . . . . . . . . . . 120
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
PcmsSetDirectory - Change Dimensions CM Default Directory . . . . . . . . . . 122
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Developer's Reference 9
Table of Contents

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 122

Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 122
PcmsSetIdleChecker - Install Idle Checker . . . . . . . . . . . . . . ...... . . . 123
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 123
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 123
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 123
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 123
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 123
PcmsSetWsetObj - Set User's Current Project . . . . . . . . . . . . ...... . . . 124
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 124
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 124
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 124
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 124
PcmsWriteAttachments - Write Specified Request Attachments To Disk . . . 125
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 125
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 125
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 125
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 125
Attribute Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 126
Initialize PcmsObjStruct attrs . . . . . . . . . . . . . . . . . . . . ...... . . . 126
Add attrDef Structures . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . 126
Single-Value Attributes (SVA) . . . . . . . . . . . . . . . . . . . . ...... . . . 126
Multi-Value Attributes (MVA) . . . . . . . . . . . . . . . . . . . . ...... . . . 127

Chapter 4 DTK API Functions for Windows Client Installations . . . . . . 129

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Building Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Sample Code Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
PcmsClntApiConnect - Connect to a Dimensions CM Database . . . . . . . . . . 132
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
PcmsClntApiDisconnect - Disconnect from a Dimensions CM Database . . . . 133
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
PcmsClntApiExecCommand - Execute a Dimensions CM Command . . . . . . 134
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
PcmsClntApiFree – Free Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

10 Serena® Dimensions® CM 12.2.1

 Table of Contents

Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
PcmsClntApiGetLastError - Get the Last Dimensions CM Message . . . . . . . 136
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Related Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
PcmsClntApiGetLastErrorEx - Get the Last Dimensions CM Message (Dynamic
Buffer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Related Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
PcmsClntApiModeBinary - Set File Transfer Mode to Binary . . . . . . . . . . . . 138
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
PcmsClntApiModeText - Set File Transfer Mode to ASCII. . . . . . . . . . . . . . 139
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
PcmsClntApiSilentConnect - Connect Silently to a Dimensions CM Database 140
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Additional Supported DTK Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Part 2 Events Callout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 5 Dimensions CM Events Callout Interface . . . . . . . . . . . . . . 145

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
MBCS Versus UTF-8 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Large File Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Public Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Event Callout Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Validate Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Pre-Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Post-Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Determining the Event You Want . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Developer's Reference 11
Table of Contents

First and Second Event Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Event Call Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Writing a DTK Callout Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Is an Event the Solution for You? . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Designing Your Event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Writing Your Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
DTK Event Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Changing System-Attributes on Validate Events . . . . . . . . . . . . . . . . . . . 157
Changing User-Attributes on Validate Events. . . . . . . . . . . . . . . . . . . . . . 158
Recommendations on How to Change Attribute Values . . . . . . . . . . . . . . . 158
Calling DTK Functions Within Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Specialist DTK Event Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Unsupported DTK Function Calls from Within an Event. . . . . . . . . . . . 159
Using the ptrEventInfo in Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Recompiling With New Versions of Dimensions CM . . . . . . . . . . . . . . . . . . 161
Event Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Events - A Final Word and a Warning . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Chapter 6 Action Driven Promotion Event Triggers . . . . . . . . . . . . . . 163

Overview . . . . . . . . . . . ..... ................... . . . . . . . . . . . 164
Approach . . . . . . . . . . . ..... ................... . . . . . . . . . . . 164
Implementation of Action Driven Promotion Event Triggers. . . . . . . . . . . . 164
Event Mechanism . . ..... ................... . . . . . . . . . . . 164
The New Event . . . . ..... ................... . . . . . . . . . . . 165

Part 3 Java API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Chapter 7 dmclient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Using dmclient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Entry Point to dmclient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Time Format Strings in Java-API . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Part 4 The Dimensions CM Templating Language . . . . . . . . 175

Chapter 8 The Templating Language and Processor . . . . . . . . . . . . . 177

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
About Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Default Template Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
)ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
)ATTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
)CALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
)CALLBACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

12 Serena® Dimensions® CM 12.2.1

 Table of Contents

)CM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
)DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
)ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
)ENDIF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
)ENDEXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
)ENDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
)ENDSCRIPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
)EXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
)IF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
)IFDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
)IFNDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
)IM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
)LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
)REP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
)SCRIPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
)SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
)SETL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
)SET_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
)SET_PATH_MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
)SET_PATH_NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
)SET_PATH_UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
)SETU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
)SLICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
)VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Special Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
General Predefined Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
%DMCOMBINEOUTERR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
%DMCURRENTDIRECTORY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
%DMCYGWIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
%DMDAY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
%DMFOLDERSEPARATOR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
%DMHOUR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
%DMMICROSEC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
%DMMINUTE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
%DMMONTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
%DMOSTDERR.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
%DMOSTDOUT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
%DMOSTYPE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
%DMOXTMPLT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
%DMPASSWORD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
%DMPATHSEPARATOR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
%DMSAVESTDERR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
%DMSAVESTDOUT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
%DMSECOND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
%DMUNIQUE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
%DMUSER.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
%DMUSERU.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
%DMYEAR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Developer's Reference 13
Table of Contents

Remote Job Execution Predefined Symbols . . . . . . . . . . . . . . . . . . . . . . . 196

%DMCERTIFICATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
%DMJOBID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Dimensions Build Standard Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
%DMPATH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
%DMINPUT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
%DMTARGET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
%DMSTEP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
%DMRUNMODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
%DMUSER. and %DMPASS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
%DMSERVER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
%DMPBEMNODE. and %DMPBEMPORT. . . . . . . . . . . . . . . . . . . . . . . 199
%DMTOKEN.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
%DMJOBID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
%DMXFERSOURCE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Dimensions Build User-Defined Optional Symbols . . . . . . . . . . . . . . . . . . 200
DMEXECENV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
DMEXPAND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
DMTASKNAME. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
DMTIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DMSTEPMODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DMMAXRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DMNOCACHE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DMREBUILDALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DMMUSTRUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DMFINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
DMTTLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
DMALTSERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
DM_SP_START_STAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
DM_BUILDER_PROGRESS_REPORTING . . . . . . . . . . . . . . . . . . . . . . 203
Dimensions for z/OS Predefined Symbols . . . . . . . . . . . . . . . . . . . . . . . . 204
User ID and Account Predefined Symbols . . . . . . . . . . . . . . . . . . . . . 204
Job Sequence Number Predefined Symbols . . . . . . . . . . . . . . . . . . . 204
Template Expansion and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Complex Symbol References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Template Inline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
MDHDSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
MDHEXTRACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
substring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
pos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Testing Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
MVS Template Testing Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Adding Template Variables to the Dimensions Configuration File . . . . . . . . 215
Extending the Template Processor with User Written Functions . . . . . . . . . 217
Template Processing—Call-Out Functionality. . . . . . . . . . . . . . . . . . . 217
pBem Template Processing—Passing Data Between Steps . . . . . . . . . 221
The Template Processor Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

14 Serena® Dimensions® CM 12.2.1

 Table of Contents

Enhancements To Dimensions Command Processing To Supported Structured

Information Return (SIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Key features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
When To Use Structured Information Return . . . . . . . . . . . . . . . . . . 231
Client Side Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Chapter 9 Build Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Default Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Pre-Requisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Build Template Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Other Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Using Build Templates with Build Configurations . . . . . . . . . . . . . . . . . . . 237
Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Transition Rule Templates and Options Groups . . . . . . . . . . . . . . . . . 237
High Level Build Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Pre-Defined Build Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Handling Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Asynchronous Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Using the SBEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Using Search Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Handling Outputs and Error Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Generating a Bill of Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Creating a BOM from the SBEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Compilation Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Windows Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
MVS Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Link Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Collection Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Windows Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
MVS Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Mixed Inputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
z/OS Return Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Miscellaneous Examples of Using Build Templates . . . . . . . . . . . . . . . . . . 256
Using REXX in a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Chapter 10 Openmake Templates . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Developer's Reference 15
Table of Contents

Chapter 11 Remote Job Execution Templates . . . . . . . . . . . . . . . . . . 267

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Simple Synchronous Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Asynchronous Remote Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Remote Job Template Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Chapter 12 Deployment Area Scripts . . . . . . . . . . . . . . . . . . . . . . . . 277

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Changes Introduced in Dimensions CM 12.2.1 . . . . . . . . . . . . . . . . . 279
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Testing Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Differences in Relation to Build Templates . . . . . . . . . . . . . . . . . . . . . . . 282
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Other Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Part 5 Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Appendix A Known DTK Event Issues . . . . . . . . . . . . . . . . . . . . . . . . 287

Missing Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Running External Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Running dmcli from Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Windows Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
UNIX Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

16 Serena® Dimensions® CM 12.2.1

Welcome to Serena Dimensions CM
Thank you for choosing Serena® Dimensions® CM, the configuration management
component of Dimensions. Dimensions CM is a powerful process management and change
control system that will revolutionize the way you develop software. Dimensions CM helps
you organize, manage, and protect your software development projects on every level—
from storing and tracking changes to individual files, to managing and monitoring an
entire development cycle. It also provides a powerful client reporting functionality.

Purpose of this This manual describes the various application programming interfaces (APIs) and other
manual programming interfaces that enable you to programmatically extend the functionality of
Dimensions CM. The intended audience for this manual is users who are well versed in
both Dimensions CM concepts and in the C, C++, and Java programming languages.

This manual has the following parts:

 Part 1: C/C++ API DTK
This part explains how you use the Dimensions CM Developer’s Toolkit (DTK) to
access and manipulate objects that are held within a Dimensions repository. This
document covers descriptions of the interface functions that the DTK provides.
 Part 2: Events Callout
This part explains how you use the Dimensions CM Event Callout Interface that
enables you to perform customizations and integrations around Dimensions CM
commands.
 Part 3: Java API
This part describes the Java API that provides full, programmatic access to the
features of Dimensions CM. The Java API allows you to create and manipulate
versioning, change management, and process modeling data while under the control
the Dimensions CM permissions and change management rules framework.
 Part 4: The Dimensions CM Templating Language
This part describes remote job execution that enables you to invoke processing on a
remote node on which a Dimensions CM listener is running. It also describes
templates and the templating language. Templates are used to execute builds,
execute general commands through remote job execution, and to construct the body
of e-mail messages used for notifications.
 Part 5: Appendixes
This part includes known API issues.

NOTE Unless definitive Linux information is required in a particular context, Linux will be
regarded as simply another "flavor" of UNIX for the purposes of this guide.

Demonstrations
Demonstrations for Dimensions CM can be accessed at the following public Web site:

http://www.serena.com/serenacourseware/dimensions

Developer's Reference 17
Welcome to Serena Dimensions CM

Typographical Conventions
The following typographical conventions are used in the online manuals and online help.
These typographical conventions are used to assist you when using the documentation;
they are not meant to contradict or change any standard use of typographical conventions
in the various product components or the host operating system.

italics Introduces new terms that you may not be familiar with and
occasionally indicates emphasis.
bold Emphasizes important information and field names.
UPPERCASE Indicates keys or key combinations that you can use. For example,
press the Enter key.
monospace Indicates syntax examples, values that you specify, or results that
you receive.
monospaced Indicates names that are placeholders for values you specify; for
italics example, filename.
monospace Indicates the results of an executed command.
bold
vertical rule | Separates menus and their associated commands. For example,
select File | Copy means to select Copy from the File menu.
Also, indicates mutually exclusive choices in a command syntax line.
brackets [] Indicates optional items. For example, in the following statement:
SELECT [DISTINCT], DISTINCT is an optional keyword.
... Indicates command arguments that can have more than one value.

Contacting Technical Support

Serena provides technical support for all registered users of this product, including limited
installation support for the first 30 days. If you need support after that time, contact
Serena Support at the following URL and follow the instructions:
http://www.serena.com/support/

Language-specific technical support is available during local business hours. For all other
hours, technical support is provided in English.

18 Serena® Dimensions® CM 12.2.1

Part 1
C/C++ API DTK

Part 1: C/C++ API DTK contains the following chapters:

What is the Dimensions CM Toolkit Interface? 21

Writing Dimensions CM DTK Applications 25
DTK API Functions for C/C++ 45
DTK API Functions for Windows Client Installations 129

Developer's Reference 19
Part 1 C/C++ API DTK

20 Serena® Dimensions® CM 12.2.1

Chapter 1
What is the Dimensions CM Toolkit
Interface?

Overview 22
Positioning Your Solutions within the DTK 22
Scope of the DTK Architecture 23

Developer's Reference 21
Chapter 1 What is the Dimensions CM Toolkit Interface?

Overview
The Serena® Dimensions® CM Developer's Toolkit Interface (DTK) is a powerful C and
C++ Applications Programming Interface (API) that allows you to access data held within
a Dimensions CM repository.

The DTK provides a way in which you can:

 Design and implement your own applications that can interact with Dimensions CM.
 Implement your own specific customizations using a rich event callout interface.

This chapter takes you through the architecture of the DTK and how you can use it to
expand on the functionality offered by Dimensions CM.

Positioning Your Solutions within the DTK

The DTK provides two comprehensive architectures that allows you to integrate your
solutions with Dimensions CM in the following ways:

1 As a separate client application that uses the DTK to access and manipulate objects
held within a Dimensions CM repository

2 As a rich event callout interface that allows you to perform your own customized
operations when certain Dimensions CM commands are run.

When you are looking at your requirements keep in mind where within the DTK
architecture you wish to position your solution. If, for example, you have a requirement
where you need to assess the impact to one of your projects of implementing a number of
application changes, then you would use the format for Client Architecture as stated in the
following subsection.

Client Architecture

Using the Client Architecture you

would design an application that Client Application interfacing
would: with a Dimensions repository
 Connect to your
Dimensions CM repository. User Application
 Query or manipulate the data
from that repository.
DTK
 Disconnect from the repository Interface
and take some action based on
that data.
Dimensions Repository

22 Serena® Dimensions® CM 12.2.1

 Scope of the DTK Architecture

This scheme enables you to use the DTK as an input/output interface into the
Dimensions CM repository. If, however, you wanted a specific operation or action to be
performed when certain Dimensions CM commands are run, then you would use the Event
Architecture described below.

Event Architecture
Using the Event Architecture you can design a set of customizations that are applied
explicitly when a user issues a certain Dimensions CM command. A public interface is
provided that allows you to pass information back and forth between the event and the
Dimensions CM server. The result of this is that you can manipulate the outcome of the
command in certain ways.

Event Callout Interface

Dimensions

Event Data

Event Callout External

DTK Application

For more details on how events operate, please refer to Chapter 5, "Dimensions CM
Events Callout Interface" on page 145.

Interactions between the Two Architectures

When you design and implement a customization, using the Event Architecture, this
customization is applied to all the standard Dimensions CM interfaces. This customization
is also applied to all those applications that you have developed using the Client
Architecture. Events, when they are deployed, literally become part of the
Dimensions CM, and as a result are used by all Dimensions CM components.

Scope of the DTK Architecture

When you look at designing your applications for either of the specific architectures
described above, there are a number of points that you must keep in mind:

Developer's Reference 23
Chapter 1 What is the Dimensions CM Toolkit Interface?

 DTK Applications using the Client Architecture

These applications are stand-alone utilities that interface with the Dimensions CM
repository through the use of PcmsConnect() and other DTK functions.
 DTK Applications using the Event Architecture
These applications interface with Dimensions CM through a public C function call
named userSuppliedFunction(). These applications are built as shared libraries
that are dynamically loaded by Dimensions CM. These applications are able to share
information with the Dimensions CM server and so do not need to call
PcmsConnect() or PcmsDisconnect().
For events to become active they only need to be deployed on the Dimensions CM
server. As a result of this, each client that accesses that Dimensions CM server will
use these events. You do not need to be concerned with deploying and controlling
events on multiple client installations.

24 Serena® Dimensions® CM 12.2.1

Chapter 2
Writing Dimensions CM DTK
Applications

Introduction 26
DTK Return Codes 27
DTK Data Structures 28
DTK System Attribute Definitions 35
DTK Constant Definitions 40
Memory Allocation within the DTK 41

Developer's Reference 25
Chapter 2 Writing Dimensions CM DTK Applications

Introduction
This chapter outlines the data structures, manifest constants, and return codes that are
used by the DTK. These structures and constants are defined in the provided include file
pcms_api.h in the directory:
 $DM_ROOT%/pcms_api for UNIX.
 %DM_ROOT%\pcms_api for Windows.

Any source file that references DTK functions or constants must include this file.

CAUTION! As part of supporting MBCS (see Notes below), Serena® Dimensions® CM

10.1.2 or later comes with MBCS libraries enabled as default. This means that any API
application—either on UNIX or Windows—must be compiled with the _MBCS define flag
enabled. Failure to do so may cause your DTK application to exhibit memory errors when
run. Please see the DTK examples for samples of how to define this flag—basically, on
Windows you need to define /D "_MBCS" and on UNIX you need to define -D_MBCS as
part of the compile line.

NOTES

1 In addition to pcms_api.h, there is also an include file called pcms_len.h for

character array sizes.

2 The Dimensions CM 10.1.2 or later API supports MBCS (Multi-Byte Character Set). As
part of this support, the legacy primitive type char has been replaced by _TCHAR. If
you do not intend to utilize any MBCS or DBCS (Double-Byte Character Set)
functionality, you can continue to use char as in previous releases of Dimensions.
Note, UTF-8 is supported on non-Windows platforms.

3 The API library files are versioned to the number of the Dimensions CM release. For
example, in Dimensions CM 10.1.3 the API libraries are named pcms_api10m.lib
(Windows) and pcms_api10.so (UNIX).

4 The Dimensions CM 2009 R1 or later API has added support for large files (4GBytes
or greater)—so, for example, you will now be able to check in and fetch back a DVD
ISO image. Consequently, the length of the corresponding item library file in such
circumstances will need to exceed 4Gbytes.
To provide support for such item library files, internally Dimensions CM 2009 R1 or
later uses 64-bit integers to represent library file lengths. Those 64-bit library
lengths are stored as pairs of low-order 32-bits and high-order 32-bits.
The PCMS_ITEM_DATA published view (see the Reports Guide) has been enhanced to
reflect this by providing a new column, LIB_FILE_LENGTH_HI, containing the high-
order 32-bits of the file length. The low-order 32-bits of the file length continue to be
stored in the LIB_FILE_LENGTH column as in releases of Dimensions CM prior to
2009 R1.
[continued on next page]

26 Serena® Dimensions® CM 12.2.1

 DTK Return Codes

NOTES [continued]
This also means that the LIB_FILE_LENGTH and FILE_LENGTH item attributes can
potentially refer to 64-bit values. If you store files larger than 4Gbytes in
Dimensions CM, and use DTK applications or event callouts, then you need to ensure
that your code uses correct C functions for converting attribute values into 64-bit
integers and vice versa. Please refer to your compiler/C library vendor reference for
information on how to convert 64-bit integers into null-terminated strings and vice
versa.

DTK Return Codes

In general, when you call a DTK function the results of that function call can be
determined by the return code given. There are three codes that a DTK function can
return:

PCMS_OK indicates that the function call succeeded, and objects were
processed (for example, a query returned some information).
PCMS_FAIL indicates that while the function call succeeded, no objects were
actually processed (for example, a query returned no objects).
PCMS_ERROR indicates that an error occurred trying to process the function call. If
an error is encountered, the reason for the error can be assessed by
examining the following variables.
int PcmsErrorNo If the error occurred due to a
char *PcmsErrorStr programming error, for example, invalid
parameters were specified to a DTK
function, these variables will be set
detailing the reason for the error.
int PcmsDbErrorNo If the error occurred due to a database
char *PcmsDbErrorStr error, for example, the database is full,
these variables will be set detailing the
reason for the error.

PcmsDbErrorNo will indicate the

database error number (if any).

PcmsDbErrorStr will indicate the SQL

error string.

NOTE ErrorNo variables and ErrorStr variables will be set only when an error occurs.

Developer's Reference 27
Chapter 2 Writing Dimensions CM DTK Applications

DTK Data Structures

The results of function calls are generally stored in the data structures that are defined in
the following sub-sections. These structures represent the abstraction of Dimensions CM
objects and other information, and can be accessed through standard C constructions.

PcmsCallbackStruct

Definition
typedef struct PcmsCallbackStruct
{
PcmsCallbackProc callback;
void *clientData;
} PcmsCallbackStruct;

Description
This structure is used to hold information regarding registered callbacks. For more
information please refer to PcmsSetCallback().

PcmsChdAttachmentStruct

Definition
typedef struct PcmsChdAttachmentStruct
{
int uid;
_TCHAR opt;
_TCHAR filename[(PCMS_L_FILENAME + 1)*CHARSIZEMAX];
_TCHAR *userFile;
_TCHAR dateTime[(PCMS_L_DATE_TIME + 1)*CHARSIZEMAX];
_TCHAR userId[(PCMS_L_USER + 1)*CHARSIZEMAX];
_TCHAR description[(PCMS_L_REMARK + 1)*CHARSIZEMAX];
}
PcmsChdAttachmentStruct;

Description
To support integration with the Application Lifecycle Framework (ALF), this structure is
used to provide Dimensions CM event level access to Dimensions CM request
attachments.

28 Serena® Dimensions® CM 12.2.1

 DTK Data Structures

PcmsEventStruct

Definition
typedef struct
{
char *database;/* Dimensions RDBMS database */
/* identification */
char *baseDb;/* Base Database */
int eventId;/* PCMS_EVENT_XXX */
/* See userSuppliedFunction */
int objType;/* PCMS_ITEM, PCMS_PART, */
/* PCMS_CHDOC */
int noAttrsChanged; /*The number of attributes */
/* that changed */
PcmsObjAttrStruct *attrsChanged;
/* Attribute number of field that changed */
int whenCalled;/* PCMS_EVENT_VALIDATE_OP, */
/* PCMS_EVENT_PRE_OP or PCMS_EVENT_POST_OP */
} PcmsEventStruct;

Description
This structure is used exclusively for events and defines which event is being fired and
with what parameters.

PcmsLcStruct

Definition
typedef struct
{
char normalPath;
int phase;
char status [PCMS_L_STATUS + 1];
char role [PCMS_L_ROLE + 1];
} PcmsLcStruct;

Description
This structure holds lifecycle definition information.

Developer's Reference 29
Chapter 2 Writing Dimensions CM DTK Applications

PcmsObjAttrDefStruct

Definition
typedef struct
{
int attr;/* Attribute number */
int valueMaxLen;/* The maximum length of the */
/* attribute */
char variable [PCMS_L_ATTR_VARIABLE + 1];
/*The attribute name */
char prompt [PCMS_L_ATTR_PROMPT + 1];
/* The screen prompt*/
char attrType;/* PCMS_ATTR_DATE = 'D' */
/* PCMS_ATTR_UNDEFINED = 'U' */
/* PCMS_ATTR_INTEGER = 'I' */
/* PCMS_ATTR_NUMBER = 'N' */
/* PCMS_ATTR_CHAR = 'C' */
char scope;/* PCMS_ATTR_ITEM='I' */
/* PCMS_ATTR_PART='P'*/
char display;/* Y or N */
char allRevisions;/* Y or N */
char manOpt;/* MANDATORY = 'Y' */
/* OPTIONAL = 'N' */
char fldUpd;/* 'Y' or 'N' */
char roleCheck [PCMS_L_ROLE + 1];
char uniqueVal;/* 'Y' *or 'N' /
char defaultVal[PCMS_L_ATTR_DEFAULT_VAL + 1];
char helpMess [PCMS_L_ATTR_HELP_MESS + 1];
char validationOn;/* Is validation enabled, */
/* Y or N */
int definedBy;/* PCMS_ATTR_PCMS/PROG/USER */
char hasLov;/* 'Y' or 'N'. List of Values */
/* must be used to set */
void **pp;/* Reserved */
char mva;/* 'Y' or 'N'.Multi-Valued */
/* use PcmsMva... macros to */
/* interpret. * /
char mvaType;/* not used currently */
char blockName [PCMS_L_ID + 1];
/* attr may belong to a */
/* display Block */
int blockColNo;/* Column number in the */
/* display block */
int displayWidth;/* Recommended display width */
int displayHeight;/* Recommended display height */
char multiLine;
/* 'Y' - use displayHeight ie. */
/* displayHeight > 0 */
/* 'N' - displayHeight not used */
char valueCase; /* 'L' - Lower 'U' - Upper, */
/* or 'M' - Mixed */
char catalogDisplay;/* 'Y' or 'N' */
} PcmsObjAttrDefStruct;

30 Serena® Dimensions® CM 12.2.1

 DTK Data Structures

Description
This structure is used to hold information relating to the attribute definition. Some of the
fields for requests are currently hard-wired to the following values.

allRevisions 'N'
manOpt' 'N'
fldUpd 'Y'
roleCheck '\0'
uniqueVal 'N'

PcmsObjAttrStruct

Definition
typedef struct
{
int attr;/* Attribute number */
void *value;/* The value of the attribute. */
/* See section on Attribute Macros */
PcmsObjAttrDefStruct *attrDef;
/* Pointer to the definition */
/* of the attribute */
} PcmsObjAttrStruct;

Description
This structure is used to hold information regarding the attributes that an object has. The
attr member details the attribute number, while the *attrDef pointer contains details
on the attribute definition. The value of the attribute is accessed through the
PcmsMvaGetVal() and PcmsSvaGetVal() attribute macros. For more information about
these macros, please refer to the "Attribute Macros" on page 126.

Developer's Reference 31
Chapter 2 Writing Dimensions CM DTK Applications

PcmsObjStruct

Definition
typedef struct PcmsObjStruct
{
int uid;
int specUid;
int objType; /* PCMS_ITEM, PCMS_PART, PCMS_CHDOC, etc */
int typeUid;
_TCHAR typeName[(PCMS_L_TYPE_NAME + 1)*CHARSIZEMAX];
_TCHAR productId[(PCMS_L_PRODUCT_ID + 1)*CHARSIZEMAX];
_TCHAR objId[(PCMS_MAX_L_ID + 1)*CHARSIZEMAX];
_TCHAR variant[(PCMS_L_VARIANT + 1)*CHARSIZEMAX];
_TCHAR revision[(PCMS_L_REVISION + 1)*CHARSIZEMAX];
_TCHAR description[(PCMS_L_DESCRIPTION + 1)*CHARSIZEMAX];
_TCHAR userName[(PCMS_L_USER + 1)*CHARSIZEMAX];
_TCHAR status[(PCMS_L_STATUS + 1)*CHARSIZEMAX];
_TCHAR dateTime[(PCMS_L_DATE_TIME + 1)*CHARSIZEMAX];
_TCHAR isExtracted;
int noAttrs; /* The number of attributes for this object. */
PcmsObjAttrStruct *attrs; /* Pointer to the array of attributes. */
int specUid;
} PcmsObjStruct;

Description
This is the generic structure used for Dimensions CM objects such as items, parts,
requests, and baselines. The type of object is defined by the member field objType being
set to a specific constant (for example, PCMS_ITEM). The *attrs pointer can be used to
access attribute information if it is defined. The specUid field contains the object's
specification uid, where applicable, or -1.

PcmsPendingUserStruct

Definition
typedef struct
{
char user [PCMS_L_USER+ 1];/* User */
char role [PCMS_L_ROLE + 1];/* Role */
char capability;/* The user's capability in */
/* role, either */
/* 'P' - Primary or */
/* 'S' - Secondary or */
/* 'L' – Leader */
char nextStatus [PCMS_L_STATUS + 1];
/* next possible status */
int nextPhase;/* next phase */
char actionable;
/* PCMS_ACT_NOT_LEADER = '1' */
/* (Can't action not leader) */
/* PCMS_ACT_OK = '2' */
/* (Can action no leaders) */

32 Serena® Dimensions® CM 12.2.1

 DTK Data Structures

/* PCMS_ACT_LEADER = '3' */
/* (Can action I am a leader) */
} PcmsPendingUserStruct;

Description
This structure holds information relating to who can action an object and to what states.

PcmsPendStruct

Definition
typedef struct
{
int objUid;
int objType;
char capability;/* 'P' - Primary, */
/* 'S'- Secondary, */
/* 'L' - Leader*/
char actionable;/* PCMS_ACT_NOT_LEADER = '1'*/
/* (can't action not leader), */
/* PCMS_ACT_OK = '2' */
/* (Can action no leaders), */
/* PCMS_ACT_LEADER = '3' */
/* (Can action I am a leader) */
} PcmsPendStruct;

Description
This structure holds object inbox information.

PcmsRelStruct

Definition
typedef struct
{
int uid;
int objType;
int relType;
int relSubTypeUid;
/* Refers to the uid field of a */
/* PcmsRelTypeStruct. For requests, users */
/* may setup up specialization's of the basic */
/* relTypes to add attributes, etc. See */
/* section on PcmsGetUserRels */
} PcmsRelStruct;

Description
This structure is used in conjunction with PcmsRelTypeStruct and stores the
relationships that an object has.

Developer's Reference 33
Chapter 2 Writing Dimensions CM DTK Applications

PcmsRelTypeStruct

Definition
typedef struct
{
int uid;/* of this relationship subType */
char name [ PCMS_L_ID + 1];
/* Name for this rel subtype*/
int relType;
/* The parent relationship type */
/* for, example, PCMS_REL_INFO */
char productId [ PCMS_L_PRODUCT_ID + 1];
/* Product name */
} PcmsRelTypeStruct;

Description
This structure is used to hold information relating to the user-defined types used in
Dimensions CM. For example, 'request to request' relationships.

PcmsRoleStruct

Definition
typedef struct PcmsRoleStruct
{
char role [PCMS_L_ROLE + 1];/* Role */
int uid;/* uid of the part */
char leader;/* 'Y' = Leader only role */
} PcmsRoleStruct;

Description
This structure holds information of the roles defined on a Dimensions CM product.

PcmsTypeStruct

Definition
typedef struct
{
int uid;
char productId [PCMS_L_PRODUCT_ID + 1];
char typeName [PCMS_L_TYPE_NAME + 1];
int objType;/* PCMS_PART, PCMS_ITEM, */
/* PCMS_CHDOC etc*/
char lifecycle [PCMS_L_ID + 1];
char typeDescription [PCMS_L_DESCRIPTION + 1];
char superType;/* '1', '2', '3', or '4'*/
/* for requests only */
} PcmsTypeStruct;

34 Serena® Dimensions® CM 12.2.1

 DTK System Attribute Definitions

Description
This structure holds object type definition information.

PcmsUserRoleStruct

Definition
typedef struct
{
char user [PCMS_L_USER + 1];/* User */
char role [PCMS_L_ROLE + 1];/* Role */
char capability;/* The users capability in */
/* this role, either */
/* 'P' - Primary or */
/* 'S' - Secondary or */
/* 'L' - Leader */
char applyDeny;/* applyDeny flag not */
/* currently used */
char treeWalk;/* treeWalk flag not */
/* currently used */
char actionable;
/* PCMS_ACT_NOT_LEADER = '1' */
/* (Can't action not leader) */
/* PCMS_ACT_OK = '2' */
/* (Can action no leaders) */
/* PCMS_ACT_LEADER = '3' */
/* (Can action I am a leader) */
char fromTree;/* 'Y' This role was found */
/* from the Part Structure */
/* 'N' This role was delegated */
/* using the DLGC command */
} PcmsUserRoleStruct;

Description
This structure is used to hold information relating to role assignments.

DTK System Attribute Definitions

A Dimensions CM object can have two kinds of attributes:
 User-defined attributes.
These are attributes defined by you in the process model.
 System-defined attributes.
These are attributes definitions that are internal to Dimensions CM. These attributes
are provided to allow you to access information that might be useful.

Developer's Reference 35
Chapter 2 Writing Dimensions CM DTK Applications

The table below details the system attributes that are available for each object type.

NOTE The number of system-defined attributes are defined by the constant

PCMS_NUM_<objtype>_ATTRS, for example, PCMS_NUM_ITEM_ATTRS.

Number of

Reference
Attributes

Definition
Attribute
System
Object
Type

PCMS_ : PCMS_NUM_ : PCMS_ATTR_ :

BASELINE BLN_ATTRS BASELINE_METHOD Indicates how the baseline
was created. Possible values
are:
Created = Created through
CBL.
Revised = Created through
CRB.
Merged = Created through
CMB.
BASELINE_TYPE The type of baseline created
1 = Design
2 = Release
3 = Archive
CREATE_DATE Create date of the baseline
SENDER_ID This attribute is only
populated if this baseline
was created as a result of
replication. This will
correspond to the database
that sent the baseline.
TEMPLATE Template name used to
create the baseline.

CHDOC CHD_ATTRS CHSEQ Sequence number of the

Dimensions request.
CREATE_DATE Create date of the request.
DELEGATED_ Issue replication attribute:
OWNER_SITE delegated owner site.
DELEGATED_ Issue replication attribute:
REFERENCE_ONLY reference only request.
LIFECYCLE Lifecycle assigned to the
request.
NO_ACTIONS Number of actions on the
request.
ORIGINATOR Originator of the request.

36 Serena® Dimensions® CM 12.2.1

 DTK System Attribute Definitions

Number of

Reference
Attributes

Definition
Attribute
System
Object
Type
PCMS_ : PCMS_NUM_ : PCMS_ATTR_ :
OWNER_SITE Issue replication attribute:
current owner site.
PHASE Current phase of the
request.
SUPER_TYPE Super type of the request.
UPDATE_DATE Update date of the request.

ITEM ITEM_ATTRS CHECKSUM Checksum of the project file.

COMPRESSED If the item is compressed.
CREATE_DATE Date of item creation.
DIR_UID Project directory uid.
DIRPATH Project directory path.
EDITABLE If the item is editable.
FILE_LENGTH Length of the project file.
See Step 4 of "Introduction"
on page 26 for a discussion
of support for files greater
than 4Gbytes.
FILE_VERSION File version in the library.
FILENAME Project filename (current
project).
FORMAT Item format.
ITEM_SPEC_UID Item spec uid.
LIB_CHECKSUM Library item file checksum.
LIB_FILE_LENGTH Length of the item file in the
library (low-order 32-bits).
See Step 4 of "Introduction"
on page 26 for a discussion
of support for files greater
than 4Gbytes.
LIB_FILENAME Library item filename.
See Step 4 of "Introduction"
on page 26 for a discussion
of support for files greater
than 4Gbytes.

Developer's Reference 37
Chapter 2 Writing Dimensions CM DTK Applications

Number of

Reference
Attributes

Definition
Attribute
System
Object
Type
PCMS_ : PCMS_NUM_ : PCMS_ATTR_ :
LIB_FILENAME_HI Length of the item file in the
library (high-order 32-bits).
See Step 4 of "Introduction"
on page 26 for a discussion
of support for files greater
than 4Gbytes.
LIFECYCLE Lifecycle id that is followed
by the item.
LOCKED_USER The user who last locked/
unlocked this file.
LOCKED_DATETIME The date that the file was
last locked/unlocked.
LOCKED_FILE Indicates if the file is
currently locked.
ORIGINATOR Who created the item.
PHASE The item's current phase.
REVISED_DATE The item's last revised date
in Julian date format (this is
the equivalent of Oracle's
date format: 'J.SSSSS').

A Julian date is the number

of days since Jan 1, 4712
BC. Julian dates allow
continuous dating from a
common reference.
SENDER_ID This attribute is only
populated if this item was
created as a result of
replication. If an item has
been remotely replicated,
then this will correspond to
the database that sent the
item. If an item has been
replicated locally, then this
will correspond to the
replication configuration
identifier.
SHARED_BRANCH This attribute is reserved for
future use.
STATUS Status of the item.
USER_FILENAME The user filename resulting
from check out, update,
check in, etc, operations.

38 Serena® Dimensions® CM 12.2.1

 DTK System Attribute Definitions

Number of

Reference
Attributes

Definition
Attribute
System
Object
Type
PCMS_ : PCMS_NUM_ : PCMS_ATTR_ :

PART PART_ATTRS LOCALNO Local Part Number.

PARTNO Part Number.
PHASE Part Phase.

WORKSET WORKSET_ATTRS CMPATHCONTROL If request path control is

enabled for this project.

CMRULES IF CM Rules are enabled for

this project.
DEFAULTCHDOC Your default working request
for this project.
DEPLOYMETHOD The project’s deployment
method.
ENFORCE_REV If revision generation is
enforced.
LOCKED Indicates if a project or
stream is currently locked.
PHASE The project's current phase.
STREAMPROJECT If this project is a stream.
TRUNK If this is a trunk project.
WS_DIR User's default project
directory.
WS_PART The project’s default product
part.

USER USER_ATTRS BASEDB The name of the base

(Additional user database.
properties that
are defined when
the user is
created.)
DEPT The user’s department.
EMAIL The user's e-mail address.
FULL_USERNAME The user’s full name.
GROUP The user’s group.
PHONE The user’s phone number.

Developer's Reference 39
Chapter 2 Writing Dimensions CM DTK Applications

Number of

Reference
Attributes

Definition
Attribute
System
Object
Type
PCMS_ : PCMS_NUM_ : PCMS_ATTR_ :
PRIVILEGE_LEVEL The user’s privilege.
SITE The user’s site name.

DTK Constant Definitions

The following constant definitions are used within the DTK to represent Dimensions CM
objects, relationships, and phases.
 Object types (objType)
Object types are constants used in the DTK to indicate classes of objects (for
example, items).

Constant Object Definition

PCMS_BASELINE Dimensions CM Baselines
PCMS_CHDOC Dimensions CM Request
PCMS_CUSTOMER Dimensions CM Customers
PCMS_ITEM Dimensions CM Items
PCMS_PART Dimensions CM Design Parts
PCMS_USER Dimensions CM Users
PCMS_WORKSET Dimensions CM Projects/Streams
PCMS_DIRECTORY Dimensions CM Directories

 Relationships (relType)
Relationship types are constants used in the DTK to indicate relationships between
objects (for example, usage).

Constant Relationship Definition

PCMS_REL_AFF Affected
PCMS_REL_BREAKDOWN Owner
PCMS_REL_DEP Dependent
PCMS_REL_DERIVED Built item
PCMS_REL_INFO Information
PCMS_REL_IRT In Response To
PCMS_REL_OWN Same as for PCMS_REL_BREAKDOWN
PCMS_REL_PRED Predecessor

40 Serena® Dimensions® CM 12.2.1

 Memory Allocation within the DTK

Constant Relationship Definition

PCMS_REL_SUCC Successor
PCMS_REL_TOP Top owner object
PCMS_REL_USE Usage
PCMS_REL_PARENT Object parent
PCMS_REL_CHILD Object child

 Relationship sub-types (relSubType)

Relationship sub-types are constants used in the DTK to indicate additional
information about relationships between objects.

Constant Relationship Definition

PCMS_REL_PERMANENT A sub-class of relationship between a request and a
baseline that details a relationship created as a result
of a revised baseline operation.

This relationship sub-class is used in the

relSubTypeUid bit mask that is part of the
PcmsRelStruct structure. This relationship
information is only retrieved as a result of a
PcmsObjGetRels() or PcmsObjGetBackRels()
operation.

 Phases

Phases are generic indicators that are used to show where a particular object is in its
lifecycle. Please refer to the related document Introduction to Dimensions CM for more
information.

Memory Allocation within the DTK

Some platforms, such as Windows, require that the shared library that allocated memory
is also responsible for freeing that memory. Because of this a number of wrapper
functions to the standard C memory functions have been provided.

DTK Function Wrapper to function

PcmsEvntFree() free()
PcmsEvntMalloc() malloc()
PcmsEvntCalloc() calloc()
PcmsEvntRealloc() realloc()

Developer's Reference 41
Chapter 2 Writing Dimensions CM DTK Applications

Usage of the Functions

 General Usage of these Functions to Allocate Memory
If any application, either in events or clients, requires you to allocate memory that will
be used by DTK functions, then you must use the wrappers as listed above. For
example, PcmsQuery() allows you to dynamically allocate memory to the
PcmsObjStruct attrs pointer to define user-defined filters. This memory must be
allocated and re-allocated through the use of the wrappers listed above. If you are
allocating memory that is not used by the DTK, then you do not have to use these
wrappers. However, it is strongly recommended for consistency that you use these
wrappers for any memory allocation that you make.
 General Usage of these Functions to De-allocate Memory
If any memory has been allocated by the DTK, or by the wrapper functions described
above, then this memory must be freed through PcmsEvntFree().
 Within DTK client applications, any memory that has been allocated by DTK functions,
such as PcmsQuery(), must be freed by the function PcmsEvntFree(). For example,
if you have the following call:

int *uids = 0;
int noUids = 0;

if (PcmsQuery(conId, &queryObj,0,&noUIds,&uids)!=PCMS_OK)
PcmsEvntFree(uids);
then you would use PcmsEvntFree() function to free this memory. You do not need
to use these functions if you are allocating memory that is not used by the DTK.
However, to be consistent in the memory functions that you do use, it is strongly
recommended that you use these functions for all memory allocation and de-
allocation.
 Within DTK events these functions must always be used to allocate or de-allocate
memory. This includes both memory usage with events and with reference to DTK
function calls, for example:

char *txt = (char *)PcmsEvntMalloc(15);

status = PcmsQuery(conId, &queryObj,0,&noUIds,&uids);

PcmsEvntFree(uids);
PcmsEvntFree(txt);

To minimize the impact of any code changes, it is suggested that you redefine the
standard C functions to use the new functions through the use of #define(s), for
example:

#define free PcmsEvntFree

#define malloc PcmsEvntMalloc
....

and then recompile the event code. Please note, however, that the prototype of the
function PcmsEventCalloc() is not the same as calloc(). Please consult Chapter 3,
"DTK API Functions for C/C++" for more information.

42 Serena® Dimensions® CM 12.2.1

 Memory Allocation within the DTK

NOTE These functions must always be used when freeing memory that has been
allocated by DTK function calls (such as PcmsQuery()) both within events and within
DTK client programs.

The table below is provided as a guideline to help you identify which functions and
pointers are dynamically assigned memory by the DTK, and what functions you should
use to free that memory. Ensure that you refer to the DTK function description for more
information on when this memory may be assigned.

Function Name Pointer to Free Free through

PcmsAttrDefInit() PcmsObjAttrDefStruct *ptrDef PcmsEvntFree()
PcmsAttrGetLov() char ***ptrVal PcmsLovFree()
char **ptrMess PcmsEvntFree()
PcmsClntApiGetLastErrorEx() char **errorBuffer PcmsClntApiFree()
PcmsCntrlPlanGet() void **ptr PcmsEvntFree()
PcmsExecCommand() char **ptrResponse PcmsEvntFree()
PcmsFullQuery() PcmsObjStruct **ptrObjs PcmsObjFree()
PcmsGetAttrFile() char **ptrFile PcmsEvntFree()
PcmsGetAttrs() PcmsObjStruct *ptrObj PcmsObjFree()
PcmsGetCandidates() char ***ptrCans PcmsEvntFree()
PcmsGetPendingUsers() PcmsPendingUserStruct PcmsEvntFree()
**ptrUsers
PcmsGetRSAttrs() int **ptrAttrs PcmsEvntFree()
char **ptrDefRole
PcmsGetRSNames() char **ptrMessage PcmsEvntFree()
char ***ptrVal
PcmsGetUserRelTypes() PcmsRelTypeStruct **ptrRels PcmsEvntFree()
PcmsGetUserRoles() PcmsGetUserRoles **ptrRoles PcmsEvntFree()
PcmsObjGetBackRels() PcmsRelStruct **ptrRels PcmsEvntFree()
PcmsObjGetRels() PcmsRelStruct **ptrRels PcmsEvntFree()
PcmsPendGet() PcmsPendStruct **ptrPend PcmsEvntFree()
PcmsPendWhoGet() PcmsPendStruct **ptrPend PcmsEvntFree()
PcmsPopulate() PcmsObjStruct **ptrObj PcmsObjFree()
PcmsQuery() int **uids PcmsEvntFree()

Developer's Reference 43
Chapter 2 Writing Dimensions CM DTK Applications

44 Serena® Dimensions® CM 12.2.1

Chapter 3
DTK API Functions for C/C++

Introduction 47
Memory Allocation by DTK Functions 47
Access Security in DTK Functions 47
PcmsAttrDefInit - Get Attribute Definition 49
PcmsAttrGetLov - Get Attribute's List of Values 50
PcmsAttrValidate - Validate an Attribute Value 53
PcmsCheckMessages - Check Results of Dimensions CM Command 54
PcmsCntrlPlanGet - Get Dimensions CM Process Model Information 56
PcmsConnect - Connect to Dimensions CM Database 59
PcmsDisconnect - Disconnect from a Dimensions CM Database 61
PcmsEvntCalloc – Allocate Zero Initialized Memory 62
PcmsEvntFree – Free Memory 63
PcmsEvntMalloc – Allocate Memory 64
PcmsEvntRealloc – Re-Allocate Memory 65
PcmsExecCommand - Execute Dimensions CM Command Synchronously 66
PcmsFullQuery - Find Dimensions CM Objects, Returning Complete Objects 68
PcmsGetAttachments - Obtain Request Attachment Structures 72
PcmsGetAttrDefNum - Get Attribute Definition Number 73
PcmsGetAttrFile - Get Request Descriptions 74
PcmsGetAttrs - Get Dimensions CM Object Attributes 76
PcmsGetBaseDbOptions - Retrieve Base Database Options 77
PcmsGetCandidates - Retrieve Candidates for Delegation 78
PcmsGetCommandLine – Get the Dimensions CM Command 79
PcmsGetConnectDesc - Get Input File Descriptor 80
PcmsGetDimensionsVersions - Obtain List of Loaded DLLs and Dates and Times for Each
81
PcmsGetPendingUsers - Obtain Inbox User Structures 82
PcmsGetRSAttrs - Retrieve Attribute Numbers in a Role Section 84
PcmsGetRSNames - Obtain Role Section Names for a Product 86
PcmsGetStringSymbolValue - Obtain Values Associated with a Symbol 88
PcmsGetSymbolInfo - Look Up Symbol in Structured Information Return Table 89
PcmsGetUserRelTypes - Obtain User Relationship Subtypes 91
PcmsGetUserRoles - Obtain User Role Structures 93
PcmsGetWsetObj - Get User's Current Project 95
PcmsInitSpec - Get Dimensions CM Object Details by Specification 96

Developer's Reference 45
Chapter 3 DTK API Functions for C/C++

PcmsInitUid - Get Dimensions CM Object Details by Uid 97

PcmsLovFree - Free a List of Values 98
PcmsObjFree - Free Dimensions CM Object Structures 99
PcmsObjGetBackRels - Get Dimensions CM Object Reverse Relationships 100
PcmsObjGetRels - Get Dimensions CM Object Relationships 102
PcmsObjInSecondary - Is Request Object in Secondary Catalog 104
PcmsPendGet - Retrieve Dimensions CM Object Inboxes for a User 105
PcmsPendWhoGet - Retrieve Users for Object 107
PcmsPopulate - Populate an Object's Attributes Values 109
PcmsQuery - Find Dimensions CM Objects, Returning Uids 110
PcmsSendCommand - Execute Dimensions CM Command Asynchronously 114
PcmsSetAttrs - Set Dimensions CM Object Attributes 116
PcmsSetCallback - Set Dimensions CM API Server Callback 118
PcmsSetDbErrorCallback - Set Server Error Callback 120
PcmsSetDirectory - Change Dimensions CM Default Directory 122
PcmsSetIdleChecker - Install Idle Checker 123
PcmsSetWsetObj - Set User's Current Project 124
PcmsWriteAttachments - Write Specified Request Attachments To Disk 125
Attribute Macros 126

46 Serena® Dimensions® CM 12.2.1

 Introduction

Introduction
This chapter describes each of the functions that are available in the Serena®
Dimensions® CM DTK for C/C++ programs. The description of each function has the
following components.

Purpose What the function does.

Prototype The function prototype.
Parameters Description of the parameters used in the function.
Return Codes Codes returned (please refer to "DTK Return Codes" on page 27 for further
details).
Sample Sample function call (if applicable).
Comments Additional relevant information (if applicable).
Related Any related DTK function calls.
Functions

Before reading this chapter, ensure that you have familiarized yourself with the contents
of Chapter 2, "Writing Dimensions CM DTK Applications" because it contains important
information relating to data structures, return codes, and manifest constants that are
referenced in this chapter.

Memory Allocation by DTK Functions

A number of the DTK functions allocate memory to pointers that then becomes the
responsibility of the calling application to free. On some operating systems, such as
Windows and Solaris, memory that has been allocated by a shared library must be freed
by that same shared library. You must free this memory through the function call
PcmsEvntFree(). If you do not use this function, you may experience memory
corruption. For more information please refer to "Memory Allocation within the DTK" on
page 41.

Access Security in DTK Functions

If your Dimensions CM installation has been configured to support product-level security,
then the following DTK functions will filter out or limit access to only those Dimensions CM
objects that a user has the rights to access:

 PcmsAttrDefNum()
 PcmsAttrGetLov()
 PcmsAttrValidate()
 PcmsCntrlPlanGet()
 PcmsFullQuery()
 PcmsGetAttachments()

Developer's Reference 47
Chapter 3 DTK API Functions for C/C++

 PcmsGetAttrFile()
 PcmsGetAttrs()
 PcmsGetCandidates()
 PcmsGetPendingUsers()
 PcmsGetRSAttrs()
 PcmsGetRSNames()
 PcmsGetUserRelTypes()
 PcmsGetUserRoles()
 PcmsInitSpec()
 PcmsInitUid()
 PcmsObjGetBackRels()
 PcmsObjGetRels()
 PcmsPendWhoGet()
 PcmsPopulate()
 PcmsQuery()
 PcmsSetAttrs()
 PcmsWriteAttachments()

48 Serena® Dimensions® CM 12.2.1

 PcmsAttrDefInit - Get Attribute Definition

PcmsAttrDefInit - Get Attribute Definition

Purpose
This function retrieves an attribute definition for a specified typeUid, object type, and
attribute number.

Prototype
int
PcmsAttrDefInit (
int connectId,
int typeUid,
int objType,
int attrNum,
PcmsObjAttrDefStruct **ptrDefStruct
);

Parameters
connectId is the database connection identifier.
typeUid is the type (the typeUid field of the PcmsObjStruct) to which the
attribute applies.
objType is the type of the object. You can use PCMS_PART, PCMS_ITEM,
PCMS_BASELINE, PCMS_USER, PCMS_CHDOC, or PCMS_WORKSET.
attrNum is the attribute number for which the definition is to be retrieved.
ptrDefStruct is the address of a pointer to a PcmsObjAttrDefStruct in which the
attribute definition will be stored.

It is the responsibility of the calling application to free this pointer

when it is no longer required.

Return Codes
PcmsAttrDefInit() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find the specified attribute number for the given type
and object type.
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

Related Functions
PcmsCntrlPlanGet().

Developer's Reference 49
Chapter 3 DTK API Functions for C/C++

PcmsAttrGetLov - Get Attribute's List of Values

Purpose
This function retrieves the list of valid set values that are allowed for a specified object
and attribute. The list of values is returned as an array of char *(s).

The PcmsObjStruct that is used in this function must have at least the following member
fields defined.
 The typeUid set to the Dimensions CM type against which the attribute has been
assigned.
 The noAttrs field set to at least 1.
 The *attrs pointer set to a PcmsObjAttrStruct structure, which must have the
member fields set as follows:
• attr: attribute number you are querying
• value: a " " string through PcmsSvaSetVal()
• attrDef: the corresponding PcmsObjAttrDefStruct.

It is possible to obtain the typeUids for a product and objType through

PcmsCntrlPlanGet(). A certain attribute definition can then be obtained by calling
PcmsAttrDefInit().

Prototype
int
PcmsAttrGetLov
(
int connectId,
PcmsObjStruct *objPtr,
int attrNum,
char **message,
int *noStrings,
char ***ptrArrayOfStrings
);

Parameters
connectId is the database connection identifier.
objPtr is the object containing the type and attribute details.
attrNum is the attribute number.
message is the error message returned if the status is not PCMS_OK. It is
the caller's responsibility to free this allocated memory if not
NULL.
noStrings is the address of an integer variable to contain the number of
strings in the array.
ptrArrayOfStrings is the address of a pointer to the array of returned strings. This
array must be freed through PcmsLovFree().

50 Serena® Dimensions® CM 12.2.1

 PcmsAttrGetLov - Get Attribute's List of Values

Return Codes
PcmsAttrGetLov() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find the specified attribute number for the given type
and object type.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Sample
/*
*--------------------------------------------------------------
* FUNCTION SPECIFICATION
* Name:
* GetLovs
* Description:
* Get LOVs for a specified attribute and typeUid
* Parameters:
* int conId
* int objType
* int typeUid
* int attr
* Return:
* int
* Notes:
*------------------------------------------------------
*/
int GetLovs(int conId, int objType, int typeUid, int attr)
{
PcmsobjStruct obj = { 0 };
PcmsObjAttrDefStruct *attrDef = 0;
char **vals = 0;
int noVals = 0;
int x = 0;
char *ptrError = 0;
int status = 0;
obj.typeUid = typeUid;
obj.noAttrs = 1;
/* Get the details on the specified attribute */
if ((status = PcmsAttrDefInit(conId,typeUid
objType,attr,&attrDef))!=PCMS_OK)
return status;
/* Put together a dummy object structure */
obj.attrs =
(PcmsObjAttrStruct*)PcmsEvntMalloc(sizeof(PcmsObjAttrStruct)*1);
obj.attrs[0].attr = attr;
PcmsSvaSetVal(obj.attrs[0].value,NULL,0);
obj.attrs[0].attrDef = attrDef;
/* Get the LOV values */
if ((status = PcmsAttrGetLov(conId,&obj,
attr,&ptrError,
&noVals,&vals))==PCMS_OK)

Developer's Reference 51
Chapter 3 DTK API Functions for C/C++

{
int i = 0;
/**
** Scan list of LOVs and report

**/
for(i=O;i<noVals;i++)
(void)fprintf(stdout,
"\nLov[%d/%d] - %s",
i,noVals,vals[i]);
PcmsLovFree(noVals,vals);
}
void)PcmsObjFree(&obj);
return(status);
}

Related Functions
PcmsAttrDefInit(), PcmsAttrValidate().

52 Serena® Dimensions® CM 12.2.1

 PcmsAttrValidate - Validate an Attribute Value

PcmsAttrValidate - Validate an Attribute Value

Purpose
This function verifies that any attribute values specified on a given object structure do not
conflict with any valid sets that may have been defined.

Prototype
int
PcmsAttrValidate (
int connectId,
PcmsObjStruct *objPtr,
int attrNum,
char **message
);

Parameters
connectId is the database connection identifier.
objPtr is the object containing the attribute values to be validated.
attrNum is the attribute number against which the object attributes will be
validated.
message is the error message returned if the status is not PCMS_OK. It is the
caller's responsibility to free this allocated memory if not NULL.

Return Codes
PcmsAttrValidate() returns:

PCMS_OK on success.
PCMS_FAIL on failure.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Related Functions
PcmsAttrGetLov(), PcmsLovFree().

Developer's Reference 53
Chapter 3 DTK API Functions for C/C++

PcmsCheckMessages - Check Results of Dimensions CM

Command

CAUTION! This function is deprecated. It no longer submits commands asynchronously.

You should, instead, use the synchronous function PcmsExecCommand, see page 66.

Purpose
This function may be used to check whether the results from Dimensions CM commands
previously submitted, using PcmsSendCommand(), are available.

Prototype
int
PcmsCheckMessages (
int connectId,
int flag
);

Parameters
connectId is the database connection identifier.
flag is used to determine whether the operation is to be blocking
(PCMS_MSG_WAIT) or non-blocking (PCMS_MSG_NOWAIT).

Return Codes
PcmsCheckMessages() returns:

PCMS_OK results of a command are available and the callback function has
been invoked.
PCMS_FAIL results of a command are not available (non-blocking operation).
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

Comments
If there are no commands being processed on this connection, PCMS_FAIL will be
returned. If there are outstanding commands, the operation of this function will depend
on the value of flag.
 If flag is equal to PCMS_MSG_WAIT, the function will block (by calling the function set
with PcmsSetIdleChecker()) until the results of the next command are available.
The function will then invoke the callback function (see PcmsSetCallback() on page
118) and return PCMS_OK.

54 Serena® Dimensions® CM 12.2.1

 PcmsCheckMessages - Check Results of Dimensions CM Command

 If flag equals PCMS_MSG_NOWAIT, the function will return immediately if no results

are available (after calling the function set with PcmsSetCallback()), and the return
value will be PCMS_FAIL. If results are available, the callback function will be invoked
and the value PCMS_OK returned.

Related Functions
PcmsSendCommand(), PcmsSetCallback(), PcmsSetIdleChecker(),
PcmsExecCommand().

Developer's Reference 55
Chapter 3 DTK API Functions for C/C++

PcmsCntrlPlanGet - Get Dimensions CM Process Model

Information

Purpose
This function queries the Dimensions CM process model and returns the data in various
different structures.

Prototype
int
PcmsCntrlPlanGet (
int connectId,
int reserved,
int options,
char *fromId,
int objUid,
char *startContext,
int *noStructs,
void **ptrStructs
);

Parameters
 When options = PCMS_CHD_TYPE:

objUid is 0 for all request types or contains a typeUid from a

PcmsObjStruct structure.
fromId is the Dimensions CM product from which to retrieve the request
types when objUid is 0. This parameter is ignored when objUid is
not 0.
startContext is NULL or a valid Dimensions CM super_type cast to a char *. This
parameter is ignored when objUid is not 0.
ptrStructs is a pointer to a contiguous block of allocated memory that lists the
structures of type PcmsTypeStruct.

 When options = PCMS_PART_TYPE or PCMS_PART_CATEGORY:

objUid is 0 for all part types or contains a typeUid from a PcmsObjStruct

structure.
fromId is the Dimensions CM product from which to retrieve the design part
types when objUid is 0. This parameter is ignored when objUid is
not 0.
startContext is ignored.
ptrStructs is a pointer to a contiguous block of allocated memory that lists the
structures of type PcmsTypeStruct.

56 Serena® Dimensions® CM 12.2.1

 PcmsCntrlPlanGet - Get Dimensions CM Process Model Information

 When options = PCMS_BASELINE:

objUid is 0 for all baseline types or contains a typeUid from

PcmsObjStruct structure.
fromId is the Dimensions CM product from which to retrieve the baseline
types when objUid is 0. This parameter is ignored when objUid is
not 0.
startContext is ignored.
ptrStructs is a pointer to a contiguous block of allocated memory that lists the
structures of type PcmsTypeStruct.

 When options = PCMS_LC:

fromId is the lifecycle-id.

objUid is ignored.
startContext is NULL (in which case the first lifecycle state is returned) or is a valid
state within the lifecycle (in which case the next possible states will
be returned).
ptrStructs is a pointer to a contiguous block of allocated memory that lists the
structures of type PcmsLcStruct.

 When options = PCMS_ATTRIBUTE OR-ed with PCMS_OBJ_TYPE OR-ed with

(PCMS_ITEM or PCMS_PART or PCMS_CHDOC or PCMS_USER or PCMS_BASELINE or
PCMS_WORKSET):

fromId is the Dimensions CM product from which to retrieve the attribute

definitions when objUid is 0. This parameter is ignored when
objUid is not 0.
objUid is 0 or the uid of the type for which to retrieve the attribute
definitions.
startContext is NULL or a valid name of a Dimensions CM type (the typeName field
of the PcmsTypeStruct). If a startContext is specified, then only
attribute definitions that have been specified in the documentation
plan will be returned. This parameter is ignored when objUid is not
0.
ptrStructs is a pointer to a contiguous block of allocated memory that lists the
structures of type PcmsObjAttrDefStruct.

 The following parameters apply whatever the definition of options.

connectId is the database connection identifier.

reserved is reserved for future use.
noStructs is a pointer to an integer variable in which to store the number of
structures returned in ptrStructs. If no objects are found
noStructs is set to zero and ptrStructs is set to (void *) zero.

It is the responsibility of the calling application to free the ptrStructs pointer when it is
no longer required.

Developer's Reference 57
Chapter 3 DTK API Functions for C/C++

Return Codes
PcmsCntrlPlanGet() returns:

PCMS_OK on success.
PCMS_FAIL when no objects were found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

58 Serena® Dimensions® CM 12.2.1

 PcmsConnect - Connect to Dimensions CM Database

PcmsConnect - Connect to Dimensions CM Database

Purpose
This function provides you with a connection to the Dimensions CM database (for
example, intermediate) specified by the input parameters. You can use this function to
open multiple connections on the same or different Dimensions CM databases. This
function will return a connectId (integer) that represents your database connection. The
database parameters reflect the same values as you would specify for a DMDB symbol.

Prototype
int
PcmsConnect (
char *database,
char *password,
char *node
);

Parameters
database is the name of the Dimensions CM database to connect to.
password is the password of the database. Use NULL if the user is secure.
node is the RDBMS Service Name assigned to the node where the RDBMS
database is located.

Return Codes
PcmsConnect() returns:

int connectId on success.

PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments
This function will not return until a successful connection has been made, or an error is
encountered while attempting the connection.

If you wish to use the default Dimensions CM database for this user (DMDB), then invoke
PcmsConnect() with NULL parameters for database, password, and node.

This function will apply all the same pre-login user-verification checks as if the user had
typed dmcli at the command prompt.

Developer's Reference 59
Chapter 3 DTK API Functions for C/C++

Sample
/*
* connect to Dimensions
*
*/
int connect()
{
int conId = PCMS_ERROR
/* CONNECT to DMDB */
conId = PcmsConnect(NULL, NULL, NULL);
return conId;
}

Related Function
PcmsDisconnect().

60 Serena® Dimensions® CM 12.2.1

 PcmsDisconnect - Disconnect from a Dimensions CM Database

PcmsDisconnect - Disconnect from a Dimensions CM

Database

Purpose
This function disconnects from the Dimensions CM database as specified by the
connectId. This connectId must be a valid connectId returned by PcmsConnect().

Prototype
int
PcmsDisconnect (
int connectId
);

Parameters
connectId is the database connection identifier.

Return Codes
PcmsDisconnect() returns:

PCMS_OK on success.
PCMS_ERROR on failure, and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Sample
/* Disconnect and exit with success… */
(void) PcmsDisconnect(conID);
return (EXIT_SUCCESS);

Comments
On some operating systems if you do not call this function before the application exits, the
connection to the repository may never terminate.

This function does not return until the disconnection is complete.

Related Function
PcmsConnect().

Developer's Reference 61
Chapter 3 DTK API Functions for C/C++

PcmsEvntCalloc – Allocate Zero Initialized Memory

Purpose
This function is a wrapper to the C function calloc(). It must be used to allocated zero
initialized memory within a DTK application. The reason for this is that on some platforms,
like Windows, the memory that is allocated within a shared library must be freed in the
same shared library. If this is not done, then memory errors begin to occur. This function
is thus provided as a convenience to ensure that all the memory is allocated within the
context of the same shared library.

Prototype
void* PcmsEvntCalloc (int size);

Parameters
size is the size of the memory to allocate.

62 Serena® Dimensions® CM 12.2.1

 PcmsEvntFree – Free Memory

PcmsEvntFree – Free Memory

Purpose
This function is a wrapper to the C function free(). It must be used to free memory
allocated by DTK functions, such as PcmsQuery(). The reason for this is that on some
platforms, like Windows, the memory that is allocated within a shared library must be
freed by the same shared library. If this is not done, then memory errors begin to occur.

Prototype
void PcmsEvntFree (void *ptr);

Parameters
ptr is a pointer to the memory block that will be freed.

Developer's Reference 63
Chapter 3 DTK API Functions for C/C++

PcmsEvntMalloc – Allocate Memory

Purpose
This function is a wrapper to the C function malloc. It must be used to allocate memory
within a DTK application. The reason for this is that on some platforms, like Windows, the
memory that is allocated within a shared library must be freed by the same shared library.
If this is not done, then memory errors begin to occur. This function is thus provided as a
convenience to ensure that all the memory is allocated within the context of the same
shared library.

Prototype
void* PcmsEvntMalloc (int size);

Parameters
size is the size of the memory to allocate.

64 Serena® Dimensions® CM 12.2.1

 PcmsEvntRealloc – Re-Allocate Memory

PcmsEvntRealloc – Re-Allocate Memory

Purpose
This function is a wrapper to the C function realloc(). It must be used to re-allocate
memory within a DTK application. The reason for this is that on some platforms, like
Windows, the memory that is allocated within a shared library must be re-allocated by the
same shared library. If this is not done, then memory errors begin to occur. This function
is thus provided as a convenience to ensure that all the memory is maintained within the
context of the same shared library.

Prototype
void* PcmsEvntRealloc (void *ptr, int size);

Parameters
ptr is a pointer to the block of memory that will be resized.
size is the size of the new memory.

Developer's Reference 65
Chapter 3 DTK API Functions for C/C++

PcmsExecCommand - Execute Dimensions CM

Command Synchronously

Purpose
This function sends a command to Dimensions CM and waits for it to complete. See the
Command-Line Reference for information on legal syntax for command mode
applications.

Prototype
int
PcmsExecCommand (
int connectId,
char *command,
char **response
);

Parameters
connectId is the database connection identifier.
command is the command to be executed.
response is the address of a char* variable that will be set to point to a
dynamically allocated buffer containing the diagnostic messages
generated during the execution of the command. It is the
responsibility of the calling application to free this buffer when it is
no longer required.

Return Codes
PcmsExecCommand () returns:

PCMS_OK on success.
PCMS_FAIL on the Dimensions CM command failing and sets the response
parameter.
PCMS_ERROR on other failures and sets PcmsErrorNo and PcmsErrorStr.

Sample
See the examples on the release media.

66 Serena® Dimensions® CM 12.2.1

 PcmsExecCommand - Execute Dimensions CM Command Synchronously

Comments
All commands that have been queued previously to Dimensions CM using
PcmsSendCommand() will be processed first. When the results from all those commands
have been received, the current command will be executed by Dimensions CM. Therefore
the time taken for PcmsExecCommand() to process a single simple command may depend
on the number of commands previously queued to Dimensions CM using
PcmsSendCommand().

Related Function
PcmsSendCommand().

Developer's Reference 67
Chapter 3 DTK API Functions for C/C++

PcmsFullQuery - Find Dimensions CM Objects,

Returning Complete Objects

Purpose
This function, like PcmsQuery(), will return a set of Dimensions CM objects based on a
user-specified filter. However, unlike PcmsQuery(), this function returns fully populated
PcmsObjStructs with both object and attribute details loaded. This function is faster
than PcmsQuery() for returning large amounts of data.

Prototype
int
PcmsFullQuery (
int connectId,
PcmsObjStruct *ptrPcmsObjStruct,
int options,
int *noObjs,
PcmsObjStruct **ptrObjs
);

Parameters
connectId is the database connection identifier.
ptrPcmsObjStruct is a pointer to a PcmsObjStruct that contains the fields to
query for. The objType field in the PcmsObjStruct can
currently only be PCMS_CHDOC.
options if this is set to PCMS_OPT_SECONDARY_CATALOGUE, then the
function will process requests in the secondary catalog. By
default this function processes requests in the primary
catalog.
noObjs is a pointer to an PcmsObjStruct variable in which to store
the objects returned in ptrObjs.
ptrObjs is a pointer to a contiguous block of allocated memory that
contains the structures that the query returned. If no objects
are found noObjs is set to zero and ptrObjs is set to
(PcmsObjStruct *) zero.

It is the responsibility of the calling application to free this

memory when it is no longer required.

68 Serena® Dimensions® CM 12.2.1

 PcmsFullQuery - Find Dimensions CM Objects, Returning Complete Objects

Return Codes
PcmsFullQuery() returns:

PCMS_OK on success.
PCMS_FAIL when no objects were found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Sample
/*
*-------------------------------------------------------------
* FUNCTION SPECIFICATION
* Name:
* CountPcmsChdocs
* Description:
* Count chdocs
* Return:
* Return no of chdocs
*-------------------------------------------------------------
*/
static int
CountPcmsChdocs(int conId, char *chdoc)
{
/*
* Query the database for chdocs with the chdoc passed in...
*/
int *uids = 0;
int noUids = 0;
int noAttrs = 5;
int i = 0;
int xx = PCMS_OK;
PcmsObjStruct obj = { 0 };
PcmsObjStruct *ptrObjs = 0;
#define SET_ATTR(_attr,_value,p) \
{\
register int x = p;\
x--;\
obj.attrs[x].attr = _attr;\
PcmsSvaSetVal(obj.attrs[x].value,_value,0);\
p++;\
}
obj.objType = PCMS_CHDOC;
obj.noAttrs = noAttrs;
obj.attrs = 0;
obj.attrs =
(PcmsObjAttrStruct *)
PcmsEvntCalloc(sizeof(PcmsObjAttrStruct)
* obj.noAttrs);
(void)strcpy(obj.objId,chdoc);

i=1;

Developer's Reference 69
Chapter 3 DTK API Functions for C/C++

/* Search for chdocs with fixed attributes */

SET_ATTR(PCMS_ATTR_CREATE_DATE,"%%",i);
SET_ATTR(PCMS_ATTR_ORIGINATOR,"%%",i);
SET_ATTR(PCMS_ATTR_PHASE,"%%",i);
SET_ATTR(PCMS_ATTR_SUPER_TYPE,"%%",i);
SET_ATTR(PCMS_ATTR_UPDATE_DATE,"%%",i);
if ((xx = PcmsFullQuery(conId,&obj,0, &noUids, &ptrObjs))==PCMS_OK)
{
/* Free memory */
if (ptrObjs && noUids > 0)
{
int xc = 0;
for(xc=0;xc<noUids;xc++)
PcmsObjFree(&ptrObjs[xc]);
}
}
else
{
(void)fprintf(stdout,"\nNo objects found - %s",
(xx == PCMS_ERROR) ? "Error" : "Fail");
if (xx == PCMS_ERROR)
(void)fprintf(stdout,PcmsErrorStr);
}
/* Free memory */
void)PcmsObjFree(&obj);
return ((xx == PCMS_ERROR) ? xx : noUids);
}

Comments
By manipulating the *attrs pointer and associated noAttrs members of the
PcmsObjStruct structure it is possible to use system and user attributes as additional
components within the query. If you wish to make use of this functionality, then you only
need to specify values in the attr and value members of the PcmsObjAttrStruct
structure. All other member fields are ignored.

Both the members of the PcmsObjStruct structure and the value field member of the
PcmsObjAttrStruct support the use of wildcard characters. There are two different
kinds of wildcard that you can use:
 ' % ' (per cent) that allows pattern matching on many characters
 ' _ ' (underscore) that allows pattern matching against one character.

This function currently supports only objects of PCMS_CHDOC.

You can only use the following as system attribute filters:

 PCMS_ATTR_CREATE_DATE
 PCMS_ATTR_ATTR_ORIGINATOR
 PCMS_ATTR_PHASE
 PCMS_ATTR_SUPER_TYPE
 PCMS_ATTR_UPDATE_DATE
 PCMS_ATTR_LIFECYCLE.

70 Serena® Dimensions® CM 12.2.1

 PcmsFullQuery - Find Dimensions CM Objects, Returning Complete Objects

If you use a multi-valued attribute as a filter, then only the first element of the attribute
list will be used, the other elements will be ignored.

Related Functions
PcmsQuery().

Developer's Reference 71
Chapter 3 DTK API Functions for C/C++

PcmsGetAttachments - Obtain Request Attachment

Structures

Purpose
This function allows users to retrieve the list of attachments for a specified request object.

Each of the structures that are returned detail an individual attachment for that request.
The "userFile" member of each returned structures is NULL.

This function supports only uids taken from PCMS_CHDOC objects.

Prototype
int
PcmsGetAttachments (
int connectId,
PcmsObjStruct object,
int *noAttachments,
PcmsChdAttachmentStruct **ptrAttachments
);

Parameters
connectId is the database connection identifier.
object is the request - PcmsObjStruct that has been initialized
through PcmsInitSpec() or PcmsInitUid().
noAttachments is the address of an integer variable to contain the number of
attachment structures returned.
ptrAttachments is a pointer to a contiguous block of allocated memory that
lists the structures of type PcmsChdAttachmentStruct. If no
attachments are found noAttachments is set to zero and
ptrAttachments is set to
(PcmsChdAttachmentStruct *)zero.
It is the responsibility of the called application to free this
pointer when it is no longer required.

Return Codes
PcmsGetAttachments() returns:

PCMS_OK on success.
PCMS_ERROR on failure or when no attachments are found.

72 Serena® Dimensions® CM 12.2.1

 PcmsGetAttrDefNum - Get Attribute Definition Number

PcmsGetAttrDefNum - Get Attribute Definition Number

Purpose
This function returns the attribute number for a specified attribute definition.

Prototype
int
PcmsGetAttrDefNum (
int connectId,
char *productId,
int objType,
char *attrName,
int *attrNum
);

Parameters
connectId is the database connection identifier.
productId is the product name.
objtype is the type of the object. You can use PCMS_PART, PCMS_ITEM,
PCMS_BASELINE, PCMS_USER, PCMS_CHDOC, or PCMS_WORKSET.
attrName is the name of the attribute (the variable field in the
PcmsObjAttrDefStruct).
attrNum is the returned attribute number.

Return Codes
PcmsGetAttrDefNum() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find the specified attribute name for the given product
and object type.
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

Developer's Reference 73
Chapter 3 DTK API Functions for C/C++

PcmsGetAttrFile - Get Request Descriptions

Purpose
This function enables you to obtain either the detailed description, the current action
description, or full action for a specified Dimensions CM request.

Prototype
int
PcmsGetAttrFile (
int connectId,
PcmsObjStruct *objPtr,
int options,
int attrNo,
char **toFile,
int *size
);

Parameters
connectId is the database connection identifier.
objPtr is the pointer to the request that the function will use.
options Options 0 to 2 and 4 are used as follows:
0 Copies the selected description into a file specified by the variable
toFile
1 Copies the selected description into the variable toFile and
populates the size of the description file into the variable size.

NOTE that if toFile is a NULL pointer, then this function will

allocate memory to hold the description. It is then the caller's
responsibility to free this memory.

2 Places only the size of the description into the variable size.
4 Do not convert the file to the local character set of the client.
attrNo specifies the type of description requested, the following values are valid.
PCMS_ATTR_ACTION_DESC Returns the full action
description of the
request.
PCMS_ATTR_THIS_ACTION_DESC Returns the current
action description for
the request.
PCMS_ATTR_DETAIL_DESC Returns the detailed
description of the
request.
toFile is a pointer to where the description is to be copied. If *toFile is a NULL
pointer, this function will allocate memory to hold the description. It is the
responsibility of the caller to free this memory after use.
size is a pointer to an integer into which the description size is returned.

74 Serena® Dimensions® CM 12.2.1

 PcmsGetAttrFile - Get Request Descriptions

Return Codes
PcmsGetAttrFile() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Developer's Reference 75
Chapter 3 DTK API Functions for C/C++

PcmsGetAttrs - Get Dimensions CM Object Attributes

Purpose
This function populates a specific PcmsObjStruct with the attribute details for that
object. Calling this function will result in the noAttrs and *attrs member elements
being populated with the full attribute details and attribute definitions. If you wish to
access the information on the attribute definitions, use the PcmsObjAttrDefStruct
pointer (attrDef) from the PcmsObjAttrStruct (attrs) pointer.

Prototype
int
PcmsGetAttrs (
int connectId,
PcmsObjStruct *ptrPcmsObjStruct
);

Parameters
connectId is the database connection identifier.
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct into which the
attribute information will be populated.

Return Codes
PcmsGetAttrs() returns:

PCMS_OK on success.
PCMS_FAIL on not finding the object.
PCMS_ERROR on failure and sets PcmsErrorStr, PcmsDbErrorNo, and
PcmsDbErrorStr.

Comments
Before calling this function ensure that you have populated a valid PcmsObjStruct
through the PcmsInitUid() or PcmsInitSpec() functions.

When you have populated an object structure using this function, remember to free the
memory associated with it through PcmsObjFree() when that object is no longer
required.

Related Functions
PcmsInitUid(), PcmsInitSpec(), PcmsObjFree()

76 Serena® Dimensions® CM 12.2.1

 PcmsGetBaseDbOptions - Retrieve Base Database Options

PcmsGetBaseDbOptions - Retrieve Base Database

Options

Purpose
This function populates a specific PcmsObjStruct with the details of the defined base
database options. Calling this function will result in the noAttrs and *attrs member
elements being populated with the full option details and option definitions. If you wish to
access the information on the database option definitions, use the
PcmsObjAttrDefStruct pointer (attrDef) from the PcmsObjAttrStruct (attrs)
pointer.

Prototype
int
PcmsGetBaseDbOptions(
int connectId,
PcmsObjStruct *ptrPcmsObjStruct
);

Parameters
connectId is the database connection identifier.
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct into which
the base database options will be populated.

Return Codes
PcmsGetBaseDbOptions() returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorStr.

Comments
This function requires that the objType member element of the supplied PcmsObjStruct
pointer be initialized to PCMS_BASEDB_OPTIONS.

PcmsInitUid() and PcmsInitSpec() should not be used to populate the supplied

PcmsObjStruct.

When you have populated an object structure using this function, remember to free the
memory associated with it via PcmsObjFree() when that object is no longer required.

Related Functions
PcmsObjFree()

Developer's Reference 77
Chapter 3 DTK API Functions for C/C++

PcmsGetCandidates - Retrieve Candidates for

Delegation

Purpose
This function returns a list of those users who are valid candidates for the object, role, and
capability supplied. Currently this function supports only objects of the type PCMS_CHDOC.

Prototype
int
PcmsGetCandidates (
int connectId,
int options,
PcmsObjStruct *objPtr,
char *role,
char capability,
char *noCandidates,
char ***candidates
);

Parameters
connectId is the database connection identifier.
options is reserved for future use.
objPtr is pointer to a PcmsObjStruct that contains an object that has been
initialized with PcmsInitSpec() or PcmsInitUid().
role is the role for which to retrieve candidates, for example,
DEVELOPER.
capability is the capability that the candidate has – 'L' (Leader),'P' (Primary) or
'S' (Secondary).
noCandidates is a pointer to an integer in which to store the number of returned
values.
candidates is the address of a pointer in which the returned list of users will be
returned. The function will allocate the associated memory.
It is the responsibility of the calling application to free this pointer
when it is no longer required.

Return Codes
PcmsGetCandidates() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

78 Serena® Dimensions® CM 12.2.1

 PcmsGetCommandLine – Get the Dimensions CM Command

PcmsGetCommandLine – Get the Dimensions CM

Command

Purpose
This function will return a constant string pointer to a copy of the command that was
submitted to Dimensions CM. This is intended to allow you, from within a DTK event, to
determine what Dimensions CM command was actually run.

Prototype
const char* PcmsGetCommandLine (void);

Parameters
None.

Developer's Reference 79
Chapter 3 DTK API Functions for C/C++

PcmsGetConnectDesc - Get Input File Descriptor

Purpose
This function returns the input file descriptor for the specified connection identifier. The
purpose of this function is for an X based application to add the file descriptor as an input
for the X application using XtAddInput(). When the X application receives notification
that there is input available on the file descriptor, the application should call
PcmsCheckMessages(). This will then activate any callback functions that have been
setup by PcmsSetCallback(). Using this method of processing Dimensions CM
messages, the need for PcmsSetIdleChecker() is eliminated.

Prototype
int
PcmsGetConnectDesc (
int connectId
);

Parameters
connectId is the database connection identifier.

Return Codes
PcmsGetConnectDesc () returns:

int fd on success.
PCMS_ERROR on failure and sets PcmsErrno and PcmsErrorStr.

Comments
This function is applicable only to UNIX.

Related Functions
PcmsExecCommand(),PcmsCheckMessages(), PcmsSetCallback().

80 Serena® Dimensions® CM 12.2.1

 PcmsGetDimensionsVersions - Obtain List of Loaded DLLs and Dates and Times for Each

PcmsGetDimensionsVersions - Obtain List of Loaded

DLLs and Dates and Times for Each

Purpose
To provide a means of determining exactly which DLLs have been loaded to support this
DTK program.

Prototype
int
PcmsGetDimensionsVersions(
_TCHAR **ppszResult
)

Parameters
Pointer to a string pointer that will return a single string of text describing the DLLs
loaded. This string should be copied and freed using the usual mechanisms for freeing
resources allocated by the DTK.

Return Codes
PcmsGetDimensionsVersions() returns NULL if the call fails.

Comments
None.

Related Functions
None.

Developer's Reference 81
Chapter 3 DTK API Functions for C/C++

PcmsGetPendingUsers - Obtain Inbox User Structures

Purpose

PRIVILEGES Manage and View Other Users' Lists.

This function allows users with the above privilege to retrieve the list of inbox users (with
their roles and capabilities) for a specified request object.

Each of the structures that are returned detail the next status and phase possible for a
user on that request.

This function supports only objects of PCMS_CHDOC type.

Prototype
int
PcmsGetPendingUsers (
int connectId,
int options,
int reserved,
PcmsObjStruct *objPtr,
int *noPendingUsers,
PcmsPendingUserStruct **ptrPendingUsers
);

Parameters
connectId is the database connection identifier.
options is reserved for future use.
reserved is reserved for future use.
objPtr is a pointer to a request - PcmsObjStruct that has been
initialized through PcmsInitSpec() or PcmsInitUid().
noPendingUsers is the address of an integer variable to contain the number of
connectId structures returned.
ptrPendingUsers is a pointer to a contiguous block of allocated memory that
lists the structures of type PcmsPendingUser. If no objects
are found noPendingUsers is set to zero and
ptrPendingUsers is set to (PcmsPendingUser *) zero.

It is the responsibility of the caller application to free this

pointer when it is no longer required.

82 Serena® Dimensions® CM 12.2.1

 PcmsGetPendingUsers - Obtain Inbox User Structures

Return Codes
PcmsGetPendingUsers() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Related Functions
PcmsInitSpec(), PcmsInitUid(), PcmsGetUserRoles().

Developer's Reference 83
Chapter 3 DTK API Functions for C/C++

PcmsGetRSAttrs - Retrieve Attribute Numbers in a Role

Section

Purpose
This function returns the attribute numbers that are used by a given role section object/
type uid combination. The order in at these attribute numbers are returned is in the
display order described in the process model. If you specify an object uid, then only those
roles section attributes applicable to that object are returned. If you specify a type uid,
then all the role section attributes associated with that type's lifecycle are returned.

Object and type uids are mutually exclusive. If you specify object uid (objUid), this will
cause the function to ignore any type uids that you may additionally specify.

This function currently supports items, requests, baselines, parts, and projects.

Prototype
int
PcmsGetRSAttrs (
int connectId,
int reserved,
int options,
int objUid,
int typeUid,
char *roleName,
char *userName,
int *noAttrs,
int **attrs,
char **defaultRole
);

Parameters
connectId is the database connection identifier.
reserved is reserved for future use.
options is reserved for future use.
objUid is the uid of the object that the function will use.
typeUid is the uid of the type name that the function will use.
roleName is the role name to request the attribute numbers for. If a NULL string
is used, the default role section name will be calculated and returned
through the parameter defaultRole.
userName is reserved for future use.
noAttrs is the total number of attribute numbers returned.

84 Serena® Dimensions® CM 12.2.1

 PcmsGetRSAttrs - Retrieve Attribute Numbers in a Role Section

attrs is a pointer to the list of attribute numbers contained in this role

section.

It is the responsibility of the calling application to free this pointer

when it is no longer required.
defaultRole is the address of a char * that is used to store the default role section
name when the roleName parameter is a NULL string. It is the caller's
responsibility to free the memory if this string is not NULL.

Return Codes
PcmsGetRSAttrs() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Comments
You can use the roleName parameter to filter on those attributes that apply to a certain
role section name. In addition, two special filters can also be used.

1 $ALL returns all the attributes that are associated with that
object or type uid's lifecycle.
2 $ALL_ROLE_SECTIONS returns all the attributes used by any role sections for
this object or type uid's lifecycle.

If you specify the roleName parameter as a NULL string, the function will calculate the
default role section name and populate this into the defaultRole parameter.

Related Functions
PcmsGetRSNames()

Developer's Reference 85
Chapter 3 DTK API Functions for C/C++

PcmsGetRSNames - Obtain Role Section Names for a

Product

Purpose
This function retrieves the list of role section names corresponding to a given object uid.
This uid can be for a request, an item, a part, a baseline, a workset, or a type name. If
you specify an object uid, then only those role sections applicable to that object are
returned. If you specify a type uid, then all role sections associated with that type's
lifecycle are returned.

Prototype
int
PcmsGetRSNames (
int connectId,
int reserved,
int options,
int uid,
char **message,
int *noValues,
char **values
);

Parameters
connectId is the database connection identifier.
reserved is reserved for future use.
options is reserved for future use.
uid is the object uid or type uid that will be used.
message is the error message returned if the status is not PCMS_OK. It is the
caller's responsibility to free this allocated memory if not NULL.
noValues is the address of an integer corresponding to the number of role section
names returned.
values is a char * array of role section names returned.

It is the responsibility of the calling application to free this pointer when

it is no longer required.

Return Codes
PcmsGetRSNames() returns:

PCMS_OK on success.

86 Serena® Dimensions® CM 12.2.1

 PcmsGetRSNames - Obtain Role Section Names for a Product

PCMS_FAIL on failure to find any data.

PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Related Functions
PcmsGetRSAttrs().

Developer's Reference 87
Chapter 3 DTK API Functions for C/C++

PcmsGetStringSymbolValue - Obtain Values Associated

with a Symbol

Purpose
Obtain a value for a symbol from the symbol table.

Prototype
int
PcmsGetStringSymbolValue(
int Pcms_connection,
const _TCHAR *pszTable,
const _TCHAR *pszSymbol,
int iIndex,
_TCHAR **ppszResult)

Parameters
Pcms_connection This is the integer identifying the connection the command was
sent on.
pszTable A string that defines the tables to search. P denotes search the
persistent table, and T the temporary table. The order is
observed, and the first match returned.
pszSymbol The symbol to search for.
iIndex The occurrence of the symbol for which a value is to be
returned.
ppszResult The string value requested, or NULL if no match. This string is
a copy of that from the symbol table, and must be freed using
the usual DTK mechanism once consumed.

Return Codes
PcmsGetStringSymbolValue() returns:

PCMS_OK on success.
PCMS_FAIL on failure to locate a symbol of the specified name.
PCMS_ERROR on failure.

Comments
None.

Related Functions
PcmsGetSymbolInfo()

88 Serena® Dimensions® CM 12.2.1

 PcmsGetSymbolInfo - Look Up Symbol in Structured Information Return Table

PcmsGetSymbolInfo - Look Up Symbol in Structured

Information Return Table

Purpose
To provide a means of checking for a symbol in the Structured Information Return (SIR)
symbol tables.

Prototype
int
PcmsGetSymbolInfo(
int Pcms_connection,
const _TCHAR *pszTable,
const _TCHAR *pszSymbol,
int *pcMaxOccurs,
int *pType)

Parameters
Pcms_connection This is the integer identifying the connection the command was
sent on.
pszTable A string that defines the tables to search. P denotes search the
persistent table, and T the temporary table. The order is
observed, and the first match returned.
pszSymbol The symbol to search for.
pcMaxOccurs A pointer to the integer to hold the maximum number of times
this field occurs. NULL is valid, and will result in this parameter
not being returned.
ptype A pointer to the type of this field. NULL is valid, and will result
in this parameter not being returned.

Values returned are drawn from:

#define PCMS_STYPE_CHAR 0
#define PCMS_STYPE_INT 1
#define PCMS_STYPE_ST 2
#define PCMS_STYPE_PVOID 3

These values are defined in pcms_api.h.

Return Codes
PcmsGetSymbolInfo() returns:

PCMS_OK on success.
PCMS_FAIL on failure to locate a symbol of the specified name.
PCMS_ERROR on failure.

Developer's Reference 89
Chapter 3 DTK API Functions for C/C++

Comments
None.

Related Functions
PcmsGetStringsSymbolValue()

90 Serena® Dimensions® CM 12.2.1

 PcmsGetUserRelTypes - Obtain User Relationship Subtypes

PcmsGetUserRelTypes - Obtain User Relationship

Subtypes

Purpose
This function returns all the user-relationship sub-types for a specified product. These
relationship types include affected, information, dependent, and user-defined item-to-
item relationships.

Prototype
int
PcmsGetUserRelTypes (
int connectId,
int reserved,
int options,
char *productId,
int *noRelTypes,
PcmsRelTypeStruct **relTypes
);

Parameters
connectId is the database connection identifier.
reserved is reserved for future use.
options is reserved for future use.
productId is the product Id that the function will use.
noRelTypes is pointer to an integer variable in which to store in relTypes.
relTypes is a pointer to a contiguous block of allocated memory that lists the an
array of PcmsRelTypeStructs returned. If no objects are found as a
result of the function call, then noRelTypes is set to zero and relTypes
is set to (PcmsRelTypeStruct *) zero.

It is the responsibility of the calling application to free this pointer when

it is no longer required.

Return Codes
PcmsGetUserRelTypes() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Developer's Reference 91
Chapter 3 DTK API Functions for C/C++

Comments
For completeness, definitions of the standard Dimensions CM defined relationships are
also given.

92 Serena® Dimensions® CM 12.2.1

 PcmsGetUserRoles - Obtain User Role Structures

PcmsGetUserRoles - Obtain User Role Structures

Purpose
This function returns those users who are found to have certain roles for this object. The
returned structures indicate whether or not the user was delegated the role, or if the role
was inherited from the design tree. These structures will also indicate if the user's
capability is primary or secondary.

The actionable field of the returned PcmsUserRoleStruct is not populated.

Prototype
int
PcmsGetUserRoles (
int connectId,
int reserved,
int options,
PcmsObjStruct *objPtr,
int partUid,
int noRoles,
char *roles[],
char *userName,
int *noUserRoles,
PcmsUserRoleStruct **ptrUserRoles
);

Parameters
connectId is the database connection identifier.
reserved is reserved for future use.
options is reserved for future use.
objPtr is a pointer to PcmsObjStruct that has been initialized through
PcmsInitSpec() or PcmsInitUid().
partUid is the partUid for which to obtain roles.
noRoles is the optional number of roles on which you wish to filter.
roles is an optional array of char * roles that are used to filter the data
returned.
userName is an optional username.
noUserRoles is the address of an integer variable to contain the number of
PcmsUserRole structures returned.
ptrUserRoles is a pointer to a contiguous block of allocated memory that lists the
structures of type PcmsUserRole. If no objects are found
noUserRoles is set to zero and ptrUserRoles is set to
(PcmsUserRoleStruct *) zero.

It is the responsibility of the calling application to free this pointer

when it is no longer required.

Developer's Reference 93
Chapter 3 DTK API Functions for C/C++

Return Codes
PcmsGetUserRoles() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments
If partUid is zero, then the appropriate parent part is calculated and used by the function
for the tree walk.

You can use the userName parameter to act as a filter for the user against which this
function will apply. If you specify a NULL value, then all users are retrieved.

If you know which particular roles that interest you, you can use the noRoles and roles
parameters to filter for these roles. If noRoles is zero (0), all the roles will be retrieved.

Related Functions
PcmsGetPendingUsers().

94 Serena® Dimensions® CM 12.2.1

 PcmsGetWsetObj - Get User's Current Project

PcmsGetWsetObj - Get User's Current Project

Purpose
This function returns the current project in which this Dimensions CM session is active.

Prototype
int
PcmsGetWsetObj (
int connectId,
int options,
PcmsObjStruct **ptrPcmsObjStruct);

Parameters
connectId is the database connection identifier.
options is not currently supported (use 0).
ptrPcmsObjStruct is a dynamically allocated buffer containing a PcmsObjStruct,
whose objType field will be PCMS_WORKSET.

Return Codes
PcmsGetWsetObj() returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Sample
static char*
GetWorkset(int conId)
{
static char workset_id[PCMS_L_PRODUCT_ID + PCMS_L_CD_ID + 5];
PcmsObjStruct *wsobj = (PcmsObjStruct *)0;
workset_id[0] = '\0';
switch(PcmsGetWsetObj(conId, 0, &wsobj))
{
case PCMS ERROR:
case PCMS FAIL:
return((char *)0);
default:
break;
}

(void)sprintf(workset_id,"\"%s\":\ "%s\"",
wsobj->productId,wsobj->objId);
return(workset_id);
}

Developer's Reference 95
Chapter 3 DTK API Functions for C/C++

PcmsInitSpec - Get Dimensions CM Object Details by

Specification

Purpose
This function populates a PcmsObjStruct with the details on a specific object.

Prototype
int
PcmsInitSpec (
int connectId,
char *objSpec,
int objType,
PcmsObjStruct *ptrPcmsObjStruct
);

Parameters
connectId is the database connection identifier.
objSpec is the textual specification of an object, for example,
"FS:HITOMI_C.A-SRC;main#1".
objType is the type of the object that the specification refers to. You
can use PCMS_PART, PCMS_ITEM, PCMS_BASELINE,
PCMS_USER, PCMS_CHDOC, PCMS_WORKSET, or
PCMS_DIRECTORY.
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct in which to
store the details on the object specified by objSpec.

Return Codes
PcmsInitSpec() returns:

PCMS_OK on success.
PCMS_FAIL on not finding the object.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments
This function does not populate the attribute details within the PcmsObjStruct structure.
This has to be done separately by calling PcmsGetAttrs().

Related Functions
PcmsInitUid(), PcmsGetAttrs().

96 Serena® Dimensions® CM 12.2.1

 PcmsInitUid - Get Dimensions CM Object Details by Uid

PcmsInitUid - Get Dimensions CM Object Details by Uid

Purpose
This function populates a PcmsObjStruct with the details on a specific object.

Prototype
int
PcmsInitUid (
int connectId,
int objUid,
int objType,
PcmsObjStruct *ptrPcmsObjStruct
);

Parameters
connectId is the database connection identifier.
objUid is the integer uid of the object.
objType is the type of the object that the specification refers to. You
can use PCMS_PART, PCMS_ITEM, PCMS_BASELINE,
PCMS_USER, PCMS_CHDOC, PCMS_WORKSET, or
PCMS_DIRECTORY.
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct in which to
store the details on the object specified by the uid.

Return Codes
PcmsInitUid() returns:

PCMS_OK on success.
PCMS_FAIL on not finding the object.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments
This function does not populate the attribute details within the PcmsObjStruct structure.
This has to be done separately by calling PcmsGetAttrs().

Related Functions
PcmsInitSpec(), PcmsGetAttrs().

Developer's Reference 97
Chapter 3 DTK API Functions for C/C++

PcmsLovFree - Free a List of Values

Purpose
This function frees an array of strings returned by PcmsAttrGetLov().

Prototype
int
PcmsLovFree (
int noValues,
char **values
);

Parameters
noValues is the number of strings in the array.
values is the array name.

Return Codes
PcmsLovFree() returns:

PCMS_OK on success.

Related Functions
PcmsAttrGetLov().

98 Serena® Dimensions® CM 12.2.1

 PcmsObjFree - Free Dimensions CM Object Structures

PcmsObjFree - Free Dimensions CM Object Structures

Purpose
This function frees any memory that may have been allocated internally to the
PcmsObjStruct structure. This includes any attributes or attribute definition structures.

Prototype
int
PcmsObjFree (
PcmsObjStruct *ptrPcmsObjStruct
);

Parameters
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct from which to
free the memory.

Return Codes
PcmsObjFree() returns:

PCMS_OK this value is always returned.

Developer's Reference 99
Chapter 3 DTK API Functions for C/C++

PcmsObjGetBackRels - Get Dimensions CM Object

Reverse Relationships

Purpose
This function can be used to navigate objects and their relationships to other objects. For
example, to return predecessor revisions of an item. This function performs the inverse
navigation of PcmsObjGetRels().

Prototype
int
PcmsObjGetBackRels (
int connectId,
int fromObjUid,
int objType,
int options,
int contextUid,
int *noRels,
PcmsRelStruct **ptrPcmsRelStruct);

Parameters
connectId is the database connection identifier.
fromObjUid is the integer uid for a Dimensions CM object.
objType is the type of the Dimensions CM object. This type must be one
of PCMS_PART, PCMS_ITEM, PCMS_CHDOC, PCMS_BASELINE, or
PCMS_DIRECTORY.
options is a collection of bits set that indicates the type of objects to
return in ptrPcmsRelStruct. If this value is zero, then all
object relationship types are returned. You can restrict the list
of objects returned by specifying one or more of the types
PCMS_PART, PCMS_ITEM, PCMS_CHDOC, PCMS_BASELINE, or
PCMS_DIRECTORY.
NOTE For directories, you must specify PCMS_DIRECTORY.
contextUid can be used to limit the objects navigated to a specific
baseline_uid.
noRels is a pointer to an integer variable in which to store the number
of structures returned in ptrPcmsRelStruct.
ptrPcmsRelStruct is a pointer to a contiguous block of allocated memory that
contains a number of structures of type PcmsRelStruct. If no
objects are found then noRels is set to zero and
ptrPcmsRelStruct is set to (PcmsRelStruct *) zero.

It is the responsibility of the calling application to free this

pointer when it is no longer required.

100 Serena® Dimensions® CM 12.2.1

 PcmsObjGetBackRels - Get Dimensions CM Object Reverse Relationships

Return Codes
PcmsObjGetBackRels() returns:

PCMS_OK on success.
PCMS_FAIL when no objects where found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Comments
If PCMS_OPT_PRED is set, then contextUid will be ignored and the fromObjUid's
predecessor revision will be returned. This option is only valid when objType is set to
either PCMS_PART or PCMS_ITEM.

The value of fromObjUid cannot be specified as zero.

The option PCMS_OPT_MERGED can be used in conjunction with PCMS_OPT_PRED to return

objects that have been used in a merge to create the object specified in fromObjUid.
Currently this option is only available for items.

The following table lists combinations of object reference, object type and query options
that are valid for this function. Note that the PCMS_BASELINE option is always invalid
when obtaining the reverse relationships recorded in a baseline.

Options

CHDOC
objType
B'LINE
PART

ITEM

PART V I V V
ITEM V V V V
BASELINE I I I V
CHDOC I I V V

Key: V = Valid I = Invalid

Related Functions
PcmsObjGetRels().

Developer's Reference 101

Chapter 3 DTK API Functions for C/C++

PcmsObjGetRels - Get Dimensions CM Object

Relationships

Purpose
This function can be used to navigate objects and their relationships to other objects. For
example, to return successor revisions of an item.

Prototype
int
PcmsObjGetRels (
int connectId,
int fromObjUid,
int objType,
int options,
int contextUid,
int *noRels,
PcmsRelStruct **ptrPcmsRelStruct);

Parameters
connectId is the database connection identifier.
fromObjUid is the integer uid for a Dimensions CM object.
objType is the type of the Dimensions CM object. This type must be one
of PCMS_PART, PCMS_ITEM, PCMS_CHDOC, PCMS_BASELINE, or
PCMS_DIRECTORY.
options is a collection of bits set that indicates the type of objects to
return in ptrPcmsRelStruct. If this value is zero, then all
object relationship types are returned. You can restrict the list
of objects returned by specifying one or more of the following
types PCMS_PART, PCMS_ITEM, PCMS_CHDOC, PCMS_BASELINE,
or PCMS_DIRECTORY.
NOTE For directories, you must specify PCMS_DIRECTORY.
contextUid can be used to limit the objects navigated to a specific
baseline_uid.
noRels is a pointer to an integer variable in which to store the number
of structures returned in ptrPcmsRelStruct.
ptrPcmsRelStruct is a pointer to a contiguous block of allocated memory that
contains a number of structures of type PcmsRelStruct. If no
objects are found then noRels is set to zero and
ptrPcmsRelStruct is set to (PcmsRelStruct *) zero.

It is the responsibility of the calling application to free this

pointer when it is no longer required.

102 Serena® Dimensions® CM 12.2.1

 PcmsObjGetRels - Get Dimensions CM Object Relationships

Return Codes
PcmsObjGetRels() returns:

PCMS_OK on success.
PCMS_FAIL when no objects were found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Comments
 If fromObjUid is zero, then the top of the Dimensions CM database is used as the
starting point for the navigation.
 If fromObjUid is zero and options is set to PCMS_PART, then only the
Dimensions CM products will be returned.
 If PCMS_OPT_LATEST is set, then only the latest version of any related objects is
returned. This option is only valid when objType is set to either PCMS_ITEM or
PCMS_PART, and only applies to 'item to design part' relationships.
 If PCMS_OPT_SUCC is set, then contextUid will be ignored and the fromObjUid's
successor revision will be returned. This option is only valid when objType is set to
either PCMS_PART or PCMS_ITEM.
 The option PCMS_OPT_MERGED can be used in conjunction with PCMS_OPT_SUCC to
return objects that have resulted as a merge based on the object specified in
fromObjUid. Currently this option is only available for items.
 The following table lists the combinations of object references, object types and query
options that are valid for this function. Note that the PCMS_BASELINE option is always
invalid when obtaining the relationships recorded in a baseline.

Options
BASELINE

fromObjUid objType
CHDOC
PART

ITEM

Zero Ignored V V V V
Non-zero PART V V I I
Non-zero ITEM I V I I
Non-zero BASELINE V V I V
Non-zero CHDOC V V V V

Key: V = Valid I = Invalid

Related Functions
PcmsGetBackRels().

Developer's Reference 103

Chapter 3 DTK API Functions for C/C++

PcmsObjInSecondary - Is Request Object in Secondary

Catalog

Purpose
This macro will return an integer indicating whether the object specified by the parameter
objPtr is a request in the secondary catalog.

Prototype
int
PcmsObjInSecondary (
PcmsObjStruct *objPtr
);

Parameters
objPtr is a pointer to a PcmsObjStruct.

Return Codes
PcmsObjInSecondary() returns:

PCMS_OK if this request is in the secondary catalog.

PCMS_FAIL if this request is in the primary catalog.

104 Serena® Dimensions® CM 12.2.1

 PcmsPendGet - Retrieve Dimensions CM Object Inboxes for a User

PcmsPendGet - Retrieve Dimensions CM Object Inboxes

for a User

Purpose
This function retrieves the inbox of items and/or requests for the current or a specified
user.

CAUTION! The parameter userName will turn into an object uid for a Dimensions CM
user object in the future.

Prototype
int
PcmsPendGet (
int connectId,
char *userName,
char *reserved,
int options,
int *noStructs,
PcmsPendStruct **ptrPcmsPendStructs
);

Parameters
connectId is the database connection identifier.
userName is the user to query the objects inbox for. If this parameter is
NULL then the current user's inbox is queried.
reserved is reserved for future use.
options this determines which objects are to be returned by this
function. You can specify one of the following:
 Zero (0) that returns all inbox object types
 PCMS_CHDOC that returns all inbox requests
 PCMS_ITEM that returns all inbox items.
noStructs is a pointer to an integer variable in which to store the number
of structures of type PcmsPendStruct returned in
ptrPcmsPendStruct.
ptrPcmsPendStructs is a pointer to a contiguous block of allocated memory that
lists the objects that the function returned. If no objects are
found, then this value is set to 0 and ptrPcmsPendStructs is
set to (PcmsPendStruct*) zero.

It is the responsibility of the calling application to free this

pointer when it is no longer required.

Developer's Reference 105

Chapter 3 DTK API Functions for C/C++

Return Codes
PcmsPendGet() returns:

PCMS_OK on success.
PCMS_FAIL when no objects are found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments

PRIVILEGES Manage and View Other Users' Lists.

This function allows users with the above privilege to use the userName parameter to
query another user's item or request inbox.

106 Serena® Dimensions® CM 12.2.1

 PcmsPendWhoGet - Retrieve Users for Object

PcmsPendWhoGet - Retrieve Users for Object

Purpose
This function retrieves the users who will have a specified object in their inbox at a user-
defined status.

Prototype
int
PcmsPendWhoGet (
int connectId,
int objUid,
int objType,
char *status,
int options,
int *noStructs,
PcmsPendStruct **ptrPcmsPendStructs
);

Parameters
connectId is the database connection identifier.
objUid is the uid for a Dimensions CM object against which this
function will be run.
NOTE objUid cannot be zero (0).
objType is the type of the Dimensions CM object. This type must be
one of PCMS_PART, PCMS_BASELINE, PCMS_ITEM, or
PCMS_CHDOC.
status is the status in the lifecycle for which you wish to return the
list of users.
options is reserved for future use.
noStructs is a pointer to an integer variable in which to store the
number of structures of type PcmsPendStruct returned in
ptrPcmsPendStructs.
ptrPcmsPendStructs is a pointer to a contiguous block of allocated memory that
lists the users that the function has found. If no objects are
found noStructs is set to zero and ptrPcmsPendStructs is
set to (PcmsPendStructs *) zero.

It is the responsibility of the calling application to free this

pointer when it is no longer required.

Developer's Reference 107

Chapter 3 DTK API Functions for C/C++

Return Codes
PcmsPendWhoGet() returns:

PCMS_OK on success.
PCMS_FAIL when no objects were found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Related Functions
PcmsPendGet().

Comments

PRIVILEGES Manage and View Other Users' Lists.

This function allows users with the above privilege to use the userName parameter to
query another user's item or request inbox.

108 Serena® Dimensions® CM 12.2.1

 PcmsPopulate - Populate an Object's Attributes Values

PcmsPopulate - Populate an Object's Attributes Values

Purpose
This function populates a given PcmsObjStruct with attributes, attribute definitions and
values. The values are copied from an existing object that you supply, and are merged
with the attributes generic to a specified type uid.

Prototype
int
PcmsPopulate (
int connectId,
int options,
int objType,
int typeUid,
PcmsObjStruct *primeObj,
PcmsObjStruct **outObject
);

Parameters
connectId is the database connection identifier.
options is reserved for future use.
objType is the type of the outObject, for example, PCMS_ITEM.
typeUid is the typeUid for the outObject.
primeObj is a pointer to another object to prime the values of the outObject
from.
outObject is the address of a pointer to a PcmsObjStruct that will be allocated
and populated by this function.

Return Codes
PcmsPopulate() returns:

PCMS_OK on success.
PCMS_FAIL on failure to find any data.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr, PcmsDbErrorNo,
and PcmsDbErrorStr.

Developer's Reference 109

Chapter 3 DTK API Functions for C/C++

PcmsQuery - Find Dimensions CM Objects, Returning

Uids

Purpose
This function finds a list of Dimensions CM objects from the fields specified in the
PcmsObjStruct. If values are present in the fields of the ptrPcmsObjStruct, they will
be used to further refine the query. The only field in ptrPcmsObjStruct that must be
filled in is objType. This means that the returned object uids will all be of the same type.

Prototype
int
PcmsQuery (
int connectId,
PcmsObjStruct *ptrPcmsObjStruct,
int options,
int *noObjs,
int **ptrObjUids
);

Parameters
connectId is the database connection identifier.
PtrPcmsObjStruct is a pointer to a PcmsObjStruct that will be used to further
refine the query. The objType field in the PcmsObjStruct must
be one of PCMS_ITEM, PCMS_PART, PCMS_CHDOC, PCMS_USER,
PCMS_BASELINE, or PCMS_WORKSET.
options is a collection of bits that is used to change the default behavior
of this function.
noObjs is a pointer to an integer variable in which to store the number of
integer uids returned in ptrObjUids.
ptrObjUids is a pointer to a contiguous block of allocated memory that lists
the uids that the query returned. If no objects are found as a
result of the function call, then noObjs is set to zero and
ptrObjUids is set to (int *) zero.

It is the responsibility of the calling application to free this

pointer when it is no longer required.

Return Codes
PcmsQuery() returns:

PCMS_OK on success.
PCMS_FAIL when no objects were found.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

110 Serena® Dimensions® CM 12.2.1

 PcmsQuery - Find Dimensions CM Objects, Returning Uids

Sample
/*
*-------------------------------------------------------------
* FUNCTION SPECIFICATION
* Name:
* CountPcmsItems
* Description:
* Count items in Dimensions
* Parameters:
* char *itemId
* Return:
* no of items
* Notes:
*-------------------------------------------------------------
*/
static int
CountPcmsItems(int conId, char *itemId)
{
/*
* Query the database for items with the itemId passed in.
*/
int *uids = 0;
int noUids = 0;
int noAttrs = 2;
int i = 0;
int xx = PCMS_OK;
PcmsObjStruct obj = { 0 };
#define SET_ATTR(_attr,_value,p) \
{\
register int x = p;\
x--;\
obj.attrs[x].attr = _attr;\
PcmsSvaSetVal(obj.attrs[x].value,_value,0);\
p++;\
}
obj.objType = PCMS_ITEM;
obj.noAttrs = noAttrs;
obj.attrs = 0;
obj.attrs =
(PcmsObjAttrStruct *)
PcmsEvntCalloc(sizeof(PcmsObjAttrStruct)
*obj.noAttrs);
(void)strcpy(obj.objId,itemId);
i=1;
/* Search for items with TXT as format and of SPEC_UID 121 */
SET_ATTR(PCMS_ATTR_FORMAT,"TXT",i);
SET_ATTR(PCMS_ATTR_ITEM_SPEC_UID,"121",i);
/* Run the query */
if ((xx = PcmsQuery(conId,&obj,0,&noUids,&uids))==PCMS_OK)
{
/* Free memory */
if (uids && noUids > 0)
PcmsEvntFree((int *)uids);
}
else

Developer's Reference 111

Chapter 3 DTK API Functions for C/C++

{
(void)fprintf(stdout,"\nNo objects found - %s",
(xx == PCMS_ERROR) ? "Error" : "Fail");
if (xx == PCMS_ERROR)
(void)fprintf(stdout,PcmsErrorStr);
}
/* Free memory */
(void)PcmsObjFree(&obj);
return ((xx == PCMS_ERROR) ? xx : noUids);
}

Comments
By manipulating the *attrs pointer and associated noAttrs members of the
PcmsObjStruct structure it is possible to use system and user attributes as additional
components within the query. If you wish to make use of this functionality, then you only
need to specify values in the attr and value members of the PcmsObjAttrStruct
structure. All other member fields are ignored.

Both the members of the PcmsObjStruct structure and the value field member of the
PcmsObjAttrStruct structure support the use of wildcard characters. There are two
different kinds of wildcard that you can use:
 '%' (per cent) that allows pattern matching on many characters
 '_' (underscore) that allows pattern matching against one character.

If the objType field member of the PcmsObjStruct is set to PCMS_CHDOC, you can use
the options parameter (PCMS_OPT_SECONDARY_CATALOGUE) to make the function query
against the secondary request catalog instead of the primary catalog. By default, the
function will always query the primary request catalog.

If the objType field member of the PcmsObjStruct is set to PCMS_ITEM, you can use the
options parameter (PCMS_OPT_LATEST) to return only the latest revisions of the items
that match the query.

If you use attribute filters or the options parameter to further restrict the list of uids
returned, the speed of the query will be affected.

Only the following system attributes are supported in this function.

Object Attribute
PCMS_PART PCMS_ATTR_PARTNO
PCMS_ATTR_LOCALNO
PCMS_ITEM PCMS_ATTR_FORMAT
PCMS_ATTR_FILENAME PCMS_ATTR_ITEM_SPEC_UID
PCMS_ATTR_LIB_FILENAME PCMS_ATTR_COMPRESSED
PCMS_ATTR_SENDER_ID
PCMS_ATTR_CREATE_DATE
PCMS_ATTR_ORIGINATOR
PCMS_ATTR_PHASE
PCMS_ATTR_LIFECYCLE
PCMS_BASELINE PCMS_ATTR_TEMPLATE
PCMS_ATTR_BASELINE_TYPE

112 Serena® Dimensions® CM 12.2.1

 PcmsQuery - Find Dimensions CM Objects, Returning Uids

Object Attribute
PCMS_CHDOC PCMS_ATTR_CREATE_DATE
PCMS_ATTR_ORIGINATOR
PCMS_ATTR_PHASE
PCMS_ATTR_SUPER_TYPE PCMS_ATTR_UPDATE_DATE
PCMS_ATTR_LIFECYCLE
PCMS_USER PCMS_ATTR_GROUP PCMS_ATTR_FULL_USERNAME
PCMS_ATTR_PHONE
PCMS_ATTR_DEPT
PCMS_ATTR_SITE
PCMS_ATTR_BASEDB
PCMS_ATTR_EMAIL
PCMS_ATTR_PRIVILEGE
PCMS_WORKSET PCMS_ATTR_TRUNK (PCMS_ATTR_TRUNC) PCMS_ATTR_ENFORCE_REV

If you use a multi-valued attribute as a filter, only the first element of the attribute list will
be used. The other elements will be ignored.

The PCMS_ATTR_PRIVILEGES system-attribute of PCMS_USER object is available for

Serena Command Center users to determine whether or not a Dimensions CM user has
been deleted or disabled. This system-attribute is populated with the current privilege
(type of user access) for a Dimensions CM user. Public values of this system-attribute are
as in the table below (but note that these may change in future releases of
Dimensions CM).

Attribute Attribute Value

PCMS_ATTR_PRIVILEGE -1 User has been disabled/dropped.
0 User is an enabled "normal" user.

Related Functions
PcmsFullQuery().

Developer's Reference 113

Chapter 3 DTK API Functions for C/C++

PcmsSendCommand - Execute Dimensions CM

Command Asynchronously

CAUTION! This function is deprecated. It no longer submits commands asynchronously.

You should, instead, use the synchronous function PcmsExecCommand, see page 66.

Purpose
This function sends a command to Dimensions CM and returns without waiting for it to
complete. See the Command-Line Reference for information on legal syntax for command
mode applications.

Prototype
int
PcmsSendCommand (
int connectId,
char *command,
int *cmdId
);

Parameters
connectId is the database connection identifier.
command is the command to execute.
cmdId is a unique command identifier that is returned to the user.

Return Codes
PcmsSendCommand () returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

Comments
You must call the function PcmsCheckMessages() to check whether the results of
commands submitted using PcmsSendCommand() are available. If results are available,
your callback function will be invoked (see PcmsSetCallback on page 118).
NOTE If your application does not call PcmsCheckMessages() periodically, commands
sent with PcmsSendCommand() may not be executed by Dimensions CM.

114 Serena® Dimensions® CM 12.2.1

 PcmsSendCommand - Execute Dimensions CM Command Asynchronously

The commands EXIT and exit will result in an error being returned. A null string will also
result in an error. Use PcmsDisconnect() to terminate the connection with the
Dimensions CM Server.

Related Functions
PcmsExecCommand,PcmsSetCallback(), PcmsCheckMessages().

Developer's Reference 115

Chapter 3 DTK API Functions for C/C++

PcmsSetAttrs - Set Dimensions CM Object Attributes

Purpose
This function uses the attribute details defined in a PcmsObjStruct and sets these
attributes on the appropriate Dimensions CM object.

By using this function you can populate a PcmsObjStruct with the details on an object,
such as an item, manipulate the noAttrs and *attrs member fields and then apply
these attributes to the Dimensions CM object.

Prototype
int
PcmsSetAttrs (
int connectId,
PcmsObjStruct *ptrPcmsObjStruct
);

Parameters
connectId is the database connection identifier.
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct that has
been initialized through PcmsInitUid() or PcmsInitSpec()
and into which the new attributes have been defined. Each
element of the array pointed to by the *attrs field must have
the attr and value member fields set.

Return Codes
PcmsSetAttrs() returns:

PCMS_OK on success.
PCMS_FAIL on not setting the attributes successfully. PcmsErrorStr will
contain the message returned from Dimensions CM.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments

IMPORTANT! If the Dimensions "electronic signatures" facility is enabled,

authentication is required for sensitive changes to a request's or item's lifecycle state and
attributes. Consequently, PcmsSetAttrs() cannot be used to modify attributes in such
situations.

 PcmsSetAttrs() can set user-defined attributes on parts, items, and requests, but
non-visible attributes (those that are not displayed in client interfaces) can be set only
on requests.

116 Serena® Dimensions® CM 12.2.1

 PcmsSetAttrs - Set Dimensions CM Object Attributes

 The *attrs pointer in the PcmsObjStruct must only be populated with attributes
that you wish to add or modify.
 This function can be used only to setup user-defined attributes on objects of type
PCMS_ITEM, PCMS_CHDOC, and PCMS_PART.
 This function enforces the same checks used when setting attribute values as
performed by any other interface.
 This function is intended for applications using the Client Architecture Model. It is not
supported when called from within DTK events. If you wish to change attributes from
within an event, then please use the Validate event as described in Chapter 5,
"Dimensions CM Events Callout Interface" on page 145.

Related Functions
PcmsInitUid(), PcmsInitSpec(), PcmsGetAttrs().

Developer's Reference 117

Chapter 3 DTK API Functions for C/C++

PcmsSetCallback - Set Dimensions CM API Server

Callback

Purpose
This function sets up a callback function for the specified connectId. The previous callback
function and associated clientData are returned in the ptrOldPcmsCallback pointer.
The callback function is used to register the results of Dimensions CM commands
submitted asynchronously by the function PcmsSendCommand(). The callback function will
be invoked when a user calls PcmsCheckMessages().

Prototype
int
PcmsSetCallback (
int connectId,
PcmsCallbackStruct *ptrNewPcmsCallback,
PcmsCallbackStruct *ptrOldPcmsCallback
);

typedef struct
{
PcmsCallbackProc callback;
void *clientData;
} PcmsCallbackStruct;

Parameters
connectId is the database connection identifier.
ptrNewPcmsCallback is a pointer to a structure of type PcmsCallbackStruct. In
this structure the member field callback is a pointer to the
callback function. This function must have the following
prototype.
void sampleCallbackProc(
int connectId,
void *clientData,
int commandStatus,
int commandId,
char *commandStr,
char *callData,
...
)
The clientData field of the PcmsCallbackStruct will be
passed as one of the parameters to the callback function.
Specifying a NULL

ptrNewPcmsCallback parameter installs the default

callback for the connection. This is a null function.

118 Serena® Dimensions® CM 12.2.1

 PcmsSetCallback - Set Dimensions CM API Server Callback

ptrOldPcmsCallback is a pointer to a structure of type PcmsCallbackStruct,

which will hold the previous callback function and client
data. If this information is of no interest then you may
specify NULL.

Return Codes
PcmsSetCallback () returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

Comments
The parameters passed to the callback function are:

connectId is the database connection identifier.

clientData is the pointer value specified in the PcmsCallbackStruct
when the callback function was installed using
PcmsSetCallback().
commandStatus is the status of the Dimensions CM command.
commandId is the unique command identifier associated with the
command. This value corresponds to that returned by
PcmsSendCommand().
commandStr is the text of the command submitted.
callData is the text output that has resulted from the command
execution.
... is a variable argument list that is used internally by
Dimensions CM. You must not attempt to use this list.

Related Functions
PcmsExecCommand(),PcmsSendCommand(), PcmsCheckMessages(),
PcmsSetNoErrorCallback().

Developer's Reference 119

Chapter 3 DTK API Functions for C/C++

PcmsSetDbErrorCallback - Set Server Error Callback

Purpose
This function sets up a callback function to be executed when the RDBMS is no longer
available. The callback function will be invoked when an application invokes a DTK
function and the DTK detects that the Dimensions CM repository is no longer available.
For example, this error may occur if the Dimensions CM server has been powered down.

Prototype
int
PcmsSetDbErrorCallback (
int connectId,
PcmsCallbackStruct *ptrPcmsCallback
);

typedef struct
{
PcmsCallbackProc callback;
void *clientData;
} PcmsCallbackStruct;

Parameters
connectId is the database connection identifier.
ptrPcmsCallback is a pointer to a structure of type PcmsCallbackStruct. In this
structure the member field callback is a pointer to the callback
function. This function must have the following prototype.
void sampleCallbackProc(
intconnectId,
void*clientData,
intcommandStatus,
intcommandId,
char*commandStr,
char*callData,
...
)
The clientData field of the PcmsCallbackStruct will be passed
as one of the parameters to the callback function.

Return Codes
PcmsSetDbErrorCallback () returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

120 Serena® Dimensions® CM 12.2.1

 PcmsSetDbErrorCallback - Set Server Error Callback

Comments
The parameters passed to the callback function are:

connectId Database connection identifier associated with the command.

clientData Null.
commandStatus The RDBMS error code detected.
commandId Zero.
commandStr Null.
callData The text output formatted to include the RDBMS error code(s) that
has resulted from the command execution.
... is a variable argument list that is used internally by
Dimensions CM. You must not attempt to use this list.

Related Functions
PcmsSetCallback().

Developer's Reference 121

Chapter 3 DTK API Functions for C/C++

PcmsSetDirectory - Change Dimensions CM Default

Directory

Purpose
This function changes the default directory of the Dimensions CM process being managed
by your application.

Prototype
int
PcmsSetDirectory (
int connectId,
char *new_directory
);

Parameters
connectId is the database connection identifier.
new_directory is the full specification of the default directory the Dimensions CM
process is to use.

Return Codes
PcmsSetDirectory() returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo and PcmsErrorStr.

Comments
The function does not change directory until all commands in the PcmsSendCommand()
queue (if any) are executed.

The directory change effects this connection only.

Related Functions
PcmsExecCommand(),PcmsSendCommand().

122 Serena® Dimensions® CM 12.2.1

 PcmsSetIdleChecker - Install Idle Checker

PcmsSetIdleChecker - Install Idle Checker

Purpose
This function installs an application function to be called before any Dimensions CM DTK
functions are blocked on a read. PcmsSetIdleChecker() will be called before making a
connection to a database, and may be useful in X applications to process events from the
X event queue while the Dimensions CM DTK is waiting for input.

Prototype
int
PcmsSetIdleChecker(
int (*userIdleChecker )(int fd, int flag)
);

Parameters
userIdleChecker is the address of the application function that will be called.

Return Codes
PcmsSetIdleChecker() returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

Comments
The prototype of the idle checker function is:
int idleCheckerFunction(int fd, int flag)

where

fd is the file descriptor for the data connection that is about to be

read.
PCMS_ERROR is either PCMS_MSG_WAIT or PCMS_MSG_NOWAIT.

If the flag is set to PCMS_MSG_WAIT, the function should only return when data is
available to be read from the file descriptor, in which case the return value will be
PCMS_OK. If the flag is set to PCMS_MSG_NOWAIT, the function will return immediately with
a return value of PCMS_OK if data is available; and a return value of PCMS_FAIL if no data
is available.

For X applications, XtAddInput() can be used to set a callback procedure when input is
pending on fd.

Developer's Reference 123

Chapter 3 DTK API Functions for C/C++

PcmsSetWsetObj - Set User's Current Project

Purpose
This function allows the user to reset the current project in which this Dimensions CM
session is active.

Prototype
int
PcmsSetWsetObj (
int connectId,
int options,
PcmsObjStruct *ptrPcmsObjStruct,
char *dir);

Parameters
connectId is the database connection identifier.
options is not currently supported (use 0).
ptrPcmsObjStruct is a pointer to a structure of type PcmsObjStruct that is
populated by the user to indicate what project to change to.
dir is the project directory to use.

Return Codes
PcmsSetWsetObj() returns:

PCMS_OK on success.
PCMS_ERROR on failure and sets PcmsErrorNo, PcmsErrorStr,
PcmsDbErrorNo, and PcmsDbErrorStr.

124 Serena® Dimensions® CM 12.2.1

 PcmsWriteAttachments - Write Specified Request Attachments To Disk

PcmsWriteAttachments - Write Specified Request

Attachments To Disk

Purpose
This function allows users to write request attachments to disk. It will process the array of
attachments, writing the attachments out to a location specified by the "userFile"
members.

The "userFile" member will be user-allocated memory, and the user will be responsible
for freeing it.

Prototype
int PcmsWriteAttachments (
int conId,
PcmsObjStruct *objPtr,
int archived,
int noAttachs,
PcmsChdAttachmentStruct **ptrAttachment
)

Parameters
connectId is the database connection identifier.
object is the request - PcmsObjStruct that has been initialized
through PcmsInitSpec() or PcmsInitUid().
archived is the integer used to indicate if the specified request object can
be found in the main catalog or the secondary catalog. 0
indicates the request can be found in the main catalog, 1
indicates the request can be found in the secondary catalog.
noAttachs is the integer containing the number of attachments structures
supplied.
ptrAttachment is a pointer to a contiguous block of allocated memory that lists
the attachment structures.

Return Codes
PcmsSetWsetObj() returns:

PCMS_OK on success.
PCMS_FAIL on failure or when no attachments are found.

Developer's Reference 125

Chapter 3 DTK API Functions for C/C++

Attribute Macros
Defined in the file pcms_api.h are a set of macros that have been provided to help you in
writing your application. These macros are public but the structures that they use may
change in the future and should not be used directly.

Initialize PcmsObjStruct attrs

 PcmsInitAttrStruct(objPtr, number)
This macro allocates number zero initialized memory structure of type
PcmsObjAttrStruct to the attrs pointer and updates noAttrs accordingly.
The parameters are:

objPtr a pointer to a PcmsObjStruct.

number the number of PcmsObjAttrStruct(s) for which to allocate memory.

NOTE This macro works only on PcmsObjStructs that have not had attributes
already setup.

Add attrDef Structures

 PcmsAddAttrDefs(objPtr)
This macro allocates zero memory for all the PcmsObjAttrDefStruct(s) within a
PcmsObjStruct.
The parameter is:

objPtr a pointer to a PcmsObjStruc.

NOTE This macro works only on PcmsObjStructs that have NULL

objPtr.attr[n].attrDefs.

Single-Value Attributes (SVA)

 PcmsSvaSetVal (valuePtr, string, reserved)
This macro sets an attribute value in a single-value attribute.
The parameters are:

valuePtr the value structure being initialized and set (for a PcmsObjStruct
object objPtr and attribute number n, valuePtr is
objPtr.attrs[n].value).
string the value itself expressed as a char * string.
reserved is an integer field reserved for future use (use 0).

126 Serena® Dimensions® CM 12.2.1

 Attribute Macros

 PcmsSvaReSetVal (valuePtr, string, reserved)

This macro resets an attribute value in a single-value attribute.
The parameters are:

valuePtr the value structure being initialized and set (for a PcmsObjStruct
object objPtr and attribute number n, valuePtr is
objPtr.attrs[n].value).
string the value itself expressed as a char * string.
Reserved is an integer field reserved for future use (use 0).

 PcmsSvaGetVal (valuePtr)
This macro returns a char * corresponding to the string value of this attribute.
The parameter is:

valuePtr the value structure pointer being queried (for an object objPtr
and attribute number n, valuePtr is objPtr.attrs[n].value).

Multi-Value Attributes (MVA)

Instead of a single value, multiple-valued attributes maintain a value-set that is accessed
through the use of an index. You can use the following macros to access and set this
value-set.
 PcmsMvaSetVal (valueSetPtr, index, string, reserved)
This macro appends a value to a value-set.
The parameters are:

valueSetPtr the value set being added to (for an object objPtr and attribute
number n the valueSetPtr is objPtr.attrs[n].value).
index the index into the list. This index is incremented within the macro.
For the first value in the value-set, this index is zero.
string the value itself as a char * string.
reserved is an integer field reserved for future use (use 0).

 PcmsMvaNumVals(valueSetPtr)
This macro returns an integer value corresponding to the number of values currently
in the value-set.
The parameter is:

valueSetPtr the value set to query.

 PcmsMvaGetVal (valueSetPtr, index)

This macro returns the value of the value-set at a specific index as a char * string.
The parameters are:

valueSetPtr the valueSet to query.

index the integer index in the list of this attribute's value-set.

Developer's Reference 127

Chapter 3 DTK API Functions for C/C++

 PcmsMvaReSetVal(valueSetPtr, index, string,reserved)

This macro frees a certain indexed value and writes the new string into the same
position given by the index.
The parameters are:

valueSetPtr the value-set to manipulate.

index the integer index in the list of this attribute's value-set value.
string the new string.
reserved reserved

 PcmsMvaFree (valueSetPtr)
This macro frees a complete PcmsMva, that is, frees the whole list.
The parameters is:

valueSetPtr the valueSet to free.

NOTE It is useful to note that the SVA macros are only a convenience. It is possible
to access all attribute value structures with PcmsMvaNumVals() and
PcmsMvaGetVal(). For single value attributes PcmsMvaNumVals() will return 1.

128 Serena® Dimensions® CM 12.2.1

Chapter 4
DTK API Functions for Windows Client
Installations

Introduction 130
Building Client Applications 130
Sample Code Fragment 131
PcmsClntApiConnect - Connect to a Dimensions CM Database 132
PcmsClntApiDisconnect - Disconnect from a Dimensions CM Database 133
PcmsClntApiExecCommand - Execute a Dimensions CM Command 134
PcmsClntApiFree – Free Memory 135
PcmsClntApiGetLastError - Get the Last Dimensions CM Message 136
PcmsClntApiGetLastErrorEx - Get the Last Dimensions CM Message (Dynamic Buffer)
137
PcmsClntApiModeBinary - Set File Transfer Mode to Binary 138
PcmsClntApiModeText - Set File Transfer Mode to ASCII 139
PcmsClntApiSilentConnect - Connect Silently to a Dimensions CM Database 140
Additional Supported DTK Functions 142

Developer's Reference 129

Chapter 4 DTK API Functions for Windows Client Installations

Introduction
This chapter describes a set of functions that have been specifically written for Windows
client machines that have had only the Serena® Dimensions® CM Windows clients
installed. These functions give you access to the full functionality of the DTK but are
specifically written for Windows clients.

The description of each function has the following components

Purpose What the function does.

Prototype The function prototype.
Parameters Description of the parameters used in the function.
Return Codes Codes returned (please refer to DTK return codes on "DTK Return
Codes" on page 27 for further details).
Sample Sample function call (if applicable).
Comments Additional relevant information (if applicable).
Related Any related DTK function calls.
Functions

Before reading this chapter, ensure that you have familiarized yourself with the contents
of Chapter 2, "Writing Dimensions CM DTK Applications" because it contains important
information relating to data structures, return codes, and manifest constants that are
referenced in this chapter.

Building Client Applications

The client application functions are available in the supplied:
 clientapi.h include file and
 clientapi10m.lib library file (for MBCS applications)
 clientapi10u.lib library file (for Unicode applications)

All the above files are located in the directory %DM_ROOT%\pcms_api\.

Any source file that references the functions or constants must include clientapi.h.

If your application references connection functions, such as PcmsClntApiConnect(), you

must include the standard WinD2K file windows.h to properly compile the application.

130 Serena® Dimensions® CM 12.2.1

 Sample Code Fragment

Sample Code Fragment

PcmsObjStruct pObj = { 0 };
int conId = 0;
char errBuff[1024];
/* API will now connect and show the login dialog */
conId = PcmsClntApiConnect((HWND)NULL);
/* This is an example public API call looking for the Project
"TEST_WORKSET" */
if (PcmsInitSpec(conId, "TEST:TEST_WORKSET",
PCMS_WORKSET, &pObj)!=PCMS_OK)
{
/* API called failed so get the error and display it */
(void)PcmsClntApiGetLastError(conId, errBuff,
sizeof(errBuff));
(void)fprintf(stderr, errBuff);
return;
}
/* List the directories in the Project "TEST_WORKSET" */
(void)PcmsClntApiExecCommand(conId, "LWSD TEST:TEST_WORKSET");
/* Now display the output */
(void)PcmsClntApiGetLastError(conId, errBuff, sizeof(errBuff));
(void)fprintf(stdout, errBuff);
/* Now disconnect */
(void)PcmsClntApiDisconnect(conId);

Developer's Reference 131

Chapter 4 DTK API Functions for Windows Client Installations

PcmsClntApiConnect - Connect to a Dimensions CM

Database

Purpose
This function provides you with a login window allowing you to connect to a
Dimensions CM database. This function will return a connectId (integer) that represents
your database connection.

Prototype
int
PcmsClntApiConnect
(
HWND parent=NULL
);

Parameters
HWND parent is the parent window for the login dialog.

Return Codes
PcmsClntApiConnect() returns:

connectId on successfully completing the connection to the

Dimensions CM server.
PCMS_ERROR on error.
PCMS_FAIL on failure.

Related Functions
PcmsClntApiSilentConnect()

132 Serena® Dimensions® CM 12.2.1

 PcmsClntApiDisconnect - Disconnect from a Dimensions CM Database

PcmsClntApiDisconnect - Disconnect from a

Dimensions CM Database

Purpose
This function disconnects from the Dimensions CM database as specified by the conId.
The connectId must be a valid connectId returned by PcmsClntApiConnect() or
PcmsClntApiSilentConnect().

Prototype
int
PcmsClntApiDisconnect
(
int connectId
);

Parameters
connectId is the database connection identifier.

Return Codes
PcmsClntApiDisconnect() returns:

PCMS_OK on success.
PCMS_ERROR on error.
PCMS_FAIL on failure.

Related Functions
PcmsClntApiConnect(), PcmsClntApiSilentConnect()

Developer's Reference 133

Chapter 4 DTK API Functions for Windows Client Installations

PcmsClntApiExecCommand - Execute a Dimensions CM

Command

Purpose
This function sends a command to the Dimensions CM server specified by connectId.

Prototype
int
PcmsClntApiExecCommand
(
int conId,
char *command
);

Parameters
connectId is the database connection identifier.
command is a pointer to a user allocated character array that is populated
with the command to be executed.

Return Codes
PcmsClntApiExecCommand() returns:

PCMS_OK on success.
PCMS_ERROR on error.
PCMS_FAIL on failure.

134 Serena® Dimensions® CM 12.2.1

 PcmsClntApiFree – Free Memory

PcmsClntApiFree – Free Memory

Purpose
This function is a wrapper to the C function free(). It must be used to free memory
allocated by PcmsClnt API DTK functions, such as PcmsClntApiGetLastErrorEx(). The
reason for this is that on some platforms, like Windows, the memory that is allocated
within a shared library must be freed by the same shared library. If this is not done, then
memory errors begin to occur.

Prototype
void PcmsClntApiFree (void *buffer);

Parameters
buffer is a pointer to the memory block that will be freed.

Developer's Reference 135

Chapter 4 DTK API Functions for Windows Client Installations

PcmsClntApiGetLastError - Get the Last Dimensions CM

Message

Purpose
This function allows you to access the output from the last Dimensions CM command that
was run on the server through PcmsClntApiExecCommand().

Prototype
int
PcmsClntApiGetLastError
(
int connectId,
char *errorBuffer,
int maxLength
);

Parameters
connectId is the database connection identifier. If the error prevented the
establishment of a connection, pass a connectID value of -1.
errorBuffer is a pointer to a user allocated character array that is populated
with the text of the server message.
maxLength is the maximum length of the server message to be displayed.

Return Codes
PcmsClntApiGetLastError() returns:

PCMS_OK on success.
PCMS_ERROR on error.
PCMS_FAIL on failure.

Related Function
PcmsClntApiGetLastErrorEx()

136 Serena® Dimensions® CM 12.2.1

 PcmsClntApiGetLastErrorEx - Get the Last Dimensions CM Message (Dynamic Buffer)

PcmsClntApiGetLastErrorEx - Get the Last

Dimensions CM Message (Dynamic Buffer)

Purpose
This function allows you to access the output from the last Dimensions CM command that
was run on the server through PcmsClntApiExecCommand(). The functionality of this
command is the same as for PcmsClntApiGetLastError() except that the buffer size is
dynamically allocated.

Prototype
int
PcmsClntApiGetLastErrorEx
(
int connectId,
char **errorBuffer
);

Parameters
connectId is the database connection identifier. If the error prevented the
establishment of a connection, pass a connectID value of -1.
errorBuffer is a pointer to a contiguous block of allocated memory that is
populated with the message text.

It is the responsibility of the calling application to free this pointer

when it is no longer required.

Return Codes
PcmsClntApiGetLastErrorEx() returns:

PCMS_OK on success.
PCMS_ERROR on error.
PCMS_FAIL on failure.

Related Function
PcmsClntApiGetLastError()

Developer's Reference 137

Chapter 4 DTK API Functions for Windows Client Installations

PcmsClntApiModeBinary - Set File Transfer Mode to

Binary

Purpose
This function sets the file transfer format to binary for any subsequent item commands
that are issued.

Prototype
void
PcmsClntApiModeBinary
(
int connectId
);

Parameters
connectId is the database connection identifier.

Return Codes
None.

Comments
You must use this command if you are going to perform operations that require file
transfer from the client to the server (or vice versa) to occur in binary mode. An example
of this might be getting a binary item into your PC. When you perform any file transfer
operations, such as check in (RI), Dimensions CM will not validate the format of the file
being transferred.

138 Serena® Dimensions® CM 12.2.1

 PcmsClntApiModeText - Set File Transfer Mode to ASCII

PcmsClntApiModeText - Set File Transfer Mode to ASCII

Purpose
This function sets the file transfer format to ASCII for any subsequent item commands
that are issued.

Prototype
void
PcmsClntApiModeText
(
int connectId
);

Parameters
connectId is the database connection identifier.

Return Codes
None.

Comments
You must use this command if you are going to perform operations that require file
transfer from the client to the server (or vice versa) to occur in ASCII mode. An example
of this might be getting an ASCII item into your PC. When you perform any file transfer
operations, such as check in (RI), Dimensions CM will not validate the format of the file
being transferred.

Developer's Reference 139

Chapter 4 DTK API Functions for Windows Client Installations

PcmsClntApiSilentConnect - Connect Silently to a

Dimensions CM Database

Purpose
This function provides you with a connection to a Dimensions CM database as specified by
your input parameters. This function will return a conId that represents your connection
to the Dimensions CM server.

Prototype
int
PcmsClntApiSilentConnect
(
char *user,
char *password,
char *host,
char *pcms_install,
char *db_name,
char *db_pword,
char *db_node
);

Parameters
user is your operating system login name.
password is your operating system password.
host is the Dimensions CM server node name that you wish to connect
to.
pcms_install is the Dimensions CM server installation directory, for example,
/opt/serena/dimensions/10.1/cm. If a null entry is submitted,
this parameter is ignored.
db_name is the name of the Dimensions CM database that you wish to
connect to, for example, intermediate.
db_pword is the password of the database. If a null entry is submitted, this
parameter is ignored.
db_node is the RDBMS service name assigned to the node where the RDBMS
database is located.

Return Codes
PcmsClntApiSilentConnect() returns:

int connectId on successful connection.

PCMS_ERROR on error.
PCMS_FAIL on failure.

140 Serena® Dimensions® CM 12.2.1

 PcmsClntApiSilentConnect - Connect Silently to a Dimensions CM Database

Related Functions
PcmsClntApiConnect()

Developer's Reference 141

Chapter 4 DTK API Functions for Windows Client Installations

Additional Supported DTK Functions

In addition to the specific Win32 functions described in this chapter, the following
standard Dimensions CM DTK functions are also available. These functions are fully
documented in Chapter 3, "DTK API Functions for C/C++".

PcmsAttrDefInit() PcmsGetRSNamest() *
PcmsAttrGetLov() * PcmsGetUserRelTypes() *
PcmsAttrValidate() * PcmsGetUserRoles() *
PcmsCntrlPlanGet() * PcmsGetWsetObj() *
PcmsEvntCalloc() PcmsInitSpec()
PcmsEvntFree() PcmsInitUid()
PcmsEvntMalloc() PcmsLovFree()
PcmsEvntRealloc() PcmsObjFree()
PcmsFullQuery() * PcmsObjGetBackRels() *
PcmsGetAttrDefNum() * PcmsObjGetRels() *
PcmsGetAttrs() PcmsPendGet() *
PcmsGetCandidates() * PcmsPendWhoGet()
PcmsGetPendingUsers() * PcmsPopulate() *
PcmsGetRSAttrs() * PcmsQuery() *

NOTE Functions marked with an asterisk (*) require that the following file to be installed
on each client: %DM_ROOT%\msg\pcms_api_sql_uk.msb. This can be accomplished by a
default client installation or by copying the file from the Dimensions CM server, where it
resides in the same directory.

142 Serena® Dimensions® CM 12.2.1

Part 2
Events Callout

Part 2: Events Callout contains the following chapters:

Dimensions CM Events Callout Interface 145

Developer's Reference 143

Part 2 Events Callout

144 Serena® Dimensions® CM 12.2.1

Chapter 5
Dimensions CM Events Callout Interface

Description 146
Shared Libraries 146
MBCS Versus UTF-8 Support 146
Large File Support 147
Public Function Call 147
Event Callout Interface 148
Determining the Event You Want 151
First and Second Event Calls 152
Event Call Summary 153
Writing a DTK Callout Event 153
DTK Event Internals 156
Changing System-Attributes on Validate Events 157
Changing User-Attributes on Validate Events 158
Recommendations on How to Change Attribute Values 158
Calling DTK Functions Within Events 159
Using the ptrEventInfo in Events 160
Recompiling With New Versions of Dimensions CM 161
Event Examples 161
Events - A Final Word and a Warning 161

Developer's Reference 145

Chapter 5 Dimensions CM Events Callout Interface

Description
This chapter outlines the functionality, design and implementation of applications using
the Serena® Dimensions® CM Event Callout Interface. Before reading this chapter ensure
that you familiarize yourself with the concept of shared libraries because it is through this
mechanism that this event interface is implemented.

Shared Libraries
The Dimensions CM Event Callout Interface is provided by giving you access to a public
function call that is invoked when certain Dimensions CM commands are run. This
function is called userSuppliedFunction() and is resolved in a shared library called
libpcmsu. On a default Dimensions CM installation a stub version of this library is
provided. If you wish to implement your own event callout, you will need to build your
own shared library and use this in place of the stub.

For more information on how to build shared libraries please refer to your system
documentation or for guidelines refer to the examples provided in:
 UNIX: $DM_ROOT/pcms_api/examples/
 Windows: %DM_ROOT%\pcms_api\examples\

MBCS Versus UTF-8 Support

Dimensions CM supports both Multi-Byte Character Sets (MBCS) and UTF-8 Character
Sets. This means, however, that depending on what type of database you are connecting
to, the way you compile your events may have to be different, namely:
 If you are connecting to a UTF-8 database, then your events will have to be compiled
using the compiler directive -DDM_UNICODE.
 If you are connecting to any type of database other than UTF-8, then your events will
have to be compiled using the compiler directive -D_MBCS.

You can determine the nature of the database you are connecting to by selecting from the
DM_CHARACTERSET view in the PCMS_SYS schema. If this view returns null or a value
other than AL32UTF8, then you are connecting to an MBCS database.

IMPORTANT! A SQL Server RDBMS is always a MBCS database.

The example DTK events provided generate UTF-8 compatible shared libraries by default,
that is, the libraries ending end in 'u'. To change this behavior, use the MBCS_NEEDED=y
make flag when you run the Dimensions CM dm_make command. This will generate a
shared library with 'm' at the end of the library name.

Copy the appropriate library you require to your usual installation directory:

146 Serena® Dimensions® CM 12.2.1

 Large File Support

 If your database has a UTF-8 character set, search the installation directory to locate
the library, and remove the 'u' in the library name.
 For any other kind of database character set, you must not rename the library name,
that is, you must leave it with the 'm' extension.

If you use an MBCS shared library against a UTF-8 database or vice versa, the results will
be unpredictable as the server will probably experience memory issues.

Large File Support

The Dimensions CM 2009 R1 or later API has added support for large files (4GBytes or
greater). See Step 4 of "Introduction" on page 26 for a discussion of this topic.

Public Function Call

The prototype for the public function call userSuppliedFunction() is:

int userSuppliedFunction(
PcmsEventStruct *ptrPcmsEventStruct,
PcmsObjStruct *ptrObj,
PcmsObjStruct *ptrUser,
char **ptrErrorMessage,
int *noEventInfo,
void **ptrEventInfo);

where the parameters are:

ptrPcmsEventStruct is a pointer to a PcmsEventStruct in which the details on

the current event being fired are held.
ptrObj is a pointer to a PcmsObjStruct that holds the object
details pertaining to the Dimensions CM object currently
being processed.
ptrUser is a pointer to a PcmsObjStruct that holds the details on
the user currently running the event.
ptrErrorMessage is a pointer to a pointer that allows you to setup an error
message to be printed instead of the default
Dimensions CM message.

Developer's Reference 147

Chapter 5 Dimensions CM Events Callout Interface

noEventInfo is an integer variable that is used in context with

ptrEventInfo to access members of that pointer.
ptrEventInfo is a pointer to a void *pointer that is populated with
different information depending on the event called.

For PCMS_EVENT_MAIL, PCMS_EVENT_DLGI, and

PCMS_EVENT_DLGC events this pointer will point to an
array of PcmsUserRoleStructs.

For a PCMS_EVENT_RELATE or PCMS_EVENT_UNRELATE

event this pointer will point to an array of
PcmsRelStructs.

Event Callout Interface

As indicated previously, when certain Dimensions CM commands are run, the public
function userSuppliedFunction() is invoked with a number of parameters. These
parameters are used to specify what event is being fired; what Dimensions CM object is
being affected, and finally which type of Dimensions CM command is being run. Each time
an event is fired the following hierarchy of calls is made to userSuppliedFunction():
 Validate event call (fired only when a user or system attribute has changed).
 Pre-event call.
 Post-event call.

Each of the event calls allows you to perform a number of operations on the
Dimensions CM object on which the event has been called.

You can access the type of event being fired by examining the ptrPcmsEventStruct as
described on page 151.

Validate Events
Validate events are called prior to any Dimensions CM validation being run on the data
supplied. Typically, you can use validation events to inspect information (such as the
object details, default, and user attributes) and then change this information. You could,
for example, use this event to implement your own automatic item identity generator or
perform extra validation on user-defined date attributes. Once this event has been fired
Dimensions CM will then proceed with its normal validation checks. This event is indicated
by the use of the constant PCMS_EVENT_VALIDATE_OP.

NOTE Validate events are fired only when user or system attributes change as a result
of a command. This means that events captured on the validate event will be Type
PCMS_EVENT_UPDATE events

Pre-Events
Pre-events are called prior to the Dimensions CM command being executed. You can use
this event to stop the execution of this command by returning the failure status

148 Serena® Dimensions® CM 12.2.1

 Event Callout Interface

PCMS_FAIL. If you populate ptrErrorMessage, then this error string will be displayed
through whatever interface invoked the command. Typically, you can use this event to
perform any specific validation before deciding to let the command proceed. This event is
indicated by the use of the constant PCMS_EVENT_PRE_OP.

Post-Events
Post-events are called after the Dimensions CM command has been run. Typically you can
use this event to perform any 'clean up' or post-command logging to other applications.
This event is indicated by the use of the constant PCMS_EVENT_POST_OP.

Event Types
In addition to the event hierarchy described in the previous sub-sections, each event fired
also has an event type that relates to the type of Dimensions CM command being run.
These event types are:

Event Type Activity to a Dimensions CM Object

PCMS_EVENT_ACTION Actioned.
PCMS_EVENT_ADD Addition.
PCMS_EVENT_CANCEL Check out of object is canceled.
PCMS_EVENT_CREATE Created.
PCMS_EVENT_DELETE Deleted.
PCMS_EVENT_DELIVER Delivered (project or stream)*.
PCMS_EVENT_DEMOTE Demoted.
PCMS_EVENT_DLGC Request is delegated to a user.
PCMS_EVENT_DLGI Item is delegated to a user.
PCMS_EVENT_EXTRACT Object is checked out.
PCMS_EVENT_FETCH Object is gotten/fetched (or browsed).
PCMS_EVENT_LOCK Object is locked.
PCMS_EVENT_MAIL A Dimensions CM mail message is being sent.
PCMS_EVENT_PROMOTE Promoted.
PCMS_EVENT_RELATE Object is related to another object.
PCMS_EVENT_REMOVE Removal.
PCMS_EVENT_REMNAME Renaming.
PCMS_EVENT_RETURN Object is checked in.
PCMS_EVENT_UNRELATE Object is unrelated from another object.
PCMS_EVENT_UNLOCK Object is unlocked.
PCMS_EVENT_UPDATE Updated.
PCMS_EVENT_UPLOAD Project is uploaded to*.

Developer's Reference 149

Chapter 5 Dimensions CM Events Callout Interface

* These events are for information purposes only (PCMS_EVENT_PRE_OP) or for aborting
the operation (PCMS_EVENT_POST_OP)—you cannot manipulate the objects passed into
them (PCMS_EVENT_VALIDATE_OP)

While a single Dimensions CM command, such as 'getting an item', can fire a single event
type (PCMS_EVENT_FETCH) it is also possible for a command to generate multiple different
events. Consider, for example, the following command:

UI "FS:TEST.A-SRC,1" /REV=2.1/ATTRIBUTE=(COMPLEXITY="Delta7")

This command performs a check out, check in, and an update of attribute values. Thus, if
you ran the command as described previously, the following events would be fired.

Event Type Action to a Dimensions CM Item

PCMS_EVENT_EXTRACT Checked out from Dimensions CM.

PCMS_EVENT_MAIL Notification of an event happening that sends out e-mail.
PCMS_EVENT_RETURN Checked in to Dimensions CM.
PCMS_EVENT_UPDATE Attributes updated.

If you added additional parameters to this command, such as /STATUS or

/RELATE_CHDOC, other events would also have been fired.

The table below describes the commands that fire events and the objects types they
involve.

BASELINE
REQUEST

PROJECT

RELEASE
PART

ITEM

EventId
PCMS_EVENT_
ACTION SPV, UP AI, SI AC AWS
ADD AIWS
CANCEL (N/A) CIU
CREATE CP, CPV CI CC CWSD, CBL, REL
DWS, CMB,
MWS CRB
DELETE DPV DI DWSD, DLB DREL
RWS
DEMOTE DMI DMRQ DMBL
DLGC (N/A) DLGC
DLGI DLGI
EXTRACT UP EI, UI
FETCH FI BC
LOCK LCK LCK

150 Serena® Dimensions® CM 12.2.1

 Determining the Event You Want

BASELINE
REQUEST

PROJECT

RELEASE
PART

ITEM
EventId
PCMS_EVENT_
MAIL CP, DPV, AI, AC,CC, AWS, ABL,
SPV, UP, AIWS, DLGC, DWS, CBL,
UPA, CPV CI, DI, RBCD, LCK, CMB,
DLGI, RCCD, RWS, CBL, DBL
DPI, EI, RICD, ULCK,
LCK, RI, RWCD, UWA
RIWS, UC,
UI, UIA, XBCD,
ULCK XCCD,
XICD,
XWCD
PROMOTE PMI PMRQ PMBL
RELATE RIP RII RCCD,
RICD,
RPCD,
RWCD
REMOVE RIWS MWSD
RENAME SWF
RETURN UP RI, UI
UNLOCK ULCK ULCK
UNRELATE XIP XII XCCD,
XICD,
XPCD,
XWCD
UPDATE UPA, UP, CI, EI, CC, UC UWA UBLA
CP, CPV RI, UI,
UIA

Determining the Event You Want

When the userSuppliedFunction() is invoked, one of the parameter passed in is a
pointer to a PcmsEventStruct that can be interrogated for details such as:
 The event type, for example, PCMS_EVENT_CREATE.
 Where in the hierarchy the event is being fired, for example, validate or pre-event.
 The object type the event is being fired on, for example, PCMS_ITEM.

By examining the following fields of the PcmsEventStruct you can trap the event you
specifically require.

eventId the event type.

Developer's Reference 151

Chapter 5 Dimensions CM Events Callout Interface

whenCalled the position in the event hierarchy.

objType the type of object that the event was fired on.

First and Second Event Calls

Populating all the parameters for an event can take time, especially if you are connected
to a remote database over a WAN. As a result of this, each time an event is to be fired you
get a chance to determine whether or not you are really interested in that event. This
separation is known as the 'first and second call' to an event.

The first call to an event populates only the sparse details on the Dimensions CM object
and the PcmsEventStruct to allow you to determine if you are interested in this event.
The specific details provided in the PcmsObjStruct depend on what command is called,
on what object, and under what circumstances—as shown in the next two tables.

Object type First call details

Baselines objType, typeUid, typeName, productId, objId, variant,
revision, userName, status, dateTime
Items objType, typeUid, typeName, productId, objId,
revision, userName, status, dateTime
Parts objType, typeUid, typeName, productId, objId,
userName, dateTime
Projects objType, typeUid, typeName, productId, objId, variant,
revision, description, userName, status, dateTime
Releases objType, productId, objId
Requests objType, productId, typeName, status, typeUid

Object type Second call details

Baselines uid, objType, typeUid, typeName, productId, objId,
variant, revision, userName, status, dateTime
Items uid, objType, typeUid, typeName, productId, objId,
variant, revision, description, userName, status,
dateTime
Parts uid, objType, typeUid, typeName, productId, objId,
variant, revision, description, userName, status,
dateTime
Projects uid, objType, typeUid, typeName, productId, objId,
variant, revision, description, userName, dateTime
Releases uid, objType, productId, objId, dateTime
Requests uid, objType, typeUid, typeName, productId, objId,
userName, status, dateTime

152 Serena® Dimensions® CM 12.2.1

 Event Call Summary

A first call event can be determined by checking if:

ptrUser == (PcmsObjStruct *)0 and ptrErrorMessage == (char *)0

If you select the first call, then only the ptrPcmsEventStruct will be fully populated. The
ptrObj will only have the object-specification fields and uid filled in. If as a result of
examining these partial details, you decide that you really want this event, then returning
the status PCMS_OK will generate a second event call. If you are not interested in this
event, then return PCMS_FAIL and the second call to this event will not be fired.

The second event call can be regarded as the 'real' event call. This has all the data
structures filled in and allows you to access all the attribute information for the object. It
is on this call that your event should perform its operation.

Event Call Summary

The following table summarizes the event callout mechanism.

Step Command
1 Read Dimensions CM Command.
2 FIRST CALL VALIDATE EVENT and check that VALIDATE EVENT is required.
3 If VALIDATE EVENT is required, then call VALIDATE EVENT again.
4 If VALIDATE EVENT not required, then END.
5 Evaluate User Data and Execute the Dimensions CM Command.
6 FIRST CALL PRE-EVENT and check that PRE-EVENT is required.
7 If PRE-EVENT is required, then call PRE-EVENT again with fully detailed data.
8 If PRE-EVENT not required, then END.
9 COMMIT Dimensions CM Command to database.
10 FIRST CALL POST-EVENT and check that POST-EVENT is required.
11 If POST-EVENT is required, call POST-EVENT again with fully detailed data.

Steps 3, 7, and 11 occur when the real VALIDATE, PRE and POST EVENTS are done.

Writing a DTK Callout Event

This section describes how to design and write a DTK event, the pitfalls to watch out for,
and in what situations an event is applicable.

Is an Event the Solution for You?

Before you start to write an event to implement your solution, you must decide if an event
is what you really need. To help you decide bear in mind the following questions.

Developer's Reference 153

Chapter 5 Dimensions CM Events Callout Interface

 Is the functionality that you seek to achieve already in Dimensions CM?

If you are seeking to implement stronger rules for object relationships or attributes,
this functionality is already available in Dimensions CM.
 Is the functionality that you seek to achieve initiated by a Dimensions CM command?
The events are strictly intended to allow you to perform inline processing or checking
on a specific object. They are not intended to allow you to run multiple
Dimensions CM commands on the same object. When a validate-event or pre-event is
fired on an object, then that object becomes locked until the transaction has been
committed to the database. If you try to spawn another Dimensions CM command,
then you run the following risks:
• The Dimensions CM command that you spawned will be suspended waiting for the
lock to be released, and it will never be released until a time-out has occurred.
• The Dimensions CM command will cause the same event to be fired that will spawn
yet another Dimensions CM command that calls the same event spawning yet
another command, and so on until your machine locks up.
If you are intending to use an event to spawn other Dimensions CM related
commands, then you are strongly advised to use a separate DTK client application to
perform this sequencing of commands.
 Does the operation you want to capture actually fire an event?
Not all Dimensions CM commands fire events. You need to be sure that the operation
you want to capture actually fires an event.

Designing Your Event

When you have decided that your solution requires an event, you need to decide which
event you need to capture, and which type of event you have to use. Events are fired
when you run a Dimensions CM command, so decide on the list of Dimensions CM
commands that invoke the events you want and scope this list to the type of objects you
wish to process. Examining this list you may discover that you may need to filter out
certain events, commands or objects to obtain just the processing you want. You will need
to code this filtering into your event. When you are looking at this list remember that
additional parameters can call additional events. You can filter the events that you select
by either examining the ptrPcmsEventStruct as described previously in "Public Function
Call" on page 147, or you can access the actual Dimensions CM command being run
through PcmsGetCommandLine() and filter on this.

Once you know the list of commands and type of events that you are going to trap, you
need to consider where in the callout hierarchy this trapping will occur. The basic rules are
to trap:
 The validate event if you wish to change any information.
 The pre-event if you wish to be able to stop the operation.
 The post-event if you wish to perform an action after the Dimensions CM operation
has committed data to the database and freed all the locks on that object.

154 Serena® Dimensions® CM 12.2.1

 Writing a DTK Callout Event

Suggestions for More Common Operations

 Changing attributes (user and system) or setting defaults
To change, set or reformat attributes you have to capture the PCMS_EVENT_UPDATE at
the PCMS_EVENT_VALIDATE_OP stage in the call hierarchy.
 Changing object Id on creation
If you wish to wish to change the object identifier or filename used when an object is
created, then you have to capture the PCMS_EVENT_CREATE and
PCMS_EVENT_UPDATE events at the PCMS_EVENT_VALIDATE_OP stage in the call
hierarchy.
 Allowing the action of an object only if certain criteria are matched
If you have specific checks that you wish to perform before objects are actioned from
one state to another e.g. releasing a baseline to test, then you have to capture the
PCMS_EVENT_ACTION event at the PCMS_EVENT_PRE_OP stage in the call hierarchy.
 Logging to another application that a Dimensions CM operation has occurred
If you have integrated Dimensions CM with another application and wish to signal to
that application that a command has been run, then you have to capture all the
events at the PCMS_EVENT_POST_OP stage in the call hierarchy.

Writing Your Event

You have to write your event code with the userSuppliedFunction() as the interface
point between Dimensions CM and your event code. The return codes from this function
call are the standard PCMS_OK, PCMS_FAIL, and PCMS_ERROR. These return calls have the
following effects:

First Event Call

PCMS_OK causes a second event call to occur.
PCMS_FAIL causes Dimensions CM to ignore this event and
continue with its normal processing for the operation.
No second event call will be made.

Second Event Call

PCMS_EVENT_VALIDATE_OP PCMS_OK will allow the Dimensions CM operation to
continue. If any attributes have been changed, then the
new values will be used.
PCMS_FAIL will cause the Dimensions CM operation to
fail and any error messages in the
ptrPcmsErrorMessage pointer will be printed.
PCMS_ERROR is the same as PCMS_FAIL
PCMS_EVENT_PRE_OP PCMS_OK will allow the Dimensions CM operation to
continue.

Developer's Reference 155

Chapter 5 Dimensions CM Events Callout Interface

Second Event Call

PCMS_FAIL will cause the Dimensions CM operation to
fail and any error messages in the
ptrPcmsErrorMessage pointer will be printed.
PCMS_ERROR is the same as PCMS_FAIL.
PCMS_EVENT_POST_OP Because the operation has been completed, the status
at this point is irrelevant, but for consistency you should
return PCMS_OK.

In the first event call you need to interrogate the ptrPcmsEventStruct to determine
whether or not to trap this event and, if so, return PCMS_OK, else return PCMS_FAIL.

In the second event call you need to place the code to support your event logic and return
the appropriate status.

DTK Event Internals

When an event is passed to your function you are able to both manipulate the data
supplied and/or view many of the internal changes that have occurred or will occur on an
object as a result of the Dimensions CM command. This section discusses what
information these pointers give you and how you can use them to achieve various
different effects.
 The PcmsEventStruct pointer – ptrPcmsEventStruct
This pointer is the most important structure passed down to an event. It is used to
both control the event operation and also to indicate what attributes (both user and
system) have been affected. How to determine which event is being called has
already been discussed. How the attributes are controlled is determined through the
noAttrsChanged and attrsChanged members of this pointer.
When events are fired, any system or user defined attributes that have been modified
as a result of the command are populated into the noAttrsChanged and
attrsChanged members. On a validate-event you can manipulate these variables to
add, reset or remove attribute values:
• If you are resetting an attribute value, then loop through the attrsChanged
pointer until you find the attribute structure that you wish to change. Once you
have found this attribute, you can use the multi value attributes (MVA) or single
value attributes (SVA) macros to reset the attribute value. If you are resetting
values on a MVA attribute, then you must first free the memory associated with
this attribute through PcmsMvaFree() before adding your new values.
• If you are adding a new attribute value, then you will need to:
 Resize the attrsChanged pointer to add a new PcmsObjAttrStruct.
 Increment the noAttrsChanged index by 1.
 Set the appropriate values on the new attribute structure.
It is important to note that the attrDef pointer in the attribute structure must be
set to NULL.

156 Serena® Dimensions® CM 12.2.1

 Changing System-Attributes on Validate Events

• If you are removing an attribute definition, then you will need to resize the
attrsChanged pointer to remove this attribute and decrease the
noAttrsChanged index by 1.
 The PcmsObjStruct – pointer ptrObj
This pointer contains all the details on the object that the event is currently
processing. On a first call to the event this object contains only minimal data. On the
second call to the event this object is fully populated.
When you create a new object, such as an item or a part, a validate-event is fired
during which you can manipulate the contents of this pointer to change the object's
details. You are able to change entries in the objId, variant, and revision fields.
Using this mechanism you could write an event that changes item Ids to suit your
own automatic object identity generator.
 The PcmsObjStruct – pointer ptrUser
This pointer contains all the details on the user currently running the event. This
pointer is populated only on the second call and is 'read only'.
 The error pointer – ptrErrorMessage
This pointer allows you to set up an error message that will be printed by
Dimensions CM when a validate-event or pre-event returns a status other than
PCMS_OK. This allows you to print your own custom error messages when an event
fails.
 The noEventInfo and ptrEventInfo pointers
These pointers operate together. Their usage is described on page 160.

Changing System-Attributes on Validate Events

While there are no restrictions on changing user-defined attributes in the validate event,
you are, however, limited to what system attributes you can change. While you can
modify the attrsChanged pointer to include any system attribute definition, only the
following will have any affect.

Event Type Object Type System Attribute

PCMS_EVENT_ : PCMS_ : PCMS_ATTR_ :
CREATE ITEM FORMAT
FILENAME

LIB_FILENAME

DIRPATH

USER_FILENAME

PART PARTNO

LOCALNO

RELEASE DIRPATH

Developer's Reference 157

Chapter 5 Dimensions CM Events Callout Interface

Event Type Object Type System Attribute

PCMS_EVENT_ : PCMS_ : PCMS_ATTR_ :
EXTRACTa ITEM FORMAT
USER_FILENAME
REVISION

RETURNb ITEM FORMAT

USER_FILENAME

a.Check out.
b.Check in.

If you specify any other values for system-attributes, these will be ignored.

The above-mentioned attributes can be changed only when a new object is created or an
item is checked out at a new revision.

Changing User-Attributes on Validate Events

There are no restrictions on what you can do with user-defined attributes on a validate
event. However, Dimensions CM will apply the usual validation to any attributes that you
setup in the attrsChanged structure. If the attribute is not defined, has the wrong value
or the user does not have the role to change it, then Dimensions CM will generate an
appropriate error message.

Recommendations on How to Change Attribute Values

The following steps provide a recommended approach on how you should change the
attrsChanged pointer.
 Examine the attrsChanged structure in the ptrPcmsEventStruct.
 If the pointer is NULL, you need to allocate memory to this pointer (that is the size of
PcmsObjAttrStruct) and set noAttrsChanged to 1. Once the memory has been
allocated, then set the members of the attrsChanged pointer to the appropriate
values.
For example, for an SVA

PtrPcmsEventStruct->attrsChanged[0].attr=<ATTR_NO>
PcmsSvaSetValue(ptrPcmsEventStruct->attrChanged[0].value,
"text String",0);
ptrPcmsEventStruct->attrChanged[0].attrDef =
(PcmsObjAttrDefStruct *)0;
 If the pointer currently has attributes setup, then you need to check if the attribute
you want to change is currently in that pointer. You can do this by looping through the
attrChanged[x].attr(s) and looking for a match to your attribute number. Once
you have found a match then use PcmsSvaSetVal() or PcmsMvaReSetVal()to reset

158 Serena® Dimensions® CM 12.2.1

 Calling DTK Functions Within Events

the value. If you are resetting the MVA values for an attribute, then remember to free
the attribute value set first through PcmsMvaFree().
 If the pointer currently has attributes setup, but you cannot find a match using the
search method indicated above then you need to re-allocate memory to the
attrsChanged pointer to add a new PcmsObjAttrStruct. Using this newly allocated
structure you can set the attribute values as described above and increment the
noAttrsChanged variable by 1.

Calling DTK Functions Within Events

When you call DTK functions from within an event the connection identifier (conId) that
you need to use is 0. This is a special connection identifier that relates to the current
connection that Dimensions CM has to your database. You do not need to call
PcmsConnect() or PcmsDisconnect() to access the DTK functions. If you try to use
these functions to initiate a connection to the database or another database, then your
Dimensions CM session may become unstable.

Specialist DTK Event Functions

There are a number of DTK functions that, although available to DTK client applications,
are specifically aimed at helping you to write your event. These functions are aimed at
memory management and accessing the Dimensions CM command line.

DTK Function Description

PcmsEvntCalloc() Wrapper to calloc().
PcmsEvntFree() Wrapper to free().
PcmsEvntMalloc() Wrapper to malloc().
PcmsEvntRealloc() Wrapper to realloc().
PcmsGetCommandLine() Access to the Dimensions CM command that invoked
this event.

Unsupported DTK Function Calls from Within an Event

You can call virtually all the DTK functions from within an event. There are, however, a
number of exceptions to this rule. Some of the DTK functions, due to the nature of the
command that they are running, are not allowed to be called from within an event. These
functions are listed below.

DTK Function Description

PcmsCheckMessages() Check results from Dimensions CM commands.

PcmsConnect() Connect to a Dimensions CM database.
PcmsDisconnect() Disconnect from a Dimensions CM database.
PcmsExecCommand() Execute a Dimensions CM command.
PcmsGetConnectDesc() Get current connection details.

Developer's Reference 159

Chapter 5 Dimensions CM Events Callout Interface

DTK Function Description

PcmsSendCommand() Execute a Dimensions CM command.

PcmsSetAttrs() Set attributes on a Dimensions CM object.
PcmsSetCallback() Set callback functions.
PcmsSetDbErrorCallback() Set callback functions.
PcmsSetDirectory() Change working directory.
PcmsSetIdleChecker() Set callback functions.

Using the ptrEventInfo in Events

The special void * pointer ptrEventInfo is filled in when certain events are fired to
provide you with additional information pertinent to those events. The information
contained in the pointer will change depending on the event that is being fired. The
following table lists the structures that this pointer needs to be typecast to depending on
the event being fired.

DTK Event DTK Structure

PCMS_EVENT_CREATE PcmsChdAttachmentStruct
PCMS_EVENT_DELIVER PcmsDeliverStruct
PCMS_EVENT_DLGC PcmsUserRoleStruct
PCMS_EVENT_DLGI PcmsUserRoleStruct
PCMS_EVENT_FETCH PcmsChdAttachmentStruct
PCMS_EVENT_MAIL PcmsUserRoleStruct
PCMS_EVENT_RELATE PcmsRelStruct
PCMS_EVENT_UNRELATE PcmsRelStruct
PCMS_EVENT_UPDATE PcmsChdAttachmentStruct

If you need to access the information in these structures, then your event needs to do the
following:
 For RELATE and UNRELATE event types, typecast the ptrEventInfo through:

PcmsRelStruct *ptrRel = (PcmsRelStruct*)*ptrEventInfo;

 For request CREATE, FETCH, and UPDATE event types, typecast the ptrEventInfo
through:

PcmsChdAttachmentStruct *ptrAttachs =
(PcmsChdAttachmentStruct*)*ptrEventInfo;
 For other events, typecast the pointer through:

PcmsUserRoleStruct *ptrRel = (PcmsUserRoleStruct*)*ptrEventInfo;

Once you have typecast the pointer, you can use the ptrEventInfo pointer to access the
information. For example, in a MAIL event you might do the following:

160 Serena® Dimensions® CM 12.2.1

 Recompiling With New Versions of Dimensions CM

{
PcmsUserRoleStruct *ptrUser =
(PcmsUserRoleStruct*)*ptrEventInfo;
int noUses = *noEventInfo;
int i = 0;

for (i = 0; i < noUsers; i++)

(void)fprintf(fd,"\nFound user : %s",ptrUser[i].user);
}

In Delegate Events (DLGI and DLGC) the applyDeny and treeWalk members of
PcmsUserRoleStruct have special meanings that relate to the option specified on the
command line. These meanings are listed below:

Operation applyDeny treeWalk

/ADD Y Y
/DELETE N N
/REPLACE Y N

Recompiling With New Versions of Dimensions CM

You must recompile any application that uses the Events Callout Interface after upgrading
to a new version of Dimensions CM. This ensures that your applications make use of any
changes to the events in new versions of Dimensions CM.

Event Examples
The release media contains a number of example events and makefiles to help you get
started. These are contained in the examples subdirectories of the Dimensions CM
installation specified below:
 $DM_ROOT/pcms_api/examples (UNIX)
 %DM_ROOT%\pcs_api\examples (WINDOWS)

IMPORTANT! To be able to successfully build these example events, you must use the
compiler versions as specified in the readme.

Events - A Final Word and a Warning

Events are a powerful and versatile way of extending the rich functionality of
Dimensions CM. They allow you to implement your own specific process controls and
integrations with external applications. Used well, events can enhance both your working
practices and use of Dimensions CM. However, if your events have not been written

Developer's Reference 161

Chapter 5 Dimensions CM Events Callout Interface

carefully, you do run the risk of affecting Dimensions CM functionality, especially if your
event causes memory corruption. You are strongly advised to test any complex events
thoroughly before deploying them, and if possible use a memory tracking tool to verify
memory use.

162 Serena® Dimensions® CM 12.2.1

Chapter 6
Action Driven Promotion Event Triggers

Overview 164
Approach 164
Implementation of Action Driven Promotion Event Triggers 164

Developer's Reference 163

Chapter 6 Action Driven Promotion Event Triggers

Overview
You can additionally assign deployment stages to request and baseline lifecycle states in a
similar manner.

Approach
To keep the action driven promotion logic separate from the Dimensions CM server, it has
been implemented as a Dimensions CM Event Trigger (a separate Dynamic-Link Library
(DLL) containing a function that will be called after the action command).

The mapping of lifecycle states to deployment stages itself is performed interactively

using the Administration Console—see the Process Modeling User’s Guide

The event trigger is called as a POST event (after the action item, action request, or
action baseline operation completes) and issues a command to promote the item, request
or baseline to the stage associated with the new lifecycle state.

NOTE Because the event trigger is a POST event, if the promotion fails for any reason
the action will still succeed—it will not be atomic. You will need to manually determine
what caused the failure.

Prior to Dimensions CM 12.1, only two event triggers were supported, namely:
 One customer supplied.
 One Serena supplied. This, however, is used by the Serena Mover integration and
Serena Release Control (formerly called Application Release Manager (ARM)).

Starting with Dimensions CM 12.1, the event mechanism now supports an unlimited
number of event libraries.

Implementation of Action Driven Promotion Event

Triggers

Event Mechanism
Prior to Dimensions CM 12.1, the Dimensions CM server runtime loaded two libraries:
libpcmsu.dll and libpcmsu2.dll on Windows and libpcmsu.so and libpcmsu2.so
on UNIX. The process address of the function userSuppliedFunction was then obtained
from the first DLL and the address of the function userSuppliedFunction2 was obtained
from the second DLL. When an operation occurred. it was these functions that were called
one after the other.

However, this mechanism only offered support for two event triggers to be called and with
automatic promotion, ARM, and Mover this would not be sufficient.

Starting with Dimensions CM 12.1, all DLLs in the Dimensions CM server lib/prog folder
are enumerated with the name libpcmsu*. All DLLs found are loaded together with the

164 Serena® Dimensions® CM 12.2.1

 Implementation of Action Driven Promotion Event Triggers

loading of the process address of a function called userSuppliedFunction. When an

event trigger needs to be called, Dimensions CM calls, in order, all the
userSuppliedFunctions that were successfully loaded.

For backwards compatibility with respect to the libpcmsu2 library, Dimensions CM first
attempts to get the process address for the function userSuppliedFunction, but if that
fails it gets the process address of userSuppliedFunction2 instead.

The New Event

Starting with Dimensions CM 12.1, a new event is be supplied in a DLL called
libpcmsu1.dll on Windows and libpcmsu1.so on UNIX. It interceptS POST-ACTION
events and performs the following pseudo-logic:

Check if the object being actioned is going to a state that has been mapped to a stage.
If the state is not mapped to a stage
return from the event code
If the state is mapped to a stage
{
If the object being actioned is not an item revision
Issue a promotion/demotion command for the object to the right stage in the
current project
else
{
Find all the projects/streams containing the item revision
For each project/stream
{
If the Project/Stream is not using local stages or the Project/stream is the
current one
issue a promotion/demotion command for the item revision to the right stage in
that project/stream
}
}
}

Developer's Reference 165

Chapter 6 Action Driven Promotion Event Triggers

166 Serena® Dimensions® CM 12.2.1

Part 3
Java API

Part 3: Java API contains the following chapters:

dmclient 169

Developer's Reference 167

Part 3 Java API

168 Serena® Dimensions® CM 12.2.1

Chapter 7
dmclient

Introduction 170
Using dmclient 171
Javadoc 173
Examples 173

Developer's Reference 169

Chapter 7 dmclient

Introduction
The dmclient Java API provides full, programmatic access to the features of Serena®
Dimensions® CM. dmclient allows users to create and manipulate versioning, change
management, and process modeling data while under the control of the permissions of
Dimensions CM and the change management rules framework.

The table below highlights the important interfaces and classes that a consumer of the
API is likely to make frequent use of. Examples of their use can be found in examples
located in the Dimensions CM installation (see "Examples" on page 173).

Interface
Name /Class Description
DimensionsArObject Interface Represents a Dimensions CM
business object that has attributes
and relationships to other business
objects.
DimensionsConnectionManager Class Entry point to the API for obtaining
an instance of the
DimensionsConnection interface.
DimensionsConnectionManager Interface Represents a connection to a
Dimensions CM server. Provides
access to an instance of the
DimensionsObjectFactory
interface.
DimensionsDatabase Interface Represents the base database to
which the current connection
pertains. Provides access to
collections of key Dimensions CM
business objects such as products
and attribute definitions.
DimensionsLcObject Interface Represents a Dimensions CM
business object that has a lifecycle.
DimensionsObjectFactory Interface Provides access to key
Dimensions CM business objects
such as the base database and the
current user.

dmclient has the following main features:

 Multiple Connections
Dimensions CM clients can maintain multiple, concurrent connections to disparate
Dimensions databases. Serena recommends that Dimensions CM clients do not
establish multiple, concurrent connections to a single Dimensions CM database.
 Multithreaded Access
Dimensions CM clients can access the Java API from multiple concurrent threads. No
upper limit is imposed on the number of threads that may access the API
concurrently.
 Caching
Dimensions CM objects are represented as Java objects; references to these objects
may be cached by a client. However, objects are not automatically updated when the

170 Serena® Dimensions® CM 12.2.1

 Using dmclient

underlying data changes. Therefore, clients should expect a runtime exception to be

thrown if they attempt to call a business method on a cached object that no longer
exists in the database.
 Querying the Database
Ad-hoc SQL querying is not supported. The Java objects that represent Dimensions
objects make use of a key-value system of attributes for storing their properties.
These properties are cached in the client's memory. The getAttribute() method is
used to read a property from the cache, and the queryAttribute() method is used
to read a property from the database.
In addition to properties, a Dimensions CM object may have related Dimensions CM
objects, which are also cached in the client's memory. The getParentXXX() and
getChildXXX() methods on an object are used to read related objects from the
cache. The queryParentXXX() and queryChildXXX() methods are used to read
related objects from the database.
 Networking
No restrictions are placed on Dimensions CM clients when they access a
Dimensions CM database locally, over a LAN, or over a WAN. Clients should expect
API performance over a LAN to be better than over a WAN.
 Exceptions
The majority of API methods do not throw checked exceptions. If a method can throw
an unchecked exception, it is noted in the method's Javadoc.
 Connection Durability
Persistent connection loss is only likely to occur if either the server is down or if the
physical connection between client and server has been broken. In those
circumstances, either a DimensionsNetworkException will be thrown or you will get
unexpected results from API methods. In this case, to be absolutely sure the server is
unavailable, consumers of the API should call
DimensionsConnection.getConnection(true), which will cause dmclient to ping
the server. If it returns anything other than
DimensionsConnection.STATE_CONNECTED, either the server is unavailable or the
session has expired, so your code should behave accordingly.
 Compatibility
dmclient is compatible with JDK 1.4.2 and later and all Dimensions CM supported
platforms.

Using dmclient
jar files To use dmclient, include the following jar files in your runtime classpath:
 dmclient.jar
 darius.jar
 dmnet.jar
 dmfile.jar
 commons-logging.jar

Developer's Reference 171

Chapter 7 dmclient

Windows example java -cp %DM_ROOT%\java_api\lib\dmclient.jar

%DM_ROOT%\java_api\lib\darius.jar
%DM_ROOT%\java_api\lib\dmnet.jar
%DM_ROOT%\java_api\lib\dmfile.jar
%DM_ROOT%\java_api\lib\commons-logging-api.jar mypackage.MyClient

UNIX example java -cp ${DM_ROOT}/java_api/lib/dmclient.jar

${DM_ROOT}/java_api/lib/darius.jar
${DM_ROOT}/java_api/lib/dmnet.jar
${DM_ROOT}/java_api/lib/dmfile.jar
${DM_ROOT}/java_api/lib/commons-logging-api.jar mypackage.MyClient

Entry Point to dmclient

The entry point to dmclient is

com.serena.dmclient.api.DimensionsConnectionManager

This point provides access to a

com.serena.dmclient.api.DimensionsConnection

object and from there to a

com.serena.dmclient.api.DimensionsObjectFactory

interface, which provides access to the top level Dimensions CM objects.

Getting Started
To get started, include the following lines at the start of a Java program:
 import com.serena.dmclient.api.
 import com.serena.dmclient.collections.
 import com.serena.dmclient.objects.

TIP To begin you only need access to the first package listed above.

Time Format Strings in Java-API

If you use the JAVA API to search for Dimensions CM objects with an Action date greater
than a specified date, a time format string value needs to be passed for the filter.

For example, to search for requests with an action date greater than a specified date, you
would have a code like:

172 Serena® Dimensions® CM 12.2.1

 Javadoc

lastCheck = Calendar.getInstance().getTime();
filter.criteria().add(new
Filter.Criterion(SystemAttributes.LAST_ACTIONED_DATE, lastCheck,
Filter.Criterion.GREATER_EQUAL));
List<Request> releaseRequests =
conn.getObjectFactory().getBaseDatabase().getAllRequests(filter);

The time format string you need to supply needs to be the same as returned by the
query:
 For non-Oracle databases this is "DD-MON-YYYY HH24:MI:SS", where the three letter
month name is one of "JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG",
"SEP", "OCT", "NOV", "DEC"—for example, "31-AUG-2008 23:59:59". For most
system date attributes, this should be in the timezone of the machine where the
dmappsrv is; excepting the revised date, which is in UTC.
 For Oracle databases with English or American NLS settings, the situation is much the
same (except the Oracle server machine's timezone is used instead of the dmappsrv
machine's—this timezone is usually the same, but is a peculiarity of the fact that date
translation is done by the database for Oracle, and by the server for other RDBMS).
 For Oracle databases with non-English/American NLS settings, the situation should
also be the same, but you may find that for system date attributes the date string
needs to be in locale-specific "DD-MON-YYYY HH24:MI:SS" format (that is, with the
abbreviated month names not being English).

Javadoc
Javadoc is the industry standard for documenting Java classes. The Javadoc for dmclient
provides full documentation about all the packages, interfaces, and classes, and can be
found at the following locations:

Windows %DM_ROOT%\java_api\docs\api\index.html

UNIX ${DM_ROOT}/java_api/docs/api/index.html

Examples
Examples of the important interfaces and classes that a consumer of the API is likely to
make frequent use of are located in the Dimensions CM installation as follows:

Windows %DM_ROOT%\java_api\examples

UNIX ${DM_ROOT}/java_api/examples

NOTE You can also use the Dimensions CM CruiseControl plug-in with the
Dimensions CM Ant task to implement a continuous integration build based on changes in
a Dimensions CM project. For more details, see Part 5 "Integrating Dimensions CM with
Build Management Tools" in the Dimensions CM Build Tools User’s Guide.

Developer's Reference 173

Chapter 7 dmclient

174 Serena® Dimensions® CM 12.2.1

Part 4
The Dimensions CM Templating
Language

Part 4: Scripts and Templates contains the following chapters:

The Templating Language and Processor 177

Build Templates 233
Openmake Templates 261
Remote Job Execution Templates 267
Deployment Area Scripts 277

Developer's Reference 175

Part 4 The Dimensions CM Templating Language

176 Serena® Dimensions® CM 12.2.1

Chapter 8
The Templating Language and
Processor

Introduction 178
About Templates 178
Directives 180
Special Directives 191
General Predefined Symbols 191
Remote Job Execution Predefined Symbols 196
Dimensions Build Standard Symbols 196
Dimensions Build User-Defined Optional Symbols 200
Dimensions for z/OS Predefined Symbols 204
Template Expansion and Scripts 205
Complex Symbol References 208
Template Inline Functions 208
Testing Templates 213
Adding Template Variables to the Dimensions Configuration File 215
Extending the Template Processor with User Written Functions 217
The Template Processor Interface 229
Enhancements To Dimensions Command Processing To Supported Structured Information
Return (SIR) 230

Developer's Reference 177

Chapter 8 The Templating Language and Processor

Introduction
A template is a customizable text file containing variables and control words. In Serena®
Dimensions® CM, templates are used to execute builds, execute general commands
through remote job execution, control deployments, and to construct the body of e-mail
messages used for notifications.

Dimensions CM supports a common templating language and processor across Windows,

UNIX, Linux, and z/OS (both USS and MVS). The templating language enables you to
customize the processing of templates on all Dimensions CM nodes.

A stand-alone utility for testing templates enables you to check the behavior of your
templates, for details see page 213.

This chapter describes the templating language and processor. For information about
writing different types of templates see the following chapters:
 Build templates on page 233.
 Openmake build templates on page 261.
 Remote execution templates on page 267.
 Deployment area scripts on page 277.
 E-mail templates, see the Process Modeling User’s Guide.

About Templates
Templates are organized into records. Records starting with a ')' in column one are
directives. Symbols are used to name values that are either a single value or an array of
one-dimensional tables. Symbol references are expressed by '%variable.' where the
variable is looked up and substituted. A template is inspected record by record and
symbols are replaced and written to the output stream. Dimensions CM constructs a
symbol table using the information passed from the commands and environment
variables. For each single value a scalar is created, and for each multiple value an array
is created. The symbol table represents the context in which template substitution
occurs.

Variables can come from the following sources:

 The )SET directive in templates.
 Build configurations.
 The PARAMETERS qualifier in the REXEC command.

178 Serena® Dimensions® CM 12.2.1

 About Templates

Default Template Characters

The template uses the following default characters:

Character Usage
) Directive
% Start substitution
. End substitution
( Used in complex references to control nesting. For example:
) %(symt(10)).
references element 11 of the symbol table symt. For more details about
complex symbol references, see page 208.
: Used to reference symbol tables nested inside other symbol tables. For
example:
%(symt(10):fred)%
references the symbol fred nested in element 11 of the symbol table
symt. For more details about complex symbol references, see page 208.

NOTE You can use the )ATTR directive to change the default characters used by the
templater, for details see page 180.

Example Input:

)SET name=World
Hello %name.

Output:

Hello World

Example Input:

)SET A=B
This line uses %A.
)IF %A.=B
The value of A is B.
)ELSE
The value of A is not B.
)ENDIF

Output:

This line uses B.

The value of A is B.

Developer's Reference 179

Chapter 8 The Templating Language and Processor

Directives
Directives are commands that are processed by the templater. The templating language
includes the directives listed below.

)ADJUST
Description Adjusts the value of the integer <variable> by adding the integer <value>. You can
use this directive to control loops.

Syntax )ADJUST <variable> <value>

where:
 <variable> specifies a variable you define with the directive )SET (see page 188).
 <value> specifies an integer value that you use to adjust <variable>.

Example Input:

)SET TEST=205
)ADJUST TEST -10
The value of TEST is %TEST.

Output:

The value of TEST is 195

)ATTR
Description Changes the default characters used by the template. You must specify a list of exactly
six characters in the following order:
 Value #1: Directive character
 Value #2: Start substitution character
 Value #3: End substitution character
 Values #4, #5, and #6: Complex references characters

Syntax )ATTR <value1,value2,value3,value4,value5,value6>

Example To change the directive character to hash '#':

)ATTR #%.():

To change the variable references to look like %var%:

)ATTR )%%():

To change back to the defaults:

)ATTR )%.():

NOTE If you use the )IM directive to embed a file inside a template you can use )ATTR
to change that file's defaults. This does not change the default settings of the parent
template.

180 Serena® Dimensions® CM 12.2.1

 Directives

)CALL
See "Additional Template Directives" on page 217.

)CALLBACK
Description Enables you to inject data directly into a template using a programming API.

Syntax )CALLBACK <ref> <NT>

where:
 <ref> specifies parameters that are delivered to the user's )CALLBACK function.
 <NT> specifies that the data provided by the )CALLBACK function is treated as
literal. If you do not specify <NT> the data provided by the )CALLBACK function is
subject to further expansion by the templater.

Example See the example for DMEXECENV on page 200.

)CM
Description Enables you to insert comments into a template.

Syntax )CM <text-string>

where:

<text-string> is a textual comment.

Example )CM
)CM The following is a single line command!
)CM

)DUMP
Description A dump utility to assist in debugging and writing templates. it is available is various
guises as explained below.

Syntax )DUMP [comment [colno]]

 The form

)DUMP
dumps the symbol table as a series of I level messages.
 The form

)DUMP comment
puts the symbol table into the output file from templating using 'comment' as a start
of line comment operator.
 The form

)DUMP comment colno

Developer's Reference 181

Chapter 8 The Templating Language and Processor

interprets 'colno' as a number (which must be positive) and truncates all output in
this form to the specified column number.
 The forms

)DUMP )SET [ colno]

)DUMP SET [ colno]
put out the data as a series of )SET and )VECTOR commands suitable for pasting into
a document.
 The form

)DUMP "str" [ colno]

where "str" contains the string )SET, takes the portion of the string up to the )SET
and prefixes each )SET with this comment. This means you can have both )SET and
comment them out in one operation.

Example )DUMP "//* )SET" 70

outputs //* in front of each )SET or )VECTOR and also truncates the line at 70.

)ELSE
Description Switches inclusion on or off in a conditional block.

Syntax )ELSE

Example See the examples for )ENDIF on page 182.

)ENDIF
Description Ends an )IF conditional block.

Syntax )ENDIF

Operators:
 =
 EQ (equals)
 NE (not equal)
 !=
 STRCONTAINS

Example Input:

)SET n=1
%n.
)IF %n. = 1
echo Is one
)ELSE
echo Is not one
)ENDIF
)ADJUST n 1
%n.

182 Serena® Dimensions® CM 12.2.1

 Directives

)IF %n. = 1
echo Is one
)ELSE
echo Is not one
)ENDIF

Output:

1
Is one
2
Is not one

Example The following example controls when compile options are used:

)SET debug=Y
%debug.
)IF %debug.=Y
<compile options>
)ENDIF

Example The following is an example of echoing strings:

Input:

)IF Nothing STRCONTAINS oth

echo this line is echoed
)ENDIF

Output:

echo this line is echoed

Example The following is another example of echoing strings:

Input:

)SET A=
)IF %A. != ""
This line is actioned
)ENDIF
)IF %A. !=
This line IS actioned
)ENDIF
)IF "%A." != " "
This line is also actioned
)ENDIF

Output:

This line is actioned

This line is also actioned

)ENDEXPAND
Description Ends template expansion started with )EXPAND.

Developer's Reference 183

Chapter 8 The Templating Language and Processor

Syntax )ENDEXPAND

For more details see page 184.

)ENDR
Description Ends a repeat block

Syntax )ENDR

Example See the examples for )REP on page 186.

)ENDSCRIPT
See "Additional Template Directives" on page 217.

)EXPAND
Description Expands a template. You can define )EXPAND with or without a script:
 )EXPAND without a script
In a simple )EXPAND where you do not specify a script, the text block between
)EXPAND and )ENDEXPAND is expanded by the template processor:

)EXPAND
<text>
<text> Expanded by the template processor
<text>
)ENDEXPAND
For example, you can use )EXPAND to specify an action that might be confused by
the special template characters, or to restrict the sections of a template that are
expanded.
 )EXPAND with a script
When you specify a script, the text block between )EXPAND and )ENDEXPAND is
processed by the named script processor, and the result is embedded into the
template at the point where you insert this directive.
Syntax:

)EXPAND <script> <parameters>

where:
• <script> specifies a processor that will be used to process the script.
• <parameters> specifies parameters for the script that you specified above.

NOTE This directive is implemented by invoking the system command on the specified
file. On z/OS this will cause an address space to be created, and this will exist only for
the duration of the script invocation. That operation is expensive and should be avoided if
possible.

For more details about using )EXPAND to expand templates, see page 205.

184 Serena® Dimensions® CM 12.2.1

 Directives

)IF
Description Starts an )IF conditional block.

Syntax )IF <expression>

where:

<expression> is the value whose existence you are checking.

Example See the examples for )ENDIF on page 182.

)IFDEF
Description Starts a conditional block based on a symbol's existence.

Syntax )IFDEF <symbol>

where <symbol> specifies the symbol whose existence you are checking.

Example )IFDEF debug

The symbol debug is defined
)ENDIF

)IFNDEF
Description Starts a conditional block based on a symbol's non-existence.

Syntax )IFNDEF <symbol>

where <symbol> specifies the symbol whose non-existence you are checking.

Example )IFNDEF debug

The symbol debug is not defined
)ENDIF

)IM
Description Embeds a file into the template at the point where you insert this directive. You can also
nest )IM directives inside other )IM directives.

NOTE When you use )IM to embed a file you can use )ATTR to change that file's
defaults. This does not change the default settings of the parent template. For details see
page 180.

Syntax )IM <filespec> <NT>

where:
 <filespec> specifies the file you want to embed.
 <NT> specifies that the named template is literal text and is not a template.

Developer's Reference 185

Chapter 8 The Templating Language and Processor

Example Input (outer.tpl)

This is section 1
)SET NAME=John Doe
)IM inner.tpl
This is section 2
This is section 3
)IM inner.tpl NT
This is section 4

Input (inner.tpl)

My name is %NAME.

Output

This is section 1
My name is John Doe
This is section 2
This is section 3
My name is %NAME.
This is section 4

)LOGON
Description Log on to the specified Dimensions CM server. This logon will be active until the end of
the script.

Syntax )LOGON <user> <pwd> <host> <db> <dsn>

where:
 <user> specifies the user-id.
 <pwd> specifies the user-id’s password.
 <host> specifies the server host name.
 <db> specifies the Dimensions CM database.
 <dsn> specifies the database connection string (data source name).

)REP
Description Starts a repeat block that you can use in conjunction with array variables. The directive
repeats until it has been round all the elements in the specified array.

Syntax )REP <var1> <var2> …

Example The example below has a single array variable containing three elements.

Input:

)VECTOR dates(3)
)SET dates(0)=12th Nov 2005
)SET dates(1)=13th Nov 2005
)SET dates(2)=14th Nov 2005
)REP dates
%dates.

186 Serena® Dimensions® CM 12.2.1

 Directives

)ENDR

Output:

12th Nov 2005

13th Nov 2005
14th Nov 2005

Example The example below has two arrays each containing three elements. The second )REP
directive (chdocs) is nested inside the first (dates). The output is a list of three dates,
each containing a list of all the change documents.

Input:

)VECTOR chdocs(3)
)SET chdocs(0)=PVCS_EC_124
)SET chdocs(1)=PVCS_EC_567
)SET chdocs(2)=PVCS_EC_444
)VECTOR dates(3)
)SET dates(0)=12th Nov 2005
)SET dates(1)=13th Nov 2005
)SET dates(2)=14th Nov 2005

)REP dates
%dates.

)REP chdocs
%chdocs.

)ENDR

)ENDR

Output:

12th Nov 2005

PVCS_EC_124
PVCS_EC_567
PVCS_EC_444

13th Nov 2005

PVCS_EC_124
PVCS_EC_567
PVCS_EC_444

14th Nov 2005

PVCS_EC_124
PVCS_EC_567
PVCS_EC_444

Example The example below has two arrays each containing three elements. The array variables
are embedded inside the text. The output is three text strings, each containing a
different change document and date.

Developer's Reference 187

Chapter 8 The Templating Language and Processor

)VECTOR chdocs(3)
)SET chdocs(0)=PVCS_EC_124
)SET chdocs(1)=PVCS_EC_567
)SET chdocs(2)=PVCS_EC_444

)VECTOR dates(3)
)SET dates(0)=12th Nov 2005
)SET dates(1)=13th Nov 2005
)SET dates(2)=14th Nov 2005

)REP chdocs dates

The change doc %chdocs. is due on the %dates.

)ENDR

Output:

The change doc PVCS_EC_124 is due on the 12th Nov 2005

The change doc PVCS_EC_567 is due on the 13th Nov 2005

The change doc PVCS_EC_444 is due on the 14th Nov 2005

)SCRIPT
See "Additional Template Directives" on page 217.

)SET
Description Creates or changes a value in the symbol table.

Syntax )SET var = value

where var can be a scalar variable name or a reference to an array element when in the
form var[n].

Example )SET name=World

Hello %name.

)SETL
Description Creates a value in lowercase, or changes an existing value to lowercase.

Syntax )SETL var = <value>

where var can be a scalar variable name or a reference to an array element when in the
form var[n].

Example Input:

)SETL name = JOHN

%name.

188 Serena® Dimensions® CM 12.2.1

 Directives

Output:

john

)SET_PATH
Description Treats <value> as a path specification in UNIX format. This value is converted to the
equivalent path specification in the local operating-system format, for example:

/a/b/c

becomes

\a\b\c

if the local operating-system is Windows, or

A.B(C)

if the local operating-system is an MVS system.

Syntax SET_PATH <variable> <value>

where:
 <variable> specifies the variable to which you are specifying a path
specification.
 <value> specifies the path specification.

)SET_PATH_MVS
Description Treats <value> as a path specification in UNIX format. This value is converted to the
equivalent path specification in MVS format, for example:

/a/b/c

becomes

A.B(C)

Syntax SET_PATH_MVS <variable> <value>

where:
 <variable> specifies the variable to which you are specifying a path
specification.
 <value> specifies the path specification.

)SET_PATH_NT
Description Treats <value> as a path specification in UNIX format. This value is converted to the
equivalent path specification in Windows format, for example:

/a/b/c

Developer's Reference 189

Chapter 8 The Templating Language and Processor

becomes

\a\b\c

Syntax SET_PATH_NTS <variable> <value>

where:
 <variable> specifies the variable to which you are specifying a path
specification.
 <value> specifies the path specification.

)SET_PATH_UNIX
Description Treats <value> as a path specification in Unix format, this value is converted to the
equivalent path specification in UNIX format (noop), for example:

/a/b/c

becomes

/a/b/c

Syntax SET_PATH_UNIX <variable> <value>

where:
 <variable> specifies the variable to which you are specifying a path
specification.
 <value> specifies the path specification.

)SETU
Description Creates a value in uppercase, or changes an existing value to uppercase.

Syntax )SETU var = value

where var can be a scalar variable name or a reference to an array element when in the
form var[n].

Example Input:

)SETU name = john

%name.

Output:

JOHN

)SLICE
Description Enables you to send arbitrary quantities of data to a program from a single string
variable. The directive creates an array in var2 that is long enough to hold all the
information in var1 in 32 byte chunks. var1 must already exist.

190 Serena® Dimensions® CM 12.2.1

 Special Directives

Syntax )SLICE var1 var2

Example Input:

)SET FOOTPRNT=THIS IS A VERY LONG FOOTPRINT INFORMATIONAL AREA

)SLICE FOOTPRNT F
)REP F
CL32'%F.'
)ENDR

Output:

CL32'THIS IS A VERY LONG FOOTPRINT IN'

CL32'FORMATIONAL AREA'

)VECTOR
Description Creates an array of elements.

Syntax )VECTOR var(n)

where var defines an array variable with n occurrences.

Example )VECTOR dates(3)

)SET dates(0)=12th Nov 2005
)SET dates(1)=13th Nov 2005
)SET dates(2)=14th Nov 2005

Special Directives
The directives listed below enable a template processing step to pass data to a later
processing step:
 )SAVE
 )LOAD
 )DELETE
 )IFGROUPDEF
 )IFGROUPNDEF

See "pBem Template Processing—Passing Data Between Steps" on page 221 for details.

General Predefined Symbols

The templating language includes the general predefined symbols listed below.

Developer's Reference 191

Chapter 8 The Templating Language and Processor

%DMCOMBINEOUTERR.
Description Is similar to %DMSAVESTDERR. (see page 194) and %DMSAVESTDOUT. (see page 194)
but combines the output and the errors into one file and places them in the variable
%DMOSTDOUT..

You can set this option when:

 Running the REXEC command with the /PARAMETERS qualifier:

REXEC /PARAMETERS %DMCOMBINEOUTERR.=Y

 Running the templating testing program with the -g flag:

template_test -g c
 Setting up build configurations.
 Writing a template, for example add the line:
)SET DMCOMBINEOUTERR=Y

Input or output Input

%DMCURRENTDIRECTORY.
Description The current directory.

Input or output Input

%DMCYGWIN.
Description This is for Windows only. It is the current directory in Cygwin (Windows UNIX utilities)
style, that is, '.'.

Input or output Input

%DMDAY.
Description Two digit string representing the day in the month when this template process is started.

Input or output Input

Example 07s

%DMFOLDERSEPARATOR.
Description The folder separator for the operating system being used. This will be '/' (forward slash)
for UNIX and '\' (backward slash) for Windows.

Input or output Input

%DMHOUR.
Description Two digit string representing the hour when this template process is started. Uses GMT
in a 24-hour format.

192 Serena® Dimensions® CM 12.2.1

 General Predefined Symbols

Input or output Input

Example 12

%DMMICROSEC.
Description Six digit string representing the microsecond when this template process is started.

Input or output Input

Example 01348

%DMMINUTE.
Description Two digit string representing the minute when this template process is started.

Input or output Input

Example 34

%DMMONTH.
Description Two digit string representing the month in the year when this template process is
started.

Input or output Input

Example 12

%DMOSTDERR.
Description Reveals the filename containing the errors of the template execution. This file exists on
the machine where the script is executing.

Input or output Output

%DMOSTDOUT.
Description Reveals the filename containing the output of the template execution. This file exists on
the machine where the script is executing.

Input or output Output

%DMOSTYPE.
Description The operating system being used. This will be 'UNIX' for UNIX and 'Windows' for
Windows.

Input or output Input

Developer's Reference 193

Chapter 8 The Templating Language and Processor

%DMOXTMPLT.
Description Reveals the filename containing the expanded template. This file exists on the machine
where the script is executing.

Input or output Output

%DMPASSWORD.
Description Set to the value of the node password specified for the work or deployment area. This
password can be different to the one you used to log on with.

Input or output Input

%DMPATHSEPARATOR.
Description The path separator for the operating system being used. This will be ':' (colon) for UNIX
and ';' (semi-colon) for Windows.

Input or output Input

%DMSAVESTDERR.
Description Requests that the errors from the template execution are saved. The filename where the
errors are saved is put into the variable DMOSTDERR.

You can set this option when:

 Running the REXEC command with the /PARAMETERS qualifier:

REXEC /PARAMETERS DMSAVESTDERR=Y

 Running the templating testing program with the -g flag:

template_test -g e
 Setting up build configurations.
 Writing a template, for example add the line:
)SET DMSAVESTDERR=Y

Input or output Input

%DMSAVESTDOUT.
Description Requests that the output of the template execution is saved. The filename where the
output is saved is put into the variable DMOSTDOUT.

You can set this option when:

 Running the REXEC command with the /PARAMETERS qualifier:

REXEC /PARAMETERS DMSAVESTDOUT=Y

194 Serena® Dimensions® CM 12.2.1

 General Predefined Symbols

 Running the templating testing program with the -g flag:

template_test -g s
 Setting up build configurations.
 Writing a template, for example add the line:
)SET DMSAVESTDOUT=Y

Input or output Input

%DMSECOND.
Description Two digit string representing the second when this template process is started.

Input or output Input

Example 24

%DMUNIQUE.
Description An eight character encoding of the date and time to within one second in the century,
formatted to conform to MVS member naming standards and lexically ordered by time.

Input or output Input

Example Input:

//INPUT DD DSN=BLD.%DMUNIQUE..COBOL,DISP=SHR

Output:

//INPUT DD DSN=BLD.A3664E3.COBOL,DISP=SHR

Input or output Input

%DMUSER.
Description Set to the value of the node user ID specified for the work or deployment area. This user
ID can be different to the one you used to log on with.

Input or output Input

%DMUSERU.
Description Same as for DMUSER, but truncated to seven characters and converted to upper case.

Input or output Input

%DMYEAR.
Description Four digit string representing the year when this template process is started.

Developer's Reference 195

Chapter 8 The Templating Language and Processor

Input or output Input

Example 2005

Remote Job Execution Predefined Symbols

The templating language includes the remote job execution predefined symbols listed
below.

%DMCERTIFICATE.
Specifies a one-time certificate used to reconnect to Dimensions CM to perform post-
build processing such as updating a job status or collecting build outputs.

%DMJOBID.
Specifies the remote job key.

Dimensions Build Standard Symbols

The templating language includes the Dimensions Build standard (permanently
available) symbols described below. You can use these symbols in a build template or
specify them in the Build Options section of a build configuration. For more details about
Dimensions Build and the Primary Build Execution Monitor (pBem) see the Dimensions
CM Build Tools User’s Guide.

NOTE There is also a set of optional Dimensions Build symbols described in "Dimensions
Build User-Defined Optional Symbols" on page 200. To be utilized, these optional
symbols must be explicitly added as Dimensions Build options, that is, they are not
defined by default.

%DMPATH.
Description DMPATH tells the build step template where the source is to be found. It always contains
at least one element, namely, the disk location where the build is being performed. This
disk location element will always be the first element in the array.

For deployment area builds, further elements of the DMPATH array are formed by
examining all deployment areas for the build configuration that are:
 firstly, located on the same node as the area being built, and
 secondly, for which the GLC sequence is higher than or equal to that of the area
being built.

On MVS systems, this is the stem of the area with // preceding each entry.

For distributed systems, it is an absolute path to the area.

196 Serena® Dimensions® CM 12.2.1

 Dimensions Build Standard Symbols

If the area being built is a work area, and if the DM_SP_START_STAGE symbol is set to a
GLC identifier, the first array entry will be the location of the work area and the
remainder of the DMPATH variable is constructed as though the work area were a
deployment area at the specified stage.

NOTE On MVS platforms the data set stem does not contain low level qualifiers, which
are added by the template.

MVS format:

//ACCOUNT.TEST
//ACCOUNT.SYSTEM
//ACCOUNT.PRODUCTION

Distributed format:

NOTE There is usually only one useful row in Windows and UNIX distributed
environments, namely, the first.

 Windows:
c:\account\test
c:\account\system
d:\account\production
 UNIX:

/account/test
/account/system
/account/production

z/OS Example Input:

)VECTOR DMPATH(3)
)SET DMPATH(0)=//BUILD.LEVEL1 This mimics the set up done by
)SET DMPATH(1)=//BUILD.LEVEL2 the pBem.
)SET DMPATH(2)=//BUILD.LEVEL3

)SET FIRST=SYSIN
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+d,%DMPATH)
//%FIRST. DD DSN=%DMPATH..COBOL,DISP=SHR
)SET FIRST=
)ENDR

Output:

//SYSIN DD DSN=BUILD.LEVEL1.COBOL,DISP=SHR
// DD DSN=BUILD.LEVEL2.COBOL,DISP=SHR
// DD DSN=BUILD.LEVEL3.COBOL,DISP=SHR

Developer's Reference 197

Chapter 8 The Templating Language and Processor

Distributed Input:
Example
)VECTOR DMPATH(3)
)SET DMPATH(0)=c:\stu\my-area This mimics the set up done by
)SET DMPATH(1)=d:\build\system-test the pBem.
)SET DMPATH(2)=e:\build\production

)SET INCLUDES=

)REP DMPATH
)SET INCLUDES=%INCLUDES. -I %DMPATH.
)ENDR

compile foo.c %INCLUDES.

Output:

compile foo.c -I c:\stu\my-area -I d:\build\system-test -I

e:\build\production

%DMINPUT.
Description Specifies an array of sources expressed as relative filenames, where each row names an
input file. Each file is categorized according to the filename extension (on distributed
platforms) or the low level qualifier (on mainframe platforms). The file type decides
where the input goes in the template. See also "MDHDSN" on page 208.

NOTE If a template only reads in one file the category is irrelevant as there is only one
place where the information can go.

Distributed  prog1.c
examples
 account\account1.c (Windows)
 account/account1.c (UNIX)

MVS examples  COBOL(PROG1)

 ACCOUNT.COBOL(ACCT1)

%DMTARGET.
Description Specifies an array of relative filenames that are the outputs from a build. Each file is
categorized according to the filename extension (on distributed platforms) or the low
level qualifier (on mainframe platforms).

Distributed  prog1.c
examples
 account\account1.c (Windows)
 account/account1.c (UNIX)

MVS examples  COBOL(PROG1)

 ACCOUNT.COBOL(ACCT1)

198 Serena® Dimensions® CM 12.2.1

 Dimensions Build Standard Symbols

%DMSTEP.
This is constructed by Dimensions Build. It specifies the sequence number of the current
step in the build process and can be used in a build template to signal to the pBem the
end of a step. For more details about Dimensions Build see the Dimensions CM Build
Tools User’s Guide.

%DMRUNMODE.
Description This is set by pBem. It is a read only symbol that conveys the actual runmode to the
template. It can be used to trigger asynchronous specific actions.

Example )IF %DMRUNMODE. = ASYNC

...
)ENDIF

%DMUSER. and %DMPASS.

Set these symbols from a build template to change the user ID that a build step runs as.
This is different to the DMUSER and DMPASSWORD symbols on the original REXEC request
that started the pBem.

%DMSERVER.
This is set by the Dimensions Build server. It is a string such as <MACHINE>:<PORT> that
can be used as a network address to locate the build server when sending messages. It
is used when messages are sent directly to the build server. To send messages back to
the controlling pBem use the variables DMPBEMNODE and DMPBEMPORT (see below).

%DMPBEMNODE. and %DMPBEMPORT.

This is set by pBem. It specifies the network address and port of the controlling pBem
process. Asynchronous tasks need to send messages back to this address to alert the
pBem of their status, but this is done automatically for MVS by SBEM.

%DMTOKEN.
This is constructed by the Dimensions Build server. It is an abstract build token that is
used internally by the build server to create a Bill of Materials report (BOM).

%DMJOBID.
This is constructed by the Dimensions listener. It is an abstract symbol generated by the
REXEC mechanism to track jobs. In Dimensions 9.x, the RSTAT and RLIST commands
used this symbol as the primary build tracking mechanism. This symbol has been
retained for backwards compatibility though the Dimensions Build server now manages
the build history.

Developer's Reference 199

Chapter 8 The Templating Language and Processor

%DMXFERSOURCE.
Set this symbol to ’Y’ to transfer sources automatically to work areas. By default
Dimensions, does not transfer sources to work areas.

Dimensions Build User-Defined Optional Symbols

The templating language includes the Dimensions Build optional (not defined by default)
symbols described below. You can use these symbols in a build template or specify them
in the Build Options section of a build configuration. For more details about Dimensions
Build and the Primary Build Execution Monitor (pBem) see the Dimensions CM Build Tools
User’s Guide.

NOTE There is also a set of standard Dimensions Build symbols described in

"Dimensions Build Standard Symbols" on page 196. These predefined symbols are
permanently available to be utilized as Dimensions Build options, that is, they are defined
by default.

DMEXECENV
Description Sets one of three modes that control the script execution environment after a template
has been expanded. It is user-defined in the template.

Mode 1 Process as an MVS batch job

In this mode the template is processed as an MVS batch job and is submitted to be run.
The script execution environment treats the template as JCL and submits it.

Syntax:

)SET DMEXECENV=JCL or )SET DMEXECENV=JES

Mode 2 Process with a shell script

In this mode the template is processed with a command, with or without arguments.

Syntax:

)SET DMEXECENV=SHELL <script>

Example:

)SET DMEXECENV=SHELL perl %%s

Mode3 Process with a different template

In this mode the expanded template is processed again by the templater using a
different template that you specify. This allows a specific template to be wrapped by
another.

Syntax:

DMEXECENV=TEMPLATE <template name>

200 Serena® Dimensions® CM 12.2.1

 Dimensions Build User-Defined Optional Symbols

Example:

In the example below the )CALLBACK directive indicates where to insert the text from
the inner template.

Input (outer.tpl):

)EXPAND
echo off
echo Building started
)CALLBACK NT
echo Building continuing

Input (inner.tpl):

)SET DMEXECENV=TEMPLATE output.tpl

echo building.....
echo building.....
echo building.....

Output:

Building started From outer.tpl

building.....
building..... From inner.tpl
building.....
Building continuing From outer.tpl

DMEXPAND
This is user-defined in the template.

If DMEXPAND is:
 Set to 'Y'
EXPAND mode is enabled, where only the parts of the template delimited by )EXPAND
and )ENDEXPAND are expanded.
 Not set to ’Y’
The template behaves as in Dimensions 9.x, where the entire template is expanded.

Dimensions Build automatically sets DMEXPAND to 'Y' by default. For examples see
"Template Expansion and Scripts" on page 205.

DMTASKNAME
Description This is used to create a message that is displayed in the Task column of the Build Monitor
Events section of the Build Job Details dialog box in Dimensions Build. You can also use
other symbols, for example, to insert program names.

Example )SET DMTASKNAME=$%DMSTEP, Compiling program %SOURCE.

Developer's Reference 201

Chapter 8 The Templating Language and Processor

DMTIMEOUT
This is set to override the time (in seconds) that the pBem waits for a step to complete
before it is marked as failed. Note that Dimensions Build also has an overall build
timeout value, which might be wait forever.

DMSTEPMODE
Description This is set to override the synchronous and asynchronous setting of a build for a given
step; usually used to ensure that certain activities are synchronous.

Values: ASYNC or SYNC

Example )SET DMSTEPMODE=SYNC

DMMAXRC
This is set in a build configuration or for doing a run to specify the highest acceptable
return code set by build, step, area, or config. It enables a template to pass back the
actual return code for information and allow certain values to be treated only as
warnings. Set this symbol to the maximum value that is considered safe for that step. If
the return code is higher than this value the pBem will not schedule dependent steps as
the step will have failed.

DMNOCACHE
This symbol is set to 'Y' for a template or build configuration to disable the caching of
some file information. It produces a slower but more accurate build for poorly defined
build configurations.

DMREBUILDALL
The default value of this symbol is ’NO’, in which case neither of the rebuild operations
described below will occur.

To initiate one of the rebuild operation described, set the symbol to the appropriate
value:
 ’YES’ or ’ALL’ to rebuild all the steps in the BRD irrespective of the stage they are in.
 ’CURRENT’ to rebuild all the targets that are physically located at the stage where
the build is occurring (the current stage). Does not automatically rebuild targets that
are higher up the lifecycle, such as at REL.

DMMUSTRUN
Define this symbol in a template or build configuration to indicate that a step is essential
and must run even if a prior dependent step has failed. Note that cleanup activities
should be done in post-build steps defined in the build configuration.

202 Serena® Dimensions® CM 12.2.1

 Dimensions Build User-Defined Optional Symbols

DMFINAL
Define this symbol for a template or build configuration to indicate that a step should run
last. Forces dependencies to be created to ensure that the step does run last. Note that
it is best practice to use a correctly configured build configuration to specify when steps
are run.

DMTTLOG
Causes detailed trace messages from the templating process to be produced, their
destination depending on the context in which they are generated. These messages can
be useful in some error situations to determine why a template failed.

Set this debug flag to 'Y' in REXEC /PARAMETERS, BLD /BUILD_OPTIONS,

BLDB /BUILD_OPTIONS, or the Dimensions CM configuration file. at the global, area, or
step level

DMALTSERVER
Enables you to change the address of the build server that is defined in the BRD file—
typically the server from where the build is launched—and specify the address of an
alternative build server.

Must be in the following format:

http://<IP address of the machine hosting the build server>:<Tomcat port number>/bws/
services/monitor
Example http://<dimensions-dev>:<8080>/bws/services/monitor

Usage scenario When you launch a build from a virtual machine, and are building on a remote node, the
address of the build server in the BRD file on the remote node may be the physical
machine hosting the virtual machine (not the actual virtual machine). You can use
DMALTSERVER to change the address to that of the virtual machine.

DM_SP_START_STAGE
Enables you to limit a search path by specifying from what stage in the Global Stage
Lifecycle (GSL) you want to start appending deployment area paths to search paths in a
BRD file. Can only contain only one value, which is the name of a stage in the GSL.

DM_BUILDER_PROGRESS_REPORTING
If you specify this symbol, any step that has a non-zero return code causes the SBEM to
issue the following message with a severity of W:

MDHSB16D112W Step <step number> Program <program> returned COND CODE = <cc>
Default: YES

Developer's Reference 203

Chapter 8 The Templating Language and Processor

Dimensions for z/OS Predefined Symbols

User ID and Account Predefined Symbols

Use the Dimensions CM symbols listed below on z/OS machines to display the security
and execution environment.

Symbol Name Usage Example

DMSYSUSR RACF user ID MERSTU1
DMSYSDIR USS home directory /u/home/merstu1
DMSYSSHL User's shell /bin/sh
DMSYSUID UID of the UNIX process (integers) 23587
DMSYSGID GID of the UNIX process (integers) 54968695

Job Sequence Number Predefined Symbols

Dimensions for z/OS maintains a sequence number that increments by one every time
you submit a template. You can use this number in the job name, or any other part of a
template, to distinguish one job from another.

To allow the sequence number to be used in restricted environment, such as an eight

character job name, there are various number formats that you can use. For example, if
you add DMSEQA to the end of a job name when the user ID is up to seven characters
long, a maximum of 36 different job names will be created.

The sequence number is made visible to the JCL tailoring skeleton through the following
predefined symbols:

Symbol Name Usage Example

DMSEQNNN Plain number, left justified, variable width. 98
DMSEQ999 Plain number, fixed width, three digits. 098
DMSEQ99 Plain number, fixed width, two digits. 98
DMSEQ9 Plain number, single digit. 8
DMSEQAAAA Alpha-numeric, variable width. 002N
DMSEQAAA Alpha-numeric, fixed width, three digits. 02N
DMSEQAA Alpha-numeric, fixed width, two digits. 2N
DMSEQA Alpha-numeric, single digit. N

Maintaining Sequence Numbers

Sequence numbers are maintained on the remote node where the template is executed
and not by the Dimensions CM server. If you execute templates on multiple machines,
each machine has its own sequence numbers. The sequence number is maintained in an
HFS file inside a directory specified in the Dimensions CM configuration symbol
DM_TPLB_SEQUENCE_PATH (see page 215).

204 Serena® Dimensions® CM 12.2.1

 Template Expansion and Scripts

Template Expansion and Scripts

In the version of the templating language released with Dimensions 9.x, the entire
template was expanded. In the current version, when you specify the symbol DMEXPAND,
only the lines between the directives )EXPAND and )ENDEXPAND are treated as template
lines, the rest being treated as literal text. For more details about using these directives
see page 184.

There are two ways that you can implement scripts in a template:
 Expansion—use a script, delimited by the directives )EXPAND and )ENDEXPAND, to
expand a specific part of a template to complete it, for example, to insert a date.
 Execution—use a script to execute an entire expanded template, for example, to
call a compiler and run the expanded template through it.

A script can be any shell scripting language, typically REXX on a mainframe, and Perl,
Python or any other command-line language on a distributed platform. Script mode
allows you to generate complex scripts and to interpret the body of the expanded section
as a command script, the output of which becomes the expanded text.

NOTE The )EXPAND directive is implemented by invoking the system command on the
specified file. On z/OS this will cause an address space to be created, and this will exist
only for the duration of the script invocation. That operation is expensive and should be
avoided if possible.

Example The example below illustrates one simple use of template expansion.

Input:

)EXPAND %%s
echo echo Hello
)ENDEXPAND

Output:
When the script runs, it outputs "echo Hello". So these three lines will be replaced by
one line containing "echo Hello". This command will execute when the template runs,
printing "hello".

Example The example below illustrates another simple use of template expansion.

Input:

)EXPAND %%s
echo Hello > c:\temp\foo.txt
)ENDEXPAND

Output:
This particular script does not output anything, the three lines simply disappearing
from the template. However, during execution, the file named (foo.txt) will get
created.

Developer's Reference 205

Chapter 8 The Templating Language and Processor

Example The mainframe example below demonstrates the power of an external scripting
language. The template does the following:
 Creates a temporary file, referred to by '%%s', containing the script delimited by
)EXPAND and )ENDEXPAND.
 Executes the temporary file with the REXX interpreter. REXX outputs the string 'job
submitted on <date>'. This line then becomes part of the template.

Input:

//*
)EXPAND %%s
/*REXX*/
Say "//* job submitted on" date()
exit 0
)ENDEXPAND
)EXPAND
//*

Output:

job submitted on 12th December 2005

NOTE Two percent characters '%%' are required if '%' is being used as a special
character. The role of '%s' is to allow a command line to be generated where the script
name is not necessarily the last parameter.

Example The mainframe example below shows how to pass variables into and out of an executed
script, where REXX is used to set a template variable called MYVAR.

Input:

//*
This )EXPAND starts the block that ends with )ENDEXPAND.
)EXPAND %%s
As it is followed by a script, this expansion is in script mode.
/*REXX*/
This )EXPAND forces the template to treat the output from REXX as
Say ")EXPAND" template lines (the default for an expanded script is not to expand).
REXX outputs this line, which is interpreted by the
Say ")SET MYVAR=" date()
templater, and causes the variable MYVAR to be set.

Say "//* job submitted on" date()

)ENDEXPAND
)EXPAND This )EXPAND forces the variable MYVAR to be expanded.

//*
//* %MYVAR.
//*

Output:

//*
//* job submitted on 8 Dec 2005
//*
//* 8 Dec 2005
//*

206 Serena® Dimensions® CM 12.2.1

 Template Expansion and Scripts

Example The Perl distributed platform example below is a template with a nested Perl script that
splits out the PATH environment variable into a template array.

Input:

)VECTOR MYPATH(20)
)EXPAND perl
This )EXPAND starts the block that ends with )ENDEXPAND. As it
%%s
is followed by a script, this expansion is in script mode.
This )EXPAND forces the template to treat the
print ")EXPAND\n"; output from Perl as template lines.
@dirs = split(/:/,$ENV{'PATH'});
$i=0;
foreach $dir (@dirs)
{
print ")SET MYPATH($i) = $dir\n";
$i=$i+1;
}
)ENDEXPAND
)EXPAND This )EXPAND forces the variable 'MYPATH' to be expanded.
//*
//* First element = %(MYPATH(0)).
//* Second element= %(MYPATH(1)).
//*
//* This is the complete array:
//*
)REP MYPATH
===> %MYPATH.
)ENDR
//*
//* End
//*

Output:

//*
//* First element = /cygdrive/c/stu/exec
//* Second element= /cygdrive/c/WINDOWS/system32
//*
//* This is the complete array:
//*
===> /cygdrive/c/stu/exec
===> /cygdrive/c/WINDOWS/system32
===> /cygdrive/c/WINDOWS
===> /cygdrive/c/WINDOWS/System32/Wbem
===> /cygdrive/c/Oracle/jre/1.4.2/bin/client
===> /cygdrive/c/Oracle/jre/1.4.2/bin
===> /cygdrive/c/Oracle/bin
===> /cygdrive/c/unix_utils
===> /cygdrive/c/jakarta-ant-1.5/bin
===> /cygdrive/c/j2sdk1.4.2_10/bin
===> /cygdrive/c/Serena/Dimensions/10.1/prog
===> /cygdrive/c/Program Files/Serena/License Manager
===> /usr/bin
===> /cygdrive/c/Program Files/QuickTime/QTSystem/
//*

Developer's Reference 207

Chapter 8 The Templating Language and Processor

//* End
//*

Complex Symbol References

A simple variable reference is '%var.' where % can be changed by )ATTR. A complex
symbol reference has an extra set of parentheses and is of the form '%(var).'. For
example, '%(date).' is a complex reference to the variable date. The most common
use of complex references is to access arrays in build templates.

The example below accesses the third row of the array DMPATH (arrays start at zero
therefore (2) is the third row).

%(DMPATH(2)).

In the example below the index to the array is the variable index.

%(DMPATH(index)).

NOTE When a variable appears in parentheses inside a complex reference, you do not
need to prefix the variable with %.

Template Inline Functions

Overview
Template inline functions enable you to add functionality to your templates that is not
available with the standard template directives. Inline functions are processed after
symbols are expanded but before template directives are executed. The text string
returned by an inline function is inserted into a template at the point where the function
is named.

Syntax:

_function name_(parameters)_

MDHDSN
Description MDHDSN is a C function that helps you to manage search paths in templates in JCL and in
distributed scripts.

Syntax _MDHDSN_(default-name,lookup-array,type,path-array,error_flag)_

where:
 default-name specifies a name if you do not specify 'type'.
 (Optional) lookup-array specifies an array of objects.
 (Optional) type specifies a file or object type.

208 Serena® Dimensions® CM 12.2.1

 Template Inline Functions

 (Optional) path-array specifies a search path.

 (Optional) error-flag is a single character specification that controls the issuing of
error messages:
The error-flag options are:

0 or S - (silent) Do not issue a message at all.

W Issue a warning only.
I Issue an information message only.
T Issue a trace message only.

This is only relevant to two messages, MDHPBO00003E and MDHPBO00004E.

Usage MDHDSN has four steps:

 Step one: optionally specify a 'type' and a 'lookup-array' to find a name
specified by your build configuration. For example, you can search for a 'c' type file
in a specific build array.
 Step two: if you do not specify a 'lookup-array' or 'type', or if there is no
match, the function searches for the name that you specify with 'default-name'.
 Step three: optionally specify a 'path-array' to locate an item in a search path.
Returns the full path name without the initial '//'. The template fails if a file is not
found in the search path.
 Step four: optionally specify an 'error-flag' character to control the issuing of
an error message on error detection. This allows a script to be written that will not
flag a build error in the case that the file is not present. If no error-flag' character
is specified, an 'E' level error message will be issued on the detection of an error.

Example The following directives create two arrays that are used by the inline functions in this
example:

)VECTOR DMPATH(5)
)SET DMPATH(0) = /zero/
)SET DMPATH(1) = /one/
)SET DMPATH(2) = /two/
)SET DMPATH(3) = /three/
)SET DMPATH(4) = /four/

)VECTOR DMSOURCE(3)
)SET DMSOURCE(0) = foo.c
)SET DMSOURCE(1) = bar.input
)SET DMSOURCE(2) = middle/blim.txt

The following function returns hello.c (the default) as no other parameters are
specified:

_MDHDSN_(hello.c,,,)_

The following function searches for test in the array DMSOURCE and returns the default
(hello.c) as there is no match:

_MDHDSN_(hello.c,DMSOURCE,test,)_

Developer's Reference 209

Chapter 8 The Templating Language and Processor

The following function searches for a 'c' type in the array DMSOURCE and returns
'foo.c':

_MDHDSN_(,DMSOURCE,c,)_

The following function searches for 'foo.c' in the array DMPATH and returns '/two/
foo.c':

_MDHDSN_(foo.c,,,DMPATH)_

The following function combines two operations by searching for a 'c' type in the arrays
DMSOURCE and DMPATH, and returns '/two/foo.c':

_MDHDSN_(hello.c,DMSOURCE,c,DMPATH)_

Example The following directives find an entry in the array 'S', which has a type of 'b'. This
matches f2.b. If this had not worked, it would use the default of default.txt. Then,
using this filename (f2.b), it would look for it on disk in all the locations in the array
'A', until found. If this does not work, it specifies not to issue an error message.

)VECTOR A(4)
)SET A(0)=d:\stu\c\tpl\1\
)SET A(1)=d:\stu\c\tpl\2\
)SET A(2)=d:\stu\c\tpl\3\
)SET A(3)=d:\stu\c\tpl\4\
)CM
)CM
)CM
)VECTOR S(3)
)SET S(0)=f1.a
)SET S(1)=f2.b
)SET S(2)=f3.c
)CM
)CM
)CM
%(A(0)).
%(A(1)).
%(A(2)).
%(A(3)).
%(S(0)).
%(S(1)).
%(S(2)).
)CM
found _MDHDSN_(default.txt,S,b,A,0)_

Example The following example shows how the function works with an MVS JCL template:

Input:

//SYSIN DD DSN=_MDHDSN_(COBOL(FOO),DMSOURCE,COBOL,DMPATH)_,DISP=SHR

Output:

//SYSIN DD DSN=SMITCHE.BLD.UNIT.COBOL(FOO),DISP=SHR

210 Serena® Dimensions® CM 12.2.1

 Template Inline Functions

MDHEXTRACT
Description MDHEXTRACT explodes filenames and data set names into component parts.

Syntax _MDHEXTRACT_(format,filename,[root])_

where:
 format is a literal string that can optionally contain one or more of the following
operators:

Operator Description
+p Returns the filename prefix, usually 'null' on distributed platforms and
'//' on MVS platforms.
+r Returns the root of the filename with a trailing directory character.
Distributed example: \test-machine\builds\test_1\
MVS example: //test-machine.builds.test_1.
See the explanation below this table about specifying a root.
+n Returns the name of the object, for example, foo.

+t Returns the type of the object, for example, c or cobol.

+s Returns the subdirectory with a trailing directory character.

Distributed example: unit_test\build_1\
MVS example: unit_test.build_1.
See the explanation below this table about specifying a root.
+d Distributed platforms: returns the entire path and filename, for example:
\test-machine\builds\test_1\unit_test\build_1\foo.c
MVS platforms: returns the full data set name without the initial '//', for
example:
test-machine.builds.test_1.unit_test.build_1.cobol(foo)

 filename specifies the filenames or data set name that you want to explode.
 [root] specifies the part of the filename or data set name that is the root. For
example:

\test-machine\builds\test_1\ unit_test\build_1\

root (+r) subdirectory (+s)

Example This example returns the name of the object.

Input:

_MDHEXTRACT_(+n,/root/test/fred.txt,)_

Output:

fred

Example This example returns the type of the object.

Input:

_MDHEXTRACT_(+n,//'MDH.DEV.UT.THING.C(FOO)',)_

Developer's Reference 211

Chapter 8 The Templating Language and Processor

Output:

FOO

Example This example specifies the root, and returns the subdirectory, the type, and the name of
the object.

Input:

_MDHEXTRACT_(subdir(+s) type(+t) name=+n,

//'MDH.DEV.UT.TEST.C(FOO)',MDH.DEV.UT)_

Output:

subdir(TEST.) type(C) name=FOO

Example This example uses MVS data set names.

Input:

_MDHEXTRACT_(t(+t) name(+n),//'MDH.DEV.UT.TEST.TEXT',)_

Output:

t(TEXT) name(TEST)

NOTE It is common for problems to occur with different kinds of slashes appearing in
filenames, particularly when the names are computed from parts. You can use a
particular form of the MDHEXTRACT function to normalize names, according to the current
platform. On Windows backslashes are used ("\") and on UNIX forward slashes are used
("/") in the output. For example:

)SET NEWNAME=_MDHEXTRACT_(+d,%OLDNAME.)_

substring
Description This function reads nothing and writes back nothing, but the first variable V1 is set to the
substring of V2 specified by the spos and len values. If spos is negative, the start
position is the specified number of characters from the end.

Syntax )CALL substring V1 V2 spos len

where:
 spos is optional and defaults to 0.
 len is optional and defaults to -1 (meaning the rest of the string).

Example Input:

)SET V2=The Quick Brown Fox

)CALL substring V1 V2 0 2
%V1.Extensibility
Output: Th

Input:

)SET V2=The Quick Brown Fox

)CALL substring V1 V2 -3 1
%V1.

212 Serena® Dimensions® CM 12.2.1

 Testing Templates

Output: F

pos
Description This function creates the variable V3 and sets its value to the result of the operation. The
variable VMAIN is searched for by the substring VSUB. If there is no match, V3 is set to
the string -1. Otherwise it is set to the string representing the decimal number equal to
the starting offset of the substring.

Syntax )CALL pos V3 VMAIN VSUB

Example Input:

)SET VMAIN=This is mine now

)SET VSUB=mine
)CALL pos V1 VMAIN VSUB

Output: V1 contains the value 8.

Input:

)SET VMAIN=This is mine now

)SET VSUB=this
)CALL pos V1 VMAIN VSUB

Output: V1 contains the value 0.

Testing Templates
For a Dimensions CM server or agent installation, a template testing program called
template test is located in the 'prog' subdirectory of the Dimensions CM root
installation directory. This template testing program enables you to unit test your own
templates. It is command-line driven and invokes the template processor on a single
input file for processing.

Command-line
template_test <input file> <switches>

Switches

Switch Default Description

-? Displays help.
-b dir NULL Specifies the base directory for templates.
-c command n/a Specifies a command string.
-d value Specifies a value.
-e dir NULL Specifies an execution directory.

Developer's Reference 213

Chapter 8 The Templating Language and Processor

Switch Default Description

-g redir None Sets redirection options. Can be one or more of s,
e, or c.
 s: stdout is directed to a temporary file.
 e: stderr is directed to a temporary file.
 c: outputs are combined into one temporary
file.
-h <headerspec> Includes the specified header before processing the
template.
-i Traces storage allocates in template_test pool.
-j False Executes under JES.
-k Creates a shared pool (SAVE/DELETE/LOAD).
-l <logspec> NULL Sends all messages to the log file you specify.
-m <messagespec> Specifies an output for diagnostic/terminal output.
-o <outputspec> NULL Spools the output to the file that you specify
instead of passing the template to the system for
execution.
-p <password> dmsys Sets the password to the value that you specify
before calling the routine.
-r False Reports on storage allocation and deallocation
requests.
-s Use service provider (_MDHDSN_ etc)
-t False If set to true, reports all messages to stdout.
-u <user id> dmsys Sets the user id to the value that you specify before
calling the service.
-w Waits for execution.
-x False Passes the template to the system for execution.
-1 <path> NULL Sets the first element of the search path (after -b
value).
-2 path NULL Sets the second search path element.
-3 path NULL Sets the third search path element.

Result codes

Return code Description

0 Completed successfully
4 Completed with errors
20 Total system failure

NOTE The file headtest.template provides a test template that sets up values similar
to those used in a build environment in Dimensions CM.

214 Serena® Dimensions® CM 12.2.1

 Adding Template Variables to the Dimensions Configuration File

MVS Template Testing Program

For the MVS version of the template testing program, see the following JCL example:

//USER1 JOB 'USER NAME',MSGCLASS=X

//*
//SETS SET B='//USER1.TEST'
//*
//TPL EXEC PGM=MDHLTPLT,
// PARM='-o DD:O -b . -t -w -1 "&B" TESTTPL'
//*
//STEPLIB DD DISP=SHR,DSN=MDH.V1010.MDHLLIB
// DD DISP=SHR,DSN=MDH.V1010.MDHLLPA
//SYSPRINT DD SYSOUT=*
//CEEPRINT DD SYSOUT=*
//*
//O DD SYSOUT=*
//*

Adding Template Variables to the Dimensions

Configuration File
You can optionally add template variables to the Dimensions CM configuration file,
dm.cfg, located in the following directories or data set.
 (Windows): %DM_ROOT%
 (UNIX): $DM_ROOT
 (MVS): MDH.V1010.MDHPARM(MDHTDCFG)

The table below lists the template related variables.

Variable Description
DM_TEMPLATE_CATALOGn Specifies a data set or directory search path where
templates are located. You can specify an array of
multiple search paths by adding multiple instances of
DM_TEMPLATE_CATALOGn and incrementing the value
of n, for example:
 DM_TEMPLATE_CATALOG1 c:\prod\templates
 DM_TEMPLATE_CATALOG2 d:\dist\templates
Default locations:
 Windows: %DM_ROOT%templates
 UNIX and MVS: $DM_ROOT/templates
(Sheet 1 of 2)

Developer's Reference 215

Chapter 8 The Templating Language and Processor

Variable Description
DM_TEMPLATE_CATALOGn Notes:
(continued)  On distributed platforms the search path
specifies a single directory.
 If you specify a file type, Dimensions CM looks in
the search paths for matching files. On MVS, if
you do not specify a file type, the default is
TEMPLATE.
DM_TPLB_LOG Switches on tracing of template processing. Specifies
the name of the file that will contain detailed
messages issued during template processing, and the
substitutions performed. You can customize this string
before using it as follows:
 %d—inserts the date in the format yyyymmdd.
 %t—inserts the time in the format hhmmss.
 %p—inserts the process id.
 %%—inserts one '%' character.

Default: none

Example: tmp/template_log_%d_%t.log
DM_TPLB_SPOOL Specifies the name of the file or data set where the
JCL will be written. The file is not passed for
execution. This field may be useful when testing new
templates.
 Maximum field length: 100 bytes
 Default: null
 Example: tmp/spooled.jcl
DM_TPLB_TTLOG Specifies that any trace sent to the file that you
specify in DM_TPLB_LOG is also sent to the message
routine (the trace comes back to the client to be
displayed).
 Default: null
 Example: yes
DM_TPLB_SEQUENCE_PATH Specifies the directory where the HFS file that
maintains the build sequence number is stored.
Default: the directory specified in the variable DM_TMP.
If this variable is not set, the defaults are:
 UNIX: /TMP
 Windows: c:\temp
(Sheet 2 of 2)

216 Serena® Dimensions® CM 12.2.1

 Extending the Template Processor with User Written Functions

Extending the Template Processor with User Written

Functions

Template Processing—Call-Out Functionality

Introduction
The functionality described here is a generalized call-out facility that allows user written
code to run in-process as part of the template processing logic. User written code can
live in user DLLs or on z/OS in an assembler module. The template processor can 'call
out' to these routines, passing values in both directions. The user code is called with a
control block (TEB) that holds the addresses of some callback routines and a context
pointer, and a count and pointer array to the parameter list.

Callback Routine Purpose

const char *TEB_ReadData( To get the next line of 'input'.
void *)
void TEB_WriteData( To write the output back to the template
void *, processor for inclusion into the input stream.
const char *)
int TEB_Message( To issue an error, warning, or informational
void *, message during processing. The last letter of
const char *pszPrefix, the prefix drives the severity. 'E' causes the
routine as a whole to fail.
const char *pszMessage)
const char *TEB_GetString( Looks up the corresponding symbol and
void *, retrieves a pointer to its value.
const char *pszName)
int TEB_SetString( Sets the value of the specified symbol to the
void *, value. Any previous data associated with the
const char *oszName, symbol is lost (the symbol is deleted first from
the symbol table). FALSE is returned if there is
const char *pszValue) an error.

Additional Template Directives

This call-out functionality is supported by the following additional template directives:
 )CALL dllname.function ParametersList
 )SCRIPT dllname.function ParametersList
cards
)ENDSCRIPT

These directives are implemented by the same code. The parameter dllname is
optional:
 If you do not specify dllname some internal entrypoints are exposed.
 If you do specify dllname the DLL is loaded once and any entrypoints that are
referenced in that DLL are resolved against the single handle.

Developer's Reference 217

Chapter 8 The Templating Language and Processor

 On z/OS, if you use the special Dllname Assembler, the entry point is fetched and
called (no dll load is attempted).

The parameter ParameterList is optional and has similar syntax to that of a C

program. For example, you can use pairs of double quotation marks (" ") to surround a
single parameter with embedded spaces. The number of parameters, and the array of
pointers to these parameters, is exactly the same as for a C program with argc and
**argv held in the TEB block.

The 'cards' are records that are processed by the template processor (with replacement)
that the function 'reads' using a specialized read processor. The function writes output
back using a specialized 'Write' function that is passed through the template processor
again, so any ')' directives in this stream are honoured.

Predefined Functions
 durules
This function gets details from Dimensions CM useful for uploading that item into
Dimensions CM. The syntax is as follows:

durules <product_id> <project_id> <project root> <context_root>

<file>
where:

<product_id> specifies the product into which the item will be placed.
<project_id> specifies the project into which the item will be placed.
<project_root> specifies the location of the root of the project within the
project hierarchy (if using sub-projects, use "\" if not).
<context_root> specifies the path that will be prepended to the file to get
the full path.
<file> specifies the file for which information is to be gathered.

Returned This is a set of vectors, with one entry in each vector corresponding to each object;
information. that is, all the [0] values pertain to the first object returned, all the [1] values to
the second object returned, and so on.

DMDUCOMMENT Comment for upload.

DMDUDESCRIPTION Description of item.
DMDUDIRPATH Directory path of item.
DMDUFILENAME Filename of item.
DMDUFORMAT Format of item (determined from upload rules).
DMDUITEM_ID Suggested item-id for item.
DMDULIB_FILENAME Suggested library filename for item.
DMDUOWNING_PART_ID ID of part that is to own item.
DMDUOWNING_PART_PCS PCS of part that is to own item.
DMDUOWNING_PART_VARIANT Variant of part that is to own item.
DMDUPRODUCT_ID ID of product that is to own item.

218 Serena® Dimensions® CM 12.2.1

 Extending the Template Processor with User Written Functions

DMDUREVISION Suggested revision for item.

DMDUSTATUS Suggested status for item.
DMDUTYPE Suggested type for item.
DMDUVARIANT Suggested variant for item.
DMDUWSPATH Suggested project path for item.

 pos
The built-in function pos is called as follows:

)CALL pos V3 VMAIN VSUB

As the result of this directive:
• The variable V3 is created, and its value is set to the result of the operation.
• The variable VMAIN is searched for the substring VSUB. If there is no match, V3 is
is set to the string -1; otherwise, it is set to the string representing the decimal
number equal to the starting offset of the substring.
For example:

)SET VMAIN=This is mine now

)SET VSUB=mine
)CALL pos V1 VMAIN VSUB
results in V1 containing the value 8;
whereas

)SET VMAIN=This is mine now

)SET VSUB=this
)CALL pos V1 VMAIN VSUB
results in V1 containing the value 0.
 scanarea
This function—which requires a connection to the Dimensions CM server—recursively
scans the area specified and returns information on all files within the area. The
syntax is as follows:
scanarea <directory path> <area root> <filter>
where:

<directory path> specifies the location of the directory that will be the root of
the search. It may be in NODE::DIR format.
<area root> specifies the root of the area that contains the target
directory. To scan the whole area <directory path> and
<area root> will be the same.
<filter> if specified, then only files matching this filter will be
returned. An example filter is "*.txt".

Developer's Reference 219

Chapter 8 The Templating Language and Processor

Returned This is a set of vectors, with one entry in each vector corresponding to each object;
information. that is, all the [0] values pertain to the first object returned, all the [1] values to
the second object returned, and so on.

DMCSFILENAME The filename.

DMCSFILEPATH The directory path containing the filename.
DMCSMODTIME Last modified time.
DMCSSIZE Byte size of file.
DMCSPERMISSIONS Permissions of file (unix format)
DMCSISDIR Y if this is a directory.
DMCS_LF_CHECKSUM Checksum assuming line-endings are in LF (UNIX)
format.
DMCS_CRLF_CHECKSUM Checksum assuming line-endings are in CRLF
(Windows) format.
DMCS_LF_SIZE Size of file assuming line-endings are in LF (UNIX)
format.
DMCS_CRLF_SIZE Size of file assuming line-endings are in CRLF
(Windows) format.
DMCS_FULLPATH Fully specified path of file.
DMCSACCESSTIME Time file was last accessed.
DMCSCREATTIME Time file was created.
DMCSCAN_READ Y if file can be read.
DMCSCAN_WRITE Y if file can be written.
DMCSCAN_EXECUTE Y if file can be executed.
DMCSDIR_HAS_SUBDIRS Y if this is a directory and it has subdirectories.
DMCSDIR_HAS_FILES Y if this is a directory and it has files in it.
DMCS_IS_DRIVE Y if this is a drive.
DMCS_DRIVE_TYPE If this is a drive, type of the drive.
DMCS_EXTENSION The extension of the file, or empty if none.
DMCS_BASENAME The basename of the file (part of name before
extension).
DMCS_LEAFDIR The lowest level enclosing directory, or empty if
none.
DMCS_LEAFBASE The directory path containing this file, minus the
lowest level directory.

 substring
There are some predefined functions that are implemented using this logic. The
built-in substring entry point is provided, and is called as follows:

)CALL substring V1 V2 spos len

220 Serena® Dimensions® CM 12.2.1

 Extending the Template Processor with User Written Functions

where:

spos is optional and defaults to 0. If spos has a negative value, then the start
position is that many characters from the end.
len is optional and defaults to -1 (meaning the rest of the string).

This directive reads nothing and writes back nothing, but the first variable V1 is set
to the substring of V2 specified by the spos and len values.
For example:

)SET V2=The Quick Brown Fox

)CALL substring V1 V2 0 2
%V1
puts 'Th' to output;
whereas

)SET V2=The Quick Brown Fox

)CALL substring V1 V2 0 2
%V1
puts 'F' to the output.

Writing z/OS Code for this Interface

On z/OS, you could write such an exit in 'C' or possibly in assembler.

Extensibility
Depending on the context, additional pre-defined functions may be available.

pBem Template Processing—Passing Data Between

Steps

Overview
A template processing step can pass data to a later template processing step. To do this,
five additional directives are provided:

)SAVE "groupname" variable/variablemask

)LOAD "groupname" [option]
)DELETE "groupname"
)IFGROUPDEF "groupname"
)IFGROUPNDEF "groupname"

where:

groupname identifies a collection of data that can be manipulated by any

template wishing to use the facility.
The groupname can contain spaces, and can be any length. The
quotation marks (" ") are optional, but if they are not specified then
white space will delimit the group name.

Developer's Reference 221

Chapter 8 The Templating Language and Processor

variable specifies both the name the variable will be saved as and, by looking
that up, the value to save.
For example:
 If 'FROG' does not already exist as a symbol, ')SAVE
NewDomain FROG' will fail.
 If 'FROG' does already exist as a symbol, then:
• If additionally the group ’NewDomain' does not exist, it will
be created;
• otherwise, if ’NewDomain' does exist, it will be updated by
the addition of the symbol 'FROG' set to its current value in
the template processor symbol table.
variable mask a variable mask is handled if the variable name contains either
asterisk '*' or question-mark '?'. '*' matches any number of
characters; whereas, ’?' matches a single character at that point.
option On a load, any variable in the group will be added to the current
symbol table. By default, any variable of the same name in the
current symbol table will be lost; this default behavior can be
modified by specifying one of the following optional values:
 OVERWRITE
 WARN
 ERROR
 DISCARDDUPLICATES

Forcing Template Expansion in the pBem

You can force a template to be expanded by setting a symbol—which can be in the step
or for the whole pBem job. This means that you can be sure that a specific template for a
certain type of step will always be expanded even if optimization discards the step
anyway. This processing is the default—the variable turns this off.

Semantics

)SAVE saves the specified symbol or all matching symbols. If the group
specified by group name does not exist, it will be created.
)LOAD merges the specified group with the current symbol table. If no
such group exists, an error will result. Remember, the incoming
)LOAD symbol gets priority.
)DELETE destroys the entire group, freeing the associated storage.
)IFGROUPDEF behaves as )IFDEF and allows conditional logic based on the
existence of the named group.
)IFGROUPNDEF behave as )IFNDEF and allows conditional logic based on the
existence of the named group.

222 Serena® Dimensions® CM 12.2.1

 Extending the Template Processor with User Written Functions

Example Template
First line
)SET V2=This is a string of data
)CALL substring V1 V2 -6 8
'%V1.'
)CALL libsampleexit101uD.so.GetIdeas
)SET V4=My own parm 4
)SCRIPT libsampleexit101uD.so.DumpParameters P1 "prm 2" "prm 3"
"%V4."
This is the first line of input to Dump - %V1.
And this the second
)ENDSCRIPT
***END***

The command:

template_test -b . -o spool.output foo2.template

will produce the following output:

First line
'f data'
Next parameter[0] = 'libsampleexit101uD.so.DumpParameters'
Next parameter[1] = 'P1'
Next parameter[2] = 'prm 2'
Next parameter[3] = 'prm 3'
Next parameter[4] = 'My own parm 4'
This is the first line of input to Dump - f data
And this the second
***END***

To create this output, the routine libsampleexit101uD.so has been created, and this
looks like this:

/* Copyright Serena 2008

* ---------------------
* This is sample code and may be used as a guide for customers
* wishing to create their own callouts.
*/
#include <stdio.h>

/* The following lines handle compilation on several platforms:

* windows, unix and z/OS
*/

#ifdef _WIN32
# define VBCALL __stdcall
# define IMPFUN __declspec(dllimport)
# define EXPFUN __declspec(dllexport)
#else
# ifdef PLATFORM_OS390UNIX
# pragma linkage(GetIdeas, OS)
# pragma linkage(DumpParameters, OS)
# endif
# define VBCALL

Developer's Reference 223

Chapter 8 The Templating Language and Processor

# define IMPFUN
# ifdef __GNUC__
# if __GNUC__ >= 4
# define EXPFUN __attribute__ ((visibility("default")))
# else
# define EXPFUN
# endif
#else
# define EXPFUN
# endif /* __GNUC__ */
#endif /* WIN32 */

/*
* This is the common copybook for using this facility
*/

#include "template_callout_public.h"

/*
* This first example just shows a call back to issue a message.
* It does nothing else.
* The last character of the prefix (JMH....W) is the severity of
the message.
* You should use 'E' for errors, 'W' for warnings, 'I' for
information.
*/

EXPFUN void GetIdeas(pTeb pData)

{
(pData->TEB_Message)
(pData->TEB_pHandle,
"JMHTPE1600001W",
"Running the sample template exit");
}

/*
* This function demonstrates a way of seeing what parameters are
* passed to this function - both on the )SCRIPT line and in
* the lines between the )SCRIPT and the )ENDSCRIPT.

* So, it shows how to use TEB_PAramterCount and TEB_Parameters.

* Then it shows how to call the TEB_WriteData routine to

* send lines back to the templater for reprocessing.

* The TEB_ReadData routine will return each line of input up to the

)ENDSCRIPT
* and these can be processed as you see fit.

* All newlines have been stripped on input and should be left off
on
* output.
*/

EXPFUN void DumpParameters(pTeb pData)

{

224 Serena® Dimensions® CM 12.2.1

 Extending the Template Processor with User Written Functions

const char *pszInput = NULL;

char szBuffer[10000];
int i;

for (i=0;i<pData->TEB_ParameterCount;i++)
{
sprintf(szBuffer,
"Next parameter[%d] = '%s'",
i,
pData->TEB_Parameters[i]);
(pData->TEB_WriteData) (pData->TEB_pHandle, szBuffer);
}

while (NULL != (pszInput = (pData->TEB_ReadData)

(pData->TEB_pHandle)))
(pData->TEB_WriteData) (pData->TEB_pHandle, pszInput);

You will need this copy book as well:

/*-----------------------------------------------------------------
* Copyright (C) 2008, Serena Software Europe, Ltd. All rights
reserved.
*
* No part of this software may be reproduced, stored, or
transmitted, in any
* form or by any means, without the prior permission in writing of
Serena
* Software Europe, Ltd and Serena Software, Inc.
*-----------------------------------------------------------------
* MODULE SPECIFICATION
* %PID%
* Description:
* %PD%
*%PCMS_HEADER_SUBSTITUTION_END%
*/

#ifndef TPCI_PUBLIC

#ifdef __cpluspls
#ifdef PLATFORM_OS390UNIX
extern "OS" {
#pragma pack(1)
#else
extern "C" {
#endif
#else
#ifdef PLATFORM_OS390UNIX

Developer's Reference 225

Chapter 8 The Templating Language and Processor

#pragma linkage(fReadData,OS)
#pragma linkage(fWriteData, OS)
#pragma linkage(fGetString, OS)
#pragma linkage(fSetString, OS)
#pragma linkage(fMessage, OS)
#pragma pack(1)
#endif
#endif

typedef int (fMessage)(void *pHandle, const char *pszPrefix, const

char *pszMessage);
typedef int (fWriteData) (void *pHandle, const char *pszData);
typedef const char *(fReadData) (void *pHandle);
typedef const char *(fGetString) (void *pHandle, const char
*pszSymbol);
typedef int (fSetString) (void *pHandle, const char *pszSymbol,
const char *pszValue);

struct TplExtensionBlock {
void *TEB_pHandle; /* handle to use with read/
write/message */

/* READ routine
* - call this to get each line of the data up to the
* )ENDSCRIPT.
* - NULL marks the end of the script.
* - lines are terminated by a null with no newline.
* Templater symbols will have been replaced in here.
*/
fReadData *TEB_ReadData;

/* WRITE routine
* - call this to create new template lines for inclusion into
the output stream.
* - templater commands issued here will be honoured.
* - The lines should terminate with a \0 character (and no \n).
* - returns -1 on error.
*/
fWriteData *TEB_WriteData;

/* MESSAGE routine
* - Call this interface to issue messages.
* - The Message Prefix is a code which should end in a severity
(E - error, W - warning, I - information)
* - Processing will be deemed to have failed iff the callout has
written an E message back.
*/
fMessage *TEB_Message;

/* The following routines provide a way of accessing the template

processor symbol table.
* The first routine will get a value from the symbol table.
* NULL is returned if the variable doesn't exist or is vectored.
*/
fGetString *TEB_GetString;

226 Serena® Dimensions® CM 12.2.1

 Extending the Template Processor with User Written Functions

/* This will put a symbol into the symbol table or if it is there

* will alter it
*/
fSetString *TEB_SetString;

/* The following are the count of parameters on the line invoking

the callback and
* pointers to each in the traditional 'C' format.
*
* TEB_ParameterCount will never be less than 1.
* *TEB_Parameters will point at the name of the called entry
point.
* Do not modify any value in these.
*/
int TEB_ParameterCount;
char **TEB_Parameters;

};

typedef struct TplExtensionBlock *pTeb;

#ifdef __cplusplus
#ifdef PLATFORM_OS390UNIX
#pragma pack(reset)
}
#else
}
#endif
#else
#ifdef PLATFORM_OS390UNIX
#pragma pack(reset)
#endif
#endif

#define TPCI_PUBLIC
#endif

This sample exit has two routines implemented, and uses an include file
template_callout_public.h which will be available to customers. The first routine
just puts out a message. The second routine dumps its parameters (both the input line
parameters and the script) back into the template processor.

Example Templates Utilizing The Rexx Interface

Rexx interface Here is a quick summary of the REXX interface:

)SCRIPT MDHDREXX.REXX
..
..
..
)ENDSCRIPT

Developer's Reference 227

Chapter 8 The Templating Language and Processor

Rexx rules 1 Instead of "say", use "call mdhsay".

2 Instead of "exit", use "return".

3 Do not define any rexx signal handlers.

4 If you define a procedure, you need to add "expose (mdhexpose)" to the definition.

5 If you need to send a MsgX message, use "call mdherr 'MDHREX4700001E ...'".

6 You can specify one, two or three numbers after this space delimited. These are:
 the size of the w/s the REXX interpreter needs to hold local data (in bytes)
 the size of the area for storing mdhsay and mdherr messages (with some
overheads for control) in bytes.
 the number of lines the REXX occupies.
These numbers default to 32000, 32000, and 2000. These values are the minimum;
if you specify less it will not get used.

Rexx example 1 This example turns http://www.something.com/remaining into just "something"

)SET URL=http://www.serena.com/splat/bim/bam

)SCRIPT MDHDREXX.REXX
url="%URL."
parse var url "http://" . "." company "." .
call mdhsetvar "COMPANY",company
)ENDSCRIPT

COMPANY = %COMPANY.

Rexx example 2 This example reverses the slashes, "/" to "\" in an array

)VECTOR DMPATH(5)
)SET DMPATH(0)=/a/1/x/fo.c
)SET DMPATH(1)=/b/2/x/fo.c
)SET DMPATH(2)=/c/3/x/fo.c
)SET DMPATH(3)=/d/4/x/fo.c
)SET DMPATH(4)=/e/5/x/fo.c

)SCRIPT MDHDREXX.REXX
i=0
)REP DMPATH
tmp = "%DMPATH."
tmp=translate(tmp,"\","/")
call mdhszy ")SET DMPATH("i")="tmp
i=i+1
)ENDR
)ENDSCRIPT

)REP DMPATH
%DMPATH.
)ENDR

228 Serena® Dimensions® CM 12.2.1

 The Template Processor Interface

The Template Processor Interface

The callback facility has a new built-in 'catsearch' on MVS only. This invokes the C/C++
catalogue search interface, which allows flexible processing of dataset names and
dataset member names within the template processor. The template processor creates a
collection of parallel arrays for each matched object.

The template command for this has the form:

)SCRIPT catsearch dsnmask membermask opt1 opt2 …

)ENDSCRIPT

Possible options include:

 +/-mems
 +/-ds
 +/- aliases
 +/-mig
 pfx <prefix string>

For example

)SCRIPT catsearch MDHDEV.QUIXOTE.PRIMES.TXT.ASM * -ds +mems -mig

-aliases pfx FF
)ENDSCRIPT

will create a series of variables ppxxxxx each of which is an array with one row
describing each member of the specified dataset in turn. The pp denotes a user-settable
prefix.

Once this command has been executed, additional variables are available in the template
processor symbol table. These are prefixed DMCS by default, but there as an option to set
a user specified value (pfx).

These variables can then be used within a )REP—)ENDR block to provide one-match-at-
a-time logic.

The variables currently supported are:

Variable Values Description

ppALIAS Y/N Y => this is an alias.
ppBLKSIZE Number Blocksize of dataset.
ppCONTAINER Y/N Y => this describes a dataset that is capable
of containing members
ppDSORG String MVS dataset organization—PO, PS, POU, PSU,
DA.
ppENTRY String Name of data set.
ppFULLNAME String build/libfilesys/mdhhcats.h. Name of data set
plus (member) in this row is talking about a
member.
ppILQ String Last qualifier of dataset.

Developer's Reference 229

Chapter 8 The Templating Language and Processor

Variable Values Description

ppLLQ String Second to last qualifier of dataset.
ppLRECL Number Record length for FB files, largest legitimate
record in Variable, 0 in RECFM U files.
ppMEMBER String NULL for a container or sequential dataset.
Alias name for an alias (could be mixed case
then).
Member name for a full library member.
ppMIGRATED Y/N Y => this data set is migrated.
ppPDSE Y/N Y => this is an MVS LIBRARY.
ppPNAME String Primary name when the object is an alias.
ppPROGRAM Y/N Y => this is executable.
ppPROGRAMOBJECTTYPE 0 This is currently always 0.
ppRECFM String Record format for this dataset. FB—fixed
blocked, VB variable blocked, U undefined
etc.
ppVOLSER String Volume serial of the first extent for this
dataset.

Enhancements To Dimensions Command Processing To

Supported Structured Information Return (SIR)

Background
To provide better support in Dimensions CM for:
 Enhanced scripting.
 Automated testing.
 XML/SOAP interfaces.

in conjunction with the need to find a better solution to that of using message scraping
mechanisms to retrieve important data, led to the idea of passing back another type of
object from the Dimensions CM command interface.

This Object Is A Structured Object Containing:

 Names and values and value arrays.
 Composite objects that in turn contain names and values/arrays and composite
objects.

This structured object is expressed as a Dimensions serialized symbol table, and is

intended to be used by the clients as required for the particular applications that that
client is specialized for.

230 Serena® Dimensions® CM 12.2.1

Enhancements To Dimensions Command Processing To Supported Structured Information Return (SIR)

Key features
 The structured information return feature is optional.
 The structured object can be requested (through an alternate outargs structure for
the COMMAND RPC) and will then be created for any command that has a request
structured in this way.
 On the server end, the symbol table is added prior to command processing and
deleted after command processing.
 On the client end, there is, by default, initially no symbol table. Local commands
have been added to control symbol table processing. Once symbol table processing
is turned on, there are always two symbol tables:
• a persistent one, which is explicitly added to as execution progresses, and
• a symbol table resulting from the last remote command RPC issued.
In addition, symbolic replacement is performed on the remote command lines to be
passed to the Dimensions Server for execution.
 The structured object minimally contains a return code (a number which indicates
the success or otherwise of the operation, 0 means total success).
 The structured object will have values added to it dependent upon the processing of
the particular command. An example command which has this feature is the
command used to create a change document.
 Since these enhancements have been made in the client API library, all interfaces
using this can take advantage of this feature. For example, it can be used from:
• The desktop client in the command window.
• dmcli
• The z/OS batch command client.

When To Use Structured Information Return

The distinction between data appropriate to messages and data appropriate to
structured information return (SIR) is as follows:
 Unexpected or abnormal information flows will come through messages.
 The command should be usable with no structured information return.
 Report data: normal flow data will come through structured information.

Client Side Processing

The processing performed by the command line client logic (the public API) has been
extended to support symbol table processing. Commands have been added to control
processing (SSPM, SAVE). In addition, the dcliDispatch routine has been enhanced to
provide symbol replacement. Symbols will be searched for first in the local symbol table,
and then in the persistent symbol table.

Developer's Reference 231

Chapter 8 The Templating Language and Processor

Commands

SPPM
The SSPM command has the forms:

SSPM DBOTH
SPPM DPERSISTENT
SPPM DTEMP
SPM NONE
SSPM OFF
SSPM ON [/USER_FILENAME="file"]
SSPM DUMP /USER_FILENAME="file"

Of the above commands

SSPM DBOTH
SPPM DPERSISTENT
SPPM DTEMP

will display the values in each symbol table through MsgX.

In any command line, if SSPM processing is enabled, then the special character '&' will
mark the start of a parameter name and '.' character the end. The text between the '&'
and the '.' characters is used as a symbol for lookup in the local symbol table and then
the persistent symbol tables and is replaced. The form '&&' is replaced by ’&' and then
just passed.

SAVE
The commands:

SAVE sym1 sym2

or
SAVE sym1 /LIT[ERAL]=value
SAVE sym1 /LIT[ERAL]=(value1,value2,,,)

will cause the value of sym2 to be added to the persistent symbol table as sym1. The
special form SAVE sym1 will lookup sym1 in the local symbol table and save it to the
persistent symbol table. The optional qualifier of /LITERAL= can be used to create a
literal set command.

232 Serena® Dimensions® CM 12.2.1

Chapter 9
Build Templates

Introduction 234
Using Build Templates with Build Configurations 237
High Level Build Templates 238
Compilation Templates 245
Link Templates 248
Collection Templates 254
z/OS Return Codes 256
Miscellaneous Examples of Using Build Templates 256

Developer's Reference 233

Chapter 9 Build Templates

Introduction
This chapter describes how to write build templates. A build template is a customizable
text file containing variables and control words that is processed and expanded when you
run a build. You can use build templates to control the execution of build steps in
Dimensions Build. Dimensions Build is a build management, execution, and monitoring
tool that is part of Serena® Dimensions® CM.

NOTE For information about extending templates with user written functions, see page
217.

Platforms
This chapter discusses MVS build templates separately from distributed build templates.
For distributed platforms the syntax for UNIX and Windows is very similar and Windows
examples are used. USS templates on the UNIX side of z/OS are identical to UNIX
templates.

Examples
Where the contents of example templates are supplied the side-head in the left margin
clearly states if it is a Windows or MVS template, for example:

Windows template Ant %ANT-OPTIONS.

Default Locations
The default locations of the templates are:
 Distributed platforms: %DM_ROOT%\templates
 MVS platforms: %INSTANCE%.TEMPLATE

If the templates are under Dimensions CM source control they can be in a build area or
the search path of a deployment area.

Pre-Requisites
To understand the concepts discussed in this chapter you require prior knowledge of the
following:
 Setting up build configurations, running and monitoring build jobs, the Primary Batch
Execution Monitor (PBEM), and the Secondary Batch Execution Monitor (SBEM). For
details see the Dimensions CM Build Tools User’s Guide.
 Dimensions deployment including projects and areas. For details see Introduction to
Dimensions CM.
 The template syntax used in build templates. For details see "The Templating
Language and Processor" on page 177.

234 Serena® Dimensions® CM 12.2.1

 Introduction

Build Template Types

There are three types of build templates; each type can be applied to distributed and MVS
platforms.

High Level Templates

A high level template invokes a procedure or tool on a build machine such as a complete
build of a sub-system. For example, it may invoke tools such as make, Ant, or Openmake.

Source control can apply to high level templates. You should set up build configurations to
include all the source files needed for the whole build, using wildcard patterns.
Dimensions keeps a search path of deployment areas up to date, or Dimensions Build can
populate a work area at build time. If the configuration is setup properly a set of created
targets can be collected and preserved in Dimensions CM after a build.

All features of the configuration are available to the template but their effect depends on
the tool being used. For example, the search path will only be searched for source files if
the tool allows such operations to be defined.

For more details see page 238.

Compilation Templates
A compilation template configures a finely tuned compile operation including inputs,
outputs, and options. Typical examples are compiling a single source file or pre-processing
a single input. A compilation template can include multiple inputs and outputs but is not
intended to iterate over multiple steps. For more details see page 245.

Collection Templates
Collection templates capture the common LINK paradigm where a set of objects of the
same type are combined. This build configuration can contain multiple inputs and outputs,
but the core of the operation is a loop, where each object in turn is combined to create the
output. These operations are typical towards the end of a build where they collect
together intermediate targets created earlier. For example, collecting a set of obj files
into an exe file using a linker. For more details see page 254.

Other Templates
Dimensions Build includes the following system templates that are not build templates:
 Area pre and post templates
Area pre and post templates are properties of an area definition and are executed
when objects are moved around in Dimensions controlled areas. For details see
"Deployment Area Scripts" on page 277.
 Build pre and post templates
Build pre and post templates are properties of a build configuration and run before
and after a build. They are identical to build templates though their purpose is not to
create targets. Usually a pre template sets up a build and a post template cleans up
after a build has executed.

Developer's Reference 235

Chapter 9 Build Templates

 Primary Batch Execution Monitor

The PBEM executes a build on the remote build machine and is invoked through its
own PBEM template. Understanding the PBEM template enables you to follow what
happens when a build is performed, and to run builds using the PBEM directly without
using Dimensions. The PBEM template is called:
• MVS: TEMPLATE(MDHBPBM0)
• Windows: pbem_start.cmd
• UNIX: pbem_start.sh

NOTE The PBEM always tries to optimize a build process by only building what is
required. To rebuild all targets irrespective of their timestamps set the symbol
DMREBUILDALL to 'Y' in the Build Options section of a build configuration or in a
template using a )SET statement.

For details about the PBEM architecture see the Dimensions CM Build Tools User’s
Guide.
 Secondary Batch Execution Monitor
The SBEM is a standalone MVS only program that reads in JCL and executes the JCL in
a controlled environment. This allows inputs and outputs of a compile step to be
automatically detected by examining when files are opened and closed.
The SBEM runs a build step in a controlled environment to generate dependency
information that details all the source files that were used. The SBEM is invoked by a
standard SBEM template called TEMPLATE(MDHBSBM0). The SBEM introduces extra
syntax to a template to control its operation and is described on page 241.
For details about the SBEM architecture see the Dimensions CM Build Tools User’s
Guide.
 Bill of Materials (BOM)
The BOM is an XML report file detailing all the components the went into a build. The
physical creation of this file is controlled by the template TEMPLATE(MDHBBOM0) that
is only shipped with MVS. For details see page 244.
 CANCEL
When a build timeout occurs, or you cancel a build, a template is executed that
cancels all current build steps. This template is called:
• MVS: TEMPLATE(MDHBEND)
• Windows: pbem_stop.cmd
• UNIX: pbem_stop.sh
 Openmake
To support Openmake in Dimensions Build the following build templates are provided:
• MVS: TEMPLATE(MDHBOMT0)
• Windows: bldtplt.cmd
• UNIX: bldtplt.sh
For details about using Openmake search paths see page 242. For details about
writing Openmake templates see page 261.

236 Serena® Dimensions® CM 12.2.1

 Using Build Templates with Build Configurations

Using Build Templates with Build Configurations

For full details about setting up build configurations see the Dimensions CM Build Tools
User’s Guide.

Build Options
A transition step defined in a build configuration can be expressed as a set of options with
pre-defined special names that encode what the step does. For example, the option
DMINPUT contains the names of the input files.

You can also add pre-defined options to a configuration or specify new options. These are
available to the template at expansion time and can be used to allow a single fixed
template to be used in a very flexible way. For example, you can inject options directly
into compiler option strings, or use other options as conditional triggers, causing arbitrary
changes in the way the template is expanded.

The example below shows an option called DEBUG with a value of Y

Transition Rule Templates and Options Groups

For large and complicated build configurations, typically found on MVS, you can use option
groups and transition rule templates.

A build option group is a logical collection of build tool options that are passed to the build
engines and templates that execute builds, for example, Compile_Options or
Link_Options.

A transition rule template describes a generic rule for building an item and applying it to
specific source items at a later time. It describes how to change or transition an item of
one type (for example, *.c) to an item of another type (for example, *obj) using a
template or script.

Developer's Reference 237

Chapter 9 Build Templates

High Level Build Templates

TIPS
 To check what actions a build step has performed, inspect the script that expanded
the template. To check what actions a build step will perform, inspect the original
template.
 To understand the examples used in this chapter, you must have a solid working
knowledge of the template syntax. For details see page 177.

The simplest case of a distributed high level build template is a script that is invoked
directly from a shell or DOS prompt. Any valid scripting technique will work including
executing further scripts or .bat files that are present in the search sequence. The
statements are processed by the default shell and can use any programming structures
normally available in that language.

The simple one line example below runs an Ant script. Assume that the build area
contains a file called build.xml that controls a large java build. In the build configuration
the inputs are *.java and the outputs are *.war or similar.

Windows template ant

Variables
Variables are the central feature of a build template. You can enhance a template by using
variables from a build configuration to insert values, for example:

Windows template Ant %ANT-OPTIONS

You can also use the variables to drive build logic used in IF statements:

Windows template )IF %DEBUG-ANT.=Y

Ant ……
)ELSE
Ant ….
)ENDIF

When you use templates there can be problems with special characters when there is a
conflict between the script language and the templater. For example, by default template
variables are introduced with %, which is also used by DOS. You can work around this
issue by turning off template expansion as follows:

Windows template )ENDEXPAND

ECHO Path is %PATH%

Sometimes this solution is not enough. To mix template variables with other syntax you
may need to use the )ATTR command to change the special characters that the template
uses. In the example below, PATH is a DOS variable and DMPATH is a template symbol:

Windows template )ATTR )~.():

ECHO PATH is %PATH%
ECHO DMPATH is ~DMPATH.

You can also use special characters twice though this produces results that are more
difficult to read:

238 Serena® Dimensions® CM 12.2.1

 High Level Build Templates

Windows template ECHO PATH is %%PATH%%

ECHO DMPATH is %DMPATH.

Pre-Defined Build Symbols

The template syntax includes pre-defined symbols, for details see "The Templating
Language and Processor" on page 177.

Handling Array Variables

Some pre-defined symbols, and those created manually with the )VECTOR command,
require special handling. Normally some kind of loop around each element of the array is
needed as shown in the following example:

Windows template )SET COUNT=0

)REP DMINPUT
)ADJUST COUNT 1
ECHO Input %COUNT. Is the file %DMINPUT.
)ENDR

Sometimes you might need a particular element. The example below gets the first
element of the search path.

Windows template )SET DESTINATION=%(DMPATH(0)).

Occasionally you might want to test the filename inside a loop to find items that match a
criteria. A common criteria is to loop around all inputs and find all those that match a
particular type. This is the purpose of the MDHEXTRACT function, which can break a
filename into pieces so that they can be compared (only on MVS and UNIX)

Windows template )REP DMINPUT

)SET TYPE=_MDHEXTRACT_(+t,%DMINPUT.)_
)IF %TYPE.=C
Echo %DMINPUT. Is a C file
)ENDIF
)ENDR

For details about MDHEXTRACT see page 211.

NOTE To find a given unique file in a list and search for it in the search path, use the
MDHDSN function. For details see page 208.

A common technique is to build up a larger structure from a list of files or directories. The
example below makes a single list from all the elements of DMINPUT.

Windows template )SET LIST=

)REP DMINPUT
)SET LIST=%LIST. %DMINPUT.
)ENDR

Developer's Reference 239

Chapter 9 Build Templates

The example below creates an MVS concatenated DDNAME from the same array.

MVS template )SET DD=//SYSUT1 DD

)REP DMINPUT
)SET SRC=_MDHDSN_(%DMINPUT.,,,DMPATH)_
%DD. DISP=SHR,DSN=%SRC.
)SET DD=// DD
)ENDR

After template expansion the result might be like this:

//SYSUT1 DD DISP=SHR,DSN=AAAA.COBOL
// DD DISP=SHR,DSN=BBBB.COBOL
// DD DISP=SHR,DSN=DDDD.COBOL
// DD DISP=SHR,DSN=EEEE.COBOL

Asynchronous Templates
UNIX and Windows build templates can run synchronously or asynchronously. MVS
templates must run asynchronously as they become batch jobs using JCL. A small piece of
template syntax is required to allow the asynchronous task to communicate back to the
controlling build monitor (PBEM) when it has completed.

The standalone utility bldcomms, which is supplied with Dimensions CM, can communicate
with the PBEM or a Dimensions Build server depending on the parameters that you specify.
The MVS version of bldcomms is MDHLBLCM.

The example below shows how to use bldcomms on distributed systems to communicate
with the PBEM:

Windows template …
…
)SET RC = <result of the step>
…
)IF %DMRUNMODE. = ASYNC
)CM
)CM the following is a single line command!
)CM
bldcomms monitormessage %DMPBEMNODE. %DMPBEMPORT. "R=%RC. I=%DMSTEP.
T=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.%DMSECOND.%DMMICROSEC."
)ELSE
exit %RC.
)END

In this example the result is RC. When run synchronously this is the return from the
template. When run asynchronously this return is part of a message passed back to the
PBEM. The other variables used in this example are pre-set by Dimensions CM and
described in "The Templating Language and Processor" on page 177.

On MVS you can use a JCL equivalent of the above example. However, the continuation
rules for JCL are complicated and alternatively you can use the SBEM component on MVS,
see page 241 for details. To run from plain JCL without the SBEM do the following:

240 Serena® Dimensions® CM 12.2.1

 High Level Build Templates

MVS template )SET TIMESTAMP=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.

)SET TIMESTAMP=%TIMESTAMP.%DMSECOND.%DMMICROSEC.
//*
//STEP200 EXEC PGM=MDHLBLCM,
)CM
)CM next line should end col 73.
)CM
// PARM='POSIX(ON),ENVAR("_CEE_ENVFILE=DD:ENV")/
monitormessage
)CM
)CM next line should start col 17. (we need the space in col 16)
)CM
// %DMPBEMNODE. %DMPBEMPORT. "R=0 I=%DMSTEP.
T=%TIMESTAMP."'
//*
//STEPLIB DD DISP=SHR,DSN=%DMCDHLQ..%DMCDILQ..MDHLLIB
// DD DISP=SHR,DSN=%DMCDHLQ..%DMCDILQ..MDHLLPA
//ENV DD DISP=SHR,DSN=%DMCDHLQ..%DMINST..PARM(MDHTDCFG)
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY

To create an MVS high level style build step add the above JCL to an existing JCL
procedure. The JCL runs normally and tells the PBEM when it has finished.

For additional details about bldcomms and MDHLBLCM see the Dimensions CM Build Tools
User’s Guide.

Using the SBEM

The SBEM makes the message passing performed above slightly easier. This is equivalent
to the previous example but using the SBEM. The //*SBEM part is a directive to the SBEM
to send the step completion message. As well as cleaner syntax, the SBEM also plugs in
the return code to the message, avoiding the need for conditional JCL that might be
required as in the previous example.

MVS template )SET TIMESTAMP=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.

)SET TIMESTAMP=%TIMESTAMP.%DMSECOND.%DMMICROSEC.
//*SBEM END I=%DMSTEP. T=%TIMESTAMP.
)SET DMEXECENV=TEMPLATE TEMPLATE(MDHBSBM0)

In the example above note how the DMEXECENV special variable gets the JCL in the file
embedded inside the actual runtime JCL, which runs the SBEM.

The SBEM has syntax to control the generation of the BOM and the detection of inputs, for
more details see "Creating a BOM from the SBEM" on page 244.

NOTE To avoid problems with the COBOL compiler, you must explicitly define SYSOUT
DD in the build template.

Developer's Reference 241

Chapter 9 Build Templates

Using Search Paths

High level build templates are not intended for use with search paths. However, you can
use search paths if they are supported by your build tool and the build tool can search for
source code in the locations listed in the DMPATH array.

It you write a procedure to support search paths you can use the Dimensions deployment
areas model to efficiently manage the hierarchy of build areas in a typical setup where
most files are at the RELEASE level and a few active versions are at TEST.

Openmake supports search paths but in an indirect way. You can only define the named
search path in Openmake itself, and only the name of this object is passed in the build
configuration. The Openmake search path is not automatically created from the contents
of the DMPATH array.

The example below shows how to use a make script template on Windows with a search
path. The script itself is the makefile and DMEXECENV ensures that it is run through make
and not the normal shell. The make vpath statement is generated from the DMPATH array
that causes make to search for objects in the search path.

Windows template )ATTR )~.():

%.tgt : %.src
copy /Y $^ $@
)SET search=
)REP DMPATH
)SET search=~search. "~DMPATH."
)ENDR
vpath %.src ~search.
all: a.tgt b.tgt c.tgt
)SET DMEXECENV=%DM_ROOT.\dm_make.exe -f %s --no-cm

Messaging
When you run in asynchronous mode the steps communicate back to the PBEM using the
bldcomms utility. In both asynchronous and synchronous modes the PBEM then
communicates with Dimensions Build server to update it about the progress of the build.
Dimensions Build displays build messages in the Task column of the Build Monitor Events
section of the Build Job Details dialog box (which appears after you start a build).

You can specify messages for a particular step by providing the PBEM with a meaningful
description string that is used instead of the generic message. To supply a message, set
the variable DMTASKNAME to the required string and optionally add other variables:

Windows template )SET DMTASKNAME = Step %DMSTEP. - Compiling %SOURCE.

You can also send messages directly from the template that is executing to Dimensions
Build. The purpose of these messages is to report on the progress of long steps. For
example, a large make script could send a message for every sub-directory that it starts

242 Serena® Dimensions® CM 12.2.1

 High Level Build Templates

to build or for every target it creates. To send these types of messages use the bldcomms
utility but with different parameters:

Windows template bldcomms buildmessage %DMSERVER. 0 %DMTOKEN. 3 0 0 "END"

%DMSTEP. "Phase2" "Target1" "just built foo.exe" 0 "" "" "" ""

There are many parameters for bldcomms, however the key ones are the last three string
fields that you can be use for any message. The messages also appear in the Build
Monitor Events section of the Build Job Details dialog box. For more details about
bldcomms see the Dimensions CM Build Tools User’s Guide.

NOTE Due to limitations in the length of the PARM field you cannot use the above
technique with the MVS MDHLBLCM utility from an MVS build template.

Handling Outputs and Error Logs

You can use the build configuration or the Dimensions configuration file to specify how
outputs and errors from a running build step are treated. See the descriptions for the
following predefined template symbols:
 DMSAVESTDOUT on page 194.
 DMSAVESTDERR on page 194.
 DMCOMBINEOUTERR on page 192.

You can also use scripts to directly set the same variables:

Windows template )SET DMSAVESTDERR=YES

)SET DMSAVESTDOUT=YES

For a UNIX/Windows template these options refer to the stdout and stderr streams.

On MVS you can use the same flags but you need to use SBEM directives to insert the
specific data set names containing the listings or error reports into the BOM. You can also
choose the file to be used for the output. For example, in a compile you can specify a full
compile listing such as stdout or a smaller summary list.

MVS template )SET DMSAVESTDERR=NO

)SET DMSAVESTDOUT=YES
//….
//….
//SYSPRINT DD DISP=SHR,DSN=%CUR..ASMLIST(PROG)
//…
//*SBEM TGT SYSPRINT Assembly_Listing
//…

In the example above Assembly_Listing specifies a listing type for this target. Without
this SYSPRINT will be interpreted as a target and not a listing. This parameter is optional
and can have any value. If it is not defined the SBEM will consider it to be a normal target
such as a load module.

Developer's Reference 243

Chapter 9 Build Templates

Generating a Bill of Materials

If a procedure that performs a build is capable of collecting the mapping between inputs
and outputs, this information can be used to create a Bill Of Materials (BOM). A BOM is an
XML file that describes what was built and what it was built from. You can generate BOMs
with the SBEM on MVS, and with Openmake on all platforms.

NOTE The dependencies listed in a BOM can also refer to header files discovered during
a compile process that are not specified in a build configuration.

To generate a BOM you need to indicate the presence of the BOM to the PBEM by setting
the variable DMOBOMRPT to the data set name. The supplied PBEM and SBEM templates on
MVS create container PDSs that store the BOMs so that they are unique across parallel
steps and parallel builds. However, you can changed this to any scheme. The example
below uses different member names in a private PDS that already exists:

MVS template )SET DMBOMDSN=XXXX.YYYY.XML

)SET DMOBOMRPT=//%DMBOMDSN.(B%DMSTEP.)

This example triggers a different mode of output collection where the process is driven by
the contents of the BOM, and creates relationships between all the items listed in the
BOM. Without a BOM, only the items specifically mentioned in the build configuration will
be collected into Dimensions CM. For information about upload rules see the Process
Modeling User’s Guide. For information about virtual items see the User’s Guide.

Creating a BOM from the SBEM

The SBEM detects input files and generates a BOM under the control of directives that start
with //*SBEM. SBEM directives are DDNAME based and appear after the EXEC statement to
which they relate. The directives SRC, DEP, and TGT should appear before any DDNAMES
for that step.

END
//*SBEM END I=<step> T=<timestamp>
A single END directive indicates success or failure, brings the job to an end, and
sends a message to the PBEM. A common ending for an MVS template would be:

//….
)SET TIMESTAMP=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.
)SET TIMESTAMP=%TIMESTAMP.%DMSECOND.%DMMICROSEC.
//*SBEM END I=%DMSTEP. T=%TIMESTAMP.
)SET DMEXECENV=TEMPLATE TEMPLATE(MDHBSBM0)

CDE
//*SBEM CDE [MAX/IGNORE/FAIL]
Controls how the return code from the current step affects the return code for the
whole job.
• MAX accumulates the MAX code of all steps.
• IGNORE means this step does not count.
• FAIL means this step must return 0 or be considered a failure.

244 Serena® Dimensions® CM 12.2.1

 Compilation Templates

DEP
//*SBEM DEP DDNAME [(*)]
Creates a dependency. This is a file that the current process needs to work, such
as a copy book used during a Cobol compile.
You can manually add explicit dependencies, in which case the DDNAME must refer
to a readable file (rather than a container). In this case multiple DEP statements
are allowed.
If (*) is coded the SBEM will monitor disk activity on that DDNAME and look for
open members.

SRC
//*SBEM SRC DDNAME [(*)]
Similar to DEP but declares a DDNAME to be an input to the process. Usually this will
correspond to an item listed as an input in the build configuration. Note that this
names an actual input. By this stage the search path resolution has been
performed so that this becomes the name where the input is located even if it is
higher up the search path.

TGT
//*SBEM TGT DDNAME [(*)] [listing-type-name]
Similar to SRC and DEP. Usually used without (*) to indicate the DDNAME of the
step that is the output of the process, such as an OBJ deck from a compile.
Can be used with (*) in which case the SBEM will detect members written to that
DDNAME. The optional listing type name causes this output to be treated as a listing
type. The type name does not matter.

Compilation Templates
The main part of a compilation template is choosing the correct filenames for the inputs
and outputs according to the build configuration. There can be multiple inputs and outputs
of different types.

When you create a build configuration in Dimensions Build you can specify any names for
inputs and outputs. Templates that you write must honor those names. For each input of
a particular type find the name specified in the build configuration for that object. Then
search for that item in the search path, which is possibly a list of locations. This gives the
actual on-disk name of the object that you want to use as your input file.

The key to writing a compilation template is the operation of built-in functions and the
array variables that capture the essence of the configuration:
 DMPATH is an array of the search path. The first element is the build area where the
build is occurring.
 DMINPUT is an array of input files.
 DMTARGET is an array of target files.
 _MDHDSN_ is a function for dealing with the above arrays.
 _MDHEXTRACT_ is a function for dealing with individual filenames.

Developer's Reference 245

Chapter 9 Build Templates

The operations you typically see at the start of a compilation template are as follows.

Step 1 Locate the build area

Access the first element of DMPATH. Use the +d option of MDHEXTRACT for compatibility
with MVS and remove any bogus // symbols from the start of the name.

Windows template )SET CUR=_MDHEXTRACT_(+d,%(DMPATH(0)).)_

Step 2 Locate the source code

There can be more than one type of input. For each input required you need to get the
configuration name for that type and then search for the resulting name in the search
path.

Windows template )SET SRC=_MDHDSN_(,DMINPUT,C,DMPATH)_

Step 3 Get the target names for the outputs

There can be more than one output. For each output locate the configuration name for
that type. There is no need to search in the search path as the output is always
written to the build area.

Windows template )SET DST=_MDHDSN_(,DMTARGET,OBJ,)_

Step 4 Pull out the primary name

When compiling a file you may want to create objects based on the filename. For
example, if you are compiling foo.c you may want to create foo.pdb. You can
extract the name component of the filename using the following method:

Windows template )SET PRM=_MDHEXTRACT_(+n,%DST.)_

Note: You can also use %SRC.

Step 5 Perform the build

You now have all the variables required to do a build. The example below is a
distributed template that does a simple copy. All aspects of the build configuration are
honored. For example, it is not assumed that foo.c creates foo.obj. Both input and
output are named according to the configuration.

Windows template copy /y "%SRC." "%CUR.\%DST."

Windows Example
The example below is a complete Windows compilation template:

Windows template )SET CUR=_MDHEXTRACT_(+d,%(DMPATH(0)).)_

)SET SRC=_MDHDSN_(,DMINPUT,C,DMPATH)_
)SET DST=_MDHDSN_(,DMTARGET,OBJ,)_
)SET PRM=_MDHEXTRACT_(+n,%DST.)_
copy /y "%SRC." "%CUR.\%DST."
)IF %DMRUNMODE. = ASYNCH
bldcomms monitormessage %DMPBEMNODE. %DMPBEMPORT. "R=%%RC%% I=%DMSTEP.
T=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.%DMSECOND.%DMMICROSEC."
)ENDIF
)SET DMEXECENV=%%s

246 Serena® Dimensions® CM 12.2.1

 Compilation Templates

MVS Example
The process for writing compilation templates on MVS is very similar to that on Windows
as the template inline helper functions (MDHDSN and MDHEXTRACT) work on data sets as
well as files. The main difference is the actual build process, which uses JCL. In JCL you
typically create a concatenated DDNAME for the input sources and add SBEM directives to
pick up any additional inputs.

The example below is an Assembler template.

MVS template )CM ------------------------------------------

)CM --
)CM -- Assemble ASM(XXX) into OBJ(YYY)
)CM --
)CM ------------------------------------------
)CM ------------------------------------------
)CM -- OUTPUT
)CM ------------------------------------------
)CM
)SET DMSAVESTDERR=NO
)SET DMSAVESTDOUT=YES
)SET DMBOMDSN=SOMTHING.XML
)SET DMOBOMRPT=//%DMBOMDSN.(B%DMSTEP.)
)CM
)CM ------------------------------------------
)CM -- SRC / TARGET
)CM ------------------------------------------
)CM
)SET CUR=_MDHEXTRACT_(+d,%(DMPATH(0)).)_
)SET SRC=_MDHDSN_(,DMINPUT,ASM,DMPATH)_
)SET DST=_MDHDSN_(,DMTARGET,OBJ,)_
)SET PRM=_MDHEXTRACT_(+n,%DST.)_
)CM
)SET DMTASKNAME=Assembling (%SRC.)=>(%DST.)
)SET DMOSTDOUT=//%CUR..ASMLIST(%PRM.)
)CM
//*
//* %DMTASKNAME.
//*
)CM
)CM -------------------------------------------
)CM
)CM Asm JCL
)CM
)CM -------------------------------------------
)CM
)CM
//STEP100 EXEC PGM=ASMA90,PARM='LIST,OBJECT,TERM'
//SYSIN DD DISP=SHR,DSN=%SRC.
)SET NAME=SYSLIB
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+d,%DMPATH.)_
//%NAME. DD DISP=SHR,DSN=%THSDIR..ASM
)SET NAME=
)ENDR
// DD DISP=SHR,DSN=SYS1.MODGEN

Developer's Reference 247

Chapter 9 Build Templates

// DD DISP=SHR,DSN=SYS1.MACLIB
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSPRINT DD DISP=SHR,DSN=%CUR..ASMLIST(%PRM.)
//SYSTERM DD DISP=SHR,DSN=%CUR..ASMTERM(%PRM.)
//SYSLIN DD DISP=SHR,DSN=%CUR..%DST.
)CM
)CM -------------------------------------------
)CM
)CM SBEM Control
)CM
)CM -------------------------------------------
)CM
//*SBEM SRC SYSIN(*)
//*SBEM DEP SYSLIB(*)
//*SBEM TGT SYSLIN
//*SBEM TGT SYSPRINT Assembly_Listing
//*SBEM CDE MAX
)CM
)CM -------------------------------------------
)CM
)CM Call SBEM
)CM
)CM -------------------------------------------
)CM
)SET TIMESTAMP=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.
)SET TIMESTAMP=%TIMESTAMP.%DMSECOND.%DMMICROSEC.
//*SBEM END I=%DMSTEP. T=%TIMESTAMP.
)SET DMEXECENV=TEMPLATE TEMPLATE(MDHBSBM0)

Link Templates
A link template is similar to a compilation template. The main difference is that link
templates are mainframe only. The following lines perform the same function as they do
in a compilation template:

//*SBEM DEP OBJECT(*)

//*SBEM DEP LNKLIB(*)
//*SBEM DEP DEPENDCY(*)
//*SBEM DEP IMPORT(*)

The lines identify the DD names of the dependency modules you are interested in
discovering during the link. This process is done using a DESERV exit which is compatible
with DFSMSMVS 1.3 or above. While the link template is executing, this exit will monitor
all disk access performed on these DD names and report the data set and member names
that were accessed. This information is then returned to Dimensions via the BOM report.

248 Serena® Dimensions® CM 12.2.1

 Link Templates

Example
)CM (c) Serena 2008
)CM Common link template
)CM - implements footprinting
)CM - used by both MDHBLNK0 and MDHBLNK1
)CM
)IM TEMPLATE(MDHBSTD0)
)IFNDEF DMLNKMULTI
)SET DMLNKMULTI=NO
)ENDIF
)SET DMSAVESTDERR=NO
)SET DMSAVESTDOUT=YES
)SET CURDIR=%(DMPATH(0)).
)SET CURDIR=_MDHEXTRACT_(+r+n.+t,%CURDIR.)_
)SET DMOBOMRPT=//%DMBOMDSN.(B%DMSTEP.)
//*+------------------------------------------------------------------+
//** *
//** LINK - CONSTRUCT THE FINAL PRODUCT FROM THE SYSLIN DATA *
//** SUPPLIED BY THE APPLICATION *
//** *
//** The FOOTPRINT is information which describes the baseline *
//** or workset from which the dimensions components were used. *
//** *
//** This information is dropped into a CSECT which can be browsed *
//** or dumped at your leisure. *
//** *
//*+------------------------------------------------------------------+
)IFNDEF LPARM
)SET LPARM=
)ENDIF
//* Inputs:
)REP DMINPUT
//* Input - %DMINPUT.
)ENDR
//* Path:
)REP DMPATH
//* Path element - %DMPATH.
)ENDR
)SET SRCLOC=_MDHDSN_(,DMINPUT,SYSLIN,DMPATH)_
)SET SRCMOD=_MDHEXTRACT_(+n,//%SRCLOC.)_
)SET TGTMOD=_MDHDSN_(,DMTARGET,LOAD,)_
)SET DMTASKNAME=S%DMSTEP. Link %SRCMOD.
)SET DMOSTDOUT=//%CURDIR..LNKTERM(%SRCMOD.)
)IFDEF DMFOOTPRNT
)SET PRELKOPT=-f
)ELSE
)SET PRELKOPT=
)ENDIF
)IF %DMLNKMULTI. = NO
)SET UOPT=-u0
)ELSE
)SET UOPT=-u1
)ENDIF
//*

Developer's Reference 249

Chapter 9 Build Templates

//* LINK EDIT ALL THIS STUFF

//*
//PRELINK EXEC PGM=MDHLLNK0,
// PARM='POSIX(OFF),TRAP(OFF)/-t DD:MDHTTRC %PRELKOPT. %UOPT.'
//*SBEM SRC SYSLIN
//*SBEM DEP DEPENDCY(*)
//*SBEM CDE MAX
//TASKLIB DD DISP=SHR,
// DSN=%DMCDHLQ..%DMCDILQ..MDHLLIB
)IF %DMCDLPA. NE YES
// DD DISP=SHR,
// DSN=%DMCDHLQ..%DMCDILQ..MDHLLPA
)ENDIF
)IFDEF DMFOOTPRNT
//*
//* In dimensions 10.1.3 and later, if the
//* dd name MDHLDECK is present on the MDHLLNK0
//* step then a member which details all the link cards
//* as assembler source is written to member
//* LINKDECK.
//*
//* This can then be included by the assembler when
//* building the footprint
//*
//MDHLDECK DD DISP=(NEW,PASS),
// DSN=&&TEMPPDS,
// DSNTYPE=LIBRARY,
// RECFM=FB,LRECL=80,BLKSIZE=3120,
// DSORG=PO,
// SPACE=(TRK,(3,50)),
// UNIT=SYSDA
)ENDIF
)SET NAME=OBJECT
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..OBJ
)SET NAME=
)ENDR
)SET NAME=LNKLIB
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..LNKLIB
)SET NAME=
)ENDR
//SYSLIN DD DISP=SHR,DSN=%SRCLOC.
)SET NAME=DEPENDCY
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..DEPENDCY
)SET NAME=
)ENDR
)SET NAME=IMPORT
)REP DMPATH

250 Serena® Dimensions® CM 12.2.1

 Link Templates

)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..IMPORT
)SET NAME=
)ENDR
// DD DISP=SHR,DSN=CBC.SCLBSID
// DD DISP=SHR,DSN=CEE.SCEELIB
//SYSLMOD DD DISP=SHR,
// DSN=%CURDIR..%TGTMOD.
//MDHFLAT DD DISP=SHR,
// DSN=%CURDIR..MDHFLAT(%SRCMOD.)
//MDHLPRNT DD SYSOUT=*
//MDHTTRC DD SYSOUT=*
//*
)IFDEF DMFOOTPRNT
//*
//* Construct a foot print
//* - this can have several components
//*
//FPMAKE EXEC PGM=ASMA90,
// PARM='RENT,LIST,OBJECT'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSLIB DD DISP=SHR,DSN=SYS1.MACLIB
// DD DISP=(OLD,PASS),
// DSN=&&TEMPPDS
//SYSLIN DD DISP=(NEW,CATLG),
// DSN=%DMMVSUSR..TEMP.%DMUNIQUE..M%DMMICROSEC..FOOTPRNT,
// LRECL=80,BLKSIZE=3120,RECFM=FB,DSORG=PS,
// SPACE=(TRK,(2,5))
//SYSIN DD *
MDHAFOOT TITLE 'Footprint'
*
* The serena footprint is extensible - you can
* add your own sections if you want. All sections
* are described by a little table scanned by a vector
*
* TAble entires look like this
*
TABENT DSECT
FPSECT DC 0D
FPSECTVN DS CL8 'SERENA' for standard ones
FPSECTID DS CL8
FPSTART DC A(0)
FPLEN DC A(0)
TABENTLN EQU *-TABENT
MDHAFOOT AMODE 31
MDHAFOOT RMODE ANY
MDHAFOOT CSECT
DC CL24'SERENA FOOTPRINT'
FTPRNVEC DC A(SECTS,TABENTLN,SECTSE-TABENTLN)
*
* Table of footprint information

Developer's Reference 251

Chapter 9 Build Templates

*
SECTS DS 0D
DC CL8'SERENA '
DC CL8'CLASSIC '
DC A(OLDSTYLE)
DC A(OLDSTYLEE-OLDSTYLE)
*
DC CL8'SERENA '
DC CL8'FOOTPRNT'
DC A(NEWSTYLE)
DC A(NEWSTYLEE-NEWSTYLE)
*
DC CL8'SERENA '
DC CL8'SYSLIN '
DC A(SYSLIN)
DC A(SYSLINE-SYSLIN)
SECTSE EQU *
*
* Old style footprint (just a string) is here
*
OLDSTYLE DS 0D
)SLICE DMFOOTPRNT DMFOOT
)REP DMFOOT
DC CL32'%DMFOOT.'
)ENDR
OLDSTYLEE EQU *
*
* New style footprint (name of footprint doc
* checked into dimensions) goes here
*
NEWSTYLE DS 0D
)SLICE DMFOOTPRINTDOC DMFPNAME
)REP DMFPNAME
DC CL32'%DMFPNAME.'
)ENDR
DC CL1' '
NEWSTYLEE EQU *
*
* Link deck goes here
*
SYSLIN DS 0D
DC CL80'***START***'
COPY LINKDECK
DC CL80'***END***'
SYSLINE EQU *
END
/*
)ENDIF
//*
//* Link the lot
//*
//LINKEDIT EXEC PGM=IEWL,
// PARM='LET,LIST,MAP,XREF,TERM,OPTIONS=LNKOPT'
//*SBEM DEP OBJECT(*)
//*SBEM DEP LNKLIB(*)
//*SBEM DEP IMPORT(*)

252 Serena® Dimensions® CM 12.2.1

 Link Templates

)IF %DMLNKMULTI. = NO
//*SBEM TFP SYSLMOD(*)
)ELSE
//*SBEM TFP SYSLMOD(*)
)ENDIF
//*SBEM TGT SYSDEFSD(*)
//*SBEM TGT SYSPRINT Final_Link_Listing
//*SBEM CDE MAX
//LNKOPT DD *
)REP LPARM
%LPARM.
)ENDR
/*
//SYSPRINT DD DISP=SHR,
// DSN=%CURDIR..LNK2LIST(%SRCMOD.)
//SYSTERM DD DISP=SHR,
// DSN=%CURDIR..LNKTERM(%SRCMOD.)
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//CSSLIB DD DISP=SHR,DSN=SYS1.CSSLIB
//SYSDEFSD DD DISP=SHR,
// DSN=%CURDIR..IMPORT
//* USE AUTOCALL TO RESOLVE SYSTEM EXTERNALS ONLY
//SYSLIB DD DISP=SHR,DSN=ISP.SISPLOAD
// DD DISP=SHR,DSN=CEE.SIBMCALL
// DD DISP=SHR,DSN=CEE.SCEELKED
// DD DISP=SHR,DSN=CEE.SCEELKEX
// DD DISP=SHR,DSN=CEE.SCEECPP
// DD DISP=SHR,DSN=CEE.SCEELOCX
// DD DISP=SHR,DSN=ISP.SISPLOAD
)SET NAME=OBJECT
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..OBJ
)SET NAME=
)ENDR
)SET NAME=LNKLIB
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..LNKLIB
)SET NAME=
)ENDR
//SYSLIN DD DISP=SHR,
// DSN=%CURDIR..MDHFLAT(%SRCMOD.)
)IFDEF DMFOOTPRNT
//MDHAFOOT DD DISP=(OLD,DELETE),
// UNIT=SYSDA,
// DSN=%DMMVSUSR..TEMP.%DMUNIQUE..M%DMMICROSEC..FOOTPRNT
)ENDIF
)SET NAME=DEPENDCY
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_

Developer's Reference 253

Chapter 9 Build Templates

//%NAME. DD DISP=SHR,
// DSN=%THSDIR..DEPENDCY
)SET NAME=
)ENDR
//SYSLMOD DD DISP=SHR,
// DSN=%CURDIR..LOAD
)SET NAME=IMPORT
)REP DMPATH
)SET THSDIR=_MDHEXTRACT_(+r+n.+t,%DMPATH.)_
//%NAME. DD DISP=SHR,
// DSN=%THSDIR..IMPORT
)SET NAME=
)ENDR
// DD DISP=SHR,DSN=CBC.SCLBSID
// DD DISP=SHR,DSN=CEE.SCEELIB
//*
//* DUMP LINK LISTING TO PAPER
//*
//LNK2LIST EXEC PGM=IEBGENER
)SET TIMESTAMP=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.
)SET TIMESTAMP=%TIMESTAMP.%DMSECOND.%DMMICROSEC.
//*SBEM END I=%DMSTEP. T=%TIMESTAMP.
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT1 DD DISP=SHR,
// DSN=%CURDIR..LNK2LIST(%SRCMOD.)
//SYSUT2 DD SYSOUT=*
)SET DMEXECENV=TEMPLATE TEMPLATE(MDHBSBM0)

Collection Templates
A collection template is similar to a compilation template, the main difference is an
iteration over all the inputs of the same type. For example, a normal OBJ link receives a
variable sized array of input OBJs to be linked together. The template loops over this array
and generates the correct link control cards. This is called a collection step.

Windows Example
The example below shows the key part of a Windows link template that constructs a list of
inputs that can be given to a link or copy command. Note the use of the MDHDSN function
to locate a given filename. This time only the first and fourth parameters of MDHDSN are
set, which look for a given default name in a search path.

Windows template )SET LIST=

)REP DMINPUT
)SET SRC=_MDHDSN_(%DMINPUT.,,,DMPATH)_
)SET LIST=%LIST. "%SRC."
)ENDR

254 Serena® Dimensions® CM 12.2.1

 Collection Templates

MVS Examples
On MVS for a link you may need to generate a list of INCLUDE statements. You may also
want to add the DMPATH list of object libraries to SYSLIB.

The example below generates a concatenated input DD of all the files using the technique
described in "Handling Array Variables" on page 239. Note the similar use of MDHDSN to
the Windows example above.

MVS template )SET DD=//SYSUT1 DD

)REP DMINPUT
)SET SRC=_MDHDSN_(%DMINPUT.,,,DMPATH)_
%DD. DISP=SHR,DSN=%SRC.
)SET DD=// DD
)ENDR

The example below is extracted from a link template, the key part generates a list of
INCLUDE statements:

MVS template )REP DMINPUT

)SET SRC=_MDHEXTRACT_(+n,%DMINPUT.)_
INCLUDE MYOBJS(%SRC.)
)ENDR

The example below is a DDNAME of all the OBJ search path locations:

MVS template )SET DD=//MYOBJS DD

)REP DMPATH
%DD. DISP=SHR,DSN=%DMPATH..OBJ
)SET DD=//
)ENDR

This example allows you to construct a link JCL that is responsive to the build
configuration and does not require pre-defined link decks to be checked in as source
items.

Another possible link model, one of many, is to treat the link instructions as a source item
and the primary input to the link. This method works well if the input dependencies are
detected by the SBEM.

Mixed Inputs
In the above examples it is assumed that all the inputs in the DMINPUT array are the OBJs
that you require. If there are other inputs in the configuration of a different type, such as
a configuration named side-file, DBRM or similar, the loops around DMINPUT have to be
enhanced to only select entries of the correct type. The example below, based on the
Windows example, shows you how to do this:

Windows template )SET LIST=

)REP DMINPUT
)SET TYPE=_MDHEXTRACT_(+t,%DMINPUT.)_
)IF %TYPE.=OBJ
)SET SRC=_MDHDSN_(%DMINPUT.,,,DMPATH)_
)SET LIST=%LIST. "%SRC."
)ENDIF
)ENDR

Developer's Reference 255

Chapter 9 Build Templates

The process is similar on MVS. Note that even though this is a link style collection
template you can use patterns from compilation templates. For example, if the input array
contains a single side file of the type SYSDEFSD that is needed in the link, its name can be
found from the MDHDSN function, as used in the compilation examples:

MVS template )SET SIDE=_MDHDSN_(,DMINPUT,SYSDEFSD,DMPATH)_

z/OS Return Codes

When an MVS build job executes, each build template is expanded and passed to the
SBEM for execution. The SBEM then executes each step of the task. Prior to Dimensions
10.1.3, if a step completed and had a non-zero return code, but this code was equal to or
less than DMMAXRC, the SBEM would silently continue with the execution of the task.
Commencing with Dimensions 10.1.3, if you specify the build symbol
DM_BUILDER_PROGRESS_REPORTING (the default is ’YES’) then any step that has a non-
zero return code causes the SBEM to issue the following message with a severity of W:

MDHSB16D112W Step <step number> Program <program> returned COND CODE = <cc>
’I’ messages are not sent back to the build log. However, ’W’ messages are sent to the log
therefore these steps are signalled to the log as an alert.

TIP If you name the steps carefully in the template you can give users a clear
understanding of the nature of the warnings.

Miscellaneous Examples of Using Build Templates

Using REXX in a Template

Although the UNIX REXX environment gives efficient access to HFS files, the best way to
get to data sets is to use an "MVS" environment that gives access to EXECIO. The
following example template JCL shows how to do this (refer to the annotated version
below for details):

Template JCL //*

//* <<<<< REXX START
//* <<<<< REXX START
)SET SERENA=_MDHDSN_(,DMINPUT,COB,DMPATH)_
)SET SERENA=_MDHEXTRACT_(+d,%SERENA.)_
)EXPAND %%s
/* rexx */
say ")EXPAND"
say "//* Hi from rexx" date()
call bpxwdyn "alloc fi(stu) da('%SERENA') shr reuse"
address mvs 'execio * diskr stu (fini stem s.'
say ")VECTOR LINES("s.0")"
say ")SET LINECOUNT = "s.0
do i=1 to s.0
say ")SET LINES("i-1") = "strip(s.i)

256 Serena® Dimensions® CM 12.2.1

 Miscellaneous Examples of Using Build Templates

say "//*" i-1") = "left(s.i,20)

end
exit 0
)ENDEXPAND
)EXPAND
//* <<<<< REXX END
//* <<<<< REXX END
//*

Annotated version

1 //*
//* <<<<< REXX START
//* <<<<< REXX START
The top of the template.

2 )SET SERENA=_MDHDSN_(,DMINPUT,COB,DMPATH)_
Set the variable SERENA to the filename of the Cobol input file. Rather
than hard code the name, use the inbuilt facilities for finding it. The above
statement searches for an entry of type COB in the array DMINPUT. (If
your type is different, you'll have to change this.)

Assuming the statement finds that one of your inputs is indeed of type
COB, it will then search for this in the search path array DMPATH. This is
important when reading in files like this, as you don't know in advance
where the build is going to find the member; for example, it may be in
RELEASE.

NOTE
The above statement is also available in UNIX and Windows templates,
and works in a similar way.

3 )SET SERENA=_MDHEXTRACT_(+d,%SERENA.)_
The return from this function is a name suitable for use in UNIX allocates,
which means it will have '//' at the front, which we don't want. The
above statement "normalizes" the name into regular JCL syntax.

If you do not have a file of type COB as an input to this step, or it cannot
be found on disk, then the result is the string <NULL>, which you could
test for if you wanted. This string will give an JCL error (which is good, as
you want the build to fail in this case).

NOTE
The above statement is also available in UNIX and Windows templates,
and works in a similar way.
4 )EXPAND %%s
Start an EXPAND block that specifies a script (in this case it is just the
name of the file itself, %%S, as this will be executable in its own right). The
double '%%' is to protect the '%'from template expansion. (%% becomes
%).
This must not appear inside of a )REP, as that doesn't work.

Developer's Reference 257

Chapter 9 Build Templates

5 /* rexx */
Start of the Rexx itself.

6 say ")EXPAND"
say "//* Hi from rexx" date()
Get Rexx to emit the ')EXPAND' instruction. This means that when the
templater processes the output from Rexx, it will expand it as if it were
further template lines, rather than just literal text.
7 call bpxwdyn "alloc fi(stu) da('%SERENA.') shr reuse"
Use BPXWDYN as a stand in for the TSO allocate command (remember that
we are not in a TSO environment at this point.). This is basically a
wrapper around the IBM SVC99 dynalloc function. The template variable
SERENA is set above to be the full data set name of the input file.
NOTE
Documentation for BPXWDYN (the IBM Dynamic Allocation Text interface)
can be found at:
ftp://ftp.software.ibm.com/s390/zos/tools/bpxwdyn/
bpxwdyn.html

8 address mvs 'execio * diskr stu (fini stem s.'

The DDNAME (stu) is now pointing at the COB source file. This is read into
a rexx stem variable using a facility that emulates the TSO EXECIO
command.

The rexx stem called 's' now contains lines from the file. You can do
whatever we like with this data. In the remainder of this example, it is
demonstrated how you would put this data into some templater variables,
so the lines would be available direct from JCL using a )REP command. At
this point, you could do any rexx based logic you liked, and set flag
variables in a similar fashion.

9 say ")VECTOR LINES("s.0")"

Creates a template array called LINES of the right size.

10 say ")SET LINECOUNT = "s.0

Creates a template variable containing the size, in case that is needed as
well.

11 do i=1 to s.0
Loop round each line of the file.

12 say ")SET LINES("i-1") = "strip(s.i)

Assign an individual line. Template arrays start at 0; rexx arrays start at
1.

258 Serena® Dimensions® CM 12.2.1

 Miscellaneous Examples of Using Build Templates

13 say "//*" i-1") = "left(s.i,20)

Optional debug line. This provides some visual confirmation in the output
JCL that rexx actually did something.
NOTE
It would be advisable to omit this line if the input is a large Cobol
program.

14 end
End of loop.

15 exit 0
End of rexx.

16 )ENDEXPAND
End of expand block.

The procedure is now back in templater mode, having finished with rexx.
It is also now in non-expand mode, as a by-product of the above
statement.

17 )EXPAND
Turn expand mode back on to enable further template syntax to be used.

18 //* <<<<< REXX END

//* <<<<< REXX END
The JCL template can now be continued, but now there are more variables
available for use.

20 //*
//* Cobol source is %LINECOUNT. lines long
//*
An example of using the new knowledge about the build input file.

Invoking the REXX Interface

For performance reasons, Serena recommends using the interface to invoke REXX.
However, you can still use REXX as described above.

)SCRIPT MDHDREXX.REXX
..
..
..
)ENDSCRIPT

Developer's Reference 259

Chapter 9 Build Templates

Usage rules:
 Instead of "say" use "call mdhsay".
 Instead of "exit", use "return”.
 Do not define any REXX signal handlers.
 If you define a procedure, add "expose (mdhexpose)" to the definition.
 If you need to send a MsgX message, use "call mdherr 'MDHREX4700001E ...'"

Example This example turns http://www.something.com/remaining into just "something"

)SET URL=http://www.serena.com/splat/bim/bam
)SCRIPT MDHDREXX.REXX
url="%URL."
parse var url "http://" . "." company "." .
call mdhsetvar "COMPANY",company
)ENDSCRIPT
COMPANY = %COMPANY.

Example This example reverses the slashes, "/" to "\" in an array:

)VECTOR DMPATH(5)
)SET DMPATH(0)=/a/1/x/fo.c
)SET DMPATH(1)=/b/2/x/fo.c
)SET DMPATH(2)=/c/3/x/fo.c
)SET DMPATH(3)=/d/4/x/fo.c
)SET DMPATH(4)=/e/5/x/fo.c
)SCRIPT MDHDREXX.REXX
i=0
)REP DMPATH
tmp = "%DMPATH."
tmp=translate(tmp,"\","/")
call mdhszy ")SET DMPATH("i")="tmp
i=i+1
)ENDR
)ENDSCRIPT
)REP DMPATH
%DMPATH.
)ENDR

260 Serena® Dimensions® CM 12.2.1

Chapter 10
Openmake Templates

Introduction 262
Variables 263

Developer's Reference 261

Chapter 10 Openmake Templates

Introduction

NOTE
 For information about the templating language and syntax see page 177.
 For information about Dimensions Build see the Dimensions CM Build Tools User’s
Guide.
 For information about using Openmake see the documentation that was installed
with the product.

To support the integration between Dimensions Build and Openmake, Serena®

Dimensions® CM ships with the following Openmake build templates:
 MVS: TEMPLATE(MDHBOMT0)
 Windows and UNIX: om_build.template

The default template directory is <install root>/templates.

The integration flow between Dimensions Build and Openmake is as follows:

1 The build configuration, and other parts of Dimensions CM, make available variables
that describe the build that is to be executed.

2 These variables are used by the Openmake templates to construct commands to

invoke the two Openmake utilities, bldmake and om (note that the Openmake
knowledgebase server must be set up correctly).

3 When the Openmake utilities have completed (the template has finished executing),
the build steps created by Openmake are run. You can monitor these steps from the
Openmake knowledgebase server.

4 The final om build step communicates to Dimensions Build that the build has
completed.

5 By this stage Openmake build steps have created a BOM (bill of materials) containing
a description of all the inputs and outputs in the build. The name of this file is passed
back to Dimensions Build so that the BOM to be picked up, parsed, and the relevant
target items collected into Dimensions CM.

In the flow above the BOM is created after the entire build submitted by om has
completed. These jobs are run asynchronously with respect to Openmake.

262 Serena® Dimensions® CM 12.2.1

 Variables

Variables
The input to the Openmake template is a set of variables. The table below lists the
variables and their source. Some of the variables are unique to Openmake and are
provided by the build configuration as area or configuration symbols. Most of the variables
are described in one of the following documents:
 Chapter 8, "The Templating Language and Processor" on page 177.
 The Serena Dimensions CM Administrator’s Guide.

Key to the abbreviations used in the table

 Platform:
• *—all
• M—MVS
• U—UNIX
• W—Windows
 Optional: optional variable or symbol
 Source:
• config—the build configuration
• build—created by the build server
• cfg—dm.cfg (the Dimensions configuration file)
• sys—provided by the system
• out—output (a variable created for use by the caller).

Variable or Symbol Platform Optional Source Description

ANT_HOME U Yes config The PATH and ANT_HOME environment
variables
DM_CURRENT_USERNAME M build The current Dimensions Build user (used
for the Openmake knowledgebase server
log in).
DM_LICENSE WU Yes cfg Environment variable for
SERENA_LICENSE_FILE
DM_META_DATASET M cfg MVS listener metadata
DM_META_LOCK_MAJOR M cfg MVS listener metadata
DM_META_LOCK_MINOR M cfg MVS listener metadata
DM_OM_OSPLATFORM W config Control file (-f option) for Openmake
DM_OPENMAKE_INSTALL * Yes cfg Default fallback for DMOMINSTALL
DM_OPENMAKE_SERVER * Yes cfg Default fallback for DMOMSERVER
DM_ROOT WU cfg Dimensions root installation
DM_TPLB_MACHINE M Yes cfg Default fallback for DMMACHINE
DM_TPLB_PUBLIC M Yes cfg Default fallback for DMPUBLIC

Developer's Reference 263

Chapter 10 Openmake Templates

Variable or Symbol Platform Optional Source Description

DMBLDLOGURL U out Openmake URL
DMBLDMAKE_OPTIONS * Yes config bldmake options
DMBLDPROJ * config Openmake project name
DMCDHLQ M cfg High level qualifier from the installation
DMCDILQ M cfg Intermediate level qualifier from the
installation
DMCDLPA M cfg LPA mode
DMCLEANBUILD M cfg Request cleanup
DMDAY * sys Date (day)
DMDIRECTORY * sys Build location
DMHOUR * sys Date (hour)
DMINHLQ M cfg Instance HLQ
DMINST M cfg Instance mid level qualifier
DMMACHINE * build Machine name (DNS) of node
DMMICROSEC * sys Date (microseconds)
DMMINUTE * sys Date (minute)
DMMONTH * sys Date (month)
DMMVSUSR M sys MVS system username RACF
DMOBOMRPT * out BOM location
DMOMDATETIME * build bldmake -ld parameter
DMOMINSTALL * Yes config Openmake installation path

DMOMSERVER * Yes config Openmake knowledgebase server address

DMOPTIONS * Yes config om options
DMOSPLATFORM U config Control file (-f option) for Openmake
DMPBEMNODE * sys TCP/IP node address of controlling PBEM
DMPBEMPORT * sys TCP/IP port the PBEM is listening on
DMPUBLIC * config Public build job (true or false)
DMRUNMODE UW sys SYNC or ASYNC
DMSEARCHPATH * config Openmake search path name
DMSECOND * sys Date (seconds)
DMSECONDS * sys Date (seconds)
DMSEQ9 * sys Build sequence number
DMSTEP * sys BRD step number in a build
DMSYSUSR M sys System user
DMTARGET * config Array of target objects
DMUNIQUE * sys Unique identifier for a run

264 Serena® Dimensions® CM 12.2.1

 Variables

Variable or Symbol Platform Optional Source Description

DMUSER * sys Dimensions CM user
DMYEAR * sys Date (year)
JAVA_HOME U Yes config Dimensions environment variable

Developer's Reference 265

Chapter 10 Openmake Templates

266 Serena® Dimensions® CM 12.2.1

Chapter 11
Remote Job Execution Templates

Introduction 268
Templates 268
Simple Synchronous Templates 268
Asynchronous Remote Jobs 270
Remote Job Template Example 271

Developer's Reference 267

Chapter 11 Remote Job Execution Templates

Introduction
The Serena® Dimensions® CM REXEC command creates a remote job on a Dimensions CM
node. You can view the details of remote jobs in the Remote Jobs cluster in the
administration console, for details see the Administrator’s Guide or the administration
console help.

You can also manage remote jobs from the command line using the commands REXEC,
RDEL, and RSTAT, for details see the Command-Line Reference.

Templates
Remote job execution templates are expanded and executed on the node specified in the
REXEC command. The templates use the syntax and variables described in "The
Templating Language and Processor" on page 177. However, these are not build
templates and build specific variables are not available.

Remote job execution templates are located in the system directories specified by the
remote node dm.cfg variable DM_TEMPLATE_CATALOGn. For details about this variable see
page 215.

Parameters
The REXEC system delivers a set of variables to the template that contain information
about the context of the request. The system can also deliver additional parameters that
you can supply using the /PARAM option of the REXEC command. You can use this
technique to define remote subroutines and supply them with varying arguments at run
time.

Parameters that you supply can be single values or arrays, for example:
 Template test.tpl:

echo VALUE is %VALUE.

)REP INPUT
echo "array line is %INPUT." >>c:\temp\foobar.log
)ENDR
 Invocation using REXEC:

REXEC /template=test.tpl /network=node /

param="VALUE=hello,INPUT=[one,two,three]"

Simple Synchronous Templates

The /NOBATCH and /NOCAPTURE options of the REXEC command create simple
synchronous templates. These templates run quickly, the REXEC command waits for
completion, and the return code is available and reported. A remote job entry is not
created in the administration console as the templates will have already finished. Simple

268 Serena® Dimensions® CM 12.2.1

 Simple Synchronous Templates

synchronous templates do not connect back to the Dimensions CM server, and you cannot
use MVS batch JCL.

Feedback
Synchronous templates generate two types of feedback:
 Numeric return code is reported and corresponds to the exit status of the script. 0 is
considered success.
 An error string is also collected and is reported at the command prompt in the event
of a failure. You can use error strings to communicate template expansion time errors.
To see this error message, the return code has to be non-zero.

The example below is a synchronous template that returns an expansion time error
message:

)SET DMERRMSG=Current user is %DMREMOTEUSER.

exit 5

When this template is executed from the REXEC command the message is displayed as
feedback. You can use this feature for messages other than error messages, as shown in
the example above. The template expansion process can use shell or Perl scripts therefore
you can make it as complicated as required.

You can also use this feature to send back listings from the remote node. The template
can allocate DMERRMSG as an array, and fill it with lines of output.

The example below is a synchronous REXEC template that returns the environment
variable PATH list in the DMERRMSG array to be displayed at the command prompt. This is
a UNIX example that uses an embedded Perl script during the template expansion time.

)VECTOR DMERRMSG(20)
)EXPAND perl %%s
print ")EXPAND\n";
@dirs = split(/:/,$ENV{'PATH'});
$i=0;
foreach $dir (@dirs)
{
print ")SET DMERRMSG($i) = $dir\n";
$i=$i+1;
}
)ENDEXPAND
)EXPAND
exit 5

The following command transcript shows an REXEC command from a Windows system
executing the above template on a Linux node. Note that inside the message feedback
from REXEC is the array of PATH locations in the UNIX host.

C:\temp>dmcli
Serena Dimensions CM 10.1.0 FT1 at 20:32:08 Wednesday 09 August 2006
Copyright (c) 1988-2006 Serena Software, Inc. All rights reserved.
Dimensions>auth /network=suse /user=xxx /password=xxxx
Operation completed
Dimensions>rexec /nobatch /nocapture /network=suse /template=t.txt
execute expanding script, cmd= perl /tmp/tpl11832-1.sh
Passing the template for execution

Developer's Reference 269

Chapter 11 Remote Job Execution Templates

cmd = /bin/sh "/tmp/tpl21832-2.sh" >/dev/null 2>/dev/null

/opt/serena/changeman/dimensions/10.1//prog
/usr/bin
/bin
.
/opt/oracle/product/10g/bin
Template processing complete and command submitted: user result code
1280
Job R-4197028 FAILED - rc(1280) errno(0)
Operation completed
Dimensions>

The return code above (1280) is 0x500. This is the UNIX shell exit code in the high word
of the result code, and importantly it is not zero.

The DMERRMSG variable is relevant during template expansion time and not during script
execution time. In the example above the Perl script does run at expand time because it is
an inline script and not an execution script. For details about template expansion see page
205.

Asynchronous Remote Jobs

The /BATCH option of the REXEC command creates an asynchronous process on the
remote node. The REXEC call returns immediately and the process is left running. The
/CAPTURE option causes the generation of the DMCERTIFICATE variable, which allows the
template to connect back to Dimensions CM to report progress. The template can use the
session established with the certificate to perform any action, such as execute CI
commands to move files into Dimensions CM control.

The command most associated with a template connecting back to Dimensions CM is

RSTAT. RSTAT allows the script to update the job table with status information allowing
you to see how the asynchronous process progressed. Return code information and a
message can also be reported. If a local file name is supplied it is collected by
Dimensions CM and loaded as messages into the job log display in the administration
console. You can issue the RSTAT manually to update a job, but normally it is issued by a
template. To use the certificate, a template can use the dmcli program with the -cert
option to log in to the originating server.

The MVS JCL equivalent uses the batch command program, MDFLCMD. However, the
certificate on MVS is longer than 80 bytes. To use it with JCL, use the slice option to split
it into an array suitable for use as instream JCL input.

The examples below show a method of connecting back to Dimensions CM from a

template, performing actions, and then using RSTAT:
 This Windows example uses a command string directly on the dmcli command line:

)IF %DMASYNC. = YES

dmcli -cert "%DMCERTIFICATE." -cmd "rstat %DMJOBID. /
description=\"example rstat command\" "
)ENDIF
exit 0
 This example uses MVS JCL. Note the use of DMNODE. An automatic AUTH to this
node is performed by the certificate handling mechanism:

270 Serena® Dimensions® CM 12.2.1

 Remote Job Template Example

//CALLB EXEC PGM=MDFLCMD,

// PARM=('POSIX(ON),ENVAR(""_CEE_ENVFILE=DD:DIMVARS"")',
// '/')
//STEPLIB DD DISP=SHR,DSN=%DMLLIB.
)IF %DM_USE_LPA. = NO
// DD DISP=SHR,DSN=%DMLLPA.
)ENDIF
//DIMVARS DD DISP=SHR,DSN=%DMDIMVARS.
//CEEPRINT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//LOGIN DD DATA,DLM=ZZ
/CERTIFICATE
)REP DMCERTIFICATEPARTS
%DMCERTIFICATEPARTS.
)ENDR
ZZ
//COMMAND DD *
RSTAT %DMJOBID. -
/STATUS=SUCCEEDED -
/RC=0 -
/DESCRIPTION="Job has run to completion" -
/RESPONSE_FILE="DMNODE::DATASET.NAME(MEMBER)"
/*

Remote Job Template Example

The example below pulls a remote directory into Dimensions CM. The command is sent by
REXEC to a remote machine, with parameters that describe the directory (for example,
c:\temp) and file pattern (for example, *.txt) that are required. The remote script
connects back to Dimensions CM to issue CI commands, and then uses RSTAT to update
the remote job status.

After issuing the command, the results are displayed in the administration console and
the output log from the individual Dimensions CM commands is available in the Job
Details/Job log view.

This is the directory on the remote machine:

C:\temp>dir
Volume in drive C has no label.
Volume Serial Number is A8CE-8883

Directory of C:\temp

08/10/2006 03:09 PM <DIR> .

08/10/2006 03:09 PM <DIR> ..
08/10/2006 12:30 PM 131 a.txt
08/10/2006 10:42 AM 34 list.txt
08/10/2006 02:15 PM 125 log.txt
08/10/2006 10:55 AM 417 out.txt
08/10/2006 11:36 AM 198 stupl1.pl

Developer's Reference 271

Chapter 11 Remote Job Execution Templates

08/10/2006 02:15 PM 203 stupl2.pl

08/10/2006 09:53 AM 21,951 testlog.txt
08/10/2006 12:09 PM 79 zlist2.txt
08/10/2006 12:09 PM 0 zlist3.txt
08/10/2006 12:08 PM 20 ztest1.bat
10 File(s) 23,158 bytes
2 Dir(s) 2,790,297,600 bytes free
C:\temp>

The REXEC command is issued from another machine:

Auth /network=nodename /user=xxxx /password=xxxxx

rexec /network=nodename /template=grabdir.tpl /capture /
PARAM="P_DIR=c:\temp,P_PAT=*.txt,P_PROD=PAYROLL,P_PART=PAYROLL"

The REXEC returns. Inspection of the remote job queue shows that the job has finished
and additional log records are available:

272 Serena® Dimensions® CM 12.2.1

 Remote Job Template Example

Inspection of Dimensions CM shows that the items have been created:

The grabdir.tpl template shown below is for Windows, though you can port it easily to
UNIX. Although this is a Windows example, it uses Perl. To try this example, make sure
you have a version of Perl in your path. Note that there is a dm.cfg symbol on the server
controlling how many lines of log output can be attached to a remote job. Set
DM_REXEC_RESPONSE_MAX_LINES to a small number (about 50) to ensure that rouge
scripts do not fill the database with output.
)CM
)CM ===========================================================================
)CM grabdir
)CM ===========================================================================
)CM
)CM Example REXEC template
)CM
)CM Windows version
)CM
)CM 1. Lists contents of a given directory with a DOS pattern
)CM 2. For each file, creates an item in Dimensions, using supplied parameters
)CM 3. Updates remote job, and supplies the trace as a response file.
)CM
)CM Parameters:
)CM
)CM P_DIR - directory on remote node, ending in "\"
)CM P_PAT - pattern (dos format)
)CM P_BASE - base name to generate new items
)CM P_PROD - Product name
)CM P_TYPE - item type
)CM P_FORM - item format
)CM P_PART - design part
)CM P_WSD - Workset directory. If present, should end in a "/"
)CM P_CLEAN- delete working files
)CM
)CM ===========================================================================
)CM

)SET DMSAVESTDOUT=Y
)SET DMSAVESTDERR=Y
)SET DMCOMBINEOUTERR=Y

)CM
)CM ===========================================================================
)CM default the parameters
)CM ===========================================================================
)CM

)IFNDEF DM_TMP

Developer's Reference 273

Chapter 11 Remote Job Execution Templates

)SET DM_TMP=c:\temp
)ENDIF

)IFNDEF P_DIR
)SET P_DIR=c:\temp\
)ENDIF

)IFNDEF P_PAT
)SET P_PAT=*.txt
)ENDIF

)IFNDEF P_BASE
)SET P_BASE=auto
)ENDIF

)IFNDEF P_PROD
)SET P_PROD=payroll
)ENDIF

)IFNDEF P_TYPE
)SET P_TYPE=txt
)ENDIF

)IFNDEF P_FORM
)SET P_FORM=src
)ENDIF

)IFNDEF P_PART
)SET P_PART=payroll
)ENDIF

)IFNDEF P_WSD
)SET P_WSD=
)ENDIF

)CM
)CM ===========================================================================
)CM create our perl script
)CM ===========================================================================
)CM

)EXPAND type %%s > "%DM_TMP.\perl-%DMUNIQUE..pl" 2>NUL:

$PDIR=$ARGV[0];
$PTMP=$ARGV[1];
$i=0;
while (<STDIN>)
{
$line=$_;
chomp $line;
print "CI \"%P_PROD.:%P_BASE.$i %P_TYPE..a-%P_FORM.\" /keep /format=%P_FORM. /filename=%P_BASE.$i /
part=%P_PART. /ws_filename=\"%P_WSD.$line\" /user_filename=\"$PDIR$line\" \n";
$i=$i+1;
}
print "RSTAT %DMJOBID. /description=\"grabdir example template\" /status=succeeded /rc=0 /
response_file=\"$PTMP\\log-%DMUNIQUE.txt\" ";
)ENDEXPAND
)EXPAND

)CM
)CM ===========================================================================
)CM create the input file for the perl script
)CM ===========================================================================
)CM

)EXPAND "%%s" >NUL: 2>NUL:

dir %P_DIR.%P_PAT. /B > "%DM_TMP.\input-%DMUNIQUE..txt"
)ENDEXPAND

274 Serena® Dimensions® CM 12.2.1

 Remote Job Template Example

)EXPAND

)CM
)CM ===========================================================================
)CM create the Dimensions commands
)CM ===========================================================================
)CM

)EXPAND "%%s" >NUL: 2>NUL:

perl "%DM_TMP.\perl-%DMUNIQUE..pl" "%P_DIR.\" "%DM_TMP.\" < "%DM_TMP.\input-%DMUNIQUE..txt" > "%DM_TMP.\output-
%DMUNIQUE..txt"
)ENDEXPAND
)EXPAND

)CM
)CM ===========================================================================
)CM EXECUTE
)CM ===========================================================================
)CM

dmcli -cert "%DMCERTIFICATE." < "%DM_TMP.\output-%DMUNIQUE..txt" >"%DM_TMP.\log-%DMUNIQUE.txt" 2>&1

)CM
)CM ===========================================================================
)CM cleanup
)CM ===========================================================================
)CM

)IFDEF P_CLEAN
del "%DM_TMP.\perl-%DMUNIQUE..pl"
del "%DM_TMP.\input-%DMUNIQUE..txt"
del "%DM_TMP.\output-%DMUNIQUE..txt"
del "%DM_TMP.\log-%DMUNIQUE.txt"
)ENDIF

exit 0

Developer's Reference 275

Chapter 11 Remote Job Execution Templates

276 Serena® Dimensions® CM 12.2.1

Chapter 12
Deployment Area Scripts

Introduction 278
Variables 280
Differences in Relation to Build Templates 282
Debugging 282
Other Features 282
Example 283

Developer's Reference 277

Chapter 12 Deployment Area Scripts

Introduction

NOTE For information about the templating language and syntax see Chapter 8, "The
Templating Language and Processor" on page 177.

You can attach the following types of templates to a deployment area:

 Pre-event transfer script
 Post-event transfer script
 Fail-event transfer script

Use these scripts when you require detailed control of a deployment, for example, to
insert rows into an external database, or to perform a bind operation on a deployed
object. The pre and post event scripts enable you to control the timing of these
operations. In the event of a failure the fail-event transfer script enables you to roll back
any external changes that you made.

NOTE
 As of Serena® Dimensions® CM 10.1.1, the Dimensions CM server runs the scripts
on the node hosting the area in bulk once per command, as opposed to once per
item, which was the case for previous Dimensions CM releases. As before, when a
DPI command results in a single item transfer into one area, then transfer scripts will
be executed before and after the item transfer into the area. However, when a DPR or
a DPB command results in multiple item transfers into one area, then:
• The pre-event transfer script will be executed once before any items are
transferred into the area.
• The post-event transfer script will be executed once after all items are
successfully transferred into the area.
• The fail-event transfer script will be executed once if there were any errors
transferring items into the area or the post script failed to execute successfully.
Bulk script execution results in significant improved deployment performance.
 You can store area scripts in your Dimensions repository. However, the preferred
location is on the node where the deployment area is located, in the system template
folder specified by the Dimensions configuration file (dm.cfg) symbol
DM_TEMPLATE_CATALOGn. For details about this variable see page 215. Note that this
is the configuration file that belongs to the node and not to the Dimensions server.
 Areas scripts are implemented differently from build templates, which you can
execute from a build area using search paths.

278 Serena® Dimensions® CM 12.2.1

 Introduction

Changes Introduced in Dimensions CM 12.2.1

Changes to deployment scripts were introduced in Dimensions CM 12.2.1, some of which
are significant, particularly for MVS users.
 Deployments are now REXEC jobs therefore the RLIST and RDEL commands can be
used.
 For MVS, the old behavior for deployment scripts was ’fire-and-forget’. The new
default behavior is to wait for the script to connect back to Dimensions and mark the
script as successful or unsuccessful. There are new symbols in dm.cfg to control this
processing:
• DM_WAIT_FOR_MVS_DEPLOYMENT_SCRIPT (Y/N): sets or clears waiting for MVS
deployments.
• DM_MAX_MVS_DEPLOY_SCRIPT_WAIT n: sets the maximum number of seconds
that an MVS deployment job will be waited for. The default is 240 seconds.
 It is now possible to attach script parameters to a deployment area using
/SCRIPT_PARAMETERS. This has been implemented, in the command line only, for the
UA and CA commands. The LA command has changed to indicate that script
parameters exist, but they cannot be listed at present. The LA command now also has
a /NODETAIL switch to provide a short list of areas.
 The RDEL /FORCE option has been added to enable the removal of REXEC jobs even if
the state is not a terminal one. This can be useful when cleaning up in some
circumstances.
 The exact list of variables being passed has changed (see "Variables" on page 280).
There are more variables and some of their meanings have changed. In the past, all
variables were either singleton, or in an array with one element for every item being
deployed. Now there are arrays of baselines, requests, and baseline product names
which are not in parallel with the list of items being handled.
 The new )DUMP syntax provided by the template processor can be used to more easily
see the variables that have been passed to the deployment script.
 There are new sample templates in the z/OS installation (MDHBPRE0, MDHBPST0 and
MDHBERR0) that provide sample pre-, post-, and fail scripts. These demonstrate the
use of )DUMP for MVS systems and will connect back to Dimensions to mark the script
as having succeeded.
 The commands that cause deployments to occur return SIR variables containing the
related jobs started. Each variable has a name that incorporates the Area name.
These can be used with REXEC /WAIT to cause a script of commands to stop until the
related job has completed.

Developer's Reference 279

Chapter 12 Deployment Area Scripts

Variables

IMPORTANT! Please note that the server generated scripts, described below, are not
automatically checked for syntax. Any syntax errors present in the scripts will cause the
scripts to fail to work as expected.

A set of area script template variables is created by the server and is made available to
give the context of the operation being performed. These variables are listed below, for
details see the Deploy Item command in the Command-Line Reference. The single-valued
variables represent properties common to the operation and all items being transferred.
The array-valued variables represent properties specific to each item being transferred.
 Arrayed over items

DMBRANCH
DMCTIME
DMDIR
DMFILENAME
DMFORMAT
DMID
DMISDIR
DMPREFIX
DMPRODUCT
DMREVISION
DMSUFFIX
DMTRANSFERTYPE
DMTYPE
DMVARIANT
DMWSID
DMWSPRODUCT
 From change set (arrayed):

DMBLNID
DMBLNPRODUCT
DMREQUEST
 From original command (arrayed):

DMCMDREQUESTS
 From original command (single value):

DMCOMMAND
 Single Value:

DMAREA
DMAREANODE
DMCERTIFICATE
DMCMDCOMMENT
DMDJQJOBID
DMJOBID
DMJOBTYPE
DMSERVER
DMSTAGE

280 Serena® Dimensions® CM 12.2.1

 Variables

Testing Variables
To test the variables create a dummy area template that expands all of the variables listed
above, and execute it on items and projects. The example below is the trace output from
such a run. To get a trace similar to this, use the debugging symbols described on page
282.

16TP1021T IN DMCERTIFICATE.
16TP1034T OUT
2DC74AB5E8F698998A898CE7F049CA777D45BBD491C5D575A8C9E52E100DF39809511D50EC89E531CABCB8035
FE52F5C86A24678F4EE581073F42EF0AEFD2928B84BED26C12DD518C273778781988111E902E762B5A797343B
77E420FE76ED0A4F4D229F09583C6E9BE433BA788D2D44CE19405FC3ED275772D502168D4D75C5
16TP1021T IN DMSERVER.
16TP1034T OUT STAL-DEV-SJM3
16TP1021T IN DMAREA.
16TP1034T OUT SCRIPTTEST1
16TP1021T IN DMDIR.
16TP1034T OUT c:\temp\scripttest1\t1\
16TP1021T IN DMCOMMENT.
16TP1034T OUT Initial Revision
16TP1021T IN DMFILENAME.
16TP1034T OUT tm.c
16TP1021T IN DMTRANSFERTYPE.
16TP1034T OUT c
16TP1021T IN DMREVISION.
16TP1034T OUT 1
16TP1021T IN DMBRANCH.
16TP1034T OUT
16TP1021T IN DMFORMAT.
16TP1034T OUT TEXT
16TP1021T IN DMPREFIX.
16TP1034T OUT tm
16TP1021T IN DMSUFFIX.
16TP1034T OUT c
16TP1021T IN DMWSPRODUCT.
16TP1034T OUT PAYROLL
16TP1021T IN DMWSID.
16TP1034T OUT DIRTEST2
16TP1021T IN DMPRODUCT.
16TP1034T OUT PAYROLL
16TP1021T IN DMID.
16TP1034T OUT TM C
16TP1021T IN DMVARIANT.
16TP1034T OUT A
16TP1021T IN DMTYPE.
16TP1034T OUT SRC
16TP1021T IN DMCTIME.
16TP1034T OUT Wed Aug 09 10:20:18 2006
16TP1021T IN DMCOMMAND.
16TP1034T OUT CI "PAYROLL:TM C.A-SRC;1" /USER_FILENAME="C:\tm.c" /FILENAME="tm-01.c" /
PART="PAYROLL:PAYROLL.A;1" /WS_FILENAME="t1\tm.c" /FORMAT="TEXT" /COMMENT="Initial
Revision"
16TP1021T IN
16TP1034T OUT

Developer's Reference 281

Chapter 12 Deployment Area Scripts

Differences in Relation to Build Templates

The build specific variables, such as DMTARGET, are described in "Dimensions Build
Standard Symbols" on page 196 and are not available for area scripts. Build specific
functions, such as _MDHDSN_(), are also not available.

Area scripts should be synchronous as the server waits for success or failure to organize
the next operation. You can have MVS batch JCL templates, but the success flag only
indicates the successful submission of the job, not its completion. In a production
environment it is unlikely that you would want a batch job submitted for each item that is
deployed.

Debugging
An error during the execution of an area script can prevent item operations from working
in the projects associated with that area. Use the following variables to help you to get the
template to execute successfully:

In the dm.cfg file on the Dimensions CM server specify the following variables:

DM_KEEP_DEPLOYMENT_SCRIPTS YES
DM_VERBOSE_DEPLOYMENT_SCRIPTS YES
These variables allow easier analysis of what happens when a server tries to execute
a template. The %DM_ROOT%/temp folder on the remote node contains evidence of any
attempted script execution, and template messages are passed back to the server in
the normal flow of messages.

In the dm.cfg file on the remote node where the deployment area is located specify the
following variable:

DM_TPLB_TTLOG YES
This variable creates more detailed trace messages from the templating routines that
expand the template. These messages appear in the console window of desktop client
when, for example, an item is deployed.

Other Features
Although performance is degraded significantly, it is possible for area scripts to use the
DMCERTIFICATE variable to gain access back to the Dimensions CM server from which the
request came. For details see page 270.

If you are going to use DMCERTIFICATE, test it carefully to avoid an endless cycle of
recursive area scripts if the area script itself causes another script to be fired, for
example, if the area script tries to perform a CI operation in the same project.

282 Serena® Dimensions® CM 12.2.1

 Example

Example
The example below is a simple pre-transfer event script that records the actions being
performed into a cumulative log file.

)SET TM=%DMYEAR.%DMMONTH.%DMDAY.%DMHOUR.%DMMINUTE.%DMSECOND.%DMMICROSEC.
)REP DMDIR DMFILENAME
echo "%TM. %DMDIR. %DMFILENAME." >>c:\temp\deployment.log
)ENDR
exit 0

NOTE the script uses a repeat block (shown in bold) to correctly deal with single item
transfers as well as multiple item transfers.

Developer's Reference 283

Chapter 12 Deployment Area Scripts

284 Serena® Dimensions® CM 12.2.1

Part 5
Appendixes

Part 5: Appendixes contains the following chapters:

Known DTK Event Issues 287

Developer's Reference 285

Part 5 Appendixes

286 Serena® Dimensions® CM 12.2.1

Appendix A
Known DTK Event Issues

Missing Events 288

Running External Executables 288
Running dmcli from Event Triggers 288

Developer's Reference 287

Appendix A Known DTK Event Issues

NOTE This appendix discusses a number of known issues that you should keep in mind
when using DTK events.

Missing Events
Some operations are currently missing events being fired that you might expect to be
fired. The Serena® Dimensions® CM commands that are affected are listed below.

AC – Action Request No VALIDATE event is fired.

CMB – Create Merged Baseline No POST_CREATE event is fired.
MWS – Merge project No POST_CREATE event is fired.

Running External Executables

CAUTION! Do not use this feature unless it is essential.

External executables called from event triggers run as the Dimensions CM proxy user
unless you have specified the -dont_use_proxy option in the dmlsnr configuration file
or the dmlsnr command line. Specifying this option causes dmappsrv processes to run as
the authenticated user instead of the Dimensions CM proxy user. This means that external
executables will run as the authenticated user; however, it also locks the dmappsrv to the
user session, which disables dmappsrv pooling.

Running dmcli from Event Triggers

If you intend to run dmcli from an event trigger, you should not specify connection
parameters as part of the command. With no connection parameters, dmcli will connect
to the same server and database as the session that called the event trigger.

If you want to connect to a different Dimensions CM database, but do so through the

same Dimensions CM server as the session that called the event trigger, you must specify
the database using the DMDB environment symbol.

Suitable command syntax for use with the system() C function is:
 UNIX

DMDB='dbname@dsn' dmcli 'Dimensions command'

 Windows

set DMDB=dbname@dsn&dmcli "Dimensions command"

288 Serena® Dimensions® CM 12.2.1

 Running dmcli from Event Triggers

NOTE On Windows there must be no whitespace between the DMDB value and the
ampersand (&).

Connecting to a remote server is possible, but you must specify a password to dmcli, so
this is not recommended.

The legacy command alias pcms exists for dmcli. If your existing event trigger code uses
pcms connecting to the same database as the session that called the event trigger, no
code changes should be necessary.

The following sections provide example code snippets for running dmcli through
system().

Windows Example
/* start of snippet */
status = snprintf(cmdBuf, sizeof(cmdBuf),
"set DMDB=%s&dmcli \"%s\" 1>%s 2>%s", databaseSpecifier,
dimensionsCommand, stdoutLog, stderrLog);

if (status < 0)
{
/* Command formatting error. */
}
else
{
_flushall();
status = system(cmdBuf);
}
/* end of snippet */

where databaseSpecifier is set to <database>@<dsn>

UNIX Example
/* start of snippet */
status = snprintf(cmdBuf, sizeof(cmdBuf),
"DMDB=%s dmcli '%s' >%s 2>&1",
databaseSpecifier,dimensionsCommand, logFile);

if (status <= 0 || status >= sizeof(cmdBuf))

{
/* Command formatting error. */
}
else
{

status = system(cmdBuf);
}
/* end of snippet */

where databaseSpecifier is set to <database>@<dsn>

Developer's Reference 289

Appendix A Known DTK Event Issues

290 Serena® Dimensions® CM 12.2.1

Index

Symbols %DMFOLDERSEPARATOR. templating language,

predefined symbols 192
)ADJUST template language directive 180 %DMHOUR. templating language, predefined
)ATTR template language directive 180 symbols 192
)CALL template language directive 217 %DMINPUT. templating language, Dimensions
)CALLBACK template language directive 181 Build standard symbols 198
)CM template language directive 181 %DMJOBID. templating language, remote job
)DELETE template language directive 221, 222 execution predefined symbols 196
)DUMP template language directive 181 %DMJOBID. templating language, remote job
)ELSE template language directive 182 execution standard symbols 199
)ENDEXPAND template language directive 183 %DMMICROSEC. templating language,
)ENDIF template language directive 182 predefined symbols 193
)ENDR template language directive 184 %DMMINUTE. templating language, predefined
)ENDSCRIPT template language directive 217 symbols 193
)EXPAND template language directive 184 %DMMONTH. templating language, predefined
)IF template language directive 185 symbols 193
)IFDEF template language directive 185 %DMOSTDERR. templating language, predefined
)IFGROUPDEF template language directive 221, symbols 193
222 %DMOSTDOUT. templating language,
)IFGROUPNDEF template language directive predefined symbols 193
221, 222 %DMOXTMPLT. templating language, predefined
)IFNDEF template language directive 185 symbols 194
)IM template language directive 185 %DMPASS. templating language, Dimensions
)LOGON template language directive 186 Build standard symbols 199
)LPAD template language directive 221, 222 %DMPASSWORD. templating language,
)REP template language directive 186 predefined symbols 194
)SAVE template language directive 221, 222 %DMPATH. templating language, Dimensions
)SCRIPT template language directive 217 Build standard symbols 196
)SET template language directive 188 %DMPATHSEPARATOR. templating language,
)SET_PATH template language directive 189 predefined symbols 193, 194
)SET_PATH_MVS template language directive %DMPBEMNODE. templating language,
189 Dimensions Build standard symbols 199
)SET_PATH_NT template language directive 189 %DMPBEMPORT. templating language,
)SET_PATH_UNIX template language directive Dimensions Build standard symbols 199
190 %DMRUNMODE. templating language,
)SETL template language directive 188 Dimensions Build standard symbols 199
)SETU template language directive 190 %DMSAVESTDERR. templating language,
)SLICE template language directive 190 predefined symbols 194
)VECTOR template language directive 191 %DMSAVESTDOUT. templating language,
%DMCERTIFICATE. templating language, remote predefined symbols 194
job execution predefined symbols 196 %DMSECOND. templating language, predefined
%DMCOMBIMEOUTERR. templating language, symbols 195
predefined symbols 192 %DMSERVER. templating language, Dimensions
%DMCURRENTDIRECTORY. templating Build standard symbols 199
language, predefined symbols 192 %DMSTEP. templating language, Dimensions
%DMCYGWIN. templating language, predefined Build standard symbols 199
symbols 192 %DMTARGET. templating language, Dimensions
%DMDAY. templating language, predefined Build standard symbols 198
symbols 192

Developer’s Reference 291

Index

%DMTOKEN. templating language, Dimensions END, SBEM directive 244

Build standard symbols 199 introduction 238
%DMUNIQUE. templating language, predefined messaging 242
symbols 195 output and error logs 243
%DMUSER. templating language, predefined predefined symbols 239
symbols 195 SBEM 241, 244
%DMUSER. templating language, standard search paths 242
symbols 199 SRC, SBEM directive 245
%DMUSERU. templating language, predefined TGT, SBEM directive 245
symbols 195 variables 238
%DMXFERSOURCE. templating language, introduction 234
Dimensions Build standard symbols 200 link templates 248
templates, types of 235
using, with build configurations 237
writing 234
Numerics z/OS return codes 256
4Gbyte or greater files 26

C
A catsearch 229
account predefined template symbols 204 CDE, SBEM directive 244
action driven promotion event trigger change Dimensions CM default directory 122
approach 164 check results of Dimensions CM command 54
event mechanism 164 client architecture 22
the new event 165 complex symbol references, templating language
allocate memory 64 205
allocate zero initialized memory 62 connect silently to a Dimensions CM database
API library file names 26 140
architecture connect to a Dimensions CM database 59, 132
client 22 connection functions 130
event 23 constants
interaction between client and event architecture PCMS_BASELINE 40
23 PCMS_CHDOC 40
scope of the DTK architecture 23 PCMS_CUSTOMERS 40
array variables, high level build templates 239 PCMS_EVENT_POST_OP 149
asynchronous templates, high level build PCMS_EVENT_PRE_OP 148
templates 240 PCMS_EVENT_VALIDATE_OP 148
attribute macros 126 PCMS_ITEM 40
attributes PCMS_PART 40
system-defined 35 PCMS_REL_AFF 40
user-defined 35 PCMS_REL_BREAKDOWN 40
PCMS_REL_DEP 40
PCMS_REL_DERIVED 40
PCMS_REL_INFO 40
B PCMS_REL_IRT 40
PCMS_REL_OWN 40
bill of materials, high level build templates 244 PCMS_REL_PERMANENT 41
build templates PCMS_REL_PRED 40
collection templates 254 PCMS_REL_SUCC 40, 41
compilation templates 245 PCMS_REL_TOP 40, 41
default locations 234 PCMS_REL_USE 40, 41
high level build templates PCMS_USER 40
array variables 239 PCMS_WORKSET 40
asynchronous templates 240 contacting technical support 18
bill of materials 244
CDE, SBEM directive 244
DEP, SBEM directive 245

292 Serena® Dimensions® CM 12.2.1

 Index

D DMSEQ9 predefined z/OS symbols 204

DMSEQ99 predefined z/OS symbols 204
DBCS 26 DMSEQ999 predefined z/OS symbols 204
DEP, SBEM directive 245 DMSEQA predefined z/OS symbols 204
deployment area scripts DMSEQAA predefined z/OS symbols 204
debugging 282 DMSEQAAA predefined z/OS symbols 204
example 283 DMSEQAAAA predefined z/OS symbols 204
introduction 278 DMSEQNNN predefined z/OS symbols 204
variables 280 DMSTEPMODE templating language, Dimensions
Dimensions CM Event Callout Interface 146 Build predefined symbols 202
Dimensions for z/OS predefined template DMSYSDIR predefined z/OS symbols 204
symbols DMSYSGID predefined z/OS symbols 204
job sequence numbers 204
DMSYSSHL predefined z/OS symbols 204
user ID and account 204
DMSYSUID predefined z/OS symbols 204
disconnect from a Dimensions CM database 61,
DMSYSUSR predefined z/OS symbols 204
133
DMTASKNAME templating language, Dimensions
DM_BUILDER_PROGRESS_REPORTING
Build optional symbols 201
templating language, Dimensions Build
DMTIMEOUT templating language, Dimensions
optional symbols 203
Build optional symbols 202
DM_SP_START_STAGE templating language,
DMTTLOG templating language, Dimensions
Dimensions Build optional symbols 203
Build optional symbols 203
DM_TEMPLATE_CATALOG template variable
DMYEAR templating language, predefined
215, 216
symbols 195
DM_TPLB_LOG template variable 216
Double-Byte Character Set 26
DM_TPLB_SEQUENCE_PATH build variable 216
DTK architecture 23
DM_TPLB_SPOOL template variable 216
durules predefined call 218
DM_TPLB_TTLOG template variable 216
dm.cfg template variables
DM_TEMPLATE_CATALOG 215, 216
DM_TPLB_LOG 216 E
DM_TPLB_SEQUENCE_PATH 216
DM_TPLB_SPOOL 216 END, SBEM directive 244
DM_TPLB_TTLOG 216 event architecture 23
DMALTSERVER templating language, Dimensions event callout interface 146
Build optional symbols 203 events
dmclient calling DTK functions 159
examples 173 changing system-attributes 157
introduction 170 changing user-attributes 158
Java API time format strings 172 designing 154
Javadoc 173 determining the event you want 151
using 171 event callout interface 148
examples 161
DMEXECENV templating language, Dimensions
first and second calls 152
Build optional symbols 200
pointers 156
DMEXPAND templating language, Dimensions post-events 149
Build optional symbols 201 pre-events 148
DMFINAL templating language, Dimensions Build public function call 147, 156
optional symbols 203 shared libraries 146
DMMAXRC templating language, Dimensions summary 153
Build optional symbols 202 types 149
DMMUSTRUN templating language, Dimensions unsupported function calls 159
Build optional symbols 202 usage warning 161
DMNOCACHE templating language, Dimensions using ptrEventInfo 160
validate 148
Build optional symbols 202
writing 155
DMREBUILDALL templating language,
writing a DTK callout 153
Dimensions Build optional symbols 202 examples
DMSAVESTDOUT templating language, asynchronous remote job 270
predefined symbols 194 build templates 256

Developer’s Reference 293

Index

code snippets for running dmcli through system() time format strings 172
289 Javadoc 173
collection templates 254 job sequence number template symbols, on z/OS
compilation templates 246 204
deployment area script 283
remote job template 271
synchronous REXEC template 269
execute a Dimensions CM command 134
K
asynchronously 114
known DTK event issues
synchronously 66
missing events 288
running dmcli from event triggers 288
running external executables 288
F
find Dimensions CM objects and return complete
objects 68
L
find Dimensions CM objects and return uids 110 large file support (greater than 4Gbytes) 26
free a list of values 98 logs, high level build templates 243
free Dimensions CM object structures 99 look up symbol in structured information return
free memory 63, 135 table 89
function call results 28

M
G
MBCS 26
get attribute MDHDSN template inline function 208
definition 49 MDHEXTRACT template inline function 211
definition number 73
memory allocation 41
get attribute's list of values 50 messaging, high level build templates 242
get Dimensions CM object Multi-Byte Character Set 26
attributes 76
details by specification 96
details by uid 97
relationships 102 O
reverse relationships 100
get Dimensions CM process model information obtain
inbox user structures 82
56
role section names for a product 86
get input file description 80
user relationship subtypes 91
get request descriptions 74 user role structures 93
get the Dimensions CM command 79 obtain list of loaded DLLs and dates and times for
get the last Dimensions CM message 136 each 81
get the last Dimensions CM message (dynamic obtain values associated with a symbol 88
buffer) 137 Openmake templates
get user's current project 95 introduction 262
variables 263

I
P
include file 26
install idle checker 123 pcms_api_sql_uk.msb 142
is request object in secondary catalog 104 pcms_api.h 26
pcms_api.lib 26
pcms_api.so 26
J PCMS_ERROR 27
PCMS_FAIL 27
Java API pcms_len.h 26
Ant 173
PCMS_OK 27
CruiseControl 173

294 Serena® Dimensions® CM 12.2.1

 Index

PcmsAttrDefInit 49 PcmsPendGet 105

PcmsAttrGetLov 50 PcmsPendingUserStruct 32
PcmsAttrValidate 53 PcmsPendStruct 33
PcmsCallbackStruct 28 PcmsPendWhoGet 107
PcmsChdAttachmentStruct 28 PcmsPopulate 109
PcmsCheckMessages 54 PcmsQuery 110
PcmsClntApiConnect 132 PcmsRelStruct 33
PcmsClntApiDisconnect 133 PcmsRelTypeStruct 34
PcmsClntApiExecCommand 134 PcmsRoleStruct 34
PcmsClntApiFree 135 PcmsSendCommand 114
PcmsClntApiGetLastErro 136 PcmsSetAttrs 116
PcmsClntApiGetLastErrorEx 137 PcmsSetCallback 118
PcmsClntApiModeBinary 138 PcmsSetDbErrorCallback 120
PcmsClntApiModeText 139 PcmsSetDirectory 122
PcmsClntApiSilentConnect 140 PcmsSetIdleChecker 123
PcmsCntrlPlanGet 56 PcmsSetWsetObj 124
PcmsConnect 59 PcmsTypeStruct 34
PcmsDisconnect 61 PcmsUserRoleStruct 35
PcmsEventStruct 29 PcmsWriteAttachments 125
PcmsEvntCalloc 62 populate an object's attributes values 109
PcmsEvntCalloc() 41 pos predefined call 219
PcmsEvntFree 63 post-events 149
PcmsEvntFree() 41 predefined call
PcmsEvntMalloc 64 durules 218
PcmsEvntMalloc() 41 pos 219
PcmsEvntRealloc 65 scanarea 219
PcmsEvntRealloc() 41 substring 220
PcmsExecCommand 66 predefined symbols, high level build templates
PcmsFullQuery 68 239
PcmsGetAttrDefNum 73 pre-events 148
PcmsGetAttrFile 74
PcmsGetAttrs 76
PcmsGetBaseDbOptions 77 R
PcmsGetCandidates 78
re-allocate memory 65
PcmsGetCommandLine 79
remote job execution templates
PcmsGetConnectDesc 80
asynchronous remote jobs 270
PcmsGetDimensionsVersions 81 introduction 268
PcmsGetPendingUsers 82 remote job script example 271
PcmsGetRSAttrs 84 synchronous templates 268
PcmsGetRSNames 86 templates 268
PcmsGetStringSymbolValue 88 results of function calls 28
PcmsGetSymbolInfo 89 retrieve
PcmsGetUserRelTypes 91 attribute numbers in a role section 84
PcmsGetUserRoles 93 candidates for delegation 78
PcmsGetWsetObj 95 Dimensions CM objects inboxes for a user 105
PcmsInitSpec 96 users for object 107
PcmsInitUid 97 retrieve base database options 77
PcmsLcStruct 29 return codes 27
PcmsLovFree 98
PcmsObjAttrDefStruct 30
PcmsObjAttrStruct 31 S
PcmsObjFree 99
SAVE 232
PcmsObjGetBackRels 100
SBEM, high level build templates 241, 244
PcmsObjGetRels 102
scanarea predefined call 219
PcmsObjInSecondary 104
search paths, high level build templates 242
PcmsObjStruct 32

Developer’s Reference 295

Index

set Dimensions CM API server callback 118 Dimensions Build standard symbols
set Dimensions CM object attributes 116 %DMINPUT. 198
set file transfer mode to ASCII 139 %DMPASS. 199
set file transfer mode to binary 138 %DMPATH. 196
set server error callback 120 %DMPBEMNODE. 199
set user's current project 124 %DMPBEMPORT. 199
SIR 230 %DMRUNMODE. 199
SPPM 232 %DMSERVER. 199
SRC, SBEM directive 245 %DMSTEP. 199
structured information return (SIR) %DMTARGET. 198
background 230 %DMTOKEN. 199
key features 231 %DMXFERSOURCE. 200
SAVE command 232 directives 180
SPPM command 232 )ADJUST 180
when to use 231 )ATTR 180
substring predefined call 220 )CALL 217
system-defined attributes 35 )CALLBACK 181
)CM 181
)DELETE 221, 222
T )DUMP 181
)ELSE 182
technical support )ENDEXPAND 183
contacting 18
)ENDIF 182
template processor interface 229
)ENDR 184
templating language
)ENDSCRIPT 217
build templates
)EXPAND 184
collection templates 254
)IF 185
compilation templates 245
)IFDEF 185
high level build templates 238
)IFGROUPDEF 221, 222
introduction 234
)IFGROUPNDEF 221, 222
link templates 248
)IFNDEF 185
types of 235
)IM 185
z/OS return codes 256
complex symbol references 205 )LOAD 221, 222
default template characters 179 )LOGON 186
deployment area scripts )REP 186
debugging 282 )SAVE 221, 222
example 283 )SCRIPT 217
introduction 278 )SET 188
variables 280 )SET_PATH 189
Dimensions Build optional symbols )SET_PATH_MVS 189
DM_BUILDER_PROGRESS_REPORTING )SET_PATH_NT 189
203 )SET_PATH_UNIX 190
DM_SP_START_STAGE 203 )SETL 188
DMALTSERVER 203 )SETU 190
DMEXECENV 200 )SLICE 190
DMEXPAND 201 )VECTOR 191
DMFINAL 203 inline functions 208
DMMAXRC 202 introduction 178
DMMUSTRUN 202 job sequence number symbols, on z/OS 204
MDHDSN inline function 208
DMNOCACHE 202
MDHEXTRACT inline function 211
DMREBUILDALL 202
Openmake symbols
DMTASKNAME 201 ANT_HOME 263
DMTIMEOUT 202 DM_CURRENT_USERNAME 263
DMTLOG 203 DM_LICENSE 263
Dimensions Build predefined symbols
DM_META_DATASET 263
DMSTEPMODE 202

296 Serena® Dimensions® CM 12.2.1

 Index

DM_META_LOCK_MAJOR 263 %DMHOUR. 192

DM_META_LOCK_MINOR 263 %DMMICROSEC. 193
DM_OM_OSPLATFORM 263 %DMMINUTE. 193
DM_OPENMAKE_INSTALL 263 %DMMONTH. 193
DM_OPENMAKE_SERVER 263 %DMOSTDERR. 193
DM_ROOT 263 %DMOSTDOUT. 193
DM_TPLB_MACHINE 263 %DMOXTMPLT. 194
DM_TPLB_PUBLIC 263 %DMPASSWORD. 194
DMBLDLOGURL 264 %DMPATHSEPARATOR. 193, 194
DMBLDMAKE_OPTIONS 264 %DMSAVESTDERR. 194
DMBLDPROJ 264 %DMSAVESTDOUT. 194
DMCDHLQ 264 %DMSECOND. 195
DMCDILQ 264 %DMUNIQUE. 195
DMCDLPA 264 %DMUSER. 195
DMCLEANBUILD 264 %DMUSERU. 195
DMDAY 264 DMSAVESTDOUT 194
DMDIRECTORY 264 DMYEAR 195
DMHOUR 264 predefined z/OS symbols
DMINHLQ 264 DMSEQ9 204
DMINST 264 DMSEQ99 204
DMMACHINE 264 DMSEQ999 204
DMMICROSEC 264 DMSEQA 204
DMMINUTE 264 DMSEQAA 204
DMMONTH 264 DMSEQAAA 204
DMMVSUSR 264 DMSEQAAAA 204
DMOBOMRPT 264 DMSEQNNN 204
DMOMDATETIME 264 DMSYSDIR 204
DMOMINSTALL 264 DMSYSGID 204
DMOMSERVER 264 DMSYSSHL 204
DMOPTIONS 264 DMSYSUID 204
DMOSPLATFORM 264 DMSYSUSR 204
DMPBEMNODE 264 remote job execution predefined symbols
DMPBEMPORT 264 %DMCERTIFICATE. 196
DMPUBLIC 264 %DMJOBID. 196
DMRUNMODE 264 remote job execution standard symbols
DMSEARCHPATH 264 %DMJOBID. 199
DMSECOND 264 remote job execution templates
DMSECONDS 264 asynchronous remote jobs 270
DMSEQ9 264 introduction 268
DMSTEP 264 remote job script example 271
DMSYSUSR 264 synchronous templates 268
DMTARGET 264 templates 268
standard symbols
DMUNIQUE 264
%DMUSER. 199
DMUSER 265
templates
DMYEAR 265
about 178
JAVA_HOME 265
expanding 205
Openmake templates
testing 210
introduction 262
TGT, SBEM directive 245
variables 263
overview 178
predefined symbols
%DMCOMBINEOUTERR. 192 U
%DMCURRENTDIRECTORY. 192
user ID predefined template symbols 204
%DMCYGWIN. 192
user written template processing
%DMDAY. 192
call out functionality 217
%DMFOLDERSEPARATOR. 192
passing data between steps 221

Developer’s Reference 297

Index

user-defined attributes 35

V
validate an attribute value 53
validate events 148
variables, high level build templates 238

W
windows.h 130
write specified request attachments to disk 125

298 Serena® Dimensions® CM 12.2.1