Data Access Routines
User Guide
AVEVA Solutions Ltd
Disclaimer
Information of a technical nature, and particulars of the product and its use, is given by AVEVA
Solutions Ltd and its subsidiaries without warranty. AVEVA Solutions Ltd and its subsidiaries disclaim
any and all warranties and conditions, expressed or implied, to the fullest extent permitted by law.
Neither the author nor AVEVA Solutions Ltd, or any of its subsidiaries, shall be liable to any person or
entity for any actions, claims, loss or damage arising from the use or possession of any information,
particulars, or errors in this publication, or any incorrect use of the product, whatsoever.
Copyright
Copyright and all other intellectual property rights in this manual and the associated software, and every
part of it (including source code, object code, any data contained in it, the manual and any other
documentation supplied with it) belongs to AVEVA Solutions Ltd or its subsidiaries.
All other rights are reserved to AVEVA Solutions Ltd and its subsidiaries. The information contained in
this document is commercially sensitive, and shall not be copied, reproduced, stored in a retrieval
system, or transmitted without the prior written permission of AVEVA Solutions Ltd. Where such
permission is granted, it expressly requires that this Disclaimer and Copyright notice is prominently
displayed at the beginning of every copy that is made.
The manual and associated documentation may not be adapted, reproduced, or copied, in any material
or electronic form, without the prior written permission of AVEVA Solutions Ltd. The user may also not
reverse engineer, decompile, copy, or adapt the associated software. Neither the whole, nor part of the
product described in this publication may be incorporated into any third-party software, product,
machine, or system without the prior written permission of AVEVA Solutions Ltd, save as permitted by
law. Any such unauthorised action is strictly prohibited, and may give rise to civil liabilities and criminal
prosecution.
The AVEVA products described in this guide are to be installed and operated strictly in accordance with
the terms and conditions of the respective license agreements, and in accordance with the relevant
User Documentation. Unauthorised or unlicensed use of the product is strictly prohibited.
First published September 2007
© AVEVA Solutions Ltd, and its subsidiaries
AVEVA Solutions Ltd, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom
Trademarks
AVEVA and Tribon are registered trademarks of AVEVA Solutions Ltd or its subsidiaries. Unauthorised
use of the AVEVA or Tribon trademarks is strictly forbidden.
AVEVA product names are trademarks or registered trademarks of AVEVA Solutions Ltd or its
subsidiaries, registered in the UK, Europe and other countries (worldwide).
The copyright, trade mark rights, or other intellectual property rights in any other product, its name or
logo belongs to its respective owner.
Data Access Routines User Guide
Data Access Routines User Guide
Contents
Page
Data Access Routines
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1
Scope of Data Access Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1
Who Can Use Data Access Routines? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1
Interfacing to 'C/C++' Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2
How To Use This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2
Use of Other PDMS Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2
Programming Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1
FORTRAN 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1
Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1
CHARACTER Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:2
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3
Basic Concepts of PDMS Data Access . . . . . . . . . . . . . . . . . . . . . . . 3:1
PDMS Database Organisation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
PDMS Database Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
Current Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
User-Defined Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
Dynamic Array Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
Monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2
Site File
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2
i
12.0
Data Access Routines User Guide
Multibyte Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2
Use of Data Access Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:8
Subroutine Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:1
Subroutine Summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:1
Initialisation Routines, D3Ixxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigation Routines, D3Mxxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Read Routines, D3Rxxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Handling Routines, D3Exxx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Utility Routines, D3Uxxx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Termination Routines, D3Fxxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Utility Routines, D3Uxxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5:1
5:1
5:2
5:4
5:4
5:5
5:5
Detailed Subroutine Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:5
Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:1
DARs Version Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:1
Compatibility of Databases and DARs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:1
Determination of Version Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:1
DARs Library Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1
Software Issued with DARs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1
File Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2
Application Program Compilation and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . A:3
Program Running and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:4
Acceptance Test Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:4
Re-Linking Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5
Running Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B:1
Error Codes and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C:1
Auxiliary Subroutine Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .D:1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D:1
List of Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D:2
ii
12.0
Data Access Routines User Guide
Subroutine Outline Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D:3
Multibyte Text Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .E:1
‘C/C++’ Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:1
Software Issued with DARs ‘C/C++’ Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:1
Application Program Compilation and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . F:1
Program Running and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:1
Acceptance Test Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:1
Compilation and Linking Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:2
'C/C++' Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:2
Example 'C' Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:10
'C/C++' Interface Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F:15
iii
12.0
Data Access Routines User Guide
iv
12.0
Data Access Routines User Guide
Introduction
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.
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:1
12.0
Data Access Routines User Guide
Introduction
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 ‘C/C++’ Library 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.
The section Use of Data Access Routines 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 Running
Examples for each of the supported machine types. More detailed machine-specific
information is presented in appendices Error Codes and Messages, Running Examples and
‘C/C++’ Library, together with details of the 'C/C++' interface.
The section Subroutine Specifications 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 detailed definitions of all arguments and lists the
possible error conditions that can arise.
The section Version Control gives details of version control mechanisms.
Appendix Error Codes and Messages provides a list of error messages for easy reference.
Appendix Auxiliary Subroutine Library 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
The Data Model Reference Manual gives details of PDMS elements and their attributes. A
comprehensive list of all PDMS attributes and pseudo-attributes is given in the Software
Customisation Reference Manual.
1:2
12.0
Data Access Routines User Guide
Programming Techniques
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.
Character and logical arguments must be explicitly declared in calling routines.
The following naming convention has been adopted in the subroutine specifications:
CHARACTER
CD3xxx
INTEGER
ID3xxx
REAL
RD3xxx
LOGICAL
LD3xxx
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.
INTEGER
ID3XYZ(*)
CHARACTER*(*)
CD3XYZ
2:1
12.0
Data Access Routines User Guide
Programming Techniques
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:
INTEGER
D3ULEN
LOGICAL
D3UCTI
LOGICAL
D3UCTR
LOGICAL
D3UGTU
LOGICAL
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').
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
will not be.
' is interpreted the same as 'ABC', the string '
2:2
ABC'
12.0
Data Access Routines User Guide
Programming Techniques
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
INTEGER
D3xxxx, D3ULEN
D3ULEN, NC
CHARACTER*10 CD3XYZ
CALL D3xxxx(.........,CD3XYZ,.....)
PRINT *, CD3XYZ(1:D3ULEN(CD3XYZ)), ' returned'
or
NC = D3ULEN(CD3XYZ)
PRINT *, CD3XYZ(1:NC), ' returned'
would print
ABC returned
rather than
ABC
returned
This could be embellished by constructions such as:
IF (D3ULEN(CD3XYZ).EQ.0) THEN
PRINT *, 'blank string returned'
ELSE
.....
ENDIF
2.4
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 Error Codes and Messages.
2:3
12.0
Data Access Routines User Guide
Programming Techniques
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.
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 to first member
CALL D3MREL( 'FIRS', 'MEMB', ID3ERR )
20
CONTINUE
IF ( ID3ERR .EQ. 0 ) THEN
NMEMB = NMEMB + 1
C
Read type
CALL D3RTYP( CD3TEX, ID3ERR )
IF ( ID3ERR .NE. 0 ) GOTO 12345
CD3TYP(NMEMB) = CD3TEX
C
Read name/reference
CALL D3RNAM( 'NAME', CD3TEX, ID3ERR )
IF ( ID3ERR .NE. 0 ) GOTO 12345
CD3NAM(NMEMB) = CD3TEX
ELSE
C
Reset internal error flag if No Members or List
Exhausted
C
Return zero ID3ERR value
IF ( ID3ERR .NE. 202 .AND. ID3ERR .NE. 203 )
GOTO 12345
CALL D3ERST
ID3ERR = 0
GOTO 100
ENDIF
2:4
12.0
Data Access Routines User Guide
Programming Techniques
C
Check if reached end of User's arrays
IF ( NMEMB .EQ. ID3NIN ) GOTO 100
C
Move to next member of current list
CALL D3MREL( 'NEXT', 'ELEM', ID3ERR )
GOTO 20
C
End of list
100
CONTINUE
.
.
12345
CONTINUE
CALL D3EMSG(ID3ERR,.TRUE.,CMESS)
PRINT*, 'Error in subroutine ABC, please report to
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.
2:5
12.0
Data Access Routines User Guide
Programming Techniques
2:6
12.0
Data Access Routines User Guide
Basic Concepts of PDMS Data Access
3
Basic Concepts of PDMS Data Access
3.1
PDMS Database Organisation
The Administrator User Guide provides an overview of 'The PDMS Databases' 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.
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
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'.
3:1
12.0
Data Access Routines User Guide
Basic Concepts of PDMS Data Access
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.
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 Multibyte Text
Handling.
3:2
12.0
Data Access Routines User Guide
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
Application main program
C
Essential type declarations
CHARACTER*50
C
SPCREF, CATREF
Can declare CD3MSG CHAR*1 if not using it
CHARACTER*1
CD3MSG
CHARACTER*6
CD3WOR, WORDS(100)
REAL PARAMS(100)
C
Optional EXTERNAL declarations
4:1
12.0
Data Access Routines User Guide
Use of Data Access Routines
EXTERNAL D3INIT, D3MMDB, D3MNAM, D3MNUM, D3MREL,
D3RNAM
EXTERNAL D3RRA,
D3UMON, D3UDEH
C
D3RWA,
D3EMSG, D3FIN,
D3FEND,
Optional type declarations
INTEGER
ID3ERR, ID3NOU, I
INTRINSIC
INT
C
C
Project entry
CALL D3INIT( 'DAR', 'SYSTEM', 'XXXXXX', 'FULL',
' ', ID3ERR )
IF ( ID3ERR .NE. 0 ) GOTO 12345
C
Select MDB
CALL D3MMDB( 'DESIGN/PLANT', ' ', ID3ERR )
IF ( ID3ERR .NE. 0 ) GOTO 12345
C
Move to a pipe component
CALL D3MNAM( '/100-B-1', ID3ERR )
CALL D3MNUM( 'BRAN', 1, ID3ERR )
CALL D3MREL( 'LAST', 'FLAN', ID3ERR )
C
Get spec ref and goto it
CALL D3RNAM( 'SPRE', SPCREF, ID3ERR )
CALL D3MNAM( SPCREF, ID3ERR )
C
Get cat ref and goto it
CALL D3RNAM( 'CATR', CATREF, ID3ERR )
CALL D3MNAM( CATREF, ID3ERR )
C
Get parameters of component and dehash conn types
C
Cancel monitor and construct own PRINT statements
CALL D3UMON('NONE')
PRINT*,'Getting elements with D3RRA'
CALL D3RRA( 'PARA', 100, PARAMS, ID3NOU, ID3ERR
)
PRINT*,'Number of elements found:',ID3NOU
4:2
12.0
Data Access Routines User Guide
Use of Data Access Routines
DO 100 I=1, ID3NOU
CD3WOR = ' '
C
If possibly a word, dehash
IF ( PARAMS(I) .GE. 531442. ) THEN
CALL D3UDEH( INT(PARAMS(I)), CD3WOR )
ENDIF
IF (CD3WOR.EQ.' ') THEN
C
Not a word; print real value
PRINT*,'Element', I, PARAMS(I)
ELSE
C
Valid word; print word
PRINT*,'Element', I, '
', CD3WOR
ENDIF
100
CONTINUE
C
Alternatively, use D3RWA directly (non-words don't
give error)
PRINT*,'Getting elements with D3RWA'
CALL D3RWA( 'WPAR', 100, WORDS, ID3NOU, ID3ERR )
DO 200 I=1, ID3NOU
IF (WORDS(I).NE.' ') PRINT*, 'Element', I, '
', WORDS(I)
200
CONTINUE
C
12345
CONTINUE
C
Cancel monitor and output message
CALL D3UMON('NONE')
CALL D3EMSG( ID3ERR, .TRUE., CD3MSG )
C
Exit project
CALL D3FIN( ID3ERR )
C
Exit DARs
4:3
12.0
Data Access Routines User Guide
Use of Data Access Routines
CALL D3FEND
END
Compilation, loading and running instructions are detailed in Running Examples.
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 <version details>
<copyright statement>
<site data>
Entering subroutine D3INIT
Input arguments:
Project name
DAR
Username
SYSTEM
Password
XXXXXX
Monitoring level
FULL
Read/Write key
Exiting subroutine D3INIT
Output arguments:
Error code
108
Project not found
Project not found
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:
PDMS DARs <version details>
<copyright statement>
<site data>
Project not found
4:4
12.0
Data Access Routines User Guide
Use of Data Access Routines
A second possible error situation, where the MDB does not exist, gives the following output,
with monitor level in D3INIT set to 'FULL':
PDMS DARs <version details>
<copyright statement>
<site data>
Entering subroutine D3INIT
Input arguments:
Project name
DAR
Username
SYSTEM
Password
XXXXXX
Monitoring level
FULL
Read/Write key
Exiting subroutine D3INIT
Output arguments:
Error code
0
Entering subroutine D3MMDB
Input arguments:
MDB name
DESIGN/PLANT
Read/Write key
Opening databases
Mode
Type
Name
----
----
----
Read
DESI
STRUC/S
Read
DESI
PIPE/MAXDBLENGTH31AFTERTHESLASH
Read
CATA
CATAL/C
Read
PROP
PIPE/PROP
4:5
12.0
Data Access Routines User Guide
Use of Data Access Routines
Read
DESI
PIPE/DR
Read
DICT
PIPE/DR
Default database type: DESI
Exiting subroutine D3MMDB
Output arguments:
Error code
0
Entering subroutine D3MNAM
Input arguments:
Element name/ref
/100-B-1
Exiting subroutine D3MNAM
Output arguments:
Error code
0
Entering subroutine D3MNUM
Input arguments:
Element type
BRAN
List position
1
Exiting subroutine D3MNUM
Output arguments:
Error code
0
Entering subroutine D3MREL
Input arguments:
Relative position
LAST
Element type
FLAN
Exiting subroutine D3MREL
Output arguments:
Error code
0
Entering subroutine D3RNAM
Input arguments:
Attribute required
4:6
SPRE
12.0
Data Access Routines User Guide
Use of Data Access Routines
Exiting subroutine D3RNAM
Output arguments:
Name/Reference
/A3B/100F1
Error code
0
Entering subroutine D3MNAM
Input arguments:
Element name/ref
/A3B/100F1
Exiting subroutine D3MNAM
Output arguments:
Error code
0
Entering subroutine D3RNAM
Input arguments:
Attribute required
CATR
Exiting subroutine D3RNAM
Output arguments:
Name/Reference
/FUAAPAMM
Error code
0
Entering subroutine D3MNAM
Input arguments:
Element name/ref
/FUAAPAMM
Exiting subroutine D3MNAM
Output arguments:
Error code
0
Entering subroutine D3UMON
Input arguments:
Monitoring level
NONE
Getting elements with D3RRA
Number of elements found:
Element
1
100.0000
Element
2
254.0000
4:7
12.0
Data Access Routines User Guide
Use of Data Access Routines
Element
3
31.80000
Element
4
54.10000
Element
5
25.00000
Element
6
114.3000
Element
7
BWD
Element
8
FGD
Getting elements with D3RWA
Element
7
BWD
Element
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 those routines (provided in
source form; see Auxiliary Subroutine Library) may be studied in conjunction with the bare
application code:
C------------------PROGRAM EXMPL2
C------------------LOGICAL
C
PROJIN, MDBIN
Optional declarations
INTEGER
IFINDM
EXTERNAL
PROJIN, MDBIN, DECCHK, D3FIN, D3FEND
IFINDM = 0
C
Project entry
IF ( .NOT. PROJIN() ) GOTO 12345
C
MDB selection
IF ( .NOT. MDBIN() ) GOTO 12345
C
Design db test
CALL DECCHK
4:8
12.0
Data Access Routines User Guide
Use of Data Access Routines
C
Exit
12345 CONTINUE
CALL D3FIN( IFINDM )
CALL D3FEND
END
C-----------------------------LOGICAL FUNCTION PROJIN()
C-----------------------------CHARACTER*1
C
TEXT
Optional declarations
INTEGER
IERR
EXTERNAL
D3INIT, D3EMSG
PRINT*, 'Enter project'
CALL D3INIT( 'DAR', 'SYSTEM', 'XXXXXX', 'NONE', ' ',
IERR
PROJIN = IERR.EQ.0
CALL D3EMSG( IERR, .TRUE., TEXT )
RETURN
END
C----------------------------LOGICAL FUNCTION MDBIN()
C----------------------------CHARACTER*50
C
TEXT
Optional declarations
INTEGER
IERR
EXTERNAL
D3MMDB, D3EMSG
PRINT*, 'Select MDB'
4:9
12.0
Data Access Routines User Guide
Use of Data Access Routines
CALL D3MMDB( '/PLANT', ' ', IERR )
MDBIN = IERR.EQ.0
CALL D3EMSG( IERR, .TRUE., TEXT )
RETURN
END
C---------------------SUBROUTINE DECCHK
C----------------------
C
CHARACTER*50
TEXT, NAMES(100)
CHARACTER*6
TYPES(100),
LNTP
LOGICAL
LOCK, BUIL, LHEA, LTAI, DETA, SHOP,
LSTR
LOGICAL
ORIL, POSI, LOFF
CHARACTER*50
NAME, OWNE, MATR
CHARACTER*50
FLUR, CASR, PSPE, ISPE, TSPE
CHARACTER*50
HSTU, HREF, TREF, SPRE, CATR, LSTU,
CREF
CHARACTER*120
DUTY, DSCO, PTSP, INSC, FUNC
INTEGER
REV , EREC, CCEN, CCLA, SAFC
INTEGER
LEVE(2), OBST, ARRI
INTEGER
D3XLEN
REAL
HPOS(3),
POS(9)
REAL
ORI(3), ANGL
TYPE,
HDIR(3),
HCON,
TCON,
TPOS(3),
FLOW,
TDIR(3),
Optional declarations
INTEGER
ISIZ, IERR, LEAV, IDISP
REAL
XLEN, YLEN, ZLEN, HEIG, RADI
REAL
BORE, HBOR, TBOR, TEMP, PRES
EXTERNAL
D3MNAM,
D3MNUM,
D3MREL, D3RORL
4:10
D3UMON,
D3RPAT,
12.0
Data Access Routines User Guide
Use of Data Access Routines
EXTERNAL
D3RPRL, D3EMSG
EXTERNAL
D3QMEM,
D3QSIT,
D3QPIP, D3QBRA
D3XLEN,
D3QZON,
EXTERNAL
D3QTEE,
D3QELB,
D3QNOZ, D3MMDB
D3QEQU,
D3QBOX,
PRINT*, ' '
PRINT*, 'Design Database Example'
PRINT*, '-----------------------'
PRINT*, ' '
IDISP
2
=
PRINT*, 'Select default db type'
CALL D3MMDB( 'DESIGN/PLANT', ' ', IERR )
IF ( IERR .NE. 0 ) THEN
PRINT*, 'Should have succeeded'
PRINT*, 'Instead error is:'
GOTO 12345
ENDIF
C
Look at world
CALL D3QMEM( IDISP, 100, TYPES, NAMES, ISIZ, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
C
Look at site
CALL D3MNAM( '/EQU', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QMEM( IDISP, 100, TYPES, NAMES, ISIZ, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
CALL D3QSIT( IDISP, TYPE, NAME, OWNE, LOCK, POS, ORI,
IERR )
4:11
12.0
Data Access Routines User Guide
Use of Data Access Routines
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
IF ( NAME .NE. '/EQU' ) THEN
PRINT*, 'Expecting name /EQU got ', NAME(:D3XLEN(NAME))
GOTO 12345
ENDIF
C
Look at zone
CALL D3MNUM( 'zone', 3, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QMEM( IDISP, 100, TYPES, NAMES, ISIZ, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
CALL D3QZON( IDISP, TYPE, NAME, OWNE, LOCK, POS, ORI,
PSPE,
+
ISPE, TSPE, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
IF ( NAME .NE. '/EQ3' ) THEN
PRINT*,
'Expecting
NAME(:D3XLEN(NAME))
name
/EQU
got
',
GOTO 12345
ENDIF
PRINT*, ' '
C
Pipe details
CALL D3MNAM( '/250-B-5', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QMEM( IDISP, 100, TYPES, NAMES, ISIZ, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
CALL D3QPIP( IDISP, TYPE, NAME, OWNE, LOCK, BUIL, SHOP,
+
BORE, TEMP, PRES, PSPE, ISPE, TSPE, MATR,
4:12
12.0
Data Access Routines User Guide
Use of Data Access Routines
+
FLUR, CASR, CCEN, CCLA, DUTY, LNTP, EREC,
+
REV,
DSCO, PTSP, INSC, SAFC, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
IF ( NAME .NE. '/250-B-5' ) THEN
PRINT*,'Expecting
name
NAME(:D3XLEN(NAME))
/250-B-5
got
',
GOTO 12345
ENDIF
C
Branch details
CALL D3MNUM( 'BRAN', 1, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QMEM( IDISP, 100, TYPES, NAMES, ISIZ, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
CALL D3QBRA( IDISP, 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, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
IF ( NAME .NE. '/250-B-5/1' ) THEN
PRINT*,'Expecting
name
',NAME(:D3XLEN(NAME))
/250-B-5/1
got
GOTO 12345
ENDIF
C
Branch PPoints with Monitoring
CALL D3UMON( 'FULL' )
CALL D3RPAT( 'PH', '/EQ3', POS(1), POS(4), BORE, HCON,
IERR )
4:13
12.0
Data Access Routines User Guide
Use of Data Access Routines
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3RPAT('ptail','worl',POS(1), POS(4), BORE, HCON,
IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3UMON( 'NONE' )
C
Tee details
CALL D3MREL( 'FIRS', 'TEE', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QTEE( IDISP, TYPE, NAME, OWNE, LOCK, POS , ORI ,
+
SPRE, LSTU, CREF, ARRI, LEAV, ANGL, HEIG,
+
RADI, BUIL, SHOP, ORIL, POSI, LOFF, ISPE,
+
TSPE, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
C
Elbow details
CALL D3MREL( 'PREV', 'ELBOW', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QELB( IDISP, TYPE, NAME, OWNE, LOCK, POS , ORI ,
+
SPRE, LSTU, CREF, ARRI, LEAV, ANGL, RADI,
+
BUIL, SHOP, ORIL, POSI, ISPE, TSPE, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
C
Elbo PPoints with Monitoring
CALL D3UMON( 'FULL' )
CALL D3RPAT( 'P1', 'WORL', POS(1), POS(4), BORE, HCON,
IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3RPAT( 'P2', 'WORL', POS(1), POS(4), BORE, HCON,
IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3UMON( 'NONE' )
4:14
12.0
Data Access Routines User Guide
Use of Data Access Routines
PRINT*, ' '
C
Equi details
CALL D3MNAM( '/1501B', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QMEM( IDISP, 100, TYPES, NAMES, ISIZ, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
CALL D3QEQU( IDISP, TYPE, NAME, OWNE, LOCK, FUNC, DSCO,
+
PTSP, INSC, POS, ORI, ISPE, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
IF ( NAME .NE. '/1501B' ) THEN
PRINT*, ' Expecting
NAME(:D3XLEN(NAME))
name
/1501B
got
',
GOTO 12345
ENDIF
C
Switch on Monitoring and check Pos and Ori
CALL D3UMON( 'FULL' )
CALL D3RORL( 'owne', POS, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3RORL( 'WORL', POS, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3RPRL( 'ZONE', POS, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3RPRL( '/EQU', POS, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3UMON( 'NONE' )
PRINT*, ' '
C
Box details
CALL D3MREL( 'FIRS', 'BOX', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
4:15
12.0
Data Access Routines User Guide
Use of Data Access Routines
CALL D3QBOX( IDISP, TYPE, NAME, OWNE, LOCK, XLEN, YLEN,
+
ZLEN, POS, ORI, LEVE, OBST, IERR )
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
C
Box PPoints with Monitoring
CALL D3UMON( 'FULL' )
CALL D3RPAT( 'P1', 'OWNE', POS(1), POS(4), BORE, HCON,
IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3RPAT( 'P2', 'WORL', POS(1), POS(4), BORE, HCON,
IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3UMON( 'NONE' )
PRINT*, ' '
C
Nozzle details
CALL D3MREL( 'next', 'nozz', IERR )
IF ( IERR .NE. 0 ) GOTO 12345
CALL D3QNOZ( IDISP, TYPE, NAME, OWNE, LOCK, TEMP, PRES,
+
POS, ORI,
DUTY,
CREF,
+
ISPE, IERR )
CATR,
ANGL,
HEIG,
RADI,
IF ( IERR .NE. 0 ) GOTO 12345
PRINT*, ' '
12345 CONTINUE
CALL D3UMON('NONE')
CALL D3EMSG( IERR, .TRUE., TEXT )
RETURN
END
The output from this example is as follows. Messages
'Entering D3Q...' and 'Exiting D3Q...' result from setting the
4:16
12.0
Data Access Routines User Guide
Use of Data Access Routines
display flag (first argument of D3Q routines) to 2.
Enter project
PDMS DARs <version details>
<copyright statement>
<site data>
Select MDB
Success
Design Database Example
-----------------------
Select default db type
Entering D3QMEM
Members of WORL
/*
1
SITE
/NEGATIVE-SITE
2
SITE
/DIMENSION-SITE
3
SITE
/VOLCAL.SITE
4
SITE
/EX1-SITE
5
SITE
/HANG-SITE
6
SITE
/CIVIL
7
SITE
/INTEST-SITE
8
SITE
/EQU
9
SITE
/OBSTR
10
GPWL
/GW1
Exiting D3QMEM
Entering D3QMEM
4:17
12.0
Data Access Routines User Guide
Use of Data Access Routines
Members of SITE
/EQU
1
ZONE
/EQ1
2
ZONE
/EQ2
3
ZONE
/EQ3
Exiting D3QMEM
Entering D3QSIT
Attributes of SITE
/EQU
Entering D3QCMA
TYPE
SITE
NAME
/EQU
OWNE
/*
LOCK
F
Exiting D3QCMA
POS
0.0000000E+0
0
0.0000000E+00
0.0000000E+
00
ORI
0.0000000E+0
0
0.0000000E+00
0.0000000E+
00
Exiting D3QSIT
Entering D3QMEM
Members of ZONE
/EQ3
1
EQUI
/EQUIP-FALL
2
PIPE
/FALL
3
PIPE
/100-B-2
4
PIPE
/50-W-3000
5
PIPE
/50-WD-2400
6
PIPE
/50-W1-3400
7
PIPE
/80-S12-1400
8
PIPE
/200-N12-1000
9
PIPE
/50-N12-1800
4:18
12.0
Data Access Routines User Guide
Use of Data Access Routines
10
PIPE
/150-W12-2000
11
PIPE
/150-W12-2200
12
PIPE
/100-C-12
13
PIPE
/100-C-13
14
PIPE
/150-A-57
15
PIPE
/150-A-3
16
PIPE
/40-B-10
17
PIPE
/80-A-11
18
PIPE
/80-B-14
19
PIPE
/100-B-1
20
PIPE
/80-B-7
21
PIPE
/150-B-6
22
PIPE
/100-B-8
23
PIPE
/50-B-9
24
PIPE
/200-B-4
25
PIPE
/250-B-5
Exiting D3QMEM
Entering D3QZON
Attributes of ZONE /EQ3
Entering D3QCMA
TYPE
ZONE
NAME
/EQ3
OWNE
/EQU
LOCK
F
Exiting D3QCMA
POS
0.0000000E+0
0
0.0000000E+00
100000.0
ORI
0.0000000E+0
0
0.0000000E+00
0.0000000E+
00
PSPE
=0/0
4:19
12.0
Data Access Routines User Guide
Use of Data Access Routines
ISPE
=0/0
TSPE
=0/0
Exiting D3QZON
Entering D3QMEM
Members of PIPE
/250-B-5
1
BRAN
/250-B-5/1
2
BRAN
/250-B-5/2
Exiting D3QMEM
Entering D3QPIP
Attributes of PIPE
/250-B-5
Entering D3QBPA
Entering D3QCMA
TYPE
PIPE
NAME
/250-B-5
OWNE
/EQ3
LOCK
F
Exiting D3QCMA
BUIL
F
SHOP
F
TEMP
-100000.0
PRES
0.0000000E+00
PSPE
/A3B
ISPE
=0/0
TSPE
=0/0
MATR
=0/0
FLUR
=0/0
CASR
=0/0
CCEN
0
4:20
12.0
Data Access Routines User Guide
Use of Data Access Routines
CCLA
0
DUTY
Unset
LNTP
Unset
EREC
0
DSCO
Unset
PTSP
Unset
INSC
Unset
SAFC
0
Exiting D3QBPA
BORE
0.0000000E+00
REV
-1
Exiting D3QPIP
Entering D3QMEM
Members of BRAN
/250-B-5/1
1
GASK
=8196/556
2
FLAN
=8196/557
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
Exiting D3QMEM
Entering D3QBRA
Attributes of BRAN
4:21
/250-B-5/1
12.0
Data Access Routines User Guide
Use of Data Access Routines
Entering D3QBPA
Entering D3QCMA
TYPE
BRAN
NAME
/250-B-5/1
OWNE
/250-B-5
LOCK
F
Exiting D3QCMA
BUIL
T
SHOP
T
TEMP
466.0000
PRES
340.0000
PSPE
/A3B
ISPE
=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
INSC
Unset
SAFC
0
Exiting D3QBPA
LHEA
T
LTAI
T
DETA
F
4:22
12.0
Data Access Routines User Guide
Use of Data Access Routines
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
HDIR
0.0000000E+0
0
0.0000000E+00
1.000000
TPOS
-319150.0
302640.0
2105.000
TDIR
0.0000000E+0
0
0.0000000E+00
1.000000
Exiting D3QBRA
Exiting subroutine D3UMON
Entering subroutine D3RPAT
Input arguments:
PPoint number
PH
Coordinate system
/EQ3
Exiting subroutine D3RPAT
Output arguments:
Position E -319150
N 297760
Direction unit vector E 0
Bore
200
Connection type
FGD
Error code
0
N 0
U 2105
U 1
Entering subroutine D3RPAT
Input arguments:
4:23
12.0
Data Access Routines User Guide
Use of Data Access Routines
PPoint number
ptail
Coordinate system
worl
Exiting subroutine D3RPAT
Output arguments:
Position E -319150
N 302640
Direction unit vector
E 0
Bore
200
Connection type
FGD
Error code
0
N 0
U 102105
U 1
Entering subroutine D3UMON
Input arguments:
Monitoring level
NONE
Entering D3QTEE
Attributes of TEE
/250-B-5/1-T1
Entering D3QCPA
Entering D3QCMA
TYPE
TEE
NAME
/250-B-5/1-T1
OWNE
/250-B-5/1
LOCK
F
Exiting D3QCMA
POS
-318315.3
300229.6
3886.000
ORI
0.0000000E+0
0
0.0000000E+00
0.0000000E+
00
SPRE
/A3B/250T
LSTU
=0/0
BUIL
F
SHOP
F
ORIFL
T
POSFL
T
ISPE
=0/0
4:24
12.0
Data Access Routines User Guide
Use of Data Access Routines
TSPE
=0/0
Exiting D3QCPA
CREF
/250-B-5/2
ANGL
90.00000
HEIG
0.0000000E+00
RADI
0.0000000E+00
LOFF
F
Exiting D3QTEE
Entering D3QELB
Attributes of ELBO =8196/559
Entering D3QCPA
Entering D3QCMA
TYPE
ELBO
NAME
=8196/559
OWNE
/250-B-5/1
LOCK
F
Exiting D3QCMA
POS
-318315.3
297759.1
3885.950
ORI
180.0000
0.0000000E+00
90.00000
SPRE
/A3B/200EL
LSTU
/A3B/200P
BUIL
F
SHOP
F
ORIFL
T
POSFL
T
ISPE
=0/0
TSPE
=0/0
Exiting D3QCPA
CREF
=0/0
4:25
12.0
Data Access Routines User Guide
Use of Data Access Routines
ANGL
90.00000
RADI
0.0000000E+00
Exiting D3QELB
Exiting subroutine D3UMON
Entering subroutine D3RPAT
Input arguments:
PPoint number
P1
Coordinate system
WORL
Exiting subroutine D3RPAT
Output arguments:
Position E -318620
N 297759
Direction
vector
E -1
unit
Bore
200
Connection type
BWD
Error code
0
N 0
U 103886
U 0
Entering subroutine D3RPAT
Input arguments:
PPoint number
P2
Coordinate system
WORL
Exiting subroutine D3RPAT
Output arguments:
Position E -318315
N 298064
Direction
vector
E 0
unit
Bore
200
Connection type
BWD
Error code
0
N 1
U 103886
U 0
Entering subroutine D3UMON
Input arguments:
4:26
12.0
Data Access Routines User Guide
Use of Data Access Routines
Monitoring level
NONE
Entering D3QMEM
Members of EQUI
/1501B
1
BOX
=8196/151
2
PYRA
=8196/152
3
CYLI
=8196/153
4
CYLI
=8196/154
5
RTOR
=8196/155
6
NOZZ
/1501B-SUCT
7
NOZZ
/1501B-DISC
Exiting D3QMEM
Entering D3QEQU
Attributes of EQUI
/1501B
Entering D3QCMA
TYPE
EQUI
NAME
/1501B
OWNE
/EQ2
LOCK
F
Exiting D3QCMA
FUNC
Unset
DSCO
Unset
PTSP
Unset
INSC
Unset
POS
-314490.0
303145.0
340.0000
ORI
0.0000000E+0
0
0.0000000E+00
180.0000
ISPE
=0/0
Exiting D3QEQU
4:27
12.0
Data Access Routines User Guide
Use of Data Access Routines
Exiting subroutine D3UMON
Entering subroutine D3RORL
Input arguments:
Coordinate system
owne
Exiting subroutine D3RORL
Output arguments:
Orientation unit vectors
X axis
E -1
Y axis
Z axis
Error code
N 0
U 0
E 0
N -1
U 0
E 0
N 0
U 1
0
Entering subroutine D3RORL
Input arguments:
Coordinate system
WORL
Exiting subroutine D3RORL
Output arguments:
Orientation unit vectors
X axis
E -1
Y axis
Z axis
Error code
N 0
U 0
E 0
N -1
U 0
E 0
N 0
U 1
0
Entering subroutine D3RPRL
Input arguments:
Coordinate system
ZONE
Exiting subroutine D3RPRL
Output arguments:
Position E -314490
N 303145
Error code
0
U 340
Entering subroutine D3RPRL
Input arguments:
4:28
12.0
Data Access Routines User Guide
Use of Data Access Routines
Coordinate system
/EQU
Exiting subroutine D3RPRL
Output arguments:
Position E -314490
N 303145
Error code
0
U 100645
Entering subroutine D3UMON
Input arguments:
Monitoring level
NONE
Entering D3QBOX
Attributes of BOX
=8196/151
Entering D3QCMA
TYPE
BOX
NAME
=8196/151
OWNE
/1501B
LOCK
F
Exiting D3QCMA
XLEN
510.0000
YLEN
1390.000
ZLEN
110.0000
POS
0.0000000E+0
0
-676.0000
-285.0000
ORI
0.0000000E+0
0
0.0000000E+00
0.0000000E+
00
LEVE
0
10
OBST
2
Exiting D3QBOX
Exiting subroutine D3UMON
Entering subroutine D3RPAT
Input arguments:
4:29
12.0
Data Access Routines User Guide
Use of Data Access Routines
PPoint number
P1
Coordinate system
OWNE
Exiting subroutine D3RPAT
Output arguments:
Position
E 255
Direction unit vector E 1
Bore
N -676
N 0
U -285
U 0
0
Connection type
Error code
0
Entering subroutine D3RPAT
Input arguments:
PPoint number
P2
Coordinate system
WORL
Exiting subroutine D3RPAT
Output arguments:
Position
E -314490
100360
Direction unit vector
Bore
E 0
N -1
N
303126
U
U 0
0
Connection type
0
Error code
Entering subroutine D3UMON
Input arguments:
Monitoring level
NONE
Entering D3QNOZ
Attributes of NOZZ
/1501B-SUCT
Entering D3QCMA
TYPE
NOZZ
NAME
/1501B-SUCT
OWNE
/1501B
4:30
12.0
Data Access Routines User Guide
Use of Data Access Routines
LOCK
F
Exiting D3QCMA
TEMP
-100000.0
PRES
0.0000000E+0
0
POS
0.0000000E+0
0
0.0000000E+00
0.0000000E+
00
ORI
0.0000000E+0
0
0.0000000E+00
180.0000
CREF
/100-B-8/1
CATR
/NFAAPAMM
ANGL
90.00000
HEIG
100.0000
RADI
0.0000000E+0
0
DUTY
Unset
ISPE
=0/0
Exiting D3QNOZ
Success
4:31
12.0
Data Access Routines User Guide
Use of Data Access Routines
4:32
12.0
Data Access Routines User Guide
Subroutine Specifications
5
Subroutine Specifications
5.1
Subroutine Summaries
5.1.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.1.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.
5:1
12.0
Data Access Routines User Guide
Subroutine Specifications
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.1.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
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.
5:2
12.0
Data Access Routines User Guide
Subroutine Specifications
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
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
5:3
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.1.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.
programmer wishes to output the nature of the error, he may call this routine.
If the
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.1.5
Utility Routines, D3Uxxx
D3UMON - Change Monitor Level
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.
5:4
12.0
Data Access Routines User Guide
Subroutine Specifications
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.1.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
An optional way of stopping a DARs application program. It results in a program exit and is
equivalent to a CALL EXIT statement.
5.1.7
General Utility Routines, D3Uxxx
D3UGTU - Get File Unit
This function allocates an unused FORTRAN file unit for use by the application program.
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.2
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:
5:5
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
D3ECHK - Switch Error Handling ON and OFF
Specification
SUBROUTINE 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
D3EMSG - Return Error Message
Specification
SUBROUTINE D3EMSG( ID3ERR, LD3DIS, CD3MSG )
CHARACTER*(*)
CD3MSG
LOGICAL
LD3DIS
INTEGER
ID3ERR
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.
5:6
12.0
Data Access Routines User Guide
Subroutine Specifications
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 Error Codes and Messages.
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.
D3ERST - Reset Internal Error Flag
Specification
SUBROUTINE 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.
D3FEND - Exit System
Specification
SUBROUTINE D3FEND
5:7
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
D3FIN - Finish
Specification
SUBROUTINE D3FIN( ID3ERR )
INTEGER
ID3ERR
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.
5:8
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
D3INIT - Initialise
Specification
SUBROUTINE D3INIT( CD3PRJ, CD3USR, CD3PAS, CD3MON, CD3RWK,
ID3ERR )
CHARACTER*(*)
CD3PRJ, CD3USR, CD3PAS, CD3MON, CD3RWK
INTEGER
ID3ERR
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.
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.
5:9
12.0
Data Access Routines User Guide
Subroutine Specifications
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' or 'Jones'
Input characters will be converted to upper case if an exact-case
match is not found (i.e. the correct case must be used if the desired
username does not consist entirely of upper-case alphabetic
characters). Strings exceeding 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).
Input characters will be converted to upper case. Strings exceeding
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.
CD3RWK
Read/write key (for future use)
Enter as ' ' in this release. The argument will be ignored.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
101
Error opening Dabacon workfile
102
Bad password
103
Unknown username
5:10
12.0
Data Access Routines User Guide
Subroutine Specifications
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
SUBROUTINE D3MCDB( CD3NAM, ID3POS, ID3ERR )
CHARACTER*(*)
CD3NAM
INTEGER
ID3POS, ID3ERR
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.
5:11
12.0
Data Access Routines User Guide
Subroutine Specifications
Possible values are:
0
Success
2
Internal error code set on entry
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
D3MDDB - Defer a Database in MDB
Specification
SUBROUTINE D3MDDB( CD3NAM, ID3ERR )
CHARACTER*(*)
CD3NAM
INTEGER
ID3ERR
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.
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 DEFER in the DESIGN module.
5:12
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
CD3NAM
The name of the database.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
120
Database not found
121
Database not in current MDB
123
Database not current
D3MEDB - Exchange Databases in MDB
Specification
SUBROUTINE D3MEDB( CD3NM1, CD3NM2, ID3ERR )
CHARACTER*(*)
CD3NM1, CD3NM2
INTEGER
ID3ERR
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.
If an error occurs then an error code is returned as specified below and the named
databases remain in an unchanged state. The change in database status is temporary, for
the duration of the DARs application, 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.
5:13
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
Possible values are:
0
Success
2
Internal error code set on entry
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 (i.e. both are current)
123
Database not current (i.e. both are deferred)
D3MMDB - Select MDB
Specification
SUBROUTINE D3MMDB( CD3MDB, CD3RWK, ID3ERR )
CHARACTER*(*)
CD3MDB, CD3RWK
INTEGER
ID3ERR
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.
5:14
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
5:15
12.0
Data Access Routines User Guide
Subroutine Specifications
3
Routine D3INIT has not been called
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
D3MNAM - Move to an Element by Name
Specification
SUBROUTINE D3MNAM( CD3NAM, ID3ERR )
CHARACTER*(*)
CD3NAM
INTEGER
ID3ERR
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5:16
12.0
Data Access Routines User Guide
Subroutine Specifications
9
Bad name/reference argument
402
Undefined name/reference
D3MNUM - Move to Element by Order Position
Specification
SUBROUTINE D3MNUM( CD3TYP, ID3LIS, ID3ERR )
CHARACTER*(*)
CD3TYP
INTEGER
ID3LIS, ID3ERR
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).
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5:17
12.0
Data Access Routines User Guide
Subroutine Specifications
10
Argument has illegal value
201
Element has no list part
202
No members
203
List exhausted
205
Cannot access this type of element
D3MOWN - Move to Owner of Current Element
Specification
SUBROUTINE D3MOWN( ID3ERR )
INTEGER
ID3ERR
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
204
Current element has no owner
D3MQDB - Query database in Current MDB
Specification
SUBROUTINE D3MQDB( ID3POS, CD3NAM, CD3TYP, ID3STA, ID3ERR )
CHARACTER*(*)
CD3NAM, CD3TYP
INTEGER
ID3POS, ID3STA, ID3ERR
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.
5:18
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
125
Invalid database position
5:19
12.0
Data Access Routines User Guide
Subroutine Specifications
D3MREL - Move Relative to the Current Position
Specification
SUBROUTINE D3MREL( CD3POS, CD3TYP, ID3ERR )
CHARACTER*(*)
CD3POS, CD3TYP
INTEGER
ID3ERR
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'.
Input characters will be converted to upper case. Abbreviations
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
TID3ERR
Error code
Possible values are:
0
Success
2
Internal error code set on entry
5:20
12.0
Data Access Routines User Guide
Subroutine Specifications
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
6
Invalid position keyword
201
Element has no list part
202
No members
203
List exhausted
205
Cannot access this type of element
D3MRST - Restore Last Saved Database Position
Specification
SUBROUTINE D3MRST( ID3ERR )
INTEGER
ID3ERR
Description
This routine restores the database position saved by the previous call to D3MSAV.
Calls to D3MSAV and D3MRST must be paired and can be nested to a 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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
127
No saved database position
5:21
12.0
Data Access Routines User Guide
Subroutine Specifications
D3MSAV - Save Current Database Position
Specification
SUBROUTINE D3MSAV( ID3ERR )
INTEGER
ID3ERR
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.
Calls to D3MSAV and D3MRST must be paired and can be nested to a 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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
126
Too many saved database levels
D3RBDU - Read Bore and Distance Units
Specification
SUBROUTINE 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 will be truncated but no error condition will
arise. If the field is too long, it will be padded with blanks.
5:22
12.0
Data Access Routines User Guide
Subroutine Specifications
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 will be truncated but no error condition will
arise. If the field is too long, it will be padded with blanks.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
D3RBOX - Read Enclosing Box Co-ordinates
Specification
SUBROUTINE D3RBOX
( LD3TUB, RD3BOX, ID3ERR )
LOGICAL
LD3TUB
INTEGER
ID3ERR
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.
If an error occurs then an error code is returned as specified below and six elements of
RD3BOX are returned as zero. Error 310 can only be returned if LD3TUB, the leave tube
flag, is set to true.
5:23
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
LD3TUB
Leave tube flag.
.TRUE.
Return box for leave tube (or branch head tube for branch)
.FALSE.
Return box for current element
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
309
Element not on spatial map
310
Leave or head tube does not exist
D3RDAT - Read Latest MDB Date-Stamp
Specification
SUBROUTINE D3RDAT( ID3DAT, CD3DAT, ID3ERR )
CHARACTER*(*)
CD3DAT
INTEGER
ID3DAT(6), ID3ERR
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.
5:24
12.0
Data Access Routines User Guide
Subroutine Specifications
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)
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
5:25
12.0
Data Access Routines User Guide
Subroutine Specifications
4
Routine D3MMDB has not been called
306
No date-stamp found
D3RIA - Read an Integer Array Attribute
Specification
SUBROUTINE D3RIA( CD3ATT, ID3NIN, ID3IA, ID3NOU, ID3ERR )
CHARACTER*(*)
CD3ATT
INTEGER
ID3NIN, ID3IA(ID3NIN), ID3NOU, ID3ERR
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.
If an error occurs then an error code is returned as specified below, 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 Dynamic Array Attributes).
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.
5:26
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
301
Attribute not found
302
Attribute of wrong type
308
Attribute unset
5:27
12.0
Data Access Routines User Guide
Subroutine Specifications
D3RINT - Read an Integer Attribute
Specification
SUBROUTINE D3RINT( CD3ATT, ID3INT, ID3ERR )
CHARACTER*(*)
CD3ATT
INTEGER
ID3INT, ID3ERR
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
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'ARR', 'SAFC' are
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.
ID3INT
The value of the integer attribute.
If the attribute is user-defined, the units pertaining to the returned
integer value may be obtained by calling routine D3RUNI.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
301
Attribute not found
302
Attribute of wrong type
5:28
12.0
Data Access Routines User Guide
Subroutine Specifications
D3RLA - Read a Logical Array Attribute
Specification
SUBROUTINE D3RLA( CD3ATT, ID3NIN, LD3LA, ID3NOU, ID3ERR )
CHARACTER*(*)
CD3ATT
INTEGER
ID3NIN, ID3NOU, ID3ERR
LOGICAL
LD3LA(ID3NIN)
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 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 false.
The routine will return a single value for a single logical attribute.
The routine will return the error 'Attribute not found' for a dynamic array attribute that has no
values set (see Dynamic Array Attributes).
If an error occurs then an error code is returned as specified below, ID3NOU is returned as
zero and ID3NIN elements of LD3LA are returned as false.
The only use of logical arrays is for UDAs.
Arguments
CD3ATT
The name of the attribute required.
This must be a PDMS attribute name 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.
A UDA name must include the leading ':' character. The number
of characters following the ':' must be greater than or equal to
the minimum abbreviation.
ID3NIN
Maximum number of array elements required.
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.
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.
5:29
12.0
Data Access Routines User Guide
Subroutine Specifications
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
301
Attribute not found
302
Attribute of wrong type
308
Attribute unset
D3RLOG - Read a Logical Attribute
Specification
SUBROUTINE D3RLOG( CD3ATT, LD3LOG, ID3ERR )
CHARACTER*(*)
CD3ATT
INTEGER
ID3ERR
LOGICAL
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
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'BUI', 'SHO' are
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.
LD3LOG
The value of the logical attribute.
ID3ERR
Error code.
Possible values are:
5:30
12.0
Data Access Routines User Guide
Subroutine Specifications
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
301
Attribute not found
302
Attribute of wrong type
D3RNAM - Read Element Name or a Name Attribute
Specification
SUBROUTINE D3RNAM( CD3ATT, CD3NAM, ID3ERR )
CHARACTER*(*)
CD3ATT, CD3NAM
INTEGER
ID3ERR
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.
If an error occurs then an error code is returned as specified below and CD3NAM is
returned as blank.
Use routine D3RREF to obtain the reference specifically even if a name is available.
Arguments
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'PSPE', 'CAT' are
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.
CD3NAM
The value of the name attribute.
5:31
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
301
Attribute not found
302
Attribute of wrong type
D3RORL - Read Orientation of the Current Element
Specification
SUBROUTINE D3RORL( CD3CRD, RD3ORI, ID3ERR )
CHARACTER*(*)
CD3CRD
INTEGER
ID3ERR
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.
If an error occurs then an error code is returned as specified below and 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.
5:32
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
7
Invalid co-ordinate system keyword
9
Bad name/reference argument
205
Cannot access this type of element
402
Undefined name/reference
5:33
12.0
Data Access Routines User Guide
Subroutine Specifications
D3RPAT - Read PPOINT Attributes
Specification
SUBROUTINE D3RPAT( CD3POI, CD3CRD, RD3POS, RD3DIR, RD3BOR,
CD3CON, ID3ERR )
CHARACTER*(*)
CD3POI, CD3CRD, CD3CON
INTEGER
ID3ERR
REAL
RD3POS(3), RD3DIR(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 names, PDMS reference numbers, PDMS nouns and
the text 'OWN/ER'. 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.
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.
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.
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).
5:34
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.
An undefined name or reference number will result in error code 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
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
7
Invalid co-ordinate system keyword
8
Invalid PPoint keyword
9
Bad name/reference argument
205
Cannot access this type of element
303
Element does not have PPoints
5:35
12.0
Data Access Routines User Guide
Subroutine Specifications
304
Illegal PPoint number
402
Undefined name/reference
D3RPRJ - Read a Project Data Item
Specification
SUBROUTINE D3RPRJ( CD3NAM, CD3TEX, ID3ERR )
CHARACTER*(*)
CD3NAM, CD3TEX
INTEGER
ID3ERR
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>'.
If an error occurs then an error code is returned as specified below and 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 3character 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.
5:36
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
5
Character output string parameter too short
11
Invalid project data keyword
D3RPRL - Read Position of the Current Element
Specification
SUBROUTINE D3RPRL( CD3CRD, RD3POS, ID3ERR )
CHARACTER*(*)
CD3CRD
INTEGER
ID3ERR
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 names, PDMS reference numbers,
PDMS nouns and the text 'OWN/ER'. The position is returned as a three element real array.
Array RD3POS must be declared at least three elements.
If an error occurs then an error code is returned as specified below and three elements of
RD3POS are returned as zero.
5:37
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.
An undefined name or reference number will result in error
code 402.
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
7
Invalid co-ordinate system keyword
9
Bad name/reference argument
205
Cannot access this type of element
402
Undefined name/reference
D3RPTX - Read REPORTER Text for a UDA
5:38
12.0
Data Access Routines User Guide
Subroutine Specifications
Specification
SUBROUTINE D3RPTX( CD3ATT, CD3RPT, ID3ERR )
CHARACTER*(*)
CD3ATT, CD3RPT
INTEGER
ID3ERR
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
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
307
UDA not found
5:39
12.0
Data Access Routines User Guide
Subroutine Specifications
D3RRA - Read a Real Array Attribute
Specification
SUBROUTINE D3RRA( CD3ATT, ID3NIN, RD3RA, ID3NOU, ID3ERR )
CHARACTER*(*)
CD3ATT
INTEGER
ID3NIN, ID3NOU, ID3ERR
REAL
RD3RA(ID3NIN)
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 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 real attribute.
The routine will return the error 'Attribute not found' for a dynamic array attribute that has no
values set (see Section Dynamic Array Attributes).
If an error occurs then an error code is returned as specified below, ID3NOU is returned as
zero and ID3NIN elements of array RD3RA are returned as zero.
Arguments
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'HDI', 'POS' are
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.
ID3NIN
Maximum number of array elements required.
Array RD3RA 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.
RD3RA
The array of real values.
If the attribute is user-defined, the units pertaining to the returned
real array may be obtained by calling routine D3RUNI.
5:40
12.0
Data Access Routines User Guide
Subroutine Specifications
ID3NOU
The number of values returned in RD3RA.
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
301
Attribute not found
302
Attribute of wrong type
308
Attribute unset
D3RREA - Read a Real Attribute
Specification
SUBROUTINE D3RREA( CD3ATT, RD3REA, ID3ERR )
CHARACTER*(*)
CD3ATT
INTEGER
ID3ERR
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.
5:41
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'TEM', 'XLE' are
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.
RD3REA
The value of the real attribute.
If the attribute is user-defined, the units pertaining to the returned
real value may be obtained by calling routine D3RUNI.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
301
Attribute not found
302
Attribute of wrong type
D3RREF - Read Element RefNo or a Reference Attribute
Specification
SUBROUTINE D3RREF( CD3ATT, CD3REF, ID3ERR )
CHARACTER*(*)
CD3ATT, CD3REF
INTEGER
ID3ERR
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.
If an error occurs then an error code is returned as specified below and CD3REF will be
returned zero.
Use routine D3RNAM to obtain the name, if available, in preference to the reference
number.
5:42
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
PDMS will be accepted by this routine (e.g. 'CREF', 'HREF' are
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.
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.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
301
Attribute not found
302
Attribute of wrong type
D3RRFA - Read a Reference Number Array Attribute
Specification
SUBROUTINE D3RRFA( CD3ATT, ID3NIN, CD3RFA, ID3NOU, ID3ERR )
CHARACTER*(*)
ID3NIN, ID3NOU, ID3ERR
INTEGER
CD3ATT, CD3RFA(ID3NIN)
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
5:43
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
The routine will return the error 'Attribute not found' for a dynamic array attribute that has no
values set (see Dynamic Array Attributes).
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
CD3ATT
The name of the attribute required.
This must be a PDMS attribute name, e.g. 'CRF/A' 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. 'CRF' 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.
ID3NIN
Maximum number of array elements required.
Array CD3RFA 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.
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.
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 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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5:44
12.0
Data Access Routines User Guide
Subroutine Specifications
5
Character output string parameter too short
301
Attribute not found
302
Attribute of wrong type
308
Attribute unset
D3RTEX - Read a Text Attribute
Specification
SUBROUTINE D3RTEX( CD3ATT, CD3TEX, ID3ERR )
CHARACTER*(*)
CD3ATT, CD3TEX
INTEGER
ID3ERR
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 Dynamic Array Attributes).
If an error occurs then an error code is returned as specified below and 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.
5:45
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
CD3ATT
The name of the attribute required.
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.
In the case of PDMS attribute name, abbreviations accepted in
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
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
301
Attribute not found
302
Attribute of wrong type
308
Attribute unset
5:46
12.0
Data Access Routines User Guide
Subroutine Specifications
D3RTYP - Read a Type Attribute
Specification
SUBROUTINE D3RTYP( CD3TYP, ID3ERR )
CHARACTER*(*)
CD3TYP
INTEGER
ID3ERR
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). 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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
D3RUDA - Read Lists of UDA Names, Abbreviations and Types
Specification
SUBROUTINE D3RUDA( CD3TYP, ID3MAX, CD3NMS, ID3ABV, CD3ATP,
ID3NUM, ID3ERR )
CHARACTER*(*)
ID3MAX, ID3ABV(ID3MAX), ID3NUM, ID3ERR
INTEGER
CD3TYP, CD3NMS(ID3MAX), CD3ATP(ID3MAX)
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
5:47
12.0
Data Access Routines User Guide
Subroutine Specifications
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'.
Input characters will be converted to upper case. Abbreviations
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 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.
5:48
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
D3RUNI - Read Unit of Measurement for a Real or Integer UDA
Specification
SUBROUTINE D3RUNI( CD3ATT, CD3UNT, ID3ERR )
CHARACTER*(*)
CD3ATT, CD3UNT
INTEGER
ID3ERR
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.
5:49
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
307
UDA not found
D3RWA - Read a Word Array Attribute
Specification
SUBROUTINE D3RWA( CD3ATT, ID3NIN, CD3WA, ID3NOU, ID3ERR )
CHARACTER*(*)
ID3NIN, ID3NOU, ID3ERR
INTEGER
CD3ATT, CD3WA(ID3NIN)
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.
5:50
12.0
Data Access Routines User Guide
Subroutine Specifications
The routine will return the error 'Attribute not found' for a dynamic array attribute that has no
values set (see Section Dynamic Array Attributes).
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 (see Example 1).
INTEGER
ID3NOU, ID3ERR, I
REAL
PARA( 100
CHARACTER*6
PARWOR( 100 )
INTRINSIC
INT
CALL D3RRA( ‘PARA’, 100, PARA, ID3NOU, ID3ERR )
IF ( ID3ERR .NE. 0 ) THEN
DO 100 I = 1, ID3NOU
PARWOR( I ) = ‘ ’
IF ( PARA( I ) .GT. 531442.0 ) THEN
CALL D3UDEH( INT( PARA( I ) ), PARWOR(I ) )
ENDIF
100
CONTINUE
ENDIF
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).
Arguments
CD3ATT
The name of the attribute required.
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).
ID3NIN
Maximum number of array elements required.
Array CD3WA 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.
5:51
12.0
Data Access Routines User Guide
Subroutine Specifications
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).
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.
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
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.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
301
Attribute not found
302
Attribute of wrong type
308
Attribute unset
D3RWOR - Read a Word Attribute
Specification
SUBROUTINE D3RWOR( CD3ATT, CD3WOR, ID3ERR)
CHARACTER*(*)
CD3ATT, CD3WOR
INTEGER
ID3ERR
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.
If an error occurs then an error code is returned as specified below and CD3WOR is
returned as blank.
5:52
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
CD3ATT
The name of the attribute required.
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).
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.
ID3ERR
Error code.
Possible values are:
0
Success
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
5
Character output string parameter too short
301
Attribute not found
302
Attribute of wrong type
D3UCLU - Clear File Unit
Specification
LOGICAL FUNCTION D3UCLU( ID3UNI )
INTEGER
ID3UNI
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.
5:53
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
ID3UNI
FORTRAN file unit number.
Function Value
D3UCLU
.TRUE. if file unit number accepted.
.FALSE. if unit invalid.
D3UCTI - Character to Integer
Specification
LOGICAL FUNCTION D3UCTI( CD3STR, ID3INT, CD3BEF, CD3AFT,
CD3ERR )
CHARACTER*(*)
CD3STR, CD3BEF, CD3AFT, CD3ERR
INTEGER
ID3INT
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.
5:54
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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 programmer
wishes to make use of this functionality, it is recommended that this
variable is declared the same size as 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.
5:55
12.0
Data Access Routines User Guide
Subroutine Specifications
.FALSE.
if no integer.
.FALSE.
if integer found with additional data.
D3UCTR - Character to Real Number
Specification
LOGICAL FUNCTION 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.
There is no limit to the length of the string.
RD3VAL
Extracted value, if found.
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 programmer
wishes to make use of this functionality, it is recommended that this
variable is declared the same size as CD3STR.
5:56
12.0
Data Access Routines User Guide
Subroutine Specifications
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 programmer
wishes to make use of this functionality, it is recommended that this
variable is declared the same size as 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 double precision REAL variable. The valid range is
system dependent (typically about -1E308 to +1E308). A real number whose value is too
close to zero to be represented by a REAL variable (typically between -1E-308 and +1E308) 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.
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.
D3UDEH - Dehash a Hashed PDMS Word
Specification
SUBROUTINE D3UDEH( ID3INT, CD3WOR )
CHARACTER*(*)
CD3WOR
INTEGER
ID3INT
5:57
12.0
Data Access Routines User Guide
Subroutine Specifications
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 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.
D3UDTM - Read Current System Date and Time
Specification
SUBROUTINE D3UDTM( ID3DAT, CD3DAT )
CHARACTER*(*)
CD3DAT
INTEGER
ID3DAT(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.
5:58
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
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.
D3UGTU - Get File Unit
Specification
SUBROUTINE LOGICAL FUNCTION D3UGTU( ID3UNI )
INTEGER
ID3UNI
5:59
12.0
Data Access Routines User Guide
Subroutine Specifications
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.
IF
(D3UGTU(IUNIT)) THEN
OPEN(IUNIT ...
NOT
DO 100 I=1,20
OK =
100
D3UGTU(IUNIT(I))
CONTINUE
OPEN (IUNIT(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.
D3UINI - Query Initialisation
Specification
SUBROUTINE D3UINI( 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.
5:60
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
LD3INI
.TRUE.
if a project is not currently initialised
.FALSE.
if no unit available.
D3ULDS - Test Latest MDB Date-Stamp
Specification
LOGICAL FUNCTION D3ULDS( CD3DAT, ID3ERR )
CHARACTER*(*)
CD3DAT
INTEGER
ID3ERR
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'
'13sept1997'
ID3ERR
is '13 Sep 1997 12:15:00'
is '13 Sep 1997 23:59:59'
Error code.
Possible values are:
0
Success
5:61
12.0
Data Access Routines User Guide
Subroutine Specifications
2
Internal error code set on entry
3
Routine D3INIT has not been called
4
Routine D3MMDB has not been called
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.
D3ULEN - Length of Character String
Specification
INTEGER FUNCTION 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.
5:62
12.0
Data Access Routines User Guide
Subroutine Specifications
Arguments
CD3STR
String for which significant length is required.
There is no limit to the length of the string.
Function Value
D3ULEN
Significant length of string.
Zero for blank string ' '. Equivalent to LEN(CD3STR) for undefined
string.
D3UMON - Change Monitor Level
Specification
SUBROUTINE 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).
Input characters will be converted to upper case. Strings exceeding 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.
5:63
12.0
Data Access Routines User Guide
Subroutine Specifications
5:64
12.0
Data Access Routines User Guide
Version Control
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.2 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.
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:
PDMS DARs C Interface Mk12.0.0.0 (WINDOWS-NT 5.2) (7 Sep 2007 : 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.
6:1
12.0
Data Access Routines User Guide
Version Control
6:2
12.0
Data Access Routines User Guide
DARs Library Details
A
DARs Library Details
At DARs 12.0, 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:
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 ‘C/C++’ Library)
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
A:1
12.0
Data Access Routines User Guide
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. pdms12.0/dars).
The DARs 12.0 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 Auxiliary Subroutine Library.
This appendix covers machine-specific information in respect of FORTRAN libraries and
utilities. ‘C/C++’ Library 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.
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.
LOGICAL D3UGTU, D3UCLU, OK
INTEGER FUNIT
IF (.NOT. D3UGTU( FUNIT )) GOTO 999
OPEN( FUNIT, .... )
A:2
12.0
Data Access Routines User Guide
DARs Library Details
READ( FUNIT, .... )
CLOSE( FUNIT )
OK = D3UCLU( FUNIT )
or
EXTERNAL EX1
CALL D3IBEG(EX1,' ')
..
SUBROUTINE 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 12 uses the standard MicroSoft C/C++ compiler, cl, and the Intel Fortran compiler,
ifort. Fortran code will need to be compiled with the following options to ensure Fortran/C/
C++ compatibility:
/iface:cref /iface:mixed_str_len_arg /libs:dll
/threads /recursive /op /real-size:64
These should be entered into a plain text file named ifort.cfg. This file should then be
referenced by setting the environment variable IFORTCFG to the full path to ifort.cfg.
The following is an example ifort.cfg file:
# This is the Fortran configuration for "Double Precision", in which REAL
# is treated as DOUBLE (64-bit) [but DOUBLE is NOT QUAD (128-bit)]
# Tells the compiler to use calling conventions C, REFERENCE.
/iface:cref
# This option tells the compiler that the hidden length passed for a
character
# argument is to be placed immediately after its corresponding character
argument.
/iface:mixed_str_len_arg
# Causes the compiler to ignore case differences in identifiers and to
convert
# external names to uppercase.
/names:uppercase
# Specifies a single-threaded, dynamic-link (DLL) library.
/libs:dll
A:3
12.0
Data Access Routines User Guide
DARs Library Details
# Tells the linker to search for unresolved references in a multithreaded
# run-time library.
/threads
# Tells the compiler that all routines should be compiled for possible
recursive execution.
/recursive
/Op
# Double indecision REAL but NOT DOUBLEs
/real-size:64
A.4
Program Running and Debugging
You will need to have d3lib.dll which is dependant on the following fortran runtime library
files:LIBIFCOREMD.DLL
LIBMMD.DLL
These are therefore included in %PDMSEXE% and with this DARs release.
MSVCP71.DLL and MSVCR71.DLL should also be present. If not already installed these
can be a obtained from Microsoft.
If, when you start up your DARs application, you get a Windows popup such as:
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%\dars\dar000
set DAR100=%PDMSEXE%\dars\dar100
A:4
12.0
Data Access Routines User Guide
DARs Library Details
2. Set the DARs library environment variable:
e.g. set DARSLIBDIR=%PDMSEXE%\dars
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 %DARSLIBDIR%\d3test > d3test.log
at the terminal.
Compare d3test.log and d3test.log.base; any significant differences?
5. Enter %DARSLIBDIR%\compload d3test
6. Enter d3test >d3test.log
Compare d3test.log and d3test.log.base; any significant differences?
7. Enter %DARSLIBDIR%\compload f77_example1
8. Enter f77_example1
Does the output appear to be the same the output in Example 1 (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.
A:5
12.0
Data Access Routines User Guide
DARs Library Details
A:6
12.0
Data Access Routines User Guide
Running Examples
B
Running Examples
The basic principles for compiling, linking and running DARs applications programs have
been outlined in appendix DARs Library Details.
The example programs illustrated in Use of Data Access Routines 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.
rem @echo off
Rem $Id: compload.bat,v 1.1 1998/09/30 14:40:33 pne Exp $
Rem NT .bat file to compile and link a PDMS DARs application
program.
Rem Argument[1] is the file to be compiled.
if not "%1"=="" goto GOTFILE
echo compload - no filename specified.
goto FINISH
:GOTFILE
Rem Compile
IFORT /c %1.f
Rem and link
link %1.obj /subsystem:console/entry:mainCRTStartup %PDMSEXE%
\dars\d3lib.lib
:FINISH
B:1
12.0
Data Access Routines User Guide
Running Examples
B:2
12.0
Data Access Routines User Guide
Error Codes and Messages
C
Error Codes and Messages
Errors are mostly handled by the return of an error code by each DARs routine. Details are
included in Error Handling, Monitoring and Detailed Subroutine Specifications 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.
2
Internal error code set on entry
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.
3
Routine D3INIT has not been called
A successful call to routine D3INIT must precede all use of data access
navigation and attribute retrieval routines in each project.
C:1
12.0
Data Access Routines User Guide
Error Codes and Messages
4
Routine D3MMDB has not been called
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.
9
Bad name/reference argument
A name has been supplied without a leading / character, or a reference
number without = and / characters.
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
C:2
12.0
Data Access Routines User Guide
Error Codes and Messages
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.
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.
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.
C:3
12.0
Data Access Routines User Guide
Error Codes and Messages
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.
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.
120
Database not found
Named database not present in current project.
121
Database not in current MDB
Named database not present in current MDB.
122
Database already current
Database cannot be made current because it already is current.
databases cannot be exchanged because both are current.
123
Database not current
Database cannot be deferred because it already is deferred.
databases cannot be exchanged because both are deferred.
124
Or,
Or,
Too many current databases
Database cannot be made current because the maximum number of
databases is already current.
125
Invalid database position
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.
127
No saved database position.
C:4
12.0
Data Access Routines User Guide
Error Codes and Messages
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.
201
Element has no list part
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.
205
Cannot access this type of element
A PDMS noun of unrecognised type has been supplied, either as element
type or coordinate system.
301
Attribute not found
The current element does not have the requested attribute.
302
Attribute of wrong type
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.
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
C:5
12.0
Data Access Routines User Guide
Error Codes and Messages
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.
402
Undefined name/reference
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
This should not occur. Ensure the user has access to the PDMS work
area and to the PDMS project.
405
File read error
This should not occur. Ensure the user has access to the PDMS work
area and to the PDMS project.
C:6
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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 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 Error Codes and Messages).
D:1
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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
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
D:2
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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 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
D.3
Integer Function returning Significant Length of a String or 1 for a
Blank String (variant of D3ULEN)
Subroutine Outline Specifications
Outline specifications are presented for the auxiliary routines in the order listed above.
SUBROUTINE D3QMEM ( ID3DIS, ID3NIN, CD3TYP, CD3NAM, ID3NOU, ID3ERR )
INTEGER
ID3DIS, ID3NIN, ID3NOU, ID3ERR
CHARACTER*(*)
CD3TYP(ID3NIN), CD3NAM(ID3NIN
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
D:3
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
SUBROUTINE D3QCMA ( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
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 NAMEName
OWNE
Owner name/ref LOCKLock flag
ID3ERR
Error code
SUBROUTINE D3QUDV ( ID3DIS, ID3ERR )
INTEGER
ID3DIS, 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.
D:4
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
SUBROUTINE D3QSIT (ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI, ID3ERR)
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
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
OWNE
Owner name/ref
LOCK
Lock flag
POS
Position
ORI
ID3ERR
Error code
Orientation
SUBROUTINE D3QZON( ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI,
PSPE,ISPE, TSPE, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, PSPE, ISPE, TSPE
REAL
POS(3), ORI(3)
Performs the equivalent of a Q ATT for a ZONE.
Calls D3RNAM, D3XLEN, D3QCMA, D3RRA, D3EMSG, D3ERST
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
POS
Position
ORI
Orientation
PSPE
Pipe spec
ISPE
Insulation spec
TSPE
Tracing spec
ID3ERR
Error code
D:5
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
SUBROUTINE D3QPIP( ID3DIS, 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 )
INTEGER
ID3DIS, CCEN, CCLA, EREC, REV, SAFC,
ID3ERR
LOGICAL
LOCK, BUIL, SHOP
CHARACTER*(*)
TYPE, NAME, OWNE, PSPE, ISPE, TSPE, MATR
CHARACTER*(*)
FLUR, CASR, DUTY, LNTP, DSCO, PTSP, INSC
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
OWNE
Owner name/ref
LOCK
Lock flag
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
SUBROUTINE D3QBRA( ID3DIS, TYPE, NAME, OWNE, LOCK, BUIL,
LTAI,DETA, SHOP, LSTR, LNTP, EREC, HBOR, TBOR, HCON,TCON,
PRES, FLOW, MATR, FLUR, CASR, PSPE,ISPE, TSPE, CCEN, CCLA,
DSCO, PTSP, INSC,SAFC, HSTU, HREF, TREF, HPOS, HDIR,
TDIR,ID3ERR )
LHEA,
TEMP,
DUTY,
TPOS,
INTEGER
ID3DIS, EREC, CCEN, CCLA, SAFC, ID3ERR
LOGICAL
LOCK, BUIL, LHEA, LTAI, DETA, SHOP, LSTR
D:6
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
CHARACTER*(*)
TYPE, NAME,
FLOW, MATR
OWNE,
LNTP,
HCON,
TCON,
CHARACTER*(*)
FLUR, CASR,
DSCO, PTSP
PSPE,
ISPE,
TSPE,
DUTY,
CHARACTER*(*)
INSC, HSTU, HREF, TREF
REAL
HBOR, TBOR, TEMP, PRES, HPOS(3), HDIR(3)
REAL
TPOS(3), TDIR(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
OWNE
Owner name/ref
LOCK
Lock flag
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
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
D:7
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
SUBROUTINE D3QBPA( ID3DIS, TYPE, NAME, OWNE, LOCK, BUIL, SHOP,
TEMP,PRES, PSPE, ISPE, TSPE, MATR, FLUR, CASR, CCEN,CCLA, DUTY,
LNTP, EREC, DSCO, PTSP, INSC, SAFC,ID3ERR )
INTEGER
ID3DIS, CCEN, CCLA, EREC, SAFC, ID3ERR
LOGICAL
LOCK, BUIL, SHOP
CHARACTER*(*)
TYPE, NAME,
MATR, FLUR
CHARACTER*(*)
CASR, DUTY, LNTP, DSCO, PTSP, INSC
REAL
TEMP, PRES
OWNE,
PSPE,
ISPE,
TSPE,
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
SUBROUTINE D3QTEE( ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI, SPRE,
LSTU, CREF, ARRI, LEAV, ANGL, HEIG, RADI, BUIL, SHOP, ORIL, POSI,
LOFF, ISPE, TSPE, ID3ERR )
INTEGER
ID3DIS, ARRI, LEAV, ID3ERR
LOGICAL
LOCK, SHOP, BUIL, ORIL, POSI, LOFF
CHARACTER*(*)
TYPE, NAME, OWNE, SPRE, LSTU, CREF,
ISPE, TSPE
REAL
POS(3), ORI(3), HEIG, 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
OWNE
Owner name/ref
LOCK
Lock flag
POS
Position
ORI
Orientation
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
D:8
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
ORIL
Orientation flag
POSI
Position flag
LOFF
Offline flag
ISPE
Insulation spec
TSPE
Tracing spec
ID3ERR
Error code
SUBROUTINE D3QELB( ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI, SPRE,
LSTU, CREF, ARRI, LEAV, ANGL, RADI, BUIL, SHOP, ORIL, POSI, ISPE,
TSPE, ID3ERR )
INTEGER
ID3DIS, ARRI, LEAV, ID3ERR
LOGICAL
LOCK, SHOP, BUIL, ORIL, POSI
CHARACTER*(*)
TYPE, NAME, OWNE, SPRE, LSTU, CREF,
ISPE, 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
OWNE
Owner name/ref
LOCK
Lock flag
POS
Position
ORI
Orientation
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
TSPE
Tracing spec
ID3ERR
Error code
SUBROUTINE D3QCPA( ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI, SPRE,
LSTU, ARRI, LEAV, BUIL, SHOP, ORIL, POSI, ISPE, TSPE, ID3ERR )
INTEGER
ID3DIS, ARRI, LEAV, ID3ERR
LOGICAL
LOCK, BUIL, SHOP, ORIL, POSI
CHARACTER*(*)
TYPE, NAME, OWNE, SPRE, LSTU, ISPE,
TSPE
REAL
POS(3), ORI(3)
D:9
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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( ID3DIS, TYPE, NAME, OWNE, LOCK, FUNC, DSCO,
PTSP, INSC, POS, ORI, ISPE, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, FUNC, DSCO, PTSP,
INSC, ISPE
REAL
POS(3), ORI(3)
Performs the equivalent of a Q ATT for an EQUI.
Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RRA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
FUNC
Function
DSCO
Design code
PTSP
Paint spec
INSC
Inspection schedule
POS
Position
ORI
Orientation
ISPE
Insulation schedule
ID3ERR
Error code
SUBROUTINE D3QNOZ( ID3DIS, TYPE, NAME, OWNE, LOCK, TEMP, PRES,
POS, ORI, CREF, CATR, ANGL, HEIG, RADI, DUTY, ISPE, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, CREF, CATR, DUTY,
ISPE
REAL
POS(3), ORI(3), TEMP, PRES, HEIG, ANGL,
RADI
Performs the equivalent of a Q ATT for a NOZZ.
D:10
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
Calls D3RNAM, D3XLEN, D3QCMA, D3RREA, D3RRA, D3RTEX, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
TEMP
Temperature
PRES
Pressure
POS
Position
ORI
Orientation
CREF
Connection ref
CATR
Catalogue ref
ANGL
Angle
HEIG
Height
RADI
Radius
DUTY
Duty
ISPE
Insulation spec
ID3ERR
Error code
SUBROUTINE D3QBOX( ID3DIS, TYPE, NAME, OWNE, LOCK, XLEN, YLEN,
ZLEN, POS, ORI, LEVE, OBST, ID3ERR )
INTEGER
ID3DIS, LEVE(2), OBST, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
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
OWNE
Owner name/ref
LOCK
Lock flag
XLEN
X length
YLEN
Y length
ZLEN
Z length
POS
Position
ORI
Orientation
LEVE
Drawing level
OBST
Obstruction level
ID3ERR
Error code
SUBROUTINE D3QCAT( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
LOGICAL
CHARACTER*(*)
ID3DIS, ID3ERR
LOCK
TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for an CATA.
D:11
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ID3ERR
Error code
SUBROUTINE D3QSEC( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for an SECT.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ID3ERR
Error code
SUBROUTINE D3QCOM( ID3DIS, TYPE, NAME, OWNE, LOCK, GTYP, PTRE,
GMRE, ID3NIN, PARA, PARWOR, ID3NOU, ID3ERR )
INTEGER
ID3DIS, ID3NIN, ID3NOU, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, GTYP, PTRE, GMRE
CHARACTER*(*)
PARWOR(ID3NIN)
REAL
PARA(ID3NIN)
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
OWNE
Owner name/ref
LOCK
Lock flag
GTYP
Generic type
PTRE
Point set ref
GMRE
Geometry set ref
PARA
Parameters array
D:12
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
PARWOR
Array of dehashed word parameters
ID3NOU
Number of elements returned in PARA array
ID3ERR
Error code
SUBROUTINE D3QUNI( ID3DIS, TYPE, NAME, OWNE, LOCK, BUNI, DUNI,
DFUN, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
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
OWNE
Owner name/ref
LOCK
Lock flag
BUNI
Bore units
DUNI
Distance units
DFUN
Defined units
ID3ERR
Error code
SUBROUTINE D3QUSE( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for an USEC.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ID3ERR
Error code
SUBROUTINE D3QUDE( ID3DIS, TYPE, NAME, OWNE, LOCK, ABRE, ADEN,
MULT, SIGF, DECP, ID3ERR )
INTEGER
ID3DIS, SIGF, DECP, ID3ERR
LOGICAL
LOCK
D:13
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
CHARACTER*(*)
REAL
TYPE, NAME, OWNE, ABRE
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
OWNE
Owner name/ref
LOCK
Lock flag
ABRE
Abbreviation
ADEN
Adend
MULT
Multiplier
SIGF
Significant figures
DECP
Decimal places
ID3ERR
Error code
SUBROUTINE D3QMSE( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for an MSET.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ID3ERR
Error code
SUBROUTINE D3QMTY( ID3DIS, TYPE, NAME, OWNE, LOCK, UREF, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
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
D:14
Name
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
OWNE
Owner name/ref
LOCK
Lock flag
UREF
Units reference
ID3ERR
Error code
SUBROUTINE D3QATL( ID3DIS, TYPE, NAME, OWNE, LOCK, ATNA, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, ATNA
Performs the equivalent of a Q ATT for an ATLI.
Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3EMSG, D3ERST
D3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ATNA
Atname
ID3ERR
Error code
ISUBROUTINE D3QSPW( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for an SPWL.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ID3ERR
Error code
SUBROUTINE D3QSPE( ID3DIS, TYPE, NAME, OWNE, LOCK, QUAL, QUES,
DEFA, TDEFA, MATR, FLUR, RATI, LNTP, ID3ERR )
INTEGER
ID3DIS, QUAL, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, QUES, TDEFA,
MATR, FLUR, LNTP
REAL
RATI. DEFA
D:15
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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
OWNE
Owner name/ref
LOCK
Lock flag
QUAL
Quality
QUES
Question
DEFA
Default
TDEFA
Text default
MATR
Material ref
FLUR
Fluid ref
RATI
Pressure rating
LNTP
Line type
ID3ERR
Error code
SUBROUTINE D3QSEL( ID3DIS, TYPE, NAME, OWNE, LOCK, QUAL, QUES,
ANSW, TANSW, MAXA, DEFA, TDEFA, ID3ERR )
INTEGER
ID3DIS, QUAL, ID3ERR
LOGICAL
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
OWNE
Owner name/ref
LOCK
Lock flag
QUAL
Quality
QUES
Question
ANSW
Answer
TANSW
Text answer
MAXA
Maxan
DEFA
Default
TDEFA
Text default
ID3ERR
Error code
SUBROUTINE D3QSPC( ID3DIS, TYPE, NAME, OWNE, LOCK, ANSW, MAXA,
TANSW, CATR, CMPR, BLTR, DETR, MATX, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
D:16
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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
OWNE
Owner name/ref
LOCK
Lock flag
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
SUBROUTINE D3QCCT( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE
Performs the equivalent of a Q ATT for a CCTA.
Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
ID3ERR
Error code
SUBROUTINE D3QCOC( ID3DIS, TYPE, NAME, OWNE, LOCK, CTYP, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, CTYP(2)
Performs the equivalent of a Q ATT for a COCO.
D:17
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
Calls D3RNAM, D3XLEN, D3QCMA, D3RWA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
CTYP
Connection type array
ID3ERR
Error code
SUBROUTINE D3QTUB( ID3DIS, TYPE, NAME, OWNE, LOCK, OUTD, ACBO,
BTOL, WTOL, UWEI, UIWE, WDIA, SHAP, RINE, SIF, PRFC, SDTH, CORA,
EFAC, PWAS, BFLE, MRKR, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, MRKR
REAL
OUTD, ACBO, BTOL, WTOL, WDIA, SHAP,
RINE(3)
REAL
SIF(3), PRFC, SDTH(3), CORA, EFAC, PWAS,
BFLE
REAL
UWEI, UIWE
Performs the equivalent of a Q ATT for a TUBD.
Calls D3RNAM, D3XLEN, D3QCDA, D3RREA, D3EMSG
ID3DIS
Display flag
TYPE
Type
NAME
Name
OWNE
Owner name/ref
LOCK
Lock flag
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
D:18
ID3ERR
Error code
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
SUBROUTINE D3QCMP( ID3DIS, TYPE, NAME, OWNE, LOCK, OUTD, ACBO,
BTOL, WTOL, CWEI, CIWE, WDIA, SHAP, RINE, SIF, PRFC, SDTH, CORA,
EFAC, PWAS, BFLE, DFFL, DMFL, RMFL, MRKR, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, MRKR
REAL
OUTD, ACBO, BTOL, WTOL, WDIA, SHAP,
RINE(3), SIF(3), PRFC
REAL
SDTH(3), CORA, EFAC, PWAS, BFLE, CWEI,
CIWE, 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
OWNE
Owner name/ref
LOCK
Lock flag
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
RMFL
Rotation moment
MRKR
3 way component marker
DMFL
Displacement moment
ID3ERR
Error code
D:19
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
SUBROUTINE D3QCDA( ID3DIS, TYPE, NAME, OWNE, LOCK, OUTD, ACBO,
BTOL, WTOL, WDIA, SHAP, RINE, SIF, PRFC, SDTH, CORA, EFAC, PWAS,
BFLE, MRKR, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, MRKR
REAL
OUTD, ACBO, BTOL, WTOL, WDIA, SHAP,
RINE(3)
REAL
SIF(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
SUBROUTINE D3QCON ( ID3DIS, TYPE, NAME, OWNE, LOCK, APPL, FORC,
MOME, DISP, ROTN, DLIM, RLIM, FLIM, MLIM, DFLF, RFLF, FCOE, CPUL,
CPUT, ID3ERR )
INTEGER
ID3DIS, ID3ERR
LOGICAL
LOCK
CHARACTER*(*)
TYPE, NAME, OWNE, APPL
REAL
FORC(3), MOME(3), DISP(3), ROTN(3),
DLIM(6)
REAL
RLIM(6), FLIM(3), MLIM(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
OWNE
Owner name/ref
LOCK
Lock flag
APPL
Application
FORC
Force
MOME
Moment
DISP
Displacement
ROTN
Rotation
DLIM
Displacement limits
RLIM
Rotation limits
FLIM
Force limits
D:20
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
MLIM
Moment limits
RFLF
Rotational flexibility factors
FCOE
CPUT
DFLF
Linear flexibility factors
Friction coefficient
CPUL
Cold pull
Cold twist
ID3ERR
Error code
SUBROUTINE D3QUDA( ID3DIS, TYPE, NAME, OWNE, LOCK, UKEY, UDNA,
ABLE, UTYP, ULEN, DFLT, RPTX, DESC, UUNI, ELEL, MAXE, OUTE, REFL,
MAXR, OUTR, ID3ERR )
INTEGER
ID3DIS, ID3ERR, UKEY, ABLE, ULEN, MAXE,
OUTE
INTEGER
MAXR, OUTR
LOGICAL
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
OWNE
Owner name/ref
LOCK
Lock flag
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
INTEGER FUNCTION D3XLEN( CD3STR )
CHARACTER*(*)
CD3STR
D:21
12.0
Data Access Routines User Guide
Auxiliary Subroutine Library
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 STRING(:D3XLEN(STRING)) 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)
D:22
12.0
Data Access Routines User Guide
Multibyte Text Handling
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 ISOIR 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')
4 characters ' def'
Genuine occurrences of '&~' are denoted by '&&~'; so that 'abc&&~&~4A;z & def' is
interpreted as:
5 characters 'abc&~'
E:1
12.0
Data Access Routines User Guide
Multibyte Text Handling
2 byte pairs corresponding to '4A' and ';z' (meaning 'kanji')
4 characters ' def'
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'
4 characters ' def'
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 machinespecific.
PROGRAM FECSRD
C
Program to read, translate and print FECs text
C
EXTERNAL FECS
CHARACTER*50 STRING, FECS, STRIN2
C
100
CONTINUE
READ(*,'(A)') STRING
IF (STRING .EQ. ' ') GOTO 999
STRIN2 = FECS(STRING)
PRINT*, STRIN2
GOTO 100
999
CONTINUE
CALL EXIT
END
CHARACTER*(*) FUNCTION FECS(STRING)
C
Function to translate FECs string
C
(machine-specific in parts)
C
E:2
12.0
Data Access Routines User Guide
Multibyte Text Handling
CHARACTER*(*) STRING
C
INTEGER IPOS, OPOS, ILEN, OLEN, IPAIR, IPOSM1,
IPOSP1
LOGICAL LFECS
C
INTRINSIC MIN, MAX, LEN, CHAR, ICHAR
ILEN = LEN(STRING)
OLEN = LEN(FECS)
IPOS = 0
OPOS = 0
FECS = ' '
LFECS = .FALSE.
100
C
CONTINUE
Consider first (next) character
IPOS = IPOS + 1
IF (IPOS .GT. ILEN) GOTO 999
C
Skip if remainder is blank (to save time)
IF (STRING(IPOS:) .EQ. ' ') GOTO 999
OPOS = OPOS + 1
IF (OPOS .GT. OLEN) GOTO 999
IF (.NOT. LFECS) THEN
C
Not already multibyte
C
Test for FECS-IN
IPOSM1 = MAX(IPOS-1, 1)
IPOSP1 = MIN(IPOS+1, ILEN)
IF (STRING(IPOS:IPOSP1) .EQ. '&~'
+
C
.AND. STRING(IPOSM1:IPOS) .NE. '&&') THEN
FECS-IN found
LFECS = .TRUE.
IPOS = IPOS + 2
IF (IPOS .GT. ILEN) GOTO 999
E:3
12.0
Data Access Routines User Guide
Multibyte Text Handling
IPAIR = 0
ENDIF
ENDIF
IF (LFECS) THEN
C
Multibyte portion of text string
IPAIR = IPAIR + 1
C
If IPAIR is odd (first of a byte-pair), test
for FECS-OUT
IPOSP1 = MIN(IPOS+1, ILEN)
IF (2*(IPAIR/2) .NE. IPAIR
+
.AND. STRING(IPOS:IPOSP1) .EQ. ' &') THEN
C
FECS-OUT found
LFECS = .FALSE.
IPOS = IPOS + 2
IF (IPOS .GT. ILEN) GOTO 999
ENDIF
ENDIF
C
Copy input string to output string
IF (LFECS) THEN
C
Multibyte portion of text string and not FECOUT
C
Convert to ASCII,
convert back
add
128
to
ASCII
FECS(OPOS:OPOS)
CHAR(ICHAR(STRING(IPOS:IPOS)) + 128)
value,
=
ELSE
FECS(OPOS:OPOS) = STRING(IPOS:IPOS)
ENDIF
C
Look at next character
GOTO 100
C
999
CONTINUE
E:4
12.0
Data Access Routines User Guide
Multibyte Text Handling
C
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
C
C
FECs translation test
CHARACTER*50
NAME, FECS, NAME3, CNAME, CNAME3
CHARACTER*120
TEXT
CHARACTER*1
CDUM
Optional declarations
INTEGER
IERR, IPOS
EXTERNAL
D3INIT, D3ERST,
D3RTEX, D3RNAM
D3MMDB,
D3MNAM,
EXTERNAL
D3EMSG, D3MNUM,
FECS, FECST
D3FIN,
D3FEND,
Project entry
CALL D3INIT( 'FEC', 'SYSTEM', 'XXXXXX', 'NONE', '
', IERR )
IF (IERR.NE.0) GOTO 9000
C
MDB Selection
CALL D3MMDB ( 'DES/|}~', ' ', IERR )
IF ( IERR .NE. 0 ) GOTO 9000
C
Go to zone
CALL D3MNAM('/ZONE1.EQUIP', IERR)
IF ( IERR .NE. 0 ) GOTO 9000
C
Goto each equipment item and read names
PRINT*,'Equipment in zone /ZONE1.EQUIP:'
IPOS = 0
E:5
12.0
Data Access Routines User Guide
Multibyte Text Handling
NAME3 = ' '
100
CONTINUE
IPOS = IPOS + 1
CALL D3MNUM('EQUIP', IPOS, IERR)
IF ( IERR .EQ. 203) THEN
CALL D3ERST
GOTO 200
ELSEIF ( IERR .NE. 0 ) THEN
GOTO 9000
ENDIF
CALL D3RNAM('NAME', NAME, IERR )
IF ( IERR .NE. 0 ) GOTO 9000
C
Convert any FECs in name
CNAME = FECS(NAME)
PRINT*, '
C
', CNAME
Remember 3rd equipment name
IF (IPOS .EQ. 3) THEN
NAME3 = NAME
CNAME3 = CNAME
ENDIF
GOTO 100
200
CONTINUE
C
C
Get attributes of last equipment
PRINT*,'Text attributes of ', CNAME
CALL FECST('DSCODE')
CALL FECST('FUNCTION')
CALL FECST('PTSPEC')
CALL FECST('INSCHED')
C
E:6
12.0
Data Access Routines User Guide
Multibyte Text Handling
C
Go to 3rd equipment, by name - then attributes
IF (NAME3 .NE. ' ') THEN
CALL D3MNAM(NAME3, IERR)
IF ( IERR .NE. 0 ) THEN
PRINT*, NAME3
GOTO 9000
ENDIF
CNAME = CNAME3
NAME3 = ' '
GOTO 200
ENDIF
IERR = 0
C
C
Exit
9000
CONTINUE
IF (IERR .NE. 0) CALL D3EMSG(IERR, .TRUE., CDUM)
CALL D3FIN( IERR )
CALL D3FEND
END
C--------------------------SUBROUTINE FECST(NAME)
C--------------------------C
Subroutine
to
read,
translate
(possible) FECs attribute
and
print
C
CHARACTER*(*)
NAME
CHARACTER*12
0 TEXT, FECS, CTEXT
CHARACTER*1
CDUM
INTEGER
D3ULEN, IERR
E:7
12.0
Data Access Routines User Guide
Multibyte Text Handling
EXTERNAL
C
D3ULEN,
D3RTEX
FECS,
D3EMSG,
D3ERST,
CALL D3RTEX(NAME, TEXT, IERR)
C
Convert any FECs in name
CTEXT = FECS(TEXT)
IF (IERR .NE. 0) THEN
CTEXT = '??????'
CALL D3EMSG(IERR, .TRUE., CDUM)
CALL D3ERST
ENDIF
IF (CTEXT .EQ. ' ') CTEXT = '**unset**'
PRINT*, '
', 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.
Equipment in zone /ZONE1.EQUIP:
/VESS1
/VESS2
/@@@@@@pump
/@@@@@@@@@@@@
/@@@@@@
/@@@@@@111
Text attributes of /@@@@@@111
DSCODE: @@@@ Japan
FUNCTION: @@@@@@@@
PTSPEC: Grade 1 @@@@@@ 2 coats
INSCHED: @@@@@@ is beautiful
Text attributes of /@@@@@@pump
DSCODE: **unset**
FUNCTION: **unset**
E:8
12.0
Data Access Routines User Guide
Multibyte Text Handling
PTSPEC: ABNS @@@@@@@@@@ abcv
INSCHED: **unset**
E:9
12.0
Data Access Routines User Guide
Multibyte Text Handling
E:10
12.0
Data Access Routines User Guide
‘C/C++’ Library
F
‘C/C++’ Library
F.1
Software Issued with DARs ‘C/C++’ Library
The DARs C/C++ library is included in with the DARs.
The files provided with a PDMS DARs ‘C/C++’ library are listed in DARs Library Details
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 Compilation and Linking
Script 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.setenv DAR000 %PDMSEXE%\dars\dar000
setenv DAR100 %PDMSEXE%\dars\dar100
2. Set the DARs library environment variable:
e.g.setenv DARSLIBDIR %PDMSEXE%\dars
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 %DARSLIBDIR/ccompload c_example
6. Enter c_example
Does the output appear to be the same as the output listed in the appendix (allowing
for differences of print format)?
F:1
12.0
Data Access Routines User Guide
‘C/C++’ Library
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. ccompload
c_example.c)
As an alternative, the program may be compiled and linked using a makefile based on the
commands in ccompload.
ccompload.bat
@echo off
Rem NT .bat file to compile and link a PDMS DARs application C
program.
Rem Argument[1] is the file to be compiled.
if not "%1"=="" goto GOTFILE
echo compload - no filename specified.
goto FINISH
:GOTFILE
Rem Compile and link
cl -Tc%1 -I%PDMSEXE%\dars %PDMSEXE%\dars\d3lib.lib
:FINISH
cxxcompload.bat
@echo off
Rem NT .bat file to compile and link a PDMS DARs application
C++ program.
Rem Argument[1] is the file to be compiled.
if not "%1"=="" goto GOTFILE
echo compload - no filename specified.
goto FINISH
:GOTFILE
Rem Compile and link
cl -Tp%1 -I%PDMSEXE%\dars %PDMSEXE%\dars\d3lib.lib
:FINISH
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'
F:2
12.0
Data Access Routines User Guide
‘C/C++’ Library
prototypes.
**
d3libc.h
**
**
header file for DARS C to FORTRAN interface.
**
The DAR routines are written in FORTRAN
**
but here is the user C/C++ interface
**
**
Notes:
**
1.
arguments are passed by address.
**
**/
#ifndef D3LIBC_H
#define D3LIBC_H
/* end of system includes */
#include <pdms.h>
/*
** DAR interface function/subroutine prototypes
*/
#ifdef __cplusplus
extern "C" void d3echk
( char *cd3err ) ;
extern "C" void d3emsg
( int *id3err, int *ld3dis, DARS_MESS
cd3msg ) ;
extern "C" void d3erst
( void ) ;
extern "C" void d3fend
( void ) ;
extern "C" void d3fin
( int *id3err ) ;
F:3
12.0
Data Access Routines User Guide
‘C/C++’ Library
extern "C" void d3init
( char *cd3prj, char *cd3usr, char
*cd3pas, char *cd3mon, char
*cd3wrk, int *id3err ) ;
extern "C" void d3mcdb
( char *cd3nam, int *id3pos, int
*id3err ) ;
extern "C" void d3mddb
( char *cd3nam, int *id3err ) ;
extern "C" void d3medb
( char *cd3nm1, char *cd3nm2, int
*id3err ) ;
extern "C" void d3mmdb
( char *cd3mdb, char *cd3wrk, int
*id3err ) ;
extern "C" void d3mnam
( char *cd3nam, int *id3err ) ;
extern "C" void d3mnum
( char *cd3typ, int *id3lis, int
*id3err ) ;
extern "C" void d3mown
( int *id3err ) ;
extern "C" void d3mqdb
( int *id3pos, PDMS_DBNAME cd3nam,
PDMS_WORD cd3typ, int *id3sta, int
*id3err ) ;
extern "C" void d3mrel
( char *cd3pos, char *cd3typ, int
*id3err ) ;
extern "C" void d3mrst
( int *id3err ) ;
extern "C" void d3msav
( int *id3err ) ;
extern "C" void d3rbdu
( PDMS_WORD cd3bun, PDMS_WORD
cd3dun, int *id3err ) ;
extern "C" void d3rbox
( int *ld3tub, float *rd3box, int
*id3err ) ;
extern "C" void d3rdat
( int *id3dat, DARS_RDAT cd3dat,
int *id3err ) ;
extern "C" void d3ria
( char *cd3att, int *id3nin, int
*id3ia, int *id3nou, int *id3err )
;
extern "C" void d3rint
( char *cd3att, int *id3int, int
*id3err ) ;
extern "C" void d3rla
( char *cd3att, int *id3nin, int
*ld3la, int *id3nou, int *id3err )
;
extern "C" void d3rlog
( char *cd3att, int *ld3log, int
*id3err ) ;
extern "C" void d3rnam
( char *cd3att, PDMS_NAME cd3nam,
int *id3err ) ;
F:4
12.0
Data Access Routines User Guide
‘C/C++’ Library
extern "C" void d3rorl
( char *cd3crd, float *rd3ori, int
*id3err ) ;
extern "C" void d3rpat
( char *cd3poi, char *cd3crd, float
*rd3pos, float *rd3dir, float
*rd3bor, PDMS_WORD cd3con, int
*id3err ) ;
extern "C" void d3rprj
( char *cd3nam, PDMS_TEXT cd3tex,
int *id3err ) ;
extern "C" void d3rprl
( char *cd3crd, float *rd3pos, int
*id3err ) ;
extern "C" void d3rptx
( char *cd3att, PDMS_RPTX cd3rpt,
int *id3err ) ;
extern "C" void d3rra
( char *cd3att, int *id3nin, float
*rd3ra, int *id3nou, int *id3err )
;
extern "C" void d3rrea
( char *cd3att, float *rd3rea, int
*id3err ) ;
extern "C" void d3rref
( char *cd3att, PDMS_NAME cd3ref,
int *id3err ) ;
extern "C" void d3rrfa
( char *cd3att, int *id3nin,
PDMS_NAME cd3rfa[], int *id3nou,
int *id3err ) ;
extern "C" void d3rtex
( char *cd3att, PDMS_TEXT cd3tex,
int *id3err ) ;
extern "C" void d3rtyp
( PDMS_WORD cd3typ, int *id3err ) ;
extern "C" void d3ruda
( char *cd3typ, int *id3max,
PDMS_UDNA cd3nms[], int *id3abv,
PDMS_WORD cd3atp[], int *id3num,
int *id3err ) ;
extern "C" void d3runi
( char *cd3att, PDMS_UUNI cd3unt,
int *id3err ) ;
extern "C" void d3rwa
( char *cd3att, int *id3nin,
PDMS_WORD cd3wa[], int *id3nou, int
*id3err ) ;
extern "C" void d3rwor
( char *cd3att, PDMS_WORD cd3wor,
int *id3err ) ;
extern "C" int d3uclu
( int *id3uni ) ;
/*
** cd3bef and cd3aft MUST be declared same length as cd3str
*/
F:5
12.0
Data Access Routines User Guide
‘C/C++’ Library
extern "C" int d3ucti
( char *cd3str, int *id3int, char
*cd3bef, char *cd3aft, DARS_CERR
cd3err ) ;
/*
** cd3bef and cd3aft MUST be declared same length as cd3str
*/
extern "C" int d3uctr
( char *cd3str, float *rd3val, char
*cd3bef, char *cd3aft, DARS_CERR
cd3err ) ;
extern "C" void d3udeh
( int *id3int, PDMS_WORD cd3wor ) ;
extern "C" void d3udtm
( int *id3dat, DARS_RDAT cd3dat ) ;
extern "C" int d3ugtu
( int *id3uni ) ;
extern "C" void d3uini
( int *ready ) ;
extern "C" int d3ulds
( char *cd3dat, int *id3err ) ;
extern "C" int d3ulen
( char *cd3str ) ;
extern "C" void d3umon
( char *cd3mon ) ;
#else /* C rather than C++ */
void d3echk
( char *cd3err ) ;
void d3emsg
( int *id3err, int *ld3dis,
DARS_MESS cd3msg ) ;
void d3erst
( void ) ;
void d3fend
( void ) ;
void d3fin
( int *id3err ) ;
void d3init
( char *cd3prj, char *cd3usr, char
*cd3pas, char *cd3mon, char
*cd3wrk, int *id3err ) ;
void d3mcdb
( char *cd3nam, int *id3pos, int
*id3err ) ;
void d3mddb
( char *cd3nam, int *id3err ) ;
void d3medb
( char *cd3nm1, char *cd3nm2, int
*id3err ) ;
void d3mmdb
( char *cd3mdb, char *cd3wrk, int
*id3err ) ;
F:6
12.0
Data Access Routines User Guide
‘C/C++’ Library
void d3mnam
( char *cd3nam, int *id3err ) ;
void d3mnum
( char *cd3typ, int *id3lis, int
*id3err ) ;
void d3mown
( int *id3err ) ;
void d3mqdb
( int *id3pos, PDMS_DBNAME cd3nam,
PDMS_WORD cd3typ, int *id3sta, int
*id3err ) ;
void d3mrel
( char *cd3pos, char *cd3typ, int
*id3err ) ;
void d3mrst
( int *id3err ) ;
void d3msav
( int *id3err ) ;
void d3rbdu
( PDMS_WORD cd3bun, PDMS_WORD
cd3dun, int *id3err ) ;
void d3rbox
( int *ld3tub, float *rd3box, int
*id3err ) ;
void d3rdat
( int *id3dat, DARS_RDAT cd3dat,
int *id3err ) ;
void d3ria
( char *cd3att, int *id3nin, int
*id3ia, int *id3nou, int *id3err )
;
void d3rint
( char *cd3att, int *id3int, int
*id3err ) ;
void d3rla
( char *cd3att, int *id3nin, int
*ld3la, int *id3nou, int *id3err )
;
void d3rlog
( char *cd3att, int *ld3log, int
*id3err ) ;
void d3rnam
( char *cd3att, PDMS_NAME cd3nam,
int *id3err ) ;
void d3rorl
( char *cd3crd, float *rd3ori, int
*id3err ) ;
void d3rpat
( char *cd3poi, char *cd3crd, float
*rd3pos, float *rd3dir, float
*rd3bor, PDMS_WORD cd3con, int
*id3err ) ;
void d3rprj
( char *cd3nam, PDMS_TEXT cd3tex,
int *id3err ) ;
void d3rprl
( char *cd3crd, float *rd3pos, int
*id3err ) ;
F:7
12.0
Data Access Routines User Guide
‘C/C++’ Library
void d3rptx
( char *cd3att, PDMS_RPTX cd3rpt,
int *id3err ) ;
void d3rra
( char *cd3att, int *id3nin, float
*rd3ra, int *id3nou, int *id3err )
;
void d3rrea
( char *cd3att, float *rd3rea, int
*id3err ) ;
void d3rref
( char *cd3att, PDMS_NAME cd3ref,
int *id3err ) ;
void d3rrfa
( char *cd3att, int *id3nin,
PDMS_NAME cd3rfa[], int *id3nou,
int *id3err ) ;
void d3rtex
( char *cd3att, PDMS_TEXT cd3tex,
int *id3err ) ;
void d3rtyp
( PDMS_WORD cd3typ, int *id3err ) ;
void d3ruda
( char *cd3typ, int *id3max,
PDMS_UDNA cd3nms[], int *id3abv,
PDMS_WORD cd3atp[], int *id3num,
int *id3err ) ;
void d3runi
( char *cd3att, PDMS_UUNI cd3unt,
int *id3err ) ;
void d3rwa
( char *cd3att, int *id3nin,
PDMS_WORD cd3wa[], int *id3nou, int
*id3err ) ;
void d3rwor
( char *cd3att, PDMS_WORD cd3wor,
int *id3err ) ;
int d3uclu
( int *id3uni ) ;
/*
** cd3bef and cd3aft MUST be declared same length as cd3str
*/
int d3ucti
( char *cd3str, int *id3int, char
*cd3bef, char *cd3aft, DARS_CERR
cd3err ) ;
/*
** cd3bef and cd3aft MUST be declared same length as cd3str
*/
int d3uctr
( char *cd3str, float *rd3val, char
*cd3bef, char *cd3aft, DARS_CERR
cd3err ) ;
F:8
12.0
Data Access Routines User Guide
‘C/C++’ Library
void d3udeh
( int *id3int, PDMS_WORD cd3wor ) ;
void d3udtm
( int *id3dat, DARS_RDAT cd3dat ) ;
int d3ugtu
( int *id3uni ) ;
void d3uini
( int *ready ) ;
int d3ulds
( char *cd3dat, int *id3err ) ;
int d3ulen
( char *cd3str ) ;
void d3umon
( char *cd3mon ) ;
#endif /* __cplusplus */
#endif
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 file to define some system constants.
**
**
Notes:
**
**
1. Strings are defined as being 1 more than in
FORTRAN
**
to account for the C string terminator '\0'.
**
*/
#ifndef PDMSH
#define PDMSH
F:9
12.0
Data Access Routines User Guide
‘C/C++’ Library
/* Some constants */
#define
TRUE
1
#define
FALSE
#define
PDMSNAMELEN
#define
PDMSUDNANAMELEN
#define
PDMSWORDLEN
6
#define
PDMSTEXTLEN
1000
#define
PDMSRPTXTEXTLEN
20
#define
PDMSUUNITEXTLEN
20
#define
DARSMESSTEXTLEN
50
#define
DARSRDATTEXTLEN
20
#define
DARSCERRTEXTLEN
3
#define
PDMSDBNAMELEN
64
typedef
char
PDMSNAME
[ PDMSNAMELEN + 1 ] ;
typedef
char
PDMSWORD
[ PDMSWORDLEN + 1 ] ;
typedef
char
PDMSTEXT
[ PDMSTEXTLEN + 1 ] ;
typedef
char
PDMSRPTX
[ PDMSRPTXTEXTLEN + 1 ] ;
typedef
char
PDMSUDNA
[ PDMSUDNANAMELEN + 1 ] ;
typedef
char
PDMSUUNI
[ PDMSUUNITEXTLEN + 1 ] ;
typedef
char
DARSMESS
[ DARSMESSTEXTLEN + 1 ] ;
typedef
char
DARSRDAT
[ DARSRDATTEXTLEN + 1 ] ;
typedef
char
DARSCERR
[ DARSCERRTEXTLEN + 1 ] ;
typedef
char
PDMSDBNAME
[ PDMSDBNAMELEN + 1 ] ;
typedef
int
LOGICAL ;
0
50
13
#endif
F.7
Example 'C' Program
The 'C' source of this program (FORTRAN source of a similar program is in Section
Example 1) is as follows:
#include <stdio.h>
#include <stdlib.h>
F:10
12.0
Data Access Routines User Guide
‘C/C++’ Library
#include <string.h>
#include "d3libc.h"
void main (int argc, char **argv)
{
/*
** Main c test program
*/
#define
PARAM_ARRAY_LEN
100
PDMS_NAME
spcref, catref ;
PDMS_WORD
cd3wor, words [ PARAM_ARRAY_LEN ] ;
LOGICAL
lval ;
DARS_MESS
cd3msg ;
PDMS_TEXT
cd3tex, cd3bef, cd3aft ;
DARS_CERR
cd3err ;
DARS_RDAT
cd3dat ;
float
params [ PARAM_ARRAY_LEN ] ;
int
id3err, id3nou, i, ival, ilen, id3dat[ 6 ], iparam ;
/* Project entry */
d3init ( "DAR", "SYSTEM", "XXXXXX", "FULL", " ", &id3err ) ;
if ( id3err != 0 ) goto finish ;
/* Get project details */
/* Use fprintf to check that writing to stdout works */
d3umon ( "NONE" ) ;
d3rprj ( "code", cd3tex, &id3err ) ;
fprintf ( stdout, "Project Code: %s\n", cd3tex ) ;
d3rprj ( "name", cd3tex, &id3err ) ;
fprintf ( stdout, "Project Name: %s\n", cd3tex ) ;
d3rprj ( "numb", cd3tex, &id3err ) ;
fprintf ( stdout, "Project Number: %s\n", cd3tex ) ;
d3rprj ( "mess", cd3tex, &id3err ) ;
fprintf ( stdout, "Project Message: %s\n", cd3tex ) ;
/* Return string length */
ilen = d3ulen ( cd3tex ) ;
printf ( "Length of %s -> %d\n", cd3tex, ilen ) ;
/* Get date */
d3udtm ( id3dat, cd3dat ) ;
printf ( "Date is: %s
or...", cd3dat ) ;
for ( i = 0; i < 6; i++ ) printf ( " %d", id3dat[ i ] ) ;
printf ( "\n" ) ;
/* Extract integer */
strcpy ( cd3tex, "abcd12345XYZ" ) ;
lval = d3ucti ( cd3tex, &ival, cd3bef, cd3aft, cd3err ) ;
if ( lval != 0 )
{
printf ( "For string: %s\n", cd3tex ) ;
printf ( "Returned integer %d\n", ival ) ;
}
else
{
printf ( "For string: %s", cd3tex ) ;
printf ( ", returned error %s\n", cd3err ) ;
if ( !strcmp ( cd3err, "ADD" ) )
{
printf ( "Returned integer %d\n", ival ) ;
F:11
12.0
Data Access Routines User Guide
‘C/C++’ Library
printf ( "String before: %s\n", cd3bef ) ;
printf ( "String after: %s\n", cd3aft ) ;
/*
/*
/*
/*
/*
/*
/*
}
}
strcpy ( cd3tex, "abcdXYZ" ) ;
lval = d3ucti ( cd3tex, &ival, cd3bef, cd3aft, cd3err ) ;
if ( lval != 0 )
{
printf ( "For string: %s\n", cd3tex ) ;
printf ( "Returned integer %d\n", ival ) ;
}
else
{
printf ( "For string: %s", cd3tex ) ;
printf ( ", returned error %s\n", cd3err ) ;
if ( !strcmp ( cd3err, "ADD" ) )
{
printf ( "Returned integer %d\n", ival ) ;
printf ( "String before: %s\n", cd3bef ) ;
printf ( "String after: %s\n", cd3aft ) ;
}
}
Select MDB */
d3umon ( "FULL" ) ;
d3mmdb ( "DESIGN/PLANT", " ", &id3err ) ;
if ( id3err != 0 ) goto finish ;
Get datestamp */
d3rdat ( id3dat, cd3dat, &id3err ) ;
printf ( "Datestamp is: %s\nor...", cd3dat ) ;
for ( i = 0; i < 6; i++ ) printf ( " %d", id3dat[ i ] ) ;
printf ( "\n" ) ;
Move to a pipe component */
d3mnam ( "/100-B-1", &id3err ) ;
ival = 1 ;
d3mnum ( "BRAN", &ival, &id3err ) ;
d3mrel ( "LAST", "FLAN", &id3err ) ;
Get spec ref and goto it */
d3rnam ( "SPRE", spcref, &id3err ) ;
printf ( "spcref is: %s\n", spcref ) ;
d3mnam ( spcref, &id3err ) ;
Get cat ref and goto it */
d3rnam ( "CATR", catref, &id3err ) ;
d3mnam ( catref, &id3err ) ;
Get parameters of component and dehash conn types */
Cancel monitor and construct own PRINT statements */
d3umon ( "NONE" ) ;
puts ( "Getting elements with D3RRA" ) ;
ival = PARAM_ARRAY_LEN ;
d3rra ( "PARA", &ival, params, &id3nou, &id3err ) ;
printf ( "Number of elements found: %d\n", id3nou ) ;
for ( i = 0; i < id3nou; i++ )
{
strcpy ( cd3wor, "\0" ) ;
/* If possibly a word, dehash */
F:12
12.0
Data Access Routines User Guide
‘C/C++’ Library
if ( params [ i ] >= 531442.0 )
{
iparam = params[ i ] ;
d3udeh ( &iparam, cd3wor ) ;
}
if ( strlen ( cd3wor ) == 0 )
/* Not a word; print real value */
printf ( "Element %d: %f\n", i+1, params [ i ] ) ;
else
/* Valid word; print word */
printf ( "Element %d: %s\n", i+1, cd3wor ) ;
}
/* Alternatively, use D3RWA directly (non-words don"t give error) */
puts ( "Getting elements with D3RWA" ) ;
ival = PARAM_ARRAY_LEN ;
d3rwa ( "WPAR", &ival, words, &id3nou, &id3err ) ;
for ( i = 0; i < id3nou; i++ )
{
if ( strlen ( words [ i ] ) != 0 )
printf ( "Element %d: %s\n", i+1, words [ i ] ) ;
}
finish: ;
/* Cancel monitor and output message */
d3umon ( "NONE" ) ;
lval = FALSE ;
d3emsg ( &id3err, &lval, cd3msg ) ;
printf ( "%s\n", cd3msg ) ;
/* Exit project */
d3fin ( &id3err ) ;
/* Exit DARs */
d3fend ( ) ;
return ;
}
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.
AVEVA DARs C Interface Mk12.000 (WINDOWS-NT 5.2) (7 Sep 2007 : 23:36)
This version of PDMS was issued to <your company>
and will only operate on registered hardware
PDMS DARs Mk12.0.0.0 (WINDOWS-NT 5.2) (7 Sep 2007 : 23:36)
(c) Copyright 1974 to 2007 AVEVA Solutions Limited
Issued to <your company>
Entering subroutine D3INIT
Input arguments:
Project name
Username
Password
Monitoring level
DAR
SYSTEM
XXXXXX
FULL
F:13
12.0
Data Access Routines User Guide
‘C/C++’ Library
Read/Write key
Exiting subroutine D3INIT
Output arguments:
Error code
0
Entering subroutine D3UMON
Input arguments:
Monitoring level
NONE
Exiting subroutine D3UMON
Entering subroutine D3MMDB
Input arguments:
MDB name
DESIGN/PLANT
Read/Write key
Exiting subroutine D3MMDB
Output arguments:
Error code
0
Entering subroutine D3RDAT
Exiting subroutine D3RDAT
Output arguments:
Date-stamp
04 Jul 2000 17:56:24
Year, Month, Day
2000 7 4
Hour, Minute, Second 17 56 24
Error code
0
Entering subroutine D3MNAM
Input arguments:
Element name/ref
/100-B-1
Exiting subroutine D3MNAM
Output arguments:
Error code
0
Entering subroutine D3MNUM
Input arguments:
Element type
BRAN
List position
1
Exiting subroutine D3MNUM
Output arguments:
Error code
0
Entering subroutine D3MREL
Input arguments:
Relative position
LAST
Element type
FLAN
Exiting subroutine D3MREL
Output arguments:
Error code
0
Entering subroutine D3RNAM
F:14
12.0
Data Access Routines User Guide
‘C/C++’ Library
Input arguments:
Attribute required
SPRE
Exiting subroutine D3RNAM
Output arguments:
Name/Reference
/A3B/100F1
Error code
0
Entering subroutine D3MNAM
Input arguments:
Element name/ref
/A3B/100F1
Exiting subroutine D3MNAM
Output arguments:
Error code
0
Entering subroutine D3RNAM
Input arguments:
Attribute required
CATR
Exiting subroutine D3RNAM
Output arguments:
Name/Reference
/FUAAPAMM
Error code
0
Entering subroutine D3MNAM
Input arguments:
Element name/ref
/FUAAPAMM
Exiting subroutine D3MNAM
Output arguments:
Error code
0
Entering subroutine D3UMON
Input arguments:
Monitoring level
NONE
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 (‘C/C++’
Library). 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
F:15
12.0
Data Access Routines User Guide
‘C/C++’ Library
of these functions: the programmer 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:16
12.0
Data Access Routines User Guide
Index
A
Acceptance Test Program . . . . . . . A:4, F:1
Application Program Compilation . . A:3, F:1
Application Program Linking . . . . . . A:3, F:1
Application Programs
re-linking . . . . . . . . . . . . . . . . . . . . . . A:5
Auxiliary Subroutine Library . . . . . . . . . .D:1
Error Handling Routines . . . . . . . . . . . . . 5:4
Error Messages . . . . . . . . . . . . . . . . . . . C:1
F
File Handling . . . . . . . . . . . . . . . . . . . . . A:2
FORTRAN 77 . . . . . . . . . . . . . . . . . . . . . 2:1
G
C
General Utility Routines . . . . . . . . . . . . . 5:5
C Program
example . . . . . . . . . . . . . . . . . . . . . F:10
C/C++ Header Files . . . . . . . . . . . . . . . . F:2
C/C++ Interface Principles . . . . . . . . . . F:15
C/C++ Library . . . . . . . . . . . . . . . . . . . . . F:1
Character Handling . . . . . . . . . . . . . . . . . 2:2
Compilation and Linking Script . . . . . . . . F:2
Current Element . . . . . . . . . . . . . . . . . . . 3:1
D
DARs Library Details . . . . . . . . . . . . . . . . A:1
Data Access Routines
examples of use . . . . . . . . . . . . . . . . 4:1
Databases and DARs
Compatibility . . . . . . . . . . . . . . . . . . . 6:1
Declarations . . . . . . . . . . . . . . . . . . . . . . 2:1
Detailed Subroutine Specifications . . . . . 5:5
Dynamic Array Attributes . . . . . . . . . . . . 3:1
E
Error Codes . . . . . . . . . . . . . . . . . . . . . . .C:1
Error Handling . . . . . . . . . . . . . . . . . . . . . 2:3
I
Initialisation Routines . . . . . . . . . . . . . . . 5:1
M
Monitoring . . . . . . . . . . . . . . . . . . . . . . .
Multibyte Text . . . . . . . . . . . . . . . . . . . . .
Multibyte Text Handling . . . . . . . . . . . . .
Chinese characters . . . . . . . . . . . . .
Kanji characters . . . . . . . . . . . . . . . .
3:2
3:2
E:1
E:1
E:1
N
Navigation Routines . . . . . . . . . . . . . . . . 5:1
P
PDMS Data Access . . . . . . . . . . . . . . . .
PDMS Database Organisation . . . . . . . .
PDMS Database Security . . . . . . . . . . .
Program Debugging . . . . . . . . . . . . A:4,
Program Running . . . . . . . . . . . . . . A:4,
Index page 1
3:1
3:1
3:1
F:1
F:1
12.0
Data Access Routines User Guide
Programming Techniques . . . . . . . . . . . . 2:1
R
Read Routines . . . . . . . . . . . . . . . . . . . . 5:2
Running Examples . . . . . . . . . . . . . . . . . B:1
S
Site File . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2
Software Issued with DARs . . . . . . . . . . A:1
Subroutine Outline Specifications . . . . . .D:3
Subroutine Specifications . . . . . . . . . . . . 5:1
Change Monitor Level . . . . . . . . . . 5:63
Character to Integer . . . . . . . . . . . . 5:54
Character to Real Number . . . . . . . 5:56
Clear File Unit . . . . . . . . . . . . . . . . . 5:53
Defer a Database in MDB . . . . . . . 5:12
Dehash a Hashed PDMS Word . . . 5:57
Exchange Databases in MDB . . . . 5:13
Exit System . . . . . . . . . . . . . . . . . . . 5:7
Finish . . . . . . . . . . . . . . . . . . . . . . . . 5:8
Get File Unit . . . . . . . . . . . . . . . . . . 5:59
Initialise . . . . . . . . . . . . . . . . . . . . . . 5:9
Length of Character String . . . . . . . 5:62
Make a Database Current in MDB . 5:11
Move Relative to the Current Position 5:20
Move to an Element by Name . . . . 5:16
Move to Element by Order Position 5:17
Move to Owner of Current Element 5:18
Query database in Current MDB . . 5:18
Query Initialisation . . . . . . . . . . . . . 5:60
Read a Logical Array Attribute . . . . 5:29
Read a Logical Attribute . . . . . . . . . 5:30
Read a Project Data Item . . . . . . . . 5:36
Read a Real Array Attribute . . . . . . 5:40
Read a Real Attribute . . . . . . . . . . . 5:41
Read a Reference Number Array Attribute
5:43
Read a Text Attribute . . . . . . . . . . . 5:45
Read a Type Attribute . . . . . . . . . . 5:47
Read a Word Array Attribute . . . . . 5:50
Read a Word Attribute . . . . . . . . . . 5:52
Read an Integer Array Attribute . . . 5:26
Read an Integer Attribute . . . . . . . . 5:28
Read Bore and Distance Units . . . . 5:22
Read Current System Date and Time 5:58
Read Element Name or a Name Attribute
5:31
Read Element RefNo or a Reference Attribute . . . . . . . . . . . . . . . . 5:42
Read Enclosing Box Co-ordinates . 5:23
Read Latest MDB Date-Stamp . . . . 5:24
Read Lists of UDA Names, Abbreviations
and Types . . . . . . . . . . . . . 5:47
Read Orientation of the Current Element
5:32
Read Position of the Current Element 5:37
Read PPOINT Attributes . . . . . . . . 5:34
Read REPORTER Text for a UDA 5:38
Read Unit of Measurement for a Real or Integer UDA . . . . . . . . . . . . . 5:49
Reset Internal Error Flag . . . . . . . . . 5:7
Restore Last Saved Database Position 5:21
Return Error Message . . . . . . . . . . . 5:6
Save Current Database Position . . 5:22
Select MDB . . . . . . . . . . . . . . . . . . 5:14
Switch Error Handling ON and OFF 5:6
Test Latest MDB Date-Stamp . . . . 5:61
Subroutines
listing . . . . . . . . . . . . . . . . . . . . . . . . D:2
T
Termination Routines . . . . . . . . . . . . . . . 5:5
U
User-Defined Attributes . . . . . . . . . . . . . 3:1
Utility Routines . . . . . . . . . . . . . . . . . . . . 5:4
V
Version Control . . . . . . . . . . . . . . . . . . . 6:1
Version Number Determination . . . . . . . 6:1
Version Numbering of DARs . . . . . . . . . 6:1
Index page 2
12.0