Data Access Routines User Guide

Data Access Routines
User Guide
Version 11.6

pdms1160/Data Access Routines User Guide
issue 070904

PLEASE NOTE:
AVEVA Solutions has a policy of continuing product development: therefore, the
information contained in this document may be subject to change without notice.
AVEVA SOLUTIONS MAKES NO WARRANTY OF ANY KIND WITH REGARD
TO THIS DOCUMENT, INCLUDING BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.
While every effort has been made to verify the accuracy of this document,
AVEVA Solutions shall not be liable for errors contained herein or direct,
indirect, special, incidental or consequential damages in connection with the
furnishing, performance or use of this material.

This manual provides documentation relating to products to which you may not have
access or which may not be licensed to you. For further information on which Products
are licensed to you please refer to your licence conditions.

Copyright 1991 through 2004 AVEVA Solutions Limited
All rights reserved. No part of this document may be reproduced, stored in a retrieval
system or transmitted, in any form or by any means, electronic, mechanical,
photocopying, recording or otherwise, without prior written permission of AVEVA
Solutions.
The software programs described in this document are confidential information and
proprietary products of AVEVA Solutions or its licensors.

For details of AVEVA's worldwide sales and support offices, see our website at
http://www.aveva.com
Aveva Solutions Ltd, High Cross, Madingley Road, Cambridge CB3 0HB, UK
Contents
1 Introduction .................................................................................................. 1-1
1.1 Scope of Data Access Routines .................................................................................1-1
1.2 Who Can Use Data Access Routines?.......................................................................1-1
1.3 Interfacing to 'C/C++' Programs ...............................................................................1-2
1.4 How To Use This Manual .........................................................................................1-2
1.5 Use of Other PDMS Manuals ...................................................................................1-3
1.6 Changes at PDMS Mk11...........................................................................................1-3
2 Programming Techniques ........................................................................... 2-1
2.1 FORTRAN 77.............................................................................................................2-1
2.2 Declarations...............................................................................................................2-1
2.3 CHARACTER Handling............................................................................................2-2
2.4 Subroutine and Common Block Naming..................................................................2-4
2.5 Error Handling..........................................................................................................2-4
3 Basic Concepts of PDMS Data Access....................................................... 3-1
3.1 PDMS Database Organisation..................................................................................3-1
3.2 PDMS Database Security..........................................................................................3-1
3.3 Current Element .......................................................................................................3-1
3.4 User-Defined Attributes............................................................................................3-2
3.5 Dynamic Array Attributes ........................................................................................3-2
3.6 Monitoring .................................................................................................................3-2
3.7 Site File......................................................................................................................3-3
3.8 Multibyte Text ...........................................................................................................3-3
4 Use of Data Access Routines...................................................................... 4-1
4.1 Introduction...............................................................................................................4-1
4.2 Example 1 ..................................................................................................................4-1
4.3 Example 2 ..................................................................................................................4-7
5 Subroutine Specifications ........................................................................... 5-1
5.1 Introduction...............................................................................................................5-1
5.2 Subroutine Summaries .............................................................................................5-3
5.2.1 Initialisation Routines, D3Ixxx .......................................................................5-3
5.2.2 Navigation Routines, D3Mxxx.........................................................................5-3
5.2.3 Read Routines, D3Rxxx ...................................................................................5-4
5.2.4 Error Handling Routines, D3Exxx..................................................................5-7
5.2.5 Utility Routines, D3Uxxx ................................................................................5-7
5.2.6 Termination Routines, D3Fxxx .......................................................................5-8
5.2.7 General Utility Routines, D3Uxxx ..................................................................5-8
5.3 Detailed Subroutine Specifications ..........................................................................5-9
VANTAGE Plant Design Data Access Routines i
User Guide
Version 11.6
Introduction
6 Version Control ............................................................................................ 6-1
6.1 DARs Version Numbering........................................................................................ 6-1
6.2 Compatibility of Databases and DARs .................................................................... 6-1
6.3 Determination of Version Number .......................................................................... 6-2
A DARs Library Details ................................................................................... A-1
A.1 Software Issued with DARs.....................................................................................A-1
A.2 File Handling ...........................................................................................................A-2
A.3 Application Program Compilation and Linking.....................................................A-3
A.4 Program Running and Debugging ..........................................................................A-4
A.5 Acceptance Test Program........................................................................................A-4
A.6 Re-Linking Application Programs ..........................................................................A-5
B Running Examples....................................................................................... B-1
C Error Codes and Messages......................................................................... C-1
D Auxiliary Subroutine Library....................................................................... D-1
D.1 Introduction.............................................................................................................. D-1
D.2 List of Subroutines................................................................................................... D-1
D.3 Subroutine Outline Specifications ......................................................................... D-3
E Multibyte Text Handling............................................................................... E-1
F C/C++ Library ............................................................................................. F-1
F.1 Software Issued with DARs C/C++ Library..........................................................F-1
F.2 Application Program Compilation and Linking.....................................................F-1
F.3 Program Running and Debugging ..........................................................................F-1
F.4 Acceptance Test Program........................................................................................F-1
F.5 Compilation and Linking Script .............................................................................F-2
F.6 'C/C++' Header Files................................................................................................F-3
F.7 Example 'C' Program.............................................................................................F-12
F.8 'C/C++' Interface Principles...................................................................................F-20
F.9 Use of System Calls in DARs Programs...............................................................F-21
ii VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6

1 Introduction
1.1 Scope of Data Access Routines
The PDMS Data Access Routines are a set of FORTRAN 77 subroutines
which may be incorporated into user-written software for the purposes of
navigating and manipulating the data held within a PDMS project. The
anticipated use of this facility will be the creation of interfaces to other
software packages, e.g. material take-off, pipe stress, isometrics, etc.
The data access routines provide the tools necessary for the user to
extract attribute values from the PDMS model. This takes the form of a
subroutine library which can be divided into the following functions:
- Initialisation
- Navigation
- Attribute retrieval
- Error handling
- Utility routines
The initialisation routines allow access to the requested PDMS project
and MDB configuration in line with the normal PDMS entry procedure.
The routines open all authorised databases in read mode only. The
navigation routines follow the current PDMS navigation techniques and
standards. The PDMS concept of 'current element' is thus maintained.
All data attributes are retrieved by first moving to the required element
using the navigation routines, and then calling the appropriate attribute
retrieval routine.
No facilities are provided for writing or updating data in PDMS
databases.
1.2 Who Can Use Data Access Routines?
Within this manual, the term user refers to a user of a PDMS DARs
application program. He will of necessity also be a PDMS user. The
term programmer refers to the programmer who calls PDMS DARs
routines in an application program.

VANTAGE Plant Design Data Access Routines 1-1
User Guide
Version 11.6
Introduction
The programmer is expected to be familiar with PDMS and proficient at
FORTRAN 77 programming. The user does not need any programming
knowledge, providing the programmer makes his program sufficiently
user-friendly.
Aveva Solutions Ltd can provide consultancy services to assist customers
in the preparation of applications programs. The experienced
programmer, however, will find DARs no more difficult to use than other
well-written library packages.
To assist the programmer in his program development, a monitor option
may be selected to obtain information on entry to and exit from each data
access routine.
A PDMS user identification and password will be needed to use an
application program and the privilege of the user will be checked before
any action is performed.
1.3 Interfacing to 'C/C++' Programs
A DARs 'C/C++' interface is included in the PDMS DARs release for all
platforms. Details are presented in Appendix F for each of the supported
machine types.
1.4 How To Use This Manual
This manual is provided more for the use of the DARs programmer than
for the user of DARs applications programs.
Sections 1 to 3 of this manual provide the programmer with an
introduction to the philosophy involved in PDMS data access and some of
the programming techniques that may be necessary.
Section 4 gives examples of the use of DARs in several simple
applications. FORTRAN source files and terminal output are given for
these examples. Compilation, loading and running details are provided
in Appendix B for each of the supported machine types. More detailed
machine-specific information is presented in Appendices Error!
Reference source not found., B and F, together with details of the 'C/C++'
interface.
Section 5 is a reference section, providing both summaries and detailed
specifications for all data access routines. The detailed specifications
follow a standard format. In particular, a convention of underlining
return arguments has been adopted. Each routine specification gives
1-2 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
Introduction
detailed definitions of all arguments and lists the possible error
conditions that can arise.
Section 6 gives details of version control mechanisms.
Appendix C provides a list of error messages for easy reference.
Appendix D gives brief details of an auxiliary subroutine library supplied
with PDMS DARs which contains FORTRAN subroutines that DARs
programmers may find useful as they stand or as a template for their
own routines.
1.5 Use of Other PDMS Manuals
Part 3 of the VANTAGE PDMS DESIGN Reference Manual for gives
details of PDMS elements and their attributes. A comprehensive list of
all PDMS attributes and pseudo-attributes is given in the Plant Design
Software Customisation Reference Manual.
1.6 Changes at PDMS Mk11
As a result of the new version of DABACON at PDMS Mk11 and other
significant changes introduced with this major version, there are several
aspects of PDMS Mk11 DARs that are not upwards compatible from
Mk10. These changes are noted as footnotes in Section 5, summarised as
follows:
PDMS words can now be of length 6 (previously maximum of four)
PDMS words are now stored as integers in the PDMS database
(previously real numbers). As a result, subroutine D3UDEH word
argument is now INTEGER instead of REAL.
Many input arguments were previously truncated to four characters.
At 11, DARs will accept element types and attribute names in the
same form as they are recognised by PDMS.
Routines handling dates now accept or return a four-digit year.
User Guide
Version 11.6
Introduction

User Guide
Version 11.6

2 Programming Techniques
2.1 FORTRAN 77
PDMS DARs are written in FORTRAN 77 and can be called from any
FORTRAN 77 program or from any other program that can call ANSI
standard FORTRAN 77 subroutines.
It is not within the scope of this manual to explain FORTRAN 77
programming methods. If necessary, the following text book is
recommended:
Title: Programming in Standard Fortran 77
Authors: A. Balfour and D.H. Marwick
Publisher: Heinemann Educational Books, 1982
Hardback: ISBN 0 435 77485 9
Paperback: ISBN 0 435 77486 7
If the programmer does not wish to pass character strings into the
application program or can convert to and from hollerith constants or
ASCII integer arrays, it would be possible to interface PDMS DARs to a
FORTRAN 66 application program via a neutral interface.
2.2 Declarations
The subroutine summaries define the argument declarations that are
used within the DARs. The following naming convention has been
adopted in the subroutine specifications:
CHARACTER CD3xxx
I NTEGER I D3xxx
REAL RD3xxx
LOGI CAL LD3xxx

User Guide
Version 11.6
Programming Techniques
Character and logical arguments must be explicitly declared in calling
routines. Integer and real arguments comply with the default
FORTRAN 77 naming convention and need not be declared.
Wherever assumed size arrays or character strings are used

e. g. I NTEGER I D3XYZ( *)
CHARACTER*( *) CD3XYZ
the programmer must provide the appropriate explicit declaration in the
application program.
Functions are avoided in PDMS DARs but some general utility functions
are provided. The calling routine must make the following declarations
where these functions are used:
I NTEGER D3ULEN
LOGI CAL D3UCTI
LOGI CAL D3UCTR
LOGI CAL D3UGTU
LOGI CAL D3UCLU
The EXTERNAL declarations are optional.
Some programmers adopt a rigid practice of declaring all variables and
external functions and subroutines. Such a practice, whilst irksome to
some, eliminates misspelling of variables within a program and prevents
accidental omission of non-default declarations (e.g. INTEGER
D3ULEN) which are difficult to identify in a 'misbehaving' program.
Some compilers provide an option that forces the programmer to declare
all variables and externals. If DARs programmers adopt the practice, it
will help to reduce Aveva's support load. In this manual, including the
example listed above, all coding examples include full declarations.
2.3 CHARACTER Handling
The handling of character variables is the most significant difference
between FORTRAN 66 and FORTRAN 77.
Whenever character arguments are passed into a DARs routine, the
routine will ignore any trailing blanks. Character arguments returned
by a routine are padded with blanks to the end of the character string. A
returned character argument will never be undefined. A blank string '
' will be returned as a 'minimum' ('blank' as distinct from 'null').
User Guide
Version 11.6
Programmers should be aware that an assignment such as:
CHARACTER*10 CD3XYZ
.
.
CD3XYZ = ' ABC'
will result in a character string ' ABC ' ; that is ' ABC' followed
by seven blanks. This is true even if CD3XYZ previously contained more
than three non-blank characters.
Whilst the string ' ABC ' is interpreted the same as ' ABC' , the
string ' ABC' will not be.
If the programmer wishes to know the significant length of a returned
string (e.g. the significant length of ' ABC ' is 3), he may use the
general utility function D3ULEN.
e. g. EXTERNAL D3xxxx, D3ULEN
I NTEGER D3ULEN, NC
CHARACTER*10 CD3XYZ

CALL D3xxxx( . . . . . . . . . , CD3XYZ, . . . . . )
PRI NT *, CD3XYZ( 1: D3ULEN( CD3XYZ) ) , ' r et ur ned'
or
NC = D3ULEN( CD3XYZ)
PRI NT *, CD3XYZ( 1: NC) , ' r et ur ned'
would print
ABC r et ur ned
rather than
ABC r et ur ned
This could be embellished by constructions such as:

I F ( D3ULEN( CD3XYZ) . EQ. 0) THEN
PRI NT *, ' bl ank st r i ng r et ur ned'
ELSE
. . . . .
ENDI F
User Guide
Version 11.6
2.4 Subroutine and Common Block Naming
PDMS DARs have adopted a simple naming convention for subroutines
and common blocks. All names begin with the prefix 'D3'. DARs
programmers should therefore avoid the use of subroutine and common
block names starting with 'D3'. They would also be wise to avoid 'D2' if
they expect to use PEGS DARs.
If DARs programmers experience difficulty with this aspect of interfacing
to PDMS DARs, they should bring their problem to the attention of
Aveva. Problems should only arise with interfaces to established
programs or with programs using other subroutine libraries.
2.5 Error Handling
The DARs routines trap user input argument errors and cases where
return character arguments are too short for the data being returned.
The way in which such errors are handled varies according to the routine
and is detailed in the 'Subroutine Specifications'. Many other potential
errors are detected by the routines in the course of execution. All error
conditions are communicated to the calling program through a return
status code argument (always named ID3ERR in the subroutine
specifications). A zero status code signifies successful execution; a
positive value indicates an error condition.
Each subroutine specification lists the status codes applicable to it and a
full list is provided in Appendix C.
Whenever an error condition is returned, the DARs set an internal error
flag. This prevents entry into the next DARs routine (unless it is D3FIN,
D3EMSG, D3ERST or D3UMON). The purpose of this action is to make
the error obvious to the programmer (or to the user) and to prevent
subsequent return of useless data. When such a failure occurs, helpful
information concerning the source of the error is output to the screen.
The programmer can obtain even more information by setting the
monitor flag at an appropriate point.
In some circumstances, the programmer deliberately creates an error
condition. This is a convenient way to terminate a loop. Routine
D3ERST is provided to allow the programmer to reset the internal error
flag in such a situation. Thus, the internal error flag is a device to trap
errors not expected by the programmer.

User Guide
Version 11.6
The following extract from D3QMEM in the auxiliary routine library
illustrates use of these principles. The status code returned by a routine
can be converted into a message by a call to D3EMSG.
C Move t o f i r st member
CALL D3MREL( ' FI RS' , ' MEMB' , I D3ERR )
20 CONTI NUE
I F ( I D3ERR . EQ. 0 ) THEN
NMEMB = NMEMB + 1
C Read t ype
CALL D3RTYP( CD3TEX, I D3ERR )
I F ( I D3ERR . NE. 0 ) GOTO 12345
CD3TYP( NMEMB) = CD3TEX
C Read name/ r ef er ence
CALL D3RNAM( ' NAME' , CD3TEX, I D3ERR )
I F ( I D3ERR . NE. 0 ) GOTO 12345
CD3NAM( NMEMB) = CD3TEX
ELSE
C Reset i nt er nal er r or f l ag i f No Member s or Li st
Exhaust ed
C Ret ur n zer o I D3ERR val ue
I F ( I D3ERR . NE. 202 . AND. I D3ERR . NE. 203 ) GOTO
12345
CALL D3ERST
I D3ERR = 0
GOTO 100
ENDI F
C Check i f r eached end of User ' s ar r ays
I F ( NMEMB . EQ. I D3NI N ) GOTO 100
C Move t o next member of cur r ent l i st
CALL D3MREL( ' NEXT' , ' ELEM' , I D3ERR )
GOTO 20
C End of l i st
100 CONTI NUE
.
.
User Guide
Version 11.6
12345 CONTI NUE

CALL D3EMSG( I D3ERR, . TRUE. , CMESS)
PRI NT*, ' Er r or i n subr out i ne ABC, pl ease r epor t t o
xxx' )
It is good practice if the programmer provides his own error trapping as
illustrated above, particularly in a released applications program. The
user can then be given an appropriate message, rather than receiving a
message from the DARs error handling system.

User Guide
Version 11.6

3 Basic Concepts of PDMS Data Access
3.1 PDMS Database Organisation
The VANTAGE PDMS ADMIN Reference Manual provides an overview
of 'The Project Control Administration System' in terms of database
organisation for a project and the grouping of databases in MDBs.
3.2 PDMS Database Security
The data access initialisation routine D3INIT requires a valid project
name and a username and password valid for that project. If invalid
values are passed, then an error code is returned and the PDMS project
is closed down.
The MDB selection routine D3MMDB, called after a successful
initialisation, requires a valid MDB name for the selected project. If the
MDB is not found, the user is allowed further attempts (since this may
be a deliberate programming strategy). Any other error condition (e.g.
database in use) results in close down of the project.
Since access to all databases is read only, there is no threat to the
integrity of the PDMS project databases in the event of either machine or
program failure.
3.3 Current Element
The navigation routines follow the current PDMS navigation techniques
and standards. The PDMS concept of 'current element' is thus
maintained. All data attributes are retrieved by first moving to the
required element using the navigation routines, and then calling the
appropriate attribute retrieval routine.
User Guide
Version 11.6
Basic Concepts of PDMS Data Access
3.4 User-Defined Attributes
The routines that retrieve attributes may be used for both system-
defined and user-defined attributes (UDAs). As with PDMS, DARs
routines identify UDAs by a leading ':' character in the UDA name.
3.5 Dynamic Array Attributes
At PDMS Mk10, the concept of dynamic array attributes was introduced.
In earlier versions of PDMS all array attributes were of fixed size (e.g.
PARA was a real array of size 3, 4, 5, 6, 7, 10, 15 or 30). This was
designed to prevent wasteful use of database space, since any array
positions not used are present in the database.
With dynamic arrays, the user may define data for any number of array
positions up to a maximum (typically 200). This is only of particular use
where the number of array positions is not fixed. For example,
attributes POS and ORI, arrays of size 3, will never need less than three
values. Where dynamic arrays are defined and no values are set, PDMS
DARs will return the error condition 'Attribute not found'.
The same technique is also applied to text attributes. In earlier versions
of PDMS all text attributes were of fixed length (e.g. STEX could be of
length 15, 30, 45, 60, 75, 90, 105 or 120). With dynamic text, the user
may define text of any length up to a maximum (typically 120). Where
dynamic text is defined and no text has been provided, DARs will return
the error condition Attribute unset.
3.6 Monitoring
The monitoring facility enables the programmer to set the level of
information displayed by the Data Access routines. It is set by an
argument passed to the initialisation routine D3INIT and can be reset at
any point by a call to D3UMON. If the monitor option FULL is selected,
then every time a data access routine is called, the name of the routine is
displayed along with the values of all the input arguments, and on exit
the returned argument values are displayed, together with all warning
and error conditions encountered. Alternatively, the programmer may
set the monitor level to OFF. In this case, he can use the routine
D3EMSG to display error messages as he wishes. Note that even if the
monitor level is set to OFF, some important low level messages will still
be displayed on the screen.
User Guide
Version 11.6
3.7 Site File
PDMS DARs operate a sitefile checking procedure in the same manner
as PDMS. A DARs program user is included in the count of PDMS users.
A PDMS DARs application program will not continue to execute if a fatal
sitefile error is encountered. Sitefile warning messages and fatal error
messages will be output to the terminal.
3.8 Multibyte Text
If a PDMS project has been identified as multibyte (PROJECT
MBCHARSET in the ADMIN module), it is possible for users to enter
multibyte element names and attributes in some PDMS modules. This
allows Far Eastern users to enter Kanji text, which is stored in PDMS as
multibyte text (two bytes per Kanji character). This also applies to the
Chinese alphabet.
Kanji and Chinese text can be input to or returned by DARs routines.
The method of interpreting multibyte names and text accessed through
DARs is detailed in Appendix E.
User Guide
Version 11.6

User Guide
Version 11.6
Use of Data Access Routines
4 Use of Data Access Routines
4.1 Introduction
The use of data access routines is best illustrated by reference to some
simple examples. The examples used in this section are based on the
PDMS project used in the acceptance test. Details in this section are
applicable to any machine type.
Where the examples use a PRINT (or list-directed WRITE) statement,
programmers should note that the default format obtained is dependent
on the compiler. Further, some compilers skip column 1 whether
outputting to terminal or file. This is not the case when a FORMAT
specifier is used with a WRITE statement, where the programmer can
control the placement of characters, including the use of column 1. In
this situation, the output should not be dependent on the compiler. The
output for these examples is therefore system-dependent in some minor
respects (e.g. spacing of numbers and number of decimal places). The
output shown in this section is typical.
Example 1 is a simple example, involving navigation to the last flange in
the first branch of a named pipe.
Example 2 is a longer example, involving calls to several of the auxiliary
routines.
FORTRAN source files for the two examples are included with a release
of data access routines.
4.2 Example 1
The FORTRAN 77 code for the application program is as follows:
PROGRAM EXMPL1
C Appl i cat i on mai n pr ogr am
C Essent i al t ype decl ar at i ons
CHARACTER*50 SPCREF, CATREF
C Can decl ar e CD3MSG CHAR*1 i f not usi ng i t
CHARACTER*1 CD3MSG
User Guide
Version 11.6
CHARACTER*6 CD3WOR, WORDS( 100)
REAL PARAMS( 100)
C Opt i onal EXTERNAL decl ar at i ons
EXTERNAL D3I NI T, D3MMDB, D3MNAM, D3MNUM, D3MREL,
D3RNAM
EXTERNAL D3RRA, D3RWA, D3EMSG, D3FI N, D3FEND,
D3UMON, D3UDEH
C Opt i onal t ype decl ar at i ons
I NTEGER I D3ERR, I D3NOU, I
I NTRI NSI C I NT
C
C Pr oj ect ent r y
CALL D3I NI T( ' DAR' , ' SYSTEM' , ' XXXXXX' , ' FULL' , '
' , I D3ERR )
I F ( I D3ERR . NE. 0 ) GOTO 12345
C Sel ect MDB
CALL D3MMDB( ' DESI GN/ PLANT' , ' ' , I D3ERR )
I F ( I D3ERR . NE. 0 ) GOTO 12345
C Move t o a pi pe component
CALL D3MNAM( ' / 100- B- 1' , I D3ERR )
CALL D3MNUM( ' BRAN' , 1, I D3ERR )
CALL D3MREL( ' LAST' , ' FLAN' , I D3ERR )
C Get spec r ef and got o i t
CALL D3RNAM( ' SPRE' , SPCREF, I D3ERR )
CALL D3MNAM( SPCREF, I D3ERR )
C Get cat r ef and got o i t
CALL D3RNAM( ' CATR' , CATREF, I D3ERR )
CALL D3MNAM( CATREF, I D3ERR )
C Get par amet er s of component and dehash conn t ypes
C Cancel moni t or and const r uct own PRI NT st at ement s
CALL D3UMON( ' NONE' )
PRI NT*, ' Get t i ng el ement s wi t h D3RRA'
CALL D3RRA( ' PARA' , 100, PARAMS, I D3NOU, I D3ERR )
PRI NT*, ' Number of el ement s f ound: ' , I D3NOU
DO 100 I =1, I D3NOU
User Guide
Version 11.6
CD3WOR = ' '
C I f possi bl y a wor d, dehash
I F ( PARAMS( I ) . GE. 531442. ) THEN
CALL D3UDEH( I NT( PARAMS( I ) ) , CD3WOR )
ENDI F
I F ( CD3WOR. EQ. ' ' ) THEN
C Not a wor d; pr i nt r eal val ue
PRI NT*, ' El ement ' , I , PARAMS( I )
ELSE
C Val i d wor d; pr i nt wor d
PRI NT*, ' El ement ' , I , ' ' , CD3WOR
ENDI F
100 CONTI NUE
C Al t er nat i vel y, use D3RWA di r ect l y ( non- wor ds don' t
gi ve er r or )
PRI NT*, ' Get t i ng el ement s wi t h D3RWA'
CALL D3RWA( ' WPAR' , 100, WORDS, I D3NOU, I D3ERR )
DO 200 I =1, I D3NOU
I F ( WORDS( I ) . NE. ' ' ) PRI NT*, ' El ement ' , I , '
' , WORDS( I )
200 CONTI NUE
C
12345 CONTI NUE
C Cancel moni t or and out put message
CALL D3EMSG( I D3ERR, . TRUE. , CD3MSG )
C Exi t pr oj ect
CALL D3FI N( I D3ERR )
C Exi t DARs
CALL D3FEND
END
Compilation, loading and running instructions are detailed in Appendix
0.

User Guide
Version 11.6
The program output first illustrated is for the situation where the project
DAR does not exist. The program therefore returns from D3INIT with
an error status, which is trapped by the program. The output, with
monitor level in D3INIT set to 'FULL', is as follows:
PDMS DARs <ver si on det ai l s>
<copyr i ght st at ement >

<si t e dat a>

Ent er i ng subr out i ne D3I NI T
I nput ar gument s:
Pr oj ect name DAR
User name SYSTEM
Passwor d XXXXXX
Moni t or i ng l evel FULL
Read/ Wr i t e key
Exi t i ng subr out i ne D3I NI T
Out put ar gument s:
Er r or code 108
Pr oj ect not f ound
The first 'Project not found' message arises from monitor output from
D3INIT. The second message is output by D3EMSG. With monitor set
to 'NONE', the output is as follows:

<si t e dat a>

A second possible error situation, where the MDB does not exist, gives
the following output, with monitor level in D3INIT set to 'FULL':

User Guide
Version 11.6
<si t e dat a>

I nput ar gument s:
Pr oj ect name DAR
User name SYSTEM
Passwor d XXXXXX
Read/ Wr i t e key
Er r or code 0
Ent er i ng subr out i ne D3MMDB
I nput ar gument s:
MDB name DESI GN/ PLANT
Read/ Wr i t e key

Openi ng dat abases
Mode Type Name
- - - - - - - - - - - -
Read DESI STRUC/ S
Read DESI
PI PE/ MAX_DB_LENGTH_31_AFTER_THESLASH
Read CATA CATAL/ C
Read PROP PI PE/ PROP
Read DESI PI PE/ DR
Read DI CT PI PE/ DI CT1

Def aul t dat abase t ype: DESI

Exi t i ng subr out i ne D3MMDB
Er r or code 0
Ent er i ng subr out i ne D3MNAM
User Guide
Version 11.6
I nput ar gument s:
El ement name/ r ef / 100- B- 1
Exi t i ng subr out i ne D3MNAM
Er r or code 0
Ent er i ng subr out i ne D3MNUM
I nput ar gument s:
El ement t ype BRAN
Li st posi t i on 1
Exi t i ng subr out i ne D3MNUM
Er r or code 0
Ent er i ng subr out i ne D3MREL
I nput ar gument s:
Rel at i ve posi t i on LAST
El ement t ype FLAN
Exi t i ng subr out i ne D3MREL
Er r or code 0
Ent er i ng subr out i ne D3RNAM
I nput ar gument s:
At t r i but e r equi r ed SPRE
Exi t i ng subr out i ne D3RNAM
Name/ Ref er ence / A3B/ 100F1
Er r or code 0
I nput ar gument s:
El ement name/ r ef / A3B/ 100F1
Er r or code 0
I nput ar gument s:
User Guide
Version 11.6
At t r i but e r equi r ed CATR
Name/ Ref er ence / FUAAPAMM
Er r or code 0
I nput ar gument s:
El ement name/ r ef / FUAAPAMM
Er r or code 0
Ent er i ng subr out i ne D3UMON
I nput ar gument s:
Moni t or i ng l evel NONE
Get t i ng el ement s wi t h D3RRA
Number of el ement s f ound: 8
El ement 1 100. 0000
El ement 2 254. 0000
El ement 3 31. 80000
El ement 4 54. 10000
El ement 5 25. 00000
El ement 6 114. 3000
El ement 7 BWD
El ement 8 FGD
Get t i ng el ement s wi t h D3RWA
El ement 7 BWD
El ement 8 FGD
Success
4.3 Example 2
This example is based on part of the acceptance test and calls several of
the auxiliary routines (D3QMEM, D3QSIT etc.). The FORTRAN code for
User Guide
Version 11.6
those routines (provided in source form; see Appendix 0) may be studied
in conjunction with the bare application code:

C- - - - - - - - - - - - - - - - - - -
PROGRAM EXMPL2
C- - - - - - - - - - - - - - - - - - -
LOGI CAL PROJ I N, MDBI N
C Opt i onal decl ar at i ons
I NTEGER I FI NDM
EXTERNAL PROJ I N, MDBI N, DECCHK, D3FI N, D3FEND

I FI NDM = 0
C Pr oj ect ent r y
I F ( . NOT. PROJ I N( ) ) GOTO 12345
C MDB sel ect i on
I F ( . NOT. MDBI N( ) ) GOTO 12345
C Desi gn db t est
CALL DECCHK
C Exi t
12345 CONTI NUE
CALL D3FI N( I FI NDM )
CALL D3FEND
END

C- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LOGI CAL FUNCTI ON PROJ I N( )
C- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

CHARACTER*1 TEXT
I NTEGER I ERR
EXTERNAL D3I NI T, D3EMSG

PRI NT*, ' Ent er pr oj ect '
User Guide
Version 11.6
CALL D3I NI T( ' DAR' , ' SYSTEM' , ' XXXXXX' , ' NONE' , ' ' ,
I ERR )
PROJ I N = I ERR. EQ. 0
CALL D3EMSG( I ERR, . TRUE. , TEXT )
RETURN
END

C- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LOGI CAL FUNCTI ON MDBI N( )
C- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

CHARACTER*50 TEXT
I NTEGER I ERR
EXTERNAL D3MMDB, D3EMSG

PRI NT*, ' Sel ect MDB'
CALL D3MMDB( ' / PLANT' , ' ' , I ERR )
MDBI N = I ERR. EQ. 0
RETURN
END

C- - - - - - - - - - - - - - - - - - - - - -
SUBROUTI NE DECCHK
C- - - - - - - - - - - - - - - - - - - - - -

CHARACTER*50 TEXT, NAMES( 100)
CHARACTER*6 TYPES( 100) , TYPE, HCON, TCON, FLOW,
LNTP
LOGI CAL LOCK, BUI L, LHEA, LTAI , DETA, SHOP,
LSTR
LOGI CAL ORI L, POSI , LOFF
CHARACTER*50 NAME, OWNE, MATR
CHARACTER*50 FLUR, CASR, PSPE, I SPE, TSPE
User Guide
Version 11.6
CHARACTER*50 HSTU, HREF, TREF, SPRE, CATR, LSTU,
CREF
CHARACTER*120 DUTY, DSCO, PTSP, I NSC, FUNC
I NTEGER REV , EREC, CCEN, CCLA, SAFC
I NTEGER LEVE( 2) , OBST, ARRI
I NTEGER D3XLEN
REAL HPOS( 3) , HDI R( 3) , TPOS( 3) , TDI R( 3) ,
POS( 9)
REAL ORI ( 3) , ANGL

I NTEGER I SI Z, I ERR, LEAV, I DI SP
REAL XLEN, YLEN, ZLEN, HEI G, RADI
REAL BORE, HBOR, TBOR, TEMP, PRES
EXTERNAL D3MNAM, D3MNUM, D3UMON, D3RPAT, D3MREL,
D3RORL
EXTERNAL D3RPRL, D3EMSG
EXTERNAL D3QMEM, D3QSI T, D3XLEN, D3QZON, D3QPI P,
D3QBRA
EXTERNAL D3QTEE, D3QELB, D3QEQU, D3QBOX, D3QNOZ,
D3MMDB

PRI NT*, ' '
PRI NT*, ' Desi gn Dat abase Exampl e'
PRI NT*, ' - - - - - - - - - - - - - - - - - - - - - - - '
PRI NT*, ' '
I DI SP = 2
PRI NT*, ' Sel ect def aul t db t ype'
CALL D3MMDB( ' DESI GN/ PLANT' , ' ' , I ERR )
I F ( I ERR . NE. 0 ) THEN
PRI NT*, ' Shoul d have succeeded'
PRI NT*, ' I nst ead er r or i s: '
GOTO 12345
ENDI F
C Look at wor l d
User Guide
Version 11.6
CALL D3QMEM( I DI SP, 100, TYPES, NAMES, I SI Z, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C Look at si t e
CALL D3MNAM( ' / EQU' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
CALL D3QSI T( I DI SP, TYPE, NAME, OWNE, LOCK, POS,
ORI , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
I F ( NAME . NE. ' / EQU' ) THEN
PRI NT*, ' Expect i ng name / EQU got ' ,
NAME( : D3XLEN( NAME) )
GOTO 12345
ENDI F
C Look at zone
CALL D3MNUM( ' zone' , 3, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
CALL D3QZON( I DI SP, TYPE, NAME, OWNE, LOCK, POS,
ORI , PSPE,
+ I SPE, TSPE, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
I F ( NAME . NE. ' / EQ3' ) THEN
PRI NT*, ' Expect i ng name / EQU got ' ,
GOTO 12345
ENDI F
PRI NT*, ' '
User Guide
Version 11.6
C Pi pe det ai l s
CALL D3MNAM( ' / 250- B- 5' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
CALL D3QPI P( I DI SP, TYPE, NAME, OWNE, LOCK, BUI L,
SHOP,
+ BORE, TEMP, PRES, PSPE, I SPE, TSPE, MATR,
+ FLUR, CASR, CCEN, CCLA, DUTY, LNTP, EREC,
+ REV, DSCO, PTSP, I NSC, SAFC, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
I F ( NAME . NE. ' / 250- B- 5' ) THEN
PRI NT*, ' Expect i ng name / 250- B- 5 got ' ,
GOTO 12345
ENDI F
C Br anch det ai l s
CALL D3MNUM( ' BRAN' , 1, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
CALL D3QBRA( I DI SP, TYPE, NAME, OWNE, LOCK, BUI L,
LHEA,
+ LTAI , DETA, SHOP, LSTR, LNTP, EREC, HBOR,
+ TBOR, HCON, TCON, TEMP, PRES, FLOW, MATR,
+ FLUR, CASR, PSPE, I SPE, TSPE, CCEN, CCLA,
+ DUTY, DSCO, PTSP, I NSC, SAFC, HSTU, HREF,
+ TREF, HPOS, HDI R, TPOS, TDI R, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
I F ( NAME . NE. ' / 250- B- 5/ 1' ) THEN
PRI NT*, ' Expect i ng name / 250- B- 5/ 1 got
' , NAME( : D3XLEN( NAME) )
User Guide
Version 11.6
GOTO 12345
ENDI F
C Br anch PPoi nt s wi t h Moni t or i ng
CALL D3UMON( ' FULL' )
CALL D3RPAT( ' PH' , ' / EQ3' , POS( 1) , POS( 4) , BORE,
HCON, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3RPAT( ' pt ai l ' , ' wor l ' , POS( 1) , POS( 4) , BORE,
HCON, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
C Tee det ai l s
CALL D3MREL( ' FI RS' , ' TEE' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3QTEE( I DI SP, TYPE, NAME, OWNE, LOCK, POS ,
ORI ,
+ SPRE, LSTU, CREF, ARRI , LEAV, ANGL, HEI G,
+ RADI , BUI L, SHOP, ORI L, POSI , LOFF, I SPE,
+ TSPE, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C El bow det ai l s
CALL D3MREL( ' PREV' , ' ELBOW' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3QELB( I DI SP, TYPE, NAME, OWNE, LOCK, POS ,
ORI ,
+ SPRE, LSTU, CREF, ARRI , LEAV, ANGL, RADI ,
+ BUI L, SHOP, ORI L, POSI , I SPE, TSPE, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C El bo PPoi nt s wi t h Moni t or i ng
CALL D3RPAT( ' P1' , ' WORL' , POS( 1) , POS( 4) , BORE,
HCON, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
User Guide
Version 11.6
HCON, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C Equi det ai l s
CALL D3MNAM( ' / 1501B' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
CALL D3QEQU( I DI SP, TYPE, NAME, OWNE, LOCK, FUNC,
DSCO,
+ PTSP, I NSC, POS, ORI , I SPE, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
I F ( NAME . NE. ' / 1501B' ) THEN
PRI NT*, ' Expect i ng name / 1501B got ' ,
GOTO 12345
ENDI F
C Swi t ch on Moni t or i ng and check Pos and Or i
CALL D3RORL( ' owne' , POS, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3RORL( ' WORL' , POS, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3RPRL( ' ZONE' , POS, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3RPRL( ' / EQU' , POS, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C Box det ai l s
CALL D3MREL( ' FI RS' , ' BOX' , I ERR )
User Guide
Version 11.6
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3QBOX( I DI SP, TYPE, NAME, OWNE, LOCK, XLEN,
YLEN,
+ ZLEN, POS, ORI , LEVE, OBST, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C Box PPoi nt s wi t h Moni t or i ng
CALL D3RPAT( ' P1' , ' OWNE' , POS( 1) , POS( 4) , BORE,
HCON, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
HCON, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '
C Nozzl e det ai l s
CALL D3MREL( ' next ' , ' nozz' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
CALL D3QNOZ( I DI SP, TYPE, NAME, OWNE, LOCK, TEMP,
PRES,
+ POS, ORI , CREF, CATR, ANGL, HEI G, RADI ,
DUTY,
+ I SPE, I ERR )
I F ( I ERR . NE. 0 ) GOTO 12345
PRI NT*, ' '

12345 CONTI NUE
RETURN
END
The output from this example is as follows. Messages 'Entering D3Q...'
and 'Exiting D3Q...' result from setting the display flag (first argument of
D3Q routines) to 2.
Ent er pr oj ect
User Guide
Version 11.6


<si t e dat a>

Sel ect MDB
Success

Desi gn Dat abase Exampl e
- - - - - - - - - - - - - - - - - - - - - - -

Sel ect def aul t db t ype
Ent er i ng D3QMEM
Member s of WORL / *
1 SI TE / NEGATI VE- SI TE
2 SI TE / DI MENSI ON- SI TE
3 SI TE / VOLCAL. SI TE
4 SI TE / EX1- SI TE
5 SI TE / HANG- SI TE
6 SI TE / CI VI L
7 SI TE / I NTEST- SI TE
8 SI TE / EQU
9 SI TE / OBSTR
10 GPWL / GW1
Exi t i ng D3QMEM

Ent er i ng D3QMEM
Member s of SI TE / EQU
1 ZONE / EQ1
2 ZONE / EQ2
3 ZONE / EQ3
Exi t i ng D3QMEM

User Guide
Version 11.6
Ent er i ng D3QSI T
At t r i but es of SI TE / EQU
Ent er i ng D3QCMA
TYPE SI TE
NAME / EQU
OWNE / *
LOCK F
Exi t i ng D3QCMA
POS 0. 0000000E+00 0. 0000000E+00
0. 0000000E+00
ORI 0. 0000000E+00 0. 0000000E+00
0. 0000000E+00
Exi t i ng D3QSI T

Ent er i ng D3QMEM
Member s of ZONE / EQ3
1 EQUI / EQUI P- FALL
2 PI PE / FALL
3 PI PE / 100- B- 2
4 PI PE / 50- W- 3000
5 PI PE / 50- WD- 2400
6 PI PE / 50- W1- 3400
7 PI PE / 80- S12- 1400
8 PI PE / 200- N12- 1000
9 PI PE / 50- N12- 1800
10 PI PE / 150- W12- 2000
11 PI PE / 150- W12- 2200
12 PI PE / 100- C- 12
13 PI PE / 100- C- 13
14 PI PE / 150- A- 57
15 PI PE / 150- A- 3
16 PI PE / 40- B- 10
17 PI PE / 80- A- 11
18 PI PE / 80- B- 14
User Guide
Version 11.6
19 PI PE / 100- B- 1
20 PI PE / 80- B- 7
21 PI PE / 150- B- 6
22 PI PE / 100- B- 8
23 PI PE / 50- B- 9
24 PI PE / 200- B- 4
25 PI PE / 250- B- 5
Exi t i ng D3QMEM

Ent er i ng D3QZON
At t r i but es of ZONE / EQ3
Ent er i ng D3QCMA
TYPE ZONE
NAME / EQ3
OWNE / EQU
LOCK F
Exi t i ng D3QCMA
POS 0. 0000000E+00 0. 0000000E+00 100000. 0
ORI 0. 0000000E+00 0. 0000000E+00
0. 0000000E+00
PSPE =0/ 0
I SPE =0/ 0
TSPE =0/ 0
Exi t i ng D3QZON

Ent er i ng D3QMEM
Member s of PI PE / 250- B- 5
1 BRAN / 250- B- 5/ 1
2 BRAN / 250- B- 5/ 2
Exi t i ng D3QMEM

Ent er i ng D3QPI P
At t r i but es of PI PE / 250- B- 5
Ent er i ng D3QBPA
User Guide
Version 11.6
Ent er i ng D3QCMA
TYPE PI PE
NAME / 250- B- 5
OWNE / EQ3
LOCK F
Exi t i ng D3QCMA
BUI L F
SHOP F
TEMP - 100000. 0
PRES 0. 0000000E+00
PSPE / A3B
I SPE =0/ 0
TSPE =0/ 0
MATR =0/ 0
FLUR =0/ 0
CASR =0/ 0
CCEN 0
CCLA 0
DUTY Unset
LNTP Unset
EREC 0
DSCO Unset
PTSP Unset
I NSC Unset
SAFC 0
Exi t i ng D3QBPA
BORE 0. 0000000E+00
REV - 1
Exi t i ng D3QPI P

Ent er i ng D3QMEM
Member s of BRAN / 250- B- 5/ 1
1 GASK =8196/ 556
2 FLAN =8196/ 557
User Guide
Version 11.6
3 ELBO =8196/ 558
4 ELBO =8196/ 559
5 REDU =8196/ 560
6 TEE / 250- B- 5/ 1- T1
7 REDU =8196/ 562
8 ELBO =8196/ 563
9 ELBO =8196/ 564
10 FLAN =8196/ 565
11 GASK =8196/ 566
Exi t i ng D3QMEM

Ent er i ng D3QBRA
At t r i but es of BRAN / 250- B- 5/ 1
Ent er i ng D3QBPA
Ent er i ng D3QCMA
TYPE BRAN
NAME / 250- B- 5/ 1
OWNE / 250- B- 5
LOCK F
Exi t i ng D3QCMA
BUI L T
SHOP T
TEMP 466. 0000
PRES 340. 0000
PSPE / A3B
I SPE =0/ 0
TSPE =0/ 0
MATR =0/ 0
FLUR =0/ 0
CASR =0/ 0
CCEN 0
CCLA 0
DUTY Unset
LNTP Unset
User Guide
Version 11.6
EREC 0
DSCO Unset
PTSP Unset
I NSC Unset
SAFC 0
Exi t i ng D3QBPA
LHEA T
LTAI T
DETA F
LSTR F
HBOR 200. 0000
TBOR 200. 0000
HCON FGD
TCON FGD
FLOW Unset
HSTU / A3B/ 200P
HREF / 1301- S2
TREF / 1301- S3
HPOS - 319150. 0 297760. 0 2105. 000
HDI R 0. 0000000E+00 0. 0000000E+00 1. 000000
TPOS - 319150. 0 302640. 0 2105. 000
TDI R 0. 0000000E+00 0. 0000000E+00 1. 000000
Exi t i ng D3QBRA
Exi t i ng subr out i ne D3UMON
Ent er i ng subr out i ne D3RPAT
I nput ar gument s:
PPoi nt number PH
Coor di nat e syst em / EQ3
Exi t i ng subr out i ne D3RPAT
Posi t i on E - 319150 N 297760 U 2105
Di r ect i on uni t vect or E 0 N 0 U 1
Bor e 200
Connect i on t ype FGD
User Guide
Version 11.6
Er r or code 0
I nput ar gument s:
PPoi nt number pt ai l
Coor di nat e syst em wor l
Posi t i on E - 319150 N 302640 U 102105
Bor e 200
Connect i on t ype FGD
Er r or code 0
I nput ar gument s:
Ent er i ng D3QTEE
At t r i but es of TEE / 250- B- 5/ 1- T1
Ent er i ng D3QCPA
Ent er i ng D3QCMA
TYPE TEE
NAME / 250- B- 5/ 1- T1
OWNE / 250- B- 5/ 1
LOCK F
Exi t i ng D3QCMA
POS - 318315. 3 300229. 6 3886. 000
ORI 0. 0000000E+00 0. 0000000E+00
0. 0000000E+00
SPRE / A3B/ 250T
LSTU =0/ 0
BUI L F
SHOP F
ORI FL T
POSFL T
I SPE =0/ 0
User Guide
Version 11.6
TSPE =0/ 0
Exi t i ng D3QCPA
CREF / 250- B- 5/ 2
ANGL 90. 00000
HEI G 0. 0000000E+00
RADI 0. 0000000E+00
LOFF F
Exi t i ng D3QTEE

Ent er i ng D3QELB
At t r i but es of ELBO =8196/ 559
Ent er i ng D3QCPA
Ent er i ng D3QCMA
TYPE ELBO
NAME =8196/ 559
OWNE / 250- B- 5/ 1
LOCK F
Exi t i ng D3QCMA
POS - 318315. 3 297759. 1 3885. 950
ORI 180. 0000 0. 0000000E+00 90. 00000
SPRE / A3B/ 200EL
LSTU / A3B/ 200P
BUI L F
SHOP F
ORI FL T
POSFL T
I SPE =0/ 0
TSPE =0/ 0
Exi t i ng D3QCPA
CREF =0/ 0
ANGL 90. 00000
RADI 0. 0000000E+00
Exi t i ng D3QELB

User Guide
Version 11.6
I nput ar gument s:
PPoi nt number P1
Coor di nat e syst em WORL
Posi t i on E - 318620 N 297759 U 103886
Di r ect i on uni t vect or E - 1 N 0 U 0
Bor e 200
Connect i on t ype BWD
Er r or code 0
I nput ar gument s:
PPoi nt number P2
Posi t i on E - 318315 N 298064 U 103886
Bor e 200
Connect i on t ype BWD
Er r or code 0
I nput ar gument s:

Ent er i ng D3QMEM
Member s of EQUI / 1501B
1 BOX =8196/ 151
2 PYRA =8196/ 152
3 CYLI =8196/ 153
4 CYLI =8196/ 154
5 RTOR =8196/ 155
User Guide
Version 11.6
6 NOZZ / 1501B- SUCT
7 NOZZ / 1501B- DI SC
Exi t i ng D3QMEM

Ent er i ng D3QEQU
At t r i but es of EQUI / 1501B
Ent er i ng D3QCMA
TYPE EQUI
NAME / 1501B
OWNE / EQ2
LOCK F
Exi t i ng D3QCMA
FUNC Unset
DSCO Unset
PTSP Unset
I NSC Unset
POS - 314490. 0 303145. 0 340. 0000
ORI 0. 0000000E+00 0. 0000000E+00 180. 0000
I SPE =0/ 0
Exi t i ng D3QEQU

Ent er i ng subr out i ne D3RORL
I nput ar gument s:
Coor di nat e syst em owne
Exi t i ng subr out i ne D3RORL
Or i ent at i on uni t vect or s
X axi s E - 1 N 0 U 0
Y axi s E 0 N - 1 U 0
Z axi s E 0 N 0 U 1
Er r or code 0
Ent er i ng subr out i ne D3RORL
I nput ar gument s:
User Guide
Version 11.6
Exi t i ng subr out i ne D3RORL
Or i ent at i on uni t vect or s
X axi s E - 1 N 0 U 0
Y axi s E 0 N - 1 U 0
Z axi s E 0 N 0 U 1
Er r or code 0
Ent er i ng subr out i ne D3RPRL
I nput ar gument s:
Coor di nat e syst em ZONE
Exi t i ng subr out i ne D3RPRL
Posi t i on E - 314490 N 303145 U 340
Er r or code 0
Ent er i ng subr out i ne D3RPRL
I nput ar gument s:
Coor di nat e syst em / EQU
Exi t i ng subr out i ne D3RPRL
Posi t i on E - 314490 N 303145 U 100645
Er r or code 0
I nput ar gument s:

Ent er i ng D3QBOX
At t r i but es of BOX =8196/ 151
Ent er i ng D3QCMA
TYPE BOX
NAME =8196/ 151
OWNE / 1501B
LOCK F
Exi t i ng D3QCMA
User Guide
Version 11.6
XLEN 510. 0000
YLEN 1390. 000
ZLEN 110. 0000
POS 0. 0000000E+00 - 676. 0000 - 285. 0000
ORI 0. 0000000E+00 0. 0000000E+00
0. 0000000E+00
LEVE 0 10
OBST 2
Exi t i ng D3QBOX

I nput ar gument s:
PPoi nt number P1
Coor di nat e syst em OWNE
Posi t i on E 255 N - 676 U - 285
Bor e 0
Connect i on t ype
Er r or code 0
I nput ar gument s:
PPoi nt number P2
Posi t i on E - 314490 N 303126 U 100360
Di r ect i on uni t vect or E 0 N - 1 U 0
Bor e 0
Connect i on t ype
Er r or code 0
User Guide
Version 11.6
I nput ar gument s:

Ent er i ng D3QNOZ
At t r i but es of NOZZ / 1501B- SUCT
Ent er i ng D3QCMA
TYPE NOZZ
NAME / 1501B- SUCT
OWNE / 1501B
LOCK F
Exi t i ng D3QCMA
TEMP - 100000. 0
PRES 0. 0000000E+00
POS 0. 0000000E+00 0. 0000000E+00
0. 0000000E+00
ORI 0. 0000000E+00 0. 0000000E+00 180. 0000
CREF / 100- B- 8/ 1
CATR / NFAAPAMM
ANGL 90. 00000
HEI G 100. 0000
RADI 0. 0000000E+00
DUTY Unset
I SPE =0/ 0
Exi t i ng D3QNOZ

Success

User Guide
Version 11.6
Subroutine Specifications
5 Subroutine Specifications
5.1 Introduction
Summaries and detailed specifications are included for all PDMS data
access routines and all general utility routines. Details of auxiliary
routines are presented separately in Appendix D.
PDMS data access routines are named D3yxx(x), where 'y' denotes the
type of action performed by the routine and xxx or yxx(x) is a mnemonic
for the action. The 'D3' denotes PDMS, whilst the DARs package for
PEGS uses an analogous D2yxxx naming convention. Many of the PEGS
and PDMS routines have names that are identical apart from the D2/D3
prefix.
Identical general utility routines applicable to PEGS and PDMS DARs
are named D2Uxxx and D3Uxxx.
The following conventions have been adopted within each routine:

There are no modified arguments; arguments are either 'input' or
'return' arguments.
Return arguments are shown underlined.
Input arguments are never modified. The programmer can safely
enter constants. Where the routine specification states that input
arguments are converted to upper case or subjected to any other
modification, this is carried out upon local variables and the
modifications are not returned in the arguments.
Some character input arguments can be abbreviated. Minimum
abbreviations are indicated by a '/' embedded in each valid entry. For
example, MEMB/ER can be abbreviated to MEMB or MEMBE.
However, MEMBO would be rejected. Where any option has no '/', the
entry cannot be abbreviated. In a similar way, some character input
arguments may be abbreviated in accordance with normal PDMS 11
usage, e.g. ELB/OW.

User Guide
Version 11.6
If character arguments are declared too short for the return data, the
action of the routine will depend on the use to which the data is likely
to be put. For example, a truncated name attribute returned by
D3RNAM will result in an error condition (and a blank string will be
returned), whereas a truncated error message returned by D3EMSG
will not raise an error condition. The action in each case is described
fully in the specification.
All return character arguments are blank padded. The programmer
can use the data access utility routine D3ULEN to find the significant
length.
Where a data access routine returns a error code, the possible values are
indicated in the specification for the routine.
Positive values denote an error condition; zero denotes no error.
If a positive error code is returned, an internal error flag is set to prevent
the next data access routine from executing. If the programmer wishes
to cancel an intentional error condition, and error handling has not been
switched off by D3ECHK, then routine D3ERST must be called to reset
the error flag before the next routine is called.
The programmer should not call D3ERST without proper cause,
otherwise the purpose of the error flag is negated.
User Guide
Version 11.6
5.2 Subroutine Summaries
5.2.1 Initialisation Routines, D3Ixxx
D3INIT Initialise
This routine initialises the system for the PDMS data access routines
and sets the monitoring level. It validates the project name and the
username and password nominated in that project, all of which may be
entered as routine arguments or interactively. It opens the required
database files and records the presence of the user in the PDMS system.
5.2.2 Navigation Routines, D3Mxxx
D3MMDB Select an MDB
This routine selects an MDB within the requested PDMS project, opens
the MDB databases and navigates to the default database world. The
user has the option of specifying the default database type or can allow it
to default to the type of the first MDB database.
D3MCDB Make a Database Current in MDB
This routine makes a named database in the current MDB current at the
specified position. Other databases are shuffled up or down, as
necessary. This is equivalent to the PDMS command CURRENT.
D3MEDB Exchange Databases in MDB
This routine exchanges a current and a deferred database in the current
MDB. One of the named databases must have 'current' status and the
other must have 'deferred' status. Their status and list order position
will be reversed. is equivalent to the PDMS command EXCHANGE.
D3MDDB Defer a Database in MDB
This routine defers a named database in the current MDB. This is
equivalent to the PDMS command DEFER.
D3MQDB Query Database in Current MDB
This routine reads the name and status of the database in a defined
position in the current MDB. If executed within a loop, this is equivalent
to the PDMS command STATUS.

User Guide
Version 11.6
D3MNAM Move to an Element by Name or Reference Number
This routine navigates the hierarchy to an element specified by name or
reference number.
D3MNUM Move to an Item by Order Position
This routine navigates the hierarchy to an element by specified list order
position. This mimics PDMS commands such as '1', 'BRAN 3', 'EQUIP 1'.
The type of element may be a PDMS noun (e.g. BRANCH) or special
keywords to move in the current list or to move to a member owned by
the current element.
D3MREL Move Relative to the Current Position
This routine navigates the hierarchy relative to the current database
position, mimicking PDMS commands such as 'PREV', 'LAST MEMB',
'NEXT BOX'.
D3MOWN Move to the Owner of the Current Element
This routine navigates to the owner of the current element.
D3MSAV Save Current Database Position
This routine saves the current database position so that it may
subsequently be restored by calling D3MRST. This is more efficient than
using D3RNAM and D3MNAM.
Calls to D3MSAV and D3MRST must be paired and can be nested to a
depth of 10.
D3MRST Restore Last Saved Database Position
This routine restores the database position saved by the previous call to
D3MSAV.
5.2.3 Read Routines, D3Rxxx
D3RPRJ Read Project Data Item
This routine retrieves project code, name, number, description or
message from the System Database.
D3RTYP Read the PDMS Type of the Current Element
This routine reads the PDMS 'type' attribute of the current element.
D3RPRL Read the Position of the Current Element

User Guide
Version 11.6
This routine reads the position of the current element relative to a
specified co-ordinate system.
D3RORL Read the Orientation of the Current Element
This routine reads the orientation of the current element relative to a
specified co-ordinate system.
D3RNAM Read Element Name or a Name Attribute
This routine reads the name of the current element or the name of a
reference attribute of the current element. It returns a reference number
if the requested name does not exist.
D3RREF Read Element Reference Number or a Reference Number
Attribute
This routine reads the reference number of the current element or of a
reference attribute of the current element.
D3RINT Read an Integer Attribute
This routine reads a specified integer attribute of the current element.
D3RIA Read an Integer Array Attribute
This routine reads a specified integer array attribute of the current
element.
D3RREA Read a Real Attribute
This routine reads a specified real attribute of the current element.
D3RRA Read a Real Array Attribute
This routine reads a specified real array attribute of the current element.
D3RLOG Read a Logical Attribute
This routine reads a specified logical attribute of the current element.
D3RLA Read a Logical Array Attribute
This routine reads a specified logical array attribute of the current
element.
D3RRFA Read a Reference Number Array Attribute
This routine reads a specified reference number array attribute of the
current element.
D3RTEX Read a Text Attribute
This routine reads a specified text attribute of the current element.
D3RWOR Read a Word Attribute

User Guide
Version 11.6
This routine reads a specified PDMS word attribute of the current
element.

D3RWA Read a Word Array Attribute
This routine reads a specified PDMS word array attribute of the current
element.

D3RPAT Read PPOINT Attributes
This routine reads the PPoint attributes (position, direction, connection
type and bore) for a piping component or equipment primitive, relative to
a specified co-ordinate system.
The specified PPoint may be PH, PT, PA, PL, or P<n> (i.e. P1, P2 etc.)

D3RUDA Read Lists of UDA Names, Abbreviations and Types
This routine reads, for a specified element type, parallel lists of UDA
names, lengths of minimum valid abbreviations and attribute types.

D3RUNI Read Unit of Measurement for a Real or Integer UDA
This routine returns a text string indicating the UNIT (of measurement)
which applies to the specified UDA. Only real or integer attributes may
have a UNIT specified. This routine will generally be used in
conjunction with the attribute retrieval routines (D3RINT, D3RIA,
D3RREA and D3RRA).

D3RPTX Read REPORTER Text for a UDA
This routine reads the REPORTER text for a given UDA. REPORTER
text may be up to 20 characters long and is used in column headers by
the PDMS module REPORTER.

D3RDAT Read Latest MDB Date-Stamp
This routine returns the latest date-stamp for any database in the mdb
system.

User Guide
Version 11.6
D3RBDU Read Bore and Distance Units
This routine returns the bore and distance units defined for the current
MDB. It returns two character strings containing the linear units.

D3RBOX Read Enclosing Box Co-ordinates
This routine reads the co-ordinates of the surrounding box for the
current element or its leave tube. This is valid for any database element
and is equivalent to the CLASHER command 'QUERY BOX'.
5.2.4 Error Handling Routines, D3Exxx
D3ECHK Switch Error Handling ON and OFF
This routine enables the user to switch the internal error handling
mechanism on and off. The default action at program entry is for error
handling to be switched ON.

D3EMSG Return Error Message for a given Error Code
Most data access routines return an error code to denote an error
condition. If the programmer wishes to output the nature of the error, he
may call this routine.
It returns the error message corresponding to a given error code. The
routine will display the error message if requested.

D3ERST Reset Internal Error Flag
This routine resets the PDMS data access internal error flag.
Whenever a positive error code is returned by a PDMS data access
routine, an internal error flag is set to prevent the next routine from
executing. If the programmer wishes to cancel an intentional error
condition and error handling has not been switched off by D3ECHK, then
this routine must be called to reset the error flag before the next routine
is called.
5.2.5 Utility Routines, D3Uxxx
D3UMON Change Monitor Level

User Guide
Version 11.6
This routine sets or resets the monitoring level. It re-defines the level
set in the last call to the routine or set in D3INIT.

D3UDEH Dehash a Hashed PDMS Word
This routine converts a hashed PDMS word (a PDMS word represented
as an integer number) into the PDMS word.
1

D3ULDS Test Latest MDB Date-Stamp
This routine checks whether any database in the current MDB has been
date-stamped later than a specified date/time. It is a utility routine built
on routine D3RDAT.

D3UINI Query Initialisation
This routine returns a true or false flag, depending on whether or not a
PDMS project is currently initialised.
5.2.6 Termination Routines, D3Fxxx
D3FIN Finish
This is the termination routine for the current PDMS project. It closes
all the database files. Access to another PDMS project requires a further
call to D3INIT.

D3FEND Exit
With the withdrawal of D3IBEG at Mk10.2, this routine has become an
optional way of stopping a DARs application program. It results in a
program exit and is equivalent to a CALL EXIT statement.
5.2.7 General Utility Routines, D3Uxxx
D3UGTU Get File Unit
This function allocates an unused FORTRAN file unit for use by the
application program.

1
Prior to PDMS 11.1, a PDMS word was represented by a real number.
User Guide
Version 11.6
D3UCLU Clear File Unit
This function cancels an allocated FORTRAN file unit no longer required
by the application program.

D3ULEN Length of Character String
This function returns the significant length of a character string. That
is, the length after stripping off all trailing blanks.

D3UCTI Character to Integer
This function converts the digits in a given string to an integer value. It
will also extract the first valid integer from a string containing other
characters.

D3UCTR Character to Real Number
This function converts the digits in a given string to a real number. It
will also extract the first valid real number from a string containing
other characters. The number may be in decimal or exponential format.

D3UDTM Return System Date and Time
This routine returns the current system date and time in two formats.
5.3 Detailed Subroutine Specifications
The following pages provide the subroutine specifications for all PDMS
and general utility routines in alphabetical order. Each subroutine
specification contains the following:

1. The subroutine (or function) statement.
2. The type declaration for each argument as it appears in the routine.
3. A description of the function of the routine.
4. A full definition of each argument.
5. A list of possible returned error codes.
6. Other possible errors and warnings.
User Guide
Version 11.6
D3ECHK Switch Error Handling ON and OFF
Specification
SUBROUTI NE D3ECHK( CD3ERR )

CHARACTER*( *) CD3ERR
Description
This routine enables the user to switch the internal error handling
mechanism on and off. The default action at program entry is for error
handling to be switched ON. When ON, the user must call D3ERST to
reset the internal error flag whenever a DARs routine generates an error
condition (see D3ERST). When OFF, routine D3ERST need not be
called. Unlike most other D3 routines, it does not require a previous
successful call to D3INIT. Thus it can be used to switch error handling
off before the first call to D3INIT.
Arguments
CD3ERR Internal error switch 'ON' or 'OFF'
Any text other than 'OFF', after upper-casing, is interpreted as
'ON'.
Errors/Warnings
No errors or warnings are generated by this routine
User Guide
Version 11.6
D3EMSG Return Error Message
Specification
SUBROUTI NE D3EMSG( I D3ERR, LD3DI S, CD3MSG )

CHARACTER*( *) CD3MSG
LOGI CAL LD3DI S
I NTEGER I D3ERR
Description
This routine returns the error message corresponding to a given error
code. Unlike other D3 routines, it does not require a previous successful
call to D3INIT. Thus it can be used to interpret a error code returned by
D3INIT itself.
If the error code is invalid, the message 'Unknown error' will be
returned.
The routine will display the error message if requested.
Arguments
ID3ERR Error code for which the corresponding message is required.
If the value is invalid, the message 'Unknown error' is returned.

LD3DIS Display flag.
.TRUE. - display error message to the default device
.FALSE. - display nothing

CD3MSG Error message corresponding to error code.
Maximum length of text string is 50 characters. If the supplied
character field is shorter than the returned message, the message
will be truncated but no error condition will arise. If the field is too
long, it will be padded with blanks.
The returned (and printed) error message will be as listed in this
section of the User Guide and in Appendix C.
User Guide
Version 11.6
Errors
No errors or warnings can arise in the use of this routine, other than
those described above. It may return 'INVALID CALL TO D3EMSG' if
called prior to a call to D3INIT.
User Guide
Version 11.6
D3ERST Reset Internal Error Flag
Specification
SUBROUTI NE D3ERST
Description
This routine resets the PDMS data access internal error flag.
Whenever a positive error code is returned by a PDMS data access
routine, an internal error flag is set to prevent the next D3 routine from
executing. If the programmer wishes to cancel an intentional error
condition, and error handling has not been switched off by D3ECHK,
then routine D3ERST must be called to reset the error flag before the
next routine is called. The programmer should not call D3ERST without
proper cause, otherwise the purpose of the error flag is negated.
Arguments
None
Errors/Warnings
No errors or warnings are generated by this routine.
User Guide
Version 11.6
D3FEND Exit System
Specification
SUBROUTI NE D3FEND
Description
This routine was necessary prior to Mk10.2 as a means of terminating
DARs in conjunction with D3IBEG. It remains available and results in a
program exit, equivalent to a CALL EXIT statement. Programmers
should call D3FEND or EXIT but are advised not to use a STOP
statement as this may be trapped by Aveva software and give rise to a
warning message.
Arguments
None
Errors/Warnings
No errors or warnings are generated by this routine.
User Guide
Version 11.6
D3FIN Finish
Specification
SUBROUTI NE D3FI N( ID3ERR )
I NTEGER I D3ERR
Description
This is the termination routine for a PDMS project.
This routine signals that the application has completed its function in
respect of the current PDMS project. It closes all PDMS database files
and removes the user from the system database/site-file. Any error code
set on entry to this routine is preserved and returned. This routine has
no error conditions of its own.
This routine should always be called at the end of a data access
applications program. It may called several times in a program, in which
case, calls should match the calls to D3INIT one for one. If D3FIN is
called without a previous call to D3INIT, it will have no effect.
This routine is called automatically from D3INIT in the event of an error
condition and from D3MMDB in the event of a serious error (e.g. corrupt
databases). It is also called automatically by D3INIT if there have been
consecutive calls to D3INIT without a call to D3FIN. Automatic calls are
not shown when monitoring is activated.
If this routine is not called before terminating a program, or if the
program terminates abnormally, project database files will remain open
(with some operating systems) and should be closed by the user.
Arguments
ID3ERR Error code (not used; for possible future use)
Possible values are:
Any error code set prior to this routine is preserved and returned
User Guide
Version 11.6
D3INIT Initialise
Specification
SUBROUTI NE D3I NI T( CD3PRJ , CD3USR, CD3PAS, CD3MON,
CD3RWK, ID3ERR )

CHARACTER*( *) CD3PRJ , CD3USR, CD3PAS, CD3MON, CD3RWK
I NTEGER I D3ERR
Description
This routine initialises the system for the PDMS data access routines
and so must be called before any of the other routines. It identifies the
PDMS project, validates the PDMS project username and password, and
records the presence of the user in the PDMS system. If an error occurs
then an error code as specified below is returned and the project is closed
down with an automatic call to D3FIN. The project, username and
password may be entered as arguments or interactively at runtime in a
manner similar to the PDMS entry procedure.
This routine may be called more than once in a program. If the
programmer has not previously called D3FIN to close down the first
project, then D3FIN will be called automatically.
The user is allowed three attempts at calling D3INIT. After the third
consecutive unsuccessful attempt, a corresponding error condition will be
raised and all successive attempts will be unsuccessful. On successful
completion of D3INIT the counter is reset and the user is allowed a
further three attempts at a subsequent project.
If any navigation or attribute retrieval routine is called prior to a
successful D3INIT, error 3 (Routine D3INIT has not been called) will be
returned to the user and no further action will be taken.
A monitoring facility may be invoked to assist the programmer in
tracking down errors. Three levels of monitoring are available: FULL,
SOME and NONE. 'SOME' monitoring will cause the names of
databases opened by D3MMDB to be output. 'FULL' monitoring will in
addition cause the details of all the data access routines which are called
together with their arguments to be output to the default output device,
including all warning/error conditions encountered. By default no
monitoring is provided. The monitoring level can be changed by a
subsequent call to D3UMON.
User Guide
Version 11.6
Arguments
CD3PRJ PDMS project name (3 characters), e.g. 'XXX'
Input characters will be converted to upper case. Strings exceeding
three characters will be truncated.
If the argument is blank (' '), the routine will prompt the user
interactively for the project name in the manner of the PDMS entry
procedure. The user is allowed three attempts to enter a valid
project name. As with PDMS, a valid but non-existent project name
will result in an error condition (error 108).

CD3USR PDMS Username (up to 32 characters), e.g. 'SMITH'
32 characters will be truncated.
If one or both of the CD3USR and CD3PAS arguments are blank,
the routine will prompt interactively. The user will be allowed
three attempts at entering a valid user/password combination.

CD3PAS User password (up to 6 characters).
Will differentiate between upper and lower case characters (PDMS
password is 'case-sensitive'). Strings exceeding six characters will
be truncated.
If one or both of the CD3USR and CD3PAS arguments are blank,
the routine will prompt interactively. The user will be allowed
three attempts at entering a valid user/password combination.

CD3MON Required monitor level (up to 4 characters).
four characters will be truncated. Any string other than 'SOME' or
'FULL' (after truncation) will be interpreted as 'NONE'.
NONE no monitoring. If required, D3EMSG can be called
selectively to output messages.

SOME display names and types of databases opened by
D3MMDB.

User Guide
Version 11.6
FULL as SOME plus display routine name and values of
input and output arguments for all routines called and
display all non-zero error messages.

User Guide
Version 11.6
CD3RWK Read/write key (for future use)
Enter as ' ' in this release. The argument will be ignored.

ID3ERR Error code.
0 Success
2 Internal error code set on entry
101 Error opening Dabacon workfile
102 Bad password
103 Unknown username
104 Too many users in project
105 Project currently locked
106 Project is incompatible version
107 Too many failed initialisations
108 Project not found
109 Error opening runfile data file
115 Sitefile/Security error
116 Invalid project name
119 System database error
Other Error Conditions
Only very few (and serious) error conditions result in immediate stop of
the DARs application program during a call to D3INIT. In each case, a
suitable error message will be output to the default output device.
D3MCDB Make a Database Current in MDB
Specification
SUBROUTI NE D3MCDB( CD3NAM, I D3POS, ID3ERR )

CHARACTER*( *) CD3NAM
I NTEGER I D3POS, I D3ERR
User Guide
Version 11.6
Description
This routine makes a named database in the current MDB current at the
specified position. Other databases are shuffled up or down, as
necessary. This is equivalent to the PDMS command CURRENT.
If an error occurs then an error code is returned as specified below and
the named database remains in an unchanged state. The change in
database status is temporary, for the duration of the DARs application,
similar to the use of CURRENT in the DESIGN module.
Arguments
CD3NAM The name of the database.

ID3POS The list order position required.
If the specified position is greater than the existing number of
current databases (but less than 100) the database will be made
current at the next position. A position less than 1 or greater than
the maximum possible (currently 100) will result in error code 125.
ID3ERR Error code.
0 Success
3 Routine D3INIT has not been called
4 Routine D3MMDB has not been called
120 Database not found
121 Database not in current MDB
122 Database already current
124 Too many current databases
125 Invalid database position
User Guide
Version 11.6
D3MDDB Defer a Database in MDB
Specification
SUBROUTI NE D3MDDB( CD3NAM, ID3ERR )

I NTEGER I D3ERR
Description
This routine defers a named database in the current MDB. This
database is also placed in the last list order position and other databases
are shuffled up to fill the gap. This is equivalent to the PDMS command
DEFER.
the named database remains in an unchanged state. The change in
similar to the use of DEFER in the DESIGN module.
Arguments
CD3NAM The name of the database.

ID3ERR Error code.
0 Success
123 Database not current
User Guide
Version 11.6
D3MEDB Exchange Databases in MDB
Specification
SUBROUTI NE D3MEDB( CD3NM1, CD3NM2, ID3ERR )

CHARACTER*( *) CD3NM1, CD3NM2
I NTEGER I D3ERR
Description
This routine exchanges a current and a deferred database in the current
MDB. One of the named databases must have 'current' status and the
other must have 'deferred' status before this routine is called. Following
successful execution their status and list order positions will be reversed.
This is equivalent to the PDMS command EXCHANGE.
the named databases remain in an unchanged state. The change in
similar to the use of EXCHANGE in the DESIGN module.
Error codes 122 and 123 require a slightly different interpretation than
suggested by the standard text (see below). Error codes 120 and 121 may
apply to either database.
Arguments
CD3NM1 The name of the first database.

CD3NM2 The name of the second database.
The order of the two databases is not important.

ID3ERR Error code.
0 Success
User Guide
Version 11.6
122 Database already current (i.e. both are current)
123 Database not current (i.e. both are deferred)
User Guide
Version 11.6
D3MMDB Select MDB
Specification
SUBROUTI NE D3MMDB( CD3MDB, CD3RWK, ID3ERR )

CHARACTER*( *) CD3MDB, CD3RWK
I NTEGER I D3ERR
Description
This routine (re)selects an MDB within the requested PDMS project. It
closes any PDMS databases that this user has open and, by default, it
opens all current databases in the MDB in read mode and updates the
PDMS system database accordingly. Subsequent database navigation
will have access to the MDB databases in the order determined by the
LIST MDB command in PDMS. That is, the default database is the first
database, which may for example be a design database or a catalogue
database. A further option allows the user/programmer to specify the
default database and, at the same time, to limit the number of databases
that are opened.
After a successful call to this routine, the current position is the world
corresponding to the default database.
If an error occurs then an error code as specified below is returned and
all databases in the MDB are closed. To allow the programmer to use
this routine interactively, some error conditions (110, 111, 117, 118) do
no more than set the internal error flag and return the error code. This
allows the programmer to call the routine repeatedly to allow the user to
select a valid MDB. All other errors, which generally denote an more
serious problem, result in an automatic call to D3FIN to close the project
down.
If any navigation or attribute retrieval routine is called prior to a
successful D3MMDB, error 4 (Routine D3MMDB has not been called)
will be returned to the user and no further action will be taken.
When SOME or FULL monitoring is activated, a list of all databases
opened, together with open mode and database type, is output to the
default output device.
User Guide
Version 11.6
Arguments
CD3MDB
Default database (up to 9 characters) & MDB Name (up to 32
characters, including the leading '/'), concatenated together.

The default database is interpreted as the text string preceding the
first '/' and it will be converted to upper case. If omitted (CD3MDB
starts with a '/'), the default database will be the first database in
the MDB. The following keywords are valid:
Keyword Default database Other databases open
DES/IGN Design (DESI) CATA PROP DICT
CAT/ALOGUE Catalogue (CATA) PROP DICT
PROP/ERTY Properties (PROP) CATA DICT
PAD/DLE PADDLE (PADD) DESI CATA PROP DICT
DIC/TIONARY Dictionary (DICT) None
Blank or null 1st database All
If a default database is specified, all databases of the types specified
in the above table are opened by this routine.
The MDB name (the string commencing with the first '/'), e.g.
'/MDB1' will NOT be converted to upper case (MDB name is case-
sensitive). Names exceeding 32 characters will be truncated.
Examples of valid entries for this argument:
DESI/PLANT : Default database DESI, MDB /PLANT
CAT/TEST : Default database CATA, MDB /TEST
/PLANT : No default database (defaults to first), MDB /PLANT

CD3RWK Read/write key (for future use)
Enter as ' ' in this release. The argument will be ignored.
User Guide
Version 11.6
ID3ERR Error code.
0 Success
110 MDB not found
111 No databases to open
112 Corrupt databases
113 Databases in use
114 Error opening database file
117 Invalid default database type
118 No databases of default type in MDB
User Guide
Version 11.6
D3MNAM Move to an Element by Name
Specification
SUBROUTI NE D3MNAM( CD3NAM, ID3ERR )

I NTEGER I D3ERR
Description
This routine navigates the hierarchy by an element name or reference
number. If an error occurs then an error code as specified below is
returned and the database position is not updated.
Arguments
CD3NAM Element name (up to 50 characters) or reference number
Should include the leading '/' if a name or the '=' and '/' characters if
a reference number, e.g. '/C1101', '=29/1301'.
For a name, an input string exceeding 50 characters will be
truncated and input characters will NOT be converted to upper
case.
For a reference number, any string that is not of the form '=m/n',
where m and n are valid integers, will be rejected with error code 9.

ID3ERR Error code.
0 Success
9 Bad name/reference argument
402 Undefined name/reference
User Guide
Version 11.6
D3MNUM Move to Element by Order Position
Specification
SUBROUTI NE D3MNUM( CD3TYP, I D3LI S, ID3ERR )

CHARACTER*( *) CD3TYP
I NTEGER I D3LI S, I D3ERR
Description
This routine navigates the hierarchy by list order position. It enables the
user to either move to an explicit list order position, or to move to the nth
member of a particular element. It mimics PDMS commands such as '1',
'BRAN 3', 'EQUIP 1'. The type of element specified may be a PDMS
noun or special keywords to move in the current list or to move to a
member owned by the current element. If an error occurs then an error
code as specified below is returned and the database position is not
updated.
Arguments
CD3TYP Type of element to be selected.
This may be a special keyword or a PDMS noun, e.g. 'PIP/E', 'BOX',
'SPCO/MPONENT'.
Input characters will be converted to upper case. Abbreviations
accepted in PDMS will be accepted by this routine (e.g. 'PIP', 'SPCO'
are accepted)
The following special keywords are valid:

ELEM/ENT : Move in the current list
MEMB/ER : Move to a member owned by the current element

ID3LIS Element's list position in the hierarchy, e.g. 1, 8
An entry greater than the highest available position will result in
error code 203 (List exhausted). An illegal value (e.g. negative) will
result in error code 10 (Argument has illegal value).

User Guide
Version 11.6
ID3ERR Error code.
0 Success
10 Argument has illegal value
201 Element has no list part
202 No members
203 List exhausted
205 Cannot access this type of element
User Guide
Version 11.6
D3MOWN Move to Owner of Current Element
Specification
SUBROUTI NE D3MOWN( ID3ERR )

I NTEGER I D3ERR
Description
This routine navigates to the owner of the current element. If an error
occurs then an error code as specified below is returned and the database
position is not updated.
Arguments
ID3ERR Error code.
0 Success
204 Current element has no owner
User Guide
Version 11.6
D3MQDB Query database in Current MDB
Specification
SUBROUTI NE D3MQDB( I D3POS, CD3NAM, CD3TYP, ID3STA,
ID3ERR )

CHARACTER*( *) CD3NAM, CD3TYP
I NTEGER I D3POS, I D3STA, I D3ERR
Description
This routine reads the name and status of the database in a defined
position in the current MDB. If executed within a loop, this is equivalent
to the PDMS command STATUS.
If an error occurs then an error code is returned as specified below,
ID3STA is returned as zero and the character arguments are returned
blank. The error code can be used to terminate a loop if the user wishes
to query the status of all databases.
Arguments
ID3POS The list order position of the database.

CD3NAM The name of the database at this position.
The database name can be up to 64 characters long. If this
character string is declared shorter than the current database name
length, the returned string will be truncated and no error will
result. The name is of the form team/name (e.g. 'PIPE/DESIGNA').

CD3TYP The type of the database.
This is the four-character database type (e.g. DESI, CATA). If this
character string is declared shorter than 4, the returned string will
be truncated and no error will result.

User Guide
Version 11.6
ID3STA Status of the database.
The returned status has a value between 1 and 3, as follows:
1: Current, Read
2: Current, Closed
3: Deferred
ID3STA will be returned as zero if the routine fails.

ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3MREL Move Relative to the Current Position
Specification
SUBROUTI NE D3MREL( CD3POS, CD3TYP, ID3ERR )

CHARACTER*( *) CD3POS, CD3TYP
I NTEGER I D3ERR
Description
This routine navigates the hierarchy relative to the current database
position, mimicking PDMS commands such as PREV, LAST MEMB,
NEXT BOX. The movement is specified using the two arguments
CD3POS, which specifies the relative position (PREV, NEXT, LAST,
FIRS) and CD3TYP which qualifies the above instruction with the type
of element required (a keyword or a PDMS noun). If an error occurs then
an error code as specified below is returned and the database position is
not updated.
Arguments
CD3POS The relative position.
Input characters will be converted to upper case.
The following keywords are valid:

FIRS/T : first element
LAST : last element
NEXT : next element
PREV/IOUS : previous element

CD3TYP Type of element to be selected.
This may be a special keyword or a PDMS noun, e.g. 'ELB/OW',
'BOX', 'EQU/IPMENT'.

User Guide
Version 11.6
accepted in PDMS will be accepted by this routine (e.g. 'ELB', 'EQU'
are accepted).
The following special keywords are valid:

ELEM/ENT : Move in the current list
MEMB/ER : Move to a member owned by the current element

ID3ERR Error code.
0 Success
6 Invalid position keyword
202 No members
203 List exhausted
User Guide
Version 11.6
D3MRST Restore Last Saved Database Position
Specification
SUBROUTI NE D3MRST( ID3ERR )

I NTEGER I D3ERR
Description
This routine restores the database position saved by the previous call to
D3MSAV.
depth of 10. Attempts to restore a position when none has been saved or
when any saved positions have already been restored will result in error
code 127. This could occur, therefore, if nesting is unbalanced. When
the routine fails, the database position is unchanged.
Arguments
ID3ERR Error code.
0 Success
127 No saved database position
User Guide
Version 11.6
D3MSAV Save Current Database Position
Specification
SUBROUTI NE D3MSAV( ID3ERR )
I NTEGER I D3ERR
Description
This routine saves the current database position so that it may
subsequently be restored by calling D3MRST. This is more efficient than
using D3RNAM and D3MNAM.
depth of 10. Attempts to exceed this depth will result in the return of
error code 126 and the position will not be saved.
Arguments
ID3ERR Error code.
0 Success
126 Too many saved database levels
User Guide
Version 11.6
D3RBDU Read Bore and Distance Units
Specification
SUBROUTI NE D3RBDU( CD3BUN, CD3DUN, ID3ERR )
CHARACTER*( *) CD3BUN, CD3DUN
Description
This routine returns the bore and distance units defined for the current
MDB. It returns two character strings of maximum length 4 containing
the linear units.
Arguments
CD3BUN Bore units, 'MM', 'INCH' or 'FINC'
If the units are undefined or null, 'MM' will be returned. The
maximum length of the returned text string is 4 characters. If the
supplied character field is shorter than the returned units, the text

CD3DUN Distance units, 'MM', 'INCH' or 'FINC'
If the units are undefined or null, 'MM' will be returned. The
maximum length of the returned text string is 4 characters. If the
supplied character field is shorter than the returned units, the text

ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3RBOX Read Enclosing Box Co-ordinates
Specification
SUBROUTI NE D3RBOX( LD3TUB, RD3BOX, ID3ERR )

LOGI CAL LD3TUB
I NTEGER I D3ERR
REAL RD3BOX( 6)
Description
This routine reads the co-ordinates of the surrounding box for the
current element or its leave tube. This is valid for any database element
and is equivalent to the CLASHER command 'QUERY BOX':

QUERY BOX name/ref
QUERY BOX LEAVE of name/ref
QUERY BOX HEAD of name/ref

In the case of branches, the leave tube is interpreted as the branch head
tube. The surrounding box is returned as a six element real array
containing the x/y/z co-ordinates of opposite corners of the box. Array
RD3BOX must be declared at least six elements.
six elements of RD3BOX are returned as zero. Error 310 can only be
returned if LD3TUB, the leave tube flag, is set to true.
Arguments

LD3TUB Leave tube flag.
.TRUE. - Return box for leave tube (or branch head tube for
branch)
.FALSE. - Return box for current element

User Guide
Version 11.6
RD3BOX Surrounding box
The box is returned as a six element real array containing the x/y/z
world co-ordinates of opposite corners of the box. The six elements
have the following arrangement:
1st corner - E (element 1), N (element 2), U (element 3)
2nd corner - E (element 4), N (element 5), U (element 6)
Array RD3BOX must be declared at least six elements.

ID3ERR Error code.
0 Success
309 Element not on spatial map
310 Leave or head tube does not exist
User Guide
Version 11.6
D3RDAT Read Latest MDB Date-Stamp
Specification
SUBROUTI NE D3RDAT( ID3DAT, CD3DAT, ID3ERR )
2

CHARACTER*( *) CD3DAT
I NTEGER I D3DAT( 6) , I D3ERR
Description
This routine returns the latest date-stamp for any database in the mdb
system. For user convenience, the date/time is returned in two
arguments: an integer array and a character string.
In a PDMS run, each database of the current MDB is date-stamped with
the current operating system date/time when a user with WRITE access
leaves a design module (e.g. DESIGN) after making a change to the data
and without QUITting. This maintains a record of the date and time of
the last database change.
Error code 306 is returned if no date-stamps can be found.
Arguments
ID3DAT Latest database date-stamp as an integer array.
The date/time is represented as six integers:

ID3DAT(1): Year (As a 4-digit number)
ID3DAT(2): Month (1 = January, 12 = December)
ID3DAT(3): Day (1 to 31)
ID3DAT(4): Hour (0 to 23)
ID3DAT(5): Minute (0 to 59)

2
Prior to PDMS 11.1, the year, both in integer and character format, was
returned as two digits (e.g. 97 for 1997). At 11, the full 4-digit year is
returned and the required character length of CD3DAT has increased
from 18 to 20 (though the result will be truncated if necessary, as
explained under CD3DAT)
User Guide
Version 11.6
ID3DAT(6): Second (0 to 59)
The ID3DAT array must be dimensioned to a minimum of six. The
array will be returned as zeroes if an error condition occurs.

CD3DAT Latest database date-stamp as a character string.
The date/time format is of the form 'dd Mon yyyy hh:mm:ss', where:
dd Mon yyyy is the date (e.g. 07 Dec 1997)
hh:mm:ss is the time on that date (e.g. 09:07:56)
dd is the day as two digits, first digit 0 if less than 10
Mon is the month (Jan, Feb etc.)
yyyy is the year (e.g. 1997)
hh, mm, ss are hour, minute, second as two digits, as dd

CD3DAT should be declared at least CHARACTER*20 for the
complete date/time to be returned. The date/time will be truncated
to fit the declared length of CD3DAT, but only as follows:
1-10: returns blank string
11-16: returns dd Mon yy
17-19: returns dd Mon yy hh:mm
No error code will be returned if a blank or truncated string is
returned. A blank string will be returned if an error condition
occurs.

ID3ERR Error code.
0 Success
306 No date-stamp found
User Guide
Version 11.6
D3RIA Read an Integer Array Attribute
Specification
SUBROUTI NE D3RI A( CD3ATT, I D3NI N, ID3IA, ID3NOU, ID3ERR )
CHARACTER*( *) CD3ATT
I NTEGER I D3NI N, I D3I A( I D3NI N) , I D3NOU, I D3ERR
Description
This routine reads an integer array attribute of the current element.
The attribute may be a UDA. The maximum size of array required is
specified by ID3NIN. The array must be dimensioned at least this big.
The number of values returned is output in ID3NOU. Any excess
elements of ID3NIN over ID3NOU are returned as zero.
The routine will return a single value for a single integer attribute.
ID3NOU is returned as zero and ID3NIN elements of array ID3IA are
returned as zero.
The routine will return the error 'Attribute not found' for a dynamic
array attribute that has no values set (see Section 3.5).
The routine will return a valid (but meaningless) integer array for a text
attribute. This results from the way that text attributes are stored on
the databases. Error code 302 will not therefore be returned for a text
attribute.
Arguments
CD3ATT The name of the attribute required.
This must be a PDMS attribute name, e.g. 'LEV/EL' or a UDA
name. Input characters will be converted to upper case.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'LEV' is accepted).
A UDA name must include the leading ':' character. The number of
characters following the ':' must be greater than or equal to the
minimum abbreviation.
User Guide
Version 11.6
ID3NIN Maximum number of array elements required.
Array ID3IA must be dimensioned at least to this size. If the array
is bigger, the elements outside the range 1 to ID3NIN will not be
changed.

ID3IA The array of integer values.
If the attribute is user-defined, the units pertaining to the returned
integer array may be obtained by calling routine D3RUNI.

ID3NOU The number of values returned in ID3IA.
If ID3NOU is less than ID3NIN, elements (ID3NOU+1) to ID3NIN
will be returned as zero. ID3NOU will be returned as zero if the
routine fails. If the number of values is genuinely zero (e.g. an
unset UDA array), ID3NOU will be returned as zero and error code
308 will be returned in ID3ERR.

ID3ERR Error code.
0 Success
301 Attribute not found
302 Attribute of wrong type
308 Attribute unset
User Guide
Version 11.6
D3RINT Read an Integer Attribute
Specification
SUBROUTI NE D3RI NT( CD3ATT, ID3INT, ID3ERR )
I NTEGER I D3I NT, I D3ERR
Description
This routine reads an integer attribute of the current element. The
attribute may be a UDA. If an error occurs then an error code is
returned as specified below and the ID3INT argument is returned as
zero.
Arguments
This must be a PDMS attribute name, e.g. 'SAFC/LASS', 'ARR/IVE',
'QUAL/IFIER' or a UDA name. Input characters will be converted
to upper case.
PDMS will be accepted by this routine (e.g. 'ARR', 'SAFC' are
accepted).

ID3INT The value of the integer attribute.
integer value may be obtained by calling routine D3RUNI.

User Guide
Version 11.6
ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3RLA Read a Logical Array Attribute
Specification
SUBROUTI NE D3RLA( CD3ATT, I D3NI N, LD3LA, ID3NOU,
ID3ERR )

I NTEGER I D3NI N, I D3NOU, I D3ERR
LOGI CAL LD3LA( I D3NI N)
Description
This routine reads a logical array attribute of the current element. The
attribute may be a UDA. The maximum size of array required is
elements of ID3NIN over ID3NOU are returned as false.
The routine will return a single value for a single logical attribute.
ID3NOU is returned as zero and ID3NIN elements of LD3LA are
returned as false.
The only use of logical arrays is for UDAs.
Arguments
This must be a PDMS attribute name or a UDA name. Input
characters will be converted to upper case.
PDMS will be accepted by this routine.
User Guide
Version 11.6
Array LD3LA must be dimensioned at least to this size. If the
array is bigger, the elements outside the range 1 to ID3NIN will not
be changed.

LD3LA The array of logical values.

ID3NOU The number of values returned in LD3LA.

ID3ERR Error code.
0 Success
308 Attribute unset
User Guide
Version 11.6
D3RLOG Read a Logical Attribute
Specification
SUBROUTI NE D3RLOG( CD3ATT, LD3LOG, ID3ERR )
I NTEGER I D3ERR
LOGI CAL LD3LOG
Description
This routine reads a logical attribute of the current element. The
attribute may be a UDA. If an error occurs then an error code is
returned as specified below and LD3LOG is returned as false.
Arguments
This must be a PDMS attribute name, e.g. 'LOCK', 'BUI/LT',
'SHO/P' or a UDA name. Input characters will be converted to
upper case.
PDMS will be accepted by this routine (e.g. 'BUI', 'SHO' are
accepted).

LD3LOG The value of the logical attribute.

ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3RNAM Read Element Name or a Name Attribute
Specification
SUBROUTI NE D3RNAM( CD3ATT, CD3NAM, ID3ERR )

CHARACTER*( *) CD3ATT, CD3NAM
I NTEGER I D3ERR
Description
This routine reads the name of the current element or the name of a
reference attribute of the current element. The reference attribute may
be a UDA. It returns a reference number if the requested name does not
exist.
A name is returned with the leading '/' character. If a reference number
is returned, it includes the '=' and '/' characters.
CD3NAM is returned as blank.
Use routine D3RREF to obtain the reference specifically even if a name
is available.
Arguments
This must be a PDMS attribute name, e.g. 'PSPE/CIFICATION',
'CAT/REFERENCE', HEA/D or a UDA name. Input characters
will be converted to upper case.
PDMS will be accepted by this routine (e.g. 'PSPE', 'CAT' are
accepted).

User Guide
Version 11.6
CD3NAM The value of the name attribute.
It is the programmer's responsibility to ensure that CD3NAM is
declared large enough. Truncated strings are not returned. Error
code 5 will indicate that the declared string is too short. If an error
occurs, CD3NAM is returned as blank.
If CD3ATT is 'NAM/E' and the element is not named, then
CD3NAM will return the reference number (if the declared string is
large enough).

ID3ERR Error code.
0 Success
5 Character output string parameter too short
User Guide
Version 11.6
D3RORL Read Orientation of the Current Element
Specification
SUBROUTI NE D3RORL( CD3CRD, RD3ORI, ID3ERR )
CHARACTER*( *) CD3CRD
I NTEGER I D3ERR
REAL RD3ORI ( 9)
Description
This routine reads the orientation of the current element relative to a
specified co-ordinate system. Valid co-ordinate systems include PDMS
names, PDMS reference numbers, PDMS nouns and the text 'OWN/ER'.
The orientation is returned as a nine element real array containing the
three unit vectors. Array RD3ORI must be declared at least nine
elements.
nine elements of RD3ORI are returned as zero.
Arguments
CD3CRD The requested co-ordinate system.
This may be the keyword 'OWN/ER' or a PDMS noun (e.g. 'ZON/E',
'WORL/D'), or a PDMS name (e.g. '/DATUM'), or a PDMS reference
number.
The input string will be tested against each type of input in turn.
An unrecognised entry for CD3CRD will result in error code 7
(Invalid co-ordinate system keyword) or error code 205 (Cannot
access this type of element).
When testing for 'OWNER' or a PDMS noun, input characters will
be converted to upper case. In the case of PDMS nouns,
abbreviations accepted in PDMS will be accepted by this routine
(e.g. 'ZON', 'WORL' are accepted).
When testing for a PDMS name, the input string will not be
converted to upper case and strings exceeding 50 characters will be
truncated.
User Guide
Version 11.6

An undefined name or reference number will result in error code
402.

RD3ORI Orientation array of three unit vectors.
The orientation is returned as a nine element real array containing
the three unit vectors. The nine elements have the following
arrangement:

X axis unit vector - E (element 1), N (element 2), U (element 3)
Y axis unit vector - E (element 4), N (element 5), U (element 6)
Z axis unit vector - E (element 7), N (element 8), U (element 9)

Array RD3ORI must be declared at least nine elements.

ID3ERR Error code.
0 Success
7 Invalid co-ordinate system keyword
User Guide
Version 11.6
D3RPAT Read PPOINT Attributes
Specification
SUBROUTI NE D3RPAT( CD3POI , CD3CRD, RD3POS, RD3DIR,
RD3BOR,
CD3CON, ID3ERR )

CHARACTER*( *) CD3POI , CD3CRD, CD3CON
I NTEGER I D3ERR
REAL RD3POS( 3) , RD3DI R( 3) , RD3BOR
Description
This routine reads the PPoint attributes (position, direction, connection
type and bore) for a piping component or equipment primitive, relative to
a specified co-ordinate system. Valid co-ordinate systems include PDMS
For branch and piping component PPoints the co-ordinate system
'OWNER' is interpreted as 'ZONE' since 'BRAN' and 'PIPE' are not
meaningful co-ordinate systems.
The specified PPoint may be 'PH', 'PT', 'PA', 'PL', or 'P<n>'. Implied
tubing points may thus be obtained by interrogating the arrive and leave
points of the appropriate components. For equipment primitives, a zero
bore and blank connection type are returned. Position and direction are
returned as real arrays of three elements each. Direction is in the form
of a unit vector.
Arrays RD3POS and RD3DIR must be declared at least three elements
each.
If an error occurs then an error code is returned as specified below, 3
elements of RD3POS, 3 elements of RD3DIR, and RD3BOR are returned
as zero, and CD3CON is returned blank.
Arguments
CD3POI The required PPOINT.
i.e. 'PH/EAD', 'PT/AIL', 'PA/RRIVE', 'PL/EAVE', or 'P<n>', where n
is an integer ('P1', 'P2', etc.).
The input string will be converted to upper case.
User Guide
Version 11.6
number.
For branch and piping component PPoints the co-ordinate system
'OWNER' is interpreted as 'ZONE' since 'BRANCH' and 'PIPE' are
not meaningful co-ordinate systems.
truncated.
402.

RD3POS The PPoint position.
The position is returned as a three element real array containing
the three vectors in E, N, U order. Array RD3POS must be
declared at least three elements.

RD3DIR The PPoint direction.
The direction is returned as a three element real array containing
the unit vector in E, N, U order. Array RD3DIR must be declared
at least three elements.

RD3BOR The PPoint bore.

CD3CON The PPoint connection type
It is the programmer's responsibility to ensure that CD3CON is
declared large enough (usually CHARACTER*4). Truncated strings
User Guide
Version 11.6
are not returned. Error code 5 will indicate that the declared string
is too short. If an error occurs, CD3CON is returned as blank.

ID3ERR Error code.
0 Success
8 Invalid PPoint keyword
303 Element does not have PPoints
304 Illegal PPoint number
User Guide
Version 11.6
D3RPRJ Read a Project Data Item
Specification
SUBROUTI NE D3RPRJ ( CD3NAM, CD3TEX, ID3ERR )
CHARACTER*( *) CD3NAM, CD3TEX
I NTEGER I D3ERR
Description
This routine retrieves project code, name, number, description or
message from the System Database as a character string. The routine is
equivalent to PDMS ADMIN/MONITOR command 'Q/UERY PROJ/ECT
<keyword>'.
the CD3TEX argument is returned blank.
This routine may be called before D3MMDB has been called.
Arguments
CD3NAM The data item keyword.
The following keywords are valid:
COD/E : project code
NUM/BER : project number
NAM/E : project name
DES/CRIPTION : project description
MES/SAGE : project message
The nomenclature of 'code' and 'name' may appear confusing.
Project 'code' is the 3-character code normally known as 'project
name' (see CD3PRJ in routine D3INIT). Project 'name' is a
descriptive text (up to 119 characters), specified in the PDMS
ADMIN module.

CD3TEX The returned text.
3 characters will be returned for project code, up to 16 characters
for project number and up to 119 characters for the other three
items. If the data item is unset, a blank string will be returned, but
no error condition will arise.
User Guide
Version 11.6
It is the programmer's responsibility to ensure that CD3TEX is
declared large enough. Truncated strings are not returned. Error
code 5 will indicate that the declared string is too short. If an error
occurs, CD3TEX is returned as blank.

ID3ERR Error code.
0 Success
11 Invalid project data keyword
User Guide
Version 11.6
D3RPRL Read Position of the Current Element
Specification
SUBROUTI NE D3RPRL( CD3CRD, RD3POS, ID3ERR )
CHARACTER*( *) CD3CRD
I NTEGER I D3ERR
REAL RD3POS( 3)
Description
This routine reads the position of the current element relative to a
specified co-ordinate system. Valid co-ordinate systems include PDMS
The position is returned as a three element real array. Array RD3POS
must be declared at least three elements.
three elements of RD3POS are returned as zero.
Arguments
number.
truncated.
402.
User Guide
Version 11.6
RD3POS The position.
The position is returned as a three element real array containing
the three vectors in E, N, U order. Array RD3POS must be
declared at least three elements.

ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3RPTX Read REPORTER Text for a UDA
Specification
SUBROUTI NE D3RPTX( CD3ATT, CD3RPT, ID3ERR )

CHARACTER*( *) CD3ATT, CD3RPT
I NTEGER I D3ERR
Description
This routine reads the REPORTER text for a given UDA. REPORTER
text may be up to 20 characters long and is used in column headers by
the PDMS module REPORTER.
If no REPORTER text has been defined, the routine will return the UDA
name.
Arguments
CD3ATT The name of the attribute required for which REPORTER
text is required.
The attribute string will be checked for a leading colon. If one does
not exist the routine will insert one. Valid abbreviations will be
accepted. For example, valid attribute strings for a UDA called
:CONTROLLER would include:
:CONTROLLER
:CONT
CONT
assuming a minimum abbreviation of 4 or less.

CD3RPT The REPORTER text string.
If the supplied string is not sufficient to hold the complete
REPORTER text the output will be truncated.
If no REPORTER text string is found, the UDA name will be
returned, including leading ':'.
User Guide
Version 11.6
ID3ERR Error code.
0 Success
307 UDA not found
D3RRA Read a Real Array Attribute
Specification
SUBROUTI NE D3RRA( CD3ATT, I D3NI N, RD3RA, ID3NOU,
ID3ERR )

REAL RD3RA( I D3NI N)
Description
This routine reads a real array attribute of the current element. The
attribute may be a UDA. The maximum size of array required is
elements of ID3NIN over ID3NOU are returned as zero.
The routine will return a single value for a single real attribute.
ID3NOU is returned as zero and ID3NIN elements of array RD3RA are
returned as zero.
User Guide
Version 11.6
Arguments
This must be a PDMS attribute name, e.g. 'POS/ITION',
'PARA/METERS', 'HDI/RECTION' or a UDA name. Input
characters will be converted to upper case.
PDMS will be accepted by this routine (e.g. 'HDI', 'POS' are
accepted).

Array RD3RA must be dimensioned at least to this size. If the
be changed.

RD3RA The array of real values.
real array may be obtained by calling routine D3RUNI.

ID3NOU The number of values returned in RD3RA.

User Guide
Version 11.6
ID3ERR Error code.
0 Success
308 Attribute unset
User Guide
Version 11.6
D3RREA Read a Real Attribute
Specification
SUBROUTI NE D3RREA( CD3ATT, RD3REA, ID3ERR )

I NTEGER I D3ERR
REAL RD3REA
Description
This routine reads a real attribute of the current element. The attribute
may be a UDA. If an error occurs then an error code is returned as
specified below and the RD3REA argument is returned as zero.
Arguments
This must be a PDMS attribute name, e.g. 'BOR/E',
'TEM/PERATURE', 'XLE/NGTH' or a UDA name. Input characters
will be converted to upper case.
PDMS will be accepted by this routine (e.g. 'TEM', 'XLE' are
accepted).

RD3REA The value of the real attribute.
real value may be obtained by calling routine D3RUNI.

User Guide
Version 11.6
ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3RREF Read Element RefNo or a Reference Attribute
Specification
SUBROUTI NE D3RREF( CD3ATT, CD3REF, ID3ERR )

CHARACTER*( *) CD3ATT, CD3REF
I NTEGER I D3ERR
Description
This routine reads the reference number of the current element or of a
reference attribute of the current element (e.g. a connection reference,
specification reference). The reference attribute may be a UDA.
CD3REF will be returned zero.
Use routine D3RNAM to obtain the name, if available, in preference to
the reference number.
Arguments
This must be a PDMS attribute name, e.g. 'CREF/ERENCE',
'HREF/ERENCE', HEAD or a UDA name. Input characters will be
converted to upper case.
PDMS will be accepted by this routine (e.g. 'CREF', 'HREF' are
accepted).

CD3REF The value of the reference number attribute.
The reference number will include the '=' and '/' characters. It is the
programmer's responsibility to ensure that CD3REF is declared
large enough. Truncated strings are not returned. Error code 5 will
indicate that the declared string is too short. If an error occurs,
CD3NAM is returned as blank.

User Guide
Version 11.6
ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3RRFA Read a Reference Number Array Attribute
Specification
SUBROUTI NE D3RRFA( CD3ATT, I D3NI N, CD3RFA, ID3NOU,
ID3ERR )

CHARACTER*( *) CD3ATT, CD3RFA( I D3NI N)
Description
This routine reads a reference number array attribute of the current
element, e.g. connection reference array. The attribute may be a UDA.
The reference numbers returned by the routine will include the '=' and '/'
characters. The maximum size of array required is specified by ID3NIN.
The array must be dimensioned at least this big. The number of values
returned is output in ID3NOU. Any excess elements of ID3NIN over
ID3NOU are returned as blank.
The routine will return a single value for a single reference attribute.
If an error occurs then an error code is returned as specified below.
Except for error code 5, ID3NOU is returned as zero and ID3NIN
elements of array CD3RFA are returned as blank.
Arguments
This must be a PDMS attribute name, e.g. 'CRF/A' or a UDA name.
Input characters will be converted to upper case.
PDMS will be accepted by this routine (e.g. 'CRF' is accepted).

User Guide
Version 11.6
Array CD3RFA must be dimensioned at least to this size. If the
be changed.

CD3RFA The array of reference numbers.
The reference numbers will include the '=' and '/' characters. It is
the programmer's responsibility to ensure that the elements of
CD3RFA are declared large enough. Truncated strings are not
returned. Error code 5 will indicate that one or more elements of
the declared string is too short. Those elements are returned as
blanks and the remainder are returned normally. Otherwise, if an
error occurs, all array elements are returned as blank.

ID3NOU The number of values returned in CD3RFA.
routine fails with an error code other than 5. If the number of
values is genuinely zero (e.g. an unset UDA array), ID3NOU will
be returned as zero and error code 308 will be returned in ID3ERR.

ID3ERR Error code.
0 Success
308 Attribute unset
User Guide
Version 11.6
D3RTEX Read a Text Attribute
Specification
SUBROUTI NE D3RTEX( CD3ATT, CD3TEX, ID3ERR )

CHARACTER*( *) CD3ATT, CD3TEX
I NTEGER I D3ERR
Description
This routine reads a system-defined text attribute of the current element
or a user-defined text or word attribute.
The routine will return the error 'Attribute unset' for a dynamic text
attribute that has no text set (see Section 3.5).
CD3TEX is returned as blank.
In some circumstances, the routine will return a valid (but meaningless)
text string for an integer array attribute. This results from the way that
text attributes are stored on the databases. Error 302 will only be
returned for an integer array attribute in circumstances where the array
does not convert into a valid text string.
Arguments
This must be a PDMS attribute name, e.g. 'STEX/T', 'DUT/Y',
'PTSP/ECIFICATION' or a UDA name. Input characters will be
converted to upper case.
PDMS will be accepted by this routine (e.g. 'STEX', 'DUT' are
accepted).
A UDA name must include the leading ':' character and may be a
word or a text UDA. The number of characters following the ':'
must be greater than or equal to the minimum abbreviation.

CD3TEX The value of the text attribute.
It is the programmer's responsibility to ensure that CD3TEX is
declared large enough. The maximum length of a text string is 120
User Guide
Version 11.6
characters. Truncated strings are not returned. Error code 5 will
indicate that the declared string is too short. Error code 308 will
indicate a null (unset) string. PDMS treats blank strings ' ' and
null strings '' differently. A null string signifies 'unset'; a blank
string signifies a deliberate setting to 'blank'. If an error occurs or
if no text is defined for the attribute, CD3TEX is returned as blank.

ID3ERR Error code.
0 Success
308 Attribute unset
User Guide
Version 11.6
D3RTYP Read a Type Attribute
Specification
SUBROUTI NE D3RTYP( CD3TYP, ID3ERR )

CHARACTER*( *) CD3TYP
I NTEGER I D3ERR
Description
This routine reads the PDMS 'type' attribute of the current element. If
an error occurs then an error code is returned as specified below and
CD3TYP is returned as blank.
This routine gives the same result as calling D3RWOR with 'TYPE' as
the attribute name.
Arguments
CD3TYP The 'type' of the current element.
It is the programmer's responsibility to ensure that CD3TYP is
declared large enough (usually CHARACTER*6
3
). Truncated
strings are not returned. Error code 5 will indicate that the
declared string is too short. If an error occurs, CD3TYP is returned
as blank.

ID3ERR Error code.
0 Success
D3RUDA Read Lists of UDA Names, Abbreviations and Types

3
Prior to PDMS 11.1, CHARACTER*4 was large enough;
CHARACTER*6 is now recommended.
User Guide
Version 11.6
Specification
SUBROUTI NE D3RUDA( CD3TYP, I D3MAX, CD3NMS, ID3ABV,
CD3ATP, ID3NUM, ID3ERR )

I NTEGER I D3MAX, I D3ABV( I D3MAX) , I D3NUM,
I D3ERR
CHARACTER*( *) CD3TYP, CD3NMS( I D3MAX) ,
CD3ATP( I D3MAX)
Description
This routine reads, for a specified element type, parallel lists of UDA
names, lengths of minimum valid abbreviations and attribute types. If
an error occurs all lists will be set to blanks, the number of attributes
returned (ID3NUM) will be set to zero, and a value indicating the type of
error will be returned in ID3ERR. If no UDAs exist for the given
element type or if the element type is invalid, the number of attributes
returned will be zero. ID3MAX specifies the number of attributes
expected to be returned in the list and must be set by the call to the
routine. If the actual number of UDAs associated with the given element
type exceeds this value the list will be truncated.
Arguments
CD3TYP The type of element for which the UDAs are to be read.
This must be a PDMS noun e.g. 'ELB/OW', 'BOX', 'EQU/IPMENT'.
accepted in PDMS will be accepted by this routine (e.g. 'ELB', 'EQU'
are accepted).

ID3MAX The maximum number of UDA definitions expected for the
specified element type.
This must be equal to the size of the arrays declared for CD3NMS,
ID3ABV and CD3ATP.

CD3NMS Array containing a list of UDA names valid for the specified
element type.
This array variable should be declared to at least CHARACTER*13.
If declared less than this, some or all of the returned array
User Guide
Version 11.6
positions may contain truncated names. No warning will be given if
truncation occurs. The names include the leading ':' character.

ID3ABV Array containing a list of the lengths of minimum valid
abbreviations.
The lengths exclude the leading ':' character.

CD3ATP Array containing a list of the UDA types. Possible UDA
types are:
REAL : Real
INT : Integer
REF : Reference
TEXT : Text
WORD : Word
LOG : Logical
This array variable should be declared to at least CHARACTER*4.
If declared less than this, the returned words will be truncated. No
warning will be given if truncation occurs. Truncation is only
significant in distinguishing between 'REF' and 'REAL', so
CHARACTER*3 would be acceptable.

ID3NUM The actual number of attributes returned.
When an element type has no UDAs defined or if the element type
is invalid, the value returned will be zero. In neither case will an
error condition arise.

ID3ERR Error code.
0 Success
D3RUNI Read Unit of Measurement for a Real or Integer UDA
User Guide
Version 11.6
Specification
SUBROUTI NE D3RUNI ( CD3ATT, CD3UNT, ID3ERR )
CHARACTER*( *) CD3ATT, CD3UNT
I NTEGER I D3ERR
Description
This routine returns a text string indicating the UNIT (of measurement)
which applies to the specified UDA. Only real or integer attributes may
have a UNIT specified. This routine will generally be used in
conjunction with the attribute retrieval routines (D3RINT, D3RIA,
D3RREA and D3RRA). Thus, for example, an attribute value of 1000.0
and units of 'mm' may be interpreted as 1000.0mm.
Arguments
CD3ATT The name of the attribute for which UNIT is to be found.
The attribute string will be checked for a leading colon. If one does
not exist the routine will insert one. Valid abbreviations will be
accepted. For example, valid attribute strings for a UDA called
:CONTROLLER would include:
:CONTROLLER
:CONT
CONT
assuming a minimum abbreviation of four or less.

CD3UNT The UNIT text string.
If the units have been defined as BORE or DISTANCE, CD3UNT
will return the default units of 'mm'. If the units have been defined
as TEXT, CD3UNT will return the actual text ('Kg', 'lb/sq in' etc.).
If no units have been defined, CD3UNT will return a blank string
with no error condition. If the UNIT text is too long to fit the
supplied string, a blank string will be returned along with error
code 5.
User Guide
Version 11.6
ID3ERR Error code.
0 Success
307 UDA not found
User Guide
Version 11.6
D3RWA Read a Word Array Attribute
Specification
SUBROUTI NE D3RWA( CD3ATT, I D3NI N, CD3WA, ID3NOU,
ID3ERR )
CHARACTER*( *) CD3ATT, CD3WA( I D3NI N)
Description
This routine reads a word array attribute of the current element (e.g.
CTYP). The maximum size of array required is specified by ID3NIN.
The array must be dimensioned at least this big. The number of values
returned is output in ID3NOU. Any excess elements of ID3NIN over
ID3NOU are returned as blank.
The routine will return a single value for a single word attribute.
If an error occurs then an error code is returned as specified below.
Except for error code 5, ID3NOU is returned as zero and ID3NIN
elements of array CD3WA are returned as blank.
In some cases, word attributes are stored within a real array (e.g. the
PARA attribute). In this situation, the word attributes can be extracted
by using successive calls to D3RRA and D3UDEH, as illustrated by the
following extract from Example 1 (section 4.2).

I NTEGER I D3NOU, I D3ERR, I
REAL PARA( 100 )
CHARACTER*6 PARWOR( 100 )
I NTRI NSI C I NT

CALL D3RRA( PARA , 100, PARA, I D3NOU, I D3ERR )
I F ( I D3ERR . NE. 0 ) THEN
DO 100 I = 1, I D3NOU
PARWOR( I ) =
I F ( PARA( I ) . GT. 531442. 0 ) THEN
User Guide
Version 11.6
CALL D3UDEH( I NT( PARA( I ) ) ,
PARWOR( I ) )
ENDI F
100 CONTI NUE
ENDI F
Alternatively, the word parameters can be extracted using D3RWA with
WPAR as the attribute name, but this will extract any non-word Real
numbers as blanks (see Example 1, section 4.2).
Arguments
This must be a PDMS attribute name, e.g. 'CTYP/E'. Input
characters will be converted to upper case. Abbreviations accepted
in PDMS will be accepted by this routine (e.g. CTYP will be
accepted).

Array CD3WA must be dimensioned at least to this size. If the
be changed.

CD3WA The array of words.
It is the programmer's responsibility to ensure that the elements of
CD3WA are declared large enough (usually CHARACTER*6
4
).
Truncated strings are not returned. Error code 5 will indicate that
one or more elements of the declared string is too short. Those
elements are returned as blanks and the remainder are returned
normally. Otherwise, if an error occurs, all array elements are
returned as blank. If any integer value does not translate into a
word, that element of CD3WA is returned as blank.

ID3NOU The number of values returned in CD3WA.

4
User Guide
Version 11.6
routine fails with an error code other than 5. If the number of
values is genuinely zero, ID3NOU will be returned as zero and
error code 308 will be returned in ID3ERR.

ID3ERR Error code.
0 Success
308 Attribute unset
User Guide
Version 11.6
D3RWOR Read a Word Attribute
Specification
SUBROUTI NE D3RWOR( CD3ATT, CD3WOR, ID3ERR)
CHARACTER*( *) CD3ATT, CD3WOR
I NTEGER I D3ERR
Description
This routine reads a PDMS 'word' attribute of the current element (e.g.
connection type). UDAs of type WORD must be accessed by using
routine D3RTEX.
CD3WOR is returned as blank.
Arguments
This must be a PDMS attribute name, e.g. 'HCO/NN', 'BUNI/TS',
'FLOW/DIRECTION'. Input characters will be converted to upper
case. Abbreviations accepted in PDMS will be accepted by this
routine (e.g. 'HCO', 'FLOW' are accepted).

CD3WOR The value of the word attribute.
It is the programmer's responsibility to ensure that CD3WOR is
declared large enough (usually CHARACTER*6
5
). Truncated
strings are not returned. Error code 5 will indicate that the
declared string is too short. If an error occurs or if the integer value
does not translate into a word, CD3WOR is returned as blank.

5
User Guide
Version 11.6
ID3ERR Error code.
0 Success
User Guide
Version 11.6
D3UCLU Clear File Unit
Specification
LOGI CAL FUNCTI ON D3UCLU( I D3UNI )
I NTEGER I D3UNI
Description
This routine accepts the return of a FORTRAN file unit number no
longer needed by the DARs application program. This routine should
only be used for returning a unit previously issued by the complementary
routine D3UGTU.
The function's result is FALSE if the unit is invalid or was not issued by
D3UGTU.
Arguments
ID3UNI FORTRAN file unit number.
Function Value
D3UCLU .TRUE. if file unit number accepted.
.FALSE. if unit invalid.
User Guide
Version 11.6
D3UCTI Character to Integer
Specification
LOGI CAL FUNCTI ON D3UCTI( CD3STR, ID3INT, CD3BEF,
CD3AFT, CD3ERR )

CHARACTER*( *) CD3STR, CD3BEF, CD3AFT, CD3ERR
I NTEGER I D3I NT
Description
This routine converts the digits in a given string to an integer value. The
character string may start with any number of spaces, optionally
followed by + or -, and is terminated by the end of the string. Trailing
blanks are ignored.
The function's result is FALSE if a valid integer is not found or if a valid
integer is found along with further characters.
If the function is FALSE, an error code is returned to identify the cause
of the failure. If the failure is due to the presence of additional
characters before and/or after an integer, these character strings are
returned as well as the integer.
It is the programmer's responsibility to declare the character arguments
large enough to hold the returned data. These character strings will be
truncated if necessary.
Arguments
CD3STR Character string to be analysed for presence of an integer.
There is no limit to the length of the string.

ID3INT Extracted integer, if found.

CD3BEF String preceding extracted integer.
Any leading blanks in CD3STR are included in this string. If the
supplied string is shorter than the found string, the string will be
truncated. No error condition will arise as a result. If the
programmer wishes to make use of this functionality, it is
recommended that this variable is declared the same size as
CD3STR.
User Guide
Version 11.6

CD3AFT String following extracted integer.
If the supplied string is shorter than the found string, the string
will be truncated. No error condition will arise as a result. If the
CD3STR.

CD3ERR Error code, if function returned .FALSE.
The following 3-character error codes may be returned:

NAN Not a number
OOR Out of range
BLA Blank string
ADD Additional data
The 'out of range' error indicates that an integer has been
identified, but that its value is outside the range of a FORTRAN
INTEGER variable. The valid range is system dependent (typically
-2147483648 to +2147483647).
If the supplied string is shorter than 3, the returned code will be
truncated. A declaration of CHARACTER*1 is acceptable whether
the programmer wishes to ignore the error or distinguish between
them. A declaration of CHARACTER*3 or more will return the full
string.
In the case of 'NAN', 'OOR' or 'BLA', no integer will be returned in
ID3INT and blank strings will be returned in CD3BEF and
CD3AFT.
In the case of 'ADD', a valid integer has been found and is returned
in ID3INT, but the string contained characters before and/or after
the valid integer. These additional characters are returned in
CD3BEF and CD3AFT.
Function Value
D3UCTI .TRUE. if integer found without additional data.
.FALSE. if no integer.
.FALSE. if integer found with additional data.
User Guide
Version 11.6
D3UCTR Character to Real Number
Specification
LOGI CAL FUNCTI ON D3UCTR( CD3STR, RD3VAL, CD3BEF,
CD3AFT, CD3ERR )

CHARACTER*( *) CD3STR, CD3BEF, CD3AFT, CD3ERR
REAL RD3VAL
Description
This routine converts the digits in a given string to a real number. The
character string may start with any number of spaces, optionally
followed by + or -, and is terminated by the end of the string. Trailing
blanks are ignored.
The function's result is FALSE if a valid real number is not found or if a
valid number is found along with further characters.
The string must be of the following form:
(spaces)(+/-)nn(.((nn))(E(+/space/-)nn)
or (spaces)(+/-).nn(E(+/space/-)nn)

e.g. ' 1. 2 ' , ' 6E3' , ' 6E 3' , ' 6. 5E- 03' , ' - . 005E7 '
If the function is FALSE, an error code is returned to identify the cause
of the failure. If the failure is due to the presence of additional
characters before and/or after a real number, these character strings are
returned as well as the real value.
It is the programmer's responsibility to declare the character arguments
large enough to hold the returned data. These character strings will be
truncated if necessary.
Arguments
CD3STR Character string to be analysed for presence of a real
number.

RD3VAL Extracted value, if found.
User Guide
Version 11.6

CD3BEF String preceding extracted real number.
Any leading blanks in CD3STR are included in this string. If the
supplied string is shorter than the found string, the string will be
truncated. No error condition will arise as a result. If the
CD3STR.

CD3AFT String following extracted real number.
If the supplied string is shorter than the found string, the string
will be truncated. No error condition will arise as a result. If the
CD3STR.

CD3ERR Error code, if function returned .FALSE.

The following 3-character error codes may be returned:
NAN Not a number
OOR Out of range
BLA Blank string
ADD Additional data
The 'out of range' error indicates that a real number has been
identified, but that its value is outside the range of a FORTRAN
single precision REAL variable. The valid range is system
dependent (typically about -1E38 to +1E38). A real number whose
value is too close to zero to be represented by a REAL variable
(typically between -1E-38 and +1E-38) will be returned as zero and
will not return the 'out of range' error.
If the supplied string is shorter than 3, the returned code will be
truncated. A declaration of CHARACTER*1 is acceptable whether
the programmer wishes to ignore the error or distinguish between
them. A declaration of CHARACTER*3 or more will return the full
string.
User Guide
Version 11.6
In the case of 'NAN', 'OOR' or 'BLA', no value will be returned in
RD3VAL and blank strings will be returned in CD3BEF and
CD3AFT.
In the case of 'ADD', a valid real number has been found and is
returned in RD3VAL, but the string contained characters before
and/or after the valid number. These additional characters are
returned in CD3BEF and CD3AFT.
Function Value
D3UCTR .TRUE. if real number found without additional data.
.FALSE. if no real number.
.FALSE. if real number found with additional data.
User Guide
Version 11.6
D3UDEH Dehash a Hashed PDMS Word
Specification
SUBROUTI NE D3UDEH( I D3I NT, CD3WOR )
6

CHARACTER*( *) CD3WOR
I NTEGER I D3I NT
Description
This routine converts a hashed PDMS word (a PDMS word represented
as an integer number) into the PDMS word.
It will normally be use to dehash a hashed word returned by a data
access routine (e.g. some elements of an integer array attribute may be
hashed words).
A hashed PDMS word is an integer number in the range 531442 (A) to
387951929 (ZZZZZZ). This routine does not check that the decoded
word is meaningful. If the decoded word is illegal, a blank word is
returned.
Arguments
ID3INT Hashed integer number.
This must be an integer number (e.g. 534552), derived from
'hashing' of a PDMS word by PDMS. In the context of PDMS DARs,
it will be an integer number returned by a data access routine (e.g.
some elements of an integer array attribute may be hashed words).

CD3WOR The word resulting from dehashing the integer number, e.g.
534552 will return 'FGD'
It is the programmer's responsibility to ensure that CD3WOR is
declared large enough (usually CHARACTER*6, or less if word has

6
Prior to PDMS 11.1, a PDMS word had a maximum length of four
characters and was represented by a real number with a valid range
between 531442 (A) and 1062881 (ZZZZ). This change in specification
is therefore not upwards-compatible.
User Guide
Version 11.6
trailing blanks). If the declared string is too short, CD3WOR is
returned as blank.
A zero or negative integer number results in the string 'NUL'.
Otherwise, if the integer number is outside the valid range or the
decoded word is illegal, CD3WOR is returned as blank.
Errors/Warnings
As noted above, the routine will return a blank string if the integer
number cannot be decoded or if the character string is too short for the
returned word.
Failure of this routine does not set the internal error flag.
User Guide
Version 11.6
D3UDTM Read Current System Date and Time
Specification
SUBROUTI NE D3UDTM( ID3DAT, CD3DAT )
7

I NTEGER I D3DAT( 6)
Description
This routine returns the current system date and time. For user
convenience, the date/time is returned in two arguments: an integer
array and a character string.
Arguments
ID3DAT Current system date / time as an integer array.
The date/time is represented as six integers:

ID3DAT(1): Year (As a 4-digit number)
ID3DAT(2): Month (1 = January, 12 = December)
ID3DAT(3): Day (1 to 31)
ID3DAT(4): Hour (0 to 23)
ID3DAT(5): Minute (0 to 59)
ID3DAT(6): Second (0 to 59)

The ID3DAT array must be dimensioned to a minimum of six. The
array will be returned as zeroes if an error condition occurs.

7
Prior to PDMS 11.1, the year, both in integer and character format, was
returned as two digits (e.g. 97 for 1997). At 11, the full 4-digit year is
returned and the required character length of CD3DAT has increased
from 18 to 20 (though the result will be truncated if necessary, as
explained under CD3DAT)
User Guide
Version 11.6
CD3DAT Current system date/time as a character string.
The date/time format is of the form 'dd Mon yyyy hh:mm:ss', where:
dd Mon yyyy is the date (e.g. 07 Dec 1997)
hh:mm:ss is the time on that date (e.g. 09:07:56)
dd is the day as two digits, first digit 0 if less than 10
Mon is the month (Jan, Feb etc.)
yyyy is the year (e.g. 1997)
hh, mm, ss are hour, minute, second as two digits, as dd
CD3DAT should be declared at least CHARACTER*20 for the
complete date/time to be returned. The date/time will be truncated
to fit the declared length of CD3DAT, but only as follows:
1-10: returns blank string
11-16: returns dd Mon yy
17-19: returns dd Mon yy hh:mm
Errors/Warnings
No errors or warnings can result from the use of this routine. If the
array ID3DAT is not dimensioned to at least six, a program crash is
possible.
User Guide
Version 11.6
D3UGTU Get File Unit
Specification
LOGI CAL FUNCTI ON D3UGTU( ID3UNI )
I NTEGER I D3UNI
Description
This routine supplies a valid available FORTRAN file unit number for
use by the DARs application program. This provides a mechanism for
avoiding units that are already in use by the DARS package, provided
that the application calls this routine for ALL the file units it needs.
This routine must be called immediately before the associated file
opening statement.
i.e. I F ( D3UGTU( I UNI T) ) THEN
OPEN( I UNI T . . .
NOT DO 100 I =1, 20
OK = D3UGTU( I UNI T( I ) )
100 CONTI NUE

OPEN ( I UNI T( 1) . . . .
The function's result is FALSE if no further units are available. The
application should use the complementary routine D3UCLU to return
units no longer needed and to allow them to be re-allocated by this
routine.
Arguments
ID3UNI FORTRAN file unit number.
Function Value
D3UGTU .TRUE. if file unit number returned.
.FALSE. if no unit available.
User Guide
Version 11.6
D3UINI Query Initialisation
Specification
SUBROUTI NE D3UI NI ( LD3INI )
Description
This routine returns a true or false flag, depending on whether or not a
PDMS project is currently initialised.
It will return TRUE if D3INIT have been successfully called and D3FIN
has not been subsequently called.
The routine can be called at any time; it does not set or unset the
internal error flag, neither does it test whether the flag is currently set.
This routine does not provide any further information if DARs
monitoring is ON.
Arguments
LD3INI .TRUE. if a project is currently initialised
.FALSE. if a project is not currently initialised
User Guide
Version 11.6
D3ULDS Test Latest MDB Date-Stamp
Specification
LOGI CAL FUNCTI ON D3ULDS( CD3DAT, ID3ERR )
8

I NTEGER I D3ERR
Description
This routine checks whether any database in the current MDB has been
date-stamped later than a specified date/time. It returns a TRUE
function value if any database has a later date-stamp.
Refer to routine D3RDAT for an explanation of the date-stamp feature.
Arguments
CD3DAT Specified date/time to check date-stamp against.
The date/time format is of the form 'dd Mon yyyy hh:mm:ss', as
described for the CD3DAT argument of routine D3RDAT.
Alternative formats are accepted as follows:
The month can be upper, lower or mixed case and can be any
abbreviation of the month, minimum length 3 (e.g. JAN/UARY)
Any delimiter or space can be used between the fields. Within the
date, the delimiter/space can be omitted.
(e.g. '13/SEP/1997 12 13 14' or '13SEP2001,12.13:14').
Integers less than 10 may be entered as a single digit (e.g. '9 Sep
1997 9.08.8').
If the time is omitted, it defaults to 23:59:59. Otherwise mm and ss
default to zero.
'13sept1997 12' is '13 Sep 1997 12:00:00'
'13sept1997 12:15' is '13 Sep 1997 12:15:00'
'13sept1997' is '13 Sep 1997 23:59:59'

8
Prior to PDMS 11.1, the year could be input as two or four digits (e.g.
97 or 1997). At 11, only a 4-digit year is allowable.
User Guide
Version 11.6

ID3ERR Error code.
0 Success
12 Invalid date/time
13 Entered date/time later than current
Function Value
D3ULDS .TRUE. if any db date-stamp later than CD3DAT
.FALSE. if no db date-stamp later than CD3DAT, or error. In
circumstances where error code 306 would be returned by D3RDAT,
this routine returns FALSE and does not return an error.
User Guide
Version 11.6
D3ULEN Length of Character String
Specification
I NTEGER FUNCTI ON D3ULEN( CD3STR )

CHARACTER*( *) CD3STR
Description
This routine returns the significant length of a character string. That is,
the length after stripping off all trailing blanks. Some compilers provide
an intrinsic function for this purpose. This routine may be used whether
or not an intrinsic function is available.
The function returns zero for a blank string. It returns the declared
length for an undefined string.
Intrinsic function LEN should be used to obtain the declared length of a
string.
Arguments
CD3STR String for which significant length is required.
Function Value
D3ULEN Significant length of string.
Zero for blank string ' '. Equivalent to LEN(CD3STR) for
undefined string.
User Guide
Version 11.6
D3UMON Change Monitor Level
Specification
SUBROUTI NE D3UMON( CD3MON )
CHARACTER*( *) CD3MON
Description
This routine sets or resets the monitoring level. It re-defines the level
set in the last call to the routine or set in D3INIT.
Three levels of monitoring are available: FULL, SOME and NONE.
'SOME' monitoring will cause the names of databases opened by
D3MMDB to be output. 'FULL' monitoring will in addition cause the
details of all the data access routines which are called, and their input
and output arguments to be output to the default output device, together
with all warning/error conditions encountered.
Arguments
CD3MON Required monitor level (up to 4 characters).
four characters will be truncated. Any string other than 'SOME' or
'FULL' (after truncation) will be interpreted as 'NONE'.
NONE - no monitoring. If required, D3EMSG can be called
selectively to output messages.
SOME - display names and types of databases opened by
D3MMDB.
FULL - as SOME plus display routine name and values of input
and output arguments for all routines called and display all non-
zero error messages.
Errors/Warnings
No errors or warnings can result from the use of this routine.
User Guide
Version 11.6

6 Version Control
6.1 DARs Version Numbering
PDMS Data Access Routines have a version number corresponding to the
version of PDMS whose FORTRAN routines they include. For example,
PDMS DARs Mk11.6.0 would be the first release of Mk11.6, based upon
library routines from PDMS Mk11.6.0. In line with PDMS version
control, any minor release of PDMS DARs Mk11.6 would be compatible
with any minor release of PDMS Mk11.6 (e.g. PDMS DARs Mk11.6..0.12
would be compatible with PDMS Mk11.6.0.3 and with PDMS
Mk11.6.0.7).
Compatibility may exist across major releases, depending on the nature
of the changes introduced with such a release. This will be confirmed
with each new release. As an example, PDMS DARs Mk11.4 was
compatible with PDMS Mk11.3.
Compatibility will definitely not exist across DDL changes. For example,
PDMS DARs Mk11.6 is not compatible with any release of PDMS Mk10.
6.2 Compatibility of Databases and DARs
PDMS DARs use the same database access routines as PDMS. For
example, PDMS DARs version 11.6.0 uses the same version of program
code to access MDBs as is used by PDMS version 11.6.0. PDMS DARs
are therefore able to detect, in the same way as PDMS, when the
databases are incompatible with the version of the program.
Upon entry to D3INIT or D3MMDB, the DARs initialisation and MDB
selection routines, the program will test for database compatibility and
act in the same way as PDMS if an error is encountered. It will therefore
not be possible for users to inadvertently use an incompatible version of
DARs (e.g. Mk11.6 DARs with Mk10.5 PDMS)
Each new major release of PDMS (Mk11.3.0, Mk11.4.0, Mk11.6.0 etc.)
will include a compatible version of PDMS DARs.
User Guide
Version 11.6
Version Control
6.3 Determination of Version Number
At each entry to D3INIT, whether successful or unsuccessful, the DARs
program will output the DARs version details to the terminal, for
example:
VANTAGE PDMS DARs C Interface Mk11.6.0.0 (WINDOWS-NT 5.0) (7
Sep 2004 : 23:36)
The only exception is that the banner is not output in the event of a
sitefile or security error (as is the case with PDMS).
The date in this banner is the creation date of the DARs library.
User Guide
Version 11.6

A DARs Library Details

At DARs 11.6, the released DARs library contains both the Fortran and
C/C++ callable routine, plus the routines in d3extras.f.
The executable programs have the extension .exe and the shell scripts
c*load are replaced by DOS batch files with the extension .bat.
The DARs library itself is dynamic link library (.dll), and a separate
library (.lib) is provided for use when linking DARs applications.
A.1 Software Issued with DARs
The following files are provided with a PDMS DARs release:
A directory dars containing the following directories and files:
dar000 - a test project directory for acceptance test
dar100 - a test project directory for acceptance test
d3test.f - FORTRAN source file
d3extras.f - FORTRAN source file
d3lib.dll - DARs Fortran/C/C++ runtime library
d3lib.lib - DARs Fortran/C/C++ link library
d3test - executable file
d3test.log.base - log file of acceptance test run
f77_example1.f - FORTRAN source for Example 1, see Section 4.2
f77_example2.f - FORTRAN source for Example 2, see Section 4.3
f77_example3.f FORTRAN source for Example 3
compload.bat - dos script to compile and link any source program
c_example.c - C source for example program (see Appendix F, )
cxx_example.cxx C++ source for example program
ccompload.bat - dos script to compile and link any C source program
cxxcompload.bat - dos script to compile and link and C++ source
program
VANTAGE Plant Design Data Access Routines A-1
User Guide
Version 11.6
DARs Library Details
d3libc.h - C header file to include in any C/C++ source program
pdms.h - C header file included in d3libc.h
The directory dars will normally be a subdirectory of the PDMS release
directory %PDMSEXE% (e.g. pdms11.2/dars).
The DARs 11.2 library is released as a dynamic link library (.dll). This
allows us to use C++ code inside PDMS, but still allows DARs
applications to be linked with the Fortran compiler, and reduces the size
of the executables produced. Like other dlls, d3lib.dll will need to be
available at runtime, and this is controlled by the environment variable
PATH.
The dos scripts can be used by the DARs programmer to compile, link
and run his own programs.
The source file d3extras.f is a library of subroutines that the DARs
programmer may find useful in his own programs. They are included in
the DARS library for programmers to use, or programmers may copy and
modify them to suit their purposes. These routines are briefly described
in Appendix 0.
This Appendix covers machine-specific information in respect of
FORTRAN libraries and utilities. Appendix F deals with the C/C++
library interface and utilities.
A.2 File Handling
The PDMS DARs routines use CreateFile to allocate file units
dynamically. The number of file units required by PDMS DARs depends
on the number of databases in the MDBs used by the DARs application
program.
A DARs application program can use two techniques, fixed and variable,
to allocate FORTRAN file units for its own use.
Using the fixed method, DARs programmers may use any logical unit
(positive integers) valid in FORTRAN.
Using the variable method, programmers request free units, as required,
by calls to D3UGTU. The variable method also provides a routine
D3UCLU which returns units when no longer required. D3UGTU
simply allocates a FORTRAN unit in the valid range. The working of
this interface depends upon the programmer following the call to
D3UGTU immediately with a file opening statement.

A-2 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
Fixed or variable methods may be used together.
If the DARs application program allocates so many units that the DARs
package runs out of file units for its own purposes, the DARs routine
affected will return an appropriate error condition.
If D3UGTU is used, files may be accessed by FORTRAN 77 input/output
statements such as OPEN, READ, CLOSE, using fixed or allocated
FORTRAN units.

LOGI CAL D3UGTU, D3UCLU, OK
I NTEGER FUNI T
I F ( . NOT. D3UGTU( FUNI T ) ) GOTO 999
OPEN( FUNI T, . . . . )
READ( FUNI T, . . . . )
CLOSE( FUNI T )
OK = D3UCLU( FUNI T )
or
EXTERNAL EX1
CALL D3I BEG( EX1, ' ' )
. .
SUBROUTI NE EX1
. .
OPEN( 5, . . . . )
A.3 Application Program Compilation and Linking
The DARs library is provided to allow programmers to interface PDMS
DARs to programs compiled using the appropriate compiler.
Compilation and linking can be achieved by the use of compload.bat.
PDMS at 11.6 uses the standard MicroSoft C/C++ compiler, cl, and the
Digital Fortran compiler, df. Fortran code will need to be compiled with
the following options to ensure Fortran/C/C++ compatibility:
/iface:cref /libs:dll /threads /recursive
This can be specified on the command line to DF, or by setting an
environment variable DF to this string.

User Guide
Version 11.6
A.4 Program Running and Debugging
You will need to have the following system dlls available:
icmp.dll, advapi32.dll, netapi32.dll, comctl32.dll, comdlg32.dll,
mfc42.dll, msvcrt.dll, kernel32.dll, user32.dll
d3lib.dll also needs dformd.dll (the Fortran runtime library) and
msvcp50.dll, which you may not have, and are therefore included in
%PDMSEXE% and with this DARs release.
If, when you start up your DARs application, you get a Windows popup
such as:
Unable to locate DLL
The dynamic link library d3lib.dll could not be found in the specified
path.
you need to ensure that PATH is set to include the location of d3lib.dll,
which is normally %PDMSEXE%\dars.
If an application program enters D3INIT successfully, program
debugging can be assisted by use of the FULL monitoring level. This can
be switched on in D3INIT or by a later call to D3UMON.
A.5 Acceptance Test Program
An acceptance test program is supplied in the form of an executable, as
listed in Section of this Appendix. The first level of test is to run the
executable.
The second level of test is to compile the source of the acceptance test
program d3test.f and build a new executable using the scripts supplied.
Running this executable completes the acceptance test.

1. Set the appropriate DAR project environment variables:
e.g. set DAR000=%PDMSEXE%\ dar s\ dar 000
set DAR100=%PDMSEXE%\ dar s\ dar 100
2. Set the DARs library environment variable:
e.g. set DARSLI BDI R=%PDMSEXE%\ dar s
A-4 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
3. Create a work directory and copy f77_example1.f, d3test.f, d3test and
d3test.log.base into the work directory from the DARs release directory
%DARSLIBDIR%.
4. Change directory to the work directory and enter
%DARSLI BDI R%\ d3t est > d3t est . l og at the terminal.
Compare d3test.log and d3test.log.base; any significant differences?
5. Enter %DARSLI BDI R%\ compl oad d3t est
6. Enter d3t est >d3t est . l og
Compare d3test.log and d3test.log.base; any significant differences?
7. Enter %DARSLI BDI R%\ compl oad f 77_exampl e1
8. Enter f 77_exampl e1
Does the output appear to be the same the output in section 4.2 (allowing
for minor differences of precision)?
A.6 Re-Linking Application Programs
When a new version of PDMS DARs has been released, advise all DARs
programmers and users that existing DARs executables should be
relinked to the new DARs library.

User Guide
Version 11.6

B Running Examples
The basic principles for compiling, linking and running DARs
applications programs have been outlined in Appendix A.
The example programs illustrated in Section 4 are best implemented
using scripts similar to compload, which compiles and loads any DARs
Fortran application program. The name of the FORTRAN source file is
entered as a command line argument (e.g. compload f77_example1.f).
The released script will compile and link a PDMS DARs application.
@echo of f

RemNT . bat f i l e t o compi l e and l i nk a PDMS DARs
appl i cat i on pr ogr am.
RemAr gument [ 1] i s t he f i l e t o be compi l ed.

i f not " %1" ==" " got o GOTFI LE
echo compl oad - no f i l ename speci f i ed.
got o FI NI SH

: GOTFI LE

RemCompi l e and l i nk
DF %1 %PDMSEXE%\ dar s\ d3l i b. l i b

: FI NI SH
VANTAGE Plant Design Data Access Routines B-1
User Guide
Version 11.6

C Error Codes and Messages
Errors are mostly handled by the return of an error code by each DARs
routine. Details are included in Sections 2.5, 3.6 and 5.3 of this manual.
The following error codes exist. The returned value can only be positive
or zero. A positive value denotes an error condition; zero denotes no
error.
The listed text messages are returned by D3EMSG; the maximum text
length is 50 characters.
The codes are grouped according to the type of error, as follows:

0 - 99: General
101 - 199: Initialisation
201 - 299: Navigation
301 - 399: Retrieval
401 - 499: Database

The error codes and their corresponding interpretations are as follows:
0 Success
No errors have occurred
1 Unknown error
An undocumented error has occurred. Please record the two
numbers that accompany this message and contact your PDMS
support engineer.

An error has occurred during a previous call to a data access
routine. No further actions can be can be carried out by data
access routines until the internal error code is reset with a call
to routine D3ERST.

VANTAGE Plant Design Data Access Routines C-1
User Guide
Version 11.6
Error Codes and Messages
A successful call to routine D3INIT must precede all use of
data access navigation and attribute retrieval routines in each
project.

A successful call to routine D3MMDB must precede all use of
data access navigation and attribute retrieval routines in each
project.

5 Character string output argument too short
The character string supplied by the programmer to take an
output argument is too short. A truncated string will not be
returned.

6 Invalid position keyword
A position keyword other than 'FIRS', 'LAST', 'NEXT' or
'PREV' has been supplied.

7 Invalid coordinate system keyword
A coordinate system not recognisable as a PDMS name,
reference number, noun or the keyword 'OWNE' has been
supplied.

8 Invalid PPoint keyword
The character string entered for PPoint is not a valid option.
Valid keywords are 'PH/EAD', 'PT/AIL', 'PA/RRIVE',
'PL/EAVE' and 'Pval', where val is an integer.

A name has been supplied without a leading / character, or a
reference number without = and / characters.
C-2 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
10 Argument has illegal value

The value of the argument is invalid. For example, a negative
value may have been entered where a positive value is
required.

11 Invalid project data keyword
The character string entered for project data item is not a valid
option. Valid keywords are: NUM/BER, NAM/E,
DES/CRIPTION, MES/SAGE, COD/E.

12 Invalid date/time
The character string entered for date/time is not a valid text
string.

13 Entered date/time later than current
The date/time argument is later than the current date/time
and is therefore invalid.

101 Error opening Dabacon workfile
This should not normally occur. It can occur if the user does
not have access to the PDMS work area or if he attempts to
run a DARs program within PDMS using the SYSCOM
command (both programs try to open the same workfile).

102 Bad password
The specified password is not valid for the specified username
in the specified project.

103 Unknown username
The specified username is not defined in the specified project.

User Guide
Version 11.6
104 Too many users in project
The number of users in the project has exceeded the maximum
allowed.

105 Project currently locked
The specified project is locked and access is denied.

106 Project is incompatible version
An attempt has been made to open a database belonging to an
incompatible version of PDMS. The current versions of the
project and of PDMS DARs are incompatible.

107 Too many failed initialisations
The application program has called D3INIT three times (or
more) in succession, each failing to initialise DARs.

108 Project not found
The directory corresponding to the specified project could not
be found, or if found does not contain a PDMS project.

109 Error opening runfile data file
This should not occur. Ensure the user has access to the
PDMS project.

110 MDB not found
The specified MDB is not defined in the specified project.

111 No databases to open
There are no current databases in the specified MDB.
Alternatively, there are no databases of the various types
required for the specified default database. For example, if the
default database is type DESI and there are no DESI, CATA or
PROP databases in the MDB.

User Guide
Version 11.6
112 Corrupt databases
Database corruption has been detected.

113 Databases in use
Databases on the specified MDB are held busy by another
user. This can occur even though DARs access is read-only,
because PDMS will allow only one user for any database in an
MDB.

114 Error opening database file
This error can occur if a required database file does not exist or
if it cannot be accessed for any reason.

115 Sitefile/Security error
Error returned by sitefile check. The nature of the error will
be output to the terminal in the same way as occurs for PDMS.
Unlike PDMS, the program will not stop, but will simply
return this error.

116 Invalid project name
The entered project name (after truncation to three characters)
is not a valid name. A valid name consists of three alphabetic
characters.

117 Invalid default database type
Invalid keyword string entered for default database type. It
must be one of the valid options or a valid abbreviation.

118 No databases of default type in MDB
The specified MDB does not contain a database of the default
type.

User Guide
Version 11.6
119 System database error
The program cannot open the system database. The nature of
the error will be output to the terminal in the same way as
occurs for PDMS (e.g. PNS Privileges not sufficient). Unlike
PDMS, the program will not stop, but will simply return this
error.

Named database not present in current project.

Named database not present in current MDB.

122 Database already current
Database cannot be made current because it already is
current. Or, databases cannot be exchanged because both are
current.

123 Database not current
Database cannot be deferred because it already is deferred.
Or, databases cannot be exchanged because both are deferred.

124 Too many current databases
Database cannot be made current because the maximum
number of databases is already current.

Specified database position is less than 1 or is greater than
maximum number of databases

126 Too many saved database levels
Nesting of D3MSAV and D3MRST exceeds a depth of 10.
User Guide
Version 11.6
127 No saved database position

D3MRST has been called with no previous matching call to
D3MSAV. This may be the result of unbalanced nesting of
D3MSAV and D3MRST, due to a program logic error.
An attempt has been made to go to a member of the current
element but it cannot own elements.

202 No members
An attempt has been made to go to a member of the current
element but it has no members (though it can own them).

203 List exhausted
An attempt has been made to go beyond the end of the current
list of elements.

204 Current element has no owner
An attempt has been made to go to the owner of the current
element when it has no owner. This only applies to the world.

A PDMS noun of unrecognised type has been supplied, either
as element type or coordinate system.
The current element does not have the requested attribute.

The requested attribute is of a different data type to that
retrieved by the this routine.

303 Element does not have PPoints
The current element does not have PPoints.

User Guide
Version 11.6
304 Illegal PPoint number
The current element does not have a PPoint with this number.

305 Wrong element type
Attempt to read an attribute specific to a particular element
type, when the current element is of an inappropriate type.
Not applicable at present.

306 No date-stamp found
Databases in MDB do not have a date-stamp. MDB not used
since project created or reconfigured.

307 UDA not found
The current element does not have the requested user-defined
attribute.

308 Attribute unset
If text, the requested attribute is unset (i.e. null '', as distinct
from blank ' '). If an array, all array elements are unset.

309 Element not on spatial map
The database spatial map is not up-to-date. Use the MAP
command in DESIGN to rebuild the spatial map.

310 Leave or head tube does not exist
The surrounding box for an element's leave tube, or branch
head tube, has been requested and there is no such leave or
head tube.
401 Dabacon error
A Dabacon system error has occurred. Please record the two
numbers that accompany this message and contact your PDMS
support engineer.
User Guide
Version 11.6
A name or reference number has been supplied which is not
defined in a database which is currently open, either to move
to it, or as a coordinate system.

403 Reference to database not open
The element referenced is not in a database that is current on
the selected MDB.

404 File write error
PDMS work area and to the PDMS project.

405 File read error
PDMS work area and to the PDMS project.
User Guide
Version 11.6

D Auxiliary Subroutine Library
D.1 Introduction
Accompanying a release of PDMS DARs is a library of auxiliary
subroutines in source code that the DARs programmer may find useful in
a number of ways:
1. For calling from an application program
2. For examples of the use of data access routines
3. For forming a basis for the programmer's own routines
Aveva may add to this library or make changes to source code from time
to time. However, no undertaking is given that the auxiliary subroutines
will be supported.
The conventions adopted in Subroutine Specifications (Section 5) have
been adopted in this appendix where appropriate.
All routines have a ID3DIS argument which can have the following
values:
0: Display no return arguments
1: Display return arguments (except ID3ERR)
2: as 1 plus display subroutine entry and exit messages
They also have a ID3ERR return argument. If an error condition arises,
ID3ERR will return the appropriate error code (see Appendix 0).
D.2 List of Subroutines
All Databases:
D3QMEM Query Members for Current Element
D3QCMA Query Attributes Common to all Element Types (TYPE,
NAME, OWNEr, LOCK)
D3QUDV Query UDAs and UDA Values for Current Element

VANTAGE Plant Design Data Access Routines D-1
User Guide
Version 11.6
Auxiliary Subroutine Library
Design Database:
D3QSIT Query Attributes for a SITE
D3QZON Query Attributes for a ZONE
D3QPIP Query Attributes for a PIPE
D3QBRA Query Attributes for a BRANCH
D3QBPA Query Attributes Common to PIPE/BRANCH (called by
D3QPIP and D3QBRA)
D3QTEE Query Attributes for a TEE
D3QELB Query Attributes for an ELBOW
D3QCPA Query Attributes Common to Piping Components (called by
D3QTEE and D3QELB)
D3QEQU Query Attributes for an EQUIPMENT
D3QNOZ Query Attributes for a NOZZLE
D3QBOX Query Attributes for a BOX

Catalog Database
D3QCAT Query Attributes for a CATALOG
D3QSEC Query Attributes for a SECTION
D3QCOM Query Attributes for a SCOMP
D3QUNI Query Attributes for a UNIT
D3QUSE Query Attributes for a USEC
D3QUDE Query Attributes for a UDEF
D3QMSE Query Attributes for a MSET
D3QMTY Query Attributes for a MTYP
D3QATL Query Attributes for a ATLI
D3QSPW Query Attributes for a SPWL
D3QSPE Query Attributes for a SPEC
D3QSEL Query Attributes for a SELE
D3QSPC Query Attributes for a SPCO
D3QCCT Query Attributes for a CCTA
D3QCOC Query Attributes for a COCO

D-2 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
Properties Database
D3QTUB Query Attributes for a TUBD
D3QCMP Query Attributes for a CMPD
D3QCDA Query Attributes Common to TUBD and CMPD (called by
D3QTUB and D3QCMP)
D3QCON Query Attributes for a CONS

Dictionary Database
D3QUDA Query Attributes for a UDA

Additional Routine
D3XLEN Integer Function returning Significant Length of a String or
1 for a Blank String (variant of D3ULEN)
D.3 Subroutine Outline Specifications
Outline specifications are presented for the auxiliary routines in the
order listed above.
User Guide
Version 11.6
SUBROUTINE D3QMEM( I D3DI S, I D3NI N, CD3TYP, CD3NAM,
ID3NOU, ID3ERR )
I NTEGER I D3DI S, I D3NI N, I D3NOU, I D3ERR
CHARACTER*( *) CD3TYP( I D3NI N) , CD3NAM( I D3NI N)

Performs the equivalent of a Q MEMBERS for the current element.
Element types and names/references are returned in the output arrays,
up to ID3NIN members.
Calls D3RNAM, D3RTYP, D3MREL, D3ERST, D3XLEN, D3MNAM

ID3DIS Display flag
ID3NIN Max number of array elements required
CD3TYP Array of element types (allow four
characters per element)
CD3NAM Array of element names (allow 50
characters per element)
ID3NOU Number of elements returned for each
of above two arrays
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QCMA( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )

I NTEGER I D3DI S, I D3ERR
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for the current element for the four
common attributes type, name, owner and lock.
Calls D3RTYP, D3RNAM, D3RLOG, D3XLEN, D3EMSG, D3ERST
Called by most other auxiliary routines.

ID3DIS Display flag
TYPE Type NAME Name
OWNE Owner name/ref LOCK Lock flag
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QUDV( I D3DI S, ID3ERR )
Performs the equivalent of a Q ATT for all UDAs for the current element.
Lists the UDAs, their properties and values.
Calls D3RIA, D3RRA, D3RLA, D3RRFA, D3RTEX, D3XLEN, D3EMSG,
D3RUDA, D3RUNI, D3RPTX, D3RNAM, D3RTYP, D3ERST
ID3DIS Display flag ID3ERR Error
code
The following are displayed but not returned:
For the element type:
UDA names & minimum abbreviations
UDA type
Reporter text
For the element, for each UDA:
UDA value and units (if any)
A value of 0 for ID3DIS does not suppress the output.
User Guide
Version 11.6
SUBROUTINE D3QSIT( I D3DI S, TYPE, NAME, OWNE, LOCK,
POS, ORI, ID3ERR )

LOGI CAL LOCK
REAL POS( 3) , ORI ( 3)

Performs the equivalent of a Q ATT for a SITE.
Calls D3RNAM, D3XLEN, D3QCMA, D3RRA, D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
POS Position ORI Orientation
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QZON( I D3DI S, TYPE, NAME, OWNE, LOCK,
POS, ORI, PSPE, ISPE, TSPE, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, PSPE, I SPE, TSPE
Performs the equivalent of a Q ATT for a ZONE.
Calls D3RNAM, D3XLEN, D3QCMA, D3RRA, D3EMSG, D3ERST

ID3DIS Display flag
TYPE Type NAME Name
PSPE Pipe spec ISPE Insulation spec
TSPE Tracing spec ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QPIP( I D3DI S, TYPE, NAME, OWNE, LOCK,
BUIL, SHOP, BORE, TEMP, PRES, PSPE, ISPE, TSPE,
MATR, FLUR, CASR, CCEN, CCLA, DUTY, LNTP, EREC,
REV, DSCO, PTSP, INSC, SAFC, ID3ERR )

I NTEGER I D3DI S, CCEN, CCLA, EREC, REV, SAFC,
I D3ERR
LOGI CAL LOCK, BUI L, SHOP
CHARACTER*( *) TYPE, NAME, OWNE, PSPE, I SPE, TSPE, MATR
CHARACTER*( *) FLUR, CASR, DUTY, LNTP, DSCO, PTSP, I NSC
REAL BORE, TEMP, PRES

Performs the equivalent of a Q ATT for a pipe.
Calls D3RNAM, D3XLEN, D3QBPA, D3RREA, D3RINT, D3EMSG
ID3DIS Display flag
TYPE Type NAME Name
BUIL Built flag SHOP Shop flag
BORE Pipe bore TEMP Temperature
PRES Pressure PSPE Pipe spec
ISPE Insulation spec TSPE Tracing spec
MATR Material ref FLUR Fluid ref
CASR List of cases ref CCEN Cost centre
CCLA Cost class DUTY Duty
LNTP Line type identifier EREC Erection
REV Revision DSCO Design code
PTSP Paint spec INSC Inspection schedule
SAFC Safety class ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QBRA( I D3DI S, TYPE, NAME, OWNE, LOCK,
BUIL, LHEA, LTAI, DETA, SHOP, LSTR, LNTP, EREC,
HBOR, TBOR, HCON, TCON, TEMP, PRES, FLOW, MATR,
FLUR, CASR, PSPE, ISPE, TSPE, CCEN, CCLA, DUTY,
DSCO, PTSP, INSC, SAFC, HSTU, HREF, TREF, HPOS,
HDIR, TPOS, TDIR, ID3ERR )

I NTEGER I D3DI S, EREC, CCEN, CCLA, SAFC, I D3ERR
LOGI CAL LOCK, BUI L, LHEA, LTAI , DETA, SHOP, LSTR
CHARACTER*( *) TYPE, NAME, OWNE, LNTP, HCON, TCON,
FLOW, MATR
CHARACTER*( *) FLUR, CASR, PSPE, I SPE, TSPE, DUTY,
DSCO, PTSP
CHARACTER*( *) I NSC, HSTU, HREF, TREF
REAL HBOR, TBOR, TEMP, PRES, HPOS( 3) , HDI R( 3)
REAL TPOS( 3) , TDI R( 3)
Performs the equivalent of a Q ATT for a branch.
Calls D3RNAM, D3XLEN, D3QBPA, D3RLOG, D3RREA, D3RWOR,
D3RRA, D3EMSG, D3ERST.

ID3DIS Display flag
TYPE Type NAME Name
BUIL Built flag LHEA Head flag
LTAI Tail flag DETA Detailed flag
SHOP Shop flag LSTR Stressed flag
LNTP Line type identifier EREC Erection
HBOR Head bore TBOR Tail bore
HCON Head connection type TCON Tail connection type
TEMP Temperature PRES Pressure
FLOW Flow direction MATR Material ref
FLUR Fluid ref CASR List of cases ref
PSPE Pipe spec ISPE Insulation spec
TSPE Tracing spec CCEN Cost centre
User Guide
Version 11.6
CCLA Cost class DUTY Duty
DSCO Design code PTSP Paint spec
INSC Inspection schedule SAFC Safety class
HSTU Tube spec ref
HREF Head ref
TREF Tail ref HPOS Head position
HDIR Head direction TPOS Tail position
TDIR Tail direction ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QBPA( I D3DI S, TYPE, NAME, OWNE, LOCK,
BUIL, SHOP, TEMP, PRES, PSPE, ISPE, TSPE, MATR,
FLUR, CASR, CCEN, CCLA, DUTY, LNTP, EREC, DSCO,
PTSP, INSC, SAFC, ID3ERR )

I NTEGER I D3DI S, CCEN, CCLA, EREC, SAFC, I D3ERR
LOGI CAL LOCK, BUI L, SHOP
CHARACTER*( *) TYPE, NAME, OWNE, PSPE, I SPE, TSPE,
MATR, FLUR
CHARACTER*( *) CASR, DUTY, LNTP, DSCO, PTSP, I NSC
REAL TEMP, PRES
Performs the equivalent of a Q ATT for the current element for the
attributes common to branch and pipe.
Calls D3QCMA, D3RLOG, D3RREA, D3RNAM, D3RINT, D3RTEX,
D3RWOR, D3XLEN, D3EMSG
Called by D3QBRA, D3QPIP
Arguments: as defined in D3QBRA, D3QPIP
User Guide
Version 11.6
SUBROUTINE D3QTEE( I D3DI S, TYPE, NAME, OWNE, LOCK,
POS, ORI, SPRE, LSTU, CREF, ARRI, LEAV, ANGL, HEIG,
RADI, BUIL, SHOP, ORIL, POSI, LOFF, ISPE, TSPE, ID3ERR
)

I NTEGER I D3DI S, ARRI , LEAV, I D3ERR
LOGI CAL LOCK, SHOP, BUI L, ORI L, POSI , LOFF
CHARACTER*( *) TYPE, NAME, OWNE, SPRE, LSTU, CREF,
I SPE, TSPE
REAL POS( 3) , ORI ( 3) , HEI G, RADI , ANGL
Performs the equivalent of a Q ATT for a TEE.
Calls D3RNAM, D3XLEN, D3QCPA, D3RREA, D3RLOG, D3EMSG,
D3ERST

ID3DIS Display flag
TYPE Type NAME Name
SPRE Spec ref LSTU Tube ref
CREF Connection ref ARRI Arrive PPoint
LEAV Leave PPoint ANGL Angle
HEIG Height RADI Radius
BUIL Built flag SHOP Shop flag
ORIL Orientation flag POSI Position flag
LOFF Offline flag ISPE Insulation spec
User Guide
Version 11.6
SUBROUTINE D3QELB( I D3DI S, TYPE, NAME, OWNE, LOCK,
POS, ORI, SPRE, LSTU, CREF, ARRI, LEAV, ANGL, RADI,
BUIL, SHOP, ORIL, POSI, ISPE, TSPE, ID3ERR )

LOGI CAL LOCK, SHOP, BUI L, ORI L, POSI
CHARACTER*( *) TYPE, NAME, OWNE, SPRE, LSTU, CREF,
I SPE, TSPE
REAL POS( 3) , ORI ( 3) , RADI , ANGL
Performs the equivalent of a Q ATT for an ELBO.
Calls D3RNAM, D3XLEN, D3QCPA, D3RREA, D3EMSG, D3ERST

ID3DIS Display flag
TYPE Type NAME Name
SPRE Spec ref LSTU Tube ref
CREF Connection ref ARRI Arrive PPoint
LEAV Leave PPoint ANGL Angle
RADI Radius BUIL Built flag
SHOP Shop flag ORIL Orientation flag
POSI Position flag ISPE Insulation spec
User Guide
Version 11.6
SUBROUTINE D3QCPA( I D3DI S, TYPE, NAME, OWNE, LOCK,
POS, ORI, SPRE, LSTU, ARRI, LEAV, BUIL, SHOP, ORIL,
POSI, ISPE, TSPE, ID3ERR )

LOGI CAL LOCK, BUI L, SHOP, ORI L, POSI
CHARACTER*( *) TYPE, NAME, OWNE, SPRE, LSTU, I SPE, TSPE
Performs the equivalent of a Q ATT for the current element for the
attributes common to piping components.
Calls D3QCMA, D3RRA, D3RNAM, D3RINT, D3RLOG, D3XLEN,
D3EMSG, D3ERST
Called by D3QELB, D3QTEE
Arguments: as defined in D3QELB, D3QTEE
SUBROUTINE D3QEQU( I D3DI S, TYPE, NAME, OWNE, LOCK,
FUNC, DSCO, PTSP, INSC, POS, ORI, ISPE, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, FUNC, DSCO, PTSP,
I NSC, I SPE
Performs the equivalent of a Q ATT for an EQUI.
Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RRA, D3EMSG
ID3DIS Display flag
TYPE Type NAME Name
FUNC Function DSCO Design code
PTSP Paint spec INSC Inspection schedule
ISPE Insulation schedule
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QNOZ( I D3DI S, TYPE, NAME, OWNE, LOCK,
TEMP, PRES, POS, ORI, CREF, CATR, ANGL, HEIG, RADI,
DUTY, ISPE, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, CREF, CATR, DUTY, I SPE
REAL POS( 3) , ORI ( 3) , TEMP, PRES, HEI G, ANGL,
RADI
Performs the equivalent of a Q ATT for a NOZZ.

Calls D3RNAM, D3XLEN, D3QCMA, D3RREA, D3RRA, D3RTEX,
D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
TEMP Temperature PRES Pressure
CREF Connection ref CATR Catalogue ref
ANGL Angle HEIG Height
RADI Radius DUTY Duty
ISPE Insulation spec ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QBOX( I D3DI S, TYPE, NAME, OWNE, LOCK,
XLEN, YLEN, ZLEN, POS, ORI, LEVE, OBST, ID3ERR )

I NTEGER I D3DI S, LEVE( 2) , OBST, I D3ERR
LOGI CAL LOCK
REAL POS( 3) , ORI ( 3) , XLEN, YLEN, ZLEN
Performs the equivalent of a Q ATT for a BOX.
Calls D3RNAM, D3XLEN, D3QCMA, D3RREA, D3RRA, D3RIA,
D3RINT, D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
XLEN X length YLEN Y length
ZLEN Z length POS Position
ORI Orientation LEVE Drawing level
OBST Obstruction level ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QCAT( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )

LOGI CAL LOCK
Performs the equivalent of a Q ATT for an CATA.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QSEC( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )

LOGI CAL LOCK

Performs the equivalent of a Q ATT for an SECT.
ID3DIS Display flag
TYPE Type NAME Name
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QCOM( I D3DI S, TYPE, NAME, OWNE, LOCK,
GTYP, PTRE, GMRE, ID3NIN, PARA, PARWOR, ID3NOU,
ID3ERR )

I NTEGER I D3DI S, I D3NI N, I D3NOU, I D3ERR
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, GTYP, PTRE, GMRE
CHARACTER*( *) PARWOR( I D3NI N)
REAL PARA( I D3NI N)

Performs the equivalent of a Q ATT for a SCOMP
Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3RRA, D3UDEH,
D3EMSG, D3ERST

ID3DIS Display flag
ID3NIN Max number of elements for PARA array
TYPE Type NAME Name
GTYP Generic type PTRE Point set ref
GMRE Geometry set ref PARA Parameters array
PARWOR Array of dehashed word parameters
ID3NOU Number of elements returned in PARA array
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QUNI( I D3DI S, TYPE, NAME, OWNE, LOCK,
BUNI, DUNI, DFUN, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, BUNI , DUNI , DFUN

Performs the equivalent of a Q ATT for a UNIT.
Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3EMSG, D3ERST

ID3DIS Display flag
TYPE Type NAME Name
BUNI Bore units DUNI Distance units
DFUN Defined units ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QUSE( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )

LOGI CAL LOCK

Performs the equivalent of a Q ATT for an USEC.

ID3DIS Display flag
TYPE Type NAME Name
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QUDE( I D3DI S, TYPE, NAME, OWNE, LOCK,
ABRE, ADEN, MULT, SIGF, DECP, ID3ERR )

I NTEGER I D3DI S, SI GF, DECP, I D3ERR
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, ABRE
REAL ADEN, MULT
Performs the equivalent of a Q ATT for a UDEF.
Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RREA, D3RINT,
D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
ABRE Abbreviation ADEN Adend
MULT Multiplier SIGF Significant figures
DECP Decimal places ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QMSE( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )
LOGI CAL LOCK
Performs the equivalent of a Q ATT for an MSET.

ID3DIS Display flag
TYPE Type NAME Name
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QMTY( I D3DI S, TYPE, NAME, OWNE, LOCK,
UREF, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, UREF
Performs the equivalent of a Q ATT for an MTYP.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG, D3ERST

ID3DIS Display flag
TYPE Type NAME Name
UREF Units reference ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QATL( I D3DI S, TYPE, NAME, OWNE, LOCK,
ATNA, ID3ERR )
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, ATNA
Performs the equivalent of a Q ATT for an ATLI.
Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3EMSG, D3ERST

ID3DIS Display flag
TYPE Type NAME Name
ATNA Atname ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QSPW( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )
LOGI CAL LOCK
Performs the equivalent of a Q ATT for an SPWL.

ID3DIS Display flag
TYPE Type NAME Name
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QSPE( I D3DI S, TYPE, NAME, OWNE, LOCK,
QUAL, QUES, DEFA, TDEFA, MATR, FLUR, RATI, LNTP,
ID3ERR )

I NTEGER I D3DI S, QUAL, I D3ERR
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, QUES, TDEFA, MATR,
FLUR, LNTP
REAL RATI . DEFA
Performs the equivalent of a Q ATT for a SPEC.
Calls D3RNAM, D3XLEN, D3QCMA, D3RINT, D3RWOR, D3RREA,
D3EMSG, D3ERST, D3RTEX

ID3DIS Display flag
TYPE Type NAME Name
QUAL Quality QUES Question
DEFA Default TDEFA Text default
MATR Material ref FLUR Fluid ref
RATI Pressure rating LNTP Line type
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QSEL( I D3DI S, TYPE, NAME, OWNE, LOCK,
QUAL, QUES, ANSW, TANSW, MAXA, DEFA, TDEFA,
ID3ERR )

I NTEGER I D3DI S, QUAL, I D3ERR
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, QUES, TANSW, TDEFA
REAL ANSW, MAXA, DEFA

Performs the equivalent of a Q ATT for a SELE.
Calls D3RNAM, D3XLEN, D3QCMA, D3RINT, D3RWOR, D3EMSG,
D3RREA, D3ERST, D3RTEX
ID3DIS Display flag
TYPE Type NAME Name
QUAL Quality QUES Question
ANSW Answer TANSW Text answer
MAXA Maxan DEFA Default
TDEFA Text default ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QSPC( I D3DI S, TYPE, NAME, OWNE, LOCK,
ANSW, MAXA, TANSW, CATR, CMPR, BLTR, DETR, MATX,
ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, TANSW, CATR, CMPR,
BLTR, DETR
CHARACTER*( *) MATX
REAL ANSW, MAXA
Performs the equivalent of a Q ATT for a SPCO.
Calls D3RNAM, D3XLEN, D3QCMA, D3RREA, D3EMSG, D3ERST,
D3RTEX
ID3DIS Display flag
TYPE Type NAME Name
ANSW Answer MAXA Maxan
TANSW Text answer CATR Catalogue ref
CMPR Component ref BLTR Bolt ref
DETR Detail text ref MATX Material text ref
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QCCT( I D3DI S, TYPE, NAME, OWNE, LOCK,
ID3ERR )

LOGI CAL LOCK
Performs the equivalent of a Q ATT for a CCTA.

ID3DIS Display flag
TYPE Type NAME Name
ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QCOC( I D3DI S, TYPE, NAME, OWNE, LOCK,
CTYP, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, CTYP( 2)
Performs the equivalent of a Q ATT for a COCO.
Calls D3RNAM, D3XLEN, D3QCMA, D3RWA, D3EMSG
ID3DIS Display flag
TYPE Type NAME Name
CTYP Connection type array ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QTUB( I D3DI S, TYPE, NAME, OWNE, LOCK,
OUTD, ACBO, BTOL, WTOL, UWEI, UIWE, WDIA, SHAP,
RINE, SIF, PRFC, SDTH, CORA, EFAC, PWAS, BFLE,
MRKR, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, MRKR
REAL OUTD, ACBO, BTOL, WTOL, WDI A, SHAP,
RI NE( 3)
REAL SI F( 3) , PRFC, SDTH( 3) , CORA, EFAC,
PWAS, BFLE
REAL UWEI , UI WE

Performs the equivalent of a Q ATT for a TUBD.
Calls D3RNAM, D3XLEN, D3QCDA, D3RREA, D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
OUTD Outside diameter ACBO Actual bore
BTOL Bore tolerance WTOL Wall thickness
tolerance
UWEI Unit pipe weight UIWE Unit insulation weight
WDIA Wind diameter modulus SHAP Shape modulus
RINE Rotational inertia SIF Stress intensity factor
PRFC Pressure factor SDTH Saddle thickness
CORA Corrosion thickness EFAC E-factor
PWAS Percentage waste factor
BFLE Out of plane flexibility factor for bends
MRKR 3 way component marker ID3ERR Error code
SUBROUTINE D3QCMP( I D3DI S, TYPE, NAME, OWNE, LOCK,
OUTD, ACBO, BTOL, WTOL, CWEI, CIWE, WDIA, SHAP,
User Guide
Version 11.6
RINE, SIF, PRFC, SDTH, CORA, EFAC, PWAS, BFLE, DFFL,
DMFL, RMFL, MRKR, ID3ERR )

LOGI CAL LOCK
REAL OUTD, ACBO, BTOL, WTOL, WDI A, SHAP, RI NE( 3) ,
SI F( 3) , PRFC
REAL SDTH( 3) , CORA, EFAC, PWAS, BFLE, CWEI , CI WE,
DFFL( 6)
REAL DMFL( 9) , RMFL( 6)
Performs the equivalent of a Q ATT for a CMPD.
Calls D3RNAM, D3XLEN, D3QCDA, D3RREA, D3RRA, D3EMSG

ID3DIS Display flag
TYPE Type NAME Name
OUTD Outside diameter ACBO Actual bore
BTOL Bore tolerance WTOL Wall thickness
tolerance
CWEI Total component weight CIWE Total insulation
weight
WDIA Wind diameter modulus SHAP Shape modulus
RINE Rotational inertia SIF Stress intensity factor
PRFC Pressure factor SDTH Saddle thickness
CORA Corrosion thickness EFAC E-factor
PWAS Percentage waste factor
BFLE Out of plane flexibility factor for bends
Next three are parts of flexibility matrix for component
DFFL Displacement force DMFL Displacement moment
RMFL Rotation moment
MRKR 3 way component marker ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QCDA( I D3DI S, TYPE, NAME, OWNE, LOCK,
OUTD, ACBO, BTOL, WTOL, WDIA, SHAP, RINE, SIF,
PRFC, SDTH, CORA, EFAC, PWAS, BFLE, MRKR, ID3ERR )

LOGI CAL LOCK
REAL OUTD, ACBO, BTOL, WTOL, WDI A, SHAP,
RI NE( 3)
REAL SI F( 3) , PRFC, SDTH( 3) , CORA, EFAC,
PWAS, BFLE

Performs the equivalent of a Q ATT for the attributes common to TUBD
and CMPD.
Calls D3QCMA, D3RREA, D3RRA, D3RWOR, D3XLEN, D3EMSG,
D3ERST
Called by D3QCMP D3QTUB
Arguments: as defined in D3QCMP, D3QTUB
User Guide
Version 11.6
SUBROUTINE D3QCON( I D3DI S, TYPE, NAME, OWNE, LOCK,
APPL, FORC, MOME, DISP, ROTN, DLIM, RLIM, FLIM,
MLIM, DFLF, RFLF, FCOE, CPUL, CPUT, ID3ERR )

LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, APPL
REAL FORC( 3) , MOME( 3) , DI SP( 3) , ROTN( 3) ,
DLI M( 6)
REAL RLI M( 6) , FLI M( 3) , MLI M( 3) , DFLF( 3) ,
RFLF( 3)
REAL FCOE( 3) , CPUL( 3) , CPUT( 3)

Performs the equivalent of a Q ATT for a CONS.
Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RRA, D3EMSG
ID3DIS Display flag
TYPE Type NAME Name
APPL Application FORC Force
MOME Moment DISP Displacement
ROTN Rotation DLIM Displacement limits
RLIM Rotation limits FLIM Force limits
MLIM Moment limits DFLF Linear flexibility
factors
RFLF Rotational flexibility factors
FCOE Friction coefficient CPUL Cold pull
CPUT Cold twist ID3ERR Error code
User Guide
Version 11.6
SUBROUTINE D3QUDA( I D3DI S, TYPE, NAME, OWNE, LOCK,
UKEY, UDNA, ABLE, UTYP, ULEN, DFLT, RPTX, DESC,
UUNI, ELEL, MAXE, OUTE, REFL, MAXR, OUTR, ID3ERR )

I NTEGER I D3DI S, I D3ERR, UKEY, ABLE, ULEN,
MAXE, OUTE
I NTEGER MAXR, OUTR
LOGI CAL LOCK
CHARACTER*( *) TYPE, NAME, OWNE, UDNA, UTYP, DFLT,
RPTX, DESC
CHARACTER*( *) UUNI , ELEL( MAXE) , REFL( MAXR)

Performs the equivalent of a Q ATT for a UDA in the dictionary
database.
Calls D3RNAM, D3XLEN, D3QCMA, D3RINT, D3EMSG, D3RTEX,
D3RWOR, D3RWA, D3ERST
ID3DIS Display flag MAXE Size of ELEL array
MAXR Size of REFL array
TYPE Type NAME Name
UKEY UDA key UDNA UDA name (without :)
ABLE Min. abbrev. of UDNA UTYP UDA type
ULEN No. of values if an array or maximum length if TEXT or
WORD
DFLT Default value as text RPTX REPORTER text
DESC Description UUNI UNITs
ELEL Element list REFL Reference list
OUTE No. of elements returned in ELEL
OUTR No. of elements returned in REFL
ID3ERR Error code
User Guide
Version 11.6
INTEGER FUNCTION D3XLEN( CD3STR )
CHARACTER*( *) CD3STR
Returns significant length of string. That is, length after removing
trailing blanks. Returns length of 1 for a blank string, ' '.
Identical to DARs routine D3ULEN, except for treatment of blank string.
For use in the construction STRI NG( : D3XLEN( STRI NG) ) to avoid run-
time error with some compilers when using D3ULEN and a blank string.
Calls D3ULEN
Called by most other auxiliary routines.

CD3STR Character string
D3XLEN Significant length of CD3STR (min 1)

User Guide
Version 11.6

E Multibyte Text Handling
If a PDMS project has been identified as multibyte (PROJECT
MBCHARSET in the ADMIN module), it is possible for users to enter
multibyte element names and attributes in some PDMS modules. This
allows Far Eastern users to enter Kanji text, which is stored in PDMS as
multibyte text (two bytes per Kanji character). Everything in this
section referring to Kanji also applies to Chinese characters. PDMS uses
the name 'FECs' (Far Eastern Characters) to indicate any multibyte
character text. The byte pairs correspond to the appropriate ISO-IR
registration. For example, for Kanji, the byte pairs correspond to ISO-
IR 87, the Japanese standard registered with the International
Standards Organisation.
FECs text can be input to or returned by DARs routines; for example:
D3MNAM: in the CD3NAM (element name) input argument
D3RNAM: in the CD3NAM (element name) return argument
D3RTEX: in the CD3TEX (text attribute) return argument
D3RPTX: in the CD3RPT (REPORTER text) return argument
D3RPAT: in the CD3CRD (coordinate system) input argument
Within DARs, multibyte text is input or returned as byte-pairs delimited
by 'escape sequences'. These are the 'FECS-IN' and 'FECS-OUT'
sequences:
FECS-IN sequence : '&~' (ISO 2/6, ISO 7/14)
FECS-OUT sequence : ' &' (ISO 2/0, ISO 2/6)
These sequences were carefully selected and meet the following criteria:
The FECS-IN sequence does not occur frequently in non-FECs usage
The FECS-OUT sequence does not exist as a byte-pair

It is possible to freely mix single-byte and multi-byte text in any text
string. For example, the text string ' abc&~4A; z & def ' is interpreted
as follows:
3 characters ' abc'
2 byte pairs corresponding to ' 4A' and ' ; z' (meaning 'kanji')
VANTAGE Plant Design Data Access Routines E-1
User Guide
Version 11.6
Multibyte Text Handling
4 characters ' def '
Genuine occurrences of ' &~' are denoted by ' &&~' ; so that
' abc&&~&~4A; z & def ' is interpreted as:
5 characters ' abc&~'
2 byte pairs corresponding to ' 4A' and ' ; z' (meaning 'kanji')
It is possible for the byte-pair '&~' to occur within a FECs string. Thus,
' abc&~&~4A; z & def ' is interpreted as:
3 characters ' abc'
3 byte pairs corresponding to ' &~' , ' 4A' and ' ; z'
Using these simple rules, Far Eastern DARs programmers should be
able to convert output FECs strings from PDMS format to the format
corresponding to their host computer and its peripherals (e.g. for output
to a Kanji terminal or printer). It is not necessary for programmers or
DARs users to know the layout of the ISO-IR 87 tabulation.
The following example program may assist programmers. It is a stand-
alone program, using no DARs routines. The user is prompted to enter
text strings containing FECS-IN and FECS-OUT sequences. The
statement converting single-byte to multibyte is machine-specific.
PROGRAM FECSRD
C Pr ogr amt o r ead, t r ansl at e and pr i nt FECs t ext
C
EXTERNAL FECS
CHARACTER*50 STRI NG, FECS, STRI N2
C
100 CONTI NUE
READ( *, ' ( A) ' ) STRI NG
I F ( STRI NG . EQ. ' ' ) GOTO 999
STRI N2 = FECS( STRI NG)
PRI NT*, STRI N2
GOTO 100
999 CONTI NUE
CALL EXI T
END
E-2 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
CHARACTER*( *) FUNCTI ON FECS( STRI NG)
C Funct i on t o t r ansl at e FECs st r i ng
C ( machi ne- speci f i c i n par t s)
C
CHARACTER*( *) STRI NG
C
I NTEGER I POS, OPOS, I LEN, OLEN, I PAI R, I POSM1,
I POSP1
LOGI CAL LFECS
C
I NTRI NSI C MI N, MAX, LEN, CHAR, I CHAR
I LEN = LEN( STRI NG)
OLEN = LEN( FECS)
I POS = 0
OPOS = 0
FECS = ' '
LFECS = . FALSE.
100 CONTI NUE
C Consi der f i r st ( next ) char act er
I POS = I POS + 1
I F ( I POS . GT. I LEN) GOTO 999
C Ski p i f r emai nder i s bl ank ( t o save t i me)
I F ( STRI NG( I POS: ) . EQ. ' ' ) GOTO 999
OPOS = OPOS + 1
I F ( OPOS . GT. OLEN) GOTO 999
I F ( . NOT. LFECS) THEN
C Not al r eady mul t i byt e
C Test f or FECS- I N
I POSM1 = MAX( I POS- 1, 1)
I POSP1 = MI N( I POS+1, I LEN)
I F ( STRI NG( I POS: I POSP1) . EQ. ' &~'
+ . AND. STRI NG( I POSM1: I POS) . NE. ' &&' ) THEN
C FECS- I N f ound
LFECS = . TRUE.
User Guide
Version 11.6
I POS = I POS + 2
I PAI R = 0
ENDI F
ENDI F
I F ( LFECS) THEN
C Mul t i byt e por t i on of t ext st r i ng
I PAI R = I PAI R + 1
C I f I PAI R i s odd ( f i r st of a byt e- pai r ) , t est
f or FECS- OUT
I POSP1 = MI N( I POS+1, I LEN)
I F ( 2*( I PAI R/ 2) . NE. I PAI R
+ . AND. STRI NG( I POS: I POSP1) . EQ. ' &' ) THEN
C FECS- OUT f ound
LFECS = . FALSE.
I POS = I POS + 2
ENDI F
ENDI F
C Copy i nput st r i ng t o out put st r i ng
I F ( LFECS) THEN
C Mul t i byt e por t i on of t ext st r i ng and not FEC-
OUT
C Conver t t o ASCI I , add 128 t o ASCI I val ue,
conver t back
FECS( OPOS: OPOS) = CHAR( I CHAR( STRI NG( I POS: I POS) )
+ 128)
ELSE
FECS( OPOS: OPOS) = STRI NG( I POS: I POS)
ENDI F
C Look at next char act er
GOTO 100
C
999 CONTI NUE
C
User Guide
Version 11.6
RETURN
END

The following is a DARs example, reading FECs names and text from a
FECs project. Character function FECS is the same as that listed above.

C- - - - - - - - - - - - - - - - - - -
PROGRAM FECDAR
C- - - - - - - - - - - - - - - - - - -

C FECs t r ansl at i on t est

CHARACTER*50 NAME, FECS, NAME3, CNAME, CNAME3
CHARACTER*120 TEXT
CHARACTER*1 CDUM
I NTEGER I ERR, I POS
EXTERNAL D3I NI T, D3ERST, D3MMDB, D3MNAM,
D3RTEX, D3RNAM
EXTERNAL D3EMSG, D3MNUM, D3FI N, D3FEND, FECS,
FECST

C Pr oj ect ent r y
CALL D3I NI T( ' FEC' , ' SYSTEM' , ' XXXXXX' , ' NONE' , '
' , I ERR )
I F ( I ERR. NE. 0) GOTO 9000
C MDB Sel ect i on
CALL D3MMDB ( ' DES/ | }~' , ' ' , I ERR )
I F ( I ERR . NE. 0 ) GOTO 9000
C Go t o zone
CALL D3MNAM( ' / ZONE1. EQUI P' , I ERR)
I F ( I ERR . NE. 0 ) GOTO 9000
C Got o each equi pment i t emand r ead names
PRI NT*, ' Equi pment i n zone / ZONE1. EQUI P: '
I POS = 0
User Guide
Version 11.6
NAME3 = ' '
100 CONTI NUE
I POS = I POS + 1
CALL D3MNUM( ' EQUI P' , I POS, I ERR)
I F ( I ERR . EQ. 203) THEN
CALL D3ERST
GOTO 200
ELSEI F ( I ERR . NE. 0 ) THEN
GOTO 9000
ENDI F
CALL D3RNAM( ' NAME' , NAME, I ERR )
I F ( I ERR . NE. 0 ) GOTO 9000
C Conver t any FECs i n name
CNAME = FECS( NAME)
PRI NT*, ' ' , CNAME
C Remember 3r d equi pment name
I F ( I POS . EQ. 3) THEN
NAME3 = NAME
CNAME3 = CNAME
ENDI F
GOTO 100
200 CONTI NUE
C
C Get at t r i but es of l ast equi pment
PRI NT*, ' Text at t r i but es of ' , CNAME
CALL FECST( ' DSCODE' )
CALL FECST( ' FUNCTI ON' )
CALL FECST( ' PTSPEC' )
CALL FECST( ' I NSCHED' )
C
C Go t o 3r d equi pment , by name - t hen at t r i but es
I F ( NAME3 . NE. ' ' ) THEN
CALL D3MNAM( NAME3, I ERR)
I F ( I ERR . NE. 0 ) THEN
User Guide
Version 11.6
PRI NT*, NAME3
GOTO 9000
ENDI F
CNAME = CNAME3
NAME3 = ' '
GOTO 200
ENDI F
I ERR = 0
C
C Exi t
9000 CONTI NUE
I F ( I ERR . NE. 0) CALL D3EMSG( I ERR, . TRUE. , CDUM)
CALL D3FI N( I ERR )
CALL D3FEND
END
C- - - - - - - - - - - - - - - - - - - - - - - - - - -
SUBROUTI NE FECST( NAME)
C- - - - - - - - - - - - - - - - - - - - - - - - - - -
C Subr out i ne t o r ead, t r ansl at e and pr i nt
( possi bl e) FECs at t r i but e
C
CHARACTER*( *) NAME
CHARACTER*120 TEXT, FECS, CTEXT
CHARACTER*1 CDUM
I NTEGER D3ULEN, I ERR
EXTERNAL D3ULEN, FECS, D3EMSG, D3ERST, D3RTEX
C
CALL D3RTEX( NAME, TEXT, I ERR)
C Conver t any FECs i n name
CTEXT = FECS( TEXT)
I F ( I ERR . NE. 0) THEN
CTEXT = ' ??????'
CALL D3EMSG( I ERR, . TRUE. , CDUM)
CALL D3ERST
User Guide
Version 11.6
ENDI F
I F ( CTEXT . EQ. ' ' ) CTEXT = ' **unset **'
PRI NT*, ' ' , NAME, ' : ' , CTEXT( : D3ULEN( CTEXT) )
RETURN
END
The output from the above program appears as follows. Since Aveva has
no Kanji printer, Kanji text in this example is indicated by '@' characters.
Equi pment i n zone / ZONE1. EQUI P:
/ VESS1
/ VESS2
/ @@@@@@pump
/ @@@@@@@@@@@@
/ @@@@@@
/ @@@@@@111
Text at t r i but es of / @@@@@@111
DSCODE: @@@@J apan
FUNCTI ON: @@@@@@@@
PTSPEC: Gr ade 1 @@@@@@2 coat s
I NSCHED: @@@@@@i s beaut i f ul
Text at t r i but es of / @@@@@@pump
DSCODE: **unset **
FUNCTI ON: **unset **
PTSPEC: ABNS @@@@@@@@@@abcv
I NSCHED: **unset **

User Guide
Version 11.6

F C/C++ Library
F.1 Software Issued with DARs C/C++ Library
At PDMS 11.6, the DARs C/C++ library is included in with the DARs.
The files provided with a PDMS DARs C/C++ library are listed in
Appendix A
F.2 Application Program Compilation and Linking
The DARs 'C/C++' library is provided to allow programmers to interface
PDMS DARs to programs written in C and/or C++.

Compilation and linking can be achieved by the use of the script
ccompload for C code, and cxxcompload for C++ code. A listing of these
is included in section ??? of this appendix.
F.3 Program Running and Debugging
If an application program enters D3INIT successfully, program
debugging can be assisted by use of the FULL monitoring level. This can
be switched on in D3INIT or by a later call to D3UMON.
F.4 Acceptance Test Program
An example program (c_example.c, see section below) constitutes an
Acceptance Test. This test follows a similar format to the FORTRAN
test, without the d3test example:

1. Set the appropriate DAR project environment variables:
e.g. set env DAR000 $PDMSEXE/ dar s/ dar 000
set env DAR100 $PDMSEXE/ dar s/ dar 100
VANTAGE Plant Design Data Access Routines F-1
User Guide
Version 11.6
C/C++ Library
2. Set the DARs library environment variable:
e.g. set env DARSLI BDI R $PDMSEXE/ dar s
3. Create a work directory and copy c_example.c into the work directory
from the DARs release directory $DARSLIBDIR.
4. Change directory to the work directory
5. Enter $DARSLI BDI R/ ccompl oad c_exampl e
6. Enter c_exampl e
Does the output appear to be the same as the output listed in section
???of this appendix (allowing for differences of print format)?
F.5 Compilation and Linking Script
'C' application programs are best implemented using scripts similar to
ccompload, and C++ with cxxcompload. Script ccompload compiles and
links any DARs 'C' application program. The name of the 'C' source file
is entered as a command line argument (e.g. ccompl oad c_exampl e. c)
As an alternative, the program may be compiled and linked using a
makefile based on the commands in ccompload.

compload.bat
@echo of f
appl i cat i on C pr ogr am.

got o FI NI SH
: GOTFI LE
cl - Tc%1 - I %PDMSEXE%\ dar s %PDMSEXE%\ dar s\ d3l i b. l i b

: FI NI SH
F-2 VANTAGE Plant Design Data Access Routines
User Guide
Version 11.6
C/C++ Library

cxxcompload.bat

@echo of f

appl i cat i on C++ pr ogr am.

got o FI NI SH

: GOTFI LE

cl - Tp%1 - I %PDMSEXE%\ dar s %PDMSEXE%\ dar s\ d3l i b. l i b

: FI NI SH

F.6 'C/C++' Header Files
Two 'C/C++' header files are supplied with the 'C/C++' DARs library.
They are included in any 'C/C++' DARs application program. pdms.h is
included within d3libc.h .
d3libc.h:
d3libc.h is the header file that defines the DARs routine 'C' prototypes.

** d3l i bc. h
**
** header f i l e f or DARS C t o FORTRAN i nt er f ace.
** The DAR r out i nes ar e wr i t t en i n FORTRAN
** but her e i s t he user C/ C++ i nt er f ace
User Guide
Version 11.6
C/C++ Library
**
** Not es:
** 1. ar gument s ar e passed by addr ess.
**
**/

#i f ndef D3LI BC_H
#def i ne D3LI BC_H

/ * end of syst emi ncl udes */
#i ncl ude <pdms. h>

/ *
** DAR i nt er f ace f unct i on/ subr out i ne pr ot ot ypes
*/

#i f def __cpl uspl us

ext er n " C" voi d d3echk ( char *cd3er r ) ;
ext er n " C" voi d d3emsg ( i nt *i d3er r , i nt *l d3di s,
DARS_MESS cd3msg ) ;
ext er n " C" voi d d3er st ( voi d ) ;
ext er n " C" voi d d3f end ( voi d ) ;
ext er n " C" voi d d3f i n ( i nt *i d3er r ) ;
ext er n " C" voi d d3i ni t ( char *cd3pr j , char *cd3usr ,
char *cd3pas,
char *cd3mon, char *cd3wr k,
i nt *i d3er r ) ;
ext er n " C" voi d d3mcdb ( char *cd3nam, i nt *i d3pos, i nt
*i d3er r ) ;
ext er n " C" voi d d3mddb ( char *cd3nam, i nt *i d3er r ) ;
ext er n " C" voi d d3medb ( char *cd3nm1, char *cd3nm2,
i nt *i d3er r ) ;
ext er n " C" voi d d3mmdb ( char *cd3mdb, char *cd3wr k,
i nt *i d3er r ) ;
ext er n " C" voi d d3mnam ( char *cd3nam, i nt *i d3er r ) ;
User Guide
Version 11.6
C/C++ Library
ext er n " C" voi d d3mnum ( char *cd3t yp, i nt *i d3l i s, i nt
*i d3er r ) ;
ext er n " C" voi d d3mown ( i nt *i d3er r ) ;
ext er n " C" voi d d3mqdb ( i nt *i d3pos, PDMS_DBNAME
cd3nam, PDMS_WORD cd3t yp,
i nt *i d3st a, i nt *i d3er r ) ;
ext er n " C" voi d d3mr el ( char *cd3pos, char *cd3t yp,
i nt *i d3er r ) ;
ext er n " C" voi d d3mr st ( i nt *i d3er r ) ;
ext er n " C" voi d d3msav ( i nt *i d3er r ) ;
ext er n " C" voi d d3r bdu ( PDMS_WORD cd3bun, PDMS_WORD
cd3dun, i nt *i d3er r ) ;
ext er n " C" voi d d3r box ( i nt *l d3t ub, f l oat *r d3box,
i nt *i d3er r ) ;
ext er n " C" voi d d3r dat ( i nt *i d3dat , DARS_RDAT cd3dat ,
i nt *i d3er r ) ;
ext er n " C" voi d d3r i a ( char *cd3at t , i nt *i d3ni n, i nt
*i d3i a,
i nt *i d3nou, i nt *i d3er r ) ;
ext er n " C" voi d d3r i nt ( char *cd3at t , i nt *i d3i nt , i nt
*i d3er r ) ;
ext er n " C" voi d d3r l a ( char *cd3at t , i nt *i d3ni n, i nt
*l d3l a,
ext er n " C" voi d d3r l og ( char *cd3at t , i nt *l d3l og, i nt
*i d3er r ) ;
ext er n " C" voi d d3r nam ( char *cd3at t , PDMS_NAME
cd3nam, i nt *i d3er r ) ;
ext er n " C" voi d d3r or l ( char *cd3cr d, f l oat *r d3or i ,
i nt *i d3er r ) ;
ext er n " C" voi d d3r pat ( char *cd3poi , char *cd3cr d,
f l oat *r d3pos,
f l oat *r d3di r , f l oat *r d3bor ,
PDMS_WORD cd3con,
i nt *i d3er r ) ;
ext er n " C" voi d d3r pr j ( char *cd3nam, PDMS_TEXT
cd3t ex, i nt *i d3er r ) ;
ext er n " C" voi d d3r pr l ( char *cd3cr d, f l oat *r d3pos,
i nt *i d3er r ) ;
User Guide
Version 11.6
C/C++ Library
ext er n " C" voi d d3r pt x ( char *cd3at t , PDMS_RPTX
cd3r pt , i nt *i d3er r ) ;
ext er n " C" voi d d3r r a ( char *cd3at t , i nt *i d3ni n,
f l oat *r d3r a,
ext er n " C" voi d d3r r ea ( char *cd3at t , f l oat *r d3r ea,
i nt *i d3er r ) ;
ext er n " C" voi d d3r r ef ( char *cd3at t , PDMS_NAME
cd3r ef , i nt *i d3er r ) ;
ext er n " C" voi d d3r r f a ( char *cd3at t , i nt *i d3ni n,
PDMS_NAME cd3r f a[ ] ,
ext er n " C" voi d d3r t ex ( char *cd3at t , PDMS_TEXT
cd3t ex, i nt *i d3er r ) ;
ext er n " C" voi d d3r t yp ( PDMS_WORD cd3t yp, i nt *i d3er r
) ;
ext er n " C" voi d d3r uda ( char *cd3t yp, i nt *i d3max,
PDMS_UDNA cd3nms[ ] ,
i nt *i d3abv, PDMS_WORD
cd3at p[ ] , i nt *i d3num,
i nt *i d3er r ) ;
ext er n " C" voi d d3r uni ( char *cd3at t , PDMS_UUNI
cd3unt , i nt *i d3er r ) ;
ext er n " C" voi d d3r wa ( char *cd3at t , i nt *i d3ni n,
PDMS_WORD cd3wa[ ] ,
ext er n " C" voi d d3r wor ( char *cd3at t , PDMS_WORD
cd3wor , i nt *i d3er r ) ;
ext er n " C" i nt d3ucl u ( i nt *i d3uni ) ;
/ *
** cd3bef and cd3af t MUST be decl ar ed same l engt h as
cd3st r
*/
ext er n " C" i nt d3uct i ( char *cd3st r , i nt *i d3i nt ,
char *cd3bef ,
char *cd3af t , DARS_CERR cd3er r
) ;
/ *
User Guide
Version 11.6
C/C++ Library
cd3st r
*/
ext er n " C" i nt d3uct r ( char *cd3st r , f l oat *r d3val ,
char *cd3bef ,
) ;
ext er n " C" voi d d3udeh ( i nt *i d3i nt , PDMS_WORD cd3wor
) ;
ext er n " C" voi d d3udt m ( i nt *i d3dat , DARS_RDAT cd3dat
) ;
ext er n " C" i nt d3ugt u ( i nt *i d3uni ) ;
ext er n " C" voi d d3ui ni ( i nt *r eady ) ;
ext er n " C" i nt d3ul ds ( char *cd3dat , i nt *i d3er r ) ;
ext er n " C" i nt d3ul en ( char *cd3st r ) ;
ext er n " C" voi d d3umon ( char *cd3mon ) ;

#el se / * C r at her t han C++ */

voi d d3echk ( char *cd3er r ) ;
voi d d3emsg ( i nt *i d3er r , i nt *l d3di s, DARS_MESS
cd3msg ) ;
voi d d3er st ( voi d ) ;
voi d d3f end ( voi d ) ;
voi d d3f i n ( i nt *i d3er r ) ;
voi d d3i ni t ( char *cd3pr j , char *cd3usr , char
*cd3pas,
char *cd3mon, char *cd3wr k,
i nt *i d3er r ) ;
voi d d3mcdb ( char *cd3nam, i nt *i d3pos, i nt *i d3er r
) ;
voi d d3mddb ( char *cd3nam, i nt *i d3er r ) ;
voi d d3medb ( char *cd3nm1, char *cd3nm2, i nt
*i d3er r ) ;
voi d d3mmdb ( char *cd3mdb, char *cd3wr k, i nt
*i d3er r ) ;
voi d d3mnam ( char *cd3nam, i nt *i d3er r ) ;
User Guide
Version 11.6
C/C++ Library
voi d d3mnum ( char *cd3t yp, i nt *i d3l i s, i nt *i d3er r
) ;
voi d d3mown ( i nt *i d3er r ) ;
voi d d3mqdb ( i nt *i d3pos, PDMS_DBNAME cd3nam,
PDMS_WORD cd3t yp,
i nt *i d3st a, i nt *i d3er r ) ;
voi d d3mr el ( char *cd3pos, char *cd3t yp, i nt
*i d3er r ) ;
voi d d3mr st ( i nt *i d3er r ) ;
voi d d3msav ( i nt *i d3er r ) ;
voi d d3r bdu ( PDMS_WORD cd3bun, PDMS_WORD cd3dun,
i nt *i d3er r ) ;
voi d d3r box ( i nt *l d3t ub, f l oat *r d3box, i nt
*i d3er r ) ;
voi d d3r dat ( i nt *i d3dat , DARS_RDAT cd3dat , i nt
*i d3er r ) ;
voi d d3r i a ( char *cd3at t , i nt *i d3ni n, i nt *i d3i a,
voi d d3r i nt ( char *cd3at t , i nt *i d3i nt , i nt *i d3er r
) ;
voi d d3r l a ( char *cd3at t , i nt *i d3ni n, i nt *l d3l a,
voi d d3r l og ( char *cd3at t , i nt *l d3l og, i nt *i d3er r
) ;
voi d d3r nam ( char *cd3at t , PDMS_NAME cd3nam, i nt
*i d3er r ) ;
voi d d3r or l ( char *cd3cr d, f l oat *r d3or i , i nt
*i d3er r ) ;
voi d d3r pat ( char *cd3poi , char *cd3cr d, f l oat
*r d3pos,
f l oat *r d3di r , f l oat *r d3bor ,
PDMS_WORD cd3con,
i nt *i d3er r ) ;
voi d d3r pr j ( char *cd3nam, PDMS_TEXT cd3t ex, i nt
*i d3er r ) ;
voi d d3r pr l ( char *cd3cr d, f l oat *r d3pos, i nt
*i d3er r ) ;
User Guide
Version 11.6
C/C++ Library
voi d d3r pt x ( char *cd3at t , PDMS_RPTX cd3r pt , i nt
*i d3er r ) ;
voi d d3r r a ( char *cd3at t , i nt *i d3ni n, f l oat
*r d3r a,
voi d d3r r ea ( char *cd3at t , f l oat *r d3r ea, i nt
*i d3er r ) ;
voi d d3r r ef ( char *cd3at t , PDMS_NAME cd3r ef , i nt
*i d3er r ) ;
voi d d3r r f a ( char *cd3at t , i nt *i d3ni n, PDMS_NAME
cd3r f a[ ] ,
voi d d3r t ex ( char *cd3at t , PDMS_TEXT cd3t ex, i nt
*i d3er r ) ;
voi d d3r t yp ( PDMS_WORD cd3t yp, i nt *i d3er r ) ;
voi d d3r uda ( char *cd3t yp, i nt *i d3max, PDMS_UDNA
cd3nms[ ] ,
i nt *i d3abv, PDMS_WORD
cd3at p[ ] , i nt *i d3num,
i nt *i d3er r ) ;
voi d d3r uni ( char *cd3at t , PDMS_UUNI cd3unt , i nt
*i d3er r ) ;
voi d d3r wa ( char *cd3at t , i nt *i d3ni n, PDMS_WORD
cd3wa[ ] ,
voi d d3r wor ( char *cd3at t , PDMS_WORD cd3wor , i nt
*i d3er r ) ;
i nt d3ucl u ( i nt *i d3uni ) ;
/ *
cd3st r
*/
i nt d3uct i ( char *cd3st r , i nt *i d3i nt , char
*cd3bef ,
) ;
/ *
User Guide
Version 11.6
C/C++ Library
cd3st r
*/
i nt d3uct r ( char *cd3st r , f l oat *r d3val , char
*cd3bef ,
) ;
voi d d3udeh ( i nt *i d3i nt , PDMS_WORD cd3wor ) ;
voi d d3udt m ( i nt *i d3dat , DARS_RDAT cd3dat ) ;
i nt d3ugt u ( i nt *i d3uni ) ;
voi d d3ui ni ( i nt *r eady ) ;
i nt d3ul ds ( char *cd3dat , i nt *i d3er r ) ;
i nt d3ul en ( char *cd3st r ) ;
voi d d3umon ( char *cd3mon ) ;

#endi f / * __cpl uspl us */

#endi f

pdms.h:

pdms.h is the header file that defines constants and variable types used
and recommended for use in Application programs.

/ *
** pdms. h
**
** Header f i l e t o def i ne some syst emconst ant s.
**
** Not es:
** 1. St r i ngs ar e def i ned as bei ng 1 mor e t han
i n FORTRAN
** t o account f or t he C st r i ng t er mi nat or ' \ 0' .
**
*/
User Guide
Version 11.6
C/C++ Library

#i f ndef PDMS_H
#def i ne PDMS_H

/ * Some const ant s */
#def i ne TRUE 1
#def i ne FALSE 0

#def i ne PDMS_NAME_LEN 50
#def i ne PDMS_UDNA_NAME_LEN 13
#def i ne PDMS_WORD_LEN 6
#def i ne PDMS_TEXT_LEN 120
#def i ne PDMS_RPTX_TEXT_LEN 20
#def i ne PDMS_UUNI _TEXT_LEN 20
#def i ne DARS_MESS_TEXT_LEN 50
#def i ne DARS_RDAT_TEXT_LEN 20
#def i ne DARS_CERR_TEXT_LEN 3
#def i ne PDMS_DBNAME_LEN 64

t ypedef char PDMS_NAME [ PDMS_NAME_LEN + 1 ] ;
t ypedef char PDMS_WORD [ PDMS_WORD_LEN + 1 ] ;
t ypedef char PDMS_TEXT [ PDMS_TEXT_LEN + 1 ] ;
t ypedef char PDMS_RPTX [ PDMS_RPTX_TEXT_LEN + 1 ] ;
t ypedef char PDMS_UDNA [ PDMS_UDNA_NAME_LEN + 1 ] ;
t ypedef char PDMS_UUNI [ PDMS_UUNI _TEXT_LEN + 1 ] ;
t ypedef char DARS_MESS [ DARS_MESS_TEXT_LEN + 1 ] ;
t ypedef char DARS_RDAT [ DARS_RDAT_TEXT_LEN + 1 ] ;
t ypedef char DARS_CERR [ DARS_CERR_TEXT_LEN + 1 ] ;
t ypedef char PDMS_DBNAME [ PDMS_DBNAME_LEN + 1 ] ;
t ypedef i nt LOGI CAL ;

User Guide
Version 11.6
C/C++ Library
#endi f
F.7 Example 'C' Program
The 'C' source of this program (FORTRAN source of a similar program is
in Section 4.2) is as follows:

#i ncl ude <st di o. h>
#i ncl ude <st dl i b. h>
#i ncl ude <st r i ng. h>

#i ncl ude " d3l i bc. h"

voi d mai n ( i nt ar gc, char **ar gv)
{
/ *
** Mai n c t est pr ogr am
*/

#def i ne PARAM_ARRAY_LEN 100

PDMS_NAME spcr ef , cat r ef ;
PDMS_WORD cd3wor , wor ds [ PARAM_ARRAY_LEN ] ;
LOGI CAL l val ;
DARS_MESS cd3msg ;
PDMS_TEXT cd3t ex, cd3bef , cd3af t ;
DARS_CERR cd3er r ;
DARS_RDAT cd3dat ;
f l oat par ams [ PARAM_ARRAY_LEN ] ;
i nt i d3er r , i d3nou, i , i val , i l en, i d3dat [ 6
] , i par am;

/ * Pr oj ect ent r y */
d3i ni t ( " DAR" , " SYSTEM" , " XXXXXX" , " FULL" , " " ,
&i d3er r ) ;
User Guide
Version 11.6
C/C++ Library
i f ( i d3er r ! = 0 ) got o f i ni sh ;

/ * Get pr oj ect det ai l s */
/ * Use f pr i nt f t o check t hat wr i t i ng t o st dout wor ks */
d3umon ( " NONE" ) ;
d3r pr j ( " code" , cd3t ex, &i d3er r ) ;
f pr i nt f ( st dout , " Pr oj ect Code: %s\ n" , cd3t ex )
;
d3r pr j ( " name" , cd3t ex, &i d3er r ) ;
f pr i nt f ( st dout , " Pr oj ect Name: %s\ n" , cd3t ex )
;
d3r pr j ( " numb" , cd3t ex, &i d3er r ) ;
f pr i nt f ( st dout , " Pr oj ect Number : %s\ n" , cd3t ex
) ;
d3r pr j ( " mess" , cd3t ex, &i d3er r ) ;
f pr i nt f ( st dout , " Pr oj ect Message: %s\ n" ,
cd3t ex ) ;

/ * Ret ur n st r i ng l engt h */
i l en = d3ul en ( cd3t ex ) ;
pr i nt f ( " Lengt h of %s - > %d\ n" , cd3t ex, i l en )
;

/ * Get dat e */
d3udt m( i d3dat , cd3dat ) ;
pr i nt f ( " Dat e i s: %s or . . . " , cd3dat ) ;
f or ( i = 0; i < 6; i ++ ) pr i nt f ( " %d" ,
i d3dat [ i ] ) ;
pr i nt f ( " \ n" ) ;

/ * Ext r act i nt eger */
st r cpy ( cd3t ex, " abcd12345XYZ" ) ;
l val = d3uct i ( cd3t ex, &i val , cd3bef , cd3af t ,
cd3er r ) ;
i f ( l val ! = 0 )
{
User Guide
Version 11.6
C/C++ Library
pr i nt f ( " For st r i ng: %s\ n" , cd3t ex ) ;
pr i nt f ( " Ret ur ned i nt eger %d\ n" , i val )
;
}
el se
{
pr i nt f ( " For st r i ng: %s" , cd3t ex ) ;
pr i nt f ( " , r et ur ned er r or %s\ n" ,
cd3er r ) ;
i f ( ! st r cmp ( cd3er r , " ADD" ) )
{
pr i nt f ( " Ret ur ned i nt eger
%d\ n" , i val ) ;
pr i nt f ( " St r i ng bef or e: %s\ n" ,
cd3bef ) ;
pr i nt f ( " St r i ng af t er : %s\ n" ,
cd3af t ) ;
}
}

st r cpy ( cd3t ex, " abcdXYZ" ) ;
l val = d3uct i ( cd3t ex, &i val , cd3bef , cd3af t ,
cd3er r ) ;
i f ( l val ! = 0 )
{
pr i nt f ( " For st r i ng: %s\ n" , cd3t ex ) ;
pr i nt f ( " Ret ur ned i nt eger %d\ n" , i val )
;
}
el se
{
pr i nt f ( " For st r i ng: %s" , cd3t ex ) ;
pr i nt f ( " , r et ur ned er r or %s\ n" ,
cd3er r ) ;
i f ( ! st r cmp ( cd3er r , " ADD" ) )
{
User Guide
Version 11.6
C/C++ Library
pr i nt f ( " Ret ur ned i nt eger
%d\ n" , i val ) ;
pr i nt f ( " St r i ng bef or e: %s\ n" ,
cd3bef ) ;
pr i nt f ( " St r i ng af t er : %s\ n" ,
cd3af t ) ;
}
}

/ * Sel ect MDB */
d3umon ( " FULL" ) ;
d3mmdb ( " DESI GN/ PLANT" , " " , &i d3er r ) ;
i f ( i d3er r ! = 0 ) got o f i ni sh ;

/ * Get dat est amp */
d3r dat ( i d3dat , cd3dat , &i d3er r ) ;
pr i nt f ( " Dat est amp i s: %s\ nor . . . " , cd3dat ) ;
f or ( i = 0; i < 6; i ++ ) pr i nt f ( " %d" ,
i d3dat [ i ] ) ;
pr i nt f ( " \ n" ) ;

/ * Move t o a pi pe component */
d3mnam( " / 100- B- 1" , &i d3er r ) ;
i val = 1 ;
d3mnum( " BRAN" , &i val , &i d3er r ) ;
d3mr el ( " LAST" , " FLAN" , &i d3er r ) ;

/ * Get spec r ef and got o i t */
d3r nam( " SPRE" , spcr ef , &i d3er r ) ;
pr i nt f ( " spcr ef i s: %s\ n" , spcr ef ) ;
d3mnam( spcr ef , &i d3er r ) ;

/ * Get cat r ef and got o i t */
d3r nam( " CATR" , cat r ef , &i d3er r ) ;
d3mnam( cat r ef , &i d3er r ) ;
User Guide
Version 11.6
C/C++ Library

/ * Get par amet er s of component and dehash conn t ypes */
/ * Cancel moni t or and const r uct own PRI NT st at ement s */
put s ( " Get t i ng el ement s wi t h D3RRA" ) ;
i val = PARAM_ARRAY_LEN ;
d3r r a ( " PARA" , &i val , par ams, &i d3nou, &i d3er r
) ;
pr i nt f ( " Number of el ement s f ound: %d\ n" ,
i d3nou ) ;

f or ( i = 0; i < i d3nou; i ++ )
{
st r cpy ( cd3wor , " \ 0" ) ;
/ * I f possi bl y a wor d, dehash */
i f ( par ams [ i ] >= 531442. 0 )
{
i par am= par ams[ i ] ;
d3udeh ( &i par am, cd3wor ) ;
}
i f ( st r l en ( cd3wor ) == 0 )
/ * Not a wor d; pr i nt r eal val ue
*/
pr i nt f ( " El ement %d: %f \ n" ,
i +1, par ams [ i ] ) ;
el se
/ * Val i d wor d; pr i nt wor d */
pr i nt f ( " El ement %d: %s\ n" ,
i +1, cd3wor ) ;
}

/ * Al t er nat i vel y, use D3RWA di r ect l y ( non- wor ds don" t
gi ve er r or ) */
put s ( " Get t i ng el ement s wi t h D3RWA" ) ;
i val = PARAM_ARRAY_LEN ;
User Guide
Version 11.6
C/C++ Library
d3r wa ( " WPAR" , &i val , wor ds, &i d3nou, &i d3er r )
;
f or ( i = 0; i < i d3nou; i ++ )
{
i f ( st r l en ( wor ds [ i ] ) ! = 0 )
pr i nt f ( " El ement %d: %s\ n" ,
i +1, wor ds [ i ] ) ;
}

f i ni sh: ;

/ * Cancel moni t or and out put message */
l val = FALSE ;
d3emsg ( &i d3er r , &l val , cd3msg ) ;
pr i nt f ( " %s\ n" , cd3msg ) ;

/ * Exi t pr oj ect */
d3f i n ( &i d3er r ) ;

/ * Exi t DARs */
d3f end ( ) ;
r et ur n ;
}

The expected output from this program is as follows. There may some
differences in the precision and format of variables. Some of the output
is printed by the FORTRAN DARs interface (with monitoring) and some
is printed by the 'C' program.

VANTAGE PDMS DARs C I nt er f ace Mk11. 6. 0. 0 ( WI NDOWS- NT
5. 0) ( 7 Sep 2004 : 23: 36)

Thi s ver si on of PDMS was i ssued t o <your company>
and wi l l onl y oper at e on r egi st er ed har dwar e
User Guide
Version 11.6
C/C++ Library

VANTAGE PDMS DARs Mk11. 6. 0. 0 ( WI NDOWS- NT 5. 0) ( 7 Sep
2004 : 23: 36)
( c) Copyr i ght 1974 t o 2004 AVEVA Sol ut i ons Li mi t ed
I ssued t o <your company>

I nput ar gument s:
Pr oj ect name DAR
User name SYSTEM
Passwor d XXXXXX
Read/ Wr i t e key
Er r or code 0
I nput ar gument s:
Ent er i ng subr out i ne D3MMDB
I nput ar gument s:
MDB name DESI GN/ PLANT
Read/ Wr i t e key
Exi t i ng subr out i ne D3MMDB
Er r or code 0
Ent er i ng subr out i ne D3RDAT
Exi t i ng subr out i ne D3RDAT
Dat e- st amp 04 J ul 2000 17: 56: 24
Year , Mont h, Day 2000 7 4
Hour , Mi nut e, Second 17 56 24
Er r or code 0
User Guide
Version 11.6
C/C++ Library
I nput ar gument s:
El ement name/ r ef / 100- B- 1
Er r or code 0
Ent er i ng subr out i ne D3MNUM
I nput ar gument s:
El ement t ype BRAN
Li st posi t i on 1
Exi t i ng subr out i ne D3MNUM
Er r or code 0
Ent er i ng subr out i ne D3MREL
I nput ar gument s:
Rel at i ve posi t i on LAST
El ement t ype FLAN
Exi t i ng subr out i ne D3MREL
Er r or code 0
I nput ar gument s:
At t r i but e r equi r ed SPRE
Name/ Ref er ence / A3B/ 100F1
Er r or code 0
I nput ar gument s:
El ement name/ r ef / A3B/ 100F1
Er r or code 0
User Guide
Version 11.6
C/C++ Library
I nput ar gument s:
At t r i but e r equi r ed CATR
Name/ Ref er ence / FUAAPAMM
Er r or code 0
I nput ar gument s:
El ement name/ r ef / FUAAPAMM
Er r or code 0
I nput ar gument s:
F.8 'C/C++' Interface Principles
The 'C/C++' subroutine names are the same as those used for the
FORTRAN subroutines (but lower case). For example, d3init for
D3INIT.
The 'C/C++' routine arguments are analogous to the FORTRAN
arguments. One of the differences between FORTRAN and 'C/C++' is
that 'C/C++' strings do not intrinsically carry their declared length when
passed as arguments. The interface has been designed so that the
programmer does not need to pass additional string lengths as
arguments. However, the programmer is assumed to know the
maximum length of each return string argument and to have declared it
as such.
The programmer should refer to the d3libc.h and pdms.h header files
printed above (Section 0). These define the format of each DARs routine
call, including definitions of all returned string lengths
(e.g. PDMS_TEXT_LEN). The example program illustrates how the
routines should be called.
All arguments are passed by address. This means that all integer and
logical input arguments must be passed through a variable address
(e.g. &ival). This is to ease the use of these functions: the programmer
User Guide
Version 11.6
C/C++ Library
doesn't have to remember which arguments are passed by address and
which are passed by value.
One of the effects of 'C/C++' string behaviour is that the DARs error
code 5 (character string output argument too short) cannot be returned if
a DARs routine is called from a 'C/C++' program. If the supplied string
is too short, the returned string will overrun the declared string and may
corrupt other variables (or it may have no noticeable effect).

As an example, the cd3tex argument of d3rprj is defined as
PDMS_TEXT. The interface defines PDMS_TEXT_LEN as 120. The
'C/C++' program should therefore declare this argument as
PDMS_TEXT cd3tex. If instead it is defined, say, as char cd3tex[2],
corruption may occur. No problem would occur if the string is declared to
be longer than necessary.
In the case of d3ucti and d3uctr, the two return arguments cd3bef and
cd3aft must be declared at least as long as the significant length of the
input argument cd3str.
F.9 Use of System Calls in DARs Programs
The FlexLM-based security system used in Aveva products may have
some implications for the use of system calls in DARs programs.
The FlexLM system features the use of certain system interrupt signals
which may interfere with software into which FlexLM is built.
DARs programmers should check whether system calls are used in any
existing DARs applications and, for each system call:
If the manual pages for the system call state that the call can generate a
EINTR error, then code must be added around the call to restart it if
interrupted:

e.g. f d = open ( f r ed, 2) ;

becomes

whi l e ( ( f d = open ( f r ed, 2) ) < 0 && er r no ==
EI NTR) ;

User Guide
Version 11.6
C/C++ Library
The number of affected system calls is too large to list and also varies
between hardware platforms
User Guide
Version 11.6

Data Access Routines User Guide

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Data Access Routines User Guide

Încărcat de

Drepturi de autor:

Formate disponibile

Data Access Routines

S-ar putea să vă placă și